Guides

Run a relayer

A relayer signs runs as their fee payer and submits them. The Pook program pays whichever account did that, so anyone can run one with their own key and their own fees. This guide starts a relayer, sets its fee, and explains what it checks, what it spends and what it earns. Relayers explains the role from the holder's side.

What you need

  • A Solana keypair for the relayer. It is the fee payer of every transaction it submits. Use a key made for this and nothing else.
  • SOL on that key. It pays network fees, and it puts up rent that comes back: the stage's wrapped SOL account inside a run, and about 0.034 SOL for each Kamino seat it opens, returned when the seat closes.
  • A Solana RPC endpoint that accepts version 1 transactions.
  • Node.js and Pook's backend source.

Start it

From the backend folder, install and build once.

Shell
npm install
npm run build

Set the relayer's environment, then start the role.

Shell
CLUSTER=mainnet
POOK_PROGRAM_ID=7qvNkZjiikySgCNbr8jbWbUziVka3Rw1NLwcxwmwwRwd
HELIUS_RPC_URL=<your mainnet RPC endpoint>
RELAYER_SECRET_KEY=<the relayer's secret key>
RELAYER_FEE_SOL=<fee in lamports>
RELAYER_FEE_USDC=<fee in USDC base units>
Shell
node start-service.mjs relayer
VariableTypeMeaning
RELAYER_SECRET_KEYstringThe relayer’s 64-byte secret key, as base58 or as a JSON array of bytes. Keep it in the environment of the process, never in a file you commit.
POOK_PROGRAM_IDaddressThe Pook program.
CLUSTERstringmainnet, devnet or localnet.
HELIUS_RPC_URLURLThe RPC used when CLUSTER is mainnet.
SOLANA_RPC_URLURLThe RPC used on any other cluster, and on mainnet when HELIUS_RPC_URL is not set.
RELAYER_FEE_SOLintegerThe fee when the asset is SOL, JitoSOL, mSOL or kSOL, in 9-decimal base units.
RELAYER_FEE_USDCintegerThe fee when the asset is USDC or kUSDC, in 6-decimal base units.
RELAYER_FEE_MAPJSONA fee for each other mint, as an object from mint address to base units. It is read before the two above.
RELAYER_PORTintegerThe port the relayer listens on.
HOSTstringThe address it binds to.
CORS_ORIGINSlistThe web origins allowed to call it, separated by commas.
DATABASE_URLURLA Postgres database to keep a record of every submission in. Without it the relayer keeps the record in memory.

GET /health answers ready once the key and the program ID are set, with the relayer's address.

Set the fee

The fee is a flat amount for each asset, charged in the asset a run returns, or for a leave in the asset leaving. RELAYER_FEE_MAP sets it mint by mint:

Shell
RELAYER_FEE_MAP={"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v":"<fee>","J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn":"<fee>"}

A mint not in the map falls to RELAYER_FEE_SOL for SOL, JitoSOL, mSOL and kSOL, and to RELAYER_FEE_USDC for USDC and kUSDC. Any other mint needs an entry in the map: a quote or a submission in a mint with no fee is refused with CONFIGURATION_REQUIRED.

Price the fee from what a run costs you: the network fee of a transaction that uses up to 1,400,000 compute units, plus any priority fee you add. Runs lists the measured compute of each launch hook.

The relayer quotes its fee at GET /v1/relayer/quote, and a quote holds for five minutes. The holder's proof fixes the fee, and the program pays exactly that amount to your key inside the run.

What it serves

RouteWhat it does
GET /healthThe relayer's state and address.
GET /v1/relayer/quoteThe fee for one kind of submission and one mint, your address, and when the quote expires.
POST /v1/relayer/runTakes a proven run and submits it.
POST /v1/relayer/leaveTakes a proven leave and submits it.
POST /v1/relayer/seat/openSubmits the opening of a seat.
POST /v1/relayer/seat/closeSubmits the closing of a seat.
GET /v1/relayer/runs/:relayIdThe state of one submission.

The API reference gives each request and response.

Put it in front of holders

An app uses your relayer by giving the SDK its address as relayerUrl. Every /v1/relayer/ request then goes to you: fee quotes, runs, leaves and seat transactions. The registry, hook quotes and the prover still come from the Pook API. List the app's web origin in CORS_ORIGINS so its browser may call you.

TypeScript
const pook = createPook({
  apiUrl: 'https://api.pook.codes',
  relayerUrl: 'https://<your relayer>',
  wasm: await loadCircuits(),
})

What it checks before it signs

Your key signs only what passes all of these. Everything that decides what the key signs is read from the Pook instruction itself: the hook, the hook's companions as stored on chain, the relayer's fee, whether the run has an asset out, and the mints. The other fields of a request are read for display only.

  • The instruction is the Pook instruction the route is for: run, leave, open_seat or close_seat.
  • The relayer's fee in the instruction is at least the fee you quote for its asset.
  • The expiry has not passed.
  • Every other instruction in the transaction is a compute budget instruction, the idempotent creation of a token account, or a companion the hook names on chain.
  • Your key appears only where a relayer belongs: as fee payer of the transaction, of the Pook instruction and of the Rings transfer inside it; as the funder of token accounts for the owners the run needs (the stage, the seat, the author's fee account, the fee recipient, yourself); as the receiver of a SOL fee; and as the opener in close_seat.
  • No account but your own is asked to sign.
  • The hook has no payer slot. A payer slot is accepted only on a launch hook, and no launch hook has one.
  • The setup calls in open_seat are exactly Kamino's seat setup.
  • The whole transaction passes simulation against the chain.

A submission that fails any check is refused with RELAY_REFUSED, and closing a seat that still holds collateral or owes debt with SEAT_NOT_EMPTY, or reported as failed with the program's error when the simulation fails. Nothing is sent and nothing is spent, yours or the holder's.

What it earns and what it spends

InOut
A run that returns an assetYour fee, in that asset, paid inside the runThe network fee, in SOL
A leaveYour fee, taken from the amount leavingThe network fee
A run that returns nothing, such as a repaymentThe network fee
Opening a seatThe network fee, and the seat's rent until it closes
Closing a seatThe rent of the seat, paid to the relayer that opened itThe network fee

Fees arrive in the assets holders run, so a relayer's income is spread over many mints: SOL arrives on the key itself, and a token in the key's token account for that mint. The key pays network fees in SOL, so keep its SOL topped up from what it earns.

Because a failed simulation stops a transaction before it is sent, you pay network fees only for transactions the chain is expected to accept.

What a relayer never holds

The amount in of a run moves from the holder's notes to the stage and on to the protocol inside one instruction. The result is deposited to an owner the proof fixed. At no point is either in an account your key controls. The relayer learns the hook, the assets, the amounts and its own fee, which is what the chain shows.