Docs

The hook's instructions are named after six callbacks. HELIX selects one with an Anchor-style discriminator, the first 8 bytes of sha256("global:<name>"), so an Anchor program whose instructions carry these names matches without extra work.

Instruction data is the discriminator followed by the Borsh encoding of TokenHookArgs: 373 bytes in all (365 for the arguments). A callback whose flag is off is not called. Any callback can refuse by returning an error: the whole transaction fails.

The five fixed accounts are read-only to the hook: it never moves tokens itself. It tells HELIX what to do in its answer, and HELIX does it.

Everything HELIX knows about the operation, as plain little-endian concatenation (Borsh). In the before phase balances and hook data are those before the operation; in the after phase, those after it.

A Token-2022 hook has to guess whether a transfer is a trade. A HELIX hook is told. HELIX sets the context from the instruction that is running, never from the caller's arguments: the transfer instruction always passes Plain.

A before_* callback may answer by setting return data (set_return_data) to a Borsh HookReturn. No return data, or empty return data, means “go ahead as is”. HELIX reads the answer only if it was set by the hook program itself.

At most 161 bytes. A cut's account is an index into the callback's account list and must point past the five fixed accounts, at one of the hook's extras. The recipient receives the amount less every cut; each cut is credited to its holding directly, without calling the hook again. after_* callbacks can't answer: they should set no return data (a well-formed answer there is ignored).

In helix-hook the answer is the struct HookReturn (deltas: [Delta; 3], delta_count, two Option<[u8; 64]>) with encode and decode; on the wire it is the Borsh shape above, a Vec<Delta> followed by two options.

HELIX signs every callback with the PDA ["hook-authority", hook_program], derived from the HELIX program id (HLX49qz3CSKQrHrdzrrWygZBaKHWWSG8JwUMFHcZ47Fr). It is account 0 and always a signer. A hook must check both, or anyone could call it directly and feed it invented arguments. The SDK gives the address as hookSignerAddress(hookProgram).

// programs/example-hook/src/lib.rs: only HELIX's signer for this hook may call it.
let [signer, mint, _source, _destination, _authority, config, collector, ..] = accounts else {
    return Err(err());
};
let expected = Address::try_find_program_address(
    &[HOOK_AUTHORITY_SEED, program_id.as_array()], // ["hook-authority", this program]
    &HELIX_ID,                                     // derived from the HELIX program id
)
.ok_or(err())?
.0;
if !signer.is_signer() || expected.as_array() != signer.address().as_array() {
    return Err(ProgramError::MissingRequiredSignature);
}
let args = TokenHookArgs::decode(data).ok_or(err())?;

A second PDA goes the other way: ["hook-authority"] derived from the hook program id is how a hook signs write_hook_data (hookSelfAddress(hookProgram) in the SDK).

A hook decides which other accounts it needs: its config, a collector's holding, anything it reads or credits. Clients append them to the HELIX instruction after the hook program and the signer: [hook_program, hook_signer, …extras]. HELIX checks that the hook program is the mint's and executable, and that the signer is the right PDA; missing accounts fail with HookAccountsMissing.

• Token operations (transfer, mint_to, burn, the liquidity instructions): hookAccounts(mint, decodedMint, extras).
• Swaps: swapHookAccounts(decodedMint, extras). It is empty for a token without a hook and for the kit, which runs on the swap's own launch account.

HELIX refuses the whole operation, and the transaction fails, if any of these doesn't hold:

1. The return data decodes exactly: at most 3 cuts, no bytes left over. Otherwise UnsupportedHookReturn.
2. Hook data is answered only if the mint has WRITES_HOOK_DATA, and only for a holding the operation touches: source data on a transfer or burn, destination data on a transfer or mint. Otherwise UnsupportedHookReturn.
3. Cuts are answered only by before_transfer, and only if the mint has TRANSFER_RETURNS_DELTA. Otherwise UnsupportedHookReturn.
4. Every cut is more than zero (UnsupportedHookReturn).
5. Every cut points at one of the hook's extras (index 5 or more), no extra is named twice, and the account is writable, is neither the source nor the destination, is a HELIX holding of the same mint and is not frozen. Otherwise InvalidDeltaAccount.
6. The cuts add up to no more than the amount (DeltaTooLarge).

Every holding carries 64 bytes that belong to the mint's hook. They start as zeros. Only the hook can change them: in a before_* answer, or through write_hook_data. HELIX hands the source's and destination's bytes to every callback in source_hook_data and destination_hook_data, so a hook can read a holder's state without an extra account.

• With WRITES_HOOK_DATA set, a holding can only be closed when its 64 bytes are all zero. A hook that wants holders to be able to close should clear them when a balance reaches zero.
• On a mint whose hook can still be changed (it has a hook authority), the bytes stay when the hook changes: the new hook sees what the old one wrote.

Tag 22. Lets a hook update a holding's bytes outside a token operation, for example when a holder claims something from the hook's own program.

• hook_self is the PDA ["hook-authority"] of the hook program, so only the hook can sign it, by CPI with invoke_signed.
• The mint must have an external hook (not none, not the kit) with WRITES_HOOK_DATA, and the holding must be of that mint.
• The SDK has no builder for it: it is called from inside a hook program, not from a client.

The kit is the hook of every launch that turns on a token rule: holder rewards, a max wallet, a creator lock or an early-buyer lock. The mint's hook_program is HELIX's own id, and the kit runs inside HELIX, without a cross-program call. It can only be installed by create_launch: create_mint, set_hook and create_pool refuse it (KitOnlyThroughLaunch). Its hook accounts are just [launch], and a swap needs none. The rules are on Launches.