Canonical: https://solanashreds.xyz/blog/token-2022-surprises

# Token 2022 surprises for decoders

Token 2022 keeps the familiar instruction shapes, then adds fees that shrink what arrives, hooks that bring their own accounts, and amounts you cannot read at all. Here is what each means for a decoder.

Token 2022 transfer hook decoding needs more than an SPL Token parser. Transfers on Token 2022 mints can carry a fee that shrinks the amount received, a hook that appends extra accounts and runs another program, or encrypted amounts no decoder can read. Detect the program per instruction, then read the mint's extensions before trusting any amount.

## Why an SPL Token decoder is not enough

Token 2022 is a separate program, `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`, that keeps the original token instruction set and adds extensions configured per mint. Because the base instructions look the same, an SPL Token decoder pointed at Token 2022 data often appears to work. It reads TransferChecked, finds the amount and decimals, and reports a transfer.

The trouble is what it does not know. Whether that amount is what arrives, whether another program ran during the transfer, and whether the amount was visible at all all depend on the mint's extensions, and those live in the mint account, not in the transaction.

## What each extension does to a transfer you decode

| Extension | Visible in the instruction | Needs mint or account state | Effect on the amount you report |
|---|---|---|---|
| None (plain mint) | Amount and decimals | No | Amount sent equals amount received |
| Transfer fee | With TransferCheckedWithFee, the amount and the expected fee; with plain TransferChecked, the amount only | Yes, the mint's fee settings | Received is amount minus fee |
| Transfer hook | The extra accounts appended to the transfer | Yes, to know which hook program the mint names | Unchanged, but another program runs and may fail the transfer |
| Confidential transfer | Encrypted amounts and proofs, no plain amount | Yes, and still not enough to read it | Unknown to anyone without the keys |
| Metadata and pointers | Nothing in the transfer | Only if you want names and symbols | None |

## Transfer fees: the amount sent is not the amount received

A mint with the transfer fee extension charges a fee on every transfer, set by basis points with a maximum, and the fee is withheld in the recipient's token account. The sender's instruction states the full amount; the recipient's balance grows by less.

There is a dedicated instruction, TransferCheckedWithFee, whose data carries the amount, the decimals and the fee the sender expects. When it is used, the fee is right there in the bytes. When a plain TransferChecked is sent to a mint with a fee, the instruction says nothing about it, and you need the mint's fee configuration to compute what arrived. Either way, report "sent" and "received" as separate fields. Alerts that show the sent amount as received are one of the causes listed in [wallet alerts without false alarms](https://solanashreds.xyz/blog/wallet-alerts-without-false-alarms).

## Transfer hooks and the extra accounts they bring

A mint with a transfer hook names a program that must approve every transfer. The token program calls it during execution, passing extra accounts that the hook declared in an account derived from the mint with the seed `extra-account-metas`. Those extra accounts are appended to the transfer instruction, so a hooked transfer has more accounts than the base layout.

For a decoder that means two things. First, do not reject a transfer because its account list is longer than expected; read the fixed accounts by position and treat the rest as hook accounts. Second, the hook's own call is an inner instruction that only exists after execution, so raw data shows that a hook will run, not what it decided. A hook can fail the whole transfer.

## Confidential transfers: amounts you cannot read

The confidential transfer extension replaces plain amounts with encrypted values and zero knowledge proofs. A decoder can see that a confidential transfer happened, between which accounts and on which mint. It cannot see how much moved, and neither can anyone without the account's decryption key. Report these as "amount hidden" instead of zero, or totals built from your rows will be quietly wrong.

## Telling the two token programs apart per instruction

Check the program id of every instruction, not the transaction. One transaction can touch both token programs, and the same instruction tag means the same base instruction in each, so the program id is the only reliable switch. Route Token 2022 instructions through a decoder that knows the extension instructions, and look up each mint's extensions once and cache them. Note that the plain Transfer instruction is marked deprecated in the Token 2022 interface in favour of TransferChecked and TransferCheckedWithFee, so expect the checked forms in new traffic.

The [Token 2022 recipe](https://solanashreds.xyz/docs/programs/token-2022) shows the decoding in code, [Token 2022 extensions](https://solanashreds.xyz/learn/token-2022-extensions) defines each extension, and [the classic token instruction tags](https://solanashreds.xyz/learn/spl-token-instructions) lists the base tags both programs share. For classic mints, the [SPL token transfer recipe](https://solanashreds.xyz/docs/programs/spl-token-transfers) is enough.

## What instruction data alone will not settle

Fees, hooks and confidential amounts all need state from outside the transaction, and the outcome needs execution. Instruction level decoding tells you what was requested and which extensions apply. The amount actually received, whether a hook approved, and whether the transfer succeeded come from the settled transaction, so treat early Token 2022 rows as provisional until then.

## Next steps

Add a mint extension cache to your decoder before Token 2022 volume grows in your data. To test against live traffic, [Standard Shreds](https://solanashreds.xyz/standard-shreds) sends raw packets to the receiver you run.
