Bonded whitepaper

1. Introduction

Bonded is a Solana program, bonded, and a set of off-chain services that let an AI agent buy metered services on credit and pay for delayed jobs through escrow. Each agent spends from a policy vault whose limits the program enforces. Each operator, the company that runs the agent, posts a USDC bond that a merchant can claim against when the agent's vault cannot pay what the agent signed for. This chapter describes how agents pay today, why that leaves metered merchants unable to bill an agent in arrears, and what Bonded adds. It ends with a map of the paper and the notation used throughout.

1.1 How agents pay today

On stablecoin rails, merchants that sell to agents take payment in advance for each request, which is how x402 works [6][7]. x402 turns the HTTP status code 402 Payment Required into a payment handshake. The client requests a resource. The server answers 402 with its payment requirements: the scheme, the network, the asset, the amount and the recipient. The client builds a payment that meets them and retries the request with the payment attached. The server, usually through a facilitator, verifies and settles the payment, then serves the response. Payment comes first, and each request carries its own payment.

On Solana the exact scheme carries a signed transaction whose payment is a top-level SPL TransferChecked inside a fixed layout of three to six instructions. The facilitator checks that layout, pays the network fee and submits the transaction [7].

Solana carried about 70% of monthly x402 volume in mid-August 2026, in a 30-day window of roughly $24.24M across all chains [8]. In January 2026 the all-chain daily volume was $69k, an average of about $0.07 per payment [9]. Two facilitators, Dexter and PayAI, carried most Solana x402 transactions in early 2026 [10].

A USDC transfer is final. No network reverses it, so a merchant paid in advance carries no payment risk, and the payer carries all of it. Prepayment is how a merchant protects itself from a client it cannot identify, and per-request prepayment is the form x402 standardizes.

The payer's losses come from the agent's own spending. An attacker who reached an operator's dashboard queued transfer prompts that moved 55.5 ETH, about $106k [21]. A probable decimal error on a 4 SOL tip sent 52.4M LOBSTAR [20]. A gifted NFT unlocked a permission tier, and a hidden instruction relayed to the agent moved about 3B DRB, $155k to $174k [19]. In each case a recipient allowlist or a per-transaction cap denominated in USDC would have bounded the loss, and those are checks a program can run before money moves.

1.2 Why metered services bill in arrears

The first merchants Bonded serves sell metered services to agents: inference, data and compute. Their price is a function of what a request consumed, such as tokens generated, rows returned or seconds of GPU time, and that quantity is known only after the work is done. Prepaying each request forces the merchant either to charge a flat price per call or to take a maximum up front and refund the difference. It also means one on-chain transfer per call, each with its own signature fee [27] and facilitator round trip.

A merchant that bills in arrears serves first, meters what was used, and settles a batch of usage in one transfer. There are signs of demand for this on agent rails: Cloudflare proposed a deferred x402 scheme for batch settlement [13], and a Dexter-linked author published a Solana payment-channel draft [35].

Billing in arrears means extending credit to the client until settlement. A human customer comes with an identity, a contract and a card network's dispute rules. An agent comes with a key. When a merchant serves an agent on credit it holds a promise, and when it comes to collect, the agent's wallet may be empty, its key may have been replaced, and the operator behind it may be a name the merchant cannot reach. A message signed by the agent's key proves the amount owed, but on its own it gives the merchant no funds to collect from.

To bill an agent in arrears, a merchant needs the following before it serves:

1. Proof of the amount owed that it can present without the agent's cooperation. A signature by the agent's key over a running total serves, because the merchant can submit it alone.
2. A ceiling on its exposure, fixed in advance, so that it knows the most it can lose before it extends any credit.
3. Collateral it can reach under rules that do not depend on the operator's cooperation, sized and visible before the credit is extended.

The operator needs the converse: the agent's key must not be able to commit the operator to unbounded spending, whether through a stolen key, an injected instruction or an arithmetic slip.

1.3 What Bonded is

Bonded is one Anchor program plus the services around it. Two kinds of account carry the design.

The policy vault (Vault) holds the USDC of one agent. It is a program-derived account whose associated token account holds the funds, so only the program can move them. The agent holds a session key, and the operator holds the admin key. The vault's policy sets a float cap, a spending window and its budget, an optional co-signer with a co-sign threshold, and a guardian that can freeze the vault. Per-merchant rules (MerchantRule) add a per-transaction cap, a per-merchant window budget and a quote requirement. USDC on Solana is a classic SPL Token mint, so Token-2022 transfer hooks are not available for it [32]; every check lives in the program that owns the vault.

The bond (Bond) holds USDC the operator posts. Against it the operator opens credit lines (CreditLine) for merchants it chooses. Each line has a limit, the sum of open limits is the bond's reserved_lines, and the bond's balance divided by that sum is its coverage ratio. Coverage is public, and the program refuses any line, limit increase or withdrawal that would take it below the operator's minimum, which is at least 3,300 bps (33%). The bond is slashable. When a merchant settles a voucher and the vault cannot pay, the program opens a default event. Every line holder may file its latest voucher within 72 hours, and the bond then pays each claim in full, or pro rata when the claims exceed the bond.

Agents pay through three lanes, each protected by a different fact:

• Float. Open-world x402 exact calls. Because the exact scheme requires a top-level transfer [7] and a program-owned vault can only sign through the program, the vault delegates a bounded SPL allowance, at most the float cap, to the session key, which signs the transfer as delegate. refill_float restores the allowance and books what was spent against the window budget. The loss bound is the allowance outstanding.
• Tab. Metered services billed in arrears. The operator opens a line for a merchant. With each request the agent signs a 96-byte voucher carrying the cumulative amount owed, and the merchant verifies it locally. Later the merchant calls settle_tab with the latest voucher and the vault pays the difference since the last settlement. If the vault is short, the bond pays.
• Escrow. Jobs with delayed delivery. The agent funds an escrow with pay_escrow against a merchant-signed quote that names the amount, a specification hash, a delivery deadline and an optional arbiter. The merchant marks delivery at or before the deadline; the payer accepts, or a 48-hour dispute window lapses and the funds release. Without a delivery mark by the deadline, anyone can call refund_on_timeout.

The program stands behind two obligations, because each rests on a fact it can check without judgment: a voucher the agent's key signed, and the absence of a delivery mark by a deadline. Every other spending decision stays inside the policy, which bounds it in USDC base units before the money moves.

Example. An operator posts 1,000 USDC to its bond and opens a 250 USDC line for an inference merchant. Reserved lines are 250 USDC and coverage is 40,000 bps (400%). Before serving a single request, the merchant knows it can be owed at most 250 USDC beyond what has settled, and that a 1,000 USDC bond stands behind that amount, shared with any other line the operator opens. If the operator opens three more 250 USDC lines, coverage falls to 10,000 bps. With a minimum of 10,000 bps, the program refuses a fifth.

Bonded's token is $BONDED, with a fixed supply of 1,000,000,000, all of it issued in one public launch on equal terms; every fee the protocol keeps is for buying $BONDED on the market and burning it (§10.7). Bonds, payments and claims stay in USDC. The two fees are paid in USDC: a tab settlement fee in basis points of each settled amount, deducted from what the merchant receives, and an escrow fee reserved on top of the job's principal and earned only when the escrow releases to the merchant. The devnet parameter file sets them at 10 bps, waived, and 25 bps.

1.4 What this paper covers

1.5 Notation

The paper uses the program's own units, encodings and names.

2. System overview

This chapter describes the whole system before later chapters take each part apart: the keys and what each one can do, the three lanes an agent pays through, the accounts the program keeps and how they relate, the life of a tab from setup to payout, and where each component runs.

2.1 Actors and keys

Bonded divides authority by key. Each key can do a short, enumerable list of things, and every instruction checks its signer against the key stored in the account it touches. A key that leaks exposes only its own list. Table 2.1 gives each actor, the key it holds, and the instructions that key can sign.

Operator

The operator is the company running the agent. Its admin key creates the Operator account at [b"operator", admin], and the same instruction, create_operator, creates the operator's one Bond at [b"bond", operator] with its USDC token account and the operator's minimum_coverage_bps, which must be at least 3,300. The admin key is any Solana signer; the program checks only its signature, so a multisig that signs as one address can hold it.

Every admin power that could let an operator leave ahead of its obligations is delayed. A line decrease takes effect 72 hours after it is scheduled (DECREASE_DELAY = 259,200 s). A guardian replacement takes effect after the same 72 hours. A bond withdrawal unlocks only after the longest line expiry, plus the 72-hour claim window, plus a configured margin. The operator's tabs_settled, defaults_count and created_at fields are public, and anyone can read them.

Agent

The agent holds one key, the session key. It is the only key in the agent's runtime, and the policy bounds everything it can do: the float allowance, the window budget, the merchant rules and the co-sign threshold. When the operator opens a line, the program copies the vault's current session key into the line's voucher_session_key; that key signs the line's vouchers until a delayed rotate_line_key replaces it. The session key cannot change policy, open lines, withdraw funds or unfreeze a vault.

Co-signer

The co-signer is a human key that approves large payments. policy.cosigner is either zero (no co-signer), an Ed25519 public key, or the address of a PasskeyCredential that holds a P-256 passkey. When a program payment exceeds cosign_threshold, pay and pay_escrow require an unused, unexpired Approval that binds the exact payment intent, merchant and amount to the vault's current policy revision. The approval is created in its own transaction, so a WebAuthn assertion, which carries authenticator data and client JSON, never has to share a transaction with a merchant quote and the payment.

Merchant

The merchant holds its own key and signs only for its own lines and jobs. Opening a line does not need the merchant's signature, because the line commits only the operator. A merchant decides whether to extend credit by reading the line, the bond and its coverage, and the operator's counters, all of which are public account state.

Guardian

A guardian can freeze a vault and do nothing else. Freezing revokes the float delegate, stops every payment from the vault and records a FreezeCheckpoint whose freeze time cannot change; it moves no funds, and only the admin can unfreeze. Each vault answers to two guardians: the operator-level Operator.guardian and the vault-level policy.guardian. The admin replaces either through rotate_operator_guardian or rotate_vault_guardian with 72 hours' notice, and set_policy cannot change a guardian directly. The operator can pre-fund the vault's freeze-reserve account so that the checkpoint's rent comes from the reserve rather than from the guardian.

Keeper

The keeper is anyone. Every keeper instruction has an outcome fixed by account state and the clock, such as a payout computed from a default's snapshot or a refund that falls due after a deadline. The signer's identity changes nothing, so any party can run the cranks and any other party can replace it.

Arbiter

An arbiter exists only for an escrow job whose quote names one. The quote's arbiter field is zero when there is none, and the program refuses a quote that names its own merchant. The arbiter can act only on a disputed job and only before resolve_until; after that deadline anyone can refund the job.

Protocol authority

The protocol authority is the program's loader-v3 upgrade authority. initialize_protocol and every governed update check that the program's ProgramData names the signer as its upgrade authority. Fee rates are bounded by maxima that are fixed once set: the tab fee maximum at initialization and the escrow fee maximum at its first configuration. No instruction gives this key access to vault, bond or escrow balances, or to the fee treasury: the fees leave only through the crank's buyback, which burns the $BONDED it buys (§10.7).

2.2 The three lanes

An agent pays through three lanes. Each lane exists because a different kind of payment rests on a different checkable fact, and the lane determines which account pays the merchant and what bounds the operator's loss.

Float

The Solana exact scheme verifies a top-level TransferChecked [7]. A vault is a program-derived address, and a PDA signs only through a cross-program invocation from its program, which produces an inner instruction rather than a top-level one. The float resolves this: the vault grants the session key an SPL delegate allowance, and the session key signs the top-level transfer as the delegate. The Bonded program is not part of that transaction, so merchant rules cannot gate it; the allowance itself is the bound.

refill_float is permissionless. It reads the token account's real delegated_amount, books what the session key consumed since the last approval into the window, and approves a new allowance.

The window is anchored at window_started_at and advances in whole periods of window_seconds. Because a refill books consumption exactly once and never approves more than the budget left in the current window, booked float spending never exceeds window_budget in a window, and the session key never holds an allowance above float_cap, however often anyone refills.

Tab

On a tab the merchant extends credit. With each request the agent signs a voucher that carries the cumulative amount owed on the line, and each voucher replaces the previous one; settlement needs only the latest. settle_tab requires the Ed25519 verification instruction immediately before it, checks the voucher's domain tag, line address, signer, nonce, cumulative amount and expiry, and pays the difference between the voucher's cumulative amount and the line's settled floor. That difference may not exceed the line's limit. When the vault holds less than the difference, settle_tab transfers nothing and opens a default event instead, and the bond pays the merchants' claims after the claim window.

Escrow

On an escrow job the protecting fact is time. The merchant signs a quote naming deliver_by; the agent funds the escrow with principal plus fee; the merchant must call mark_delivered at or before deliver_by. Without that mark, refund_on_timeout returns everything to the vault after the deadline. With it, a 48-hour dispute window opens (DISPUTE_WINDOW_SECONDS = 172,800 s), after which the funds release to the merchant. Within the window the payer may dispute, but only when the quote named an arbiter; the arbiter then releases or refunds before the job's resolution deadline, and after that deadline anyone can refund it.

Program payments

Beside the three lanes, pay sends USDC from the vault to an allowlisted merchant through the program, final at once. It runs the same checks as escrow funding: the merchant's MerchantRule, its per-transaction cap and window budget, the vault's window budget, an optional or required quote, and an approval above the co-sign threshold. The outstanding float allowance counts against the vault's window budget before any program payment, so the float and program payments together never exceed window_budget in one window.

2.3 Accounts at a glance

All Bonded state lives in program-derived accounts of one program. Each account's address is derived from fixed seeds, so any party can compute where an account must be and the program can reject a substitute. Every program account starts with an 8-byte discriminator and a 1-byte bump.

The vault, the bond and each escrow hold their USDC in classic SPL associated token accounts whose authority is the PDA itself. The protocol's mint must have 6 decimals, and every token account must belong to the classic SPL Token program; Token-2022 accounts are refused.

The cardinalities follow from the seeds. One admin key has one Operator, and one operator has one Bond. An operator has any number of vaults, one per 32-byte agent_id (the TypeScript builder uses the SHA-256 of a UTF-8 agent ID). A bond backs any number of lines, at most one per merchant, and each line names the single vault whose USDC pays its tab. Merchant rules gate program payments and escrow from a vault; they do not gate tabs, which a line governs. A bond has at most one active default at a time, recorded in active_default_sequence, and each default holds at most one claim per merchant.

2.4 The life of a tab

A tab runs in four stages: the operator sets up, the agent buys on credit, the merchant settles, and, if the vault is short, the bond pays the line holders' claims.

Setup

1. create_operator(guardian, minimum_coverage_bps) creates the Operator, the Bond and the bond's token account. It refuses a minimum below 3,300 bps.
2. create_vault(agent_id, policy) creates the vault and its token account. The policy must name a non-zero session key, a positive window_seconds, and a float_cap no greater than window_budget.
3. The operator funds the vault with an ordinary SPL TransferChecked from its own USDC account into the vault's token account. The API prepares it as the fund_vault action; no program instruction is involved.
4. post_bond(amount) moves the operator's USDC into the bond. The program refuses a bond balance above 25,000,000,000 base units (25,000 USDC) and a protocol-wide total above 250,000,000,000 base units (250,000 USDC) (BOND_CAP, TOTAL_CAP).
5. open_line(limit, expires_at) opens a line for one merchant. The vault must not be frozen and the bond must have no active default. The program adds limit to reserved_lines and checks coverage against the collateral not already promised to a pending withdrawal. It records the line's tab fee, which is zero when the protocol waives fees, and copies the vault's session key as the line's voucher key.

Service

Before serving, the merchant reads the line and the bond: the limit, expiry, voucher key, settled and retired cumulative amounts, maximum nonce, the vault's freeze state. Its middleware caches the line and re-reads it when an outstanding increment reaches a configured threshold; whether the bond's coverage is enough to serve on credit is the merchant's own call, read from the public bond.

On a request, the merchant middleware answers 402 with exactly one bonded-tab offer, in the JSON body and in a base64 Payment-Required header. The offer names the line, the request key, a request digest, the metered units, and the next voucher's cumulative amount, nonce, expiry and usage digest. The usage digest commits to the request's method, URL, body, request key, charge and units. The agent SDK checks the URL, method, network, mint, merchant, digests, counters and its maximum charge, signs the 96-byte voucher with the session key, and retries the same request with a Payment-Signature header. The merchant verifies the Ed25519 signature and checks that the cumulative amount and nonce advance its stored latest voucher and that the unsettled amount stays within the limit. It then serves and stores the response so that a retry with the same key is replayed and not billed twice.

Settlement

The merchant's worker settles one line per legacy transaction: an Ed25519 verification instruction whose data is exactly 208 bytes, followed immediately by settle_tab(default_sequence, ed25519_ix_index). In the local benchmark, a bare single-voucher transaction measures 894 bytes and 61,044 compute units. The program finds the proof through the instructions sysvar and checks its header, signer and message byte for byte. It requires the voucher's nonce to exceed the line's maximum_nonce, its cumulative amount to exceed the line's settled floor, and its expiry to lie in the future and no later than the line's expiry. It then pays.

