Programs

Token-2022 recipe: transfers and extensions

A Token-2022 transfer can deliver less than it sends, and the instruction alone does not always say how much less. This recipe decodes all three transfer forms, reads the mint state that decides the rest, and was checked against the recipient balances of real mainnet transfers, fee-bearing ones included.

To decode a Token-2022 transfer, read its tag: 3 is Transfer, 12 is TransferChecked, and 26 followed by 1 is TransferCheckedWithFee. All three name the amount taken from the source. Only the last also states the fee. For the others, what the recipient gets depends on the mint's transfer fee settings, which you must read from the mint account.

Program IDs and sources#

WhatValue
Token-2022 program IDTokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
SPL Token program IDTokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
Layoutssolana-program/token-2022, commit 875693f
RuntimeNode 24, no dependencies

Token-2022 is not an Anchor program: it has no IDL and no discriminators, just a one-byte tag like the classic program. Both appear with their sources on the program IDs page. The classic program now runs p-token, which added new tags of its own, including a Batch instruction (255); that change applies to SPL Token only, not to Token-2022.

Three transfer forms and what the recipient gets#

FormData after the tagAccountsRecipient receives
Transfer (3)amount (u64)source, destination, authoritythe amount; Token-2022 refuses it when the source account carries fee, hook or pause state
TransferChecked (12)amount (u64), decimals (u8)source, mint, destination, authoritythe amount, less the mint's transfer fee if it has one
TransferCheckedWithFee (26, 1)amount (u64), decimals (u8), fee (u64)source, mint, destination, authoritythe amount less the stated fee; the program rejects it if the fee is not the one it computes

So the form that tells you everything is the rarest. We found no TransferCheckedWithFee among the transfers in our samples, so our code decodes it from the layout but it is untested on real data. The everyday form on fee-bearing mints is TransferChecked, and there the fee is not in the instruction at all. The extension side of Token-2022 is covered in Token-2022 extensions; this page is about reading the transfers.

How the transfer fee is computed#

A mint with the transfer fee extension stores two fee settings, an older and a newer, each with a starting epoch, a rate in basis points and a maximum. The program uses the newer one once the current epoch reaches its starting epoch, and the older one before that. The fee is the amount times the rate divided by 10,000, rounded up, and never more than the maximum.

Rounding up is visible on chain. On a 3 percent mint, a TransferChecked of 15,000,859,137,060 raw units gives 450,025,774,111.8 before rounding; the recipient received 14,550,833,362,948, exactly 450,025,774,112 less. On a 0.5 percent mint, an inner transfer of 1,678,664 gives 8,393.32; 8,394 was withheld.

The epoch matters because a mint's owner can schedule a new rate. To know which setting applied, compute the epoch from the slot: on mainnet each epoch is 432,000 slots, so slot 448,575,076 is in epoch 1,038.

Extensions that need mint state#

ExtensionWhat it changesCan you read it from the transfer?
Transfer feewhat the recipient receivesonly with TransferCheckedWithFee; otherwise read the mint
Scaled UI amountthe displayed amount: raw units times a multiplier, which can change at a set timeno: the raw amount is unchanged, the display depends on the mint
Interest-bearingthe displayed amount grows over timeno
Transfer hookanother program runs on every transfer and adds accounts to the instructionpartly: the extra accounts appear, their meaning comes from the hook program
Pausable, default account state, non-transferablewhether a transfer can happen at allno: read the mint and the accounts
Permanent delegatewho may sign a transferno

Among the 154 Token-2022 mints in our fixtures, 7 had the transfer fee extension (one of them set to 0 basis points), 7 had a scaled UI amount and 10 had a transfer hook. Most mints carry only metadata extensions, which change nothing about transfers. Token-2022 surprises collects the cases that catch decoders out.

Steps#

  1. For each top-level call to either token program, decode it with decodeTokenTransfer. It returns null for anything that is not one of the three transfer forms.
  2. Keep a cache of mint state. Fetch each new Token-2022 mint once with getAccountInfo in base64 and parse it with readMint; refresh when the mint changes, since fee settings and multipliers can be updated.
  3. Call amountReceived with the slot's epoch to get what lands in the destination.
  4. Plain Transfer names no mint. If you need the mint, take it from the destination account's own data, or from the balance records RPC returns after execution.
  5. After confirmation, compare with the balance change from RPC. Our tests matched it on every transfer they could isolate.

