Users: contract design
Guarantees
The properties the program enforces on every transaction, and the evidence for each. These are the program's rules. An upgrade can change them; see Admin and upgrade powers.
| Guarantee | In one line |
|---|---|
| Exact amounts | The premium and the strike are exact to the last atom, or the trade does not happen. |
| Settlement recipients | The program fixes who is paid when a position settles. A flash exercise may spend an exact, temporary allowance through an outside swap route, and must still pay you in full. |
| Chain-clock deadlines | Every time rule uses the Solana clock, not covr's servers. |
| Signatures and nonces | A maker's quote works once, on one market, for one wallet. |
| Collateral and payment | Your side is fully locked and the premium paid at fill. The maker's side is not set aside: it is paid in full at exercise, or exercise fails. |
| Flash exercise atomicity | Begin and finish succeed together in one transaction, or its instruction effects roll back. |
| No price oracle | No oracle decides exercise. It is the maker's choice at the fixed strike. The only price the program reads is a bound the maker sets for flash exercise. |
| Release stays open | Pauses and maker limits cannot disable release after the deadline. Other paths keep their own conditions. |
Exact amounts
What is enforced. The strike amount T and the gross premium G are computed with exact integer arithmetic. If either is not a whole number of atoms, or is zero, the fill fails with InvalidAmount (6002) and no tokens move. The program never rounds T or G in either direction. The market fee, floor(G × fee_bps / 10,000), rounds down to a whole atom of the payment token, so the fraction stays with you. The only other rounding is the flash exercise floor, the least the maker's swap must return, which rounds up. That is conservative for the maker and does not change what you receive. See No price oracle.
| Amount | Formula |
|---|---|
| T | Q × strike_e8 / 10^(d+2) |
| G | Q × price_e18 / 10^(d+12) |
Example, round illustrative numbers. On a $220 JitoSOL market, a quantity of 1,000,000,001 atoms (just over 1 JitoSOL) gives a strike amount of 220,000,000.22 USDC atoms. Rounding down would give a valid-looking 220,000,000. The program refuses the fill instead.
Why it matters. No one can open a position whose strike or premium differs from the signed price by a rounding error, and no rounding dust collects anywhere.
Evidence.
- A put test fills 20 atoms at a price where G would be 1.5 atoms. Rounding down would give 1 atom, which is not zero and would pass a simple "above zero" check. The program refuses it with
InvalidAmount. The same test refuses a quantity whose strike has a remainder. - A covered-call test refuses a quote priced one unit above an exact price on one whole token of a 9-decimal asset, where rounding down would still pay 3 USDC. Nothing is reserved or spent.
- A test across mint decimals from 0 to 24, on both token programs, checks that every fill, exercise and release pays exactly the integer formula, and that a quantity one step off is refused whole, with every balance unchanged.
Settlement recipients
What is enforced. The program fixes the final settlement recipients. Every transfer the program itself makes goes to a party the position names, or to a temporary flash account. During a flash exercise, the maker's temporary key holds an exact allowance over your locked amount and can spend it through an outside swap route, so those tokens can pass through accounts that no party to the position owns. The transaction succeeds only if finish pays you the required amount and sends the remaining settlement proceeds to the maker's bound accounts.
| Moment | Who can receive tokens |
|---|---|
| Fill | The position's vault or escrow (your asset or your stablecoin). You (the premium, minus the fee). The market's fee account (the fee). |
| Exercise | You (the strike, or the asset for a put, plus any extra in the vault). The maker's own vault or its owner key's account (your asset, or your stablecoin for a put). |
| Flash exercise | At begin: the temporary flash input, from which a temporary key may spend up to exactly your locked amount, through any route. At finish: you (exactly T for a call or Q for a put, plus any extra in the vault or escrow) and the maker's own vaults or its owner key's account (the rest). |
| Release | You only. |
| Early close | The original maker's vault (the price it signed). You (everything else). |
| Sale to a desk | You (the sale price). The writer field changes to the buying desk's owner key. |
| Close | Only SOL rent, to a wallet you choose. |
How the program makes sure:
- Your locked tokens sit in an account owned by the position's program address, not by covr or the maker. Only the program can sign for it, and only inside the instructions on Instructions.
- Every recipient is checked against the position. "You" means the position's current writer, read from the account. Your receiving token accounts must be owned by that wallet. The maker's receiving accounts must be its canonical vault or owned by its registered owner key.
- Every transfer is checked before and after. Before: right mint, right owner, not frozen, no delegate and no close authority other than the owner on the receiving account, enough in the source. After: the balances changed by exactly the amount, or the transaction fails with
CustodyPostTransferMismatch(7406). - A vault must be empty before it closes. Otherwise
TokenLifecycleTransfer(8303). - The premium never sits in the program. It moves from the maker's vault straight to you at fill.
Evidence. Tests check that transfers to arbitrary system wallets still settle only to the named writer, that a fee account owned by the writer, the maker or the program never mis-accounts, that the flash swap cannot reach the maker's vault, another position's input or any bound account, and that an unpaid burn or diversion of the flash input is refused at finish, while a paid one still gives you exactly T.
Chain-clock deadlines
What is enforced. Every time rule reads the Solana cluster clock (Clock::unix_timestamp) inside the program. covr's servers do not decide any deadline.
| Action | Allowed when |
|---|---|
| Fill | now < expiry and now < valid_until <= expiry |
| Early close, transfer, sale to a desk | opened_at <= now < expiry |
| Exercise, flash exercise, tokenized-stock funding | expiry <= now < expiry + window |
| Release | now >= expiry + window |
| Tokenized-stock joint cancel | now >= funded_at + 604,800 (7 days) |
Each market fixes its expiry and window when it is created. The window is between 60 and 3,600 seconds. Expiry must be between 60 seconds and 90 days after creation. Every position copies both at fill, and exits check that they still match the market.
The exercise window is half-open: at expiry + window exactly, exercise is refused and release is allowed. So exactly one of them can settle a position at any moment. The Solana clock is set by the network's validators and can differ from your device's clock, so leave a margin near a deadline.
Evidence. A boundary test runs every action at expiry − 1, expiry, deadline − 1 and deadline, and checks that each position reaches exactly one final state, including when two settlements are packed into one transaction.
Signatures and nonces
What is enforced. A maker's quote is an Ethereum-style typed signature (EIP-712) checked by the program at fill. It can be used once, on one market, by one wallet.
What the signature binds:
| Bound to | How |
|---|---|
| This program and deployment | The signing domain's contract address is derived from the deployment id and program address. |
| This one market | The domain also hashes every field of the market: its address, creator, asset, payment token, fee owner, terms, salt, expiry, window, strike, size cap and fee. The pause flag is the only field left out. |
| Calls, puts and stock calls separately | Each market type has its own domain text, and put quotes set isPut to true. A call quote cannot open a put. |
| Your wallet and this request | The quote includes the auction id and your wallet. Another wallet cannot use it. |
| The terms of the trade | Maker, nonce, price, quantity, valid_until, strike and expiry are all in the signed message. |
Signatures must be canonical: low s and v of 27 or 28. A malleated copy of a valid signature is refused.
Nonces stop reuse.
- A position's address comes from the maker's quote key and the quote's nonce. So one maker nonce can open at most one position, ever, across every market and product.
- A fill needs
nonce >= min_nonce. A maker can cancel all its outstanding quotes at once by raisingmin_nonce. The floor can only go up. - A settled position can be closed only after the floor is above its nonce, so a closed position's nonce can never open a new one.
- Early-close and sale quotes create permanent receipts keyed by maker and nonce. Each can be used once.
Evidence. Tests replay a quote signed for one market on another market and on another maker, and replay a quote signed for another wallet; all fail with BadSignature. A quote signed for another deployment is refused. Malleated signatures are refused. A closed position's nonce cannot be refilled in any market. A used close or sale receipt cannot be reused.
Limit. The domain uses a fixed chain id and does not read the cluster at run time. A copy of the program at the same address on another Solana cluster, with copied state, would accept the same quote there. That cannot touch mainnet funds.
Collateral and payment
What is enforced. Your side of the trade is fully locked at fill, and the maker pays the full premium at fill, in the same transaction. The maker's side is not locked at fill. It is paid in full at exercise, or the exercise does not happen.
| At fill | At exercise | |
|---|---|---|
| Covered call | Your full Q of the asset moves into the position's vault. The maker pays G in full. | The maker pays T in full from its vault, in the same transaction that takes your Q. If its vault holds less than T, exercise fails and no tokens move. |
| Cash-secured put | Your full T moves into the position's escrow first. The maker pays G in full. | The maker delivers Q in full from its asset vault, in the same transaction that takes your T. If it holds less than Q, exercise fails and no tokens move. |
| Tokenized-stock call | As for a covered call. | The maker must first move the full T into an escrow. Delivery then sends it all to you. |
What is reserved at fill, product by product:
| Product | Actually locked in an account at fill | Only counted at fill (maker-side caps, no tokens set aside) |
|---|---|---|
| Covered call | Your Q, in the position's vault | The maker's usage counters add Q and T, its exposure adds Q, its budget adds G |
| Cash-secured put | Your T, in the position's escrow | The maker's put usage adds Q and T, its put exposure adds Q, its budget and ledger add G |
| Tokenized-stock call | Your Q, in the position's vault. The maker's T is escrowed later, inside the exercise window. | As for a covered call |
The counters cap how much a maker can take on. They are bookkeeping, not money.
The maker's exercise payment is not escrowed at fill. A maker can withdraw its vault at any time. If it cannot pay at exercise, the exercise fails. A failed exercise cannot take your collateral without paying you the full consideration: T for a call, Q for a put. After the window, a release returns your full locked amount, as long as the token transfers work (see Release stays open). You keep the premium either way. There is no partial exercise. This protects you from a maker that cannot pay. It does not remove price, lockup or token issuer risk.
Evidence. A test empties a maker's vault while a position is open: exercise then fails with no tokens moved, and release returns your full collateral. Fill tests check the exact locked and paid amounts. A put test shows a writer without enough T is refused and every balance rolls back.
Flash exercise atomicity
What is enforced. A flash exercise lets the maker sell your locked asset (or, for a put, spend your locked stablecoin) during the exercise itself. The program makes that safe with one rule: begin and finish succeed together in one transaction, or its instruction effects roll back.
beginandfinishmust both be called directly by the transaction, in the same transaction, withfinishas the very last instruction.beginchecks that the exact matchingfinishis there before it moves anything.- There is exactly one covr pair in the transaction, and nothing else may call covr.
- The swap instructions in between cannot touch your accounts, the position, its vault or escrow, or the maker's accounts.
- The swap may spend at most the locked amount, through a temporary key approved for exactly that amount on a temporary account. The route can send those tokens to outside accounts, such as swap pools. The program fixes only who is paid at finish.
finishpays you exactly what an ordinary exercise pays: T for a call, Q for a put. If the swap returned less than the floor,finishfails.- While the transaction runs, the position is in a
FLASHstate that every other instruction refuses. If any step fails, Solana rolls back every effect of the transaction: the lock, the moved collateral, the approval and every token transfer. Your tokens are back in the position, and it is open again. A failed transaction that was processed still charges its SOL network fee to whoever sent it.
Evidence. Tests cover a missing finish, a finish that is not last, a duplicate finish, two begins, wrong indices, nested and cross-position pairs, calls from another program, a forged Instructions sysvar, every protected account in a swap instruction, a swap that pays one atom below the floor, a failing swap, and running out of compute at every stage. Each one either refuses or rolls back every token balance and the position state.
No price oracle
What is enforced. The program makes no oracle-driven exercise decision. It does not consult a market price feed or a swap quote to decide whether your position is exercised. Exercise remains the maker's decision within the window. The program enforces the fixed consideration, T for a call or Q for a put, and the maker's policy bounds.
The only price the program reads is a bound the maker configures in its flash policy: a minimum sale price per token for calls, a maximum purchase price per token for puts. It uses that bound to set the flash floor, the least the swap must return, and rounds it up: ceil(Q × R / 10^d) for calls and ceil(T × 10^d / R) for puts. The floor protects the maker. You receive exactly T (call) or Q (put) whatever the swap returned.
Release stays open
What is enforced. Exercise, release, early close, transfer and close never read the market pause flag, the maker's mint policy, its budget, its exposure limit or its spend ledger. So a new-order pause and the maker's admission limits cannot disable release after the deadline. From then on, anyone can submit release for an open position. It needs no one's signature and pays only the position's writer. covr does not send it automatically: you send it from covr's app, or anyone else can.
Other paths keep their own requirements:
| Path | What it still needs |
|---|---|
| Exercise | The maker's authority or operator, inside the window, and full payment in the same transaction. |
| Flash exercise | The maker's flash policy: enabled, at the generation the maker expects, and within its size limits. A disabled policy does not stop ordinary exercise or release. |
| Early close | A current quote from the original maker. Raising the maker's nonce floor above the quote's nonce cancels it. |
| Closing the position account | The maker's nonce floor above the position's nonce, before the rent comes back. |
| Release | Working token transfers, as below. |
Release still needs the chain and the token transfers to work. A token issuer can freeze an account, and the program refuses any transfer from or to a frozen account. A frozen maker vault blocks exercise but never release, which does not touch it. A frozen receiving account of yours blocks only that account; release accepts any clean account you own. A frozen source is different. A put's escrow holds a payment token whose issuer may freeze it, and a frozen escrow must be thawed by that issuer before release can return your funds. Choosing another destination does not help. A tokenized-stock position the maker has funded is not released at all: it ends by delivery or by a cancel both parties sign.
How we test these
- On-chain test suites. The compiled program runs in a local Solana runtime with real signature checks. The suites cover every instruction on Instructions, including the attack cases above.
- Deliberate-fault (mutation) testing. We change one guard in the program at a time, rebuild it, and rerun the tests. Each change must make a test fail. A guard whose removal no test notices does not count as tested.
- Upgrade rehearsals against the live program's bytes. Before an upgrade, we read the live program's bytes from mainnet, read-only, and keep them. In a local runtime we open test positions on those bytes, upgrade through the real upgrade loader, and compare settlement outcomes and account state with the old program. The test positions, tokens and stake pool are synthetic local fixtures, not copies of user positions.
- Review of every change before it ships.
- Automated security scanning of the program source. See Security.
For how to report a problem, see Security.