DEV Community: Lymah

Coming from Web2, Token-2022 taught me that some of the hardest bugs aren't failed transactions; they're successful transactions with incorrect outcomes. Here are five mistakes I wish I'd known sooner.

Lymah — Fri, 03 Jul 2026 19:32:06 +0000

Lymah

Jun 30

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

#100daysofsolana #web3 #blockchain #writing

7 min read

CPIs and PDA Signers: What I Built and What Actually Clicked

Lymah — Fri, 03 Jul 2026 17:45:51 +0000

I spent four days building programs that move SOL and tokens on Solana.
Day 71 was a simple SOL transfer through a CPI. Day 74 was a mint
whose authority belongs to a PDA with no private key — meaning nobody
can ever mint outside the program's rules again.

This post is what I learned between those two points, written for
someone who understands Web2 backend code but has never written a
Solana program.

The One Sentence Version

A CPI is a program calling another program. A PDA signer is how a
program proves it authorized that call without holding a private key.

Everything else is details.

What CPIs Actually Are

In Web2, your backend calls external APIs. A payment service, a
messaging provider, a database driver. You pass credentials, the
service does something, you get a result.

On Solana, programs call other programs the same way — except the
"credentials" are not an API key. They are either a wallet signature
that propagated from the outer transaction, or a set of seeds that
prove the calling program derived a specific address.

The mechanism is CpiContext:

let cpi_ctx = CpiContext::new(
    ctx.accounts.system_program.key(), // which program to call
    Transfer {                          // the accounts it needs
        from: ctx.accounts.user.to_account_info(),
        to: ctx.accounts.vault.to_account_info(),
    },
);
transfer(cpi_ctx, amount)?; // the instruction

Three things: the program to call, the accounts it needs, the
instruction to run. The ? makes it atomic — if the CPI fails,
the whole transaction rolls back.

The Two Cases

Case 1: the wallet signs

When a user signs the outer transaction, that signature propagates
automatically into any CPI that uses the wallet as an authority.
You do not have to do anything special.

// User signed the tx → their wallet can authorize this CPI
transfer(CpiContext::new(system_program, Transfer {
    from: user_wallet,
    to: recipient,
}), amount)?;

This is what I used on Day 71 (SOL transfer) and Day 72 (token mint).
The program is a policy layer — it checks conditions, then forwards
the call.

Case 2: the program signs

When the program needs to authorize something the user never signed
for — like returning SOL from a vault or minting a reward — it uses
PDA signer seeds:

let signer_seeds: &[&[&[u8]]] = &[&[
    b"vault",
    user_key.as_ref(),
    &[bump]
]];

let cpi_ctx = CpiContext::new(system_program, Transfer {
    from: vault_pda,
    to: user_wallet,
}).with_signer(signer_seeds); // ← this is the entire mechanism

transfer(cpi_ctx, amount)?;

The runtime re-derives the PDA from those seeds and your program ID.
If the result matches the account you passed in, the CPI is
authorized. No private key. No human approval.

The Vault: Deposit In, Program Signs Out

Day 73 was the clearest demonstration. Two instructions:

deposit(amount)  → user wallet signs, SOL flows INTO the vault PDA
withdraw(amount) → program signs via seeds, SOL flows OUT of vault PDA

The vault PDA is derived from ["vault", user_pubkey]. This means:

Every user has their own vault at a unique address
The program can only withdraw to the user whose key is in the seeds
Passing a different user's vault produces a seeds mismatch — rejected

The test confirmed it:

vault after deposit:  500000000 lamports
vault after withdraw: 0 lamports
✔ deposits, then the program signs to withdraw

And the failure test confirmed the protection:

Impostor trying to withdraw from original user vault...
✗ FAILURE 2: AnchorError caused by account: vault.
Error Code: ConstraintSeeds. Error Number: 2006.
A seeds constraint was violated.

The seeds are the authorization policy. Not an ownership check in
the handler — the derivation itself.

The PDA Mint Authority: Permanent Program Control

Day 74 was the harder version. I created a Token-2022 mint, then
transferred mint authority to a PDA:

await setAuthority(
  connection,
  payer,
  mint,
  payer,
  AuthorityType.MintTokens,
  mintAuthorityPda, // ← PDA with no private key
  [],
  undefined,
  TOKEN_2022_PROGRAM_ID
);

After this transaction, the only way to mint tokens is through
the program's mint_tokens instruction. No wallet can call
mintTo directly because no private key corresponds to the
PDA address. The program is the only entity that can reconstruct
the signer seeds at runtime.

Mint authority PDA: 8p6j3X6pBDVf4kzXcgk2VnnN3Jo18tJpjWqraMzguSbC
Minted base units:  500000000
✔ PDA signs the mint CPI — no human holds mint authority
Confirmed: only the program can mint — PDA has no private key

What This Pattern Unlocks

Every meaningful DeFi primitive on Solana uses this pattern:

Protocol type	What the PDA controls
Vault / escrow	SOL or token release conditions
AMM	Token pool balances
Lending protocol	Collateral and liquidation
Reward program	When and how much to mint
DAO treasury	Fund distribution rules

In every case, the rules live in the program. The PDA enforces
that only the program can act. The seeds determine what the program
can act on behalf of.

The Three Failures That Made It Real

I wrote a test suite that deliberately triggered three CPI failures:

Failure 1 — Insufficient funds:
Tried to withdraw 5 SOL from a vault holding 0.1 SOL.
✗ FAILURE 1: Simulation failed.
The System Program rejected the transfer before it hit the chain.

Failure 2 — Wrong signer (seeds mismatch):
An impostor wallet tried to withdraw from a different user's vault.

✗ FAILURE 2: ConstraintSeeds. Error Number: 2006.
A seeds constraint was violated.

The PDA derivation produced a different address. Rejected before
the handler ran.

Failure 3 — Wrong program ID:
Passed a fake address instead of the System Program.

✗ FAILURE 3: InvalidProgramId. Error Number: 3008.
Program ID was not as expected.

Anchor validated the program address before the CPI could execute.

All three caught cleanly. All three tell you exactly what went wrong.

What I Would Tell Someone Starting This Week

The wallet signature propagates automatically.
You do not need .with_signer when the user's wallet is the
authority. That is only for PDAs.

.with_signer is the entire PDA signing mechanism.
Everything else — the CpiContext, the accounts struct, the
instruction call — is the same whether a wallet or a PDA signs.
The only difference is that one line.

Store the bump on the account.
Compute it once in the init instruction with ctx.bumps.counter,
store it as a field, reuse it on every subsequent call.
Re-deriving it each time wastes compute.

The seeds are the authorization policy.
A vault derived from ["vault", user_pubkey] can only be drained
to that user. You do not need an explicit ownership check — the
derivation enforces it. If someone passes the wrong account, the
seeds mismatch and Anchor rejects the transaction.

setAuthority is a point of no return.
Once you transfer mint authority to a PDA, no human can mint outside
your program's rules. Make sure those rules are correct before you
call it on mainnet.

Resources

Part of *#100DaysOfSolana*. Building every day.

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

Lymah — Tue, 30 Jun 2026 14:46:47 +0000

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);

This is the most common Token-2022 gotcha. Every numeric parameter
involving token amounts is in base units. The CLI doesn't warn you.
The transaction succeeds. The number is just wrong.

Web2 equivalent: Imagine a payment processor that charges fees in
cents but you accidentally configured it in mills (1/10 of a cent).
Everything "works" — the fee is just 10x smaller than you intended,
and you only notice when you check the receipts.

Mistake 2: The Instruction Order Problem

When creating a Token-2022 mint with extensions programmatically, you
build a transaction with multiple instructions. The order matters — a lot.

Here's the wrong order:

const tx = new Transaction().add(
  SystemProgram.createAccount({ ... }),
  createInitializeMintInstruction(...),     // ← WRONG: mint before extensions
  createInitializeTransferFeeConfigInstruction(...),
  createInitializeMetadataPointerInstruction(...),
);

This produces a cryptic error:

Error: Transaction simulation failed:
Error processing Instruction 2: invalid account data for instruction

The error points at instruction 2 (the transfer fee config), but the
real problem is instruction 1 (the mint initialization). The mint is
being initialized before the extension space is configured, so the
runtime finds data in unexpected places.

The fix: Extension initializers must come before
createInitializeMintInstruction:

const tx = new Transaction().add(
  SystemProgram.createAccount({ ... }),
  createInitializeMetadataPointerInstruction(...),   // extensions first
  createInitializeTransferFeeConfigInstruction(...), // extensions first
  createInitializeMintInstruction(...),              // mint LAST
  createInitializeInstruction({ ... }),              // metadata after mint
);

The mental model: extensions configure the account's memory layout.
The mint instruction writes into that layout. If you write before you
configure, you're writing into the wrong shape.

Mistake 3: Extensions Are Immutable After Creation

Coming from Web2, I expected to be able to add features to a token
after deploying it. In Rails you'd add a column with a migration.
In Postgres you'd ALTER TABLE. On Token-2022, you can't.

Extensions are baked into the mint account when it's created.
The getMintLen() function calculates how many bytes to allocate
based on which extensions you declare. Once the account is allocated
and the mint is initialized, that's the shape it has forever.

I discovered this when I created a plain mint and then tried to add
a transfer fee to it. There's no instruction for that. I had to
create a new mint.

// This is everything you can do with a mint you forgot to add
// extensions to: nothing. You create a new one.
const extensions = [
  ExtensionType.TransferFeeConfig,  // must declare ALL of these
  ExtensionType.InterestBearingConfig, // at creation time
  ExtensionType.MetadataPointer,    // you can't add them later
];
const mintLen = getMintLen(extensions);

The practical consequence: Design your token before you deploy it.
Write down every extension you think you'll need. Add one or two you
might need later. The cost of over-allocating is a slightly larger
rent-exempt deposit. The cost of under-allocating is creating a new
mint and migrating all your holders.

Mistake 4: Interest Is a View, Not a Balance

This one is subtle and it confused me for longer than I'd like to admit.

The Token-2022 InterestBearingConfig extension stores an APR on the
mint. As time passes, wallets and explorers show a growing balance.
I assumed this meant new tokens were being minted. It doesn't.

The raw on-chain balance never changes. What changes is the displayed
amount — a formula applied on the fly:

UI Amount = raw_balance × e^(rate × elapsed_years)

I proved this by snapshotting the balance twice, 30 seconds apart,
with no transactions in between:

