1. Introduction

OpenProp is a proprietary automated market maker (prop AMM) for SOL/USDC on Solana with an open quoting seat. Independent quoters post a USDC bond, each receives its own segregated book, and each prices that book by streaming a five-level quote ladder to the chain. The SOL and USDC that the books trade come from one shared LP vault. The program checks a fixed set of risk limits on every fill, so a quoter decides prices but never holds custody of the inventory it prices and has no instruction that moves it.

This chapter defines OpenProp, describes the two groups it is built for, states the four principles the design follows, gives an overview of the parties and the lifecycle of capital, fixes the units used throughout the paper, and maps the remaining chapters.

1.1 Prop AMMs and the three parts OpenProp separates

A prop AMM is a venue in which one operator writes its own prices into a small on-chain account and takers fill against those prices, normally through an aggregator route. On Solana these venues now fill most SOL–stablecoin trades. Estimates put them between about one third of Solana on-chain volume and 62% of Solana spot DEX volume in the first quarter of 2026, and more than 90% of Jupiter's SOL–stablecoin flow is routed to them. Each existing venue is a closed book run by a single operator on its own capital: HumidiFi, BisonFi, Tessera V, SolFi, Obric, ZeroFi, GoonFi and others. None of them accepts outside LP deposits.

A prop AMM bundles a venue, an inventory and a pricing function. OpenProp assigns each of these to a different party:

Part	What it consists of	Who supplies it in OpenProp
Venue	An on-chain program, an aggregator integration, a fast path for landing quote updates	Shared by every quoter: the single openprop program, an adapter for Jupiter's Amm interface that exposes each book as a market, and a quoter SDK that sends updates down the landing paths a quoter plugs in — BAM's Maker Priority Plugin, the Block Engine, the TPU
Inventory	The SOL and USDC that fill trades	LPs, through the pair's LpVault; the vault allocates inventory to books at each epoch's settlement, and each quoter's USDC bond takes the first loss on its book
Pricing	The quote ladder and the cadence at which it moves	Competing quoters, each writing to its own Quote account through update_quote

The program sits between these parties. It holds every token account, accepts prices only from a book's registered hot keys, and executes a swap only when the book, its quote and the pair's reference price pass every check at the slot of execution.

1.2 The problem

Quoters without a venue

A mid-tier quantitative or market-making firm can have competitive pricing and still have no venue. Running a prop AMM of its own requires an on-chain program, aggregator approval, landing infrastructure and inventory. Jupiter's DEX integration is permissioned and assesses audits, traction and team, and Jito's Maker Priority Plugin (MPP) is open only to selected makers. That is months of work before the first fill.

Independent quants and AI-agent teams face a second barrier: they have no way to demonstrate skill on live flow without committing all of their own capital, and no track record to show an aggregator's review.

OpenProp gives such a quoter a venue, an aggregator adapter and landing code from the first epoch, and LP capital that scales with its own bond and its measured record. A new quoter registers permissionlessly with register_quoter, starts at tier 0 with an allocation of at most 1× its bond, and earns leverage of 5× (tier 1) and 15× (tier 2) through epochs of positive performance.

LPs without access to prop flow

SOL/USDC flow has moved to prop AMMs, and the flow that remains in public pools is the less profitable part of it. In a 12-month sample, passive SOL/USDC AMM makers had gross 2-second markouts of −0.22 bps, against +0.37 bps for prop AMMs. Prop AMMs take no deposits, so a passive LP has no direct way to hold the side of the market that prop AMMs occupy.

OpenProp lets an LP deposit SOL and USDC into a vault whose inventory is traded by bonded quoters. The LP carries SOL direction risk as in any SOL/USDC pool. Trading losses are charged to the quoter's bond before they reach the vault.

The design target

The largest operators are not short of capital: HumidiFi reported routing $0.5–1B a day on about $8M of inventory, and they keep their full edge. OpenProp is therefore built as the distribution and bounded-capital layer for quoters that lack a venue, capital, or both. Aggregators route each trade on price, so a book receives the trades on which its quote is the best available; a quoter does not need to beat the top of the SOL/USDC book on average to be filled.

1.3 Design principles

Quoters price

Pricing runs off-chain on the quoter's own servers, and only its output reaches the chain. A quoter's hot key signs update_quote, which replaces the book's entire ladder in one write to the 304-byte Quote account: a mid price, five bid levels and five ask levels, each an offset in basis points from the mid and a size in lamports, plus a retail delta. The runtime verifies the transaction signature, so authenticating the update costs the program no compute; the measured cost of the instruction is 178 CU against a 200 CU target. update_quote writes only the Quote account and has no path to any token account. The quoter pays its own update fees and sets its own update cadence.

The program enforces limits on every fill

swap_exact_in evaluates five checks before any level fills: the quote is fresh (no older than quoteStalenessSlots), its mid lies inside a band around the reference price, the book's inventory skew stays inside its limit after the fill, the book's hourly and epoch loss windows are not breached, and the pair's circuit breaker is not tripped. A fill that fails a check does not happen, and the rejection is atomic: no state is written and no token moves. Because a limit can never be crossed and punished afterwards, OpenProp has no slashing for rule violations. The same rules crate (openprop-rules) is compiled into the program and to WASM, so aggregators, the indexer and the browser evaluate a swap with the code that executes it.

LP capital sits in one vault

Each pair has one LpVault with its own SOL and USDC token accounts and a classic SPL share mint (OPLP, 6 decimals). Deposits are proportional to the vault's current free basket and mint shares at net asset value. At each epoch's settlement, settle_epoch recalls every book, values it against the reference price, and reallocates the free basket to books by a deterministic score-based rule: score from checkpoint excess returns, a 10% exploration pool for tier-0 books, at most 35% of the vault per quoter and at most a 25% change per epoch. Withdrawal requests are served at the next settlement, within at most 2 epochs.

Bonds take first loss

Each quoter posts a USDC bond held in a program-owned token account. A book's performance is measured as excess over hold, the value of its inventory now minus the value of its starting inventory, both marked at the current reference price:

$$X=\left(\frac{B\cdot P}{10^9}+Q\right)-\left(\frac{B_0\cdot P}{10^9}+Q_0\right)$$

where:

Symbol	Meaning
$X$	Excess over hold, in USDC micros
$B,Q$	The book's tracked SOL (lamports) and USDC (micros) now
$B_0,Q_0$	The book's starting inventory, set at the last settlement
$P$	The reference price, in USDC micros per SOL

A quoter is therefore judged on spread capture and inventory management, not on the direction of SOL. At settlement, negative excess is charged to the bond first and only the remainder falls on LPs. Positive excess above the book's high-water mark is split 50% to LPs, 40% to the quoter and 10% to the protocol, and the quoter's share is credited to its bond, which adds first-loss capacity. Allocation is capped at tier leverage times bond. At tier 2 the bond is therefore at least 1/15 (6.7%) of allocation, more than the 2% epoch loss at which the book stops filling.

The protocol's share burns $OPENPROP

The protocol keeps 10% of positive excess above each book's high-water mark, and that share has one use: it buys $OPENPROP, the protocol's token, on the market and burns it. $OPENPROP has a fixed supply of 1,000,000,000, all of it sold in one public launch on equal terms. Chapter 9 gives the flow.

1.4 The system at a glance

Capital moves through a fixed cycle of program instructions:

Step	Instruction	Signed by	Effect
Deposit	deposit	LP	SOL and USDC enter the vault; OPLP shares are minted
Allocate	settle_epoch	Cranker (any fee payer)	Books are recalled and refilled from the free basket by score
Quote	update_quote	Quoter hot key	The book's ladder is replaced
Swap	swap_exact_in	Taker	A fill against the ladder, after every check passes
Checkpoint	checkpoint_book	Anyone	The book is marked to the reference price, its score sums updated, and it halts on a loss limit
Settle	settle_epoch	Cranker (any fee payer)	Excess is split or charged to the bond; allocations are reweighted; withdrawals are reserved

An epoch lasts epochSlots slots, 432,000 slots or about 24 hours at 200 ms slots, and checkpoints run about every 1,500 slots.

1.5 Conventions

All on-chain integers are little-endian, and every account and instruction described in this paper belongs to wire and account version 6: each instruction begins with the bytes [5, tag] and each account begins with version byte 5 and a kind byte.

Quantity	Unit	Scale
SOL amounts	lamports	1 SOL = $10^9$ lamports (base mint, 9 decimals)
USDC amounts and values	micros	1 USDC = $10^6$ micros (quote mint, 6 decimals)
Prices	micros per SOL	200.000000 USDC/SOL is stored as 200,000,000
LP shares	share atoms	OPLP, 6 decimals
Offsets, bands and limits	bps	1 bps = 0.01% = $10^{-4}$
Fill-quality metrics	BpsE4	basis points × $10^4$
Scores	E6	value × $10^6$
Scoring returns	E9	return × $10^9$
Time	slots	200 ms per slot on mainnet-beta since epoch 1053
Settlement period	OpenProp epoch	epochSlots slots, 432,000 in the v0 parameter set

Parameter values quoted in this paper are the v0 starting set, for example quoteStalenessSlots = 2 slots and epochLossBps = 200. Parameters whose values the deployment's parameter file sets at initialization, such as the band width bandBps and the skew limit skewBps, are described by name and role only. Worked examples use a sample book quoted at a 200.00 USDC mid with levels at 1, 2, 4, 8 and 12 bps of 1, 2, 4, 8 and 16 SOL.

1.6 Map of the paper

Chapter	Content
2. Market structure	The roles and what each signs, the accounts, how order flow reaches books, how a book differs from a pool and an order book, the single pair and the registry of books
3. The book	The five-level ladder, update_quote, price derivation, retail delta, inventory bounds, freshness and the hot/cold key split
4. The reference price	post_ref_price, the Pyth Pro and Switchboard Surge proofs, slot attestation, the two-source midpoint and confidence
5. The five checks	Freshness, band, skew, loss windows and the pair breaker, with their formulas and error codes
6. Swap execution	swap_exact_in step by step: ladder walk, rounding, partial fills at the skew limit, transfers and state updates
7. The vault and LP shares	Deposits, NAV, OPLP issuance, virtual shares, withdrawal requests and claims
8. Bonds, tiers and allocation	Bond posting and unbonding, tier promotion and downgrade, scoring and the allocation rule
9. Checkpoints, settlement and fees	checkpoint_book, excess over hold, the high-water mark, first-loss charging, the fee split and profit locks
10. Parameters and governance	The parameter set, the immutable safety envelope, set_params, timelocks and identity rotation
11. Security design	Custody, signer authority per instruction, replay protection, checks and timelocks
12. Program architecture	The Pinocchio program, hot and cold paths, account layouts, events and compute measurements
13. Infrastructure and integration	The cranker, guardian, indexer and API, the quoter SDK, landing paths and the aggregator adapter
Appendices	Parameters, instructions, accounts, errors and the glossary

2. Market structure

This chapter describes who participates in an OpenProp market, what each participant signs, which accounts carry the market's state, and how a taker's order reaches a book. It closes with the two structural facts that bound a deployment: it serves exactly one SOL/USDC pair, and its registry holds at most five books.

2.1 Roles

Six roles interact with the program. Authority is assigned by key: every instruction either names the account whose key must sign it, or requires no signer beyond the transaction fee payer.

Role	Key	Instructions it signs	What it can change	What it cannot do
Quoter, cold owner	The wallet that registered (Quoter.owner)	register_quoter, add_bond, request_unbond, claim_unbond, set_quote_authority, pause_book, resume_book, deregister_quoter	Its bond, its hot keys, the paused state of its own book	Withdraw book or vault assets
Quoter, hot authority	Up to three keys cached in Quote	update_quote	Its own book's Quote account	Write any other account or move any token
LP	Any wallet	deposit, request_withdraw, claim	Its own shares and withdrawal tickets	Direct inventory to a book
Taker	Any wallet, or an aggregator's transfer authority	swap_exact_in	One book's inventory, within the checks	Fill a stale, out-of-band or halted book
Cranker	Any fee payer	post_ref_price, checkpoint_book, settle_epoch	The order in which deterministic state transitions run	Choose prices, allocations or splits
Guardian	Config.guardian; optional Config.guardianHaltSigner	halt_pair, review_tier (guardian only)	Halt the pair; approve a tier-2 review	Resume the pair, change parameters, move funds
Admin	Config.admin, a multisig	initialize_config, initialize_pair, set_params, resume_pair, rotate_identities	Parameters and identities, under a timelock for every loosening	Move vault, book or bond assets

Quoters

