Extend `TokenMetadata` for the Token Standards

[onurinanc]

This issue aims to extend the TokenMetadata required by Miden Confidential Token Standard. I’m also opening this issue as a response to the metadata section in the this discussion:

In addition, this issue and the related PR are aligned with the direction of the following conversation: #1949 and #1993

For the token standard, TokenMetadata currently covers:

• token_supply: currently circulating tokens
• max supply: maximum cap
• symbol: (12-character ASCII; see Increase max allowed characters in TokenSymbol #2406)
• decimals: since the value is stored as a felt, using 6 decimals is recommended. Higher decimals can make supplies and balances so small that they become impractical

Items to Discuss for the Token Standard:

description:
does not need to be defined as part of the standard.
name:
must be the part of the standard
contract_uri:
In the EIP for confidential fungible token standards, compliant tokens MUST implement contract_uri. In other words, this is not presented as an optional extension, it is part of the standard.

The primary motivation is to provide an additional mechanism for verifying critical public information associated with a token’s identity. From a compliant perspective, this acts as a complementary layer of validation. It is also offered as a standard feature on other chains such as Sui and Solana.

Therefore, contract_uri would be included as a mandatory part of the standard.

Related reference for contract-level metadata in EIPs: https://eips.ethereum.org/EIPS/eip-7572.

name

Length constraints:

• In EVM, name is a String do not enforce a strict character limit
• Solana and Algorand enforce 32-byte limits.
  • In EVM, there are token names exceeding 32 bytes.
• If we choose 32 bytes, we can fit it into one storage slot, but using two storage slots enables a wider character set and longer names.
  • 32 bytes → 1 storage slot (single storage value)
  • 64 bytes → 2 storage slots (a double-word array may be a better fit)

Encoding:

• UTF-8

contract_uri

As noted above, contract_uri should be part of the standard.
Length constraints:

• On EVM, String implies effectively no strict limit.
• Solana uses 200 bytes, Algorand uses 96 bytes of fix contract_uri
• An unbounded URI may increase the DoS surface on Miden, so imposing a limit is reasonable. A practical bound could be 160–200 bytes, which corresponds to roughly 5–7 storage slots.

Encoding:

• UTF-8

Metadata Management

The metadata is controlled by the owner of the network accounts.

The set_contract_uri procedure is not inherently part of the standard and is opinionated. The following options should be considered:

• Do not implement it in the standard and users can implement it themselves if needed.
• Introduce an optional flag:
  • Include a note indicating it is not part of the standard
  • Use an explicit naming convention such as optional_set_contract_uri
  • Use it with an optional flag as a part of the standard

#! Note
#! This procedure is not part of the Miden Confidential Token Standard.
#! It can be enabled optionally via a flag.
pub proc set_contract_uri
    # exec.verify_owner
    # set the new contract_uri
end

[afa7789]

Right now, Miden storage is a bit of a "guessing game." We’re hardcoding indices—manually tracking that a "Logo URI" starts at Index 2 and ends at Index 5. It works for now, but it’s brittle. One "off-by-one" error or a minor schema change, and everything breaks. It also makes it impossible for other contracts to interact with our data without knowing our exact source code.

The fix is a self-describing header at Index 0. Think of it as a "Table of Contents" for the storage slot. It tells the VM exactly what’s inside, how big each field is, and what version of the schema we’re using. By reading this header, we can dynamically calculate offsets instead of hardcoding them.

For an NFT, the layout would look like this:

Index	Field	Size	Role
0	Header	1 dw	The Manifest
1	Owner	1 dw	Identity
2–3	Name	2 dw	Text
4–7	URI	4 dw	Metadata Link

This means no more manual math—we just use get_field(field_id) and let the logic handle the rest. It makes our contracts upgradable via versioning and much easier for other developers to inspect and understand.

double_word_array.masm    ← raw access (bottom layer)
          ▲
          │
storage_struct.masm       ← THE "BRAINS" (new logic)
          ▲
          │
fungible / nft_metadata   ← clean, easy-to-write contracts

[afa7789]

made a prototype with tests to make sure it works:
afa7789#7

@bobbinth maybe we can think about this kind of storage in the future or for other solutions.

[afa7789]

proposed solution #2439

[bobbinth]

Thank you for putting this together! I'm just catching up on this. A few preliminary thoughts/comments:

First, I think we should design this in two ways:

1. How we can implement it now.
2. How we'd update the standard once Add support for multi-value storage slots #2176 is implemented.

The current implementation would be a bit annoying because we'd need to use multiple storage slots for the same logical element - but hopefully, it won't be too bad. From the API standpoint, we should design things to that changing underling storage layout wouldn't cause a breaking change (I think this should be possible).

Miden storage is a bit of a "guessing game." We’re hardcoding indices—manually tracking that a "Logo URI" starts at Index 2 and ends at Index 5.

I didn't quite understand this: we have storage slot names now - so, we shouldn't need to mess around with indexes. But maybe i'm missing something?

---

A few specific comments:

• name - let's go with two storage slots. Technically, it'll be slightly less than 64 bytes, but I don't think this matters too much.
• contract URI - let's go with 6 storage slots - this should be slightly less than 192 bytes. In general, I'm still fuzzy on what this would be used for - do you have an example of a contract URI for some well-known contract?
  • Should we make contract URI optional? I'm assuming if someone doesn't want to specify a contract URI for their token for some reason, they could always put something dummy in - but maybe this should be explicit?
  • A concern we discussed in the past: putting URLs that the user is expected to query into on-chain contracts may lead to security issues. How are you thinking about these? At some point we discussed that it may be better to embed an image for the logo into a storage slot rather than put a link to an image because the latter would require querying of a potentially untrusted URLs.

[onurinanc]

Hi @bobbinth thank you for the comments!, we have implemented here with the current storage slots option: #2439

Related to contract_uri, this is one of best known example for Zama FHEVM Contracts known as ERC7984 standards:
https://github.com/OpenZeppelin/openzeppelin-confidential-contracts/blob/586eb39bfb20fb9af7c936e18e75ce1349f2a1b7/contracts/interfaces/IERC7984.sol#L37

There are some details here, too: https://eips.ethereum.org/EIPS/eip-7572

Should we make contract URI optional? I'm assuming if someone doesn't want to specify a contract URI for their token for some reason, they could always put something dummy in - but maybe this should be explicit?

Yes, anyone could put something dummy in that case. The reason why we're having this non-optional is that we're putting standards, and as a standard, we recommend using it. And, we know also have optional_set_content_uri procedure to make it mutable in that case.

What I suggest is for now, we choose either optional or non-optional (Currently, we have implemented this as non-optional). Once the token standards is audited, we can have a special note for security researches to look at it more deeply and choose one of the optional/non-optional accordingly. For now, as you specified, it is not explicit but anyone can put a dummy variable, too. We can make it explicit once this is audited. What do you think?

[bobbinth]

Related to contract_uri, this is one of best known example for Zama FHEVM Contracts known as ERC7984 standards:
https://github.com/OpenZeppelin/openzeppelin-confidential-contracts/blob/586eb39bfb20fb9af7c936e18e75ce1349f2a1b7/contracts/interfaces/IERC7984.sol#L37

Are there examples of URIs that are actually being used by contracts? For example, what response would be returned from USDC or some other live contract that specifies contractURI?

What I suggest is for now, we choose either optional or non-optional (Currently, we have implemented this as non-optional). Once the token standards is audited, we can have a special note for security researches to look at it more deeply and choose one of the optional/non-optional accordingly. For now, as you specified, it is not explicit but anyone can put a dummy variable, too. We can make it explicit once this is audited. What do you think?

I would probably go with the optional approach. But I do want to clarify: is the main reason for including contractURI is to avoid putting the data that is supposed to be contained in the response on-chain? Basically, why not just put the actual contents below into the account storage:

{
  "name": "Example Contract",
  "symbol": "EC",
  "description": "Your description here",
  "image": "ipfs://QmTNgv3jx2HHfBjQX9RnKtxj2xv2xQCtbDXoRi5rJ3a46e",
  "banner_image": "ipfs://QmdChMVnMSq4U7oVKhud7wUSEZGnwuMuTY5rUQx57Ayp6H",
  "featured_image": "ipfs://QmS9m6e1E1NfioMM8dy1WMZNN2FRh2WDjeqJFWextqXCT8",
  "external_link": "https://project-website.com",
  "collaborators": ["0x388C818CA8B9251b393131C08a736A67ccB19297"]
}

(name and symbol are already there)

[onurinanc]

Thank you @bobbinth for your questions.

Are there examples of URIs that are actually being used by contracts? For example, what response would be returned from USDC or some other live contract that specifies contractURI?

Actually, I haven't found some examples related to it.

I would probably go with the optional approach.

That makes sense. Instead of having dummy variable and make it a standard for every user, making it optional seems like a more reasonable approach, basically, we'll be providing conractURI as an optional.

But I do want to clarify: is the main reason for including contractURI is to avoid putting the data that is supposed to be contained in the response on-chain? Basically, why not just put the actual contents below into the account storage:

The first reason is that I believe it is easier to update the information. Secondly, using account storage is more expensive. We basically need 25-30 storage slots instead of having 6 storage slots.

Additionally, I would like to approach this problem for two different use cases.
1. Confidential Fungible Token Standard
As we are mostly agree on having the contentURI as an optional metadata extension, it seems more reasonable to keep contractURI as 6 storage slots.

2. Confidential NFTs

{
 "name": "Example Contract",
 "symbol": "EC",
 "description": "Your description here",
 "image": "ipfs://QmTNgv3jx2HHfBjQX9RnKtxj2xv2xQCtbDXoRi5rJ3a46e",
 "banner_image": "ipfs://QmdChMVnMSq4U7oVKhud7wUSEZGnwuMuTY5rUQx57Ayp6H",
 "featured_image": "ipfs://QmS9m6e1E1NfioMM8dy1WMZNN2FRh2WDjeqJFWextqXCT8",
 "external_link": "https://project-website.com",
 "collaborators": ["0x388C818CA8B9251b393131C08a736A67ccB19297"]
}

I'll be opening a separate issue to discuss whether we keep this data on-chain/off-chain in the context of NFTs.

[bobbinth]

The first reason is that I believe it is easier to update the information. Secondly, using account storage is more expensive. We basically need 25-30 storage slots instead of having 6 storage slots.

I actually don't mind if tokens take up a bit more storage. Regarding updatability - is that a desired property? I guess things like external_link and collaborators should be easily updatable - but the rest should probably be pretty static.

This also brings me to a question: what happens if the on-chain and off-chain data diverges? For example, we have name and symbol in the account storage and if it is also returned from contentURI, we could have a situation where, for example, on-chain symbol is different from the off-chain symbol.

As we are mostly agree on having the contentURI as an optional metadata extension, it seems more reasonable to keep contractURI as 6 storage slots.

I think having it as optional is definitely better than non-optional, but it is still an open question for me whether this is the best approach. Specifically, if we do have it, we need to make sure we answer the following questions:

1. Do we want the data returned from contentURI to be static or dynamic? If static, we should probably add a commitment to the storage - but based on the above discussion, I think we want it to be dynamic.
2. If the data is dynamic, how do we reconcile potential conflicts between on-chain and off-chain data. One simple solution would be to remove the duplication - e.g., name and symbol fields should not be in the contentUri response.
3. Do we actually need banner_image and featured_image in the response? Would be helpful to see how these are used by someone.
4. It is also not clear what value the collaborators field brings. Unless we want these to be cryptographically signed somehow? (i.e., if there is a collaborator listed, we know for sure that the owner consented to being listed in the list of collaborators).

But then, if we remove the fields I mentioned above, we end up with the response that looks like so:

{
  "description": "Your description here",
  "image": "ipfs://QmTNgv3jx2HHfBjQX9RnKtxj2xv2xQCtbDXoRi5rJ3a46e",
  "external_link": "https://project-website.com",
}

And this could probably easily go into the storage of the account.

[onurinanc]

Before answering the questions, I want to step back and revisit the contractURI design we’ve proposed:

• contractURI is an optional field.
• contractURI has immutable and mutable flag options, so the user can choose whether contractURI should be updateable or not.
• to support mutability, set_contract_URI procedure will be added, and this procedure only works if the mutable flag is selected. If the immutable option is chosen, the procedure becomes effectively disabled and contractURI cannot be updated.

With this design, we give users the following options:

• An optional contractURI extension for Confidential Fungible Tokens.
• The ability to optionally make contractURI updatable, depending on their preference.

So, I believe this pretty much covers every option related to contractURI

I think the link I have shared above ended up being a bit confusing, because it includes data that’s more relevant for NFTs, whereas the scope of this issue should focus on fungible tokens.

With this design in mind, I’ll address your questions one by one:

I actually don't mind if tokens take up a bit more storage. Regarding updatability - is that a desired property? I guess things like external_link and collaborators should be easily updatable - but the rest should probably be pretty static.

With the above design, we provide updatability if desired with a contentURI extension. (collaborators is not desired for fungible token standards, and external_link can be provided in the contractURI as desired)

This also brings me to a question: what happens if the on-chain and off-chain data diverges? For example, we have name and symbol in the account storage and if it is also returned from contentURI, we could have a situation where, for example, on-chain symbol is different from the off-chain symbol.

I still think the link is confusing in this context. We shouldn't adopt that JSON schema as part of our Confidential Fungible Token Standard. Specifically, we don’t need to return name and symbol in a JSON response, because as part of the Miden Confidential Token Standard we already provide name and symbol. If we were recommending applications to follow that JSON schema, then potential conflicts would matter, and the document seems to mark using the name and symbol returned by the JSON as “RECOMMENDED” in case of a mismatch. But that’s not the direction we want to take. (1)

1. Do we want the data returned from contentURI to be static or dynamic? If static, we should probably add a commitment to the storage - but based on the above discussion, I think we want it to be dynamic.

We leave the decision to the user by introducing optional "mutable" and "immutable" flags.

As part of the standard, we also expose get_contract_uri_mutable, which returns whether contractURI is configured as mutable or immutable. So, in the “static” case, we don’t need to add a separate commitment, the user can determine whether it’s meant to be static or dynamic by calling this procedure.

Within the contractURI extension, we recommend defining contractURI as immutable by default, choosing the mutable option is intentionally left as a user decision.

2. If the data is dynamic, how do we reconcile potential conflicts between on-chain and off-chain data. One simple solution would be to remove the duplication - e.g., name and symbol fields should not be in the contentUri response.
3. Do we actually need banner_image and featured_image in the response? Would be helpful to see how these are used by someone.
4. It is also not clear what value the collaborators field brings. Unless we want these to be cryptographically signed somehow? (i.e., if there is a collaborator listed, we know for sure that the owner consented to being listed in the list of collaborators).

We don't need them, and I believe this is addressed in (1).

But then, if we remove the fields I mentioned above, we end up with the response that looks like so:
{
"description": "Your description here",
"image": "ipfs://QmTNgv3jx2HHfBjQX9RnKtxj2xv2xQCtbDXoRi5rJ3a46e",
"external_link": "https://project-website.com",
}
And this could probably easily go into the storage of the account.

So, I believe that we don't need separate image and external_link here as contractURI can have both of these fields, or more than these fields as desired by the account creator. I don't think having an image field should be the part of the standard.

"description": "Your description here"

I believe description shouldn't be part of the standard but as an optional field if desired, and should be immutable similar to name and symbol. I also think that description field shouldn't be implemented by us but anyone who desire should be able to fork it and add a description field. The main reason is that description doesn’t have a clear, standardizable constraint in the same way name or symbol does. It can be essentially arbitrary text, and we can’t reliably define what an appropriate size limit should be.

A description might be 64 bytes, it could just as easily be 192 bytes, 512 bytes, or even larger. Because of this variability, description should not be part of the standard itself. It should remain a user choice (even it might be provided via contractURI), rather than a required standardized on-chain field.

To summarize, I still believe the design I outlined above should remain the direction we follow. In fact, I’m a bit less convinced by making contractURI optional. Even if a user doesn’t want to use contractURI, they can always provide a dummy value. But for any user who needs to provide more information, contractURI provides a lot of flexibility by allowing the user to populate whatever metadata they need.

[bobbinth]

So, I believe that we don't need separate image and external_link here as contractURI can have both of these fields, or more than these fields as desired by the account creator. I don't think having an image field should be the part of the standard.

Maybe I'm missing something, but if we include contractURI (whether optional or not) in the standard, we should also specify the schema for the data that should be returned from this URI. What would this schema be for fungible tokens? Is it basically just description and image?

[onurinanc]

Thank you @bobbinth for the comments.

Yes, if we include contractURI, then we really do need to provide a schema for the response. But if we directly adopt the schema from that standard (EIP-7572), it becomes a bit unnecessary for fungible tokens. And defining a whole schema just for description, image, and external_link also feels unreasonable.

So for fungible tokens, the most sensible route seems to be:
Instead of standardizing contractURI for fungible tokens, we can provide on-chain optional fields as a metadata extension. Then, wallets or apps can rely on-chain fields rather than guessing what a contractURI JSON might contain.

For a fungible token, the optional fields that could be useful would be:

• logo_uri: 6 storage slots (~192 bytes)
• description: we can allocate 6 storage slots (similar to logo_uri since 2 storage slots (~64 bytes) feels too small for a description

Since these are optional and we already provide UTF-8 data with 6 slots, we could also add the following if it is also desired in addition to logo_uri

• external_link: 6 storage slots (~192 bytes)

We also add optional mutable & immutable flags for logo_uri, and state that immutable is recommended by default from a security perspective.

“It may be better to embed an image for the logo into a storage slot rather than put a link to an image, because the latter would require querying potentially untrusted URLs.”

I agree this is a valid point. However, wallets can mitigate the risk of untrusted fetching by applying standard safeguards when retrieving metadata. If we consider to add 2KB limit for a logo_uri , we already need to add an image field for NFTs, even a 2 MB image would require roughly ~65k storage slots, which introduce complexity to implement and inefficiency.

So, my suggestion remains for fungible tokens:

• optional on-chain description and logo_uri (and optionally external_link)
• recommend immutable by default with an explicit mutable option.
• the owner as an access control mechanism responsible for administrative operations such as setting a new logo_uri when mutable

[bobbinth]

So, my suggestion remains for fungible tokens:

• optional on-chain description and logo_uri (and optionally external_link)
• recommend immutable by default with an explicit mutable option.
• the owner as an access control mechanism responsible for administrative operations such as setting a new logo_uri when mutable

Largely agree with these. A few comments:

• I think having name, description, logo_uri, and external_link as additional metadata fields in the account makes sense.
• I don't think we can support "optional" storage slots (cc @PhilippGackstatter or @mmagician in case I'm off here) - so, all of these would need to be present in the account - but I think that's fine. We could probably have a config field which indicates whether each of these elements is present and/or mutable.