covr.Docs

Users: contract design

Position lifecycle

Every state a position can be in, every allowed transition, and the clock rule on each one.

A position's state is the state byte of its PositionV3 account. Accounts lists the codes. This page uses three clock readings, all from the Solana cluster clock in unix seconds:

  • expiry: the market's expiry, copied into the position at fill.
  • deadline: expiry + exercise_window_seconds. The window is 60 to 3,600 seconds.
  • now: the clock when the transaction runs.

The three periods

text
 fill                       expiry                        deadline
  |                            |                              |
  |       before expiry        |       exercise window        |      after the deadline
  |    opened_at <= now        |   expiry <= now < deadline   |        now >= deadline
  |         now < expiry       |                              |
  |                            |                              |
  |  early close (you)         |  exercise (maker)            |  release (anyone)
  |  transfer, sale (you)      |  flash exercise (maker)      |
  |                            |  restricted funding (maker)  |

The periods do not overlap and leave no gap. For an open covered call or put, at every second after expiry exactly one kind of exit is open: exercise until the deadline, release from the deadline on. Before expiry, neither is.

States

CodeStateTerminalReached by
0opennoa fill
1pendingnorestricted funding
2exercisedyesexercise, flash exercise, restricted delivery
3releasedyesrelease after the deadline
4early closedyesearly close before expiry
5canceled by bothyesbilateral cancellation of a funded restricted exercise
6flashnever storedthe begin step of a flash exercise, replaced by exercised in the same transaction

A terminal position never changes state again. Its only remaining step is closing the account to reclaim rent. See Closing the position account.

Covered calls

Positions with timeout_anchor 0. Exercise is atomic: the strike and the collateral move in one transaction.

text
                                  fill_v3
                                     |
                                     v
  early closed (4) <-------- +---------------+ --------> released (3)
     early_close_v3          |    open (0)   |       release_v3
     before expiry           +---------------+       after the deadline
                                 |       |
                    exercise_v3  |       |  begin_flash_exercise_v3
               in the window     |       |  in the window
                                 |       v
                                 |   +-----------+
                                 |   | flash (6) |   same transaction only
                                 |   +-----------+
                                 |       |  finish_flash_exercise_v3
                                 v       v
                               exercised (2)
FromToInstructionWho signsClock ruleWhat moves
noneopenfill_v3you, with the maker's signed quotenow < expiry, now < valid_until <= expiry, market not pausedYour collateral into the position's vault. The premium minus the fee to you. The fee to the market's fee account.
openearly closedearly_close_v3you, with a price the maker's quote key signedbefore expiry, now < valid_until <= expiryYou pay the signed amount to the maker's vault. All the collateral comes back to you.
openexercisedexercise_v3the maker's authority or operatorexercise windowThe strike from the maker's vault to you. quantity_atoms of collateral to the maker's authority. Any extra collateral and the vault's rent to you.
openflashbegin_flash_exercise_v3the maker's authority or operator, plus a temporary delegate key it choosesexercise windowquantity_atoms of collateral into the flash input for a swap.
flashexercisedfinish_flash_exercise_v3none beyond the begin signer's transactionsame transaction as beginExactly the strike to you. Any extra collateral and the vault's rent to you. The rest of the swap proceeds to the maker.
openreleasedrelease_v3anyoneafter the deadlineAll the collateral and the vault's rent back to you.

Ownership changes keep the position open and change only writer:

InstructionWho signsClock ruleEffect
transfer_position_v3youbefore expiryThe position moves to another wallet you choose. Nothing else changes.
buy_position_v3you, with a price a buying maker signedbefore expiry, market not paused, valid_until <= deadlineThe buying maker's vault pays you. Its authority becomes the writer. The original maker's obligations do not change.

The flash state exists only between two instructions of one transaction. Begin checks that finish is the last instruction of the same transaction and that no other covr instruction is in it. If the swap does not return enough, or any step fails, the whole transaction fails and the position stays open.

Restricted covered calls

