covr.Docs

SDK reference

Settlement

Exact USDC arithmetic for a fill, the position decoder, the builders for fill, exercise and release, and one-transaction helpers that assemble a whole exercise or release. The math returns exactly what the program computes and throws wherever the program would refuse the amount. Nothing here signs or submits.

To exercise or release, use exerciseV3Instructions and releaseV3Instructions. They return every instruction of the transaction in order. The low-level builders exerciseV3 and releaseV3 remain for custom transactions.

Units and rounding

QuantityUnitFormula
atomscollateral base units (JitoSOL: 10^-9)
priceE18USDC × 10^18 per one whole collateral token
strikeE8USD × 10^8 per whole collateral token
gross premiumUSDC atoms (10^-6 USDC)atoms × priceE18 / 10^(decimals + 12), must divide exactly, must be > 0 and ≤ 2^64 - 1
strike paymentUSDC atomsatoms × strikeE8 / 10^(decimals + 2), must divide exactly, must be > 0 and ≤ 2^64 - 1
feeUSDC atomsfloor(gross × feeBps / 10000), feeBps 0 to 1,000
writer premiumUSDC atomsgross - fee
wire quantitycollateral atoms × 10^(18 - decimals)must convert exactly both ways

Nothing is rounded except the fee, which rounds down. An amount that does not divide exactly is refused, never rounded. The vault pays the gross premium at fill (the fee is carved out of it) and the strike payment at exercise.

Worked example (the golden-vector quote): 0.5 JitoSOL (500_000_000 atoms, 9 decimals) at priceE18 = 2_400_000_000_000_000_000 (2.40 USDC per JitoSOL), strike $170 (17_000_000_000), fee 1,000 bps:

AmountValue
gross premium500_000_000 × 2.4e18 / 10^21 = 1_200_000 (1.20 USDC)
feefloor(1_200_000 × 1000 / 10000) = 120_000 (0.12 USDC)
writer premium1_080_000 (1.08 USDC)
strike payment500_000_000 × 17_000_000_000 / 10^11 = 85_000_000 (85 USDC)
wire quantity"500000000000000000"

strikePayment

Returns the USDC atoms your vault pays the writer on exercise.

ts
export declare function strikePayment(atoms: bigint, strikeE8: bigint, collateralDecimals: number): bigint;
NameTypeDescription
atomsbigintPosition size in collateral atoms. u64.
strikeE8bigintStrike, USD × 10^8. u64.
collateralDecimalsnumberCollateral mint decimals, 0 to 255.

Returns: bigint, USDC atoms: atoms × strikeE8 / 10^(collateralDecimals + 2), exact, positive.

Throws:

ConditionMessage
atoms or strikeE8 is not a bigint in [0, 2^64 - 1]maker-sdk: atoms must be a bigint in [0, u64] range (or strikeE8 ...)
collateralDecimals is not an integer 0 to 255maker-sdk: decimals must be a u8
atoms or strikeE8 is zeromaker-sdk: strike payment: atoms and price must be positive (zero is refused)
The product does not divide exactlymaker-sdk: strike payment is not exact: atoms x price is not divisible by 10^(decimals+2)
The result exceeds 2^64 - 1maker-sdk: strike payment overflows u64
ts
import { strikePayment } from '@covrfun/maker-sdk';

strikePayment(1_000_000_000n, 17_000_000_000n, 9); // 170_000_000n: 1 JitoSOL at $170 is 170 USDC

grossPremium

Returns the gross premium in USDC atoms that your vault pays at fill. The protocol fee is carved out of it.

ts
export declare function grossPremium(atoms: bigint, priceE18: bigint, collateralDecimals: number): bigint;
NameTypeDescription
atomsbigintFill size in collateral atoms. u64.
priceE18bigintPrice per whole token, USDC × 10^18. u128.
collateralDecimalsnumberCollateral mint decimals, 0 to 255.

Returns: bigint, USDC atoms: atoms × priceE18 / 10^(collateralDecimals + 12), exact, positive.

Throws: as strikePayment, with priceE18 checked against [0, u128] and the messages naming gross premium and 10^(decimals+12):

ConditionMessage
priceE18 is not a bigint in [0, 2^128 - 1]maker-sdk: priceE18 must be a bigint in [0, u128] range
Zero inputmaker-sdk: gross premium: atoms and price must be positive (zero is refused)
Not exactmaker-sdk: gross premium is not exact: atoms x price is not divisible by 10^(decimals+12)
Too largemaker-sdk: gross premium overflows u64
ts
import { grossPremium } from '@covrfun/maker-sdk';

grossPremium(500_000_000n, 2_400_000_000_000_000_000n, 9); // 1_200_000n (1.20 USDC)

fee

Returns the protocol fee in USDC atoms: floor(gross × feeBps / 10000). Use the market's feeBps.

ts
export declare function fee(gross: bigint, feeBps: number): bigint;
NameTypeDescription
grossbigintGross premium, USDC atoms. u64.
feeBpsnumberMarket fee in basis points, integer 0 to 1,000.

Returns: bigint, USDC atoms, rounded down.

Throws:

ConditionMessage
gross is not a bigint in [0, 2^64 - 1]maker-sdk: gross must be a bigint in [0, u64] range
feeBps is not an integer 0 to 1,000maker-sdk: feeBps must be an integer 0..1000
ts
import { fee } from '@covrfun/maker-sdk';

fee(1_200_001n, 1000); // 120_000n (rounded down)

writerPremium

Returns what the writer receives: gross - fee(gross, feeBps).

ts
export declare function writerPremium(gross: bigint, feeBps: number): bigint;
NameTypeDescription
grossbigintGross premium, USDC atoms. u64.
feeBpsnumberMarket fee in basis points, 0 to 1,000.

Returns: bigint, USDC atoms.

Throws: as fee.

ts
import { writerPremium } from '@covrfun/maker-sdk';

writerPremium(1_200_000n, 1000); // 1_080_000n

