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.
| Step | Builder | Creates or changes | Required before a fill? |
|---|---|---|---|
| 1 | signRegistrationGrant, then registerMakerV3 | Maker and MakerOriginV1 accounts | yes |
| 2 | initializeVault | USDC vault and PremiumBudget (no cap) | yes |
| 3 | initializeExposureV3 | Exposure account for one collateral mint | yes, per mint |
| 4 | initializeMintPolicyV1 with mintPolicySettingsFor | MintPolicyV1 and MintUsageV1 for one mint | yes, per mint |
| 5 | bootstrapMintUsageV1 | Marks MintUsageV1 ready | yes, per mint |
| 6 | setPremiumBudget | Optional lifetime premium cap | no |
| 7 | deposit | USDC into the vault | yes: fills pay premium from it |
| 8 | Your authority's JitoSOL associated token account (@solana-program/token) | Where exercised JitoSOL is delivered | no, but needed before exercise |
| optional | configureMaker | Operator key and nonce floor | no |
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.
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:
| Builder | Changes | Notes |
|---|---|---|
withdraw | Vault USDC back to your own USDC token account | Nothing in the vault is reserved for open positions. |
setExposureLimit | The Exposure cap of one collateral | Classic SPL Token collateral only. Gates new fills only. |
updateMintPolicyV1 | Every mint policy setting | Needs the current generation from decodeMintPolicy. |
pauseMintPolicyV1 | enabled = false | The policy's watcher may sign it too. |
setPremiumBudget, configureMaker | Lifetime premium cap; operator and nonce floor | As in the setup sequence. |
Read your current state with decodeMaker, decodeMintPolicy and decodeMintUsage.
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.
export declare function deriveMaker(makerEthAddress: string, d?: Deployment): Promise<{
maker: Address;
makerBump: number;
origin: Address;
originBump: number;
}>;| Name | Type | Description |
|---|---|---|
makerEthAddress | string | Your quote key address: 0x plus 40 hex characters, any case. |
d | Deployment | Optional. Default MAINNET. |
Returns: maker, the PDA ["maker", 20 address bytes]; origin, the PDA ["maker-origin-v1", maker]; and their bumps.
Throws:
| Condition | Message |
|---|---|
makerEthAddress is not 0x + 40 hex characters | MakerOriginV1: hex identity |
makerEthAddress is all zeros | MakerOriginV1: zero hex identity |
d.programAddress is the zero key | MakerOriginV1: zero identity |
d.programAddress is not base58 | SolanaError from @solana/kit |
import { deriveMaker } from '@covrfun/maker-sdk';
const { maker, origin } = await deriveMaker('0x7B99e6A7407Fe0058119F4f13494C0b9cec35738');
// maker = 6cHK5gxK31ksD3fX7ZPPP6FqBw5CR8vHWehrvLGNx3of
// origin = 4gHXS1EcizH1hp2CNVBLLAHn7ibMc8Ddp13g8ghGaYnbdecodeMaker
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.
export declare function decodeMaker(makerAddress: string, raw: Uint8Array, makerEthAddress: string, d?: Deployment): Promise<DecodedMakerAccount>;| Name | Type | Description |
|---|---|---|
makerAddress | string | The account you read: deriveMaker(makerEthAddress).maker. |
raw | Uint8Array | The account data, read at finalized commitment. |
makerEthAddress | string | Your quote key address. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
makerAddress is not the PDA of makerEthAddress | maker-sdk: Maker account address is not the PDA of this maker key |
raw has the wrong length for a Maker account | Invalid Maker account length |
| Wrong account discriminator | Invalid Maker discriminator |
| The account's trailing marker bytes are wrong | Invalid Maker fence magic |
Stored Ethereum address differs from makerEthAddress | maker-sdk: Maker account belongs to another maker key |
| Stored bump differs from the PDA bump | maker-sdk: Maker account bump is not the PDA bump |
Bad makerEthAddress | as deriveMaker |
The decoder never sees the account owner. Check that the account's owner is PROGRAM_ID yourself.
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.
export declare function deriveVault(maker: string, d?: Deployment): Promise<{
vault: Address<string>;
premiumBudget: Address<string>;
}>;| Name | Type | Description |
|---|---|---|
maker | string | Your Maker account (from deriveMaker). |
d | Deployment | Optional. 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.
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.
export declare function deriveExposure(maker: string, collateral: string, d?: Deployment): Promise<Address>;| Name | Type | Description |
|---|---|---|
maker | string | Your Maker account. |
collateral | string | Collateral mint, for example JITOSOL_MINT. |
d | Deployment | Optional. Default MAINNET. |
Returns: the PDA ["exposure", maker, collateral].
Throws: SolanaError when an address is not valid base58.
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.
export declare function deriveMintPolicy(maker: string, collateral: string, d?: Deployment): Promise<{
policy: Address;
usage: Address;
}>;| Name | Type | Description |
|---|---|---|
maker | string | Your Maker account. |
collateral | string | Collateral mint. |
d | Deployment | Optional. Default MAINNET. |
Returns: policy, the PDA ["mint-policy", maker, collateral]; usage, the PDA ["mint-usage", maker, collateral].
Throws:
| Condition | Message |
|---|---|
collateral is the zero key | Invalid zero collateral identity |
| An address is not valid base58 | SolanaError from @solana/kit |
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.
export declare function deriveMarket(creator: string, salt: bigint, d?: Deployment): Promise<{
market: ReturnType<typeof address>;
bump: number;
}>;| Name | Type | Description |
|---|---|---|
creator | string | The wallet that creates (and pays for) the market. |
salt | bigint | Any u64 the creator chooses. One market per (creator, salt). |
d | Deployment | Optional. Default MAINNET. |
Returns: market, the PDA ["market-v3", creator, salt as u64 little-endian], and its bump.
Throws:
| Condition | Message |
|---|---|
salt is not a bigint in [0, 2^64 - 1] | MarketV3 integer |
creator is not valid base58 | SolanaError from @solana/kit |
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.
export declare function derivePosition(makerEthAddress: string, nonce: bigint, collateral: string, d?: Deployment): Promise<Readonly<import("../settlement/position-v3.js").PositionV3Addresses>>;| Name | Type | Description |
|---|---|---|
makerEthAddress | string | Your quote key address. |
nonce | bigint | The quote's nonce, 0 to 2^64 - 2. |
collateral | string | The market's collateral mint. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
Bad makerEthAddress | PositionV3: invalid hex identity or PositionV3: zero hex identity |
collateral or d.programAddress is the zero key | PositionV3: zero identity |
nonce is not a u64 bigint | PositionV3: invalid nonce |
nonce is 2^64 - 1 (reserved) | PositionV3: reserved nonce |
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.
export declare const REGISTER_TYPES: Readonly<{
Register: {
name: string;
type: string;
}[];
}>;- Value:
{ Register: [{ name: 'authority', type: 'bytes32' }] } - Where it matters:
signRegistrationGrantsigns 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.
export declare function registrationGrantDomain(d?: Deployment): TypedDataDomain;| Name | Type | Description |
|---|---|---|
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
d.deploymentId is not 32 bytes, or is all zeros | Invalid deployment identity |
d.deploymentId is not hex | ethers invalid BytesLike value error |
d.programAddress is not valid base58 | SolanaError from @solana/kit |
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.
export declare function registrationGrantMessage(authority: string): {
authority: string;
};| Name | Type | Description |
|---|---|---|
authority | string | Your Solana authority (base58). |
Returns: { authority }, the key's 32 bytes as 0x + 64 hex characters.
Throws:
| Condition | Message |
|---|---|
authority is not a string | maker-sdk: authority address required |
authority is the zero key | maker-sdk: authority must not be the zero key |
authority is not valid base58 | SolanaError from @solana/kit |
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.
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;
};
}>;| Name | Type | Description |
|---|---|---|
signer | TypedDataSigner | Your quote key. |
authority | string | The Solana authority that will own the Maker account. |
d | Deployment | Optional. 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:
- Every error of
registrationGrantMessageandregistrationGrantDomain. - Any error your signer throws.
assertCanonicalSignatureerrors when the signer returns a malformed or high-s signature.
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.
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;
};
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority. It signs the transaction and pays rent. |
input.makerEthAddress | string | Your quote key address. |
input.signature | string | Uint8Array | The grant signature from signRegistrationGrant: 0x-hex or 65 raw bytes. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
| Signature malformed or high-s | see assertCanonicalSignature |
| Signature does not verify for this authority and domain | maker-sdk: registration grant does not verify |
| Signature recovers to another key | maker-sdk: registration grant is not signed by the maker key for this authority and deployment |
Bad makerEthAddress | MakerOriginV1: hex identity or MakerOriginV1: zero hex identity |
Bad authority | as registrationGrantMessage |
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.
export declare function initializeVault(input: {
authority: string;
maker: string;
}, d?: Deployment): Promise<{
vault: Address<string>;
premiumBudget: Address<string>;
instruction: SdkInstruction;
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs, pays rent). |
input.maker | string | Your Maker account. |
d | Deployment | Optional. Default MAINNET. |
Returns: vault, premiumBudget and an SdkInstruction. Accounts: authority (writable signer), maker, USDC mint, vault (writable), Token program, System program, premiumBudget (writable).
Throws:
| Condition | Message |
|---|---|
authority or maker is not a string | maker-sdk: authority address required / maker-sdk: maker address required |
authority or maker is the zero key | maker-sdk: authority must not be the zero key / maker-sdk: maker must not be the zero key |
| Not valid base58 | SolanaError from @solana/kit |
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.
export declare function setPremiumBudget(input: {
authority: string;
maker: string;
enabled: boolean;
limit: bigint;
}, d?: Deployment): Promise<{
premiumBudget: Address<string>;
instruction: SdkInstruction;
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs). |
input.maker | string | Your Maker account. |
input.enabled | boolean | true applies the cap. false removes it. |
input.limit | bigint | Lifetime gross premium cap, in USDC atoms (10^-6 USDC). u64. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
enabled is not a boolean | maker-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 maker | as initializeVault |
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.
export declare function deposit(input: {
authority: string;
maker: string;
source: string;
amount: bigint;
}, d?: Deployment): Promise<{
vault: Address<string>;
instruction: SdkInstruction;
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs). |
input.maker | string | Your Maker account. |
input.source | string | A USDC token account whose owner is authority. |
input.amount | bigint | USDC atoms to move. Positive u64. |
d | Deployment | Optional. Default MAINNET. |
Returns: vault and an SdkInstruction. Accounts: authority (read-only signer), maker, USDC mint, vault (writable), source (writable), Token program.
Throws:
| Condition | Message |
|---|---|
amount is not a bigint in [0, 2^64 - 1] | maker-sdk: amount must be a u64 bigint |
amount is 0n | maker-sdk: deposit amount must be positive |
source equals the vault, the maker or the authority | maker-sdk: source must be the authority's own USDC token account |
Bad authority, maker or source | maker-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.
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.
export declare function withdraw(input: {
authority: string;
maker: string;
destination: string;
amount: bigint;
}, d?: Deployment): Promise<{
vault: Address<string>;
instruction: SdkInstruction;
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority. The only signer. |
input.maker | string | Your Maker account. |
input.destination | string | A USDC token account whose owner is authority. |
input.amount | bigint | USDC atoms to move. Positive u64. |
d | Deployment | Optional. 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.
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:
| Condition | Message |
|---|---|
amount is not a bigint in [0, 2^64 - 1] | maker-sdk: amount must be a u64 bigint |
amount is 0n | maker-sdk: withdraw amount must be positive |
destination equals the vault, the maker or the authority | maker-sdk: destination must be the authority's own USDC token account |
Bad authority, maker or destination | maker-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.
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.
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;
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs, pays rent). |
input.makerEthAddress | string | Your quote key address. |
input.collateral | CollateralIdentity | Mint, token program and decimals. |
input.limitAtoms | bigint | Cap, in collateral atoms. u64. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
authority or d.programAddress is the zero key | OrdinaryV3: zero identity |
collateral.program is not a token program, or the mint is native SOL | OrdinaryV3: unsupported token identity |
collateral.decimals is not an integer 0 to 255 | OrdinaryV3: invalid decimals |
limitAtoms is not a u64 bigint | OrdinaryV3: integer out of range |
Bad makerEthAddress | PositionV3: invalid hex identity or PositionV3: zero hex identity |
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.
export declare function setExposureLimit(input: {
authority: string;
makerEthAddress: string;
collateral: CollateralIdentity;
limitAtoms: bigint;
}, d?: Deployment): Promise<{
maker: Address;
exposure: Address;
instruction: SdkInstruction;
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs). |
input.makerEthAddress | string | Your quote key address. |
input.collateral | CollateralIdentity | The collateral. program must be TOKEN_PROGRAM. decimals is not used. |
input.limitAtoms | bigint | New cap, in collateral atoms. u64. |
d | Deployment | Optional. 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.
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:
| Condition | Message |
|---|---|
limitAtoms is not a bigint in [0, 2^64 - 1] | maker-sdk: limitAtoms must be a u64 bigint |
Bad authority | maker-sdk: authority address required, maker-sdk: authority must not be the zero key, or SolanaError |
collateral.mint missing or the zero key | maker-sdk: collateral mint address required / maker-sdk: collateral mint must not be the zero key |
collateral.program is not the SPL Token program | maker-sdk: set_exposure_limit reads the collateral as a legacy SPL Token mint: a Token-2022 collateral cap cannot be changed |
Bad makerEthAddress | as deriveMaker |
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.
export declare function mintPolicySettingsFor(market: {
termsId: Uint8Array;
profileHash: Uint8Array;
}, caps: {
watcher?: string;
enabled?: boolean;
maxOrderAtoms: bigint;
maxReservedAtoms: bigint;
maxReservedStrikeUsdc: bigint;
lifetimePremiumLimitUsdc?: bigint;
}): MintPolicySettingsV1;| Name | Type | Description |
|---|---|---|
market | { termsId; profileHash } | Usually a DecodedMarketV3. Both are 32 bytes. |
caps.watcher | string | Optional. A key that may pause the policy (and do nothing else). Default: the zero key 11111111111111111111111111111111, meaning no watcher. |
caps.enabled | boolean | Optional. Default true. A disabled policy refuses every fill on the mint. |
caps.maxOrderAtoms | bigint | Largest single fill, in collateral atoms. |
caps.maxReservedAtoms | bigint | Most collateral atoms open at once on this mint. |
caps.maxReservedStrikeUsdc | bigint | Most strike obligation open at once on this mint, in USDC atoms. |
caps.lifetimePremiumLimitUsdc | bigint | Optional. 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).
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.
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.
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;
};
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs, pays rent). |
input.maker | string | Your Maker account. |
input.collateral | string | Collateral mint. |
input.settings | MintPolicySettingsV1 | From mintPolicySettingsFor. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
collateral is the zero key | Invalid zero collateral identity |
lifetimePremiumLimitEnabled is false but the limit is not 0 | A disabled lifetime limit must be zero |
enabled or lifetimePremiumLimitEnabled is not a boolean | Invalid policy boolean |
termsId or profileHash is not 32 bytes or is all zeros | termsId must be a nonzero 32-byte value / profileHash must be a nonzero 32-byte value |
| A cap is not a u64 bigint | Invalid maxOrderAtoms u64 (and likewise for each cap) |
| An address is not valid base58 | SolanaError from @solana/kit |
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.
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;
};
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority. Only it may update; a watcher may not. |
input.maker | string | Your Maker account. |
input.collateral | string | Collateral mint. |
input.expectedGeneration | bigint | The policy's current generation, from decodeMintPolicy. |
input.settings | MintPolicySettingsV1 | The complete new settings. Start from the decoded settings to change one field. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
Bad authority or maker | maker-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 - 1 | Invalid expected generation |
collateral is the zero key | Invalid zero collateral identity |
| Bad settings | the initializeMintPolicyV1 settings errors |
| An address is not valid base58 | SolanaError from @solana/kit |
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.
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;
};
}>;| Name | Type | Description |
|---|---|---|
input.signer | string | Your Solana authority, or the policy's watcher. |
input.maker | string | Your Maker account. |
input.collateral | string | Collateral mint. Used only to derive the policy address. |
input.expectedGeneration | bigint | The policy's current generation. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
Bad signer or maker | maker-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 - 1 | Invalid expected generation |
collateral is the zero key | Invalid zero collateral identity |
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.
export declare function decodeMintPolicy(policyAddress: string, raw: Uint8Array, expected: {
authority: string;
maker: string;
collateral: CollateralIdentity;
}, d?: Deployment): Promise<MintPolicyV1>;| Name | Type | Description |
|---|---|---|
policyAddress | string | The account you read: deriveMintPolicy(maker, collateral.mint).policy. |
raw | Uint8Array | Its 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.authority | string | Your Solana authority, from your own config. |
expected.maker | string | Your Maker account. |
expected.collateral | CollateralIdentity | Mint, token program and decimals of the collateral. |
d | Deployment | Optional. Default MAINNET. |
Returns: MintPolicyV1.
The decoder never sees the account owner. Check that it is PROGRAM_ID yourself.
Throws:
| Condition | Message |
|---|---|
collateral.program is neither token program | Unsupported collateral token program |
collateral.decimals is not an integer 0 to 255 | Invalid collateral decimals |
collateral.mint is the zero key | Invalid zero collateral identity |
raw is not 342 bytes | Invalid policy account length |
| Wrong discriminator | Invalid policy account discriminator |
| Schema byte is not 1 | Unsupported policy schema version |
policyAddress or bump is not the canonical PDA | Invalid policy PDA or canonical bump |
| Stored maker, authority, collateral, token program, USDC mint or Token program differs | Policy identity mismatch at byte <offset> |
| Stored decimals differ | Policy decimals mismatch |
| Generation is 0 | Invalid policy generation |
| A stored flag is not 0 or 1, or the settings are invalid | Invalid policy boolean, or a settings error |
| An address is not valid base58 | SolanaError from @solana/kit |
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.
export declare function decodeMintUsage(usageAddress: string, raw: Uint8Array, expected: {
maker: string;
collateral: CollateralIdentity;
}, d?: Deployment): Promise<MintUsageV1>;| Name | Type | Description |
|---|---|---|
usageAddress | string | The account you read: deriveMintPolicy(maker, collateral.mint).usage. |
raw | Uint8Array | Its 261 bytes, read at finalized commitment. |
expected.maker | string | Your Maker account. |
expected.collateral | CollateralIdentity | Mint, token program and decimals of the collateral. |
d | Deployment | Optional. 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:
| Condition | Message |
|---|---|
Bad collateral identity | Unsupported collateral token program, Invalid collateral decimals or Invalid zero collateral identity |
raw is not 261 bytes | Invalid policy account length |
| Wrong discriminator or schema | Invalid policy account discriminator / Unsupported policy schema version |
usageAddress or bump is not the canonical PDA | Invalid usage PDA or canonical bump |
| Stored maker, collateral, token program, USDC mint, Token program or policy differs | Policy identity mismatch at byte <offset> |
| Stored decimals differ | Usage decimals mismatch |
| The bootstrapped flag is not 0 or 1 | Invalid policy boolean |
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.
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;
};
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs). |
input.makerEthAddress | string | Your quote key address. |
input.collateral | string | Collateral mint. |
d | Deployment | Optional. Default MAINNET. |
Returns: origin, policy, usage and the instruction. Accounts: authority (read-only signer), maker, origin, policy, usage (writable). Data: the discriminator only.
Throws:
| Condition | Message |
|---|---|
Bad makerEthAddress | as deriveMaker |
authority or collateral is the zero key | MakerOriginV1: zero identity |
| An address is not valid base58 | SolanaError from @solana/kit |
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.
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;
};
}>;| Name | Type | Description |
|---|---|---|
input.authority | string | Your Solana authority (signs). |
input.makerEthAddress | string | Your quote key address. |
input.operator | string | The operator key. It may sign exercises for you. Pass the current operator to keep it. The zero key 11111111111111111111111111111111 revokes it. |
input.minNonce | bigint | New nonce floor. u64. Must be at least the current floor. |
d | Deployment | Optional. 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.
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:
| Condition | Message |
|---|---|
minNonce is not a bigint in [0, 2^64 - 1] | uint64 bigint required |
makerEthAddress is all zeros | Zero maker identity |
makerEthAddress is not 0x + 40 hex | Node's generated message, starting The input did not match the regular expression |
authority or d.programAddress is the zero key | Node's generated message, starting Expected "actual" to be strictly unequal to |
| An address is not valid base58 | SolanaError from @solana/kit |
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,
});