TypeScript SDK

@contingency/voucher encodes, signs and verifies vouchers, runs a merchant's offline checks, and builds settlement instructions. It uses @solana/web3.js v1 types and @noble/curves for ed25519.

Create and sign a voucher#

import { Keypair, PublicKey } from "@solana/web3.js";
import { createVoucher, findVaultAddress, signVoucher, encodeVoucher } from "@contingency/voucher";

const signer = Keypair.generate(); // the phone's voucher key
const USDC = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"); // devnet USDC
const [vault] = findVaultAddress(signer.publicKey, USDC);

const voucher = signVoucher(
  createVoucher({
    vault,
    payee: merchantWallet,
    mint: USDC,
    amount: 4_500_000n,          // 4.50 USDC
    seq: 1n,
    createdAt: BigInt(Math.floor(Date.now() / 1000)),
    memo: "order-0001",          // up to 32 bytes
    relayerTipBps: 50,           // 0.5%
  }),
  signer.secretKey,
);

const bytes = encodeVoucher(voucher); // 227 bytes to send over the mesh

expiresAt defaults to 30 days after createdAt. All integer fields are bigint.

Check a voucher offline (merchant)#

import { checkVoucherOffline, decodeVoucher } from "@contingency/voucher";

const voucher = decodeVoucher(received);
const errors = checkVoucherOffline(voucher, {
  signer: presentedSigner,         // from the payment handshake
  payee: myWallet,
  acceptedMints: [USDC],
  now: BigInt(Math.floor(Date.now() / 1000)),
  seenSeqs: alreadyAccepted,       // Set<bigint> for this vault
  perPaymentLimit: cachedLimit,    // optional
});

if (errors.length === 0) markAsSigned(voucher);

Possible errors: unsupported_version, bad_signature, vault_not_derived_from_signer, wrong_payee, unaccepted_mint, zero_amount, over_payment_limit, tip_too_high, bad_seq, seq_already_seen, created_in_future, expired and lifetime_too_long.

Settle vouchers (relayer)#

import { Transaction } from "@solana/web3.js";
import { buildRedeemInstructions, decodeVaultAccount } from "@contingency/voucher";
import { getAssociatedTokenAddressSync } from "@solana/spl-token";

const vaultInfo = decodeVaultAccount((await connection.getAccountInfo(vault))!.data);

const ixs = buildRedeemInstructions(vouchers, {
  relayer: relayer.publicKey,
  relayerTokens: getAssociatedTokenAddressSync(USDC, relayer.publicKey),
  voucherSigner: vaultInfo.voucherSigner,
  payeeTokens: (v) => getAssociatedTokenAddressSync(v.mint, v.payee, true),
});

const tx = new Transaction().add(...ixs);
// simulate first: one invalid voucher fails the whole batch

buildRedeemInstructions sorts the batch by (createdAt, seq) and requires that every voucher comes from one vault. Keep batches to one or two vouchers to fit the 1232-byte transaction limit.

Claim a double-spend#

import { buildClaimDoubleSpendInstructions } from "@contingency/voucher";

const ixs = buildClaimDoubleSpendInstructions(rejectedVoucher, {
  claimant: me.publicKey,
  payeeTokens: myTokenAccount,
  voucherSigner: vaultInfo.voucherSigner,
});

Reference#

ExportPurpose
createVoucher, signVoucher, verifyVoucherSignatureBuild, sign and verify
encodeVoucher, decodeVoucher, encodeVoucherBody, decodeVoucherBodyBorsh encoding
voucherSigningMessage, voucherDigestSigned bytes and their sha256
relayerTip, memoBytesHelpers
checkVoucherOfflineMerchant-side checks
findVaultAddress, findVaultTokensAddress, findClaimAddressPDAs
buildRedeemInstructions, buildRedeemVouchersInstruction, buildClaimDoubleSpendInstructionsSettlement
buildEd25519Instruction, buildVoucherVerifyInstructioned25519 precompile instructions
decodeVaultAccountRead a vault account
CONTINGENCY_PROGRAM_ID, SEQ_WINDOW, MAX_RELAYER_TIP_BPS and other constantsProtocol constants