covr.Docs

Guides

Fills and exercise

The gateway never tells you about a fill. You find fills on chain. Then, at expiry, you exercise the positions that are worth it before the window closes.

Find your fills

Each quote opens at most one position. Its address comes from your quote key and the quote's nonce:

ts
import { derivePosition, JITOSOL_MINT } from '@covrfun/maker-sdk';

const { position } = await derivePosition(makerEthAddress, nonce, JITOSOL_MINT);

For every quote in your journal, read that address at finalized commitment:

What you seeMeaning
The account exists, owned by the covr programFilled. Track it to expiry.
No account, the quote's validUntil has passed, and no transaction ever referenced the addressNot filled. Release the cash you held for it.
Anything elseUnknown. Keep the cash held and check again.
Warning

A missing account alone does not prove "not filled". A position can fill and later close. Check the address's transaction history too (getSignaturesForAddress), from a node that has reached the slot you read.

Read the position and your Maker account in one getMultipleAccounts call, so both come from the same slot. decodePositionV3 trusts the slot you pass; it cannot tell if the two reads came from different slots.

Exercise

Exercising pays the strike and delivers the JitoSOL, so it only makes sense when JitoSOL is worth more than the strike. The premium is already spent either way. The decision is yours; the rules are fixed by the market:

RuleValue
OpensAt the market's expiry (chain time)
Closesexpiry + window. The window is 60 to 3,600 seconds.
Who signsYour authority or your operator
PaysThe strike, from your vault, to the customer
DeliversThe locked JitoSOL, to a token account owned by your authority
Compute units400,000 (ORDINARY_V3_COMPUTE_UNIT_LIMITS.exercise)

Every position on a market expires at the same moment. Fund the vault for all strikes you plan to pay before expiry, and leave time to land every transaction inside the window.

Tip

The package ships an example keeper that exercises and releases for you, dry run by default. See Expiry keeper.

Note

You can also exercise without the strike in your vault: a flash exercise sells the JitoSOL and pays the strike in the same transaction. It needs a flash policy and your own swap instructions. The SDK has no flash builders yet, so the rest of this guide uses exercise_v3.

Customer token accounts

The exercise pays the customer into their token accounts. The program refuses a customer account that someone else could control: one with a delegate, or with a close authority other than the customer. The customer controls their own accounts and could change or close one to block your exercise. So the exercise creates fresh token accounts for the customer, owned by the customer, in the same transaction. covr's own maker does the same.

Full example

exerciseV3Instructions returns the whole transaction body, in order:

  1. a compute-unit limit of 400,000 (the default 200,000 is not enough);
  2. two fresh customer token accounts (USDC and JitoSOL);
  3. exercise_v3, paying the strike from your vault and sending the JitoSOL to your authority's token account (setup step 8).

Do not add a second compute-unit limit: the transaction would be refused. You may add a priority fee.

The job signs with one key: your authority or your operator. It needs no quote key. Save this as signer.ts next to send.ts:

ts
import { readFile } from 'node:fs/promises';
import { createKeyPairSignerFromBytes } from '@solana/kit';

// The one key this job signs with: your authority, your operator (exercise) or your watcher (pause).
// It needs no quote key, so an exercise or pause box never holds one.
export const signer = await createKeyPairSignerFromBytes(
  Uint8Array.from(JSON.parse(await readFile(process.env.SIGNER_KEYPAIR!, 'utf8'))),
);

Then exercise.ts:

ts
import {
  PROGRAM_ID, WRITER_ACCOUNT_SPACE,
  deriveMaker, derivePosition, decodeMarketV3, decodePositionV3, exerciseV3Instructions,
} from '@covrfun/maker-sdk';
import { address, createSolanaRpc } from '@solana/kit';
import { signer } from './signer.ts'; // your authority or your operator
import { send } from './send.ts';

const rpc = createSolanaRpc(process.env.RPC_URL!);
const makerEthAddress = process.env.MAKER_ETH_ADDRESS!; // your quote key's 0x address
const makerAuthority = process.env.MAKER_AUTHORITY!;    // your authority's address, pinned in config
const nonce = BigInt(process.env.NONCE!);               // this position's nonce, from your journal
const marketAddress = process.env.POSITION_MARKET!;     // this position's market, from your journal
const b64 = (data: readonly [string, string]) => Buffer.from(data[0], 'base64');

// 1. Read the market, then the position and your Maker account in ONE finalized call.
const m = await rpc.getAccountInfo(address(marketAddress), { commitment: 'finalized', encoding: 'base64' }).send();
if (!m.value || m.value.owner !== PROGRAM_ID) throw Error('not a covr market');
const market = await decodeMarketV3(marketAddress, b64(m.value.data));
const { maker } = await deriveMaker(makerEthAddress);
const { position } = await derivePosition(makerEthAddress, nonce, market.collateral);
const { context, value } = await rpc
  .getMultipleAccounts([position, maker], { commitment: 'finalized', encoding: 'base64' })
  .send();
const [posAcct, makerAcct] = value;
if (!posAcct || !makerAcct || posAcct.owner !== PROGRAM_ID || makerAcct.owner !== PROGRAM_ID)
  throw Error('position not found: this quote did not fill, or the position is closed');
const decoded = await decodePositionV3({
  position: { address: position, data: b64(posAcct.data) },
  maker: { address: maker, data: b64(makerAcct.data) },
  slot: context.slot, makerEthAddress, makerAuthority, nonce, collateral: market,
});
if (decoded.status !== 'open') throw Error(`position is ${decoded.status}`);

// 2. One transaction: compute limit, two fresh customer token accounts, exercise_v3.
//    The JitoSOL goes to your authority's token account (setup step 8) by default.
const rent = await rpc.getMinimumBalanceForRentExemption(BigInt(WRITER_ACCOUNT_SPACE), { commitment: 'finalized' }).send();
const { instructions } = await exerciseV3Instructions({
  market, position: decoded, authority: signer.address, rentLamports: rent,
});
console.log('exercised', await send(signer, ...instructions));

Run it once per position, with that position's market and nonce from your journal:

sh
SIGNER_KEYPAIR=./operator.json MAKER_ETH_ADDRESS=0x<quote key address> MAKER_AUTHORITY=<authority address> \
POSITION_MARKET=<this position's market> NONCE=<this position's nonce> \
RPC_URL=https://<your rpc> RPC_WS_URL=wss://<your rpc> npx tsx exercise.ts
ValueWhere it comes from
rentLamportsRead getMinimumBalanceForRentExemption(165) from your RPC. Rent can change, so read it each time.
makerCollateralOptional. Defaults to your authority's JitoSOL account. It must exist (setup step 8) and must be owned by the authority, even when your operator signs.

With a priority fee added, the transaction is 1,111 bytes at most when the signer also pays the fee, within Solana's 1,232-byte limit. With a separate fee payer it is 1,207 bytes, which leaves no room for a Jito tip.

Each exercise funds two fresh customer token accounts: about 0.004 SOL at current rent (2 × 0.00203928 SOL for two 165-byte token accounts), which the customer, not you, can later reclaim.

Release

If you do not exercise, nothing more is needed from you. After the window closes, anyone can call release_v3. The JitoSOL goes back to the customer, and your exposure and mint usage are freed for new orders. The customer, covr or you can send it.

To free your limits sooner, send it yourself with releaseV3Instructions. Like exercise, it creates a fresh customer-owned JitoSOL account in the same transaction, and sets a 400,000 compute-unit limit.