Settlement and relaying

Settlement turns a voucher into an actual transfer. Any device with a connection can do it: the merchant, the payer, or a phone that happened to carry the voucher. Whoever submits it is the relayer and can earn the voucher's tip.

What a settlement transaction contains#

  1. An ed25519 instruction carrying the signed voucher messages. Solana's runtime verifies every signature before the transaction runs. If any signature is invalid, the whole transaction fails.
  2. A redeem_vouchers instruction that reads the vouchers back out of the ed25519 instruction, checks them, and pays out.

Vouchers aren't repeated in the second instruction. That keeps each voucher to about 300 bytes of transaction space, so about two vouchers fit in one transaction.

The rules#

For each voucher, the program checks that:

  • It's version 1, for this vault and this token, and signed by the vault's voucher signer.
  • The amount is above zero and within the vault's per-payment limit.
  • The tip is at most 5%.
  • It hasn't expired, wasn't created more than 10 minutes in the future, and its lifetime is within the vault's limit.
  • Its sequence number hasn't been redeemed and is within the replay window.
  • The payee token account belongs to the voucher's payee.

A batch must come from one vault, ordered by created_at then seq. The batch is all-or-nothing: one bad voucher fails it, so relayers should simulate first and drop failures.

Who gets paid what#

  1. The payee is paid from the vault's balance. If the balance runs out, the bond covers the rest. Anything neither can cover is reported as unpaid.
  2. The relayer tip (amount × tip_bps / 10,000) is paid on top, from the balance only, never from the bond.

Within a batch, vouchers are paid in created_at order, so earlier payments are covered first when funds are short.

Out-of-order settlement#

Vouchers often reach Solana through different relays at different times. The program remembers the last 128 sequence numbers per vault, in any order, so a voucher with seq 3 can settle after one with seq 9.

A voucher is rejected as too old only if a sequence number at least 128 higher has already taken its slot. That's rare in everyday use.