Token Metadata extension to form standard by afa7789 · Pull Request #2439 · 0xMiden/protocol

afa7789 · 2026-02-12T19:43:16Z

Unified metadata: One place for account/faucet metadata: token (symbol, decimals, max_supply), owner, name, and content URI. Slot names live under miden::standards::metadata::* (and ownable for owner).

Layout: Token metadata and owner in slots 0–1; name in 2 words (name_0, name_1); content URI in 6 words (content_uri_0..5). Same layout in Rust and MASM.

Faucets: Basic and network fungible faucets support optional name and content URI; both re-export metadata getters (get_name, get_content_uri, get_token_metadata, get_max_supply, get_decimals, get_token_symbol; network also get_owner).

Standalone Info: Non-faucet accounts can use the metadata Info component (name + content URI) for future use (e.g. NFTs).

Testing: Unit tests in miden-standards (metadata storage, recovery); integration tests in miden-testing (MASM getters, faucet + metadata).

crates/miden-standards/src/account/faucets/basic_fungible.rs

onurinanc · 2026-02-17T10:15:13Z

@afa7789 In the context of token metadata discussion #2423 : Let's keep the contractURI as optional.

Basically, instead of:

 name: Option<TokenName>,
 contract_uri: Option<TokenContractURI>

We need to have:

 name: TokenName,
 contract_uri: Option<TokenContractURI>

onurinanc · 2026-02-17T10:25:44Z

We should also consider adding the corresponding metadata and the new constructor to the network fungible faucets: https://github.com/afa7789/miden-base/blob/f7426116833b1f76da3195738ccb838a52880f80/crates/miden-standards/src/account/faucets/network_fungible.rs#L93-L101

onurinanc · 2026-02-17T13:33:18Z

@afa7789 we should also add a flag and procedure to change max_supply. It's basically similar to have we have done in optional_set_contract_uri

afa7789 · 2026-02-17T13:39:50Z

@afa7789 we should also add a flag and procedure to change max_supply. It's basically similar to have we have done in optional_set_contract_uri

In this branch ? pr ?

onurinanc · 2026-02-17T13:51:47Z

@afa7789 we should also add a flag and procedure to change max_supply. It's basically similar to have we have done in optional_set_contract_uri

In this branch ? pr ?

Yes, it would be better if you can have this in this PR.

afa7789 · 2026-02-19T00:26:04Z

@bobbinth @mmagician this is ready for review :)

bobbinth

Not a review - but I left a couple of comments inline. The main one is about how we can handle returning large amounts of data from account interface procedures.

crates/miden-standards/asm/standards/metadata/fungible.masm

onurinanc · 2026-02-26T10:35:27Z

@afa7789 Additionally, as this discussion #2423 (comment) has been concluded, you can update the PR with the following:

name (mandatory): up to 2 words, ~64 bytes (UTF-8)
description (optional): up to 6 words, ~192 bytes (UTF-8)
logo_uri (optional): up to 6 words, ~192 bytes (UTF-8)
external_link (optional): up to 6 words, ~192 bytes (UTF-8)

For description, logo_uri, and external_link:

configuration flags will be introduced to indicate whether the account was initialized with these fields.
mutable/immutable flags will also be added for these fields. (similar to how you did in content_uri)

crates/miden-standards/src/account/faucets/token_metadata.rs

crates/miden-standards/src/account/metadata/mod.rs

PhilippGackstatter · 2026-02-27T16:15:41Z

crates/miden-standards/src/account/metadata/mod.rs

