From 6e11ac15f6b44b2ced0fcbedaa4cf4da434d56d0 Mon Sep 17 00:00:00 2001 From: Fabio Lama Date: Fri, 25 Nov 2022 09:53:10 +0000 Subject: [PATCH 1/6] start with version 3 of clear_prefix --- ab_host-api/storage.adoc | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index aacefed33..6345f7356 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -110,7 +110,7 @@ to _0_ if otherwise. ==== `ext_storage_clear_prefix` Clear the storage of each key/value pair where the key starts with the given -prefix. +prefix in lexicographic order (<>). ===== Version 1 - Prototype ---- @@ -148,6 +148,23 @@ 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. +===== Version 2 - Prototype +---- +(func $ext_storage_clear_prefix_version_3 + (param $prefix i64) (param $maybe_limit i64) (param $maybe_cursor i64) + (return i64)) +---- + +Arguments:: +* `prefix`: a pointer-size (<>) containing +the prefix. +* `limit`: a pointer-size (<>) to an _Option_ type +(<>) containing an unsigned 32-bit integer indicating the +limit on how many keys should be deleted. No limit is applied if this is _None_. +Any keys created during the current block execution do not count towards the +limit. +* `maybe_cursor` a pointer-size (<<>>) to an _Option_ type (<<>>) containing an unsigned 32-bit integer indicating the TODO... + ==== `ext_storage_append` Append the SCALE encoded value to a SCALE encoded sequence (<>) From a5d5fece4697f4294429acbbad282569a80bbd59 Mon Sep 17 00:00:00 2001 From: Fabio Lama Date: Fri, 25 Nov 2022 11:19:13 +0000 Subject: [PATCH 2/6] describe maybe_cursor argument --- ab_host-api/storage.adoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index 6345f7356..9dfd4c475 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -148,7 +148,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. -===== Version 2 - Prototype +===== Version 3 - Prototype ---- (func $ext_storage_clear_prefix_version_3 (param $prefix i64) (param $maybe_limit i64) (param $maybe_cursor i64) @@ -163,7 +163,11 @@ the prefix. limit on how many keys should be deleted. No limit is applied if this is _None_. Any keys created during the current block execution do not count towards the limit. -* `maybe_cursor` a pointer-size (<<>>) to an _Option_ type (<<>>) containing an unsigned 32-bit integer indicating the TODO... +* `maybe_cursor` a pointer-size (<>) to an _Option_ +type (<>) containing an unsigned 32-bit integer indicating the +key at which or after which the clear operation should be applied. If the key +does not exist, then the clear operation starts at the next key matching the +`prefix` in lexicographic (<>) ordering. ==== `ext_storage_append` From 53627ff5b113f1612c13f69faaf85ce3bdaed9e8 Mon Sep 17 00:00:00 2001 From: Fabio Lama Date: Fri, 25 Nov 2022 13:26:59 +0000 Subject: [PATCH 3/6] spec returned return value of clear_prefix version 3 --- ab_host-api/storage.adoc | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index 9dfd4c475..7495edda9 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -164,10 +164,33 @@ limit on how many keys should be deleted. No limit is applied if this is _None_. Any keys created during the current block execution do not count towards the limit. * `maybe_cursor` a pointer-size (<>) to an _Option_ -type (<>) containing an unsigned 32-bit integer indicating the -key at which or after which the clear operation should be applied. If the key -does not exist, then the clear operation starts at the next key matching the -`prefix` in lexicographic (<>) ordering. +type (<>) containing an byte array indicating the key +("cursor") at which or after which the clear operation should be applied. If the +key does not exist, then the clear operation starts at the next key matching the +`prefix` in lexicographic order (<>). +* `result`: a pointer-size (<>) returning a SCALE +encoded structure stem:[R] of the following format: ++ +[stem] +++++ +R = (C, s, u, l) +++++ ++ +where ++ +* stem:[C] is a pointer-size (<>) to an _Option_ type +(<>) containing the byte array indicating the next cursor +which must be provided to a subsequent call to this function, which might be the +needed depending on the defined `limit`. This value is _None_ if all the matching +keys were deleted and no further subsequent calls are needed. +* stem:[s] is an unsigned 32-bit integer indicating the number of keys that were +deleted by the operation. Any deleted keys that were created during the current +block execution do not count towards this number. +* stem:[u] is an unsigned 32-bit integer indicating the number of keys that were +deleted by the operations. This does include the deleted keys that were created +during the current block execution. +* stem:[l] is an unsigned 32-bit integer indicating the number of keys that were +deleted from the state but were not created during the current block execution. ==== `ext_storage_append` From 6c5191229e34e48973f4502ce293be660ec98abc Mon Sep 17 00:00:00 2001 From: Fabio Lama Date: Fri, 25 Nov 2022 13:57:48 +0000 Subject: [PATCH 4/6] add version 3 of clear_prefix for child storages --- ab_host-api/child_storage.adoc | 50 ++++++++++++++++++++++++++++++++-- ab_host-api/storage.adoc | 9 +++--- 2 files changed, 53 insertions(+), 6 deletions(-) diff --git a/ab_host-api/child_storage.adoc b/ab_host-api/child_storage.adoc index 9ed72bdeb..ae1dc8457 100644 --- a/ab_host-api/child_storage.adoc +++ b/ab_host-api/child_storage.adoc @@ -209,8 +209,54 @@ k = {(0,-> c),(1,-> c):} ++++ + 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. +followed by the unsigned 32-bit number of removed keys, stem:[c]. The variant +_1_ indicates that there are remaining keys, followed by the unsigned 32-bit +number of removed keys. + +===== Version 3 - Prototype +---- +(func $ext_storage_clear_prefix_version_3 + (param $prefix i64) (param $maybe_limit i64) (param $maybe_cursor i64) + (return i64)) +---- + +Arguments:: +* `prefix`: a pointer-size (<>) containing +the prefix. +* `limit`: a pointer-size (<>) to an _Option_ type +(<>) containing an unsigned 32-bit integer indicating the +limit on how many keys should be deleted. No limit is applied if this is _None_. +Any keys created during the current block execution do not count towards the +limit. +* `maybe_cursor` a pointer-size (<>) to an _Option_ +type (<>) containing an byte array indicating the key +("cursor") at which or after which the clear operation should be applied. If the +key does not exist, then the clear operation starts at the next key matching the +`prefix` in lexicographic order (<>). +* `result`: a pointer-size (<>) returning a SCALE +encoded structure stem:[R] of the following format: ++ +[stem] +++++ +R = (C, s, u, l) +++++ ++ +where ++ +* stem:[C] is a pointer-size (<>) to an _Option_ type +(<>) containing the byte array indicating the next cursor +which must be provided to a subsequent call to this function, which might be the +needed depending on the defined `limit`. This value is _None_ if all the matching +keys were deleted and no further subsequent calls are needed. +* stem:[s] is an unsigned 32-bit integer indicating the number of keys that were +deleted by the operation. Any deleted keys that were created during the current +block execution do not count towards this number. +* stem:[u] is an unsigned 32-bit integer indicating the number of keys that were +deleted by the operations. This does include the deleted keys that were created +during the current block execution. +* stem:[l] is an unsigned 32-bit integer indicating the number of keys that were +deleted from the state but were not created during the current block execution. + ==== `ext_default_child_storage_root` diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index 7495edda9..9a0d67cf6 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -144,13 +144,14 @@ limit. k = {(0,-> c),(1,-> c):} ++++ + -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. +where _0_ indicates that all keys of the storage have been removed, followed by +the unsigned 32-bit number of removed keys, stem:[c]. The variant _1_ indicates +that there are remaining keys, followed by the unsigned 32-bit number of removed +keys. ===== Version 3 - Prototype ---- -(func $ext_storage_clear_prefix_version_3 +(func $ext_default_child_storage_clear_prefix_version_3 (param $prefix i64) (param $maybe_limit i64) (param $maybe_cursor i64) (return i64)) ---- From c8e621c469759ec5a32176bc4783595c44ab2fac Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Mon, 28 Nov 2022 14:45:28 +0000 Subject: [PATCH 5/6] document version 4 of storage_kill --- ab_host-api/child_storage.adoc | 52 ++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/ab_host-api/child_storage.adoc b/ab_host-api/child_storage.adoc index ae1dc8457..447841fb1 100644 --- a/ab_host-api/child_storage.adoc +++ b/ab_host-api/child_storage.adoc @@ -147,6 +147,51 @@ 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. +===== Version 4 - Prototype +---- +(func $ext_default_child_storage_storage_kill_version_4 + (param $child_storage_key i64) (param $maybe_limit i64) + (param $maybe_cursor i64) (return i64)) +---- + +Arguments:: + +* `child_storage_key`: a pointer-size (<>) to the +child storage key (<>). +* `limit`: a pointer-size (<>) to an _Option_ type +(<>) containing an unsigned 32-bit integer indicating the +limit on how many keys should be deleted. No limit is applied if this is _None_. +Any keys created during the current block execution do not count towards the +limit. +* `maybe_cursor` a pointer-size (<>) to an _Option_ +type (<>) containing an byte array indicating the key +("cursor") at which or after which the clear operation should be applied. If the +key does not exist, then the clear operation starts at the next key matching the +`prefix` in lexicographic order (<>). +* `result`: a pointer-size (<>) returning a SCALE +encoded structure stem:[R] of the following format: ++ +[stem] +++++ +R = (C, s, u, l) +++++ ++ +where ++ +* stem:[C] is a pointer-size (<>) to an _Option_ type +(<>) containing the byte array indicating the next cursor +which must be provided to a subsequent call to this function, which might be the +needed depending on the defined `limit`. This value is _None_ if all the matching +keys were deleted and no further subsequent calls are needed. +* stem:[s] is an unsigned 32-bit integer indicating the number of keys that were +deleted by the operation. Any deleted keys that were created during the current +block execution do not count towards this number. +* stem:[u] is an unsigned 32-bit integer indicating the number of keys that were +deleted by the operations. This does include the deleted keys that were created +during the current block execution. +* stem:[l] is an unsigned 32-bit integer indicating the number of keys that were +deleted from the state but were not created during the current block execution. + ==== `ext_default_child_storage_exists` Checks whether the given key exists in the child storage. @@ -216,11 +261,15 @@ number of removed keys. ===== Version 3 - Prototype ---- (func $ext_storage_clear_prefix_version_3 - (param $prefix i64) (param $maybe_limit i64) (param $maybe_cursor i64) + (param $child_storage_key i64) (param $prefix i64) + (param $maybe_limit i64) (param $maybe_cursor i64) (return i64)) ---- Arguments:: + +* `child_storage_key`: a pointer-size (<>) to the +child storage key (<>). * `prefix`: a pointer-size (<>) containing the prefix. * `limit`: a pointer-size (<>) to an _Option_ type @@ -257,7 +306,6 @@ during the current block execution. * stem:[l] is an unsigned 32-bit integer indicating the number of keys that were deleted from the state but were not created during the current block execution. - ==== `ext_default_child_storage_root` Commits all existing operations and computes the resulting child storage From 630777af72afe1d4356ca1ffaa19044126fe59ba Mon Sep 17 00:00:00 2001 From: lamafab <42901763+lamafab@users.noreply.github.com> Date: Mon, 28 Nov 2022 15:35:36 +0000 Subject: [PATCH 6/6] unify multi removal results structure --- ab_host-api/child_storage.adoc | 46 ++-------------------------------- ab_host-api/storage.adoc | 16 +++++++++--- 2 files changed, 14 insertions(+), 48 deletions(-) diff --git a/ab_host-api/child_storage.adoc b/ab_host-api/child_storage.adoc index 447841fb1..2115b9de7 100644 --- a/ab_host-api/child_storage.adoc +++ b/ab_host-api/child_storage.adoc @@ -169,28 +169,7 @@ type (<>) containing an byte array indicating the key key does not exist, then the clear operation starts at the next key matching the `prefix` in lexicographic order (<>). * `result`: a pointer-size (<>) returning a SCALE -encoded structure stem:[R] of the following format: -+ -[stem] -++++ -R = (C, s, u, l) -++++ -+ -where -+ -* stem:[C] is a pointer-size (<>) to an _Option_ type -(<>) containing the byte array indicating the next cursor -which must be provided to a subsequent call to this function, which might be the -needed depending on the defined `limit`. This value is _None_ if all the matching -keys were deleted and no further subsequent calls are needed. -* stem:[s] is an unsigned 32-bit integer indicating the number of keys that were -deleted by the operation. Any deleted keys that were created during the current -block execution do not count towards this number. -* stem:[u] is an unsigned 32-bit integer indicating the number of keys that were -deleted by the operations. This does include the deleted keys that were created -during the current block execution. -* stem:[l] is an unsigned 32-bit integer indicating the number of keys that were -deleted from the state but were not created during the current block execution. +encoded _multi removal results_ structure (<>). ==== `ext_default_child_storage_exists` @@ -283,28 +262,7 @@ type (<>) containing an byte array indicating the key key does not exist, then the clear operation starts at the next key matching the `prefix` in lexicographic order (<>). * `result`: a pointer-size (<>) returning a SCALE -encoded structure stem:[R] of the following format: -+ -[stem] -++++ -R = (C, s, u, l) -++++ -+ -where -+ -* stem:[C] is a pointer-size (<>) to an _Option_ type -(<>) containing the byte array indicating the next cursor -which must be provided to a subsequent call to this function, which might be the -needed depending on the defined `limit`. This value is _None_ if all the matching -keys were deleted and no further subsequent calls are needed. -* stem:[s] is an unsigned 32-bit integer indicating the number of keys that were -deleted by the operation. Any deleted keys that were created during the current -block execution do not count towards this number. -* stem:[u] is an unsigned 32-bit integer indicating the number of keys that were -deleted by the operations. This does include the deleted keys that were created -during the current block execution. -* stem:[l] is an unsigned 32-bit integer indicating the number of keys that were -deleted from the state but were not created during the current block execution. +encoded _multi removal results_ structure (<>). ==== `ext_default_child_storage_root` diff --git a/ab_host-api/storage.adoc b/ab_host-api/storage.adoc index 9a0d67cf6..aca6fbefc 100644 --- a/ab_host-api/storage.adoc +++ b/ab_host-api/storage.adoc @@ -170,15 +170,22 @@ type (<>) containing an byte array indicating the key key does not exist, then the clear operation starts at the next key matching the `prefix` in lexicographic order (<>). * `result`: a pointer-size (<>) returning a SCALE -encoded structure stem:[R] of the following format: -+ +encoded _multi removal results_ structure (<>). + +[#defn-multi-removal-results] +.<> +==== +The **multi removal results** is a datastructure returned by various removal +mechanisms, referenced in the appropriate sections. The datastructure is of the +following format: + [stem] ++++ R = (C, s, u, l) ++++ -+ + where -+ + * stem:[C] is a pointer-size (<>) to an _Option_ type (<>) containing the byte array indicating the next cursor which must be provided to a subsequent call to this function, which might be the @@ -192,6 +199,7 @@ deleted by the operations. This does include the deleted keys that were created during the current block execution. * stem:[l] is an unsigned 32-bit integer indicating the number of keys that were deleted from the state but were not created during the current block execution. +==== ==== `ext_storage_append`