Historically, the SPL token standard was incredibly simple. It did exactly one thing: manage a generic u64 integer. If a protocol needed anything more complex like royalties, KYC whitelists, vesting schedules, or privacy, developers had to write custom wrapper smart contracts. They had to spin up external PDAs, force users to route transactions through proprietary programs, and execute Cross-Program Invocations (CPIs) just to mutate basic state.

This fragmented liquidity, broke composability across DeFi, and multiplied smart contract attack vectors.

Token-2022 flips this architecture on its head. By pushing custom logic directly into the Mint and the Token Account via Type-Length-Value (TLV) extensions, the asset itself becomes smart. The L1 runtime handles the complexity natively, allowing decentralized exchanges, lending markets, and automated market makers to interact with heavily customized tokens without needing to trust or audit a third-party wrapper contract.

But Token-2022 is not just about massive, complex upgrades like Zero-Knowledge proofs. The standard also ships with a suite of lightweight, “utility” primitives designed to solve everyday enterprise, compliance, and UX issues.

In this final installment of our Token-2022 series, we are going to close out the toolkit. We will break down the smaller, highly effective extensions that every Solana developer needs in their arsenal: Permanent Delegates, Non-Transferable tokens, Default Account States, and Required Memos.

Permanent Delegate Extension

In the legacy SPL standard, there is a strict cryptographic boundary: Only the Token Account Owner can transfer or burn the tokens inside their wallet. The Mint Authority only has the power to create new tokens. Once those tokens land in a user’s wallet, the protocol loses all control over them. If you are building a stablecoin and need to comply with OFAC sanctions by clawing back funds from a hacked wallet, you are out of luck. If you are building an automated subscription service and need to deduct tokens every month, you have to force the user to sign a pre-approved delegation transaction which is a massive UX friction point.

Token-2022 solves this by introducing the Permanent Delegate extension.

This extension allows the token creator to designate a specific public key at the Mint level that has unrestricted, permanent transfer and burn rights over every single token account holding that asset.

Hands-on overview

To truly understand how powerful this is, let’s test it live on Devnet. We are going to create a token with a Permanent Delegate, mint it to a user, and then watch the delegate reach in and burn the user’s tokens without their signature.

Create Token

You enable this extension and specify the delegate address during the initial Mint creation. Once set, the permanent delegate has “God Mode” over the token supply.

spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --enable-permanent-delegate

We can see the created PermanentDelegate extension for our token.

Mint Token To Someone

Create token account for someone’s wallet and mint 100 tokens to him.

# create token account for someone
spl-token create-account <MINT_ADDRESS> --owner <SOME_WALLET> --fee-payer ~/.config/solana/id.json

# mint 100 tokens to someone's Token Account
spl-token mint <MINT_ADDRESS> 100 <SOME_WALLET_TOKEN_ACCOUNT> 

Burning Tokens With the delegate address

Right now, someone holds 100 tokens. In legacy SPL, only this address could touch them. But because we established a Permanent Delegate on our address, we can reach directly into this wallet’s account and burn 50 tokens.

spl-token burn <SOMEONE_TOKEN_ACCOUNT> 50

The transaction succeeds. The Token-2022 program checks the Mint, sees that We are the Permanent Delegate, bypasses Someone’s wallet ownership authority entirely, and burns the tokens.

This primitive is incredibly powerful on its own, but it unlocks a massive architectural design pattern when paired with next extension.

Non-Transferable Tokens Extension

Sometimes, you need a guarantee that a user cannot sell, trade, or transfer an asset once it lands in their wallet.

Historically, developers achieved this using a standard NFT mint to a user and immediately issue a Freeze instruction to lock the token account. This worked, but it was fragile. It required the issuer to maintain freeze authority, pay external protocol fees, and if they ever accidentally unfroze the account, the user could immediately dump the “identity” token on a secondary marketplace.

Token-2022 completely replaces this legacy NFT use-case with the Non-Transferable extension. It makes immobility a fundamental law of the Mint itself. The L1 base layer will permanently reject any Transfer instruction involving this token.

Hands-on Overview

To create a Non-Transferable token, you must apply the flag during the initial Mint creation. Once the Mint is initialized, this extension is permanently baked into the asset and cannot be disabled.

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

Note: You can mint this token to your users exactly like a normal SPL token. The restriction only applies when they try to send it somewhere else

Let’s say some address holds 100 of these tokens and tries to transfer it to another wallet.

spl-token transfer 7b7FYYVpa5xgTS3PCHAU6ZBDjD1NbwZcKCqYcMmArj4n 50 L6h2ugreR3oNmKtBCpcsMPSLg3BwLR31fSPB1iU76mp

Output

The Result: Hard Fail. The transaction will instantly revert at the protocol level with a Transfer is disabled for this mint custom program error.

Architecture 1: Native L1 Soulbound Badges

When developers hear “Non-Transferable,” they almost exclusively think of 1-of-1 NFTs. For example, issuing an on-chain graduation certificate for a developer bootcamp or a KYC verification badge.

By combining the Metadata extension (which we covered here) with 0 Decimals and the Non-Transferable extension, you can mint native, beautifully rendered L1 “Soulbound Badges” without ever touching a third-party standard.

Architecture 2: On-Chain Consumables

But the real magic happens when you apply the Non-Transferable extension to a Fungible token (for example with 9 decimals) and combine it with the Permanent Delegate we just built previously.

This creates the perfect architecture for On-Chain Consumables or Prepaid Credits. Imagine an RPC node provider, a decentralized AI compute network, or an in-game economy. A user buys 1,000 API credits.

1. Because the tokens are Non-Transferable, you guarantee the user cannot create an AMM liquidity pool to dump their unused credits and crash your internal economy. They can only hold them.

2. Because your protocol backend holds the Permanent Delegate key, your server can automatically execute a Burn instruction to destroy tokens directly from the user’s wallet every time they make an API call.

The user gets transparent, on-chain accounting of their prepaid credits, and the protocol gets absolute economic security without sacrificing UX.

Example

spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --enable-permanent-delegate --enable-non-transferable

What about manual burning?

A common developer assumption is that “non-transferable” means the token is permanently stuck in the user’s wallet forever. This is a massive UX risk what if a user receives a malicious or spam soulbound token and wants to clean up their wallet?

Non-transferable does not mean non-burnable. Even though the base layer blocks the Transfer instruction, the Token-2022 program still allows the account owner to execute a standard Burn instruction. Users always retain the ultimate authority to destroy assets in their own wallets to prevent permanent spam.

Default Account State Extension

If you are building a regulated protocol like an enterprise stablecoin, a real estate RWA (Real World Asset), or a strict KYC ecosystem, you need absolute control over who can hold and move your token.

By configuring this extension at the Mint level, you can force the L1 runtime to automatically initialize every single new Token Account in a Frozen state. Users can create their accounts to receive the asset, but they cannot send or receive tokens until your backend server verifies their KYC status and explicitly unfreezes their specific account.

Hands-on Overview

To use this, you must apply the --default-account-state frozen flag during Mint creation. Because you will eventually need to unfreeze compliant accounts, you must also stack the --enable-freeze flag so your protocol retains the Freeze Authority.

# Create a compliance-gated Mint
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --default-account-state frozen --enable-freeze

Output

If someone creates an account for this token, it is frozen the millisecond it is initialized. Any incoming or outgoing transfers will revert until your protocol explicitly thaws their account.

Lets say that now someone creates his own token account and did not submit all the required data to our backend server, and our automated system accidentally tries to mint to this token account

spl-token mint <MINT_ADDRESS> 100 <SOME_TOKEN_ACCOUNT>

Output

It will fail with “account is frozen“ error. The transaction reverts perfectly at the runtime level. The Token-2022 program recognizes that this account is completely locked. It cannot receive incoming mints or transfers, and it cannot send tokens out.

Now lets say that this user submitted all the required data. Our backend verifies the identity and executes a Thaw instruction to unlock her specific Token Account.

spl-token thaw <SOME_TOKEN_ACCOUNT>

Output

Now that this user is legally verified and the account is thawed, Our backend tries the exact same mint command again.

spl-token mint <MINT_ADDRESS> 100 <SOME_TOKEN_ACCOUNT>

Output

The Result: Success. This user receives the 100 tokens, fully compliant with the protocol’s L1 rules.

Required Memo on Transfer

If you have ever deposited tokens into a centralized exchange (CEX - centralized exchange), you know the panic of forgetting the “Deposit Memo.”

Because exchanges use massive, shared omnibus wallets to collect user deposits, they rely on attached text memos to map an incoming L1 transfer to a specific user’s database ID. The Required Memo on Transfer extension solves this at the protocol level.

Unlike the previous extensions we discussed, this is an Account Extension, not a Mint extension. It is applied by the owner of the Token Account, not the creator of the token.

Hands-on Overview

Let’s say your protocol’s treasury wallet (Alice) wants to ensure that no one can blindly dump tokens into her account without explaining what the transfer is for. Alice simply enables the extension on her specific Token Account.

# Alice enforces memos on her own Token Account
spl-token enable-required-transfer-memos <ALICE_TOKEN_ACCOUNT_ADDRESS>

Output On Explorer

Now we see that the Memo is Required, if someone tries to run a standard transfer command to Alice’s account:

spl-token transfer <MINT_ADDRESS> 50 <ALICE_TOKEN_ACCOUNT_ADDRESS>

Output

The Result: Hard Fail. The transaction reverts at the runtime level because the destination account requires a memo, and none was provided.

To successfully send tokens to Alice, the sender is now mathematically forced to attach a memo string to the transaction instruction:

# The sender must explicitly attach the memo for the transaction to succeed
spl-token transfer <MINT_ADDRESS> 50 <ALICE_TOKEN_ACCOUNT_ADDRESS> --with-memo "Invoice payment for Q3 RPC node hosting"

Output

Summary

Over the course of this series, we have covered Metadata, Transfer Hooks, Interest-Bearing Mints, Confidential Transfers, and finally, the core Utility Primitives.

If there is one major takeaway for developers, it is that the this blog’s architecture is no longer just a theory it is the standard. Token-2022 shifts complex, vulnerable logic out of custom smart contracts and pushes it natively into the L1 asset itself.

By stacking these extensions, you can build a stablecoin that natively yields interest, shields transfer amounts with Zero-Knowledge proofs, automatically freezes non-compliant accounts, and blocks unknown deposits, all without writing or deploying a single line of Rust.

The standard is here. It is time to start building.

Historically, solving the privacy problem has meant abandoning the Layer-1 execution environment. Developers have been forced to spin up complex Layer-2 Zero-Knowledge (ZK) rollups, manage off-chain provers, or fragment their liquidity into isolated privacy pools.

Solana’s Token-2022 standard changes this by bringing the cryptography directly to the base layer.

With the introduction of the Confidential Transfers extension, Token-2022 embeds native Zero-Knowledge proofs and Twisted ElGamal encryption directly into the SPL token standard. Instead of moving assets to a separate network to obfuscate them, the tokens themselves carry encrypted state. The runtime mathematically proves to the network that a transfer is valid, ensuring no tokens were secretly minted or burned without ever revealing the actual transfer amount or the underlying account balances.

Just like the Interest-Bearing extension shifted yield from state mutation to pure computation, the Confidential Transfer extension shifts privacy from off-chain infrastructure to native, on-chain cryptography.

However, encrypting and decrypting state natively on the BPF runtime requires a radical shift in how we handle token routing. A standard transfer no longer just subtracts from Account A and adds to Account B. Instead, it introduces complex cryptographic states like “pending balances” and requires explicit ZK-proof verification instructions.

In this deep dive, we are going to unpack the architecture of the ConfidentialTransfer extension. We will break down the encrypted state layout and inspect the raw ciphertexts using the Solana CLI.

What are Confidential Transfers

When developers first hear “Confidential Transfers,” they often assume it is a privacy coin mixer like Tornado Cash. It is not. Token-2022 Confidential Transfers do not obfuscate the transaction graph.

If Alice sends a confidential transfer to Bob, the network (and anyone looking at a block explorer) can still see:

• The Sender: Alice’s wallet address.

• The Receiver: Bob’s wallet address.

• The Token: The specific Mint address being transferred.

What the network cannot see is the amount of tokens transferred and the underlying balances of Alice and Bob’s accounts.

To achieve this, Token-2022 introduces a dual-state architecture. A single token account now holds two entirely separate balances:

1. The Public Balance: The standard u64 integer representing public tokens (fully transparent).

2. The Confidential Balance: Cryptographic ciphertexts representing encrypted tokens.

These two balances exist side-by-side. Tokens enter the encrypted ecosystem via a Deposit instruction, where a user converts their public tokens into an encrypted ciphertext. However, once those tokens are shielded, they can circulate privately forever. If you receive a confidential transfer from a friend or an employer, you never have to touch the public balance, you can simply hold, transfer, or spend those encrypted tokens using Zero-Knowledge proofs (will be explained shortly). If you ever want to exit the shielded ecosystem, you execute a Withdraw instruction, decrypting the ciphertext and moving the funds back to your public balance.

Initializing the Cryptographic State via CLI

To truly understand how this dual-state architecture works, we need to look at it on-chain. Let’s use the Solana CLI to create a confidential token, fund a user’s account, and watch the state transition from public to encrypted.

Creating the Mint

First, we initialize a Token-2022 mint and explicitly tell the program to allocate the ConfidentialTransfer extension.

spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --enable-confidential-transfers auto

Note: The auto keyword means that any token user can permissionlessly configure their account to perform confidential transfers.

Configuring the User’s Token Account

Next, we create a standard token account for our wallet. However, a standard token account can only hold a public u64 balance. We must explicitly configure the account to allocate the extra bytes required to hold the ElGamal ciphertexts.

# Create the base token account
spl-token create-account <YOUR_MINT_ADDRESS>

# Allocate the cryptographic extension and generate the ElGamal keypair
spl-token configure-confidential-transfer-account <YOUR_MINT_ADDRESS>

Under the hood, this second command does something important, it generates a Twisted ElGamal keypair (will be explained shortly) locally on your machine and stores the public key directly on the token account. This is the key the Token-2022 program will use to encrypt your incoming transfers.

The Public-to-Confidential Deposit

Now that our account is configured for cryptography, let’s give ourselves 100 public tokens.

spl-token mint <YOUR_MINT_ADDRESS> 100

lets take a look at the token account state

spl-token display <TOKEN_ACCOUNT_ACCRESS>

We can see that the public balance is 100 and still not encrypted.

To enter the shielded state, we must deposit these public tokens into the encrypted balance.

spl-token deposit-confidential-tokens <YOUR_MINT_ADDRESS> 100

and run the display again

spl-token display <TOKEN_ACCOUNT_ACCRESS>

This is where the magic happens. The Token-2022 program deducts the 100 from your public amount, encrypts the number 100 using your account’s ElGamal public key, and writes the resulting ciphertext to the ConfidentialTransferAccount TLV extension.

right now, your public balance will show 0, but your funds are not gone, they are locked inside the cryptographic state, ready to be transferred with Zero-Knowledge proofs.

Note: Even though your CLI wallet holds the ElGamal private key locally, the standard spl-token CLI currently lacks a --decrypt flag. Instead of a clean integer, you will be staring at raw, encrypted bytes, the actual Pedersen commitments and ciphertexts living on the BPF runtime. To see the human-readable number 100, you must write a custom client-side script to manually fetch the state and decrypt the ciphertext locally.

open github issue: https://github.com/solana-program/token-2022/issues/145

A High-Level Overview of the Cryptography of Encrypted State

To understand the architecture, lets understand the core problem.

Imagine Alice wants to send Bob 10 tokens. On a standard SPL token, the runtime simply checks if Alice has >= 10 tokens and if so subtracts 10 from her balance, and adds 10 to Bob’s balance.

If we want to make this confidential, the most obvious solution is to encrypt the token balances before writing them to the account data. But this introduces an immediate architectural roadblock: if the Token-2022 program cannot read the raw numbers because they are encrypted, how can it execute the transfer? It cannot natively subtract 10 from Alice’s account if it doesn’t know what her balance is.

Linear Homomorphism

To solve this, Token-2022 relies on a class of encryption called Linear Homomorphism.

A linearly homomorphic encryption scheme allows mathematical operations, like addition and subtraction to be performed directly on encrypted ciphertexts, yielding a result that perfectly matches the encrypted sum or difference of the underlying plaintexts.

When Alice initiates a confidential transfer, she doesn’t pass the raw number 10 to the program. Instead, she generates an encrypted ciphertext of the transfer amount. The Token-2022 program simply takes Alice’s encrypted account balance, subtracts the encrypted transfer amount, and saves the new ciphertext back to her state. It then takes Bob’s encrypted balance, adds the encrypted transfer amount, and saves it.

Encrypted(50) - Encrypted(10) = Encrypted(40)

Because the math is homomorphic, the Solana runtime successfully processes the transfer without ever knowing that the underlying numbers were 50, 10, and 40.

Zero-Knowledge Proofs - Trust but Verify

If the program never decrypts the underlying numbers, what stops a malicious user with an encrypted balance of 50 from sending an encrypted transfer of 70? Or what stops them from sending a negative amount to mathematically inflate their own balance?

Because the token program cannot natively see the hidden inputs, every confidential transfer must be accompanied by Zero-Knowledge (ZK) Proofs generated locally by the sender’s wallet:

1. Range Proofs: The sender must prove that the transfer amount is a positive 64-bit integer, and that subtracting this amount from their current balance will leave a value >= 0.

2. Equality Proofs: The transfer amount is encrypted twice, once under the sender’s public key to deduct it and once under the receiver’s public key to add it. The sender must mathematically prove that both ciphertexts encrypt the exact same underlying value.

Token-2022 passes these proofs to Solana’s native ZK Token Proof program. Once the ZK program verifies the math is sound, Token-2022 executes the homomorphic addition and subtraction.

More detailed reference can be found here.

Preventing Cryptographic Griefing with the Split State Architecture

Encrypting state and using ZK proofs creates a unique new attack vector that doesn’t exist in standard transparent tokens: Cryptographic Front-Running.

To submit a valid transfer, Alice must generate her ZK proofs locally on her machine. This proof is mathematically tied to her current encrypted account balance on-chain. Generating this proof takes computational time (often a few seconds on a standard client).

Imagine Alice generates a proof based on her encrypted balance of 50 tokens and submits the transaction to the network. However, milliseconds before her transaction lands, a malicious actor (or just a busy protocol) transfers 1 token to Alice.

Because of the homomorphic math, that incoming 1 token mutates Alice’s encrypted state on-chain. When Alice’s transaction finally hits the Token-2022 program a fraction of a second later, the ZK proof she generated is instantly rejected because it was built against the old ciphertext.

If an attacker continuously flooded Alice’s account with micro-transfers (dusting), they could constantly mutate her state, making it mathematically impossible for her to ever generate a valid ZK proof fast enough to send an outgoing transfer. Her account would be permanently bricked.

The Solution: Splitting the Balance

To solve this, Token-2022 fundamentally alters the Token Account layout. The ConfidentialTransferAccount TLV extension splits the encrypted balance into two entirely separate ciphertexts:

1. available_balance

2. pending_balance

When Alice sends tokens out, the Token-2022 program subtracts the ciphertext strictly from her available_balance. When someone sends tokens to Alice, the program adds the ciphertext strictly to her pending_balance.

This strict separation guarantees that nobody but Alice can mutate her available_balance. Because her ZK proofs are generated exclusively against her available_balance, incoming transfers can no longer invalidate her outgoing proofs. The attack vector is completely neutralized.

However, this architecture introduces an integration trap.

The Mechanics of the Pending Balance

The split-state architecture solves the cryptographic front-running problem. Because incoming transfers only hit your pending_balance, your available_balance remains completely static. This ensures that the ZK proofs your client is busy generating locally will never be invalidated by unexpected network traffic.

However, this architectural safeguard introduces a necessary friction point in the token lifecycle: Incoming funds are not immediately spendable.

If Alice sends you 50 encrypted tokens, the Token-2022 program homomorphically adds the transfer ciphertext to your pending_balance ciphertext. Your available_balance remains untouched. Because outgoing transfers can only deduct from the available_balance, those 50 tokens are effectively parked in a cryptographic waiting room.

The State Sweep - Apply Pending Balance

To actually spend received funds, the account owner must explicitly instruct the Token-2022 program to merge the two ciphertexts. This is done via the ApplyPendingBalance instruction.

spl-token apply-pending-balance <MINT_ACCOUNT>

When this instruction is fired, it triggers a deterministic state transition on-chain. The Token-2022 processor:

1. Takes the current pending_balance ciphertext.

2. Homomorphically adds it to the available_balance ciphertext.

3. Overwrites the available_balance with the new combined ciphertext.

4. Resets the pending_balance ciphertext to a zero-value encryption.

Note: This is done manually because by forcing the account owner to explicitly call ApplyPendingBalance, the protocol guarantees that the available_balance only ever mutates exactly when the user wants it to. You control your own state updates, ensuring your local ZK proof generation environment remains perfectly stable.

The Transfer Trap: Failing vs Succeeding hands on

Let’s prove that the 100 tokens we just deposited are unspendable in their current state. We will try to send 50 confidential tokens to a friend.

Prerequisite: The Receiver Opt-In Handshake

If you try to send confidential tokens to a standard public wallet, the transfer will instantly fail because to send an encrypted transfer, your local client must encrypt the transfer amount using the receiver’s ElGamal public key.

If Bob hasn’t explicitly opted into the shielded ecosystem, he doesn’t have an ElGamal keypair attached to his account. You cannot force-send privacy tokens, it is a two-way handshake. Before we can route tokens to Bob, he must create an account and configure his cryptography:

# Bob creates his token account
spl-token create-account <YOUR_MINT_ADDRESS> --owner bob.json

# Bob generates his ElGamal keypair and appends it to his account
spl-token configure-confidential-transfer-account <YOUR_MINT_ADDRESS> --owner bob.json

The Fail Case

Now that Bob is mathematically ready to receive encrypted funds, let’s execute the transfer. We must pass the --confidential flag, otherwise the CLI will attempt a standard public routing.

spl-token transfer <MINT_ACCOUNT> 50 <BOB_TOKEN_ACCOUNT> --confidential

Output

The program fails because it specifically attempts to deduct 50 tokens from your Available Balance, which is mathematically zero. Your 100 tokens are still stuck in the Pending Balance ciphertext.

The Success Case

To actually spend these received funds, you must explicitly instruct the Token-2022 program to mathematically merge the two ciphertexts. This is done via the ApplyPendingBalance instruction.

Note: If you pass your Token Account address directly to this command, the CLI will hallucinate a fake Associated Token Account and throw an Account not found error. You must either pass the Mint address

spl-token apply-pending-balance <MINT_ADDRESS>

The Token-2022 takes the current pending_balance ciphertext, homomorphically adds it to the available_balance ciphertext, overwrites the state, and resets the pending balance to zero.

Now that the sweep is complete, our 100 tokens have safely moved into our Available Balance. If we run the exact same transfer command again

spl-token transfer <MINT_ACCOUNT> 50 <BOB_TOKEN_ACCOUNT> --confidential

Output

The Withdraw Instruction - Exiting the Shielded State

Finally, what happens when a user wants to exit the shielded ecosystem? Perhaps you want to view your raw balance on a standard block explorer, or you need to interact with legacy Solana infrastructure that doesn’t support the ConfidentialTransfer extension.

You must transition the state from encrypted back to public using the Withdraw instruction.

spl-token withdraw-confidential-tokens <MINT_ADDRESS> 100

Output after running the display command

This instruction is the exact inverse of the Deposit we ran in preiously. When you deposit, you are just encrypting a public number. But when you withdraw, you are asking the public network to subtract a specific amount from an encrypted balance.

To execute this, your local client must do the heavy lifting:

1. It uses your local ElGamal private key to decrypt your current available_balance.

2. It verifies you actually have >= 100 tokens.

3. It generates a ZK proof mathematically verifying that subtracting 100 from the ciphertext is valid and will not result in a negative number.

It sends this proof to the network. The Token-2022 program verifies the proof via the ZK Token Proof program, homomorphically subtracts the ciphertext of 100 from your available_balance, and explicitly adds the raw integer 100 back to your public amount field. Your funds are now public again.

A Brief Note on Smart Contract Integration

Note: If you are writing a smart contract, say, a payment router or an automated market maker, and it receives a confidential transfer, the contract cannot immediately route those tokens in the next instruction. The funds will be stuck in the contract’s pending_balance. Your program must execute a Cross-Program Invocation to trigger ApplyPendingBalance to merge the ciphertexts before attempting any outgoing transfers. Forgetting this single CPI will cause every incoming transaction to your protocol to hard-fail.

Summary

The Token-2022 Confidential Transfer extension is a masterclass in natively integrating zero-knowledge cryptography into a high-performance runtime.

By pushing the encryption directly to the L1 standard:

1. Liquidity Remains Unified: Developers no longer have to bridge assets to isolated Layer-2 ZK-rollups to achieve privacy.

2. State is Protected: The pending vs. available balance split brilliantly neutralizes the cryptographic griefing vectors that plague other privacy networks.

3. Math Replaces Trust: Linear homomorphism ensures the base layer can blindly but flawlessly execute accounting without ever compromising user data.

In the traditional DeFi stack, engineering a yield-bearing asset has always been a battle against state bloat and compute costs. If you saw systems around EVM rebasing tokens, think of stETH as example, you know the architectural headaches they introduce. To reflect accrued interest, an EVM protocol must either continuously update storage slots across thousands of user accounts (which is expensive) or rely on a complex “shares-to-balances” mathematical abstraction under the hood, forcing every integrating smart contract to implement custom logic just to read a user’s true balance.

Solana’s Token-2022 standard completely flips this paradigm. Instead of fighting state mutations, it eliminates them entirely.

With the introduction of the Interest-Bearing Mint Extension, Solana introduces the concept of “Cosmetic Yield.” At the state level, the raw token amount residing in a user’s Token Account never changes. There are no rebasing events, no automated yield-harvesting cranks, and no state bloat. Instead, the accrued interest is calculated mathematically and continuously at the UI and RPC layer based on the network’s clock. The protocol simply applies a continuous compounding formula:

to the static principal.

Just as Transfer Hooks modularized transfer logic by pushing it to external programs, the Interest-Bearing extension modularizes yield by separating the configuration of the interest rate from the execution of the math. It relies heavily on a strict separation between execution logic in processor.rs and pure mathematical interfaces mod.rs.

In this post, we are going to get under the hood of the InterestBearingConfig. We will break down the Rust implementation, explore the continuous compounding math, and look at the architecture.