+/// - Slot 12–17: logo_uri (6 Words)
+/// - Slot 18–23: external_link (6 Words)
+#[derive(Debug, Clone, Default)]
+pub struct Info {


Why is this not part of TokenMetadata directly?

It feels very closely related, so I would consider including it. Making it a separate component means users always need to remember to include it in their account next to TokenMetadata and need to decode both TokenMetadata and Info to get all the related data, so this pushes some complexity up the stack.

It would also be nice if we could set mutability flags directly via the mentioned TokenMetadataBuilder, e.g. TokenMetadataBuilder::new(...).description("abc").mutable_description().build().

Related, I think Info does not be an AccountComponent, since it does not have any code. This suggests it is a set of standard storage slots but not a full account component (a combination of functionality / code and storage). So in the same way as TokenMetadata is not an account component (but more like a standardized storage slot), we could make Info a reusable set of storage slots. I would then include it in TokenMetadata, which in turn is included in BasicFungibleFaucet (a proper account component). Notably, this does not prevent reusing Info for other purposes in the future (such as for NFTs).

Naming: I think this is more aptly described as TokenMetadata. This is more generic metadata than what is currently called TokenMetadata which is specific to fungible assets. So maybe it is better to rename the current TokenMetadata to FungibleTokenMetadata to free up that name for this.

crates/miden-standards/src/account/metadata/mod.rs

afa7789 · 2026-03-02T15:52:34Z

@PhilippGackstatter I did most of the mentioned things.
The exceptions are the Builder pattern and Generalized encoding, which will be left for the future.

crates/miden-standards/src/account/faucets/network_fungible.rs

crates/miden-standards/src/account/faucets/basic_fungible.rs

afa7789 · 2026-03-21T20:46:15Z

I rolled back the agglayer code and left a residue of TokenMetadata as before to try and touch it as little as possible. We can them in a future PR adapt it.

To make easier reviewing this, since it's too big, we can close this or rebase this if needed.
If closing it I would of course open a new branch with the files.

…okenMetadata

PhilippGackstatter

Thanks for the updates!

I left a few more comments, but am still in the process of getting through everything.

PhilippGackstatter · 2026-03-24T12:31:42Z

crates/miden-standards/asm/standards/faucets/mod.masm

-const METADATA_SLOT=word("miden::standards::fungible_faucets::metadata")
+# Note: this slot name should match TOKEN_METADATA_SLOT in metadata/fungible_faucet.masm.
+const METADATA_SLOT=word("miden::standards::metadata::fungible_faucet::token_metadata")


We should be able to remove this, make the slot in crates/miden-standards/asm/standards/metadata/fungible_faucet.masm public and then import it here.

crates/miden-standards/asm/standards/metadata/fungible_faucet.masm

crates/miden-standards/src/account/faucets/mod.rs

crates/miden-standards/src/account/metadata/token_metadata/fungible_token/mod.rs

PhilippGackstatter · 2026-03-24T13:41:14Z

crates/miden-standards/src/account/metadata/token_metadata/fungible_token/mod.rs

+        if max_supply.as_canonical_u64() > FungibleAsset::MAX_AMOUNT {
+            return Err(FungibleFaucetError::MaxSupplyTooLarge {
+                actual: max_supply.as_canonical_u64(),
+                max: FungibleAsset::MAX_AMOUNT,
+            });
+        }
+        if token_supply.as_canonical_u64() > max_supply.as_canonical_u64() {
+            return Err(FungibleFaucetError::TokenSupplyExceedsMaxSupply {


We now have new_validated, could we now call it here instead of reimplementing the checks?

Self::new_validated( symbol, decimals, max_supply, token_supply, metadata.name.ok_or_else(todo!()), metadata.description, metadata.logo_uri, metadata.external_link, );

crates/miden-standards/src/account/metadata/token_metadata/fungible_token/mod.rs

crates/miden-standards/asm/standards/metadata/fungible_faucet.masm

…ble tokens

PhilippGackstatter

I think the last merge commit broke a few things like removing some comments in faucets/mod.masm and deleting most of the changelog. Might be best to remove this commit and re-do the merge.

I left a few more comments to simplify the encoding/decoding logic and some structural comments, but overall I think we can soon merge.

I have yet to take a look at most the tests, though.

crates/miden-standards/asm/standards/faucets/mod.masm

crates/miden-standards/src/account/metadata/token_metadata/fungible_token/mod.rs

crates/miden-standards/src/account/metadata/token_metadata/mod.rs

PhilippGackstatter

I left a few comments to remove duplicate tests or using more concise setups. Tests look good overall, thank you for setting them up in a well-structured way!

The size of the PR and the number of reviews made it tricky to keep track, so I'm not convinced I reviewed every single detail of the PR, but I think it can be merged, and so I'll approve it.

crates/miden-standards/src/account/metadata/token_metadata/fungible_token/builder.rs

crates/miden-testing/src/standards/token_metadata.rs

afa7789 · 2026-03-30T10:47:24Z

Okay, @PhilippGackstatter , I will implement this changes above as soon as possible. :)

Move max_supply validation and Felt conversion into new_validated so the check lives in exactly one place. Builder token_supply field is now u64 for API consistency, removing the Felt::new() with SAFETY comment.

Replace silent fallback to empty TokenName with ? operator so test failures surface the actual error instead of hiding it.

Use FungibleTokenMetadata::try_from(storage) to verify stored values instead of raw Felt::new comparisons on individual storage word elements.

Remove basic_faucet_name_readable_from_masm and network_faucet_name_readable_from_masm which are functionally equivalent to get_name_from_masm.

Already covered by basic_faucet_with_max_name_and_full_description which builds an account with a 32-byte name and verifies storage round-trip.

Delete name_33_bytes_rejected (already covered by token_name_too_long) and description_7_words_full_capacity from integration tests. Add description_7_words_full_capacity as a pure unit test in miden-standards using into_storage_slots() instead of building a full Account.

Replace manual Vec of cases with rstest #[case] attributes using build_faucet_metadata() + with_*_mutable() for conciseness. No content fields needed since these tests only check the flag bit.

Remove .add_note_script() from owner-succeeds test since notes already have code via .code(). Simplify non-owner-fails test by removing hash push and advice_map since the auth check fires before data is touched.

Change token name from "POL" (3 bytes, single word chunk) to "Polygon Token" (13 bytes) so both name_chunk_0 and name_chunk_1 are non-zero, exercising both storage slots.

The push.0 padding between successive call-convention getter invocations was unnecessary — call already pads the stack to 16 elements. Verified the test passes without them.

…er_fails test

afa7789 · 2026-03-30T21:36:30Z

@PhilippGackstatter , you can do a last check before we merge I think so.

PhilippGackstatter

Updates look great, thank you!

afa7789 mentioned this pull request Feb 12, 2026

Extend TokenMetadata for the Token Standards #2423

Open

afa7789 marked this pull request as ready for review February 12, 2026 20:12

onurinanc reviewed Feb 13, 2026

View reviewed changes

crates/miden-standards/src/account/faucets/basic_fungible.rs Outdated Show resolved Hide resolved

afa7789 force-pushed the oz/metadata_extension branch 2 times, most recently from 55282e1 to b1dba96 Compare February 14, 2026 12:48

onurinanc reviewed Feb 15, 2026

View reviewed changes

crates/miden-standards/src/account/faucets/basic_fungible.rs Outdated Show resolved Hide resolved

afa7789 changed the title ~~Oz/metadata extension~~ Token Metadata extension to form standard. Feb 19, 2026

afa7789 mentioned this pull request Feb 19, 2026

Unlimited and timed fungible faucets ( supply related ) #2459

Closed

mmagician added the pr-from-maintainers PRs that come from internal contributors or integration partners. They should be given priority label Feb 19, 2026

bobbinth reviewed Feb 26, 2026

View reviewed changes

crates/miden-standards/asm/standards/metadata/fungible.masm Outdated Show resolved Hide resolved

crates/miden-standards/asm/standards/metadata/fungible.masm Outdated Show resolved Hide resolved

afa7789 force-pushed the oz/metadata_extension branch 2 times, most recently from 5548bd5 to 609b355 Compare February 26, 2026 14:43

PhilippGackstatter reviewed Feb 27, 2026

View reviewed changes

crates/miden-standards/src/account/metadata/mod.rs Outdated Show resolved Hide resolved

afa7789 force-pushed the oz/metadata_extension branch 3 times, most recently from ebcbd2e to 671a9dc Compare March 5, 2026 04:05

onurinanc reviewed Mar 5, 2026

View reviewed changes

crates/miden-standards/src/account/faucets/network_fungible.rs Outdated Show resolved Hide resolved

onurinanc reviewed Mar 5, 2026

View reviewed changes

crates/miden-standards/src/account/faucets/basic_fungible.rs Outdated Show resolved Hide resolved

afa7789 force-pushed the oz/metadata_extension branch from ecf267b to 2e50884 Compare March 5, 2026 14:17

afa7789 added 2 commits March 5, 2026 17:54

Refactor code structure for improved readability and maintainability

40e538c

fix: fixing after rebase.

728e145

refactor: update slot name for token metadata to align with FungibleT…

6255a66

…okenMetadata

PhilippGackstatter reviewed Mar 24, 2026

View reviewed changes

This was referenced Mar 24, 2026

Rename TokenSymbol to Symbol #2683

Open

Rename Felt::new to indicate it is unsafe 0xMiden/crypto#914

Open

afa7789 added 2 commits March 25, 2026 11:31

refactor: update token metadata handling and error messages for fungi…

8905d37

…ble tokens

Merge branch 'next' into oz/metadata_extension

a514ec3

PhilippGackstatter reviewed Mar 26, 2026

View reviewed changes

refactor: enhance fungible token metadata handling and validation logic

daafb4d

PhilippGackstatter approved these changes Mar 30, 2026

View reviewed changes

afa7789 added 15 commits March 30, 2026 11:17

refactor: change new_validated + builder to accept u64 for supply fields

e80eb1f

Move max_supply validation and Felt conversion into new_validated so the check lives in exactly one place. Builder token_supply field is now u64 for API consistency, removing the Felt::new() with SAFETY comment.

fix: propagate TokenName errors in network_faucet_metadata helper

5135e47

Replace silent fallback to empty TokenName with ? operator so test failures surface the actual error instead of hiding it.

refactor: replace Felt::new assertions with try_from storage roundtrip

2c10b10

Use FungibleTokenMetadata::try_from(storage) to verify stored values instead of raw Felt::new comparisons on individual storage word elements.

test: remove duplicate MASM name readback tests

a4a3232

Remove basic_faucet_name_readable_from_masm and network_faucet_name_readable_from_masm which are functionally equivalent to get_name_from_masm.

test: remove name_32_bytes_accepted duplicate test

3bbd04d

Already covered by basic_faucet_with_max_name_and_full_description which builds an account with a 32-byte name and verifies storage round-trip.

refactor: convert is_field_mutable_checks to rstest parametrized test

c1c01cf

Replace manual Vec of cases with rstest #[case] attributes using build_faucet_metadata() + with_*_mutable() for conciseness. No content fields needed since these tests only check the flag bit.

refactor: simplify field setter test scripts

c4bae86

Remove .add_note_script() from owner-succeeds test since notes already have code via .code(). Simplify non-owner-fails test by removing hash push and advice_map since the auth check fires before data is touched.

test: use multi-word token name in build_pol_faucet_metadata

5bf26a3

Change token name from "POL" (3 bytes, single word chunk) to "Polygon Token" (13 bytes) so both name_chunk_0 and name_chunk_1 are non-zero, exercising both storage slots.

test: remove unnecessary push.0 between getter calls

a787be9

The push.0 padding between successive call-convention getter invocations was unnecessary — call already pads the stack to 16 elements. Verified the test passes without them.

Merge remote-tracking branch 'upstream/next' into oz/metadata_extension

fa8bf94

refactor: remove unused import and redundant note script compilation

a038bfb

refactor: remove unused note script compilation from max supply tests

8b1d7e5

refactor: simplify hash handling in test_field_setter_owner_succeeds

e816b49

refactor: simplify note script code in set_max_supply_mutable_non_own…

3324137

…er_fails test

afa7789 requested a review from onurinanc March 30, 2026 22:23

PhilippGackstatter approved these changes Mar 31, 2026

View reviewed changes

PhilippGackstatter requested a review from bobbinth March 31, 2026 15:33

Conversation

afa7789 commented Feb 12, 2026

Uh oh!

Uh oh!

Uh oh!

onurinanc commented Feb 17, 2026

Uh oh!

onurinanc commented Feb 17, 2026

Uh oh!

onurinanc commented Feb 17, 2026

Uh oh!

afa7789 commented Feb 17, 2026

Uh oh!

onurinanc commented Feb 17, 2026

Uh oh!

afa7789 commented Feb 19, 2026

Uh oh!

bobbinth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

onurinanc commented Feb 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PhilippGackstatter Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

afa7789 commented Mar 2, 2026

Uh oh!

Uh oh!

Uh oh!

afa7789 commented Mar 21, 2026

Uh oh!

PhilippGackstatter left a comment

Choose a reason for hiding this comment

Uh oh!

PhilippGackstatter Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PhilippGackstatter Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PhilippGackstatter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PhilippGackstatter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!