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.

OffsetSizeFieldType
01versionu8
132vaultpublic key
3332payeepublic key
6532mintpublic key
978amountu64 LE
1058sequ64 LE
1138created_ati64 LE
1218expires_ati64 LE
12932memobytes
1612relayer_tip_bpsu16 LE
16364signaturebytes

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 == 1
  • vault is the vault being redeemed against, and mint matches that vault's mint
  • the signature is from the vault's voucher_signer
  • 0 < amount <= per_payment_limit
  • relayer_tip_bps <= 500
  • seq >= 1
  • created_at <= now + 600
  • now < expires_at
  • 0 < 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.