Snapshot 1: 1,000,000.069191 tokens
Snapshot 2: 1,000,000.544703 tokens
Growth:     +0.475512 tokens in 30s
Raw balance: 1,000,000,000,000 base units (unchanged)

No transaction ran. The number grew because the display formula grew,
not because any state changed.

Why this matters: Transfer fees operate on the raw balance. Interest display operates on the raw balance through a formula. They're completely independent. If you transfer tokens, the fee calculation uses the raw amount, not the interest-adjusted display amount. This is correct behavior, but if you're building a UI, you need to know which number to show and which to calculate with.

Web2 equivalent: A savings account balance display that multiplies
the raw database value by an interest factor before rendering. The
database row doesn't change until you explicitly trigger a settlement.

Mistake 5: The Two-Layer Image Cache Problem

When I updated my NFT's metadata URI to point at a new JSON file, the
name changed immediately in Solana Explorer. The image took over an
hour to update in wallets.

These are two completely different layers:

Layer	Where it lives	Update speed
Name, symbol, URI	On-chain (mint account)	Instant — one transaction
Image, attributes	Off-chain (JSON at URI)	Depends on wallet cache

The on-chain URI is a pointer. The image it points at lives on an HTTP
server. Wallets fetch that image when they first index the NFT and
cache it aggressively — sometimes for hours, sometimes for days.

When I ran this:

// Update the on-chain URI — instant
await sendAndConfirmTransaction(connection, new Transaction().add(
  createUpdateFieldInstruction({
    programId: TOKEN_2022_PROGRAM_ID,
    metadata: mint,
    updateAuthority: wallet.publicKey,
    field: "uri",
    value: "https://new-metadata.json",
  })
), [wallet]);

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

Always multiply by 10 ** decimals. Every time. Without exception.
Extension initializers come before createInitializeMintInstruction. Burn this into your muscle memory.
Design your token schema before you create the mint. You can't migrate. You can only start over.
Interest is a display formula, not a ledger update. Raw balance is truth. UI amount is interpretation.
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:

Token Extensions overview — the canonical reference
Transfer Fee extension — with the base units trap explained
Interest-Bearing extension — including the view vs balance distinction
Token Metadata extension — 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.

What I Learned About PDAs in a Week of Building on Solana

Lymah — Sat, 27 Jun 2026 16:37:12 +0000

I spent a week building a counter program in Anchor. By the end, every
user had their own account, a global config singleton controlled whether
new counters could be created, and a close instruction returned the rent
deposit back to the wallet. None of that would have been possible without
Program Derived Addresses.

This post is what I wish someone had handed me on day one.

The Problem PDAs Solve

On Solana, programs are stateless. If your program needs to remember
something, a user's score, a vault balance, a config flag, it needs
a dedicated account to store it in. And that account needs an address
your program can find again later, without the client having to pass
around a randomly generated keypair.

PDAs are that address. Deterministic. Derivable from inputs your
program already knows. No private key required.

The Mental Model

Here is the Web2 analogy that helped me most:

A PDA is like a database primary key you can compute from the
row's logical identity.

In Postgres, if you want one row per user, you use user_id as the
primary key. You never store the key separately — you derive it from
who is asking. PDAs work the same way. You feed in a list of seeds
(bytes that describe the identity of the thing you want to store) plus
your program's ID, and you get back a deterministic address.

Every time you run the derivation with the same inputs, you get the
same address. That is the whole point.

Where the analogy breaks: the address may or may not have an account
at it yet. Deriving a PDA does not create anything on the chain. It just
computes a public key. The account gets created when your program runs
an instruction with the init constraint, and that creation costs
rent, paid by whoever is signing the transaction.

One more thing the analogy misses: the program ID is baked into the
derivation. The same seeds run through a different program produce a
completely different address. This means only your program can
predictably derive and sign for its own PDAs. No other program can
guess them or collide with them accidentally.

Anatomy of a Derivation

Here is the accounts struct from my counter program, exactly as it
appears in lib.rs:

#[derive(Accounts)]
pub struct InitCounter {
    #[account(
        init,
        payer = user,
        space = 8 + Counter::INIT_SPACE,
        seeds = [b"counter", user.key().as_ref()],
        bump
    )]
    pub counter: Account,
    #[account(mut)]
    pub user: Signer,
    pub system_program: Program,
}

Let me walk through every piece.

seeds = [b"counter", user.key().as_ref()]

The seed array is the input to the hash. It has two parts here:

b"counter" — a static byte string that acts as a namespace. It ensures this address is clearly "a counter account," not something else.
user.key().as_ref() — the signer's public key as bytes. This is what makes the address unique per user.

Under the hood, Anchor runs sha256(seeds + program_id + bump)
and checks whether the result lands on the ed25519 elliptic curve.
If it does, it decrements the bump and tries again. The first result
that lands off the curve is returned as the canonical PDA. Off-curve
means no private key can produce it, which means only your program
can sign for it.

bump

The bump is a single byte (0–255) appended to the hash input.
PublicKey.findProgramAddressSync starts at 255 and counts down
until it finds an off-curve result. The first bump that works is
the canonical bump. Anchor computes it for you and stores it in
ctx.bumps.counter.

init

This constraint tells Anchor to create the account at the derived
address if it doesn't already exist. It makes a CPI (cross-program
invocation) to the System Program, which allocates the bytes and
transfers the rent-exempt deposit from the payer.

space = 8 + Counter::INIT_SPACE

The 8 bytes are Anchor's discriminator — a prefix stamped on every
account so the program can later verify "yes, this is a Counter
account, not something else." Counter::INIT_SPACE is computed
automatically by the #[derive(InitSpace)] macro.

Why the Seeds Matter

The seeds are your access control policy.

My counter program uses [b"counter", user.key().as_ref()]. That
means every signer gets their own PDA. Alice's counter and Bob's
counter live at completely different addresses, derived independently.

// Alice's counter
const [alicePda] = PublicKey.findProgramAddressSync(
  [Buffer.from("counter"), alice.toBuffer()],
  programId
);

// Bob's counter
const [bobPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("counter"), bob.toBuffer()],
  programId
);

console.log(alicePda.equals(bobPda)); // false — always

Compare that to the config singleton in my program, which uses
[b"config"] — no wallet in the seeds:

// Same address for every caller
const [configFromAlice] = PublicKey.findProgramAddressSync(
  [Buffer.from("config")], programId
);
const [configFromBob] = PublicKey.findProgramAddressSync(
  [Buffer.from("config")], programId
);

console.log(configFromAlice.equals(configFromBob)); // true — always

One address. Every caller computes the same thing. That's exactly what
you want for a global config — one row at the top of the database that
everyone reads from.

Use the wrong pattern and you get disasters. If I had written my
counter as [b"counter"], the first user to call init_counter
would own the only counter that can ever exist. Everyone else would
get "account already in use."

One byte changes everything:

["counter",  walletA] → E4C9RStxbiweqVv7rHM88HgzWNhcCibTHWtGn7HrowjM

["counters", walletA] → AoaX8ntGs9tj7b96pbMcPHD822X8tEqRAg7p48VgdcmZ

["counter\0",walletA] → Es37q2wXjeYPkGhfcn4qnB3Uu167VmbtKUVaQ8i87LTm

["Counter",  walletA] → 2WSX2ScZwFgDDYZWkspqrCHTWnSsGoXquH425a2zgsWy

Same program, same wallet, four completely different addresses.
There is no "close enough" in PDA derivation.

What the Bump Buys You

The bump is not magic. It is just the first byte value (starting from
255, counting down) that pushed the hash result off the ed25519 curve.
Off-curve means no private key exists at that point. No private key
means no human can sign for it. Only your program can — by providing
the same seeds plus bump to the runtime when it needs to authorize
something.

Always store the bump on the account:

#[account]
#[derive(InitSpace)]
pub struct Counter {
    pub user: Pubkey,
    pub count: u64,
    pub bump: u8,   // ← store this
}

pub fn init_counter(ctx: Context<InitCounter>) -> Result<()> {
    let counter = &mut ctx.accounts.counter;
    counter.bump = ctx.bumps.counter;  // ← Anchor gives it to you here
    Ok(())
}

Then on subsequent instructions, pass it back instead of re-deriving:

#[account(
    mut,
    seeds = [b"counter", user.key().as_ref()],
    bump = counter.bump,   // ← use the stored bump, not bump alone
)]
pub counter: Account<'info, Counter>,

Re-deriving the bump on every call is unnecessary compute. Storing
it once and reusing it is free. Anchor's bump constraint (without
= counter.bump) re-derives every time. bump = counter.bump
uses the stored value. Use the stored value.

The Full Lifecycle

My week in four steps:

1. Derive the address (off-chain)

const [counterPda] = PublicKey.findProgramAddressSync(
  [Buffer.from("counter"), wallet.toBuffer()],
  programId
);
// counterPda is an address. Nothing on the chain yet.

2. Initialize the account (init instruction)

The init constraint on the Anchor accounts struct creates the
account at the derived address, allocates the right number of bytes,
and funds the rent-exempt deposit from the payer. After this
transaction, the account exists on the chain with your program as its
owner.

3. Mutate data (subsequent instructions)

Every later instruction re-derives the PDA from the seeds and
validates that it matches the account passed in. The seeds and bump
Constraints do this automatically. Your handler just reads and writes
the fields.

4. Close the account (close instruction)

Closing a PDA is not like dropping a table row. It is:

Transfer all lamports to the destination wallet
Zero out the account data
The runtime removes the account from state at the end of the transaction (a zero-lamport account cannot persist)

In Anchor, one constraint does all of this:

#[account(
    mut,
    close = user,    // ← drains lamports to user, zeros data
    seeds = [b"counter", user.key().as_ref()],
    bump = counter.bump,
    has_one = user,
)]
pub counter: Account<'info, Counter>,

The rent deposit comes back to the wallet. The account disappears.
getAccountInfo returns null on the next call.

What I Would Tell Past Me

The program ID is part of the derivation. The same seeds in a
different program produce a completely different address. This is a
feature — your PDAs belong to your program and no other.

PDAs cannot sign transactions themselves. Only programs can sign
on a PDA's behalf, by providing the seeds and bump to the runtime as
"signer seeds." This is how your program authorizes CPIs from a PDA
it owns.

init_if_needed is a footgun. It initializes the account if it
doesn't exist, and silently does nothing if it does. That sounds
convenient until a caller reuses it to overwrite an account they
don't own. Use init when you mean "create exactly once."

