Voucher format

A voucher is a fixed-layout, little-endian, 202-byte packet with no optional fields. Bytes 0..105 are the message the secure element signs.

The layout

Off	Len	Field	Type	Notes
0	1	`version`	`u8`	`= 1`. Anything else is rejected outright
1	32	`vault`	`Pubkey`	Binds the voucher to one payer
33	8	`seq`	`u64`	Monotonic per vault — the anti-replay handle
41	8	`amount`	`u64`	Token base units, USDC 6 dp
49	8	`remaining_after`	`u64`	Payer’s claimed balance after — lets the merchant sanity-check offline
57	32	`merchant`	`Pubkey`	A voucher is not bearer; it names its payee
89	8	`expires_at`	`i64`	Bounds how long a signed voucher can sit unredeemed
97	8	`salt`	`[u8; 8]`	Per-voucher randomness
105	64	`signature`	`[u8; 64]`	P-256 `r‖s`, low-S, from StrongBox
169	33	`device_pubkey`	`[u8; 33]`	SEC1 compressed — carried so the merchant can verify with no network

Signed message: 105 bytes. Total packet: 202 bytes.

Why 202 is the budget

202 bytes fits an NDEF record for NFC and a QR code at version 10, error-correction level M — 213 bytes of capacity in byte mode, on a 57×57 grid that scans cleanly off a phone screen.

That means the offline path is not hard-blocked on NFC, which matters because the low-cost Android handsets this product targets do not all have usable host card emulation. QR is the transport that cannot fail on hardware you do not control.

Any field added later comes out of that budget. Growing past 213 bytes costs you QR version 10, and the fallback is a denser code that scans worse in a dim shop.

The layout is a contract

The TypeScript in @nelo/voucher and the Rust in programs/nelo_vault must produce byte-identical signed messages, or every signature fails verification. That is not left to careful reading. packages/voucher/vectors/voucher-v1.json is a frozen set of golden vectors:

Generated by the Rust side, because the chain is authoritative.
Asserted by both sides — tests/vectors.rs and test/voucher.test.ts.
TypeScript also verifies signatures that Rust produced, so the check covers the crypto and not only the byte layout.

If the two ever drift, the vectors are where it surfaces — not in the field.

Encoding

import { signedMessage, encode, decode, verify } from "@nelo/voucher";

// The 105 bytes the secure element signs
const message = signedMessage({
  version: 1,
  vault,            // Uint8Array(32)
  seq: 5n,
  amount: 2_000_000n,        // $2.00 at 6 dp
  remainingAfter: 18_000_000n,
  merchant,         // Uint8Array(32)
  expiresAt: 1789000000n,
  salt,             // Uint8Array(8)
});

const signature = await sign("nelo-device", message);   // @nelo/attest, StrongBox
const packet = encode({ ...fields, signature, devicePubkey });   // 202 bytes

Decoding is total — a packet of the wrong length, or carrying an unknown version, is refused rather than partially parsed.

`remaining_after` is a claim, not a fact

This is the field most likely to be misread. remaining_after is what the payer’s device asserts its balance will be once this voucher settles. It exists so a merchant with no network can sanity-check a voucher against the last vault balance they saw cached. The program does not verify it. It cannot — it has no idea what other vouchers are in flight. What the program checks is the real constraint: amount <= vault.balance at redemption, and the replay window.

A payer running a modified device can sign successive sequences that each carry a plausible remaining_after while together exceeding their collateral. The replay window stops the same sequence settling twice; it does not stop different sequences over-spending in aggregate.report_conflict only accepts two vouchers at the same sequence, so that pattern does not trigger the freeze either. This is the exposure the insurance line prices — see the reserve model. Widening the conflict proof to accept an inconsistent-remaining_after pair would shorten the window a compromised device keeps trading in; it is an open design decision, not an oversight.

Low-S, and why it bites

P-256 signatures have two valid forms for every signature: (r, s) and (r, n − s). Android returns whichever it computes. The Solana precompile accepts only the low-S form. The failure is nasty because it is intermittent and silent-looking: roughly half your signatures verify fine on the phone and are rejected on chain with no obvious pattern.

// @nelo/voucher — every signing path must go through this
const raw = derToRawSignature(derFromAndroid);   // DER → r‖s, normalised low-S

Both the normalisation and the failure mode are pinned by tests that run without a handset.

Get started

How it works

Reference

Economics

Operations

Voucher format

The layout

Why 202 is the budget

The layout is a contract

Encoding

`remaining_after` is a claim, not a fact

Low-S, and why it bites

​The layout

​Why 202 is the budget

​The layout is a contract

​Encoding

​remaining_after is a claim, not a fact

​Low-S, and why it bites

The layout

Why 202 is the budget

The layout is a contract

Encoding

`remaining_after` is a claim, not a fact

Low-S, and why it bites