The line's settled_cumulative and maximum_nonce advance to the voucher's values, and the operator's tabs_settled counter increments.

Default, claims and payout

If the vault's token account holds less than delta, settle_tab transfers nothing. It opens the DefaultEvent at [b"default", bond, default_sequence], where default_sequence is the bond's previous sequence plus one, sets window_end to the opening time plus 259,200 s (CLAIM_WINDOW), clears any pending bond withdrawal, and increments the operator's defaults_count. A frozen vault opens a default the same way once its frozen time in the current freeze episode reaches the configured freeze grace, which is at least 345,600 s (96 h).

While the window is open, each merchant whose line was opened or renewed since the bond's previous default files its latest voucher with file_claim, strictly before window_end. A merchant may refile a voucher with both a higher nonce and a higher cumulative amount, which replaces its earlier claim. At or after window_end, anyone calls execute_default_payout once per claim. The first call snapshots the bond's balance as the pool and the claims total as the denominator, so the order in which claims are paid does not change any amount. Each claim receives its eligible amount, or its floored pro-rata share when the claims exceed the pool, and closes. Its line's retired_cumulative and maximum_nonce advance to the claimed voucher's cumulative amount and nonce, so the same debt cannot be paid twice. The last payout clears the bond's active default. Only the bond pays; whatever the vault still holds stays in the vault.

Example. An operator posts 1,000 USDC and opens two lines with limits of 250 USDC each, one for an inference merchant A and one for a data merchant B. Coverage is ⌊1,000 × 10,000 ÷ 500⌋ = 20,000 bps. The vault holds 300 USDC.

• A settles a voucher of 180 USDC cumulative. The delta is 180 USDC, the vault pays it, and 120 USDC remains. With the fee waived, A receives all of it; at 10 bps, A would receive 179.82 USDC and the fee treasury 0.18 USDC.
• A's vouchers reach 400 USDC cumulative, a delta of 220 USDC, within the 250 USDC limit. The vault holds 120 USDC, so settle_tab opens a default.
• A files 400 USDC: eligible = min(400 − 180, 250) = 220 USDC. B, which never settled, files 240 USDC: eligible = min(240 − 0, 250) = 240 USDC. Claims total 460 USDC, below the 1,000 USDC pool, so after the window both are paid in full and the bond falls to 540 USDC.
• Had the bond held 400 USDC (8,000 bps coverage, allowed under a 3,300 bps minimum), the pool would be 400,000,000 base units against 460,000,000 eligible. A would receive ⌊400,000,000 × 220,000,000 ÷ 460,000,000⌋ = 191,304,347 base units and B ⌊400,000,000 × 240,000,000 ÷ 460,000,000⌋ = 208,695,652. The remaining 1 base unit stays in the bond.

2.5 Where each piece runs

Bonded's on-chain part is one program. Everything else is off-chain software that prepares, signs, watches or cranks transactions, and each piece runs with the party whose key it uses.

The API prepares and the wallet signs. A prepared transaction contains unsigned legacy bytes, their hash, the blockhash, the signer roles and the result of simulating it. The holder of the right key signs exactly those bytes, and the API checks the canonical bytes, the message, the fee payer, every signature and the expiry before it broadcasts. The SDK does not trust the API's description of a transaction: it decodes the message, rebuilds each permitted instruction from its own inputs and its own RPC reads, and compares every account, privilege, byte and program ID before it signs.

Chain state is the source of truth for every service. The indexer commits projections, events and its cursor atomically, reprocesses idempotently, and reconciles projected accounts against the chain. The keeper judges deadlines by the indexed chain time, and the guardian evaluates only committed payment projections. The merchant's evidence, its stored vouchers and metered usage, stays in the merchant's own database. The chain shows settled amounts, and an unsettled voucher becomes public only when its merchant settles, files or attests it.

3. Policy vaults

The vault is the agent's account. It holds the USDC the agent spends and the policy that decides which of the agent's payments execute. The agent does not own those funds. It holds a session key, and the session key reaches the vault's USDC in three ways only: by signing pay or pay_escrow, which the program checks against the policy before it moves anything; by spending the float, a capped SPL Token allowance described in §4; and by signing vouchers on credit lines the admin opened, which merchants settle against the vault up to each line's limit (§5). Changing the policy, allowing a merchant, rotating a key and withdrawing all take the operator's admin key. The guardian key can freeze the vault and do nothing else.

The policy lives in the program because nothing else on the payment path can enforce it. USDC on Solana is a classic SPL Token mint, so Token-2022 transfer hooks are not available for it [32]. The only place a rule can run on every program payment is inside the program that owns the token account.

3.1 The vault account and its policy

Address and token account

A vault is a program-derived account at [b"vault", operator, agent_id]. operator is the address of the operator's Operator account, itself at [b"operator", admin], and agent_id is a 32-byte seed; the TypeScript builder derives it as the SHA-256 of a UTF-8 agent ID. One admin key owns one Operator and any number of vaults, one per agent. The admin may be a Squads smart-account PDA, so an operator's existing multisig controls every vault it runs.

Each vault owns one token account: the classic SPL associated token account of the vault PDA for the protocol's USDC mint, ProtocolConfig.usdc_mint, which must have 6 decimals. Token-2022 accounts are refused. The owner of that token account is the vault PDA. A PDA has no private key, so the only signer that can act as owner of the vault's USDC is the program itself, and it signs only inside its own instructions, after their checks pass. Every outflow from the vault is therefore either a program transfer (pay, pay_escrow, settle_tab, withdraw) or a transfer by the SPL delegate the program installed, which is the float.

Fields

The vault's fields, in Borsh order:

The policy is one embedded struct, PolicyArgs. The same struct is the argument of create_vault and of set_policy, so a policy is always written whole.

The policy separates the keys by what each may authorize. The session key acts on every payment but cannot change any limit. The co-signer adds a second signature above a threshold but cannot start a payment. The guardian stops payments but cannot start them or move funds. Only the admin changes limits, and two of its changes are themselves constrained: a guardian change waits 72 hours, and every policy change voids outstanding approvals (§3.2).

The account is allocated at its largest encoding, 8 + 343 = 351 bytes. Borsh writes an Option compactly: when pending_guardian is None it takes one byte, and the three episode fields that follow it start 40 bytes earlier than when it is Some (a 32-byte key and an 8-byte time). The figure therefore stops at the option tag.

The vault's satellite accounts

A vault works with a small set of accounts derived from its own address. Rent is the rent-exempt minimum, (size + 128) × 3,480 × 2 lamports [28], and is returned when an account closes: to its rent payer, or for a checkpoint to the freeze reserve.

PaymentReceipt and QuoteReceipt are what make each payment intent and each merchant quote usable once. They outlive the approval and escrow accounts that refer to them, so a closed account can never be replayed into existence.

3.2 Creating a vault and setting policy

create_vault

create_vault(agent_id, policy) is signed by the admin, who pays rent. Its accounts are the admin (writable signer), the Operator at [b"operator", admin] with has_one = admin, ProtocolConfig, the USDC mint (it must equal protocol.usdc_mint), the new vault, and the vault's associated token account, created when absent; a correctly precreated ATA is accepted. The handler validates the policy:

A failed condition returns InvalidConfiguration. The third condition is what keeps the window invariant of §3.3: the float allowance is reserved against the window budget, and an allowance larger than the budget could never be fully reserved.

On success the vault has window_started_at = now, window_spent = 0, last_approved = 0, policy_revision = 0 and no delegate. The session key receives its first allowance at the first refill_float. The program emits CoreEvent kind 2.

Funding needs no Bonded instruction: the operator sends USDC to the vault's token account with an ordinary SPL TransferChecked, which the API's fund_vault builder prepares and the indexer records as vault_funded.

set_policy

set_policy(policy) replaces the whole policy. The admin signs. The accounts are the admin, the Operator, the vault, the vault's token account, the token program and ProtocolConfig. The handler runs in this order:

1. Validate the new policy as for create_vault.
2. Require policy.guardian to equal the current guardian, otherwise GuardianRotationRequired.
3. Reconcile the window under the old policy (§3.3), booking float the session key has already spent.
4. Revoke the SPL delegate on the vault's token account and set last_approved = 0.
5. Increment policy_revision.
6. Install the new policy and emit CoreEvent kind 3.

Each step has its reason. Reconciliation comes before revocation so the window books exactly the float that was consumed; after Revoke the token account reports a delegated_amount of zero, and the unspent rest of the allowance lapses instead of being counted. The revocation exists because the outstanding allowance was granted under the old float_cap and possibly the old session key; the new policy starts with no delegate until a refill computes one from the new values. The revision bump voids every outstanding approval, because each approval signs the revision it was issued under (§3.5): a co-signer who approved a payment under one threshold, one session key and one budget has not approved it under another. The guardian is excluded because it is a commitment to whoever monitors the vault. Changing it goes through rotate_vault_guardian and its 72-hour notice (§3.7), and set_policy cannot shorten that.

set_policy keeps window_started_at and window_spent as reconciled. A new window_seconds takes effect at the next reconciliation, which counts whole periods of the new length from the stored start. A lower window_budget applies at once: if the current window has already booked more than the new budget, every payment and refill in that window returns WindowBudgetExceeded until the window rolls. set_policy has no frozen check, so an admin can tighten a frozen vault's policy before unfreezing it.

Who signs what

Every instruction that acts on a vault, its signer, and the CoreEvent kind it emits (the event codec the indexer reads, §9):

3.3 Window accounting

The window

Session-key spending (the float, pay and pay_escrow) is counted against one budget per window. The window is fixed and anchored: its boundaries sit at the vault's creation time plus whole multiples of window_seconds, and traffic never moves them. A sliding window would need the history of recent payments in the account; the anchored window needs two fields, window_started_at and window_spent, and constant compute per payment. Tab settlement does not draw on the window. A merchant decides when to call settle_tab, and tab exposure is bounded per line by its limit instead (§5, §6).

The program cannot see a float payment when it happens, because a delegate transfer is an SPL Token instruction that never invokes Bonded. It sees the payment afterwards, as the drop in the token account's delegated_amount since the allowance was set. last_approved holds the allowance as of the last observation, and the difference is what the session key has spent since.

Reconciliation

reconcile_window runs first in every instruction that books spending or touches the delegate: pay, pay_escrow, refill_float, set_policy, rotate_session_key, withdraw and freeze.

It requires now ≥ window_started_at, window_seconds > 0 and delegated_amount ≤ last_approved, and returns InvalidConfiguration otherwise. The last condition holds by construction: only the vault PDA can Approve on its token account, so between two reconciliations delegated_amount can only fall.

Two details are deliberate. The rollover happens before the booking, so float spent before a boundary but observed after it is charged to the new window. The program cannot date an SPL transfer, and charging it late means no window ever books less than it spent. And the window advances by whole periods from the stored start, so a vault idle for three windows moves its start forward three windows in one step, and its boundaries stay where creation put them.

Booking a payment

After reconciliation, book_spend tests the payment against the merchant's rule and the vault's budget. The full order of checks is in §3.4; the budget arithmetic is:

The vault-level test includes delegated_amount. Outstanding float reserves its share of the budget before any program payment, because the session key can spend it at any moment without asking the program; a program payment that ignored it could be followed by a float spend that pushed the window past its budget.

A merchant rule's counter shares the vault's window and resets lazily. When the rule's saved window_started_at differs from the vault's after reconciliation, the program copies the vault's start into the rule and zeroes rule.window_spent before the test. Readers render a rule counter from a stale window as zero.

Refunds never rewind either counter. An escrow refund returns USDC to the vault, but the window keeps the debit it booked: a refund is not a reason for the session key to spend again in the same window.

The window invariant

With the refill rule allowance = min(float_cap, window_budget − window_spent) (§4.4), every instruction leaves the vault inside these bounds for as long as its policy is unchanged:

A refill sets last_approved to at most the unspent budget. A payment books only when window_spent + amount + delegated_amount fits. A rollover zeroes window_spent and then books at most last_approved, which is at most float_cap and so at most window_budget.

The invariant gives the bound the window exists for. Under one policy, the USDC that leaves the vault through the float, pay and pay_escrow during any single window is at most window_budget. Every unit that leaves during the window is either booked in that window's window_spent, or is float spent after the window's last reconciliation, and the invariant already counts that in last_approved.

The shared domain model

@bonded/contract carries the same accounting as pure functions. initializeWindowState(policy, at, initialFloatAllowance) starts a window at at with no spending and an allowance no larger than floatCap (zero for a frozen policy). evaluateWindow applies one event, float_spend, refill_float or pay; a float_spend is checked only against the remaining allowance, as the SPL Token program checks it. replayWindowAccounting folds a chronological list of events and keeps the previous state whenever an event is refused, as a failed transaction leaves the chain unchanged. Vectors generated from these functions run against the compiled program, which must reproduce the same counters and remaining delegation.

One day of payments

Example. A vault has float_cap = 20,000,000 (20 USDC), window_seconds = 86,400 s (24 h), window_budget = 200,000,000 (200 USDC), an Ed25519 co-signer and cosign_threshold = 100,000,000 (100 USDC). Its window starts at 00:00. Two merchants have rules: an inference API, M1 (per_transaction_cap 50 USDC, window_budget 120 USDC, no quote required), and a GPU seller, M2 (cap 150 USDC, budget 150 USDC, quote required). The table gives amounts in USDC; the program holds base units.

On the first day the vault paid 40 USDC on the float and 160 USDC through pay, exactly its 200 USDC budget. The first window booked 198 of it; the last 2 USDC, observed after midnight, is charged to the second window. The refused payment at 11:30 shows the transaction rule: its reconciliation would have booked 10.50 USDC, but the refusal rolled the whole instruction back, and the next successful instruction booked it instead.

3.4 Merchant rules and the checks in pay

The rule

A MerchantRule is one allowlist entry with its own limits:

set_merchant_rule(per_transaction_cap, window_budget, quote_required) is signed by the admin, who pays rent the first time. The rule lives at [b"rule", vault, merchant] and is created when absent; at creation it records the vault, the merchant and the vault's current window_started_at. Every call overwrites the three limits and leaves window_spent alone, so a budget lowered mid-window applies against what the merchant has already received in it. The call emits CoreEvent kind 21 carrying the cap.

The rules are the vault's allowlist for program payments. A rule is never deleted. Setting per_transaction_cap to zero refuses every payment to that merchant, since every payment must be positive. The rules govern pay and pay_escrow; they cannot govern the float, where the session key is the top-level authority of an SPL transfer to any address. That lane is bounded by its allowance instead (§4.6).

The quote requirement is for merchants whose prices should bind the agent. With quote_required set, the agent does not choose the amount: the merchant signs a 169-byte quote naming the vault, the merchant, the amount, an expiry and a nonce (layout in §8), and pay accepts that amount once. Together with the per-transaction cap in base units, this is the guard against amount and decimal errors: the agent pays what the merchant priced, below a ceiling the admin set.

The order of checks

pay(amount, nonce, quote_hash, intent_hash, quote_ix_index) is signed by the session key. A separate payer signer pays the rent of the receipts and may be a relayer. Anchor's account constraints run first, then the handler. The first failing check decides the error, and because a Solana transaction is atomic, a refusal leaves every account as it was, reconciliation included.

Each step, its condition and its refusal:

After the last check the program commits both counters, transfers amount with a CPI TransferChecked (6 decimals) from the vault's token account to the merchant's, signed by the vault PDA, writes the PaymentReceipt (lane 0, outcome 1, merchant paid), emits PaymentCommitted and CoreEvent kind 23, and closes a consumed approval to its original rent payer.

The order follows meaning. Identity and replay come first, so a payment that could never be valid fails before any state is read. The merchant's own limits come before the vault's. The co-signer check comes last, so an approval is consumed only by a payment every other rule already accepts: in the example of §3.3 the 14:00 payment fails on the vault budget and its approval remains usable.

In pay the merchant is read from the rule account itself, so the allowlist is enforced by the rule's existence and by the destination-owner constraint, and the MerchantNotAllowed comparison holds trivially. It does its work in pay_escrow, where the merchant comes from the quote. pay_escrow calls the same book_spend with the quote mandatory and amount equal to principal plus the escrow fee, so caps, budgets and approvals bind the full debit (§8).

3.5 Approvals and the co-signer

The threshold

With a co-signer in the policy, every program payment whose debit is strictly above cosign_threshold needs an Approval. With cosigner zero the threshold is ignored. The co-signer is a key a person holds, Ed25519 or a passkey, and it adds a second decision above the amount where the operator wants one. It cannot start a payment. It approves one exact payment, which the session key then submits.

The payment intent

