Settlement program
The settlement program is an Anchor 0.31 program on Solana. It holds offline vaults, redeems vouchers and enforces bonds.
| Program id | Fd2jLRwZreujtCDvaB4ryn4Ca6HBopia2kQf9axw8poo |
| Source | program/programs/contingency/ |
| IDL | program/target/idl/contingency.json, after anchor build |
| Token support | SPL Token. Token-2022 through the token interface, untested |
Accounts#
PDAs#
| Account | Seeds |
|---|---|
| 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.
| Field | Type | Notes |
|---|---|---|
owner | Pubkey | Withdrawal authority |
voucher_signer | Pubkey | Key that signs vouchers |
mint | Pubkey | |
balance | u64 | Spendable by vouchers |
bond | u64 | Covers overspends and double-spends |
per_payment_limit | u64 | Immutable |
max_balance | u64 | Immutable |
max_voucher_lifetime | i64 | Seconds, at most 30 days |
withdraw_delay | i64 | At least max_voucher_lifetime |
pending_withdrawal / withdrawal_unlocks_at | u64 / i64 | Current withdrawal request |
highest_seq, redeemed_count, total_redeemed, bond_drawn | u64 | Statistics |
flags | u8 | 1 = 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.
| Argument | Type |
|---|---|
bond_amount | u64, greater than 0 |
per_payment_limit | u64, greater than 0 |
max_balance | u64, at least per_payment_limit |
max_voucher_lifetime | i64, from 1 second to 30 days |
withdraw_delay | i64, 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#
| Code | Name | Meaning |
|---|---|---|
| 6000 | UnsupportedVersion | Voucher version isn't 1 |
| 6001 | WrongVault | Voucher is for a different vault |
| 6002 | InvalidSigner | Not signed by the vault's voucher signer |
| 6003 | WrongMint | Mint doesn't match the vault |
| 6004 | ZeroAmount | Voucher amount is zero |
| 6005 | OverPaymentLimit | Above the per-payment limit |
| 6006 | TipTooHigh | Tip above 500 bps |
| 6007 | InvalidSequence | Sequence number is 0 |
| 6008 | CreatedInFuture | created_at more than 10 minutes ahead |
| 6009 | Expired | Past expires_at |
| 6010 | InvalidLifetime | Lifetime invalid or above the vault maximum |
| 6011 | AlreadyRedeemed | Same voucher already settled |
| 6012 | DoubleSpend | A different voucher used this sequence number |
| 6013 | SequenceTooOld | Outside the replay window |
| 6014 | NotDoubleSpent | Claim made for a voucher that wasn't double-spent |
| 6015 | NoVouchers | No vouchers found in ed25519 instructions |
| 6016 | ExpectedOneVoucher | A claim must carry exactly one voucher |
| 6017 | PayeeAccountMismatch | Payee accounts don't match the voucher count |
| 6018 | BatchNotSorted | Not ordered by (created_at, seq) |
| 6019 | WrongPayeeAccount | Token account not owned by the payee |
| 6020 | SelfPayment | Paying into the vault's own token account |
| 6021 | MalformedVoucher | Message has the prefix but a bad length or body |
| 6022 | MalformedEd25519 | ed25519 instruction data is malformed |
| 6023 | ExternalEd25519Data | Offsets point outside the ed25519 instruction |
| 6024 | DigestMismatch | Claim digest doesn't match the voucher |
| 6025 | InvalidParams | Bad vault parameters |
| 6026 | ZeroAmountTransfer | Deposit or withdrawal of zero |
| 6027 | OverMaxBalance | Deposit above max_balance |
| 6028 | InsufficientBalance | Withdrawal above the balance |
| 6029 | VaultFrozen | Vault frozen after a double-spend |
| 6030 | NoPendingWithdrawal | Nothing to withdraw or cancel |
| 6031 | WithdrawalLocked | Time lock still running |
| 6032 | MathOverflow | Arithmetic overflow |
Events#
| Event | Fields |
|---|---|
VaultCreated | vault, owner, voucher_signer, mint, bond |
Deposited | vault, amount, to_bond, balance, bond |
WithdrawalRequested | vault, amount, unlocks_at |
Withdrawn | vault, amount |
VoucherRedeemed | vault, seq, payee, amount, paid_from_balance, paid_from_bond, unpaid, relayer_tip, relayer, memo |
DoubleSpendClaimed | vault, seq, payee, amount, paid_from_bond, unpaid |