From 6e7d7357907695fee4964b2fe89f9fe59171d86e Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 11 Sep 2023 20:26:59 +0300 Subject: [PATCH 01/17] archive/storage: Backport API from chainHead Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 118 +++++++++++++++++++++++----- 1 file changed, 97 insertions(+), 21 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 4fdeaec..fb2684b 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -3,9 +3,13 @@ **Parameters**: - `hash`: String containing an hexadecimal-encoded hash of the header of the block whose storage to fetch. -- `key`: String containing the hexadecimal-encoded key to fetch in the storage. +- `items`: Array of objects. The structure of these objects is found below. - `childTrie`: `null` for main storage look-ups, or a string containing the hexadecimal-encoded key of the child trie of the "default" namespace. -- `includeDescendants`: Boolean indicating whether the key-values of all the descendants of the `key` should be returned as well. + +Each element in `items` must be an object containing the following fields: + +- `key`: String containing the hexadecimal-encoded key to fetch in the storage. +- `type`: String equal to one of: `value`, `hash`, `closestDescendantMerkleValue`, `descendantsValues`, `descendantsHashes`. **Return value**: String containing an opaque value representing the operation, or `null` if no block with that `hash` exists. @@ -32,49 +36,92 @@ This function will later generate notifications in the following format: Where `subscription` is equal to the value returned by this function, and `result` can be one of: -### item +### started -```json +``` { - "event": "item", - "key": "0x0000000...", - "value": "0x0000000...", + "result": "started", + "discardedItems": ... } ``` -Yields an item that was found in the storage. +This return value indicates that the request has successfully started. -The `key` field is a string containing the hexadecimal-encoded key of the value that was found. -If the `includeDescendants` parameter was `true`, this `key` is guaranteed to start with the `key` provided as parameter. -If the `includeDescendants` parameter was `false`, then it is also guaranteed to be equal to the `key` provided as parameter. +Where `discardedItems` is an integer indicating the number of items at the back of the array of the `items` parameters that couldn't be processed. -The `value` field is a string containing the hexadecimal-encoded value of the storage item. +If the list the JSON-RPC server is overloaded, it might refuse to accept new storage requests. In that situation, the JSON-RPC server will discard some or all the `items` passed as parameter. The number of items discarded is indicated in `discardedItems`. When that happens, the JSON-RPC client should try again after an on-going `archive_unstable_storage` operation finishes. -### waiting-for-continue +### items ```json { - "event": "waiting-for-continue" + "event": "items", + "items": [ + { + "key": "0x0000000...", + "value": "0x0000000...", + "hash": "0x0000000...", + "closestDescendantMerkleValue": "0x000000..." + }, + ... + ] } ``` -The `waiting-for-continue` event is generated after at least one `"item"` event has been generated, and indicates that the JSON-RPC client must call `archive_unstable_storageContinue` before more events are generated. +Yields one or more items that were found in the storage. -This event only ever happens if the `includeDescendants` parameter was `true`. +The `key` field is a string containing the hexadecimal-encoded key of the item. This `key` is guaranteed to start with one of the `key`s provided as parameter to `archive_unstable_storage`. +If the `type` parameter was `"value"`, `"hash"`, `"closestDescendantMerkleValue"`, then it is also guaranteed to be equal to one of the `key`s provided as parameter to `archive_unstable_storage`. -While the JSON-RPC server is waiting for `archive_unstable_storageContinue` to be called, it can generate a `stop` event indicating that it can no longer proceed with that storage access. +In the situation where the `type` parameter was `"closestDescendantMerkleValue"`, the fact that `key` is equal to a `key` that was provided as parameter is necessary in order to avoid ambiguities when multiple `items` of type `"closestDescendantMerkleValue"` were requested. + +The `value` field is set if this item corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"`. The `value` field is a string containing the hexadecimal-encoded value of the storage entry. + +The `hash` field is set if this item corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`. The `hash` field is a string containing the hexadecimal-encoded hash of the storage entry. + +The `closestDescendantMerkleValue` field is set if this item corresponds to one of the requested items whose `type` was `"closestDescendantMerkleValue"`. The trie node whose Merkle value is indicated in `closestDescendantMerkleValue` is not indicated, as determining the key of this node might incur an overhead for the JSON-RPC server. The Merkle value is equal to either the node value or the hash of the node value, as defined in the [Polkadot specification](https://spec.polkadot.network/chap-state#defn-merkle-value). + +### waitingForContinue + +```json +{ + "event": "waitingForContinue", +} +``` + +The `waitingForContinue` event is generated after at least one `"items"` event has been generated, and indicates that the JSON-RPC client must call `archive_unstable_storageContinue` before more events are generated. + +This event only ever happens if the `type` of one of the `items` provided as a parameter to `archive_unstable_storage` was `descendantsValues` or `descendantsHashes`. ### done ```json { - "event": "done" + "event": "done", + "operationId": ... +} +``` + +The `done` event indicates that an operation started with `archive_unstable_storage` went well and all result has been provided through `items` events in the past. + +If no `items` event was yielded, then the storage doesn't contain a value at the given key. + +No more event will be generated with this `subscription`. + +### error + +```json +{ + "event": "error", + "error": "..." } ``` -The `done` event indicates that everything went well and all values have been provided through `item` events in the past. +The `error` event indicates a problem during the operation. This includes failing to parse the block header. -If no `item` event was yielded, then the storage doesn't contain a value at the given key. +Repeating the same call in the future will not succeed. + +`error` is a human-readable error message indicating why the call has failed. This string isn't meant to be shown to end users, but is for developers to understand the problem. No more event will be generated with this `subscription`. @@ -86,8 +133,37 @@ No more event will be generated with this `subscription`. } ``` -The `stop` event can be generated after a `waiting-for-continue` event in order to indicate that the JSON-RPC server can't continue. The JSON-RPC client should simply try again. +The `stop` event can be generated after a `waitingForContinue` event in order to indicate that the JSON-RPC server can't continue. The JSON-RPC client should simply try again. No more event will be generated with this `subscription`. **Note**: This event is generated in very niche situations, such as a node doing a clean shutdown of all its active subscriptions before shutting down. + +## Overview + +For each item in `items`, the JSON-RPC server must start obtaining the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. + +For the purpose of storage requests, the trie root hash of the child tries of the storage can be found in the main trie at keys starting the bytes of the ASCII string `:child_storage:`. This behaviour is consistent with all the other storage-request-alike mechanisms of Polkadot and Substrate-based chains, such as host functions or libp2p network requests. + +This function should be used when the target block is older than the blocks reported by `chainHead_unstable_follow`. +Use `chainHead_unstable_storage` if instead you want to retrieve the storage of a block obtained by the `chainHead_unstable_follow`. + +`{"event": "storageItems"}` notifications will be generated. Each notification contains a list of items. The list of items, concatenated together, forms the result. + +If the `type` of an item is `value`, and `key` is associated with a storage value in the trie, then the result will include an item that contains this storage value. If `key` is not associated with a storage value in the trie, then the result will not include such item. + +If the `type` of an item is `hash`, the behavior is similar to a `type` equal to `value`, except that the cryptographic hash of the value is included in the result rather than the value itself. The hashing algorithm used is the one of the chain, which is typically blake2b. This can lead to significantly less bandwidth usage and can be used in order to compare the value of an item with a known hash and querying the full value only if it differs. + +If the `type` of an item is `descendantsValues` or `descendantsHashes`, then the result will contain zero or more items whose key starts with the `key` of this item. + +If the `type` of an item is `closestDescendantMerkleValue`, then the so-called trie Merkle value of the `key` can be found in the result. If `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then the result will not contain any relevant item. + +If `items` contains multiple identical or overlapping queries, the JSON-RPC server can choose whether to merge or not the items in the result. For example, if the request contains two items with the same key, one with `hash` and one with `value`, the JSON-RPC server can choose whether to generate two `item` objects, one with the value and one with the hash, or only a single `item` object with both `hash` and `value` set. The JSON-RPC server is encouraged to notify as soon as possible of the information at its disposal, without waiting for missing information. + +It is allowed (but discouraged) for the JSON-RPC server to provide the same information multiple times in the result, for example providing the `value` field of the same `key` twice. Forcing the JSON-RPC server to de-duplicate items in the result might lead to unnecessary overhead. + +If a `{"event": "waitingForContinue"}` notification is generated, the subscription will not generate any more notification unless the JSON-RPC client calls the `archive_unstable_storageContinue` JSON-RPC function. The JSON-RPC server is encouraged to generate this event after having sent a certain number of bytes to the JSON-RPC client in order to avoid head-of-line-blocking issues. + +## Possible errors + +- A JSON-RPC error is generated if `type` isn't one of the allowed values (similarly to a missing parameter or an invalid parameter type). From 5ebe0c270a1926709a1dcc20707fc9967da446e4 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 12 Sep 2023 18:43:57 +0300 Subject: [PATCH 02/17] archive/storage: Rename `result` to `event` for started Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index fb2684b..00b5619 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -40,12 +40,12 @@ Where `subscription` is equal to the value returned by this function, and `resul ``` { - "result": "started", + "event": "started", "discardedItems": ... } ``` -This return value indicates that the request has successfully started. +This return value indicates that the request has successfully started. The `started` event is generated at most once and can only be the first generated event. Where `discardedItems` is an integer indicating the number of items at the back of the array of the `items` parameters that couldn't be processed. From e86673176a76e9df9680ff6e45ada92a1228d327 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 12 Sep 2023 18:44:55 +0300 Subject: [PATCH 03/17] archive/storage: Remove `operationId` Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 00b5619..3585d6b 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -98,7 +98,6 @@ This event only ever happens if the `type` of one of the `items` provided as a p ```json { "event": "done", - "operationId": ... } ``` From 4dde0697bd340f862e4f30d558f182336f78ab6b Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Thu, 14 Sep 2023 15:31:43 +0300 Subject: [PATCH 04/17] archive/storage: Use method response instead of subscription Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 129 ++++++++++------------------ 1 file changed, 46 insertions(+), 83 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 3585d6b..71c01b2 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -10,8 +10,9 @@ Each element in `items` must be an object containing the following fields: - `key`: String containing the hexadecimal-encoded key to fetch in the storage. - `type`: String equal to one of: `value`, `hash`, `closestDescendantMerkleValue`, `descendantsValues`, `descendantsHashes`. +- `paginationStartKey`: This parameter is optional and should be a string containing the hexadecimal-encoded key from which the storage iteration should resume. This parameter is only valid in the context of `descendantsValues` and `descendantsHashes`. -**Return value**: String containing an opaque value representing the operation, or `null` if no block with that `hash` exists. +**Note**: The JSON-RPC server must obtain the value of the entry with the given `key` from the storage, either from the main trie of from `childTrie`. If `includeDescendants` is `true`, then the values of all the descendants must be obtained as well. @@ -19,124 +20,90 @@ If the block was previously returned by `archive_unstable_hashByHeight` at a hei If the block was previously returned by `archive_unstable_hashByHeight` at a height strictly superior to the current finalized block height (as indicated by `archive_unstable_finalizedHeight`), then the block might "disappear" and calling this function might return `null` at any point. -## Notifications format +**Return value**: A JSON object. -This function will later generate notifications in the following format: +The JSON object returned by this function has the following format: -```json -{ - "jsonrpc": "2.0", - "method": "archive_unstable_storageEvent", - "params": { - "subscription": "...", - "result": ... - } -} -``` - -Where `subscription` is equal to the value returned by this function, and `result` can be one of: - -### started - -``` -{ - "event": "started", - "discardedItems": ... -} ``` - -This return value indicates that the request has successfully started. The `started` event is generated at most once and can only be the first generated event. - -Where `discardedItems` is an integer indicating the number of items at the back of the array of the `items` parameters that couldn't be processed. - -If the list the JSON-RPC server is overloaded, it might refuse to accept new storage requests. In that situation, the JSON-RPC server will discard some or all the `items` passed as parameter. The number of items discarded is indicated in `discardedItems`. When that happens, the JSON-RPC client should try again after an on-going `archive_unstable_storage` operation finishes. - -### items - -```json { - "event": "items", - "items": [ + "result": [ { - "key": "0x0000000...", - "value": "0x0000000...", - "hash": "0x0000000...", - "closestDescendantMerkleValue": "0x000000..." + ... }, ... - ] + ], + "discardedItems": ... } ``` -Yields one or more items that were found in the storage. +Where: -The `key` field is a string containing the hexadecimal-encoded key of the item. This `key` is guaranteed to start with one of the `key`s provided as parameter to `archive_unstable_storage`. -If the `type` parameter was `"value"`, `"hash"`, `"closestDescendantMerkleValue"`, then it is also guaranteed to be equal to one of the `key`s provided as parameter to `archive_unstable_storage`. +- `result` contains a vector of JSON objects (possibly empty) that were found in the storage. +- `discardedItems` is an integer indicating the number of items at the back of the array of the `items` parameters that couldn't be processed. -In the situation where the `type` parameter was `"closestDescendantMerkleValue"`, the fact that `key` is equal to a `key` that was provided as parameter is necessary in order to avoid ambiguities when multiple `items` of type `"closestDescendantMerkleValue"` were requested. -The `value` field is set if this item corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"`. The `value` field is a string containing the hexadecimal-encoded value of the storage entry. +The JSON objects in the `"result"` field can have one of the following formats based on their type: -The `hash` field is set if this item corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`. The `hash` field is a string containing the hexadecimal-encoded hash of the storage entry. +### Value -The `closestDescendantMerkleValue` field is set if this item corresponds to one of the requested items whose `type` was `"closestDescendantMerkleValue"`. The trie node whose Merkle value is indicated in `closestDescendantMerkleValue` is not indicated, as determining the key of this node might incur an overhead for the JSON-RPC server. The Merkle value is equal to either the node value or the hash of the node value, as defined in the [Polkadot specification](https://spec.polkadot.network/chap-state#defn-merkle-value). - -### waitingForContinue - -```json +``` { - "event": "waitingForContinue", + "key": "0x0000000...", + "value": "0x0000000...", } ``` -The `waitingForContinue` event is generated after at least one `"items"` event has been generated, and indicates that the JSON-RPC client must call `archive_unstable_storageContinue` before more events are generated. - -This event only ever happens if the `type` of one of the `items` provided as a parameter to `archive_unstable_storage` was `descendantsValues` or `descendantsHashes`. +The JSON object corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"` -### done - -```json -{ - "event": "done", -} -``` +Returned when the `type` of the query was `"value"`: -The `done` event indicates that an operation started with `archive_unstable_storage` went well and all result has been provided through `items` events in the past. +- `key` is guaranteed to be equal to one of the `key`s provided as parameter +- `value` is a string containing the hexadecimal-encoded value of the storage entry. -If no `items` event was yielded, then the storage doesn't contain a value at the given key. +Returned when the `type` of the query was `"descendantsValues"`: -No more event will be generated with this `subscription`. +- `key` is guaranteed to start with one of the `key`s provided as parameter +- `value` is a string containing the hexadecimal-encoded value of the storage entry. -### error +### Hash -```json +``` { - "event": "error", - "error": "..." + "key": "0x0000000...", + "hash": "0x0000000...", } ``` -The `error` event indicates a problem during the operation. This includes failing to parse the block header. +The JSON object corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"` + +Returned when the `type` of the query was `"hash"`: -Repeating the same call in the future will not succeed. +- `key` is guaranteed to be equal to one of the `key`s provided as parameter +- `hash` is a string containing the hexadecimal-encoded value of the storage entry. -`error` is a human-readable error message indicating why the call has failed. This string isn't meant to be shown to end users, but is for developers to understand the problem. +Returned when the `type` of the query was `"descendantsHashes"`: -No more event will be generated with this `subscription`. +- `key` is guaranteed to start with one of the `key`s provided as parameter +- `hash` is a string containing the hexadecimal-encoded value of the storage entry. -### stop -```json +### ClosestDescendantMerkleValue + +``` { - "event": "stop" + "key": "0x0000000...", + "closestDescendantMerkleValue": "0x000000..." } ``` -The `stop` event can be generated after a `waitingForContinue` event in order to indicate that the JSON-RPC server can't continue. The JSON-RPC client should simply try again. +The JSON object corresponds to one of the requested items whose `type` was `"closestDescendantMerkleValue"`. -No more event will be generated with this `subscription`. +- `key` is guaranteed to be equal to one of the `key`s provided as parameter +- `closestDescendantMerkleValue`: the closest trie Merkle value of the `key` -**Note**: This event is generated in very niche situations, such as a node doing a clean shutdown of all its active subscriptions before shutting down. +If `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then the result will not contain any relevant item. + +The trie node whose Merkle value is indicated in `closestDescendantMerkleValue` is not indicated, as determining the key of this node might incur an overhead for the JSON-RPC server. The Merkle value is equal to either the node value or the hash of the node value, as defined in the [Polkadot specification](https://spec.polkadot.network/chap-state#defn-merkle-value). ## Overview @@ -147,8 +114,6 @@ For the purpose of storage requests, the trie root hash of the child tries of th This function should be used when the target block is older than the blocks reported by `chainHead_unstable_follow`. Use `chainHead_unstable_storage` if instead you want to retrieve the storage of a block obtained by the `chainHead_unstable_follow`. -`{"event": "storageItems"}` notifications will be generated. Each notification contains a list of items. The list of items, concatenated together, forms the result. - If the `type` of an item is `value`, and `key` is associated with a storage value in the trie, then the result will include an item that contains this storage value. If `key` is not associated with a storage value in the trie, then the result will not include such item. If the `type` of an item is `hash`, the behavior is similar to a `type` equal to `value`, except that the cryptographic hash of the value is included in the result rather than the value itself. The hashing algorithm used is the one of the chain, which is typically blake2b. This can lead to significantly less bandwidth usage and can be used in order to compare the value of an item with a known hash and querying the full value only if it differs. @@ -161,8 +126,6 @@ If `items` contains multiple identical or overlapping queries, the JSON-RPC serv It is allowed (but discouraged) for the JSON-RPC server to provide the same information multiple times in the result, for example providing the `value` field of the same `key` twice. Forcing the JSON-RPC server to de-duplicate items in the result might lead to unnecessary overhead. -If a `{"event": "waitingForContinue"}` notification is generated, the subscription will not generate any more notification unless the JSON-RPC client calls the `archive_unstable_storageContinue` JSON-RPC function. The JSON-RPC server is encouraged to generate this event after having sent a certain number of bytes to the JSON-RPC client in order to avoid head-of-line-blocking issues. - ## Possible errors - A JSON-RPC error is generated if `type` isn't one of the allowed values (similarly to a missing parameter or an invalid parameter type). From 7c5d5b50a1d540c3fb6f4f361d01c42a2fcbb429 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Thu, 14 Sep 2023 15:32:51 +0300 Subject: [PATCH 05/17] archive/storage: Remove the continue function Signed-off-by: Alexandru Vasile --- src/SUMMARY.md | 1 - src/api/archive_unstable_storageContinue.md | 15 --------------- 2 files changed, 16 deletions(-) delete mode 100644 src/api/archive_unstable_storageContinue.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8965602..dee1378 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -15,7 +15,6 @@ - [archive_unstable_hashByHeight](api/archive_unstable_hashByHeight.md) - [archive_unstable_header](api/archive_unstable_header.md) - [archive_unstable_storage](api/archive_unstable_storage.md) - - [archive_unstable_storageContinue](api/archive_unstable_storageContinue.md) - [chainHead](api/chainHead.md) - [chainHead_unstable_body](api/chainHead_unstable_body.md) - [chainHead_unstable_call](api/chainHead_unstable_call.md) diff --git a/src/api/archive_unstable_storageContinue.md b/src/api/archive_unstable_storageContinue.md deleted file mode 100644 index 668fffc..0000000 --- a/src/api/archive_unstable_storageContinue.md +++ /dev/null @@ -1,15 +0,0 @@ -# archive_unstable_storageContinue - -**Parameters**: - -- `subscription`: An opaque string that was returned by `archive_unstable_storage`. - -**Return value**: *null* - -Resumes a storage fetch started with `archive_unstable_storage` after it has generated a `waiting-for-continue` event. - -Has no effect if the `subscription` is invalid or refers to a subscription that has emitted a `{"event": "stop"}` event. - -## Possible errors - -- A JSON-RPC error is generated if the `subscription` is valid but hasn't generated a `waiting-for-continue` event. From a9db9f4ff504b8be9d5661afc365fdd3540223e2 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> Date: Thu, 21 Sep 2023 20:50:06 +0300 Subject: [PATCH 06/17] Update src/api/archive_unstable_storage.md Co-authored-by: James Wilson --- src/api/archive_unstable_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 71c01b2..8111b06 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -62,7 +62,7 @@ Returned when the `type` of the query was `"value"`: Returned when the `type` of the query was `"descendantsValues"`: -- `key` is guaranteed to start with one of the `key`s provided as parameter +- `key` is guaranteed to start with one of the `key`s provided as a parameter - `value` is a string containing the hexadecimal-encoded value of the storage entry. ### Hash From aff40ed5addea081533e9325645a54b4696011b6 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> Date: Thu, 21 Sep 2023 20:50:32 +0300 Subject: [PATCH 07/17] Update src/api/archive_unstable_storage.md Co-authored-by: James Wilson --- src/api/archive_unstable_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 8111b06..60094b8 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -107,7 +107,7 @@ The trie node whose Merkle value is indicated in `closestDescendantMerkleValue` ## Overview -For each item in `items`, the JSON-RPC server must start obtaining the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. +For each item in `items`, the JSON-RPC server must obtain the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. For the purpose of storage requests, the trie root hash of the child tries of the storage can be found in the main trie at keys starting the bytes of the ASCII string `:child_storage:`. This behaviour is consistent with all the other storage-request-alike mechanisms of Polkadot and Substrate-based chains, such as host functions or libp2p network requests. From 0fb19322f67268fa6a8069770b283f22008229a0 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Fri, 22 Sep 2023 13:29:16 +0300 Subject: [PATCH 08/17] archive/storage: Adjust notes Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 60094b8..72a8053 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -14,11 +14,11 @@ Each element in `items` must be an object containing the following fields: **Note**: -The JSON-RPC server must obtain the value of the entry with the given `key` from the storage, either from the main trie of from `childTrie`. If `includeDescendants` is `true`, then the values of all the descendants must be obtained as well. +For each item in `items`, the JSON-RPC server must start obtaining the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. -If the block was previously returned by `archive_unstable_hashByHeight` at a height inferior or equal to the current finalized block height (as indicated by `archive_unstable_finalizedHeight`), then calling this method multiple times is guaranteed to always return non-null and always the same results. +If the height of the block hash provided is less than or equal to the current finalized block height (which can be obtained via archive_unstable_finalizedHeight), then calling this method with the same parameters will always return the same response. -If the block was previously returned by `archive_unstable_hashByHeight` at a height strictly superior to the current finalized block height (as indicated by `archive_unstable_finalizedHeight`), then the block might "disappear" and calling this function might return `null` at any point. +If the height of the block hash provided is greater than the current finalized block height, then the block might be pruned at any time and calling this method may return null. **Return value**: A JSON object. From bfd5dd4c795f3503839d3a72f963baca5a66e14e Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Fri, 22 Sep 2023 13:31:51 +0300 Subject: [PATCH 09/17] archive/storage: Add missing dots and unify params Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 72a8053..db06d68 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -53,16 +53,16 @@ The JSON objects in the `"result"` field can have one of the following formats b } ``` -The JSON object corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"` +The JSON object corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"`. Returned when the `type` of the query was `"value"`: -- `key` is guaranteed to be equal to one of the `key`s provided as parameter +- `key` is guaranteed to be equal to one of the `key`s provided. - `value` is a string containing the hexadecimal-encoded value of the storage entry. Returned when the `type` of the query was `"descendantsValues"`: -- `key` is guaranteed to start with one of the `key`s provided as a parameter +- `key` is guaranteed to start with one of the `key`s provided. - `value` is a string containing the hexadecimal-encoded value of the storage entry. ### Hash @@ -74,16 +74,16 @@ Returned when the `type` of the query was `"descendantsValues"`: } ``` -The JSON object corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"` +The JSON object corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`. Returned when the `type` of the query was `"hash"`: -- `key` is guaranteed to be equal to one of the `key`s provided as parameter +- `key` is guaranteed to be equal to one of the `key`s provided. - `hash` is a string containing the hexadecimal-encoded value of the storage entry. Returned when the `type` of the query was `"descendantsHashes"`: -- `key` is guaranteed to start with one of the `key`s provided as parameter +- `key` is guaranteed to start with one of the `key`s provided. - `hash` is a string containing the hexadecimal-encoded value of the storage entry. @@ -98,8 +98,8 @@ Returned when the `type` of the query was `"descendantsHashes"`: The JSON object corresponds to one of the requested items whose `type` was `"closestDescendantMerkleValue"`. -- `key` is guaranteed to be equal to one of the `key`s provided as parameter -- `closestDescendantMerkleValue`: the closest trie Merkle value of the `key` +- `key` is guaranteed to be equal to one of the `key`s provided. +- `closestDescendantMerkleValue` is the closest trie Merkle value of the `key`. If `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then the result will not contain any relevant item. From 5a58b9a02a63f3c8a0981953d39702ff66fbec2c Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Fri, 22 Sep 2023 13:46:14 +0300 Subject: [PATCH 10/17] archive/storage: Remove the overview section Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 44 +++++++++++------------------ 1 file changed, 17 insertions(+), 27 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index db06d68..46fb50d 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -16,10 +16,18 @@ Each element in `items` must be an object containing the following fields: For each item in `items`, the JSON-RPC server must start obtaining the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. -If the height of the block hash provided is less than or equal to the current finalized block height (which can be obtained via archive_unstable_finalizedHeight), then calling this method with the same parameters will always return the same response. +For the purpose of storage requests, the trie root hash of the child tries of the storage can be found in the main trie at keys starting the bytes of the ASCII string `:child_storage:`. This behaviour is consistent with all the other storage-request-alike mechanisms of Polkadot and Substrate-based chains, such as host functions or libp2p network requests. +If the height of the block hash provided is less than or equal to the current finalized block height (which can be obtained via archive_unstable_finalizedHeight), then calling this method with the same parameters will always return the same response. If the height of the block hash provided is greater than the current finalized block height, then the block might be pruned at any time and calling this method may return null. +This function should be used when the target block is older than the blocks reported by `chainHead_unstable_follow`. +Use `chainHead_unstable_storage` if instead you want to retrieve the storage of a block obtained by the `chainHead_unstable_follow`. + +If `items` contains multiple identical or overlapping queries, the JSON-RPC server can choose whether to merge or not the items in the result. For example, if the request contains two items with the same key, one with `hash` and one with `value`, the JSON-RPC server can choose whether to generate two `item` objects, one with the value and one with the hash, or only a single `item` object with both `hash` and `value` set. The JSON-RPC server is encouraged to notify as soon as possible of the information at its disposal, without waiting for missing information. + +It is allowed (but discouraged) for the JSON-RPC server to provide the same information multiple times in the result, for example providing the `value` field of the same `key` twice. Forcing the JSON-RPC server to de-duplicate items in the result might lead to unnecessary overhead. + **Return value**: A JSON object. The JSON object returned by this function has the following format: @@ -41,7 +49,6 @@ Where: - `result` contains a vector of JSON objects (possibly empty) that were found in the storage. - `discardedItems` is an integer indicating the number of items at the back of the array of the `items` parameters that couldn't be processed. - The JSON objects in the `"result"` field can have one of the following formats based on their type: ### Value @@ -55,6 +62,8 @@ The JSON objects in the `"result"` field can have one of the following formats b The JSON object corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"`. +If the `key` is not associated with a storage value in the trie, then no response is generated. + Returned when the `type` of the query was `"value"`: - `key` is guaranteed to be equal to one of the `key`s provided. @@ -76,15 +85,17 @@ Returned when the `type` of the query was `"descendantsValues"`: The JSON object corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`. +If the `key` is not associated with a storage value in the trie, then no response is generated. + Returned when the `type` of the query was `"hash"`: - `key` is guaranteed to be equal to one of the `key`s provided. -- `hash` is a string containing the hexadecimal-encoded value of the storage entry. +- `hash` is a string containing the hexadecimal-encoded cryptographic hash of the storage entry. Returned when the `type` of the query was `"descendantsHashes"`: - `key` is guaranteed to start with one of the `key`s provided. -- `hash` is a string containing the hexadecimal-encoded value of the storage entry. +- `hash` is a string containing the hexadecimal-encoded cryptographic hash of the storage entry. ### ClosestDescendantMerkleValue @@ -98,34 +109,13 @@ Returned when the `type` of the query was `"descendantsHashes"`: The JSON object corresponds to one of the requested items whose `type` was `"closestDescendantMerkleValue"`. +If the `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then no response is generated. + - `key` is guaranteed to be equal to one of the `key`s provided. - `closestDescendantMerkleValue` is the closest trie Merkle value of the `key`. -If `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then the result will not contain any relevant item. - The trie node whose Merkle value is indicated in `closestDescendantMerkleValue` is not indicated, as determining the key of this node might incur an overhead for the JSON-RPC server. The Merkle value is equal to either the node value or the hash of the node value, as defined in the [Polkadot specification](https://spec.polkadot.network/chap-state#defn-merkle-value). -## Overview - -For each item in `items`, the JSON-RPC server must obtain the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. - -For the purpose of storage requests, the trie root hash of the child tries of the storage can be found in the main trie at keys starting the bytes of the ASCII string `:child_storage:`. This behaviour is consistent with all the other storage-request-alike mechanisms of Polkadot and Substrate-based chains, such as host functions or libp2p network requests. - -This function should be used when the target block is older than the blocks reported by `chainHead_unstable_follow`. -Use `chainHead_unstable_storage` if instead you want to retrieve the storage of a block obtained by the `chainHead_unstable_follow`. - -If the `type` of an item is `value`, and `key` is associated with a storage value in the trie, then the result will include an item that contains this storage value. If `key` is not associated with a storage value in the trie, then the result will not include such item. - -If the `type` of an item is `hash`, the behavior is similar to a `type` equal to `value`, except that the cryptographic hash of the value is included in the result rather than the value itself. The hashing algorithm used is the one of the chain, which is typically blake2b. This can lead to significantly less bandwidth usage and can be used in order to compare the value of an item with a known hash and querying the full value only if it differs. - -If the `type` of an item is `descendantsValues` or `descendantsHashes`, then the result will contain zero or more items whose key starts with the `key` of this item. - -If the `type` of an item is `closestDescendantMerkleValue`, then the so-called trie Merkle value of the `key` can be found in the result. If `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then the result will not contain any relevant item. - -If `items` contains multiple identical or overlapping queries, the JSON-RPC server can choose whether to merge or not the items in the result. For example, if the request contains two items with the same key, one with `hash` and one with `value`, the JSON-RPC server can choose whether to generate two `item` objects, one with the value and one with the hash, or only a single `item` object with both `hash` and `value` set. The JSON-RPC server is encouraged to notify as soon as possible of the information at its disposal, without waiting for missing information. - -It is allowed (but discouraged) for the JSON-RPC server to provide the same information multiple times in the result, for example providing the `value` field of the same `key` twice. Forcing the JSON-RPC server to de-duplicate items in the result might lead to unnecessary overhead. - ## Possible errors - A JSON-RPC error is generated if `type` isn't one of the allowed values (similarly to a missing parameter or an invalid parameter type). From 2e955eee5836f04ff8d3440b2fc9fd7a48feebc0 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> Date: Wed, 11 Oct 2023 14:43:14 +0200 Subject: [PATCH 11/17] Update src/api/archive_unstable_storage.md Co-authored-by: James Wilson --- src/api/archive_unstable_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 46fb50d..2671703 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -2,7 +2,7 @@ **Parameters**: -- `hash`: String containing an hexadecimal-encoded hash of the header of the block whose storage to fetch. +- `hash`: String containing a hexadecimal-encoded hash of the header of the block whose storage to fetch. - `items`: Array of objects. The structure of these objects is found below. - `childTrie`: `null` for main storage look-ups, or a string containing the hexadecimal-encoded key of the child trie of the "default" namespace. From 22f1a1571ca82db823bf8479ee7d6d2b3cca6e07 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Oct 2023 14:53:16 +0200 Subject: [PATCH 12/17] archive: Move note section above possible errors Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 32 ++++++++++++++--------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 2671703..3536a3e 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -12,22 +12,6 @@ Each element in `items` must be an object containing the following fields: - `type`: String equal to one of: `value`, `hash`, `closestDescendantMerkleValue`, `descendantsValues`, `descendantsHashes`. - `paginationStartKey`: This parameter is optional and should be a string containing the hexadecimal-encoded key from which the storage iteration should resume. This parameter is only valid in the context of `descendantsValues` and `descendantsHashes`. -**Note**: - -For each item in `items`, the JSON-RPC server must start obtaining the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. - -For the purpose of storage requests, the trie root hash of the child tries of the storage can be found in the main trie at keys starting the bytes of the ASCII string `:child_storage:`. This behaviour is consistent with all the other storage-request-alike mechanisms of Polkadot and Substrate-based chains, such as host functions or libp2p network requests. - -If the height of the block hash provided is less than or equal to the current finalized block height (which can be obtained via archive_unstable_finalizedHeight), then calling this method with the same parameters will always return the same response. -If the height of the block hash provided is greater than the current finalized block height, then the block might be pruned at any time and calling this method may return null. - -This function should be used when the target block is older than the blocks reported by `chainHead_unstable_follow`. -Use `chainHead_unstable_storage` if instead you want to retrieve the storage of a block obtained by the `chainHead_unstable_follow`. - -If `items` contains multiple identical or overlapping queries, the JSON-RPC server can choose whether to merge or not the items in the result. For example, if the request contains two items with the same key, one with `hash` and one with `value`, the JSON-RPC server can choose whether to generate two `item` objects, one with the value and one with the hash, or only a single `item` object with both `hash` and `value` set. The JSON-RPC server is encouraged to notify as soon as possible of the information at its disposal, without waiting for missing information. - -It is allowed (but discouraged) for the JSON-RPC server to provide the same information multiple times in the result, for example providing the `value` field of the same `key` twice. Forcing the JSON-RPC server to de-duplicate items in the result might lead to unnecessary overhead. - **Return value**: A JSON object. The JSON object returned by this function has the following format: @@ -116,6 +100,22 @@ If the `key` doesn't exist in the trie, then the Merkle value of the closest des The trie node whose Merkle value is indicated in `closestDescendantMerkleValue` is not indicated, as determining the key of this node might incur an overhead for the JSON-RPC server. The Merkle value is equal to either the node value or the hash of the node value, as defined in the [Polkadot specification](https://spec.polkadot.network/chap-state#defn-merkle-value). +**Note**: + +For each item in `items`, the JSON-RPC server must start obtaining the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. + +For the purpose of storage requests, the trie root hash of the child tries of the storage can be found in the main trie at keys starting the bytes of the ASCII string `:child_storage:`. This behaviour is consistent with all the other storage-request-alike mechanisms of Polkadot and Substrate-based chains, such as host functions or libp2p network requests. + +If the height of the block hash provided is less than or equal to the current finalized block height (which can be obtained via archive_unstable_finalizedHeight), then calling this method with the same parameters will always return the same response. +If the height of the block hash provided is greater than the current finalized block height, then the block might be pruned at any time and calling this method may return null. + +This function should be used when the target block is older than the blocks reported by `chainHead_unstable_follow`. +Use `chainHead_unstable_storage` if instead you want to retrieve the storage of a block obtained by the `chainHead_unstable_follow`. + +If `items` contains multiple identical or overlapping queries, the JSON-RPC server can choose whether to merge or not the items in the result. For example, if the request contains two items with the same key, one with `hash` and one with `value`, the JSON-RPC server can choose whether to generate two `item` objects, one with the value and one with the hash, or only a single `item` object with both `hash` and `value` set. The JSON-RPC server is encouraged to notify as soon as possible of the information at its disposal, without waiting for missing information. + +It is allowed (but discouraged) for the JSON-RPC server to provide the same information multiple times in the result, for example providing the `value` field of the same `key` twice. Forcing the JSON-RPC server to de-duplicate items in the result might lead to unnecessary overhead. + ## Possible errors - A JSON-RPC error is generated if `type` isn't one of the allowed values (similarly to a missing parameter or an invalid parameter type). From 24f6a7d3daac7bcf028795e002b4e862a232dff3 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Oct 2023 14:54:38 +0200 Subject: [PATCH 13/17] archive: Rename note section to overview Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 3536a3e..0d122f2 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -100,7 +100,7 @@ If the `key` doesn't exist in the trie, then the Merkle value of the closest des The trie node whose Merkle value is indicated in `closestDescendantMerkleValue` is not indicated, as determining the key of this node might incur an overhead for the JSON-RPC server. The Merkle value is equal to either the node value or the hash of the node value, as defined in the [Polkadot specification](https://spec.polkadot.network/chap-state#defn-merkle-value). -**Note**: +## Overview For each item in `items`, the JSON-RPC server must start obtaining the value of the entry with the given `key` from the storage, either from the main trie or from `childTrie`. If `type` is `descendantsValues` or `descendantsHashes`, then it must also obtain the values of all the descendants of the entry. From fe357ad78e4bd14c49b960005eda8ead2323907b Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Oct 2023 14:55:59 +0200 Subject: [PATCH 14/17] archive: Remove last line Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 0d122f2..1a6bdbc 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -112,7 +112,7 @@ If the height of the block hash provided is greater than the current finalized b This function should be used when the target block is older than the blocks reported by `chainHead_unstable_follow`. Use `chainHead_unstable_storage` if instead you want to retrieve the storage of a block obtained by the `chainHead_unstable_follow`. -If `items` contains multiple identical or overlapping queries, the JSON-RPC server can choose whether to merge or not the items in the result. For example, if the request contains two items with the same key, one with `hash` and one with `value`, the JSON-RPC server can choose whether to generate two `item` objects, one with the value and one with the hash, or only a single `item` object with both `hash` and `value` set. The JSON-RPC server is encouraged to notify as soon as possible of the information at its disposal, without waiting for missing information. +If `items` contains multiple identical or overlapping queries, the JSON-RPC server can choose whether to merge or not the items in the result. For example, if the request contains two items with the same key, one with `hash` and one with `value`, the JSON-RPC server can choose whether to generate two `item` objects, one with the value and one with the hash, or only a single `item` object with both `hash` and `value` set. It is allowed (but discouraged) for the JSON-RPC server to provide the same information multiple times in the result, for example providing the `value` field of the same `key` twice. Forcing the JSON-RPC server to de-duplicate items in the result might lead to unnecessary overhead. From d26e3ce4e624ea2dd21fc557d99d5f7865d00681 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Oct 2023 14:56:47 +0200 Subject: [PATCH 15/17] archive: Remove storageContinue method Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageContinue.md | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 src/api/archive_unstable_storageContinue.md diff --git a/src/api/archive_unstable_storageContinue.md b/src/api/archive_unstable_storageContinue.md deleted file mode 100644 index 47c5ee1..0000000 --- a/src/api/archive_unstable_storageContinue.md +++ /dev/null @@ -1,15 +0,0 @@ -# archive_unstable_storageContinue - -**Parameters**: - -- `subscription`: An opaque string that was returned by `archive_unstable_storage`. - -**Return value**: *null* - -Resumes a storage fetch started with `archive_unstable_storage` after it has generated a `waitingForContinue` event. - -Has no effect if the `subscription` is invalid or refers to a subscription that has emitted a `{"event": "stop"}` event. - -## Possible errors - -- A JSON-RPC error is generated if the `subscription` is valid but hasn't generated a `waitingForContinue` event. From 00d6825c262a5db917aed270175b133d3f820da7 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> Date: Wed, 15 Nov 2023 12:56:31 +0200 Subject: [PATCH 16/17] Update src/api/archive_unstable_storage.md Co-authored-by: Niklas Adolfsson --- src/api/archive_unstable_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index 1a6bdbc..dde52b1 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -74,7 +74,7 @@ If the `key` is not associated with a storage value in the trie, then no respons Returned when the `type` of the query was `"hash"`: - `key` is guaranteed to be equal to one of the `key`s provided. -- `hash` is a string containing the hexadecimal-encoded cryptographic hash of the storage entry. +- `hash` is a string containing the hexadecimal-encoded hash of the storage entry. Returned when the `type` of the query was `"descendantsHashes"`: From e894512afbf7da78b9f3a381ebdf255f834b5bee Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 15 Nov 2023 13:24:10 +0200 Subject: [PATCH 17/17] archive/storage: Clarify empty responses Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storage.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/api/archive_unstable_storage.md b/src/api/archive_unstable_storage.md index dde52b1..f68dd24 100644 --- a/src/api/archive_unstable_storage.md +++ b/src/api/archive_unstable_storage.md @@ -46,7 +46,7 @@ The JSON objects in the `"result"` field can have one of the following formats b The JSON object corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"`. -If the `key` is not associated with a storage value in the trie, then no response is generated. +If the `key` is not associated with a storage value in the trie, then no response is generated in the `"result"` vector for this item. Returned when the `type` of the query was `"value"`: @@ -69,7 +69,7 @@ Returned when the `type` of the query was `"descendantsValues"`: The JSON object corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`. -If the `key` is not associated with a storage value in the trie, then no response is generated. +If the `key` is not associated with a storage value in the trie, then no response is generated in the `"result"` vector for this item. Returned when the `type` of the query was `"hash"`: @@ -93,7 +93,7 @@ Returned when the `type` of the query was `"descendantsHashes"`: The JSON object corresponds to one of the requested items whose `type` was `"closestDescendantMerkleValue"`. -If the `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then no response is generated. +If the `key` doesn't exist in the trie, then the Merkle value of the closest descendant of `key` (including branch nodes) is provided. If `key` doesn't have any descendant in the trie, then no response is generated in the `"result"` vector for this item. - `key` is guaranteed to be equal to one of the `key`s provided. - `closestDescendantMerkleValue` is the closest trie Merkle value of the `key`.