covr.Docs

SDK reference

Setup

On-chain setup and upkeep for a maker: derive your accounts, register your quote key, open and fund your USDC vault, set the caps the program enforces on every fill, and later change them or withdraw. Every function here builds an instruction, computes an address or decodes bytes you read. None signs a transaction, reads the chain or submits anything. The program re-checks every authority and amount.

Setup sequence

Your Solana authority signs and pays rent for every step. Confirm each step at finalized commitment before you send the next.

StepBuilderCreates or changesRequired before a fill?
1signRegistrationGrant, then registerMakerV3Maker and MakerOriginV1 accountsyes
2initializeVaultUSDC vault and PremiumBudget (no cap)yes
3initializeExposureV3Exposure account for one collateral mintyes, per mint
4initializeMintPolicyV1 with mintPolicySettingsForMintPolicyV1 and MintUsageV1 for one mintyes, per mint
5bootstrapMintUsageV1Marks MintUsageV1 readyyes, per mint
6setPremiumBudgetOptional lifetime premium capno
7depositUSDC into the vaultyes: fills pay premium from it
8Your authority's JitoSOL associated token account (@solana-program/token)Where exercised JitoSOL is deliveredno, but needed before exercise
optionalconfigureMakerOperator key and nonce floorno

A fill passes the exposure, premium budget, mint policy, mint usage and origin accounts to the program, so steps 1 to 5 must exist before any fill can land. Step 7 funds the premium the vault pays at fill and the strike it pays at exercise.

Sending a setup instruction

Builders return a @solana/kit instruction. Its accounts carry roles (0 read-only, 1 writable, 2 read-only signer, 3 writable signer) but no signer objects. Add it to a transaction with your own pipeline and sign with your authority.

ts
import {
  appendTransactionMessageInstructions,
  createSolanaRpc,
  createTransactionMessage,
  pipe,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransactionMessageWithSigners,
  type TransactionSigner,
} from '@solana/kit';
import { initializeVault, deriveMaker } from '@covrfun/maker-sdk';

declare const authority: TransactionSigner; // your Solana authority
declare const quoteKeyAddress: string; // your 0x quote key address
const rpc = createSolanaRpc('https://<your rpc>');

const { maker } = await deriveMaker(quoteKeyAddress);
const { instruction } = await initializeVault({ authority: authority.address, maker });
const { value: blockhash } = await rpc.getLatestBlockhash({ commitment: 'finalized' }).send();

const message = pipe(
  createTransactionMessage({ version: 0 }),
  m => setTransactionMessageFeePayerSigner(authority, m),
  m => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  m => appendTransactionMessageInstructions([instruction], m),
);
const signed = await signTransactionMessageWithSigners(message);
// Simulate, send and confirm `signed` with your own RPC at finalized commitment.

Builders that return recommendedComputeUnitLimit expect you to prepend a compute-unit-limit instruction with at least that value, and to simulate first.

Later changes

Signed by the same authority, at any time after setup:

BuilderChangesNotes
withdrawVault USDC back to your own USDC token accountNothing in the vault is reserved for open positions.
setExposureLimitThe Exposure cap of one collateralClassic SPL Token collateral only. Gates new fills only.
updateMintPolicyV1Every mint policy settingNeeds the current generation from decodeMintPolicy.
pauseMintPolicyV1enabled = falseThe policy's watcher may sign it too.
setPremiumBudget, configureMakerLifetime premium cap; operator and nonce floorAs in the setup sequence.

Read your current state with decodeMaker, decodeMintPolicy and decodeMintUsage.

Note

Two changes have no builder. The SDK cannot pause a market you created. Nothing can change the exposure cap of a Token-2022 collateral: the program's set_exposure_limit accepts only a classic SPL Token mint.

deriveMaker

Derives your Maker account and its MakerOriginV1 record from your quote key address. Use it to find the maker address every other setup builder takes.

ts
export declare function deriveMaker(makerEthAddress: string, d?: Deployment): Promise<{
    maker: Address;
    makerBump: number;
    origin: Address;
    originBump: number;
}>;
NameTypeDescription
makerEthAddressstringYour quote key address: 0x plus 40 hex characters, any case.
dDeploymentOptional. Default MAINNET.

Returns: maker, the PDA ["maker", 20 address bytes]; origin, the PDA ["maker-origin-v1", maker]; and their bumps.

Throws:

ConditionMessage
makerEthAddress is not 0x + 40 hex charactersMakerOriginV1: hex identity
makerEthAddress is all zerosMakerOriginV1: zero hex identity
d.programAddress is the zero keyMakerOriginV1: zero identity
d.programAddress is not base58SolanaError from @solana/kit
ts
import { deriveMaker } from '@covrfun/maker-sdk';

const { maker, origin } = await deriveMaker('0x7B99e6A7407Fe0058119F4f13494C0b9cec35738');
// maker  = 6cHK5gxK31ksD3fX7ZPPP6FqBw5CR8vHWehrvLGNx3of
// origin = 4gHXS1EcizH1hp2CNVBLLAHn7ibMc8Ddp13g8ghGaYnb

decodeMaker

Decodes your Maker account and proves the bytes belong to your quote key. Use it to read your on-chain nonce floor (minNonce) and operator.

ts
export declare function decodeMaker(makerAddress: string, raw: Uint8Array, makerEthAddress: string, d?: Deployment): Promise<DecodedMakerAccount>;
NameTypeDescription
makerAddressstringThe account you read: deriveMaker(makerEthAddress).maker.
rawUint8ArrayThe account data, read at finalized commitment.
makerEthAddressstringYour quote key address.
dDeploymentOptional. Default MAINNET.

Returns: DecodedMakerAccount. minNonce is the floor every fill compares a quote nonce to: sign new quotes with nonces at or above it.