The Architecture of Cosmetic Yield vs. State Mutation

To truly appreciate the engineering behind Solana’s Interest-Bearing extension, we first have to look at the problem it solves. In blockchain architecture, state is expensive, and mutating state across thousands of accounts simultaneously is almost impossible.

The EVM Bottleneck: Rebasing and Shares

If you look at the successful yield-bearing assets on the EVM for example Lido’s stETH Token it rely on state mutation. Because an ERC-20 balanceOf function needs to return a constantly growing number to reflect yield, EVM developers had to get creative.

They introduced the “shares” model. Under the hood, your wallet doesn’t actually hold stETH, it holds a static number of shares of the total pool. When you call balanceOf(user), the smart contract executes a calculation:

Here is where the architectural bottleneck occurs. While UserShares and TotalShares remain relatively static, the actual amount of ETH backing the protocol on the Beacon Chain is constantly growing. However, the Ethereum execution layer smart contract is entirely isolated from this growth. The variable TotalPooledEther is just a static number sitting in contract storage. It cannot update itself.

For users to actually see their stETH balances increase, an external Oracle (a bot) must explicitly broadcast a transaction to the smart contract every period of time. This transaction calls a function that overwrites the global TotalPooledEther state variable to reflect the new yield. Because that global variable was changed, the math equation now outputs a higher number for every single user. But getting that higher number required an active transaction, gas fees, and a global state write.

Solana’s Token-2022 Approach: Computation over State

Solana’s architecture prioritizes parallel execution and isolated account state. Forcing a global state update to reflect yield across all token holders would create massive write-locks, crippling network throughput.

Token-2022 solves this by shifting the burden entirely from state storage to computation. This introduces the concept of Cosmetic Yield.

When an interest-bearing mint is initialized, the raw amount stored in a user’s Token Account (a simple u64 integer) represents only the principal: the exact original baseline number of tokens the user received. This raw principal amount never changes, even as the tokens earn yield. Instead of mutating the state to add the newly accumulated profit, the yield is calculated dynamically. No automated cranks, no oracle updates, and no global state mutations are required to generate this yield. The state remains static, while the math handles the growth.

The uiAmount Abstraction (Where the Yield Lives)

If the raw balance doesn’t change, and no oracle is updating a global variable, how does the user actually see their money growing?

This is where the uiAmount comes in. In the Token-2022 standard, the interface makes a strict distinction between the raw amount (the state) and the uiAmount (the human-readable representation).

Instead of relying on an external party to push updates, the Solana Token-2022 program pulls its truth from the Network Clock. The Mint account holds an InterestBearingConfig, which stores the initialization timestamp and the current interest rate in basis points.

Because the network clock (Clock::get()?.unix_timestamp) inherently advances with every single block, the input to the continuous compounding formula

is always growing automatically.

When a dApp, wallet, or RPC node queries a user’s balance, it doesn’t just read the static integer. Instead, it calls the program’s amount_to_ui_amount instruction (will be explained shortly). This routes the query directly through the extension’s math engine. The program fetches the current network timestamp, calculates the accrued interest purely in memory, and returns the combined total as a formatted string (the uiAmount). The protocol completely bypasses the need for state-mutating transactions; the state remains static, while the math handles the growth.

The Math: Continuous Compounding On-Chain

Now that we understand the yield is calculated dynamically rather than stored in state, we have to ask: how is the math actually executed? If you have written smart contracts before, you know that floating-point math and exponential calculations are generally the enemy of blockchain development. They consume massive amounts of compute units and introduce rounding errors that can easily be exploited. Yet, the Token-2022 program handles this seamlessly using continuous compounding.

The Formula

The core mathematical engine of the Interest-Bearing extension relies on the standard continuous compound interest formula:

Here is exactly how these variables map to the Solana Token-2022 architecture:

• A (Final Amount): The final ui_amount that includes the accrued yield.

• P (Principal): The raw amount of tokens stored in the user’s Token Account (which never mutates).

• e (Euler’s Number): The mathematical constant ~2.71828.

• r (Rate): The annualized interest rate. On-chain, this is configured in basis points (where 10,000 bps = 100%) and converted to a decimal during the calculation.

• t (Time): The time elapsed in years. Solana tracks this natively using the Unix timestamp in seconds, which the math engine divides by 31,556,736 (the number of seconds in a 365.24-day year).

reference can be found here.

The State Variables: Handling Rate Changes Without State Mutations

A major architectural challenge arises when the rate_authority decides to change the interest rate. If a token yielded 5% for the first six months, and the authority updates it to 10%, the protocol cannot retroactively apply 10% to the entire lifespan of the token.

If this were an EVM rebasing token, changing the rate would require a massive, O(N) state-mutating “checkpoint” transaction to lock in every individual user’s balance at the 5% rate before starting the 10% epoch.

Token-2022 solves this elegantly within the InterestBearingConfig Type-Length-Value (TLV) layout stored directly on the Mint account. It tracks three crucial variables (will be explained more in the next section):

• current_rate: The active interest rate in basis points.

• last_update_timestamp: The exact Unix timestamp of the last rate change.

• pre_update_average_rate: The time-weighted average rate of all compounding periods prior to the last update.

fn process_update_rate(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    new_rate: &BasisPoints,
) -> ProgramResult {
    // ... Authority validation checks omitted for brevity

    let clock = Clock::get()?;
    
    // Calculate the historical average up to this exact second
    let new_average_rate = extension
        .time_weighted_average_rate(clock.unix_timestamp)
        .ok_or(TokenError::Overflow)?;
        
    // Lock in the historical average
    extension.pre_update_average_rate = new_average_rate.into();
    
    // Move the checkpoint timestamp forward to the current block
    extension.last_update_timestamp = clock.unix_timestamp.into();
    
    // Set the new active rate
    extension.current_rate = *new_rate;
    Ok(())
}

Notice what is completely absent from this function: there is no iteration over token accounts. Zero user balances are touched.

The protocol simply calculates the new pre_update_average_rate up to the current block time, moves the last_update_timestamp forward, and sets the new current_rate inside the Mint’s TLV extension. When a user’s balance is calculated tomorrow, the math engine simply uses the locked historical average for the past, and the new active rate for the present.

Full code can be found here.

The Checkpoint in Practice

Now that we have seen the raw Rust logic, let’s watch the Token-2022 program execute this checkpointing in real-time. To see exactly how the state mutates without touching user accounts, we are going to use the Solana CLI to create a token, inspect its abstracted state, and trigger an interest rate change.

Creating the Mint

First, we initialize a Token-2022 mint and tell the program to allocate space for the InterestBearingConfig TLV extension. We are going to set the initial rate to 5% (which is 500 basis points).

spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --interest-rate 500

Output:

Creating token Dmcd... (your new mint address)
Signature: 4j...

Inspecting the Abstracted State

Now that the mint is live, we can look at the exact bytes stored in the account data using the display command.

spl-token display <YOUR_MINT_ADDRESS>

If you look closely at the output, the CLI decodes the Interest-bearing extension block. It will look like this:

Extensions
  Interest-bearing:
    Current rate: 500bps
    Average rate: 500bps
    Rate authority: <YOUR_WALLET>

Because the token was just created, the Average rate and Current rate are identical (500 bps). However, the CLI is actually hiding some crucial data here for the sake of a clean UI. Under the hood, the raw Rust struct is also storing the initialization and update timestamps. The math engine knows that, as of this exact moment, the token earns 5%.

Triggering the Checkpoint (Updating the Rate)

Let’s say six months pass. We want to update the rate to 10% (1000 basis points). As the Rate Authority, we fire the set-interest-rate command:

spl-token set-interest-rate <YOUR_MINT_ADDRESS> 1000

If we immediately run spl-token display <YOUR_MINT_ADDRESS> again, we will see the Token-2022 math engine has safely mutated the Mint’s state:

Extensions
  Interest-bearing:
    Current rate: 1000bps
    Average rate: 500bps
    Rate authority: L6h2ugreR3oNmKtBCpcsMPSLg3BwLR31fSPB1iU76mp

Look at what just happened: Zero user accounts were touched. Instead, the Mint locked its own history.

Behind the scenes, the program updated its hidden last_update_timestamp to the current network clock. When a frontend UI or an RPC node calculates a user’s yield tomorrow, it simply breaks the continuous compounding formula into two distinct chunks:

1. The Past: It looks at the time between the creation and the hidden update timestamp, applying the Average rate (1 year 5%).

2. The Present: It looks at the time since the last update up to the current block time, applying the new Current rate (0.5 years 10%).

Peeking Under the Hood: Finding the Hidden Timestamps

While the CLI conveniently formats the output for a clean terminal experience, as developers, we need to know what the math engine is actually reading.

If you take that same Mint address, plug it into a Solana block explorer, and look at the raw on-chain data, the UI abstraction falls away. You will see the complete JSON representation of the interestBearingConfig extension exactly as it lives on the network:

Here, the hidden architecture is fully exposed. You can clearly see the initializationTimestamp and the lastUpdateTimestamp that the continuous compounding formula inherently relies on to slice the yield curve into the “Past” and the “Present” without touching a single user’s token account.

The Abstraction Layer and the BPF Math Engine

The entire architecture of the Interest-Bearing extension hinges on a strict separation between state storage and presentation. In the Token-2022 standard, there is a hard boundary between the amount (the raw u64 integer stored in the database) and the uiAmount (the mathematically yielded float presented to the user).

If a developer or indexer bypasses this abstraction layer and attempts to read the raw state directly, the architecture breaks down visually. Look at this screenshot from a popular Solana block explorer attempting to render the exact Mint we just updated:

The Raw Data Trap

When we used the CLI to update the rate, we passed the integer 1000. In the Rust engine, this strictly represents 1000 basis points (bps), which equates to exactly 10%.

Because the block explorer bypassed the program’s native math engine and directly deserialized the raw currentRate bytes from the Mint’s TLV extension and appended a % sign to the raw integer. The result is a frontend mistakenly advertising a 1,000% APY.

This highlights a critical architectural constraint: You cannot natively trust the raw state of an Interest-Bearing token.

To safely bridge the gap between the static state and the continuous compounding math, the Solana developers introduced two specific, native instructions to the Token-2022 program:

1. AmountToUiAmount

2. UiAmountToAmount

Instead of forcing RPC nodes or other programs to import a math library and attempt to recreate the

formula locally, these instructions allow you to query the program directly. You pass the raw u64 amount into the instruction, and the Token-2022 program executes the exponential math using the Mint’s exact timestamps, returning the formatted string.

Querying the Math Engine

To safely bridge the gap between the static state and the continuous compounding math, the Solana developers built the yield conversion directly into the RPC layer.

Before we can query a balance, we actually need a token account with some principal in it. Let’s use the CLI to create an account for our Mint and give ourselves 100 tokens.

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

Now, let’s imagine a few hours pass. To see the yield in action, we can query that specific token account using a standard curl request to the getTokenAccountBalance RPC method:

curl https://api.devnet.solana.com -X POST -H "Content-Type: application/json" -d '
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTokenAccountBalance",
  "params": [
    "<YOUR_TOKEN_ACCOUNT_ADDRESS>"
  ]
}'

When the RPC node receives this request, it detects the Interest-Bearing extension, runs the exponential math using the Mint’s hidden timestamps, and returns both numbers simultaneously:

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "apiVersion": "3.1.10",
      "slot": 448286815
    },
    "value": {
      "amount": "100000000000",   <-- The raw principal (100 tokens with 9 decimals)
      "decimals": 9,
      "uiAmount": 100.009224922,  <-- The mathematically yielded balance!
      "uiAmountString": "100.009224922"
    }
  },
  "id": 1
}

Notice what is completely absent from this JSON response? The interest rate itself.

You don’t have to fetch the 1000 basis points from the Mint, and you don’t have to manually calculate whether that means 10% or 1,000%. The RPC node handled the basis-point conversion, fetched the network clock, and ran the

formula entirely under the hood. The uiAmount already contains the correct yield.

By relying on the RPC (or the native on-chain CPI) to execute the math, your protocol becomes completely immune to the kind of frontend parsing bugs we saw on the block explorer. The hard boundary is perfectly clear: the amount stays static, but the uiAmount safely delivers the continuously compounding truth.

Summary

To wrap up, the Token-2022 Interest-Bearing extension represents a fundamental architectural shift from state storage to computation:

• No State Bloat: Unlike EVM rebasing tokens that require constant Oracle transactions to mutate global state, Solana calculates yield dynamically using continuous compounding

  driven by the network clock.

• Checkpointing the Mint: Interest rate changes lock historical averages directly into the Mint’s TLV configuration. This completely bypasses the need to iterate over or mutate individual user accounts.

• The Abstraction Layer: A user’s raw amount is strictly static principal. To get the true yielded balance, developers cannot just read the raw state, they must query the program’s math engine directly via RPC or on-chain CPI.

Ultimately, it is an elegant, compute-heavy solution to EVM state bloat, paving the way for highly scalable, natively yielding assets.

The Solana Token-2022 standard introduces a paradigm shift in how developers manage digital assets. Among these extensions, Transfer Hooks represent the most powerful capability, allowing protocols to execute custom, synchronous on-chain logic every time a token is transferred. This enables use cases ranging from compliance enforcement and dynamic royalties to sophisticated whitelisting systems.

Implementing Transfer Hooks within the modern Solana toolchain requires a precise understanding of cross-program invocations (CPIs) and account resolution. In this comprehensive guide, we will architect a production-ready Transfer Hook that enforces a maximum transfer limit constraint. We will cover environment configuration, the mechanics of the ExtraAccountMetaList, the optimal Rust implementation bypassing common CPI pitfalls, and a robust TypeScript integration test suite.

In this blog post we will understand the hands-on side of the hooks extension and how to use it.

Overview

The Solana Token-2022 standard and the Transfer Hook Interface introduce the ability to create Mint Accounts that execute custom instruction logic on every token transfer. This architectural shift unlocks a massive design space for token transfers, enabling use cases such as:

• Enforcing NFT royalties.

• Building black or white lists for wallets authorized to receive tokens.

• Implementing dynamic, custom fees on token transfers.

• Creating custom token transfer events.

• Tracking on-chain statistics over your token transfers.

To achieve this, developers must build a program that implements the Transfer Hook Interface and initialize a Mint Account with the Transfer Hook extension enabled. For every token transfer involving tokens from the Mint Account, the Token Extensions program makes a Cross Program Invocation (CPI) to execute an instruction on the Transfer Hook program.

Crucially, when the Token Extensions program CPIs to a Transfer Hook program, all accounts from the initial transfer are converted to read-only accounts. This means the signer privileges of the sender do not extend to the Transfer Hook program a deliberate design decision implemented at the runtime level to prevent the malicious use of Transfer Hook programs.

Transfer Hook Interface Overview

The Transfer Hook Interface provides a standardized method for developers to implement custom instruction logic that is executed on every token transfer for a specific Mint Account. The interface specifies the following core instructions:

• Execute: The primary instruction that the Token Extension program invokes on every token transfer.

• InitializeExtraAccountMetaList (optional): Creates an account that stores a list of additional accounts required by the custom Execute instruction.

• UpdateExtraAccountMetaList (optional): Updates the list of additional accounts by overwriting the existing list.

While it is technically not required to implement the InitializeExtraAccountMetaList instruction directly through the interface (the account can be created by any custom instruction), the Program Derived Address (PDA) for the account must be derived deterministically using specific seeds:

1. The hardcoded string "extra-account-metas"

2. The Mint Account address

3. The Transfer Hook program ID

By storing the extra accounts required by the Execute instruction in this predefined PDA, these accounts can be automatically resolved and added to a token transfer instruction from the client.

Environment and Toolchain Configuration

Recent updates to the Solana ecosystem require strict version alignment between the Anchor framework, the Agave toolchain, and the SPL interface crates. To establish a stable build environment for Token-2022 development, In this blog we will use:

• Agave CLI: v3.1.9.

• Anchor CLI: 0.31.1.

• SPL Interface Crates: 0.10.0

Cargo.toml example:

...
[dependencies]
anchor-lang = "0.31.1"
anchor-spl = { version = "0.31.1", features = ["token_2022", "token_2022_extensions"] }

spl-transfer-hook-interface = "0.10.0"
spl-tlv-account-resolution = "0.10.0"

The Architecture of Account Resolution

To truly master Transfer Hooks, developers must first understand the fundamental limitation of Solana’s execution model: A program cannot read from or write to an account that was not explicitly passed to it in the transaction. In a standard token transfer, the client (or wallet) only passes four core accounts: the Source, the Mint, the Destination, and the Owner. However, custom Transfer Hook will likely need access to other accounts, such as a global configuration state, a whitelist directory or any other use-case.

Since the client initiating the transfer has no knowledge of your protocol’s internal architecture, how does the Token-2022 program know which additional accounts to fetch and pass to your Hook?

The answer lies in On-Chain Account Resolution via the ExtraAccountMetaList.

The ExtraAccountMetaList PDA

The ExtraAccountMetaList is a stateless, on-chain roadmap. It is a Program Derived Address (PDA) deterministically generated using three seeds:

1. The hardcoded byte string b"extra-account-metas"

2. The SPL Token Mint address

3. Your Transfer Hook Program ID

Before executing the cross-program invocation (CPI) to your Hook, the Token-2022 program queries this specific PDA. If the PDA exists, Token-2022 reads its data, unpacks the roadmap, and automatically appends the requested accounts to the transfer transaction.

Defining the Architecture in Anchor

To set this up safely, we first define the validation constraints for the initialization context.

#[derive(Accounts)]
pub struct InitializeExtraAccountMetaList<'info> {
    #[account(
        init,
        seeds = [b"extra-account-metas", mint.key().as_ref()],
        bump,
        payer = payer,
        // 8 bytes for the Anchor discriminator + 64 bytes for the TLV data
        space = 8 + 64 
    )]
    /// CHECK: PDA storing the metadata roadmap for the Token-2022 program
    pub extra_metas_account: AccountInfo<'info>,
    /// CHECK: The SPL Token Mint
    pub mint: AccountInfo<'info>,
    #[account(mut)]
    pub payer: Signer<'info>,
    pub system_program: Program<'info, System>,
}

Note: Notice how the PDA is derived using the exact seeds required by the Token-2022 specification that was defined above.

How Anchor Fulfills the Specification

If you look at the seeds = [...] array in the code above, you only see two items explicitly written:

1. b"extra-account-metas" (The hardcoded byte string).

2. mint.key().as_ref() (The Mint’s Public Key).

So, where is the third seed (the Program ID)?

This is where the Anchor framework steps in. Whenever you use the
seeds = [...] macro in an Anchor #[account(...)] constraint, Anchor automatically appends the currently executing Program ID as the final seed during compilation. Full docs here.

// Under the hood, Anchor translates that macro into the raw Solana runtime function: 
Pubkey::find_program_address(&[b"extra-account-metas", mint.key().as_ref()], program_id)

The initialize_extra_account_meta_list Function

With the account structure validated, developers must implement the initialize_extra_account_meta_list instruction. This function’s sole responsibility is to pack the ExtraAccountMeta configurations into the PDA.

Instead of hardcoding static addresses (which breaks composability), professional implementations use Seed-Based Resolution.

    pub fn initialize_extra_account_meta_list(ctx: Context<InitializeExtraAccountMetaList>) -> Result<()> {
        let account_metas = vec![
            // Instructs Token-2022 to derive the required PDA using dynamic seeds
            spl_tlv_account_resolution::account::ExtraAccountMeta::new_with_seeds(
                &[
                    spl_tlv_account_resolution::seeds::Seed::Literal { bytes: b"extra-account-metas".to_vec() },
                    spl_tlv_account_resolution::seeds::Seed::AccountKey { index: 1 }, // Resolves using the Mint (Index 1)
                ],
                false, // is_signer
                false, // is_writable
            )?
        ];

        let mut data = ctx.accounts.extra_metas_account.try_borrow_mut_data()?;
        
        // Formats the data as a Type-Length-Value (TLV) structure for the Execute instruction
        spl_tlv_account_resolution::state::ExtraAccountMetaList::init::<
            spl_transfer_hook_interface::instruction::ExecuteInstruction
        >(&mut data, &account_metas)?;

        msg!("Extra Account Meta List Initialized");
        Ok(())
    }

By utilizing ExtraAccountMeta::new_with_seeds(), you instruct the Token-2022 program to dynamically derive the required accounts at the exact moment of transfer.

For example, by specifying Seed::AccountKey { index: 1 }, you are telling the Token-2022 runtime: “To find the extra account my Hook needs, derive a PDA using the Public Key of the account currently sitting at Index 1 of this transaction (the Mint field in the InitializeExtraAccountMetaList struct ).”

This dynamic resolution mechanism ensures that your Transfer Hook remains entirely deterministic, allowing the Token-2022 program to bridge the gap between standard wallet transfers and complex, multi-account protocol logic.

The line:

let mut data = ctx.accounts.extra_metas_account.try_borrow_mut_data()?;

In Solana, an account's data payload is protected behind a RefCell. By calling try_borrow_mut_data()?, we bypass standard Anchor struct serialization to safely borrow a mutable reference to the PDA's underlying raw byte slice (&mut [u8]). We need this raw access because Token-2022 expects a very specific memory layout that we are about to construct manually.

spl_tlv_account_resolution::state::ExtraAccountMetaList::init::<
    spl_transfer_hook_interface::instruction::ExecuteInstruction
>(&mut data, &account_metas)?;

Once we have our raw byte slice (&mut data), we invoke the init function from the spl_tlv_account_resolution crate. This function formats your account_metas vector and writes it into the PDA using a Type-Length-Value (TLV) encoding scheme. TLV is the backbone of Token-2022, allowing multiple extensions and state variables to be packed sequentially into a single account without data collisions.

On-Chain Implementation

With the account resolution architecture defined, we can move on to the core logic. Writing a Transfer Hook requires stepping slightly outside the standard Anchor boundaries.

Below is the complete implementation for our Transfer Hook. This program initializes the metadata roadmap and enforces a strict volume constraint on transfers.

use anchor_lang::prelude::*;
use spl_transfer_hook_interface::instruction::TransferHookInstruction;

declare_id!("<YourGeneratedAddress>");

#[program]
pub mod transfer_hook_project {
    use super::*;

    /// Initializes the PDA that Token-2022 reads to resolve extra accounts.
    pub fn initialize_extra_account_meta_list(ctx: Context<InitializeExtraAccountMetaList>) -> Result<()> {
        let account_metas = vec![
            // Instructs Token-2022 to derive the required PDA using dynamic seeds
            spl_tlv_account_resolution::account::ExtraAccountMeta::new_with_seeds(
                &[
                    spl_tlv_account_resolution::seeds::Seed::Literal { bytes: b"extra-account-metas".to_vec() },
                    spl_tlv_account_resolution::seeds::Seed::AccountKey { index: 1 }, // Resolves using the Mint (Index 1)
                ],
                false, // is_signer
                false, // is_writable
            )?
        ];

        let mut data = ctx.accounts.extra_metas_account.try_borrow_mut_data()?;
        
        spl_tlv_account_resolution::state::ExtraAccountMetaList::init::<
            spl_transfer_hook_interface::instruction::ExecuteInstruction
        >(&mut data, &account_metas)?;

        msg!("Extra Account Meta List Initialized");
        Ok(())
    }

    pub fn transfer_hook(_ctx: Context<TransferHook>, amount: u64) -> Result<()> {
        msg!("Hook executed for transfer amount: {}", amount);
        
        if amount > 1_000_000_000_000 { 
            return err!(ErrorCode::TransferVolumeExceeded);
        }
        Ok(())
    }

    pub fn fallback<'info>(program_id: &Pubkey, accounts: &'info [AccountInfo<'info>], data: &[u8]) -> Result<()> {
        let instruction = TransferHookInstruction::unpack(data)?;
        match instruction {
            TransferHookInstruction::Execute { amount } => {
                let amount_bytes = amount.to_le_bytes();
                
                // Routes execution to the Anchor instruction without requiring a standard CPI
                __private::__global::transfer_hook(program_id, accounts, &amount_bytes)
            }
            _ => return Err(ProgramError::InvalidInstructionData.into()),
        }
    }
}

#[derive(Accounts)]
pub struct InitializeExtraAccountMetaList<'info> {
    #[account(
        init,
        seeds = [b"extra-account-metas", mint.key().as_ref()],
        bump,
        payer = payer,
        space = 8 + 64 
    )]
    pub extra_metas_account: AccountInfo<'info>,
    pub mint: AccountInfo<'info>,
    #[account(mut)]
    pub payer: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[derive(Accounts)]
pub struct TransferHook<'info> {
    /// CHECK: Source Token Account
    pub source: AccountInfo<'info>,
    /// CHECK: The SPL Token Mint
    pub mint: AccountInfo<'info>,
    /// CHECK: Destination Token Account
    pub destination: AccountInfo<'info>,
    /// CHECK: Owner of the Source Account
    pub owner: AccountInfo<'info>, 
    /// CHECK: The resolved ExtraAccountMetaList PDA
    #[account(
        seeds = [b"extra-account-metas", mint.key().as_ref()], 
        bump
    )]
    pub extra_metas_account: UncheckedAccount<'info>,
}

#[error_code]
pub enum ErrorCode {
    #[msg("Transfer amount exceeds the maximum protocol limit.")]
    TransferVolumeExceeded,
}

Architectural Deep Dive: The Discriminator Mismatch

If you look closely at the code above, a glaring architectural question arises: If our core logic lives inside an Anchor function, why doesn’t the Token-2022 program call it directly? Why do we need a fallback function to intercept the call? Furthermore, why not just name our function execute to match the Token-2022 standard?

The answer lies in how the Solana Virtual Machine (SVM) and the Anchor framework handle instruction routing via Instruction Discriminators.

When the Anchor framework compiles your Rust code, it automatically generates an 8-byte discriminator for every function to route incoming transactions. To prevent naming collisions between different programs, Anchor automatically injects a namespace prefix before hashing the string. For a standard instruction, it uses the prefix global:.

If you were to name your function pub fn execute(...), Anchor would generate the discriminator by taking the SHA-256 hash of exactly this string: "global:execute".

However, the Token-2022 program has no knowledge of your Anchor program’s internal namespaces. When a token transfer fires, Token-2022 blindly issues a CPI using the standardized SPL interface discriminator, which is generated by hashing this specific string: "spl_transfer_hook_interface:execute".

Because the input strings are different, the resulting 8-byte hashes are entirely different. If the Token-2022 program hits your standard Anchor instruction, Anchor will immediately reject the transaction as an “Invalid Instruction,” even if the human-readable function names are identical.

