From c03bf3c5941196e431d0b2c612fe9eaabd775814 Mon Sep 17 00:00:00 2001 From: Dan Forbes Date: Tue, 28 Apr 2020 07:13:17 -0700 Subject: [PATCH] Small changes for readability and elaboration --- current/advanced/storage.md | 34 +++++++++++++++++++--------------- current/runtime/storage.md | 5 +---- 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/current/advanced/storage.md b/current/advanced/storage.md index df368da..9c46a80 100644 --- a/current/advanced/storage.md +++ b/current/advanced/storage.md @@ -78,14 +78,17 @@ these needs automatically; thus a child trie is used instead. Blockchains that are built with Substrate expose a remote procedure call (RPC) server that can be used to query runtime storage. When you use the Substrate RPC to access a storage item, you only need to provide -[the key](#Key-Value-Database) associated with that item. +[the key](#Key-Value-Database) associated with that item. [Substrate's runtime storage APIs](../runtime/storage) expose +a number of storage item types; keep reading to learn how to calculate storage keys for the different types of storage +items. ### Storage Value Keys -To calculate the key for a simple Storage Value, take the [TwoX 128 hash](https://github.com/Cyan4973/xxHash) of the -name of the module that contains the Storage Value and append to it the TwoX 128 hash of the name of the Storage Value -itself. For example, the [Sudo](https://substrate.dev/rustdocs/master/pallet_sudo/index.html) module exposes a Storage -Value item named [`Key`](https://substrate.dev/rustdocs/master/pallet_sudo/struct.Module.html#method.key): +To calculate the key for a simple [Storage Value](../runtime/storage#Storage-Value), take the +[TwoX 128 hash](https://github.com/Cyan4973/xxHash) of the name of the module that contains the Storage Value and +append to it the TwoX 128 hash of the name of the Storage Value itself. For example, the +[Sudo](https://substrate.dev/rustdocs/master/pallet_sudo/index.html) module exposes a Storage Value item named +[`Key`](https://substrate.dev/rustdocs/master/pallet_sudo/struct.Module.html#method.key): ``` twox_128("Sudo") = "0x5c0d1176a568c1f92944340dbfed9e9c" @@ -110,12 +113,13 @@ item) are determined by the runtime developer and not by potentially malicious u ### Storage Map Keys -Like Storage Values, the keys for Storage Maps are equal to the TwoX 128 hash of the name of the module that contains -the map prepended to the TwoX 128 hash of the name of the Storage Map itself. To retrieve an element from a map, simply -append the hash of the desired map key to the storage key of the Storage Map. For maps with two keys (Storage Double -Maps), append the hash of the first map key followed by the hash of the second map key to the Storage Double Map's -storage key. Remember, Substrate will use the TwoX 128 hashing algorithm for the module and storage item names, but you -will need to make sure to use the correct hashing algorithm (the one that was declared in +Like Storage Values, the keys for [Storage Maps](../runtime/storage#StorageMaps) are equal to the TwoX 128 hash of the +name of the module that contains the map prepended to the TwoX 128 hash of the name of the Storage Map itself. To +retrieve an element from a map, simply append the hash of the desired map key to the storage key of the Storage Map. +For maps with two keys (Storage Double Maps), append the hash of the first map key followed by the hash of the second +map key to the Storage Double Map's storage key. Like Storage Values, Substrate will use the TwoX 128 hashing algorithm +for the module and Storage Map names, but you will need to make sure to use the correct +[hashing algorithm](../runtime/storage#Hashing-Algorithms) (the one that was declared in [the `decl_storage` macro](../runtime/storage#Declaring-Storage-Items)) when determining the hashed keys for the elements in a map. @@ -135,10 +139,10 @@ state_getStorage("0xc2261276cc9d1f8598ea4b6a74b15c2f6482b9ade7bc6657aaca787ba1ad The value that is returned from the storage query (`"0x0000a0dec5adc9353600000000000000"` in the example above) is the [SCALE](./codec)-encoded value of Alice's account balance (`"1000000000000000000000"` in this example). Notice -that before hashing Alice's account ID it has to be SCALE-encoded. Also notice that the output of the `blake2_128_concat` -function consists of 32 hexadecimal characters followed by the function's input. This is because the Blake2 128 Concat -is [a transparent hashing algorithm as describe above](../runtime/storage#Transparent-Hashing-Algorithms). Although the -above example may make this characteristic seem superfluous, its utility becomes more apparent when the goal is to +that before hashing Alice's account ID it has to be SCALE-encoded. Also notice that the output of the +`blake2_128_concat` function consists of 32 hexadecimal characters followed by the function's input. This is because +the Blake2 128 Concat is [a transparent hashing algorithm](../runtime/storage#Transparent-Hashing-Algorithms). Although +the above example may make this characteristic seem superfluous, its utility becomes more apparent when the goal is to iterate over the keys in a map (as opposed to retrieving the value associated with a single key). The ability to iterate over the keys in a map is a common requirement in order to allow _people_ to use the map in a way that seems natural (such as UIs): first, a user is presented with a list of elements in the map, then, that user can select the diff --git a/current/runtime/storage.md b/current/runtime/storage.md index 81067e2..49ef0cd 100644 --- a/current/runtime/storage.md +++ b/current/runtime/storage.md @@ -116,10 +116,7 @@ the `iter` and `drain` methods require a parameter, i.e. the first key: As mentioned above, a novel feature of Substrate Storage Maps is that they allow developers to specify the hashing algorithm that will be used when generating a map's keys. A Rust object that is used to encapsulate hashing logic is referred to as a "hasher". Broadly speaking, the hashers that are available to Substrate developers can be described -in two ways: whether or not they are cryptographic and whether or not they produce output that is transparent. In this -document you will find information about the pros and cons of the different approaches to hashing; read -[the advanced storage document](../advanced/storage) if you would like a better understanding of _why_ the different -algorithms may behave differently. +in two ways: whether or not they are cryptographic and whether or not they produce output that is transparent. ##### Cryptographic Hashing Algorithms