CIP-0068 | Make more economic and contract-friendly

CIP-0068/README.md

@@ -57,7 +57,12 @@ Some remarks about the above,
 1. The `user token` and `reference NFT` do not need to be minted in the same transaction. The order of minting is also not important.
 2. It may be the case that there can be multiple `user tokens` (multiple asset names or quantity greater than 1) referencing the same `reference NFT`.
 
-The datum in the output with the `reference NFT` contains the metadata at the first field of the constructor 0. The version number is at the second field of this constructor:
+The version 1 datum in the output with the `reference NFT` contains metadata and a version number. Based on the constructor the first field is either a single metadata (constructor 0) or a map from reference assets to metadata (constructor 1). The version number is at the second field of the datum and applies to all metadata.
+
+Having every single reference token has to be on a separate UTxO might require unnesessarily large amount of ADA to be locked along with it. Especially, when considering NFT series and sending the reference tokens to an unspendable address with more than 1 ADA. In this case batching the metadata through constructor 1 can be beneficial. On the other hand, if the data is referenced often from smart contracts: including and parsing the batched metadata might be much more expensive.
+
+The proposal does not make any assumptions about the exact datum storage method: inlined or using just the hash. There are trade-offs when it comes to using inlining the datum. Inlining will increase UTxO storage costs, while hashes increase interaction costs - see CIP-0032.
+
 ```
 big_int = int / big_uint / big_nint
 big_uint = #6.2(bounded_bytes)
@@ -71,9 +76,13 @@ metadata =
 
 version = int
 
-datum = #6.121([metadata, version])
+; version 1
+datum = #6.121([metadata, version]) /
+        #6.122([multiasset<metadata>, version])
 ```
 
+Similar to version 1, version 2 does not constain if the reference datum should be inlined or not. In case the reference token is often interacting with smart contracts, it's recommended to have the data inlined. On the other hand (e.g. NFT series), it might more economic to only use the hash and provide the datum in the minting transaction. This would reduce the utxo size and hence the minADA that would need to be locked.
+
 ## 222 NFT Standard
 
 Besides the necessary standard for the `reference NFT` we're introducing two specific token standards in this CIP. Note that the possibilities are endless here and more standards can be built on top of this CIP for FTs, other NFTs, semi fungible tokens, etc. The first is the `222` NFT standard with the registered `asset_name_label` prefix value
@@ -98,7 +107,7 @@ Example:\
 
 ### Metadata
 
-This is a low-level representation of the metadata, following closely the structure of CIP-0025. All UTF-8 encoded keys and values need to be converted into their respective byte's representation when creating the datum on-chain.
+This is a low-level representation of the metadata, following closely the structure of CIP-0025. All UTF-8 encoded keys and values need to be converted into their respective byte's representation when creating the datum on-chain. The metadata can be batched with constructor 1 to reduce locked ADA costs.
 
 ```
 files_details = 
@@ -116,10 +125,13 @@ metadata =
     ? description : bounded_bytes, ; UTF-8
     ? files : [* files_details]
   }
-
-datum = #6.121([metadata, 1]) ; version 1
+
+; version 1
+datum = #6.121([metadata, 1]) \
+        #6.122([multiasset<metadata>, 1])
+
 ```
-Example datum as JSON:
+Example of a single metadata datum as JSON:
 ```json
 {"constructor" : 0, "fields": [{"map": [{"k": "6E616D65", "v": "5370616365427564"}, {"k": "696D616765", "v": "697066733A2F2F74657374"}]}, {"int": 1}]}
 ```
@@ -130,7 +142,9 @@ A third party has the following NFT `d5e6bf0500378d4f0da4e8dde6becec7621cd8cbf5c
 
 1. Construct `reference NFT` from `user token`: `d5e6bf0500378d4f0da4e8dde6becec7621cd8cbf5cbb9b87013d4cc.(100)TestToken`
 2. Look up `reference NFT` and find the output it's locked in.
-3. Get the datum from the output and lookup metadata by going into the first field of constructor 0.
+3. Get the datum from the output and lookup metadata by going into the first field
+   - of constructor 0
+   - of constructor 1 and finding the metadata through the reference token policy ID and assetName
 4. Convert to JSON and encode all string entries to UTF-8 if possible, otherwise leave them in hex.
 
 ### Retrieve metadata from a Plutus validator
@@ -188,8 +202,10 @@ metadata =
 ; 'logo' does not follow the explanation of the token-registry, it needs to be a valid URI and not a plain bytestring.
 ; Only use the following media types: `image/png`, `image/jpeg`, `image/svg+xml`
 uri = bounded_bytes 
-
-datum = #6.121([metadata, 1]) ; version 1
+
+; version 1
+datum = #6.121([metadata, 1]) \
+        #6.122([multiasset<metadata>, 1])
 ```
 Example datum as JSON:
 ```json
@@ -202,7 +218,9 @@ A third party has the following FT `d5e6bf0500378d4f0da4e8dde6becec7621cd8cbf5cb
 
 1. Construct `reference NFT` from `user token`: `d5e6bf0500378d4f0da4e8dde6becec7621cd8cbf5cbb9b87013d4cc.(100)TestToken`
 2. Look up `reference NFT` and find the output it's locked in.
-3. Get the datum from the output and lookup metadata by going into the first field of constructor 0.
+3. Get the datum from the output and lookup metadata by going into the first field
+   - of constructor 0
+   - of constructor 1 and finding the metadata through the reference token policy ID and assetName
 4. Convert to JSON and encode all string entries to UTF-8 if possible, otherwise leave them in hex.
 
 ### Retrieve metadata from a Plutus validator