The Fallback Router & Context Isolation

To bridge this gap, we must implement the fallback function. In Anchor, the fallback acts as a catch-all safety net. If an incoming instruction does not match any known Anchor discriminator, the framework passes the raw transaction data directly to the fallback.

Inside this fallback, we manually assume control of the routing logic:

1. We unpack the raw SPL instruction data.

2. We cryptographically verify it is the standard Execute command.

3. We dynamically route the execution to our actual transfer_hook function.

The Context Routing Trick: Notice the __private::__global::transfer_hook call inside the fallback.

A common critical mistake developers make here is attempting to use a standard Solana invoke (a self-CPI) to jump from the fallback to the target function. This will cause an immediate crash (Account missing error) because the Token-2022 runtime actively strips out non-essential accounts (like the System Program or your Program ID) from the transfer payload to maintain strict security boundaries.

By utilizing __private::__global, we tap into an internal Anchor dispatcher. It takes the raw accounts passed by Token-2022 and feeds them directly into our Anchor instruction within the exact same call stack. This completely bypasses the SVM’s CPI limitations, allowing your program to retain all of Anchor’s robust security constraints without the overhead or limitations of a cross-program invocation.

Deploying to Solana

Deploying a Token-2022 Transfer Hook to Solana's Devnet requires a few specific configuration shifts to ensure both the Anchor framework and the SPL CLI are targeting the correct RPC cluster.

Configure and Deploy the Anchor Program

First, open your Anchor.toml file at the root of your project. You need to switch the provider cluster from Localnet to Devnet and explicitly declare your program ID for the new network.

[provider]
cluster = "Devnet"
wallet = "~/.config/solana/id.json" # Ensure this points to your active deployment keypair

[programs.devnet]
transfer_hook_project = "<YOUR_NEW_PROGRAM_ID>"

Once configured and funded with Devnet SOL, run a clean build and deploy the program to the live network:

anchor clean
anchor build
anchor deploy

you should see something like:

on Explorer:

Provisioning the Token on Devnet

Once the Anchor program is successfully deployed, we can leverage the spl-token CLI to create the actual Token-2022 Mint, attach the hook, and prepare our test accounts.

# Create the Token-2022 Mint and attach the newly deployed Hook
spl-token create-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb --transfer-hook <YOUR_PROGRAM_ID> --url devnet

# output:
# Creating token 71H52RsWiLbMXQuBtH5a1hLSzUnbTgiDjFhktuJrJT1m under program TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

# Address:  71H52RsWiLbMXQuBtH5a1hLSzUnbTgiDjFhktuJrJT1m
# Decimals:  9

# Signature: 2rtXMX3TaXZoWMJqcYj7vwhtWng3eLUBfDHbG4N45QxnQnuwrNReKZgPoLPNfHKBXofuoH1daFAP73FoWJAFRWJV

on Explorer:

# Create your Devnet Associated Token Account (ATA)
spl-token create-account <TOKEN_MINT_ADDRESS> --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb --url devnet

# Mint the initial test supply to your wallet
spl-token mint <TOKEN_MINT_ADDRESS> 2000 --url devnet

Note: Now your account should have 2000 of the minted token

Initialize the PDA Roadmap

At this point, the Token-2022 program is aware of your Hook, but any token transfer will still fail because the ExtraAccountMetaList PDA has not been instantiated on Devnet. You must invoke your initialize_extra_account_meta_list instruction to write the resolution map to the blockchain.

Since this logic lives entirely inside your custom Anchor program, the standard SPL CLI cannot do this for you. We bridge this gap with a standalone TypeScript script:

import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { TransferHookProject } from "../target/types/transfer_hook_project";

async function main() {
    // 1. Force the provider to use Devnet
    process.env.ANCHOR_PROVIDER_URL = "https://api.devnet.solana.com";

    const provider = anchor.AnchorProvider.env();
    anchor.setProvider(provider);

    // 2. Define your specific Devnet addresses
    const programId = new anchor.web3.PublicKey("<ProgramID>");
    const mintAddress = new anchor.web3.PublicKey("<MintID>");

    console.log("Connecting to Devnet as:", provider.wallet.publicKey.toBase58());

    // 3. Load the workspace program
    const program = anchor.workspace.TransferHookProject as Program<TransferHookProject>;

    // 4. Deterministically derive the PDA using the exact Token-2022 seeds
    // Only for the print, not needed for the program its done automatically.
    const [extraMetasPDA] = anchor.web3.PublicKey.findProgramAddressSync(
        [Buffer.from("extra-account-metas"), mintAddress.toBuffer()],
        programId
    );

    console.log("Target Mint:", mintAddress.toBase58());
    console.log("Derived Metadata PDA:", extraMetasPDA.toBase58());
    console.log("Broadcasting initialization transaction...");

    // 5. Execute the Anchor instruction
    try {
        const tx = await program.methods
            .initializeExtraAccountMetaList()
            .accounts({
                mint: mintAddress,
            })
            .rpc();

        console.log("\nSuccess! The ExtraAccountMetaList roadmap is live on Devnet.");
        console.log(`View on Explorer: https://explorer.solana.com/tx/${tx}?cluster=devnet`);
    } catch (error) {
        console.error("Transaction failed:", error);
    }
}

main();

The output should look like:

On Explorer:

Live Network Validation

With the PDA roadmap live on Devnet, your token is now 100% locked into the Transfer Hook. The modern spl-token CLI natively supports Transfer Hooks and Account Resolution. Let’s trigger a transfer that violates our 1,000-token limit:

spl-token transfer <TOKEN_MINT_ADDRESS> 1500 <DESTINATION_WALLET> --fund-recipient --url devnet

The Error:

Error: Client(Error { request: Some(SendTransaction), kind: RpcError(RpcResponseError { code: -32002, message: "Transaction simulation failed: Error processing Instruction 1: custom program error: 0x1770", data: SendTransactionPreflightFailure(RpcSimulateTransactionResult { err: Some(UiTransactionError(InstructionError(1, Custom(6000)))), logs: Some([
  ...
  "Program log: Instruction: TransferHook", 
  "Program log: Hook triggered for amount: 1500000000000", 
  "Program log: AnchorError thrown in programs/transfer-hook-project/src/lib.rs:36. Error Code: AmountTooBig. Error Number: 6000. Error Message: Transfer amount exceeds the blog's demo limit.", 
  "Program AgfLd9BmQcLZj9h13gYTsAgWdEnXKAArnRypuPd9hCub failed: custom program error: 0x1770"
])

The Hook perfectly intercepted the transfer and threw our custom Anchor error!

Now, let’s drop the volume to 500 tokens to satisfy the protocol constraint:

spl-token transfer <TOKEN_MINT_ADDRESS> 500 <DESTINATION_WALLET> --fund-recipient --url devnet

The output

On Explorer:

Summary

If you followed along and triggered those final Devnet transactions, you just successfully intercepted a native token transfer and injected your own custom business logic directly into the execution flow.

Token Extensions have fundamentally changed what is possible on Solana. By mastering Account Resolution via the ExtraAccountMetaList and properly isolating Anchor execution contexts to bypass the CPI discriminator mismatch, you can implement complex, synchronous state updates with high cryptographic security and minimal compute overhead.

Token-2022 adds extensibility to SPL tokens, but not all extensibility lives at the same layer.

Two features are often discussed together: the fee-on-transfer extension and transfer hooks. Both are triggered during a token transfer, and both influence what happens when value moves between accounts.

This similarity is misleading.

These features exist at different layers of the system, solve different classes of problems, and are subject to very different execution constraints. Treating them as interchangeable leads to designs that work in theory, pass simulation, and then fail at runtime.

In this post, we’ll start with the fee-on-transfer extension, how it works and why it exists. Then move to transfer hooks, and finally compare what is and is not possible with each.

Fee-on-Transfer Extension: Defining Token Economics

When people hear “fee on transfer,” they usually imagine a separate program that runs during a transfer and skims a percentage to a treasury.

Token-2022 does it differently.

The Fee-on-Transfer extension makes the fee part of the token program’s native transfer logic. In other words, it changes what a “transfer” means for that mint, at the protocol level.

What it is

A Token-2022 mint can be configured with:

• a fee rate (basis points), and

• a maximum fee cap (so big transfers don’t create absurd fees).

Once enabled, every transfer of that mint automatically applies the fee inside the Token-2022 program.

What actually happens during a transfer

Suppose Alice sends Bob 100 tokens and the mint charges a fee.

At execution time, Token-2022:

1. calculates the fee from the mint’s fee config,

2. deducts it from the transferred amount, and

3. withholds the fee rather than immediately paying it out to an arbitrary address.

That “withheld” detail matters a lot.

Where the fees go

With transfer fees enabled, the fee amount is tracked in Token-2022 extension state (commonly recorded on the recipient token account via the transfer-fee amount extension). The recipient can’t spend those withheld tokens as part of their normal balance.

Later, a withdraw authority (configured on the mint) can withdraw accumulated withheld fees.

There’s also a practical mechanism to harvest withheld fees from many token accounts into the mint before withdrawing, which matters when a token has lots of holders.

Why this extension exists

This extension exists because “transfer tax” is not just extra logic it is token economics:

• It changes how much value moves in the transfer.

• It must be deterministic (same inputs → same result).

• It must be enforced atomically by the token program, without relying on external programs, CPIs, wallets, or simulation quirks.

So you can think of it like this:

Fee-on-transfer is not a hook.
It’s a rule baked into the token program’s definition of a transfer.

Example

lets set the environment

solana config set --url devnet

Create two wallets (sender + recipient) and fund them

solana-keygen new --no-bip39-passphrase -o ./alice.json
solana-keygen new --no-bip39-passphrase -o ./bob.json
solana airdrop 1 -k ./alice.json
solana airdrop 1 -k ./bob.json

Create a Token-2022 mint with transfer fees:

Important: spl-token flag names can vary by version. First, confirm what your CLI supports:

spl-token create-token --help | grep -i fee

Most recent CLIs support enabling fees at mint creation using the flags for:

• --transfer-fee-basis-points

• --transfer-fee-maximum-fee

set the primary private key

solana config set --keypair ./alice.json

Example: 1% fee, max fee 5 tokens, 0 decimals (so it’s easy to see):

MINT=$(spl-token create-token \
  --program-2022 \
  --decimals 0 \
  --transfer-fee-basis-points 100 \
  --transfer-fee-maximum-fee 5 \
  | awk '/Creating token/ {print $3}')

echo "MINT=$MINT"

# Output:
# MINT=9ncw8asA7P79w7vJ3XbUFWW4EKy7cSYRVdhp9xjXb9cf

On explorer it will look like this:

Note: Max fee is set to 5 means that the fee will never take more than 5 tokens

create Alice’s token account:

ALICE_ATA=$(spl-token create-account $MINT --program-2022 | awk '/Creating account/ {print $3}')
echo "ALICE_ATA=$ALICE_ATA"

# Output:
# ALICE_ATA=J9V83VXc4H1LcCHu6DjxKLn6tkem5Se4ZYiybLnqoG35

On explorer it will look like this:

create Bob’s token account

# switch to bob
solana config set --keypair ./bob.json

BOB_ATA=$(spl-token create-account $MINT --program-2022 | awk '/Creating account/ {print $3}')
echo "BOB_ATA=$BOB_ATA"

# Output:
# BOB_ATA=G5DjAMaTSrTajDK3Y9EW1dwSsXz6SUWQdvpu9Ft3CNif

# Then switch back to Alice for minting/transferring:
solana config set --keypair ./alice.json 

On explorer it will look like this:

After you have both ATAs lets mint and transfer:

# Alice mints to herself
spl-token mint $MINT 1000 $ALICE_ATA --program-2022

# Alice transfers to Bob
spl-token transfer $MINT 100 $BOB_PUBKEY \
  --from $ALICE_ATA \
  --fund-recipient \
  --program-2022

lets check the balance of Bob to see how much he got

spl-token balance $MINT \
  --owner $BOB_PUBKEY \
  --program-2022

# Output:
# 99

On explorer it will look like this:

Transfer Hooks

If Fee-on-Transfer is a built-in “tax law” of the token program, a Transfer Hook is a “custom security checkpoint.” It allows a token creator to mandate that an external, custom program must approve every single transfer before it can finalize.

What it is

The Transfer Hook extension allows a Mint to specify a Program ID that must be called during any transfer. This essentially turns a standard token into a programmable asset.

When a transfer is initiated:

1. Token-2022 sees the hook extension on the Mint.

2. It pauses the transfer logic and sends a Cross-Program Invocation (CPI) to your custom program.

3. Your hook program runs its logic and returns either a “Success” or an “Error”.

Why this is a game-changer

Before Token-2022, if you wanted to enforce custom logic you had to “wrap” the token in a custom contract or “freeze” it and only “unfreeze” it via a proxy program. This destroyed composability, wallets and DEXs didn’t know how to talk to your proxy.

Hooks fix this by putting the logic directly into the standard transfer flow.

Execution-Time Side Effects

A Transfer Hook is Token-2022’s way to run your program during a token transfer. But the key detail is who initiates it:

The user does not call your hook program. The Token-2022 program calls it as part of processing a transfer.

So instead of “a token transfer plus my callback”, the mental model is:

A token transfer is a pipeline, and one stage of that pipeline can invoke your program.

What “hooked” actually means

When a mint has the transfer-hook extension enabled, Token-2022 stores:

• the hook program id

• and a configuration describing extra accounts the hook will need

Then, whenever someone transfers that mint, Token-2022 will:

1. validate the transfer

2. perform its internal extension logic

3. invoke the hook program (CPI) with the transfer context

This invocation is automatic and deterministic. If the hook fails, the transfer fails.

Why hooks exist

Transfer hooks are not meant to redefine the economics of the token (that’s what fee-on-transfer is for). Hooks exist for things that are inherently conditional and policy-driven, like:

Gating / compliance:

• allowlist / blocklist

• KYC / region gating

• “only transfers to approved destinations”

• “only transfers above/below a threshold”

Runtime enforcement

• pause transfers based on some on-chain flag

• rate-limit transfers

• require “membership” / “badge” / “NFT ownership” to receive

The common theme:

Note: Hooks let you add policy and stateful side effects to transfers.

The most important constraint

When your hook runs, it’s not a top-level instruction. It’s running inside the Token-2022 transfer instruction. That means two consequences that matter a lot:

1) No privilege escalation

Accounts passed into your hook have fixed privileges (read-only / writable, signer / non-signer). Your program cannot “upgrade” an account’s permissions mid-flight.
If Token-2022 passed an account as read-only, your hook cannot treat it as writable.

2) The hook cannot change what the transfer is

A hook can:

• validate

• reject

• record

• perform side effects on explicitly provided accounts

But it cannot retroactively redefine the transfer semantics the way a token-program-level extension can. This is exactly why “take a fee in the same token inside the hook” fails in practice.

Why Hooks Cannot Implement Token-Level Fees

After setting up a hook, the first instinct for many developers is to add a “tax” or “royalty” logic. However, if you try to make your hook move tokens to a treasury during a transfer, you will hit two fundamental architectural walls.

1. The “Read-Only” Wall

When the Token-2022 program invokes your hook, it provides the source and destination token accounts. However, for security reasons, these accounts are passed to your hook as read-only.

• The Constraint: You cannot modify the data or the balance of a read-only account.

• The Result: Since your hook cannot “write” to the balances, it cannot deduct a fee.

2. The Re-entrancy Lock

You might think: “I’ll just issue a CPI (Cross-Program Invocation) from my hook back to Token-2022 to move the 1% fee.”

• The Constraint: Solana prohibits “re-entrancy.” You cannot call the Token-2022 program to move a token while that same Token-2022 program is currently suspended, waiting for your hook to finish.

• The Result: The transaction will fail immediately.

Note: In next blog post we will write code and see this in practice

What Is Possible With Each Mechanism

The core difference lies in state mutation (writing) versus state validation (reading).

Modifying the Transfer Amount

• Fee-on-Transfer: Yes. Because this logic lives inside the Token-2022 program, it has the authority to split the transfer amount. If Alice sends 100, the program physically writes 99 to Bob and 1 to a withheld bucket.

• Transfer Hooks: No. Your hook program is a guest. The accounts it receives are restricted by the caller (Token-2022). To prevent a hook from “stealing” tokens, the runtime passes the source and destination accounts as Read-Only. You can see the 100 tokens, but you cannot change that number to 99.

Gating by Identity or Metadata

• Fee-on-Transfer: No. This extension is “blind.” It applies the same math to every transfer regardless of who is involved. You cannot say “charge 1% except for these five wallets” using only this extension.

• Transfer Hooks: Yes. This is the hook’s superpower. Because the hook is a custom program, it can look at a MemberAccount PDA or an external Registry to see if Alice or Bob are authorized. If they aren’t, it returns an error and the whole transfer is aborted.

Side-Effects in External Programs

• Fee-on-Transfer: No. It does one thing: math. It cannot ping a different program to update a “Points” balance or log a trade on an external leaderboard.

• Transfer Hooks: Yes. Your hook can be passed writable extra accounts. For example, you could pass a UserStats PDA. Every time a user transfers tokens, your hook could increment a “Total Volume” counter on that PDA.

Choosing the Correct Layer

The decision tree is simple:

• Does it change the math of the transfer? Use Fee-on-Transfer. It is the only way to ensure the fee is deducted atomically and safely at the protocol level.

• Does it change the permission of the transfer? Use Transfer Hooks. It is the only way to check external state (like a denylist PDA or an NFT) to decide if a transfer should be allowed to happen at all.

Summary

Token-2022 isn’t just about “more features”, it’s about putting those features at the correct layer of the stack.

• Fee-on-Transfer handles the the math. It ensures your token economics are immutable, deterministic, and enforced natively.

• Transfer Hooks handle the the policy. They turn your token into a programmable asset that can react to the world around it.

Coming up next: In the next blog post, we’re going to get our hands dirty. We’ll write a real Transfer Hook in Anchor, deploy it, and see exactly how to pair it with a Fee-on-Transfer mint to build a fully regulated token economy.

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

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

That approach solved coordination, but not discoverability.

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

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

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

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

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

What is Token2022

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

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

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

Token-2022 was developed to address this structural limitation.

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

Extensions as Explicit, Optional State

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

These extensions are:

• Explicit: their presence is encoded directly in the account data

• Optional: only the features you enable are stored

• Composable: multiple extensions can coexist when compatible

• Forward-compatible: unknown extensions can be safely ignored

Existing Extensions

• TransferFeeConfig: Includes transfer fee rate info and accompanying authorities to withdraw and set the fee

• TransferFeeAmount: Stores transfer fees that have been withheld from token transfers and are pending withdrawal.

• MintCloseAuthority: Adds an optional authority that can permanently close the mint account.

• ConfidentialTransferMint: Configures a mint for confidential transfers, enabling privacy-preserving token movements.

• ConfidentialTransferAccount: Holds per-account state required to participate in confidential transfers.

• DefaultAccountState: Specifies the default state (initialized or frozen) for newly created token accounts.

• ImmutableOwner: Prevents the token account owner authority from ever being changed.

• MemoTransfer: Requires all inbound transfers to include a transaction memo.

• NonTransferable: Marks the mint as non-transferable, preventing tokens from being transferred between accounts.

• InterestBearingConfig: Enables tokens to accrue interest over time based on a configured rate.

• CpiGuard: Restricts privileged token operations from being invoked through cross-program invocations (CPI).

• PermanentDelegate: Assigns a permanent delegate with authority over token operations.

• NonTransferableAccount: Indicates that a token account belongs to a non-transferable mint.

• TransferHook: Requires token transfers to invoke an external program that implements a transfer hook interface.

• TransferHookAccount: Marks a token account as belonging to a mint that enforces transfer hooks.

• ConfidentialTransferFeeConfig: Configures encrypted transfer fees and the public key used for encryption.

• ConfidentialTransferFeeAmount: Stores encrypted transfer fees that have been withheld.

• MetadataPointer: Stores a pointer to another account (or the mint itself) that holds token metadata.

• TokenMetadata: Stores token metadata directly inside the mint account.

• GroupPointer: Stores a pointer to another account that holds token group configuration.

• TokenGroup: Defines group-level configuration for a set of related tokens.

• GroupMemberPointer: Stores a pointer to another account that holds group membership configuration.

• TokenGroupMember: Defines group membership information for a specific token.

• ConfidentialMintBurn: Enables confidential minting and burning of tokens.

• ScaledUiAmount: Applies a scaling factor to the token’s UI amount representation.

• Pausable: Allows minting, burning, and transferring of tokens to be paused.

• PausableAccount: Indicates that a token account belongs to a pausable mint.

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

Why Token-2022 Exists

Token-2022 exists because convention does not scale indefinitely.

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

Token-2022 shifts that burden into explicit state.

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

Example:

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

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

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

Example of token creation without metadata attached:

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

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

Metadata Pointer Extension: Making Metadata Location Explicit

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

Where should metadata for this token be found?

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

The Metadata Pointer extension removes that assumption.

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

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

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

Why it was added

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

• It removes hardcoded derivation rules from clients

• It reduces the number of assumptions required to interpret a token

• It allows metadata systems to evolve independently

• It enables metadata to be stored wherever it makes sense for a given use case

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

Example:

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

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

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

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

The output should look like that:

TokenMetadata Extension: When the Mint Carries the Meaning

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

TokenMetadata is the opposite approach.

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

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

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

• name

• symbol

• URI

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

What This Enables and What It Trades Off

TokenMetadata optimizes for simplicity and locality:

• One account read to fetch both mint parameters and metadata

• No extra accounts to manage

• No dependency on external derivation rules

But the tradeoff is equally structural:

• Metadata now shares the mint’s lifecycle and authority model

• Schemas must remain conservative because they live inside the mint

• Tooling still needs Token-2022 awareness to decode it

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

TokenMetadata vs Metadata Pointer

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

• MetadataPointer makes metadata discoverable without assuming where it lives.

• TokenMetadata makes metadata local by embedding it directly into the mint.

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

In practice, you’ll see combinations like:

• Pointer → Metaplex metadata that will provide compatibility with existing ecosystem

• Pointer → custom metadata account application-specific semantics

• Inline TokenMetadata small, native, self-contained metadata

Example

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

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

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

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

and the output is:

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

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

Tooling Reality: Explicit State vs Ecosystem Support

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

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

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

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

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

Summary

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

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

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

• MetadataPointer makes metadata location explicit, replacing convention-based discovery with on-chain declaration.

• TokenMetadata allows small, native metadata to live directly inside the mint, removing indirection entirely. The pointer and is created is simply resolves to the mint itself, unifying discovery regardless of where metadata is stored.

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

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

In the previous post, we examined how the SPL Token program models fungible assets on Solana using accounts, authorities, and runtime enforcement.

One important question was left intentionally unanswered:

Where does token metadata live, and how does the runtime know how to find it?

On Solana, accounts do not carry intrinsic meaning. They are byte arrays interpreted by programs. Any relationship between accounts must be explicitly encoded, derived, or conventionally agreed upon.

Token metadata is a perfect example of this design tension.

Early Solana token designs relied on well-known conventions such as Program-Derived Addresses, to associate metadata with a mint. This approach worked, but it also introduced implicit assumptions that the runtime itself does not enforce.

In this post, we’ll examine how token metadata is modeled on Solana, why it was originally externalized into separate accounts, and why newer designs are moving toward explicit, data-driven references instead of convention.

The goal is not to describe a specific framework, but to understand the architectural trade-offs behind where token meaning lives on-chain.

Accounts Do Not Carry Meaning

At the runtime level, an account on Solana is nothing more than a byte array with an owner, lamports, and a data length. The runtime does not interpret that data, validate its structure, or attach any semantic meaning to it.

There is no native concept of:

• a token

• a balance

• metadata

• ownership semantics

All of that meaning is introduced entirely by programs.

This distinction is easy to miss because most developers interact with Solana through SDKs and frameworks that present a much richer mental model. A “Mint account” feels like a first-class object. A “Token Account” feels like a balance record. But those are program-level interpretations, not runtime primitives.

From the runtime’s perspective:

• an SPL Token mint account is just an account owned by the SPL Token Program

• a token account is just another account owned by the same program

• the relationship between them is not enforced globally

The runtime does not know that a token account “belongs” to a mint.
It only enforces that the owning program is the one allowed to read and mutate the data.

This is a crucial property of Solana’s design:

Meaning is not intrinsic. It is contextual.

Every invariant you rely on: total supply, balances, authorities, decimals, exists only because a specific program chooses to enforce it when invoked.

The same principle applies to metadata.

There is nothing in the runtime that says:

• “this account contains metadata”

• “this metadata describes that mint”

• “this metadata must exist”

Those are assumptions layered on top of the account model.

Why Token Metadata Started Outside the Mint

Given this model, the natural question is: Why wasn’t metadata stored directly inside the mint account from the beginning? The answer is not ideological, it is structural.

Early SPL Token mint accounts had:

• a fixed layout

• a fixed size

• no mechanism for optional or extensible fields

Once a mint was created, its data layout was effectively frozen.
There was no safe way to append arbitrary information without breaking compatibility.

At the same time, metadata had very different requirements from the core token state:

• variable-length fields: names, symbols and URIs

• evolving schemas

• different authority rules

• different lifecycle expectations

Putting metadata into the mint would have tightly coupled all of that complexity to the token program itself. Instead, Solana developers leaned on one of the runtime’s strongest primitives: Program-Derived Addresses (PDAs).

A metadata account could be:

• deterministically derived from the mint address

• owned by a separate program

• versioned independently

• optional

This led to the now-familiar pattern: The mint account contains only core token state, lives in a separate program-owned account and the relationship between them is defined by a derivation rule, Crucially, this relationship is not enforced by the runtime. All of those guarantees exist only because clients and programs agree to look in the same place.

Metadata as Data, introduction to Metaplex

Once metadata was separated from the mint, the ecosystem needed more than an informal pattern. It needed a shared interpretation layer something that could describe what metadata looks like, who can update it, and how clients should reason about it.

This is the role played by Metaplex. Metaplex does not change how tokens work at the runtime level. It does not introduce a new asset type, nor does it modify the SPL Token program. Instead, it introduces a dedicated program whose only responsibility is to interpret metadata stored in accounts.

That program, the Metaplex Token Metadata Program, formalizes a simple but powerful idea: a token’s human-meaningful description should live in a separate account, owned and governed independently from the token’s supply and balances.

The relationship between a mint and its metadata is established through a deterministic derivation rule. Given a mint address, the metadata account can be derived as a Program-Derived Address using a fixed seed and the metadata program ID. This makes the relationship predictable without embedding any metadata logic into the token program itself.

The metadata account contains structured fields such as the token’s name, symbol, URI, and update authority. From the token program’s point of view, none of this exists. From Metaplex’s point of view, this is the authoritative description of what the token represents.

Note: Metaplex’s seeds can be found here

Example

Lets mint a new token and deploy the Metadata for this token, this example assumes you read the previous blog post and understand whats going on,

Token minting:

spl-token create-token --decimals 9

Token account creation:

spl-token create-account H3NmgE4YBxzkNY94vV7z6UpHQaWse7VhQeYYrnHr3g5D

Minting tokens to the created account:

spl-token mint H3NmgE4YBxzkNY94vV7z6UpHQaWse7VhQeYYrnHr3g5D 1000

Metadata creation:

import { createMetadataAccountV3 } from "@metaplex-foundation/mpl-token-metadata";
import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import { keypairIdentity, createSignerFromKeypair } from "@metaplex-foundation/umi";
import { publicKey } from "@metaplex-foundation/umi-public-keys";
import * as fs from "fs";
import * as os from "os";
import * as path from "path";

const keypairPath = path.join(os.homedir(), ".config", "solana", "id.json");

const secretKey = JSON.parse(fs.readFileSync(keypairPath, "utf8"));

const mint = "H3NmgE4YBxzkNY94vV7z6UpHQaWse7VhQeYYrnHr3g5D";

async function main() {
  // Create UMI instance
  const umi = createUmi("https://api.devnet.solana.com");

  // Set up the keypair identity
  const keypair = umi.eddsa.createKeypairFromSecretKey(
    new Uint8Array(secretKey)
  );
  umi.use(keypairIdentity(keypair));

  // Create signer from keypair
  const mintAuthoritySigner = createSignerFromKeypair(umi, keypair);

  // Create metadata account
  const tx = createMetadataAccountV3(umi, {
    mint: publicKey(mint),
    mintAuthority: mintAuthoritySigner,
    data: {
      name: "Example Token",
      symbol: "EXMPL",
      uri: "https://example.com/metadata.json",
      sellerFeeBasisPoints: 0,
      creators: null,
      collection: null,
      uses: null,
    },
    isMutable: true,
    collectionDetails: null,
  });

  const signature = await tx.sendAndConfirm(umi);
  console.log("Transaction signature:", signature);
}

main().catch((error) => {
  console.error("Error:", error);
  process.exit(1);
});

This code created this account:

To read the Metadata of the token we can use this code:

import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import { publicKey } from "@metaplex-foundation/umi-public-keys";
import { fetchDigitalAsset } from "@metaplex-foundation/mpl-token-metadata";

const MINT_ADDRESS = "H3NmgE4YBxzkNY94vV7z6UpHQaWse7VhQeYYrnHr3g5D";

const RPC_URL = "https://api.devnet.solana.com";

async function main() {
  console.log("Checking metadata for mint:", MINT_ADDRESS);

  // Create UMI instance
  const umi = createUmi(RPC_URL);

  try {
    // Fetch the digital asset (mint + metadata + edition info)
    const mint = publicKey(MINT_ADDRESS);
    const digitalAsset = await fetchDigitalAsset(umi, mint);

    const metadata = digitalAsset.metadata;

    console.log("\nMetadata found!");
    console.log("\nToken Metadata:");
    console.log("─".repeat(50));
    console.log("Name:                ", metadata.name);
    console.log("Symbol:              ", metadata.symbol);
    console.log("URI:                 ", metadata.uri);
    console.log("Seller Fee (bps):    ", metadata.sellerFeeBasisPoints);
    console.log("Is Mutable:          ", metadata.isMutable);
    console.log("Update Authority:    ", metadata.updateAuthority);
    console.log("\n Mint Info:");
    console.log("Mint Address:        ", digitalAsset.mint.publicKey);
    console.log("Decimals:            ", digitalAsset.mint.decimals);
    console.log("Supply:              ", digitalAsset.mint.supply);
    console.log("Mint Authority:      ", digitalAsset.mint.mintAuthority);
    console.log("Freeze Authority:    ", digitalAsset.mint.freezeAuthority);
  } catch (error) {
    if (error.message?.includes("Account Not Found")) {
      console.log("\n No metadata found for this token mint");
      console.log("The token exists but doesn't have metadata associated with it yet");
      console.log("Use metadata.ts to create metadata for this token");
    } else {
      throw error;
    }
  }
}

main().catch((error) => {
  console.error("Error:", error);
  process.exit(1);
});

Output:

The Hidden Cost of Convention

The Metaplex model worked and still works because it created a shared convention across the ecosystem. Wallets, marketplaces, indexers, and SDKs all agree on where metadata lives and how to interpret it. But that agreement exists outside the protocol.

The Solana runtime does not enforce the relationship between a mint and its metadata. A mint does not contain a reference to its metadata account. The metadata account does not declare which mint it describes. The link exists only because every participant in the ecosystem already knows how to derive it.

This means correctness depends on shared knowledge rather than explicit state.

If metadata is missing, nothing fails at the protocol level. If metadata is malformed, the runtime does not object. If a token chooses to store metadata somewhere else, the chain does not prevent it. These are all valid states from Solana’s point of view.

The cost of this design is not immediately visible in happy paths. It appears at the boundaries: when programs disagree, when tooling makes assumptions, or when new use cases stretch old conventions.

At that point, the chain cannot help you. There is no on-chain way to verify that “this account is the metadata for that mint” unless every program involved already agrees on the same rules.

Summary

Token metadata on Solana has always existed outside the runtime’s understanding of token relationships. The difference between early designs is not what metadata contains, but how its location and association are communicated.

Convention-based designs rely on shared assumptions between programs and tooling. The Metaplex Token Metadata program standardized those assumptions, but did not make them part of the runtime’s enforcement.

This creates a clear boundary between what the protocol enforces and what the ecosystem agrees upon.

In the next post, we’ll examine how newer token program designs move beyond convention, and what it means to make token relationships explicit rather than assumed.

The SPL Token program is the foundation of fungible assets on Solana.

It defines how tokens are represented on-chain, how ownership is enforced, and how balances are created, transferred, and destroyed at runtime.

While most developers interact with SPL tokens through high-level SDKs, those abstractions hide important architectural details. Understanding the SPL Token program at the protocol level is essential for building reliable token flows, integrating with DeFi protocols, and debugging unexpected on-chain behavior.

This post provides a technical overview of the SPL Token program’s architecture. We’ll focus on how the program models state using accounts, how authority is enforced, and how common token operations are executed by the runtime.

By the end of this article, you will understand:

• how the SPL Token program represents tokens using Mint and Token Account state

• how balances are derived from account data, not stored globally

• how authorities (mint, freeze, owner) are enforced by the program

• how SPL token design differs fundamentally from account-based token models on other chains

This post establishes the architectural foundation.

In the next blogs, we’ll build on this to explore transfers, authorities and extensions.

How the SPL Token program represents

Tokens are on-chain constructs used to represent ownership and transferability of assets. Tokenization allows property rights and value to be expressed and enforced programmatically on a blockchain.

On Solana, tokens are implemented through the SPL (Solana Program Library) Token program.

This section introduces the core concepts behind how tokens are modeled and managed on Solana. For practical examples and code walkthroughs, refer to the SPL Token Basics section.

Concepts:

• Token programs define the instruction set and validation logic for creating, minting, transferring, and burning tokens on the network. The same program supports both fungible and non-fungible tokens.

• A Mint account represents a specific token type and stores global, token-wide state such as total supply, decimal precision, and mint authority (the address permitted to issue new tokens).

• A Token account represents ownership of tokens for a given mint and owner. It holds the balance and ownership metadata for that specific combination.

• An Associated Token Account (ATA) is a canonical Token account whose address is deterministically derived from the owner’s address and the mint address, ensuring a standard and predictable location for token balances.

All tokens on Solana are effectively data accounts owned by a Token Program.

Mint Account

On Solana, a token is uniquely defined by its Mint account address, which is owned by the SPL Token program. The Mint account represents the global state of a specific token and serves as the canonical source of truth for its configuration and supply.

The Mint account stores the following information:

• Supply: the total number of tokens that have been minted

• Decimals: the decimal precision used to represent fractional units

• Mint authority: the account permitted to mint new tokens and increase the total supply

• Freeze authority: the account permitted to freeze Token accounts, preventing transfers or burns

The full struct representation can be found here and looks like that:

pub struct Mint {
    pub mint_authority: COption<Pubkey>,
    pub supply: u64,
    pub decimals: u8,
    pub is_initialized: bool,
    pub freeze_authority: COption<Pubkey>,
}

For reference, here is a Solana Explorer link to the USDT Mint Account.

Token Account

To represent individual ownership, the Token program uses Token accounts. Each Token account is associated with a single Mint and is used to track the balance of that token for a specific owner.

A Token account stores the following information:

• Mint: the token type to which the account belongs

• Owner: the account authorized to transfer tokens from the Token account

• Amount: the number of token units currently held in the account

The full struct representation can be found here and looks like that:

pub struct Account {
    pub mint: Pubkey,
    pub owner: Pubkey,
    pub amount: u64,
    pub delegate: COption<Pubkey>,
    pub state: AccountState,
    pub is_native: COption<u64>,
    pub delegated_amount: u64,
    pub close_authority: COption<Pubkey>,
}

A wallet must have a dedicated Token account for each token (Mint) it intends to hold, with the wallet’s address set as the owner of that account. While a single wallet can control multiple Token accounts for the same Mint, each Token account is restricted to a single owner and can hold units of only one Mint.

Associated Token Account

Associated Token Accounts (ATAs) provide a standardized way to locate a Token account for a given Mint and owner. An ATA serves as the canonical, or default, Token account for a specific combination of owner and Mint.

An Associated Token Account is created at an address that is deterministically derived from the owner’s address and the Mint address. Functionally, an ATA is no different from any other Token account the distinction lies solely in how its address is derived.

This mechanism relies on a fundamental Solana concept: Program Derived Addresses (PDAs) that we learned here.

Cli examples

Configuring the Solana CLI for devnet

solana config set --url https://api.devnet.solana.com

Create a new keypair or use an existing one:

solana-keygen new

Verify your active configuration:

solana config get

it should look like this:

airdrop to your created account some SOL

solana airdrop 1

you should see output like this:

Install SPL CLI:

cargo install spl-token-cli

Run this to verify that it is installed successfully:

spl-token --version

// The output will look like:
// spl-token-cli 5.4.0

Creating a new token mint

spl-token create-token

// To specify decimal precision explicitly:
// spl-token create-token --decimals 6

output:

Creating a token account

spl-token create-account <MINT_ADDRESS>

output:

Minting tokens

spl-token mint <MINT_ADDRESS> 1000

output:

Check balance

spl-token balance <MINT_ADDRESS>

output:

Transferring tokens

Automatically create the recipient’s associated token account if it does not exist:

spl-token transfer <MINT_ADDRESS> 100 <RECIPIENT_WALLET_ADDRESS> --fund-recipient

output:

Summary

This article covered the foundational architecture of the SPL Token program and how tokens are represented on Solana. We examined the roles of Mint accounts, Token accounts, and Associated Token Accounts, and how they work together to model token supply and ownership on-chain.

This understanding provides the basis for analyzing token transfers, authority management, and interactions with higher-level protocols. In the next part of the series, we’ll explore how the SPL Token program enforces these rules during instruction execution.

In the previous post, we broke down how Solana transactions are structured: messages, signatures, serialization, and how the runtime executes them.

In this final part, we’ll stop theorizing and start sending real transactions.

We’ll build a small on-chain program and a client that calls it. Then we’ll send the exact same instruction two different ways:

• as a versioned (v0) transaction

• and as a v0 transaction using an Address Lookup Table

We’ll look at the actual code that builds each transaction, inspect the messages that get signed, and see how accounts are passed, locked, and resolved at runtime.

Along the way, we’ll make several things explicit that most tutorials hide:

• why some accounts live in .accounts() and others in remainingAccounts

• how the same instruction can be executed under completely different messages

• what Address Lookup Tables really do (and what they don’t)

• what the IDL describes, and why it has nothing to do with execution

Nothing here relies on magic helpers. Every transaction is constructed deliberately, every account is passed explicitly, and every optimization is visible in the message.

By the end, you’ll know how to build v0 transactions with and without ALTs, when they behave the same, and why scaling on Solana is mostly a message-level problem.

This post closes the series by connecting instructions, messages, and tooling into one concrete, executable mental model.

From theory to execution

In the previous parts of this series, we treated Solana transactions almost like a protocol specification.

We broke them down into:

• instructions and their serialized data

• messages and account lists

• signatures, fees, and blockhashes

• and how the runtime executes a message once it’s accepted by the network

All of that can feel abstract when looked at in isolation. In real programs, those same concepts reappear not as definitions, but as constraints you have to work with.

This post is about seeing those ideas surface in practice.

How real programs experience instructions

From the program’s point of view, an instruction is still just:

• a byte array

• a list of accounts

• and a program ID

The program has no concept of:

• legacy vs versioned transactions

• address lookup tables

• fee payers or signatures

It only sees the result of the message: a fixed set of accounts it is allowed to read or write, in a fixed order.

That’s why well-designed programs:

• avoid hardcoding account layouts

• rely on passed-in accounts

• and stay agnostic to how the client constructs the message

In other words, programs live below the transaction abstraction.

How real clients experience messages

Clients live at the opposite end. They don’t care about program internals.

They care about:

• how many accounts must be passed

• how large the message becomes

• whether the transaction still fits on-chain

• and whether it can be signed and broadcast successfully

This is where concepts like:

• instruction batching

• versioned messages

• and Address Lookup Tables

stop being optional and start being architectural. The logic hasn’t changed. The instruction hasn’t changed. Only the message has.

What we’ll do next

With that context in mind, the rest of this post will walk through a small, intentionally boring program and show how:

• the same instruction executes under different messages

• nothing changes for the program

• and everything changes for the client

That’s where theory stops and real Solana development begins.

Solana Program

With the execution model in mind, we can now look at a concrete on-chain program. We won’t cover environment setup, deployment, or tooling configuration here those were already covered in earlier posts in the series. Nothing in this section depends on Anchor specifics beyond basic program structure.

Instead, we’ll focus entirely on the implementation and how it interacts with instructions and messages at runtime.

The program itself is intentionally simple.

It does not write state. It does not create accounts. It does not perform CPIs.

Its only job is to read token account data passed to it and return balances.

That simplicity is deliberate: it lets us isolate how accounts are passed, how instructions are executed, and how messages constrain execution, without unrelated complexity.

Code:

use anchor_lang::prelude::*;
use anchor_lang::solana_program::{program::set_return_data, program_pack::Pack};
use anchor_spl::{token, token_2022};


declare_id!(”<YOUR-GENERATED-PROGRAM-ID>”);

fn ata_for_token(owner: &Pubkey, mint: &Pubkey) -> Pubkey {
    Pubkey::find_program_address(&[owner.as_ref(), anchor_spl::token::ID.as_ref(), mint.as_ref()],
        &anchor_spl::associated_token::ID,           // Associated Token Program id
    ).0
}

fn ata_for_token22(owner: &Pubkey, mint: &Pubkey) -> Pubkey {
    Pubkey::find_program_address(&[owner.as_ref(), anchor_spl::token_2022::ID.as_ref(), mint.as_ref()],
        &anchor_spl::associated_token::ID,           // Associated Token Program id
    ).0
}

#[program]
pub mod wallet_token_balances {
    use super::*;

    pub fn get_balances(ctx: Context<GetBalances>, wallet_mints: Vec<WalletMints>) -> Result<()> {
        // Build output: Vec<Balance> (wallet, mint, amount)
        let mut out: Vec<Balance> = Vec::new();

        // Map remaining accounts for quick lookup
        use std::collections::HashMap;
        let mut rem: HashMap<Pubkey, &AccountInfo> = HashMap::with_capacity(ctx.remaining_accounts.len());
        for ai in ctx.remaining_accounts.iter() {
            rem.insert(*ai.key, ai);
        }

        // For each wallet and its mint list
        for wm in wallet_mints.iter() {
            for mint in wm.mints.iter() {
                // let ata = get_associated_token_address(&wm.wallet, mint);

                let ata_v1  = ata_for_token(&wm.wallet, mint);
                let ata_v22 = ata_for_token22(&wm.wallet, mint);

                // Prefer whichever ATA the client actually passed in remaining_accounts
                let ai_opt = rem.get(&ata_v1).copied().or_else(|| rem.get(&ata_v22).copied());

                let amount: u64 = match ai_opt {
                    Some(ai) if *ai.owner == token::ID => {
                        let data_ref = ai.data.borrow();
                        match token::spl_token::state::Account::unpack_from_slice(&data_ref) {
                            Ok(ta) if ta.owner == wm.wallet && ta.mint == *mint => ta.amount,
                            _ => 0,
                        }
                    }
                    Some(ai) if *ai.owner == token_2022::ID => {
                        let data_ref = ai.data.borrow();
                        match token_2022::spl_token_2022::state::Account::unpack_from_slice(&data_ref) {
                            Ok(ta) if ta.owner == wm.wallet && ta.mint == *mint => ta.amount,
                            _ => 0,
                        }
                    }
                    _ => 0,
                };

                out.push(Balance {
                    wallet: wm.wallet,
                    mint: *mint,
                    amount,
                });
            }
        }

        // Return all results
        let bytes = out.try_to_vec()?;
        set_return_data(&bytes);
        Ok(())
    }
}

#[derive(Accounts)]
pub struct GetBalances {}

#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
pub struct WalletMints {
    pub wallet: Pubkey,
    pub mints: Vec<Pubkey>,
}

#[derive(AnchorSerialize, AnchorDeserialize, Clone, Copy)]
pub struct Balance {
    pub wallet: Pubkey,
    pub mint: Pubkey,
    pub amount: u64,
}

What this program shows

This program is intentionally simple. It doesn’t own state, create accounts, or perform CPIs. Its purpose is to read token balances in batches for a list of wallets and mints provided by the client.

Instead of querying balances one-by-one, the instruction accepts a vector of (wallet, mints) and processes them in a single execution. This makes it suitable for aggregators, dashboards, or off-chain systems that need to fetch many balances efficiently.

The instruction declares no required accounts. All token accounts are passed via ctx.remaining_accounts, which means the program only sees the accounts the message explicitly provides.

For each wallet and mint, the program derives the expected associated token account addresses for both SPL Token v1 and Token-2022, checks which one was included in the message, and reads the balance if it exists.

The result is returned using set_return_data, without writing anything on-chain.

The key takeaway is that this batching logic is completely agnostic to transaction format. Whether the client uses a legacy transaction, a v0 transaction, or a v0 transaction with an Address Lookup Table, the instruction behaves exactly the same. Only the message changes.

we will run:

anchor build

after the build is successfully finished, we can deploy it.

anchor deploy

After deploying, you can see the program on Solana Explorer (devnet) by its program-ID

you can see that on devnet.

Client side: building the message the program will execute

The on-chain program is simple. The complexity lives on the client side, because Solana programs can only read accounts that the message explicitly provides. So the client has two jobs:

1. figure out which token accounts (ATAs) might hold the balances

2. build a transaction message that includes those accounts and calls the instruction

In this example, we’ll also walk through creating an Address Lookup Table. As we’ve seen earlier, there’s a limit to how many account addresses can be included directly in a transaction message. In real-world scenarios, especially when batching or aggregating data, you quickly hit that limit. Address Lookup Tables are the mechanism Solana provides to scale beyond it, and this example shows how and why they’re used.

Note on setup: For this example, I’m using two pre-created token mints and a pre-created Address Lookup Table:

SPL TOKEN: 86uVjmYf4ehGPRZYhMWzHM4yMmEj13TNtutSnvESPLLN

TOKEN2022: 2hyxpEgEH7gAFTPQi6Yguqxg4gmn9KSDyaGUfL7dJm7p

ALT: 5h6TFGPPaF2r9unFdS2ExqGveVNhFRWGQtURQ1RZvxSd

The details of how these tokens were created aren’t important for understanding this post. What matters is how their addresses are used inside the transaction message. I’ll cover token creation(SPL Token vs Token-2022), minting in a separate post. Here, the focus is entirely on transaction construction, message layout, and execution. I covered the motivation behind ALTs in the previous blog post, here we focus on using them in practice.

create alts table code:

import * as anchor from “@coral-xyz/anchor”;
import {
  AddressLookupTableProgram,
  PublicKey,
} from “@solana/web3.js”;
import fs from “fs”;

async function main() {
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);
  const connection = provider.connection;
  const payer = provider.wallet;

  const slot = await connection.getSlot(”confirmed”);

  const [createIx, lookupTableAddress] =
    AddressLookupTableProgram.createLookupTable({
      authority: payer.publicKey,
      payer: payer.publicKey,
      recentSlot: slot,
    });

  const tx = new anchor.web3.Transaction().add(createIx);
  const sig = await provider.sendAndConfirm(tx, []);

  console.log(”ALT created”);
  console.log(”sig:”, sig);
  console.log(”lookupTableAddress:”, lookupTableAddress.toBase58());

  fs.writeFileSync(
    “alt.json”,
    JSON.stringify({ lookupTableAddress: lookupTableAddress.toBase58() }, null, 2),
  );
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

Client.ts

import { PublicKey, TransactionSignature, AddressLookupTableProgram } from “@solana/web3.js”;
import * as anchor from “@coral-xyz/anchor”;
import {
  getAssociatedTokenAddressSync,
  TOKEN_2022_PROGRAM_ID,
} from “@solana/spl-token”;
import {WalletTokenBalances}from“../target/types/wallet_token_balances”;
import {TransactionMessage, VersionedTransaction} from “@solana/web3.js”;

/**
 * Types mirroring your Rust structs
 */
export type WalletMints = {
  wallet: PublicKey;
  mints: PublicKey[];
};

export type BalanceResult = {
  wallet: PublicKey;
  mint: PublicKey;
  amount: bigint;
};

async function ensureAltHasAddresses(
  provider: anchor.AnchorProvider,
  altPubkey: PublicKey,
  addrs: PublicKey[],
) {
  const connection = provider.connection;

  const altResp = await connection.getAddressLookupTable(altPubkey);
  const altAccount = altResp.value;
  if (!altAccount) {
    throw new Error(”ALT not found (maybe not finalized yet?)”);
  }

  const existing = new Set(altAccount.state.addresses.map((a) => a.toBase58()));
  const missing = addrs.filter((a) => !existing.has(a.toBase58()));

  if (missing.length === 0) {
    return altAccount; // nothing to do
  }

  const extendIx = AddressLookupTableProgram.extendLookupTable({
    payer: provider.wallet.publicKey,
    authority: provider.wallet.publicKey,
    lookupTable: altPubkey,
    addresses: missing,
  });

  const tx = new anchor.web3.Transaction().add(extendIx);
  const sig = await provider.sendAndConfirm(tx, []);
  console.log(`ALT extended with ${missing.length} addresses. sig:`, sig);

  // refetch updated ALT
  const altResp2 = await connection.getAddressLookupTable(altPubkey);
  if (!altResp2.value) throw new Error(”ALT refetch failed after extend”);
  return altResp2.value;
}

export async function getBalancesClient(
  program: anchor.Program<WalletTokenBalances>,
  walletMints: { wallet: PublicKey; mints: PublicKey[] }[],
  altPubkey: PublicKey, // pass ALT separately
): Promise<{ sig: TransactionSignature; balances: BalanceResult[] }> {
  const provider = program.provider as anchor.AnchorProvider;
  const connection = provider.connection;

  // 1) Compute candidate ATAs (v1 + 2022)
  const candidateAtas: PublicKey[] = [];
  for (const wm of walletMints) {
    for (const mint of wm.mints) {
      candidateAtas.push(getAssociatedTokenAddressSync(mint, wm.wallet, true));
      candidateAtas.push(
        getAssociatedTokenAddressSync(mint, wm.wallet, true, TOKEN_2022_PROGRAM_ID),
      );
    }
  }

  // 2) Filter only existing ATAs -> these will be remaining accounts AND ALT entries
  const infos = await connection.getMultipleAccountsInfo(candidateAtas);
  const existingAtas: PublicKey[] = [];
  for (let i = 0; i < candidateAtas.length; i++) {
    if (infos[i]) existingAtas.push(candidateAtas[i]);
  }

  const remainingAccounts: anchor.web3.AccountMeta[] = existingAtas.map((pk) => ({
    pubkey: pk,
    isWritable: false,
    isSigner: false,
  }));

  // 3) Ensure ALT contains these ATA addresses (one-time-ish)
  const altAccount = await ensureAltHasAddresses(provider, altPubkey, existingAtas);

  // 4) Build the instruction
  const ix = await program.methods
    .getBalances(
      walletMints.map((wm) => ({ wallet: wm.wallet, mints: wm.mints })),
    )
    .accounts({})
    .remainingAccounts(remainingAccounts)
    .instruction();

  // 5) Build and send v0 transaction USING ALT
  const latest = await connection.getLatestBlockhash(”confirmed”);

  const msgV0 = new TransactionMessage({
    payerKey: provider.wallet.publicKey,
    recentBlockhash: latest.blockhash,
    instructions: [ix],
  }).compileToV0Message([altAccount]);

  const vtx = new VersionedTransaction(msgV0);
  await provider.wallet.signTransaction(vtx);

  const sig = await connection.sendTransaction(vtx, { maxRetries: 3 });
  await connection.confirmTransaction({ signature: sig, ...latest }, “confirmed”);

  // 6) Fetch tx + return data (same as you already do)
  const txInfo = await connection.getTransaction(sig, {
    commitment: “confirmed”,
    maxSupportedTransactionVersion: 0,
  });
  if (!txInfo) throw new Error(”getTransaction returned null”);

  const metaAny = txInfo.meta as any;
  const rd = metaAny?.returnData as { programId: string; data: [string, string] } | null | undefined;
  if (!rd) throw new Error(”Transaction succeeded but meta.returnData is null”);

  const raw = Buffer.from(rd.data[0], “base64”);
  const balances = decodeBalances(raw);
  return { sig, balances };
}


/**
 * Decode Vec<Balance> from Borsh:
 * struct Balance { wallet: Pubkey; mint: Pubkey; amount: u64 }
 *
 * Layout:
 * - u32 length (little endian)
 * - then `len` * (32 + 32 + 8) bytes
 */
function decodeBalances(buf: Buffer): BalanceResult[] {
  let offset = 0;
  const dv = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);

  const len = dv.getUint32(offset, true);
  offset += 4;

  const results: BalanceResult[] = [];
  for (let i = 0; i < len; i++) {
    const walletBytes = buf.slice(offset, offset + 32);
    offset += 32;
    const mintBytes = buf.slice(offset, offset + 32);
    offset += 32;
    const amount = dv.getBigUint64(offset, true);
    offset += 8;

    results.push({
      wallet: new PublicKey(walletBytes),
      mint: new PublicKey(mintBytes),
      amount,
    });
  }

  return results;
}

async function main() {
  // 1) Setup provider from env / solana config
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);

  // Use Anchor workspace (uses generated IDL/types under target/)
  const program = anchor.workspace
  .walletTokenBalances as anchor.Program<WalletTokenBalances>;
  const wallet = provider.wallet as anchor.Wallet;

  // 4) Paste real mint pubkeys from spl-token CLI
  const MINT_V1 = new PublicKey(”86uVjmYf4ehGPRZYhMWzHM4yMmEj13TNtutSnvESPLLN”);
  const MINT_22 = new PublicKey(”2hyxpEgEH7gAFTPQi6Yguqxg4gmn9KSDyaGUfL7dJm7p”);
  const altPubkey = new PublicKey(”5h6TFGPPaF2r9unFdS2ExqGveVNhFRWGQtURQ1RZvxSd”);

  const walletMints = [{
    wallet: wallet.publicKey,
    mints: [MINT_V1, MINT_22],
  }];

  // 5) Call your on-chain program
  const { sig, balances } = await getBalancesClient(program, walletMints, altPubkey);

  console.log(”tx:”, sig);
  for (const b of balances) {
    console.log(
      “wallet”,
      b.wallet.toBase58(),
      “mint”,
      b.mint.toBase58(),
      “amount”,
      b.amount.toString(),
    );
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Note: We still pass accounts as metas via remainingAccounts because that’s what grants the program access. The ALT only compresses addresses inside the message; it doesn’t “provide” accounts by itself. Transaction without alt table will look the same but without altAccount variable.

Then we will run it:

 npx ts-node scripts/client.ts

In the logs you should see Program return: and the decoded balances printed by the client.

this is the link to the transaction in the scanner.

Step 1: derive the candidate accounts (ATAs)

The input to the instruction is just a list of wallets and mints:

[{ wallet, mints: [MINT_V1, MINT_22] }]

But the program doesn’t receive token accounts from that. It receives accounts. So the client derives the associated token account addresses for both token programs:

• classic SPL Token (v1)

• Token-2022

That’s why for every (wallet, mint) pair we compute two candidates:

getAssociatedTokenAddressSync(mint, wallet) // v1
getAssociatedTokenAddressSync(mint, wallet, ..., TOKEN_2022_PROGRAM_ID) // 2022

This mirrors the Rust helpers that derive ATAs on-chain. The client and the program must agree on these addresses.

Step 2: only pass accounts that actually exist

Deriving ATAs is cheap, but many of them might not exist on-chain. Passing non-existent accounts would just waste space or fail during account loading, so the client filters them:

const infos = await connection.getMultipleAccountsInfo(candidateAtas);

Only existing accounts are turned into remainingAccounts.

This is the crucial Solana rule in action:

If it’s not in the instruction’s account list, the program can’t read it. So the client must bring the world with it.

Step 3: remaining accounts are message wiring, not “program API”

When we build the instruction we call:

.accounts({})
.remainingAccounts(remainingAccounts)

.accounts({}) is empty because the program’s Anchor context is empty.

But remainingAccounts is where the real work happens: it becomes the instruction’s account metas list, which becomes part of the message, which becomes what the runtime loads and locks.

This is why this program scales with batching: the instruction data stays small while the message can carry lots of accounts.

Step 4: ALTs optimize the message, not the instruction

With batching, the message grows quickly because it has to include many account addresses. That’s where Address Lookup Tables come in.

The helper:

ensureAltHasAddresses(...)

is just a convenience wrapper that:

• fetches the ALT

• checks which addresses are already stored there

• extends the table with missing ones (only if needed)

Importantly: the ALT does not “send accounts to the program”.

It only lets the message reference account addresses more efficiently.

We still pass the token accounts via remainingAccounts.

The ALT only changes how the message encodes those addresses.

Step 5: send a v0 transaction (where ALT actually matters)

ALTs only work with versioned (v0) messages, so the client builds a v0 message explicitly:

new TransactionMessage({...}).compileToV0Message([altAccount]);

Then signs and sends a VersionedTransaction:

const vtx = new VersionedTransaction(msgV0);
await provider.wallet.signTransaction(vtx);
await connection.sendTransaction(vtx);

This is the key conceptual point:

The instruction is identical. The program is identical. Only the message format changes.

v0 vs v0+ALT is purely a client-side message construction choice.

Summary

In this post, we took Solana’s transaction model out of theory and into practice.

We built a real program, constructed real messages, and sent the same instruction using v0 transactions with and without Address Lookup Tables. Nothing changed for the program. Everything changed for the client.

That’s the core lesson: scaling on Solana is a message-level problem, not a program-level one. Programs execute instructions. Clients decide how those instructions are wrapped, encoded, and optimized.

In the next post, we’ll focus on the tokens used here, SPL Token vs Token-2022 and how their accounts differ, how ATAs are derived, and why those details matter when building real systems.

In the previous part of this series, we unpacked how Solana structures instructions and messages, and why the network eventually outgrew the legacy message format.

We saw how v0 messages and Address Lookup Tables allowed developers to reference far more accounts than the original ~35 account limit, and how the message, not the transaction is the canonical record of “what should happen.”

But understanding message formats is only the first half of the story.

Because once you know how messages are built, the natural next question is:

“What actually happens when this message becomes a real transaction on the network?”

• How is it serialized?

• How does a wallet sign it?

• Why do blockhashes expire?

• Where do fees come from?

How does the runtime decide which instructions can run in parallel?

And why does simulation sometimes produce results that differ from real execution?

This post goes one layer deeper.

We’re going to follow a transaction end-to-end from the moment a message is assembled, through signature verification, account loading, and runtime execution, all the way to atomic state commit.

What is a Solana Transaction?

To interact with Solana, you submit a transaction. As we discussed in the previous post, a transaction doesn’t hold raw instructions directly, it holds a message that defines which instructions will run, which accounts they require, and which recent blockhash anchors the transaction to the current chain state.

Each instruction inside that message represents a specific operation the network should perform. In the example below, the first transaction contains a message with a single instruction, while the second contains a message with three instructions that will execute sequentially: instruction 1, then instruction 2, then instruction 3.

The transaction object looks like that:

• signatures: An array of signatures

• message: Transaction information, including the list of instructions to be processed

pub struct Transaction {
    #[serde(with = “short_vec”)]
    pub signatures: Vec<Signature>,
    pub message: Message,
}

Transactions have a total size limit of 1232 bytes. This limit includes both the signatures array and the message struct.

Signatures

The transaction holds an array of 64-byte signatures.

Each one is produced by signing the transaction’s Message with the private key of an account that appears as a required signer. Every signer referenced by any instruction must provide a corresponding signature in this array.

The first signature always comes from the fee-payer. This is also the transaction’s primary signature the one you use to look up the transaction on explorers and RPC endpoints.

The signature struct looks like that:

 pub struct Signature(GenericArray<u8, U64>);

Transactions Are Atomic

A Solana transaction is an all-or-nothing operation.

Even if a message contains multiple instructions, the runtime treats the entire set as a single atomic unit. This means:

• All instructions succeed → state is committed

• Any instruction fails → nothing is committed

There is no partial success.

This is why Solana must know every account that will be touched before execution begins. It allows the runtime to lock those accounts, validate the message, and ensure that the entire transaction can be applied in one deterministic step.

Atomicity is also what makes Solana composable. You can pack multiple program calls into a single transaction (e.g., swap → transfer → stake), and the chain guarantees the entire sequence either completes or doesn’t happen at all.

Transaction Fees

Every Solana transaction includes a fee paid in SOL. This fee has two components: a base fee and an optional prioritization fee.

The base fee compensates validators for executing the transaction, while the prioritization fee allows a user to pay extra to increase the likelihood that the current leader will include their transaction in the block.

What is the base Fee

Solana charges a base fee of 5,000 lamports per signature in a transaction. The fee-payer the first signer in the message is responsible for covering this amount, and only System Program–owned accounts are eligible to pay it.

The network divides the base fee into two equal parts:

• Half is burned, reducing the total SOL supply.

• Half is given to the validator that included the transaction.

What is the prioritization fee

A prioritization fee is an optional amount you can add to improve the likelihood that the current leader includes your transaction. The validator receives 100% of this fee.

You set the prioritization fee by specifying a compute unit (CU) limit and a CU price on the transaction.

The fee is computed as:

Prioritization fee = CU limit × CU price

Note: Solana only charges a prioritization fee when you explicitly set one using the ComputeBudgetProgram. If you do not include a compute budget instruction, then:

• CU price = 0

• Prioritization fee = 0

• Only the base fee is charged (5,000 lamports per signature)

This value helps determine how your transaction ranks against others in the leader’s queue. Solana derives a transaction’s overall priority using:

Priority = (Prioritization fee + Base fee) / (1 + CU limit + Signature CUs + Write lock CUs)

A higher priority increases the chance your transaction is selected during contention.

Compute Unit Limit

By default, Solana allocates 200,000 compute units per instruction and up to 1.4 million compute units per transaction.

You can override these defaults by adding a

SetComputeUnitLimit 

instruction from the ComputeBudgetProgram.

A practical way to choose an appropriate limit is:

1. Simulate the transaction to see how many CUs it actually consumes.
   (coming soon in the next blogs)

2. Add X% overhead to avoid unexpected failures.

It’s important to note that the prioritization fee uses the requested CU limit, not the compute units the transaction ultimately consumes.

If you set the limit too high (or rely on the large default), you may end up paying for unused compute capacity.

Compute Unit Price

The compute unit price is an optional amount, specified in micro-lamports, that you’re willing to pay per requested compute unit.

You can think of it as a tip that incentivizes the current leader to include your transaction ahead of others.

To set a CU price, include a

SetComputeUnitPrice 

instruction from the ComputeBudgetProgram.

If you do not specify a CU price, it defaults to zero, and the transaction will not pay a prioritization fee, only the base fee.

Note: Compute Budget program instructions are ignored when calculating the prioritization fee. You can see this here.

Example: lets take a look at this transaction

We see that the Priority fee here is 0.000004 SOL, and the total fee is 0.000009 SOL

lets understand how it is computed:

as we said before, By default, Solana allocates 200,000 compute units per instruction.

In this transaction we have here 2 instructions, but as said previously the

ComputeBudget

Instructions are omitted from the calculation, so we end up only with 1 instruction and a price of 20000 micro-lamports which is 0.02 lamports/CU.

so the price will be: 200,000 * 0.02 = 4000 lamports, which is 0.000004 SOL.

In addition we have 1 transaction signer on the transfer instruction, which is costs 0.000005 SOL.

Total fee = BaseFee + PriorityFee =  0.000004 + 0.000005 = 0.000009

How the Wallet Actually Signs

A common point of confusion is how a signer can sign a message when the message itself already includes that signer’s account. This feels circular at first, how can the wallet include the signer in the message before the signer has produced the signature?

The key is understanding that the message contains the signer’s public key, not their signature.

The signature is added after the message is finalized.

Here’s how the process actually works:

1. The wallet builds the complete message first

Before any signature exists, the wallet constructs the message in its final form:

• the message header (signer counts),

• all account public keys,

• the recent blockhash,

• the compiled instructions.

At this stage, the message already includes the signer’s public key, because the runtime needs to know:

• which accounts must sign,

• the order of signer accounts,

• which signature corresponds to which key.

No signatures exist yet.

The message is simply a byte array describing exactly what will be executed.

2. The signer signs the message bytes

Once the message is fully constructed, the wallet signs the exact serialized message bytes:

signature = Ed25519_sign(private_key, message_bytes)

Any change to the message, however small invalidates the signature.

Because the message contains only public keys, signing it has no circular dependency.

It’s like signing a legal document that lists your name:

your name is part of the document, but your signature is added afterward.

3. The signature is inserted into the transaction

After signing, the signature is placed into the transaction’s signature array according to the signer’s position in account_keys:

• signature at index 0 → first signer (fee-payer)

• signature at index 1 → second signer

• etc.

The signature does not modify the message.

The message is now locked, changing it would break every signature.

Transaction packs all this data into its structure and sends the built transaction to the node.

Overview

• Messages never contain signatures, only public keys.

• Signatures are created over the final message, not before it.

• Signatures live outside the message, in the transaction wrapper.

This separation allows:

• deterministic signing,

• canonical verification,

• simple replay protection,

• and lightweight transactions.

There is no circular dependency, signers sign the message, and the message simply identifies who the signers are.

How Solana Executes a Transaction

Up to this point, we’ve focused on how a transaction is constructed, how messages are formed, how signatures are produced, how fees are calculated, and how the wallet packages everything together.

Once a validator receives a transaction, Solana processes it through a series of steps that ensure the transaction is valid, safe to run in parallel, and either fully succeeds or fully fails.

1. Signature Verification

• The validator hashes the message.

• Each signature is checked against its corresponding public key.

• Any invalid signature → the transaction is immediately rejected.

2. Account Loading

• All accounts listed in the message (and ALTs, if used) are fetched.

• The runtime checks:

  • account existence

  • ownership rules

  • signer flags

  • read/write permissions

• If anything is invalid → the transaction stops here.

3. Account Locking

• Writable accounts get a write lock.

• Read-only accounts get a read lock.

• These locks ensure no conflicting transactions execute in parallel.

• If required accounts are already locked → the transaction may be delayed or skipped.

4. Instruction Execution

• Instructions run in order, one by one.

• Each instruction:

  • invokes the target program

  • updates compute usage

  • may perform CPIs

• If any instruction fails → the entire transaction fails.

5. Compute Budget Enforcement

• The runtime tracks consumed compute units.

• If the CU limit is exceeded:

  • execution stops

  • the transaction fails

  • the fee-payer still pays the fee

6. Atomic Commit or Rollback

• If all instructions succeed:

  • account changes are committed atomically

  • locks are released

• If any instruction fails:

  • no state changes are applied

  • the transaction is recorded as failed

  • the fee is still charged

Summary

A Solana transaction is more than a signed bundle of instructions. It’s a structured request that moves through a precise execution pipeline. The message defines what should happen, signatures authorize who approved it, and the runtime ensures everything is valid, safe to run in parallel, and fully atomic.

You’ve seen how fees are calculated, how compute budgets influence prioritization, how wallets sign messages, and how validators process transactions from signature checks to final commit. Together, these pieces form the foundation of Solana’s high-throughput, parallel execution model.

Understanding this flow gives you the tools to reason about transaction behavior, debug failures, and write programs that interact with the network reliably and efficiently.

Before now, we explored Solana’s parallel architecture and account model how data lives on-chain, who can modify it, and why Sealevel enables true concurrency.

But accounts alone don’t change state. Every update on Solana, from transferring tokens to creating PDAs, happens through transactions composed of instructions.

In this post, we’ll unpack what really happens between a wallet click and on-chain execution:

1. how a transaction is structured under the hood,

2. how the runtime routes instructions to programs,

3. how accounts are locked for safe parallel execution,

4. what “signing,” “message,” and “recent blockhash” actually mean.

By the end, you’ll understand how Solana encodes, validates, and executes transactions step by step and how to build, simulate, and send them directly from your code.

Instructions

Instructions are the core unit of execution on Solana. Think of each instruction as a function call exposed by an on-chain program. Every program defines its own instruction set, the specific actions it can perform. When you interact with the network, you don’t call programs directly, you package one or more of their instructions into a transaction, sign it, and submit it for execution.

Instruction consists of

• ProgramId

• Accounts

• Instruction specific data

ProgramId

The on-chain Id of the program (address) that contains the logic of the instruction

Accounts

Each instruction includes an array of AccountMeta entries, metadata describing every account it will read from or write to. By explicitly listing these accounts, Solana’s runtime can determine which instructions are independent and safely execute them in parallel, as long as they don’t modify the same account.

• is_signer: Set to true if the account must sign the transaction

• is_writable: Set to true if the instruction modifies the account’s data

• pubkey: The account’s public key address

Data

The instruction’s data field is a sequence of bytes that tells the program which specific function to execute and includes the parameters needed for that call.

Example (Simple 0.01SOL Transfer)

{
  “program_id”: “11111111111111111111111111111111”,
  “accounts”: [
    {
      “pubkey”: “6uR7N6oDgE3vJXvM6Eh4xVHw2g7o7YhA7FJxC4pXcZtT”,
      “is_signer”: true,
      “is_writable”: true
    },
    {
      “pubkey”: “3Nq8yVbGz7KpYw9sT6rF2LmHc4Qz5XvA1uJd8BvCzRy”,
      “is_signer”: false,
      “is_writable”: true
    }
  ],
  “data”: [2, 0, 0, 0, 128, 150, 152, 0, 0, 0, 0, 0]
}

program_id

That’s the System Program Solana’s built-in program for managing native SOL transfers, creating accounts, and assigning ownership. Every validator includes this program by default. This tells the runtime Call the System Program to execute one of its functions

accounts:

6uR7…ZtT: Sender, must sign and can be modified (lamports will be deducted).

3Nq8…zRy: Recipient, writable because lamports will be added, but no signature required.

data:

Each data variant encoded as [variant_index:u32][variant_payload]
in our case:

pub enum SystemInstruction {
    CreateAccount { ... },
    Assign { ... },
    Transfer { lamports: u64 },
    ...
}

Transfer variant is at index 2 and its payload is u64 (8-bytes)

[2, 0, 0, 0, 128, 150, 152, 0, 0, 0, 0, 0]

which is:

[02 00 00 00 | 80 96 98 00 00 00 00 00] // 4 + 8 = 12

[0:4) bytes

• Type: u32

• Value: 2 :  in this program source code we can see that Transfer is at index 2 in the SystemInstruction enum

[4:12) bytes

• Type: u64

• Value: 10000000 lamports

[2, 0, 0, 0]  → discriminant = 2
[128, 150, 152, 0, 0, 0, 0, 0] → bytes to hex
[80 96 98 00 00 00 00 00] → hex representation
[0x00000000989680] → 0x00989680 = 10_000_000 lamports (0.01 SOL)

Messages

A transaction on Solana is more than just a list of instructions it’s a message signed by one or more accounts. The message defines exactly what will run, which accounts are involved, and which recent blockhash anchors it to the chain’s current state.

Solana signs the message, not each instruction individually. That design makes transactions compact and verifiable: a validator only needs to check that the signers authorized the same message bytes the network received.

Once signatures are verified, the runtime executes the instructions in order and commits all changes atomically either everything succeeds or the whole transaction reverts.

In other words:

• The message is the canonical record of “what should happen”

• The signature just proves “who approved it”

Legacy and Versioned Messages

Originally, all Solana transactions used a single message format, now referred to as the legacy message. It worked well for simple transfers and small programs, but every transaction must list all accounts it will read or write (For the purpose of parallel execution).

Since each account address is 32 bytes, the total message size grows quickly, and Solana enforces a strict upper bound (≈ 1232 bytes for serialized transactions) to fit inside the network’s MTU. That limited legacy transactions to about 35 accounts, which became a problem for complex, composable DeFi protocols that interact with many programs at once.

To solve this, Solana introduced versioned transactions, starting with v0 messages, along with a new on-chain program called the Address Lookup Table (ALT) program.

Lookup tables let developers store groups of addresses on-chain and reference them later by small 1-byte indexes instead of full 32-byte keys. The transaction can then “look up” additional accounts during execution without exceeding the size limit.

Legacy Messages

pub struct Message {
    pub header: MessageHeader,
    pub account_keys: Vec<Address>,
    pub recent_blockhash: Hash,
    pub instructions: Vec<CompiledInstruction>,
}

pub struct MessageHeader {
    pub num_required_signatures: u8,
    pub num_readonly_signed_accounts: u8,
    pub num_readonly_unsigned_accounts: u8,
}

// As learned previously
pub struct CompiledInstruction {
    pub program_id_index: u8,
    pub accounts: Vec<u8>,
    pub data: Vec<u8>,
}

Note: the #[serde(with = “short_vec”)] is important and we will see later why

can hold about 35 accounts (35 * 32(address size) = 1120bytes out of 1232) we can see that it is holds a fixed header, accounts, blockhash, instructions and can be used for simple or medium transactions.

Versioned Messages

pub enum VersionedMessage {
    Legacy(LegacyMessage),
    V0(v0::Message),
}

pub struct Message {
  pub header: MessageHeader,
  pub account_keys: Vec<Pubkey>,
  pub recent_blockhash: Hash,
  pub instructions: Vec<CompiledInstruction>,
  /// List of address table lookups used to load additional accounts
  /// for this transaction.
  #[serde(with = “short_vec”)]
  pub address_table_lookups: Vec<MessageAddressTableLookup>,
}

pub struct MessageAddressTableLookup {
  pub account_key: Pubkey,
  #[serde(with = “short_vec”)]
  pub writable_indexes: Vec<u8>,
  #[serde(with = “short_vec”)]
  pub readonly_indexes: Vec<u8>,
}

Transactions must fit in ~1232 bytes of packet payload. Listing every account inline (32 bytes each) caps legacy messages at ~35 accounts after signatures/overhead. V0 introduces Address Lookup Tables (ALTs) so a message can reference many accounts by 1-byte indexes instead of inlining 32-byte pubkeys.

How address lookup works

At runtime, the validator constructs a single resolved account list that instructions index into:

resolved_keys =
    [ message.account_keys
    , looked_up_writable_keys (from all ALTs, in order)
    , looked_up_readonly_keys (from all ALTs, in order)
    ]

Each MessageAddressTableLookup points to a specific on-chain ALT (account_key).

writable_indexes and readonly_indexes are u8 indexes into that ALT’s stored addresses.

The runtime fetches those pubkeys and appends them to resolved_keys in two groups:

• all writable lookups (preserves order across tables)

• all readonly lookups (preserves order across tables).

program_id and accounts still point into this combined list exactly like legacy messages.

how v0 is identified

Versioned transactions use a leading version bit in the message encoding:

• If the top bit of the first byte is set, the remaining bits encode a version number (v0 = 0).

• If not set, it’s treated as a legacy message.

You won’t usually touch this directly, SDKs handle it but it’s why v0 and legacy can coexist.

Size implications

v0 adds small overhead but dramatically reduces inline key bytes when many accounts are needed

Added overhead per transaction (approx) this is at least sizes:

• +1 byte: version tag

• +1 byte: address_table_lookups length

• +34 bytes per lookup table (32 for table pubkey + 1 + 1 for lengths of writable/readonly index arrays)

• +1 byte per looked-up index (each index into the ALT)

Saved space: each looked-up address replaces a 32-byte inline pubkey with a 1-byte index in the message.

When you reference dozens/hundreds of accounts, this tradeoff wins easily

Limits and rules to remember

• 256 max entries per ALT. Indexes are u8.

• Up to 256 unique accounts can be loaded overall (since compiled instruction account indexes are u8 as well).

• Signers cannot come from ALTs. All signer keys must appear in account_keys so their signatures can be verified efficiently.

• No duplicates. The same account may not be loaded more than once across account_keys and ALT lookups.

• ALT availability: Newly appended ALT entries become usable after one slot (warm-up).

• ALT lifecycle: Tables must be rent-exempt, are append-only, can be deactivated, and only closed after a cooldown to avoid censorship/race issues

Lets make sense of the numbers and why those are the limits

Lets look at the confusing statements from before

256 max entries per ALT. Indexes are u8:
Each Address Lookup Table (ALT) can store up to 256 addresses because the indexes used to reference them are u8 (1 byte).

pub writable_indexes: Vec<u8>,
pub readonly_indexes: Vec<u8>,

Each element in those vectors is a single byte → range 0–255.
So when we say:

writable_indexes = [0, 2, 4, 6]

the runtime loads the 0th, 2nd, 4th, and 6th addresses from that table’s on-chain storage. Hence Max 256 because u8 can encode 0–255 possible values, means 256 unique entries per lookup table
(this is impossible: writable_indexes = [0, 2, 310]).

1 byte: address_table_lookups length
The first question that can come up to mind is, why only the lenght only 1 byte if it is a vector which might be unlimited. the magic is in
#[serde(with = “short_vec”)] which means
This Vec<…> in Solana’s serialized structs uses a short_vec format.
That’s how Bincode (via the short_vec module) serializes variable-length arrays efficiently
[length (1-9 bytes)][elements...]
For small vectors (length < 128), the length fits in a single byte
If you have 3 lookup tables, that length byte would literally contain 0x03.
It means there’s one byte added to encode how many lookup tables are attached, before serializing their contents.

34 bytes per lookup table (32 + 1 + 1)
This is the same the prev statement, take a look that

pub struct MessageAddressTableLookup {
  pub account_key: Pubkey,
  #[serde(with = “short_vec”)]
  pub writable_indexes: Vec<u8>,
  #[serde(with = “short_vec”)]
  pub readonly_indexes: Vec<u8>,
}

serialized with #[serde(with = “short_vec”)] means that every MessageAddressTableLookup needs at least 34 bytes + N-bytes for each entry.

MessageHeader

The header tells the runtime how many accounts must sign, and which accounts are read-only.

It’s the preamble the runtime uses to understand how to interpret the account_keys slice.

num_required_signatures (u8)

How many of the first account_keys must provide signatures.

• If this is 1, the first key in account_keys is the signer.

• If this is 2, the first two keys are signers, etc.

These signatures come from the transaction’s signature array. Every signer must match with its position in the account_keys.

num_readonly_signed_accounts (u8)

Among the signer accounts (the first num_required_signatures), how many of them are read-only. They can be read, but the program cannot modify their account data or lamports. This prevents accidental or malicious modification of signer accounts when they don’t need to be writable.

Example:

• A user signs a transaction using their wallet (signer),

• But that wallet account is never written to so it should remain read-only.

num_readonly_unsigned_accounts (u8)

Among the non-signers (the remaining accounts), how many of them are read-only.

Why this matters:
Some accounts are passed to a program as read-only e.g., system program, token program, metadata program. Marking them read-only improves security and performance.

recent_blockhash

This field prevents replay attacks and sets a liveness requirement.

Solana does not use nonces.

Instead, every transaction must include a recent blockhash from the last ~150 blocks (≈ 2 minutes).

Why it’s required

Anti-replay
If someone copies your signed transaction and tries to submit it again, it will be rejected because the blockhash is too old.

Transaction expiration
Solana requires transactions to be “fresh.”
If the blockhash is too old, the validator won’t accept the transaction.

Fork commitment
Validators agree that transactions built on a recent blockhash belong to the current fork, reducing ambiguity.

Summary

You should now understand how Solana structures the logic behind every transaction. An instruction defines what to run, the program, accounts, and data, while a message bundles those instructions together into an atomic unit that can be signed and verified. Legacy messages work for most cases, but v0 messages extend the format with Address Lookup Tables, allowing many more accounts to be referenced through compact 1-byte indexes.
In short, you now know how Solana encodes what happens in a transaction

When you start building on Solana with Anchor, the hardest part isn’t Rust it’s understanding how accounts, PDAs, bumps, and the client all fit together.

In this post we’ll walk through a minimal Anchor program that creates, updates, and closes a user-owned PDA, and then call it end-to-end from a TypeScript script. Along the way you’ll learn how Anchor derives accounts, when you need to pass them manually, why storing the bump matters, and how the client auto-fills everything based on your constraints.

What is Anchor and How it represents accounts and constraints in Rust

Anchor is the most popular framework for Solana programs. Think of it as:

• a Rust DSL for accounts & constraints (declarative checks instead of manual AccountInfo plumbing),

• a toolchain (build, deploy, test, IDL generation),

• and a TypeScript client that auto-types your program interface from the IDL.

In practice, Anchor gives you:

• #[account] Rust structs that map 1:1 to on-chain data accounts,

• #[derive(Accounts)] contexts with constraints like init, seeds, bump, has_one, close (Will be covered soon)

• auto-generated IDL + a TypeScript client (@coral-xyz/anchor) to call your instructions safely.

Installation

Prereqs

• Rust toolchain (rustup)

• Node 18+ (20 recommended)

• Yarn or npm (or pnpm)

Install Solana CLI (Agave toolchain)

This section will automatically install:

• solana CLI

• solana-test-validator

• build-bpf pipeline

• loader

• runtime libs

• all tooling that Anchor expects

Note: This installs into $HOME/.local/share/solana/install/active_release/bin

# 1. Download/install the Agave installer script
sh -c “$(curl -sSfL https://release.anza.xyz/stable/install)”

# 2. Setting up the PATH env var so everything work together
export PATH=”$HOME/.local/share/solana/install/active_release/bin:$PATH”

# To make it permanent (zsh), or change zshrc to your shell
# echo ‘export PATH=”$HOME/.local/share/solana/install/active_release/bin:$PATH”’ >> ~/.zshrc
# source ~/.zshrc

# if avm --version is not 0.31.1. do this:
# avm install 0.31.1
# avm use 0.31.1

# 3. Verify installation
cargo-build-sbf --version
# You should see something like:
# solana-cargo-build-sbf 3.0.10
# platform-tools v1.51
# rustc 1.84.1

Scaffold a New Program

anchor init solana_accounts
cd solana_accounts

We will go over a code now that should be pasted in programs/solana_accounts/src/lib.rs

more about anchor directory layout can be found here. We will cover only the interesting part: How the program behaves on-chain.

Rust code

use anchor_lang::prelude::*;

declare_id!(”<YOUR-PROGRAM-ID>”);

#[program]
pub mod solana_accounts {
    use super::*;

    /// Create a PDA for the user and store their name + creation time.
    pub fn create_user(ctx: Context<CreateUser>, name: String) -> Result<()> {
        // Enforce max length in BYTES (UTF-8). Emojis count as multiple bytes.
        require!(
            name.as_bytes().len() <= UserAccount::MAX_NAME,
            ErrorCode::NameTooLong
        );

        let user = &mut ctx.accounts.user_account;
        user.owner = ctx.accounts.authority.key();
        user.name = name.clone(); // fits because we sized with MAX_NAME
        user.created_at = Clock::get()?.unix_timestamp;
        user.bump = ctx.bumps.user_account;

        msg!(”✅ Created user PDA: {}”, user.key());
        msg!(”   Owner: {}”, user.owner);
        msg!(”   Name: {}”, name);
        msg!(”   Created at: {}”, user.created_at);
        Ok(())
    }

    /// Update name field (only the owner can do it).
    /// No realloc needed as long as new_name.len() ≤ MAX_NAME.
    pub fn update_name(ctx: Context<UpdateUser>, new_name: String) -> Result<()> {
        require!(
            new_name.as_bytes().len() <= UserAccount::MAX_NAME,
            ErrorCode::NameTooLong
        );

        let user = &mut ctx.accounts.user_account;
        msg!(”✏️ Updating user: {}”, user.key());
        msg!(”   Old name: {}”, user.name);
        user.name = new_name.clone();
        msg!(”   New name: {}”, new_name);
        Ok(())
    }

    /// Close account and refund rent to the authority (owner).
    pub fn close_user(_ctx: Context<CloseUser>) -> Result<()> {
        msg!(”🧹 Closed user PDA and refunded rent.”);
        Ok(())
    }
}

#[account]
#[derive(InitSpace)]
pub struct UserAccount {
    pub owner: Pubkey,              // 32
    #[max_len(32)]
    pub name: String,               // 4 + up to 32 bytes
    pub created_at: i64,            // 8
    pub bump: u8,                   // 1
}

impl UserAccount {
    pub const MAX_NAME: usize = 32;
    // Total space to allocate at init time:
    // 8 (discriminator) + INIT_SPACE computed by Anchor from the struct
    pub const SPACE: usize = 8 + Self::INIT_SPACE;
}

#[derive(Accounts)]
pub struct CreateUser<’info> {
    #[account(mut)]
    pub authority: Signer<’info>,

    /// PDA: seeds = [”user”, authority]
    #[account(
        init,
        payer = authority,
        space = UserAccount::SPACE,
        seeds = [b”user”, authority.key().as_ref()],
        bump
    )]
    pub user_account: Account<’info, UserAccount>,

    pub system_program: Program<’info, System>,
}

#[derive(Accounts)]
pub struct UpdateUser<’info> {
    pub authority: Signer<’info>,

    #[account(
        mut,
        constraint = user_account.owner == authority.key(),
        seeds = [b”user”, authority.key().as_ref()],
        bump = user_account.bump
    )]
    pub user_account: Account<’info, UserAccount>,
}

#[derive(Accounts)]
pub struct CloseUser<’info> {
    #[account(mut)]
    pub authority: Signer<’info>,

    #[account(
        mut,
        close = authority,
        constraint = user_account.owner == authority.key(),
        seeds = [b”user”, authority.key().as_ref()],
        bump = user_account.bump
    )]
    pub user_account: Account<’info, UserAccount>,
}

#[error_code]
pub enum ErrorCode {
    #[msg(”Name too long (max 32 bytes).”)]
    NameTooLong,
}

Overview:

What it stores: A per-wallet UserAccount at a PDA derived from [“user”, authority].

Instructions:

• create_user(name): creates and initializes the PDA with owner, name, created_at, bump.

• update_name(new_name): only the owner can change name, within the pre-allocated limit

• close_user(): closes the PDA and refunds rent to the owner.

Program Id (why it matters)

declare_id!(”<YOUR-PROGRAM-ID>”);

• Anchor bakes this value into the binary.

• At runtime, it must equal the on-chain program account you’re invoking, or you’ll get DeclaredProgramIdMismatch.

• Make sure declare_id!, Anchor.toml, and your client all use the same pubkey before you build/deploy.

The account: layout & size

#[account]
#[derive(InitSpace)]
pub struct UserAccount {
    pub owner: Pubkey,              // 32
    #[max_len(32)]
    pub name: String,               // 4 + up to 32 bytes
    pub created_at: i64,            // 8
    pub bump: u8,                   // 1
}

• Anchor will compute UserAccount::INIT_SPACE.

• When initializing, allocate 8 + UserAccount::INIT_SPACE (the extra 8 is the discriminator).

• Enforce the length at runtime (require!(name.as_bytes().len() <= 32, …)).

• This avoids “serialize to unexpected length” failures.

• Remember: emojis/multibyte chars count as multiple bytes.

PDAs, seeds, and bump

PDA derivation:

• PDA = find_program_address([”user”, authority_pubkey], program_id)

• Why bump exists: it’s the one-byte nonce that forces the derived address off the ed25519 curve so it can be program-owned.

• Store bump on the account so you can reference it in constraints:

seeds = [b”user”, authority.key().as_ref()], bump = user_account.bump

Note: The bump is the single byte Anchor/SDK found to make the address fall off the ed25519 curve (so it’s program-owned). You store it so you can re-derive the PDA later in constraints.

Important derivations overview

#[account] : This derivation above struct means THIS struct is an on-chain account (in our case UserAccount) that has: lamports , owner , data …

#[account(...)] : Above each field in each struct (that was derived with #derive(Accounts)) we will have this derivation which mean that this field is an account and this will declare its constraints

#[derive(Accounts)] : This macro tells Anchor “This struct describes the accounts required to call the instruction”

Anchor uses it to:

• deserialize account inputs

• enforce constraints (seeds, mutability, ownership)

• automatically derive PDAs

• perform runtime validation before entering your handler

Instruction: create_user

object overview

#[derive(Accounts)]
pub struct CreateUser<’info> {
    #[account(mut)]
    pub authority: Signer<’info>,

    /// PDA: seeds = [”user”, authority]
    #[account(
        init,
        payer = authority,
        space = UserAccount::SPACE,
        seeds = [b”user”, authority.key().as_ref()],
        bump
    )]
    pub user_account: Account<’info, UserAccount>,

    pub system_program: Program<’info, System>,
}

pub authority: Signer<’info> : This field represents the caller of the instruction, and the Signer represents that this account must sign the transaction, it have #[account(mut)] because this signer will pay for the account creation fee, so their balance will change.

pub user_account: Account<’info, UserAccount> : This is the PDA account that we are creating. It is the on-chain data structure it will store what was declared in UserAccount object.

Notes

• init: creates the PDA and zero-inits data.

• payer: authority funds rent.

• space: uses 8 + INIT_SPACE (as declared in impl UserAccount).

• seeds: uses “user” constant string and authority address.

• bump: anchor know how to autofill it (used to find address off curve).

pub system_program: Program<’info, System> : Any init must call the system program under the hood which allocate new account, assign ownership, transfer lamports from payer. This field is required for account creation, lamport transfers, PDA initialization

handler overview

pub fn create_user(ctx: Context<CreateUser>, name: String) -> Result<()> {
        // Enforce max length in BYTES (UTF-8). Emojis count as multiple bytes.
        require!(
            name.as_bytes().len() <= UserAccount::MAX_NAME,
            ErrorCode::NameTooLong
        );

        let user = &mut ctx.accounts.user_account;
        // Stores the wallet that created this profile
        user.owner = ctx.accounts.authority.key();
        // This assigns into the fixed allocated space Anchor reserved via #[max_len]
        user.name = name.clone(); // fits because we sized with MAX_NAME
        // Clock sysvar contains the current cluster time
        user.created_at = Clock::get()?.unix_timestamp;
        // Why store the bump:
        //   we used: PDA = find_program_address([”user”, authority], bump)
        //   We don’t want to recompute bump manually later
        //   update_name and close_user enforce (We will see it later)
        user.bump = ctx.bumps.user_account;
        ...
}

Context<CreateUser>: Gives you validated access to all accounts declared in the CreateUser struct. Anchor has already validated all constraints and created/allocated required accounts

Instruction: update_name

object overview

#[derive(Accounts)]
pub struct UpdateUser<’info> {
    // Same as before, why not mut? no lamports changed here
    pub authority: Signer<’info>,
    
    // mut - because we modify the name, If you remove mut, Solana will reject the transaction
    // This is our access control rule, It ensures that only the original creator of the profile can update it
    // seeds - ensure correct automatic derivation
    // bump - because the PDA was initialized earlier using ctx.bumps.user_account.Storing and reusing the bump guarantees PDA stability.
    #[account(
        mut,
        constraint = user_account.owner == authority.key(),
        seeds = [b”user”, authority.key().as_ref()],
        bump = user_account.bump
    )]
    pub user_account: Account<’info, UserAccount>,
}

handler overview

pub fn update_name(ctx: Context<UpdateUser>, new_name: String) -> Result<()> {
        // Enforce max length in BYTES (UTF-8). Emojis count as multiple bytes.
        require!(
            new_name.as_bytes().len() <= UserAccount::MAX_NAME,
            ErrorCode::NameTooLong
        );

        let user = &mut ctx.accounts.user_account;
        msg!(”✏️ Updating user: {}”, user.key());
        msg!(”   Old name: {}”, user.name);
        user.name = new_name.clone();
        msg!(”   New name: {}”, new_name);
        Ok(())
    }

This instruction is straight-forward, it updates the already existing PDA’s name with new_name

Instruction: close_user

#[derive(Accounts)]
pub struct CloseUser<’info> {
    // Same as previous, this time is mut because balance increases with the refunded rent
    #[account(mut)]
    pub authority: Signer<’info>,

    // mut: we’re modifying (actually zeroing/closing) this account.
    // close: tells Anchor to refund all lamports from user_account to authority and then close the account when the instruction finishes. You don’t call anything manually—Anchor performs the close in the account’s “drop” (teardown) phase.
    // seeds: same as previous
    // bump: same as previous
    #[account(
        mut,
        close = authority,
        constraint = user_account.owner == authority.key(),
        seeds = [b”user”, authority.key().as_ref()],
        bump = user_account.bump
    )]
    pub user_account: Account<’info, UserAccount>,
}

handler overview

// Everything is done automatically
pub fn close_user(_ctx: Context<CloseUser>) -> Result<()> {
    msg!(”🧹 Closed user PDA and refunded rent.”);
    Ok(())
}

client side (Ts)

Save this file in scripts/solana_accounts.ts

Note: For this code to run we need to export 2 env variables:

export ANCHOR_PROVIDER_URL=”http://127.0.0.1:8899”

export ANCHOR_WALLET=”$HOME/.config/solana/id.json”

import * as anchor from “@coral-xyz/anchor”;
import type { Program } from “@coral-xyz/anchor”;
import { LAMPORTS_PER_SOL, PublicKey } from “@solana/web3.js”;
import { SolanaAccounts } from “../target/types/solana_accounts”;

async function ensureAirdrop(connection: anchor.web3.Connection, pubkey: PublicKey, min = 2 * LAMPORTS_PER_SOL) {
  const bal = await connection.getBalance(pubkey);
  if (bal >= min) return;
  const sig = await connection.requestAirdrop(pubkey, min);
  await connection.confirmTransaction(sig, “confirmed”);
}

(async () => {
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);

  // Use Anchor workspace (uses generated IDL/types under target/)
  const program = anchor.workspace.solanaAccounts as Program<SolanaAccounts>;
  const wallet = provider.wallet as anchor.Wallet;

  // Make sure we have SOL (useful on localhost)
  try { await ensureAirdrop(provider.connection, wallet.publicKey); } catch {}

  // PDA: seeds = [”user”, authority]
  // Seeds must match the program’s #[account(seeds = [b”user”, authority])]. From Rust!
  const [userPda] = PublicKey.findProgramAddressSync(
    [Buffer.from(”user”), wallet.publicKey.toBuffer()],
    program.programId
  );

  console.log(”Wallet:”, wallet.publicKey.toBase58());
  console.log(”Program:”, program.programId.toBase58());
  console.log(”User PDA:”, userPda.toBase58());

  // 1) createUser
  //    Derivable accounts (PDAs) are autofilled by Anchor
  //    No need to pass programId or PDA here! it knows from the context.
  const sig1 = await program.methods
    .createUser(”0xByteBeetle”)
    .accounts({ authority: wallet.publicKey }) // derivable accounts are autofilled
    .rpc();
  console.log(”createUser tx:”, sig1);

  // Fethch and log the created account
  const acct1 = await program.account.userAccount.fetch(userPda);
  console.log(”After create:”, {
    owner: acct1.owner.toBase58(),
    name: acct1.name,
    created_at: new Date(acct1.createdAt.toNumber() * 1000).toISOString(),
    bump: acct1.bump,
  });

  // 2) updateName
  const sig2 = await program.methods
    .updateName(”bytebeetle”)
    .accounts({ authority: wallet.publicKey })
    .rpc();
  console.log(”updateName tx:”, sig2);

  const acct2 = await program.account.userAccount.fetch(userPda);
  console.log(”After update:”, { name: acct2.name });

  // 3) closeUser
  const sig3 = await program.methods
    .closeUser()
    .accounts({ authority: wallet.publicKey })
    .rpc();
  console.log(”closeUser tx:”, sig3);

  try {
    await program.account.userAccount.fetch(userPda);
  } catch {
    console.log(”PDA closed (fetch failed as expected).”);
  }

  console.log(”Done ✅”);
})().catch((e) => {
  console.error(e);
  process.exit(1);
});

Note: Explanations inside the code.

Run it all together

Open new terminal in our project root directory and run:

• solana config set --url https://api.devnet.solana.com:will set the default node RPC URL

• solana-keygen new -o ~/.config/solana/id.json: It will generate a dummy wallet for this test

• solana airdrop 1: It will fund your dummy wallet with 10 SOL (needed for deployments and execution), probably more is needed you can use this faucet

• solana-keygen new -o target/deploy/solana_accounts-keypair.json --no-bip39-passphrase: It will generate the keypair for the program.
  Paste this pubkey into:
  1. programs/solana_accounts/src/lib.rs: declare_id(”...”)
2. Anchor.toml: [programs.devnet].solana_accounts=”“

• solana-keygen pubkey target/deploy/solana_accounts-keypair.json: Will print the generated programID.

• Put pubkey into both: declare_id!(”<YOUR-PROGRAM-ID>”) and in Anchor.toml under [programs.devnet] where solana_accounts = <YOUR-PROGRAM-ID>:

For example(For you the address will be different):

And run:

solana-keygen new -o target/deploy/solana_accounts-keypair.json --no-bip39-passphrase
solana-keygen pubkey target/deploy/solana_accounts-keypair.json
# Paste this pubkey into:
#   - programs/solana_accounts/src/lib.rs: declare_id!(”...”)
#   - Anchor.toml: [programs.devnet].solana_accounts = “...”

anchor clean
anchor build
anchor deploy

You should see something like:

then run

# Reminder: you need to run this before:
# export export ANCHOR_PROVIDER_URL=”https://api.devnet.solana.com”
# export ANCHOR_WALLET=”$HOME/.config/solana/id.json”

pnpm ts-node scripts/solana_accounts.ts

You should see something like:

Resources

• Anchor code can be found here

After reading the previous post we have a knowledge about Solana architecture, in this post we will learn that in Solana, everything revolves around accounts.
Every piece of state from your tokens to your program data lives inside an account. Programs themselves are stateless, they only read and modify data that accounts expose to them. Once you understand that, Solana’s entire design starts to make sense.

In this post, we’ll slow down and unpack what “an account” really means.
We’ll go through its structure, ownership rules, and how Solana uses Program-Derived Addresses (PDAs) to create predictable and secure addresses without private keys. You’ll also learn how different types of accounts fit together, from system accounts managed by the runtime to program state accounts that store your app’s logic or user data.

• What makes an account the basic unit of state on Solana

• Account Types

• What is Program derived address (PDA)

• How Solana enforces ownership, rent, and access

In the next blog, we’ll explore what is Anchor and see how these concepts map to real code and how Anchor’s account macros simplify safety and boilerplate.

Previous part

• Understanding Solana - Part 1

What makes an account the basic unit of state on Solana

The most important thing to understand about Solana is that unlike most blockchains where “contracts” hold their own state internally, Solana separates code and data completely.
Programs (smart contracts) are pure logic, they don’t own persistent storage.
Instead, all persistent data lives in accounts, which are on-chain data containers managed by the runtime.

You can think of an account as a self-contained piece of state with:

struct Account {
    // num of lamports in the account
    lamports:   uint64,
    // data held in this account
    data:       bytes,
    // PubKey that owns this account. If executable, the program that loads this account.
    owner:      Pubkey,
    // this account’s data contains a loaded program (and is now read-only)
    executable: bool,
    // the epoch at which this account will next owe rent
    rent_epoch: Epoch,
}

Every instruction that runs on Solana explicitly lists which accounts it wants to read or write.
The runtime enforces access rules:

• Only the account’s owner program can modify its data.

• Only the account’s signer (or a PDA acting as signer, PDA will be explained in next section) can authorize transfers or ownership changes.

This strict separation achieves two things:

1. Parallelism: since programs operate only on the accounts listed in the transaction, Solana can execute unrelated transactions concurrently.

2. Security and clarity: a program cannot accidentally modify global state; it must be given explicit permission to touch each account.

In short, accounts are the atomic unit of state on Solana.
If Ethereum’s equivalent is a contract with internal storage slots, Solana’s model externalizes that: each “slot” becomes its own addressable account on-chain.

Everything you interact with: users, tokens, pools, NFTs, even the Solana runtime itself is built on top of these accounts.

What is Program derived address (PDA)

Solana doesn’t allow programs to hold private keys.
Yet, sometimes your program needs an address it can own and control deterministically, for example, a vault to store user deposits, or a metadata account tied to a specific mint.
That’s exactly what Program-Derived Addresses (PDAs) provide.

A PDA is a special kind of account address that is:

• Deterministically derived from a set of seeds and a program ID

• Guaranteed not to collide with any address that has a valid Ed25519 private key.

Because PDAs don’t correspond to real keypairs, they cannot be signed using a private key.
Instead, the Solana runtime lets the owning program “sign” on behalf of that PDA during an instruction but only if the PDA was derived with the program’s own ID.

How PDAs are generated

A PDA is derived like that with the help of solana-sdk on rust:

Pubkey::find_program_address(seeds: &[&[u8]], program_id: &Pubkey)

This function tries different “bump” values: It iterate bump values by starting at 255 and decrements by 1 until a valid PDA is found that is not on the Ed25519 curve (i.e., cannot have a private key).
That results a unique PDA is created for the combination of:

• program_id

• and the seeds array.

Example:

let (vault_pda, bump) =
    Pubkey::find_program_address(&[b”my_vault”, user.key().as_ref()], &program_id);

Now vault_pda will always be the same for this user and program no need to store it anywhere.

Overview:

How PDAs “sign”

When your program makes a cross-program invocation (CPI) (Don’t worry it will be covered in later chapters, now we only want to understand the sign effect) that needs the PDA to act as a signer, for example, to transfer tokens from a PDA’s account
you use the function invoke_signed() and pass the same seeds and bump used to derive the PDA.

Example:

invoke_signed(
    &instruction,
    &account_infos,
    &[&[b”my_vault”, user.key().as_ref(), &[bump]]],
)?;

The runtime checks that those seeds and bump match a valid PDA for your program ID. If they do, it lets your program “sign” as that PDA.
No private keys, no risk of exposure.

Why PDAs matter

PDAs are at the heart of how complex Solana programs structure state.
They let you:

• Create per-user or per-pool state accounts deterministically (like [”profile”, user] or [”pool”, token_a, token_b]).

• Build vaults or treasuries controlled solely by your program.

• Prevent arbitrary users from hijacking your storage addresses.

• Avoid having to store mapping data on-chain (you can recompute addresses instead).

They are what make Solana’s stateless programs practical, safe, and composable.

Account Types

There are two basic categories that accounts fall into:

• Program accounts: Accounts that contain executable code

• Data accounts: Accounts that do not contain executable code, but holds information

This separation means that a program’s executable code and its state are stored in separate accounts.

Program accounts

A program account stores the compiled bytecode that defines how a Solana program behaves.

Key characteristics

• Executable flag: executable = true

• Owner: always the BPF Loader

• Data: the actual code of the program

Program accounts do not hold user state or variables.
When your transaction calls a program, Solana loads this executable account into memory and executes the code inside it.

Data accounts

Data accounts store all persistent state for your application: user profiles, pools, vaults, mints, and so on.
They are owned by a program, and only that program can modify their contents.

Within this broad category, you’ll encounter several important sub-types:

Program state account:

Custom accounts that hold the on-chain data for your program.
They represent things like: liquidity pool, user’s staking position, configuration record and so on…

Key properties

• owner = your program’s public key

• executable = false

• must hold enough lamports to be rent-exempt (will be covered in next section)

• usually Program-Derived Addresses (PDAs) to ensure deterministic, secure ownership (Explained above)

Example

Address:  pool_pda (derived from [”pool”, token_a, token_b])
Owner:    MyDex111111111111111111111111111111111111111
Data:     { token_a, token_b, reserves, bump }

System accounts:

Accounts that are managed by the System Program.
These include:

• Wallet accounts that hold SOL and can sign transactions

• Temporary storage or uninitialized accounts before they’re assigned to a program

• Upgrade or admin authorities (often simple keypair accounts)

System accounts are the backbone of Solana’s runtime. They can send SOL, pay rent, and be reassigned to another program as their owner.

Sysvar accounts

Read-only system-provided accounts that expose internal blockchain data to programs.
Instead of embedding runtime data into every instruction, Solana provides them through these predefined accounts. More data can be found here.

How Solana enforces ownership, rent, and access

Now that we’ve seen the different types of accounts, it’s important to understand how Solana controls who can read, write, or move lamports and how it ensures the network stays economically stable through rent.

Ownership

Every account has an owner field a public key that identifies the program authorized to modify its data.

• Only the owning program can change an account’s data bytes.

• The System Program can change an account’s owner (using assign) or lamport balance (using transfer).

• User wallets are just system accounts whose owner is the System Program.

• When your custom program creates an account, it sets itself as the owner, making it the only program that can write to that account’s data.

Example:

account.owner = <your program id>

means that only your program can modify this account’s internal data field no other program can. This strict owner–writer rule prevents accidental or malicious modification of another program’s state.

Access Control (Signers and Writable Flags)

When a transaction executes, it must explicitly list all accounts the instruction will use.
For each account, the transaction specifies:

• Whether the account is read-only or writable

• Whether it is a signer

The runtime enforces these flags:

• Writable accounts are the only ones that can have their data or lamports modified.

• Signer accounts are those that have authorized the transaction typically user wallets or PDAs through invoke_signed.

• Programs cannot arbitrarily access any on-chain data. They only see what’s passed into the instruction’s context.

This explicit access model enables parallel transaction execution, since Solana knows which accounts each instruction touches.

Rent and Rent Exemption

Every account must pay rent, which is a small cost to occupy on-chain storage. However, most programs make accounts rent-exempt by depositing enough lamports upfront.