priceForGross

Returns the one priceE18 that pays exactly gross USDC atoms for atoms. Use it to audit a price, not to choose one: for most sizes no price pays an arbitrary gross exactly.

ts
export declare function priceForGross(gross: bigint, atoms: bigint, collateralDecimals: number): bigint;
NameTypeDescription
grossbigintTarget gross premium, USDC atoms. Positive u64.
atomsbigintFill size, collateral atoms. Positive u64.
collateralDecimalsnumberCollateral mint decimals, 0 to 255.

Returns: bigint: gross × 10^(collateralDecimals + 12) / atoms, exact.

Throws:

ConditionMessage
gross or atoms out of u64 rangemaker-sdk: gross must be a bigint in [0, u64] range (or atoms ...)
Bad decimalsmaker-sdk: decimals must be a u8
gross or atoms is zeromaker-sdk: gross and atoms must be positive
No exact price existsmaker-sdk: no exact priceE18 pays that gross for these atoms (not divisible)
The price exceeds 2^128 - 1maker-sdk: priceE18 exceeds u128
ts
import { priceForGross } from '@covrfun/maker-sdk';

priceForGross(1_200_000n, 500_000_000n, 9); // 2_400_000_000_000_000_000n

exactPriceAtOrBelow

Rounds a model price down to the greatest priceE18 whose gross premium for exactly atoms is a whole USDC atom. Bid this value, not a price derived from a rounded premium. It is how covr's own maker rounds.

ts
export declare function exactPriceAtOrBelow(priceE18: bigint, atoms: bigint, collateralDecimals: number): bigint;
NameTypeDescription
priceE18bigintYour model price, USDC × 10^18 per whole token. u128.
atomsbigintThe RFQ size in collateral atoms. Positive u64.
collateralDecimalsnumberCollateral mint decimals, 0 to 255.

Returns: bigint: floor(priceE18 / step) × step, where step = 10^(decimals + 12) / gcd(atoms, 10^(decimals + 12)). 0n means no positive exact price is at or below priceE18: skip the RFQ.

For JitoSOL, 0.5 token (500_000_000 atoms) gives step = 2_000_000_000_000: prices move in steps of 0.000002 USDC per token. A 1-atom RFQ gives step = 10^21, so its smallest exact price is 1,000 USDC per token.

Throws:

ConditionMessage
priceE18 out of u128 rangemaker-sdk: priceE18 must be a bigint in [0, u128] range
atoms out of u64 rangemaker-sdk: atoms must be a bigint in [0, u64] range
Bad decimalsmaker-sdk: decimals must be a u8
atoms is zeromaker-sdk: atoms must be positive
ts
import { exactPriceAtOrBelow, type RfqSnapshot } from '@covrfun/maker-sdk';

declare const snapshot: RfqSnapshot;
declare function myModel(snapshot: RfqSnapshot): Promise<bigint>; // your pricing
const myPriceE18 = await myModel(snapshot);
const bid = exactPriceAtOrBelow(myPriceE18, 500_000_000n, 9);
if (bid === 0n) {
  // skip this RFQ
}

wireQuantity

Converts collateral atoms to the 18-decimal wire quantity used in RFQs, intents and quotes.

ts
export declare function wireQuantity(atoms: bigint, collateralDecimals: number): string;
NameTypeDescription
atomsbigintCollateral atoms. u64.
collateralDecimalsnumberCollateral mint decimals, 0 to 255.

Returns: string, a decimal integer: atoms × 10^(18 - decimals) (for decimals above 18, atoms / 10^(decimals - 18), exact).

Throws:

ConditionMessage
atoms out of u64 rangemaker-sdk: atoms must be a bigint in [0, u64] range
Bad decimalsmaker-sdk: decimals must be a u8
Not exact (only possible above 18 decimals)maker-sdk: quantity not exact on the 18-decimal wire (precision): Amount precision loss
ts
import { wireQuantity } from '@covrfun/maker-sdk';

wireQuantity(500_000_000n, 9); // '500000000000000000'

atomsFromWire

Converts an RFQ's wire quantity back to collateral atoms. Use it on snapshot.request.quantity before pricing.

ts
export declare function atomsFromWire(quantityE18: string | bigint, collateralDecimals: number): bigint;
NameTypeDescription
quantityE18string | bigintWire quantity. A string must be a canonical decimal integer (no sign, no leading zeros, no 0x).
collateralDecimalsnumberCollateral mint decimals, 0 to 255.

Returns: bigint, collateral atoms.

Throws:

ConditionMessage
Bad decimalsmaker-sdk: decimals must be a u8
String is not a canonical decimal integercanonical unsigned integer required
String is 2^256 or moreinteger overflow
Not whole atomsmaker-sdk: wire quantity is not exact whole atoms (precision): Amount precision loss
More than 2^64 - 1 atomsmaker-sdk: wire quantity is not exact whole atoms (precision): Amount overflow
ts
import { atomsFromWire } from '@covrfun/maker-sdk';

atomsFromWire('500000000000000000', 9); // 500_000_000n

minimumExactLot

Returns the smallest atom count whose strike payment is a whole USDC atom: 10^(decimals + 2) / gcd(strikeE8, 10^(decimals + 2)). Every RFQ quantity is a multiple of it, because the gateway refuses an RFQ whose strike payment is not exact.

ts
export declare function minimumExactLot(strikeE8: bigint, collateralDecimals: number): bigint;
NameTypeDescription
strikeE8bigintStrike, USD × 10^8. Positive u64.
collateralDecimalsnumberCollateral mint decimals, 0 to 255.

Returns: bigint, collateral atoms.

This is the smallest exact size, not a size limit. The largest JitoSOL fill is capped by the program at 50 SOL of stake-pool value (JitoSOL fill cap). The SDK does not check that cap.

Throws:

ConditionMessage
strikeE8 out of u64 rangemaker-sdk: strikeE8 must be a bigint in [0, u64] range
Bad decimalsmaker-sdk: decimals must be a u8
strikeE8 is zeromaker-sdk: strikeE8 must be positive
ts
import { minimumExactLot } from '@covrfun/maker-sdk';

minimumExactLot(17_000_000_000n, 9); // 100n: $170 JitoSOL quantities move in 100-atom steps

settlementAmounts

Computes every amount of one fill at once, as the program does.

ts
export declare function settlementAmounts(input: {
    atoms: bigint;
    priceE18: bigint;
    strikeE8: bigint;
    decimals: number;
    feeBps: number;
}): {
    grossPremiumUsdc: bigint;
    feeUsdc: bigint;
    writerPremiumUsdc: bigint;
    strikeUsdc: bigint;
    quantityE18: string;
};
NameTypeDescription
input.atomsbigintFill size, collateral atoms.
input.priceE18bigintPrice per whole token, USDC × 10^18.
input.strikeE8bigintStrike, USD × 10^8.
input.decimalsnumberCollateral mint decimals.
input.feeBpsnumberMarket fee, basis points.

Returns: grossPremiumUsdc, feeUsdc, writerPremiumUsdc and strikeUsdc in USDC atoms, and quantityE18, the wire quantity string.

Throws: every error of grossPremium, fee, strikePayment and wireQuantity.

Amounts that compute here can still be refused on chain. For JitoSOL, the program caps one fill at 50 SOL of stake-pool value. In JitoSOL, the cap is 50 divided by the pool rate (SOL per JitoSOL), so it shrinks as the rate rises; see the JitoSOL fill cap. This function does not check it.

ts
import { settlementAmounts } from '@covrfun/maker-sdk';

const amounts = settlementAmounts({
  atoms: 500_000_000n,
  priceE18: 2_400_000_000_000_000_000n,
  strikeE8: 17_000_000_000n,
  decimals: 9,
  feeBps: 1000,
});
// { grossPremiumUsdc: 1200000n, feeUsdc: 120000n, writerPremiumUsdc: 1080000n,
//   strikeUsdc: 85000000n, quantityE18: '500000000000000000' }

decodePositionV3

Decodes a PositionV3 account with covr's canonical decoder and binds it to your Maker account. Use it before you exercise or release.

ts
export declare function decodePositionV3(input: PositionReadInput, d?: Deployment): Promise<Readonly<PositionV3>>;
NameTypeDescription
inputPositionReadInputThe position and Maker bytes from one finalized getMultipleAccounts read, its slot, your quote key, your authority, the nonce and the market.
dDeploymentOptional. Default MAINNET.

Returns: a frozen PositionV3.

By calling it you assert that both accounts were read at finalized commitment and are owned by the program. Check the owners yourself: the decoder does not see them. It checks the layout, every stored identity (maker, authority, quote key, genesis, deployment, collateral, USDC), the obligations, the clock terms, the funding state, and every PDA and bump.

Throws: PositionV3: <reason>, or a Maker decoding error. The reasons:

ReasonCause
zero identity, invalid hex identity, zero hex identityA bad key, quote key or d.deploymentId
invalid nonce, reserved noncenonce not a u64, or 2^64 - 1
unsupported collateral program, invalid collateral decimalsBad collateral identity
invalid observation slot, invalid minimum slot, stale observationslot not a u64, or below minContextSlot
invalid account length, account length or discriminatorPosition is not 652 bytes of PositionV3, or Maker has the wrong length
snapshot address mismatchAn address differs from the expected one
timeout anchorThe position is a cash-secured put (anchor 2), which 0.1.1 does not support, or the byte is malformed
schema, state, decimals, zero field <offset>Malformed position bytes
fence slot after observationMaker's registration slot is after slot
maker Ethereum identity, maker identityStored quote key, authority or maker differs
deployment identity, collateral identity, payment identityStored genesis, deployment, collateral or USDC differs
writer driftinput.writer given and the stored writer differs
nonce, admission generation, zero obligation, clock termsStored obligations are invalid or the nonce differs
duration outside i64, time overflow, timeout duration outside i64Time fields overflow
ordinary mode has no cancellation timeout, ordinary mode cannot carry funded or pending rights, funding in unfunded state, funding provenance, funding time, cancellation timeInconsistent funding state
position PDA, maker PDA, collateral vault PDA, strike escrow PDA, policy or usage PDAAn address or bump is not canonical

Maker decoding errors: Invalid Maker account length, Invalid Maker discriminator, Invalid Maker fence magic.

ts
import { address, createSolanaRpc } from '@solana/kit';
import { decodePositionV3, derivePosition, PROGRAM_ID, type DecodedMarketV3 } from '@covrfun/maker-sdk';

declare const market: DecodedMarketV3;
declare const quoteKeyAddress: string;
declare const authority: string; // your Solana authority
const rpc = createSolanaRpc('https://<your rpc>');

const nonce = 1001n;
const { position, maker } = await derivePosition(quoteKeyAddress, nonce, market.collateral);
const { context, value } = await rpc
  .getMultipleAccounts([address(position), address(maker)], { commitment: 'finalized', encoding: 'base64' })
  .send();
const [p, m] = value;
if (!p || !m || p.owner !== PROGRAM_ID || m.owner !== PROGRAM_ID) throw new Error('no position');

const decoded = await decodePositionV3({
  position: { address: position, data: new Uint8Array(Buffer.from(p.data[0], 'base64')) },
  maker: { address: maker, data: new Uint8Array(Buffer.from(m.data[0], 'base64')) },
  slot: context.slot,
  makerEthAddress: quoteKeyAddress,
  makerAuthority: authority,
  nonce,
  collateral: market,
});
console.log(decoded.status, decoded.quantityAtoms, decoded.strikeUsdc, decoded.exerciseDeadline);

fillV3

Builds the fill instruction for a signed quote: fill_v3 for an ordinary market, fill_restricted_v3 for a restricted one. The writer (the customer) signs and submits fills; covr's gateway prepares them. Use this to simulate or audit the exact instruction your quote produces.

ts
export declare function fillV3(input: FillInput): Promise<{
    addresses: import("../settlement/ordinary-v3.js").OrdinaryV3Addresses;
    quantityE18: bigint;
    grossPremiumUsdc: bigint;
    strikeUsdc: bigint;
    premiumFeeUsdc: bigint;
    writerPremiumUsdc: bigint;
    recommendedComputeUnitLimit: 300000;
    instruction: import("../settlement/ordinary-v3.js").OrdinaryV3Instruction;
}>;
NameTypeDescription
inputFillInputDecoded market, writer and its token accounts, fee account, quantity in atoms, and the signed quote.

Returns:

FieldMeaning
addressesmaker, position, collateralVault, strikeEscrow, policy, usage, exposure, premiumBudget, paymentVault (your USDC vault), origin
quantityE18Wire quantity, as a bigint
grossPremiumUsdc, premiumFeeUsdc, writerPremiumUsdc, strikeUsdcUSDC atoms, as the program computes them
recommendedComputeUnitLimit300,000
instructionAccounts: writer (writable signer), market, maker, position (w), collateral vault (w), collateral mint, USDC mint, writer collateral (w), writer USDC (w), fee account (w), maker vault (w), collateral token program, Token program, System program, exposure (w), premium budget (w), mint policy, mint usage (w), origin; then the Jito stake pool (read-only) when the collateral is JitoSOL. Data: discriminator, keccak256(auctionId) (32), nonce (u64), quantity atoms (u64), price (u128), validUntil (i64), signature (65); restricted adds the timeout (u64).

For a restricted market the result also carries termsId and cancellationTimeoutSeconds at run time. The declared type does not list them.

The builder verifies the quote exactly as the program will: market identity and terms, the quote's instrument against the market, quantity equal to wireQuantity(quantityAtoms), the signature against the market domain, exact amounts, and no aliasing between transfer accounts. It does not check time, balances, caps or min_nonce: simulate for those.

Warning

JitoSOL fill cap. The program refuses a JitoSOL fill worth more than 50 SOL of stake-pool value: it requires quantityAtoms × totalLamports <= 50_000_000_000 × poolTokenSupply, read from the Jito stake pool account passed with the fill. A refused fill fails with JitoSolOrderLimit (code 6008). In JitoSOL, the cap is 50 divided by the pool rate (SOL per JitoSOL), so it shrinks as the rate rises. Read the pool and size from it. The cap was 2 SOL until the program upgrade of 4 November 2026. The pool account must also be current for the epoch, or the fill fails with InvalidJitoPool (6009). The SDK does not check either rule: simulate the fill.

Throws: OrdinaryV3: <reason> (restricted: RestrictedV3: <reason>), plus parsing errors from the quote:

ReasonCause
nonzero hash required, zero identity, unsupported token identity, invalid decimals, ordinary atomic market required (restricted: restricted market required), payment or genesis identity, ordinary terms identity (restricted: restricted terms identity), integer out of range, market terms, market PDAThe market object is not a valid decoded market
fill timeout differs from market termsRestricted only: timeout mismatch
QuoteV2 requiredThe quote lacks auctionId or writer
opening paused or quantity exceeds marketMarket paused, or quantityAtoms is 0 or above maxQuantityAtoms
nonce, price or e18 quantity mismatchNonce is 2^64 - 1, price is 0, or quote.quantity differs from the atoms
quote identity or side mismatchWriter, asset alias, USDC alias, chain id or side differs from the market
quote time or strike mismatchStrike or expiry differs from the market, or validUntil is not in (0, expiry]
zero auction, signature length, signature recovery byteMalformed auction id or signature
fractional USDC obligation, USDC obligation overflow or zeroPremium or strike not exact
quote signature signer mismatch (restricted: ... (restricted domain))The signature does not recover to quote.maker in this market's domain
transfer account alias (restricted: account alias)Two transfer accounts are the same key
wrong Jito pool, unexpected remaining accountjitoStakePool is not JITO_STAKE_POOL, or given for a non-JitoSOL market

Quote parsing errors: Unsupported quote schema, Invalid auction ID, canonical unsigned integer required, integer overflow, Amount precision loss. Setting the reserved fields makerProvenance or useMigrationHolds to an invalid value throws an AssertionError.

ts
import { fillV3, type DecodedMarketV3, type QuoteV2 } from '@covrfun/maker-sdk';

declare const market: DecodedMarketV3;
declare const quote: QuoteV2; // your signed quote
declare const writer: string, writerCollateral: string, writerPayment: string, feeTokens: string;

const fill = await fillV3({
  market,
  writer,
  writerCollateral,
  writerPayment,
  feeTokens,
  quantityAtoms: 500_000_000n,
  quote,
});
console.log(fill.addresses.position, fill.grossPremiumUsdc, fill.strikeUsdc);

exerciseV3

Builds exercise_v3 for an ordinary position: your vault pays the strike to the writer and the collateral moves to you, in one instruction.

Tip

Most desks should call exerciseV3Instructions instead. It builds the whole transaction: the compute-unit limit, fresh writer accounts and this instruction. Use exerciseV3 only to assemble your own transaction.

ts
export declare function exerciseV3(input: {
    market: DecodedMarketV3;
    position: Readonly<PositionV3>;
    authority: string;
    writerCollateral: string;
    writerPayment: string;
    makerCollateral: string;
}): Promise<{
    addresses: import("../settlement/ordinary-v3.js").OrdinaryV3Addresses;
    recommendedComputeUnitLimit: 400000;
    instruction: import("../settlement/ordinary-v3.js").OrdinaryV3Instruction;
}>;
NameTypeDescription
input.marketDecodedMarketV3The position's market. Must be ordinary (mode 0).
input.positionPositionV3From decodePositionV3, status open.
input.authoritystringThe signer: your Solana authority, or your operator if one is set.
input.writerCollateralstringCollateral token account owned by the writer.
input.writerPaymentstringUSDC token account owned by the writer. Receives the strike.
input.makerCollateralstringCollateral token account owned by your authority (even when the operator signs). Receives the collateral.

