5 Token-2022 Mistakes I Made So You Don't Have To

I spent two weeks building with Solana's Token-2022 program. I created fungible tokens, attached transfer fees, stacked interest on top, built

soulbound credentials, and minted NFTs with on-chain metadata. Every one of those features worked — eventually. But before "eventually," each one had a moment where my output was wrong, my transaction failed, or my wallet balance moved in a direction I didn't expect.

This post is about those moments. Not the happy path. The five mistakes

that cost me the most time, and exactly what I had to understand to fix

them.

If you're coming from Web2 and you're curious about Solana tokens, this

is the post I wish I'd had.

A Quick Mental Model Before We Start

On Solana, a token isn't a smart contract. It's a mint account — a small on-chain record that stores:

• Total supply


• Decimal precision


• Who's allowed to create more tokens (the mint authority)

The Token-2022 program (also called Token Extensions) is the

upgraded version that lets you bolt additional behaviours onto a mint

at creation time. Things like automatic transfer fees, interest accrual,

and transfer restrictions.

The catch: extensions are declared at mint creation and cannot be

added later. This is Mistake #3, and I'll come back to it. First,

the one that burned me the most.

Mistake 1: The Base Units Trap

When you create a Token-2022 mint with a transfer fee, you configure

two numbers: the fee rate in basis points, and a maximum fee cap.

The CLI command looks like this:

spl-token create-token \

  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \

  --transfer-fee-basis-points 100 \

  --transfer-fee-maximum-fee 5000 \

  --decimals 9

I ran this. I transferred 100 tokens at 1%. I expected 1 token to be

withheld as a fee. Instead, the recipient received 99.999995 tokens.

The withheld amount was 0.000005 — basically nothing.

What went wrong: --transfer-fee-maximum-fee 5000 is in base

units, not whole tokens. With 9 decimals, 5000 base units equals

0.000005 whole tokens. The cap kicked in immediately and capped

every fee at a fraction of a cent.

The fix: Multiply by 10 ** decimals:

// Wrong

const MAX_FEE = BigInt(5000);



// Right — 5000 whole tokens as the cap

const MAX_FEE = BigInt(5000 * 10 ** DECIMALS);

No transaction ran. The number grew because the display formula grew,

not because any state changed.

The URI changed on-chain immediately. But the wallet kept showing the

old image because it had cached the previous fetch.

The fix for production: Host your metadata and images on Arweave

or IPFS with content-addressed URLs. Since the content hash is part

of the URL, a changed image gets a new URL, which forces a fresh fetch.

A mutable HTTP URL (like a GitHub Gist) means wallets might show stale

content indefinitely.

This is why serious NFT projects pay for permanent storage. The

on-chain pointer is permanent. The thing it points at should be too.

What I'd Tell Myself at the Start

1. Always multiply by 10 ** decimals. Every time. Without exception.




2. Extension initializers come before createInitializeMintInstruction. Burn this into your muscle memory.




3. Design your token schema before you create the mint. You can't migrate. You can only start over.




4. Interest is a display formula, not a ledger update. Raw balance is truth. UI amount is interpretation.




5. On-chain metadata updates instantly. Off-chain images don't. If you need fast image updates, use content-addressed storage.

What I Actually Built

Despite all of this, the extensions work beautifully once you

understand them. By the end of Epoch 2 I had:

• A fungible token with 1% transfer fees, harvested and withdrawn


• A stacked mint with both transfer fees and 50% APR interest


• A soulbound credential token that the runtime physically refuses to transfer


• An NFT with on-chain metadata, grouped into a collection


• Live metadata mutation — renaming an NFT mid-life in one transaction

All of it built on Windows, without the spl-token CLI, using

Node.js and @solana/spl-token directly. The mistakes above are

the price of admission. The program is worth it.

Where to Go From Here

If you want to explore Token-2022 extensions yourself, the best

starting points are:

• 
  — with the base units trap explained


• 
  — on-chain vs off-chain metadata

All of the code in this post was written in Node.js on Windows — no

CLI available, every extension built programmatically using

@solana/web3.js and @solana/spl-token. If I could do it without

the CLI, so can you.

This post is part of *#100DaysOfSolana*. I've been building on

Solana every day for over two months. If you're starting out, the

mistakes above will save you hours. If you're experienced and I got

something wrong, tell me in the comments — I'm still learning too.