Reference

Hook schema

Every field of a hook, in the form you write for defineHook and in the form the Pook program stores, with the rule the program applies to each value when the hook is published and when it runs. Hooks says what each part is for.

The definition

defineHook(definition) checks a definition against the HookDraft schema and returns it frozen. pook.publishHook({ hook }) takes the result. A key the schema does not name is refused. The one key defineHook takes beside the schema's is notes, an array of strings kept on the definition and left out of what is published. Write a hook walks through one from start to finish.

A definition has two layers. The descriptive fields name every argument and account of the instruction, and the API returns them with the hook. The on-chain fields are the exact values the program stores. When an on-chain field is absent, it is derived from the descriptive fields by the mapping below.

In this page, hex means an even-length string of hex digits with no 0x prefix, and an address is base58 of 32 bytes.

Descriptive fields

FieldTypeRequiredMeaning
idstring, 2 to 48 charactersyesThe hook id, such as jupiter.swap. Stored on chain.
protocolstring, 1 to 32yesThe protocol's short name, such as jupiter. The registry filters by it.
protocolNamestring, 1 to 64yesThe protocol's name as shown, such as Jupiter.
labelstring, 1 to 64yesThe action's name, such as Swap.
descriptionstring, 1 to 280yesOne or two sentences on what a run does.
kindflow or seatyesThe kind. Stored on chain.
targetProgramaddressyesThe program the hook calls. Stored on chain.
instructionNamestring, 1 to 64yesThe instruction's name in the target program.
discriminatorhex, up to 256 bytesyesThe instruction's leading bytes.
dataTemplateobjectyesThe instruction data with named slots.
accountsTemplatearray, 1 to 48 entriesyesThe instruction's accounts, each with a role.
companionInstructionsarray, up to 8 entriesnoInstructions that must be in the same transaction.
formFieldsarray, up to 16 entriesnoThe inputs of the run screen. See Form fields.
mintInaddress or nullyesThe one mint going in, or null when the run chooses.
mintOutaddress or nullyesThe one mint coming out, or null when the run chooses.
assetInSymbolstring up to 24, or nullnoThe symbol shown for the asset in.
assetOutSymbolstring up to 24, or nullnoThe symbol shown for the asset out.

dataTemplate

FieldTypeRequiredMeaning
baseHexhex, up to 256 bytesyesThe instruction data as the target program expects it, with zero bytes where a slot writes.
slotsarray, up to 16 entriesyesThe values that change from run to run, in the order they are applied.

Each entry of slots:

FieldTypeRequiredMeaning
namestring, 1 to 64yesThe argument's name in the instruction.
kindslot kindyesWhere the value comes from.
offsetinteger, 0 to 256yesThe byte position in the data.
lengthinteger, 0 to 256yesThe number of bytes.
typeslot typeyesHow the bytes are read.
labelstring up to 64noThe name shown for the value.
descriptionstring up to 240noA note on the value.

The slot kinds, with the on-chain kind each becomes:

KindTypeMeaning
amount_inAmountInU64LeThe run’s amount in.
min_outMinOutU64LeThe run’s minimum out.
caller_argCallerSlice or CallerTailA value the caller supplies at run time.
seat_argCallerSlice or CallerTailA value the caller supplies for a seat action.

The slot types:

TypeTypeMeaning
u81 byteUnsigned integer.
u162 bytesUnsigned integer, little-endian.
u324 bytesUnsigned integer, little-endian.
u648 bytesUnsigned integer, little-endian.
u12816 bytesUnsigned integer, little-endian.
bool1 byte0 or 1.
pubkey32 bytesAn address.
byteslengthRaw bytes. With length 0 on a caller slot, the slot becomes a caller tail.

accountsTemplate

One entry per account, in the order the target program reads them.

FieldTypeRequiredMeaning
indexinteger, 0 to 47yesThe account's position in the instruction.
namestring, 1 to 64yesThe account's name in the instruction.
roleroleyesWho supplies the account.
addressaddress or nullnoThe address, for the roles that fix one.
writablebooleanyesWhether the target program writes to it.
signerbooleanyesWhether it signs the call.
descriptionstring up to 240noA note on the account.

