What Does the Token-2022 Transfer Hook Call?

The Token-2022 transfer hook will call an external program pre-configured during token minting, executing developer-defined transfer logic. This hook program typically needs to implement a standard Execute instruction and automatically resolves the required extra accounts based on the configuration.

Standard Instruction Call Flow

The execution of the Token-2022 transfer hook follows several standard steps:

1. User initiates the transfer: Calls the transfer_checked instruction of the Token-2022 program.

2. Token program detects the hook: Discovers that the token's mint account has the Transfer Hook extension configured.

3. Token program performs a cross-program invocation (CPI): Calls the configured hook program, executing the Execute instruction.

4. Hook program executes custom logic: Validates, modifies, or rejects the transfer.

5. Transfer completes or rolls back: The hook program returns a success (Ok) or failure (Err) result. If it passes, assets are transferred; if it fails, the entire transaction rolls back.

Detailed Explanation of the Call

1. Instruction Being Called

The protocol requires every Transfer Hook program to implement at least the Execute instruction. When a user transfers, it is precisely this instruction that the Token-2022 program invokes via CPI.

Some hook programs also implement the optional InitializeExtraAccountMetaList instruction, used to configure the list of additional accounts required for subsequent transfers.

2. Accounts Passed

When calling the hook, the Token-2022 program passes a set of accounts. According to the standard specification, these accounts include:

• Source Account: The account sending the tokens.

• Token Mint: The mint account of the tokens being transferred.

• Destination Account: The account receiving the tokens.

• Owner/Delegate of the Source Account: The account authorizing the transfer.

• Validation Account: An account used for additional account resolution.

• Extra Accounts (M number): A variable number of additional accounts, automatically resolved and added by the Token-2022 program based on the configuration.

3. Core Logic Executed

The hook program can execute various custom logic, such as:

• Verifying recipient eligibility: KYC whitelist checks, geographic restrictions, blocklist checks.

• Collecting royalties: Ensuring royalties are automatically paid on every NFT resale.

• Enforcing dynamic fees: Charging different fee percentages based on the transfer amount or recipient.

• Statistical tracking: Updating an on-chain transfer counter or statistics.

• Permission verification: Checking whether the sender holds specific permissions (e.g., DAO multisig approval).

Core Mechanism: Extra Account Resolution (ExtraAccountMetaList)

The most critical part of the call is the automatic resolution of Extra Accounts. Since the wallet or transfer initiator doesn't know which extra accounts the hook program needs, the Token-2022 program introduces a mechanism to solve this.

1. Configuration phase: The hook program initializes a PDA (Program Derived Address) using the combination of fixed seeds "extra-account-metas" + mint address + hook program ID, and stores the metadata of required extra accounts there.

2. Transfer phase: The Token-2022 program automatically queries this PDA, reads the configured metadata, then dynamically resolves the required extra accounts and appends them to the call to the hook program.

Check Your Understanding

You can confirm your understanding of what the Token-2022 transfer hook calls through the following methods:

1. Review official examples: Read the example programs in the SPL library to understand the standard Execute instruction implementation.

2. Refer to community implementations: Observe open-source projects on GitHub, such as how the counter_hook program updates a transfer counter, or hook programs implementing KYC compliance.

3. Core verification: Confirm that transfer_checked was used instead of transfer during the transfer; check whether the called program implements the Execute instruction; trace the transaction via a block explorer to see the actual list of accounts passed to the hook program.

The essence of the Token-2022 transfer hook is the combination of "hook program + Execute instruction", achieving excellent extensibility through automatic account resolution. Regular users do not need to actively call the hook; they only need to be aware of whether the token mint has Transfer Hook configured, and the transfer action will automatically trigger the hook execution.