Throws:

ConditionMessage
makerAddress is not the PDA of makerEthAddressmaker-sdk: Maker account address is not the PDA of this maker key
raw has the wrong length for a Maker accountInvalid Maker account length
Wrong account discriminatorInvalid Maker discriminator
The account's trailing marker bytes are wrongInvalid Maker fence magic
Stored Ethereum address differs from makerEthAddressmaker-sdk: Maker account belongs to another maker key
Stored bump differs from the PDA bumpmaker-sdk: Maker account bump is not the PDA bump
Bad makerEthAddressas deriveMaker
Warning

The decoder never sees the account owner. Check that the account's owner is PROGRAM_ID yourself.

ts
import { createSolanaRpc, address } from '@solana/kit';
import { decodeMaker, deriveMaker, PROGRAM_ID } from '@covrfun/maker-sdk';

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

const { maker } = await deriveMaker(quoteKeyAddress);
const { value } = await rpc
  .getAccountInfo(address(maker), { commitment: 'finalized', encoding: 'base64' })
  .send();
if (!value || value.owner !== PROGRAM_ID) throw new Error('Maker account missing');
const decoded = await decodeMaker(maker, new Uint8Array(Buffer.from(value.data[0], 'base64')), quoteKeyAddress);
console.log('nonce floor', decoded.minNonce);

deriveVault

Derives your USDC vault and your PremiumBudget account.

ts
export declare function deriveVault(maker: string, d?: Deployment): Promise<{
    vault: Address<string>;
    premiumBudget: Address<string>;
}>;
NameTypeDescription
makerstringYour Maker account (from deriveMaker).
dDeploymentOptional. Default MAINNET.

Returns: vault, the PDA ["stable", maker, USDC mint], a USDC token account whose token authority is your Maker account; premiumBudget, the PDA ["premium-budget", maker, USDC mint].

Throws: SolanaError from @solana/kit when maker or d.programAddress is not a valid address.

ts
import { deriveMaker, deriveVault } from '@covrfun/maker-sdk';

declare const quoteKeyAddress: string;
const { maker } = await deriveMaker(quoteKeyAddress);
const { vault, premiumBudget } = await deriveVault(maker);

deriveExposure

Derives your Exposure account for one collateral mint. One Exposure covers that mint across every market.

ts
export declare function deriveExposure(maker: string, collateral: string, d?: Deployment): Promise<Address>;
NameTypeDescription
makerstringYour Maker account.
collateralstringCollateral mint, for example JITOSOL_MINT.
dDeploymentOptional. Default MAINNET.

Returns: the PDA ["exposure", maker, collateral].

Throws: SolanaError when an address is not valid base58.

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

declare const quoteKeyAddress: string;
const { maker } = await deriveMaker(quoteKeyAddress);
const exposure = await deriveExposure(maker, JITOSOL_MINT);

deriveMintPolicy

Derives your MintPolicyV1 and MintUsageV1 accounts for one collateral mint.

ts
export declare function deriveMintPolicy(maker: string, collateral: string, d?: Deployment): Promise<{
    policy: Address;
    usage: Address;
}>;
NameTypeDescription
makerstringYour Maker account.
collateralstringCollateral mint.
dDeploymentOptional. Default MAINNET.

Returns: policy, the PDA ["mint-policy", maker, collateral]; usage, the PDA ["mint-usage", maker, collateral].

Throws:

ConditionMessage
collateral is the zero keyInvalid zero collateral identity
An address is not valid base58SolanaError from @solana/kit
ts
import { deriveMaker, deriveMintPolicy, JITOSOL_MINT } from '@covrfun/maker-sdk';

declare const quoteKeyAddress: string;
const { maker } = await deriveMaker(quoteKeyAddress);
const { policy, usage } = await deriveMintPolicy(maker, JITOSOL_MINT);

deriveMarket

Derives a MarketV3 address from its creator and salt. Use it to pick a free salt before createMarketV3, or to check an address you were given.

ts
export declare function deriveMarket(creator: string, salt: bigint, d?: Deployment): Promise<{
    market: ReturnType<typeof address>;
    bump: number;
}>;
NameTypeDescription
creatorstringThe wallet that creates (and pays for) the market.
saltbigintAny u64 the creator chooses. One market per (creator, salt).
dDeploymentOptional. Default MAINNET.

Returns: market, the PDA ["market-v3", creator, salt as u64 little-endian], and its bump.

Throws:

ConditionMessage
salt is not a bigint in [0, 2^64 - 1]MarketV3 integer
creator is not valid base58SolanaError from @solana/kit
ts
import { deriveMarket } from '@covrfun/maker-sdk';

declare const creator: string;
const { market } = await deriveMarket(creator, 1n);

derivePosition

Derives the PositionV3 a fill of your quote with a given nonce creates, plus its collateral vault, strike escrow, policy and usage. Use it to watch the chain for your fills: the gateway sends no fill message.

ts
export declare function derivePosition(makerEthAddress: string, nonce: bigint, collateral: string, d?: Deployment): Promise<Readonly<import("../settlement/position-v3.js").PositionV3Addresses>>;
NameTypeDescription
makerEthAddressstringYour quote key address.
noncebigintThe quote's nonce, 0 to 2^64 - 2.
collateralstringThe market's collateral mint.
dDeploymentOptional. Default MAINNET.

Returns: a frozen object with maker, position (PDA ["position", 20 address bytes, nonce u64 LE]), collateralVault (["collateral", position]), strikeEscrow (["strike-escrow-v3", position]), policy, usage, and a ...Bump for each.

The position address depends only on your quote key and the nonce, not on the market. One nonce can open at most one position across all your markets, so never reuse a nonce.

Throws:

ConditionMessage
Bad makerEthAddressPositionV3: invalid hex identity or PositionV3: zero hex identity
collateral or d.programAddress is the zero keyPositionV3: zero identity
nonce is not a u64 bigintPositionV3: invalid nonce
nonce is 2^64 - 1 (reserved)PositionV3: reserved nonce
ts
import { derivePosition, JITOSOL_MINT } from '@covrfun/maker-sdk';

declare const quoteKeyAddress: string;
const { position } = await derivePosition(quoteKeyAddress, 1001n, JITOSOL_MINT);
// A PositionV3 at `position` owned by the program means quote nonce 1001 filled.

REGISTER_TYPES

The EIP-712 types of the registration grant: one bytes32 authority field. The object is frozen.

ts
export declare const REGISTER_TYPES: Readonly<{
    Register: {
        name: string;
        type: string;
    }[];
}>;
  • Value: { Register: [{ name: 'authority', type: 'bytes32' }] }
  • Where it matters: signRegistrationGrant signs with it. Your own signer must use exactly this type to match the program's digest.

registrationGrantDomain

Returns the EIP-712 domain of the registration grant for a deployment.

ts
export declare function registrationGrantDomain(d?: Deployment): TypedDataDomain;
NameTypeDescription
dDeploymentOptional. Default MAINNET.

Returns: TypedDataDomain (ethers): name: 'SOL Covered Calls', version: '1', chainId: 2000000001, and verifyingContract = last20(keccak256("deployment-v2" || deploymentId || programId || "registration-v3")). On mainnet verifyingContract is 0xd2d2b887d02b01d3a4371c7b77f96c3880513b4e.

Throws:

ConditionMessage
d.deploymentId is not 32 bytes, or is all zerosInvalid deployment identity
d.deploymentId is not hexethers invalid BytesLike value error
d.programAddress is not valid base58SolanaError from @solana/kit
ts
import { registrationGrantDomain } from '@covrfun/maker-sdk';

const domain = registrationGrantDomain();
// { name: 'SOL Covered Calls', version: '1', chainId: 2000000001,
//   verifyingContract: '0xd2d2b887d02b01d3a4371c7b77f96c3880513b4e' }

registrationGrantMessage

Builds the grant's message: your Solana authority's 32 public-key bytes as bytes32.

ts
export declare function registrationGrantMessage(authority: string): {
    authority: string;
};
NameTypeDescription
authoritystringYour Solana authority (base58).

Returns: { authority }, the key's 32 bytes as 0x + 64 hex characters.

Throws:

ConditionMessage
authority is not a stringmaker-sdk: authority address required
authority is the zero keymaker-sdk: authority must not be the zero key
authority is not valid base58SolanaError from @solana/kit
ts
import { registrationGrantMessage } from '@covrfun/maker-sdk';

registrationGrantMessage('4bBXSXQzPMFD7ayeSiMd1SYHjnCtxLTSyfis5VVu7kWh');
// { authority: '0x3554b5709c9cf550f27084d8e693104bafaa5eec4a51e3555818c69136da1a76' }

signRegistrationGrant

Signs the registration grant with your quote key. The grant lets your Solana authority register that quote key on chain, once.

ts
export declare function signRegistrationGrant(signer: TypedDataSigner, authority: string, d?: Deployment): Promise<{
    signature: string;
    signer: string;
    domain: TypedDataDomain;
    types: {
        Register: {
            name: string;
            type: string;
        }[];
    };
    message: {
        authority: string;
    };
}>;
NameTypeDescription
signerTypedDataSignerYour quote key.
authoritystringThe Solana authority that will own the Maker account.
dDeploymentOptional. Default MAINNET.

Returns: signature (lowercase 0x-hex, 65 bytes); signer, the checksummed address the signature recovers to; and the exact domain, types and message that were signed.

The function does not compare signer with any expected key. Check it equals your quote key address before you register.

Throws:

ts
import { signRegistrationGrant, type TypedDataSigner } from '@covrfun/maker-sdk';

declare const quoteKey: TypedDataSigner & { address: string };
declare const authority: string; // your Solana authority

const grant = await signRegistrationGrant(quoteKey, authority);
if (grant.signer !== quoteKey.address) throw new Error('grant signed by the wrong key');

registerMakerV3

Builds register_maker_v3, which creates your Maker and MakerOriginV1 accounts. It verifies the grant locally first, so a wrong domain, key or authority fails before you pay any fee.

ts
export declare function registerMakerV3(input: RegisterMakerV3Input, d?: Deployment): Promise<{
    maker: Address;
    origin: Address;
    instruction: Instruction<string, readonly (import("@solana/kit").AccountLookupMeta<string, string> | AccountMeta<string>)[]> & {
        accounts: AccountMeta[];
        data: Uint8Array;
    };
}>;
NameTypeDescription
input.authoritystringYour Solana authority. It signs the transaction and pays rent.
input.makerEthAddressstringYour quote key address.
input.signaturestring | Uint8ArrayThe grant signature from signRegistrationGrant: 0x-hex or 65 raw bytes.
dDeploymentOptional. Default MAINNET.

Returns: maker, origin, and the instruction. Accounts: authority (writable signer), maker (writable), origin (writable), System program. Data: the 8-byte discriminator, the 20 address bytes, the 65 signature bytes.

On chain the program verifies the grant again and creates a 117-byte Maker with no operator (the zero key) and min_nonce = 0. The authority and the quote key can never change afterwards.

Throws:

ConditionMessage
Signature malformed or high-ssee assertCanonicalSignature
Signature does not verify for this authority and domainmaker-sdk: registration grant does not verify
Signature recovers to another keymaker-sdk: registration grant is not signed by the maker key for this authority and deployment
Bad makerEthAddressMakerOriginV1: hex identity or MakerOriginV1: zero hex identity
Bad authorityas registrationGrantMessage
ts
import { registerMakerV3, signRegistrationGrant, type TypedDataSigner } from '@covrfun/maker-sdk';