A quoter controls two classes of key. The cold owner is the wallet that called register_quoter; the Quoter account is a program-derived address seeded by it (["quoter", owner]), so one wallet holds at most one quoter seat. Registration transfers the initial USDC bond, which must be at least minBondQuoteAtoms, and creates in one instruction the Quoter account, its USDC bond token account, the Book, the Quote and the book's SOL and USDC token accounts. The cold owner manages the bond (add_bond, request_unbond, claim_unbond), pauses and resumes its book, installs hot keys, and can deregister a fully unbonded, flat seat.

A hot authority signs only update_quote. It is the key a quoting engine holds in memory and uses many times a second, so its permissions are reduced to writing one 304-byte account. Chapter 3 describes the split between the two key classes in detail.

LPs

An LP calls deposit with a maximum SOL amount, a maximum USDC amount and a minimum share count. The program sizes a basket proportional to the vault's current free SOL/USDC holdings across the vault and all books, consumes the limiting maximum in full, leaves unused tokens in the wallet, and mints OPLP shares against the vault's net asset value. Exits go through request_withdraw, which burns liquid shares into pending shares, and claim, which pays the reserved basket after the next settlement.

Takers

A taker calls swap_exact_in with a side (0 sells SOL, 1 buys SOL), an exact input amount and a signed minimum output. Most takers do not call the program directly: they request a route from an aggregator, and the aggregator's router program invokes swap_exact_in by cross-program invocation. The four aggregators that cover nearly all routed Solana volume are Jupiter, DFlow, Titan and OKX.

Cranker

The cranker runs three permissionless instructions. post_ref_price stores a new reference price after verifying signed Pyth Pro and Switchboard Surge payloads (Chapter 4). checkpoint_book marks one book to the reference price about every 1,500 slots (checkpointSlots) and halts it if a loss limit is breached. settle_epoch runs once the epoch's last slot has passed and settles every registered book in one transaction. None of these instructions takes a decision from its caller: each computes its result from accounts, the clock and verified oracle proofs, so any fee payer can run them, and a repeated or competing call either produces the same transition or is a no-op (a checkpoint inside its cadence, an already posted oracle update, an already settled epoch). The protocol's cranker service runs all reference-writing jobs under one fenced lease per pair and journals each signed packet before broadcast.

Guardian

The guardian is a multisig whose only market action is halt_pair, which sets the manual-halt flag on the pair's RefPrice and so stops fills in every book. An optional second key, guardianHaltSigner, may also call halt_pair and nothing else; the protocol's guardian bot uses it when an explicitly configured, sustained oracle divergence is observed. The guardian also signs review_tier, the v0 review required for tier 2. It cannot resume a halted pair, change parameters, quote or transfer assets.

Admin

The admin is a Squads multisig. It initializes the deployment, proposes parameter changes with set_params, resumes a manually halted pair with resume_pair, and rotates identities with rotate_identities. A change that tightens a limit applies immediately. A change that loosens a limit is stored as pending and can be applied only after both $\text{Clock.slot}\ge s_p+\text{timelockEpochs}\cdot \text{epochSlots}$ and $e_v\ge e_p+\max (w,w^{\prime })+1$, where $s_p$ and $e_p$ are the proposal slot and vault epoch, $e_v$ is the current vault epoch, and $w,w^{\prime }$ are the current and proposed withdrawEpochs. An LP who disagrees with a loosening therefore always has a full withdrawal cycle in which to exit. No admin instruction transfers vault, book or bond assets.

2.2 Accounts

Every account is a program-derived address (PDA) of the openprop program, and every token account is owned by a PDA, so the program is the only signer that can move tokens out of them.

Account	Seeds	Bytes	Holds
Config	["config"]	1,728	Identities (admin, guardian, oracle signers, retail signer, cranker), mints, the protocol USDC account and the buyback mint, the active and pending parameter sets, the immutable safety envelope
PairConfig	["pair", baseMint, quoteMint]	168	Links from the pair to its Config, RefPrice and LpVault
RefPrice	["ref", pair]	3,776	Reference mid, confidence, source slots, both source prices, breaker state and a 150-slot price history
LpVault	["vault", pair]	408	Epoch, share supply, reserved withdrawal assets, deferred fees and the registry of books
Vault token accounts	["vault_base", pair], ["vault_quote", pair]	165 each	Free SOL and USDC
Share mint	["shares", pair]	82	OPLP, 6 decimals, mint authority LpVault
Quoter	["quoter", owner]	1,304	Cold owner, hot authorities, bond, tier, review flag, trip history, profit-lock tranches
Bond token account	["bond", quoter]	165	The quoter's USDC bond
Book	["book", quoter, pair]	576	Allocation, starting and tracked inventory, excess, high-water mark, loss windows, scoring sums, state
Book token accounts	["book_base", book], ["book_quote", book]	165 each	The book's SOL and USDC
Quote	["quote", book]	304	Generation, sequence, slot, mid, retail delta, ten levels, cached hot authorities
WithdrawTicket	["wd", owner, epoch]	144	One LP's queued withdrawal for one epoch
WithdrawBatch	["withdraw_batch", vault, epoch]	104	The epoch's aggregate withdrawal reservation
UnbondTicket	["unbond", quoter, requestId]	136	One unbond request with paid, haircut and remaining amounts
OperationReceipt	["receipt", owner, requestId]	320	The original payload of a monetary request, for replay-safe retries

Quote is deliberately separate from Book. A quote update write-locks only the small Quote account; a swap reads Quote and writes Book. Quote updates and swaps on the same book therefore never contend for the same write lock, and an update scheduled ahead of swaps in a block reprices the book before they execute.

2.3 How order flow reaches a book

Aggregator routing through the Jupiter Amm adapter

An aggregator's routing engine treats each Book as one market. The reference integration is OpenPropAmm, an implementation of the Amm trait from jupiter-amm-interface 0.6.1. The adapter is constructed from a Book account; it derives Config (["config"]), RefPrice (["ref", pair]) and Quote (["quote", book]) and reads the book's two token-account addresses from the Book. Its get_accounts_to_update returns exactly these six accounts.

update receives the six accounts from the aggregator's account cache and validates program ownership, exact version, kind and length, the PDA links between them, the mints, the token authorities, and that actual token balances cover the book's tracked inventory. An invalid update clears the previous snapshot, so a market never quotes from stale or mismatched state. quote performs no network calls: it evaluates the swap with the same openprop-rules crate the program executes, at the slot supplied by the aggregator's shared clock. It returns no route when the quote or reference is stale, the epoch has ended, the book or pair is halted or paused, the ladder is invalid, the reference confidence or source divergence is outside its gate, or a loss limit is breached. It also declines a route that would consume the input only partially at the skew or depth boundary, because an ExactIn route must not leave input unspent. The quoted fee is zero; the quoter's spread is contained in the level prices.

get_swap_and_account_metas returns the ten accounts of swap_exact_in in program order, with the router's token transfer authority as the signer. The instruction is encoded with an explicit user-approved minimum output; if the actual output is smaller, the program rejects the whole swap with SLIPPAGE_EXCEEDED.

The quote an aggregator computes and the fill the program executes can differ only through state that changed between the two slots. If the book's quote aged past quoteStalenessSlots, its mid left the band, or the pair halted in between, the swap fails and no token moves. If the quoter replaced the ladder in between, the swap executes against the new ladder and the signed minimum output protects the taker.

Direct swaps

Any wallet can call swap_exact_in without a router. The contract package's swapExactIn builder assembles the ten accounts: taker (signer), Config, RefPrice, Book (writable), Quote, the book's SOL and USDC token accounts (writable), the taker's SOL and USDC token accounts (writable), and the SPL Token program. A direct caller also receives the program's native partial-fill behaviour: when the skew limit or the book's inventory stops the ladder walk, the program transfers only the consumed input and the corresponding output, provided the output meets the signed minimum.

Flow class

A swap is either standard or retail. A retail swap carries an eleventh account, the key stored in Config.retailSigner, and that key must sign the transaction. The designated signer is an aggregator frontend's signing key; Jupiter documents a frontend signer for its retail flow and classifies that flow as non-toxic. On a retail swap each level's offset is reduced by the quote's retail delta (Chapter 3). A zero retailSigner disables the class, and an aggregator's fee-mode hint without the configured signature never grants retail pricing.

2.4 A book compared with a pool and an order book

A book is neither a liquidity pool nor a central limit order book. Its price comes from one quoter, its inventory comes from LPs through the vault, and the program checks its risk limits on each fill.

Property	Constant-function pool	Central limit order book	OpenProp book
Who sets the price	A curve over the pool's reserves; it moves only when trades move the reserves	Each maker's resting orders	One quoter, by replacing the whole ladder with update_quote
Price anchor	None	None	The quote's mid must lie within bandBps of the reference price
Capital	Passive LP deposits	Each maker's own balance	LP capital allocated from the vault, priced by the quoter, with the quoter's bond in first loss
Cost of moving the price	None, but it cannot move without a trade	100–300k CU per order-book update on Phoenix	178 CU per ladder replacement, measured
Matching	Along the curve	Price-time priority across all makers	Within one ladder; an aggregator splits a trade across books as across venues
Who absorbs adverse fills	LPs	The maker	The quoter's bond first, then LPs
On-chain risk limits	None beyond the curve	None per maker	Freshness, band, skew, hourly and epoch loss, pair breaker on every fill

The book shares the oracle-centred ladder design of BisonFi's prop AMM: a mid price and per-level offsets, rather than absolute prices, so that a single field moves the whole ladder.

2.5 One SOL/USDC pair per deployment

A deployment of the program serves exactly one pair. Config is a singleton PDA (["config"]) that stores one base mint and one quote mint, and mint identities are immutable: rotate_identities replaces the admin, guardian, oracle, retail, cranker and buyback-mint keys but never the pair's mints or the protocol USDC account. initialize_pair requires the base mint to have 9 decimals and the quote mint 6, and creates PairConfig at ["pair", baseMint, quoteMint] together with the pair's RefPrice, LpVault, vault token accounts and share mint. Every swap, checkpoint and settlement checks that the Book, RefPrice and LpVault it receives belong to that pair. Books and the vault hold SOL as SPL token balances of the base mint; wrapping native SOL is a separate step outside the program.

2.6 The registry of books

LpVault holds the registry: a 160-byte array of five 32-byte book addresses (books) and a counter (bookCount). Config.maxBooks sets how many seats are open and must lie between 1 and 5, the storage capacity of the array.

register_quoter appends the new book at index bookCount and increments the counter. When bookCount has reached maxBooks it fails with REGISTRY_FULL (6038), "The vault has no free quoter seats. A quoter must deregister before another can register." deregister_quoter frees a seat. It requires the seat to be flat: zero bond, zero pending unbond, zero locked profit, zero allocation, zero tracked inventory and zero deferred fees, otherwise it fails with BOND_IN_USE (6021). It removes the book from the array, shifts the later entries down so registry order is preserved, clears the hot authorities and pauses the book with reason DEREGISTERED. The Quoter and Book accounts remain as history.

Registry order is canonical. deposit and settle_epoch must receive every registered book, with its token accounts, Quoter and bond account, in registry order; the program checks each entry against the array. A deposit therefore prices shares against the inventory of every book, and a settlement cannot omit a book's loss or liability. The account count grows by five per book:

Instruction	Fixed accounts	Per registered book	With five books
deposit	13	5 (book, book SOL, book USDC, quoter, bond)	38
settle_epoch	10	5 (quoter, bond, book, book SOL, book USDC)	35

At five books both instructions are sent as v0 transactions with an address lookup table.

Each swap write-locks its Book. Solana caps the compute that transactions writing one account can use in a block at 12M CU; at about 40k CU per swap this allows roughly 300 fills per book per block. Measured swaps cost between 17,934 CU (a representative three-level swap) and 37,497 CU (a skew-limited partial fill on a large book). Depth spread across several books therefore also spreads this per-account capacity.

3. The book

A book is one quoter's segregated market. It holds its own SOL and USDC, filled from the LP vault at each settlement, and it is priced by one account, the Quote, which the quoter's hot keys overwrite with a complete five-level ladder on every update. This chapter covers the ladder and its prices, the limits that bound what it can fill, the update_quote instruction, freshness, and the split between the quoter's cold and hot keys.

3.1 Accounts of a book

The Quoter holds the authoritative list of hot keys; Quote holds a cache of the same list so that update_quote can authenticate its signer by reading only the account it writes. The Book records the book's state byte: 0 live, 1 halted by a loss limit, 2 paused by its owner (or deregistered).

3.2 The quote ladder

A quote is a mid price and two ladders of five levels. Each level is an offset from the mid in whole basis points and a size in lamports. Bid levels are the prices at which the book buys SOL from a taker who sells; ask levels are the prices at which it sells SOL to a taker who buys. A retail delta, also in basis points, tightens every offset for retail-class swaps (Section 3.4).

