Skip to main content

state_getKeys

Description#

Retrieves all storage keys matching a given prefix from the Acala blockchain state. This method performs a complete enumeration of storage keys beginning with the specified prefix, returning the full list of matching keys in a single response. Storage keys in Substrate chains are organized in a hierarchical structure using hash-based prefixes, where each storage map, double map, or value has a unique prefix derived from the pallet and storage item name. This method is essential for discovering all entries in a storage map, such as all accounts, all staking nominations, or all governance proposals.

Request Example#

curl -s https://api-acala.n.dwellir.com/YOUR_API_KEY -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"state_getKeys","params":["0x26aa394eea5630e07c48ae0c9558cef7", null]}'

Parameters#

ParameterTypeRequiredDescription
prefixstringYesHexadecimal storage key prefix to search for
block_hashstringNoBlock hash to query at. Omit for latest state

Response Format#

Returns an array of storage key strings in hexadecimal format. Each key represents a storage entry matching the specified prefix. The keys can then be used with state_getStorage to retrieve the associated values. For large storage maps, the response can contain thousands or millions of keys.

Storage Key Structure#

Substrate storage keys follow a deterministic structure: the first portion identifies the pallet and storage item through a double Blake2-128 hash, followed by optional key-specific data for maps and double maps. Understanding this structure helps construct appropriate prefixes for targeted queries.

Use Cases#

  • Account Enumeration: List all accounts on the chain by querying the System.Account storage map
  • Token Balances: Discover all holders of a specific token by querying balance storage
  • Governance Participation: Find all voters or proposals in governance pallets
  • Validator Discovery: Enumerate all validators or nominators in staking systems
  • Custom Storage Analysis: Investigate chain-specific storage structures for analytics
  • State Auditing: Verify storage contents or detect anomalies across entire storage maps

Best Practices#

Warning: Use this method with caution on large storage maps. Attempting to retrieve all keys for heavily populated storage can return massive responses that may timeout, consume excessive bandwidth, or overwhelm your client application. For storage maps with more than a few hundred entries, always prefer state_getKeysPaged which provides controlled pagination. Consider the block state carefully - querying historical states requires an archive node.

Performance Considerations#

This method performs a complete storage scan, which is an expensive operation on the node. The response time and size grow linearly with the number of matching keys. Public RPC endpoints may have limits on the number of keys returned or may reject requests for excessively large result sets. Always test with narrow prefixes before expanding queries.