Solana Token-2022 metadata: from conventions to state

Token-2022 did not introduce new token features. It introduced a new way for tokens to describe themselves.

For most of Solana’s history, SPL Token mints were structurally simple and intentionally rigid. Their layouts were fixed, their semantics minimal, and any additional meaning, metadata, rules, or auxiliary state had to live somewhere else. Metadata was one of the first things to be pushed out, formalized through conventions and external programs such as Metaplex.

That approach solved coordination, but not discoverability.

Nothing in a classic SPL Token mint indicates where its metadata lives. The runtime does not enforce a relationship between a mint and any metadata account. The link exists only because clients, wallets, and programs already know how to derive it.

Token-2022 changes this at the data-model level.

By introducing extensible mint layouts and Type-Length-Value encoded extensions, Token-2022 allows tokens to declare optional semantics directly inside their own accounts. One of the most important of these extensions is the Metadata Pointer: a field stored in the mint itself that explicitly identifies where the token’s metadata can be found.

With this shift, metadata discovery no longer depends on hardcoded derivation rules or mandatory external programs. The mint becomes self-describing, and the relationship between a token and its metadata becomes explicit, inspectable, and forward-compatible.

This post explores why the Metadata Pointer exists, what architectural problems it solves compared to convention-based metadata systems, and how Token-2022 moves Solana tokens from implicit assumptions toward explicit on-chain state.

What is Token-2022

The original SPL Token program was intentionally minimal. A mint defined supply, decimals, and authorities. Token accounts held balances. The layout of both was fixed, and once an account was created, its structure could not evolve.

That simplicity was a strength early on, but it also imposed a hard limit: any new behavior had to live outside the token itself.

As Solana matured, tokens were expected to do more than represent balances. They needed fees, hooks, compliance rules, pausing, interest, metadata, grouping, and custom transfer logic. Since the mint layout could not change, each of these features had to be implemented through separate programs, additional accounts, and ecosystem-level conventions.

Token-2022 was developed to address this structural limitation.

Instead of redefining what a token is, Token-2022 extends how token state can be expressed. It introduces a model where mints and token accounts can include optional, well-scoped extensions alongside their base state.

Extensions as Explicit, Optional State

At the core of Token-2022 is the idea that token behavior should be declared, not inferred. A token mint or token account still has a base layout, the same fundamental fields that existed before. What changes is that this base state can now be followed by a structured region that holds extension data. Each extension contributes a specific piece of state: transfer rules, fee configuration, metadata references, group membership, or other optional behavior.

These extensions are:

• Explicit: their presence is encoded directly in the account data
• Optional: only the features you enable are stored
• Composable: multiple extensions can coexist when compatible
• Forward-compatible: unknown extensions can be safely ignored

Existing Extensions

• TransferFeeConfig: Includes transfer fee rate info and accompanying authorities to withdraw and set the fee
• TransferFeeAmount: Stores transfer fees that have been withheld from token transfers and are pending withdrawal.
• MintCloseAuthority: Adds an optional authority that can permanently close the mint account.
• ConfidentialTransferMint: Configures a mint for confidential transfers, enabling privacy-preserving token movements.
• ConfidentialTransferAccount: Holds per-account state required to participate in confidential transfers.
• DefaultAccountState: Specifies the default state (initialized or frozen) for newly created token accounts.
• ImmutableOwner: Prevents the token account owner authority from ever being changed.
• MemoTransfer: Requires all inbound transfers to include a transaction memo.
• NonTransferable: Marks the mint as non-transferable, preventing tokens from being transferred between accounts.
• InterestBearingConfig: Enables tokens to accrue interest over time based on a configured rate.
• CpiGuard: Restricts privileged token operations from being invoked through cross-program invocations (CPI).
• PermanentDelegate: Assigns a permanent delegate with authority over token operations.
• NonTransferableAccount: Indicates that a token account belongs to a non-transferable mint.
• TransferHook: Requires token transfers to invoke an external program that implements a transfer hook interface.
• TransferHookAccount: Marks a token account as belonging to a mint that enforces transfer hooks.
• ConfidentialTransferFeeConfig: Configures encrypted transfer fees and the public key used for encryption.
• ConfidentialTransferFeeAmount: Stores encrypted transfer fees that have been withheld.
• MetadataPointer: Stores a pointer to another account (or the mint itself) that holds token metadata.
• TokenMetadata: Stores token metadata directly inside the mint account.
• GroupPointer: Stores a pointer to another account that holds token group configuration.
• TokenGroup: Defines group-level configuration for a set of related tokens.
• GroupMemberPointer: Stores a pointer to another account that holds group membership configuration.
• TokenGroupMember: Defines group membership information for a specific token.
• ConfidentialMintBurn: Enables confidential minting and burning of tokens.
• ScaledUiAmount: Applies a scaling factor to the token’s UI amount representation.
• Pausable: Allows minting, burning, and transferring of tokens to be paused.
• PausableAccount: Indicates that a token account belongs to a pausable mint.

