From 1c7c38ec05731fe76cfb04a570beac37278d3e6e Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Fri, 22 Sep 2023 14:18:41 +0300 Subject: [PATCH 1/4] archive/call: Return a JSON-RPC object Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_call.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/api/archive_unstable_call.md b/src/api/archive_unstable_call.md index 1fced36..1e240ca 100644 --- a/src/api/archive_unstable_call.md +++ b/src/api/archive_unstable_call.md @@ -8,16 +8,18 @@ **Return value**: -- If no block with that `hash` exists, `null`. -- If the call was successful, `{ "success": true, "value": ... }` where the `value` is a string containing the hexadecimal-encoded SCALE-encoded value returned by the runtime. -- If the call wasn't successful, `{ "success": false, "error": ... }` where the `error` is a human-readable message indicating the problem. +- If no block with that `hash` exists, returns `null`. +- If the call was successful, the hexadecimal-encoded SCALE-encoded value returned by the runtime. The JSON-RPC server must invoke the entry point of the runtime of the given block using the storage of the given block. **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. -In situations where the provided runtime function doesn't exist, or the runtime crashes, or similar, an error is returned. The `error` isn't meant to be shown to end users, but is for developers to understand the problem. +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 block was previously returned by `archive_unstable_hashByHeight` at a height inferior or equal to the current finalized block height (as indicated by `archive_unstable_finalizedHeight`), then calling this method multiple times is guaranteed to always return non-null and always the same 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. -If the block was previously returned by `archive_unstable_hashByHeight` at a height strictly superior to the current finalized block height (as indicated by `archive_unstable_finalizedHeight`), then the block might "disappear" and calling this function might return `null` at any point. +## Possible errors + +- A JSON-RPC error if the provided parameters are invalid. +- A JSON-RPC error containing a human-readable message if the call wasn't successful, the provided runtime function doesn't exist, or the runtime crashes, or similar. The `error` isn't meant to be shown to end users, but is for developers to understand the problem. From 372b824da228da4d1199163cf9848a2de3e9a6f3 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 25 Sep 2023 16:16:14 +0300 Subject: [PATCH 2/4] archive/call: Adjust params Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_call.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/api/archive_unstable_call.md b/src/api/archive_unstable_call.md index 1e240ca..3477515 100644 --- a/src/api/archive_unstable_call.md +++ b/src/api/archive_unstable_call.md @@ -9,7 +9,8 @@ **Return value**: - If no block with that `hash` exists, returns `null`. -- If the call was successful, the hexadecimal-encoded SCALE-encoded value returned by the runtime. +- If the call was successful, `{"result": ... }` where the `result` is a string containing the hexadecimal-encoded SCALE-encoded value returned by the runtime. +- If the call wasn't successful, `{"error": ... }` where the `error` is a human-readable message indicating the problem. The JSON-RPC server must invoke the entry point of the runtime of the given block using the storage of the given block. @@ -22,4 +23,4 @@ If the height of the block hash provided is greater than the current finalized b ## Possible errors - A JSON-RPC error if the provided parameters are invalid. -- A JSON-RPC error containing a human-readable message if the call wasn't successful, the provided runtime function doesn't exist, or the runtime crashes, or similar. The `error` isn't meant to be shown to end users, but is for developers to understand the problem. +- `{"error":"..."}` is returned if a problem happens during the call, such as a Wasm trap, runtime panics, function not supported etc. From e6f1e5a97c1d4b6fd73ded0c37dd92939bd8bdeb Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Thu, 22 Feb 2024 12:29:36 +0200 Subject: [PATCH 3/4] Adjust sudo_sessionKeys Signed-off-by: Alexandru Vasile --- src/api/archive_unstable_call.md | 8 ++++---- src/api/sudo_sessionKeys_unstable_generate.md | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/api/archive_unstable_call.md b/src/api/archive_unstable_call.md index 3477515..ad567a8 100644 --- a/src/api/archive_unstable_call.md +++ b/src/api/archive_unstable_call.md @@ -8,9 +8,9 @@ **Return value**: -- If no block with that `hash` exists, returns `null`. -- If the call was successful, `{"result": ... }` where the `result` is a string containing the hexadecimal-encoded SCALE-encoded value returned by the runtime. -- If the call wasn't successful, `{"error": ... }` where the `error` is a human-readable message indicating the problem. +- If no block with that `hash` exists, `null`. +- If the call was successful, `{ "success": true, "value": ... }` where the `value` is a string containing the hexadecimal-encoded SCALE-encoded value returned by the runtime. +- If the call wasn't successful, `{ "success": false, "error": ... }` where the `error` is a human-readable message indicating the problem. The JSON-RPC server must invoke the entry point of the runtime of the given block using the storage of the given block. @@ -23,4 +23,4 @@ If the height of the block hash provided is greater than the current finalized b ## Possible errors - A JSON-RPC error if the provided parameters are invalid. -- `{"error":"..."}` is returned if a problem happens during the call, such as a Wasm trap, runtime panics, function not supported etc. +- `{ "success": false, "error": ... }` is returned if a problem happens during the call, such as a Wasm trap, runtime panics, function not supported etc. diff --git a/src/api/sudo_sessionKeys_unstable_generate.md b/src/api/sudo_sessionKeys_unstable_generate.md index 3c85828..34dcd68 100644 --- a/src/api/sudo_sessionKeys_unstable_generate.md +++ b/src/api/sudo_sessionKeys_unstable_generate.md @@ -6,8 +6,8 @@ **Return value**: -- If the runtime supports the function call (see below), an object of the form `{"result":"..."}` where `result` contains a string containing the hexadecimal-encoded output of the runtime function call. -- Otherwise, an object of the form `{"error":"..."}` where `error` is a human-readable error message indicating the problem. This string isn't meant to be shown to end users, but is for developers to understand the problem. +- If the runtime supports the function call (see below), an object of the form `{ "success": true, "value": ... }` where `value` contains a string containing the hexadecimal-encoded output of the runtime function call. +- Otherwise, an object of the form `{ "success": false, "error": ... }` where `error` is a human-readable error message indicating the problem. This string isn't meant to be shown to end users, but is for developers to understand the problem. The JSON-RPC server must check that the runtime supports the `SessionKeys` API (64bits blake2 hash: `0xab3c0572291feb8b`) at version 1, and call the `SessionKeys_generate_session_keys` runtime function. The runtime call is done against the current best block of the chain. @@ -20,9 +20,9 @@ Contrary to most other JSON-RPC functions that perform runtime function calls wh ## Possible errors -- `{"error":"..."}` is returned if the runtime doesn't support the given API. -- `{"error":"..."}` is returned if a problem happens during the call, such as a Wasm trap. -- `{"error":"..."}` is returned if the runtime attempts to modify the storage of the block. +- `{ "success": false, "error": ... }` is returned if the runtime doesn't support the given API. +- `{ "success": false, "error": ... }` is returned if a problem happens during the call, such as a Wasm trap. +- `{ "success": false, "error": ... }` is returned if the runtime attempts to modify the storage of the block. ## About the behavior of `SessionKeys_generate_session_keys` From 89b6135c134e9aad943ffd81f0abe06d078a69da Mon Sep 17 00:00:00 2001 From: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> Date: Mon, 26 Feb 2024 14:13:03 +0200 Subject: [PATCH 4/4] Update src/api/archive_unstable_call.md Co-authored-by: James Wilson --- src/api/archive_unstable_call.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/archive_unstable_call.md b/src/api/archive_unstable_call.md index ad567a8..bb861d7 100644 --- a/src/api/archive_unstable_call.md +++ b/src/api/archive_unstable_call.md @@ -23,4 +23,4 @@ If the height of the block hash provided is greater than the current finalized b ## Possible errors - A JSON-RPC error if the provided parameters are invalid. -- `{ "success": false, "error": ... }` is returned if a problem happens during the call, such as a Wasm trap, runtime panics, function not supported etc. +- `{ "success": false, "error": ... }` is returned if a problem happens during the call, such as a Wasm trap, runtime panics, function not supported etc. The `error` isn't meant to be shown to end users, but is for developers to understand the problem.