The seeds enforce access control, not just naming. When Anchor
validates a PDA constraint, it re-derives the expected address from
the seeds and compares it to what you passed in. If someone passes
the wrong account, the derivation produces a different address, and
the transaction is rejected before your handler runs. You do not need
an explicit ownership check — the seeds are the ownership check.

Design your seed scheme before you write any code. You cannot
change the seeds after deployment. A counter keyed by
[b"counter", user.key()] and one keyed by
[b"user_counter", user.key()] are in completely different address
spaces. Pick once, keep forever.

Resources

Program Derived Addresses — Solana docs The canonical reference for how PDAs are derived and what guarantees you actually get.
PDAs in Anchor The seed and bump constraint syntax, with examples.
Anchor account constraints reference Full list of constraints including init, has_one, seeds, bump, close, and constraint.
GitHub

The full counter program from this arc is available in my
100 Days of Solana repo. If anything in this post is wrong,
leave a comment — I'm still learning.

This post is part of *#100DaysOfSolana*. Building on Solana
every day.

How I Built a Counter Program in Anchor and Learned to Trust My Tests

Lymah — Sat, 20 Jun 2026 18:54:21 +0000

I spent a week building a counter program in Anchor — the Rust framework
for writing Solana programs. By the end I had two instructions, one
authorization constraint, and a test suite I could actually trust. Here
is what I built, how I tested it, and the moment I proved the tests
were real.

Start Here: The Accounts Struct

If you come from Web2, this is the part that looks the strangest:

#[derive(Accounts)]
pub struct Initialize {
    #[account(
        init,
        payer = authority,
        space = 8 + Counter::INIT_SPACE,
    )]
    pub counter: Account,
    #[account(mut)]
    pub authority: Signer,
    pub system_program: Program,
}

In a Web2 backend, your handler receives a request object and talks
to a database. On Solana, there is no database; there are accounts.
Every account your instruction needs to read or write must be declared
upfront, before the handler runs. Anchor validates them before your
code ever executes.

Here is what each field does:

counter — the account being created. The init constraint tells Anchor to make a CPI to the System Program, allocate 8 + Counter::INIT_SPACE bytes, and fund it from authority. The 8 is for the discriminator Anchor stamps on every account so the program can later verify "this is mine."
authority — the wallet signing and paying for the transaction. mut because its SOL balance is decreasing to fund the new account.
system_program — required any time you create accounts. Anchor checks that the address matches the real System Program.

The accounts struct is the schema. The handler is the logic.

The Handlers

pub fn initialize(ctx: Context) -> Result {
    let counter = &mut ctx.accounts.counter;
    counter.authority = ctx.accounts.authority.key();
    counter.count = 0;
    Ok(())
}

ctx.accounts gives you typed access to every account declared in
the struct. The handler is short because Anchor already did the hard
work: allocating the account, checking the signer, paying the rent.
Your code just sets the initial values.

pub fn increment(ctx: Context) -> Result {
    let counter = &mut ctx.accounts.counter;
    counter.count = counter.count
        .checked_add(1)
        .ok_or(error!(ErrorCode::ArithmeticOverflow))?;
    Ok(())
}

The accounts struct for increment has a constraint worth paying
attention to:

#[derive(Accounts)]
pub struct Increment {
    #[account(mut, has_one = authority)]
    pub counter: Account,
    pub authority: Signer,
}

has_one = authority tells Anchor: before this handler runs, check
that counter.authority == authority.key(). If the wallet signing
the transaction does not match the wallet stored on the counter,
the transaction is rejected. My handler never sees a bad caller —
the constraint rejects them first.

This is the Solana equivalent of a 403 check, but it is declarative
and enforced by the runtime. There is no application layer to
accidentally bypass.

The Tests

I used LiteSVM — an in-process
Solana VM that runs your compiled program against a fresh ledger in
milliseconds. No devnet, no flakiness, no airdrop required.

Happy path

#[test]
fn initialize_then_increment() {
    let mut svm = LiteSVM::new();
    // ... load program, airdrop, create keypairs ...

    svm.send_transaction(init_tx).unwrap();
    svm.send_transaction(inc_tx).unwrap();

    let account = svm.get_account(&counter_kp.pubkey()).unwrap();
    let parsed = counter::Counter::try_deserialize(
        &mut account.data.as_slice()
    ).unwrap();

   assert_eq!(parsed.count, 1);
   assert_eq!(parsed.authority, authority.pubkey());
 }

This test would fail if increment stored the wrong number, or if
initialize set the wrong authority. It proves both instructions
work correctly together.

Failure path

#[test]
fn increment_fails_when_wrong_authority_signs() {
    // authority_a creates the counter
    svm.send_transaction(init_tx).expect("initialize should succeed");

    // authority_b tries to increment it
    let bad_tx = build_increment_tx(&svm, program_id,
        &authority_b, counter.pubkey());

    let result = svm.send_transaction(bad_tx);
    assert!(result.is_err(),
        "increment should fail when signed by the wrong authority");
}

This test would fail if I removed or weakened the has_one = authority
constraint. It proves the gate is real, not just assumed.

The Experiment That Made the Tests Real

A passing test suite is a story. The question is whether it tells the
truth.

On the last day of the week I planted bugs on purpose, one at a time,
and watched the suite catch them.

The most instructive experiment: I changed checked_add(1) to
checked_add(2) in the increment handler. The transaction still
succeeded — no error, no panic. But the stored value was wrong.

The test output:
test initialize_then_increment ... FAILED
thread panicked at:

assertion left == right failed
left: 1
right: 2

One character change in production code. One specific failure with a
specific line number pointing exactly at the assertion that caught it.
That is what assertions are for.

Then I removed the has_one = authority constraint entirely. The
happy-path test stayed green — it uses the correct authority. But:

test increment_fails_when_wrong_authority_signs ... FAILED

increment should fail when signed by the wrong authority

The wrong-signer transaction now succeeded, and the test that expected
a rejection panicked. Without that failure test, I would have silently
shipped a program that lets anyone increment anyone else's counter.
The negative test is the only reason I would have known.

Both times I put the code back, ran the suite, and got green. The
suite told the truth both times.

What I Would Build Next

The counter account in this program lives at a random keypair's
address. That means the client has to remember which keypair holds
which user's counter — messy in practice. The natural next step is
Program Derived Addresses (PDAs): deterministic addresses derived
from the user's wallet and a seed string, so any client can find any
user's counter without storing a keypair.

After that: a decrement instruction, a reset instruction, and
then connecting the program to a TypeScript client so it can run
on devnet with a real wallet.

Resources

Anchor framework — the framework used throughout
Anchor account constraints reference — full list of constraints including has_one, init, mut
LiteSVM — the in-process test harness
Solana docs — accounts model primer

This post is part of *#100DaysOfSolana*. Building on Solana every
day — follow along or jump in any time.

Three Token-2022 Mints in One Week: Fees, Yield, and Soulbound

Lymah — Sat, 13 Jun 2026 16:30:17 +0000

If you come from Web2, you probably think of a token as a number in a database that moves around when people transact. On Solana, the original SPL Token program is exactly that. Token-2022 is the upgrade — and it lets you bolt behaviors directly onto the mint itself, the way you would add middleware to a payment pipeline, except the middleware lives inside the asset and cannot be bypassed.

This week I shipped three different mints on Solana devnet, each
demonstrating a different Token-2022 extension. Here's what I built, the exact commands I ran, and when you'd actually reach for each one.

Mint 1: Transfer Fee (Days 50–51)

Mint address: ACvRnk4m9fDji76fq74n7Nzwo6tUcPyajmgi3jX9BY1Q
View on Solana Explorer

Extension: TransferFeeConfig

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 6 \
  --transfer-fee-basis-points 100 \
  --transfer-fee-maximum-fee 1000000

This creates a mint where every transfer automatically withholds 1%
(100 basis points) into the recipient's account. The recipient can't spend the withheld amount — only the withdraw authority (whoever created the mint) can sweep it out.

When you'd use this: Protocol treasury fees, creator royalties on
a community token, or a skim on every transaction in a marketplace.
The fee logic is enforced by the Token-2022 program itself. No wallet, no dApp, no smart contract can route around it.

After creating the mint, I transferred 1,000 tokens to a second wallet:

spl-token transfer \
  --expected-fee 10 \
  $MINT 1000 $RECIPIENT \
  --allow-unfunded-recipient

The --expected-fee 10 flag is a safety check — the transfer aborts if the calculated fee doesn't match. Out of 1,000 tokens sent, the recipient received 990. Ten tokens sat withheld in their account until I swept them:

spl-token withdraw-withheld-tokens $MY_TOKEN_ACCOUNT $RECIPIENT_TOKEN_ACCOUNT

My final balance: 1,000,010 tokens. That extra 10 is the fee I collected.

Mint 2: Transfer Fee + Interest (Day 52)

Mint address: A2qxipYpyY4gs1BAwv45U88Uj9RuuseEwCiB3s76ZB2J
View on Solana Explorer

Extensions: TransferFeeConfig + InterestBearingConfig

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 6 \
  --transfer-fee-basis-points 100 \
  --transfer-fee-maximum-fee 1000000 \
  --interest-rate 5000

One command. Two extensions. Both baked into the same mint account.

What the interest extension actually does — and doesn't do:
This is the part I wish someone had told me upfront. The
InterestBearingConfig extension does not mint new tokens over
time. Your raw on-chain balance never changes. What changes is the displayed (UI) amount — a formula applied on the fly using the stored rate and the network's clock:
UI Amount = raw_balance × e^(rate × elapsed_years)

It's a view, not a balance update. No transaction runs. No new tokens appear. The number you see in a wallet grows because the display formula grows — not because your account data changed.

To make the effect visible quickly I used 50% APR (5,000 basis
points). Two snapshots 30 seconds apart:

Snapshot 1: 1,000,000.069191 tokens
Snapshot 2: 1,000,000.544703 tokens
Growth:     +0.475512 tokens in 30s

No transaction ran between those two reads.

When you'd use this: Yield-bearing stablecoins, savings-style
tokens, or any token where you want the displayed value to grow as a function of time without actually minting supply on a schedule.

Mint 3: Non-Transferable / Soulbound (Day 54)

Mint address: 39eGRkFWbb52icCEdoaqSRtjH257KGHhhssZ2J3b2RdA
View on Solana Explorer