The 304-byte Quote account stores the ladder in fixed positions:

Offset	Field	Type	Written by
0	version (5), kind (6), bump, flags, reason	5 × u8	register_quoter
8	book	public key	register_quoter
40	sequence	u64	update_quote; reset to 0 by set_quote_authority
48	slot	u64	update_quote, from the Clock sysvar; reset to 0 by set_quote_authority
56	mid	u64, micros per SOL	update_quote; reset to 0 by set_quote_authority
64	retailDeltaBps	u32	update_quote
72	levels	10 × (u32 offset, u64 size), 120 bytes	update_quote
192	cachedAuthorityCount	u8	set_quote_authority
200	cachedAuthorities	3 × public key	set_quote_authority
296	generation	u64	set_quote_authority

Within levels, entries 0 to 4 are bid levels 1 to 5 and entries 5 to 9 are ask levels 1 to 5. Each entry is 12 bytes: the offset as a u32 at +0 and the size as a u64 at +4.

update_quote stores the ladder without inspecting it. Every swap validates the ladder it is about to walk, and rejects the swap with QUOTE_LADDER_INVALID (6034) unless all of the following hold:

Rule	Condition
Mid present	mid > 0
Retail delta bounded	retailDeltaBps ≤ retailDeltaLimitBps
Offsets below 100%	every offset < 10,000 bps
Offsets monotone	within each side, no offset is smaller than the offset of the level before it
Sizes bounded	every size ≤ maxLevelBaseAtoms

A level with size 0 is valid and is skipped by the walk, so a quoter can post fewer than five levels on a side, or withdraw one side entirely, by zeroing sizes. Deferring validation to the fill keeps the update path to a fixed sequence of comparisons and copies, and the swap checks the ladder against the configuration that is current at execution.

3.3 Prices from mid and offsets

The program derives each level's price from the mid and the level's offset at fill time:

$$p_i^{\text{bid}}=\lfloor \frac{m(10^4-o_i)}{10^4}\rfloor ,p_i^{\text{ask}}=\lfloor \frac{m(10^4+o_i)}{10^4}\rfloor$$

where:

Symbol	Meaning
$m$	Quote.mid, in USDC micros per SOL
$o_i$	The effective offset of level $i$ in bps: the stored offset for a standard swap, or the retail offset of Section 3.4
$p_i^{\text{bid}},p_i^{\text{ask}}$	The price of level $i$, in USDC micros per SOL

A level fills in whole lamports. When a taker sells $q$ lamports into bid level $i$ it receives $\lfloor q{p}_i^{\text{bid}}/10^9\rfloor$ micros. When a taker buys with $U$ micros remaining, ask level $i$ delivers

$$q_i=\min \left(\lfloor \frac{U\cdot 10^9}{p_i^{\text{ask}}}\rfloor ,s_i,B\right)\text{for a payment of}\lceil \frac{q_i{p}_i^{\text{ask}}}{10^9}\rceil$$

where $s_i$ is the level's size in lamports and $B$ is the book's remaining tracked SOL. Rounding favours the book by at most one micro per level: a seller's proceeds round down and a buyer's payment rounds up.

Worked price table

The sample ladder has a mid of 200.000000 USDC (200,000,000 micros), offsets of 1, 2, 4, 8 and 12 bps on both sides, sizes of 1, 2, 4, 8 and 16 SOL, and a retail delta of 1 bps.

Level	Offset (bps)	Size (SOL)	Size (lamports)	Bid (USDC)	Ask (USDC)	Retail offset (bps)	Retail bid	Retail ask
1	1	1	1,000,000,000	199.980000	200.020000	0	200.000000	200.000000
2	2	2	2,000,000,000	199.960000	200.040000	1	199.980000	200.020000
3	4	4	4,000,000,000	199.920000	200.080000	3	199.940000	200.060000
4	8	8	8,000,000,000	199.840000	200.160000	7	199.860000	200.140000
5	12	16	16,000,000,000	199.760000	200.240000	11	199.780000	200.220000

For level 1, $p_1^{\text{bid}}=\lfloor 200,000,000\times 9,999/10,000\rfloor =199,980,000$ micros. Because sizes double from level to level, the depth-weighted average offset of the full side is $(1\cdot 1+2\cdot 2+4\cdot 4+8\cdot 8+16\cdot 12)/31=277/31\approx 8.94$ bps.

Levels swept	SOL	Taker receives selling into bids (USDC)	Average bid	Taker pays buying asks (USDC)	Average ask	Average distance from mid
1	1	199.98	199.980000	200.02	200.020000	1.00 bps
1–2	3	599.90	199.966667	600.10	200.033333	1.67 bps
1–3	7	1,399.58	199.940000	1,400.42	200.060000	3.00 bps
1–4	15	2,998.30	199.886667	3,001.70	200.113333	5.67 bps
1–5	31	6,194.46	199.821290	6,205.54	200.178710	8.94 bps

Worked fills

These two fills are the shared rules crate's own test vectors.

A taker sells 2.5 SOL (2,500,000,000 lamports) with a signed minimum of 499.90 USDC. Level 1 takes 1 SOL at 199.980000 for 199,980,000 micros; level 2 takes the remaining 1.5 SOL at 199.960000 for 299,940,000 micros. The taker receives 499,920,000 micros (499.92 USDC), an average of 199.968, 1.6 bps below the mid.

A taker buys with 300.04 USDC (300,040,000 micros). At level 1, $\lfloor 300,040,000\times 10^9/200,020,000\rfloor$ exceeds the level's 1 SOL, so the level fills in full for 200,020,000 micros. At level 2, the remaining 100,020,000 micros buy $\lfloor 100,020,000\times 10^9/200,040,000\rfloor =500,000,000$ lamports for exactly 100,020,000 micros. The taker receives 1.5 SOL for the full input.

3.4 Retail delta

For a retail swap, the one co-signed by the key in Config.retailSigner, every level's offset is reduced by the quote's retail delta $\delta$, saturating at zero:

$$o_i^{\text{retail}}=\max (o_i-\delta ,0)$$

where $o_i$ is the stored offset of level $i$ and $\delta$ is Quote.retailDeltaBps. A positive delta tightens the spread on both sides for flow the quoter treats as non-toxic. In the sample ladder a 1 bps delta moves level 1 on both sides to the mid itself and every other level 1 bps closer to it, as the retail columns of the table above show. The quoter chooses $\delta$ on every update, and $\delta =0$ prices both classes identically. retailDeltaLimitBps, set in Config, bounds it; a quote whose delta exceeds the limit cannot fill in either class.

3.5 How inventory and allocation bound the sizes

The sizes a quoter posts are upper bounds. The amount a swap actually fills is the smallest of four limits.

Tracked inventory. At each settlement settle_epoch gives the book a basket from the vault's free SOL and USDC in proportion to its target allocation, so every book starts the epoch with the vault's SOL:USDC ratio. The basket is recorded as both the starting inventory (startBase, startQuote) and the tracked inventory (trackedBase, trackedQuote), and its value at the settlement's reference price becomes allocation. Only swaps and settlement change tracked inventory; tokens sent to a book account by anyone else are excluded from it and swept to the vault at settlement. A buy can take no more SOL than trackedBase, and a sell can be paid no more USDC than trackedQuote; when either runs out, the walk stops and the swap fills partially with INSUFFICIENT_LIQUIDITY as the stop reason.

Level cap. Each level's size is at most maxLevelBaseAtoms, which bounds the gap a single level can expose between quote updates.

Skew. After each level the program measures the inventory skew at the reference price $P$:

$$\sigma (B,Q)=\frac{\left|V_B-Q\right|}{V_B+Q},V_B=\lfloor \frac{B\cdot P}{10^9}\rfloor$$

where:

Symbol	Meaning
$B,Q$	Tracked SOL (lamports) and USDC (micros) after the fill
$V_B$	The SOL inventory's value in micros at the reference price
$\sigma$	Skew, 0 for a book balanced by value and 1 for a book holding one asset

A fill is admissible while $10^4\cdot \sigma \le$ skewBps. A book that starts a swap already beyond the limit may fill only while its skew stays at or below the skew it started the swap with. When a level would cross the limit, the program finds the largest quantity at that level that stays inside it, fills that amount and stops; Chapters 5 and 6 give the check and the search.

Loss windows. The book's hourly and epoch losses, marked at the reference price, must stay within fractions of allocation:

$$10^4\cdot L_h\le A\cdot \text{hourlyLossBps},10^4\cdot L_e\le A\cdot \text{epochLossBps}$$

where $A$ is Book.allocation in micros, $L_e=\max (-X,0)$ is the loss against the starting inventory, $X$ is the book's excess over hold, and $L_h$ is the fall in $X$ since the start of the current hourly window of hourlyWindowSlots slots. A swap whose post-fill loss would exceed either limit is rejected.

Worked bounds on the sample book

The sample book holds 900 SOL and 180,000 USDC, worth 360,000 USDC at a 200.00 reference, so its allocation is 360,000 USDC and its starting skew is 0. With the v0 limits of 50 bps hourly and 200 bps per epoch, the book stops filling once its hourly loss exceeds 1,800 USDC or its epoch loss exceeds 7,200 USDC; a loss exactly at a limit still fills.

Swap	Book after (SOL / USDC)	Value at 200.00	Excess	Skew after
Taker sells 2.5 SOL	902.5 / 179,500.08	360,000.08	+0.08	27.8 bps
Taker sells 31 SOL into all bids	931 / 173,805.54	360,005.54	+5.54	344.3 bps
Taker buys all 31 SOL of asks	869 / 186,205.54	360,005.54	+5.54	344.6 bps

With the mid equal to the reference price, each fill adds the spread it captured to excess. A full sweep of one side uses 3.4% of the book's USDC and 3.4% of its SOL, so on this book the ladder sizes and the skew limit, not inventory, decide how much a sweep can fill: the sweep completes only if skewBps is at least 345. Losses arise afterwards, when the reference moves against the inventory the book has taken on, or at fill time when the quote's mid sits on the adverse side of the reference within the band.

3.6 The update_quote instruction

update_quote (tag 0) takes three accounts: the hot authority (signer, fee payer), the Quote (writable) and the Clock sysvar. Its instruction data is 150 bytes, or 151 with the authority hint:

Bytes	Field	Type
0–1	Header [6, 0]	2 × u8
2–9	generation	u64
10–17	sequence	u64
18–25	mid	u64, micros per SOL
26–145	Ten levels: bids 1–5, then asks 1–5, each offset u32 and size u64	120 bytes
146–149	retailDeltaBps	u32
150	Authority index, optional	u8

The program performs these checks in order and fails on the first that does not hold:

Step	Check	Error
1	Exactly three accounts; body of 148 or 149 bytes	INVALID_INSTRUCTION (6000)
2	The hot authority signed	UNAUTHORIZED (6002)
3	Quote is owned by the program, is 304 bytes and carries version 6, kind 6	INVALID_ACCOUNT (6001)
4	The signer equals the cached authority at the hinted index, or, without a hint, one of the cached authorities	UNAUTHORIZED (6002)
5	generation equals Quote.generation	STALE_SEQUENCE (6014)
6	sequence is strictly greater than Quote.sequence	STALE_SEQUENCE (6014)
7	The third account is the Clock sysvar with 40 bytes of data	INVALID_ACCOUNT (6001)

It then writes sequence, slot (the current Clock.slot), mid, retailDeltaBps and the 120 level bytes. It makes no cross-program invocation, emits no log and allocates no memory. The strictly increasing sequence makes updates idempotent and ordered: a delayed or duplicated packet with a sequence at or below the stored one fails, so an older ladder can never overwrite a newer one, whatever path each packet took.

The hinted compute path

When the loader passes exactly three accounts, the program's entrypoint deserializes only three account slots and, if the instruction data is 150 or 151 bytes beginning with [5, 0], calls the update handler directly; every other instruction takes the general path. The Clock is read from the sysvar account after its key and length are checked.

The optional final byte names the position of the signing key in the cached authority list. With the hint, the program compares the signer against one cached key, and the cost is the same for every position. Without it, the program compares the signer against the cached keys in order. Measured on the release artifact (LiteSVM 0.6.1 executing the SBF program, cu-measurements.json):

Path	Signing key	Measured CU	Target
Hinted	Any of three positions	178	200
Scan	The only key	170	200
Scan	First of three	172	200
Scan	Middle of three	177	200
Scan	Last of three	183	200

A quote-update transaction contains a compute-unit limit, a compute-unit price and the single update_quote instruction, signed by the hot key as sole signer and fee payer; it is about 300 bytes, well under the 1,232-byte packet limit. The quoter pays every update's fees, so the update cadence is set by the quoter's own engine.

