Soroban Token Metadata Storage

[leighmcculloch]

SEP-41 intentionally doesn’t define how a token contract stores its state. In practice, though, most token contracts write their name, symbol, and decimals into instance storage in one of two well-known formats, and indexers, explorers, and ETLs have come to depend on reading them from there rather than running a Soroban host to simulate the getters.

From data that @sydneynotthecity shared, of the 1,587 Wasm token contracts on mainnet in October 2026, 89.7% use one of these formats.

Given the dependence of data products on reading this information it seems valuable to standardize the storage of meta for data products, with little disadvantage given the static nature of this information.

This SEP captures the existing practices:

• Key: Either:
  • Symbol("METADATA") first seen in the Stellar Asset Contract and soroban-token-sdk
  • Vec([Symbol("Meta")]) first seen in the OpenZeppelin Stellar Contracts library
• Value: a map with name, symbol, and decimal (or decimals).

It doesn’t change SEP-41, and doesn’t replace the requirement for tokens to implement decimals(), name(), and symbol().

Draft: https://github.com/stellar/stellar-protocol/blob/sep-token-metadata-storage/ecosystem/sep_tokenmetadatastorage.md

The developer docs already push developer in this direction too:

• https://developers.stellar.org/docs/tokens/token-interface#metadata

Note that those docs provide a looser definition, allowing the metadata to exist under any key. The proposed SEP does not recommend this due to the implications discussed in the security section of the proposal.

Why now? To encourage more tokens being developed to follow a consistent pattern, to avoid more cases like stellar/stellar-dbt-public#346.

Wdyt @sydneynotthecity?

[tupui]

Should this also define a token_metadata function? I am trying to think how to also use this for SEP-50.

[fazzatti]

@tupui I really like having a SEP focused on storage that complements the interface SEPs. I’d keep functions out of this one and focus on making the keys and data predictable for anyone reading storage directly. I can see this approach being useful beyond token metadata too.

For SEP-50, could we have a small set of shared required fields, plus fields that depend on the token type? name and symbol work for both fungible tokens and NFT collections. decimals would be required for fungible tokens, but wouldn’t apply to SEP-50 NFTs.

With NFTs, the term “metadata” can also mean information about the collection or about an individual token, so I think it would help to clarify which we’re covering here. While name and symbol fit this shared entry, other properties like URIs, images, and attributes could have their own storage convention.

Also perhaps, we could explicitly allow extra fields and have readers ignore ones they don’t recognize. That would keep this small while leaving room for other SEPs to build on it.

Update: After giving this a bit more thought, I’d perhaps lean more toward keeping this SEP focused on fungible tokens for now. Accommodating NFTs could introduce more variations than we need here. Perhaps it’s better to keep this simple and let NFT metadata storage have its own SEP if there’s demand for it, using this proposal as a starting point.

[tupui]

I agree with the above. The one thing I would bring from SEP-50 is the token_uri. That fits well IMO with the stellar.toml which we could serve from here. Then in SEP-50 we can easily extend the draft with the extension on the storage.

[leighmcculloch]

token_metadata function?

I’d keep functions out of this one

+1 Going to leave function out. This draft aims to capture existing behaviours. If we add fns, then it's something new that no one yet implements.

[vendrell46]

Two cases the reader side still has to guess at. If a token has both keys, or one map with both decimal and decimals holding different values, the draft says a token should have one but not what a reader does on finding both, so two indexers can pick differently and show different decimals for the same token. A line saying readers treat that as non-conforming and fall back to simulating the getters would keep them consistent.

The values are also static by convention only. Any function in the contract can call instance().set on that key again, and a Wasm update can install code that does. An indexer that caches the first read keeps the old name and symbol, and a token renaming itself after it gets listed is an easy spoofing path. Worth adding to Security Concerns that readers should pick up changes to the instance entry rather than cache it.

[leighmcculloch]

👍🏻 I've updated the draft to address both of these. diff

[vendrell46]

Thanks, both read well. One addition to "Metadata can change": it names a stale name and symbol, but decimals can change the same way, and a reader that cached the first value would then scale every amount by the wrong power of ten. Worth naming decimals there too.

[orbitlens]

Our SEP41 parser reads the data from Symbol("METADATA"). When parsing contracts from the ledger stream, it's impossible to resolve the data from the contract invocation simulation directly. This can be done as a post-processing step, but requires mass RPC invocations and additional tooling.

Also, when reading through the functions like decimals(), we are actually invoking the method of the current version of the contract. The contract might have been updated several times, and there is no guarantee that token name or decimals haven't been changed during updates.

[vendrell46]

Good point, and it rules out the fallback I suggested for anyone reading the ledger stream. The rule for a token with both keys, or with both decimal and decimals, then has to work from storage alone. A fixed order (say METADATA before Meta, decimal before decimals) or treating the decimals as unknown would both keep readers consistent; unknown is the safer of the two, since that token is already non-conforming.

On updates, storage is the better record of history anyway. The instance entry also holds the contract's Wasm hash, so that one entry changes on both a metadata rewrite and a code update, and its value at a given ledger is what the token stored at that point. Simulating decimals() only tells you what today's code returns.

[leighmcculloch]

👍🏻 I've added a note about the security concern of the data being updated or diverging from the functions to the draft. diff