Note: In this blog we will talk about MetadataPointer and TokenMetadata

Why Token-2022 Exists

Token-2022 exists because convention does not scale indefinitely.

Under the original model, advanced token behavior relied on shared knowledge:
which extra accounts to look for, which programs to trust, which derivation rules to apply, and which assumptions held in practice. None of this was visible from the mint itself.

Token-2022 shifts that burden into explicit state.

Instead of asking clients and programs to know how a token behaves, the mint can now declare its behavior. Tools can inspect the account, see which extensions are present, and reason about the token without relying on ecosystem-wide conventions or hardcoded assumptions.

Example:

The Metadata Pointer extension that we will learn about in this post is one concrete example of this shift.

It doesn’t invent metadata. It changes how metadata is located from convention-based discovery to explicit declaration inside the mint itself. To understand why that matters, it’s important to first understand Token-2022 as an extensibility framework, not as a collection of features.

With that foundation in place, we can now examine how metadata fits into this model, and why Solana moved from implicit relationships toward explicit, inspectable state.

Example of token creation without metadata attached:

spl-token create-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb --decimals 9

Note: the TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb address the program address of token-2022

Metadata Pointer Extension: Making Metadata Location Explicit

The Metadata Pointer extension is the simplest possible application of Token-2022’s extensibility model. It does not define metadata, It does not interpret metadata, It only answers one question:

Where should metadata for this token be found?

Under the original SPL Token model, the mint does not reference its metadata in any way. Clients are expected to derive the metadata account using well-known seeds and a known program ID. This works only because every participant already knows the rules.

The Metadata Pointer extension removes that assumption.

When enabled, the mint stores a single piece of information: a public key pointing to the account that holds the token’s metadata. That account may be owned by any program, follow any schema, or even be the mint itself.

From an architectural perspective, this is a shift from convention-based discovery to explicit declaration. Programs and tools no longer need to guess where metadata lives. They can read the mint account, inspect its extensions, and discover the metadata location directly from on-chain state.

Importantly, the Metadata Pointer does not enforce correctness. The runtime does not verify that the pointed account actually contains metadata, nor that it conforms to any standard. The pointer only makes the relationship visible and inspectable.

Why it was added

The Metadata Pointer solves a structural problem rather than a functional one.

• It removes hardcoded derivation rules from clients
• It reduces the number of assumptions required to interpret a token
• It allows metadata systems to evolve independently
• It enables metadata to be stored wherever it makes sense for a given use case

Crucially, this does not replace existing metadata programs. A pointer can reference a Metaplex metadata account, a custom metadata account, or any future standard.

Example:

Lets create a new token-2022 and assign it a metadata pointer. You can see how we created a metadata address in the previous blog.

spl-token create-token \                                        
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 9 \
  --metadata-address <METADATA-ADDRESS>

And with this command we can see that the newly created token supports the metadata pointer:

spl-token display <MINT-ADDRESS> \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

The output should look like that:

TokenMetadata Extension: When the Mint Carries the Meaning

Metadata Pointer solves discovery by introducing indirection: the mint declares where metadata lives.

TokenMetadata is the opposite approach.

Instead of pointing somewhere else, the mint can store metadata directly inside its own account data as an extension. There is no separate metadata account to derive, no pointer to resolve, and no external program that must be consulted to retrieve a token’s human-facing fields.

From an architectural perspective, TokenMetadata turns metadata from an ecosystem convention into explicit mint state.

A Token-2022 mint with the TokenMetadata extension can include fields such as:

• name
• symbol
• URI

These are not “runtime fields”. They are still program-defined bytes inside an account. The Solana runtime does not interpret them. But unlike the Metaplex model, the relationship between the token and its metadata is no longer implicit or derived. The metadata is literally part of the mint’s declared state.

What This Enables and What It Trades Off

TokenMetadata optimizes for simplicity and locality:

• One account read to fetch both mint parameters and metadata
• No extra accounts to manage
• No dependency on external derivation rules

But the tradeoff is equally structural:

• Metadata now shares the mint’s lifecycle and authority model
• Schemas must remain conservative because they live inside the mint
• Tooling still needs Token-2022 awareness to decode it

