Skip to content

Commit

Permalink
Clarify map ordering only applies to binary
Browse files Browse the repository at this point in the history
  • Loading branch information
PhilippGackstatter committed Jan 22, 2024
1 parent f747012 commit c33788a
Showing 1 changed file with 12 additions and 2 deletions.
14 changes: 12 additions & 2 deletions tips/TIP-0038/tip-0038.md
Original file line number Diff line number Diff line change
Expand Up @@ -858,7 +858,8 @@ Feature</i>: smart contract request parameters are encoded in the metadata field
- Each `Key` in the `Entries` must consist only of bytes that are printable ASCII characters, that is, for each
character `char` (interpreted as a byte) in the `Key` it must hold: `33 <= char <= 126`.
- Each `Key` in the `Entries` must be unique.
- The `Entries` must be lexicographically ordered based on the `Key`.
- The `Entries` must be lexicographically ordered based on `Key`.
- Note: This requirement only applies to the binary serialization. See also the note on [map ordering](#map-ordering).
- `Entries Count` must be at least `1`.
- The serialized size of the map, consisting of the serialized size of `Entries Count` plus the serialized size of all
`Entries`, must not exceed `8192` bytes.
Expand Down Expand Up @@ -1055,7 +1056,7 @@ is the block's `Issuing Time` timestamp, which is is meant to be very difficult
In Stardust, the Metadata Feature was defined as an arbitrary byte array to allow applications to be built on top of the
data stored in the ledger. However, only one such feature was allowed in a given output making it practically impossible
for two independent applications to both store data in the same output. Moreover, it was hard to identify what
application has written data into the metadata, making it tough for applications, such as wallets, that read these
application has written data into the metadata, making it tough for other applications, such as wallets, that read these
values, to interpret the data correctly. To address this, the feature was changed to a map of key-value pairs, where the
keys are human-readable identifiers and the keys are arbitrary byte values. This additional level of abstraction allows
multiple applications to write data into the same output, as long as they use different keys. The keys are limited to
Expand All @@ -1067,6 +1068,15 @@ their encoding, compression or other relevant information for the correct interp
wallets and other data readers to detect content based on the keys, which is much more resilient than attempting to
inspect the raw bytes for magic bytes, encoding or compression markers.

### Map Ordering

The map's `Entries` are required to be lexicographically ordered, in order to produce a deterministic binary
serialization, on which identifiers like the Transaction ID or the signing message of a transaction depend on. Map
implementations often don't retain an order like lists/arrays do, which requires this sorting. However, this requirement
only applies to the binary serialization, since it must be deterministic. Other data exchange formats, like JSON used in
REST APIs are not signed or hashed. JSON in particular also does not require or guarantee a map order. Hence, the
ordering is not strictly required for any other format than the binary one.

# Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

0 comments on commit c33788a

Please sign in to comment.