Extension: NonTransferable

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --enable-non-transferable

This mint produces tokens that cannot be sent anywhere. Once a token lands in a wallet, it stays there. The holder is the holder forever.

I minted one token to myself, created a recipient wallet, then tried to transfer:

spl-token transfer $MINT 1 $RECIPIENT --allow-unfunded-recipient

The response:

Error 0x25: NonTransferable — token program rejected transfer
Transaction simulation failed: Error processing instruction

That error didn't come from my code. It didn't come from a smart
contract I wrote. It came from the Token-2022 program refusing the instruction. My balance was unchanged. The token was still with me.

When you'd use this: Course completion badges, KYC verification tokens, DAO membership credentials, employee IDs. Anything where the value comes from who holds it, not from being tradeable.

In Web2, you'd enforce this at the application layer — a database
constraint, an API check. Someone who talks to the database directly can bypass that. On Solana the rule is inside the program that owns the asset. There is no around.

What the Audit Taught Me

On Day 53 I ran the Solana equivalent of DESCRIBE against all three mints — reading every extension the protocol sees on each account:

spl-token display $MINT_ADDRESS

The output confirmed everything I had configured was actually there.
But the more interesting thing was the account sizes:

Mint	Extensions	Size
Day 50	TransferFeeConfig	278 bytes
Day 52	TransferFeeConfig + InterestBearingConfig	334 bytes

56 bytes more for the second extension. Those bytes cost SOL in
rent-exempt deposits. Extensions are not free. You choose them
deliberately at mint creation time — and you can't add them later.
That constraint forces upfront design in a way I actually appreciate.

What Surprised Me

The thing I expected least: extensions are completely independent.
The transfer fee operates on the raw token amount. The interest
display formula also operates on the raw amount. They don't interfere with each other at all. I kept expecting some interaction, some edge case where they'd conflict. There isn't one. Two different TLV entries in the same byte buffer, each doing its own thing, neither knowing the other exists.

The thing I'd reach for in a real product: NonTransferable +
metadata on a single mint. A credential system where the badge is
self-describing (name, issuer, URI) and permanently bound to the
wallet that earned it. No backend. No revocation list. Just a token with rules baked in.

Resources

This post is part of *#100DaysOfSolana*. Building on devnet every day — follow along or jump in any time.

Solana NFTs Without Metaplex: What I Built with Token Extensions published

Lymah — Tue, 09 Jun 2026 16:08:47 +0000

Before this week, I thought minting an NFT on Solana meant learning Metaplex. It turns out you can mint a full NFT — with metadata, a collection, and live mutation — using just the Token Extensions program and about 50 lines of Node.js.

Here's what I actually built, what surprised me, and what I'd do differently.

The Mental Model: What Is a Solana NFT?

Strip away the marketplaces and the profile pictures and an NFT on Solana
is just a token mint with three properties:

Supply = 1 — only one copy exists
Decimals = 0 — it can't be split into fractions
Mint authority disabled — nobody can ever create a second copy

That's it. The same SPL Token program that handles fungible tokens handles
NFTs. The only difference is the configuration.

With the Token Extensions Program (Token-2022), you can go further. You attach extensions to the mint at creation time that add behavior at the protocol level. For NFTs, the relevant ones are:
| Extension | What it does |
|-----------|-------------|
| MetadataPointer | Points to the account that holds the token's metadata |
| TokenMetadata | Stores name, symbol, URI, and custom fields on the mint itself |
| GroupPointer | Marks a mint as a collection |
| GroupMemberPointer | Links a mint to a parent collection |

No Metaplex account. No companion program. The metadata lives on the mint.

What I Built: Four Days, One NFT Arc

Day 1: The bare 1-of-1

I started with the simplest possible NFT — no metadata, no name, just the three properties above.

// Create a mint with 0 decimals using original SPL Token
const createMintTx = new Transaction().add(
  SystemProgram.createAccount({
    fromPubkey: wallet.publicKey,
    newAccountPubkey: mint,
    space: 82,
    lamports: mintLamports,
    programId: TOKEN_PROGRAM_ID,
  }),
  createInitializeMintInstruction(
    mint,
    0,               // decimals
    wallet.publicKey,
    wallet.publicKey,
    TOKEN_PROGRAM_ID
  )
);

// After minting 1 token, permanently disable the mint authority
await sendAndConfirmTransaction(connection, new Transaction().add(
  createSetAuthorityInstruction(
    mint,
    wallet.publicKey,
    AuthorityType.MintTokens,
    null,            // null = disable forever
    [],
    TOKEN_PROGRAM_ID
  )
), [wallet]);

Opening this in Solana Explorer showed "Unknown Token" — no name, no image, just an address. That blankness was the point. It proved the NFT-ness has nothing to do with the presentation layer.

Day 2: Stamping metadata with Token-2022

The next day I rebuilt it using Token-2022 with the MetadataPointer and TokenMetadata extensions. Now the name, symbol, and URI live on the mint account itself.

// Key instruction: write metadata directly onto the mint
createInitializeInstruction({
  programId: TOKEN_2022_PROGRAM_ID,
  metadata: mint,           // metadata lives on the mint itself
  updateAuthority: wallet.publicKey,
  mint,
  mintAuthority: wallet.publicKey,
  name: "First Light",
  symbol: "LIGHT",
  uri: "https://gist.githubusercontent.com/.../metadata.json",
})

After this transaction confirmed, the Explorer rendered the token with its name, symbol, and image fetched from the URI. It looked like a real NFT because it was one.

Day 3: Wrapping it in a collection

Collections on Token-2022 use two extension pairs:

The collection mint gets GroupPointer + TokenGroup
Each member NFT gets GroupMemberPointer + TokenGroupMember

The member extension stores a pointer back to the collection. This is exactly a foreign key in a relational database — the collection is the parent table, and each NFT is a child row.

After minting two member NFTs, the collection mint's Token Group showed size: 2, maxSize: 3. Any wallet or marketplace can verify membership by reading that pointer without trusting any off-chain index.

Day 4: Mutating metadata live

The metadata extension is mutable as long as you hold the update authority. This turned out to be the most interesting day.

// Rename the NFT
await sendAndConfirmTransaction(connection, new Transaction().add(
  createUpdateFieldInstruction({
    programId: TOKEN_2022_PROGRAM_ID,
    metadata: new PublicKey(NFT_MINT),
    updateAuthority: wallet.publicKey,
    field: "name",
    value: "Field Notes",
  })
), [wallet]);

// Add a custom key-value pair
await updateField(connection, wallet, NFT_MINT, "edition", "field-test-1");

// Remove it
await sendAndConfirmTransaction(connection, new Transaction().add(
  createRemoveKeyInstruction({
    programId: TOKEN_2022_PROGRAM_ID,
    metadata: new PublicKey(NFT_MINT),
    updateAuthority: wallet.publicKey,
    key: "rarity",
    idempotent: true,
  })
), [wallet]);

Each of those is a single transaction. The on-chain name changed instantly. The image in the wallet lagged for a while — it was cached. That gap between the on-chain layer (instant) and the off-chain image layer (cached) is one of the more practical things I learned this week.

The Surprising Parts

Extensions are declared at creation time and can't be added later.
This is the Solana version of "schema decisions are forever." If you create a mint and forget to include GroupMemberPointer, you can't patch it in.
You have to mint a new token. This forces upfront design in a way that felt restrictive at first but is actually good discipline.

The instruction order inside a transaction matters.
Extension initializers must run before createInitializeMintInstruction. I got a cryptic InvalidAccountData error the first time I got this wrong.
Once I understood that extensions configure the account before the mint is initialized, the order made sense.

Windows doesn't have the spl-token CLI.
I did every challenge in Node.js using @solana/web3.js and
@solana/spl-token directly. This was harder than using the CLI but taught me more — I had to understand the actual instructions rather than just running commands.

The fungible vs NFT comparison is just numbers.
Running an audit script against my Day 30 fungible token alongside my NFTs made this concrete:

Property	Fungible (Day 30)	NFT (Day 44)
Supply	1,000,000,000 base units	1
Decimals	6	0
Mint authority	Active	Disabled
Extensions	None	MetadataPointer, TokenMetadata
Account size	82 bytes	469 bytes

Same program. Same instruction set. Just different configuration.

What I'd Build Next

The natural next step is exploring Metaplex Core — the higher-level NFT standard that most production projects on Solana use. Now that I understand what Token Extensions give you natively, I can actually evaluate what Metaplex adds (royalty enforcement, collection verification, creator splits) versus what you get for free at the protocol level.

I'm also curious about Arweave and IPFS for URI hosting. Right now my NFT points at a GitHub Gist. That's fine for devnet experiments, but the whole point of an immutable on-chain pointer is that the thing it points at should also be permanent. A mutable Gist defeats that.

Resources

Token Extensions overview — the canonical reference
Metadata Pointer and Token Metadata extensions — what I used for on-chain metadata
Token Groups and Members — how collections work
Solana Explorer (devnet) — where I verified every step
Metaplex Core — the production NFT standard worth knowing

This post is part of #100DaysOfSolana. I'm building every day on devnet
— follow along or jump in any day.

Soulbound Credentials on Solana: Building Revocable Tokens with Non-Transferable + Permanent Delegate

Lymah — Mon, 01 Jun 2026 21:25:42 +0000

I spent 7 days learning Solana token extensions. Here's what clicked, what surprised me, and the code you need to build tokens that can't be traded but can be revoked.

The Problem (In Web2 Terms)

Imagine you work in HR. You issue an employee a digital badge proving they're a certified security officer. Here's what you'd want:

The badge stays in their wallet — they can't trade or sell it
Only they can use it
If they leave the company or fail a compliance check, you can revoke it silently without their permission
The badge metadata (name, symbol, type) is on-chain and permanent

You could build this with centralized databases and APIs. On Solana, it's just three extensions on a token mint.

What Are Token Extensions?

Solana's Token-2022 program lets you attach additional behaviors to any mint at creation time. Think of them like middleware for tokens.
Before extensions, every token was the same — a mint with supply and decimals, token accounts holding balances, and transfer instructions. Extensions let you add rules on top:

Extension	What It Does	Use Case
Transfer Fee	Charge a percentage on every transfer	Protocol revenue, marketplace commissions
Non-Transferable	Make tokens unmovable after minting	Soulbound badges, credentials, memberships
Permanent Delegate	Let the issuer burn tokens from anyone	Revocable credentials, subscriptions with expiry
Metadata	Store name, symbol, URI on-chain	Self-describing tokens, no external API needed
Default Account State	Freeze all new accounts by default	Compliance gates, KYC verification

