CIP-0068 | Support multi-asset metadata a la CIP-0025#1112
CIP-0068 | Support multi-asset metadata a la CIP-0025#1112thaddeusdiamond wants to merge 3 commits intocardano-foundation:masterfrom
Conversation
…tion#1112) Add version 4 metadata support with 721-ERC-style mappings to NFT (222), FT (333) and RFT (444) standards, ensuring consistency across all asset classes. Changes: - Add metadata_field union type supporting both direct and 721-map formats - Add __RESERVE_KEYWORD_721_V4__ marker for 721-style detection - Update retrieval steps to handle both metadata formats - Support version 4 in FT standard - Support version 3/4 in RFT standard - Add 721-style JSON example for NFT standard - Update pattern descriptions with asset_name terminology - Fix URI support to include [* bounded_bytes] for RFT
thaddeusdiamond
force-pushed
the
master
branch
from
fe50df9 to
264170d
Compare
thaddeusdiamond
changed the title
|
@thaddeusdiamond I was answering your comments by subject in alphabetical (not chronological) order, so I posted this response without seeing you've already done the proposed update: I think these changes are consistent with your suggestion of a new best-practice approach, the editorial guidelines, and the requirements of CIP-0068... but we'll follow the related issue in case other feedback indicates that a different approach should be taken. In any case we'll tag this |
rphair
added
Update
rphair
changed the title
|
@thaddeusdiamond I'm recording this meeting resolution to leave this submission |
rphair
added
State: Unconfirmed
|
I think @Crypto2099 was onboard as is since it's backwards compatible but he can comment here. Will close #1111 |
|
@thaddeusdiamond we might not get @Crypto2099's participation on this issue... so if there are any review points you could record here about that conversation please do... otherwise we'll continue on with this without it. If that's the case... @Ryun1 @perturbing if you can recall any other blocking issues to consider this a CIP candidate, perhaps you can post them here? Otherwise we might mark this as |
|
Correct that's the plan.
I've calculated that several of my artists could get a roughly 75% reduction in minUTxO. For a multi-thousand art piece collection this is several hundred to several thousand dollars.
The only problem with that is since the name is part of the reference token itself, you would have to "reprint" the reference tokens instead of making this at the datum level. But I'm open to suggestions.
I would think this would be up to the dApp developer? So long as it conforms to the spec they can either "respend" the datum and rewrite every related token metadata, or they could split it overall.
Consistency issues? This aims to be backwards-compatible with the existing data formats so I'm not sure I'm following. As for the rationale, I'll attach it to the bottom of this comment and you can let me know what/where you want it.
Yes there is no change to SC usage. Since the datum is just "larger" the contract may be slightly more complex, but there is no structural change. This is more on the dApp or SC developer to interpret the datum in a new way. Not sure about Rationale for Introducing Optional CIP-0025-Compatible Metadata Within CIP-0068The current design of CIP-0068 inadvertently creates a significant cost barrier for large NFT collections due to minimum-ADA requirements. As ADA approaches parity with USD, artists and platforms minting 5,000–10,000+ on-chain assets are increasingly impacted by the minUTxO amplification effect: the metadata-bearing reference scripts and datums mandated by CIP-0068 can cause 10–20% of project budgets to be consumed purely by ADA locked in outputs, rather than by art production or ecosystem growth. This cost profile wasn’t as visible when ADA was significantly cheaper, but it has now become an operational friction point across multiple creator workflows. The proposal aims to reduce the minUTxO footprint for CIP-0068 assets by allowing an optional alternate metadata shape that mirrors CIP-0025 (721-style metadata) while preserving CIP-0068’s semantics. Concretely: 1. Dual-format Metadata Reduces Unnecessary ADA LockingAllowing a CIP-0025-shaped metadata payload means:
This addresses a real-world pain point reported by multiple production-level minting pipelines, not just isolated cases. 2. Improved Migration Path from CIP-0025 to CIP-0068A sizeable portion of the ecosystem still lives on CIP-0025, particularly older marketplaces and archived collections. When artists revisit or reissue older collections, the transition path to CIP-0068 is currently friction-heavy, requiring metadata restructuring and toolchain updates. Supporting a CIP-0025-compatible metadata envelope inside CIP-0068:
3. Strict Optionality Preserves Backward CompatibilityThis proposal does not modify or deprecate existing CIP-0068 patterns. This allows:
Why a CIP-0068 Version Bump May Be Preferable to a New CIPAlthough this change is cross-cutting, it:
A versioned update (e.g., v5) avoids fracturing standards, while still being explicit enough for tooling authors and indexers to adopt cleanly. |
|
Thanks. A lot of the confusion came from the fact that you previously didn't introduce the MinUTXO issue at all in your proposal. The introduction was:
Which is why I thought it was about consistency. So it looked like it was trying to solve some metadata issues, but it actually tries to solve some cost and locked ADA issues. This is therefore a work-around for the current value of MinUTXO, quite unrelated to metadata formats. Overall I think comparing to CIP25 is very confusing, and even more "721-ERC". This has almost nothing to do with CIP25:
The only common thing with CIP25 that you introduce is the "policy_id -> asset_name" mapping. The 222/333/444 metadata is then not encoded like CIP25. So given all these differences, I don't think it particularly helps migrating to CIP68. This might instead introduce a lot of errors like in CIP25 v2, where users use strings instead of bytes or mix both versions. Therefore in my opinion this proposal should be introduced without talking about CIP25 at all, but instead just introduce the aim of supporting multiple assets per tx_output and datum. I will add other note in changes comments. |
CIP-0068/README.md
Outdated
| This is either: | ||
|
|
||
| 1. A low-level direct representation of the metadata, following closely the structure of CIP-0025 | ||
| 2. A 721-ERC-style token mapping exactly matching the structure of CIP-0025 |
There was a problem hiding this comment.
This is confusing. Why referencing 721-ERC-style here? What does this mean? This is an Ethereum standard and it is not referenced anywhere. The only link with CIP25 is the 721 metadata label.
Also "mapping exactly matching the structure of CIP-0025" is also confusing. I think you are only talking about the policy_id -> asset_name mapping? The rest is different (222/333/444, bytes instead of strings, etc.). Also only CIP25v2 use bytes as keys in the mapping.
Note that "following closely the structure of CIP-0025" was about the individual asset metadata (name, image, files, etc.). Whereas you seem to talk about its encapsulation in policy_id -> asset_name maps.
There was a problem hiding this comment.
You're absolutely right. I've removed the "721-ERC-style" terminology and clarified that:
- Option 1 refers to the direct metadata format with individual asset metadata fields (name, image, files, etc.) following CIP-0025's structure
- Option 2 refers to CIP-0025's nested map organization with policy_id -> asset_name keys, where the outer map contains a "721" key
The clarification now distinguishes between the individual metadata structure (which CIP-0025 defines) and the encapsulation structure (the policy_id -> asset_name mapping that CIP-0025 uses).
| } | ||
| } | ||
| } | ||
|
|
There was a problem hiding this comment.
This is not some valid CDDL. It looks like you are confusing CDDL with JSON.
More importantly, this does not tell how the policy_id and asset_name keys are encoded (I guess byte encoding like CIP25v2 and all CIP68 fields?).
Overall we should avoid talking about JSON as metadata and datum are CBOR encoded and CBOR -> JSON is not directly bijective. This only leads to confusion.
Note that JSON in CIP68 is only discussed in examples and even this is slightly questionable in my opinion.
There was a problem hiding this comment.
Fixed. The CDDL now properly uses bounded_bytes for all keys:
- "721" key is encoded as bounded_bytes (UTF-8 bytes: 0x373231)
- policy_id keys are bounded_bytes (as in CIP-0025 version 2)
- asset_name keys are bounded_bytes (as in CIP-0025 version 2)
This matches CIP-0025 version 2 conventions where keys are byte-encoded rather than text strings.
CIP-0068/README.md
Outdated
| } | ||
| ``` | ||
|
|
||
| Example datum as JSON (721-style): |
There was a problem hiding this comment.
Again what "721-style" means?
There was a problem hiding this comment.
Changed to "nested map format" to be consistent with the terminology used throughout the document and avoid the ambiguous "721-style" reference.
CIP-0068/README.md
Outdated
| { | ||
| __RESERVE_KEYWORD_721_V4__ : bool, ; Long name to avoid conflict | ||
|
|
||
| "721": |
There was a problem hiding this comment.
What is the point of having __RESERVE_KEYWORD_721_V4__ bool here? Wouldn't the presence of "721" key be enough?
There was a problem hiding this comment.
Removed the __RESERVE_KEYWORD_721_V4__ marker. You're correct that the presence of the "721" key is sufficient to detect the nested map format. The format can be determined simply by checking if the metadata map contains a "721" key.
| } | ||
| } | ||
| } | ||
|
|
There was a problem hiding this comment.
All metadata_map definitions across 222, 333, and 444 standards have been updated with proper CDDL syntax using bounded_bytes for all keys, consistent with CIP-0025 version 2.
| } | ||
| } | ||
| } | ||
|
|
There was a problem hiding this comment.
All metadata_map definitions across 222, 333, and 444 standards have been updated with proper CDDL syntax using bounded_bytes for all keys, consistent with CIP-0025 version 2.
CIP-0068/README.md
Outdated
|
|
||
| #### version 4 | ||
|
|
||
| - Add backwards-compatible support for multi-asset 721-ERC-style metadata mappings |
There was a problem hiding this comment.
"Backwards-compatible" with what exactly?
And again "721-ERC-style" is not clear. There is no ERC on Cardano.
There was a problem hiding this comment.
Clarified:
- "Backwards-compatible" means compatible with versions 1-3, which only supported direct metadata format. Version 4 adds the nested map format as an additional option.
- Removed "721-ERC-style" terminology entirely, replacing it with "nested map format following CIP-0025's policy_id -> asset_name structure"
I meant introducing a new label instead of reusing 222/333/444. Without doing this, this not fully backward compatible because a current indexer will not expect a version 4. So some new CIP68 token minted as a single asset but with version 4 will be ignored or rejected by such tools. I don't understand what you mean by "you would have to "reprint" the reference tokens". |
I'm not sure there is any choice: assuming there are n tokens in a single tx output with their metadata in the output datum. To update only one of the tokens metadata, you will have to spend all of them, at least as change, but CIP68 metadata lookup is described as:
Note that the lookup only looks at the unspent output (not a previous output). Therefore you will have to rewrite the metadata of all tokens in a datum, hence it makes no sense to split them, it would be even costlier. |
Makes sense. So rewrite it then makes sense to me. |
This is quite a significant drawback compared to current CIP68 and even CIP25 (as only one of the tokens can be minted again to update its metadata), so maybe it's worth thinking more about it to avoid introducing a new flaw? |
If it's an optional capability what's the drawback? I don't know how to solve the minUTxO problem without consolidating the NFT metadata. To give a specific example: one of the artists I am minting for has taken roughly 10,000 ADA in project funds and the locked minUTxO is over 1,000 ADA. So that's 10% of his total funds that are locked and can't contribute to his product development. |
Actually, the datum does not have to be inline, in which case I think it can be later referenced just by its hash. I guess this would solve this issue assuming your standard recommends using non-inline datum, at least when the policy allows updates. |
Fix terminology and CDDL syntax issues identified in review: - Remove "721-ERC-style" terminology; clarify reference to CIP-0025's nested map structure vs individual metadata fields - Fix CDDL syntax: use proper bounded_bytes for "721", policy_id, and asset_name keys (matching CIP-0025 version 2 conventions) - Remove __RESERVE_KEYWORD_721_V4__ marker; presence of "721" key is sufficient for format detection - Update retrieval steps to detect format by checking for "721" key - Clarify "backwards-compatible" in changelog: version 4 adds nested map format as additional option, compatible with v1-3 direct format - Rename "721-style" example label to "nested map format" - Propagate all fixes consistently across 222, 333, and 444 standards
Add comprehensive rationale explaining the motivation for introducing the CIP-0025-compatible nested map format in version 4: - Addresses minUTxO cost barriers for large NFT collections - Enables metadata consolidation to reduce ADA locking (10-20% savings) - Improves migration path from CIP-0025 to CIP-0068 - Preserves backward compatibility through strict optionality This rationale explains the economic and practical benefits that led to the version 4 design decision.
|
I published a new change, rationale, and some of my responses. By "reprint" I mean that I already have a ton of (222) NFTs that I want to optimize without having to airdrop everyone a token. Since this is optional and backward-compatible, I can do this optimization inline for my artists now without requiring the creation of 555/666 or whatnot. Please let me know the path to approval @rphair @SmaugPool |
There was a problem hiding this comment.
@thaddeusdiamond at the CIP meeting earlier today we spontaneously picked this one off the Unconfirmed list and decided that we'd been looking for the response that you made a few hours later. 😅
In my opinion this satisfies all the demanding review points beginning with #1112 (comment) with corresponding changes in the text.
Personally I appreciate that #1112 (comment) was put literally into the Rationale & I'd also like to see that happen for any remaining clarifications resulting from the debate — past, present or future — for the benefit of new implementors and others who may be interested in migrating their tokens.
@SmaugPool can you please go back & double-check the conversations beginning with your #1112 (comment) and mark "resolved" the ones you believe have been properly addressed... or note otherwise if you think they need more debate or adjustment?
Otherwise I think we have a achieved a CIP candidate and so have put this on Review for the next CIP meeting (https://hackmd.io/@cip-editors/126) & we'll double-check all pending review points again in 2 weeks.
@thaddeusdiamond @SmaugPool please also tag other associates who you think would be interested in confirming, disputing, or reviewing this update. 🙏
|
@thaddeusdiamond due to a lot of proposals on the |
|
Seems this review may have been deleted? But no, this is intended to be
fully backwards-compatible.
…On Tue, Feb 17, 2026 at 9:52 AM Ryan ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In CIP-0068/README.md
<#1112 (comment)>
:
>
Example:\
`user token`: `(222)Test123`\
`reference NFT`: `(100)Test123`
##### 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 either:
+
+1. A low-level direct representation of the metadata, following closely the structure of CIP-0025 for individual asset metadata (name, image, files, etc.)
+2. A nested map structure following CIP-0025's organization with policy_id and asset_name as keys, where the outer map contains a "721" key whose value maps policy_id to asset_name to metadata
could this extended definition break any existing implementations?
—
Reply to this email directly, view it on GitHub
<#1112 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAE6JBOCZO5TYMCN3564FID4MM2LVAVCNFSM6AAAAACK5RMSECVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTQMJUG44TENBWGQ>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
There was a problem hiding this comment.
@thaddeusdiamond my guess is that @Ryun1 deleted that review (posted a few minutes before today's CIP meeting) after answering his own question about the backward compatibility (this had already been briefly settled at an earlier meeting).
We pressed this item through our Review agenda at that meeting and those present believed it to be technically in order, but with some concern coming from "whether wallet devs have asked for this". The editors believe this could be an issue because of pathological cases like (hypothetically):
- without interest, let alone buy-in, to this addition: this "next generation" of the CIP-0068 standard is merged in, but wallet implementations don't (or don't consistently) use it;
- then some other conception of that "next generation" comes along and this update needs to be backed out somehow — or worse: somehow merged with another evolution that it might not be easily compatible with.
So our decision was to progress this if & when we can get some endorsement from tagged representatives from wallet development teams. @Ryun1 and @perturbing said they would work on this and we're awaiting their tagging some of these for review.
In the meantime I think we can call this Confirmed (though not Last Check as it would be for an unquestioned update PR) as we would any technically complete update awaiting more detailed review.
rphair
added
State: Confirmed
|
Sounds good.
|
|
@thaddeusdiamond appreciate the efforts It would be beneficial to see further review from a range of implementors Tagging some known CIP-68 implementors for visibility |
|
I had a quick look and I do not clearly understand how this is intended to work. Today, with CIP-68, we have: To retrieve metadata, we replace the type with the reference type and then read the datum from the UTxO that contains the reference asset. Each token has a clearly identifiable reference pattern: So we know exactly which reference token to look for in order to extract metadata. What I do not understand is how multiple tokens such as: are mapped to a single reference. How do I determine which reference token to query? Will there be a single reference shared across multiple tokens? I also noticed mention of including the policy as a key in the datum. Is this because we expect multiple reference tokens from different policies to coexist within the same UTxO? If this proposal assumes multiple reference tokens sharing a UTxO:
One additional point: I am generally not a fan of CIP-68. Across nearly all Cardano indexers we use, both managed and self-hosted, retrieving the latest transaction for a given asset, which is required to locate the UTxO containing the datum, is consistently problematic. It is a slow operation and frequently times out or fails altogether. |
|
Let me try to answer inline below:
The name determines how you query. So there are no changes to the token type (that lives in the actual asset name itself as a prefix). All you are looking up is the metadata of {asset_id}{name} => CDDL
The idea is to share a single datum for space and cost efficiency as all.
It allows for that (similar to how we did it in CIP-0025)
Agree with this.
Good to hear.
Yeah CIP-0068 is controversial, but the rationale here is to save artists developing on the chain from ballooning minUTxO (which often reaches into the many thousands of ADA for mints). |
|
@thaddeusdiamond Thank you for the reply! I feel like your message already mostly implies it, but I'll still ask the following question directly to be 100% I'm not mis-interpreting the purpose of this CIP. Today: Every reference token sits in a dedicated UTxO and the UTxO datum only refers to this (single) token. The CIP proposal: Multiple reference tokens (potentially from multiple policies) can coexist in the same UTxO and share a single datum (containing the metadata for all of them). Am I correct in understanding correctly that this is the core (and only?) proposal made by this CIP? |
|
Yes exactly!
|
|
@thaddeusdiamond really nice to see this proposal moving along into peer review. ⭐ If you're going to keep responding by email to GitHub, please pay attention to how you enter your text (separating by a newline is essential; maybe even a blank line) so the entire quoted email doesn't appear here in the GitHub review stream. 🙏 (otherwise editors have to fit it: e.g. #1112 (comment)) |
haha TIL... Fixed. Sorry about that. |
|
Hi, from Eternl's perspective, I don't see any direct issue with the proposed CIP but I haven't spent much time digging through it either. This will likely first happen at the implementation stage if there are any issues. If I read change and comments correctly, fetching the datum works just like before, its just that the content of the datum can now either be as before with direct metadata, or using the 721 style with policy and name in the data structure? |
That is correct yes. |
|
Ok, then it should be fairly easy to implement I think. |
6 participants
Add version 4 metadata support with 721-ERC-style mappings to NFT (222), FT (333) and RFT (444) standards, ensuring consistency across all asset classes.
Changes: