Concepts

Runs

A run is one action through one hook. It is a single Solana transaction that spends your notes, calls the protocol the hook describes, and puts what comes back into your private balance. A relayer signs and pays for the transaction. Your wallet is not in it.

  1. 1ProofPook verifies the holder’s proof. It binds the hook, the accounts and data, the amount in, the minimum out, the owner of the output, the relayer’s fee and an expiry to this one transaction.
  2. 2SpendThe holder’s notes are nullified, change returns as a new note, and the amount in moves to the stage.
  3. 3CallPook calls the protocol exactly as the hook describes, signing as the stage.
  4. 4CheckPook measures what arrived in the stage. Less than the minimum out fails the whole transaction.
  5. 5DepositThe run fee and the relayer’s fee come off, and the rest becomes a new note for the owner the proof fixed.
One transaction. Every step completes, or none of them happened.

How a run works walks one run from start to end. This page holds the exact rules: what the proof fixes, the order the program works in, what makes a run fail, and what a run takes on chain.

What you decide before a run

Every value below is fixed by your proof. The relayer that submits the run cannot change any of them, and the program refuses a transaction where one differs.

ValueWhat it is
The hookThe address of the hook's account.
The callThe protocol's program, the exact instruction data after the slots are filled, and every account passed to the protocol with its writable and signer flags.
Amount inWhat leaves your notes for the stage, in the smallest unit of the asset in.
Minimum outThe least the run may bring back. Less than this and the run fails.
Output ownerThe one-time owner of the note that receives the result.
Relayer's feeWhat the relayer takes from the result.
ExpiryA Unix time in seconds. The proof is valid up to and including that second.

The call is fixed as one hash over the target program, the asset out, the instruction data and the account list. Changing one account in a swap route changes the hash, and the proof no longer verifies.

The order of a run

The program does these in order inside one instruction, run.

  1. Checks before anything moves

    The program reads the clock and refuses an expired proof. It loads the hook, checks that the protocol's program is the one the hook names, and checks the assets against the hook's mints. If the hook names companion instructions, it checks that each one is in the transaction.

  2. Proof

    The program builds the instruction it is about to send to the protocol, hashes it, and verifies your proof against that hash and the values in the table above. No asset has moved yet.

  3. Spend

    The program calls the Solana Privacy Program. Your input notes are nullified, change comes back as a new note, and the amount in arrives in the stage.

  4. Call

    The program calls the protocol and signs as the stage. For a seat hook it signs as the seat.

  5. Check

    The program measures what arrived in the stage's out account, as the change in its balance since before the run. Less than the minimum out fails the transaction.

  6. Fees and deposit

    The run fee and the relayer’s fee come off what arrived. The rest is deposited to the Solana Privacy Program as a new note for the output owner.

Notes in, notes out

A run spends one or two of your notes of the asset in. Together they must hold at least the amount in. What is left over returns as one change note under a new one-time key.

The result arrives as one new note of the asset out. So a run that spends two notes leaves you with two: the change and the result.

A hook whose protocol returns nothing, such as a repayment or a collateral deposit, has no result note, and with no result there is no run fee and no relayer's fee.

If the protocol takes less than the amount in, the part it left is returned to you as a note in the same transaction. A repayment larger than the debt comes back this way. The fees are worked out on what the protocol returned, never on input handed back.

Three kinds of run

The run instruction takes one of three proofs, by what the hook does.

KindUsed bySpends notesPresents a seat
FlowFlow hooks: jupiter.swap, kamino.supply, kamino.withdraw, jito.stake, jito.unstakeYesNo
Seat fundSeat hooks that put an asset into a seat: kamino.collateral.deposit, kamino.repayYesYes
Seat actionSeat hooks that take an asset out of a seat: kamino.borrow, kamino.collateral.withdrawNoYes

Seats explains the two seat kinds.

When a run fails

A Solana transaction is all or nothing. When any step fails, the spend in step 3 is undone with everything else, and your notes are exactly as they were.

What happenedProgram errorWhat to do
The protocol returned less than the minimum outSlippageExceeded (7519)Quote again. Raise the slippage if the price is moving.
The proof reached the chain after its expiryExpired (7514)Prove again. Nothing was spent.
The result is no larger than the fees taken from itOutputBelowFees (7520)Run a larger amount.
The asset in or out is not one the hook allowsMintConstraintViolated (7521)Use the mints the hook names.
A companion instruction the hook requires is missingMissingCompanionInstruction (7522)The relayer builds these. Send the run again.
An account passed to the protocol is one of Pook's ownForbiddenHookAccount (7517)The hook or the resolved accounts are wrong.
The accounts do not match the hook's account slotsCallerAccountsMismatch (7539)Resolve the accounts again from the hook.
The proof does not match the transactionProofVerificationFailed (7512)Something changed between proving and sending. Prove again.

A relayer that never sends your run costs you nothing. The same proof can go to another relayer until it expires.

The full list of errors is in the program reference.

What a run takes on chain

A run travels as a version 1 transaction: up to 4,096 bytes and 64 addresses, with a compute limit of 1,400,000 units.

Measured on a local network running the mainnet programs, one transaction each:

TransactionCompute unitsBytesAccounts
jupiter.swap, USDC to SOL through a Meteora DLMM pool353,0711,93733
jupiter.swap, SOL to USDC through a Raydium CLMM pool370,7821,95734
kamino.supply, USDC366,1231,74329
kamino.withdraw, to USDC351,9441,74329
jito.stake309,6571,55624
jito.unstake306,4931,62326
Opening a seat at Kamino338,9311,76523
kamino.collateral.deposit, USDC384,5772,05031
kamino.borrow, SOL429,9822,00930
kamino.repay, SOL412,7222,13628
kamino.collateral.withdraw, USDC421,6612,07933
Closing a seat213,3119189
Leave, SOL to a public address224,6941,04410
Leave, USDC to a Rings private balance281,0671,18214

Each figure covers everything in the transaction: the proof check, the spend, the protocol's own work, the fees and the deposit.