3.7 Landing and freshness

The SDK's land sends one signed update down an ordered list of paths: Jito BAM's Maker Priority Plugin on a known BAM leader slot when the quoter is enrolled, otherwise the Block Engine, then the TPU. The quoter supplies the network client for each path (an enrolled sender for MPP, a Block Engine JSON-RPC client, a TPU client); the SDK formats the packets and keeps the order. The reference quoter in the repository sends through a standard RPC endpoint. MPP collects maker updates in batches of about 50 ms, deduplicates them by sequence number and places the latest update first in the batch, so on BAM slots a book's newest ladder is the one that executes and older copies are dropped before they reach the program. A submission acknowledgement does not stop the fallback; only an observed landing does.

Freshness is measured in slots by the program's own clock. The slot field is written from Clock.slot when the update executes, not supplied by the quoter, so the age of a quote is the time since it landed:

$$a=\text{Clock.slot}-\text{Quote.slot},\text{fill requires }a\le \text{quoteStalenessSlots}$$

With the v0 value of 2 slots, a quote that lands in slot $s$ can fill in slots $s$, $s+1$ and $s+2$, and every swap against it in slot $s+3$ or later fails with QUOTE_STALE (6004) until the next update lands. At 200 ms slots that is at most 400 ms after the landing slot. Staleness uses Clock.slot and never Clock.unix_timestamp, which the block leader sets.

3.8 Hot and cold keys

The cold owner and the hot authorities have disjoint powers. The cold owner can manage the bond, pause and resume the book, and replace the hot keys, but no cold instruction writes a ladder. A hot authority can write its book's ladder and nothing else. A leaked hot key therefore exposes at most bad quotes, which every fill still checks against the band, skew and loss limits, and the cold owner can revoke it in one transaction.

Up to three hot authorities

set_quote_authority (tag 11) takes the cold owner (signer), the Quoter and the Quote (both writable), and then one signer account for each newly added key. Its data is a count from 0 to 3 followed by that many public keys, and optionally a trailing byte 1 that requests a full sequence reset. The program enforces:

Rule	Error
At most three keys	AUTHORITY_LIMIT (6022)
Keys nonzero and distinct	INVALID_AUTHORITY_CHANGE (6032)
The cold owner signed; the quoter is registered	UNAUTHORIZED (6002)
Every key not already in the list co-signs, in list order	UNAUTHORIZED (6002)
With a reset, no new key appears in the current list	INVALID_AUTHORITY_CHANGE (6032)

Retained keys and removals need only the cold owner. The co-signature exists because swaps whose taker is the cold owner or a current hot authority are known self-flow: they still change the book's inventory, losses and excess, but they add nothing to its scoring returns or scored turnover. Without the new key's consent a cold owner could list an unrelated taker's key as a hot authority and remove that taker's fills from its own score.

Replacement and generation

Every change to the list writes Quoter and Quote in the same instruction: the new list replaces Quoter.authorities and the cache in Quote, Quote.generation increases by one, and sequence, slot and mid are set to zero. The book has no fillable quote until a key from the new list lands an update carrying the new generation and a sequence of at least 1.

Operation	Data	Extra signers	Effect on Quote
Add a key	Current keys plus the new key	The new key	Generation + 1; sequence, slot and mid cleared
Remove a key	Current keys minus the removed key	None	Generation + 1; sequence, slot and mid cleared
Replace a key	The new key in place of the old	The new key	Generation + 1; sequence, slot and mid cleared
Repeat the current list	Identical list, no reset byte	None	No change; generation, sequence and live quote kept
Full reset	A list disjoint from the current one, reset byte 1	Every new key	Generation + 1, even for an identical empty list; sequence, slot and mid cleared

Because every update packet names a generation, a packet signed before a change cannot execute after it, even if its key is later re-added and its blockhash is still valid. The sequence alone cannot provide this, since a change resets it to zero.

Sequence discipline in the SDK

The protocol accepts up to three hot authorities for engines that coordinate sequences among themselves. The reference Rust SDK requires exactly one configured hot authority and takes an exclusive lease on the Quote's sequence before it reads the reference price or inventory. It starts above both the on-chain sequence and its own persisted high-water mark for the current generation, and it durably writes {generation, last_issued} before it returns signed bytes, so a crash cannot cause it to sign two different ladders with one sequence number. After local state is lost, the cold owner opens a new generation with set_quote_authority before the engine resumes.

4. The reference price

Each pair has one reference mid, stored in its RefPrice account, and every risk decision in OpenProp is taken against it. The band check compares a quoter's mid with it. The skew and loss checks mark book inventory at it. checkpoint_book and settle_epoch value books and the vault at it. The pair breaker, which halts every book in the pair at once, keeps its state in the same account.

A reference is written by post_ref_price, which anyone can call. It accepts a value only as two signed updates, one from Pyth Pro and one from Switchboard Surge, verified by the runtime in the same transaction and bound to one recent slot, and it stores their median next to each source's own price. A failed confidence, divergence or move test does not reject the post. The value is stored and the pair breaker trips.

4.1 The RefPrice account

RefPrice is a program-derived account with seeds ["ref", pair], account kind 2 and version byte 5. It is 3,776 bytes long: a 176-byte body followed by a 3,600-byte price history used by the move rule. initialize_pair creates it and records the pair address. Prices are written only by post_ref_price. The breaker fields are also written by halt_pair, resume_pair and, when the reference is stale, checkpoint_book.

All prices are integers in micro-USDC per SOL (six decimals), so 200.00 USDC per SOL is stored as 200000000.

Offset	Field	Type	Content
3	flags	u8	bit 0: pair breaker active; bit 1: guardian halt
4	reason	u8	reason code of the current halt
8	pair	pubkey	the pair account (PairConfig)
40	mid	u64	reference mid: the two-source median
48	confidence	u64	combined confidence
56	sourceSlot	u64	slot $s$ that both signed updates are bound to
64	postedSlot	u64	Clock.slot when the post executed
72	pythPrice	u64	Pyth Pro price
80	pythConfidence	u64	Pyth Pro confidence
88	pythSlot	u64	equal to sourceSlot
96	pythTimestampUs	u64	Pyth Pro signed timestamp, microseconds
104	switchboardPrice	u64	Switchboard Surge price
112	switchboardConfidence	u64	zero: Surge publishes no confidence
120	switchboardSlot	u64	equal to sourceSlot
128	switchboardTimestampUs	u64	zero: Surge publishes no timestamp
136	trippedSlot	u64	slot at which the current halt began
144	clearedSlot	u64	slot at which the halting condition was first seen clear; zero while it persists
152	resumeSlot	u64	first slot at which a clean post lifts the halt
160	lastPythTimestampUs	u64	replay cursor for Pyth Pro
168	lastSwitchboardSlot	u64	replay cursor for the source slot
176	history	150 × 24 bytes	ring of (slot, low, high) per source slot

The reason byte uses the incident reason codes shared with book halts:

reason	Condition	Written by
1	guardian halt	halt_pair
2	stale reference	post_ref_price (gap detected), checkpoint_book
3	confidence too wide	post_ref_price
4	price move	post_ref_price
5	source divergence	post_ref_price

4.2 The post_ref_price instruction

post_ref_price has wire tag 2. Its 14-byte body names where the three signed messages sit in the transaction and which slot they are bound to:

Bytes	Field
0–1	index of the Pyth Pro Ed25519 instruction (u16)
2–3	index of the Switchboard Surge Ed25519 instruction (u16)
4–11	source slot $s$ (u64)
12–13	index of the slot-attestation Ed25519 instruction (u16)

It takes four accounts in this order: Config, RefPrice (writable), the Instructions sysvar and the SlotHashes sysvar. No signature is required beyond the fee payer's. The instruction makes no cross-program call. It reads the already verified messages from the Instructions sysvar.

The protocol cranker builds each reference transaction as a compute-budget instruction, three Ed25519 verification instructions (Pyth Pro, Switchboard Surge, slot attestation), and post_ref_price(1, 2, s, 3). It takes $s$ from the newest entry of SlotHashes. It plans a reference post in every slot where Clock.slot is past postedSlot. When a book is due for a checkpoint, checkpoint_book is appended to the same transaction, so the checkpoint marks the book at the price posted a moment earlier. The design estimates the instruction at 10–20k CU.

4.3 Verifying the signed updates

Ed25519 instructions

The Ed25519 precompile verifies every signature in the transaction before any program executes, and an invalid signature fails the whole transaction. post_ref_price then checks, for each of the three indices, that:

1. the index is lower than the index of the executing post_ref_price instruction;
2. the instruction's program is Ed25519SigVerify111111111111111111111111111;
3. it carries exactly one signature (data byte 0 is 1, byte 1 is 0);
4. its signature, public-key and message references (the instruction-index fields at data bytes 4, 8 and 14) all point into that same instruction, either as 0xFFFF or as its own index, so the bytes the program reads are the bytes that were verified;
5. the 32-byte public key equals the configured signer: Config.pythSigner, Config.switchboardSigner or Config.pythSlotAttestor.

Any mismatch fails with INVALID_ORACLE (6027).

The Pyth Pro update

The Pyth Pro message is the provider's own signed binary payload, read byte for byte:

Bytes	Field	Rule
0–3	magic, u32	must be 2479346549
4–11	timestamp, u64 microseconds	must advance (replay order, below)
12	channel
13	feed count	must be 1
14–17	feed id, u32	must equal Config.pythFeedId
18	property count
19–	properties	id 0: price i64; id 4: exponent i16; id 5: confidence i64

The three properties may appear in any order, each exactly once. An unknown property, a duplicate or trailing bytes fail with INVALID_ORACLE. The price must be positive, the confidence non-negative and the exponent between −18 and 6. Both values are converted to micro-units:

