The hook protocol

How a hook is called#

By CPI, with an Anchor-style discriminator and Borsh arguments, signed by the caller’s ["hook-authority", hook_program] PDA, always the first account. There is one signer per hook program, so a hook accepts only its own: a signer another hook passes on vouches for nothing. A hook never moves funds itself and never gets the user’s signature; it answers, and the caller checks and applies the answer.

Callbacks#

For a mint or a burn, the mint stands in for the side the operation lacks. Pool callbacks also carry the caller’s opaque hook data (Uniswap v4’s hookData), up to 256 bytes.

Flags#

Mint.hook_flags and Pool.hook_flags subscribe a hook. A callback whose flag is off is never called, and an answer is read only when a flag allows one.

Arguments#

A callback is told everything the caller knows about the operation. Balances and hook data are those before it in the before phase, after it in the after phase.

pub struct TokenHookArgs {
    pub op: TokenOp,                     // Transfer, Mint or Burn
    pub phase: Phase,                    // Before or After
    pub mint: Pubkey,
    pub source: Pubkey,                  // the mint, for a mint
    pub destination: Pubkey,             // the mint, for a burn
    pub source_owner: Pubkey,
    pub destination_owner: Pubkey,
    pub authority: Pubkey,               // who signed
    pub authority_is_delegate: bool,
    pub amount: u64,
    pub delta: u64,                      // what the cuts took (known after)
    pub source_balance: u64,
    pub destination_balance: u64,
    pub decimals: u8,
    pub supply: u64,
    pub source_hook_data: [u8; 64],      // the holdings' 64 bytes
    pub destination_hook_data: [u8; 64],
}

Answers#

A before_* callback, and a pool’s after_swap, may answer in its return data. A field it may not fill must be empty, zero or None, or the whole answer is refused (UnsupportedHookReturn).

pub const MAX_DELTAS: usize = 3;
pub const HOOK_DATA_LEN: usize = 64;

pub struct Delta {
    pub amount: u64,                     // above zero
    pub account: u8,                     // index in the callback's accounts; must be an extra
}

pub struct HookReturn {
    pub deltas: Vec<Delta>,                              // at most MAX_DELTAS
    pub burn: u64,                                       // pool swap callbacks only
    pub lp_fee_bps: Option<u16>,                         // before_swap only
    pub source_hook_data: Option<[u8; HOOK_DATA_LEN]>,   // token callbacks only
    pub destination_hook_data: Option<[u8; HOOK_DATA_LEN]>,
}

The caller reads an answer only when the flags allow it and the return data is the hook’s own, then checks:

• at most three cuts, each above zero, no account named twice, the sums in checked arithmetic (DeltaTooLarge);
• a transfer: the cuts add up to at most the amount, each to a writable, unfrozen holding of the mint that is neither the source nor the destination. The destination gains the amount less the cuts;
• a swap: the cuts and the burn stay below the side’s amount, never to a vault or the trader’s own holdings; a burn needs the mint writable (MintNotWritable), and min_amount_out is checked against what the recipient actually gained;
• a cut credits a holding without calling the hook for it, so a hook that keeps per-holder state names only holdings it leaves out of that state.

Extra accounts#

A hook that needs accounts of its own publishes them at registryAddress(hook_program, mint-or-pool): literal keys, or PDAs whose seeds are literals or accounts already in the callback’s list. Clients resolve the list and append the accounts after the fixed prefix; the calling programs pass them through untouched.

A swap, in order#

A pool hook’s answer is taken at two points, drawn on ink: from the input before the curve, and from the output after it. The LP fee stays on the input side; the protocol fee is always taken in the quote token.

Who is paid#

Each pool copies its fee model (fee_model) from the DEX config when it is created and keeps it for life. A launch pool is a curve the launchpad creates as its own hook; a curve any other program opens pays the flat rate.

A launch whose rules collect nothing pays the LP fee alone. Anyone may send collect_protocol_fees_sol: it unwraps a launch pool’s fees through the bridge and pays them to the fee collector as SOL.