Reference

Program

The pook program is one Solana program at 7qvNkZjiikySgCNbr8jbWbUziVka3Rw1NLwcxwmwwRwd. This page lists its addresses, accounts, instructions, call hash, circuits and errors with their exact values.

Addresses

Every address is derived from the program id.

AddressSeedsWhat it is
Authority[b"authority"]F5LdT1ZsevWdh2HQviGQtUhoBn8nn9UYScqi3pE3F2Yr. Owns every Pook note and signs the calls to the Solana Privacy Program. It holds no data.
Stage[b"stage"]9hqmRBsxBtGkEywAuZ89McRqccDuVm68NJXcXNUQQdFf. Receives a run's amount in, signs the protocol call and the deposit of the result. It holds no data.
Config[b"config"]9JtAtvLC4PNsKjEEiB1tNQN95GBgLfnRxqHotjaNfgZX. The Config account.
Hook[b"hook", Sha256BE(hook_id)]One Hook account per hook id.
Author fees[b"author_fees", author, mint]One AuthorFees account per author and mint. mint is 32 zero bytes for SOL.
Seat[b"seat", commitment]Owns a position at a protocol and signs for it. Owned by the System program. It holds no data.
Seat state[b"seat_state", commitment]The Seat account.

Sha256BE is SHA-256 with the first byte of the digest set to zero, so the result fits a BN254 field element. hook_id is hashed as its UTF-8 bytes.

Stage token accounts are associated token accounts: of the stage for a flow hook, of the seat for a seat hook. The fee recipient's token account and an author fees account's token account are associated token accounts as well.

Conventions

  • Instruction data starts with one tag byte. The arguments follow in the order listed.
  • Integers are little-endian. A bool is one byte, 0 or 1.
  • A mint argument of 32 zero bytes means SOL.
  • Account data and the arguments of init_config, set_config, publish_hook, enter from a public wallet and claim_author_fees are Borsh: a String or Vec is a u32 length followed by its items.
  • run, leave, open_seat and close_seat carry a proof. Their arguments are followed by the instruction data of the Solana Privacy Program's transact, and their account list ends with that instruction's accounts. The program forwards both unchanged in a call signed by the authority, which must be among those accounts.
  • proof is 128 bytes: a (32), b (64), c (32).
  • expiry is a Unix time in seconds. An instruction is accepted while the clock is at or before it, and the transact data must carry the same expiry.

Accounts

Each account starts with an 8-byte ASCII discriminator.

Config

77 bytes. Discriminator PKCONFIG.

FieldTypeMeaning
discriminator[u8; 8]Offset 0.
admin[u8; 32]Offset 8. The wallet that may call set_config.
fee_recipient[u8; 32]Offset 40. Receives the protocol share of each run fee.
run_fee_bpsu16Offset 72. The run fee in basis points of what a run returns, 0 to 10,000.
author_share_bpsu16Offset 74. The author’s share of the run fee in basis points, 0 to 10,000.
bumpu8Offset 76.

Hook

Variable length, sized to its content when published. Discriminator PKHOOK01. Fields are stored in this order. Hook schema gives the meaning of each slot kind.

FieldTypeMeaning
discriminator[u8; 8]8 bytes.
hook_id_hash[u8; 32]Sha256BE of hook_id. The seed of the account’s address.
hook_idString4 bytes of length, then 1 to 48 bytes.
author[u8; 32]The signer of publish_hook.
target_program[u8; 32]The program the hook calls.
kindu80 Flow, 1 Seat.
mint_inMintConstraintOne tag byte: 0 None, 1 Any, 2 Sol, 3 Spl. Spl is followed by the 32-byte mint.
mint_outMintConstraintSame encoding as mint_in.
wrap_sol_inboolSOL going in is wrapped into the stage’s wrapped SOL account before the call.
unwrap_sol_outboolWrapped SOL coming out is unwrapped and settled as SOL.
data_templateVec<u8>4 bytes of length, then up to 256 bytes.
data_slotsVec<DataSlot>4 bytes of count, then up to 16 slots of 5 bytes: offset u16, len u16, kind u8 (0 AmountInU64Le, 1 MinOutU64Le, 2 CallerSlice, 3 CallerTail).
account_slotsVec<AccountSlot>4 bytes of count, then up to 48 slots of 35 bytes: kind u8 (0 Fixed, 1 StagePda, 2 StageIn, 3 StageOut, 4 SeatPda, 5 Caller, 6 CallerRemaining, 7 Payer), is_writable bool, is_signer bool, pubkey [u8; 32].
companionsVec<CompanionRequirement>4 bytes of count, then up to 8 entries of 42 bytes: program_id [u8; 32], discriminator [u8; 8], disc_len u8, must_precede bool.
bumpu81 byte.

AuthorFees

81 bytes. Discriminator PKAFEE01. run creates the account the first time an author's share accrues in a mint, and the relayer pays its rent.

FieldTypeMeaning
discriminator[u8; 8]Offset 0.
author[u8; 32]Offset 8. The hook author the fees belong to.
mint[u8; 32]Offset 40. 32 zero bytes for SOL.
accruedu64Offset 72. The amount waiting to be claimed. claim_author_fees sets it to zero.
bumpu8Offset 80.

Accrued SOL sits in the account itself, above its rent. Accrued tokens sit in the account's associated token account for the mint.

Seat

82 bytes. Discriminator PKSEAT01. Stored at the seat state address.

FieldTypeMeaning
discriminator[u8; 8]Offset 0.
commitment[u8; 32]Offset 8. The seat commitment.
opener_relayer[u8; 32]Offset 40. The payer of open_seat. close_seat returns the rent to it.
opened_ati64Offset 72. The clock’s Unix time when the seat was opened.
seat_pda_bumpu8Offset 80. The bump of the seat address.
bumpu8Offset 81. The bump of the seat state address.

Instructions

The second column is the tag byte.

InstructionTypeMeaning
init_config0Creates the config account. The signer becomes the admin.
set_config1Replaces the admin, the fee recipient and both fee rates.
publish_hook2Creates a hook account. The signer becomes its author.
enter3Moves an asset from a public wallet or a Rings private balance into a Pook note.
run4Runs one hook: verifies the proof, spends notes, calls the protocol, takes fees, deposits the result and any unused input.
leave5Moves an asset from Pook notes to a public address or a Rings private balance.
open_seat6Creates a seat state account, reserves the commitment and creates the first seat note.
close_seat7Spends the seat note for good, closes the seat state account and returns its rent.
claim_author_fees8Pays an author what has accrued to them in one mint.

In the account tables, W marks a writable account and S a signer.

init_config

ArgumentTypeMeaning
fee_recipient[u8; 32]Stored in the config.
run_fee_bpsu16At most 10,000.
author_share_bpsu16At most 10,000.
#AccountWSWhat it is
0adminWSPays the rent and is stored as the admin.
1configWThe config address.
2system_program

set_config

Writes all four values.

ArgumentTypeMeaning
admin[u8; 32]The admin from now on.
fee_recipient[u8; 32]The fee recipient from now on.
run_fee_bpsu16At most 10,000.
author_share_bpsu16At most 10,000.
#AccountWSWhat it is
0adminSThe admin stored in the config.
1configWThe config address.

publish_hook

The arguments are the Hook account's fields from hook_id to companions, in the same order and encoding. The program computes hook_id_hash, author and bump.

ArgumentTypeMeaning
hook_idString1 to 48 bytes.
target_program[u8; 32]Any program except Pook, the Solana Privacy Program, the System program and the upgradeable loader.
kindu80 Flow, 1 Seat.
mint_inMintConstraintA flow hook cannot use None.
mint_outMintConstraintNone for a hook whose protocol returns nothing.
wrap_sol_inbool
unwrap_sol_outbool
data_templateVec<u8>Up to 256 bytes.
data_slotsVec<DataSlot>Up to 16.
account_slotsVec<AccountSlot>Up to 48. SeatPda and Payer slots only in a seat hook. One CallerRemaining slot at most. Only StagePda, SeatPda and Payer slots may set is_signer.
companionsVec<CompanionRequirement>Up to 8. disc_len is at most 8.
#AccountWSWhat it is
0authorWSPays the rent and is stored as the author.
1hookWThe hook address for hook_id. It must not exist yet.
2system_program

enter

The byte after the tag is the mode: 0 from a public wallet, 1 from a Rings private balance.

Mode 0 deposits to the Solana Privacy Program for a one-time owner, tagged with the authority.

ArgumentTypeMeaning
kindu80 for SOL. 1 for a token, followed by one more byte: spl_interface_bump, the bump of the Solana Privacy Program’s interface account for the mint.
authority_bumpu8The bump of the authority address.
owner_hash[u8; 32]The one-time owner of the new note.
amountu64Greater than zero.
#SOLToken
0depositor W Sdepositor W S
1tree Wtree W
2spp_programspp_program
3system_programtoken_program
4sol_interface Wmint
5user_token W
6spl_interface W

Mode 1 takes authority_bump (u8) followed by transact instruction data signed by the holder's Rings wallet. The accounts are that instruction's accounts, with the Solana Privacy Program at index 2. At least one output must carry the authority as its inline owner tag.

run

ArgumentTypeMeaning
kindu80 Flow, 1 SeatFund, 2 SeatAction. It selects the circuit.
proof[u8; 128]
authority_bumpu8
stage_bumpu8
amount_inu64Greater than zero for Flow and SeatFund. Zero for SeatAction.
min_outu64The least the call must bring to the stage out account.
output_owner_hash[u8; 32]The one-time owner of the result note and of the note that returns unused input. A run with an amount in names one even when the hook has no asset out. Zero when the run has neither.
relayer_feeu64Taken from the result in the asset out.
expiryu64
seat_commitment[u8; 32]Zero for Flow.
mint_in[u8; 32]Zero for SOL and when amount_in is zero.
mint_out[u8; 32]Zero for SOL and when has_mint_out is false.
has_mint_outboolFalse when the hook’s mint_out is None.
out_spl_interface_bumpu8The bump of the Solana Privacy Program’s interface account for mint_out. Unused for SOL.
spp_account_countu8How many of the trailing accounts belong to transact.
caller_databytesA u16 length, then the bytes that fill the hook’s CallerSlice and CallerTail slots.
caller_remaining_writablebytesA u8 length, then one byte per CallerRemaining account: 1 writable, 0 read-only.

The accounts come in groups, in this order. A group whose condition does not hold is left out.

GroupPresent whenAccounts in order
HeaderAlwayspayer W S (the relayer), config, hook, stage W, target_program, system_program, output_tree W, spp_program
InSOL in and the hook wraps ittoken_program_in, stage_in_wsol_ata W
InA token intoken_program_in, mint_in, stage_in_ata W
OutSOL outsol_interface_out W, fee_recipient W, author_fees W. When the hook unwraps: then token_program_out, stage_out_wsol_ata W
OutA token outtoken_program_out, mint_out, stage_out_ata W, spl_interface_out W, fee_recipient_ata W, author_fees W, author_fees_ata W, relayer_fee_ata W
SeatA seat hookseat_state, seat W
CompanionsThe hook names companionsinstructions_sysvar
TransactAlwaysspp_account_count accounts, at least 4. The second is output_tree.
CallerThe hook has Fixed, Caller or CallerRemaining slotsOne account per Fixed and Caller slot in slot order, then every CallerRemaining account

SOL in that the hook does not wrap adds no accounts to the In group: the stage itself is the stage in account. SOL out that the hook does not unwrap arrives in the stage itself.

The program refuses a caller account that is the Pook program, the Solana Privacy Program, the authority, the config, the hook, output_tree, author_fees, author_fees_ata, the fee recipient account, seat_state, spl_interface_out or the interface account among the transact accounts that the amount in is withdrawn from.

The protocol share goes to fee_recipient or fee_recipient_ata, the author's share to author_fees or author_fees_ata, the relayer's fee to payer or relayer_fee_ata. The rest is deposited for output_owner_hash, tagged with the authority.

The program measures the stage in and stage out accounts by their change since before the withdrawal. Input the protocol call leaves unused in the stage in account, at most amount_in, returns to the holder as a note for output_owner_hash, tagged with the authority. It goes in the same deposit as the result, through the interface account the withdrawal used among the transact accounts. A seat hook with SOL on one side and a token on the other makes a second deposit for it. Wrapped SOL left unused is unwrapped and returns as SOL. The run fee and the relayer's fee are computed on the result only, never on the returned input. When stage in and stage out are the same account, unused input is part of the result. A hook with no asset out returns unused input when output_owner_hash is not zero.

The amounts are defined in Fees and POOK, and the order of work inside run in Runs.

leave

ArgumentTypeMeaning
proof[u8; 128]
authority_bumpu8
stage_bumpu8
leave_kindu80 to a public address or token account, 1 to a Rings private balance.
mint[u8; 32]Zero for SOL.
amountu64What leaves the notes. Greater than zero.
relayer_feeu64Less than amount. The destination receives amount minus relayer_fee.
expiryu64
dest_owner_hash[u8; 32]For leave_kind 1, the owner hash of the receiving Rings balance. Zero for leave_kind 0.
dest_view_tag[u8; 32]For leave_kind 1, the view tag of the receiving Rings balance. Zero for leave_kind 0.
spl_interface_bumpu8Used for leave_kind 1 with a token.
spp_account_countu8The exact number of transact accounts that follow.

Accounts 0 to 2 are payer W S (the relayer), stage W and system_program. The next group depends on the destination, and the transact accounts follow it.

DestinationAccounts in order
Public address, SOLdest_wallet W
Public token accounttoken_program, mint, stage_ata W, dest_ata W, relayer_fee_ata W
Rings private balance, SOLoutput_tree W, spp_program, sol_interface W
Rings private balance, tokenoutput_tree W, spp_program, token_program, mint, stage_ata W, spl_interface W, relayer_fee_ata W

The relayer's fee is paid to payer in SOL, or to relayer_fee_ata in a token.

open_seat

ArgumentTypeMeaning
proof[u8; 128]
authority_bumpu8
seat_commitment[u8; 32]Poseidon of the domain PKST, read as a big-endian u32, and the hash of the seat secret.
expiryu64
spp_account_countu8How many of the trailing accounts belong to transact. At least 4.
setup_cpislistA u8 count, at most 4. Each entry: target_program [u8; 32], a u16 length and that many data bytes, a u8 count of accounts (at most 16), then per account: account_index u8, is_writable bool, is_signer bool.
#AccountWSWhat it is
0payerWSThe relayer. Pays the rent and is stored as opener_relayer.
1seat_stateWThe seat state address. It must not exist yet.
2seatWThe seat address.
3system_program
4..transact accountsspp_account_count of them.
thensetup accountsEverything after the transact accounts.

A setup call is a call to the protocol the seat will hold a position at, made once the seat exists and signed by the seat. account_index 0 is the payer, 1 the seat, 2 the System program, and 3 and up index the setup accounts from zero. Only the payer and the seat can be signers. A setup call cannot target Pook, the Solana Privacy Program, the System program or the upgradeable loader, and cannot name the Pook program, the Solana Privacy Program, the authority, the config, the stage, seat_state or the output tree.

close_seat

ArgumentTypeMeaning
proof[u8; 128]
authority_bumpu8
seat_commitment[u8; 32]
expiryu64
#AccountWSWhat it is
0payerWSThe relayer.
1seat_stateWClosed by this instruction.
2seatWAny lamports on it go to opener_relayer.
3opener_relayerWThe address stored in the seat state. Receives the rent.
4system_program
5..transact accounts

claim_author_fees

ArgumentTypeMeaning
mint[u8; 32]The mint to claim. Zero for SOL.
#AccountWSWhat it is
0authorWSThe author. Receives SOL claims.
1author_feesWThe author fees address for the signer and mint.
2token_programToken claims only, with the three below.
3mint
4author_fees_ataWThe associated token account of author_fees.
5author_dest_ataWThe token account that receives the claim.

A SOL claim pays accrued, or every lamport the account holds above its rent when that is less. A token claim transfers accrued.

The call hash