Positions with timeout_anchor 1. Settlement takes two steps, because the collateral (for example a tokenized stock) may not be transferable at every moment. The maker first locks the strike, then delivery completes as soon as transfers work.

text
                    fill_restricted_v3
                            |
                            v
                     +-------------+   release_restricted_v3
                     |   open (0)  | ----------------------------> released (3)
                     +-------------+   anyone, after the deadline,
                            |          only if never funded
                            |  fund_restricted_exercise_v3
                            |  maker, in the window
                            v
                     +-------------+   complete_pending_delivery_v3
                     | pending (1) | ----------------------------> exercised (2)
                     +-------------+   anyone, any time after funding
                            |
                            |  cancel_pending_delivery_v3
                            |  maker authority and you together,
                            |  from funded_at + 7 days
                            v
                    canceled by both (5)
FromToInstructionWho signsClock ruleWhat moves
noneopenfill_restricted_v3you, with the maker's signed quoteas fill_v3As fill_v3.
openpendingfund_restricted_exercise_v3the maker's authority or operatorexercise window; the vault still holds the full quantityThe full strike from the maker's vault into the strike escrow. Sets funded_at = now and cancel_eligible_at = now + 604,800.
openreleasedrelease_restricted_v3anyoneafter the deadlineWhatever the collateral vault holds, and its rent, back to you.
pendingexercisedcomplete_pending_delivery_v3anyonenow >= funded_at, with no end, also after the 7 daysThe whole escrow to you. quantity_atoms to the maker's authority. Extra collateral and the vault's rent to you.
pendingcanceled by bothcancel_pending_delivery_v3the maker's authority (never the operator) and you, in one transactionnow >= cancel_eligible_atThe whole escrow back to the maker. The whole collateral vault to you. You keep the premium.

A cancellation request names the program, the position, both parties, the intent generation, the full strike refund, both destination accounts and an expiry time. Both parties sign the same transaction. A request that does not match the position exactly fails.

Restricted positions have no early close, no transfer, no sale and no flash exercise.

Cash-secured puts

Positions with timeout_anchor 2. You lock the full strike in cash. If the maker exercises, it takes that cash and delivers the asset to you.

text
                                  fill_put_v3
                                      |
                                      v
  early closed (4) <-------- +---------------+ --------> released (3)
   early_close_put_v3        |    open (0)   |       release_put_v3
   before expiry             +---------------+       after the deadline
                                 |       |
               exercise_put_v3   |       |  begin_flash_put_v3
               in the window     |       |  in the window
                                 |       v
                                 |   +-----------+
                                 |   | flash (6) |   same transaction only
                                 |   +-----------+
                                 |       |  finish_flash_put_v3
                                 v       v
                               exercised (2)
FromToInstructionWho signsClock ruleWhat moves
noneopenfill_put_v3you, with the maker's signed quotenow < expiry, now < valid_until <= expiry, market not pausedExactly strike_usdc of your cash into the strike escrow. The premium minus the fee to you. The fee to the market's fee account.
openearly closedearly_close_put_v3you, with an amount the maker's quote key signed, at most the strikebefore expiry, now < valid_until <= expiryThe signed amount from the escrow to the maker. The rest of the escrow and its rent to you. You pay nothing in.
openexercisedexercise_put_v3the maker's authority or operatorexercise windowThe strike from the escrow to the maker's vault. quantity_atoms of the asset from the maker's put asset vault to you. Any extra cash in the escrow, and its rent, to you.
openflashbegin_flash_put_v3the maker's authority or operator, plus a temporary delegate key it choosesexercise windowThe strike from the escrow into the flash input for a swap.
flashexercisedfinish_flash_put_v3none beyond the begin signer's transactionsame transaction as beginExactly quantity_atoms of the asset to you. Any extra cash in the escrow, and its rent, to you. The rest of the swap proceeds to the maker.
openreleasedrelease_put_v3anyoneafter the deadlineThe whole escrow and its rent back to you.
InstructionWho signsClock ruleEffect
transfer_position_v3xyoubefore expiryThe position moves to another wallet you choose. The escrow and every amount stay.
buy_put_position_v3you, with a price a buying maker signedbefore expiry, market not paused, valid_until <= deadlineThe buying maker's vault pays you. Its authority becomes the writer.