src/token2022.ts#

src/token2022.ts
// Token-2022 transfers, and the mint state needed to know what the recipient actually receives.
// Layouts: solana-program/token-2022 interface (instruction.rs, extension/mod.rs ExtensionType order,
// extension/transfer_fee/mod.rs, extension/scaled_ui_amount/mod.rs), commit 875693f. SPL Token shares tags 3 and 12.
import { b58 } from "./base58.ts";
export const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
export const TOKEN_2022_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
export type TokenTransfer = {
program: string; kind: "transfer" | "transferChecked" | "transferCheckedWithFee";
source: string; mint: string | null; destination: string; authority: string;
amount: bigint; // taken from the source
decimals: number | null; // checked variants only
declaredFee: bigint | null; // transferCheckedWithFee only; the program rejects it unless it equals the mint's fee
};
/** Top-level Transfer (3), TransferChecked (12) and, for Token-2022, TransferCheckedWithFee (26, 1). */
export function decodeTokenTransfer(programId: string, data: Uint8Array, accounts: string[]): TokenTransfer | null {
if (programId !== TOKEN_PROGRAM && programId !== TOKEN_2022_PROGRAM) return null;
const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
const base = { program: programId, declaredFee: null };
if (data[0] === 3 && data.length === 9)
return { ...base, kind: "transfer", source: accounts[0], mint: null, destination: accounts[1], authority: accounts[2], amount: v.getBigUint64(1, true), decimals: null };
if (data[0] === 12 && data.length === 10)
return { ...base, kind: "transferChecked", source: accounts[0], mint: accounts[1], destination: accounts[2], authority: accounts[3], amount: v.getBigUint64(1, true), decimals: data[9] };
if (programId === TOKEN_2022_PROGRAM && data[0] === 26 && data[1] === 1 && data.length === 19)
return { ...base, kind: "transferCheckedWithFee", source: accounts[0], mint: accounts[1], destination: accounts[2], authority: accounts[3],
amount: v.getBigUint64(2, true), decimals: data[10], declaredFee: v.getBigUint64(11, true) };
return null;
}
// ExtensionType values are the enum's order in extension/mod.rs.
const EXT = ["Uninitialized", "TransferFeeConfig", "TransferFeeAmount", "MintCloseAuthority", "ConfidentialTransferMint",
"ConfidentialTransferAccount", "DefaultAccountState", "ImmutableOwner", "MemoTransfer", "NonTransferable", "InterestBearingConfig",
"CpiGuard", "PermanentDelegate", "NonTransferableAccount", "TransferHook", "TransferHookAccount", "ConfidentialTransferFeeConfig",
"ConfidentialTransferFeeAmount", "MetadataPointer", "TokenMetadata", "GroupPointer", "TokenGroup", "GroupMemberPointer",
"TokenGroupMember", "ConfidentialMintBurn", "ScaledUiAmount", "Pausable", "PausableAccount", "PermissionedBurn"];
type Fee = { epoch: bigint; maximumFee: bigint; basisPoints: number };
export type MintState = {
decimals: number; extensions: string[];
transferFee: { older: Fee; newer: Fee } | null;
scaledUiAmount: { multiplier: number; newMultiplier: number; newMultiplierTimestamp: bigint } | null;
transferHookProgram: string | null;
};
/** Parse a mint account's raw data (base mint, then account type at byte 165, then type-length-value extensions). */
export function readMint(data: Uint8Array): MintState {
const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
const st: MintState = { decimals: data[44], extensions: [], transferFee: null, scaledUiAmount: null, transferHookProgram: null };
if (data.length <= 165 || data[165] !== 1) return st; // a plain mint: no extensions
for (let o = 166; o + 4 <= data.length;) {
const type = v.getUint16(o, true), len = v.getUint16(o + 2, true), b = o + 4;
if (type === 0 && len === 0) break;
st.extensions.push(EXT[type] ?? `extension ${type}`);
const fee = (p: number): Fee => ({ epoch: v.getBigUint64(p, true), maximumFee: v.getBigUint64(p + 8, true), basisPoints: v.getUint16(p + 16, true) });
if (type === 1) st.transferFee = { older: fee(b + 72), newer: fee(b + 90) }; // two authorities (32 each), withheld u64
if (type === 25) st.scaledUiAmount = { multiplier: v.getFloat64(b + 32, true), newMultiplierTimestamp: v.getBigInt64(b + 40, true), newMultiplier: v.getFloat64(b + 48, true) };
if (type === 14) { const p = b58(data.subarray(b + 32, b + 64)); st.transferHookProgram = p === "11111111111111111111111111111111" ? null : p; }
o = b + len;
}
return st;
}
/** The fee the program withholds from a transfer in `epoch`: ceil(amount x bps / 10,000), capped at the maximum. */
export function transferFee(mint: MintState, amount: bigint, epoch: bigint): bigint {
if (!mint.transferFee) return 0n;
const f = epoch >= mint.transferFee.newer.epoch ? mint.transferFee.newer : mint.transferFee.older;
const raw = (amount * BigInt(f.basisPoints) + 9_999n) / 10_000n;
return raw < f.maximumFee ? raw : f.maximumFee;
}
/** What lands in the destination account. Needs mint state for every variant except transferCheckedWithFee. */
export function amountReceived(t: TokenTransfer, mint: MintState | null, epoch: bigint): bigint {
if (t.kind === "transferCheckedWithFee") return t.amount - t.declaredFee!;
if (t.program === TOKEN_PROGRAM || !mint) return t.amount;
return t.amount - transferFee(mint, t.amount, epoch);
}

Real transfers on a fee-bearing mint#

FieldTransfer, slot 448,575,076Transfer, slot 470,917,488
formTransferChecked, top levelTransferChecked, top level
mintDdvgbCH2N2Yo9fgCq8yb2qqNYDFJtsr1GT2pRVhJxsXiVzUPBWqREGVggS27kiFuSVZFUVFt1f9VrMfecjT8888
mint fee setting300 basis points, maximum 1,000,000,000,000,000, from epoch 1,038300 basis points, maximum 1,000,000,000,000,000,000, from epoch 1,009
amount in the instruction15,000,859,137,060100,000,000,000
fee computed by transferFee450,025,774,1123,000,000,000
recipient's balance change, from RPC14,550,833,362,94897,000,000,000

Neither instruction mentions a fee. Without the mint state, a decoder would record the recipient as receiving 3 percent more than arrived.

How this code was tested#

CheckResult
readMint against RPC's parsed view: extensions, decimals, fee settings, scale multipliers154/154 mints
Token-2022 TransferChecked, no fee, recipient's balance change15/15 top level, 358/358 inner
Token-2022 TransferChecked, fee withheld2/2 top level, 3/3 inner
SPL Token Transfer and TransferChecked6/6 and 21/21 top level, 31/31 and 366/366 inner
Token-2022 TransferCheckedWithFeenone found: decoded from the layout, untested on real data

A transfer counts only when no other token instruction in the transaction touches its destination, so the balance change is that transfer's alone. Inner transfers, made by other programs, are not in shreds, but they run through the same fee rule and were included to test it on more than two transfers. Mint state was read on 18 November 2026 and fees use each transfer's own epoch. On every fee mint in our samples the older and newer settings were identical, so the choice between them follows the source but was not exercised by these tests. The test is test-token2022.ts in the examples' test-all.sh.

What the instruction cannot tell you#

For TransferChecked on a fee-bearing mint, the instruction gives the amount sent, not the amount received; you need the mint. Displayed amounts on scaled and interest-bearing mints need mint state and a time. Transfer-hook programs can make a transfer fail for their own reasons. Plain Transfer does not name the mint. Transfers made by other programs, which is most transfers in DEX swaps, are inner instructions and do not appear in shreds. And this decoder does not unpack SPL Token's Batch instruction.

More about tokens#

The instruction tags of the classic token program are listed separately, and associated token accounts explains how token accounts relate to wallets. The Raydium CPMM and CLMM recipe shows a pool deposit that lost 3 percent to a transfer fee. To decode token transfers as blocks are produced, see the plans.

Sources#

Raw shreds on your own server

Ultra Low Latency Shreds is $200 and Standard Shreds is $100. You pay in crypto, tell us which IPv4 address and UDP port should receive the stream, and we wire it up by hand.