Settlement program

The settlement program is an Anchor 0.31 program on Solana. It holds offline vaults, redeems vouchers and enforces bonds.

Program idFd2jLRwZreujtCDvaB4ryn4Ca6HBopia2kQf9axw8poo
Sourceprogram/programs/contingency/
IDLprogram/target/idl/contingency.json, after anchor build
Token supportSPL Token. Token-2022 through the token interface, untested

Accounts#

PDAs#

AccountSeeds
Vault"vault", voucher signer, mint
Vault token account"vault_tokens", vault
Double-spend claim"double_spend_claim", vault, voucher digest

Vault#

A zero-copy account of about 5.3 KB. Most of that is the replay window.

FieldTypeNotes
ownerPubkeyWithdrawal authority
voucher_signerPubkeyKey that signs vouchers
mintPubkey
balanceu64Spendable by vouchers
bondu64Covers overspends and double-spends
per_payment_limitu64Immutable
max_balanceu64Immutable
max_voucher_lifetimei64Seconds, at most 30 days
withdraw_delayi64At least max_voucher_lifetime
pending_withdrawal / withdrawal_unlocks_atu64 / i64Current withdrawal request
highest_seq, redeemed_count, total_redeemed, bond_drawnu64Statistics
flagsu81 = overspent, 2 = double-spent (frozen)
seq_ring, digest_ring[u64; 128], [[u8; 32]; 128]Replay window, slot = seq % 128

Instructions#

create_vault#

Creates a vault and posts the bond.

ArgumentType
bond_amountu64, greater than 0
per_payment_limitu64, greater than 0
max_balanceu64, at least per_payment_limit
max_voucher_lifetimei64, from 1 second to 30 days
withdraw_delayi64, from max_voucher_lifetime to 90 days

Accounts: owner (signer, writable), voucher_signer (signer), mint, vault, vault_tokens, owner_tokens, token_program, system_program.

deposit#

deposit(amount: u64, to_bond: bool). Anyone may deposit. When to_bond is false the deposit goes to the balance, which is capped at max_balance. When it's true it tops up the bond.

Accounts: depositor (signer), vault, vault_tokens, mint, depositor_tokens, token_program.

request_withdrawal, cancel_withdrawal, withdraw#

  • request_withdrawal(amount) starts the time lock. The amount must not exceed the balance, and the vault must not be frozen.
  • cancel_withdrawal() clears the request.
  • withdraw() runs after the lock ends and transfers whichever is smaller: the requested amount or the remaining balance.

Accounts: owner (signer) and vault. withdraw also takes vault_tokens, mint, destination and token_program.

redeem_vouchers#

Takes no arguments. It reads vouchers from the ed25519 instruction(s) in the same transaction.

Accounts: relayer (signer), vault, vault_tokens, mint, relayer_tokens (receives tips), the instructions sysvar, and token_program. Then come remaining accounts: one payee token account per voucher, in voucher order.

claim_double_spend#

claim_double_spend(digest: [u8; 32]). For a valid voucher whose sequence number was already redeemed by a different voucher. It pays the payee from the bond and freezes withdrawals.

Accounts: claimant (signer, writable), vault, vault_tokens, mint, payee_tokens, claim, the instructions sysvar, token_program, system_program.

ed25519 instruction requirements#

The program accepts signatures only when all three offsets (signature, public key, message) point into the ed25519 instruction's own data. Entries whose message doesn't start with the voucher prefix are ignored.

Errors#

CodeNameMeaning
6000UnsupportedVersionVoucher version isn't 1
6001WrongVaultVoucher is for a different vault
6002InvalidSignerNot signed by the vault's voucher signer
6003WrongMintMint doesn't match the vault
6004ZeroAmountVoucher amount is zero
6005OverPaymentLimitAbove the per-payment limit
6006TipTooHighTip above 500 bps
6007InvalidSequenceSequence number is 0
6008CreatedInFuturecreated_at more than 10 minutes ahead
6009ExpiredPast expires_at
6010InvalidLifetimeLifetime invalid or above the vault maximum
6011AlreadyRedeemedSame voucher already settled
6012DoubleSpendA different voucher used this sequence number
6013SequenceTooOldOutside the replay window
6014NotDoubleSpentClaim made for a voucher that wasn't double-spent
6015NoVouchersNo vouchers found in ed25519 instructions
6016ExpectedOneVoucherA claim must carry exactly one voucher
6017PayeeAccountMismatchPayee accounts don't match the voucher count
6018BatchNotSortedNot ordered by (created_at, seq)
6019WrongPayeeAccountToken account not owned by the payee
6020SelfPaymentPaying into the vault's own token account
6021MalformedVoucherMessage has the prefix but a bad length or body
6022MalformedEd25519ed25519 instruction data is malformed
6023ExternalEd25519DataOffsets point outside the ed25519 instruction
6024DigestMismatchClaim digest doesn't match the voucher
6025InvalidParamsBad vault parameters
6026ZeroAmountTransferDeposit or withdrawal of zero
6027OverMaxBalanceDeposit above max_balance
6028InsufficientBalanceWithdrawal above the balance
6029VaultFrozenVault frozen after a double-spend
6030NoPendingWithdrawalNothing to withdraw or cancel
6031WithdrawalLockedTime lock still running
6032MathOverflowArithmetic overflow

Events#

EventFields
VaultCreatedvault, owner, voucher_signer, mint, bond
Depositedvault, amount, to_bond, balance, bond
WithdrawalRequestedvault, amount, unlocks_at
Withdrawnvault, amount
VoucherRedeemedvault, seq, payee, amount, paid_from_balance, paid_from_bond, unpaid, relayer_tip, relayer, memo
DoubleSpendClaimedvault, seq, payee, amount, paid_from_bond, unpaid