Puts never enter pending or canceled by both. Covered-call instructions refuse put positions, and put instructions refuse covered-call positions.

Closing the position account

Once a position is terminal, you can close its account and take back the rent you paid at fill. Nothing else moves.

KindsInstructionWho signsConditions
Covered callsclose_position_v3youState exercised, released or early closed.
Restricted callsclose_restricted_position_v3youState exercised, released or canceled by both.
Putsclose_position_v3xyouState exercised, released or early closed.

For all three, the maker's nonce floor (min_nonce) must already be above the position's nonce, the instruction must be at the top level of the transaction, and you pass the exact current account bytes so the record stays in transaction history. The rent goes to a plain wallet you choose. Settlement alone is not enough: the close waits until the maker has raised its floor above that nonce. covr's maker does not raise its floor that way yet, so today the position's rent does not come back. See What you pay and what you get.

Original-format positions

Positions opened in the original format use the Position account. covr's app stopped opening them in October 2026. On 21 October 2026 none was open: all 30 original-format position accounts left on chain were released. They follow the same clock rules with their own instructions.

StatusFromInstructionWho signsClock rule
1 exercisedopen (0)exercisethe maker's authority or operatorexercise window
2 releasedopen (0)releaseanyoneafter the deadline
3 early closedopen (0)early_closeyou, with a price the maker signedbefore expiry, valid_until <= expiry
still open, new writeropen (0)transfer_position, buy_positionyoubefore expiry
account closed1, 2 or 3close_settled_positionyouthe maker's min_nonce above the position's nonce, top level

Original-format status codes differ from the current ones. Check the account size before you read status: see Accounts. If the maker has since moved to the current format, closing an original position also needs the maker's migration record to have accounted for it first.

Impossible by design

Each of these is refused by the program on every transaction, not by covr's servers.

  • Leaving a terminal state. Every exit loads the position and requires it to be open (or pending, for restricted completion and cancellation). Exercised, released, early closed and canceled positions accept no transition.
  • A stored flash state. Begin and finish must be one pair in one transaction, with finish last. Every other instruction refuses a position in the flash state.
  • Exercise outside the window. Not before expiry, not at or after the deadline.
  • Release before the deadline. And never for a funded restricted position.
  • Both exercise and release. Their clock rules do not overlap, and the first one to run makes the position terminal.
  • Changing owner at or after expiry. Transfer, sale and early close all stop at expiry, so whoever is the writer at expiry receives the outcome.
  • Partial settlement. Exercise moves exactly quantity_atoms and exactly strike_usdc. Release and early close return the whole vault or escrow.
  • Paying the wrong wallet. Writer payouts go only to token accounts owned by the position's current writer. The maker's collateral or cash goes only to accounts owned by the maker's authority or to its own vaults. In a flash exercise the locked amount goes first to the temporary flash input, where the maker's swap route may spend it; finish still pays the writer in full and the rest to the maker's own accounts.
  • One-sided cancellation. Cancellation needs the maker's authority and the writer to sign the same transaction. The maker's operator cannot sign it, and it cannot run before cancel_eligible_at.
  • Early close, transfer, sale or flash on a restricted position. Those instructions accept only covered calls (or, for their put twins, only puts).
  • A pause blocking an exit. Market pauses and the maker's mint policies are read only by fills and sales. No exit reads them. Flash exercise also reads the maker's flash policy, which can stop only that route, never a release.
  • Reusing a quote nonce. A nonce opens at most one position, and a closed position's nonce is always below the maker's floor, so no fill can recreate it.

These are the program's rules. covr can upgrade the program, and an upgrade can change them. See Admin and upgrade powers.