The roles, with the on-chain kind each becomes:

RoleTypeMeaning
fixedFixedOne address written into the hook. Set it in address.
stage_authorityStagePdaPook’s stage, the address that signs the call.
stage_inStageInThe stage’s account holding the run’s amount in.
stage_outStageOutThe stage’s account the result arrives in.
seat_pdaSeatPdaThe seat. Seat hooks only.
caller_suppliedCallerOne account the caller supplies at run time.
programFixedA program the instruction names, such as the token program. Set it in address.
sysvarFixedA sysvar the instruction names. Set it in address.
payerPayerThe relayer. Seat hooks only.

companionInstructions

FieldTypeRequiredMeaning
programIdaddressyesThe program the companion instruction belongs to.
instructionNamestring, 1 to 64yesThe instruction's name.
discriminatorhex, up to 8 bytesyesThe leading bytes of the instruction's data.
positionbefore or afteryesbefore when it has to come ahead of the run.
descriptionstring up to 240noA note on what it does.

On-chain fields

Each of these is optional. One that is present is published as written and replaces its own derivation. The others are still derived.

FieldTypeMeaning
mintInConstraint{ kind: 'None' }, { kind: 'Any' }, { kind: 'Sol' } or { kind: 'Spl', mint }The mint constraint on the asset in.
mintOutConstraintthe sameThe mint constraint on the asset out.
wrapSolInbooleanWrap SOL going in. false when absent.
unwrapSolOutbooleanUnwrap wrapped SOL coming out. false when absent.
dataTemplateHexhex, up to 256 bytesThe data template's bytes.
dataSlotsarray, up to 16 entriesEach { offset, len, kind }, with offset and len integers from 0 to 256 and kind a data slot kind.
accountSlotsarray, up to 48 entriesEach { kind, isWritable, isSigner, pubkey }, with kind an account slot kind. pubkey is the System program's address when absent.
companionsarray, up to 8 entriesEach { programId, discriminatorHex, discLen, mustPrecede }, with discriminatorHex up to 8 bytes and discLen from 0 to 8. See Companions.

From descriptive to on-chain

On-chain valueTaken fromRule
hook_ididCopied.
target_programtargetProgramCopied.
kindkindflow becomes Flow, seat becomes Seat.
mint_inmintInConstraint, else mintInnull becomes Any. The wrapped SOL mint or the System program's address becomes Sol. Any other address becomes Spl with that mint.
mint_outmintOutConstraint, else mintOutThe same rule.
wrap_sol_inwrapSolInfalse when absent.
unwrap_sol_outunwrapSolOutfalse when absent.
data_templatedataTemplateHex, else dataTemplate.baseHexThe hex decoded to bytes.
data_slotsdataSlots, else dataTemplate.slotsOne slot per entry, in array order. offset is copied and length becomes len. Kind amount_in becomes AmountInU64Le. Kind min_out becomes MinOutU64Le. Any other kind becomes CallerTail when its type is bytes and its length is 0, and CallerSlice otherwise.
account_slotsaccountSlots, else accountsTemplateOne slot per entry, in array order. writable becomes is_writable, signer becomes is_signer, and address becomes pubkey, or the System program's address when there is none. Role stage_authority becomes StagePda, stage_in becomes StageIn, stage_out becomes StageOut, seat_pda becomes SeatPda, payer becomes Payer. Roles fixed, program and sysvar become Fixed. caller_supplied becomes Caller.
companionscompanions, else companionInstructionsprogramId is copied. discriminator becomes the discriminator bytes. disc_len is the discriminator's length in bytes, 8 at most. must_precede is true when position is before.

Three values come only from the on-chain fields: a None constraint, a CallerRemaining slot, and a wrap or unwrap flag set to true.

The schema holds a definition to the limits the program enforces: an id of 48 UTF-8 bytes, a template of 256 bytes, 16 data slots, 48 account slots and 8 companions.

The record on chain

A hook is one account owned by the Pook program. publish_hook creates it and the author pays its rent. Program lists the instruction's accounts and errors.

The hook address