A run's proof fixes the protocol call as one field element. The program builds the call from the hook and the run's arguments, hashes it, and gives the hash to the verifier as call_hash.

Text
call_hash = Sha256BE(
    "PKCALL01"                      8 bytes, ASCII
    target_program                  32 bytes
    has_mint_out                    1 byte
    mint_out                        32 bytes
    data length                     u32, little-endian
    data                            the data template with every slot filled
    account count                   u16, little-endian
    per account, in call order:
        address                     32 bytes
        is_writable                 1 byte
        is_signer                   1 byte
)

The accounts are the ones the protocol receives, in the order of the hook's account slots, with a CallerRemaining slot expanded in place. is_signer is taken from the slot for StagePda, SeatPda and Payer slots and is 0 for every other kind. is_writable is taken from the slot, and from caller_remaining_writable for CallerRemaining accounts.

Circuits

The program verifies Groth16 proofs over BN254 with one verifying key per circuit. Each circuit's public inputs are hashed, in the order listed, together with the transaction hash into the single public input of the proof. The transaction hash is computed from the private_tx_hash in the transact data and the public withdrawal: the mint, the amount and the stage account that receives it.

CircuitVerified byConstraintsPublic inputs in order
runrun with kind Flow9,891authority_identity, hook_hash, call_hash, amount_in, min_out, output_owner_hash, relayer_fee, expiry
leaveleave9,898authority_identity, leave_kind, dest_hash, dest_view_tag_hash, amount, relayer_fee, expiry
seat_openopen_seat6,170authority_identity, seat_commitment, expiry
seat_fundrun with kind SeatFund15,721authority_identity, seat_commitment, hook_hash, call_hash, amount_in, min_out, output_owner_hash, relayer_fee, expiry
seat_actionrun with kind SeatAction6,740authority_identity, seat_commitment, hook_hash, call_hash, min_out, output_owner_hash, relayer_fee, expiry
seat_closeclose_seat4,578authority_identity, seat_commitment, expiry

enter has no circuit.

The program computes these inputs itself. The rest come from the instruction's arguments.

InputHow the program computes it
authority_identityThe Solana Privacy Program's owner identity of the authority address.
hook_hashThe hash of the hook account's address.
call_hashThe call hash.
dest_hashleave_kind 0: the hash of the destination wallet or token account address. leave_kind 1: dest_owner_hash.
dest_view_tag_hashleave_kind 0: zero. leave_kind 1: the hash of dest_view_tag.

run, leave and seat_fund spend one or two notes of one asset and return the change as one note. seat_fund and seat_action spend the seat note and create it again under a new one-time owner. seat_open reserves the commitment and creates the first seat note. seat_close spends the seat note without creating another.

Errors

The second column is the custom error code a failed transaction reports.