What the co-signer approves is a payment intent: the SHA-256 of 121 bytes naming the vault, the merchant, the debit, a nonce, the quote and the lane. pay recomputes it from its own arguments and accounts and refuses a mismatch with ApprovalMismatch, so an intent cannot be attached to a different payment. The intent hash is also the seed of the payment's Approval and of its permanent PaymentReceipt.

The domain tag binds the intent to one program on one cluster (§1.5). For an unquoted payment the agent picks the nonce; distinct nonces make distinct intents and distinct receipts, so two equal payments to one merchant remain two payments.

The approval message

The co-signer signs 128 bytes:

policy_revision binds the approval to the policy in force when it was signed. expiry is the co-signer's choice and must lie in the future when the approval is recorded.

Ed25519 co-signer: approve_payment

approve_payment(intent_hash, merchant, amount, expiry, ed25519_ix_index, policy_revision) records an approval from an Ed25519 co-signer. The co-signer does not sign the transaction. Its signature travels in a native Ed25519 precompile instruction placed immediately before the Bonded instruction; any payer submits the transaction and pays the approval's rent. The handler checks, in order:

1. No PaymentReceipt exists at [b"payment", vault, intent_hash], otherwise PaymentReplay. A committed payment can never be approved again.
2. policy_revision equals the vault's, otherwise ApprovalPolicyChanged.
3. amount > 0 and now < expiry ≤ i64::MAX, otherwise InvalidAmount.
4. The proof is the instruction at index current − 1, the current instruction is a top-level Bonded instruction, and the proof's data is exactly 240 bytes with the header [1,0,48,0,255,255,16,0,255,255,112,0,128,0,255,255]: one signature, public key at offset 16, signature at 48, a 128-byte message at 112, all inside the same instruction. Otherwise InvalidPrecompile.
5. The policy has a co-signer, the proof's key equals it, and the signed message equals the approval message rebuilt from the arguments. Otherwise ApprovalMismatch.

The approval is created at [b"approval", vault, intent_hash] with used = false, the payer as rent_payer and the signed revision; ApprovalCreated and CoreEvent kind 22 record it. Solana's precompile verifies the signature; the program verifies that the verified bytes are the ones it expects, from the key it expects, with no foreign offsets, extra signatures or wrapping program.

Passkey co-signer

A passkey lets a person approve with a phone or laptop authenticator through WebAuthn. Solana's native secp256r1 precompile verifies the P-256 signature [30][38]; the program verifies everything WebAuthn wraps around it.

The admin first registers the credential with set_passkey_credential(credential_id_hash, public_key, rp_id_hash, allowed_origin_hash), which creates a PasskeyCredential at [b"passkey", vault, credential_id_hash]:

The key must be compressed (first byte 2 or 3), otherwise InvalidPasskey. Registration is immutable: repeating it with identical values succeeds without change, any other value is refused, and a different key or domain needs a new credential ID. No relying-party domain is inferred. The admin then selects the credential by writing its PDA address into policy.cosigner with set_policy. A PDA has no private key, so no Ed25519 proof can ever match it: choosing a passkey turns the Ed25519 path off.

approve_payment_passkey(intent_hash, merchant, amount, expiry, precompile_ix_index, authenticator_data, client_data_json, policy_revision) applies the same receipt, revision and amount checks as approve_payment, requires policy.cosigner to equal the credential's address (ApprovalMismatch), rebuilds the 128-byte approval message, and verifies the assertion:

Failures return InvalidPasskey or InvalidPrecompile. On success sign_count advances to the assertion's counter. Authenticators that always report zero are accepted, because replay is already prevented by the intent's single use; a zero counter can never reset a stored nonzero one.

The approval is a transaction of its own. A WebAuthn assertion adds authenticator data and client data to the proof, and the assertion, a merchant quote and pay together would not reliably fit one 1,232-byte legacy packet. Measured on the built program, a passkey approval with 37 bytes of authenticator data is 897 bytes and 32,701 compute units. The Approval account carries the decision from that transaction into the payment.

Consumption, expiry and single use

pay consumes an approval only when one is needed (the co-signer step of §3.4). It requires used = false, now < expiry, the vault's current revision, and an exact match of intent, merchant and amount. It then sets used, moves the USDC and closes the Approval in the same instruction, returning its rent to approval.rent_payer; the rent receiver passed must be that address, otherwise ApprovalMismatch. An approval passed with a payment at or below the threshold is left untouched.

Single use rests on the permanent receipt, not on the closed account. pay initializes the PaymentReceipt at [b"payment", vault, intent_hash], so the same intent can never be paid twice, and approve_payment refuses an intent that already has a receipt, so a consumed approval cannot be recreated from the co-signer's old signature. The signed revision closes the remaining path: an approval voided by set_policy cannot be recorded again under the new policy, because its signature names the old revision.

An approval that is never used is closed with close_approval. Anyone may call it once now ≥ expiry or once the approval's revision differs from the vault's, and the rent goes only to the original payer; an unexpired approval of the current revision returns ApprovalStillValid. Once it is closed, a new approval for the same intent may be recorded with a fresh expiry, provided no payment has committed that intent.