The address is derived from the seeds [b"hook", hook_id_hash] under the Pook program. hook_id_hash is the SHA-256 of the id's UTF-8 bytes with the first byte set to 0. The same id always gives the same address, and publishing an id that already has an account fails with HookAlreadyPublished.

The hook id

An id uses lowercase a-z, 0-9, ., _ and -. It starts and ends with a letter or a digit and has at least 2 characters. The program stores up to 48 bytes.

publish_hook arguments

The instruction data is the tag byte 2, then these fields in order. Integers are little-endian. A boolean is one byte, 0 or 1. A list is a 4-byte count followed by its entries.

FieldEncodingLimit
hook_id4-byte length, then UTF-8 bytes1 to 48 bytes
target_program32 bytes
kind1 byte0 or 1
mint_in1 tag byte, then 32 bytes when the tag is 3
mint_outthe same
wrap_sol_in1 byte
unwrap_sol_out1 byte
data_template4-byte length, then the bytesup to 256 bytes
data_slotslist of 5-byte entriesup to 16
account_slotslist of 35-byte entriesup to 48
companionslist of 42-byte entriesup to 8

A data slot entry:

FieldEncoding
offset2 bytes
len2 bytes
kind1 byte, the data slot kind's tag

An account slot entry:

FieldEncoding
kind1 byte, the account slot kind's tag
is_writable1 byte
is_signer1 byte
pubkey32 bytes. Read for Fixed slots.

A companion entry:

FieldEncoding
program_id32 bytes
discriminator8 bytes, padded with zeros
disc_len1 byte, 0 to 8
must_precede1 byte

The Hook account

The account holds the same values with four fields the program adds. decodeHookAccount from @pook/contract reads it.

FieldEncodingMeaning
discriminator8 bytesThe ASCII bytes PKHOOK01.
hook_id_hash32 bytesThe hash the address is derived from.
hook_id4-byte length, then UTF-8 bytesThe id.
author32 bytesThe wallet that signed publish_hook.
target_program32 bytesAs published.
kind1 byteAs published.
mint_in1 or 33 bytesAs published.
mint_out1 or 33 bytesAs published.
wrap_sol_in1 byteAs published.
unwrap_sol_out1 byteAs published.
data_template4-byte length, then the bytesAs published.
data_slotslistAs published.
account_slotslistAs published.
companionslistAs published.
bump1 byteThe bump of the hook address.

What publish refuses

publish_hook fails with InvalidHookDefinition when any of these holds:

  • hook_id is empty or longer than 48 bytes.
  • data_template is longer than 256 bytes, or there are more than 16 data slots, 48 account slots or 8 companions.
  • target_program is the Pook program, the Solana Privacy Program, the System program or the upgradeable loader.
  • kind is Flow and mint_in is None.
  • A SeatPda or Payer slot is in a hook whose kind is Flow.
  • A Fixed, StageIn, StageOut, Caller or CallerRemaining slot has is_signer set.
  • There is more than one CallerRemaining slot.
  • A companion's disc_len is above 8.

It fails with InvalidHookAccount when the hook account passed is not the address derived from the id. Slot offsets are checked against the data when the hook runs.

Kind

KindTypeMeaning
flowtag 0The stage signs the call. Every run sends an amount in.
seattag 1The stage and the seat both sign the call. A run sends an amount in, or none.

A run states its own kind, and it has to fit the hook's. A flow hook takes a Flow run with an amount in above 0. A seat hook takes a SeatFund run with an amount in above 0, or a SeatAction run with an amount in of 0. A run kind the hook does not take fails with WrongHookKind, and an amount in that does not fit the run kind fails with InvalidInstructionData.

The kind also decides who owns the stage's token accounts. In a flow hook they are the stage address's associated token accounts. In a seat hook they are the seat's associated token accounts. The program measures each account by its change during the run, so a balance already there counts neither as the result nor as unused input. Runs and Seats cover the rest.

Mint constraints

mint_in and mint_out each hold one constraint. The run names its own mint in and mint out, and each is checked against the hook's constraint before any funds move. A mismatch fails with MintConstraintViolated.

