@epicentral/sos-sdk 0.15.1-beta → 0.16.0-beta

package/generated/types/mintLegArgs.ts

@@ -0,0 +1,67 @@
+/**
+ * This code was AUTOGENERATED using the Codama library.
+ * Please DO NOT EDIT THIS FILE, instead use visitors
+ * to add features, then rerun Codama to update it.
+ *
+ * @see https://github.com/codama-idl/codama
+ */
+
+import {
+  combineCodec,
+  getF64Decoder,
+  getF64Encoder,
+  getStructDecoder,
+  getStructEncoder,
+  getU64Decoder,
+  getU64Encoder,
+  type FixedSizeCodec,
+  type FixedSizeDecoder,
+  type FixedSizeEncoder,
+} from "@solana/kit";
+
+/**
+ * One leg of a multi-strike mint. All amounts in base units
+ * (1 contract = 1_000_000; collateral in collateral-mint base units).
+ */
+export type MintLegArgs = {
+  strikePrice: number;
+  quantity: bigint;
+  makerCollateralAmount: bigint;
+  borrowedAmount: bigint;
+  maxRequiredCollateralAmount: bigint;
+};
+
+export type MintLegArgsArgs = {
+  strikePrice: number;
+  quantity: number | bigint;
+  makerCollateralAmount: number | bigint;
+  borrowedAmount: number | bigint;
+  maxRequiredCollateralAmount: number | bigint;
+};
+
+export function getMintLegArgsEncoder(): FixedSizeEncoder<MintLegArgsArgs> {
+  return getStructEncoder([
+    ["strikePrice", getF64Encoder()],
+    ["quantity", getU64Encoder()],
+    ["makerCollateralAmount", getU64Encoder()],
+    ["borrowedAmount", getU64Encoder()],
+    ["maxRequiredCollateralAmount", getU64Encoder()],
+  ]);
+}
+
+export function getMintLegArgsDecoder(): FixedSizeDecoder<MintLegArgs> {
+  return getStructDecoder([
+    ["strikePrice", getF64Decoder()],
+    ["quantity", getU64Decoder()],
+    ["makerCollateralAmount", getU64Decoder()],
+    ["borrowedAmount", getU64Decoder()],
+    ["maxRequiredCollateralAmount", getU64Decoder()],
+  ]);
+}
+
+export function getMintLegArgsCodec(): FixedSizeCodec<
+  MintLegArgsArgs,
+  MintLegArgs
+> {
+  return combineCodec(getMintLegArgsEncoder(), getMintLegArgsDecoder());
+}

package/index.ts

