Voucher format
This is the byte-level specification of a version 1 voucher. Every implementation (TypeScript, Rust, Swift and Kotlin) must produce identical bytes. The test vectors are the reference.
Structure#
struct Voucher {
version: u8,
vault: Pubkey, // payer's offline vault
payee: Pubkey, // merchant wallet
mint: Pubkey, // token being paid
amount: u64, // base units of mint
seq: u64, // unique per vault, starts at 1
created_at: i64, // unix seconds
expires_at: i64, // unix seconds
memo: [u8; 32], // optional reference, zero-padded
relayer_tip_bps: u16, // tip on top of amount, max 500
signature: [u8; 64], // ed25519
}
Encoding#
Vouchers use Borsh: fields in declaration order, integers little-endian, fixed-size arrays with no length prefix. The 163-byte body is every field except the signature.
| Offset | Size | Field | Type |
|---|---|---|---|
| 0 | 1 | version | u8 |
| 1 | 32 | vault | public key |
| 33 | 32 | payee | public key |
| 65 | 32 | mint | public key |
| 97 | 8 | amount | u64 LE |
| 105 | 8 | seq | u64 LE |
| 113 | 8 | created_at | i64 LE |
| 121 | 8 | expires_at | i64 LE |
| 129 | 32 | memo | bytes |
| 161 | 2 | relayer_tip_bps | u16 LE |
| 163 | 64 | signature | bytes |
A full encoded voucher, the bytes sent over the mesh, is 227 bytes: the body followed by the signature.
Signing#
The payer signs a signing message, not the raw body:
signing_message = 0xff || "contingency-voucher" || body (20 + 163 = 183 bytes)
signature = ed25519_sign(voucher_signer, signing_message)
The 20-byte prefix separates domains. A Solana transaction message can never start with 0xff, so a voucher signature can't be replayed as a transaction signature. The prefix also differs from Solana's off-chain message prefix.
ed25519 (RFC 8032) signing is deterministic, so a given key and voucher always produce the same signature.
Digest#
digest = sha256(signing_message)
The settlement program stores the digest for each redeemed sequence number. It's computed over the message rather than the signature, so a different signature encoding can't make a voucher look new.
Validity rules#
A voucher is valid for settlement only if:
version == 1vaultis the vault being redeemed against, andmintmatches that vault's mint- the signature is from the vault's
voucher_signer 0 < amount <= per_payment_limitrelayer_tip_bps <= 500seq >= 1created_at <= now + 600now < expires_at0 < expires_at - created_at <= max_voucher_lifetime, which is at most 30 days
Vault address#
vault = find_program_address(["vault", voucher_signer, mint], program_id)
Because the vault derives from the signer, a merchant can check offline that vault belongs to the key that signed the voucher.