ConstraintTypeMeaning
Nonetag 0No asset on this side. The run must carry none: an amount in of 0 for mint in, no mint out for mint out.
Anytag 1Any mint, SOL included. The run must carry an asset on this side and chooses which.
Soltag 2Native SOL only. The run’s mint must be the 32 zero bytes that stand for SOL.
Spltag 3 + 32 bytesOne named SPL or Token-2022 mint. The run’s mint must equal it.

A run has an asset in when its amount in is above 0. A run names SOL and wrapped SOL the same way, as 32 zero bytes: toProgramMintBytes from @pook/contract gives them for either mint.

A run with an amount in names an output owner, also when the hook's mint out is None. Whatever part of the amount in the target program leaves in the stage's account goes back to that owner as a note. When StageIn and StageOut are the same account, that part is counted in the result.

The run's minimum out comes from the hook's resolver. For a hook that has none, the caller sends minimumOut in the quote request, and a quote for a hook with a mint out is refused without it.

Data slot kinds

At run time the program copies data_template, then applies the data slots in the order they are stored. The caller's data is one byte string sent with the run. CallerSlice and CallerTail read it from the front, each starting where the last one stopped.

KindTypeMeaning
AmountInU64Letag 0Writes the run’s amount in as 8 bytes, little-endian, at offset. len is not read. Fails with DataSlotOutOfBounds when offset + 8 is past the end of the data.
MinOutU64Letag 1Writes the run’s minimum out as 8 bytes, little-endian, at offset. len is not read. Fails with DataSlotOutOfBounds when offset + 8 is past the end of the data.
CallerSlicetag 2Copies the next len bytes of the caller’s data to offset. Fails with DataSlotOutOfBounds when the caller’s data has fewer than len bytes left, or offset + len is past the end of the data.
CallerTailtag 3Appends every byte the caller’s data has left to the end of the data. offset is not read. A len above 0 is the most bytes the tail may hold, and a longer tail fails with DataSlotOutOfBounds. A len of 0 sets no maximum.

When every slot has been applied, all of the caller's data must have been read. Bytes left over fail the run with InvalidInstructionData.

The resulting bytes are the data of the call to the target program, and they are part of what the proof fixes.

Account slot kinds

The accounts of the call are built from the account slots in the order they are stored. The run carries a list of caller accounts. Fixed, Caller and CallerRemaining slots take from it in order.

KindTypeMeaning
Fixedtag 0Takes the next caller account. Its address must equal the slot’s pubkey, or the run fails with CallerAccountsMismatch. Passed with the slot’s writable flag. Cannot be a signer.
StagePdatag 1The stage address. Passed with the slot’s writable and signer flags. The program signs for it.
StageIntag 2The stage account holding the amount in. Passed with the slot’s writable flag. Cannot be a signer. A run with no amount in fails with CallerAccountsMismatch.
StageOuttag 3The stage account the result arrives in. Passed with the slot’s writable flag. Cannot be a signer. A run with no mint out fails with CallerAccountsMismatch.
SeatPdatag 4The seat’s address. Seat hooks only. Passed with the slot’s writable and signer flags. The program signs for it.
Callertag 5Takes the next caller account, whatever its address. Passed with the slot’s writable flag. Cannot be a signer.
CallerRemainingtag 6Takes every caller account that is left, in order. One per hook. Each is writable or read-only by its own flag in the run. Cannot be a signer.
Payertag 7The relayer, the account that pays for the transaction. Seat hooks only. Passed with the slot’s writable and signer flags.

The run fails with CallerAccountsMismatch when:

  • a Fixed or Caller slot finds no caller account left,
  • a Fixed slot's account has another address,
  • the number of accounts a CallerRemaining slot takes differs from the number of writable flags the run sent,
  • caller accounts are left over after the last slot.

The writable flags of a CallerRemaining slot are one byte per account, sent with the run: 0 for read-only, anything else for writable. The slot's own is_writable is not read.

What StageIn and StageOut resolve to

The run's assetStageInStageOut
An SPL or Token-2022 mintThe stage's associated token account for the mint inThe stage's associated token account for the mint out
SOL, with the wrap or unwrap flag setThe stage's wrapped SOL token accountThe stage's wrapped SOL token account
SOL, with the flag clearThe stage address itselfThe stage address itself

