From 5922d71a4f5ddb27cf5877645e3a213bbed94e73 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Thu, 1 Aug 2024 12:59:09 +0300 Subject: [PATCH 01/18] archive: Introduce archive_storageDiff Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 104 ++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 src/api/archive_unstable_storageDiff.md diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md new file mode 100644 index 0000000..42ce814 --- /dev/null +++ b/src/api/archive_unstable_storageDiff.md @@ -0,0 +1,104 @@ +# archive_unstable_storageDiff + +**Parameters**: + +- `currentHash`: String containing a hexadecimal-encoded hash of the header of the block whose storage difference will be retrieved. The storage difference is calculated between the `currentHash` block and the parent of the `currentHash` block. + +- `fromHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. When this parameter is provided, the storage difference is calculated between the `currentHash` block and the `fromHash` block. If this parameter is not provided, the storage difference is calculated between the `currentHash` block and the parent of the `currentHash` block. + +- `items` (optional): JSON object containing the following fields: + + ```json + "items": { + "prefixes": [ + { + "key": "0x...", + "type": "value" | "hash" | "none", + }, + ], + "excludeKeyPrefixes": [ + "0x...", + ], + "childTrie": "0x...", + } + ``` + + If the `items` parameter is not provided, the storage difference is calculated for all keys of the main storage trie. + - `prefixes` (optional): Array of JSON objects describing how the storage difference will be calculated. Each object contains the following fields: + - `key`: String containing the hexadecimal-encoded key prefix under which the storage difference is calculated. + - `type`: String equal to one of: `value`, `hash`, `none`. + - containing the key prefixes for which the storage difference will be calculated. If this parameter is not provided, the storage difference is calculated for all keys. + - `excludeKeyPrefixes` (optional): Array of strings containing the key prefixes for which the storage difference will not be calculated. If this parameter is not provided, the storage difference is calculated for all keys. + - `childTrie` (optional): A string containing the hexadecimal-encoded key of the child trie of the "default" namespace. If this parameter is not provided, the storage difference is calculated for the main storage. + +**Return value**: String containing an opaque value representing the operation. + +This function calculates the storage difference between two blocks. The storage difference is calculated by comparing the storage of the `fromHash` block with the storage of the `currentHash` block. If the `fromHash` parameter is not provided, the storage difference is calculated between the parent of the `currentHash` block and the `currentHash` block. + +The storage difference is calculated for the main storage trie by default. The `items` parameter can be used to specify the key prefixes for which the storage difference will be calculated. The `prefixes` field contains an array of objects, each describing a key prefix and the type of the storage difference to calculate. The `excludeKeyPrefixes` field contains an array of key prefixes for which the storage difference will not be calculated. The `childTrie` field specifies the child trie for which the storage difference will be calculated. + +The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription per JSON-RPC client. Trying to open more might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new subscriptions. + +## Notifications format + +This function will later generate notifications with the following format: + +```json +{ + "jsonrpc": "2.0", + "method": "archive_unstable_storageDiffEvent", + "params": { + "subscription": "...", + "result": ... + } +} +``` + +Where `subscription` is the value returned by this function, and `result` can be one of the following: + +### differences + +```json +{ + "event": "differences", + "differences": [ + { + "key": "0x...", + "value": "0x...", + "hash": "0x...", + "type": "added" | "modified" | "deleted", + }, + ], +} +``` + +The `differences` field contains an array of objects, each describing a storage difference. + +The `key` field contains the hexadecimal-encoded key of the storage entry. If the a key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. If the `excludeKeyPrefixes` field was provided in the `items` parameter, the `key` field is guaranteed not to start with any of the excluded key prefixes provided. + +The `value` field contains the hexadecimal-encoded value of the storage entry. This field is present when prefixes are not provided or when the `type` field in the `items` parameter is set to `value`. + +The `hash` field contains the hexadecimal-encoded hash of the storage entry. This field is only present when the `type` field in the `items` parameter is set to `hash`. + +When the `type` field in the `items` parameter is set to `none`, the `value` and `hash` fields are not present. + +The `type` field indicates the type of the storage difference. The possible values are: + +- `added`: The storage entry was added. +- `modified`: The storage entry was modified. +- `deleted`: The storage entry was deleted. + +### done + +```json +{ + "event": "done", +} +``` + +This notification is sent when the storage difference calculation is complete. + +## Possible errors + +- A JSON-RPC error can be generated if the JSON-RPC client has to many active subscriptions to `archive_unstable_storageDiff`. +- A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type). From 6c8e97042a9ce47ebc372df8d00a40017154e9b1 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Thu, 1 Aug 2024 13:02:38 +0300 Subject: [PATCH 02/18] archive: Stop the store diff subscription Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 2 +- src/api/archive_unstable_storageDiffStop.md | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 src/api/archive_unstable_storageDiffStop.md diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 42ce814..c07ae62 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -7,7 +7,7 @@ - `fromHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. When this parameter is provided, the storage difference is calculated between the `currentHash` block and the `fromHash` block. If this parameter is not provided, the storage difference is calculated between the `currentHash` block and the parent of the `currentHash` block. - `items` (optional): JSON object containing the following fields: - + ```json "items": { "prefixes": [ diff --git a/src/api/archive_unstable_storageDiffStop.md b/src/api/archive_unstable_storageDiffStop.md new file mode 100644 index 0000000..1f96526 --- /dev/null +++ b/src/api/archive_unstable_storageDiffStop.md @@ -0,0 +1,11 @@ +# archive_unstable_storageDiff + +**Parameters**: + +- `diffSubscription`: An opaque string that was returned by `archive_unstable_storageDiff`. + +**Return value**: *null* + +Stops a subscription started with `archive_unstable_storageDiff`. Has no effect if the `diffSubscription` is invalid or refers to a subscription that has already emitted a `{"event": "done"}` event. + +JSON-RPC client implementations must be aware that, due to the asynchronous nature of JSON-RPC client <-> server communication, they might still receive storage difference notifications, for example because these notifications were already in the process of being sent back by the JSON-RPC server. From 7e20f5fd494f529bb90c42234d4c4244a24f4caf Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Thu, 1 Aug 2024 13:07:01 +0300 Subject: [PATCH 03/18] archive: Add ability to continue storage diff Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 10 ++++++++++ src/api/archive_unstable_storageDiffContinue.md | 13 +++++++++++++ src/api/archive_unstable_storageDiffStop.md | 4 ++-- 3 files changed, 25 insertions(+), 2 deletions(-) create mode 100644 src/api/archive_unstable_storageDiffContinue.md diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index c07ae62..7773a2b 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -88,6 +88,16 @@ The `type` field indicates the type of the storage difference. The possible valu - `modified`: The storage entry was modified. - `deleted`: The storage entry was deleted. +### continue + +```json +{ + "event": "continue", +} +``` + +This notification is sent when the storage difference calculation is paused and needs to be resumed. The user must call `archive_unstable_storageDiffContinue` with the subscription value to continue the calculation. + ### done ```json diff --git a/src/api/archive_unstable_storageDiffContinue.md b/src/api/archive_unstable_storageDiffContinue.md new file mode 100644 index 0000000..27bf421 --- /dev/null +++ b/src/api/archive_unstable_storageDiffContinue.md @@ -0,0 +1,13 @@ +# archive_unstable_storageDiffContinue + +**Parameters**: + +- `subscription`: An opaque string that was returned by `archive_unstable_storageDiff`. + +**Return value**: *null* + +Continues a subscription started with `archive_unstable_storageDiff`. Has no effect if the `subscription` is invalid or refers to a subscription that has already emitted a `{"event": "done"}` event. + +## Possible errors + +- A JSON-RPC error generated if the `subscription` is valid but haven't generated a `{"event": "continue"}` event. diff --git a/src/api/archive_unstable_storageDiffStop.md b/src/api/archive_unstable_storageDiffStop.md index 1f96526..ba7d72e 100644 --- a/src/api/archive_unstable_storageDiffStop.md +++ b/src/api/archive_unstable_storageDiffStop.md @@ -2,10 +2,10 @@ **Parameters**: -- `diffSubscription`: An opaque string that was returned by `archive_unstable_storageDiff`. +- `subscription`: An opaque string that was returned by `archive_unstable_storageDiff`. **Return value**: *null* -Stops a subscription started with `archive_unstable_storageDiff`. Has no effect if the `diffSubscription` is invalid or refers to a subscription that has already emitted a `{"event": "done"}` event. +Stops a subscription started with `archive_unstable_storageDiff`. Has no effect if the `subscription` is invalid or refers to a subscription that has already emitted a `{"event": "done"}` event. JSON-RPC client implementations must be aware that, due to the asynchronous nature of JSON-RPC client <-> server communication, they might still receive storage difference notifications, for example because these notifications were already in the process of being sent back by the JSON-RPC server. From 70515bc90fc6ba67279672ac3a4ff82b35677b5b Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 16:43:07 +0300 Subject: [PATCH 04/18] archive: Rename currentHash->hash and fromHash->previousHash Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 7773a2b..4eacb1d 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -2,9 +2,9 @@ **Parameters**: -- `currentHash`: String containing a hexadecimal-encoded hash of the header of the block whose storage difference will be retrieved. The storage difference is calculated between the `currentHash` block and the parent of the `currentHash` block. +- `hash`: String containing a hexadecimal-encoded hash of the header of the block whose storage difference will be retrieved. The storage difference is calculated between the `hash` block and the parent of the `hash` block. -- `fromHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. When this parameter is provided, the storage difference is calculated between the `currentHash` block and the `fromHash` block. If this parameter is not provided, the storage difference is calculated between the `currentHash` block and the parent of the `currentHash` block. +- `previousHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. When this parameter is provided, the storage difference is calculated between the `hash` block and the `previousHash` block. If this parameter is not provided, the storage difference is calculated between the `hash` block and the parent of the `hash` block. - `items` (optional): JSON object containing the following fields: @@ -33,7 +33,7 @@ **Return value**: String containing an opaque value representing the operation. -This function calculates the storage difference between two blocks. The storage difference is calculated by comparing the storage of the `fromHash` block with the storage of the `currentHash` block. If the `fromHash` parameter is not provided, the storage difference is calculated between the parent of the `currentHash` block and the `currentHash` block. +This function calculates the storage difference between two blocks. The storage difference is calculated by comparing the storage of the `previousHash` block with the storage of the `hash` block. If the `previousHash` parameter is not provided, the storage difference is calculated between the parent of the `hash` block and the `hash` block. The storage difference is calculated for the main storage trie by default. The `items` parameter can be used to specify the key prefixes for which the storage difference will be calculated. The `prefixes` field contains an array of objects, each describing a key prefix and the type of the storage difference to calculate. The `excludeKeyPrefixes` field contains an array of key prefixes for which the storage difference will not be calculated. The `childTrie` field specifies the child trie for which the storage difference will be calculated. From 9fe2b32af9312ddb8aee7da4410ecd96cc50083a Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 16:44:00 +0300 Subject: [PATCH 05/18] archive: Remove leftover comment Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 4eacb1d..1480fbd 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -27,7 +27,6 @@ - `prefixes` (optional): Array of JSON objects describing how the storage difference will be calculated. Each object contains the following fields: - `key`: String containing the hexadecimal-encoded key prefix under which the storage difference is calculated. - `type`: String equal to one of: `value`, `hash`, `none`. - - containing the key prefixes for which the storage difference will be calculated. If this parameter is not provided, the storage difference is calculated for all keys. - `excludeKeyPrefixes` (optional): Array of strings containing the key prefixes for which the storage difference will not be calculated. If this parameter is not provided, the storage difference is calculated for all keys. - `childTrie` (optional): A string containing the hexadecimal-encoded key of the child trie of the "default" namespace. If this parameter is not provided, the storage difference is calculated for the main storage. From aeb19a0fdd83be4b9697157c20c402eeee864d59 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 16:44:59 +0300 Subject: [PATCH 06/18] archive: Remove `excludeKeyPrefixes` param Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 1480fbd..8d7ee4a 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -16,9 +16,6 @@ "type": "value" | "hash" | "none", }, ], - "excludeKeyPrefixes": [ - "0x...", - ], "childTrie": "0x...", } ``` @@ -27,14 +24,13 @@ - `prefixes` (optional): Array of JSON objects describing how the storage difference will be calculated. Each object contains the following fields: - `key`: String containing the hexadecimal-encoded key prefix under which the storage difference is calculated. - `type`: String equal to one of: `value`, `hash`, `none`. - - `excludeKeyPrefixes` (optional): Array of strings containing the key prefixes for which the storage difference will not be calculated. If this parameter is not provided, the storage difference is calculated for all keys. - `childTrie` (optional): A string containing the hexadecimal-encoded key of the child trie of the "default" namespace. If this parameter is not provided, the storage difference is calculated for the main storage. **Return value**: String containing an opaque value representing the operation. This function calculates the storage difference between two blocks. The storage difference is calculated by comparing the storage of the `previousHash` block with the storage of the `hash` block. If the `previousHash` parameter is not provided, the storage difference is calculated between the parent of the `hash` block and the `hash` block. -The storage difference is calculated for the main storage trie by default. The `items` parameter can be used to specify the key prefixes for which the storage difference will be calculated. The `prefixes` field contains an array of objects, each describing a key prefix and the type of the storage difference to calculate. The `excludeKeyPrefixes` field contains an array of key prefixes for which the storage difference will not be calculated. The `childTrie` field specifies the child trie for which the storage difference will be calculated. +The storage difference is calculated for the main storage trie by default. The `items` parameter can be used to specify the key prefixes for which the storage difference will be calculated. The `prefixes` field contains an array of objects, each describing a key prefix and the type of the storage difference to calculate. The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription per JSON-RPC client. Trying to open more might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new subscriptions. @@ -73,7 +69,7 @@ Where `subscription` is the value returned by this function, and `result` can be The `differences` field contains an array of objects, each describing a storage difference. -The `key` field contains the hexadecimal-encoded key of the storage entry. If the a key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. If the `excludeKeyPrefixes` field was provided in the `items` parameter, the `key` field is guaranteed not to start with any of the excluded key prefixes provided. +The `key` field contains the hexadecimal-encoded key of the storage entry. If the a key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. The `value` field contains the hexadecimal-encoded value of the storage entry. This field is present when prefixes are not provided or when the `type` field in the `items` parameter is set to `value`. From ee2a8c12516d164d5d2c2e5dd2087f8ebac379d5 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 16:46:57 +0300 Subject: [PATCH 07/18] archive: Clarify hash parameter wrt storage diff calculation Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 8d7ee4a..ff419b8 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -2,7 +2,7 @@ **Parameters**: -- `hash`: String containing a hexadecimal-encoded hash of the header of the block whose storage difference will be retrieved. The storage difference is calculated between the `hash` block and the parent of the `hash` block. +- `hash`: String containing a hexadecimal-encoded hash of the header of the block whose storage difference will be retrieved. - `previousHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. When this parameter is provided, the storage difference is calculated between the `hash` block and the `previousHash` block. If this parameter is not provided, the storage difference is calculated between the `hash` block and the parent of the `hash` block. From 7aeb735a3d446c7e4394276f481f0dd423436a89 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 16:48:23 +0300 Subject: [PATCH 08/18] archive: Make previousHash ancestor of hash Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index ff419b8..dbe5e69 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -4,7 +4,7 @@ - `hash`: String containing a hexadecimal-encoded hash of the header of the block whose storage difference will be retrieved. -- `previousHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. When this parameter is provided, the storage difference is calculated between the `hash` block and the `previousHash` block. If this parameter is not provided, the storage difference is calculated between the `hash` block and the parent of the `hash` block. +- `previousHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. The `previousHash` must be an ancestor of the provided `hash`. When this parameter is provided, the storage difference is calculated between the `hash` block and the `previousHash` block. If this parameter is not provided, the storage difference is calculated between the `hash` block and the parent of the `hash` block. - `items` (optional): JSON object containing the following fields: From 82d42458699721755f5a5354a29c0ea6aec5c2fe Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 16:58:27 +0300 Subject: [PATCH 09/18] archive: Make subscription into a method Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 49 +++---------------- .../archive_unstable_storageDiffContinue.md | 13 ----- src/api/archive_unstable_storageDiffStop.md | 11 ----- 3 files changed, 6 insertions(+), 67 deletions(-) delete mode 100644 src/api/archive_unstable_storageDiffContinue.md delete mode 100644 src/api/archive_unstable_storageDiffStop.md diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index dbe5e69..403ecd8 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -26,36 +26,12 @@ - `type`: String equal to one of: `value`, `hash`, `none`. - `childTrie` (optional): A string containing the hexadecimal-encoded key of the child trie of the "default" namespace. If this parameter is not provided, the storage difference is calculated for the main storage. -**Return value**: String containing an opaque value representing the operation. +**Return value**: A JSON object. -This function calculates the storage difference between two blocks. The storage difference is calculated by comparing the storage of the `previousHash` block with the storage of the `hash` block. If the `previousHash` parameter is not provided, the storage difference is calculated between the parent of the `hash` block and the `hash` block. - -The storage difference is calculated for the main storage trie by default. The `items` parameter can be used to specify the key prefixes for which the storage difference will be calculated. The `prefixes` field contains an array of objects, each describing a key prefix and the type of the storage difference to calculate. - -The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription per JSON-RPC client. Trying to open more might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new subscriptions. - -## Notifications format - -This function will later generate notifications with the following format: - -```json -{ - "jsonrpc": "2.0", - "method": "archive_unstable_storageDiffEvent", - "params": { - "subscription": "...", - "result": ... - } -} -``` - -Where `subscription` is the value returned by this function, and `result` can be one of the following: - -### differences +The JSON object returned by this function has the following format: ```json { - "event": "differences", "differences": [ { "key": "0x...", @@ -69,7 +45,7 @@ Where `subscription` is the value returned by this function, and `result` can be The `differences` field contains an array of objects, each describing a storage difference. -The `key` field contains the hexadecimal-encoded key of the storage entry. If the a key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. +The `key` field contains the hexadecimal-encoded key of the storage entry. If the key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. The `value` field contains the hexadecimal-encoded value of the storage entry. This field is present when prefixes are not provided or when the `type` field in the `items` parameter is set to `value`. @@ -83,25 +59,12 @@ The `type` field indicates the type of the storage difference. The possible valu - `modified`: The storage entry was modified. - `deleted`: The storage entry was deleted. -### continue - -```json -{ - "event": "continue", -} -``` - -This notification is sent when the storage difference calculation is paused and needs to be resumed. The user must call `archive_unstable_storageDiffContinue` with the subscription value to continue the calculation. -### done +## Overview -```json -{ - "event": "done", -} -``` +This function calculates the storage difference between two blocks. The storage difference is calculated by comparing the storage of the `previousHash` block with the storage of the `hash` block. If the `previousHash` parameter is not provided, the storage difference is calculated between the parent of the `hash` block and the `hash` block. -This notification is sent when the storage difference calculation is complete. +The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription per JSON-RPC client. Trying to open more might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new subscriptions. ## Possible errors diff --git a/src/api/archive_unstable_storageDiffContinue.md b/src/api/archive_unstable_storageDiffContinue.md deleted file mode 100644 index 27bf421..0000000 --- a/src/api/archive_unstable_storageDiffContinue.md +++ /dev/null @@ -1,13 +0,0 @@ -# archive_unstable_storageDiffContinue - -**Parameters**: - -- `subscription`: An opaque string that was returned by `archive_unstable_storageDiff`. - -**Return value**: *null* - -Continues a subscription started with `archive_unstable_storageDiff`. Has no effect if the `subscription` is invalid or refers to a subscription that has already emitted a `{"event": "done"}` event. - -## Possible errors - -- A JSON-RPC error generated if the `subscription` is valid but haven't generated a `{"event": "continue"}` event. diff --git a/src/api/archive_unstable_storageDiffStop.md b/src/api/archive_unstable_storageDiffStop.md deleted file mode 100644 index ba7d72e..0000000 --- a/src/api/archive_unstable_storageDiffStop.md +++ /dev/null @@ -1,11 +0,0 @@ -# archive_unstable_storageDiff - -**Parameters**: - -- `subscription`: An opaque string that was returned by `archive_unstable_storageDiff`. - -**Return value**: *null* - -Stops a subscription started with `archive_unstable_storageDiff`. Has no effect if the `subscription` is invalid or refers to a subscription that has already emitted a `{"event": "done"}` event. - -JSON-RPC client implementations must be aware that, due to the asynchronous nature of JSON-RPC client <-> server communication, they might still receive storage difference notifications, for example because these notifications were already in the process of being sent back by the JSON-RPC server. From c7921f679410f50bdf165b3bc53d3640cd4f4220 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 17:54:50 +0300 Subject: [PATCH 10/18] archive: Support multiple childTrie queries Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 74 ++++++++++++++++--------- 1 file changed, 48 insertions(+), 26 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 403ecd8..249bf3a 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -6,25 +6,37 @@ - `previousHash` (optional): String containing a hexadecimal-encoded hash of the header of the block from which the storage difference will be calculated. The `previousHash` must be an ancestor of the provided `hash`. When this parameter is provided, the storage difference is calculated between the `hash` block and the `previousHash` block. If this parameter is not provided, the storage difference is calculated between the `hash` block and the parent of the `hash` block. -- `items` (optional): JSON object containing the following fields: +- `items` (optional): Array of objects. The structure of these objects is found below. ```json - "items": { - "prefixes": [ - { - "key": "0x...", - "type": "value" | "hash" | "none", - }, - ], - "childTrie": "0x...", - } + "items": [ + { + "prefixes": [ + { + "key": "0x...", + "type": "value" | "hash" | "none", + }, + ], + + "trieType": "mainTrie" | "childTrie", + "childTrieKey": "0x...", + }, + ] ``` If the `items` parameter is not provided, the storage difference is calculated for all keys of the main storage trie. + + Each element in `items` must be an object containing the following fields: + - `prefixes` (optional): Array of JSON objects describing how the storage difference will be calculated. Each object contains the following fields: - `key`: String containing the hexadecimal-encoded key prefix under which the storage difference is calculated. - `type`: String equal to one of: `value`, `hash`, `none`. - - `childTrie` (optional): A string containing the hexadecimal-encoded key of the child trie of the "default" namespace. If this parameter is not provided, the storage difference is calculated for the main storage. + + - `trieType`: A string indicating the trie type for which the storage difference will be calculated. The possible values are: + - `mainTrie`: The storage difference is calculated for the main storage. + - `childTrie`: The storage difference is calculated for the child trie of the "default" namespace. If this type is provided, the `childTrieKey` field must be provided. + + - `childTrieKey`: String containing the hexadecimal-encoded key of the child trie of the "default" namespace. This field is only present when the `trieType` field is set to `childTrie`. **Return value**: A JSON object. @@ -32,33 +44,42 @@ The JSON object returned by this function has the following format: ```json { - "differences": [ + "result": [ { - "key": "0x...", - "value": "0x...", - "hash": "0x...", - "type": "added" | "modified" | "deleted", - }, + "differences": [ + { + "key": "0x...", + "value": "0x...", + "hash": "0x...", + "type": "added" | "modified" | "deleted", + }, + ], + + "trieType": "mainTrie" | "childTrie", + "childTrieKey": "0x...", + } ], } ``` -The `differences` field contains an array of objects, each describing a storage difference. +The `result` field contains an array of objects, each containing a JSON object: -The `key` field contains the hexadecimal-encoded key of the storage entry. If the key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. +The `differences` field is an array of objects describing storage differences. Each element contains the following fields: -The `value` field contains the hexadecimal-encoded value of the storage entry. This field is present when prefixes are not provided or when the `type` field in the `items` parameter is set to `value`. +- `key`: String containing the hexadecimal-encoded key of the storage entry. If the key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. -The `hash` field contains the hexadecimal-encoded hash of the storage entry. This field is only present when the `type` field in the `items` parameter is set to `hash`. +- `value`: String containing the hexadecimal-encoded value of the storage entry. This field is present when prefixes are not provided or when the `type` field in the `items` parameter is set to `value`. -When the `type` field in the `items` parameter is set to `none`, the `value` and `hash` fields are not present. +- `hash`: String containing the hexadecimal-encoded hash of the storage entry. This field is only present when the `type` field in the `items` parameter is set to `hash`. -The `type` field indicates the type of the storage difference. The possible values are: +- `type`: String indicating the type of the storage difference. The possible values are: + - `added`: The storage entry was added. + - `modified`: The storage entry was modified. + - `deleted`: The storage entry was deleted. -- `added`: The storage entry was added. -- `modified`: The storage entry was modified. -- `deleted`: The storage entry was deleted. +The `trieType` field is a string indicating the trie type for which the storage difference was calculated. The possible values are `mainTrie` and `childTrie`. These have the same meaning as in the `items` parameter. +The `childTrieKey` field is a string containing the hexadecimal-encoded key of the child trie of the "default" namespace. This field is only present when the `trieType` field is set to `childTrie`. ## Overview @@ -66,6 +87,7 @@ This function calculates the storage difference between two blocks. The storage The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription per JSON-RPC client. Trying to open more might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new subscriptions. + ## Possible errors - A JSON-RPC error can be generated if the JSON-RPC client has to many active subscriptions to `archive_unstable_storageDiff`. From f059c18285395518e46b6bee1916d524e55072a8 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 18:01:37 +0300 Subject: [PATCH 11/18] archive: Add a bit more details Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 249bf3a..c2f396a 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -29,7 +29,7 @@ Each element in `items` must be an object containing the following fields: - `prefixes` (optional): Array of JSON objects describing how the storage difference will be calculated. Each object contains the following fields: - - `key`: String containing the hexadecimal-encoded key prefix under which the storage difference is calculated. + - `key`: String containing a hexadecimal-encoded key prefix. Only the storage entries whose key starts with the provided prefix are returned. - `type`: String equal to one of: `value`, `hash`, `none`. - `trieType`: A string indicating the trie type for which the storage difference will be calculated. The possible values are: @@ -87,6 +87,8 @@ This function calculates the storage difference between two blocks. The storage The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription per JSON-RPC client. Trying to open more might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new subscriptions. +Users that want to obtain the storage difference between two blocks should use this function instead of calling `archive_unstable_storage` for each block and comparing the results. +When users are interested in the main trie storage differences, as well as in a child storage difference, they can call this function with `items: [ { "trieType": "mainTrie" }, { "trieType": "childTrie", "childTrieKey": "0x..." } ]`. ## Possible errors From e40142ba741242d7dec5fd857d8143adbb4ffff4 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 6 Aug 2024 18:04:02 +0300 Subject: [PATCH 12/18] archive: Extend error section Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index c2f396a..949b978 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -93,4 +93,6 @@ When users are interested in the main trie storage differences, as well as in a ## Possible errors - A JSON-RPC error can be generated if the JSON-RPC client has to many active subscriptions to `archive_unstable_storageDiff`. +- A JSON-RPC error can be generated if the `previousHash` parameter is provided, but the `previousHash` block is not an ancestor of the `hash` block. +- A JSON-RPC error can be generated if one of the hashes provided does not correspond to a known block header hash. - A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type). From e1d08ad69af3fdefd33d9c7e401e83680b2131e9 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Sep 2024 15:59:43 +0300 Subject: [PATCH 13/18] archive: Remove prefixes array Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 949b978..e492321 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -11,14 +11,8 @@ ```json "items": [ { - "prefixes": [ - { - "key": "0x...", - "type": "value" | "hash" | "none", - }, - ], - - "trieType": "mainTrie" | "childTrie", + "key": "0x...", + "type": "value" | "hash" | "none", "childTrieKey": "0x...", }, ] @@ -28,15 +22,9 @@ Each element in `items` must be an object containing the following fields: - - `prefixes` (optional): Array of JSON objects describing how the storage difference will be calculated. Each object contains the following fields: - - `key`: String containing a hexadecimal-encoded key prefix. Only the storage entries whose key starts with the provided prefix are returned. - - `type`: String equal to one of: `value`, `hash`, `none`. - - - `trieType`: A string indicating the trie type for which the storage difference will be calculated. The possible values are: - - `mainTrie`: The storage difference is calculated for the main storage. - - `childTrie`: The storage difference is calculated for the child trie of the "default" namespace. If this type is provided, the `childTrieKey` field must be provided. - - - `childTrieKey`: String containing the hexadecimal-encoded key of the child trie of the "default" namespace. This field is only present when the `trieType` field is set to `childTrie`. + - `key` (optional): String containing a hexadecimal-encoded key prefix. Only the storage entries whose key starts with the provided prefix are returned. If this field is not present, the storage difference is calculated for all keys of the trie. + - `returnType`: String equal to one of: `value`, `hash`, `none`. + - `childTrieKey` (optional): String containing the hexadecimal-encoded key of the child trie of the "default" namespace. This field is only present when the `trieType` field is set to `childTrie`. If this field is not present, the storage difference is calculated for the main storage trie. **Return value**: A JSON object. From 821093d4663fee28c8dafc8f119ca5e6ac4bdf4b Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Sep 2024 16:13:07 +0300 Subject: [PATCH 14/18] archive: Adjust return object fields Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 35 ++++++++++--------------- 1 file changed, 14 insertions(+), 21 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index e492321..ff1d42c 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -12,7 +12,7 @@ "items": [ { "key": "0x...", - "type": "value" | "hash" | "none", + "returnType": "value" | "hash" | "none", "childTrieKey": "0x...", }, ] @@ -24,7 +24,10 @@ - `key` (optional): String containing a hexadecimal-encoded key prefix. Only the storage entries whose key starts with the provided prefix are returned. If this field is not present, the storage difference is calculated for all keys of the trie. - `returnType`: String equal to one of: `value`, `hash`, `none`. - - `childTrieKey` (optional): String containing the hexadecimal-encoded key of the child trie of the "default" namespace. This field is only present when the `trieType` field is set to `childTrie`. If this field is not present, the storage difference is calculated for the main storage trie. + - When `value` is provided, the `value` field is present in the result. + - When `hash` is provided, the `hash` field is present in the result. + - When `none` is provided, neither the `value` nor the `hash` field is present in the result. + - `childTrieKey` (optional): String containing the hexadecimal-encoded key of the child trie of the "default" namespace. If this field is not present, the storage difference is calculated for the main storage trie. **Return value**: A JSON object. @@ -34,17 +37,11 @@ The JSON object returned by this function has the following format: { "result": [ { - "differences": [ - { - "key": "0x...", - "value": "0x...", - "hash": "0x...", - "type": "added" | "modified" | "deleted", - }, - ], - - "trieType": "mainTrie" | "childTrie", - "childTrieKey": "0x...", + "key": "0x...", + "value": "0x...", + "hash": "0x...", + "type": "added" | "modified" | "deleted", + "childTrieKey": "0x..." | null, } ], } @@ -52,22 +49,18 @@ The JSON object returned by this function has the following format: The `result` field contains an array of objects, each containing a JSON object: -The `differences` field is an array of objects describing storage differences. Each element contains the following fields: +- `key`: String containing the hexadecimal-encoded key of the storage entry. A prefix of this key may have been provided in the items input. -- `key`: String containing the hexadecimal-encoded key of the storage entry. If the key prefix was provided in the `items` parameter, the `key` field is guaranteed to start with one of the key prefixes provided. +- `value` (optional): String containing the hexadecimal-encoded value of the storage entry. This field is present when the `returnType` field in the `items` parameter is set to `value`. -- `value`: String containing the hexadecimal-encoded value of the storage entry. This field is present when prefixes are not provided or when the `type` field in the `items` parameter is set to `value`. - -- `hash`: String containing the hexadecimal-encoded hash of the storage entry. This field is only present when the `type` field in the `items` parameter is set to `hash`. +- `hash` (optional): String containing the hexadecimal-encoded hash of the storage entry. This field is present when the `returnType` field in the `items` parameter is set to `hash`. - `type`: String indicating the type of the storage difference. The possible values are: - `added`: The storage entry was added. - `modified`: The storage entry was modified. - `deleted`: The storage entry was deleted. -The `trieType` field is a string indicating the trie type for which the storage difference was calculated. The possible values are `mainTrie` and `childTrie`. These have the same meaning as in the `items` parameter. - -The `childTrieKey` field is a string containing the hexadecimal-encoded key of the child trie of the "default" namespace. This field is only present when the `trieType` field is set to `childTrie`. +- `childTrieKey` field is a string containing the hexadecimal-encoded key of the child trie of the "default" namespace if the storage entry is part of a child trie. If the storage entry is part of the main trie, this field is `null`. ## Overview From 1f8854b25b4cb69b7627d21b7919b42a4db31841 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Sep 2024 16:14:14 +0300 Subject: [PATCH 15/18] archive: Remove concept of subscription Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index ff1d42c..ec7f335 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -66,14 +66,14 @@ The `result` field contains an array of objects, each containing a JSON object: This function calculates the storage difference between two blocks. The storage difference is calculated by comparing the storage of the `previousHash` block with the storage of the `hash` block. If the `previousHash` parameter is not provided, the storage difference is calculated between the parent of the `hash` block and the `hash` block. -The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription per JSON-RPC client. Trying to open more might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new subscriptions. +The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` method per JSON-RPC client. Trying to make more calls might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new method call. Users that want to obtain the storage difference between two blocks should use this function instead of calling `archive_unstable_storage` for each block and comparing the results. When users are interested in the main trie storage differences, as well as in a child storage difference, they can call this function with `items: [ { "trieType": "mainTrie" }, { "trieType": "childTrie", "childTrieKey": "0x..." } ]`. ## Possible errors -- A JSON-RPC error can be generated if the JSON-RPC client has to many active subscriptions to `archive_unstable_storageDiff`. +- A JSON-RPC error can be generated if the JSON-RPC client has to many active calls to `archive_unstable_storageDiff`. - A JSON-RPC error can be generated if the `previousHash` parameter is provided, but the `previousHash` block is not an ancestor of the `hash` block. - A JSON-RPC error can be generated if one of the hashes provided does not correspond to a known block header hash. - A JSON-RPC error with error code `-32602` is generated if one of the parameters doesn't correspond to the expected type (similarly to a missing parameter or an invalid parameter type). From d87aa842148065994fb315aa25e09afc2c42eb2b Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Sep 2024 17:30:26 +0300 Subject: [PATCH 16/18] archive: Remove none return Type Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index ec7f335..9fd21e5 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -12,7 +12,7 @@ "items": [ { "key": "0x...", - "returnType": "value" | "hash" | "none", + "returnType": "value" | "hash", "childTrieKey": "0x...", }, ] @@ -23,10 +23,9 @@ Each element in `items` must be an object containing the following fields: - `key` (optional): String containing a hexadecimal-encoded key prefix. Only the storage entries whose key starts with the provided prefix are returned. If this field is not present, the storage difference is calculated for all keys of the trie. - - `returnType`: String equal to one of: `value`, `hash`, `none`. - - When `value` is provided, the `value` field is present in the result. - - When `hash` is provided, the `hash` field is present in the result. - - When `none` is provided, neither the `value` nor the `hash` field is present in the result. + - `returnType`: String indicating the return type of the storage under the given `key`. The possible values are: + - `value`: The result contains the hexadecimal-encoded value of the storage entry. + - `hash`: The result contains the hexadecimal-encoded hash of the storage entry. - `childTrieKey` (optional): String containing the hexadecimal-encoded key of the child trie of the "default" namespace. If this field is not present, the storage difference is calculated for the main storage trie. **Return value**: A JSON object. From 9390a226466ffb960d225256dc69dafd32794a0e Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 11 Sep 2024 18:04:26 +0300 Subject: [PATCH 17/18] archive: Remove null from childTrieKey Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 9fd21e5..2df09d7 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -40,7 +40,7 @@ The JSON object returned by this function has the following format: "value": "0x...", "hash": "0x...", "type": "added" | "modified" | "deleted", - "childTrieKey": "0x..." | null, + "childTrieKey": "0x...", } ], } @@ -59,7 +59,7 @@ The `result` field contains an array of objects, each containing a JSON object: - `modified`: The storage entry was modified. - `deleted`: The storage entry was deleted. -- `childTrieKey` field is a string containing the hexadecimal-encoded key of the child trie of the "default" namespace if the storage entry is part of a child trie. If the storage entry is part of the main trie, this field is `null`. +- `childTrieKey` (optional): String containing the hexadecimal-encoded key of the child trie of the "default" namespace if the storage entry is part of a child trie. If the storage entry is part of the main trie, this field is not present. ## Overview From 1ed910f9c7020311c76881aca6e83408f7556f7d Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 17 Sep 2024 12:55:22 +0300 Subject: [PATCH 18/18] archive: Remove trieType type from example Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 2df09d7..a667e96 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -68,7 +68,7 @@ This function calculates the storage difference between two blocks. The storage The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` method per JSON-RPC client. Trying to make more calls might lead to a JSON-RPC error when calling `archive_unstable_storageDiff`. The JSON-RPC server must return an error code if the server is overloaded and cannot accept new method call. Users that want to obtain the storage difference between two blocks should use this function instead of calling `archive_unstable_storage` for each block and comparing the results. -When users are interested in the main trie storage differences, as well as in a child storage difference, they can call this function with `items: [ { "trieType": "mainTrie" }, { "trieType": "childTrie", "childTrieKey": "0x..." } ]`. +When users are interested in the main trie storage differences, as well as in a child storage difference, they can call this function with `items: [ { "returnType": "value" }, { "returnType": "value", "childTrieKey": "0x..." } ]`. ## Possible errors