CIP-0048? | NFT metadata references and payloads

CIP-0048/README.md

@@ -0,0 +1,249 @@
+---
+CIP: 48?
+Title: 721 References and Payloads
+Authors: Jack (ada9000, https://forum.cardano.org/u/jack7e/, @ada9000_ twitter)
+Comments-URI: https://forum.cardano.org/t/cip-extended-721/
+Status: Draft
+Type: Informational
+Created: 2022-04-22 (updated 2022-09-22)
+---
+
+## Important note
+
+This CIP mentions the `ext` json key defined by [CIP49](https://github.com/cardano-foundation/CIPs/pull/343/files) which is an outcome of work on CIP48.
+
+# Abstract
+
+- This standard proposes a method to allow NFT assets to reference other onchain data.
+- This would allow users of 721 metadata to increase or reduce the amount of data an NFT asset uses.
+
+# Motivation
+
+- Large token mints that duplicated data could be dramatically reduced in size by pointing to one transaction payload that contains a ‘boilerplate’ structure.
+- 16kB is the upper limit of data in each transaction but If a user wanted more there is no alternative than to store that data off-chain using an external service such as ipfs.
+- There is no current mechanism to reduce duplicated metadata
+- NFT assets are restricted by there own metadata scope, optional references would prevent this restriction
+- There is currently no way to reference on chain data stored in a different policy
+
+# Specification
+
+### **Inside the 721 metadata JSON**
+
+| reserved | description | scope |
+| -------- | ------------------------------------------------------ | ------------------------- |
+| refs | references tag, defines where to find the onchain data | Inside `<asset_name>` tag |
+| p | contains raw data (on chain data). | Inside `<policy_id>` tag |
+
+### **The `refs` tag**
+
+Contains the `name`, `mediaType`, `src` tags (and the optional `type` tag)
+
+- `name` (string) is the references name (similar usage to name in the current `files` tag)
+- `mediaType` (string) defines the mime type for the data referenced in `src`
+ - is a string
+- `src` (string array) is an **ordered** array of references.
+ - The order is that of which the data will be parsed. For example `["1","3","2"]` will result in payload `"1"` being the start of the data, followed by payload `"3"` and ending with payload `"2"`.
+
+### **Optional `type` tag for `refs`**
+
+The default CIP-48 behavior is to assume the assets parent `<policy_id>` contains all the payloads.
+
+Optionally we define `type` and two options `policy` and `txhash`. To allow for non-default behavior
+
+- `policy`
+ - Defines an external policy (instead of the default behavior of using the parent policy)
+ - example
+ ```json
+ "refs": [
+ {
+ "name": "...",
+ "mediaType": "...",
+ "type": {
+ "policy": "<some_external_policy>"
+ }
+ }
+ ]
+ ```
+- `txhash`
+ - Defines an array of transaction hashes (instead of the default behavior of using the parent policy)
+ - example
+ ```json
+ "refs": [
+ {
+ "name": "...",
+ "mediaType": "...",
+ "type": {
+ "txhash": ["<mint_txhash>", "<mint_txhash>"]
+ }
+ }
+ ]
+ ```
+ - `txhash` is faster than parsing all transactions in a given policy.
+ - `txhash` can dramatically reduce onchain data usage if duplicated data is referenced here _(however, the bytes required to define the reference would have to be less than the reference data itself)_
+
+### **The payload `p` tag**
+
+- Defined within the `<policy_id>` scope
+- contains payload reference names followed by a string array of payload data
+- example
+ ```json
+ "p":
+ {
+ "1": ["1 is a valid payload"],
+ "payloadA": ["a...64","b...64"], //a string has a max length of 64 characters
+ "payloadB": ["I'm found by referencing payloadB"],
+ }
+ ```
+
+## General structure
+
+```json
+{
+ "721": {
+ "ext": ["cip48"], // tells 'user' cip48 is in use within the metadata
+ "<policy_id>": {
+ "<asset_name>": {
+ "project": "<string>",
+ "name": "<string>",
+ "image": "<ref_name | uri | array>" // image is defined by refs or a uri
+ // references
+ "refs": [
+ {
+ "name": "<ref_name>",
+ "mediaType": "text/plain",
+ "src": ["<payload_id>", "<payload_id>"] // array of required payload ids (ordered)
+ }
+ ]
+ },
+ // payload
+ "p": {
+ "<payload_id>": ["<data>", "<data>"], // payload0
+ "<payload_id>": ["<data>"] // payload1
+ }
+ }
+ }
+}
+```
+
+## Notes
+
+- CIP25 currently defines a 'required' image tag.
+ - CIP48 alters the use of image. Requiring the 'user' to first check if the image string matches any reference names. Then to fallback on the default behavior.
+ - example, in which the image is found by referring to payloads.
+ ```json
+ {
+ "image":"myImageNFT"
+ "refs":[
+ {
+ "name": "myImageNFT"
+ "mediaType":"image/svg+xml;utf8"
+ "src": ["refToPayloadA", "refToPayloadB"]
+ }
+ ]
+ }
+ ```
+ - The `image` tag can still be used as a thumbnail if required.
+- If there are multiple `refs` defined the references that are _NOT_ defined in the `image` tag have the same behavior as the `files` tag currently defined in CIP25
+
+# Example
+
+Mint transaction 1
+
+```json
+{
+ "721": {
+ "ext": ["cip48"],
+ "0000000000000000000000000000000000000000000000000000000A": {
+ "NFT0": {
+ "project": "CIP48 Example",
+ "name": "NFT0",
+ // references
+ "refs": [
+ {
+ "name": "NFT0",
+ "mediaType": "text/plain",
+ "src": ["0", "2"]
+ }
+ ]
+ },
+ // payload
+ "p": {
+ "0": ["Hello"],
+ "1": ["Goodbye"]
+ }
+ }
+ }
+}
+```
+
+Mint transaction 2
+
+```json
+{
+ "721": {
+ "ext": ["cip48"],
+ "0000000000000000000000000000000000000000000000000000000A": {
+ "NFT1": {
+ "project": "CIP48 Example",
+ "name": "NFT1",
+ // references
+ "refs": [
+ {
+ "name": "NFT1",
+ "mediaType": "text/plain",
+ "src": ["0", "3"]
+ }
+ ]
+ },
+ // payload
+ "p": {
+ "2": ["World"],
+ "3": ["Moon"]
+ }
+ }
+ }
+}
+```
+
+### Pseudo code walk through using the above example (using default behavior)
+
+1. Find all transactions for the given `<policy_id>`
+
+ - `found 2 mint transcations`
+
+2. Check the **ext** tag for **cip48**
+
+ - `found cip48` we now know the metadata contains references and payloads
+
+3. Iterate over each transaction. If a payload is found append that to an map or some data structure
+
+ - found 4 payloads
+ - ```js
+ payloads = { 0: "Hello", 1: "Goodbye", 2: "World", 3: "Moon" };
+ ```
+
+4. Find all `refs` (references) for the `<asset_name>` we use NFT0. Then build the data in the order defined by the `src` array.
+
+ - found 2 references
+ - ```js
+ nft0_refs = ["0", "2"];
+ nft0_data = "HelloWorld";
+ ```
+
+5. use the mediaType (mimetype) to determine the data.
+ - mediaType = "test/plain"
+ - NFT0 contains text "HelloWorld"
+
+# Backwards compatibility
+
+Handled via the use of the `"ext"` tag defined in CIP-48.
+
+# Further considerations
+
+- Later we may want to use different reference types, maybe even plutus contract references. Due to this I have defined the `type` tag inside the `refs` (references) tag.
+- `p` is used instead of **payload** to reduce bytes. Specifically `p` is not used within the `<asset_name>` tag therefore readability is less of a priority than data size. Unlike `refs` which is defined in the `<asset_name>` tag
+- JSON is kept over CBOR or alternatives as this CIP is encapsulated in the 721 metadatum tag and JSON is easier for developers to adopt
+
+### Duplicate data
+
+There could be issues with duplicate payloads. To solve the payload defined in the most recently minted tx takes priority.