declare const quoteKey: TypedDataSigner & { address: string };
declare const authority: string;

const grant = await signRegistrationGrant(quoteKey, authority);
const { maker, instruction } = await registerMakerV3({
  authority,
  makerEthAddress: quoteKey.address,
  signature: grant.signature,
});
// Your authority signs and sends `instruction`.

initializeVault

Builds initialize_vault, which creates your USDC vault and your PremiumBudget. The budget starts disabled: no lifetime premium cap applies until you call setPremiumBudget.

ts
export declare function initializeVault(input: {
    authority: string;
    maker: string;
}, d?: Deployment): Promise<{
    vault: Address<string>;
    premiumBudget: Address<string>;
    instruction: SdkInstruction;
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs, pays rent).
input.makerstringYour Maker account.
dDeploymentOptional. Default MAINNET.

Returns: vault, premiumBudget and an SdkInstruction. Accounts: authority (writable signer), maker, USDC mint, vault (writable), Token program, System program, premiumBudget (writable).

Throws:

ConditionMessage
authority or maker is not a stringmaker-sdk: authority address required / maker-sdk: maker address required
authority or maker is the zero keymaker-sdk: authority must not be the zero key / maker-sdk: maker must not be the zero key
Not valid base58SolanaError from @solana/kit
ts
import { deriveMaker, initializeVault } from '@covrfun/maker-sdk';

declare const authority: string;
declare const quoteKeyAddress: string;
const { maker } = await deriveMaker(quoteKeyAddress);
const { vault, instruction } = await initializeVault({ authority, maker });

setPremiumBudget

Builds set_premium_budget, which sets an absolute lifetime ceiling on the gross premium your vault pays, summed across every collateral.

ts
export declare function setPremiumBudget(input: {
    authority: string;
    maker: string;
    enabled: boolean;
    limit: bigint;
}, d?: Deployment): Promise<{
    premiumBudget: Address<string>;
    instruction: SdkInstruction;
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs).
input.makerstringYour Maker account.
input.enabledbooleantrue applies the cap. false removes it.
input.limitbigintLifetime gross premium cap, in USDC atoms (10^-6 USDC). u64.
dDeploymentOptional. Default MAINNET.

Returns: premiumBudget and an SdkInstruction. Accounts: authority (read-only signer), maker, USDC mint, premiumBudget (writable). Data: discriminator, enabled (1 byte), limit (u64 LE).

The cap compares against everything spent since the budget was created. Changing it never resets spent. While enabled, a fill fails when spent + gross premium > limit. A limit below what you have already spent blocks every fill.

Throws:

ConditionMessage
enabled is not a booleanmaker-sdk: enabled must be a boolean
limit is not a bigint in [0, 2^64 - 1]maker-sdk: limit must be a u64 bigint
Bad authority or makeras initializeVault
ts
import { setPremiumBudget } from '@covrfun/maker-sdk';

declare const authority: string;
declare const maker: string;
// Cap lifetime gross premium at 50,000 USDC.
const { instruction } = await setPremiumBudget({ authority, maker, enabled: true, limit: 50_000_000_000n });

deposit

Builds deposit, which moves USDC from a token account you own into your vault.

ts
export declare function deposit(input: {
    authority: string;
    maker: string;
    source: string;
    amount: bigint;
}, d?: Deployment): Promise<{
    vault: Address<string>;
    instruction: SdkInstruction;
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs).
input.makerstringYour Maker account.
input.sourcestringA USDC token account whose owner is authority.
input.amountbigintUSDC atoms to move. Positive u64.
dDeploymentOptional. Default MAINNET.

Returns: vault and an SdkInstruction. Accounts: authority (read-only signer), maker, USDC mint, vault (writable), source (writable), Token program.

Throws:

ConditionMessage
amount is not a bigint in [0, 2^64 - 1]maker-sdk: amount must be a u64 bigint
amount is 0nmaker-sdk: deposit amount must be positive
source equals the vault, the maker or the authoritymaker-sdk: source must be the authority's own USDC token account
Bad authority, maker or sourcemaker-sdk: <name> address required, maker-sdk: <name> must not be the zero key, or SolanaError

The program also requires the source's token owner to be the authority.

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

declare const authority: string;
declare const maker: string;
declare const myUsdcAccount: string; // your USDC token account
// Deposit 10,000 USDC.
const { instruction } = await deposit({ authority, maker, source: myUsdcAccount, amount: 10_000_000_000n });

withdraw

Builds withdraw, which moves USDC from your vault to a USDC token account you own.

ts
export declare function withdraw(input: {
    authority: string;
    maker: string;
    destination: string;
    amount: bigint;
}, d?: Deployment): Promise<{
    vault: Address<string>;
    instruction: SdkInstruction;
}>;
NameTypeDescription
input.authoritystringYour Solana authority. The only signer.
input.makerstringYour Maker account.
input.destinationstringA USDC token account whose owner is authority.
input.amountbigintUSDC atoms to move. Positive u64.
dDeploymentOptional. Default MAINNET.

Returns: vault and an SdkInstruction. Accounts: authority (read-only signer), maker, USDC mint, vault (writable), destination (writable), Token program. These are the program's deposit accounts, with the destination in the slot a deposit uses for its source. The program pays out under your Maker account's authority.

Warning

Nothing in the vault is reserved for your open positions. Each exercise pays the strike from the vault, and each fill pays the gross premium from it. Withdraw too much and those exercises and fills fail until you deposit again.

Throws:

ConditionMessage
amount is not a bigint in [0, 2^64 - 1]maker-sdk: amount must be a u64 bigint
amount is 0nmaker-sdk: withdraw amount must be positive
destination equals the vault, the maker or the authoritymaker-sdk: destination must be the authority's own USDC token account
Bad authority, maker or destinationmaker-sdk: <name> address required, maker-sdk: <name> must not be the zero key, or SolanaError

The program also requires amount > 0, the destination's mint to be USDC and its owner to be the authority.

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

declare const authority: string;
declare const maker: string;
declare const myUsdcAccount: string; // your USDC token account
// Withdraw 1,000 USDC.
const { instruction } = await withdraw({ authority, maker, destination: myUsdcAccount, amount: 1_000_000_000n });

initializeExposureV3

Builds initialize_exposure_v3, which creates the Exposure account for one collateral mint: a cap on the collateral atoms held across all your open positions on that mint.

ts
export declare function initializeExposureV3(input: {
    authority: string;
    makerEthAddress: string;
    collateral: CollateralIdentity;
    limitAtoms: bigint;
}, d?: Deployment): Promise<{
    maker: Address;
    exposure: Address;
    recommendedComputeUnitLimit: 200000;
    instruction: import("../settlement/ordinary-v3.js").OrdinaryV3Instruction;
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs, pays rent).
input.makerEthAddressstringYour quote key address.
input.collateralCollateralIdentityMint, token program and decimals.
input.limitAtomsbigintCap, in collateral atoms. u64.
dDeploymentOptional. Default MAINNET.

Returns: maker, exposure, recommendedComputeUnitLimit (200,000) and the instruction. Accounts: authority (writable signer), maker, collateral mint, exposure (writable), System program. Data: discriminator, limitAtoms (u64 LE).

A fill fails when the open atoms on this mint plus the fill's atoms would exceed limitAtoms.

Throws:

ConditionMessage
authority or d.programAddress is the zero keyOrdinaryV3: zero identity
collateral.program is not a token program, or the mint is native SOLOrdinaryV3: unsupported token identity
collateral.decimals is not an integer 0 to 255OrdinaryV3: invalid decimals
limitAtoms is not a u64 bigintOrdinaryV3: integer out of range
Bad makerEthAddressPositionV3: invalid hex identity or PositionV3: zero hex identity
ts
import { initializeExposureV3, JITOSOL_MINT, TOKEN_PROGRAM } from '@covrfun/maker-sdk';

declare const authority: string;
declare const quoteKeyAddress: string;
// At most 100 JitoSOL open at once.
const { exposure, instruction, recommendedComputeUnitLimit } = await initializeExposureV3({
  authority,
  makerEthAddress: quoteKeyAddress,
  collateral: { mint: JITOSOL_MINT, program: TOKEN_PROGRAM, decimals: 9 },
  limitAtoms: 100_000_000_000n,
});

setExposureLimit

Builds set_exposure_limit, which replaces the cap initializeExposureV3 set for one collateral. It takes the same input.

ts
export declare function setExposureLimit(input: {
    authority: string;
    makerEthAddress: string;
    collateral: CollateralIdentity;
    limitAtoms: bigint;
}, d?: Deployment): Promise<{
    maker: Address;
    exposure: Address;
    instruction: SdkInstruction;
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs).
input.makerEthAddressstringYour quote key address.
input.collateralCollateralIdentityThe collateral. program must be TOKEN_PROGRAM. decimals is not used.
input.limitAtomsbigintNew cap, in collateral atoms. u64.
dDeploymentOptional. Default MAINNET.

Returns: maker, exposure and an SdkInstruction. Accounts: authority (read-only signer), maker, collateral mint, exposure (writable). Data: discriminator, limitAtoms (u64 LE).

The cap gates new fills only. Positions already open above a lowered cap stay open.

Note

Classic SPL Token collateral only. The program reads the collateral account as a classic SPL Token mint, so it cannot change a Token-2022 collateral's cap. The SDK refuses that case instead of letting it fail on chain.

Throws:

ConditionMessage
limitAtoms is not a bigint in [0, 2^64 - 1]maker-sdk: limitAtoms must be a u64 bigint
Bad authoritymaker-sdk: authority address required, maker-sdk: authority must not be the zero key, or SolanaError
collateral.mint missing or the zero keymaker-sdk: collateral mint address required / maker-sdk: collateral mint must not be the zero key
collateral.program is not the SPL Token programmaker-sdk: set_exposure_limit reads the collateral as a legacy SPL Token mint: a Token-2022 collateral cap cannot be changed
Bad makerEthAddressas deriveMaker
ts
import { setExposureLimit, JITOSOL_MINT, TOKEN_PROGRAM } from '@covrfun/maker-sdk';

declare const authority: string;
declare const quoteKeyAddress: string;
// Lower the JitoSOL cap to 50 JitoSOL open at once.
const { instruction } = await setExposureLimit({
  authority,
  makerEthAddress: quoteKeyAddress,
  collateral: { mint: JITOSOL_MINT, program: TOKEN_PROGRAM, decimals: 9 },
  limitAtoms: 50_000_000_000n,
});

mintPolicySettingsFor

Builds mint policy settings bound to one market's termsId and profileHash, with your caps. Pass a decoded market. The result goes to initializeMintPolicyV1.

