From b2cba40b3ebc8a431650a334ca5b88f232d057c8 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 4 Nov 2024 13:26:33 +0200 Subject: [PATCH 1/9] archive: Use subscriptions for storageDiff Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 52 +++++++++++++++++++------ 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index a667e96..1a4f8c6 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -28,25 +28,41 @@ - `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. +**Return value**: String containing an opaque value representing the operation. + +## Notifications format + +This function will later generate one or more notifications in 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: + +### storageDiff The JSON object returned by this function has the following format: ```json { - "result": [ - { - "key": "0x...", - "value": "0x...", - "hash": "0x...", - "type": "added" | "modified" | "deleted", - "childTrieKey": "0x...", - } - ], + "event": "storageDiff", + "key": "0x...", + "value": "0x...", + "hash": "0x...", + "type": "added" | "modified" | "deleted", + "childTrieKey": "0x...", } ``` -The `result` field contains an array of objects, each containing a JSON object: +The `storageDiff` event is generated for each storage difference between the two blocks. - `key`: String containing the hexadecimal-encoded key of the storage entry. A prefix of this key may have been provided in the items input. @@ -61,11 +77,23 @@ The `result` field contains an array of objects, each containing a JSON object: - `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. +### storageDiffDone + +The JSON object returned by this function has the following format: + +```json +{ + "event": "storageDiffDone", +} +``` + +This event is always generated after all `storageDiff` events have been generated. + ## Overview 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` 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. +The JSON-RPC server is encouraged to accept at least one `archive_unstable_storageDiff` subscription 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 subscription 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: [ { "returnType": "value" }, { "returnType": "value", "childTrieKey": "0x..." } ]`. From b4e472de0cf50dc64d72093797118393559827b2 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 4 Nov 2024 13:29:46 +0200 Subject: [PATCH 2/9] archive: Add stop method Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_stopStorageDiff.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 src/api/archive_unstable_stopStorageDiff.md diff --git a/src/api/archive_unstable_stopStorageDiff.md b/src/api/archive_unstable_stopStorageDiff.md new file mode 100644 index 0000000..527296e --- /dev/null +++ b/src/api/archive_unstable_stopStorageDiff.md @@ -0,0 +1,11 @@ +# archive_unstable_stopStorageDiff + +**Parameters**: + +- 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 opaque string is invalid or refers to a subscription that has already emitted a `{"event": "storageDiffDone"}` event. + +JSON-RPC client implementations must be aware that, due to the asynchronous nature of JSON-RPC client <-> server communication, they might still receive chain updates notifications, for example because these notifications were already in the process of being sent back by the JSON-RPC server. From fafa3fea6271e6cfb215a3066e83ead3205b28ea Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 5 Nov 2024 16:39:31 +0200 Subject: [PATCH 3/9] archive: Move previousHash as last parameter 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 1a4f8c6..e03a7ad 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -4,10 +4,10 @@ - `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. 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): Array of objects. The structure of these objects is found below. +- `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. + ```json "items": [ { From cb124be469a0287074cd39e81024667148ac7464 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 5 Nov 2024 16:39:43 +0200 Subject: [PATCH 4/9] archive: Make items non-optional 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 e03a7ad..9a906e4 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. -- `items` (optional): Array of objects. The structure of these objects is found below. +- `items`: Array of objects. The structure of these objects is found below. - `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. From c2112e3691ff2b78d74d7fed80f9f57b918ccd92 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 5 Nov 2024 18:12:51 +0200 Subject: [PATCH 5/9] archive: Introduce storageDiffError event Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 9a906e4..79cdb4c 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -49,8 +49,6 @@ Where `subscription` is the value returned by this function, and `result` can be ### storageDiff -The JSON object returned by this function has the following format: - ```json { "event": "storageDiff", @@ -79,8 +77,6 @@ The `storageDiff` event is generated for each storage difference between the two ### storageDiffDone -The JSON object returned by this function has the following format: - ```json { "event": "storageDiffDone", @@ -89,6 +85,21 @@ The JSON object returned by this function has the following format: This event is always generated after all `storageDiff` events have been generated. +No more events will be generated after a `storageDiffDone` event. + +### storageDiffError + +```json +{ + "event": "storageDiffError", + "error": "...", +} +``` + +`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 events will be generated after a `storageDiffError` event. + ## Overview 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. From c7af0da46d6558c43f262345c06adc5e30abaf5a Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 5 Nov 2024 18:14:00 +0200 Subject: [PATCH 6/9] archive: Simplify error code Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_storageDiff.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/api/archive_unstable_storageDiff.md b/src/api/archive_unstable_storageDiff.md index 79cdb4c..711c8a5 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -112,6 +112,4 @@ 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 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 1900a7991b908a5f79ebb2b3ecb8dbe153fe7dd4 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> Date: Tue, 5 Nov 2024 18:14:47 +0200 Subject: [PATCH 7/9] Update src/api/archive_unstable_stopStorageDiff.md Co-authored-by: Niklas Adolfsson --- src/api/archive_unstable_stopStorageDiff.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_stopStorageDiff.md b/src/api/archive_unstable_stopStorageDiff.md index 527296e..613c8ca 100644 --- a/src/api/archive_unstable_stopStorageDiff.md +++ b/src/api/archive_unstable_stopStorageDiff.md @@ -2,7 +2,7 @@ **Parameters**: -- An opaque string that was returned by `archive_unstable_StorageDiff`. +- An opaque string that was returned by `archive_unstable_storageDiff`. **Return value**: *null* From 399a67fd248743e0b10a1a2e94cf1c51ce729a52 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> Date: Tue, 5 Nov 2024 18:14:55 +0200 Subject: [PATCH 8/9] Update src/api/archive_unstable_stopStorageDiff.md Co-authored-by: Niklas Adolfsson --- src/api/archive_unstable_stopStorageDiff.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_stopStorageDiff.md b/src/api/archive_unstable_stopStorageDiff.md index 613c8ca..3252bc3 100644 --- a/src/api/archive_unstable_stopStorageDiff.md +++ b/src/api/archive_unstable_stopStorageDiff.md @@ -6,6 +6,6 @@ **Return value**: *null* -Stops a subscription started with `archive_unstable_StorageDiff`. Has no effect if the opaque string is invalid or refers to a subscription that has already emitted a `{"event": "storageDiffDone"}` event. +Stops a subscription started with `archive_unstable_storageDiff`. Has no effect if the opaque string is invalid or refers to a subscription that has already emitted a `{"event": "storageDiffDone"}` event. JSON-RPC client implementations must be aware that, due to the asynchronous nature of JSON-RPC client <-> server communication, they might still receive chain updates notifications, for example because these notifications were already in the process of being sent back by the JSON-RPC server. From c87d0c7a9620c0d326fa5d24dcf6e7191872104c Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Fri, 15 Nov 2024 18:01:46 +0200 Subject: [PATCH 9/9] archive: Move previousHash below items description 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 711c8a5..7be7039 100644 --- a/src/api/archive_unstable_storageDiff.md +++ b/src/api/archive_unstable_storageDiff.md @@ -6,8 +6,6 @@ - `items`: Array of objects. The structure of these objects is found below. -- `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. - ```json "items": [ { @@ -28,6 +26,8 @@ - `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. +- `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. + **Return value**: String containing an opaque value representing the operation. ## Notifications format