From 380330570d09b47096150a18e8509c9f64ead132 Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Mon, 7 Nov 2022 15:09:02 +0000 Subject: [PATCH 1/6] expand disclaimer, reference from relevant sections --- ab_host-api/storage.adoc | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index aacefed33..ccc106b25 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -4,10 +4,13 @@ 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]. +with the `:child_storage:` prefix or any keys that are a substring of that +prefix, such as `:child_sto` (but not `:other`, for example). This applies to +reading and writing. If the function expects a return value, then _None_ +(<>) should be returned. See the +https://github.com/w3f/polkadot-spec/issues/575[polkadot-spec issue #575] and +the https://github.com/paritytech/substrate/issues/12461[substrate issue #12461] +for more info. [#defn-state-version] .<> @@ -29,6 +32,9 @@ merkle proof (<>). ==== `ext_storage_set` Sets the value under a given key into storage. +IMPORTANT: Please note the section disclaimer (<>) regarding +child storage keys. + ===== Version 1 - Prototype ---- (func $ext_storage_set_version_1 @@ -43,6 +49,9 @@ value. ==== `ext_storage_get` Retrieves the value associated with the given key from storage. +IMPORTANT: Please note the section disclaimer (<>) regarding +child storage keys. + ===== Version 1 - Prototype ---- (func $ext_storage_get_version_1 @@ -112,6 +121,9 @@ to _0_ if otherwise. Clear the storage of each key/value pair where the key starts with the given prefix. +IMPORTANT: Please note the section disclaimer (<>) regarding +child storage keys. + ===== Version 1 - Prototype ---- (func $ext_storage_clear_prefix_version_1 From 44c39d15657d20ad7c26e8acbf935dc26f373b34 Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Mon, 7 Nov 2022 16:03:32 +0000 Subject: [PATCH 2/6] add section on Substrate assumptions --- ab_host-api/storage.adoc | 40 ++++++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index ccc106b25..fb66b1a3a 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -3,14 +3,38 @@ 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:` prefix or any keys that are a substring of that -prefix, such as `:child_sto` (but not `:other`, for example). This applies to -reading and writing. If the function expects a return value, then _None_ -(<>) should be returned. See the -https://github.com/w3f/polkadot-spec/issues/575[polkadot-spec issue #575] and -the https://github.com/paritytech/substrate/issues/12461[substrate issue #12461] -for more info. +==== Implementation Assumptions +The storage and child storage (<>) functionality in the +Substrate implementation is based on a couple of assumptions in order for the +Runtime to behave deterministically. While Polkadot Host implementers can decide +for themselves on how those APIs are implemented - as long as the interface is +corerct - those behaviors must be replicated. In Substrate, child storages are +namespaces 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 or any keys that are a +substring of that 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`, retuns the root of the child storage. This +is described in TODO. + +See the https://github.com/w3f/polkadot-spec/issues/575[polkadot-spec issue +#575] and the https://github.com/paritytech/substrate/issues/12461[substrate +issue #12461] for more info. [#defn-state-version] .<> From a4a95c5d8ace2a1b1f8f4b65f162335c4a1470ed Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Mon, 7 Nov 2022 16:10:19 +0000 Subject: [PATCH 3/6] resentence, expand a little --- ab_host-api/storage.adoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index fb66b1a3a..47ee8f491 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -4,16 +4,16 @@ Interface for accessing the storage from within the runtime. ==== Implementation Assumptions -The storage and child storage (<>) functionality in the -Substrate implementation is based on a couple of assumptions in order for the -Runtime to behave deterministically. While Polkadot Host implementers can decide -for themselves on how those APIs are implemented - as long as the interface is -corerct - those behaviors must be replicated. In Substrate, child storages are -namespaces 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. +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 From b0c3337535ffbf3f61a30c3801823cfab3ab64b5 Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Mon, 7 Nov 2022 16:38:19 +0000 Subject: [PATCH 4/6] expand on child storage root behavior --- ab_host-api/child_storage.adoc | 5 ++++ ab_host-api/storage.adoc | 50 ++++++++++++++++++++-------------- 2 files changed, 35 insertions(+), 20 deletions(-) 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 47ee8f491..4554bb692 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -3,6 +3,7 @@ Interface for accessing the storage from within the runtime. +[#sect-storage-assumptions] ==== Implementation Assumptions The storage and child storage (<>) API in the Substrate implementation makes some behavioral assumptions on the underlying storage @@ -15,26 +16,33 @@ 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`. +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 or any keys that are a -substring of that prefix, such as `:child_sto` (but not `:other`, for example). -If the function expects a return value, then _None_ (<>) -should be returned. +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 `: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`, retuns the root of the child storage. This -is described in TODO. - -See the https://github.com/w3f/polkadot-spec/issues/575[polkadot-spec issue -#575] and the https://github.com/paritytech/substrate/issues/12461[substrate -issue #12461] for more info. +`: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 yet. 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] .<> @@ -56,8 +64,8 @@ merkle proof (<>). ==== `ext_storage_set` Sets the value under a given key into storage. -IMPORTANT: Please note the section disclaimer (<>) regarding -child storage keys. +IMPORTANT: Do note that this API must implement some specific behaviors, +described further in <> ===== Version 1 - Prototype ---- @@ -70,11 +78,12 @@ 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: Please note the section disclaimer (<>) regarding -child storage keys. +IMPORTANT: Do note that this API must implement some specific behaviors, +described further in <> ===== Version 1 - Prototype ---- @@ -140,13 +149,14 @@ 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: Please note the section disclaimer (<>) regarding -child storage keys. +IMPORTANT: Do note that this API must implement some specific behaviors, +described further in <> ===== Version 1 - Prototype ---- From d715c2357a9988dac39efdf0bf77be6cb45af410 Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Mon, 7 Nov 2022 16:40:26 +0000 Subject: [PATCH 5/6] formatting --- ab_host-api/storage.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index 4554bb692..389c51586 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -23,7 +23,7 @@ the key `:child_storage:default:some_child:some_key` is equivalent to calling 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 +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 `:child_storage:` prefix, @@ -34,8 +34,8 @@ 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 yet. Respectively, that 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. From 0320fc0561f4e40a919d1008c81f09fd98e0e584 Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Tue, 8 Nov 2022 00:29:35 +0000 Subject: [PATCH 6/6] update sentence --- ab_host-api/storage.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index 389c51586..1e96fbaa0 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -26,7 +26,7 @@ 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 `:child_storage:` prefix, +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. @@ -40,6 +40,7 @@ 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