Example. On the second day of the §3.3 example, the vault buys a quoted GPU job of 140 USDC from M2. The agent computes the intent from the quote (amount 140,000,000, the quote's nonce and hash, lane 0) and sends it to the co-signer, who signs an approval expiring 15 minutes ahead at policy_revision 0. The approval transaction records it. The agent then submits pay: 140 ≤ 150 on the cap, the quote is present, M2's counter gives 0 + 140 ≤ 150, the vault gives 2 + 140 + 20 = 162 ≤ 200, and 140 > 100, so the approval is checked, consumed and closed. Had the admin changed the policy between approval and payment, pay would return ApprovalPolicyChanged, and anyone could close the void approval to refund its rent.

3.6 Session key rotation

rotate_session_key(session_key) replaces the vault's session key. The admin signs, with the same accounts as set_policy. The handler requires a nonzero key (InvalidConfiguration), reconciles the window, revokes the SPL delegate, sets last_approved = 0, writes the new key and emits CoreEvent kind 24.

From that instruction on, the old key can do nothing with the vault's USDC: pay and pay_escrow require the new key as signer, and the float delegate is gone. The new key receives an allowance at the next refill_float, whose session account must equal the new policy.session_key. Rotation leaves policy_revision unchanged. An approval binds an intent, a merchant, an amount and a policy, not the key that submits the payment, so a pending approval stays valid for the new key. The instruction has no frozen check, so the admin can rotate the key of a frozen vault before unfreezing it.

Credit lines keep their own key

Tabs follow a separate key schedule. A credit line copies the vault's session key into voucher_session_key when it is opened, and the merchant extends credit against vouchers signed by that key. Rotating the vault's key changes no line; lines opened afterwards adopt the new key. Each existing line rotates with rotate_line_key, on notice:

1. The admin calls rotate_line_key(session_key). The line records pending_voucher_key with effective_at = now + 259,200 s (72 h) and emits CoreEvent kind 18. Repeating the same key before that time returns KeyRotationDelayNotReached; a different key restarts the notice.
2. Verification switches exactly at effective_at, with no transaction needed. At time t, a voucher must be signed by the pending key once t ≥ effective_at, by the previous key for t before the last switch, and by the current key otherwise.
3. Calling rotate_line_key again with the same key at or after effective_at materializes the switch: the old key moves to previous_voucher_key, rotated_at records the switch time, and CoreEvent kind 19 marks it applied.

The 72 hours are the merchant's notice. During them the merchant can settle the outgoing key's latest voucher, or record it with attest_line_voucher in a VoucherAttestation at [b"voucher-attestation", line, outgoing key, effective_at], which holds a maximum nonce and a cumulative ceiling. After the switch, an old-key voucher settles or claims only through that record and only up to both ceilings: the outgoing key cannot sign new debt, and the merchant keeps the debt it already accepted (§5). Scheduling and attestation remain available while the vault is frozen, while unfreeze recourse locks collateral and during an active default, so a rotation is never blocked by the lock it may be needed to get out of.

A replaced key is therefore removed in two stages. rotate_session_key, or a guardian freeze, ends its reach into the vault at once. rotate_line_key moves each line's voucher authority after the merchant's notice, and during the notice each line's limit bounds what any voucher on it can claim.

3.7 The guardian and freezing

Who can freeze

A guardian is a monitoring key whose only power is freeze. There are two guardian slots: Operator.guardian, set by create_operator and covering every vault of the operator, and policy.guardian on each vault. freeze accepts the admin, the operator guardian or the vault guardian as signer; anyone else gets Unauthorized. unfreeze takes the admin alone. A guardian can stop a vault and cannot restart it, and no guardian can move USDC anywhere.

Either guardian is replaced with rotate_operator_guardian or rotate_vault_guardian, signed by the admin. The first call schedules the replacement 259,200 s (72 h) ahead and emits GuardianRotated with applied = false. Calling again with the same key at or after that time applies it; before it, the call returns GuardianRotationDelayNotReached; naming a different key restarts the notice; naming the current guardian returns InvalidConfiguration. The zero key removes the guardian. Rotation stays available while frozen and during a default, so an obsolete guardian cannot block its own replacement.

What freeze does

freeze takes the actor (writable signer), the Operator, the vault, its token account, the token program, the FreezeCheckpoint address of the next generation (of the current one when the vault is already frozen), the system program and the vault's freeze reserve. In order:

1. Check the actor.
2. Reconcile the window, so float spent up to the freeze is booked.
3. Revoke the SPL delegate. The session key loses the float in the same instruction.
4. If the vault is not already frozen: increment freeze_generation to g, create the FreezeCheckpoint at [b"freeze", vault, g], start a new freeze episode when this is the vault's first freeze or the previous recourse tail has ended (now > recourse_until), set frozen_at = now, increment Operator.frozen_vault_count, and set frozen = true.
5. Set last_approved = 0 and emit CoreEvent kind 15.

Freezing a vault that is already frozen repeats steps 1–3 and 5 against the same checkpoint, time and generation. A measured freeze with a pre-funded reserve is 409 bytes and 54,390 compute units.

Bonded's freeze is program state, separate from SPL Token's own account freeze, which belongs to the mint's freeze authority. The token account stays usable to the SPL Token program, so deposits still arrive and escrow refunds still return; it is the program, and the absence of a delegate, that close every outflow.

The checkpoint is evidence. It records the vault, the generation, frozen_at, the operator's defaults_count at that moment and the episode's first generation, and unfreeze later fills unfrozen_at and recourse_until once. Credit lines judge voucher and line expiry at a checkpoint's freeze time, so a merchant whose vouchers expire while the vault is frozen keeps the claim it held when the freeze began (§7).

The freeze reserve

A guardian is usually a hot key run by a monitoring worker, holding no SOL. The vault's freeze reserve, a system-owned PDA at [b"freeze-reserve", vault] that the admin funds with fund_freeze_reserve(amount) in lamports, pays the checkpoint's rent instead: 1,510,320 lamports for its 89 bytes. If the reserve would be left below the rent-exempt minimum of an empty account, the program moves all of it, so no unusable remainder stays behind. When the reserve is short, the freezing signer pays, and a signer that cannot gets FreezeReserveInsufficient. A guardian with zero lamports and a separate fee payer can therefore freeze.

close_freeze_checkpoint is permissionless and returns a checkpoint's rent to the same reserve once no claim can still use it: for a checkpoint of an older episode, once 259,200 s (72 h) have passed since the current episode began; for the current episode, once the vault is unfrozen and 72 hours have passed after recourse_until. Earlier, it returns FreezeCheckpointInUse.

What a frozen vault refuses and what it allows

Grace and the recourse tail

A freeze must not become a way to avoid paying tabs. Merchants that served the agent before the freeze hold valid vouchers, and a frozen vault will not pay them. Once the vault has been frozen for freeze_grace_seconds within the episode, a merchant may call settle_tab and open a default against the operator's bond; no USDC leaves the vault on that path.

The 96-hour floor is the guardian rotation delay plus a margin. A guardian that freezes in bad faith cannot push the operator into a forced default before the admin's 72-hour replacement completes, and the operator keeps 24 hours to respond. Grace counts only frozen time: an admin who unfreezes promptly stops the clock, and repeated unfreeze and refreeze within one episode cannot restart time already accumulated.

unfreeze adds the finished interval to episode_frozen_seconds, sets recourse_until, writes unfrozen_at and recourse_until into the current checkpoint (the instruction takes it as its last account and checks its address, owner, vault, generation and that it is still open, InvalidFreezeCheckpoint otherwise), raises Operator.recourse_lock_until to at least recourse_until, decrements frozen_vault_count and clears frozen. It does not restore the float; the next refill_float does. A measured unfreeze is 376 bytes and 28,056 compute units.

Through the tail the bond stays locked. An operator cannot unfreeze, withdraw collateral and leave merchants without recourse for vouchers judged at the freeze. A freeze during the tail continues the same episode with its accumulated frozen seconds; a freeze after the tail starts a new episode with a fresh count.

The guardian worker

The program defines what a guardian may do; the guardian worker in backend/src/guardian.ts decides when. It reads committed payment projections (float transfers, pay and escrow fundings, leaving out tab settlements, whose timing the merchant chooses) and raises an alert on a burst of payments to new counterparties, a spend spike against a baseline, or spending above a window cap. Every rule value is operator configuration with no default. An alert becomes a durable freeze job, which a sponsored executor signs with the guardian key and a separate fee payer (§11.4).

3.8 Withdrawals from the vault

withdraw(amount) moves USDC from the vault to any classic SPL token account for the configured mint, which may belong to another treasury wallet. The admin signs. The accounts are the admin, the Operator, ProtocolConfig, the vault, the vault's token account, the destination, the mint and the token program. The handler:

1. Refuses a frozen vault (VaultFrozen) and a zero amount (InvalidAmount).
2. Reconciles the window.
3. Revokes the float and sets last_approved = 0.
4. Transfers amount with a CPI TransferChecked, signed by the vault PDA; the SPL Token program refuses an amount above the balance.
5. Emits CoreEvent kind 25.

A withdrawal is not session-key spending, so it books nothing against the window. Like every admin action on the vault, it ends with no delegate outstanding, and the agent's next allowance is issued by a refill under the vault's state after the withdrawal.

The vault has no cooldown and no safety margin; those belong to the bond. The vault's balance is working capital and carries no promise to merchants. A merchant on a tab relies on the operator's bond, and a bond withdrawal unlocks only at

so an operator cannot leave ahead of a default (§6). If the admin withdraws the vault below what a merchant's voucher asks, settle_tab finds the vault short and opens a default event, and the line holders' claims are paid from that bond (§7). A vault withdrawal moves the shortfall onto the operator's own collateral.

The frozen refusal completes the freeze. A frozen vault has every outflow closed: program payments, the float, tab settlement from the vault and withdrawal. Only the admin's unfreeze opens them again, and that instruction is a public on-chain act that starts the recourse tail and keeps the bond locked for its whole length.

4. The float

The float is the vault's lane for open-web x402 calls. It is a small USDC allowance on the vault's token account, held by the session key as SPL Token delegate, so the agent can pay any x402 endpoint the way an ordinary wallet does: with one top-level TransferChecked. The program does not see these payments as they happen. It bounds them in advance by the size of the allowance, and books them afterwards against the vault's window budget (§3.3).

4.1 Why the float exists

An x402 merchant is paid before it serves: its 402 response names an amount and a recipient, the client pays, and the merchant's facilitator verifies the payment. On Solana the exact scheme requires a top-level TransferChecked in a fixed instruction layout [7]. A vault cannot produce one. Its USDC is owned by a PDA, a PDA signs only through its program, and every program payment from a vault is therefore a TransferChecked issued by cross-program invocation from inside pay, an inner instruction. A facilitator that checks for a top-level transfer rejects that shape.

The float resolves it with SPL Token's delegate. The vault approves the session key as delegate of its token account for a capped amount. The session key then signs an ordinary top-level TransferChecked with itself as authority, which is the shape the exact scheme expects, and the facilitator pays the network fee [7]. The merchant needs nothing from Bonded.

The program cannot inspect these payments. A delegate transfer is an SPL Token instruction: Bonded is not invoked, merchant rules do not apply, and the destination can be any token account. The float is therefore a bound rather than a rule. Its cap limits what the session key can move between two program observations, the window budget limits the sum per window, and a freeze removes the delegate in one instruction (§4.6).

4.2 The allowance

SPL Token's delegate mechanics are the whole enforcement, so they are stated exactly:

• Approve(delegate, amount) sets the token account's delegate and sets delegated_amount = amount. It replaces any previous allowance; it never adds to it.
• A TransferChecked signed by the delegate succeeds only when amount ≤ delegated_amount, and lowers delegated_amount by the amount. At zero the delegate is cleared.
• Revoke clears the delegate and sets delegated_amount = 0.
• Only the token account's owner can Approve or Revoke.

The owner is the vault PDA. Only the program can grant or remove the allowance, and it does so in exactly five places: refill_float approves, and set_policy, rotate_session_key, withdraw and freeze revoke. Between two Bonded instructions the allowance can only shrink, as the session key spends it.

The vault tracks the allowance with two numbers: policy.float_cap, the most a refill may approve, and last_approved, the allowance as of the last reconciliation. With the token account they keep:

The allowance is a permission, not a reservation of tokens. Approve neither checks nor locks the balance, and a float transfer fails at the SPL Token program if the vault holds less than its amount. What the allowance reserves is window capacity: pay and pay_escrow count the outstanding delegated_amount as already spent when they test the vault budget (§3.3).

The program has no default float cap; each policy supplies its own. The brief's $20 is an example, and the scripted example operator uses float_cap = 20,000,000 (20 USDC) with a daily window_budget of 500,000,000 (500 USDC).

4.3 A float payment

An agent requests a paywalled endpoint, receives HTTP 402 offering the exact scheme, and pays with a transaction holding one SPL TransferChecked:

The session key signs as transfer authority, the facilitator adds its fee-payer signature and submits, and SPL Token lowers delegated_amount. The example agent in backend/examples/agent makes exactly this payment: it refills, builds one TransferChecked from the vault's token account with the session key as authority, and refills again to book it.

Because Bonded is not invoked, the indexer finds float payments in the vault token account's own transaction history. A USDC transfer with 6 decimals and a positive amount, whose source is a vault's token account owned by that vault, is recorded as a payment in lane FLOAT, and the guardian worker counts it with the vault's other session-initiated spending (§3.7, §11.4).

4.4 refill_float

refill_float takes no arguments and four accounts: the vault (writable), its token account (writable; it must be vault.token_account with the vault as authority), session (it must equal policy.session_key and does not sign), and the token program. No Bonded signer is required; anyone who pays the network fee may call it. The handler:

1. Refuses a frozen vault with VaultFrozen.
2. Reconciles the window (§3.3): rolls over whole periods, then books what the session key spent since the last reconciliation.
3. Requires window_spent ≤ window_budget, otherwise WindowBudgetExceeded.
4. Computes the new allowance and calls SPL Approve for it, signed by the vault PDA, with the session key as delegate.
5. Sets last_approved to the new allowance and emits CoreEvent kind 20 carrying it.

Four properties follow from the formula.

It books once. After a refill last_approved = delegated_amount, so a second refill books zero and approves the same allowance, unless a window boundary passed in between. No spend is ever counted twice, which is what allows anyone to call the instruction.

Anyone may call it. The outcome is fully determined by the policy, the window state and the token account. No caller chooses the amount, the delegate or a destination; the most any caller can do is bring the allowance up to the value the policy already allows. The agent (refillFloat in the agent SDK, bonded_refill_float in the MCP server), a keeper or a merchant's service can keep the float topped up without holding any vault key.

The window is its rate limit. Once window_spent reaches window_budget, the allowance is zero until the window rolls. The program has no separate refill cooldown: a refill may come at any time, and the budget left in the window is the only limit on how much it restores. Step 3 matters only after set_policy has lowered the budget below what the window already booked; the vault then cannot refill until the window rolls.

It overwrites. Step 4 replaces the remaining allowance. A session key holding 12.50 USDC of a 20 USDC float is reset to 20, not raised to 32.50, so the outstanding allowance never exceeds float_cap.

A refill is how float payments enter the window when no program payment follows them. Every other instruction that reconciles books them too, so the book is current after any Bonded instruction on the vault.

4.5 Every instruction that touches the float

Every admin action on the vault, and every freeze, ends with no delegate outstanding. The agent's next allowance is always issued by a refill, under the vault's current policy, key and window state. A session key can never hold an allowance computed under a policy that has since changed.

4.6 The float as a loss bound

The float is the part of the vault the program cannot check payment by payment, so its design question is how much the session key can move without the program. Three quantities answer it:

At any instant the session key can move at most the outstanding allowance, at most float_cap, to any address. Every further unit needs a refill, and every refill first books what the previous allowance paid out. The float cap is therefore the bound between two program observations, and the window budget bounds the sum of all draws in a window, shared with the vault's program payments (§3.3). A freeze closes the lane in one instruction: it books the float spent up to that moment, revokes the delegate, and makes refill_float refuse until the admin unfreezes.

The two parameters do different work. float_cap sets the size of each draw, and with it how much leaves before a guardian can act on what it sees. window_budget sets the ceiling when no one acts. Payments to merchants the operator chose run through pay, where rules, quotes and approvals apply; open-web calls run on the float, where the protection is the size of the allowance the operator chooses to expose. The bond backs tabs; spending on the float is bounded by the allowance and the window rather than guaranteed.

4.7 Worked example

Example. A vault has float_cap = 20,000,000 (20 USDC), window_budget = 200,000,000 (200 USDC) and window_seconds = 86,400 s (24 h). At 09:00 the window has booked 60 USDC of program payments, and the session key holds a full float: last_approved = delegated_amount = 20,000,000.

Ordinary use. Between 09:00 and 10:00 the agent makes 140 x402 calls at 0.05 USDC each, 7,000,000 base units in all, and delegated_amount falls to 13,000,000. At 10:00 a keeper calls refill_float:

Approve sets the allowance back to 20 USDC. A second refill at 10:01 books zero and approves 20 USDC again. The invariant holds: 67 + 20 = 87 ≤ 200.

The bound at its limit. At 11:00 whoever holds the session key moves the whole 20 USDC to an address no merchant rule names. SPL Token accepts the transfer, because the key is the delegate. The holder then calls refill_float, which books 20 USDC and approves min(20, 200 − 87) = 20 USDC, moves that too, and repeats:

Amounts are in USDC. With nobody acting, the outflow stops at 133 USDC, the window budget less the 67 USDC already booked; in the next window the same key could draw again, 20 USDC at a time, up to that window's budget. The key cannot use pay to reach the same address, because no merchant rule names it. If the guardian worker freezes the vault after the second draw, the outflow is 40 USDC: the freeze books the second draw, revokes the delegate and makes every further refill fail with VaultFrozen. The admin then rotates the session key (§3.6) and unfreezes, and the new key's first refill computes its allowance from the window as booked.

5. Tabs and vouchers

A tab is the lane for metered services billed in arrears. The merchant serves a request before it is paid. With each request the agent's session key signs a voucher that states the total the line owes so far. The merchant checks the voucher locally, keeps the newest one, and later presents it to the program with settle_tab, which moves the unpaid difference from the agent's vault to the merchant. When the vault holds less than that difference, the same instruction opens a default event and the operator's bond becomes the source of payment (§7). A tab needs no facilitator and no transaction per request. The only on-chain step is the settlement, and one settlement covers any number of requests.

This chapter follows a tab from the HTTP exchange to the transaction that settles it: the bonded-tab scheme (§5.1), the voucher bytes (§5.2), the domain tag (§5.3), cumulative amounts and nonces (§5.4), the merchant's checks (§5.5), settle_tab (§5.6), transaction size and compute (§5.7), settlement cadence (§5.8), and voucher attestations during a line-key rotation (§5.9).

5.1 The bonded-tab scheme

x402 lets an HTTP server answer a request with status 402 and a description of the payment it accepts; the client pays and retries. The exact scheme prepays every request. bonded-tab keeps the 402 negotiation and replaces the payment with a signed voucher on a credit line, so the merchant can serve first and collect later. The merchant middleware (@bonded/merchant-middleware) issues and verifies the scheme, the agent SDK (@bonded/agent-sdk) answers it, and both use the wire types and digest functions in @bonded/contract/tab.

The request

The agent sends an ordinary HTTP request with an Idempotency-Key header of 8 to 128 characters drawn from A–Z a–z 0–9 . _ : -. The key names one billable request: a retry with the same key, URL, method and body is the same request, and the merchant never bills it twice. The middleware calls three hooks the merchant host supplies: admit and lineFor before it reads any payment data, and price once it has decoded the payment and found no stored replay (a replay is answered from the store and never priced again). admit(request) returns the authenticated client identifier (clientId), or false, which produces 429. lineFor(request) returns the credit line the request draws on. price(request) returns the charge in USDC base units and the metered units, both positive u64 values. On every request the middleware also confirms that its own RPC reports the configured cluster genesis hash.

The challenge

When the request carries no payment, the middleware computes the next voucher for the line and answers 402. The challenge appears twice: as JSON in the body and, base64-encoded, in the Payment-Required header, sent with Cache-Control: no-store. It contains x402Version: 2, the resource (url, method) and exactly one offer. The merchant proposes the next cumulative amount, nonce and expiry and the agent checks them. The counter stays in one place, the merchant's meter, and the agent still sees every value it needs to refuse a charge it did not agree to.

The challenge's resource.url and resource.method must also equal the request the SDK sent, and the SDK refuses redirects, so a challenge for another resource cannot be answered with this request's voucher.

The payment

fetchWithTab(input, init, { maxCharge, requestKey, maxRetries, maxRequestBytes }) handles the challenge. It decodes Payment-Required, verifies the network against the program ID and genesis hash the operator pinned (both the API's protocol record and the SDK's own RPC must match), and reads the line fresh from a trusted chain adapter or the authenticated API, never from the 402 alone. It signs only if every check above holds, then resends the same request bytes with a Payment-Signature header: base64 JSON of { x402Version: 2, scheme: "bonded-tab", network, requestKey, voucher }. Before sending, it records the request authorization (request digest, header, charge, cumulative amount, nonce) under origin:requestKey. A retry of that key resends the same header, and the SDK never authorizes a second increment for one request key. A request body needs an explicit maxRequestBytes between 1 and 16,777,216 and is buffered once, so every attempt carries identical bytes.

Both headers are limited to 8,192 bytes of JSON, and the decoder accepts at most 12,000 base64 characters. The MCP server's bonded_fetch_tab tool calls the same method with a maxCharge taken from operator-configured per-call and window ceilings, so a model cannot raise the charge it authorizes.

Responses

On a 409 the SDK sends the request again without payment to obtain a fresh challenge, at most maxRetries times (one by default, two at most).

5.2 The 96-byte voucher

The voucher is the agent's signed acknowledgement of debt. It is fixed-length, with every field at a fixed offset, so the program decodes it by slicing without length prefixes, and the Ed25519 precompile instruction that carries it can pin the message size to 96 (§5.6).

The voucher names no merchant, vault or amount increment because the line address implies them. A line is the PDA [b"line", bond, merchant], and it stores the vault it draws on, so a voucher for one line can be settled only by that line's merchant, against that line's vault, under that line's bond. The increment is computed by the program from the line's stored floor (§5.4), never taken from the signer.

The shared test vector in backend/test-vectors/core.json shows the bytes for a program ID of 32 × 0x11 and a genesis hash of 32 × 0x42 (Example: synthetic identifiers):

17efe2eb836316fc                                                  domain tag
000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f  line
ffffffffffffffff                                                  cumulative = 18 446 744 073 709 551 615
2a00000000000000                                                  nonce = 42
00d2496b00000000                                                  expiry = 1 800 000 000
fffefdfcfbfaf9f8f7f6f5f4f3f2f1f0efeeedecebeae9e8e7e6e5e4e3e2e1e0  usage digest

The browser codec generates this vector and the program's Rust tests decode it with the program's own decode_voucher, so both sides produce and accept the same 96 bytes. The same tests confirm that the bytes fail under a genesis hash of 32 × 0x43, under another program ID, and when truncated to 95 bytes.

5.3 The v2 domain tag

An Ed25519 signature over 96 bytes is valid wherever those bytes are presented. The first eight bytes of the voucher bind it to one deployment of the program on one cluster, so a signature made for one cannot be spent on another.

initialize_protocol takes cluster_genesis_hash as an explicit argument and derives the tag in the program from its own ID: voucher_domain(crate::ID, &cluster_genesis_hash). Both values are stored in ProtocolConfig. Initialization requires the signature of the program's actual upgrade authority, checked against the loader's ProgramData account, so no other key can install a different tag. Every instruction that reads a voucher (settle_tab, file_claim, attest_line_voucher) compares bytes 0–7 with the stored voucher_domain before it reads any voucher field. A voucher with another tag, including the old literal tag BONDTAB1, fails with InvalidVoucher.

The two inputs stop two different replays.

• Across clusters. PDAs derive from the program ID and seeds only. An operator who uses the same admin key, merchant and program ID on devnet and on mainnet has the same Operator, Bond and CreditLine addresses on both, and the session key may be the same too. Without the genesis hash in the tag, a voucher signed against a devnet line would carry a valid signature and a valid line address on mainnet. The genesis hash makes the two tags differ.
• Across programs. Another deployment of the program, or any program that reuses the layout, has a different ID. The line address already differs there, and the tag differs as well, so a session key that signs vouchers for several deployments produces signatures each deployment alone accepts.

The other messages Bonded signs use the same derivation with their own prefixes, so a signature over one kind of message cannot be presented as another.

Sign-in messages carry the distinct prefix Bonded off-chain authentication v1, and the SDK refuses to sign arbitrary API messages, voucher bytes included, through its login path. Both off-chain parties pin the tag inputs. The SDK's verifyNetwork() requires the API's voucherDomain.programId to equal the operator-pinned program ID, and both the API's clusterGenesisHash and the SDK's own RPC getGenesisHash() to equal the pinned genesis hash; signatureContextFromProtocol recomputes the tag and requires it to equal the API's tagHex. The middleware refuses to start if its signature context and configured genesis hash differ, and refuses every request while its RPC reports another genesis hash.

5.4 Cumulative amounts and nonces

A voucher states the total owed on the line since it opened, not the amount of one request. The newest voucher therefore includes every earlier one, and a merchant that holds it can collect the whole tab with a single settlement. Settling records the voucher's amount and nonce on the line, and every older voucher falls below those floors.

Both the nonce and the cumulative amount must strictly advance. Requiring both makes the accepted vouchers a single chain: a voucher with a higher amount but an old nonce, or a new nonce for the same amount, is rejected with VoucherReplay. The program requires an increase, not a step of exactly one, so a merchant can settle any voucher in its history that is newer than the floor. The retired floor stops a voucher from being collected twice. A default payout raises retired_cumulative to the claimed voucher's amount and maximum_nonce to its nonce, so the same debt cannot be settled again from the vault after the bond has resolved it.

The limit bounds the unsettled amount, not the line's lifetime volume. After each settlement the floor rises, and the agent can again owe up to limit above it.

Vouchers v1, v2 and v4 were never settled and need not be: v3 and v5 contain them.

How the merchant issues the next voucher

The middleware derives each offer from its meter and the chain state:

The last line is the merchant's limit check. It uses a matured pending decrease before the chain applies it, because settle_tab applies a matured decrease before it checks the delta (§5.6, §6.4). The agent SDK runs the same calculation independently. It signs only if the offered cumulative equals the highest of its own latest issued voucher, the line's settled amount and its retired amount, plus the charge it was shown. A merchant cannot add a charge the agent did not see.

The usage digest

The usage digest ties a voucher to the request and charge that produced it:

The program carries the digest without interpreting it. It is evidence for the parties: the merchant keeps every request's voucher, so each increment of the cumulative amount can be traced to one request, its body hash, its charge and its units. For off-chain review of metering, the newest voucher establishes the total, and the stored history attributes each part of it to one request.

5.5 Merchant-side verification

The merchant decides at request time whether to extend credit, using its own copy of the line state, and confirms everything the program will check later. A voucher the middleware accepts is one settle_tab would accept. The middleware holds no private key; it reads, verifies and records.

For a request with a Payment-Signature header the middleware runs these steps in order:

1. Admission and framing. admit must return a client identifier; the body must fit maxRequestBytes; the Idempotency-Key must be well formed; the merchant's RPC must report the configured genesis hash.
2. Envelope. The payment's network, requestKey and voucher.line must equal solana:<genesis>, the request's key and lineFor(request).
3. Idempotent replay. The store looks up (merchant, line, requestKey). A completed request with the same client, request digest and exact voucher proof is answered from the stored response. One that is in service returns 409. One from another client returns 403, and one with different bytes or proof returns 409.
4. Line state. Reads are cached for cacheMilliseconds. A charge, or an outstanding increment over the settled amount, that reaches rereadIncrement forces a fresh read.
5. Pause conditions. Credit pauses and settlement is queued when the line expiry, a pending key switch, or the newest outstanding voucher's expiry falls within settlementHorizonSeconds (§5.8).
6. Line checks. The vault must not be frozen; the line must be active; the charge must fit the effective limit (§5.4).
7. Voucher bytes. The 96 bytes are decoded under the signature context (domain tag). Their cumulative amount, nonce, expiry, line and usage digest must equal the DTO's fields and the recomputed usage digest. signer must equal the line key effective now, voucherKeyAt(line, now), which switches to a scheduled key exactly at its effective_at. The expiry must lie beyond now + horizon and no later than the offered expiry. The signature must verify under strict RFC 8032 rules (zip215: false), which refuse non-canonical encodings.
8. Reservation. Under a PostgreSQL advisory transaction lock on merchant:line, the voucher's cumulative amount must equal max(meter, chain floor) + charge and its nonce max(meter nonce, chain nonce) + 1. The meter advances, the usage row is created, and the line's settlement job is queued. A concurrent request that lost the race receives 409 and fetches a new challenge.
9. Service. The service callback receives the idempotency key, units and voucher. Its response, bounded by maxResponseBytes, is stored before it is returned.

Steps 3 and 8 make billing exactly-once per request key. Each service execution holds a lease of serviceLeaseMilliseconds, which must exceed maximumServeMilliseconds. A failed service releases its lease, and a retry with the same key resumes the same billed request instead of creating a new charge.

The middleware keeps its state in PostgreSQL through one of two adapters with the same three roles. createBondedMerchant uses the built-in pg store, whose tables BondedMerchantMeter, BondedMerchantUsage and BondedMerchantJob are created by bonded-merchant migrate; its worker scans the lines on each run. The Prisma adapter (@bonded/merchant-middleware/postgres) keeps them in these tables:

The meter answers "what is owed now". The usage table is the proof history: every request's own voucher, kept for replay and for the worker, which searches it for the newest voucher that can still settle. The job table is the settlement outbox.

5.6 settle_tab on chain

settle_tab(default_sequence: u64, ed25519_ix_index: u16) is signed by the merchant that holds the line. Its 18 bytes of instruction data are the 8-byte discriminator (the first 8 bytes of SHA-256(global:settle_tab)), the bond's next default sequence and the index of the proof instruction.

The Ed25519 proof and the instructions sysvar

Ed25519 verification runs in Solana's native precompile, not in the program. The transaction carries an Ed25519 program instruction holding the public key, signature and message; the runtime verifies it before any instruction executes, and a bad signature fails the whole transaction. The program then has to establish that the verified message is this voucher, verified under this key. It reads the transaction's instructions from the instructions sysvar and accepts exactly one form:

verified_voucher performs these checks, in order:

1. load_current_index_checked gives the index of the executing instruction; it must be greater than 0, and ed25519_ix_index must be exactly one less. The proof immediately precedes the settlement.
2. The instruction at the current index must belong to the Bonded program itself. When Bonded is reached through a CPI, the top-level instruction belongs to the calling program, so CPI wrappers are refused.
3. The proof instruction must belong to the Ed25519 program, list no accounts and carry exactly 208 bytes of data.
4. Its first 16 bytes must equal [1, 0, 48, 0, 255, 255, 16, 0, 255, 255, 112, 0, 96, 0, 255, 255].
5. Bytes 112–207 are decoded as the voucher, with the domain tag check, and the voucher's line must equal the line account.
6. Bytes 16–47 are returned as the signer.

The header pins every instruction index to 0xFFFF, which tells the precompile to read key, signature and message from its own data. Without that, a proof could verify a signature over bytes in some other instruction while the program decoded different bytes here. Pinning the offsets and the count to one signature means the bytes the runtime verified are the bytes the program reads. Any other layout, a second signature, a proof elsewhere in the transaction, or a reference into another instruction fails with InvalidPrecompile.

Checks

The freeze rows exist because a frozen vault cannot transfer and its lines keep a recourse path through the bond. §3 describes freeze and §7 the forced default. On an unfrozen vault with no recourse tail, the validation time is simply the current block time.

What moves

When the vault holds at least the delta and is not frozen, the program pays the delta from the vault, signing as the vault PDA with seeds [b"vault", operator, agent_id, bump]:

Two TransferChecked CPIs (decimals 6) move the amounts; the second is skipped when the fee is zero. The line then records settled_cumulative = voucher.cumulative and maximum_nonce = voucher.nonce, the operator's tabs_settled increases by one, the program emits CoreEvent kind 8 (tab_settled) with the delta as amount and the fee as fee, and it closes the DefaultEvent placeholder, returning its rent to the merchant in the same instruction.

The merchant pays the fee out of the settled amount. The rate is fixed per line at opening, so a governed change to tab_fee_bps applies to lines opened afterwards and never reprices a voucher already accepted on an existing line. update_protocol cannot raise the rate above maximum_tab_fee_bps, which is fixed at initialization and at most 10,000. The devnet parameter file sets tabFeeBps 10, tabFeeWaived true and maximumTabFeeBps 100, so lines opened under it carry tab_fee_bps = 0 (§10).

Example. A line opened with tab_fee_bps = 10 settles a delta of 12,500,000 (12.5 USDC): the fee is ⌊12,500,000 × 10 ÷ 10,000⌋ = 12,500, the merchant receives 12,487,500 and the fee treasury 12,500. A delta of 999 base units at the same rate carries a fee of 0, because the rate rounds down.

When the vault holds less than the delta, or the vault is frozen and its grace has run, no USDC moves and the voucher is not booked as settled. The program opens the DefaultEvent at sequence default_sequence, sets active_default_sequence, clears any pending bond withdrawal, sets the 259,200-second (72 h) claim window, increments defaults_count and emits kind 9 (default_opened). There is no partial payment. §7.1 describes this branch.

A full tab

5.7 Transaction size and compute

A settlement is a legacy Solana transaction, limited to 1,232 serialized bytes. The program's own measurement run executes each signed transaction in LiteSVM 0.7.1 (Agave 2.3 runtime) against the compiled program and records its full serialized size, including the signature section, and the compute it consumed.

The compute figures describe this reproducible benchmark. Other actor keys change the cost of PDA searches, so they are measurements of the implementation, not a protocol constant. Against the planning estimates, the bare single-voucher transaction is 894 bytes where roughly 700 were estimated, and 61,044 units where the estimate was well under 100,000.

The 894 bytes break down exactly into the legacy wire format:

The 17 keys are the 15 accounts of §5.6, the Ed25519 program and the Bonded program. The SDK path adds the associated token program's CreateIdempotent instruction for the merchant's token account: 10 instruction bytes plus the program's 32-byte key, 936 in all. The API path also appends an SPL Memo bonded:<preparation UUID>, which gives separate preparations distinct messages: a 46-byte instruction plus the memo program's key, 1,014 in all. The merchant worker submits API-prepared transactions: the 1,014-byte, 82,363-unit row plus the two ComputeBudget instructions every API preparation puts at the front (a unit limit and a unit price, 52 bytes), 1,066 bytes in all.

A second line costs at least 248 instruction bytes (212 + 36). A second line of a different merchant on the same bond and vault also needs a second signature (64 bytes) and three keys (its merchant, line and token account; the placeholder PDA is shared), 408 bytes in all. A second line of the same merchant must belong to another bond, because one merchant has one line per bond, and that adds seven keys (472 bytes). The bare single-voucher transaction leaves 338 bytes of headroom, so no second line fits, and the measured two-line candidates are 1,302 and 1,366 bytes. Settling two vouchers of the same line is never needed, because the newer one contains the older. The production planner therefore puts exactly one line in each legacy transaction (settlementsPerLegacyTransaction: 1) and checks the fully serialized size before signing and before broadcasting.

One settlement transaction carries one signature, so its network fee is the 5,000-lamport signature fee [27] plus the priority fee its compute budget sets (1,000 micro-lamports per unit by default, about 100 lamports for a settlement), however many requests its voucher covers.

5.8 Batching and settlement cadence

Batching in a tab happens over time, not across lines. Every request on a line folds into the next voucher, and one settle_tab collects all of them. A merchant that settles once per minute pays one transaction per line per minute, however many requests the line served in that minute.

The worker

createMerchantWorker(db, merchant, executor, { leaseMilliseconds, retryMilliseconds, settlementHorizonSeconds }) runs the settlement outbox. The host calls runOnce() on its own schedule; no daemon starts on import. Each run has two passes.

• Discovery. For every meter of this merchant, the worker reads chain time, the line and the line's defaults. A pending line-key switch in the future queues an attest_line_voucher job. A default whose claim window is open queues a file_claim job. A line with no unresolved default queues its settle:<merchant>:<line> job. A finished job is queued again when a stored voucher with a higher nonce exists.
• Processing. Due jobs run in order of kind and then ID, so attestations run before claims and claims before settlements. Each job takes a lease. The worker re-reads the line, picks the newest eligible voucher from the usage table (above the line's nonce and floor, unexpired at its judgment time, signed by an authorized key), prepares the action through the API, and requires a live simulation that succeeds for exactly that action. It checks the 1,232-byte limit and persists the prepared ID. The host's sign callback must authorize the original action independently, against the pinned program, genesis hash and trusted account state; the example merchant rebuilds the instructions itself and compares the complete message. The worker then checks the size again, persists the signed bytes, and submits them.

Persisting the signed bytes before submission makes a crash or an ambiguous RPC response safe. The next run resubmits the identical transaction under the same submit key and cannot produce a second, different settlement. A settlement job is closed without action while any default on the line's bond is unresolved, because settle_tab would fail with DefaultActive. While the default's claim window is open, the line's file_claim job runs instead, and settlement resumes after the payout, once the operator has renewed the line into the bond's new epoch (§6.2).

The settlement horizon

The cadence is bounded by one parameter, settlementHorizonSeconds: the time the merchant needs to get a voucher on chain, covering the scheduler interval, confirmation and every retry. The middleware and worker require explicit values and reject inconsistent ones at construction.

The horizon protects the latest voucher. Earlier vouchers need no protection, because the latest one contains them. The latest voucher must reach the chain before its expiry, since afterwards settle_tab refuses it with VoucherExpired. The middleware therefore accepts a voucher only if it expires more than one horizon from now, and it pauses credit on the line, answering 409 DEADLINE_NOT_REACHED and queuing settlement, as soon as any of three deadlines comes within the horizon:

• the line's expires_at,
• a pending line-key switch, after which the outgoing key's vouchers need an attestation (§5.9),
• the expiry of the newest voucher that is still above the chain floor.

Requiring voucherTtlSeconds to exceed twice the horizon gives every accepted voucher more than one horizon of service time before the pause, and one full horizon of settlement time after it. Once the settlement confirms, the floor rises, the outstanding voucher no longer counts, and the next request receives a fresh expiry.

With the Prisma adapter every accepted request re-queues its line's settlement job; the pg store's worker finds the line on its next scan. Either way the line settles at the worker's next run. The example merchant runs the worker every second. A merchant that settles less often runs it less often, within the same horizon rules, and the line limit bounds how much it has outstanding in between. The guardian worker leaves tab settlements out of its spend and counterparty rules for this reason: the merchant, not the agent, chooses when a settlement executes.

5.9 Voucher attestations

A line's voucher key is copied from the vault's session key when the line opens, and it changes only through rotate_line_key. The admin signs it, and the new key becomes pending_voucher_key with effective_at = now + 259,200 seconds (72 h). Verification switches at exactly that timestamp, with no transaction to apply it. A compromised or retired session key therefore stops creating new debt at a time every party can read on chain, and the merchant has 72 hours of notice. Rotating the vault's session key (rotate_session_key) revokes the float delegation and leaves each line's own scheduled rotation unchanged.

The switch raises one question: vouchers the outgoing key signed before the switch and the merchant had not settled yet. After the switch the outgoing key is no longer voucher_key_at(now), so its signatures carry no authority on their own. attest_line_voucher(ed25519_ix_index) lets the line's merchant record, during the notice, the newest outgoing-key voucher it holds. That record caps what the outgoing key can be held to afterwards.

The merchant signs, and the voucher arrives in the same canonical Ed25519 proof as for settle_tab. The program requires:

• a pending key switch whose effective_at is still in the future (AttestationNoticeClosed otherwise);
• a signer equal to the line's current, outgoing voucher_session_key;
• 0 < voucher.expiry ≤ line.expires_at;
• nonce and cumulative amount above the line's floors, and the delta within the limit;
• if an attestation for this epoch already exists, a nonce and amount at least as high as the recorded ones, so the ceilings only rise.

It writes a VoucherAttestation account at [b"voucher-attestation", line, outgoing_key, effective_at] (the switch time as i64 little-endian), funded by the merchant, holding bump, line, merchant, voucher_key, valid_from (the line's rotated_at, the start of the outgoing key's epoch), effective_at, maximum_nonce, cumulative_amount and attested_at, and emits CoreEvent kind 26 with the attested cumulative amount.

After the switch, settle_tab and file_claim accept an outgoing-key voucher only when the attestation is passed as their first remaining account and

A fresh signature from the outgoing key, made after the switch, cannot raise the acknowledged debt, because it cannot exceed either ceiling. An unexpired, acknowledged voucher stays payable from the vault after the switch, freeze or no freeze. The attestation moves no funds and revives nothing: settlement still applies every expiry and replay check of §5.6 at its own judgment time. Each rotation's attestation is its own PDA, so later rotations never discard the evidence of earlier epochs.

The merchant worker automates this. While a switch is pending, every discovery pass queues an attestation job for the line and re-queues it when a newer outgoing-key voucher arrives. Attestations run first in the processing order, and the middleware pauses credit when the switch comes within the horizon. An attestation transaction is 589 bytes and 17,652 compute units. A settlement that pays archived outgoing-key debt, with the attestation as an extra account, is 927 bytes and 68,692 compute units (§5.7).

6. Bonds and credit lines

The bond is the operator's USDC collateral, held by a program-owned account. Credit lines are the merchant-specific limits that collateral backs. A line gives one merchant the right to accept vouchers from one vault up to its limit until its expiry, with the bond standing behind the vault if the vault cannot pay. The bond pays nothing while the vault settles tabs. It pays only through a default event (§7), and then to every line holder under one formula. The rules in this chapter keep that promise checkable in advance: how much collateral the bond books, how much exposure it may back, how fast either can change, and when collateral may leave.

6.1 The Bond account and post_bond

An operator has exactly one bond. create_operator(guardian, minimum_coverage_bps), signed and paid for by the admin key, creates three accounts in one instruction: the Operator at [b"operator", admin], the Bond at [b"bond", operator], and the bond's USDC associated token account, owned by the Bond PDA. It accepts a correctly created token account that already exists. It refuses a minimum_coverage_bps below 3,300 with CoverageTooLow and emits CoreEvent kind 1. The bond backs every line the operator opens, across all of the operator's vaults.

The offsets after withdrawal assume a pending request. Without one, its Borsh Option tag is a single zero byte and default_sequence and active_default_sequence start 24 bytes earlier, at 100 and 108. The account is allocated at its maximum size of 141 bytes.

post_bond

post_bond(amount) is signed by the admin. It transfers amount from a USDC token account the admin owns into the bond's token account with TransferChecked (decimals 6), then books it:

A deposit that would pass either cap fails with BetaCapExceeded, and the instruction emits CoreEvent kind 4 (bond_posted). post_bond checks no coverage, freeze or default state. Adding collateral can only raise coverage, so the program never refuses it on those grounds. Collateral posted while a default is open joins the payout pool, which is snapshotted at the first payout (§7.3).

The bond's collateral is the booked balance, not the token account's amount. USDC that reaches the bond's token account by any other path is not booked. It counts toward no coverage check, no cap and no payout, and the protocol-wide total that enforces the 250,000 USDC cap stays exact. The token account's authority is the Bond PDA, and the program signs for it with [b"bond", operator, bump] in two places only: finalize_withdrawal, after the cooldown of §6.5, and execute_default_payout, to the merchant recorded in a claim.

6.2 open_line and the CreditLine account

open_line(limit: u64, expires_at: i64) gives one merchant credit against the bond. The admin signs and pays the line's rent. The merchant is passed as an unsigned account. A line obliges the operator's bond, not the merchant, and the merchant decides request by request whether to use it (§5.5).

The line is the PDA [b"line", bond, merchant], so a bond has at most one line per merchant. The line also names one of the operator's vaults, and every settlement on it draws from that vault. The checks run in this order:

1. The vault is not frozen (VaultFrozen).
2. No default is active on the bond (DefaultActive).
3. limit > 0 and expires_at > now (InvalidAmount).
4. Coverage holds with the new limit added: (balance − pending withdrawal) × 10,000 ≥ (reserved_lines + limit) × minimum_coverage_bps (CoverageTooLow, §6.3).

Then reserved_lines grows by limit, longest_line_expiry becomes the later of itself and expires_at, and a pending withdrawal's unlock_at moves later if the new expiry requires it (§6.5). The line is initialized and CoreEvent kind 5 (line_opened) is emitted with the limit as its amount.

The fixed part of the layout runs from the discriminator through expires_at at offset 161. pending_limit starts at offset 169, and the fields after it follow the Option encoding. The account is allocated at 302 bytes. At the rent formula (size + 128) × 3,480 × 2 lamports [28], that is 2,992,800 lamports, paid by the admin. Lines are never closed: a line is a persistent record whose replay floors (maximum_nonce, settled_cumulative, retired_cumulative) must outlive any one epoch.

reserved_lines equals the sum of limit over the bond's lines at all times. Opening adds the limit, a raise adds the difference, an applied decrease subtracts it, and nothing else writes either side. Expired lines stay in the sum until their limits are decreased, so reserved exposure is never understated.

Expiry and renewal

A line's expiry bounds every voucher on it: settle_tab requires the voucher's expiry to be no later than expires_at and the judgment time to be before it (§5.6). It also bounds the bond's withdrawal cooldown (§6.5). Expiry can only move later. renew_line(expires_at) requires the vault not frozen, no active default, the operator's collateral not locked by a freeze, an expiry after now and no earlier than the current one, and coverage at the current reservation. It sets the new expiry, moves the line into the bond's current default epoch, raises longest_line_expiry and any pending unlock_at as open_line does, and emits kind 17. Limit, key, fee, opened_at, freeze generation and every replay floor stay as they were, so a renewed line cannot collect old debt a second time.

The default epoch is how a default retires lines. When a default opens, bond.default_sequence advances and every line's opened_default_sequence falls behind. Those lines can no longer settle and can only claim against that default: settle_tab refuses them with LineExpired, and only renew_line brings a line into the new epoch once the default is paid (§7.1).

6.3 The coverage ratio

The coverage ratio is the bond's collateral divided by the exposure it backs. The program enforces it as an exact integer inequality, with u128 products and no division, at every point where exposure grows or collateral leaves.

The first line is the program's check, coverage(balance, reserved, minimum). The second is the published figure. calculateCoverageRatio(bondBalance, lineLimits, minimumBps) in the shared contract package returns the floored basis points, or null when there are no lines, together with meetsMinimum, which is the same inequality as the program's. The API computes it with collateral net of any pending withdrawal, the same figure the program uses for new exposure. The third line is the most exposure a given collateral admits.

The unchecked instructions either raise collateral, lower exposure, or pay out what the bond already owes. A default payout can leave coverage below the minimum. The bond then accepts no new line, raise, renewal or withdrawal until collateral is posted or reservations are decreased.

The operator's minimum

minimum_coverage_bps is chosen once, at create_operator, and no instruction changes it. The program's floor is COVERAGE_FLOOR_BPS = 3,300 (33%). The field is a u16, so a minimum can go up to 65,535 bps (655.35%) for an operator that wants to publish more than full collateral. COVERAGE_DEFAULT_BPS = 10,000 (100%) is the value the transaction builder writes when the operator does not choose one. At 10,000 bps the sum of limits can never exceed the collateral. At the 3,300 floor it can reach ⌊collateral × 10,000 ÷ 3,300⌋, about 3.03 times the collateral: a bond of 25,000,000,000 base units (25,000 USDC) can back at most 75,757,575,757 base units of limits.

A line that would take coverage below the operator's minimum is not opened. open_line fails with CoverageTooLow (program error 6005, "Coverage would fall below the operator minimum."), the transaction writes nothing, and the API's preparation, which simulates every transaction before returning it for signing, reports COVERAGE_TOO_LOW before anything is signed.

Worked example

Example. An operator posts 25,000 USDC, the per-bond cap, and chose a minimum of 5,000 bps (50%). Amounts are in USDC; the program compares the same quantities in base units, each side scaled by 10⁶.

After step 9 the pending 1,000 USDC no longer counts as collateral for new exposure, so the published ratio is 24,000 ÷ 48,000. The bond is at its minimum, and any further line or raise fails until the operator posts more or decreases a line.

The ratio is the share of its limit each merchant would recover if every line claimed its full limit at once, and the published figure is a lower bound on that share. Opening a default cancels the pending withdrawal (§6.5), so here the pool would be the full 25,000 USDC against eligible claims of 48,000 USDC, and each claim would receive ⌊pool × eligible ÷ total⌋, about 52% of its limit (§7.3). At 10,000 bps or more, every claim up to its limit is paid in full.

6.4 resize_line

resize_line(limit) is signed by the admin and changes one line's limit. Raises take effect at once. Decreases take effect only after a 72-hour notice, DECREASE_DELAY = 259,200 seconds, which is visible on chain from the moment it is scheduled. Any call fails with DefaultActive while a default is open on the bond.

A matured decrease is also applied by the next settle_tab on the line that passes its voucher checks, provided the vault is not frozen and the operator's collateral is not locked, so it does not wait for the admin to repeat the call. The decrease is applied before the delta is compared with the limit. Decreases carry no expiry check, so an expired line can release its reservation through the same schedule.

Why decreases wait

A merchant extends credit against the limit it reads. An instant decrease could cut a line below what the merchant had already served, and in a default the merchant's claim is capped by the limit. The notice period protects the credit already extended in three ways:

• The merchant sees the change coming. pending_limit and its effective_at are public. The middleware and the agent SDK both use the lower value from effective_at onward, even before the chain applies it (§5.4), and in the meantime the merchant settles its outstanding vouchers so that what it is owed fits the new limit.
• The reservation stays. reserved_lines keeps backing the old limit until the decrease applies. The operator cannot free collateral for a withdrawal or another line by announcing a decrease.
• A default judges the limit at its opening. When the operator's collateral was not locked at opening, a claim is measured against effective_limit_at(opened_at), the limit in force when the default opened, with a pending decrease counted only if it had already matured. When the operator's collateral was locked by a freeze at opening, or a freeze reference applies, the claim uses the stored limit. An unapplied decrease never reduces it (§7.2).

A raise reduces nothing a merchant relied on. It is checked for coverage at the moment it applies, so it needs no notice. A line's voucher key follows the same 72-hour schedule for the same reason: the merchant must be able to see it change before it does (§5.9).

6.5 Bond withdrawals

Collateral leaves the bond in two steps, request_withdrawal(amount) and finalize_withdrawal(), separated by a cooldown that outlasts every default the bond's current lines could still open. The unlock time is fixed by a formula, not chosen by the operator:

With the parameter files' margin, unlock_at is 345,600 seconds (96 h) after the later of the request time and the longest line expiry.

request_withdrawal(amount)

The admin signs. The program requires the operator's collateral not to be locked by a freeze, meaning no frozen vault and the time past recourse_lock_until (FrozenRecourseActive). It also requires no active default (DefaultActive), no pending request (WithdrawalExists), 0 < amount ≤ balance (InvalidAmount), and coverage with balance − amount against the current reservation (CoverageTooLow). It stores {amount, requested_at: now, unlock_at} and emits kind 13. From then on the requested amount is excluded from the collateral that backs new lines, raises and renewals (§6.3).

finalize_withdrawal()

The admin signs and names the destination token account, which may belong to any wallet but must hold the configured USDC mint under classic SPL Token. The program again requires no freeze lock and no active default. It requires a request (NoWithdrawal), now ≥ unlock_at (WithdrawalCoolingDown), and coverage with balance − amount. It then transfers amount from the bond's token account, signing as the bond PDA, lowers balance and the protocol total, clears the request and emits kind 14.

Why the formula prevents an exit ahead of a default

A default against the bond opens only inside settle_tab, for a voucher judged valid on a line of the current epoch at a validation time before that line's expires_at (§5.6). Unless a freeze reference applies, the validation time is the moment the default opens. Every default the current lines can open therefore opens before longest_line_expiry, a high-water mark the program never lowers. A default opened at time t accepts claims until t + CLAIM_WINDOW, so the latest claim window the current lines can produce ends before longest_line_expiry + CLAIM_WINDOW, and unlock_at lies at least withdrawal_margin_seconds beyond that. The margin is positive, so the boundary is strict. The freeze-reference case is covered below.

Three further rules close the remaining paths:

• A default cancels the request. When settle_tab opens a default it sets bond.withdrawal = None, so a request made before the default can never be finalized after it. The operator requests again once the payout completes, against the residual balance and with a newly computed unlock time.
• An open default blocks both steps. While active_default_sequence is set, request_withdrawal and finalize_withdrawal fail with DefaultActive, and the pool the claims share cannot shrink before the payout snapshot.
• New exposure extends the cooldown. open_line and renew_line raise longest_line_expiry and push a pending unlock_at later by the same formula, so a line added during the cooldown is covered by it.

A frozen vault can open a default after its expiry, through the line's freeze reference. That path is guarded by the collateral lock: while any of the operator's vaults is frozen, and until recourse_lock_until after unfreeze (the unfreeze time plus freeze_grace_seconds plus 72 h), neither withdrawal step runs (§3, §7). The program does not try to prove that a line's exposure ended early. A line decreased to zero still holds longest_line_expiry where it was, and the cooldown waits for the latest expiry the bond has ever recorded.

Example. A bond's lines expire 30 days from now, and the operator wants all of its collateral back. Times are in days from now, and the margin is the parameter files' 24 hours.

A full withdrawal needs the reservations released first, because request_withdrawal checks coverage with balance − amount against reserved_lines. Between day 0 and day 3 the old limits still apply. A settlement that found a vault short in that interval would have opened a default against the full bond, and no request could have been made until its payout completed. From day 3 the limits are zero, so no voucher can pass the delta check. The cooldown still runs to day 34, because the high-water mark stays at day 30.

6.6 Public coverage as the merchant's credit signal

A merchant decides whether to accept a line, and how much to serve on it, from public state. Every figure below is an account field written only by the program, or a value derived from one, and anyone can read it. The API publishes an operator's aggregates as a public profile, PublicOperatorProfile { operator, coverage, lineCount, totalLineLimit }, and returns that profile with every line a merchant views.

The counters are the operator's record. They live in the Operator PDA, which is derived from the admin key and cannot be transferred, and settle_tab is the only instruction that writes them: tabs_settled increments in every healthy settlement, and defaults_count in every settlement that opens a default. The operator has no instruction to set or reset either one.

Coverage is a property of the whole bond, not of one line, because every line on the bond shares one payout pool. A merchant's recovery in a default is the smaller of what it is owed above the floor and its own limit, scaled down pro-rata when the bond's claims exceed its balance (§7.3). The total limit of all lines is therefore part of each merchant's terms. Lines are public accounts, so a merchant sees every other line that would share the pool, including lines the operator opens after the merchant's own. The program then enforces the published minimum on every future change: whatever lines are added, coverage cannot fall below minimum_coverage_bps through open_line, resize_line, renew_line or a withdrawal. A merchant that reads a minimum of 5,000 bps knows that new lines, raises and withdrawals can bring coverage down to 5,000 bps and no further. Only a default payout takes it lower. reserved_lines keeps counting expired lines until their limits are decreased, so the published ratio errs low rather than high.

The middleware applies the operational part of this signal on its own. It refuses new credit on a line whose vault is frozen, whose line has expired or been retired by a default, or whose limit, effective decrease included, would be exceeded (§5.5). Beyond that, the ratio, the counters and the line terms are the inputs to the merchant's own decision to extend credit.

7. Defaults and claims

A tab is credit the merchant extends. The merchant serves requests first and collects later, against cumulative vouchers the agent's session key signed, and the vault pays each settlement. The default path handles the one case where the vault does not pay: settle_tab finds less USDC in the vault than the voucher asks for, or finds the vault frozen past its grace period. From that moment the bond pays instead of the vault, and it pays every line holder of that bond under one formula instead of whichever merchant reaches the program first.

Four instructions carry the path. settle_tab opens a DefaultEvent. During a fixed claim window each line holder calls file_claim with its latest voucher. After the window anyone calls execute_default_payout, once per claim, and the bond pays each claim its eligible amount in full, or pro-rata when the claims together exceed the bond. If no one filed, finalize_empty_default closes the event. Every step is decided by signatures, stored account state and the cluster clock. No step asks anyone for a judgment, so the outcome of a default can be computed in advance from public accounts, and anyone can drive it to completion.

7.1 When settle_tab finds the vault short

settle_tab(default_sequence: u64, ed25519_ix_index: u16) is signed by the merchant that holds the line; §5.6 describes its healthy path in full. The instruction immediately before it is an Ed25519 precompile instruction carrying the 96-byte voucher (§5.2), the key that signed it and the signature. The program reads that instruction through the instructions sysvar and accepts only the canonical 208-byte form with the fixed offsets header, so the voucher it evaluates is exactly the one the runtime verified.

The handler runs its checks in a fixed order, and the vault balance is the last thing it looks at:

1. The voucher is decoded, bound to this line and to the protocol's voucher domain, and its signer is checked against the line's voucher key. For a frozen vault, the key and validity are judged at the line's freeze reference instead of the current time.
2. If the vault is frozen, its accumulated frozen time in the current freeze episode must have reached freeze_grace_seconds, otherwise the call fails with VaultFrozen.
3. The bond has no active default (DefaultActive), and default_sequence equals bond.default_sequence + 1 (InvalidDefault).
4. The line belongs to the bond's current epoch, line.opened_default_sequence == bond.default_sequence, and has not expired at the validation time (LineExpired).
5. The voucher's expiry lies after the validation time and no later than the line's expiry (VoucherExpired).
6. Both the nonce and the cumulative amount advance past the line's replay floors (VoucherReplay).
7. A pending limit decrease that has matured is applied, provided the operator's collateral is not locked by a freeze.
8. The amount the voucher adds, delta, must fit within the line limit (LineLimitExceeded).

Only then does the program compare the vault's token balance with delta.

Because every validity check runs before the balance comparison, only a voucher that would have been payable can open a default: correctly signed, unexpired, advancing, and within the line limit. A merchant cannot turn a voucher the vault would have refused for another reason into a claim on the bond.

What moves

On the healthy path the vault transfers delta − fee to the merchant and fee to the fee treasury, the line records the voucher as settled, and the operator's tabs_settled counter increments. On the default path no USDC moves at all. The vault keeps its balance, the line keeps its settled amount, and the instruction writes the event instead.

There is no partial settlement. If the vault paid part of a delta, the first merchant to settle against a draining vault would take what remained and the next would meet an empty account, and the line would record a settled amount that no voucher states. Opening the event instead removes the race: every line holder of the bond becomes a claimant on the same terms, and only the bond takes part in the payout. The vault's remaining balance stays in the vault.

The forced path exists for a frozen vault. A frozen vault cannot transfer, so while the freeze lasts the bond is the only source that can pay a line holder. settle_tab therefore takes the default branch whatever the balance, once the vault has spent freeze_grace_seconds frozen within its current episode. The beta parameter files set 345,600 seconds (96 hours), and the program refuses any configured value below that floor. Before the grace has run, the call fails with VaultFrozen and the operator has time to unfreeze and settle normally.

A pending bond withdrawal is cleared when the default opens. Its amount was checked against the balance before the default, and after payout the residual may be smaller than the request, so the request would otherwise block a valid new one. The operator can request again once the event is paid.

The sequence number

DefaultEvent lives at the PDA [b"default", bond, sequence], with the sequence as a little-endian u64. The merchant passes default_sequence as an instruction argument because Anchor derives the account address from it, and the program requires it to equal bond.default_sequence + 1. The event address is therefore the bond's next unused sequence number, and no caller can open an event at any other address. The builder computes it from the indexed bond.

The account is declared init_if_needed with the merchant as payer, so every settle_tab transaction carries it. On the healthy path the program closes it again at the end of the same instruction and returns its 1,976,640 lamports of rent to the merchant; the placeholder never outlives the transaction, and its opened_at stays zero. On the default path the program fills it and keeps it. The merchant whose settlement opened the default has funded the public record of that default.

bond.default_sequence is also the bond's epoch counter. Each CreditLine stores opened_default_sequence, the epoch it was opened or last renewed in. When a default opens and the counter advances, every line of the bond falls one epoch behind. settle_tab rejects such a line with LineExpired, resize_line refuses to raise it, and only renew_line brings it into the new epoch. file_claim accepts a line only when line.opened_default_sequence + 1 equals the event's sequence. The lines a default retires are exactly the lines that may claim against it, and a line renewed afterwards cannot claim against an old event.

While active_default_sequence is set, the bond is closed to change: open_line, resize_line, renew_line, request_withdrawal, finalize_withdrawal and further settle_tab calls on that bond all fail with DefaultActive. The pool the claims will share cannot be diluted by a new line or reduced by a withdrawal while the window is open.

eligibility_at records the validation time the opening voucher was judged at: the current time, or the line's freeze reference for a frozen vault. collateral_locked_at_open records whether the operator's collateral was locked by a frozen vault or an unfreeze tail when the event opened. The flag decides which limit each claim is measured against (§7.2) and cannot change after opening, whatever happens to the freeze later.

7.2 The claim window and file_claim

The claim window is a compiled constant, CLAIM_WINDOW = 72 × 60 × 60 seconds, 259,200 seconds or 72 hours. The deployment parameter files carry the same value and the deploy script refuses a file that differs from the compiled constant. A claim is accepted while now < window_end; at window_end the window is closed.

The window has two jobs. It gives every line holder time to see the event and file, and it fixes the moment after which the set of claims can no longer change, so the payout can be computed from a closed list. Merchants do not need to watch the chain by hand: the merchant middleware's worker discovers open defaults on its lines and files the newest eligible voucher it holds.

The same 72 hours sits inside the bond's withdrawal unlock, which is what keeps an operator from leaving ahead of a default:

A withdrawal requested today cannot complete until every voucher on every line of the bond has expired and a full claim window has passed after that. Opening or renewing a line extends a pending request's unlock to match. §6 describes bond withdrawals and their cooldown.

Who files, and with which voucher

file_claim(ed25519_ix_index: u16) is signed by the merchant. The line is the PDA [b"line", bond, merchant] with has_one constraints on bond, merchant and vault, so only the holder of a line on this bond can file, and only for its own line. The merchant whose settlement opened the default files like everyone else: settle_tab records the event, not a claim.

The voucher arrives the same way as in settle_tab, as the canonical Ed25519 instruction immediately before file_claim. The merchant files its latest voucher, the one with the highest cumulative amount. The program checks, in order:

Validity is judged at the moment the default opened, not at the moment of filing. A voucher that was valid when the vault came up short stays claimable for the whole window even if its own expiry passes during the window. An outgoing voucher key from a line-key rotation remains usable only up to the nonce and cumulative ceilings the merchant attested during the rotation notice (§5.9).

Claims against a frozen vault

A freeze, by the guardian or the admin, stops every transfer out of the vault (§3.7). Vouchers keep their expiry while the vault sits frozen, so judging them at the opening time alone would let a long freeze run out the clock on debt the vault was prevented from paying. The program therefore lets a claim be judged at the line's freeze reference instead, under conditions it checks from immutable accounts:

• Every real freeze creates a FreezeCheckpoint at [b"freeze", vault, generation] recording its freeze time, its episode and the operator's defaults_count at that moment. Unfreeze writes the end of the freeze and of its recourse tail once.
• The claim supplies an activity checkpoint proving that the freeze episode was still in force when the default opened: a freeze that began before the opening, whose interval or recourse tail covers the opening, and whose recorded defaults_count is below the event's sequence. A freeze that happened after the default, even in the same second, cannot qualify. Passing the program ID instead disables the exception.
• The reference is the first checkpoint the line lived through in that episode, max(line.freeze_generation_at_open + 1, episode start), or for a later voucher key, the earliest checkpoint of the episode at which that key was in force.

A voucher authorized and unexpired at that reference is eligible. The claim's limit snapshot is then the stored line.limit, as it is for every claim on an event opened while collateral was locked, because the freeze lock prevented the operator from applying any pending decrease. §12.7 describes the freeze path from the guardian's side.

One claim per line

The claim is the PDA [b"claim", default_event, merchant]. A bond has one line per merchant, so an event has at most one claim per line. Filing a second time does not add a claimant; it replaces the filed voucher, and only with one that has both a higher nonce and a higher cumulative amount. The program subtracts the old eligible amount from claims_total and adds the new one. claim_count increments only on the first filing.

Two snapshots are fixed at the first filing and never move:

• settled_snapshot = max(line.settled_cumulative, line.retired_cumulative), the part of the voucher the vault or an earlier default has already resolved.
• line_limit_snapshot, the limit the claim is measured against. In the ordinary case it is the limit in force at opened_at, so a pending decrease whose effective_at had passed by the opening counts. When the claim supplies a freeze reference, or the event recorded collateral_locked_at_open, it is the stored line.limit, because a decrease the operator could not apply while collateral was locked cannot reduce what the merchant is owed.

The merchant pays the claim account's rent, 2,074,080 lamports for 170 bytes, and receives it back when the claim is paid. Each filing emits ClaimFiled with the full snapshot and CoreEvent kind 10, so an indexer that starts after the claim has closed can still reconstruct it.

7.3 execute_default_payout

execute_default_payout() takes no arguments and requires no signer in its account list. Anyone may submit it once now ≥ window_end; before that it fails with ClaimWindowOpen. Each call pays exactly one claim, named by its accounts: the claim, its line, its merchant and a token account the merchant owns for the configured mint. Every one of those is bound by a constraint: the claim's seeds and has_one links, the line's seeds under the bond, merchant equal to claim.merchant, and merchant_token.owner == claim.merchant. The submitter chooses only when the claim is paid, never where the USDC goes or how much.

The first payout of an event takes the snapshot. It sets snapshot_taken, copies the bond's tracked balance into payout_pool and claims_total into eligible_total_snapshot. Every payout of the event, including the first, then computes its claim's amount from those two fixed numbers:

The multiplication runs in u128, so P × eligible_amount cannot overflow, and the division floors. Rounding is therefore always downward, per claim, and the base units the floors drop stay in the bond. In the pro-rata case each floor drops less than one base unit and the exact shares sum to P, so the residual is a whole number below the number of claims. Because every claim's amount depends only on P, E and its own eligible_amount, the result is the same in whatever order the claims are paid, and one claim per instruction is enough: no instruction needs to see the whole list.

The off-chain contract computes the same numbers. calculateDefaultPayout in the shared domain package takes the bond balance and the claims, applies min(max(voucher − settled, 0), limit), sets proRata when the eligible total exceeds the balance, floors each share and reports the residual with the rounding rule floor_each_claim_residual_stays_in_bond. The program's payout function and the TypeScript function are tested against the same vectors.

The pool is the bond's tracked balance, not the raw balance of its token account. Only post_bond adds to the tracked balance; USDC sent to the bond's token account by a plain transfer is not booked collateral and does not join the pool. The vault does not join it either.

What one payout writes

In one instruction the program:

1. transfers payout from the bond's token account to the merchant's token account, signed by the bond PDA;
2. subtracts payout from bond.balance and from the protocol-wide total_bond_balance that enforces the beta cap;
3. marks the claim paid with paid_amount = payout;
4. advances the line's retired_cumulative to the claim's full voucher_amount and its maximum_nonce to the claim's nonce;
5. adds payout to total_paid, increments processed_claims, and emits CoreEvent kind 11;
6. closes the claim account and returns its rent to the merchant.

When processed_claims reaches claim_count, the same instruction sets paid, clears bond.active_default_sequence and emits CoreEvent kind 12 with the event's total. The bond is open to change again.

Step 4 retires the whole voucher, including any part a pro-rata payout did not cover. The written-off fraction becomes part of the line's replay floor, so no later settlement or default on that line can collect it again, even after renew_line brings the line back into service. A second submission for a claim already paid transfers nothing: the claim account no longer exists, and if a retained one is passed, the handler returns early on claim.paid.

When the pool covers everything

Whether a default pays in full is decided before it happens, by the coverage the operator chose. open_line, limit increases, renew_line and both withdrawal steps all require collateral × 10 000 ≥ reserved_lines × minimum_coverage_bps, where collateral is the tracked balance less the pending (or requested) withdrawal amount and reserved_lines includes the limit of every line that can claim. Every eligible amount is capped at its line's limit. At the v0 default minimum of 10,000 bps the lines that can claim therefore never sum to more than the bond, and every claim is paid in full. Pro-rata payment occurs only on a bond whose operator set its minimum below 10,000 bps, down to the floor of 3,300, and that minimum is public before any merchant extends credit.

An event no one claimed

If the window closes with claim_count == 0, there is nothing for execute_default_payout to pay. finalize_empty_default() is permissionless as well: after window_end it sets the snapshot fields, marks the event paid, clears the bond's active default and emits CoreEvent kind 12 with a zero total. The bond keeps its whole balance.

7.4 Worked examples

Both examples use dollar figures written in USDC and are carried out in base units, as the program computes them. They are examples, not measurements.

One claimant, paid in full

An operator posts a 10 USDC bond and opens one line of 10 USDC for a merchant that charges 0.25 USDC per request, so coverage is 10,000 bps. The agent makes 40 requests and signs a voucher with each; the last one states a cumulative 10,000,000 base units. The merchant settled once after 16 requests, so settled_cumulative is 4,000,000. The operator then draws the vault down to 2,500,000 base units.

The merchant receives every base unit the agent vouched for and the vault had not paid. The line's retired_cumulative becomes 10,000,000, and the operator's record shows one default.

Five claimants, paid pro-rata

The second example is the five-line bond the site's default passage shows. One bond of 900 USDC backs five lines whose limits sum to 1,500 USDC, a coverage of 6,000 bps, which the operator's minimum allows. At time T the inference API settles its newest voucher: cumulative 1,880 USDC against 1,500 settled gives a delta of 380 USDC, within its 400 USDC limit. The vault holds less than 380 USDC, so the default opens and nothing moves. All five merchants file within the window.

Amounts other than the payout column are in USDC. The first payout snapshots P = 900,000,000 and E = 1,140,000,000. Since E > P, each claim receives ⌊ 900,000,000 × eligible ÷ 1,140,000,000 ⌋, which here equals ⌊ eligible × 15 ÷ 19 ⌋:

• inference API: 380,000,000 × 15 ÷ 19 = 300,000,000 exactly.
• data API: 4,500,000,000 ÷ 19 = 236,842,105 remainder 5.
• RPC provider: 1,800,000,000 ÷ 19 = 94,736,842 remainder 2.
• GPU rental: 3,750,000,000 ÷ 19 = 197,368,421 remainder 1.
• search API: 1,350,000,000 ÷ 19 = 71,052,631 remainder 11.

The remainders sum to 19 nineteenths, which is the single base unit left in the bond: residual = 900,000,000 − 899,999,999 = 1. Every merchant receives 15/19 of its eligible amount, rounded down to the base unit, whichever order the keeper processes them in.

The data API's unsettled 350 USDC exceeds its 300 USDC limit. The bond's liability on a line ends at the line's limit, so the 50 USDC above it is outside any claim. The column on the right is the part of each eligible amount the pool could not cover; each line's retired_cumulative moves to the full voucher amount (1,880, 950, 420, 610 and 290 USDC), so none of it can be collected again on the same line.

7.5 The keeper's part

The payout needs a transaction after window_end, and someone has to send it. That role is the keeper's, and the program grants it no authority: execute_default_payout and finalize_empty_default have no signer constraint, every account they touch is fixed by the event and its claim, and the only choice left to the submitter is timing. Any key can run the keeper, any merchant can pay its own claim with the same instruction, and replacing the keeper changes nothing about who is paid or how much. The deployment requires no keeper registration.

Bonded's keeper worker runs in passes. In each pass it:

1. reconciles the chain projection and reads the indexer cursor's last block time; the keeper decides what is due by chain time, not by its own clock;
2. queues every default event that is not paid and whose window_end has passed, and every escrow whose deadline has passed (§8.4);
3. for each due event, takes a 60-second lease on the event's job, lists its unpaid claims in address order, and plans one claim per legacy transaction, or one finalize_empty_default for an event with no claims;
4. for each claim, keeps a persisted attempt record. If an earlier attempt was submitted, it checks its status and rebroadcasts the identical signed bytes instead of signing anew; if it confirmed, it marks the attempt done;
5. otherwise prepares execute_default_payout, refuses to sign unless the live simulation succeeds, signs, submits, and records the signature;
6. after the claims, marks the event's job done if the indexed event is paid, or requeues it.

Failures are local to one claim. A failed attempt goes to retry with a backoff of min(60 s, 1 s × 2^min(attempts, 6)), and the other claims of the event and other events proceed. A merchant whose token account cannot receive does not delay anyone else's payout. The keeper can also be given a merchant-chosen replacement destination; the program still checks that its owner is the claim's merchant and its mint is the configured USDC mint.

§11.3 describes how the worker is deployed. The builder places an idempotent associated-token-account creation for the merchant before the payout when no replacement destination is given, paid by the transaction's signer. A keeper therefore spends 5,000 lamports in signature fees per payout transaction and the priority fee of its API-prepared compute budget (1,000 micro-lamports per unit by default), plus the rent for the merchant's associated token account if the merchant does not yet have one. In the local development stack the keeper runs every 500 milliseconds against the local bank with a local key.

7.6 What the operator's record shows afterwards

A default leaves a permanent, public trace in the operator's accounts, and the trace is written by the program, not reported by the operator.

Operator.defaults_count increments in the instruction that opens the default, in the same step as bond.default_sequence. The counter records that the vault came up short, whether the bond then covered every claim or not. tabs_settled counts healthy settlements and does not change. The API serves these as the operator's reputation, tabsSettled and defaults, together with daysActive, which the indexer derives from the operator's created_at and the last block time. A merchant can read the record before it extends credit on a line.

After the last payout of the five-claimant example, the accounts read:

The paid DefaultEvent stays on chain as the public record of the default: its pool, its denominator and the total paid. The API reports it as payout_executed with a roundingRemainder equal to payout_pool − total_paid, here 1 base unit.

The lines are retired, not closed. A CreditLine PDA persists for the life of the bond, one per merchant, and keeps its watermarks; the API reports each as defaulted. Their limits stay in reserved_lines, so the bond's public coverage ratio, computed against the limits of its lines, reads 0 bps until the operator acts. Two paths lead out:

• To leave, the operator schedules each line's limit down to zero with resize_line and applies the decreases after the 72-hour delay, which frees reserved_lines, then withdraws the residual through request_withdrawal and finalize_withdrawal on the usual unlock.
• To continue, the operator posts new collateral with post_bond and calls renew_line, which must pass the coverage check against the new balance and moves the line into the current epoch while keeping its replay floors, so nothing already resolved can be claimed again.

request_withdrawal checks coverage against every reserved limit, retired lines included, so the residual leaves the bond only after the reservations it no longer backs have been decreased.

8. Escrow

Escrow is the lane for jobs that are paid before they are delivered: a compute run, a dataset, a service with a turnaround. Here the exposure runs the other way from a tab. The agent pays first, and the merchant may never deliver. On a stablecoin rail a payment is final, so the payer has no chargeback to fall back on.

The escrow lane closes that gap without asking anyone to judge whether a job was done well. The agent's payment goes into a token account owned by the program, bound to a quote the merchant signed, and it leaves only on objective events: a delivery mark before the deadline, a dispute window that lapses, a decision by the arbiter the quote named, or a deadline that passes with nothing. If no delivery mark arrives by the deadline, anyone can return the whole payment to the vault.

Eight instructions make up the lane: pay_escrow funds a job; mark_delivered records delivery; accept and release_after_window pay the merchant; dispute and resolve route a contested job to its arbiter; refund_on_timeout and refund_after_resolution_deadline return the payment. Every one of them except accept checks the clock against a deadline determined by the quote, a program constant or the configuration snapshotted at funding.

8.1 The merchant-signed quote

A quote is the merchant's offer for one job: the price, a hash of what will be delivered, the delivery deadline, the arbiter if there is one, and how long the offer stands. The merchant signs it, and the program will fund an escrow only against a quote whose signature it has verified. The price, the deadline and the arbiter therefore come from the merchant's signature, never from the agent's arguments. A decimal slip in the agent or an injected instruction cannot change the amount, and the merchant cannot later claim it offered different terms.

The quote is a fixed 169-byte message, little-endian, with a context tag that binds it to one program on one cluster.

The tag uses the same derivation as the voucher domain with its own prefix, so a quote signed for a devnet deployment, or for another program, is refused on mainnet-beta, and a quote cannot be replayed as a voucher or an approval. The lane byte separates quotes for an immediate program pay (lane 0) from quotes for escrow (lane 1); each instruction accepts only its own lane. The off-chain encoder writes an absent arbiter as 32 zero bytes and rejects an explicit all-zero arbiter key, so "no arbiter" has exactly one encoding.

quote_hash, the SHA-256 of the full message, is the quote's identity. It seeds the Escrow PDA, it seeds the persistent QuoteReceipt that makes the quote single-use, and the payment intent commits to it.

The signature check

The merchant's Ed25519 signature is verified by the native Ed25519 precompile in the instruction immediately before pay_escrow. The program does not trust the precompile's presence alone; it loads that instruction through the instructions sysvar and requires its exact canonical form.

The header encodes one signature whose key, signature and message all lie inside this same instruction (index 0xFFFF) at offsets 16, 48 and 112, with a 169-byte message. The instruction must belong to the Ed25519 program, reference no accounts, and sit at index current − 1, where current is pay_escrow itself. Foreign offsets, a second signature, or a proof elsewhere in the transaction are refused with InvalidPrecompile. The measured proof instruction is 281 bytes, and the pay_escrow instruction data is 82 bytes.

After decoding, verify_quote requires every field to agree with the transaction:

The API accepts the quote as a QuoteInput: quoteHash, amount, specificationHash, deliverBy, arbiter, expiresAt, and the merchant's signature and message in base64. Before it builds a transaction, the API decodes the message, recomputes the hash, compares every field with the DTO, checks vault, merchant and lane, and verifies the signature. The on-chain checks above then repeat the decisive ones against the bytes the runtime verified.

8.2 pay_escrow and the Escrow account

pay_escrow(amount: u64, quote_hash: [u8; 32], intent_hash: [u8; 32], ed25519_ix_index: u16) is signed by the vault's session key, which also pays for the accounts the instruction creates. The merchant must already be allowlisted for the vault: the instruction requires the MerchantRule at [b"rule", vault, merchant], and every limit in that rule and in the vault policy applies to the escrow exactly as to a direct payment.

The handler runs in this order:

1. Reads the protocol's escrow configuration. escrow_fee_bps, maximum_escrow_fee_bps and a positive escrow_resolve_seconds must all be set, and the fee must not exceed its maximum; otherwise InvalidConfiguration. Escrow funding is refused until governance has configured both the fee and the resolution duration.
2. Computes fee_amount = ⌊ amount × fee_bps ÷ 10 000 ⌋ and total_debit = amount + fee_amount (§8.7).
3. Verifies the quote and its deadline (§8.1).
4. Recomputes the payment intent and requires it to equal intent_hash (ApprovalMismatch).
5. Books the spend against the vault's policy with total_debit as the amount, through the same routine as pay (§3.4): vault not frozen, window reconciled, merchant allowlisted, total_debit ≤ per_transaction_cap, merchant window budget, vault window budget including outstanding float allowance (§4), and a co-signer approval when total_debit exceeds the threshold (§8.6).
6. Refuses a quote whose QuoteReceipt is already used (PaymentReplay), then writes the QuoteReceipt, the PaymentReceipt and the Escrow.
7. Transfers total_debit from the vault's token account to the escrow's token account, signed by the vault PDA.
8. Emits PaymentCommitted and an EscrowEvent snapshot that carries the 169-byte quote and the merchant's 64-byte signature.
9. Closes a consumed approval to its original rent payer.

The intent is the single hash that every authorization of this payment refers to. It commits to the vault, the merchant, the full debit including the fee, the quote nonce, the quote itself and the lane. It seeds the PaymentReceipt at [b"payment", vault, intent_hash], which is created with init and never closed, so the same intent can be paid at most once. The quote has its own persistent receipt at [b"quote", vault, quote_hash], so the same quote cannot fund a second escrow under a different fee or intent. The Escrow itself is the PDA [b"escrow", vault, quote_hash].

pay_escrow creates up to four accounts, all paid by the session key:

Rent is (size + 128) × 3,480 × 2 lamports; §10.5 shows the computation. The escrow token account is created with init_if_needed under the associated-token constraints, so a correctly precreated account is accepted.

The escrow token account's authority is the Escrow PDA, and the program signs for it with the seeds [b"escrow", vault, quote_hash, bump] only inside the handlers of §8.3. No private key controls it: not the session key that funded it, not the operator's admin, not the merchant, and not the protocol's upgrade authority, which can't move even the fee treasury. The escrowed USDC can leave by exactly two routes, release to the quote's merchant or refund to the paying vault, and the state machine decides which.

Three values are snapshots taken at funding: fee_bps with its fee_amount, and resolve_seconds. A later governance change to the fee or the resolution duration applies only to escrows funded afterwards. A job's cost and its recourse are fixed at the moment the payer commits.

specification_hash comes from the quote and deliverable_hash from the merchant's delivery mark. The program stores both and does not compare them: the hashes are commitments the parties and an arbiter can check against the actual specification and output off chain, and each transition's EscrowEvent preserves them after the account closes.

8.3 The state machine

The program keeps five states in Escrow.state: funded (0), delivered (1), disputed (2), released (3) and refunded (4). Acceptance and resolution are instructions, not states: accept moves a delivered job to released, and resolve moves a disputed job to released or refunded. Released and refunded are terminal. The handler that reaches either one closes the escrow token account and the Escrow account in the same instruction, so a terminal state is never stored in a live account; it survives in the final EscrowEvent snapshot and in the PaymentReceipt, whose outcome becomes 1 (merchant paid) or 2 (vault refunded) with completed_at set.

Every transition, with who may sign it and when:

Any other instruction in any state fails with StateTransitionNotAllowed, a wrong signer with ActorNotAllowed, an early call with DeadlineNotReached, a late one with DeadlinePassed, and a dispute or resolution without an arbiter with ArbiterRequired. The off-chain contract carries the same table as ESCROW_TRANSITIONS, and checkEscrowTransition evaluates state, then actor, then arbiter, then deadline. The program's own order differs in places (dispute and accept check the actor before the state, resolve the arbiter before the actor), so a call that breaks two rules may name a different one on chain. The API uses it to report, for each escrow, which actions are open to which role at the indexed chain time.

The principal on the paying side is either the vault's session key or the operator's admin key; the program accepts both for accept and dispute. The agent can accept a delivery as a step of its own workflow, and the operator can step in for a job the agent is no longer handling. The merchant can never accept or dispute its own job, and the permissionless instructions exist only where the outcome is already decided by a deadline: once a deadline has passed, the result does not depend on who sends the transaction.

How a job finishes

Every path to released or refunded ends in one routine. It first requires the escrow token account to hold at least amount + fee_amount, then:

• Release (accept, release_after_window, resolve(true)). The destination must be a classic SPL token account whose owner is escrow.merchant and whose mint is the configured USDC mint. The routine transfers amount to it, then fee_amount to the protocol's fee treasury when the fee is positive, then any surplus above amount + fee_amount back to the vault.
• Refund (refund_on_timeout, resolve(false), refund_after_resolution_deadline). The routine transfers the escrow token account's entire balance to the vault: principal, the reserved fee, and any surplus.

It then closes the escrow token account and the Escrow account, sending both rents to rent_payer, the session key that funded the job, and never to the caller. It writes the outcome into the PaymentReceipt and emits the final snapshot.

Two details keep the refund path unconditional. The merchant's destination account is passed unchecked and deserialized only on release, so a merchant that closes or corrupts its token account can block its own payment but never the vault's refund. And USDC sent to the escrow token account by a plain transfer is returned to the vault rather than left behind, so a donation cannot keep the account from closing.

The record after closure

Closing the accounts on every terminal outcome keeps finished jobs from holding rent, and it means the chain's account state shows only open jobs. The history lives in events. Every transition emits an EscrowEvent with the complete account snapshot, the actor and the time; the funding event alone also carries the 169-byte quote and the merchant's 64-byte signature, and later events carry zeroes in those fields. The indexer rebuilds each job from this evidence: before it records a funded escrow it decodes the quote from the funding event, checks that vault, merchant, amount, specification hash, deadline, arbiter and hash match the snapshot, and verifies the merchant's signature. A job that closed before the indexer first saw it is reconstructed from the same committed events. The persistent PaymentReceipt and QuoteReceipt remain on chain as the payment's single-use guards and its result.

A refund returns the USDC but does not rewind the vault's window counters or the merchant rule's window spend. The window budget limits what the session key can commit within a window, whatever the outcome, so a job that times out does not grant the agent fresh spending authority inside the same window.

8.4 Deadlines and windows

Four clocks govern a job. Two come from the quote, one is a program constant and one is protocol configuration.

DISPUTE_WINDOW_SECONDS is a compiled constant, 48 × 60 × 60, 172,800 seconds. The resolution duration is protocol configuration: governance sets it with configure_escrow_resolution(resolve_seconds), which requires a positive value, and every escrow snapshots it at funding. The devnet and mainnet-beta parameter files set 259,200 seconds, 72 hours, as does the local development stack.

Each pair of boundaries meets without overlap or gap. At exactly deliver_by the merchant may still mark delivery and the refund is refused; one second later only the refund is possible. At exactly dispute_until the dispute is closed and the release is open. At exactly resolve_until the arbiter's authority has ended and the refund is open. There is no second at which both sides of a boundary are available, and none at which neither is.

expires_at and deliver_by measure different things. expires_at bounds how long the merchant's offer can be taken up; deliver_by bounds the job itself. A merchant can offer a quote valid for an hour on a job due in sixty.

refund_on_timeout stays available after deliver_by for as long as the job is funded, and it needs no signature from the agent. The keeper runs it: each pass, it selects funded escrows with deliver_by before the indexed chain time, delivered escrows at or past dispute_until, and disputed escrows at or past resolve_until, and sends refund_on_timeout, release_after_window or refund_after_resolution_deadline respectively, with the same persisted attempts, leases and retries it uses for default payouts (§7.5, §11.3).

A timeline, as an example

A merchant quotes a job at 340 USDC with deliver_by 60 hours after funding and names an arbiter. The fee at 25 bps is 850,000 base units, so the vault's debit is 340,850,000. Times are hours after funding at t₀.

The longest any of these jobs can hold the vault's USDC is fixed at funding. With delivery on the last permitted second and a dispute on the last second of its window, every path is open to some signer by deliver_by + 172,800 + resolve_seconds, here 60 + 48 + 72 = 180 hours after funding.

8.5 The arbiter and resolve

The arbiter is a key the merchant names in the quote, at bytes 120 to 151. The payer agrees to it by funding: the session key signs pay_escrow for that exact quote hash, and when a co-signer is required, the approval commits to an intent that contains the quote hash. The program places one rule on the choice: the arbiter cannot be the merchant (MerchantCannotArbitrate), since a merchant that could decide its own dispute would make the dispute meaningless. Beyond that the program keeps no allowlist of arbiters, and any key qualifies, a multisig included. Which arbiters an agent accepts is decided by which quotes it funds.

A dispute exists only if an arbiter was named. dispute requires a nonzero arbiter (ArbiterRequired) and can be raised only by the paying side, only on a delivered job, and only before dispute_until. A quote without an arbiter has no party to decide a dispute, so the program does not open one: the principal can accept early, and otherwise the job releases to the merchant when the window lapses. The payer chose a quote that named no arbiter, and the quote's terms decide.

resolve(release: bool) is signed by the arbiter, actor == escrow.arbiter, on a disputed job before resolve_until. Its outcome is binary. true releases the principal to the merchant and earns the fee; false refunds principal and fee to the vault. There is no split: the instruction carries no amount, and every destination it can reach, the merchant's own token account, the vault's token account and the fee treasury, is fixed by account constraints. The arbiter decides which of the two outcomes the quote already defined takes effect, and cannot direct USDC to itself or to any third account.

The resolution deadline bounds the arbiter's role in time. The duration is copied into the escrow at funding, the deadline is set at disputed_at + resolve_seconds, and from resolve_until onwards anyone may call refund_after_resolution_deadline. An arbiter that never answers cannot hold either the principal or the unearned fee indefinitely, and the outcome of its silence is known in advance: the payer gets the full debit back.

8.6 Co-signing above the threshold

The vault policy can name a co-signer and a threshold. book_spend, the policy check pay_escrow shares with pay, requires an approval whenever the vault has a co-signer and the amount booked exceeds cosign_threshold. For escrow the amount booked is total_debit, the principal plus the fee, and the comparison is strict.

The approval is a separate account created in a separate, earlier transaction. A WebAuthn passkey assertion carries authenticator data and client-data JSON besides the signature; the measured passkey approval transaction is 897 bytes and escrow funding with a consumed approval is 1,097 bytes, so one transaction carrying both would exceed the 1,232-byte legacy limit. A separate approval also works with wallets that sign only legacy transactions.

§3.5 describes approvals for every payment lane; the escrow-specific part is what the approval binds. The co-signer signs a 128-byte approval message: an 8-byte tag derived from "Bonded approval v2\0", the vault, the intent hash, the merchant, the amount, the expiry and the vault's current policy_revision. approve_payment verifies an Ed25519 signature through the precompile; approve_payment_passkey verifies a P-256 WebAuthn assertion through the secp256r1 precompile against a registered PasskeyCredential. Either one first refuses an intent whose PaymentReceipt already exists, then creates the Approval at [b"approval", vault, intent_hash], paid by the transaction's payer.

pay_escrow then consumes it only if every bound value matches:

The approval is marked used and closed in the same instruction, its rent returned to whoever paid for it. Because the intent commits to the quote hash, the co-signer has approved one specific job at one specific price including its fee, not a budget the agent may spend as it likes. Any set_policy increments the vault's policy revision and voids every outstanding approval at once.

An approval that is never used does not linger. Once its expiry has passed, or once the vault's policy revision has moved past the one it was signed under, close_approval closes it, signed by any key, and returns the rent to the original payer. The signed revision also keeps an old proof from recreating the approval under a newer policy, and the intent's PaymentReceipt, once it exists, keeps any proof from recreating it after the payment.

The threshold, the per-transaction cap, the merchant budget and the vault's window budget are all checked against the same total_debit, in that one booking step. A job that passes the co-signer can still be refused by a cap, and a job under the threshold is still bounded by every budget. A MerchantRule with quote_required set is satisfied by every escrow, since pay_escrow cannot run without a verified quote.

As an example, take a vault whose co-sign threshold is 100 USDC and a merchant rule with a per-transaction cap of 150 USDC. A 120 USDC job has a 300,000 base-unit fee, a total debit of 120,300,000, and needs an approval. So does a job priced at exactly 100 USDC: its total debit of 100,250,000 exceeds the threshold, because the threshold is compared with what leaves the vault.

8.7 Escrow fees

The escrow fee is charged to the payer, in USDC, on top of the principal, and is earned only when the merchant is paid.

The multiplication runs in u128 and the division floors, so the fee rounds down, in the payer's favour, and never exceeds the configured rate. A principal below 400 base units pays no fee at 25 bps. The merchant receives exactly the quoted principal on release; the fee is never taken out of it.

The fee moves in three steps. At funding it is reserved: pay_escrow debits total_debit from the vault, and the vault's policy counts the fee inside every cap, budget and co-sign threshold. While the job is open it sits in the escrow token account with the principal. At the terminal outcome it goes one of two ways: on release it is transferred to the protocol's fee treasury, and on any refund it returns to the vault with the principal. A job the merchant never delivers, or loses before the arbiter, costs the payer nothing in protocol fees.

Governance sets the rate with configure_escrow_fee(fee_bps, maximum_fee_bps), signed by the program's upgrade authority. Both values start unset, and funding fails until they are configured. The first call fixes the maximum, which may not exceed 10,000 bps; every later call must pass the same maximum, and the fee must not exceed it. pay_escrow checks the fee against the maximum again at funding. The parameter files configure 25 bps with a maximum of 100 bps.

Worked through for the 340 USDC job of §8.4:

The fee treasury, its buyback, and the tab settlement fee are described in §10.

9. Program architecture

Bonded's on-chain side is one Anchor program, bonded. It owns every vault, bond, credit line, default, claim and escrow account; it signs every USDC movement through a program-derived address (PDA); and it checks every off-chain signature (vouchers, merchant quotes, co-signer approvals, passkey assertions) by reading the native precompile instruction placed immediately before it. One program means one audit surface and no cross-program calls between Bonded's own modules. The program has 47 instructions, 15 account types, 10 event types and 61 error codes. This chapter describes how they fit together. Appendix A gives every instruction's arguments, accounts and checks in order, Appendix B every account's byte layout, and Appendix C every error.

9.1 The program

Program ID

The program ID is the declare_id! value in lib.rs. The source carries the local test ID Fg6PaFpoGXkYsidMpWxTWqkZqjc5pNFGWET1AG2LskRa, which the local LiteSVM bank loads directly and Anchor.toml lists for localnet. The ID is set per deployment: a deployment build passes BONDED_BUILD_PROGRAM_ID, the build helper replaces the single declare_id! for the duration of the build, restores the source afterwards and records the ID in bonded-build.json in its output directory (target/deploy/<cluster>/ for a deployment build).

The ID does more than address the code. Every PDA is derived under it, and the four signed message domains (voucher, quote, payment intent, approval) hash it together with the cluster's genesis hash. A voucher signed for one deployment on one cluster cannot verify against another deployment or another cluster (see §5.3).

Source layout

Build

The crate depends on anchor-lang 0.31.1 (with init-if-needed), anchor-spl 0.31.1 (token, associated_token; token_2022 is enabled only so Anchor's IDL generator compiles, while every executable context requires Program<Token>), and serde/serde_json without the standard library, used only to parse WebAuthn client data. npm run build:program runs programs/bonded/build.mjs, which calls cargo-build-sbf with the installed platform-tools v1.52 compiler and the flags --skip-tools-install --no-rustup-override --offline, writing target/deploy/bonded.so. Anchor.toml pins Anchor 0.31.1 and Solana 3.1.14. idl.json is generated from the same sources with the idl-build feature.

Encoding conventions

• Instruction data starts with the first 8 bytes of SHA-256 of global:<instruction_name>; account data with SHA-256 of account:<AccountName>; event data with SHA-256 of event:<EventName>.
• Fields are Borsh, little endian. An Option is a one-byte tag (0 or 1) followed by its value when present.
• Amounts are u64 USDC base units (6 decimals). Account timestamps are i64 Unix seconds; vouchers and quotes carry u64 expiries on the wire.
• Every addition and subtraction on balances, counters and timestamps is checked and fails with ArithmeticOverflow; every product of two amounts or of an amount and basis points is computed in u128.
• Every program account begins with its 8-byte discriminator and a 1-byte PDA bump. There is no layout-version byte.

9.2 Accounts

The program owns 15 account types. Two more addresses complete the set: the fee token account, a token account at the PDA [b"fees"], and the freeze reserve, a system-owned PDA that holds lamports for freeze checkpoint rent. The vault, bond and escrow balances sit in classic SPL associated token accounts whose authority is the respective PDA (§9.5).

The table below lists each account with its seeds, its allocated size and the rent-exempt minimum for that size. Sizes are 8 + INIT_SPACE, which reserves the full payload of every Option. Rent follows Solana's formula [28]:

Seeds bind cardinality. One admin key has one Operator, which has one Bond. An operator has a Vault per 32-byte agent_id (the TypeScript builder hashes a UTF-8 agent ID with SHA-256). A bond has one CreditLine per merchant, and that line names the single vault that pays its tab. Each default has a sequence number; each default has at most one Claim per merchant.