Stabilize archive methods (#167)

jsdw · web-flow · commit 12dd1a7813ff · 2025-03-31T14:59:01.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
 book
+.DS_Store
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -8,13 +8,13 @@
   - [Load balancers](load-balancers.md)
 - [API specification](api.md)
   - [archive](api/archive.md)
-    - [archive_unstable_body](api/archive_unstable_body.md)
-    - [archive_unstable_call](api/archive_unstable_call.md)
-    - [archive_unstable_finalizedHeight](api/archive_unstable_finalizedHeight.md)
-    - [archive_unstable_genesisHash](api/archive_unstable_genesisHash.md)
-    - [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_v1_body](api/archive_v1_body.md)
+    - [archive_v1_call](api/archive_v1_call.md)
+    - [archive_v1_finalizedHeight](api/archive_v1_finalizedHeight.md)
+    - [archive_v1_genesisHash](api/archive_v1_genesisHash.md)
+    - [archive_v1_hashByHeight](api/archive_v1_hashByHeight.md)
+    - [archive_v1_header](api/archive_v1_header.md)
+    - [archive_v1_storage](api/archive_v1_storage.md)
   - [chainHead](api/chainHead.md)
     - [chainHead_v1_body](api/chainHead_v1_body.md)
     - [chainHead_v1_call](api/chainHead_v1_call.md)
diff --git a/src/api/archive.md b/src/api/archive.md
@@ -8,11 +8,11 @@ These functions are typically expensive for a JSON-RPC server, because they like
 
 # Usage
 
-The JSON-RPC server exposes a finalized block height, which can be retrieved by calling `archive_unstable_finalizedHeight`.
+The JSON-RPC server exposes a finalized block height, which can be retrieved by calling `archive_v1_finalizedHeight`.
 
-Call `archive_unstable_hashByHeight` in order to obtain the hash of a block by its height.
+Call `archive_v1_hashByHeight` in order to obtain the hash of a block by its height.
 
-If the height passed to `archive_unstable_hashByHeight` is inferior or equal to the value returned by `archive_unstable_finalizedHeight`, then it is always guaranteed that there is exactly one block with this hash.
-The JSON-RPC client can then call `archive_unstable_header`, `archive_unstable_body`, `archive_unstable_storage`, and `archive_unstable_call` in order to obtain details about the block with this hash. It is always guaranteed to return a value.
+If the height passed to `archive_v1_hashByHeight` is inferior or equal to the value returned by `archive_v1_finalizedHeight`, then it is always guaranteed that there is exactly one block with this hash.
+The JSON-RPC client can then call `archive_v1_header`, `archive_v1_body`, `archive_v1_storage`, and `archive_v1_call` in order to obtain details about the block with this hash. It is always guaranteed to return a value.
 
-If the height passed to `archive_unstable_hashByHeight` is strictly superior to the value returned by `archive_unstable_finalizedHeight`, then `archive_unstable_hashByHeight` might return zero, one, or more blocks. Furthermore, the list of blocks being returned can change at any point. It is also possible to call `archive_unstable_header`, `archive_unstable_body`, `archive_unstable_storage`, and `archive_unstable_call` on these blocks, but these functions might return `null` even if their hash was previously returned by `archive_unstable_hashByHeight`.
+If the height passed to `archive_v1_hashByHeight` is strictly superior to the value returned by `archive_v1_finalizedHeight`, then `archive_v1_hashByHeight` might return zero, one, or more blocks. Furthermore, the list of blocks being returned can change at any point. It is also possible to call `archive_v1_header`, `archive_v1_body`, `archive_v1_storage`, and `archive_v1_call` on these blocks, but these functions might return `null` even if their hash was previously returned by `archive_v1_hashByHeight`.
diff --git a/src/api/archive_unstable_body.md b/src/api/archive_unstable_body.md
diff --git a/src/api/archive_unstable_header.md b/src/api/archive_unstable_header.md
diff --git a/src/api/archive_v1_body.md b/src/api/archive_v1_body.md
@@ -0,0 +1,11 @@
+# archive_v1_body
+
+**Parameters**:
+
+- `hash`: String containing a hexadecimal-encoded hash of the header of the block whose body will be retrieved.
+
+**Return value**: If a block with that hash is found, an array of strings containing the hexadecimal-encoded SCALE-codec-encoded transactions in that block. If no block with that hash is found, `null`.
+
+If the block was previously returned by `archive_v1_hashByHeight` at a height inferior or equal to the current finalized block height (as indicated by `archive_v1_finalizedHeight`), then calling this method multiple times is guaranteed to always return non-null and always the same result.
+
+If the block was previously returned by `archive_v1_hashByHeight` at a height strictly superior to the current finalized block height (as indicated by `archive_v1_finalizedHeight`), then the block might "disappear" and calling this function might return `null` at any point.
diff --git a/src/api/archive_v1_call.md b/src/api/archive_v1_call.md
@@ -1,4 +1,4 @@
-# archive_unstable_call
+# archive_v1_call
 
 **Parameters**:
 
@@ -16,7 +16,7 @@ The JSON-RPC server must invoke the entry point of the runtime of the given bloc
 
 **Note**: The runtime is still allowed to call host functions with side effects, however these side effects must be discarded. For example, a runtime function call can try to modify the storage of the chain, but this modification must not be actually applied. The only motivation for performing a call is to obtain the return value.
 
-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 multiple times is guaranteed to always return non-null and always the same result (except for the `error` message which is allowed to change).
+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_v1_finalizedHeight`), then calling this method multiple times is guaranteed to always return non-null and always the same result (except for the `error` message which is allowed to change).
 
 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.
 
diff --git a/src/api/archive_v1_finalizedHeight.md b/src/api/archive_v1_finalizedHeight.md
@@ -1,11 +1,11 @@
-# archive_unstable_finalizedHeight
+# archive_v1_finalizedHeight
 
 **Parameters**: *none*
 
 **Return value**: An integer height of the current finalized block of the chain.
 
 The value returned by this function must only ever increase over time. In other words, if calling this function returns `N`, then calling it again later must return a value superior or equal to `N`.
 
-When implemented on a load balancer, keep in mind that the other functions of the `archive` namespace must always return the same value when the block's height is inferior or equal to the finalized block height indicated by this function. One possible implementation strategy is for this function to call `archive_unstable_finalizedHeight` on every node being load balanced and return the smallest value.
+When implemented on a load balancer, keep in mind that the other functions of the `archive` namespace must always return the same value when the block's height is inferior or equal to the finalized block height indicated by this function. One possible implementation strategy is for this function to call `archive_v1_finalizedHeight` on every node being load balanced and return the smallest value.
 
 This function is expected to be called rarely by the JSON-RPC client. This function exists in order to give an indication of which blocks are accessible, and not for JSON-RPC clients to follow the finalized block. The `archive` namespace isn't meant to follow the head of the chain, and `chainHead` should be used instead in that situation.
diff --git a/src/api/archive_v1_genesisHash.md b/src/api/archive_v1_genesisHash.md
@@ -1,4 +1,4 @@
-# archive_unstable_genesisHash
+# archive_v1_genesisHash
 
 **Parameters**: *none*
 
diff --git a/src/api/archive_v1_hashByHeight.md b/src/api/archive_v1_hashByHeight.md
@@ -1,4 +1,4 @@
-# archive_unstable_hashByHeight
+# archive_v1_hashByHeight
 
 **Parameters**:
 
diff --git a/src/api/archive_v1_header.md b/src/api/archive_v1_header.md
@@ -0,0 +1,11 @@
+# archive_v1_header
+
+**Parameters**:
+
+- `hash`: String containing the hexadecimal-encoded hash of the header to retreive.
+
+**Return value**: If a block with that hash is found, a string containing the hexadecimal-encoded SCALE-codec encoding header of the block. If no block with that hash is found, `null`.
+
+If the block was previously returned by `archive_v1_hashByHeight` at a height inferior or equal to the current finalized block height (as indicated by `archive_v1_finalizedHeight`), then calling this method multiple times is guaranteed to always return non-null and always the same result.
+
+If the block was previously returned by `archive_v1_hashByHeight` at a height strictly superior to the current finalized block height (as indicated by `archive_v1_finalizedHeight`), then the block might "disappear" and calling this function might return `null` at any point.
diff --git a/src/api/archive_v1_stopStorage.md b/src/api/archive_v1_stopStorage.md
@@ -1,11 +1,11 @@
-# archive_unstable_stopStorage
+# archive_v1_stopStorage
 
 **Parameters**:
 
-- An opaque string that was returned by `archive_unstable_storage`.
+- An opaque string that was returned by `archive_v1_storage`.
 
 **Return value**: *null*
 
-Stops a subscription started with `archive_unstable_storage`. Has no effect if the opaque string is invalid or refers to a subscription that has already emitted a `{"event": "storageDone"}` event.
+Stops a subscription started with `archive_v1_storage`. Has no effect if the opaque string is invalid or refers to a subscription that has already emitted a `{"event": "storageDone"}` 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.
diff --git a/src/api/archive_v1_stopStorageDiff.md b/src/api/archive_v1_stopStorageDiff.md
@@ -1,11 +1,11 @@
-# archive_unstable_stopStorageDiff
+# archive_v1_stopStorageDiff
 
 **Parameters**:
 
-- An opaque string that was returned by `archive_unstable_storageDiff`.
+- An opaque string that was returned by `archive_v1_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.
+Stops a subscription started with `archive_v1_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.
diff --git a/src/api/archive_v1_storage.md b/src/api/archive_v1_storage.md
@@ -1,4 +1,4 @@
-# archive_unstable_storage
+# archive_v1_storage
 
 **Parameters**:
 
@@ -21,7 +21,7 @@ This function will later generate one or more notifications in the following for
 ```json
 {
     "jsonrpc": "2.0",
-    "method": "archive_unstable_storageEvent",
+    "method": "archive_v1_storageEvent",
     "params": {
         "subscription": "...",
         "result": ...
@@ -88,7 +88,7 @@ For each item in `items`, the JSON-RPC server must start obtaining the value of
 
 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 less than or equal to the current finalized block height (which can be obtained via archive_v1_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_v1_follow`.
@@ -100,5 +100,5 @@ It is allowed (but discouraged) for the JSON-RPC server to provide the same info
 
 ## 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 JSON-RPC client has to many active calls to `archive_v1_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).
diff --git a/src/api/archive_v1_storageDiff.md b/src/api/archive_v1_storageDiff.md
@@ -1,4 +1,4 @@
-# archive_unstable_storageDiff
+# archive_v1_storageDiff
 
 **Parameters**:
 
@@ -37,7 +37,7 @@ This function will later generate one or more notifications in the following for
 ```json
 {
     "jsonrpc": "2.0",
-    "method": "archive_unstable_storageDiffEvent",
+    "method": "archive_v1_storageDiffEvent",
     "params": {
         "subscription": "...",
         "result": ...
@@ -104,12 +104,12 @@ No more events will be generated after a `storageDiffError` event.
 
 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 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.
+The JSON-RPC server is encouraged to accept at least one `archive_v1_storageDiff` subscription per JSON-RPC client. Trying to make more calls might lead to a JSON-RPC error when calling `archive_v1_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.
+Users that want to obtain the storage difference between two blocks should use this function instead of calling `archive_v1_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..." } ]`.
 
 ## 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 JSON-RPC client has to many active calls to `archive_v1_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).
diff --git a/src/api/chainHead_v1_body.md b/src/api/chainHead_v1_body.md
@@ -45,7 +45,7 @@ The progress of the operation is indicated through `operationBodyDone`, `operati
 
 The operation continues even if the target block is unpinned with `chainHead_v1_unpin`.
 
-This function should be seen as a complement to `chainHead_v1_follow`, allowing the JSON-RPC client to retrieve more information about a block that has been reported. Use `archive_unstable_body` if instead you want to retrieve the body of an arbitrary block.
+This function should be seen as a complement to `chainHead_v1_follow`, allowing the JSON-RPC client to retrieve more information about a block that has been reported. Use `archive_v1_body` if instead you want to retrieve the body of an arbitrary block.
 
 ## Possible errors
 
diff --git a/src/api/chainHead_v1_call.md b/src/api/chainHead_v1_call.md
@@ -49,7 +49,7 @@ The progress of the operation is indicated through `operationCallDone`, `operati
 
 The operation continues even if the target block is unpinned with `chainHead_v1_unpin`.
 
-This function should be seen as a complement to `chainHead_v1_follow`, allowing the JSON-RPC client to retrieve more information about a block that has been reported. Use `archive_unstable_call` if instead you want to call the runtime of an arbitrary block.
+This function should be seen as a complement to `chainHead_v1_follow`, allowing the JSON-RPC client to retrieve more information about a block that has been reported. Use `archive_v1_call` if instead you want to call the runtime of an arbitrary block.
 
 **Note**: This can be used as a replacement for the legacy `state_getMetadata`, `system_accountNextIndex`, and `payment_queryInfo` functions.
 
diff --git a/src/api/chainHead_v1_header.md b/src/api/chainHead_v1_header.md
@@ -12,7 +12,7 @@
 
 Retrieves the header of a pinned block.
 
-This function should be seen as a complement to `chainHead_v1_follow`, allowing the JSON-RPC client to retrieve more information about a block that has been reported. Use `archive_unstable_header` if instead you want to retrieve the header of an arbitrary block.
+This function should be seen as a complement to `chainHead_v1_follow`, allowing the JSON-RPC client to retrieve more information about a block that has been reported. Use `archive_v1_header` if instead you want to retrieve the header of an arbitrary block.
 
 **Note**: As explained in the documentation of `chainHead_v1_follow`, the JSON-RPC server reserves the right to kill an existing subscription and unpin all its blocks at any moment in case it is overloaded or incapable of following the chain. If that happens, `chainHead_v1_header` will return `null`.
 
diff --git a/src/api/chainHead_v1_storage.md b/src/api/chainHead_v1_storage.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# archive_unstable_genesisHash`
	`1`	`+# archive_v1_genesisHash`
`2`	`2`
`3`	`3`	`Parameters: none`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# archive_unstable_hashByHeight`
	`1`	`+# archive_v1_hashByHeight`
`2`	`2`
`3`	`3`	`Parameters:`
`4`	`4`