From 565fe2cc0a3179a6c3dcdd39052479c537405bce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20K=C3=B6cher?= Date: Wed, 6 Sep 2023 15:22:57 +0200 Subject: [PATCH 1/4] Specify merkle value --- src/api.md | 7 +++++++ src/api/chainHead_unstable_storage.md | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/api.md b/src/api.md index a875ffd..0e19776 100644 --- a/src/api.md +++ b/src/api.md @@ -8,3 +8,10 @@ Any missing parameter, or parameter with an invalid format, should result in a J - "hexadecimal-encoded" designates a binary value encoded as hexadecimal. The value must either be empty, or start with `"0x"` and contain an even number of characters. - "SCALE-encoded" designates a value encoded using [the SCALE codec](https://docs.substrate.io/v3/advanced/scale-codec/). +- ["Merkle value"](https://spec.polkadot.network/chap-state#defn-merkle-value) designates a SCALE encoded value of the following type: + ``` + enum MerkleValue { + Node(Vec), + Hash(Hash) + } + ``` diff --git a/src/api/chainHead_unstable_storage.md b/src/api/chainHead_unstable_storage.md index bdb0cac..695b600 100644 --- a/src/api/chainHead_unstable_storage.md +++ b/src/api/chainHead_unstable_storage.md @@ -64,7 +64,7 @@ This function should be seen as a complement to `chainHead_unstable_follow`, all If the `type` of an item is `value`, and `key` is associated with a storage value in the trie, then the result will include an item that contains this storage value. If `key` is not associated with a storage value in the trie, then the result will not include such item. -If the `type` of an item is `hash`, the behaviour is similar to a `type` equal to `value`, except that the cryptographic hash of the value is included in the result rather than the value itself. The hashing algorithm used is the one of the chain, which is typically blake2b. This can lead to significantly less bandwidth usage and can be used in order to compare the value of an item with a known hash and querying the full value only if it differs. +If the `type` of an item is `hash`, the behavior is similar to a `type` equal to `value`, except that the cryptographic hash of the value is included in the result rather than the value itself. The hashing algorithm used is the one of the chain, which is typically blake2b. This can lead to significantly less bandwidth usage and can be used in order to compare the value of an item with a known hash and querying the full value only if it differs. If the `type` of an item is `descendantsValues` or `descendantsHashes`, then the result will contain zero or more items whose key starts with the `key` of this item. From ace6a8d3a03d4ad29eb531a442663861bf352e8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20K=C3=B6cher?= Date: Wed, 6 Sep 2023 18:37:06 +0200 Subject: [PATCH 2/4] Fix --- src/api.md | 8 +------- src/api/chainHead_unstable_follow.md | 2 +- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/src/api.md b/src/api.md index 0e19776..b8d96f9 100644 --- a/src/api.md +++ b/src/api.md @@ -8,10 +8,4 @@ Any missing parameter, or parameter with an invalid format, should result in a J - "hexadecimal-encoded" designates a binary value encoded as hexadecimal. The value must either be empty, or start with `"0x"` and contain an even number of characters. - "SCALE-encoded" designates a value encoded using [the SCALE codec](https://docs.substrate.io/v3/advanced/scale-codec/). -- ["Merkle value"](https://spec.polkadot.network/chap-state#defn-merkle-value) designates a SCALE encoded value of the following type: - ``` - enum MerkleValue { - Node(Vec), - Hash(Hash) - } - ``` +- "Merkle value" as decribed in the [Polkadot spec](https://spec.polkadot.network/chap-state#defn-merkle-value). diff --git a/src/api/chainHead_unstable_follow.md b/src/api/chainHead_unstable_follow.md index ee95896..0e95ba4 100644 --- a/src/api/chainHead_unstable_follow.md +++ b/src/api/chainHead_unstable_follow.md @@ -200,7 +200,7 @@ The `value` field is set if this item corresponds to one of the requested items The `hash` field is set if this item corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`. The `hash` field is a string containing the hexadecimal-encoded hash of the storage entry. -The `closestDescendantMerkleValue` field is set if this item corresponds to one of the requested items whose `type` 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 `closestDescendantMerkleValue` field is set if this item corresponds to one of the requested items whose `type` 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 value returned by the server must be either the node value or the hash of the node as defined by the Merkle value. ### operationWaitingForContinue From 5b9ab7d511b5dfa7c4a9c8e736157a01f391a813 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20K=C3=B6cher?= Date: Thu, 7 Sep 2023 10:54:01 +0200 Subject: [PATCH 3/4] Update src/api/chainHead_unstable_follow.md Co-authored-by: Pierre Krieger --- src/api/chainHead_unstable_follow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/chainHead_unstable_follow.md b/src/api/chainHead_unstable_follow.md index 0e95ba4..07a2c6c 100644 --- a/src/api/chainHead_unstable_follow.md +++ b/src/api/chainHead_unstable_follow.md @@ -200,7 +200,7 @@ The `value` field is set if this item corresponds to one of the requested items The `hash` field is set if this item corresponds to one of the requested items whose `type` was `"hash"` or `"descendantsHashes"`. The `hash` field is a string containing the hexadecimal-encoded hash of the storage entry. -The `closestDescendantMerkleValue` field is set if this item corresponds to one of the requested items whose `type` 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 value returned by the server must be either the node value or the hash of the node as defined by the Merkle value. +The `closestDescendantMerkleValue` field is set if this item corresponds to one of the requested items whose `type` 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). ### operationWaitingForContinue From 82cafadfc310523533d9ba199d17cd6365809726 Mon Sep 17 00:00:00 2001 From: Josep M Sobrepere Date: Thu, 7 Sep 2023 15:02:59 +0200 Subject: [PATCH 4/4] Update src/api.md Co-authored-by: Pierre Krieger --- src/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api.md b/src/api.md index b8d96f9..6e6a6b4 100644 --- a/src/api.md +++ b/src/api.md @@ -8,4 +8,4 @@ Any missing parameter, or parameter with an invalid format, should result in a J - "hexadecimal-encoded" designates a binary value encoded as hexadecimal. The value must either be empty, or start with `"0x"` and contain an even number of characters. - "SCALE-encoded" designates a value encoded using [the SCALE codec](https://docs.substrate.io/v3/advanced/scale-codec/). -- "Merkle value" as decribed in the [Polkadot spec](https://spec.polkadot.network/chap-state#defn-merkle-value). +- "Merkle value" is described in the [Polkadot specification](https://spec.polkadot.network/chap-state#defn-merkle-value).