Settlement on Solana
What happens between your click and your tokens: a 509-byte message signed by opcode's quote key, a transaction you sign, and a program that checks one against the chain before moving anything. For readers who want the mechanism.
The idea
OPmode settles by signed quote. opcode commits, off chain, to exact amounts for one wallet for up to 10 seconds. You carry that commitment to the chain inside a transaction of your own. A program verifies the commitment, re-checks every condition it was priced under, and then moves both sides together. If any check fails, nothing moves.
- Order
- Priced
- Signed
- Confirmed
- Final
Step by step
opcode signs a quote
The message is 509 bytes: a version tag, thirteen 32-byte identities and ten 8-byte integers. It names the deployment, the program, the market, your wallet, your source and destination token accounts, both mints and token programs, the amount in, the amount out, the fee, the validity window by slot and by clock, and four epochs. There is no optional field and only one way to encode a given quote.
A transaction is built around it
Two instructions: Solana's Ed25519 verification carrying the maker's key, signature and the message, then the settlement program's
execute_quote. Before them, at most the compute-budget settings and the creation of your own token account if you lack one. The settlement instruction names 21 accounts, including the market'sOracleConfig. An address lookup table keeps the whole thing at about 1,119 bytes of the 1,232 allowed, as measured on a local validator.You sign and it is sent
Your wallet signs as fee payer and as the owner of the tokens being paid. opcode submits the exact bytes you signed.
The program checks the template
It must be running at the top level, not called by another program. It must be the last instruction. The instruction before it must be the Ed25519 verification, with no accounts and exactly 621 bytes, whose offsets all point inside itself. The key in it must equal the quote authority stored in the market's own account. Anything else in the transaction beyond the allowed prelude is a rejection.
The program checks the quote against the chain
Identities match the accounts supplied. All four epochs are current. The slot and the clock are inside the window. The fee is exactly the configured rate. The token's configuration and multiplier are unchanged. The market's reference, written from a Pyth report the chain verified, still matches its
OracleConfigrecord, its source is at most 20 seconds old, its confidence and publisher count still meet the session's limits, and it has not expired; the price lies within 1% of it. Size, vault floors and the fixed-window turnover cap all hold.Three transfers and a receipt
The protocol's 20% of the fee to the fee vault; the rest of your payment, including the providers' 80% of the fee, to the pool's vault; the output from the pool's vault to you. Then every one of the five token balances is re-read and must have changed by exactly the signed amounts. A receipt account is created at an address derived from the market and the quote ID, and a fill event is emitted.
What this guarantees
| Property | How |
|---|---|
| You receive exactly what you were shown, or nothing | Amounts come from the signed bytes and are re-verified against balances after the transfers. Solana transactions are all-or-nothing. |
| A quote cannot fill twice | The receipt's address is fixed by the quote ID. Creating it a second time fails. |
| Nobody can redirect your fill | Your wallet and both of your token accounts are inside the signed message. |
| Nobody can wrap your fill in other logic | The program refuses to run unless it is top-level and last. |
| A stale quote cannot be used | Validity is bounded by slot and by clock: the markets allow at most 30 seconds and 64 slots, opcode issues quotes for up to 10 seconds, and four epochs can void a quote early. |
| A stolen quote key is bounded | It cannot withdraw. It cannot price outside the reference band, exceed size or turnover limits, or drain a vault below its floor. |
Reasons the program refuses
| Error | Meaning |
|---|---|
| Paused | The protocol or this market is halted. |
| EpochMismatch | Configuration, units, risk state or policy moved on after the quote was signed. |
| QuoteExpired | Outside the slot or clock window. |
| SignatureLayout · TransactionTemplate · QuoteEncoding | The transaction or the signed 509-byte message is not in the required shape. |
| Unauthorized | The key in the signature instruction is not the market's quote authority. |
| DomainMismatch · AccountMismatch · AccountAlias | An identity in the quote does not match an account supplied, or two accounts are the same. |
| Amount | An amount is zero, or the fee is not exactly the configured rate. |
| MintConfiguration · TokenConfiguration · NormalizationChanged | The token, an account, or the multiplier is not as registered. |
| ReferenceUnavailable · PriceBand | No fresh on-chain reference, or the price is outside the band around it. |
| OracleConfiguration · OracleProvenance · OraclePolicy | The market's OracleConfig is not valid, the reference no longer matches its verified Pyth record, or that record's price is more than 20 seconds old or outside the session's confidence and publisher limits. |
| LiquiditySharesRequired | The market's pool has no liquidity shares. |
| RiskLimit | Size, vault floor or turnover cap. |
| ParticipantPolicy | The market requires a permission this wallet does not hold. |
| BalanceDelta | A balance did not change by exactly the signed amount. |
Go deeperHow the reference gets on chain
Each market's reference is written by a separate transaction that carries a 158-byte price report signed by Pyth. Solana's Ed25519 instruction checks the signature, and the official Pyth verifier program checks, through a cross-program call, that the signer is trusted and unexpired and that the bytes are exact. The opcode program then reads those verified bytes itself: feed, channel, session, publisher count, confidence and a source time at most five seconds old. It multiplies the underlying dollar price by the token's active multiplier, read from the mint, and writes the reference together with an OracleConfig record of the report hash, source time, policy revision and normalization epoch. The reference expires at most 20 seconds after its source time. A relayer pays the fees for these transactions but chooses no price, and every OPmode market is in a one-way Pyth-only mode in which the older reference key can no longer publish. The program does not check a USDC price: it assumes one USDC equals one dollar. Measured on a local validator, a publication uses about 67,949 compute units and a fill against it about 108,037.
Go deeperWhy the signature check is so strict
Solana programs do not verify Ed25519 signatures themselves. They rely on a built-in instruction that does, and then have to prove that it verified the right bytes. That instruction's header holds offsets that may legally point into other instructions. A program that checks only “was there a valid signature in this transaction” can be shown a valid signature over one message and then read a different one. opcode requires the offsets to be the seven exact values that place key, signature and message inside that single instruction, and takes the key from its own market account rather than from the caller. The whitepaper, Chapter 10, has the full specification.