From cf9ce550c889c6cbebb70e23c8f5dfedd2987476 Mon Sep 17 00:00:00 2001 From: Joe Polny Date: Thu, 15 Jun 2023 17:15:24 -0400 Subject: [PATCH 1/4] tuple end in head --- ARCs/arc-draft_tuple_end_head.md | 54 ++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 ARCs/arc-draft_tuple_end_head.md diff --git a/ARCs/arc-draft_tuple_end_head.md b/ARCs/arc-draft_tuple_end_head.md new file mode 100644 index 000000000..d7629d096 --- /dev/null +++ b/ARCs/arc-draft_tuple_end_head.md @@ -0,0 +1,54 @@ +--- +arc: +title: Dynamic Tuple End In Head +description: Append the end of a dynamic tuple to the head values +author: Joe Polny (@joe-p) +discussions-to: +status: Draft +type: Standards Track +category: ARC +created: 2023-07-15 +requires (*optional): [ARC-0004](./arc-0004.md) +--- + +## Abstract +According to [ARC-0004](./arc-0004.md), when encoding dynamic types in a tuple the tuple consists of a `head` containing all of the offsets of the actual values in the `tail`. An additional value, the byte offset of the end of the tuple, should be added to the end of the `head` value for more efficient element reading. + +## Motivation +When reading a value in a dynamic tuple, the head offset of the element must be extracted as a `uint16` to get the start of the element. To get the end of the element, which is necessary to properly read the element, the following head value can be extracted. This, however, fails to work when the element being read is the last element in its respective dynamic array or tuple. When the element is the last in the array or tuple, one must compute the length of the element. For static types, this is trivial and for dynamic arrays of static types this is also trivial because the length prefix can be used. For more complex nested dynamic types, however, this could involve many levels of extracting lengths and offsets, thus reading an element is `O(N)`, which `N` being the depth of the nested dynamic types. If there was an additional head value containing the end of the dynamic tuple, readnig any element, regardless of its type or position, would be `O(1)` since one can always just extract the following head value. + +## Specification +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in RFC-2119. + +Tuples **MUST** be encoded with the following rules: + +* If `x` is a tuple of `N` types, `(T1,T2,...,TN)`, where `x[i]` is the value at index `i`, starting at 1 and `x[i]` is dynamic: + * `head(x[i]) = enc(2 + len( head(x[1]) ... head(x[N]) tail(x[1]) ... tail(x[i-1]) ))` + * `tail(x[i]) = enc(x[i])` +* If `x` is a tuple of `N` types, `(T1,T2,...,TN)`, and any type is dynamic + * `x = enc( head(x[i]) ... head(x[N]) + ( 2 + len( head(x[i]) ... head(x[N]) ) + len( tail(x[i]) ... tail(x[N]) ) ) + tail(x[i]) ... tail(x[N]) )` + + +## Rationale +This will make reading values from an ABI encoded tuple much more efficient, which is especially important for on-chain logic. + +## Backwards Compatibility +[ARC-0004](./arc-0004.md) clients will be able to read tuples encoded according to this ARC, but they will not be able to write them. + +## Test Cases +N/A + +## Reference Implementation + +Encoding of `["Hello", "World"]` as `string[]` + +[ARC-0004](./arc-0004.md): `0x0002 0004 000b 0005 48656c6c6f 0005 576f726c64` + +This ARC: `0x0002 0006 000d 0014 0005 48656c6c6f 0005 576f726c64` + +Note the addition of the `0014` signifying the end of the tuple/array and `head(x[1])` and `head[x[2]]` being incremented by two to account for this additional value. +## Security Considerations +None + +## Copyright +Copyright and related rights waived via CCO. From e058bad2248568c93face3d53defa5cc6ffa33bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Fri, 16 Jun 2023 10:45:13 +0200 Subject: [PATCH 2/4] Assign number + fix format --- ARCs/{arc-draft_tuple_end_head.md => arc-0039.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename ARCs/{arc-draft_tuple_end_head.md => arc-0039.md} (97%) diff --git a/ARCs/arc-draft_tuple_end_head.md b/ARCs/arc-0039.md similarity index 97% rename from ARCs/arc-draft_tuple_end_head.md rename to ARCs/arc-0039.md index d7629d096..359b0d525 100644 --- a/ARCs/arc-draft_tuple_end_head.md +++ b/ARCs/arc-0039.md @@ -1,14 +1,14 @@ --- -arc: +arc: 39 title: Dynamic Tuple End In Head description: Append the end of a dynamic tuple to the head values author: Joe Polny (@joe-p) -discussions-to: +discussions-to: https://github.com/algorandfoundation/ARCs/issues/212 status: Draft type: Standards Track category: ARC created: 2023-07-15 -requires (*optional): [ARC-0004](./arc-0004.md) +requires: 4 --- ## Abstract From c294270c6e06c128843826e5e0fbc679bb40355d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Mon, 10 Jul 2023 16:40:51 +0200 Subject: [PATCH 3/4] Update and rename arc-0039.md to arc-0045.md Rename this one to keep ARC-39 for BIP-39 approach. --- ARCs/{arc-0039.md => arc-0045.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename ARCs/{arc-0039.md => arc-0045.md} (99%) diff --git a/ARCs/arc-0039.md b/ARCs/arc-0045.md similarity index 99% rename from ARCs/arc-0039.md rename to ARCs/arc-0045.md index 359b0d525..28f17f054 100644 --- a/ARCs/arc-0039.md +++ b/ARCs/arc-0045.md @@ -1,5 +1,5 @@ --- -arc: 39 +arc: 45 title: Dynamic Tuple End In Head description: Append the end of a dynamic tuple to the head values author: Joe Polny (@joe-p) From cb5fc67534cb854bf221208d433cfa82c9448601 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Mon, 10 Jul 2023 16:41:37 +0200 Subject: [PATCH 4/4] Update and rename arc-0045.md to arc-0046.md --- ARCs/{arc-0045.md => arc-0046.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename ARCs/{arc-0045.md => arc-0046.md} (99%) diff --git a/ARCs/arc-0045.md b/ARCs/arc-0046.md similarity index 99% rename from ARCs/arc-0045.md rename to ARCs/arc-0046.md index 28f17f054..963667c13 100644 --- a/ARCs/arc-0045.md +++ b/ARCs/arc-0046.md @@ -1,5 +1,5 @@ --- -arc: 45 +arc: 46 title: Dynamic Tuple End In Head description: Append the end of a dynamic tuple to the head values author: Joe Polny (@joe-p)