This is not a replacement for richer metadata systems. It’s a native baseline: a minimal on-chain description that can be resolved without conventions.

TokenMetadata vs Metadata Pointer

These two extensions are not redundant. They are complementary primitives:

• MetadataPointer makes metadata discoverable without assuming where it lives.
• TokenMetadata makes metadata local by embedding it directly into the mint.

Token-2022 doesn’t force a single standard. It provides the ability to express both models explicitly.

In practice, you’ll see combinations like:

• Pointer → Metaplex metadata that will provide compatibility with existing ecosystem
• Pointer → custom metadata account application-specific semantics
• Inline TokenMetadata small, native, self-contained metadata

Example

with this next lines it is possible to create a new token-2022 token and enable the TokenMetadata extension:

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 9 \
  --enable-metadata

After that the attachment of the small native metadata looks like that:

spl-token initialize-metadata <MINT-ADDRESS> \                  
  "Example Token" \
  "EXMPL" \                            
  "https://example.com/metadata.json" \                   
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

and the output is:

spl-token display <MINT-ADDRESS> \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb 

Note: When a Token-2022 mint uses inline metadata via the TokenMetadata extension, it will often also include a MetadataPointer extension that points back to the mint itself. This is intentional.

Tooling Reality: Explicit State vs Ecosystem Support

Token-2022 makes token semantics explicit on-chain, but explicit state does not automatically imply universal tooling support. At the protocol level, MetadataPointer and TokenMetadata are just bytes in an account owned by the Token-2022 program. The runtime enforces ownership and access, but it does not interpret extensions, nor does it require clients to understand them.

As a result, much of today’s tooling still treats Token-2022 mints as generic SPL tokens. Explorers may show the correct owning program while omitting extension data entirely. CLI tools can initialize metadata, but often cannot decode or display it back to the user. This is not a contradiction in the design. It is an expected phase of adoption.

Token-2022 intentionally prioritizes backward compatibility. Programs and clients that do not understand extensions must be able to safely ignore them. Full visibility requires extension-aware tooling that explicitly opts into parsing Token-2022’s extensible layouts.

In practice, this means that inspecting metadata pointers or inline metadata often requires programmatic clients rather than generic interfaces.

The important distinction is this:
the data exists, the relationship is explicit, and the semantics are declared on-chain even if the surrounding ecosystem has not yet caught up.

Summary

Token-2022 represents a shift in how token meaning is expressed on Solana.

The original SPL Token model relied heavily on convention. Relationships between a mint and its metadata were not encoded on-chain, but reconstructed by clients that already knew where to look and how to derive it. This worked, but only as long as those assumptions were shared universally. Token-2022 moves those assumptions into explicit state.

By introducing extensible mint layouts, tokens can now declare optional semantics directly inside their own accounts. Extensions such as MetadataPointer and TokenMetadata do not change what metadata is, but they change how it is discovered and interpreted.

• MetadataPointer makes metadata location explicit, replacing convention-based discovery with on-chain declaration.
• TokenMetadata allows small, native metadata to live directly inside the mint, removing indirection entirely. The pointer and is created is simply resolves to the mint itself, unifying discovery regardless of where metadata is stored.

The Solana runtime still does not understand metadata. Nothing is enforced globally. Meaning remains program-defined. What has changed is where that meaning is declared.

Token-2022 does not eliminate ecosystem standards like Metaplex. It makes them optional, inspectable, and composable. Tokens no longer depend on shared off-chain knowledge to describe themselves. They can state their semantics explicitly, in their own on-chain data.

Learn more about Solana architecture from our articles

• Architecture & Parallel Transactions
• Account Model and Transactions
• Anchor Accounts: Seeds, Bumps, PDAs
• Instructions and Messages
• Transaction, Serialization, Signatures, Fees, and Runtime Execution
• SPL Token Program Architecture
• Where token metadata lives on Solana

Reliable Solana RPC infrastructure

Getting started with Solana on Chainstack is fast and straightforward. Developers can deploy a reliable Solana node within seconds through an intuitive Console — no complex setup or hardware management required. 

Chainstack provides low-latency Solana RPC access and real-time gRPC data streaming via Yellowstone Geyser Plugin, ensuring seamless connectivity for building, testing, and scaling DeFi, analytics, and trading applications. With Solana low-latency endpoints powered by global infrastructure, you can achieve lightning-fast response times and consistent performance across regions. 

Start for free, connect your app to a reliable Solana RPC endpoint, and experience how easy it is to build and scale on Solana with Chainstack – one of the best RPC providers.