diff --git a/ab_host-api/child_storage.adoc b/ab_host-api/child_storage.adoc index 9ed72bdeb..18f9c8192 100644 --- a/ab_host-api/child_storage.adoc +++ b/ab_host-api/child_storage.adoc @@ -3,6 +3,9 @@ Interface for accessing the child storage from within the runtime. +IMPORTANT: Do note that this API must implement some specific behaviors, +described further in <> + [#defn-child-storage-type] .<> ==== @@ -25,6 +28,7 @@ child storage key (<>). * `key`: a pointer-size (<>) to the key. * `value`: a pointer-size (<>) to the value. +[#sect-ext-default-child-storage-get] ==== `ext_default_child_storage_get` Retrieves the value associated with the given key from the child storage. @@ -212,6 +216,7 @@ where _0_ indicates that all keys of the child storage have been removed, followed by the number of removed keys, stem:[c]. The variant _1_ indicates that there are remaining keys, followed by the number of removed keys. +[#ext-default-child-storage-root] ==== `ext_default_child_storage_root` Commits all existing operations and computes the resulting child storage diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index aacefed33..1e96fbaa0 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -3,11 +3,47 @@ Interface for accessing the storage from within the runtime. -IMPORTANT: As of now, the storage API should silently ignore any keys that start -with the `:child_storage:default:` prefix. This applies to reading and writing. -If the function expects a return value, then _None_ (<>) -should be returned. See -https://github.com/paritytech/substrate/issues/12461[substrate issue #12461]. +[#sect-storage-assumptions] +==== Implementation Assumptions +The storage and child storage (<>) API in the Substrate +implementation makes some behavioral assumptions on the underlying storage +architecture. While Polkadot Host implementers can decide for themselves on how +those APIs are implemented, those behaviors must be replicated in order for the +Runtime to be executed deterministically. In Substrate, child storages are +namespaced respectively segregated by attaching the `:child_storage:default:` +prefix to every child storage keys, followed by `:` for the key within that +child storage. However, the storage API described in this section and the child +storage API share the same database. This means that the storage API can +retrieve child storage entries. + +For example, calling `ext_storage_get_version_1` (<>) with +the key `:child_storage:default:some_child:some_key` is equivalent to calling +`ext_default_child_storage_get_version_1` +(<>) with child storage key `some_child` and +key `some_key`. + +Importantly, the storage API can only _read_ child storage entries, but must +implement write protection. Any function that modifies data must **silently ignore** +any keys that start with the `:child_storage:` prefix. For +`ext_storage_clear_prefix` (<>) specifically, +this also applies to any key that is a substring of the `:child_storage:` prefix, +such as `:child_sto` (but not `:other`, for example). If the function expects a +return value, then _None_ (<>) should be returned. + +Additionally, calling `ext_storage_get_version_1` on a child storage key +directly (without a key within the child storage), such as +`:child_storage:defaut:some_child`, the function returns the root of the child +storage from when `ext_default_child_storage_root` +(<>) has been **last called** or _None_ +(<>) if it has never been called. Respectively, that root +value is cached. Calling `ext_default_child_storage_root` directly always +recomputes the current root value. + +See the following issues for more information: + +* https://github.com/w3f/polkadot-spec/issues/575 +* https://github.com/w3f/polkadot-spec/issues/577 +* https://github.com/paritytech/substrate/issues/12461 [#defn-state-version] .<> @@ -29,6 +65,9 @@ merkle proof (<>). ==== `ext_storage_set` Sets the value under a given key into storage. +IMPORTANT: Do note that this API must implement some specific behaviors, +described further in <> + ===== Version 1 - Prototype ---- (func $ext_storage_set_version_1 @@ -40,9 +79,13 @@ Arguments:: * `value`: a pointer-size (<>) containing the value. +[#sect-ext-storage-get] ==== `ext_storage_get` Retrieves the value associated with the given key from storage. +IMPORTANT: Do note that this API must implement some specific behaviors, +described further in <> + ===== Version 1 - Prototype ---- (func $ext_storage_get_version_1 @@ -107,11 +150,15 @@ Arguments:: * `return`: an i32 integer value equal to _1_ if the key exists or a value equal to _0_ if otherwise. +[#sect-ext-storage-clear-prefix] ==== `ext_storage_clear_prefix` Clear the storage of each key/value pair where the key starts with the given prefix. +IMPORTANT: Do note that this API must implement some specific behaviors, +described further in <> + ===== Version 1 - Prototype ---- (func $ext_storage_clear_prefix_version_1