Skip to content

Commit d964c35

Browse files
lexnvlexnv
authored
archive: Use subscriptions for archive_storage (#162)
Signed-off-by: Alexandru Vasile <[email protected]>
1 parent e3d9dd3 commit d964c35

File tree

1 file changed

+39
-56
lines changed

1 file changed

+39
-56
lines changed

‎src/api/archive_unstable_storage.md‎

Lines changed: 39 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -12,93 +12,75 @@ Each element in `items` must be an object containing the following fields:
1212
- `type`: String equal to one of: `value`, `hash`, `closestDescendantMerkleValue`, `descendantsValues`, `descendantsHashes`.
1313
- `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`.
1414

15-
**Return value**: A JSON object.
15+
**Return value**: String containing an opaque value representing the operation.
1616

17-
The JSON object returned by this function has the following format:
17+
## Notifications format
1818

19-
```
19+
This function will later generate one or more notifications in the following format:
20+
21+
```json
2022
{
21-
"result": [
22-
{
23-
...
24-
},
25-
...
26-
],
27-
"discardedItems": ...
23+
"jsonrpc": "2.0",
24+
"method": "archive_unstable_storageDiffEvent",
25+
"params": {
26+
"subscription": "...",
27+
"result": ...
28+
}
2829
}
2930
```
3031

31-
Where:
32-
33-
- `result` contains a vector of JSON objects (possibly empty) that were found in the storage.
34-
- `discardedItems` is an integer indicating the number of items at the back of the array of the `items` parameters that couldn't be processed.
35-
36-
The JSON objects in the `"result"` field can have one of the following formats based on their type:
32+
Where `subscription` is the value returned by this function, and `result` can be one of:
3733

38-
### Value
34+
### storage
3935

40-
```
36+
```json
4137
{
42-
"key": "0x0000000...",
43-
"value": "0x0000000...",
38+
"event": "storage",
39+
"key": "0x...",
40+
"value": "0x...",
41+
"hash": "0x...",
42+
"closestDescendantMerkleValue": "0x...",
43+
"childTrieKey": "0x...",
4444
}
4545
```
4646

47-
The JSON object corresponds to one of the requested items whose `type` was `"value"` or `"descendantsValues"`.
47+
The notification corresponds to a storage response for one of the requested items.
4848

49-
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.
49+
- `key`: String containing the hexadecimal-encoded key of the storage entry. This is guaranteed to be equal to one of the `key`s provided for `type` equal to `value`, `hash` or `closestDescendantMerkleValue`. For queries of type `descendantsValues` or `descendantsHashes`, `key` is guaranteed to start with one of the `key`s provided.
5050

51-
Returned when the `type` of the query was `"value"`:
51+
- `value` (optional): String containing the hexadecimal-encoded value of the storage entry. This field is present when the `type` of the query was `"value"` or `"descendantsValues"`.
5252

53-
- `key` is guaranteed to be equal to one of the `key`s provided.
54-
- `value` is a string containing the hexadecimal-encoded value of the storage entry.
53+
- `hash` (optional): String containing the hexadecimal-encoded hash of the storage entry. This field is present when the `type` of the query was `"hash"` or `"descendantsHashes"`.
5554

56-
Returned when the `type` of the query was `"descendantsValues"`:
55+
- `closestDescendantMerkleValue` (optional): String containing the hexadecimal-encoded Merkle value of the closest descendant of `key` (including branch nodes). This field is present when the `type` of the query 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).
5756

58-
- `key` is guaranteed to start with one of the `key`s provided.
59-
- `value` is a string containing the hexadecimal-encoded value of the storage entry.
57+
- `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.
6058

61-
### Hash
59+
### storageDone
6260

63-
```
61+
```json
6462
{
65-
"key": "0x0000000...",
66-
"hash": "0x0000000...",
63+
"event": "storageDone",
6764
}
6865
```
6966

70-
The JSON object corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`.
71-
72-
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.
67+
This event is always generated after all `storage` events have been generated.
7368

74-
Returned when the `type` of the query was `"hash"`:
69+
No more events will be generated after a `storageDone` event.
7570

76-
- `key` is guaranteed to be equal to one of the `key`s provided.
77-
- `hash` is a string containing the hexadecimal-encoded hash of the storage entry.
71+
### storageError
7872

79-
Returned when the `type` of the query was `"descendantsHashes"`:
80-
81-
- `key` is guaranteed to start with one of the `key`s provided.
82-
- `hash` is a string containing the hexadecimal-encoded cryptographic hash of the storage entry.
83-
84-
85-
### ClosestDescendantMerkleValue
86-
87-
```
73+
```json
8874
{
89-
"key": "0x0000000...",
90-
"closestDescendantMerkleValue": "0x000000..."
75+
"event": "storageError",
76+
"error": "...",
9177
}
9278
```
9379

94-
The JSON object corresponds to one of the requested items whose `type` was `"closestDescendantMerkleValue"`.
95-
96-
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.
80+
`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.
9781

98-
- `key` is guaranteed to be equal to one of the `key`s provided.
99-
- `closestDescendantMerkleValue` is the closest trie Merkle value of the `key`.
82+
No more events will be generated after a `storageError` event.
10083

101-
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).
10284

10385
## Overview
10486

@@ -118,4 +100,5 @@ It is allowed (but discouraged) for the JSON-RPC server to provide the same info
118100

119101
## Possible errors
120102

121-
- 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).
103+
- A JSON-RPC error can be generated if the JSON-RPC client has to many active calls to `archive_unstable_storageDiff`.
104+
- 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).

0 commit comments

Comments
 (0)