Payment vouchers

A voucher is a payment instruction signed on the payer's phone. It says: pay this merchant this amount from my vault. It's 227 bytes, small enough to cross a Bluetooth mesh in a few packets, and it can wait in the mesh for days before anyone submits it.

What's in a voucher#

FieldMeaning
versionFormat version. Currently 1.
vaultThe payer's offline vault
payeeThe merchant's wallet
mintThe token being paid, such as USDC
amountAmount in the token's smallest unit
seqSequence number, unique per vault and increasing
created_atWhen the payer signed it (Unix seconds)
expires_atAfter this time it can't be settled
memoOptional 32-byte reference, such as an order number
relayer_tip_bpsTip for whoever settles it, in basis points, up to 5%
signatureed25519 signature over everything above

The exact byte layout is in Voucher format.

Why a message and not a transaction#

Solana transactions need a recent blockhash, which a phone can't get offline. The usual workaround, durable nonces, allows only one pending transaction per nonce account, and Solana's documentation notes the feature may be deprecated.

A voucher avoids both problems. It's a signed message rather than a transaction, so a payer can have many outstanding at once, and they can settle in any order. At settlement, Solana's built-in ed25519 program verifies the signature and the settlement program checks everything else.

Sequence numbers#

Each voucher from a vault carries a unique seq. The settlement program records every sequence number it redeems:

  • The same voucher submitted twice is rejected as a replay.
  • A different voucher with an already-used sequence number is a double-spend. It's rejected, and the merchant who was given it can claim from the payer's bond.

What a merchant can check offline#

Before marking a payment as signed, the merchant's app can verify, with no connection:

  • The signature is valid for the signer the payer presented.
  • The vault address derives from that signer, so it's the signer's own vault.
  • The payee is this merchant, and the token is one they accept.
  • The voucher hasn't expired, wasn't created in the future, and has a valid lifetime.
  • The merchant hasn't already accepted this sequence number.

What it can't check offline is whether the vault still holds enough funds. That gap is what the bond covers.