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#
| Field | Meaning |
|---|---|
version | Format version. Currently 1. |
vault | The payer's offline vault |
payee | The merchant's wallet |
mint | The token being paid, such as USDC |
amount | Amount in the token's smallest unit |
seq | Sequence number, unique per vault and increasing |
created_at | When the payer signed it (Unix seconds) |
expires_at | After this time it can't be settled |
memo | Optional 32-byte reference, such as an order number |
relayer_tip_bps | Tip for whoever settles it, in basis points, up to 5% |
signature | ed25519 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.