Returns: addresses, recommendedComputeUnitLimit (400,000) and the instruction. Accounts: authority (read-only signer), market, maker, position (w), collateral vault (w), writer, collateral mint, writer collateral (w), collateral token program, exposure (w), mint usage (w), USDC mint, maker vault (w), writer USDC (w), maker collateral (w), Token program.

The program accepts it only while expiry <= now < expiry + window. Destination token accounts must be initialized, not frozen, owned by the expected owner, with no delegate and no close authority other than the owner. For the writer's accounts, create fresh token accounts owned by the writer in the same transaction, so the writer cannot block your exercise: exerciseV3Instructions does exactly this. See Fills and exercise.

Throws:

ConditionMessage
The market is restrictedmaker-sdk: restricted markets exercise in two steps: fundRestrictedExerciseV3, then completePendingDeliveryV3
authority is neither the position's maker authority nor its operatorOrdinaryV3: authority differs from observed maker owner/operator
Position not open and ordinaryOrdinaryV3: ordinary open position required
Position obligations or terms differ from the marketOrdinaryV3: invalid claim obligations, OrdinaryV3: ordinary position cannot carry pending rights, OrdinaryV3: position market or deployment mismatch, OrdinaryV3: position token identity mismatch, OrdinaryV3: position immutable terms mismatch
Position object not from the decoderOrdinaryV3: decoded position observation required
Position addresses not canonicalOrdinaryV3: position canonical PDA mismatch
Two transfer accounts are the sameOrdinaryV3: transfer account alias
A key is the zero key, or the market object is invalidOrdinaryV3: zero identity and the market reasons of fillV3
ts
import { exerciseV3, type DecodedMarketV3, type PositionV3 } from '@covrfun/maker-sdk';

declare const market: DecodedMarketV3;
declare const position: Readonly<PositionV3>; // from decodePositionV3
declare const authority: string;
declare const writerCollateral: string, writerPayment: string, makerCollateral: string;

const { instruction, recommendedComputeUnitLimit } = await exerciseV3({
  market,
  position,
  authority,
  writerCollateral,
  writerPayment,
  makerCollateral,
});

releaseV3

Builds release_v3 (ordinary) or release_restricted_v3 (restricted): after the exercise window, anyone may return the collateral to the writer. This frees your exposure and mint usage.

Tip

releaseV3Instructions builds the whole release transaction, with a compute-unit limit of 400,000 and a fresh writer collateral account. Use releaseV3 only to assemble your own transaction.

ts
export declare function releaseV3(input: {
    market: DecodedMarketV3;
    position: Readonly<PositionV3>;
    writerCollateral: string;
}): Promise<{
    addresses: import("../settlement/ordinary-v3.js").OrdinaryV3Addresses;
    recommendedComputeUnitLimit: 400000;
    instruction: import("../settlement/ordinary-v3.js").OrdinaryV3Instruction;
} | {
    addresses: import("../settlement/restricted-v3.js").RestrictedV3Addresses;
    recommendedComputeUnitLimit: 200000;
    instruction: import("../settlement/restricted-v3.js").RestrictedV3Instruction;
}>;
NameTypeDescription
input.marketDecodedMarketV3The position's market.
input.positionPositionV3From decodePositionV3, status open.
input.writerCollateralstringCollateral token account owned by the writer.

Returns: addresses, recommendedComputeUnitLimit (400,000 ordinary, 200,000 restricted) and the instruction. Accounts: market, maker, position (w), collateral vault (w), writer, collateral mint, writer collateral (w), collateral token program, exposure (w), mint usage (w). The instruction has no signer account: whoever pays the transaction fee may send it.

The program accepts it only when now >= expiry + window.

Throws: the position and market reasons of exerciseV3 (OrdinaryV3: prefix), or for restricted markets RestrictedV3: restricted position required, RestrictedV3: position state does not permit this action and the same family under RestrictedV3:.

ts
import { releaseV3, type DecodedMarketV3, type PositionV3 } from '@covrfun/maker-sdk';

declare const market: DecodedMarketV3;
declare const position: Readonly<PositionV3>;
declare const writerCollateral: string;
const { instruction } = await releaseV3({ market, position, writerCollateral });

exerciseV3Instructions

Builds every instruction of one exercise transaction for an ordinary position, in order. This is the recommended way to exercise.

ts
export declare function exerciseV3Instructions(input: {
    market: DecodedMarketV3;
    position: Readonly<PositionV3>;
    authority: string;
    makerCollateral?: string;
    rentLamports: bigint;
    seeds?: {
        writerPayment?: string;
        writerCollateral?: string;
    };
}): Promise<{
    instructions: import("../settlement/ordinary-v3.js").OrdinaryV3Instruction[];
    computeUnitLimit: 400000;
    rentLamports: bigint;
    writerPayment: FreshWriterAccount;
    writerCollateral: FreshWriterAccount;
    makerCollateral: string;
    addresses: import("../settlement/ordinary-v3.js").OrdinaryV3Addresses;
}>;
NameTypeDescription
input.marketDecodedMarketV3The position's market. Must be ordinary (mode 0).
input.positionPositionV3From decodePositionV3, status open. Read once, before any await.
input.authoritystringThe signer and fee payer: your maker authority, or your operator. It also pays the rent of both new accounts.
input.makerCollateralstringOptional. The token account that receives the collateral. Default: your maker authority's associated token account for the collateral mint, under the market's collateral token program.
input.rentLamportsbigintRent for one 165-byte token account, in lamports. Any positive u64.
input.seeds{ writerPayment?, writerCollateral? }Optional. 32 lowercase hex characters each. Default: 16 random bytes as hex, new on every call.

Returns:

FieldMeaning
instructionsThe 8 instructions below, in order.
computeUnitLimit400000.
rentLamports2 × input.rentLamports: what authority pays for the two accounts.
writerPayment, writerCollateralThe two new accounts (FreshWriterAccount): address, base, seed, mint, token program.
makerCollateralThe collateral destination used.
addressesAs exerciseV3 returns.
#InstructionWhat it does
0Compute Budget SetComputeUnitLimit(400000)The default 200,000 is too low: exercise_v3 measured up to 277,316 CU.
1System Transferauthority sends rentLamports to the new writer USDC account address.
2System AllocateWithSeedAllocates 165 bytes at that address (base authority, the seed), owned by the USDC token program.
3Token InitializeAccount3Makes it a USDC token account owned by the writer.
4 to 6the same threeA new writer collateral account: 165 bytes, collateral mint, collateral token program, owned by the writer.
7exercise_v3Pays the strike into account 1 to 3 and the collateral into makerCollateral, and returns any surplus collateral to account 4 to 6.

Why fresh accounts: the program pays the writer only into clean token accounts (no delegate, not frozen, no foreign close authority). An existing writer account could be broken by the writer at any time. These addresses come from createWithSeed(authority, seed, tokenProgram), so only your signer can allocate them. Transfer plus AllocateWithSeed, unlike CreateAccountWithSeed, still work if someone sent lamports to the address first. The writer owns both accounts and keeps their rent. Ordinary markets take only collateral mints without extensions, so both accounts are WRITER_ACCOUNT_SPACE (165) bytes, Token-2022 or not.

Signing and size. Sign with authority as fee payer: one signature. You may add one SetComputeUnitPrice instruction; never a second SetComputeUnitLimit, which the runtime refuses. With a priority fee the transaction is 1,111 of the 1,232 bytes a packet allows, in the worst case (Token-2022 collateral). A separate fee payer adds a signature: 1,207 bytes, which leaves no room for a Jito tip.

Warning

makerCollateral must be your authority's account. The program pays the collateral only into a token account for the collateral mint owned by your maker authority, even when the operator signs. It must not be frozen, have a delegate, or have a close authority other than its owner. Any other account fails every attempt. The default (the authority's associated token account) must already exist: create it before the exercise window opens. The helper cannot see the chain, so it does not check that.

Note

Rent. Read getMinimumBalanceForRentExemption(165) from your RPC at finalized commitment before each exercise, and pass that value. The SDK hard-codes no rate and checks only that rent is positive, because mainnet rent has changed before. Too little rent fails the whole transaction, which simulation shows. Accounts created on mainnet in October 2026 held (128 + size) × 5,080 lamports (1,488,440 for 165 bytes), but read the value; do not compute it.

Throws:

ConditionMessage
The market is restricted (checked first)maker-sdk: restricted markets exercise in two steps: fundRestrictedExerciseV3, then completePendingDeliveryV3
rentLamports is not a bigint in [0, 2^64 - 1]maker-sdk: rentLamports must be a bigint in [0, u64] range
rentLamports is 0nmaker-sdk: rentLamports must be positive
A seed is not 32 lowercase hex charactersmaker-sdk: seed must be 32 lowercase hex characters
The market's token program is neither token programmaker-sdk: token program must be SPL Token or Token-2022
Anything exerciseV3 refusesits OrdinaryV3: ... message, for example OrdinaryV3: authority differs from observed maker owner/operator
A new account equals another account of the transaction (or both seeds give one address)maker-sdk: fresh writer account collides with another account of the exit: use other seeds
makerCollateral is the authority or operator wallet, or another account of the exercisemaker-sdk: makerCollateral must be the maker authority's own token account for the collateral mint, not a wallet or another account of the exercise
makerCollateral is the operator's associated token account (and the operator is not the authority)maker-sdk: makerCollateral is the operator's associated token account: the program pays only the maker authority's
An address is not valid base58SolanaError from @solana/kit
ts
import {
  address,
  appendTransactionMessageInstructions,
  createSolanaRpc,
  createTransactionMessage,
  pipe,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransactionMessageWithSigners,
  type Instruction,
  type TransactionSigner,
} from '@solana/kit';
import { exerciseV3Instructions, WRITER_ACCOUNT_SPACE, type DecodedMarketV3, type PositionV3 } from '@covrfun/maker-sdk';

declare const signer: TransactionSigner; // your maker authority or operator
declare const market: DecodedMarketV3;
declare const position: Readonly<PositionV3>; // from decodePositionV3, status 'open'
const rpc = createSolanaRpc('https://<your rpc>');

// Read rent for the account size every time; never hard-code it.
const rentLamports = await rpc
  .getMinimumBalanceForRentExemption(BigInt(WRITER_ACCOUNT_SPACE), { commitment: 'finalized' })
  .send();
const exit = await exerciseV3Instructions({ market, position, authority: signer.address, rentLamports });

// Optional priority fee: SetComputeUnitPrice (1,000 micro-lamports per CU) right after the limit.
const priceData = new Uint8Array(9);
priceData[0] = 3;
new DataView(priceData.buffer).setBigUint64(1, 1_000n, true);
const computeUnitPrice: Instruction = {
  programAddress: address('ComputeBudget111111111111111111111111111111'),
  data: priceData,
};

const { value: blockhash } = await rpc.getLatestBlockhash({ commitment: 'finalized' }).send();
const message = pipe(
  createTransactionMessage({ version: 0 }),
  m => setTransactionMessageFeePayerSigner(signer, m),
  m => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  m => appendTransactionMessageInstructions([exit.instructions[0], computeUnitPrice, ...exit.instructions.slice(1)], m),
);
const signed = await signTransactionMessageWithSigners(message);
// Simulate, then send `signed` inside the exercise window.

releaseV3Instructions

Builds every instruction of one release transaction, ordinary or restricted, in order: after the exercise window, return the collateral to the writer through a fresh account. This is the recommended way to release.