ErrorTypeMeaning
InvalidInstructionData7500The arguments do not decode. Also: an enter mode other than 0 or 1, an enter amount of zero, a transact expiry that differs from the expiry argument, transact data of a leave or of a run with an amount in that does not carry exactly one withdrawal of the asset and amount in, a run withdrawal whose accounts are not among the transact accounts, any public transfer in the transact data of open_seat, close_seat or a run with no amount in, a run whose amount_in is zero for Flow or SeatFund or non-zero for SeatAction, an output_tree that is not the second transact account, fewer than 4 transact accounts in a run, caller data bytes that no data slot used, more than 4 setup calls, a setup call with more than 16 accounts.
ConfigAlreadyInitialized7501init_config when the config account already exists.
InvalidConfigAccount7502The config account is not at the config address, is not owned by the program, or does not start with the Config discriminator.
UnauthorizedAdmin7503The signer of set_config is not the admin stored in the config.
InvalidFeeRate7504run_fee_bps or author_share_bps is above 10,000 in init_config or set_config.
InvalidHookAccount7505publish_hook: the hook account is not at the address derived from hook_id. run: the hook account is not owned by the program, does not start with the Hook discriminator, or does not decode.
HookAlreadyPublished7506publish_hook for a hook_id whose account already exists.
InvalidHookDefinition7507publish_hook with arguments that break one of the rules listed under publish_hook.
InvalidAuthorityPda7508authority_bump does not derive an address from the authority seed.
InvalidStagePda7509stage_bump does not derive an address from the stage seed, or the stage account passed is not that address.
InvalidStageTokenAccount7510A stage token account is not the associated token account of the stage (of the seat, for a seat hook) for that mint, holds another mint or owner, or is too short. Also a mint account that differs from the mint argument.
StageNotEmpty7511No instruction returns it. A balance already in a stage account does not stop a run or a leave, and a run counts only what changes during the run.
ProofVerificationFailed7512The Groth16 proof does not verify against the public inputs the program computed.
HashingFailed7513A hash over the public inputs, the hook id or the call cannot be computed.
Expired7514The clock is past the expiry argument.
InvalidShieldedPoolProgram7515The account passed as the Solana Privacy Program is another address.
MissingAuthorityPda7516The authority is not among the transact accounts.
ForbiddenHookAccount7517run: an account given for a Fixed, Caller or CallerRemaining slot is one of the forbidden accounts, or a flow hook has a Payer slot. open_seat: a setup call targets a forbidden program, names a forbidden account, or marks an account other than the payer or the seat as signer.
TargetProgramMismatch7518The target_program account of run is not the program the hook names.
SlippageExceeded7519The amount the protocol call added to the stage out account is less than min_out, or the account holds less than it did before the run.
OutputBelowFees7520The run fee plus the relayer fee is equal to or greater than the amount that arrived.
MintConstraintViolated7521mint_in or mint_out of run does not satisfy the hook mint_in or mint_out.
MissingCompanionInstruction7522A companion the hook requires is not in the transaction, or does not come before run when it must.
InvalidFeeRecipient7523The fee recipient account is not the one in the config, or the token account is not its associated token account for mint_out.
InvalidAuthorFeesAccount7524The author fees account or its token account is not at the address derived for the hook author and the mint, is not owned by the program, or does not start with the AuthorFees discriminator. In claim_author_fees, also a mint account that differs from the mint argument.
UnauthorizedAuthor7525The signer of claim_author_fees is not the author stored in the account.
NothingToClaim7526accrued is zero, or for SOL the account holds nothing above its rent.
InvalidSeatAccount7527The seat or seat state account is not at the address derived from seat_commitment, the seat state is not owned by the program or does not start with the Seat discriminator, its commitment differs, or the opener_relayer account of close_seat differs from the one stored.
SeatAlreadyOpen7528open_seat for a commitment whose seat state account already exists.
SeatNotClosable7529No instruction returns it.
WrongHookKind7530The run kind does not fit the hook: Flow needs a flow hook, SeatFund and SeatAction need a seat hook.
StageLamportsDrained7531After the protocol call the stage holds fewer lamports than it held before the amount in arrived.
InvalidTokenProgram7532A token program account is neither SPL Token nor Token-2022.
InvalidSystemProgram7533The system program account is another address.
InvalidInstructionsSysvar7534The instructions sysvar account is another address, or its data cannot be read.
Overflow7535A sum of fees, accrued fees or lamports does not fit in 64 bits.
InvalidRelayerFee7536leave with an amount of zero, or a relayer_fee equal to or greater than the amount.
InvalidLeaveKind7537leave_kind is not 0 or 1.
InvalidEnterOwnerTag7538enter from a Rings private balance where no output of the transact data is tagged with the authority.
CallerAccountsMismatch7539The caller accounts of run do not line up with the hook account slots: one is missing or left over, a Fixed slot got another address, caller_remaining_writable has a different length from the remaining accounts, or a StageIn or StageOut slot has no stage account in this run. In open_seat, a setup call names an account index that is not there.
DataSlotOutOfBounds7540A data slot writes past the end of the data template, a CallerSlice reads past the end of the caller data, or the caller tail is longer than the slot len.

An unknown tag, or instruction data with no bytes, returns Solana's own InvalidInstructionData. A trailing account list that does not fit spp_account_count returns NotEnoughAccountKeys.

Compute and size

Runs lists the measured compute units, bytes and accounts of every launch hook, of opening and closing a seat and of a leave.