The critical rule: extensions must be declared at mint creation. You cannot add them later. This forces you to think about your token's full lifecycle before deploying — which is good design discipline.

The Journey: Three Combinations That Matter

Over the past week I built three different token types. Here's what I learned from each.

Day 34: Transfer Fees (The Marketplace Token)
A token that charges 1% on every transfer, withheld automatically and sweepable by the issuer.
What clicked: Fees are calculated at the protocol level — there's no fee handler to bypass. If someone transfers your token, the fee is withheld. Full stop.
Day 37: Multi-Extension Token (The Compliance Token)
I combined three extensions at once: TransferFeeConfig + InterestBearingConfig + MetadataPointer.
What clicked: Extensions are truly independent. The interest-bearing display formula applies regardless of whether a fee is configured. The metadata doesn't affect functionality. They compose without interfering.
Days 38–40: Soulbound Credentials (The Revocable Badge)
The combination that unlocked a genuinely new primitive:

NonTransferable — token can't move
PermanentDelegate — issuer can revoke without the holder's consent
MetadataPointer — credential is self-describing on-chain

The Code: Building a Revocable Credential

I'm on Windows without access to the spl-token CLI, so I built this entirely in Node.js using @solana/web3.js and @solana/spl-token.

import {
  Connection,
  Keypair,
  SystemProgram,
  Transaction,
  sendAndConfirmTransaction,
} from "@solana/web3.js";

import {
  ExtensionType,
  TOKEN_2022_PROGRAM_ID,
  createInitializeMintInstruction,
  createInitializeNonTransferableMintInstruction,
  createInitializePermanentDelegateInstruction,
  createInitializeMetadataPointerInstruction,
  getMintLen,
  getAssociatedTokenAddressSync,
  createAssociatedTokenAccountInstruction,
  mintTo,
  createBurnInstruction,
} from "@solana/spl-token";

import { createInitializeInstruction, pack, TYPE_SIZE, LENGTH_SIZE } from "@solana/spl-token-metadata";

const connection = new Connection("https://api.devnet.solana.com", "confirmed");

// Load your saved keypairs (never generate fresh keypairs on every run)
const authority = loadWallet("~/.config/solana/id.json"); // issuer
const recipient = loadWallet("~/recipient-wallet.json");  // holder
const mintKeypair = Keypair.generate();                   // new mint each run
const mint = mintKeypair.publicKey;

// Define metadata
const tokenMetadata = {
  mint,
  name: "Solana Dev Credential",
  symbol: "CRED",
  uri: "https://example.com/credential.json",
  additionalMetadata: [],
};

// Calculate space: base mint + extensions + metadata
const metadataExtLen = TYPE_SIZE + LENGTH_SIZE + pack(tokenMetadata).length;
const extensions = [
  ExtensionType.NonTransferable,
  ExtensionType.PermanentDelegate,
  ExtensionType.MetadataPointer,
];
const mintLen = getMintLen(extensions);
const mintLamports = await connection.getMinimumBalanceForRentExemption(
  mintLen + metadataExtLen
);

// Build the transaction — instruction order matters
const createMintTx = new Transaction().add(
  // 1. Allocate the account
  SystemProgram.createAccount({
    fromPubkey: authority.publicKey,
    newAccountPubkey: mint,
    space: mintLen,
    lamports: mintLamports,
    programId: TOKEN_2022_PROGRAM_ID,
  }),
  // 2. Extension initializers MUST come before createInitializeMintInstruction
  createInitializeNonTransferableMintInstruction(mint, TOKEN_2022_PROGRAM_ID),
  createInitializePermanentDelegateInstruction(
    mint,
    authority.publicKey, // issuing authority = permanent delegate
    TOKEN_2022_PROGRAM_ID
  ),
  createInitializeMetadataPointerInstruction(
    mint, authority.publicKey, mint, TOKEN_2022_PROGRAM_ID
  ),
  // 3. Initialize the mint itself (0 decimals — credentials are whole units)
  createInitializeMintInstruction(
    mint, 0, authority.publicKey, authority.publicKey, TOKEN_2022_PROGRAM_ID
  ),
  // 4. Write metadata on-chain
  createInitializeInstruction({
    programId: TOKEN_2022_PROGRAM_ID,
    metadata: mint,
    updateAuthority: authority.publicKey,
    mint,
    mintAuthority: authority.publicKey,
    name: tokenMetadata.name,
    symbol: tokenMetadata.symbol,
    uri: tokenMetadata.uri,
  })
);

await sendAndConfirmTransaction(
  connection, createMintTx, [authority, mintKeypair]
);
console.log("✅ Mint created:", mint.toBase58());

// Create recipient's token account (authority pays)
const recipientATA = getAssociatedTokenAddressSync(
  mint, recipient.publicKey, false, TOKEN_2022_PROGRAM_ID
);

const createATATx = new Transaction().add(
  createAssociatedTokenAccountInstruction(
    authority.publicKey, recipientATA, recipient.publicKey,
    mint, TOKEN_2022_PROGRAM_ID
  )
);
await sendAndConfirmTransaction(connection, createATATx, [authority]);

// Mint 1 credential to the recipient
await mintTo(
  connection, authority, mint, recipientATA, authority,
  BigInt(1), [], undefined, TOKEN_2022_PROGRAM_ID
);
console.log("✅ Credential issued to recipient");

// === TRANSFER ATTEMPT — will fail ===
// (Try this yourself — the NonTransferable extension blocks it at simulation)

// === REVOCATION — authority burns without holder's consent ===
const revokeTx = new Transaction().add(
  createBurnInstruction(
    recipientATA,
    mint,
    authority.publicKey, // permanent delegate signs — NOT the holder
    BigInt(1),
    [],
    TOKEN_2022_PROGRAM_ID
  )
);
await sendAndConfirmTransaction(connection, revokeTx, [authority]);
console.log("✅ Credential revoked — recipient balance: 0");

What Surprised Me

Silent revocation is real. I expected revoking to require the holder's signature. It doesn't. The permanent delegate burns the token without any interaction from the holder. For compliance scenarios, that's exactly what you want — but it's worth being deliberate about who you hand this power to.

Transfer is blocked at simulation, before the chain. When I tried to transfer a NonTransferable token, the RPC rejected the transaction before it was even submitted. No gas spent, no on-chain footprint. The rejection is that clean.

Instruction order is unforgiving. Extension initializers must run before createInitializeMintInstruction in the same transaction. Put them in the wrong order and you get a cryptic error. Once I understood that extensions configure the account before the mint is initialized, the order made sense.

What Confused Me

Token accounts vs. mints. For the first few days I kept conflating these. The mint holds supply, decimals, authorities, and extensions. A token account (ATA) is where a holder's balance lives. Extensions live on the mint. Token accounts just hold tokens and follow the mint's rules.

Why so many instructions? Creating a mint with three extensions means six instructions in one transaction. The reason is modularity — you only pay for what you use. A basic mint is one instruction. A complex mint is six. Cost scales with your needs.

What Clicked

Extensions are middleware, not token types. I kept thinking of NonTransferable tokens as a different kind of token. They're not. It's the same token with a rule bolted on. Transfer fee is a rule. Permanent delegate is a rule. Rules compose.

This unlocks genuinely new primitives. Before Token-2022 extensions, soulbound + revocable in a single token was not possible on Solana without a custom program. Now it's a 50-line script. That matters.

The Real Gotchas

Save your keypairs. Generate once, save to JSON, load on every run. Generating fresh keypairs every time means your authority has no SOL on the next run.

// Save
fs.writeFileSync("authority.json", JSON.stringify(Array.from(kp.secretKey)));

// Load
const kp = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(fs.readFileSync("authority.json", "utf8")))
);

Always pass TOKEN_2022_PROGRAM_ID when working with Token-2022 mints. The default program ID in most helper functions points to the original SPL Token program. Pass the wrong one and your transactions fail with confusing errors.

Base units, not whole tokens. Every numeric parameter is in base units. With 0 decimals this is fine — 1 base unit = 1 token. With 9 decimals, BigInt(1) = 0.000000001 tokens. Always scale by 10 ** decimals.

How This Compares to Web2

Feature	Web2	Solana Extensions
Issue a credential	API call, DB entry	Mint a token with extensions
Holder keeps it forever	Require them to log in to see it	Non-Transferable: it just lives in their wallet
Revoke silently	Flip a flag in your DB, holder doesn't know	Permanent Delegate: authority burns it without consent
Verify credential	Call your API	Query the chain for the token balance
Cost	Your servers, your infrastructure	Minimal (rent-exempt account on Solana)

The shift: you don't control the infrastructure. The token is self-custody. The rules are on-chain. The program enforces them, not your API.

Going Deeper

The official Token Extensions documentation covers every extension with parameters, use cases, and CLI examples. If you're following the 100 Days of Solana challenge, the extension challenges build on each other across several days — start with a basic mint, add metadata, add transfer fees, then combine everything.
Extensions I haven't tried yet that look interesting:

Interest-bearing — display a time-adjusted balance using continuous compounding, no new tokens minted
Confidential transfers — encrypted token amounts on a public chain
Oracle-driven freezes — freeze accounts based on external data

The pattern is clear: token behavior is becoming a set of composable, declared rules. That's what programmable money looks like.

Built on Solana devnet. All code written in Node.js on Windows — no CLI available, every challenge solved programmatically using @solana/web3.js and @solana/spl-token.

Transfer Fees, Metadata, and Soulbound Tokens: A Tour of Solana Token Extensions

Lymah — Sun, 24 May 2026 23:02:29 +0000

I spent the past week building tokens on Solana. Not wrapping existing ones, not swapping — actually creating token mints from scratch, attaching economic rules to them at the protocol level, and watching a blockchain reject a transaction I told it to make. This post walks through what I built, what surprised me, and why the Token Extensions Program changes how I think about on-chain rules.

Where I Started

My background is Web2. I know how platforms build internal currencies — a database table for balances, API endpoints for transfers, middleware to collect fees, application logic to enforce rules like "this badge can't be sold." It works, but the rules live in code that can be changed, bypassed, or taken offline.

My starting question going into this was simple: what does Solana actually give you that a well-designed backend doesn't? By the end of the week, I had a concrete answer.