The flag is wrap_sol_in for StageIn and unwrap_sol_out for StageOut. In a seat hook the token accounts are the seat's.

Accounts the program refuses to pass

An account taken by a Fixed, Caller or CallerRemaining slot fails the run with ForbiddenHookAccount when it is one of these:

  • the Pook program or the Solana Privacy Program,
  • Pook's authority address, the config account or the hook account,
  • the run's output tree,
  • the author's fee account, or its token account,
  • the fee recipient's account for the run,
  • the seat's state account,
  • the Solana Privacy Program's vault account for an SPL mint out,
  • the Solana Privacy Program's vault account the amount in is withdrawn from.

Companions

A companion names an instruction that must be in the same transaction as the run.

FieldMeaning
program_idThe program the instruction must belong to.
discriminatorThe bytes the instruction's data must start with.
disc_lenHow many of those bytes are compared, 0 to 8. With 0, any instruction of the program matches.
must_precedetrue when the instruction has to come before the run in the transaction. false when it can be anywhere in it.

A hook with companions makes the run take the Instructions sysvar. The program reads the transaction's instructions from it and looks for each companion. One that is not found fails the run with MissingCompanionInstruction.

wrap_sol_in and unwrap_sol_out

Both flags act only when the run's asset on that side is native SOL.

FlagSetClear
wrap_sol_inThe amount in is moved from the stage into its wrapped SOL token account before the call. StageIn is that token account. A part the target program leaves there is unwrapped before it goes back to the holder.The amount in stays on the stage address as lamports. StageIn is the stage address.
unwrap_sol_outThe result is measured as the rise in the wrapped SOL token account's balance. After the call the account is closed and the result becomes lamports. StageOut is that token account.The result is measured as the rise in the stage address's lamports. StageOut is the stage address.

With unwrap_sol_out set, the wrapped SOL token account's rent goes back to the relayer when the account is closed.

Form fields

formFields describes the inputs of the run screen for a hook. Each entry is one input, and its kind decides which field of the quote request the value is sent in.

FieldTypeRequiredMeaning
namestring, 1 to 64yesThe input's name. For text and integer it is the key the value is sent under.
kindform field kindyesThe kind of input.
labelstring, 1 to 64yesThe label shown above the input.
requiredbooleanyesWhether a value is needed.
defaultValuestring up to 128noThe starting value.
placeholderstring up to 128noThe hint shown in an empty input.
KindTypeMeaning
asset_inmintInA choice of the asset going in. Shown when the hook does not name one mint in.
asset_outmintOutA choice of the asset coming out. Shown when the hook does not name one mint out.
amountamountInSets the label and placeholder of the amount input. The amount is sent in base units.
slippage_bpsslippageBpsA choice of slippage in basis points. defaultValue is the starting choice, 50 when absent.
seatseatAddressA choice among your open seats. When required is false, the choice includes opening a new seat.
textargs[name]A free input. Its value is sent under the field’s name.
integerargs[name]A numeric input. Its value is sent under the field’s name.

A seat field with required set to true makes the run act on an open seat. With required set to false, a run with no seat chosen opens one first.

The launch hooks

Pook published nine hooks at launch. jupiter.swap as a definition:

TypeScript
import { SYSTEM_PROGRAM_ID } from '@pook/contract'
import { defineHook } from '@pook/sdk'