The rent-exempt minimum depends on:

• the account’s data size (number of bytes), and

• the current rent rate (available via the SysvarRent account).

Key points:

• If an account’s lamports drop below the rent-exempt threshold, the runtime can reclaim it.

• Rent-exempt accounts never lose lamports or get purged.

• Programs typically calculate rent like this:

let rent = Rent::get()?;
let lamports = rent.minimum_balance(space);

Up Next

Once you have this foundation, we’ll move from theory to practice.
In the next post, we’ll open up Anchor in Rust, create our first on-chain program, and see how all these ideas: ownership, seeds, PDAs, and account sizing come together in real code.

You’ll learn how Anchor’s macros automatically enforce the same rules we explored conceptually here, making Solana development both safer and more ergonomic.

Factories make it easy to deploy many contracts, but each deployment still costs gas for full bytecode.
What if you could deploy thousands of instances for just a fraction of that cost?

That’s the idea behind EIP-1167, the Minimal Proxy (or clone) pattern.
Instead of redeploying the entire logic each time, a minimal proxy holds only a few bytes of code that delegate every call to a single implementation contract.
Every instance behaves like a full contract but reuses the same logic: saving gas, storage, and bytecode size.

In this post, we’ll cover:

• How EIP-1167 reduces deployment cost using a tiny bytecode stub

• The difference between normal proxies and clones

• A Foundry walkthrough for deploying and verifying minimal proxies on-chain

By the end, you’ll understand how different protocols scale massive deployments without redeploying logic again and again.

Minimal proxy (EIP-1167)

Not all proxies are about upgrades. Sometimes, the goal isn’t to keep one address stable forever ,  it’s to stamp out many identical contracts cheaply, each with its own state but sharing the same logic. That’s exactly what EIP-1167 “Minimal Proxy” contracts (aka clones) are designed for.

What’s a Minimal Proxy?

A clone is just ~45 bytes of runtime code that forwards every call to a fixed implementation using DELEGATECALL.

• The logic contract (the “master copy”) holds all the functions.

• Each clone stores no logic, only data. Calls to the clone are executed in its storage, but using the master copy’s code.

• The only difference between clones is their state, not their code.

Because the implementation address is baked into the clone’s bytecode, the clone can’t be upgraded later. This makes them extremely small, gas-efficient, and predictable, but also fundamentally different from upgradeable proxies.

How the Clone’s Bytecode Works

The “magic” behind EIP-1167 is that all clones share the same tiny runtime code, with just one variable part: the embedded implementation address.

The canonical runtime looks like this (hex):

363d3d373d3d3d363d73<20-byte-impl>5af43d82803e903d91602b57fd5bf3

// <20-byte-impl> can be: 0xbebebebebe.... (the shared logic address)

OPcode explanation:

Press enter or click to view image in full size

Note: A real world example can be a dex pair where each liquidity pair is a clone with its own reserves, but all share the same pair logic.

Minimal example

minimalProxy.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/* ---------------------------------- */
/* 1) Implementation (shared logic)   */
/* ---------------------------------- */
contract Counter {
    address public owner;
    uint256 public value;
    bool private _initialized;
    // Called via the clone after deployment
    function initialize(address _owner, uint256 start) external {
        require(!_initialized, “already initialized”);
        _initialized = true;
        owner = _owner;
        value = start;
    }
    function inc() external {
        require(msg.sender == owner, “not owner”);
        unchecked { value += 1; }
    }
    // Optional: prevent initializing the logic contract itself
    constructor() {
        _initialized = true;
    }
}
/* ---------------------------------- */
/* 2) Minimal Clone Factory           */
/* ---------------------------------- */
contract CounterCloneFactory {
    event CloneCreated(address indexed clone, address indexed owner, uint256 start, bytes32 salt);
    /* ---- Internal helpers: build creation code for the clone ---- */
    // Clone creation code = small prologue that returns the 45-byte runtime
    function _cloneCreationCode(address impl) internal pure returns (bytes memory code) {
        // creation: 3d602d80600a3d3981f3  -> return(next 0x37 bytes)
        // runtime:  363d3d373d3d3d363d73 <impl> 5af43d82803e903d91602b57fd5bf3
        code = abi.encodePacked(
            hex”3d602d80600a3d3981f3”,
            hex”363d3d373d3d3d363d73”,
            impl,
            hex”5af43d82803e903d91602b57fd5bf3”
        );
    }
    /* ---- Deploy a clone with CREATE ---- */
    function createClone(address implementation, address owner_, uint256 start_)
        external
        returns (address clone)
    {
        bytes memory code = _cloneCreationCode(implementation);
        assembly {
            clone := create(0, add(code, 0x20), mload(code))
            if iszero(clone) { revert(0, 0) }
        }
        // Initialize immediately (constructors don’t run through clones)
        (bool ok, ) = clone.call(abi.encodeWithSignature(”initialize(address,uint256)”, owner_, start_));
        require(ok, “init failed”);
        emit CloneCreated(clone, owner_, start_, bytes32(0));
    }
    /* ---- Deploy a deterministic clone with CREATE2 ---- */
    function createCloneDeterministic(address implementation, address owner_, uint256 start_, bytes32 salt)
        external
        returns (address clone)
    {
        bytes memory code = _cloneCreationCode(implementation);
        assembly {
            clone := create2(0, add(code, 0x20), mload(code), salt)
            if iszero(clone) { revert(0, 0) }
        }
        (bool ok, ) = clone.call(abi.encodeWithSignature(”initialize(address,uint256)”, owner_, start_));
        require(ok, “init failed”);
        emit CloneCreated(clone, owner_, start_, salt);
    }
}

Lets deploy it and run some on chain functions:

Start the node:

anvil

Deploy the contract:

// Deployment of the shared logic
forge create src/minimalProxy.sol:Counter \
  --rpc-url localhost:8545 \
  --private-key <YOUR-ANVIL-PK> --broadcast

// Expected output:
// [⠊] Compiling...
// No files changed, compilation skipped
// Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
// Deployed to: 0x5FC8d32690cc91D4c39d9d3abcBD16989F875707
//Transaction hash: 0x43f37888e5c370cc1a398f1891cea860a80815fdf59716d4e2d8adb198b5edb8
// Deployment of the minimal proxy factory 
forge create src/minimalProxy.sol:CounterCloneFactory \
  --rpc-url localhost:8545 \
  --private-key <YOUR-ANVIL-PK> --broadcast
// Expected output:
// [⠊] Compiling...
// No files changed, compilation skipped
// Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
// Deployed to: 0x0165878A594ca255338adfa4d48449f69242Eb8F
// Transaction hash: 0x6ddac050694baf16fc7bcfde90dcf0516bd1777b6a1b8ea23fd8019bc20391b2

Create Some clones:

// Deploy first instance
cast send 0x0165878A594ca255338adfa4d48449f69242Eb8F \
  “createClone(address,address,uint256)(address)” \
  0x5FC8d32690cc91D4c39d9d3abcBD16989F875707 <YOUR-ANVIL-PK-ADDR> 100 \  
  --rpc-url localhost:8545 \
  --private-key <YOUR-ANVIL-PK>

// On success expected this log:
// logs [
// {”address”:”0x0165878a594ca255338adfa4d48449f69242eb8f”,
//    “topics”:[”0x6823f533242a9c540bd8ab230da11a7199723745abb9d484732bb57b4f34d4d1”,
//              “0x0000000000000000000000003b02ff1e626ed7a8fd6ec5299e2c54e1421b626b”,
//              “0x000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266”],
//              “data”:”0x00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000000”,
//              “blockHash”:”0xe7748e4f28f2492642e9f64e7252fd40e85079e5211523b7b5b35c82adceff69”,”blockNumber”:”0x8”,”blockTimestamp”:”0x68b92822”,”transactionHash”:”0xe48d780a8268235887019e74d62e09a7e09164aaa37bdea60a2c0aa97f81d00c”,
//              “transactionIndex”:”0x0”,
//              “logIndex”:”0x0”,
//              “removed”:false}]
// 
// From logs we can see that the address is: 0x3b02ff1e626ed7a8fd6ec5299e2c54e1421b626b
// Deploy second instance
cast send 0x0165878A594ca255338adfa4d48449f69242Eb8F \
  “createClone(address,address,uint256)(address)” \
  0x5FC8d32690cc91D4c39d9d3abcBD16989F875707 <YOUR-ANVIL-PK-ADDR> 100 \
  --rpc-url localhost:8545 \
  --private-key <YOUR-ANVIL-PK>
// On success expected this log:
// [{”address”:”0x0165878a594ca255338adfa4d48449f69242eb8f”,
//   “topics”:[”0x6823f533242a9c540bd8ab230da11a7199723745abb9d484732bb57b4f34d4d1”,
//   “0x000000000000000000000000ba12646cc07adbe43f8bd25d83fb628d29c8a762” ....
//
// From logs we can see that the address is: 0xba12646cc07adbe43f8bd25d83fb628d29c8a762

Lets do some reads and writes:

// Read the value of the first proxy
cast call 0x3b02ff1e626ed7a8fd6ec5299e2c54e1421b626b “value()(uint256)” --rpc-url localhost:8545
// Expected output: 100

// Read the value of the first proxy
cast call 0xba12646cc07adbe43f8bd25d83fb628d29c8a762 “value()(uint256)” --rpc-url localhost:8545
// Expected output: 100
// Write operation on first contract
cast send 0x3b02ff1e626ed7a8fd6ec5299e2c54e1421b626b “inc()” \
  --rpc-url http://localhost:8545 \
  --private-key <YOUR-ANVIL-PK>
// Read the value of the first proxy
cast call 0x3b02ff1e626ed7a8fd6ec5299e2c54e1421b626b “value()(uint256)” --rpc-url localhost:8545
// Expected output: 101
// Read the value of the first proxy
cast call 0xba12646cc07adbe43f8bd25d83fb628d29c8a762 “value()(uint256)” --rpc-url localhost:8545
// Expected output: 100

Note: As we see each proxy holds its own storage while pointing to some shared logic. We used here the factory pattern combined with proxy.

Why Not Just Deploy Full Contracts in a Factory?

The simple CounterFactory example works fine: each call to createCounter deploys a full Counter contract. But there’s a big tradeoff: gas costs. Every time you deploy a contract on EVM, you pay gas proportional to the size of the bytecode you’re putting on-chain.

• A normal Counter might have a few kilobytes of bytecode.

• Deploying 10,000 counters = writing that same bytecode 10,000 times into EVM state.

That’s expensive and wasteful: the code never changes, it’s just repeated.

Summary

Minimal proxies take the factory concept to its logical extreme: reuse everything except state.
Instead of redeploying full logic bytecode, each clone stores just a 45-byte delegatecall stub that forwards execution to a shared implementation.
This design cuts deployment costs dramatically while maintaining isolated state for every instance a perfect fit for protocols that need to spin up large numbers of identical contracts.

It’s the pattern behind many famous protocols, and it’s a foundational tool for any protocol aiming to scale efficiently on the EVM.
Factories create consistency, minimal proxies make it affordable.

By now, we’ve seen how contracts get deployed (CREATE and CREATE2 in this post) and how they can be upgraded through proxies like EIP-1967 (in this post) and EIP-1822 (in this post).
But most real-world systems don’t stop there they need to deploy many contracts, not just one.

That’s where factories come in.
A factory is a smart contract that knows how to deploy, initialize, and track other contracts on-chain. Instead of manually deploying every instance, you call the factory once and it handles everything: creation, configuration, and event emission for indexing.

This pattern powers everything from DEX pairs to vaults, wallets, and DAOs anywhere a protocol needs predictable, standardized deployments.

In this post, we’ll cover:

• How factories use CREATE and CREATE2 under the hood

• Why deterministic deployments matter for discoverability and security

• A full Foundry example of deploying and interacting with contracts via a factory

By the end, you’ll understand why nearly every modern protocol includes a factory and how to build your own to safely scale deployments across the EVM.

Factories

Up to now, we’ve looked at how contracts are deployed and how proxies help with upgrades. But there’s another pattern you’ll see everywhere in production EVM code: the factory.

A factory is simply a contract that knows how to deploy other contracts. Instead of deploying each new contract by hand, you interact with a single factory contract that:

• Spins up new instances (CREATE or CREATE2)

• Initializes them safely

• Emits events so you can track them on-chain

Think of it as an assembly line for contracts. You give the factory the parameters, it returns a fresh instance.

Why Factories?

Factories are used by almost every major protocol because they bring:

• Standardization: every instance is deployed with the same code path.

• Discoverability: you can query factory events or mappings to find all deployed instances.

• Initialization safety: the factory usually calls the initializer right after deployment, so you don’t end up with half-baked contracts someone else can hijack.

• Determinism: with CREATE2, a factory can precompute an instance’s address before it even exists (great for “counterfactual” wallets or deterministic pool addresses).

Example:

basicfactory.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract Counter {
    address public owner;
    uint256 public value;
    constructor(address _owner, uint256 start) {
        owner = _owner;
        value = start;
    }
    function inc() external {
        require(msg.sender == owner, “not owner”);
        value += 1;
    }
}

contract CounterFactory {
    event CounterCreated(address indexed counter, address indexed owner, uint256 start);

    function createCounter(address owner_, uint256 start_) external returns (address addr) {
        for (uint256 i = 0; i < 5; i++) {
            Counter c = new Counter(owner_, start_);
            addr = address(c);
            emit CounterCreated(addr, owner_, start_);
        }
    }
}

Note: createCounter here is not deployed with CREATE2 but it could be easily achieved by getting the bytecode of Counter contract and executing create2(...)

Setup the node:

anvil

Deploy the contract and call it

// Deploy the factory contract
forge create src/basicfactory.sol:CounterFactory \
  --rpc-url localhost:8545 \
  --private-key <YOUR-ANVIL-PK>

// Expected output:
// [⠊] Compiling...
// [⠒] Compiling 1 files with Solc 0.8.30
// [⠢] Solc 0.8.30 finished in 52.99ms
// Compiler run successful!
// Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
// Deployed to: 0x610178dA211FEF7D417bC0e6FeD39F05609AD788
// Transaction hash: 0x5c25685d15aacde7128a648d48dcd8b975ffc6e20aac9605bce2f582125b6437
// Call the factory
cast send 0x610178dA211FEF7D417bC0e6FeD39F05609AD788 \
  “createCounter(address,uint256)(address)” \
  0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 42 \
  --rpc-url localhost:8545 --private-key <YOUR-ANVIL-PK>
// Logs expected in after this call with topics for each emited event
// and there you will find the contract addresses

Summary

Factories turn contract creation into a repeatable process.
Instead of deploying each instance manually, you get a single trusted entry point that handles deployment, initialization, and tracking making large on-chain systems both safer and easier to manage.

They’re the backbone behind scalable architectures in DeFi, from liquidity pools to vaults and smart wallets.
Once you understand factories, you can start designing protocols that deploy and manage entire ecosystems of contracts automatically.

By the end, you’ll understand why nearly every modern protocol includes a factory — and how to build your own to safely scale deployments across the EVM.

In the previous post, we explored the Transparent Proxy (EIP-1967) pattern where the proxy holds both the forwarding logic and the upgrade control plane.
That design works, but it comes with baggage: an extra admin contract, more bytecode, and slightly higher gas overhead.

UUPS (Universal Upgradeable Proxy Standard, EIP-1822) takes a leaner approach.
It keeps the proxy as a minimal forwarder and moves the upgrade logic into the implementation contract itself.
Instead of calling upgradeTo on the proxy, you call it on the implementation through the proxy.
This makes the proxy reusable, smaller, and easier to reason about, while each implementation defines its own upgrade rules.

In this post, you’ll learn:

• How UUPS differs from the Transparent Proxy pattern

• The role of proxiableUUID and the keccak256(”PROXIABLE”) storage slot

• How to deploy and upgrade a UUPS proxy end-to-end with Foundry

By the end, you’ll understand how modern protocols (and OpenZeppelin’s UUPSUpgradeable contracts) achieve upgradability with less overhead and the trade-offs that come with that simplicity.

UUPS proxy (EIP-1822)

Transparent proxies are fine, but they have an extra baggage: you have to maintain both the proxy contract and the upgrade admin logic. UUPS (Universal Upgradeable Proxy Standard) flips that design.

UUPS proxies instead of making the proxy contract responsible for upgrades, UUPS pushes that responsibility into the implementation contract. The proxy itself is just a “dumb forwarder” that delegates all calls. The implementation contains a special function (usually called proxiableUUID or upgradeTo) that knows how to upgrade to a new version. This keeps the proxy very small and reusable, while each implementation can define its own rules for who’s allowed to upgrade.

the address of the Logic Contract is stored at the defined storage position keccak256(”PROXIABLE”)=0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7.

Key differences:

• The proxy is slimmer: no upgrade code inside it.

• Each implementation contract must include an upgrade function (and usually OpenZeppelin’s UUPSUpgradeable mixin).

• Storage layout still matters: if you change storage order between upgrades, you’ll corrupt state.

Example:

UUPSLogicContract.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.12;

// The proxy
contract Proxiable {
    // Code position in storage is keccak256(”PROXIABLE”) = “0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7”
    function updateCodeAddress(address newAddress) internal {
        require(
            bytes32(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7) == Proxiable(newAddress).proxiableUUID(),
            “Not compatible”
        );
        assembly { // solium-disable-line
            sstore(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7, newAddress)
        }
    }
    function proxiableUUID() public pure returns (bytes32) {
        return 0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7;
    }
}
// Controls that only owner can do changes
contract Owned {
    address owner;
    function setOwner(address _owner) internal {
        owner = _owner;
    }
    modifier onlyOwner() {
        require(msg.sender == owner, “Only owner is allowed to perform this action”);
        _;
    }
}

contract LibraryLockDataLayout {
  bool public initialized = false;
}

// Locking mechaninsm.
contract LibraryLock is LibraryLockDataLayout {
    // Ensures no one can manipulate the Logic Contract once it is deployed.
    // PARITY WALLET HACK PREVENTION
    modifier delegatedOnly() {
        require(initialized == true, “The library is locked. No direct ‘call’ is allowed”);
        _;
    }
    function initialize() internal {
        initialized = true;
    }
}

contract ERC20DataLayout is LibraryLockDataLayout {
  uint256 public totalSupply;
  mapping(address=>uint256) public tokens;
}

contract MyToken is Owned, ERC20DataLayout, Proxiable, LibraryLock {
    function constructor1(uint256 _initialSupply) public {
        totalSupply = _initialSupply;
        tokens[msg.sender] = _initialSupply;
        initialize();
        setOwner(msg.sender);
    }
    function updateCode(address newCode) public onlyOwner delegatedOnly  {
        updateCodeAddress(newCode);
    }
    function transfer(address to, uint256 amount) public delegatedOnly {
        require(tokens[msg.sender] >= amount, “Not enough funds for transfer”);
        tokens[to] += amount;
        tokens[msg.sender] -= amount;
    }
}

Note: A lot of precautions added here, the main contract is MyToken that inherits Proxiable. other inherits keep the contract safe from different possible attacks.

UUPSProxy.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.12;

/*
 * Very simplified UUPS pattern.
 * - Proxy stores state and delegates calls.
 * - Implementation holds upgrade logic.
 */
// ---------------- Proxy ----------------
contract UUPSProxy {
    // Code position in storage is keccak256(”PROXIABLE”) = “0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7”
    constructor(bytes memory constructData, address contractLogic) {
        // save the code address
        assembly {
            sstore(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7, contractLogic)
        }
        // call the constructor
        (bool success,  ) = contractLogic.delegatecall(constructData);
        require(success, “Construction failed”);
    }
    // This fallback will actually call the logic contract
    // because every function with databytes will arrive here
    fallback() external payable {
        assembly {
            // load the logic contract address
            let contractLogic := sload(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7)
            calldatacopy(0x0, 0x0, calldatasize())
            // call the logic contract with the databytes
            let success := delegatecall(sub(gas(), 10000), contractLogic, 0x0, calldatasize(), 0, 0)
            let retSz := returndatasize()
            returndatacopy(0, 0, retSz)
            switch success
            case 0 {
                revert(0, retSz)
            }
            default {
                return(0, retSz)
            }
        }
    }
}

Lets spin the node:

anvil

and deploy the two contracts from a different terminal

// Deploy the contract logic
forge create src/UUPSLogicContract.sol:MyToken --rpc-url localhost:8545 --private-key <YOUR-ANVIL-PRIVATE-KEY> --broadcast

// expected output, something like:
// [⠊] Compiling...
// [⠒] Compiling 1 files with Solc 0.8.30
// [⠆] Solc 0.8.30 finished in 69.50ms
// Compiler run successful!
// Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
// Deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
// Transaction hash: 0xfd7f81e7a54dba55a1a6399e465ed9ff67dc0d95a3f2fbbf85542fd7b0ffdf81
// Deploy the UUPS proxy
INIT_DATA=$(cast calldata “constructor1(uint256)” 1000000)
forge create src/UUPSProxy.sol:UUPSProxy --rpc-url localhost:8545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --broadcast --constructor-args “$INIT_DATA” 0x5FbDB2315678afecb367f032d93F642f64180aa3
// expected output, something like:
// [⠊] Compiling...
// No files changed, compilation skipped
// Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
// Deployed to: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
// Transaction hash: 0x60c04bf75c647a9c5bcd73155c8906675247ccf4f25fab20bf76e1b5a4ef129e

Now lets call the auto-generated getter on MyToken contract via the proxy:

// Note that 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 is the proxy address
cast call 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 “totalSupply()(uint256)” --rpc-url http://localhost:8545

Summary

UUPS proxies strip upgradeability down to its simplest form.
The proxy only knows how to forward calls. The implementation handles upgrades through its own updateCode (or upgradeTo) function, secured by access control.

This pattern reduces bytecode size, deployment cost, and complexity but it also puts more responsibility on the implementation contract. A single mistake in upgrade logic can brick the system, which is why production frameworks (like OpenZeppelin’s UUPSUpgradeable) wrap it with guards and the ERC-1967 slot standard.

Understanding UUPS gives you a deeper sense of how real protocols balance immutability with flexibility, and how much power (and risk) lives behind a single delegatecall.

Once you understand how contracts get on-chain, the next big question is how they stay useful after deployment.
Ethereum contracts are immutable by design once the bytecode is there, it can’t be changed. That’s great for trust, but painful for reality: bugs happen, features evolve, and governance rules shift.

To solve that, developers use proxies, minimal contracts that never move, while their logic can be replaced underneath.
They keep the same address, preserve all user state, and route execution to a separate implementation contract using delegatecall.

In this post, we’ll break down the most common proxy pattern: the Transparent Proxy (EIP-1967) and see exactly how it works in practice:

• How delegatecall lets logic live elsewhere while state stays local

• Why EIP-1967 standardizes admin and implementation storage slots

• How to deploy, upgrade, and inspect a proxy on-chain with Foundry

By the end, you’ll understand how protocols like Aave and OpenZeppelin upgrade contracts without breaking users and how to do the same safely.

Proxies and Upgradability

Smart contracts are, by design, immutable. Once deployed, their bytecode can’t be changed. That immutability is great for trust, but painful for real protocols: bugs happen, standards evolve, governance rules change. How do you “upgrade” logic without asking every user to migrate to a new address?

The answer is proxies. Contracts that never change their address but forward calls to an implementation that can be swapped.

The Core Idea

A proxy is a thin contract that:

1. Receives a call.

2. Forwards it (via delegatecall) to another contract, called the implementation.

3. Returns the result to the user.

Because delegatecall executes in the caller’s context, all storage is preserved in the proxy, while the logic lives in the implementation. Swap the implementation → you’ve “upgraded” the contract, but users keep interacting with the same address.

Transparent Proxy (EIP-1967)

Problem: Contracts are immutable, but real systems need fixes and new features.
Solution: A Transparent Proxy keeps one public address and forwards user calls to a swappable implementation. It uses fixed storage slots from
EIP-1967 so tools and audits know exactly where admin/implementation live.

Two faces of the same proxy

User surface (normal callers)

• Any caller that is not the admin hits the proxy’s fallback.

• The proxy delegatecalls to the current implementation and returns the result.

• All state lives in the proxy; the implementation is just logic.

Admin surface (upgrade operator)

• If the caller is the admin, the proxy does not delegate.

• The admin can call explicit management functions like upgradeTo, changeAdmin, etc.

• This prevents an admin from accidentally hitting app code through the fallback (function-selector clashes).

That split is why it’s called transparent: to users the proxy behaves like the app and to the admin it exposes a tiny control plane.

The three canonical EIP-1967 slots (readable on any explorer/RPC)

• Implementation slot(holds the address of the executed contract)
  0x360894A13BA1A3210667C828492DB98DCA3E2076CC3735A920A3CA505D382BBC

• Admin slot (holds the address of the proxy contract admin)
  0xB53127684A568B3173AE13B9F8A6016E243E63B6E8EE1178D6A717850B5D6103

• Beacon slot (for Beacon proxies. We will not cover it here)
  0xA3F0AD74E5423AEBFD80D3EF4346578335A9A72AEAEE59FF6CB3582B35133D50

Note: You can inspect them with eth_getStorageAt / cast storage and read the last 20 bytes as an address.

Important operational gotcha (EOA vs. ProxyAdmin):

Do not set your everyday EOA as the proxy admin if you also need to use the dapp from that address.

• Admins cannot hit fallback → they can’t use the app through the proxy.

• Best practice: make the proxy admin a separate authority (usually an OpenZeppelin ProxyAdmin contract controlled by a multisig/timelock). Your user EOAs remain normal users.

Lets take a look at minimal Transparent Proxy implementation:

Contract implementationStorageV1.sol :

// SPDX-License-Identifier: MIT
pragma solidity 0.8.12;

contract StorageV1 {
    // IMPORTANT: storage lives in the proxy; layout must be stable across upgrades.
    uint256 public number;
    string public ownerName;
    bool private _initialized;
    // Will be initialized only once, you can use openzeppelin guard
    function initialize(uint256 n, string calldata who) external {
        require(!_initialized, “already initialized”);
        _initialized = true;
        number = n;
        ownerName = who;
    }
    function setNumber(uint256 n) external {
        number = n;
    }
}

Other contract implementation StorageV2.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.12;

import “./StorageV1.sol”;
contract StorageV2 is StorageV1 {
    // new vars only at the end
    string public note;
    function setNote(string calldata s) external { note = s; }
    function double() external view returns (uint256) { return number * 2; }
}

Transparent Proxy implementationTransparentProxy1967.sol :

