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.
- 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.
- 2SpendThe holder’s notes are nullified, change returns as a new note, and the amount in moves to the stage.
- 3CallPook calls the protocol exactly as the hook describes, signing as the stage.
- 4CheckPook measures what arrived in the stage. Less than the minimum out fails the whole transaction.
- 5DepositThe run fee and the relayer’s fee come off, and the rest becomes a new note for the owner the proof fixed.
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.
| Value | What it is |
|---|---|
| The hook | The address of the hook's account. |
| The call | The 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 in | What leaves your notes for the stage, in the smallest unit of the asset in. |
| Minimum out | The least the run may bring back. Less than this and the run fails. |
| Output owner | The one-time owner of the note that receives the result. |
| Relayer's fee | What the relayer takes from the result. |
| Expiry | A 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.
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.
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.
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.
Call
The program calls the protocol and signs as the stage. For a seat hook it signs as the seat.
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.
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.
| Kind | Used by | Spends notes | Presents a seat |
|---|---|---|---|
| Flow | Flow hooks: jupiter.swap, kamino.supply, kamino.withdraw, jito.stake, jito.unstake | Yes | No |
| Seat fund | Seat hooks that put an asset into a seat: kamino.collateral.deposit, kamino.repay | Yes | Yes |
| Seat action | Seat hooks that take an asset out of a seat: kamino.borrow, kamino.collateral.withdraw | No | Yes |
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 happened | Program error | What to do |
|---|---|---|
| The protocol returned less than the minimum out | SlippageExceeded (7519) | Quote again. Raise the slippage if the price is moving. |
| The proof reached the chain after its expiry | Expired (7514) | Prove again. Nothing was spent. |
| The result is no larger than the fees taken from it | OutputBelowFees (7520) | Run a larger amount. |
| The asset in or out is not one the hook allows | MintConstraintViolated (7521) | Use the mints the hook names. |
| A companion instruction the hook requires is missing | MissingCompanionInstruction (7522) | The relayer builds these. Send the run again. |
| An account passed to the protocol is one of Pook's own | ForbiddenHookAccount (7517) | The hook or the resolved accounts are wrong. |
| The accounts do not match the hook's account slots | CallerAccountsMismatch (7539) | Resolve the accounts again from the hook. |
| The proof does not match the transaction | ProofVerificationFailed (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:
| Transaction | Compute units | Bytes | Accounts |
|---|---|---|---|
jupiter.swap, USDC to SOL through a Meteora DLMM pool | 353,071 | 1,937 | 33 |
jupiter.swap, SOL to USDC through a Raydium CLMM pool | 370,782 | 1,957 | 34 |
kamino.supply, USDC | 366,123 | 1,743 | 29 |
kamino.withdraw, to USDC | 351,944 | 1,743 | 29 |
jito.stake | 309,657 | 1,556 | 24 |
jito.unstake | 306,493 | 1,623 | 26 |
| Opening a seat at Kamino | 338,931 | 1,765 | 23 |
kamino.collateral.deposit, USDC | 384,577 | 2,050 | 31 |
kamino.borrow, SOL | 429,982 | 2,009 | 30 |
kamino.repay, SOL | 412,722 | 2,136 | 28 |
kamino.collateral.withdraw, USDC | 421,661 | 2,079 | 33 |
| Closing a seat | 213,311 | 918 | 9 |
| Leave, SOL to a public address | 224,694 | 1,044 | 10 |
| Leave, USDC to a Rings private balance | 281,067 | 1,182 | 14 |
Each figure covers everything in the transaction: the proof check, the spend, the protocol's own work, the fees and the deposit.