1: Your First Mint (It's Just an Account)

The first thing that reframes everything is understanding that a token on Solana is not a smart contract. It's an account — specifically a Mint account — that stores three pieces of state: total supply, decimal precision, and the address that's allowed to create more tokens (the mint authority).

spl-token create-token
spl-token create-account YOUR_MINT_ADDRESS
spl-token mint YOUR_MINT_ADDRESS 100

What surprised me: you can't receive tokens directly into your wallet. Every wallet needs a dedicated token account for each token type it holds. Think of your wallet as a filing cabinet — each token account is a labeled folder inside it. It felt awkward at first, but it's how Solana keeps account state fast and cheap to look up.

The Mint account is the source of truth. The token account is where your specific balance lives. One program, the SPL Token Program, manages both.

2: Metadata — Giving Your Token an Identity

A freshly minted token has no name, no symbol, nothing. In a block explorer it shows up as "Unknown Token." That's where the Token Extensions Program (Token-2022) comes in.

Instead of storing metadata in a separate account (the old Metaplex approach), Token-2022 lets you attach metadata directly to the mint account itself using the metadata extension.

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

spl-token initialize-metadata YOUR_MINT "100DaysCoin" "HUNDO" \
  "https://your-metadata-uri.json"

The result: a single mint account that holds the token's supply, decimal config, mint authority, and its name and symbol. Fewer accounts, fewer transactions, lower cost. After running this I could see 100DaysCoin (HUNDO) show up properly in the Solana Explorer on devnet.

Key insight: The URI in the metadata points to a JSON file with extended details (description, image, attributes). It's the same pattern as NFT metadata — one on-chain pointer to off-chain details.

3: Transfer Fees — Economics Without Middleware

This is where things got genuinely interesting. In Web2, collecting a percentage of every transaction means building middleware: intercept the transfer, calculate the fee, split the payment, handle edge cases. And it can be bypassed if someone finds a way around your API.

Token-2022 has a transfer fee extension that enforces collection at the program level. When you configure it on a mint, every transfer of that token automatically withholds a percentage in the recipient's account — locked there until the withdraw authority (you) sweeps it out.

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --transfer-fee-basis-points 200 \
  --transfer-fee-maximum-fee 5000000000000 \
  --decimals 9

I transferred 100 tokens at a 2% fee. The recipient received 98. Two tokens were withheld in their account, untouchable by them. Then I ran the withdraw:

spl-token withdraw-withheld-tokens YOUR_TOKEN_ACCOUNT RECIPIENT_TOKEN_ACCOUNT

Final balance: 902. The 2 tokens came home.

What tripped me up: The --transfer-fee-maximum-fee parameter is in base units, not whole tokens. With 9 decimals, 5000 base units = 0.000005 tokens — basically nothing. My first two runs had the fee capped at a fraction of a token because I forgot to scale it. The fix: multiply by 10 ** decimals.

const MAX_FEE = BigInt(5000 * 10 ** DECIMALS); // 5000 whole tokens as cap

This is the kind of thing that only clicks after you see the wrong number in your output.

4: The Full Lifecycle in One Run

Day 4 was a consolidation challenge: reproduce the entire workflow — metadata + transfer fees — from a blank terminal without notes. I built a single Node.js script that:

Created a Token-2022 mint with both metadata and transfer fee extensions
Minted 1000 tokens
Transferred 100 to a second wallet (98 received, 2 withheld)
Harvested and withdrew the fees
Printed the full token config as a summary

```Final output:

Primary wallet: 902 tokens
Second wallet: 98 tokens


Fees collected:    2 tokens

Running it clean, without errors, in one go, felt like the proof that the concepts had actually landed.

---

## Day 5: Non-Transferable Tokens — Soulbound on the Protocol

The last experiment was the most conceptually interesting. Solana's Token-2022 has a **non-transferable extension** that permanently prevents any token from that mint from moving between wallets. Not "our API won't let you" — the transaction is rejected by the token program before it even hits the chain.



```bash
spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --enable-non-transferable

I minted 10 tokens, tried to transfer 5 to a second wallet, and got this:

✗ TRANSFER REJECTED (This is correct!)
Error: Transaction simulation failed: Error processing instruction
The Non-Transferable extension blocks ALL transfers at the protocol level.

Then I burned 3 tokens — and that worked fine. Balance dropped from 10 to 7.

That distinction matters: non-transferable doesn't mean non-destructible. The holder can burn their own tokens. They just can't send them to anyone else. This is exactly the behavior you'd want for things like:

Course completion certificates
KYC verification tokens
DAO membership credentials
Event participation proofs

In Web2, preventing credential trading means application-layer rules. Here, the restriction is part of the asset itself. No backend change, no API update, no workaround possible.

What I'd Tell Myself at the Start

1. Read the error messages carefully. Solana program errors are specific. "NonTransferable" in an error isn't noise — it's the program telling you exactly which extension blocked you.

2. Base units will get you. Every numeric parameter involving token amounts is in base units. Always multiply by 10 ** decimals before passing values into instructions.

3. Extensions are set at creation time. You can't add a transfer fee to an existing mint. Design your token before you deploy it.

4. Token-2022 is the right default now. The original SPL Token Program is simpler, but Token-2022 is a strict superset. Unless you have a specific reason to use the old program, start with Token-2022.

What's Next

I'm continuing through the 100 Days of Solana challenge. Next up: diving into compressed NFTs and Solana's state compression model. If you're following along or building something similar, drop a comment — I'd like to see what you're working on.

Built on Solana devnet. All code written in Node.js using @solana/web3.js and @solana/spl-token. Windows environment — no CLI available, so every challenge was solved programmatically.

Solana's System Program: Understanding the Kernel

Lymah — Fri, 22 May 2026 06:08:17 +0000

The Question That Started It All

Three posts in, I kept running into the same address:
11111111111111111111111111111111.

It showed up as the owner of every wallet I queried.
It appeared in every transaction I decoded in
Post 3.
My explorer from Post 2
labeled it "System Program" but I didn't really
understand what that meant.

Why can't I create an account myself? Why does the
System Program have to do it? Why does every wallet
on Solana belong to it?

The answer reveals Solana's elegance: The System
Program is Solana's kernel. Like a Unix kernel
manages processes and permissions, the System Program
manages accounts and state creation. Understanding it
means understanding why Solana works the way it does.

What is the System Program?

Address: 11111111111111111111111111111111

It's an account like any other:

Owner: NativeLoader
Executable: true
Data: "system_program" (14 bytes of ASCII)
Balance: 1 lamport (rent-exempt minimum)

But it's special. It's built into Solana's validator
runtime. When you send a transaction, the System
Program enforces:

Who can transfer SOL
Who can create accounts
How much lamports accounts must hold
Account closure rules

Run this yourself and see:

solana account 11111111111111111111111111111111

The System Program — owned by NativeLoader, built
into the validator runtime itself.

Core Insight: Programs Own Accounts, Not People

Here's what breaks beginner brains:

Your wallet is NOT owned by you. It's owned by the
System Program.

Your Wallet
├── Owner: 11111111111111111111111111111111 (System Program)
├── Executable: false
├── Data: (empty)
└── Lamports: 5000000000 (your SOL)
Run this to see it yourself:

solana account <your-wallet-address>

Your wallet — owned by the System Program, not by
you. Your keypair is the authorization mechanism,
not the owner.

But you can spend from it because:

Your keypair can sign for this account
The System Program's rules say: "Only an account owner or authorized keypair can transfer from that account"
Since your keypair authorized the transfer, the System Program allows it

You don't own your account. You authorize
transactions on it. The System Program enforces
your authorization.

This is the security model: permission enforcement
is separate from asset ownership.

The System Program's Four Main Instructions

1. CreateAccount

Creates a new account owned by you or another program.

// What it does:
// 1. Allocate <space> bytes for data
// 2. Set owner to <owner> (usually your program)
// 3. Charge enough lamports to cover rent
// 4. Fund from payer's account

Cost: ~2,400 lamports for a basic account +
space × 0.00348 lamports/byte

2. Transfer

Move SOL from one account to another.

// What it does:
// 1. Decrease sender's lamports by amount
// 2. Increase recipient's lamports by amount
// 3. Verify sender's keypair signature

No fee beyond the network fee. The System Program
allows SOL transfer to any account.

3. Allocate

Increase an account's data space after creation.

// What it does:
// 1. Expand data buffer
// 2. Charge additional lamports for rent

4. Assign

Change an account's owner.

// What it does:
// 1. Set owner to <new-owner>
// 2. Only works if current owner is System Program

Example: The Lifecycle of Creating an Account

When you create a token, the Token Program does this:
User sends transaction:
│
├─> System Program.CreateAccount(...)
│ ├─ Payer: Your wallet
│ ├─ New Account: Token mint address
│ ├─ Owner: Token Program
│ └─ Space: 82 bytes
│
└─> Token Program.InitializeMint(...)
├─ Reads the new account
├─ Writes mint data
└─ Returns success
Result:
Token Mint Account
├── Owner: TokenkegQfe... (Token Program)
├── Executable: false
├── Data: (82 bytes with supply, decimals, authorities)
└── Lamports: (rent-exempt amount)
Notice the two-step pattern:

System Program creates the container — allocates space, funds rent
Token Program initializes the data — writes the mint info

This separation is the genius: the System Program
handles account creation, programs handle
initialization.

Rent: The System Program's Economic Rule

The System Program enforces rent-exemption economics.

You must hold:
(account_data_size + 128) × 0.00348 lamports/byte

// Example: 1 KB account
const dataSize = 1000;
const rentPerByte = 0.00348; // lamports
const requiredLamports = (dataSize + 128) * rentPerByte;
const requiredSOL = requiredLamports / 1e9;

console.log(`Required: ${requiredSOL} SOL`);

Check it yourself:

solana rent 1000

The exact SOL required to rent-exempt a 1KB
account. The System Program enforces this minimum
at account creation.

Note: Only 0.000000004 SOL for 1KB — rent-exemption
is cheap for small accounts. Scale this up to
10MB and it becomes meaningful.

Note on rent deprecation: Solana deprecated
ongoing rent collection, but the rent-exemption
minimum is still enforced when accounts are created.
You must fund new accounts above this threshold or
the transaction fails.

Seeing It Through the Explorer

If you built the account explorer from
Post 2,
run it against the System Program now:

node explorer.mjs 11111111111111111111111111111111

The same explorer from Post 2 — but now you know
exactly what you're looking at. NativeLoader means
this program is baked into the validator, not deployed
like other programs.

The output tells the whole story in five fields.

Why This Design?

Consistency

Every program uses the same account model. Every
account creation uses the System Program. The
protocol scales because you don't write custom
account-creation logic.

Security

The System Program is battle-tested and immutable.
Bugs there would be catastrophic. By centralizing
account logic, Solana minimizes the surface area
for vulnerabilities.

Economics

Rent exemption is managed uniformly. Everyone follows
the same rules: hold enough lamports and your account
lives forever.

Auditability

Want to know who owns an account? Read the owner
field. Solana's permission model is transparent and
on-chain.

System Program vs. Ethereum

Ethereum:

Anyone can create accounts implicitly
Storage rent is implicit through gas fees
Account ownership is straightforward

Solana:

System Program explicitly creates all accounts
Rent-exemption is explicit — you must hold a minimum balance
Account ownership is decoupled from transaction authorization — owner vs. signer are different things

Solana's model is more explicit. You see the kernel.
You can audit it. That explicitness is a feature,
not a bug.

Debugging: Common System Program Errors

"Account does not have enough lamports."

❌ You tried to create an account without funding
it enough
✅ Calculate the rent-exempt amount and include
extra lamports

"Account is not owned by the System Program"

❌ You tried to Assign an account owned by a
different program
✅ Only the System Program can Assign accounts

"Cannot allocate more space"

❌ Account is owned by something other than the
System Program
✅ Only the System Program allows re-allocation

What to Do Next

Inspect the System Program

   solana account 11111111111111111111111111111111

Check your own wallet's owner

   solana account <your-address>

Owner will always be 11111... for a standard wallet.

Check rent for different sizes

   solana rent 1000    # 1 KB
   solana rent 10000   # 10 KB
   solana rent 100000  # 100 KB

Watch how the required SOL scales with data size.

Read the System Program source The code is public. Reading it shows you the exact validation rules the entire network runs on.

Wrapping Up Epoch 1

This is the fourth and final post in my Epoch 1
Writing Challenge series. What started with
"everything is an account" ends here — with the one
program that makes the whole account model work.

If you've followed along from Post 1, you now have
a complete mental model:

Post 1 — What accounts are and why they all share five fields
Post 2 — How to query any account and read those fields directly
Post 3 — How to decode the raw binary data sitting in those fields
Post 4 — The System Program that creates, owns, and enforces rules on all of it

That's Solana's foundation. Everything else — DeFi,
NFTs, DAOs, gaming — is built on top of this.

Series: The Account Model Foundation

Part 1: The Account Model Explained
Part 2: Building an Account Explorer
Part 3: Decoding Account Data
Part 4: Solana's System Program — Understanding the Kernel (this post)

Have questions about the System Program? Ask in
the comments — I'll cover advanced patterns like
PDAs (Program Derived Addresses) in a future post.

Part of the 100 Days of Solana Epoch 1 Writing Challenge.

Decoding Solana Account Data: Three Methods Compared

Lymah — Wed, 20 May 2026 17:09:25 +0000

From Hex to Human-Readable

At the end of Post 2, my account explorer was printing this for the Token Program:

Data:
Size: 48 bytes
First 48 bytes (hex):
7436346a506...

I could see the data existed. I had no idea what it meant.

That wall of hex bytes is actually structured information — token supply, decimals, mint authority. It's just encoded in binary. This post is about the three ways I learned to decode it, what each method taught me, and when to use which.

The Problem

You've got an account. You can fetch it. But the data field is a binary blob:

data: [2, 0, 0, 0, 39, 241, 144, 177, 211, 175, 152, 184, 206, 113, 76, 68, ...]

How do you turn this into meaningful information?

This is where decoding comes in. And it turns out, there are three different ways to do it in Solana. Each has tradeoffs.

Background: Account Data is Binary Borsh

SPL (Solana Program Library) accounts use Borsh, a binary serialization format. It's deterministic, language-independent, and compact.

For example, a token mint account is 82 bytes:

Bytes 0-3:       Mint discriminator
Bytes 4-35:      Mint authority (32-byte public key)
Bytes 36-43:     Total supply (u64 = 8 bytes, little-endian)
Byte 44:         Number of decimals (u8)
Bytes 45-76:     Freeze authority (32-byte public key)

Raw bytes look like nonsense. Decoding means:

Reading bytes at specific offsets
Interpreting them as specific types
Converting little-endian → numbers

We need a reliable way to do this.

Method 1: Using a Codec Library

The cleanest approach: use @solana-program/token with its built-in decoders.

npm install @solana-program/token

import { getMintDecoder } from "@solana-program/token";
import { base58Decoder } from "@solana/codecs";

async function decodeWithCodec() {
  const connection = new Connection("https://api.mainnet-beta.solana.com");

  // Fetch the token mint
  const WRAPPED_SOL = "So11111111111111111111111111111111111111112";
  const accountInfo = await connection.getAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );

  // Decode using the official codec
  const mintDecoder = getMintDecoder();
  const decodedMint = await mintDecoder.decode(accountInfo.data);

  console.log("Method 1: Codec");
  console.log("Supply:", decodedMint.supply);
  console.log("Decimals:", decodedMint.decimals);
  console.log("Mint Authority:", decodedMint.mintAuthority);
  console.log("Freeze Authority:", decodedMint.freezeAuthority);
}