// SPDX-License-Identifier: MIT
pragma solidity 0.8.12;

/// @title Minimal Transparent Proxy (EIP-1967) – for education/demo
/// @notice Admin gets upgrade functions; non-admin callers are delegated to implementation.
///         Admin is blocked from fallback to avoid selector clashes.
contract TransparentProxy1967 {
    // EIP-1967 slots (implementation, admin)
    bytes32 private constant _IMPLEMENTATION_SLOT =
        0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
    bytes32 private constant _ADMIN_SLOT =
        0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;
    event Upgraded(address indexed implementation);
    event AdminChanged(address previousAdmin, address newAdmin);
    // logic        - The address of the logic contract
    // initialAdmin - The admin of this proxy that can upgrade logic
    // data         - “constructor” for the logic contract
    constructor(address logic, address initialAdmin, bytes memory data) payable {
        require(_isContract(logic), “Proxy: logic not a contract”);
        require(initialAdmin != address(0), “Proxy: admin zero”);
        _setAddress(_ADMIN_SLOT, initialAdmin);
        _setAddress(_IMPLEMENTATION_SLOT, logic);
        // optional initializer call (acts like a constructor for the implementation)
        if (data.length > 0) {
            (bool ok, bytes memory err) = logic.delegatecall(data);
            require(ok, string(err));
        }
    }
    // -------- Admin control plane --------
    modifier ifAdmin() {
        if (msg.sender == _admin()) {
            _;
        } else {
            _fallback();
        }
    }
    function admin() external ifAdmin returns (address) { return _admin(); }
    function implementation() external ifAdmin returns (address) { return _implementation(); }
    function changeAdmin(address newAdmin) external ifAdmin {
        require(newAdmin != address(0), “Proxy: admin zero”);
        emit AdminChanged(_admin(), newAdmin);
        _setAddress(_ADMIN_SLOT, newAdmin);
    }
    function upgradeTo(address newImplementation) external ifAdmin {
        _upgradeTo(newImplementation);
    }
    function upgradeToAndCall(address newImplementation, bytes calldata data) external payable ifAdmin {
        _upgradeTo(newImplementation);
        (bool ok, bytes memory err) = newImplementation.delegatecall(data);
        require(ok, string(err));
    }
    // -------- User surface (fallback/delegate) --------
    fallback() external payable { _fallback(); }
    receive() external payable { _fallback(); }
    function _fallback() internal {
        require(msg.sender != _admin(), “Transparent: admin cannot fallback”);
        _delegate(_implementation());
    }
    function _delegate(address impl) internal {
        assembly {
            // 0x00–0x3f: scratch space the compiler may use temporarily.
            // Using memory at 0x00 is safe in this proxy fallback
            // because the assembly block never returns to Solidity.
            calldatacopy(0, 0, calldatasize())
            let ok := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
            returndatacopy(0, 0, returndatasize())
            switch ok
            case 0 { revert(0, returndatasize()) }
            default { return(0, returndatasize()) }
        }
    }
    // -------- Slot helpers & guards --------
    function _admin() internal view returns (address a) { a = _getAddress(_ADMIN_SLOT); }
    function _implementation() internal view returns (address a) { a = _getAddress(_IMPLEMENTATION_SLOT); }
    function _upgradeTo(address newImpl) internal {
        require(_isContract(newImpl), “Proxy: new impl not a contract”);
        _setAddress(_IMPLEMENTATION_SLOT, newImpl);
        emit Upgraded(newImpl);
    }
    function _getAddress(bytes32 slot) internal view returns (address a) {
        assembly { a := sload(slot) }
    }
    function _setAddress(bytes32 slot, address a) internal {
        assembly { sstore(slot, a) }
    }
    function _isContract(address a) internal view returns (bool) {
        uint256 size; assembly { size := extcodesize(a) }
        return size > 0;
    }
}

Note: Notice how the real contract execution happens in the fallback function.

Take a look that we dont have a constructor in the logic contract. but why?

Why a normal constructor doesn’t work with proxies

• Different storage context: delegatecall (as learned in one of the previous blog posts) executes the logic code in the caller’s storage (the proxy). The implementation’s constructor ran earlier in its own context.

• Constructors can’t be re-run: Once the implement(logic contract) is deployed, its constructor is gone. You can’t “constructor-via-delegatecall” later.

• You’ll see zeros via the proxy: Your constructor may have set owner/number on the logic address, but reading via the proxy will return defaults until you initialize the proxy’s storage.

• Security best practice: In upgradeable patterns we also lock the logic contract by disabling initializers so nobody can later “initialize” the implementation contract itself.

Lets dive into the fun part:

lets the local chain with the anvil as we did previously in different terminal

anvil

Logic contract deployment:

forge create src/StorageV1.sol:StorageV1 --rpc-url http://localhost:8545 --private-key <PRIVATE-KEY-FROM-ANVIL> --broadcast

// Output will be:
// [⠊] Compiling...
// No files changed, compilation skipped
// Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
// Deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3
// Transaction hash: 0x35b7d8d461c60c3759ab08a733c2f66e5fd8e22656ca5e158b37eecec605a80e

Transparent proxy deployment:

// Previuosly deployed contract
IMPL=0x5FbDB2315678afecb367f032d93F642f64180aa3
// ADMIN is the second address given by anvil, you can use any other admin
// for the sake of simplicity we will use this address
ADMIN=0x70997970C51812dc3A010C7d01b50e0d17dc79C8

# Build FULL calldata (selector + args)
# “constructor” of the logic contract
INIT_DATA=$(cast calldata “initialize(uint256,string)” 42 “some-owner”)
// --private-key - in this case is the private key of the ADMIN we provided previously
// but any other deployer could be used
forge create src/TransparentProxy1967.sol:TransparentProxy1967 \
  --rpc-url http://127.0.0.1:8545 \
  --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d \
  --broadcast \
  --constructor-args $IMPL $ADMIN “$INIT_DATA”
// Output should look like that:
// [⠊] Compiling...
// No files changed, compilation skipped
// Deployer: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
// Deployed to: 0x8464135c8F25Da09e49BC8782676a84730C318bC
// Transaction hash: 0x389ad3d17e7d8fe850c9325247cd3bd6d9c7bcd59757a73246656d56fb9425c3

Lets use the transparent proxy contarct as Users:

# read via proxy (uses delegatecall)
cast call 0x8464135c8F25Da09e49BC8782676a84730C318bC “number()(uint256)” --rpc-url http://127.0.0.1:8545
cast call 0x8464135c8F25Da09e49BC8782676a84730C318bC “ownerName()(string)” --rpc-url http://127.0.0.1:8545

// Output should look like:
// 42
// “some-owner”
# write via proxy
cast send 0x8464135c8F25Da09e49BC8782676a84730C318bC “setNumber(uint256)” 77 --private-key <YOUR-PRIVATE-KEY> --rpc-url http://127.0.0.1:8545
# Check that it worked
cast call 0x8464135c8F25Da09e49BC8782676a84730C318bC “number()(uint256)” --rpc-url http://127.0.0.1:8545
// Expected output: 77

Lets prove that address can’t fallback (use logic contract):

# this reverts: “Transparent: admin cannot fallback”
cast call 0x8464135c8F25Da09e49BC8782676a84730C318bC “number()(uint256)” --from 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 --rpc-url http://127.0.0.1:8545

// Expected output:
// server returned an error response: error code 3: execution reverted: Transparent: admin cannot fallback...

Lets inspects transparent proxy slots:

# admin slot (last 20 bytes)
cast storage 0x8464135c8F25Da09e49BC8782676a84730C318bC 0xB53127684A568B3173AE13B9F8A6016E243E63B6E8EE1178D6A717850B5D6103 --rpc-url http://127.0.0.1:8545

# logic contract address slot (last 20 bytes)
cast storage 0x8464135c8F25Da09e49BC8782676a84730C318bC 0x360894A13BA1A3210667C828492DB98DCA3E2076CC3735A920A3CA505D382BBC --rpc-url http://127.0.0.1:8545
// Expected outputs:
// 0x00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8
// 0x0000000000000000000000005fbdb2315678afecb367f032d93f642f64180aa3

Lets Upgrade to a new implementation StorageV2 with added functions, same storage prefix)

Lets the deploy the second contract:

forge create src/StorageV2.sol:StorageV2 --rpc-url  http://127.0.0.1:8545 --private-key <YOUR-PRIVATE-KEY> --broadcast

// Output should be something like
// [⠊] Compiling...
// No files changed, compilation skipped
// Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
// Deployed to: 0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9
// Transaction hash: 0x80fd23c7145fff6853e17439b1e4d1332b41526a411dfaa842a4f985d55f936c

Point the transparent proxy to the newly created contract:

cast send 0x8464135c8F25Da09e49BC8782676a84730C318bC “upgradeTo(address)” 0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9 --from 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 --rpc-url http://127.0.0.1:8545 --private-key 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d

now you can re-run the storage and see that the address of the logic contract address is changed.

Takeaways

• Transparent Proxy: “one address, swappable logic” with an explicit admin plane.

• Admins cannot use the app through the proxy; that’s by design. Keep admin separate (ideally a ProxyAdmin contract controlled by a multisig/timelock).

• Slots are standardized by EIP-1967, which makes inspection and audits predictable.

• Use initializers in logic contracts; constructors don’t run through proxies.

Summary

Proxies let contracts keep one public address while swapping logic behind the scenes. A Transparent proxy (EIP-1967) routes user calls to an implementation via delegatecall, keeps all state in the proxy, and exposes a separate admin plane for upgrades. You show the three standard slots (implementation/admin/beacon), why constructors don’t work (use initialize), and a full Foundry walkthrough: deploy V1, deploy proxy with init calldata, read/write via proxy, inspect slots, then upgrade to V2 and confirm state continuity.

Most of what confuses people about on-chain systems isn’t the Solidity itself it’s how contracts actually get on-chain.
What happens in a deployment transaction?
How does Ethereum decide where a contract will live?
And how can some teams know an address before they even deploy?

This post breaks down that lifecycle step by step.
We’ll start with first principles: what a deployment transaction really is (to = null, init code → runtime code) and how the EVM derives a contract’s address using the CREATE opcode.
Then we’ll extend that to CREATE2, the trick that makes addresses deterministic and lets protocols pre-compute pools, wallets, and factory outputs with mathematical precision.

By the end, you’ll be able to:

• Compute a contract’s address manually from a sender and nonce

• Predict addresses in advance with CREATE2

• Understand what’s really stored on-chain (and why constructors disappear after deployment)

How Contract Deployment Works

When you deploy a smart contract, you’re really just sending a special kind of transaction. Unlike a normal transfer where to is an existing address, a deployment transaction sets to = null and uses the transaction’s calldata to carry the contract’s init code.

That init code has two jobs:

1. Run once at deployment: it executes any constructor logic, sets up initial storage, and processes constructor arguments.

2. Return the runtime code: the actual bytecode that will live at the contract’s address permanently.

In other words:

• Init code = “bootloader.”

• Runtime code = “the operating system” that stays on-chain.

Constructor Arguments

When you pass parameters to a constructor in Solidity, they get ABI-encoded and appended to the init code. They’re consumed during deployment and don’t remain in the contract bytecode. This is why you don’t see them in the runtime code when you query eth_getCode.

Where Does the Contract Live

The EVM deterministically computes a contract’s address at the moment of deployment:

With CREATE (default):

address = keccak256(rlp(sender_address, sender_nonce))[12:]

Meaning: take the deploying account’s address + its nonce, RLP-encode them, hash, and use the last 20 bytes.

Size Limits

There’s also a ceiling: contracts can’t be bigger than 24 KB of bytecode (EIP-170).

Example

As we can see the contract code is not relevant for address computation for CREATE opcode. Lets use manual computation for calculating contract address after deployment.

Lets Run Anvil (as we learned here)

anvil

Manual Computation

Lets select one of the anvils default addresses and private-keys and check the nonce:

we can check the nonce with the native EVM call of eth_getTransactionCount or use cast by forge.

cast nonce <YOUR-ADDRESS> --rpc-url http://localhost:8545

This will show you the nonce of the address. Now lets use the calculation formula from above. Lets do the RLP encoding. You can take the code for RLP encoding from one of the previous blogs or use some online tool. i will be using online tool for clarity.

Press enter or click to view image in full size

rlp(sender_address, sender_nonce)

Note: My nonce here was 1 in the response, input your nonce in hex. if it is 0 type 0x

Now lets calculate a keccak256 for the next step, ill be using an online tool again:

Press enter or click to view image in full size

keccak256(rlp(sender_address, sender_nonce))[12:]

The input here is the output of the previous image and we take the last 20 bytes of the hash.

Lets validate the address with the help of forge, for that we will run the next line:

// <YOUR-ADDRESS> - can be address from anvil default addresses
cast compute-address <YOUR-ADDRESS> --nonce 1
Computed Address: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512

We see that the address is the same.

Deterministic Deployments with CREATE2

Normal contract deployments (CREATE) tie the new address to the deployer’s account and its nonce. That means addresses are sequential and you can’t know them in advance unless you track nonces.

EIP-1014 (CREATE2) introduced a way to deploy contracts at an address that’s predictable before the transaction is even mined. This is why people say CREATE2 gives you “deterministic deployments.”

With CREATE2:

address = keccak256( 0xff ++ sender ++ salt ++ keccak256(init_code) )[12:]

• 0xff → a constant marker byte to avoid collisions with normal CREATE.

• sender → the deployer’s address.

• salt → a 32-byte value you pick.

• init_code → the same “bootloader” we saw earlier (constructor logic + runtime code).

Example

lets use the next contract:

pragma solidity ^0.8.12;

contract Storage {
    struct my_storage_struct {
        uint256 number;
        string owner;
    }
    my_storage_struct my_storage;

    function store(my_storage_struct calldata new_storage) public {
        if (new_storage.number > 100) {
            revert(”Number too large”);
        }
        my_storage = new_storage;
    }
    function retrieve() public view returns (my_storage_struct memory){
        return my_storage;
    }
}

To determine the contract init code we can use forge cli:

forge inspect Storage bytecode

after that we can use one online tool or forge to calculate the keccak256:

cast keccak $(forge inspect Storage bytecode)

The output should look like:

0x9e7ceb5009cf19fc3a77cbead52c79f881b81800108a8931565aa92f9f1f5b64

Now lets put everything in the formula for the keccak256 input:

Press enter or click to view image in full size

I chose a random salt here of

0x0000000000000000000000000000000000000000000000000000000000000042

Lets validate it with forge:

// <YOUR-ADDRESS> - can be address from anvil default addresses
cast compute-address <YOUR-ADDRESS>\
  --salt 0x0000000000000000000000000000000000000000000000000000000000000042 \
  --init-code-hash 0x9e7ceb5009cf19fc3a77cbead52c79f881b81800108a8931565aa92f9f1f5b64

// Computed Address: 0x93eFaEdEe330e749D9AF79424398204EC04F89F1

As you can see we got the same address.

Why it matters

developers guarantee contract addresses before deployment, enabling things like pre-funded wallets, deterministic DEX pools, and verifiable system contracts.

ChatGPT said:

Summary

Contract deployments aren’t magic they’re math.
A to = null transaction runs init code once to produce the on-chain runtime code.
With CREATE, the address is keccak256(rlp(sender, nonce))[12:]; with CREATE2, it’s keccak256(0xff ++ sender ++ salt ++ keccak256(init_code))[12:].

CREATE2 makes addresses predictable before deployment perfect for deterministic pools, wallets, and factories.

If your app makes dozens of eth_calls for balances, symbols, or reserves, you’re wasting time and rate-limit budget.
Multicall fixes that. It’s a simple on-chain contract that executes multiple staticcalls in one go, returning all results from a single block snapshot.
In this post, you’ll see how to pack multiple reads into one eth_call, run them through Multicall3 on Polygon Amoy, and decode the results in Go. We’ll also compare it to JSON-RPC batching and explain why only Multicall guarantees consistent state across all results.

Batching Calls with Multicall

When your app needs lots of view calls: balances, allowances, symbols, pool reserves, doing them one‑by‑one means:

• extra latency (N round‑trips),

• higher provider bill (N requests),

• more rate‑limit pain (bursts get throttled),

• and inconsistent snapshots (results from slightly different blocks).

Multicall fixes all of that. It’s a tiny contract that executes many staticcalls in one go and returns all results so you make one eth_call, get N answers, all at the same block.

Why Multicall is a must have

• Fewer RPCs → fewer rate‑limit hits + lower cost.

• Lower latency → one round‑trip instead of many.

• Consistent state → all reads at the same block (no “half-old” data).

How its done

You ABI‑encode each read (e.g., balanceOf(user)), pack them into an array → call Multicall’s aggregate/tryAggregate via one eth_call → decode each return blob.

Note: you can find Multicall deployments here

Example:

package main

import (
   “context”
   “fmt”
   “log”
   “math/big”
   “strings”
   “github.com/ethereum/go-ethereum”
   “github.com/ethereum/go-ethereum/accounts/abi”
   “github.com/ethereum/go-ethereum/common”
   “github.com/ethereum/go-ethereum/ethclient”
)

const multicallABI = `[  {    “inputs”:[      {”internalType”:”bool”,”name”:”requireSuccess”,”type”:”bool”},      {        “components”:[          {”internalType”:”address”,”name”:”target”,”type”:”address”},          {”internalType”:”bytes”,”name”:”callData”,”type”:”bytes”}        ],
        “internalType”:”struct Call[]”,
        “name”:”calls”,
        “type”:”tuple[]”
      }
    ],
    “name”:”tryAggregate”,
    “outputs”:[
      {
        “components”:[
          {”internalType”:”bool”,”name”:”success”,”type”:”bool”},
          {”internalType”:”bytes”,”name”:”returnData”,”type”:”bytes”}
        ],
        “internalType”:”struct Result[]”,
        “name”:”returnData”,
        “type”:”tuple[]”
      }
    ],
    “stateMutability”:”nonpayable”,
    “type”:”function”
  }
]`

const erc20ABI = `[  {”name”:”balanceOf”,”type”:”function”,”stateMutability”:”view”,”inputs”:[{”name”:”owner”,”type”:”address”}],”outputs”:[{”type”:”uint256”}]},
  {”name”:”symbol”,”type”:”function”,”stateMutability”:”view”,”inputs”:[],”outputs”:[{”type”:”string”}]},
  {”name”:”decimals”,”type”:”function”,”stateMutability”:”view”,”inputs”:[],”outputs”:[{”type”:”uint8”}]}
]`

var (
   RPC            = “https://polygon-amoy.drpc.org”
   MULTICALL_ADDR = common.HexToAddress(”0xcA11bde05977b3631167028862bE2a173976CA11”) // Multicall3
   TOKEN_ADDR     = common.HexToAddress(”0x0Fd9e8d3aF1aaee056EB9e802c3A762a667b1904”) // LINK on Amoy
   USER           = common.HexToAddress(”0x7F8b1ca29F95274E06367b60fC4a539E4910FD0c”)
)

func main() {
   ctx := context.Background()
   client, err := ethclient.Dial(RPC)
   if err != nil {
      log.Fatalf(”dial rpc: %v”, err)
   }

   mabi, err := abi.JSON(strings.NewReader(multicallABI))
   if err != nil {
      log.Fatalf(”parse multicall abi: %v”, err)
   }
   eabi, err := abi.JSON(strings.NewReader(erc20ABI))
   if err != nil {
      log.Fatalf(”parse erc20 abi: %v”, err)
   }

   // Build calldata for ERC20 reads
   balData, err := eabi.Pack(”balanceOf”, USER)
   if err != nil {
      log.Fatalf(”pack balanceOf: %v”, err)
   }

   symData, err := eabi.Pack(”symbol”)
   if err != nil {
      log.Fatalf(”pack symbol: %v”, err)
   }

   decData, err := eabi.Pack(”decimals”)
   if err != nil {
      log.Fatalf(”pack decimals: %v”, err)
   }

   type Call struct {
    Target   common.Address
    CallData []byte
   }

   calls := []Call{
      {Target: TOKEN_ADDR, CallData: balData},
      {Target: TOKEN_ADDR, CallData: symData},
      {Target: TOKEN_ADDR, CallData: decData},
   }

   input, err := mabi.Pack(”tryAggregate”, false, calls)
   if err != nil {
      log.Fatalf(”pack tryAggregate: %v”, err)
   }

   // Single eth_call
   msg := ethereum.CallMsg{To: &MULTICALL_ADDR, Data: input}
   out, err := client.CallContract(ctx, msg, nil)
   if err != nil {
      log.Fatalf(”CallContract (eth_call): %v”, err)
   }

   // Decode results
   var results []struct {
      Success    bool
      ReturnData []byte
   }

   if err := mabi.UnpackIntoInterface(&results, “tryAggregate”, out); err != nil {
      log.Fatalf(”unpack tryAggregate: %v”, err)
   }
   if len(results) != 3 {
      log.Fatalf(”unexpected results len: %d”, len(results))
   }

   var (
      balance  *big.Int
      symbol   string
      decimals uint8
   )

   // 0: balanceOf
   if results[0].Success {
      vals, err := eabi.Unpack(”balanceOf”, results[0].ReturnData)
      if err != nil {
       log.Fatalf(”unpack balanceOf: %v”, err)
      }
      balance = vals[0].(*big.Int)
   } else {
      log.Printf(”balanceOf failed”)
   }

   // 1: symbol
   if results[1].Success {
      vals, err := eabi.Unpack(”symbol”, results[1].ReturnData)
      if err != nil {
         log.Fatalf(”unpack symbol: %v”, err)
      }
      symbol = vals[0].(string)
   } else {
        log.Printf(”symbol failed”)
   }

   // 2: decimals
   if results[2].Success {
      vals, err := eabi.Unpack(”decimals”, results[2].ReturnData)
      if err != nil {
         log.Fatalf(”unpack decimals: %v”, err)
      }
      decimals = vals[0].(uint8)
   } else {
      log.Printf(”decimals failed”)
   }

   fmt.Printf(”Symbol: %s, Decimals: %d\n”, symbol, decimals)

   if balance != nil {
      fmt.Printf(”Balance(%s): %s\n”, TOKEN_ADDR.Hex(), balance.String())
   }
}

The result will be something like:

Symbol: LINK, Decimals: 18
Balance(0x0Fd9e8d3aF1aaee056EB9e802c3A762a667b1904): 38000000000000000000

JSON-RPC Batching

Some providers support sending an array of eth_* requests in one HTTP call. This can be handy for things like fetching balances, block headers, or transaction receipts. But for eth_call it’s usually not recommended. The node still executes each call separately, and you lose the guarantee that results come from the exact same block. If you care about consistent snapshots and rate-limit savings, Multicall on-chain is the better option.

Note: JSON-RPC batching helps reduce HTTP requests, but only Multicall guarantees a consistent snapshot across all calls at the same block.

Summary

Multicall is one of those rare utilities that quietly powers almost every dashboard, analytics app, and on-chain data service in the ecosystem. It gives you consistency, lower latency, and fewer RPC headaches all in a single eth_call.

While JSON-RPC batching can reduce HTTP requests, it can’t guarantee that all results come from the same block. Multicall does. By executing reads on-chain in one static context, you get atomic, synchronized snapshots of state a must for accurate data pipelines or price displays.

Together with tracing and event streaming, Multicall rounds out the toolkit for anyone building real-time, efficient Ethereum integrations.

Events (as explained here) tell a lot but not everything.
A contract can move native ETH without emitting a single log. Bridge payouts, refunds, self-destructs they can all happen silently.
In this post, you’ll learn two reliable ways to detect native ETH transfers even when no events are emitted:

Reading top-level transactions directly.

Tracing internal calls with trace_replayTransaction.
We’ll walk through the JSON-RPC calls and show how to recursively parse the call tree to find every movement of value inside a transaction.

Catching ETH Transfers Without Events

Events are great, but they’re not the whole story.
A contract can send native ETH with a simple CALL{value: ...} and emit no logs at all. Unless the contract chooses to emit, that movement won’t show up in eth_getLogs. So if you only listen to events, you’ll miss:

• Payouts from routers/bridges/treasuries to users

• Refunds via CALL{value}

• Self‑destruct payouts (SELFDESTRUCT sending the contract’s balance)

• Any internal ETH moves hidden inside a larger transaction

There are two reliable ways to see ETH moving:

Top‑level ETH transfers (easy): look at the transaction itself

If an EOA sends ETH directly to to, it’s visible without logs:

• Read tx.to and tx.value (wei).

• If the tx succeeds, that amount of ETH moved from from → to.

Caveats:

• If the tx reverts, nothing moved.

• If to is a contract and it makes further payments, those are internal (see next).

Internal ETH transfers (the real deal): trace the execution

To see ETH moved inside a transaction (contract → user), you must parse the call tree. Use node tracing APIs (as we learned in the previous post).

You’re looking for calls with non‑zero value :

curl -s -X POST <YOUR-BLOCKCHAIN-NODE-URL>\
  -H “Content-Type: application/json” \
  --data ‘{
    “jsonrpc”:”2.0”,
    “id”:1,
    “method”:”trace_replayTransaction”,
    “params”:[
      “<tx-hash>”,
      [”trace”]
    ]
  }’ \
| jq -r ‘.result.trace[]
| select(.action.value!=”0x0”)
| {type, from:.action.from, to:.action.to, value:.action.value}’

The output will look like this:

{
  “type”: “call”,
  “from”: “<addr1>”,
  “to”: “<addr2>”,
  “value”: “0x22e92f1cfbaaacd5d”
}
{
  “type”: “call”,
  “from”: “<addr3>”,
  “to”: “<addr4>”,
  “value”: “0x22e92f1cfbaaacd5d”
}

• Walk the tree depth‑first; collect any object where value != 0.

Also you can handle:

• “type”: “SELFDESTRUCT” → has a to and value payout.

• “type”: “DELEGATECALL” → value is always 0 (it forwards context), so skip unless you track side‑effects(you can see inner call after delegation).

Note: You can just parse every “node” recursievly and see if value != 0.

Small pseudo-code example:

function collectEthTransfers(node):
  if node.value > 0:
    record(from=node.from, to=node.to, value=node.value, type=node.type)
  for child in node.calls:
    collectEthTransfers(child)

Summary

ETH can move even when no Transfer event exists through low-level calls, refunds, or self-destructs that never emit logs. By combining top-level transaction reads with execution traces from trace_replayTransaction, you can uncover every hidden movement of value inside a transaction.

This tracing approach is the foundation for real analytics, accounting, and bridge monitoring tools anywhere you need a full picture of how value actually flowed.