ts
export declare function mintPolicySettingsFor(market: {
    termsId: Uint8Array;
    profileHash: Uint8Array;
}, caps: {
    watcher?: string;
    enabled?: boolean;
    maxOrderAtoms: bigint;
    maxReservedAtoms: bigint;
    maxReservedStrikeUsdc: bigint;
    lifetimePremiumLimitUsdc?: bigint;
}): MintPolicySettingsV1;
NameTypeDescription
market{ termsId; profileHash }Usually a DecodedMarketV3. Both are 32 bytes.
caps.watcherstringOptional. A key that may pause the policy (and do nothing else). Default: the zero key 11111111111111111111111111111111, meaning no watcher.
caps.enabledbooleanOptional. Default true. A disabled policy refuses every fill on the mint.
caps.maxOrderAtomsbigintLargest single fill, in collateral atoms.
caps.maxReservedAtomsbigintMost collateral atoms open at once on this mint.
caps.maxReservedStrikeUsdcbigintMost strike obligation open at once on this mint, in USDC atoms.
caps.lifetimePremiumLimitUsdcbigintOptional. Lifetime gross premium cap on this mint, in USDC atoms. Omitted means no cap.

Returns: MintPolicySettingsV1. lifetimePremiumLimitEnabled is true exactly when you passed lifetimePremiumLimitUsdc. termsId and profileHash are copies.