@@ -12,7 +12,25 @@ export {
 export { parseOptionProgramInstruction } from "./shared/option-program-parser";
 
 export * from "./accounts/pdas";
-export * from "./accounts/fetchers";
+export {
+  accountExists,
+  decodeCollateralVaultFromCollateralPoolRawData,
+  decodeOptionPoolTradePubkeysFromRawData,
+  fetchAccountData,
+  fetchBuyerPosition,
+  fetchBuyerSettlementClaim,
+  fetchCollateralPool,
+  fetchLenderPosition,
+  fetchMakerSettlementClaim,
+  fetchManyAccounts,
+  fetchMarketDataAccount,
+  fetchOptionAccount,
+  fetchOptionAccounts,
+  fetchOptionPool,
+  fetchPoolLoan,
+  fetchVault,
+  fetchWriterPosition,
+} from "./accounts/fetchers";
 export * from "./accounts/list";
 export * from "./accounts/resolve-option";
 
@@ -33,6 +51,7 @@ export {
 
 export * from "./short/builders";
 export * from "./short/close-option";
+export * from "./short/multi-mint";
 export * from "./short/pool";
 export * from "./short/preflight";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.15.1-beta",
+  "version": "0.16.0-beta",
   "private": false,
   "description": "Solana Option Standard SDK. The frontend-first SDK for Native Options Trading on Solana. Created by Epicentral Labs.",
   "type": "module",

package/shared/option-program-parser.ts

@@ -23,6 +23,7 @@ import {
   parseInitConfigInstruction,
   parseInitializeMarketDataInstruction,
   parseInitOptionPoolInstruction,
+  parseInitOptionSeriesInstruction,
   parseLiquidateWriterPositionInstruction,
   parseLiquidateWriterPositionRescueInstruction,
   parseMigrateCollateralPoolV1ToV2Instruction,
@@ -38,6 +39,7 @@ import {
   parseOmlpUpdateSupplyLimitInstruction,
   parseOptionExerciseInstruction,
   parseOptionMintInstruction,
+  parseOptionMintMultiInstruction,
   parseOptionValidateInstruction,
   parsePrepareBuyerSettlementInstruction,
   parsePrepareMakerSettlementInstruction,
@@ -162,6 +164,11 @@ export function parseOptionProgramInstruction<
         parseInitConfigInstruction(instruction),
         instructionType,
       );
+    case OptionProgramInstruction.InitOptionSeries:
+      return withInstructionType(
+        parseInitOptionSeriesInstruction(instruction),
+        instructionType,
+      );
     case OptionProgramInstruction.InitOptionPool:
       return withInstructionType(
         parseInitOptionPoolInstruction(instruction),
@@ -247,6 +254,11 @@ export function parseOptionProgramInstruction<
         parseOptionMintInstruction(instruction),
         instructionType,
       );
+    case OptionProgramInstruction.OptionMintMulti:
+      return withInstructionType(
+        parseOptionMintMultiInstruction(instruction),
+        instructionType,
+      );
     case OptionProgramInstruction.OptionValidate:
       return withInstructionType(
         parseOptionValidateInstruction(instruction),

package/short/multi-mint.ts

@@ -0,0 +1,403 @@
+/**
+ * Multi-strike minting builders (Phase 2).
+ *
+ * Flow:
+ * 1. `deriveOptionSeriesLegAddresses` per strike (pure derivation).
+ * 2. `findLegsNeedingSeriesInit` — checks which strikes still need
+ *    `init_option_series` (missing option account OR missing writer position
+ *    for this maker). Series init creates NO Metaplex metadata: the option's
+ *    identity lives on the OptionAccount PDA and clients render names from
+ *    chain state.
+ * 3. `buildInitOptionSeriesInstruction` per needed strike (chunk 2 per tx).
+ * 4. `buildOptionMintMultiTransactionWithDerivation` — chunks legs into
+ *    transactions of ≤ MAX_MINT_LEGS, one Switchboard quote per chunk, and
+ *    per-leg account bundles in remaining_accounts after the quote triple.
+ *
+ * Per-leg remaining_accounts stride (must match the program's
+ * `multi_mint::MINT_LEG_ACCOUNT_STRIDE`):
+ *   [option_account, option_pool, collateral_pool, collateral_vault,
+ *    long_mint, short_mint, escrow_long_account, maker_short_account,
+ *    writer_position, (pool_loan when leg.borrowedAmount > 0)]
+ */
+
+import type { Address, Instruction, TransactionSigner } from "@solana/kit";
+import {
+  getInitOptionSeriesInstructionAsync,
+  getOptionMintMultiInstructionAsync,
+  type OptionType,
+} from "../generated";
+import { PROGRAM_ID, toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction, KitRpc } from "../client/types";
+import { fetchMarketDataAccount } from "../accounts/fetchers";
+import {
+  deriveAssociatedTokenAddress,
+  deriveCollateralPoolPda,
+  deriveLongMintPda,
+  deriveMarketDataPda,
+  deriveOptionAccountPda,
+  deriveOptionPoolPda,
+  derivePoolLoanPdaFromWriterPosition,
+  deriveShortMintPda,
+  deriveWriterPositionPda,
+} from "../accounts/pdas";
+import { invariant } from "../shared/errors";
+import {
+  appendRemainingAccounts,
+  type RemainingAccountInput,
+} from "../shared/remaining-accounts";
+import {
+  buildSwitchboardQuoteInstruction,
+  feedIdBytesToHex,
+  inferSwitchboardNetwork,
+  INSTRUCTIONS_SYSVAR_ADDRESS,
+  SLOT_HASHES_SYSVAR_ADDRESS,
+  SWITCHBOARD_DEFAULT_DEVNET_QUEUE,
+} from "../oracle/switchboard";
+import { deriveVolatilityQuoteAddressFromMarketData } from "../oracle/volatility-quote";
+
+/**
+ * Effective legs per `option_mint_multi` transaction. The on-chain ceiling is
+ * 4 (`multi_mint::MAX_MINT_LEGS`); 3 keeps the quote + multi-mint transaction
+ * comfortably inside the 1232-byte wire limit with ALT compression and the
+ * ~1.4M CU budget.
+ */
+export const MAX_MINT_LEGS = 3;
+
+/** Series-init instructions that fit in one transaction (no oracle quote needed). */
+export const MAX_SERIES_INITS_PER_TRANSACTION = 2;
+
+export interface MultiMintLegInput {
+  strikePrice: number;
+  /** Contracts in base units (1 contract = 1_000_000). */
+  quantity: bigint;
+  /** Maker's own deposit for this leg (collateral base units). */
+  makerCollateralAmount: bigint;
+  /** Borrowed portion for this leg (collateral base units). */
+  borrowedAmount: bigint;
+  /** Slippage guard: max on-chain required collateral accepted (base units). */
+  maxRequiredCollateralAmount: bigint;
+}
+
+export interface OptionSeriesLegAddresses {
+  strikePrice: number;
+  optionAccount: Address;
+  longMint: Address;
+  shortMint: Address;
+  optionPool: Address;
+  collateralPool: Address;
+  collateralVault: Address;
+  escrowLongAccount: Address;
+  premiumVault: Address;
+  makerShortAccount: Address;
+  writerPosition: Address;
+  poolLoan: Address;
+}
+
+export async function deriveOptionSeriesLegAddresses(params: {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  collateralMint: AddressLike;
+  maker: AddressLike;
+  programId?: AddressLike;
+}): Promise<OptionSeriesLegAddresses> {
+  const programId = params.programId ?? PROGRAM_ID;
+  const [optionAccount] = await deriveOptionAccountPda({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId,
+  });
+  const [[longMint], [shortMint], [optionPool], [collateralPool]] = await Promise.all([
+    deriveLongMintPda(optionAccount, programId),
+    deriveShortMintPda(optionAccount, programId),
+    deriveOptionPoolPda(optionAccount, programId),
+    deriveCollateralPoolPda(optionAccount, programId),
+  ]);
+  const [[writerPosition], collateralVault, escrowLongAccount, premiumVault] =
+    await Promise.all([
+      deriveWriterPositionPda(optionPool, params.maker, programId),
+      deriveAssociatedTokenAddress(collateralPool, params.collateralMint, true),
+      deriveAssociatedTokenAddress(optionPool, longMint, true),
+      deriveAssociatedTokenAddress(optionPool, params.collateralMint, true),
+    ]);
+  const [makerShortAccount, [poolLoan]] = await Promise.all([
+    deriveAssociatedTokenAddress(params.maker, shortMint),
+    derivePoolLoanPdaFromWriterPosition(writerPosition, programId),
+  ]);
+
+  return {
+    strikePrice: params.strikePrice,
+    optionAccount,
+    longMint,
+    shortMint,
+    optionPool,
+    collateralPool,
+    collateralVault,
+    escrowLongAccount,
+    premiumVault,
+    makerShortAccount,
+    writerPosition,
+    poolLoan,
+  };
+}
+
+/**
+ * Strikes that still need `init_option_series` before `option_mint_multi`:
+ * the option account is missing OR the maker's writer position has not been
+ * allocated yet (both are created by series init).
+ */
+export async function findLegsNeedingSeriesInit(
+  rpc: KitRpc,
+  legs: OptionSeriesLegAddresses[]
+): Promise<OptionSeriesLegAddresses[]> {
+  if (legs.length === 0) return [];
+  const addresses = legs.flatMap((leg) => [leg.optionAccount, leg.writerPosition]);
+  const response = await rpc
+    .getMultipleAccounts(addresses, { encoding: "base64" })
+    .send();
+  const needing: OptionSeriesLegAddresses[] = [];
+  legs.forEach((leg, i) => {
+    const optionInfo = response.value[i * 2];
+    const writerInfo = response.value[i * 2 + 1];
+    if (!optionInfo || !writerInfo) {
+      needing.push(leg);
+    }
+  });
+  return needing;
+}
+
+export interface BuildInitOptionSeriesParams {
+  underlyingAsset: AddressLike;
+  underlyingMint: AddressLike;
+  collateralMint: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  maker: TransactionSigner<string>;
+  volatilityQuoteAccount: AddressLike;
+  programId?: AddressLike;
+}
+
+/** One `init_option_series` instruction (no oracle quote, no metadata CPIs). */
+export async function buildInitOptionSeriesInstruction(
+  params: BuildInitOptionSeriesParams
+): Promise<Instruction<string>> {
+  return await getInitOptionSeriesInstructionAsync(
+    {
+      volatilityQuoteAccount: toAddress(params.volatilityQuoteAccount),
+      underlyingMint: toAddress(params.underlyingMint),
+      collateralMint: toAddress(params.collateralMint),
+      maker: params.maker,
+      optionType: params.optionType,
+      strikePrice: params.strikePrice,
+      expirationDate: params.expirationDate,
+      underlyingAsset: toAddress(params.underlyingAsset),
+    },
+    { programAddress: params.programId ? toAddress(params.programId) : PROGRAM_ID }
+  );
+}
+
+export interface BuildOptionMintMultiParams {
+  underlyingAsset: AddressLike;
+  underlyingMint: AddressLike;
+  /** Collateral mint shared by every leg (one collateral pool family). */
+  collateralMint: AddressLike;
+  optionType: OptionType;
+  expirationDate: bigint | number;
+  legs: MultiMintLegInput[];
+  maker: TransactionSigner<string>;
+  /** Maker's collateral ATA; derived when omitted. */
+  makerCollateralAccount?: AddressLike;
+  rpc: KitRpc;
+  rpcEndpoint: string;
+  programId?: AddressLike;
+  /** Required when any leg borrows. */
+  vault?: AddressLike;
+  escrowState?: AddressLike;
+  escrowAuthority?: AddressLike;
+  escrowTokenAccount?: AddressLike;
+  /** Legs per transaction (default {@link MAX_MINT_LEGS}, on-chain max 4). */
+  maxLegsPerTransaction?: number;
+  switchboardCrossbarUrl?: string;
+  switchboardNumSignatures?: number;
+  /**
+   * 0-based index of the Switchboard quote ix in the FINAL transaction after
+   * wallet-prepended compute-budget ixs (OPX standard layout: 2).
+   */
+  switchboardQuoteInstructionIndex?: number;
+}
+
+export interface BuiltOptionMintMultiChunk extends BuiltTransaction {
+  /** Legs included in this transaction (same order as the stride bundles). */
+  legs: MultiMintLegInput[];
+  legAddresses: OptionSeriesLegAddresses[];
+}
+
+export interface BuildOptionMintMultiResult {
+  /** One entry per transaction to send sequentially. */
+  chunks: BuiltOptionMintMultiChunk[];
+  /** Per-leg derived addresses (for ALT extension before sending). */
+  legAddresses: OptionSeriesLegAddresses[];
+  /**
+   * Every per-leg address referenced via remaining_accounts — extend the
+   * program lookup table with these before sending so each chunk compresses
+   * under the 1232-byte limit.
+   */
+  lookupAddresses: Address[];
+}
+
+/**
+ * Build `option_mint_multi` transactions for a strike ladder. Every leg's
+ * series must already exist (`init_option_series`); use
+ * {@link findLegsNeedingSeriesInit} + {@link buildInitOptionSeriesInstruction}
+ * first.
+ */
+export async function buildOptionMintMultiTransactionWithDerivation(
+  params: BuildOptionMintMultiParams
+): Promise<BuildOptionMintMultiResult> {
+  invariant(params.legs.length > 0, "at least one leg is required");
+  const maxLegs = params.maxLegsPerTransaction ?? MAX_MINT_LEGS;
+  invariant(maxLegs >= 1 && maxLegs <= 4, "maxLegsPerTransaction must be 1-4");
+
+  const anyBorrow = params.legs.some((leg) => leg.borrowedAmount > 0n);
+  if (anyBorrow) {
+    invariant(!!params.vault, "vault is required when any leg borrows");
+    invariant(!!params.escrowState, "escrowState is required when any leg borrows");
+    invariant(
+      !!params.escrowAuthority,
+      "escrowAuthority is required when any leg borrows"
+    );
+    invariant(
+      !!params.escrowTokenAccount,
+      "escrowTokenAccount is required when any leg borrows"
+    );
+  }
+
+  const programId = params.programId ?? PROGRAM_ID;
+  const [marketData] = await deriveMarketDataPda(params.underlyingAsset, programId);
+  const marketDataAccount = await fetchMarketDataAccount(params.rpc, marketData);
+  invariant(!!marketDataAccount, "Market data account not found for underlying asset.");
+  const volatilityQuoteAccount =
+    deriveVolatilityQuoteAddressFromMarketData(marketDataAccount);
+  const switchboardFeedId = feedIdBytesToHex(
+    Uint8Array.from(marketDataAccount.switchboardFeedId as unknown as Uint8Array)
+  );
+
+  const makerAddress = toAddress(params.maker.address);
+  const makerCollateralAccount = params.makerCollateralAccount
+    ? toAddress(params.makerCollateralAccount)
+    : await deriveAssociatedTokenAddress(makerAddress, params.collateralMint);
+
+  const legAddresses = await Promise.all(
+    params.legs.map((leg) =>
+      deriveOptionSeriesLegAddresses({
+        underlyingAsset: params.underlyingAsset,
+        optionType: params.optionType,
+        strikePrice: leg.strikePrice,
+        expirationDate: params.expirationDate,
+        collateralMint: params.collateralMint,
+        maker: makerAddress,
+        programId,
+      })
+    )
+  );
+
+  const quoteNetwork = await inferSwitchboardNetwork(params.rpc);
+
+  const chunks: BuiltOptionMintMultiChunk[] = [];
+  for (let start = 0; start < params.legs.length; start += maxLegs) {
+    const chunkLegs = params.legs.slice(start, start + maxLegs);
+    const chunkAddresses = legAddresses.slice(start, start + maxLegs);
+
+    const multiIx = await getOptionMintMultiInstructionAsync(
+      {
+        volatilityQuoteAccount: toAddress(volatilityQuoteAccount),
+        underlyingMint: toAddress(params.underlyingMint),
+        collateralMint: toAddress(params.collateralMint),
+        makerCollateralAccount,
+        vault: params.vault ? toAddress(params.vault) : undefined,
+        escrowState: params.escrowState ? toAddress(params.escrowState) : undefined,
+        escrowAuthority: params.escrowAuthority
+          ? toAddress(params.escrowAuthority)
+          : undefined,
+        escrowTokenAccount: params.escrowTokenAccount
+          ? toAddress(params.escrowTokenAccount)
+          : undefined,
+        maker: params.maker,
+        optionType: params.optionType,
+        expirationDate: params.expirationDate,
+        underlyingAsset: toAddress(params.underlyingAsset),
+        legs: chunkLegs.map((leg) => ({
+          strikePrice: leg.strikePrice,
+          quantity: leg.quantity,
+          makerCollateralAmount: leg.makerCollateralAmount,
+          borrowedAmount: leg.borrowedAmount,
+          maxRequiredCollateralAmount: leg.maxRequiredCollateralAmount,
+        })),
+      },
+      { programAddress: toAddress(programId) }
+    );
+
+    const remaining: RemainingAccountInput[] = [
+      { address: SWITCHBOARD_DEFAULT_DEVNET_QUEUE, isWritable: false },
+      { address: SLOT_HASHES_SYSVAR_ADDRESS, isWritable: false },
+      { address: INSTRUCTIONS_SYSVAR_ADDRESS, isWritable: false },
+    ];
+    chunkLegs.forEach((leg, i) => {
+      const addrs = chunkAddresses[i];
+      remaining.push(
+        { address: addrs.optionAccount, isWritable: true },
+        { address: addrs.optionPool, isWritable: true },
+        { address: addrs.collateralPool, isWritable: true },
+        { address: addrs.collateralVault, isWritable: true },
+        { address: addrs.longMint, isWritable: true },
+        { address: addrs.shortMint, isWritable: true },
+        { address: addrs.escrowLongAccount, isWritable: true },
+        { address: addrs.makerShortAccount, isWritable: true },
+        { address: addrs.writerPosition, isWritable: true }
+      );
+      if (leg.borrowedAmount > 0n) {
+        remaining.push({ address: addrs.poolLoan, isWritable: true });
+      }
+    });
+
+    const fullIx = appendRemainingAccounts(multiIx, remaining);
+
+    const quote = await buildSwitchboardQuoteInstruction({
+      rpcEndpoint: params.rpcEndpoint,
+      feedIdHex: switchboardFeedId,
+      network: quoteNetwork,
+      crossbarUrl: params.switchboardCrossbarUrl,
+      numSignatures: params.switchboardNumSignatures,
+      instructionIdx: params.switchboardQuoteInstructionIndex ?? 1,
+    });
+
+    chunks.push({
+      instructions: [quote.instruction, fullIx],
+      legs: chunkLegs,
+      legAddresses: chunkAddresses,
+    });
+  }
+
+  const lookupAddresses = Array.from(
+    new Set(
+      legAddresses.flatMap((addrs) => [
+        addrs.optionAccount,
+        addrs.optionPool,
+        addrs.collateralPool,
+        addrs.collateralVault,
+        addrs.longMint,
+        addrs.shortMint,
+        addrs.escrowLongAccount,
+        addrs.makerShortAccount,
+        addrs.writerPosition,
+        addrs.poolLoan,
+      ])
+    )
+  );
+
+  return { chunks, legAddresses, lookupAddresses };
+}