export const jupiterSwapHook = defineHook({
  id: 'jupiter.swap',
  protocol: 'jupiter',
  protocolName: 'Jupiter',
  label: 'Swap',
  description: 'One asset in, another out, at Jupiter’s route.',
  kind: 'flow',
  targetProgram: 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4',
  instructionName: 'route_v2',
  discriminator: 'bb64facc31c4af14',
  mintInConstraint: { kind: 'Any' },
  mintOutConstraint: { kind: 'Any' },
  wrapSolIn: true,
  unwrapSolOut: true,
  dataTemplateHex: '',
  dataSlots: [{ offset: 0, len: 0, kind: 'CallerTail' }],
  accountSlots: [
    { kind: 'Caller', isWritable: false, isSigner: false, pubkey: SYSTEM_PROGRAM_ID },
    { kind: 'StagePda', isWritable: false, isSigner: true, pubkey: SYSTEM_PROGRAM_ID },
    { kind: 'StageIn', isWritable: true, isSigner: false, pubkey: SYSTEM_PROGRAM_ID },
    { kind: 'StageOut', isWritable: true, isSigner: false, pubkey: SYSTEM_PROGRAM_ID },
    { kind: 'CallerRemaining', isWritable: false, isSigner: false, pubkey: SYSTEM_PROGRAM_ID },
  ],
  companions: [],
  dataTemplate: {
    baseHex: '',
    slots: [
      { name: 'routeData', kind: 'caller_arg', offset: 0, length: 0, type: 'bytes', label: 'Jupiter route instruction payload' },
    ],
  },
  accountsTemplate: [
    { index: 0, name: 'tokenProgram', role: 'caller_supplied', writable: false, signer: false },
    { index: 1, name: 'userTransferAuthority', role: 'stage_authority', writable: false, signer: true },
    { index: 2, name: 'userSourceTokenAccount', role: 'stage_in', writable: true, signer: false },
    { index: 3, name: 'userDestinationTokenAccount', role: 'stage_out', writable: true, signer: false },
    { index: 4, name: 'routeAccounts', role: 'caller_supplied', writable: false, signer: false },
  ],
  mintIn: null,
  mintOut: null,
})

The on-chain fields are what is stored: an empty template and one CallerTail slot, so the whole of route_v2's data comes from the hook's resolver, and the route's accounts arrive through CallerRemaining. dataTemplate and accountsTemplate name the same slots for the API to return with the hook.

The other eight, as stored on chain. The programs they call:

HookKindTarget programInstruction
kamino.supplyFlowKLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjDdeposit_reserve_liquidity
kamino.withdrawFlowKLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjDredeem_reserve_collateral
jito.stakeFlowSPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHyDepositSol
jito.unstakeFlowSPoo1Ku8WFXoNDMHPsrGSTSG1Y47rzgn41SLUNakuHyWithdrawSol
kamino.collateral.depositSeatKLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjDdeposit_reserve_liquidity_and_obligation_collateral_v2
kamino.borrowSeatKLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjDborrow_obligation_liquidity_v2
kamino.repaySeatKLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjDrepay_obligation_liquidity_v2
kamino.collateral.withdrawSeatKLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjDwithdraw_obligation_collateral_and_redeem_reserve_collateral_v2

Their assets and data. Every data template is the bytes shown followed by 8 zero bytes, and its one slot fills those 8 bytes.

HookMint inMint outWrap SOL inUnwrap SOL outData template startsData slotAccount slots
kamino.supplyAnyAnyyesnoa9c91e7e06cd6644AmountInU64Le at 812
kamino.withdrawAnyAnynoyesea75b57db98edc1dAmountInU64Le at 812
jito.stakeSolSpl JitoSOLnono0eAmountInU64Le at 110
jito.unstakeSpl JitoSOLSolnono10AmountInU64Le at 112
kamino.collateral.depositAnyNoneyesnod8e0bf1bcc9766afAmountInU64Le at 815
kamino.borrowNoneAnynoyesa1808ff5abc7c206CallerSlice at 8, 8 bytes13
kamino.repayAnyNoneyesno74aed54cb435d290AmountInU64Le at 810
kamino.collateral.withdrawNoneAnynoyeseb34779895c51407CallerSlice at 8, 8 bytes15

The JitoSOL mint is J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn. kamino.borrow and kamino.collateral.withdraw send no amount in, so the amount to borrow or withdraw is 8 bytes of caller data placed by the CallerSlice.

Their companions. Each is an instruction of the Kamino Lend program, compared on all 8 bytes, and has to come before the run.

HookCompanions
kamino.supplyrefresh_reserve (02da8aeb4fc91966)
kamino.withdrawrefresh_reserve (02da8aeb4fc91966)
jito.stakenone
jito.unstakenone
kamino.collateral.depositrefresh_reserve (02da8aeb4fc91966), refresh_obligation (218493e497c04859)
kamino.borrowrefresh_reserve, refresh_obligation
kamino.repayrefresh_reserve, refresh_obligation
kamino.collateral.withdrawrefresh_reserve, refresh_obligation