A policy holds one termsId, so one mint is quoted in ordinary markets or in restricted markets, never both. The policy also admits only markets with the same profileHash (the mint's committed token profile).

Warning

lifetimePremiumLimitUsdc: 0n is a cap of zero, not "no cap": the first fill's premium already exceeds it, so the mint takes no fills. Omit the field for no mint-level lifetime cap.

Throws: nothing. It validates nothing; initializeMintPolicyV1 does.

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

declare const market: DecodedMarketV3; // from decodeMarketV3
const settings = mintPolicySettingsFor(market, {
  maxOrderAtoms: 1_000_000_000n, // 1 JitoSOL per fill (the program caps a fill at 50 SOL of stake-pool value)
  maxReservedAtoms: 100_000_000_000n, // 100 JitoSOL open
  maxReservedStrikeUsdc: 25_000_000_000n, // 25,000 USDC of strike open
});

initializeMintPolicyV1

Builds initialize_mint_policy_v1, which creates your MintPolicyV1 (generation 1) and MintUsageV1 for one collateral mint.

ts
export declare function initializeMintPolicyV1(input: {
    authority: string;
    maker: string;
    collateral: string;
    settings: MintPolicySettingsV1;
}, d?: Deployment): Promise<{
    policy: Address;
    usage: Address;
    instruction: Instruction<string, readonly (import("@solana/kit").AccountLookupMeta<string, string> | AccountMeta<string>)[]> & {
        accounts: AccountMeta[];
        data: Uint8Array;
    };
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs, pays rent).
input.makerstringYour Maker account.
input.collateralstringCollateral mint.
input.settingsMintPolicySettingsV1From mintPolicySettingsFor.
dDeploymentOptional. Default MAINNET.

Returns: policy, usage and the instruction. Accounts: authority (writable signer), maker, collateral mint, USDC mint, policy (writable), usage (writable), System program. Data: discriminator, then the settings (watcher 32, enabled 1, termsId 32, profileHash 32, maxOrderAtoms u64, maxReservedAtoms u64, maxReservedStrikeUsdc u64, lifetimePremiumLimitEnabled 1, lifetimePremiumLimitUsdc u64).

Fills on this mint still fail until bootstrapMintUsageV1 runs.

Throws:

ConditionMessage
collateral is the zero keyInvalid zero collateral identity
lifetimePremiumLimitEnabled is false but the limit is not 0A disabled lifetime limit must be zero
enabled or lifetimePremiumLimitEnabled is not a booleanInvalid policy boolean
termsId or profileHash is not 32 bytes or is all zerostermsId must be a nonzero 32-byte value / profileHash must be a nonzero 32-byte value
A cap is not a u64 bigintInvalid maxOrderAtoms u64 (and likewise for each cap)
An address is not valid base58SolanaError from @solana/kit
ts
import { initializeMintPolicyV1, JITOSOL_MINT, type MintPolicySettingsV1 } from '@covrfun/maker-sdk';

declare const authority: string;
declare const maker: string;
declare const settings: MintPolicySettingsV1; // from mintPolicySettingsFor
const { policy, usage, instruction } = await initializeMintPolicyV1({
  authority,
  maker,
  collateral: JITOSOL_MINT,
  settings,
});

updateMintPolicyV1

Builds update_mint_policy_v1, which replaces every setting of one mint policy. It applies only if the policy is still at expectedGeneration; the generation then goes up by one.

ts
export declare function updateMintPolicyV1(input: {
    authority: string;
    maker: string;
    collateral: string;
    expectedGeneration: bigint;
    settings: MintPolicySettingsV1;
}, d?: Deployment): Promise<{
    policy: Address;
    usage: Address;
    instruction: Instruction<string, readonly (import("@solana/kit").AccountLookupMeta<string, string> | AccountMeta<string>)[]> & {
        accounts: AccountMeta[];
        data: Uint8Array;
    };
}>;
NameTypeDescription
input.authoritystringYour Solana authority. Only it may update; a watcher may not.
input.makerstringYour Maker account.
input.collateralstringCollateral mint.
input.expectedGenerationbigintThe policy's current generation, from decodeMintPolicy.
input.settingsMintPolicySettingsV1The complete new settings. Start from the decoded settings to change one field.
dDeploymentOptional. Default MAINNET.

Returns: policy, usage and the instruction. Accounts: authority (read-only signer), maker, collateral mint, USDC mint, policy (writable), usage. Data: discriminator, expectedGeneration (u64 LE), then the settings as in initializeMintPolicyV1.

If another update or a pause landed first, the generation has moved and the program refuses yours. Read the policy again and rebuild.

Throws:

ConditionMessage
Bad authority or makermaker-sdk: authority address required, maker-sdk: authority must not be the zero key, maker-sdk: maker address required, maker-sdk: maker must not be the zero key, or SolanaError
expectedGeneration is not a bigint with 0 < g < 2^64 - 1Invalid expected generation
collateral is the zero keyInvalid zero collateral identity
Bad settingsthe initializeMintPolicyV1 settings errors
An address is not valid base58SolanaError from @solana/kit
ts
import { updateMintPolicyV1, JITOSOL_MINT, type MintPolicyV1 } from '@covrfun/maker-sdk';

declare const authority: string;
declare const maker: string;
declare const current: MintPolicyV1; // from decodeMintPolicy, read just now

// Halve the largest single fill, keep everything else.
const { instruction } = await updateMintPolicyV1({
  authority,
  maker,
  collateral: JITOSOL_MINT,
  expectedGeneration: current.generation,
  settings: { ...current.settings, maxOrderAtoms: current.settings.maxOrderAtoms / 2n },
});

pauseMintPolicyV1

Builds pause_mint_policy_v1, which sets the policy's enabled to false so the mint takes no new fills. Your authority or the policy's watcher may sign it.

ts
export declare function pauseMintPolicyV1(input: {
    signer: string;
    maker: string;
    collateral: string;
    expectedGeneration: bigint;
}, d?: Deployment): Promise<{
    policy: Address;
    instruction: Instruction<string, readonly (import("@solana/kit").AccountLookupMeta<string, string> | AccountMeta<string>)[]> & {
        accounts: AccountMeta[];
        data: Uint8Array;
    };
}>;
NameTypeDescription
input.signerstringYour Solana authority, or the policy's watcher.
input.makerstringYour Maker account.
input.collateralstringCollateral mint. Used only to derive the policy address.
input.expectedGenerationbigintThe policy's current generation.
dDeploymentOptional. Default MAINNET.

Returns: policy and the instruction. Accounts: signer (read-only signer), maker, policy (writable). Data: discriminator, expectedGeneration (u64 LE).

Like an update, it applies only at expectedGeneration and moves the generation up by one. It works even if the collateral mint has since been frozen, closed or changed. To resume, send updateMintPolicyV1 with enabled: true.

Throws:

ConditionMessage
Bad signer or makermaker-sdk: signer address required, maker-sdk: signer must not be the zero key, the same for maker, or SolanaError
expectedGeneration is not a bigint with 0 < g < 2^64 - 1Invalid expected generation
collateral is the zero keyInvalid zero collateral identity
ts
import { pauseMintPolicyV1, JITOSOL_MINT, type MintPolicyV1 } from '@covrfun/maker-sdk';

declare const signer: string; // your authority, or the policy's watcher
declare const maker: string;
declare const current: MintPolicyV1;
const { instruction } = await pauseMintPolicyV1({
  signer,
  maker,
  collateral: JITOSOL_MINT,
  expectedGeneration: current.generation,
});

decodeMintPolicy

Decodes your MintPolicyV1 account and binds it to your maker, authority and collateral. Use it to read the current generation and settings before an update or a pause.

ts
export declare function decodeMintPolicy(policyAddress: string, raw: Uint8Array, expected: {
    authority: string;
    maker: string;
    collateral: CollateralIdentity;
}, d?: Deployment): Promise<MintPolicyV1>;
NameTypeDescription
policyAddressstringThe account you read: deriveMintPolicy(maker, collateral.mint).policy.
rawUint8ArrayIts 342 bytes, read at finalized commitment. For a pause or update you may read generation at confirmed: a stale value only fails with MintPolicyGeneration (6012).
expected.authoritystringYour Solana authority, from your own config.
expected.makerstringYour Maker account.
expected.collateralCollateralIdentityMint, token program and decimals of the collateral.
dDeploymentOptional. Default MAINNET.

Returns: MintPolicyV1.

Warning

The decoder never sees the account owner. Check that it is PROGRAM_ID yourself.

Throws:

ConditionMessage
collateral.program is neither token programUnsupported collateral token program
collateral.decimals is not an integer 0 to 255Invalid collateral decimals
collateral.mint is the zero keyInvalid zero collateral identity
raw is not 342 bytesInvalid policy account length
Wrong discriminatorInvalid policy account discriminator
Schema byte is not 1Unsupported policy schema version
policyAddress or bump is not the canonical PDAInvalid policy PDA or canonical bump
Stored maker, authority, collateral, token program, USDC mint or Token program differsPolicy identity mismatch at byte <offset>
Stored decimals differPolicy decimals mismatch
Generation is 0Invalid policy generation
A stored flag is not 0 or 1, or the settings are invalidInvalid policy boolean, or a settings error
An address is not valid base58SolanaError from @solana/kit
ts
import { address, createSolanaRpc } from '@solana/kit';
import { decodeMintPolicy, deriveMintPolicy, JITOSOL_MINT, PROGRAM_ID, TOKEN_PROGRAM } from '@covrfun/maker-sdk';

declare const authority: string;
declare const maker: string;
const rpc = createSolanaRpc('https://<your rpc>');
const collateral = { mint: JITOSOL_MINT, program: TOKEN_PROGRAM, decimals: 9 };

const { policy } = await deriveMintPolicy(maker, collateral.mint);
const { value } = await rpc
  .getAccountInfo(address(policy), { commitment: 'finalized', encoding: 'base64' })
  .send();
if (!value || value.owner !== PROGRAM_ID) throw new Error('no mint policy');
const current = await decodeMintPolicy(policy, new Uint8Array(Buffer.from(value.data[0], 'base64')), {
  authority,
  maker,
  collateral,
});
console.log(current.generation, current.settings.enabled, current.settings.maxOrderAtoms);

decodeMintUsage

Decodes your MintUsageV1 account: what is open on the mint, the lifetime premium, and whether it is bootstrapped.

ts
export declare function decodeMintUsage(usageAddress: string, raw: Uint8Array, expected: {
    maker: string;
    collateral: CollateralIdentity;
}, d?: Deployment): Promise<MintUsageV1>;
NameTypeDescription
usageAddressstringThe account you read: deriveMintPolicy(maker, collateral.mint).usage.
rawUint8ArrayIts 261 bytes, read at finalized commitment.
expected.makerstringYour Maker account.
expected.collateralCollateralIdentityMint, token program and decimals of the collateral.
dDeploymentOptional. Default MAINNET.

Returns: MintUsageV1. Compare reservedAtoms, reservedStrikeUsdc and cumulativePremiumUsdc with your policy caps to see the room left.

Check the account owner yourself, as for decodeMintPolicy.

Throws:

ConditionMessage
Bad collateral identityUnsupported collateral token program, Invalid collateral decimals or Invalid zero collateral identity
raw is not 261 bytesInvalid policy account length
Wrong discriminator or schemaInvalid policy account discriminator / Unsupported policy schema version
usageAddress or bump is not the canonical PDAInvalid usage PDA or canonical bump
Stored maker, collateral, token program, USDC mint, Token program or policy differsPolicy identity mismatch at byte <offset>
Stored decimals differUsage decimals mismatch
The bootstrapped flag is not 0 or 1Invalid policy boolean
ts
import { decodeMintUsage, JITOSOL_MINT, TOKEN_PROGRAM } from '@covrfun/maker-sdk';

declare const maker: string;
declare const usageAddress: string; // deriveMintPolicy(maker, JITOSOL_MINT).usage
declare const raw: Uint8Array; // finalized account data, owner checked
const usage = await decodeMintUsage(usageAddress, raw, {
  maker,
  collateral: { mint: JITOSOL_MINT, program: TOKEN_PROGRAM, decimals: 9 },
});
console.log(usage.bootstrapped, usage.reservedAtoms, usage.openClaims);

bootstrapMintUsageV1

Builds bootstrap_mint_usage_v1, which marks your MintUsageV1 for a mint as ready. Fills on the mint fail until it runs.

ts
export declare function bootstrapMintUsageV1(input: {
    authority: string;
    makerEthAddress: string;
    collateral: string;
}, d?: Deployment): Promise<{
    origin: Address<string>;
    policy: Address;
    usage: Address;
    instruction: Instruction<string, readonly (import("@solana/kit").AccountLookupMeta<string, string> | AccountMeta<string>)[]> & {
        accounts: AccountMeta[];
        data: Uint8Array;
    };
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs).
input.makerEthAddressstringYour quote key address.
input.collateralstringCollateral mint.
dDeploymentOptional. Default MAINNET.

Returns: origin, policy, usage and the instruction. Accounts: authority (read-only signer), maker, origin, policy, usage (writable). Data: the discriminator only.

Throws:

ConditionMessage
Bad makerEthAddressas deriveMaker
authority or collateral is the zero keyMakerOriginV1: zero identity
An address is not valid base58SolanaError from @solana/kit
ts
import { bootstrapMintUsageV1, JITOSOL_MINT } from '@covrfun/maker-sdk';

declare const authority: string;
declare const quoteKeyAddress: string;
const { usage, instruction } = await bootstrapMintUsageV1({
  authority,
  makerEthAddress: quoteKeyAddress,
  collateral: JITOSOL_MINT,
});

configureMaker

Builds configure_maker, which sets your operator key and your nonce floor min_nonce. Raising min_nonce is how you cancel signed quotes: every fill of a quote with a lower nonce fails.

ts
export declare function configureMaker(input: {
    authority: string;
    makerEthAddress: string;
    operator: string;
    minNonce: bigint;
}, d?: Deployment): Promise<{
    maker: Address<string>;
    instruction: Instruction<string, readonly (import("@solana/kit").AccountLookupMeta<string, string> | AccountMeta<string>)[]> & {
        accounts: AccountMeta[];
        data: Uint8Array;
    };
}>;
NameTypeDescription
input.authoritystringYour Solana authority (signs).
input.makerEthAddressstringYour quote key address.
input.operatorstringThe operator key. It may sign exercises for you. Pass the current operator to keep it. The zero key 11111111111111111111111111111111 revokes it.
input.minNoncebigintNew nonce floor. u64. Must be at least the current floor.
dDeploymentOptional. Default MAINNET.

Returns: maker and the instruction. Accounts: authority (read-only signer), maker (writable). Data: discriminator, operator (32 bytes), minNonce (u64 LE).

The instruction replaces both fields. There is no default operator: read your current one with decodeMaker and pass it back if you want to keep it. The program refuses a minNonce lower than the current one.

Warning

Desks have no gateway route to withdraw a quote. For an immediate, reversible stop, pause your mint policy first (Cancel quotes). To cancel signed quotes for good, raise min_nonce above their nonces with this instruction. A quote also expires on its own: its validUntil is at most 60 s after the gateway admits it.

Throws: AssertionError (from node:assert) on bad input:

ConditionMessage
minNonce is not a bigint in [0, 2^64 - 1]uint64 bigint required
makerEthAddress is all zerosZero maker identity
makerEthAddress is not 0x + 40 hexNode's generated message, starting The input did not match the regular expression
authority or d.programAddress is the zero keyNode's generated message, starting Expected "actual" to be strictly unequal to
An address is not valid base58SolanaError from @solana/kit
ts
import { configureMaker, type DecodedMakerAccount } from '@covrfun/maker-sdk';

declare const authority: string;
declare const quoteKeyAddress: string;
declare const current: DecodedMakerAccount; // from decodeMaker, read just now

// Cancel every signed quote with a nonce below 5000, keep the operator.
const { instruction } = await configureMaker({
  authority,
  makerEthAddress: quoteKeyAddress,
  operator: current.operator,
  minNonce: 5000n,
});