diff --git a/tips/TIP-0038/tip-0038.md b/tips/TIP-0038/tip-0038.md index ecc199ff0..9bb8527b2 100644 --- a/tips/TIP-0038/tip-0038.md +++ b/tips/TIP-0038/tip-0038.md @@ -858,7 +858,8 @@ Feature: 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. @@ -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 @@ -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/).