Pros:

✅ Type-safe
✅ Official/audited
✅ Handles complex types automatically
✅ No manual offset calculations

Cons:

❌ Only works for SPL types
❌ External dependency
❌ Black box — you don't see the binary

Method 2: Manual Byte-Level Parsing

Read raw bytes and extract fields yourself using DataView.

function decodeManually(data) {
  const view = new DataView(data.buffer);

  // Bytes 0-3: Skip discriminator

  // Bytes 4-35: Mint authority (public key = 32 bytes, stored as base58)
  const mintAuthBytes = data.slice(4, 36);

  // Bytes 36-43: Supply (u64, little-endian)
  const supply = view.getBigUint64(36, true);

  // Byte 44: Decimals (u8)
  const decimals = view.getUint8(44);

  // Bytes 45-76: Freeze authority
  const freezeAuthBytes = data.slice(45, 77);

  return {
    mintAuthority: base58Decoder.encode(mintAuthBytes),
    supply,
    decimals,
    freezeAuthority: base58Decoder.encode(freezeAuthBytes)
  };
}

Key gotcha: The true parameter means little-endian. Solana uses little-endian (LSB first). Get this wrong and your numbers are garbage.

// ❌ WRONG - big-endian
const supply = view.getBigUint64(36, false);  // Incorrect!

// ✅ CORRECT - little-endian
const supply = view.getBigUint64(36, true);   // Correct

Pros:

✅ Complete control
✅ Learn exactly how serialization works
✅ Works for any binary format
✅ No dependencies

Cons:

❌ Easy to get offsets wrong
❌ Tedious for complex structures
❌ No type checking
❌ Must handle endianness manually

Method 3: RPC's jsonParsed Format

Let Solana's RPC do the parsing for you:

async function decodeViaRpc() {
  const connection = new Connection("https://api.mainnet-beta.solana.com");

  const WRAPPED_SOL = "So11111111111111111111111111111111111111112";

  // Use getParsedAccountInfo instead of getAccountInfo
  const accountInfo = await connection.getParsedAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );

  const parsed = accountInfo.value.data.parsed.info;

  console.log("Method 3: RPC jsonParsed");
  console.log("Supply:", parsed.supply);
  console.log("Decimals:", parsed.decimals);
  console.log("Mint Authority:", parsed.owner);
}

Pros:

✅ One RPC call
✅ Automatic parsing
✅ Type-safe JSON response
✅ Easiest to implement

Cons:

❌ Only works for known program types
❌ Depends on RPC node supporting it
❌ Can't inspect raw data
❌ Slower than local parsing

Comparison: Real Results

I tested all three methods on Wrapped SOL (So11111111...):

Method 1 (Codec):      Supply: 10234567890000000000n, Decimals: 9
Method 2 (Manual):     Supply: 10234567890000000000n, Decimals: 9
Method 3 (RPC):        Supply: "10234567890000000000", Decimals: 9

Status: ✅ All three match!

Deciding Which to Use

Use Method 1 (Codec) if:

You're working with SPL types (tokens, mints, associated accounts)
You want type safety
You're okay with an external dependency

Use Method 2 (Manual) if:

You're parsing custom program data
You want to understand the binary format
You need maximum control
You're building low-level tools

Use Method 3 (RPC) if:

You're building quick scripts
The RPC node supports parsing your account type
Performance isn't critical
You just want the data, not the details

Real-World Example: Parsing Token Account Data

Here's where it gets practical. A token account has a different structure than a mint. Let's decode one:

async function decodeTokenAccount(address) {
  const connection = new Connection("https://api.mainnet-beta.solana.com");
  const accountInfo = await connection.getAccountInfo(new PublicKey(address));

  const view = new DataView(accountInfo.data.buffer);

  // Token account structure:
  // 0-31:   Mint (32 bytes)
  // 32-63:  Owner (32 bytes)
  // 64-71:  Amount (u64)
  // 72:     Decimals (u8)
  // 73-103: Delegate (32 bytes)
  // etc.

  const amount = view.getBigUint64(64, true);
  const decimals = view.getUint8(72);
  const realAmount = Number(amount) / Math.pow(10, decimals);

  console.log(`Token Balance: ${realAmount}`);
}

The Key Insight

Borsh serialization is deterministic: given the same account data, all three methods produce identical results. The difference is:

Implementation complexity (codec > RPC > manual)
Type safety (codec > manual > RPC)
Performance (manual > codec > RPC)
Flexibility (manual > codec > RPC)

Choose based on your use case.

Practical Debugging

When parsing fails, debug systematically:

console.log("Raw data length:", data.length);
console.log("First 10 bytes:", data.slice(0, 10));

const view = new DataView(data.buffer);
for (let i = 0; i < Math.min(64, data.length); i += 8) {
  const value = view.getBigUint64(i, true);
  console.log(`Offset ${i}: ${value} (0x${value.toString(16)})`);
}

Often the issue is:

Wrong offset (miscounted bytes)
Wrong endianness (used false instead of true)
Wrong data type (u32 instead of u64)
Missing discriminators or padding

Check the SPL source code for the exact account layout.

The Full Example

Here's a complete script using all three methods:

import { Connection, PublicKey } from "@solana/web3.js";
import { getMintDecoder } from "@solana-program/token";
import { base58Decoder } from "@solana/codecs";

const WRAPPED_SOL = "So11111111111111111111111111111111111111112";

async function compareDecodingMethods() {
  const connection = new Connection("https://api.mainnet-beta.solana.com");
  const accountInfo = await connection.getAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );

  // Method 1: Codec
  const mintDecoder = getMintDecoder();
  const m1 = await mintDecoder.decode(accountInfo.data);

  // Method 2: Manual
  const view = new DataView(accountInfo.data.buffer);
  const m2 = {
    supply: view.getBigUint64(36, true),
    decimals: view.getUint8(44)
  };

  // Method 3: RPC
  const parsed = await connection.getParsedAccountInfo(
    new PublicKey(WRAPPED_SOL)
  );
  const m3 = parsed.value.data.parsed.info;

  console.log("Supply Comparison:");
  console.log("Codec:", m1.supply);
  console.log("Manual:", m2.supply);
  console.log("RPC:", m3.supply);
}

compareDecodingMethods();

Challenge

Try parsing a token account you own:

Get the account address
Fetch it via RPC
Decode using all three methods
Verify they match

Understanding this deepens your grasp of Solana's data model.

Next in this series: Post 4 covers Solana's System Program — the kernel-level program that owns every wallet and enforces the rules that hold the whole network together.

Series: The Account Model Foundation

Part 1: The Account Model Explained
Part 2: Building an Account Explorer
Part 3: Decoding Account Data (this post)
Part 4: System Program Deep Dive (coming May 22)

Which method do you prefer? Let me know in the comments!

Part of the 100 Days of Solana Epoch 1 Writing Challenge.

Building a Solana Account Explorer: Query On-Chain Data Like a Database

Lymah — Mon, 18 May 2026 17:58:44 +0000

From Concept to Code

In Part 1 of this series, I explained that everything on Solana is an account with five fields: lamports, data, owner, executable, and rent_epoch.

That's the theory. But theory only sticks when you run it against real data.

So I built a command-line account explorer that queries any Solana address and prints all five fields in a readable format. In this post, I'll walk you through how I built it, what I learned from the output, and the three things that genuinely surprised me when I started querying real accounts.

By the end, you'll have a tool you can run against any address on the network — and a much sharper intuition for what's actually living on-chain.

What We're Building

A CLI tool that takes any Solana address and returns:

Balance in both SOL and lamports
Owner program (with friendly names for known programs)
Whether it's executable or a data account
Data size and a hex preview of the first bytes
Rent epoch

Here's what the output looks like against three different account types:

A wallet account:

The Token Program:

The System Program itself:

Same five fields. Three completely different accounts. Let's build it.

Setup

mkdir solana-account-explorer
cd solana-account-explorer
npm init -y
npm install @solana/kit

Create explorer.mjs — we use .mjs for ES module syntax with top-level await.

The Full Code

import { createSolanaRpc } from "@solana/kit";

// Known program addresses mapped to friendly names
const KNOWN_PROGRAMS = {
  "11111111111111111111111111111111": "System Program",
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA": "Token Program",
  "TokenzQdsByhw9vBi3wq3kQtj78oYCa9PzPgcGW8K3": "Token Program (SPL-2022)",
  "ATokenGPvbdGVqstVQmcLsNZAqeEoctVrGMMXuLYDJ": "Associated Token Program",
  "9xQeWvG816bUx9EPjHmaT23yfBYP5ihLeLSKcsFqrXa": "Raydium Program",
  "JUP4Fb2cqiRUcaTHdrPC8h2gNsszFildan3xnjnZALn": "Jupiter Aggregator",
  "DezXAZ8z7PnrnRJjz3wXBoRgixVpdZuvXAfqJ7DKPs1": "Magic Eden",
  "BPFLoaderUpgradeab1e11111111111111111111111": "BPF Loader (Program Upgrades)",
  "BPFLoader2111111111111111111111111111111111": "BPF Loader",
};

// Get address from command line argument
const address = process.argv[2];

if (!address) {
  console.error("❌ Error: No address provided!");
  console.error("Usage: node explorer.mjs <solana-address>");
  process.exit(1);
}

// Connect to devnet
const rpc = createSolanaRpc("https://api.devnet.solana.com");

async function exploreAccount() {
  try {
    console.log("\n🔍 Solana Account Explorer\n");
    console.log("━".repeat(60));

    // Fetch balance and account info in parallel
    const [balance, accountInfo] = await Promise.all([
      rpc.getBalance(address).send(),
      rpc.getAccountInfo(address).send(),
    ]);

    // Convert lamports to SOL
    const solBalance = (Number(balance.value) / 1e9).toFixed(9);
    console.log(`\n📍 Address:\n   ${address}\n`);
    console.log(`💰 Balance:\n   ${solBalance} SOL (${balance.value} lamports)\n`);

    if (!accountInfo.value) {
      console.log("ℹ️  This address does not exist on the blockchain yet.\n");
      console.log("━".repeat(60) + "\n");
      return;
    }

    // Resolve owner to friendly name if known
    const owner = accountInfo.value.owner;
    const ownerName = KNOWN_PROGRAMS[owner] || owner;
    console.log(`👤 Owner:\n   ${ownerName}\n`);

    // Executable flag
    const isExecutable = accountInfo.value.executable;
    console.log(
      `⚙️  Executable:\n   ${isExecutable ? "Yes (Program Account)" : "No (Data/Wallet Account)"}\n`
    );

    // Rent epoch
    console.log(`📅 Rent Epoch:\n   ${accountInfo.value.rentEpoch}\n`);

    // Data size and hex preview
    const dataLength = accountInfo.value.data.length;
    console.log(`📦 Data:\n   Size: ${dataLength} bytes\n`);

    if (dataLength > 0) {
      const displaySize = Math.min(64, dataLength);
      const dataSample = Buffer.from(accountInfo.value.data)
        .slice(0, displaySize)
        .toString("hex");
      console.log(`   First ${displaySize} bytes (hex):`);
      console.log(`   ${dataSample}`);
      if (dataLength > displaySize) {
        console.log(`   ... (${dataLength - displaySize} more bytes omitted)`);
      }
    } else {
      console.log(`   (empty)\n`);
    }

    console.log("\n" + "━".repeat(60) + "\n");
  } catch (error) {
    console.error("❌ Error exploring account:");
    console.error(error.message);
    process.exit(1);
  }
}

exploreAccount();

Run it against any address:

# Query the System Program
node explorer.mjs 11111111111111111111111111111111

# Query the Token Program
node explorer.mjs TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA

# Query your own wallet
node explorer.mjs <your-wallet-address>

What the Output Taught Me

The System Program owns itself — sort of

When I queried 11111111111111111111111111111111, I expected to see the System Program as its own owner. Instead I got NativeLoader.

That threw me until I understood: NativeLoader is the Solana runtime's built-in loader. It owns the System Program the same way a kernel owns its own system calls. The System Program is baked into the runtime at a level below the normal account ownership model. It's not a program that was deployed — it was compiled into the validator itself.

Key difference from Token Program: The Token Program is owned by BPF Loader (Program Upgrades), which means it was deployed like any other program and can be upgraded. The System Program cannot — it's part of the protocol.

The Token Program is only 48 bytes — but controls everything

Look at the Token Program output: 48 bytes of data. That's it. 48 bytes of what turns out to be a pointer — not the actual bytecode.

This is because the Token Program uses the upgradeable BPF loader pattern. The 48 bytes in the main account point to a separate program data account that holds the actual bytecode. The split exists so the program can be upgraded without changing its address.

This was my first real encounter with indirection on Solana — the account you call isn't always where the code lives.

A wallet with 0 bytes of data is a complete account

The wallet output shows Size: 0 bytes and (empty) for data. In Web2 terms that looks like a broken record — a row with no content. But on Solana, a wallet doesn't need data. Its entire purpose is to hold lamports. The owner field (System Program) and the lamports field are all it needs to function.

This is the account model in action: the structure is always the same, but some fields are intentionally empty depending on the account's purpose.

Three Things Worth Noticing in Your Own Queries

1. Compare executable accounts vs data accounts

Run the explorer on a program address and a wallet address back to back. Notice how executable: Yes vs executable: No changes everything about what that account does — even though both have identical field structures.

2. Watch the owner field

Every account you'll ever encounter is owned by exactly one program. Query five random addresses and look at what owns them. You'll start recognizing patterns: wallets owned by System Program, tokens owned by Token Program, NFT metadata owned by Metaplex's program.

3. The data field is where all the interesting stuff hides

The hex bytes in the data field aren't random — they're structured binary data that each program knows how to decode. That wall of hex is actually a token supply, or a price oracle, or a governance vote. Decoding that raw data is exactly what Post 3 covers.

The `KNOWN_PROGRAMS` Map — Why It Matters

One design choice worth explaining: the KNOWN_PROGRAMS lookup table at the top of the file.

Without it, the owner field just shows a raw base58 address like BPFLoaderUpgradeab1e11111111111111111111111. With it, you see BPF Loader (Program Upgrades) — immediately meaningful.

This is the same pattern Solana Explorer uses under the hood. As you build on Solana, you'll develop your own mental map of which program addresses do what. This table is a starter version of that map. Add to it as you encounter new programs.

Try It Yourself

# Copy the code above into explorer.mjs, then:
npm install @solana/kit

# Try these three to see the contrast clearly:
node explorer.mjs 11111111111111111111111111111111
node explorer.mjs TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
node explorer.mjs SysvarC1ock11111111111111111111111111111111

Each one will show you the same five fields, completely different values. That contrast is worth seeing with your own eyes.

What's Next

This explorer shows you the raw bytes in the data field — but doesn't tell you what they mean. A token mint's data field contains supply, decimals, and mint authority. A governance account's data field contains vote counts and proposal state. All of it is encoded in binary.

Post 3 covers exactly that: three methods for decoding raw Solana account data, from manual buffer parsing to using Anchor's IDL to using pre-built deserializers. That's where the hex bytes stop being noise and start being information.

Series: The Account Model Foundation

Part 1: The Account Model Explained
Part 2: Building an Account Explorer (this post)
Part 3: Decoding Account Data (coming May 20)
Part 4: System Program Deep Dive (coming May 22)

What address did you query first? Drop it in the comments — I'd love to see what people are exploring.

Part of the 100 Days of Solana Epoch 1 Writing Challenge.