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
| Quantity | Unit | Formula |
|---|---|---|
atoms | collateral base units (JitoSOL: 10^-9) | |
priceE18 | USDC × 10^18 per one whole collateral token | |
strikeE8 | USD × 10^8 per whole collateral token | |
| gross premium | USDC atoms (10^-6 USDC) | atoms × priceE18 / 10^(decimals + 12), must divide exactly, must be > 0 and ≤ 2^64 - 1 |
| strike payment | USDC atoms | atoms × strikeE8 / 10^(decimals + 2), must divide exactly, must be > 0 and ≤ 2^64 - 1 |
| fee | USDC atoms | floor(gross × feeBps / 10000), feeBps 0 to 1,000 |
| writer premium | USDC atoms | gross - fee |
| wire quantity | collateral 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:
| Amount | Value |
|---|---|
| gross premium | 500_000_000 × 2.4e18 / 10^21 = 1_200_000 (1.20 USDC) |
| fee | floor(1_200_000 × 1000 / 10000) = 120_000 (0.12 USDC) |
| writer premium | 1_080_000 (1.08 USDC) |
| strike payment | 500_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.
export declare function strikePayment(atoms: bigint, strikeE8: bigint, collateralDecimals: number): bigint;| Name | Type | Description |
|---|---|---|
atoms | bigint | Position size in collateral atoms. u64. |
strikeE8 | bigint | Strike, USD × 10^8. u64. |
collateralDecimals | number | Collateral mint decimals, 0 to 255. |
Returns: bigint, USDC atoms: atoms × strikeE8 / 10^(collateralDecimals + 2), exact, positive.
Throws:
| Condition | Message |
|---|---|
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 255 | maker-sdk: decimals must be a u8 |
atoms or strikeE8 is zero | maker-sdk: strike payment: atoms and price must be positive (zero is refused) |
| The product does not divide exactly | maker-sdk: strike payment is not exact: atoms x price is not divisible by 10^(decimals+2) |
| The result exceeds 2^64 - 1 | maker-sdk: strike payment overflows u64 |
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 USDCgrossPremium
Returns the gross premium in USDC atoms that your vault pays at fill. The protocol fee is carved out of it.
export declare function grossPremium(atoms: bigint, priceE18: bigint, collateralDecimals: number): bigint;| Name | Type | Description |
|---|---|---|
atoms | bigint | Fill size in collateral atoms. u64. |
priceE18 | bigint | Price per whole token, USDC × 10^18. u128. |
collateralDecimals | number | Collateral 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):
| Condition | Message |
|---|---|
priceE18 is not a bigint in [0, 2^128 - 1] | maker-sdk: priceE18 must be a bigint in [0, u128] range |
| Zero input | maker-sdk: gross premium: atoms and price must be positive (zero is refused) |
| Not exact | maker-sdk: gross premium is not exact: atoms x price is not divisible by 10^(decimals+12) |
| Too large | maker-sdk: gross premium overflows u64 |
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.
export declare function fee(gross: bigint, feeBps: number): bigint;| Name | Type | Description |
|---|---|---|
gross | bigint | Gross premium, USDC atoms. u64. |
feeBps | number | Market fee in basis points, integer 0 to 1,000. |
Returns: bigint, USDC atoms, rounded down.
Throws:
| Condition | Message |
|---|---|
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,000 | maker-sdk: feeBps must be an integer 0..1000 |
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).
export declare function writerPremium(gross: bigint, feeBps: number): bigint;| Name | Type | Description |
|---|---|---|
gross | bigint | Gross premium, USDC atoms. u64. |
feeBps | number | Market fee in basis points, 0 to 1,000. |
Returns: bigint, USDC atoms.
Throws: as fee.
import { writerPremium } from '@covrfun/maker-sdk';
writerPremium(1_200_000n, 1000); // 1_080_000npriceForGross
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.
export declare function priceForGross(gross: bigint, atoms: bigint, collateralDecimals: number): bigint;| Name | Type | Description |
|---|---|---|
gross | bigint | Target gross premium, USDC atoms. Positive u64. |
atoms | bigint | Fill size, collateral atoms. Positive u64. |
collateralDecimals | number | Collateral mint decimals, 0 to 255. |
Returns: bigint: gross × 10^(collateralDecimals + 12) / atoms, exact.
Throws:
| Condition | Message |
|---|---|
gross or atoms out of u64 range | maker-sdk: gross must be a bigint in [0, u64] range (or atoms ...) |
| Bad decimals | maker-sdk: decimals must be a u8 |
gross or atoms is zero | maker-sdk: gross and atoms must be positive |
| No exact price exists | maker-sdk: no exact priceE18 pays that gross for these atoms (not divisible) |
| The price exceeds 2^128 - 1 | maker-sdk: priceE18 exceeds u128 |
import { priceForGross } from '@covrfun/maker-sdk';
priceForGross(1_200_000n, 500_000_000n, 9); // 2_400_000_000_000_000_000nexactPriceAtOrBelow
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.
export declare function exactPriceAtOrBelow(priceE18: bigint, atoms: bigint, collateralDecimals: number): bigint;| Name | Type | Description |
|---|---|---|
priceE18 | bigint | Your model price, USDC × 10^18 per whole token. u128. |
atoms | bigint | The RFQ size in collateral atoms. Positive u64. |
collateralDecimals | number | Collateral 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:
| Condition | Message |
|---|---|
priceE18 out of u128 range | maker-sdk: priceE18 must be a bigint in [0, u128] range |
atoms out of u64 range | maker-sdk: atoms must be a bigint in [0, u64] range |
| Bad decimals | maker-sdk: decimals must be a u8 |
atoms is zero | maker-sdk: atoms must be positive |
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.
export declare function wireQuantity(atoms: bigint, collateralDecimals: number): string;| Name | Type | Description |
|---|---|---|
atoms | bigint | Collateral atoms. u64. |
collateralDecimals | number | Collateral mint decimals, 0 to 255. |
Returns: string, a decimal integer: atoms × 10^(18 - decimals) (for decimals above 18, atoms / 10^(decimals - 18), exact).
Throws:
| Condition | Message |
|---|---|
atoms out of u64 range | maker-sdk: atoms must be a bigint in [0, u64] range |
| Bad decimals | maker-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 |
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.
export declare function atomsFromWire(quantityE18: string | bigint, collateralDecimals: number): bigint;| Name | Type | Description |
|---|---|---|
quantityE18 | string | bigint | Wire quantity. A string must be a canonical decimal integer (no sign, no leading zeros, no 0x). |
collateralDecimals | number | Collateral mint decimals, 0 to 255. |
Returns: bigint, collateral atoms.
Throws:
| Condition | Message |
|---|---|
| Bad decimals | maker-sdk: decimals must be a u8 |
| String is not a canonical decimal integer | canonical unsigned integer required |
| String is 2^256 or more | integer overflow |
| Not whole atoms | maker-sdk: wire quantity is not exact whole atoms (precision): Amount precision loss |
| More than 2^64 - 1 atoms | maker-sdk: wire quantity is not exact whole atoms (precision): Amount overflow |
import { atomsFromWire } from '@covrfun/maker-sdk';
atomsFromWire('500000000000000000', 9); // 500_000_000nminimumExactLot
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.
export declare function minimumExactLot(strikeE8: bigint, collateralDecimals: number): bigint;| Name | Type | Description |
|---|---|---|
strikeE8 | bigint | Strike, USD × 10^8. Positive u64. |
collateralDecimals | number | Collateral 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:
| Condition | Message |
|---|---|
strikeE8 out of u64 range | maker-sdk: strikeE8 must be a bigint in [0, u64] range |
| Bad decimals | maker-sdk: decimals must be a u8 |
strikeE8 is zero | maker-sdk: strikeE8 must be positive |
import { minimumExactLot } from '@covrfun/maker-sdk';
minimumExactLot(17_000_000_000n, 9); // 100n: $170 JitoSOL quantities move in 100-atom stepssettlementAmounts
Computes every amount of one fill at once, as the program does.
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;
};| Name | Type | Description |
|---|---|---|
input.atoms | bigint | Fill size, collateral atoms. |
input.priceE18 | bigint | Price per whole token, USDC × 10^18. |
input.strikeE8 | bigint | Strike, USD × 10^8. |
input.decimals | number | Collateral mint decimals. |
input.feeBps | number | Market 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.
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.
export declare function decodePositionV3(input: PositionReadInput, d?: Deployment): Promise<Readonly<PositionV3>>;| Name | Type | Description |
|---|---|---|
input | PositionReadInput | The position and Maker bytes from one finalized getMultipleAccounts read, its slot, your quote key, your authority, the nonce and the market. |
d | Deployment | Optional. 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:
| Reason | Cause |
|---|---|
zero identity, invalid hex identity, zero hex identity | A bad key, quote key or d.deploymentId |
invalid nonce, reserved nonce | nonce not a u64, or 2^64 - 1 |
unsupported collateral program, invalid collateral decimals | Bad collateral identity |
invalid observation slot, invalid minimum slot, stale observation | slot not a u64, or below minContextSlot |
invalid account length, account length or discriminator | Position is not 652 bytes of PositionV3, or Maker has the wrong length |
snapshot address mismatch | An address differs from the expected one |
timeout anchor | The 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 observation | Maker's registration slot is after slot |
maker Ethereum identity, maker identity | Stored quote key, authority or maker differs |
deployment identity, collateral identity, payment identity | Stored genesis, deployment, collateral or USDC differs |
writer drift | input.writer given and the stored writer differs |
nonce, admission generation, zero obligation, clock terms | Stored obligations are invalid or the nonce differs |
duration outside i64, time overflow, timeout duration outside i64 | Time 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 time | Inconsistent funding state |
position PDA, maker PDA, collateral vault PDA, strike escrow PDA, policy or usage PDA | An address or bump is not canonical |
Maker decoding errors: Invalid Maker account length, Invalid Maker discriminator, Invalid Maker fence magic.
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.
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;
}>;| Name | Type | Description |
|---|---|---|
input | FillInput | Decoded market, writer and its token accounts, fee account, quantity in atoms, and the signed quote. |
Returns:
| Field | Meaning |
|---|---|
addresses | maker, position, collateralVault, strikeEscrow, policy, usage, exposure, premiumBudget, paymentVault (your USDC vault), origin |
quantityE18 | Wire quantity, as a bigint |
grossPremiumUsdc, premiumFeeUsdc, writerPremiumUsdc, strikeUsdc | USDC atoms, as the program computes them |
recommendedComputeUnitLimit | 300,000 |
instruction | Accounts: 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.
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:
| Reason | Cause |
|---|---|
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 PDA | The market object is not a valid decoded market |
fill timeout differs from market terms | Restricted only: timeout mismatch |
QuoteV2 required | The quote lacks auctionId or writer |
opening paused or quantity exceeds market | Market paused, or quantityAtoms is 0 or above maxQuantityAtoms |
nonce, price or e18 quantity mismatch | Nonce is 2^64 - 1, price is 0, or quote.quantity differs from the atoms |
quote identity or side mismatch | Writer, asset alias, USDC alias, chain id or side differs from the market |
quote time or strike mismatch | Strike or expiry differs from the market, or validUntil is not in (0, expiry] |
zero auction, signature length, signature recovery byte | Malformed auction id or signature |
fractional USDC obligation, USDC obligation overflow or zero | Premium 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 account | jitoStakePool 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.
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.
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.
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;
}>;| Name | Type | Description |
|---|---|---|
input.market | DecodedMarketV3 | The position's market. Must be ordinary (mode 0). |
input.position | PositionV3 | From decodePositionV3, status open. |
input.authority | string | The signer: your Solana authority, or your operator if one is set. |
input.writerCollateral | string | Collateral token account owned by the writer. |
input.writerPayment | string | USDC token account owned by the writer. Receives the strike. |
input.makerCollateral | string | Collateral 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:
| Condition | Message |
|---|---|
| The market is restricted | maker-sdk: restricted markets exercise in two steps: fundRestrictedExerciseV3, then completePendingDeliveryV3 |
authority is neither the position's maker authority nor its operator | OrdinaryV3: authority differs from observed maker owner/operator |
Position not open and ordinary | OrdinaryV3: ordinary open position required |
| Position obligations or terms differ from the market | OrdinaryV3: 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 decoder | OrdinaryV3: decoded position observation required |
| Position addresses not canonical | OrdinaryV3: position canonical PDA mismatch |
| Two transfer accounts are the same | OrdinaryV3: transfer account alias |
| A key is the zero key, or the market object is invalid | OrdinaryV3: zero identity and the market reasons of fillV3 |
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.
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.
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;
}>;| Name | Type | Description |
|---|---|---|
input.market | DecodedMarketV3 | The position's market. |
input.position | PositionV3 | From decodePositionV3, status open. |
input.writerCollateral | string | Collateral 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:.
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.
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;
}>;| Name | Type | Description |
|---|---|---|
input.market | DecodedMarketV3 | The position's market. Must be ordinary (mode 0). |
input.position | PositionV3 | From decodePositionV3, status open. Read once, before any await. |
input.authority | string | The signer and fee payer: your maker authority, or your operator. It also pays the rent of both new accounts. |
input.makerCollateral | string | Optional. 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.rentLamports | bigint | Rent 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:
| Field | Meaning |
|---|---|
instructions | The 8 instructions below, in order. |
computeUnitLimit | 400000. |
rentLamports | 2 × input.rentLamports: what authority pays for the two accounts. |
writerPayment, writerCollateral | The two new accounts (FreshWriterAccount): address, base, seed, mint, token program. |
makerCollateral | The collateral destination used. |
addresses | As exerciseV3 returns. |
| # | Instruction | What it does |
|---|---|---|
| 0 | Compute Budget SetComputeUnitLimit(400000) | The default 200,000 is too low: exercise_v3 measured up to 277,316 CU. |
| 1 | System Transfer | authority sends rentLamports to the new writer USDC account address. |
| 2 | System AllocateWithSeed | Allocates 165 bytes at that address (base authority, the seed), owned by the USDC token program. |
| 3 | Token InitializeAccount3 | Makes it a USDC token account owned by the writer. |
| 4 to 6 | the same three | A new writer collateral account: 165 bytes, collateral mint, collateral token program, owned by the writer. |
| 7 | exercise_v3 | Pays 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.
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.
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:
| Condition | Message |
|---|---|
| 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 0n | maker-sdk: rentLamports must be positive |
| A seed is not 32 lowercase hex characters | maker-sdk: seed must be 32 lowercase hex characters |
| The market's token program is neither token program | maker-sdk: token program must be SPL Token or Token-2022 |
Anything exerciseV3 refuses | its 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 exercise | maker-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 base58 | SolanaError from @solana/kit |
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.
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;
}>;| Name | Type | Description |
|---|---|---|
input.market | DecodedMarketV3 | The position's market, either mode. |
input.position | PositionV3 | From decodePositionV3, status open. Read once, before any await. |
input.payer | string | Any wallet. Signs alone, pays the fee and the rent. |
input.rentLamports | bigint | Rent for the new account at its size, in lamports. Any positive u64. |
input.collateralAccountSpace | number | Size 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.seed | string | Optional. 32 lowercase hex characters. Default: random. |
Returns: instructions (5, below), computeUnitLimit (400000), rentLamports (the input), writerCollateral (FreshWriterAccount) and addresses (as releaseV3 returns).
| # | Instruction | What it does |
|---|---|---|
| 0 | Compute Budget SetComputeUnitLimit(400000) | 400,000 in both modes: both release instructions take the same accounts, measured up to 233,135 CU. |
| 1 to 3 | System Transfer, System AllocateWithSeed, Token InitializeAccount3 | A new collateral token account at createWithSeed(payer, seed, collateral token program), of collateralAccountSpace (or 165) bytes, owned by the writer. |
| 4 | release_v3 or release_restricted_v3 | Returns 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:
| Condition | Message |
|---|---|
SPL Token collateral with collateralAccountSpace other than 165 | maker-sdk: an SPL Token account is exactly 165 bytes |
Token-2022 collateral without collateralAccountSpace | maker-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,536 | maker-sdk: collateralAccountSpace must be an integer from 165 to 65536 |
Bad rentLamports | maker-sdk: rentLamports must be a bigint in [0, u64] range / maker-sdk: rentLamports must be positive |
Bad seed | maker-sdk: seed must be 32 lowercase hex characters |
Anything releaseV3 refuses | its OrdinaryV3: or RestrictedV3: message |
| The new account equals another account of the release | maker-sdk: fresh writer account collides with another account of the exit: use other seeds |
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.
export declare const WRITER_ACCOUNT_SPACE = 165;- Value:
165 - Where it matters: the size to price rent for with
getMinimumBalanceForRentExemptionbeforeexerciseV3Instructions, and beforereleaseV3Instructionson SPL Token collateral. A Token-2022 collateral account on release is larger when its mint requires account extensions: passcollateralAccountSpace.
fundRestrictedExerciseV3
Builds fund_restricted_exercise_v3, step 1 of a restricted exercise: your vault moves the exact strike into the position's strike escrow.
Restricted markets are covr-only today.
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;
}>;| Name | Type | Description |
|---|---|---|
input.market | RestrictedMarketV3 | The position's restricted market. |
input.position | PositionV3 | Status open. |
input.authority | string | Your 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).
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.
Restricted markets are covr-only today.
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;
}>;| Name | Type | Description |
|---|---|---|
input.market | RestrictedMarketV3 | The position's restricted market. |
input.position | PositionV3 | Status pending_delivery. |
input.caller | string | Any signer. |
input.writerCollateral | string | Collateral token account owned by the writer. |
input.writerPayment | string | USDC token account owned by the writer. |
input.makerCollateral | string | Collateral 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.
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.
Restricted markets are covr-only today.
export declare function encodeCancellationRequestV1(r: CancellationRequestV1): Uint8Array;| Name | Type | Description |
|---|---|---|
r | CancellationRequestV1 | The 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:
| Condition | Message |
|---|---|
termsId is not 0x + 64 hex | RestrictedV3: 32-byte hex required |
| An integer is out of range | RestrictedV3: integer out of range |
| A key is not valid base58 | SolanaError from @solana/kit |
import { encodeCancellationRequestV1, type CancellationRequestV1 } from '@covrfun/maker-sdk';
declare const request: CancellationRequestV1;
const bytes = encodeCancellationRequestV1(request); // 288 bytesdecodeCancellationRequestV1
Decodes 288 bytes back into a CancellationRequestV1.
export declare function decodeCancellationRequestV1(b: Uint8Array): CancellationRequestV1;| Name | Type | Description |
|---|---|---|
b | Uint8Array | Exactly 288 bytes. |
Returns: CancellationRequestV1. Keys are base58; termsId is 0x + 64 hex.
Throws: RestrictedV3: request must be exactly 288 bytes.
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.
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.
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,closeandbundlehave no builder in this SDK.releaseV3Instructionssets 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.