$$\mathrm{scale}(v,e)=\{\begin{array}{ll}v\cdot 10^{e+6}& \text{if }e+6\ge 0\\ \lfloor v/10^{-(e+6)}\rfloor & \text{if }e+6<0\end{array}{p}_P=\mathrm{scale}(v_P,e),c_P=\mathrm{scale}(v_c,e)$$

where:

• $v_P$ is the signed Pyth Pro price mantissa and $v_c$ its confidence mantissa;
• $e$ is the signed exponent;
• $p_P$ and $c_P$ are the Pyth Pro price and confidence in micro-USDC per SOL.

A result that does not fit in a u64 fails with ARITHMETIC_OVERFLOW (6025). For example, a mantissa of 19,999,000,000 at exponent −8 gives $p_P=\lfloor 19,999,000,000/100\rfloor =199,990,000$, which is 199.99 USDC.

The Switchboard Surge update

The Surge message is the 81-byte record defined by Switchboard's OracleQuote format:

Bytes	Field	Rule
0–31	signed slot hash	must match SlotHashes at slot $s$
32–63	feed hash	must equal Config.switchboardFeed
64–79	value, i128, 18 decimals	must be positive
80	minimum sample count	must be above zero

The price is $p_S=\lfloor v_S/10^{12}\rfloor$, where $v_S$ is the signed 18-decimal value. Surge signs a slot hash, not a slot number. The program therefore looks up $s$ from the instruction body in the SlotHashes sysvar, which holds up to 512 recent (slot, hash) pairs, and requires an entry whose slot is $s$ and whose hash equals the signed hash. A Surge update can only carry a hash the cluster had already produced, so it was signed at slot $s$ or later. The unsigned slot footer that the Switchboard SDK appends to its instruction is never read.

The Pyth slot attestation

Pyth Pro signs a timestamp, not a Solana slot. To bind the Pyth update to the same slot $s$, a third key, Config.pythSlotAttestor, signs a message that wraps the complete Pyth payload:

Bytes	Field
0–20	ASCII OPENPROP_PYTH_SLOT_V1
21–52	OpenProp program id
53–84	Config address
85–92	source slot $s$, u64
93–124	slot hash of $s$, equal to the Surge signed hash
125–126	Pyth payload length $n$, u16
127–126+$n$	the Pyth Pro payload, byte for byte

The message must be exactly $127+n$ bytes long. The program id and Config address bind the attestation to one deployment. Config.oracleSlotAttestationPolicy must be 1, which configuration validation also enforces; any other value fails the post with UNDECIDED_PARAMETER (6003).

Freshness and replay order

Once both updates are bound to $s$, the program applies two ordering rules:

1. Source age. $t-s\le N_r$, where $t$ is Clock.slot and $N_r$ is Config.refStalenessSlots. Otherwise the post fails with REF_STALE (6005).
2. Replay order. If the Pyth timestamp and $s$ both equal the stored cursors lastPythTimestampUs and lastSwitchboardSlot, the post returns success and changes nothing. Otherwise the timestamp must be strictly greater than lastPythTimestampUs and $s$ must be at least lastSwitchboardSlot, or the post fails with INVALID_ORACLE.

The Pyth timestamp orders updates and nothing else. Every expiry, staleness and cooldown rule counts Clock.slot, never Clock.unix_timestamp.

4.4 The two-source median

With two sources the median is the midpoint. The program stores

$$m=\lfloor \frac{p_P+p_S}{2}\rfloor ,c=\max \left(c_P,\lfloor \frac{|p_P-p_S|}{2}\rfloor \right)$$

where:

• $m$ is the reference mid written to RefPrice.mid;
• $c$ is the combined confidence written to RefPrice.confidence;
• $p_P,c_P$ are the scaled Pyth Pro price and confidence, and $p_S$ the scaled Surge price.

Surge publishes no confidence interval, so the second term stands in for it: half the disagreement between the sources. $c$ is never narrower than either Pyth's own interval or the spread between the two feeds. The same post writes $p_P$, $c_P$ and $p_S$ to their own fields, and sets pythSlot, switchboardSlot and sourceSlot to $s$ and postedSlot to $t$.

Using the contract's sample sources, $p_P=199,990,000$ and $p_S=200,010,000$ with $c_P=10,000$ (0.01 USDC):

Quantity	Value	Relative to $m$
$m$	200,000,000 (200.00 USDC)
$|p_P-p_S|$	20,000	1.0 bps
$c=\max (10,000,10,000)$	10,000	0.5 bps

4.5 Confidence and divergence gates

Two gates test the quality of the stored reference:

$$\text{confidence:}c\cdot 10^4\le m\cdot \kappa \text{divergence:}|p_P-p_S|\cdot 10^4\le m\cdot \delta$$

where:

• $\kappa$ is Config.confidenceBps and $\delta$ is Config.divergenceBps, both in basis points;
• $c$, $m$, $p_P$, $p_S$ are as in §4.4.

Both comparisons use integer arithmetic with no division, and equality passes. Because $c$ includes half the source disagreement, the confidence gate also fails whenever the sources differ by more than $2\kappa$ basis points of $m$. Both limits are set by the deployment's parameter file. Each must be at least its immutable floor, minimumConfidenceBps and minimumDivergenceBps, fixed at initialization, and neither may exceed 10,000. The sample reference above passes for every configuration that validation accepts: it sits at 0.5 bps of confidence and 1 bps of divergence, and both gates are at least 1 bps.

The gates are applied in three places with different consequences:

Where	Failing confidence	Failing divergence
post_ref_price	post stored, breaker trips with reason 3	post stored, breaker trips with reason 5
swap_exact_in (check 3, chapter 5)	CONFIDENCE_TOO_WIDE (6007), no fill	REFERENCE_DIVERGENCE (6035), no fill
checkpoint_book, settle_epoch valuation	CONFIDENCE_TOO_WIDE	REFERENCE_DIVERGENCE

Valuation also requires a positive, fresh mid and two positive source prices. It does not read the breaker flag, so a book can be marked and an epoch settled through a halt caused by a price move, but never at an uncertain or contested price.

4.6 Reference staleness

Staleness is measured in slots against Config.refStalenessSlots ($N_r$). The v0 set uses 10 slots, about 2 seconds at 200 ms slots. It is checked at four points:

Point	Test	On failure
post_ref_price, new update	$t-s\le N_r$	REF_STALE; the post is rejected
post_ref_price, previous reference	$t-{\text{sourceSlot}}_{\text{old}}\le N_r$	gap detected: breaker trips with reason 2 before the new value is written
swap_exact_in	$t-t_x\le N_r$ for $t_x$ each of sourceSlot, pythSlot, switchboardSlot	REF_STALE, no fill
checkpoint_book	$t-\text{sourceSlot}\le N_r$	breaker trips with reason 2 and any cooldown in progress restarts; no checkpoint is taken

deposit also requires a fresh reference and a clear breaker, and fails with REF_STALE otherwise.

The gap check runs before the new value overwrites sourceSlot. A pair whose reference went stale therefore cannot skip the cooldown by posting a fresh price: the post that repairs the gap trips the breaker first, and the resume delay runs from there. refStalenessSlots must be at least 1 and at least the immutable floor minimumRefStalenessSlots.

4.7 The pair breaker

The pair breaker halts every book in the pair at once. Swaps read bit 0 of RefPrice.flags as check 8 and fail with PAIR_HALTED (6008) while it is set (chapter 5). The breaker trips on four conditions detected by the program, stale reference, wide confidence, source divergence and price move, and on a guardian halt.

The price history

history is a ring of 150 buckets of 24 bytes each: a source slot, the lowest mid posted for that slot and the highest. A post writes into bucket $s\mathrm{mod}150$. If the bucket already holds slot $s$, the post widens its low and high. Otherwise it overwrites the bucket with $(s,m,m)$. Several posts within one source slot are kept as their low and high, and the ring covers the most recent 150 source slots.

The move rule

Before writing its own bucket, the post compares the new mid with every bucket inside the window:

$$\text{trip if}\exists j,\exists p\in \{{\ell }_j,h_j\},p>0:0\le s-s_j<W\text{ and }|m-p|\cdot 10^4>p\cdot \mu$$

where:

• $s$ is the new source slot and $m$ the new mid;
• $s_j$, ${\ell }_j$, $h_j$ are the slot, low and high of bucket $j$;
• $W$ is Config.breakerWindowSlots, between 1 and 150;
• $\mu$ is Config.breakerMoveBps, at least the immutable floor minimumBreakerMoveBps.

The window is strict: with $W=150$ it holds slot $s$ and the 149 slots before it. The move is measured relative to the older price $p$, and a move of exactly $\mu$ does not trip. The v0 set uses $\mu =300$ bps and $W=150$ slots: a move above 3% within 150 slots, about 30 seconds. Against a stored 200.00 the threshold is $200\times 300/10^4=6.00$ USDC, so 206.00 passes and 206.01 trips. Against a bucket with low 200.00 and high 201.00, a new mid of 194.50 trips on the high: $|194.50-201.00|=6.50>6.03$.

When several conditions fail in one post, the stored reason is the last one evaluated: price move (4) over divergence (5) over confidence (3).

Trip, clear and resume

After the gates and the move rule, each post applies one transition:

1. A condition fails. If bit 0 is clear, the program sets trippedSlot to $t$ and emits an incident event (kind 3: reason, action 0, mid). It sets bit 0, writes the reason, and zeroes clearedSlot and resumeSlot. A condition that persists keeps zeroing them, so the cooldown cannot start while the condition holds.
2. The post is clean and the breaker is active without a guardian halt. On the first clean post, clearedSlot becomes $t$ and resumeSlot becomes $t+D$, where $D$ is Config.resumeDelaySlots. On any clean post with $t\ge \text{resumeSlot}$, the program clears bit 0, sets the reason to 0 and emits an incident event with action 1.

The v0 set uses $D=50$ slots, about 10 seconds. $D$ is bounded above by the immutable maximumResumeDelaySlots. Lifting a halt always takes a post: the program lifts it only while processing a clean reference at or after resumeSlot.

For a sustained step from 200.00 to about 206.10 between source slots $s_0$ and $s_0+1$, with the v0 values:

Source slot	Mid	Move test	State after the post
$s_0$	200.00	clean	clear
$s_0+1$	206.10	6.10 > 6.00 against bucket $s_0$	tripped, reason 4
$s_0+2$ … $s_0+149$	≈ 206.10	bucket $s_0$ still inside the window	tripped; clearedSlot stays 0
$s_0+150$	≈ 206.10	bucket $s_0$ aged out; clean	tripped; clearedSlot = $t$, resumeSlot = $t+50$
posts with Clock.slot ≥ resumeSlot	≈ 206.10	clean	clear; incident with action 1

A sustained step therefore halts the pair for about 200 slots, roughly 40 seconds. Throughout, checkpoint_book and settle_epoch can still mark at the new price, because valuation does not read the breaker flag.

Guardian halt and admin resume

halt_pair (tag 13) is signed by Config.guardian or by the optional halt-only delegate Config.guardianHaltSigner. It sets both flag bits (value 3), reason 1 and trippedSlot, and emits an incident event. Repeating it while a guardian halt is in place changes nothing. While bit 1 is set, no post can lift the halt. Only resume_pair (tag 20), signed by Config.admin, clears bit 1, and it requires a fresh reference, failing otherwise with REF_STALE. It leaves bit 0 set, sets clearedSlot to $t$ and resumeSlot to $t+D$, and hands the pair back to the ordinary cooldown above. Neither instruction moves funds.

4.8 Parameters

Config field	Role	Value
refStalenessSlots	maximum reference age	10 slots (v0)
breakerMoveBps	move threshold $\mu$	300 bps (v0)
breakerWindowSlots	move window $W$, 1 to 150	150 slots (v0)
resumeDelaySlots	cooldown $D$ after the condition clears	50 slots (v0)
confidenceBps	confidence gate $\kappa$	set by the deployment's parameter file
divergenceBps	divergence gate $\delta$	set by the deployment's parameter file
oracleSlotAttestationPolicy	Pyth slot attestation required	must be 1
pythSigner, switchboardSigner, pythSlotAttestor	Ed25519 keys whose signatures are accepted	set at initialization
pythFeedId, switchboardFeed	the SOL/USDC feed on each source	set at initialization
minimumConfidenceBps, minimumDivergenceBps, minimumRefStalenessSlots, minimumBreakerMoveBps, maximumResumeDelaySlots	immutable envelope bounding later changes	fixed at initialization

Under set_params, raising confidenceBps, divergenceBps, refStalenessSlots or breakerMoveBps counts as loosening, as does lowering resumeDelaySlots or breakerWindowSlots. A loosening change waits timelockEpochs × epochSlots slots, and at least one epoch longer than the withdrawal queue. A tightening change applies immediately. The signer keys and feed identities change only through rotate_identities, which always waits the full timelock.

5. The five checks

OpenProp names five conditions a fill must meet: the quote is fresh, its mid is inside the band around the reference, inventory skew stays inside its limit after the fill, the book's loss windows are not breached, and the pair breaker is not tripped. The program enforces them as nine ordered checks. The five are joined by a book-state check, a validity check on the reference itself and a check of the taker's signed minimum output, and the loss check is split into an hourly and an epoch window.

All nine run in the shared rules crate openprop-rules (rules version 0.6.0). The same source is compiled into the on-chain program, linked into the quoter SDK and, through it, the Jupiter adapter, and compiled to the WASM module that the API and the web app evaluate. swap_exact_in calls evaluate_runtime_swap_with_state with the current Clock.slot, the Quote, the RefPrice, the book's tracked inventory and the risk parameters read from Config. The engine computes the whole fill in memory and returns a result. The program writes book state and moves tokens only when that result is a fill or a partial fill. A rejection returns the error of the first failing check, and the transaction leaves every account unchanged.

5.1 Order of evaluation

#	Contract key	Test	Config parameters	Error on failure	Outcome
0	(runtime)	slot before the book's epoch end		EPOCH_NOT_READY (6026)	no fill
1	book-state	book live; input nonzero		BOOK_PAUSED (6010), BOOK_HALTED (6009), INVALID_AMOUNT (6033)	no fill
2	freshness	ladder valid; quote age within limit	quoteStalenessSlots, retailDeltaLimitBps, maxLevelBaseAtoms	QUOTE_LADDER_INVALID (6034), QUOTE_STALE (6004)	no fill
3	reference	reference positive, fresh, confident, sources agree	refStalenessSlots, confidenceBps, divergenceBps	INVALID_ORACLE (6027), REF_STALE (6005), CONFIDENCE_TOO_WIDE (6007), REFERENCE_DIVERGENCE (6035)	no fill
4	band	quote mid within the band	bandBps	MID_OUTSIDE_BAND (6006)	no fill
5	skew	post-fill skew within the cap, applied level by level	skewBps	SKEW_LIMIT (6011), INSUFFICIENT_LIQUIDITY (6016)	partial fill at the cap; no fill if nothing fits
6	hourly-loss	projected hourly loss within limit	hourlyLossBps, hourlyWindowSlots	HOURLY_LOSS_LIMIT (6012)	no fill
7	epoch-loss	projected epoch loss within limit	epochLossBps	EPOCH_LOSS_LIMIT (6013)	no fill
8	pair-breaker	RefPrice flag bit 0 clear		PAIR_HALTED (6008)	no fill
9	slippage	total output at least the signed minimum		SLIPPAGE_EXCEEDED (6015)	no fill

A configuration with an unset or out-of-range limit (any basis-point limit above 10,000, or maxLevelBaseAtoms of zero) fails at position 1 with UNDECIDED_PARAMETER (6003). Configuration validation prevents that state from being written.

The engine records one status per check in check_status[9]: 0 not reached, 1 passed, 2 failed, 3 partial (skew only). The overall status is 0 for a rejection, 1 for a complete fill and 2 for a partial fill. A partial result carries the reason the walk stopped, SKEW_LIMIT or INSUFFICIENT_LIQUIDITY, in its error field, but the swap succeeds. The contract exposes the nine keys and statuses to clients so that a quote shown in an interface explains a rejection the same way the program would.

5.2 Before the checks: epoch end and the pre-fill mark

Two runtime steps come first. A book trades only inside its current epoch: if $t\ge$ Book.epochEndSlot, where $t$ is Clock.slot, the swap fails with EPOCH_NOT_READY until settle_epoch rolls the book into the next epoch. A book that has never been allocated has an epochEndSlot of zero and fails the same way.

The engine then marks the book's loss state from its tracked inventory before the fill (§5.8). This step is where an expired hourly window resets. Its results replace the stored hourlyLoss and epochLoss counters as inputs to checks 6 and 7, so the stored counters are records of the last mark and are never trusted as inputs.

5.3 Check 1: book state

The book's state byte (Book.flags) must be 0, live. State 2 is a pause set by the quoter's cold key through pause_book and fails with BOOK_PAUSED. State 1 is a risk halt set by checkpoint_book on a loss-limit breach and fails with BOOK_HALTED. A risk halt is cleared only by the epoch rebalance in settle_epoch, and a cold-key pause cannot overwrite it. The same position rejects an amount_in of zero with INVALID_AMOUNT.

5.4 Check 2: quote freshness

The quote is first checked for a well-formed ladder. update_quote stores the ladder as written and leaves validation to every swap. The quote fails with QUOTE_LADDER_INVALID if its mid is zero, if its retailDeltaBps exceeds Config.retailDeltaLimitBps, or if on either side a level has an offset of 10,000 bps or more, a size above Config.maxLevelBaseAtoms, or an offset smaller than the level before it. Offsets therefore never decrease from level 1 to level 5, and level 1 is the best price.

Freshness is then

$$0\le t-t_q\le N_q$$

where:

• $t$ is Clock.slot at execution;
• $t_q$ is Quote.slot, the slot update_quote last wrote;
• $N_q$ is Config.quoteStalenessSlots.

A failure returns QUOTE_STALE. The v0 set uses $N_q=2$: a quote written at slot $t_q$ fills through slot $t_q+2$ and fails from slot $t_q+3$, about 600 ms later at 200 ms slots. Staleness is counted in slots, never in unix_timestamp.

5.5 Check 3: reference validity

The engine re-validates the stored reference on every swap:

1. RefPrice.mid, pythPrice and switchboardPrice are all positive, or INVALID_ORACLE.
2. $t-t_x\le N_r$ for each of sourceSlot, pythSlot and switchboardSlot, where $N_r$ is Config.refStalenessSlots, or REF_STALE.
3. $c\cdot 10^4\le p\cdot \kappa$, or CONFIDENCE_TOO_WIDE.
4. $|p_P-p_S|\cdot 10^4\le p\cdot \delta$, or REFERENCE_DIVERGENCE.

Here $p$ is the reference mid, $c$ its combined confidence, $p_P$ and $p_S$ the two source prices, $\kappa$ = confidenceBps and $\delta$ = divergenceBps. Chapter 4 derives each quantity. The v0 set uses $N_r=10$ slots. The confidence and divergence limits are set by the deployment's parameter file.

5.6 Check 4: band

$$|m_q-p|\cdot 10^4\le p\cdot \beta$$

where $m_q$ is Quote.mid, $p$ the reference mid and $\beta$ = Config.bandBps. A failure returns MID_OUTSIDE_BAND. The band bounds how far a quoter's ladder can be centred away from the reference. A quote mid of 202.00 against a reference of 200.00 is 100 bps away and is rejected for any bandBps below 100. The band width is set by the deployment's parameter file.

5.7 Check 5: inventory skew

Skew compares the reference value of the book's SOL with its USDC:

$$V(B)=\lfloor \frac{B\cdot p}{10^9}\rfloor ,\sigma (B,Q)=\frac{|V(B)-Q|}{V(B)+Q}$$

where:

• $B$ is the book's tracked SOL in lamports (Book.trackedBase);
• $Q$ is its tracked USDC in micro-USDC (Book.trackedQuote);
• $p$ is the reference mid in micro-USDC per SOL;
• $V(B)$ is the SOL marked at the reference, in micro-USDC.

A balanced book has $\sigma =0$, and a book holding only one asset has $\sigma =1$. The admissible set for the post-fill inventory $(B^{\prime },Q^{\prime })$ depends on where the book starts:

$$\text{inside the cap:}|V(B^{\prime })-Q^{\prime }|\cdot 10^4\le (V(B^{\prime })+Q^{\prime })\cdot \gamma \text{beyond the cap:}|V(B^{\prime })-Q^{\prime }|\cdot T_0\le (V(B^{\prime })+Q^{\prime })\cdot D_0$$

where $\gamma$ = Config.skewBps, and $D_0=|V(B_0)-Q_0|$ and $T_0=V(B_0)+Q_0$ are taken from the inventory before the swap. A book already beyond the cap, which a reference move can cause, may still trade in the direction that reduces its skew, but no fill may leave it more skewed than it started.

Skew is tested inside the level walk (chapter 6) after each level's proposed fill. When a full level would leave the admissible set, the engine binary-searches for the largest quantity in $[0,q_{\text{level}}]$ that stays inside it. Absolute skew along one trade direction is V-shaped in quantity, and the starting inventory is admissible in both modes, so the admissible quantities form an interval starting at zero and the search is exact. The walk fills that quantity and stops with reason SKEW_LIMIT:

• if earlier levels or a nonzero part of this level filled, the swap is a partial fill (status 2, check status 3). The program transfers only the consumed input, and the unconsumed input never leaves the taker;
• if nothing at all fits, the swap is rejected with SKEW_LIMIT.

The limit binds at equality: a fill that brings skew exactly to the cap is admitted. On the contract's sample book, 900 SOL and 180,000 USDC at a reference of 200.00, so $V(B)=Q$, each SOL of one-directional flow moves $\sigma$ by about 11.1 bps. The 5 SOL sell worked through in chapter 6 leaves $\sigma$ at 55.55 bps. The skew limit is set by the deployment's parameter file.

5.8 Checks 6 and 7: hourly and epoch loss

Excess over hold

Losses are measured as excess over hold: the book's value now minus the value of its epoch-start inventory, both marked at the current reference:

$$E=(V(B)+Q)-(V(B_0)+Q_0)$$

where $B_0$, $Q_0$ are Book.startBase and Book.startQuote, set at the epoch rebalance. A move in the SOL price alone does not create excess, because the hold portfolio moves with it. Only trading at prices worse than the reference, or inventory built up before an adverse move, creates a loss.

The two windows

$$L_e=\max (-E,0),L_h=\max (H-E,0)$$

where:

• $L_e$ is the epoch loss: negative excess since the epoch began;
• $H$ is the hourly baseline Book.hourlyStartExcess, the excess when the current hourly window opened;
• $L_h$ is the hourly loss: the fall in excess since that baseline.

The hourly window is a fixed window, not a rolling one. At the pre-fill mark, if $t-\text{hourlyStartSlot}\ge W_h$, where $W_h$ is Config.hourlyWindowSlots, the window resets: hourlyStartSlot becomes $t$ and $H$ becomes the current pre-fill excess $E_{\text{pre}}$. The post-fill mark keeps the baseline chosen by the pre-fill mark, so a fill's own loss always counts in the window it executes in. checkpoint_book applies the same reset. settle_epoch opens a fresh window at the rebalance with $H=0$. $W_h$ is set at initialization and belongs to the clock geometry that set_params cannot change in place.

Projection

The engine marks the book twice, at the pre-fill inventory and at the post-fill inventory produced by the walk, and tests the larger of the two:

$$\max (L_h^{\text{post}},L_h^{\text{pre}})\cdot 10^4\le A\cdot {\lambda }_h,\max (L_e^{\text{post}},L_e^{\text{pre}})\cdot 10^4\le A\cdot {\lambda }_e$$

where:

• $A$ is Book.allocation, the book's reference value at the epoch rebalance, in micro-USDC;
• ${\lambda }_h$ is Config.hourlyLossBps and ${\lambda }_e$ is Config.epochLossBps.

Failures return HOURLY_LOSS_LIMIT and EPOCH_LOSS_LIMIT. The post-fill term rejects a fill that would take the book past a limit. The pre-fill term rejects every fill on a book whose window is already breached, so a profitable fill cannot reopen it. Equality passes. The v0 set uses ${\lambda }_h=50$ bps (0.5% of allocation) and ${\lambda }_e=200$ bps (2%).

Worked example

On the sample book, $A$ = 360,000 USDC, so the hourly limit is 1,800 USDC and the epoch limit 7,200 USDC. A fill loses against the reference when its level price is on the book's wrong side of $p$, which the band permits up to bandBps.

Situation	$H$	$E_{\text{pre}}$	$E_{\text{post}}$	$L_h$ pre / post	$L_e$ post	Result
Fill losing 60.00 against the reference	+40.00	−1,700.00	−1,760.00	1,740.00 / 1,800.00	1,760.00	passes: hourly loss equals the limit
Same fill, losing 60.000001	+40.00	−1,700.00	−1,760.000001	1,740.00 / 1,800.000001	1,760.000001	HOURLY_LOSS_LIMIT
Window expired at the pre-fill mark	reset to −1,700.00	−1,700.00	−1,760.00	0 / 60.00	1,760.00	passes
Profitable fill on a breached window	+40.00	−1,760.000001	−1,750.00	1,800.000001 / 1,790.00	1,750.00	HOURLY_LOSS_LIMIT

All amounts are in USDC. The contract's recorded vectors reject a book carrying 1,801 USDC of hourly loss or 7,201 USDC of epoch loss on this allocation.

What is persisted

On success the program writes the post-fill hourlyLoss, epochLoss and epochExcess, and the window's hourlyStartSlot and hourlyStartExcess, which may have just reset. On rejection nothing is written, including a pending window reset, which the next swap or checkpoint performs again. The swap never halts a book. checkpoint_book, which a cranker calls about every 1,500 slots, applies the same marks. If epoch loss exceeds its limit it halts the book with reason 7, otherwise if hourly loss exceeds its limit it halts it with reason 6. Either halt sets the book's state to 1 and records the trip in the Quoter's trip bitmaps, which the tier rules read. From then on, check 1 rejects every swap until the epoch rebalance.

5.9 Check 8: pair breaker

The swap fails with PAIR_HALTED while bit 0 of RefPrice.flags is set. Chapter 4 describes how the bit is set by a stale reference, wide confidence, source divergence, a price move above breakerMoveBps within breakerWindowSlots, or a guardian halt, and how it clears resumeDelaySlots after the condition clears. The breaker covers every book of the pair because all of them read the same RefPrice.

5.10 Check 9: slippage

$$\text{out}\ge \text{min\_amount\_out}$$

where out is the total output of the walk, partial or complete, and min_amount_out is the minimum the taker signed into the instruction. A failure returns SLIPPAGE_EXCEEDED. This check is what bounds a partial fill for the taker: a route that needs the full amount sets a minimum the partial output cannot reach.

5.11 Equality at the limit

Every limit is tested as a cross-multiplied integer inequality, and every limit admits its boundary value:

Check	Passes when	Fails when
Quote freshness	age $=N_q$	age $>N_q$
Reference age	age $=N_r$	age $>N_r$
Confidence	$c\cdot 10^4=p\cdot \kappa$	$c\cdot 10^4>p\cdot \kappa$
Divergence	equal to the limit	above the limit
Band	mid exactly bandBps from the reference	further
Skew	post-fill skew exactly at skewBps	above: the fill is trimmed to the cap
Hourly, epoch loss	loss exactly at the limit	above
Slippage	output equals the minimum	output below the minimum

6. Swap execution

swap_exact_in is the instruction aggregators route to. It fills an exact input amount against one book's current quote. With side 0 the taker sells SOL for USDC against the bids. With side 1 the taker buys SOL with USDC against the asks. The instruction runs in four stages: it validates the accounts, evaluates the nine checks and the level walk in the shared rules engine (chapter 5), writes the book, and makes two SPL Token transfers. It makes no other cross-program call, emits no logs and allocates nothing on the heap.

6.1 Instruction and accounts

The instruction has wire tag 1 and a 17-byte body:

Bytes	Field	Meaning
0	side	0: sell SOL (SellBase); 1: buy SOL (BuyBase)
1–8	amount_in	exact input: lamports when selling, micro-USDC when buying
9–16	min_amount_out	smallest acceptable total output, signed by the taker

It takes ten accounts, or eleven with a retail signer:

#	Account	Access	Validation	Error
0	taker	signer	must sign	UNAUTHORIZED (6002)
1	Config	read	program-owned, kind 0, version 6	INVALID_ACCOUNT (6001)
2	RefPrice	read	kind 2; pair equals Book.pair	INVALID_ACCOUNT
3	Book	write	kind 5	INVALID_ACCOUNT
4	Quote	read	kind 6; Quote.book equals the book address	INVALID_ACCOUNT
5	book SOL account	write	equals Book.baseToken; mint Config.baseMint; authority the book	INVALID_ACCOUNT, INVALID_TOKEN_ACCOUNT (6029)
6	book USDC account	write	equals Book.quoteToken; mint Config.quoteMint; authority the book	as above
7	taker SOL account	write	mint Config.baseMint; authority the taker	INVALID_TOKEN_ACCOUNT
8	taker USDC account	write	mint Config.quoteMint; authority the taker	INVALID_TOKEN_ACCOUNT
9	SPL Token program	read	TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA	INVALID_TOKEN_ACCOUNT
10	retail signer (optional)	signer	equals Config.retailSigner	none: pricing falls back to standard

Every token account must be a 165-byte account owned by the classic SPL Token program and initialized. A wrong account count, body length or side value fails with INVALID_INSTRUCTION (6000). The book's token balances must also cover its tracked inventory, trackedBase and trackedQuote (§6.6), or the swap fails with INVALID_ACCOUNT.

A swap write-locks the Book and the four token accounts and only reads the Quote. update_quote write-locks only the Quote. The book PDA has seeds ["book", quoter, pair], and the Quote PDA has seeds ["quote", book].

6.2 The level walk

After checks 1 to 4 pass (chapter 5), the engine walks one side of the ladder: the bids for a sell, the asks for a buy. It takes levels in order from level 1 outward. Offsets never decrease from one level to the next, so level 1 is the best price. A level with zero size is skipped. For each level $i$:

$$o_i^{\ast }=\{\begin{array}{ll}\max (o_i-\rho ,0)& \text{retail flow}\\ o_i& \text{otherwise}\end{array}{P}_i=\{\begin{array}{ll}\lfloor m_q(10^4-o_i^{\ast })/10^4\rfloor & \text{sell (bids)}\\ \lfloor m_q(10^4+o_i^{\ast })/10^4\rfloor & \text{buy (asks)}\end{array}$$

where:

• $o_i$ is the level's offset in bps and $\rho$ is Quote.retailDeltaBps;
• $m_q$ is Quote.mid in micro-USDC per SOL;
• $P_i$ is the level price in micro-USDC per SOL.

The quantity and output at the level then depend on the side:

$$\text{sell:}{q}_i=\min \left(R,z_i,\lfloor \frac{(Q+1)\cdot 10^9-1}{P_i}\rfloor \right),u_i=\lfloor \frac{q_i{P}_i}{10^9}\rfloor$$ $$\text{buy:}{q}_i=\min \left(\lfloor \frac{R\cdot 10^9}{P_i}\rfloor ,z_i,B\right),u_i=\lceil \frac{q_i{P}_i}{10^9}\rceil$$

where:

• $R$ is the input not yet consumed: lamports for a sell, micro-USDC for a buy;
• $z_i$ is the level size in lamports;
• $B$, $Q$ are the book's SOL and USDC after the previous levels;
• $q_i$ is the SOL that changes hands at level $i$, in lamports;
• $u_i$ is the USDC that changes hands: paid to the taker on a sell, charged to the taker on a buy.

On a sell, the third term caps $q_i$ so that $u_i$ never exceeds the book's USDC. On a buy, $q_i\le B$ caps it at the book's SOL. The proposed inventory is then tested against the skew cap, and the quantity is trimmed by binary search if it fails (§5.7). The engine applies the level, $B\pm q_i$ and $Q\mp u_i$, records a level fill (level, price, input, output, lamports) and reduces $R$ by the input spent: $q_i$ on a sell, $u_i$ on a buy. The walk continues until $R=0$ or a stop condition ends it:

Condition	Stop reason	Result
input consumed ($R=0$)		complete fill (status 1)
sell: the book's USDC cannot pay for the full level	INSUFFICIENT_LIQUIDITY	partial fill, or rejection if nothing filled
buy: the book's SOL is exhausted	INSUFFICIENT_LIQUIDITY	partial fill, or rejection if nothing filled
skew cap reached	SKEW_LIMIT	partial fill, or rejection if nothing fits
a level's USDC amount rounds to zero after an earlier fill	INSUFFICIENT_LIQUIDITY	partial fill
all five levels used with $R>0$	INSUFFICIENT_LIQUIDITY	partial fill

A sell too small to earn one micro-USDC at the first level, such as 1 lamport, is rejected with INVALID_AMOUNT. The per-level fills are not logged on chain. Clients recompute them with the same rules crate.

Rounding

Every rounding step is fixed in the code:

Quantity	Rounding	In whose favour
bid price $P_i$	down	the book
ask price $P_i$	down	the taker, by less than one micro-USDC per SOL
USDC paid to a seller, $u_i$	down	the book
SOL a buyer can afford, $\lfloor R\cdot 10^9/P_i\rfloor$	down	the book
USDC charged to a buyer, $u_i$	up	the book
inventory mark $V(B)$ in skew and loss checks	down	neither; used for limits, not for payment

At integer bps offsets on a mid that is a multiple of 10,000 micro-USDC, such as 200.00, both price formulas are exact. The amount rounding then decides every residual atom, and the book keeps it.

6.3 Partial fills and the minimum output

A partial fill (status 2) is a successful swap. The program transfers only the consumed input, and the rest never leaves the taker's account. The output is still checked against min_amount_out (check 9), so a taker that needs the whole amount filled sets a minimum the partial output cannot reach. The Jupiter adapter evaluates the same rules on its account snapshot and returns no quote for an amount that would fill only partially. A routed swap is therefore complete at quote time, and min_amount_out governs if the book changes before execution.

Selling 40 SOL into the sample bids exhausts the ladder. All five levels fill, 31 SOL for 6,194.46 USDC at an average of 199.82, and the walk ends with $R$ = 9 SOL. The result is a partial fill with reason INSUFFICIENT_LIQUIDITY, and the 9 SOL stay with the taker. The result also requires skewBps to admit the post-fill skew of 344.29 bps.

6.4 Worked example: the sample ladder

The examples use the contract's sample book: quote mid 200.00 equal to the reference, levels at 1, 2, 4, 8 and 12 bps of 1, 2, 4, 8 and 16 SOL on each side, a retail delta of 1 bps, and a book holding 900 SOL and 180,000 USDC at its epoch start. They assume a fresh quote and reference, a maxLevelBaseAtoms of at least 16 SOL so the ladder is valid, and a skewBps of at least 56. The figures were produced by the shared rules engine.

Selling 5 SOL

Level	Offset	Price (USDC)	Size (SOL)	Filled (SOL)	Output (USDC)	Remaining (SOL)
1	1 bps	199.98	1	1	199.980000	4
2	2 bps	199.96	2	2	399.920000	2
3	4 bps	199.92	4	2	399.840000	0
Total				5	999.740000

The taker receives 999.74 USDC, an average of 199.948 USDC per SOL, 2.60 bps below the mid. The book ends at 905 SOL and 179,000.26 USDC. Marked at 200.00, its excess over hold rises by 0.26 USDC, the spread it captured, and its skew moves from 0 to 55.55 bps.

Buying with 1,000 USDC

Level	Offset	Price (USDC)	Affordable (SOL)	Filled (SOL)	Charged (USDC)	Remaining (USDC)
1	1 bps	200.02	4.999500049	1.000000000	200.020000	799.980000
2	2 bps	200.04	3.999100179	2.000000000	400.080000	399.900000
3	4 bps	200.08	1.998700519	1.998700519	399.900000	0
Total				4.998700519	1,000.000000

At level 3 the remaining 399.90 USDC buys $\lfloor 399,900,000\cdot 10^9/200,080,000\rfloor$ = 1,998,700,519 lamports. Their exact cost is 399.89999984 USDC, which the ceiling charges as 399.900000. The input is consumed exactly. The taker receives 4.998700519 SOL for 1,000 USDC, an average of 200.052 USDC per SOL, 2.60 bps above the mid. The book ends at 895.001299481 SOL and 181,000 USDC, an excess gain of 0.259896 USDC at the reference, with skew again 55.55 bps.

The same swaps as retail flow

With the configured retail signer present, each offset shrinks by the quote's 1 bps retail delta, so level 1 trades at the mid:

Swap	Level prices used (USDC)	Output	Average price
Sell 5 SOL, retail	200.00, 199.98, 199.94	999.840000 USDC	199.968
Buy with 1,000 USDC, retail	200.00, 200.02, 200.06	4.999200239 SOL	200.032

6.5 The two token transfers

When the result status is nonzero, the program writes the book (§6.6), releases its account borrows and makes exactly two SPL Token Transfer calls:

Side	Transfer 1: input	Transfer 2: output
Sell SOL	input_consumed lamports, taker SOL → book SOL, signed by the taker	output_amount micro-USDC, book USDC → taker USDC, signed by the book PDA
Buy SOL	input_consumed micro-USDC, taker USDC → book USDC, signed by the taker	output_amount lamports, book SOL → taker SOL, signed by the book PDA

The book PDA signs with seeds ["book", quoter, pair, bump]. Only swap_exact_in and epoch settlement can make the book sign. The quoter's keys cannot move book tokens. The design estimates the two transfers at about 10k CU of the swap's cost.

6.6 Inventory tracking on the book

The rules engine never reads token balances. It works on the book's tracked inventory, trackedBase and trackedQuote, which only swaps and settlement change. The program requires the real balances of the book's token accounts to be at least the tracked amounts. Tokens sent to a book unsolicited are therefore excluded from its performance, and settlement sweeps them to the LP vault. On success the program writes:

Fields	Value written
trackedBase, trackedQuote	post-fill inventory from the walk
hourlyStartSlot, hourlyStartExcess	the loss window, reset if it expired (§5.8)
hourlyLoss, epochLoss, epochExcess	the post-fill marks
epochFillCount	incremented
lastFillSlot, lastFillSequence	Clock.slot and the Quote.sequence that was filled
lastFillInput, lastFillOutput, lastFillSide	consumed input, output, side
scoreBaseDelta, scoreQuoteDelta	signed inventory change, added only for external takers
epochScoredFillCount, epochFillNotional	incremented, and filled SOL marked at RefPrice.mid, only for external takers

A taker is external when it is neither the book's cold owner nor one of the hot authorities cached in the Quote. A quoter's own fills change the real inventory and count fully toward losses, excess and settlement, but they add nothing to the scoring statistics or the turnover that allocation reads.

6.7 The retail flow class and retail delta

Each quote carries a retail delta, Quote.retailDeltaBps ($\rho$), that tightens every offset for flow the program can attribute to retail users. The attributing credential is a signature from the aggregator frontend signer recorded in Config.retailSigner. A swap is priced as retail when an eleventh account is present, has signed, and equals Config.retailSigner. Any other eleventh account is priced as standard flow without error. A zero retailSigner disables the class, and the key changes only through rotate_identities after the timelock. The delta is bounded per quote by Config.retailDeltaLimitBps, and a quote above it fails check 2 with QUOTE_LADDER_INVALID. An offset smaller than the delta is floored at zero, so retail pricing never crosses the mid. The Jupiter adapter quotes standard pricing, because only the on-chain signer check unlocks the retail offsets.

6.8 Compute cost

The program's compute use is measured by LiteSVM 0.6.1 executing the SBF release artifact, and recorded in program/cu-measurements.json:

Path	Measured CU	Budget
update_quote, indexed authority	178	200
swap_exact_in, representative three-level swap	17,934	40,000
swap_exact_in, five-level sell	20,911	40,000
swap_exact_in, five-level buy	20,874	40,000
swap_exact_in, skew partial on a small book	30,974	40,000
swap_exact_in, skew partial on a large book	37,497	40,000

The highest observation, 37,497 CU, is the figure the measurement file reports for swap_exact_in. The skew-partial cases cost more than full five-level walks because of the binary search for the largest admissible quantity at the cap. Every swap writes its Book, so the 12M CU cap per writable account limits fills per book per block: the design estimates about 300 fills per book per block at 40k CU per swap. Liquidity spread across several books multiplies that capacity.

7. The vault and LP shares

Each pair has one liquidity vault. The LpVault account records the share supply, the withdrawal queue and the registry of books. Two SPL token accounts under the vault's authority hold the SOL and USDC that are not allocated to a book, and a classic SPL Token mint issues the vault's shares, OPLP. This chapter gives the account layout, the valuation the program uses to convert between tokens and shares, and the arithmetic of deposit, request_withdraw and claim. How vault inventory is divided among books is the subject of chapter 8.

7.1 Accounts

initialize_pair, signed by the admin, creates the vault, its two token accounts and the share mint in the same transaction as the pair's PairConfig and RefPrice. All of them are program-derived addresses.

Account	Seeds	Owning program	Authority
LpVault	["vault", pair]	OpenProp	—
Vault SOL account	["vault_base", pair]	SPL Token	LpVault
Vault USDC account	["vault_quote", pair]	SPL Token	LpVault
OPLP share mint	["shares", pair]	SPL Token	mint authority LpVault, 6 decimals
WithdrawBatch	["withdraw_batch", vault, epoch]	OpenProp	—
WithdrawTicket	["wd", owner, epoch]	OpenProp	—
OperationReceipt	["receipt", owner, requestId]	OpenProp	—

The LpVault account is 408 bytes:

Field	Content
pair, baseToken, quoteToken, shareMint	Bindings to the pair and to the three SPL accounts above
epoch, epochStartSlot, lastSettledEpoch	The epoch clock. Epoch $E$ runs from epochStartSlot for epochSlots slots (432,000 slots, about 24 hours at 200 ms)
shareSupply	OPLP in circulation
pendingShares	Shares burned by withdrawal requests of the current epoch and not yet reserved
reservedBase, reservedQuote	Tokens set aside for settled withdrawal batches and not yet claimed
allocatedBase, allocatedQuote	Tokens sent to books at the last settlement
bookCount, books	The registry: up to five books in canonical order
lastPrice, lastNav	Valuation price and free NAV of the last settlement
deferredQuoterFees, deferredProtocolFees	Performance fees owed and not yet paid

The vault's token accounts are debited by two instructions only. claim pays the owner of a withdrawal ticket. settle_epoch moves inventory to book token accounts and pays performance fees to quoter bond accounts and the protocol USDC account. No admin, guardian or quoter instruction transfers tokens out of these accounts.

7.2 Units and valuation

Amounts are integers in token atoms: SOL in lamports ($10^{-9}$ SOL), USDC in micros ($10^{-6}$ USDC), OPLP in share atoms ($10^{-6}$ OPLP). The reference price $P$ is RefPrice.mid, in USDC micros per whole SOL. The program values an inventory of $b$ lamports and $q$ micros as

$$V(b,q;P)=\lfloor \frac{b\cdot P}{10^9}\rfloor +q$$

where $V$ is the value in USDC micros, rounded down on the SOL leg.

deposit accepts the reference when its mid is positive, its source slot is at most refStalenessSlots behind the current slot (10 slots in v0) and the pair is not halted. settle_epoch additionally requires the confidence and the disagreement between the two oracle sources to be inside confidenceBps and divergenceBps; it can value inventory while swaps are halted by a price-move breaker.

7.3 NAV and share price

Free physical basket

The vault's inventory is spread over its own token accounts and the token accounts of every registered book. The free basket counts all of it except tokens already reserved for withdrawal claims:

$$B=B_v+\sum _{i=1}^n{B}_i-R_B,Q=Q_v+\sum _{i=1}^n{Q}_i-R_Q$$

where $B_v,Q_v$ are the vault's SOL and USDC token balances, $B_i,Q_i$ the token balances of book $i$, $n$ the bookCount, and $R_B,R_Q$ the vault's reservedBase and reservedQuote.

Economic NAV

Between settlements, books carry gains and losses that settlement will turn into bond charges and fees. deposit prices them as if the epoch settled now, so that a new LP neither buys into a loss the bond has yet to cover nor acquires fees owed to quoters and the protocol:

$${\mathrm{NAV}}^{\mathrm{econ}}=V(B,Q;P)+\sum _{i=1}^n\left(c_i-f_i\right)-D$$

where

• $x_i=V({\hat{b}}_i,{\hat{q}}_i;P)-V(b_i^0,q_i^0;P)$ is book $i$'s excess over hold this epoch, with tracked inventory ${\hat{b}}_i,{\hat{q}}_i$ (trackedBase, trackedQuote) and starting inventory $b_i^0,q_i^0$ (startBase, startQuote);
• $c_i=\min \left(\max (0,-x_i),{\beta }_i+d_i\right)$ is the first-loss coverage the book's quoter would supply, with ${\beta }_i$ the quoter's bond and $d_i$ the book's unpaid quoter credit (deferredQuoterFees);
• $e_i=\min \left(x_i,\max (0,X_i+x_i-H_i)\right)$ for $x_i\ge 0$, else $0$, is the new excess above the high-water mark, with $X_i$ the book's cumulativeExcess and $H_i$ its highWaterMark;
• $f_i=e_i-\lfloor e_i\cdot \text{lpShareBps}/10^4\rfloor$ is the quoter and protocol part of $e_i$ (50% of it at the v0 50/40/10 split);
• $D$ is the sum of the vault's deferredQuoterFees and deferredProtocolFees.

The LP NAV is $\mathrm{NAV}=\max (0,{\mathrm{NAV}}^{\mathrm{econ}})$. While ${\mathrm{NAV}}^{\mathrm{econ}}<0$, deposits fail with FEE_LIABILITY_SHORTFALL; withdrawals and settlement continue.

Economic supply and virtual offsets

Shares burned by a withdrawal request still own part of the free basket until settlement reserves their tokens, so the program prices against the economic supply

$$S=S_{\mathrm{act}}+S_{\mathrm{pend}}$$

where $S_{\mathrm{act}}$ is shareSupply and $S_{\mathrm{pend}}$ is pendingShares.

Two configuration values, virtualShares ($V_s$, share atoms) and virtualQuoteAtoms ($V_q$, USDC micros), are added to the supply and to the NAV in every conversion. Configuration validation requires

$$V_q\cdot 10^6={\pi }_0\cdot V_s$$

where ${\pi }_0$ is initialSharePrice, in USDC micros per whole OPLP. The offsets fix the conversion rate of an empty vault at ${\pi }_0$ and keep the rate of early deposits from being set by tokens sent to the vault accounts outside deposit. No virtual asset is ever transferred; the offsets exist only in the arithmetic.

Share prices

The program and the API use two prices, in USDC per OPLP:

$$p_{\mathrm{r}}=\frac{\mathrm{NAV}}{S+V_s},p_{\mathrm{d}}=\frac{\mathrm{NAV}+V_q}{S+V_s}$$

where $p_{\mathrm{r}}$ is the redemption value of one share (sharePriceMicros in the API) and $p_{\mathrm{d}}$ the price at which deposits are converted (depositSharePriceMicros). Writing $p=\mathrm{NAV}/S$ for the vault's own per-share value,

$$p_{\mathrm{d}}=\frac{S}{S+V_s}p+\frac{V_s}{S+V_s}\cdot \frac{{\pi }_0}{10^6}$$

so the deposit price is a weighted mean of the vault's per-share value and the initial price, with weight $V_s/(S+V_s)$ on the initial price. That weight is 1 for an empty vault and falls toward zero as the supply grows.

7.4 Deposits

The instruction

deposit takes four u64 values: requestId, maxBaseAtoms, maxQuoteAtoms and minShares. The two maxima are spending limits, not exact amounts. The accounts are the owner (signer), Config, RefPrice, the vault with its token accounts and share mint, the owner's SOL, USDC and OPLP token accounts, the receipt, the token and system programs, and then every registered book as a group of five accounts (book, book SOL, book USDC, quoter, bond) in registry order. A deposit that omits a book fails, so the program always sees the whole basket and every pending bond charge and fee.

The program processes it in this order:

1. Receipt. The OperationReceipt at ["receipt", owner, requestId] binds the original payload, including both maxima. A retry with the same payload returns without effect; a different payload under the same requestId fails with REPLAY_PAYLOAD_MISMATCH.
2. Epoch window. The current slot must be below epochStartSlot + epochSlots, else EPOCH_NOT_READY. Deposits close at the nominal end of an epoch and reopen when settle_epoch advances the vault to the next one.
3. Reference. Fresh and not halted (section 7.2), else REF_STALE.
4. Registry. Each book's token balances must cover its tracked inventory, and each bond account must cover the recorded bond.
5. Basket, NAV, cap and shares, as below.
6. Transfers. The selected SOL and USDC move from the owner to the vault token accounts, the vault mints $s$ OPLP to the owner, and shareSupply grows by $s$.

Basket selection

With $S>0$, the program takes the largest basket in the free basket's physical SOL/USDC ratio that fits both maximums. With maxima $\bar{b}$ and $\bar{q}$:

$$(b,q)=\{\begin{array}{ll}\left(\bar{b},\lfloor \bar{b}Q/B\rfloor \right)& \text{if }\bar{b}Q\le \bar{q}B\\ \left(\lfloor \bar{q}B/Q\rfloor ,\bar{q}\right)& \text{otherwise}\end{array}$$

where $(b,q)$ is the basket actually transferred. The limiting maximum is consumed in full and its counterpart is rounded down to whole atoms; the unused tokens stay in the owner's accounts. The ratio comes from custody at execution, not from the snapshot the wallet signed against. The program requires $B>0$ and $Q>0$ (NON_PROPORTIONAL_DEPOSIT) and $b>0$, $q>0$ (INVALID_AMOUNT). Because a deposit adds both tokens in the vault's existing proportions, it leaves the SOL exposure per share of existing holders unchanged.

For the first deposit ($S=0$) there is no ratio to follow. Both maximums are consumed in full and must have equal reference-marked value, exactly to the atom:

$$\lfloor \frac{\bar{b}\cdot P}{10^9}\rfloor =\bar{q}$$

otherwise the deposit fails with NON_PROPORTIONAL_DEPOSIT. At a 200.00 USDC reference, 10 SOL must be paired with exactly 2,000 USDC. The first basket therefore sets the vault at equal value in SOL and USDC.

Shares, minimum and cap

With $A=V(b,q;P)$, the value of the consumed basket:

$$s=\lfloor \frac{A\cdot (S+V_s)}{\mathrm{NAV}+V_q}\rfloor$$

where $s$ is the number of share atoms minted. The deposit requires

$$s\ge \max (1,\text{minShares}),\mathrm{NAV}+A\le \text{vaultCapQuoteAtoms}$$

failing with MINIMUM_SHARES or VAULT_CAP_EXCEEDED. Only consumed value counts toward the cap, so unused maximums never cause a rejection. The v0 cap is 2,000,000 USDC. For the first deposit into an empty vault ($\mathrm{NAV}=0$), the formula reduces to $s=A\cdot 10^6/{\pi }_0$: the first LP buys at the initial share price.

Worked example

Take a vault with this state:

Quantity	Value
Reference $P$	200.00 USDC
Free basket $B$, $Q$	3,500 SOL, 500,000 USDC
$V(B,Q;P)$	$3,500\times 200+500,000=1,200,000$ USDC
Pending charges and fees, $D$	none
NAV	1,200,000 USDC
Deposit price $p_{\mathrm{d}}$ (from $S$ and the offsets)	1.200000 USDC per OPLP
vaultCapQuoteAtoms	2,000,000 USDC

An LP signs maxBaseAtoms = 10 SOL ($10^{10}$ lamports) and maxQuoteAtoms = 1,000 USDC ($10^9$ micros).

1. Limiting side: $\bar{b}Q=10\times 500,000=5,000,000$ and $\bar{q}B=1,000\times 3,500=3,500,000$. Since $\bar{b}Q>\bar{q}B$, USDC is the limiting token.
2. Basket: $q=1,000$ USDC and $b=\lfloor \frac{10^9\cdot 3.5\times 10^{12}}{5\times 10^{11}}\rfloor =7\times 10^9$ lamports, so 7 SOL. The other 3 SOL stay in the wallet. The ratio used is the vault's physical 142.857 USDC per SOL, not the 200.00 reference.
3. Value: $A=7\times 200+1,000=2,400$ USDC.
4. Cap: $1,200,000+2,400=1,202,400\le 2,000,000$. The vault had 800,000 USDC of headroom before this deposit.
5. Shares: $s=2,400/1.2=2,000$ OPLP, i.e. $2\times 10^9$ share atoms.
6. Minimum: a wallet that previewed 2,000 OPLP and signed minShares = 1,990 OPLP accepts this result. If fills in the books had changed the free basket between preview and execution, the program would recompute $b$, $q$ and $s$ at execution and reject an issuance below 1,990 OPLP.

The app computes the same preview with previewDepositV5 from the /v1/vault and /v1/pair reads, then simulates the transaction before the wallet signs.