Token metadata explained, from the account to the image

Where metadata lives

A Solana token's name, symbol and image are not part of the token. Under the original SPL Token program the mint account has room for a supply, a decimals byte, two optional authority fields and an initialised flag, and no room for text at all. Everything a wallet shows comes from a second account, created by the Metaplex Token Metadata program, at an address derived deterministically from the mint.

That separation is the single fact that explains the rest. It is why a token can exist with no name, why two tokens can carry the same ticker, why an image can disappear while the token continues to trade, and why a name can be rewritten after people have already bought it.

The metadata account

The metadata account is a program-derived address. Its seeds are the literal string metadata, the Metaplex Token Metadata program address, and the mint address, hashed together by the runtime into an address with no private key. Because the derivation is deterministic, any interface that knows a mint address can compute where the metadata should be and look there, with no registry and no lookup service in between.

It is created by an explicit instruction, commonly the create-metadata-account instruction in its current version, signed by the mint authority at the time. The payer funds a rent-exempt deposit for it, as with any account. If nobody ever calls that instruction, the derived address simply holds nothing, and the token stays nameless.

The account layout, its versions and its instruction set are documented by the Token Metadata program documentation. Reading the layout is worth ten minutes even for non-developers, because it makes clear how little of what people treat as a token's identity is actually enforced by anything.

The on-chain fields

What is stored on chain is deliberately small. Long text and imagery would be expensive to keep in an account that every reader has to fetch, so the standard stores short identifiers plus a pointer.

Two things in that table are frequently misread. The royalty field is a convention that marketplaces choose to honour, not a rule the token program enforces, so it means nothing on a fungible token being swapped in a pool. And the creators array is only meaningful where an entry is verified, because an unverified entry is just an address somebody typed in.

The off-chain JSON

The URI points at a JSON document, and that document carries the parts too large for an account: a description, the image link, and any extra attributes. It is fetched over HTTP by whatever software is displaying the token, exactly like any other web resource.

A minimal fungible-token document contains a name, a symbol, a description and an image URL, and often an extensions block with project links. The name and symbol in the JSON are expected to match the on-chain values, but nothing enforces that either. When a wallet and an explorer disagree about a token's name, a mismatch between the two layers is the usual cause.

The Token-2022 route

Token-2022 offers a different arrangement. Two extensions work together: a metadata pointer that records where a mint's metadata should be read from, and a token metadata extension that stores the name, symbol, URI and arbitrary additional key-value pairs inside the mint account itself.

The trade-off is support versus simplicity. The in-mint route is cleaner and cheaper to read, and it removes a whole class of mismatch between an account and its pointer. It also depends on the software reading it having been updated for Token-2022, which is documented in the Token-2022 documentation and is not universal. As with every extension, the decision belongs to creation time and cannot be revisited.

Token standards and decimals

The metadata standard carries a token standard field, and the value assigned depends on properties of the mint rather than on anything a creator types. A fungible token with decimals greater than zero and a metadata account is a fungible standard. A token with zero decimals and a supply greater than one is a fungible asset. A token with zero decimals, a supply of exactly one and a revoked mint authority is a non-fungible one.

This matters in practice because interfaces branch on it. A wallet decides whether to show your token in the balances list or in the collectibles list based on this classification, and a marketplace decides whether it is listable at all. A project that picks zero decimals for a token intended to trade as a currency will find it displayed in unexpected places by software behaving exactly as specified.

The relationship between decimals and classification is one more reason the decimals byte deserves a deliberate decision, since it cannot be revised. That decision is worked through with arithmetic on the decimals and supply note.

Who can change what

The update authority on a metadata account is a separate key from the mint authority and the freeze authority. A token can have a revoked mint authority, a revoked freeze authority and a fully live update authority at the same time, and that combination is extremely common.

While the account is mutable and an update authority exists, that key can rewrite the name, the symbol and the URI in a single transaction. Rewriting the URI is the most consequential of the three, because it repoints the whole off-chain document: description, image and links all change at once, everywhere, for everyone, retroactively.

Two irreversible actions close this off. Clearing the mutable flag prevents any further update permanently. Setting the update authority to none has the same effect by removing the signer. Both are one-way, and choosing between leaving them open and closing them is a real trade rather than an obvious one, which is why it has a note of its own on immutable versus updatable metadata.

Why symbols are not unique

There is no registry. The metadata program does not check whether a symbol is already in use, and it could not do so meaningfully, since it would have to arbitrate between competing claims to a string. Any number of mints can carry an identical ticker, and creating one costs a rent deposit and a transaction fee.

The consequence for readers is simple and absolute: a ticker is not an identifier. The mint address is. Wallets and aggregators add verification badges, warning labels and curated lists on top, and those are genuinely useful, but they are layers of judgement applied by third parties rather than properties of the token.

Market tooling has settled on the same convention for the same reason. A router quotes against a mint address, and a volume bot for Solana is pointed at a pair by its address rather than its ticker, because a ticker cannot resolve to one thing. Anything that asks a user to identify a token by symbol alone has moved a real ambiguity onto the user.

Reading a token metadata state

Everything above can be checked from a browser in a couple of minutes, given the mint address. This is the order this workshop uses.

1. Confirm the metadata account exists. An explorer will show it alongside the mint. If it does not exist, the token has no name of its own, whatever an interface may be displaying from a private list.
2. Read the mutable flag. Mutable means the name, symbol and URI can change at any time. This is not a fault, but it is a fact a holder should know.
3. Read the update authority. Note the address and whether it matches the mint authority. A single key holding everything is a different risk profile from a distributed arrangement.
4. Open the URI directly. Fetch the JSON in a browser tab. Check that its name and symbol match the on-chain values and that the image URL actually loads.
5. Check where both URLs are hosted. A permanent storage network and an ordinary web host imply very different lifespans for the same token's appearance.
6. Compare against the mint address you started from. Everything read here hangs off that address, so confirm it is the address you actually intend to trade against.

Metadata over a token lifetime

Metadata is usually treated as a launch task and then forgotten, which is why most of its failures appear months later. Three of them are common enough to plan for, and all three are cheap to prevent while the account is still mutable.

The first is link rot. A JSON document or an image served from ordinary hosting stops resolving when a domain lapses or a bucket is emptied, and the token quietly loses its appearance everywhere at once. Nothing on chain has changed and nothing is broken in the token program; the pointer simply now points at nothing. Content-addressed permanent storage removes this failure entirely, at the cost of making the URI impossible to correct if the content was wrong to begin with.

The second is drift between the two layers. An on-chain name of one thing and an off-chain name of another produces interfaces that disagree, because some read the account and some read the document. It is nearly always an oversight rather than anything meaningful, and it is worth fixing precisely because a reader has no way to tell which of those it is.

The third is authority abandonment. An update authority sitting on a key nobody uses is a power that still exists and that nobody is watching, which is the worst of both arrangements: holders carry the risk that it can be exercised, and the project cannot exercise it because the key is on a machine somebody replaced. Deciding early whether that key will be used, moved to a multisig or removed is a five-minute decision that stops being available once the people involved have moved on.

What this note does not cover

It does not cover design, naming or branding. What a token should be called and what its image should look like are outside the scope of a workshop about accounts, and no field limit implies an aesthetic.

It does not evaluate hosting providers or storage networks. The relevant technical property is whether the URL will still resolve in several years, and that is a question about the specific arrangement rather than about the category.

And it contains nothing about using metadata to resemble another project. Names and symbols are unenforced free text, which is exactly why impersonation is trivial and why this workshop writes only the verification half of the subject: how to establish which mint you are actually looking at, never how to be mistaken for a different one.

Questions the workshop is asked