ts
export declare function releaseV3Instructions(input: {
    market: DecodedMarketV3;
    position: Readonly<PositionV3>;
    payer: string;
    rentLamports: bigint;
    collateralAccountSpace?: number;
    seed?: string;
}): Promise<{
    instructions: import("../settlement/ordinary-v3.js").OrdinaryV3Instruction[];
    computeUnitLimit: 400000;
    rentLamports: bigint;
    writerCollateral: FreshWriterAccount;
    addresses: import("../settlement/ordinary-v3.js").OrdinaryV3Addresses | import("../settlement/restricted-v3.js").RestrictedV3Addresses;
}>;
NameTypeDescription
input.marketDecodedMarketV3The position's market, either mode.
input.positionPositionV3From decodePositionV3, status open. Read once, before any await.
input.payerstringAny wallet. Signs alone, pays the fee and the rent.
input.rentLamportsbigintRent for the new account at its size, in lamports. Any positive u64.
input.collateralAccountSpacenumberSize of the new collateral account in bytes. Required for Token-2022 collateral: the token account size with every account extension the mint requires (175 for covr's tokenized-stock mints, which need TransferHook and Pausable; 165 for a Token-2022 mint without such extensions). For SPL Token collateral omit it, or pass exactly 165.
input.seedstringOptional. 32 lowercase hex characters. Default: random.

Returns: instructions (5, below), computeUnitLimit (400000), rentLamports (the input), writerCollateral (FreshWriterAccount) and addresses (as releaseV3 returns).

#InstructionWhat it does
0Compute Budget SetComputeUnitLimit(400000)400,000 in both modes: both release instructions take the same accounts, measured up to 233,135 CU.
1 to 3System Transfer, System AllocateWithSeed, Token InitializeAccount3A new collateral token account at createWithSeed(payer, seed, collateral token program), of collateralAccountSpace (or 165) bytes, owned by the writer.
4release_v3 or release_restricted_v3Returns the collateral into it.

With a priority fee the transaction is 769 of 1,232 bytes, in both modes. The program accepts the release only when now >= expiry + window. Read getMinimumBalanceForRentExemption(size) at finalized commitment for the exact size you pass, as for exerciseV3Instructions. At the October 2026 mainnet rate a 175-byte account needed (128 + 175) × 5,080 = 1,539,240 lamports; read it, do not compute it.

Throws:

ConditionMessage
SPL Token collateral with collateralAccountSpace other than 165maker-sdk: an SPL Token account is exactly 165 bytes
Token-2022 collateral without collateralAccountSpacemaker-sdk: Token-2022 collateral needs collateralAccountSpace: the token account size with every account extension its mint requires (175 for TransferHook + Pausable)
collateralAccountSpace not an integer from 165 to 65,536maker-sdk: collateralAccountSpace must be an integer from 165 to 65536
Bad rentLamportsmaker-sdk: rentLamports must be a bigint in [0, u64] range / maker-sdk: rentLamports must be positive
Bad seedmaker-sdk: seed must be 32 lowercase hex characters
Anything releaseV3 refusesits OrdinaryV3: or RestrictedV3: message
The new account equals another account of the releasemaker-sdk: fresh writer account collides with another account of the exit: use other seeds
ts
import { createSolanaRpc } from '@solana/kit';
import { releaseV3Instructions, WRITER_ACCOUNT_SPACE, type DecodedMarketV3, type PositionV3 } from '@covrfun/maker-sdk';

declare const payerAddress: string; // any wallet; it signs alone
declare const market: DecodedMarketV3;
declare const position: Readonly<PositionV3>;
// Token-2022 collateral only: the mint's token account size (for example getTokenSize from
// @solana-program/token-2022). Leave undefined for SPL Token collateral such as JitoSOL.
declare const collateralAccountSpace: number | undefined;
const rpc = createSolanaRpc('https://<your rpc>');

const size = collateralAccountSpace ?? WRITER_ACCOUNT_SPACE;
const rentLamports = await rpc
  .getMinimumBalanceForRentExemption(BigInt(size), { commitment: 'finalized' })
  .send();
const exit = await releaseV3Instructions({ market, position, payer: payerAddress, rentLamports, collateralAccountSpace });
// Put exit.instructions in a transaction with `payerAddress` as fee payer, simulate, send.

WRITER_ACCOUNT_SPACE

The size in bytes of a token account with no extensions. Every SPL Token account, every writer USDC account and every exercise collateral account the helpers create has this size.

ts
export declare const WRITER_ACCOUNT_SPACE = 165;
  • Value: 165
  • Where it matters: the size to price rent for with getMinimumBalanceForRentExemption before exerciseV3Instructions, and before releaseV3Instructions on SPL Token collateral. A Token-2022 collateral account on release is larger when its mint requires account extensions: pass collateralAccountSpace.

fundRestrictedExerciseV3

Builds fund_restricted_exercise_v3, step 1 of a restricted exercise: your vault moves the exact strike into the position's strike escrow.

Note

Restricted markets are covr-only today.

ts
export declare function fundRestrictedExerciseV3(input: {
    market: RestrictedMarketV3;
    position: Readonly<PositionV3>;
    authority: string;
}): Promise<{
    addresses: import("../settlement/restricted-v3.js").RestrictedV3Addresses;
    strikeUsdc: bigint;
    recommendedComputeUnitLimit: 200000;
    instruction: import("../settlement/restricted-v3.js").RestrictedV3Instruction;
}>;
NameTypeDescription
input.marketRestrictedMarketV3The position's restricted market.
input.positionPositionV3Status open.
input.authoritystringYour Solana authority or operator.

Returns: addresses, strikeUsdc (USDC atoms moved into escrow), recommendedComputeUnitLimit (200,000) and the instruction. Accounts: authority (writable signer), market, maker, position (w), collateral vault, collateral mint, collateral token program, USDC mint, maker vault (w), strike escrow (w), mint usage (w), Token program, System program.

Throws: RestrictedV3: authority differs from observed maker owner/operator, RestrictedV3: restricted position required, RestrictedV3: position state does not permit this action, RestrictedV3: account alias, and the restricted market and position reasons (RestrictedV3: prefix).

ts
import { fundRestrictedExerciseV3, type PositionV3, type RestrictedMarketV3 } from '@covrfun/maker-sdk';

declare const market: RestrictedMarketV3;
declare const position: Readonly<PositionV3>;
declare const authority: string;
const { strikeUsdc, instruction } = await fundRestrictedExerciseV3({ market, position, authority });

completePendingDeliveryV3

Builds complete_pending_delivery_v3, step 2 of a restricted exercise: any signer delivers the escrowed strike to the writer and the collateral to the maker.

Note

Restricted markets are covr-only today.

ts
export declare function completePendingDeliveryV3(input: {
    market: RestrictedMarketV3;
    position: Readonly<PositionV3>;
    caller: string;
    writerCollateral: string;
    writerPayment: string;
    makerCollateral: string;
}): Promise<{
    addresses: import("../settlement/restricted-v3.js").RestrictedV3Addresses;
    recommendedComputeUnitLimit: 300000;
    instruction: import("../settlement/restricted-v3.js").RestrictedV3Instruction;
}>;
NameTypeDescription
input.marketRestrictedMarketV3The position's restricted market.
input.positionPositionV3Status pending_delivery.
input.callerstringAny signer.
input.writerCollateralstringCollateral token account owned by the writer.
input.writerPaymentstringUSDC token account owned by the writer.
input.makerCollateralstringCollateral token account owned by the maker authority. Must differ from writerCollateral.

Returns: addresses, recommendedComputeUnitLimit (300,000) and the instruction. Accounts: caller (read-only signer), market, maker, position (w), collateral vault (w), writer, collateral mint, writer collateral (w), collateral token program, exposure (w), mint usage (w), USDC mint, strike escrow (w), writer USDC (w), maker collateral (w), maker authority (w, receives the escrow rent), Token program.

Throws: RestrictedV3: recipient alias, RestrictedV3: account alias, RestrictedV3: position state does not permit this action, and the restricted market and position reasons.

ts
import { completePendingDeliveryV3, type PositionV3, type RestrictedMarketV3 } from '@covrfun/maker-sdk';

declare const market: RestrictedMarketV3;
declare const position: Readonly<PositionV3>;
declare const caller: string, writerCollateral: string, writerPayment: string, makerCollateral: string;
const { instruction } = await completePendingDeliveryV3({
  market,
  position,
  caller,
  writerCollateral,
  writerPayment,
  makerCollateral,
});

encodeCancellationRequestV1

Encodes a restricted cancellation request to its 288-byte Borsh form, the argument of cancel_pending_delivery_v3. Both parties (the maker authority and the writer) sign that transaction. This SDK has no builder for the instruction itself.

Note

Restricted markets are covr-only today.

ts
export declare function encodeCancellationRequestV1(r: CancellationRequestV1): Uint8Array;
NameTypeDescription
rCancellationRequestV1The request fields.

Returns: Uint8Array, 288 bytes: genesis hash, program, terms id, position, maker, writer (32 bytes each), intentGeneration, refundStrikeUsdc, returnCollateralAtoms (u64 LE each), payment destination, collateral destination (32 bytes each), validUntil (i64 LE).

Throws:

ConditionMessage
termsId is not 0x + 64 hexRestrictedV3: 32-byte hex required
An integer is out of rangeRestrictedV3: integer out of range
A key is not valid base58SolanaError from @solana/kit
ts
import { encodeCancellationRequestV1, type CancellationRequestV1 } from '@covrfun/maker-sdk';

declare const request: CancellationRequestV1;
const bytes = encodeCancellationRequestV1(request); // 288 bytes

decodeCancellationRequestV1

Decodes 288 bytes back into a CancellationRequestV1.

ts
export declare function decodeCancellationRequestV1(b: Uint8Array): CancellationRequestV1;
NameTypeDescription
bUint8ArrayExactly 288 bytes.

Returns: CancellationRequestV1. Keys are base58; termsId is 0x + 64 hex.

Throws: RestrictedV3: request must be exactly 288 bytes.

ts
import { decodeCancellationRequestV1 } from '@covrfun/maker-sdk';

declare const bytes: Uint8Array;
const request = decodeCancellationRequestV1(bytes);

ORDINARY_V3_COMPUTE_UNIT_LIMITS

Compute-unit limits for ordinary instructions. Builders return the matching value as recommendedComputeUnitLimit. The object is frozen.

ts
export declare const ORDINARY_V3_COMPUTE_UNIT_LIMITS: Readonly<{
    initializeExposure: 200000;
    fill: 300000;
    exercise: 400000;
    release: 400000;
}>;
  • Value: { initializeExposure: 200000, fill: 300000, exercise: 400000, release: 400000 }
  • Meaning: tested envelopes, not worst-case guarantees or fee estimates. Prepend your own compute-unit-limit instruction with this value and simulate the full transaction. The chain allows at most 1,400,000 per transaction.

RESTRICTED_V3_COMPUTE_UNIT_LIMITS

Compute-unit limits for restricted instructions. The object is frozen.

ts
export declare const RESTRICTED_V3_COMPUTE_UNIT_LIMITS: Readonly<{
    create: 200000;
    pause: 200000;
    fill: 300000;
    fund: 200000;
    complete: 300000;
    cancel: 300000;
    release: 200000;
    close: 200000;
    bundle: 450000;
}>;
  • Value: { create: 200000, pause: 200000, fill: 300000, fund: 200000, complete: 300000, cancel: 300000, release: 200000, close: 200000, bundle: 450000 }
  • Meaning: provisional envelopes, not measured worst cases. Simulate first. pause (the restricted market pause), cancel, close and bundle have no builder in this SDK. releaseV3Instructions sets 400,000 for a restricted release, not this table's 200,000: both release instructions take the same accounts, measured up to 233,135 CU.