diff --git a/docs/build/api/jsonrpc.mdx b/docs/build/api/jsonrpc.mdx index 2ae65318c..b21cb8767 100644 --- a/docs/build/api/jsonrpc.mdx +++ b/docs/build/api/jsonrpc.mdx @@ -297,6 +297,15 @@ Get information about [address](https://docs.massa.net/docs/learn/architecture/basic-concepts#address) (es) (balances, block creation, \...). +:::note +The `final_datastore_keys` and `candidate_datastore_keys` fields list **every** +datastore key of the address, with no prefix filter and no limit. On addresses +holding many keys this makes the call expensive and the response large. + +Prefer [`get_addresses_datastore_keys`](#get_addresses_datastore_keys), which +supports prefix filtering and pagination. +::: + @@ -416,7 +425,57 @@ Retrieve datastore keys for given addresses. | `inclusive_start_key` | `boolean` | No | `true` | Include or exclude the start_key. | | `end_key` | `array` | No | `null` | The key to end filtering at (inclusive by default). Bytes as array of integers. | | `inclusive_end_key` | `boolean` | No | `true` | Include or exclude the end_key. | -| `count` | `integer` | No | `500` | The maximum number of keys to retrieve (Max: 500). | +| `count` | `integer` | No | `500` | The maximum number of keys to retrieve. Cannot exceed the node's configured cap (`500` on the default configuration); a higher value is rejected with an error. | + +:::caution +The result is **capped** and truncated **silently**. + +Starting with MAIN.6.0 for Mainnet / DEVN.31.0 for Buildnet, omitting `count` +defaults it to the node's maximum (`500` on the default configuration). Earlier +releases documented the same default but did not enforce it, and returned every +matching key instead. + +The response carries no indicator that keys were left out: a truncated result is +indistinguishable from a complete one. An address holding more keys than the cap +therefore returns a partial list rather than an error. + +If you need every key, paginate as shown below, or use +[`getStorageKeys`](../massa-web3/provider.md) from massa-web3 `5.3.0` or later, +which paginates internally. +::: + +#### Pagination + +Keys are returned in ascending lexicographic byte order. To read a full range, +request pages of `count` keys and start each page just after the last key of the +previous one, by passing it as `start_key` with `inclusive_start_key` set to +`false`: + +```js +const PAGE_SIZE = 500 // must not exceed the node's cap +let startKey = null +const keys = [] + +for (;;) { + const [res] = await rpc('get_addresses_datastore_keys', [[{ + address, + prefix, + is_final: true, + start_key: startKey, + // the start key was already returned by the previous page + inclusive_start_key: startKey ? false : null, + end_key: null, + inclusive_end_key: null, + count: PAGE_SIZE, + }]]) + + if (res.keys.length === 0) break + keys.push(...res.keys) + // a short page means the end of the range has been reached + if (res.keys.length < PAGE_SIZE) break + startKey = res.keys[res.keys.length - 1] +} +``` diff --git a/docs/build/massa-web3/provider.md b/docs/build/massa-web3/provider.md index 2bd9c6de5..30800c88d 100644 --- a/docs/build/massa-web3/provider.md +++ b/docs/build/massa-web3/provider.md @@ -106,6 +106,17 @@ Retrieves all storage keys registered at a given address. - `filter`: Prefix key filter. - `final`: Defaults to true. +From version `5.3.0` this method is backed by +[`get_addresses_datastore_keys`](../api/jsonrpc.mdx#get_addresses_datastore_keys) +and paginates internally, so it returns every matching key regardless of the +node's cap on a single datastore key query. + +Earlier versions instead read the full key list from +[`get_addresses`](../api/jsonrpc.mdx#get_addresses) and filtered it client-side. +That still returns every key, but it fetches the address's entire keyset on each +call and cannot filter by prefix node-side, so upgrading is recommended for +addresses holding many keys. + ```typescript readStorage(address: string, keys: Uint8Array[] | string[], final?: boolean): Promise<(Uint8Array | null)[]> ``` diff --git a/docs/node/constants.mdx b/docs/node/constants.mdx index 5be5a5af7..670606568 100644 --- a/docs/node/constants.mdx +++ b/docs/node/constants.mdx @@ -94,7 +94,7 @@ The following constants directly depend on the network deployed. | Constant | Description | Value | |----------|-------------|-------| | GENESIS_TIMESTAMP | Unix timestamp (in milliseconds) of the first block of the network | `1704289800000` Wednesday, January 3, 2024 1:50:00 PM UTC | -| VERSION | A string representing the network's version | `"DEVN.29.0"` | +| VERSION | A string representing the network's version | `"DEVN.30.0"` | | CHAINID | A number representing the network. A signed operation contains the CHAINID, and is only valid on the corresponding network. | `77658366` |