Concepts

Relayers

A relayer is the account that signs a run as its fee payer and sends it to the network. It stands where your wallet would stand in an ordinary transaction, so the chain records the relayer's address and not yours.

What a relayer does

  1. Names its fee

    Before you prove, the relayer quotes a fee for the run, in the asset the run returns, with a time the quote holds until.

  2. Takes the proven run

    You send it the proven instruction with its accounts. It reads its fee, the hook and the mints from the instruction itself, and checks that the fee is at least what it quoted, that the transaction holds nothing but the Pook instruction, the companions the hook names on chain and the token accounts the run needs, and that its key appears only as fee payer and funder. Then it simulates the transaction.

  3. Pays and submits

    It signs as fee payer, pays the network fee in SOL and sends the transaction. Where the run needs an account created first, such as the stage's wrapped SOL account, the relayer creates it in the same transaction.

  4. Follows it

    It reports the run as accepted, submitted, confirmed or finalized, or as failed or expired with the reason.

What a relayer is paid

The relayer’s fee is part of your proof. The program pays exactly that amount to the relayer out of what the run returns, in the same instruction that deposits the rest to you. A relayer cannot take more, and it is paid only when the run completes.

For a leave, the fee comes off the amount leaving, and it has to be smaller than that amount. A run that returns no asset, such as a repayment, carries no fee, and neither does opening or closing a seat.

Rent the relayer puts up comes back to it. The rent of the stage's wrapped SOL account is refunded inside the run. The rent of a seat's state account, and of the accounts the protocol creates for the seat, returns to the relayer that opened the seat when the seat is closed.

What a relayer sees

A relayer receives what the chain is about to show: the hook, the assets, the amount in, the minimum out and its own fee. It also sees the network address the request came from, as any server does.

It does not receive your wallet address, your keys or your balance. The proofs it carries show that the spender owns the notes without saying who the spender is.

What a relayer cannot do

  • Change the run. The hook, the call, the amounts, the output owner, its fee and the expiry are fixed by the proof. A transaction that differs in any of them fails the proof check.
  • Send the result elsewhere. The output owner is one of the fixed values.
  • Take the input. The amount in moves from your notes to the stage and on to the protocol inside one instruction. It is never in an account the relayer controls.
  • Hold a run open. A proof is valid until its expiry and no later.

A relayer can decline to send a run, or fail to. That costs you nothing: no note is spent until the transaction lands. The same proof can go to another relayer until it expires, and after that you prove again.

Who runs relayers

The relayer is a standalone service. Pook runs one, and the app and the SDK use it unless an app names another with relayerUrl. Anyone can run their own with their own key and their own fee policy: the program accepts any fee payer as the relayer of a run and pays it the fee the proof names.