@epicentral/sos-sdk 0.9.0-beta

package/long/exercise.ts

@@ -0,0 +1,123 @@
+import { getOptionExerciseInstruction } from "../generated/instructions";
+import type { Instruction } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction, KitRpc } from "../client/types";
+import { fetchMarketDataAccount } from "../accounts/fetchers";
+import { invariant } from "../shared/errors";
+import {
+  buildSwitchboardQuoteInstruction,
+  feedIdBytesToHex,
+  getDefaultSwitchboardQueueAddress,
+  inferSwitchboardNetwork,
+  prependSwitchboardQuote,
+} from "../oracle/switchboard";
+
+export interface BuildOptionExerciseParams {
+  optionAccount: AddressLike;
+  positionAccount: AddressLike;
+  marketData: AddressLike;
+  underlyingMint: AddressLike;
+  /** Switchboard queue account (defaults when `disableSwitchboardCrank` + `rpc`). */
+  switchboardQueue?: AddressLike;
+  buyerPaymentAccount: AddressLike;
+  makerCollateralAccount: AddressLike;
+  escrowState: AddressLike;
+  escrowTokenAccount: AddressLike;
+  escrowAuthority: AddressLike;
+  buyer: AddressLike;
+  tokenProgram?: AddressLike;
+  rpc?: KitRpc;
+  /** HTTP RPC URL — required to fetch Switchboard quote ix unless `disableSwitchboardCrank`. */
+  rpcEndpoint?: string;
+  disableSwitchboardCrank?: boolean;
+  switchboardCrossbarUrl?: string;
+  switchboardNumSignatures?: number;
+  /**
+   * 0-based index of the quote ix after wallet prepends. OPX `sendInstructions` (limit + price) → **2** by default.
+   */
+  switchboardQuoteInstructionIndex?: number;
+}
+
+/**
+ * Legacy escrow-based option exercise. Prefer pool flows: close_long_to_pool and auto_exercise_expired.
+ * @deprecated Use buildCloseLongToPoolTransaction for closing longs and rely on auto_exercise_expired for expiration.
+ */
+export function buildOptionExerciseInstruction(
+  params: BuildOptionExerciseParams
+): Instruction<string> {
+  invariant(
+    !!params.switchboardQueue,
+    "switchboardQueue is required to build option exercise instruction."
+  );
+  return getOptionExerciseInstruction({
+    optionAccount: toAddress(params.optionAccount),
+    positionAccount: toAddress(params.positionAccount),
+    marketData: toAddress(params.marketData),
+    underlyingMint: toAddress(params.underlyingMint),
+    switchboardQueue: toAddress(params.switchboardQueue),
+    buyerPaymentAccount: toAddress(params.buyerPaymentAccount),
+    makerCollateralAccount: toAddress(params.makerCollateralAccount),
+    escrowState: toAddress(params.escrowState),
+    escrowTokenAccount: toAddress(params.escrowTokenAccount),
+    escrowAuthority: toAddress(params.escrowAuthority),
+    buyer: toAddress(params.buyer) as any,
+    tokenProgram: params.tokenProgram ? toAddress(params.tokenProgram) : undefined,
+  });
+}
+
+/**
+ * Builds an option exercise transaction (escrow/ask-based flow).
+ * Prefer pool-based flows: buildCloseLongToPoolTransaction for closing longs and auto_exercise_expired for expired ITM.
+ * @deprecated Use buildCloseLongToPoolTransaction and auto_exercise_expired; do not use for new flows.
+ */
+export async function buildOptionExerciseTransaction(
+  params: BuildOptionExerciseParams
+): Promise<BuiltTransaction> {
+  if (params.disableSwitchboardCrank === true) {
+    const switchboardQueue = params.switchboardQueue
+      ? toAddress(params.switchboardQueue)
+      : params.rpc
+        ? getDefaultSwitchboardQueueAddress(await inferSwitchboardNetwork(params.rpc))
+        : undefined;
+    invariant(
+      !!switchboardQueue,
+      "switchboardQueue or rpc is required when disableSwitchboardCrank is set."
+    );
+    const instruction = buildOptionExerciseInstruction({
+      ...params,
+      switchboardQueue,
+    });
+    return { instructions: [instruction] };
+  }
+
+  invariant(
+    !!params.rpc && !!params.rpcEndpoint,
+    "rpc and rpcEndpoint are required to prepend Switchboard quote (or set disableSwitchboardCrank)."
+  );
+
+  const marketDataAccount = await fetchMarketDataAccount(
+    params.rpc,
+    params.marketData
+  );
+  invariant(!!marketDataAccount, "Market data account not found.");
+  const feedIdHex = feedIdBytesToHex(
+    Uint8Array.from(marketDataAccount.switchboardFeedId as unknown as Uint8Array)
+  );
+  const network = await inferSwitchboardNetwork(params.rpc);
+
+  const quote = await buildSwitchboardQuoteInstruction({
+    rpcEndpoint: params.rpcEndpoint,
+    feedIdHex,
+    network,
+    crossbarUrl: params.switchboardCrossbarUrl,
+    numSignatures: params.switchboardNumSignatures,
+    instructionIdx: params.switchboardQuoteInstructionIndex ?? 2,
+  });
+
+  const instruction = buildOptionExerciseInstruction({
+    ...params,
+    switchboardQueue: getDefaultSwitchboardQueueAddress(network),
+  });
+
+  return prependSwitchboardQuote(quote, { instructions: [instruction] });
+}

package/long/preflight.ts

@@ -0,0 +1,214 @@
+import type { AddressLike, KitRpc } from "../client/types";
+import type { OptionType } from "../generated/types";
+import { fetchWriterPositionsForPool } from "../accounts/list";
+import { resolveOptionAccounts } from "../accounts/resolve-option";
+import { fetchOptionPool } from "../accounts/fetchers";
+import { assertNonNegativeAmount, assertPositiveAmount } from "../shared/amounts";
+import { invariant } from "../shared/errors";
+
+function toBigInt(value: bigint | number): bigint {
+  return typeof value === "bigint" ? value : BigInt(value);
+}
+
+export interface PreflightBuyFromPoolMarketOrderParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  quantity: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+  quotedPremiumTotal?: bigint | number;
+  slippageBufferBaseUnits?: bigint | number;
+}
+
+export interface BuyFromPoolMarketOrderPremiumSummary {
+  quotedPremiumTotal: bigint;
+  slippageBufferBaseUnits: bigint;
+  maxPremiumAmount: bigint;
+}
+
+export interface PreflightBuyFromPoolMarketOrderResult {
+  canBuy: boolean;
+  reason?: string;
+  poolTotalAvailable: bigint;
+  requestedQuantity: bigint;
+  remainingAccountsCount: number;
+  remainingUnsoldAggregate: bigint;
+  premium?: BuyFromPoolMarketOrderPremiumSummary;
+}
+
+export async function preflightBuyFromPoolMarketOrder(
+  params: PreflightBuyFromPoolMarketOrderParams
+): Promise<PreflightBuyFromPoolMarketOrderResult> {
+  assertPositiveAmount(params.quantity, "quantity");
+  const requestedQuantity = toBigInt(params.quantity);
+
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const [optionPool, writerPositions] = await Promise.all([
+    fetchOptionPool(params.rpc, resolved.optionPool),
+    fetchWriterPositionsForPool(params.rpc, resolved.optionPool, params.programId),
+  ]);
+
+  invariant(
+    !!optionPool,
+    "Option pool must exist; ensure rpc is provided and pool is initialized."
+  );
+
+  // Filter out inactive positions (settled, liquidated, or zero unsold)
+  const activeWriterPositions = writerPositions.filter(
+    ({ data }) => !data.isSettled && !data.isLiquidated && toBigInt(data.unsoldQty) > 0n
+  );
+
+  // Use active positions for coverage calculation
+  const availableWriterPositions = activeWriterPositions;
+  const remainingUnsoldAggregate = availableWriterPositions.reduce(
+    (acc, { data }) => acc + toBigInt(data.unsoldQty),
+    0n
+  );
+  const poolTotalAvailable = toBigInt(optionPool.totalAvailable);
+
+  const hasPoolLiquidity = poolTotalAvailable >= requestedQuantity;
+  const hasWriterCoverage = remainingUnsoldAggregate >= requestedQuantity;
+
+  let reason: string | undefined;
+  if (!hasPoolLiquidity) {
+    reason = "Pool total_available is less than requested quantity.";
+  } else if (!hasWriterCoverage) {
+    reason =
+      "Remaining writer-position liquidity is insufficient to fully fill requested quantity.";
+  }
+
+  const result: PreflightBuyFromPoolMarketOrderResult = {
+    canBuy: hasPoolLiquidity && hasWriterCoverage,
+    reason,
+    poolTotalAvailable,
+    requestedQuantity,
+    remainingAccountsCount: availableWriterPositions.length,
+    remainingUnsoldAggregate,
+  };
+
+  if (params.quotedPremiumTotal !== undefined) {
+    assertPositiveAmount(params.quotedPremiumTotal, "quotedPremiumTotal");
+    if (params.slippageBufferBaseUnits !== undefined) {
+      assertNonNegativeAmount(params.slippageBufferBaseUnits, "slippageBufferBaseUnits");
+    }
+    const quotedPremiumTotal = toBigInt(params.quotedPremiumTotal);
+    const slippageBufferBaseUnits =
+      params.slippageBufferBaseUnits !== undefined
+        ? toBigInt(params.slippageBufferBaseUnits)
+        : 0n;
+
+    result.premium = {
+      quotedPremiumTotal,
+      slippageBufferBaseUnits,
+      maxPremiumAmount: quotedPremiumTotal + slippageBufferBaseUnits,
+    };
+  }
+
+  return result;
+}
+
+export interface PreflightCloseLongToPoolParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  quantity: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+}
+
+export interface PreflightCloseLongToPoolResult {
+  /**
+   * Safe to submit the close-long transaction. When `false`, inspect `reason`.
+   * Note: the buyer's own balance (`buyer_position.quantity >= requested`) is
+   * enforced on-chain and not rechecked here.
+   */
+  canClose: boolean;
+  reason?: string;
+  requestedQuantity: bigint;
+  /** `OptionPool.total_sold_qty` at preflight time. */
+  poolTotalSoldQty: bigint;
+  /**
+   * Sum of `sold_qty` across active WriterPositions returned by
+   * `getCloseLongToPoolRemainingAccounts`. Must equal `poolTotalSoldQty` for the
+   * on-chain Hamilton completeness check to pass.
+   */
+  activeWriterSoldSum: bigint;
+  /** Number of WriterPosition accounts the SDK will pass as remaining_accounts. */
+  remainingAccountsCount: number;
+}
+
+export async function preflightCloseLongToPool(
+  params: PreflightCloseLongToPoolParams
+): Promise<PreflightCloseLongToPoolResult> {
+  assertPositiveAmount(params.quantity, "quantity");
+  const requestedQuantity = toBigInt(params.quantity);
+
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const [optionPool, writerPositions] = await Promise.all([
+    fetchOptionPool(params.rpc, resolved.optionPool),
+    fetchWriterPositionsForPool(params.rpc, resolved.optionPool, params.programId),
+  ]);
+
+  invariant(
+    !!optionPool,
+    "Option pool must exist; ensure rpc is provided and pool is initialized."
+  );
+
+  const active = writerPositions.filter(
+    ({ data }) => !data.isSettled && !data.isLiquidated
+  );
+  const activeWriterSoldSum = active.reduce(
+    (acc, { data }) => acc + toBigInt(data.soldQty),
+    0n
+  );
+  const poolTotalSoldQty = toBigInt(optionPool.totalSoldQty);
+
+  const hasInventory = poolTotalSoldQty > 0n;
+  const hasWriters = active.length > 0;
+  const sumMatches = activeWriterSoldSum === poolTotalSoldQty;
+  const hasCapacity = requestedQuantity <= poolTotalSoldQty;
+
+  let reason: string | undefined;
+  if (!hasInventory) {
+    reason =
+      "Pool has no sold inventory to close against (total_sold_qty is zero).";
+  } else if (!hasWriters) {
+    reason =
+      "Pool reports sold inventory but no active WriterPositions were returned by RPC (data staleness?).";
+  } else if (!sumMatches) {
+    reason =
+      `Active WriterPosition sold_qty sum (${activeWriterSoldSum}) does not match OptionPool.total_sold_qty (${poolTotalSoldQty}). ` +
+      `Refetch and retry; a new mint or close may have just landed.`;
+  } else if (!hasCapacity) {
+    reason =
+      `Requested close quantity (${requestedQuantity}) exceeds pool sold inventory (${poolTotalSoldQty}).`;
+  }
+
+  return {
+    canClose: hasInventory && hasWriters && sumMatches && hasCapacity,
+    reason,
+    requestedQuantity,
+    poolTotalSoldQty,
+    activeWriterSoldSum,
+    remainingAccountsCount: active.length,
+  };
+}

package/long/quotes.ts

@@ -0,0 +1,48 @@
+import { assertPositiveAmount } from "../shared/amounts";
+import { SdkValidationError } from "../shared/errors";
+
+export function applySlippageBps(amount: bigint | number, slippageBps: number): bigint {
+  if (slippageBps < 0) {
+    throw new SdkValidationError("slippageBps cannot be negative.");
+  }
+
+  const base = BigInt(amount);
+  return (base * BigInt(10_000 + slippageBps)) / 10_000n;
+}
+
+export function applyMinSlippageBps(amount: bigint | number, slippageBps: number): bigint {
+  if (slippageBps < 0) {
+    throw new SdkValidationError("slippageBps cannot be negative.");
+  }
+
+  const base = BigInt(amount);
+  return (base * BigInt(10_000 - slippageBps)) / 10_000n;
+}
+
+export function buildBuyQuote(params: {
+  quantity: bigint | number;
+  premiumPerContract: bigint | number;
+  maxSlippageBps: number;
+}): { expectedPremium: bigint; maxPremium: bigint } {
+  assertPositiveAmount(params.quantity, "quantity");
+  assertPositiveAmount(params.premiumPerContract, "premiumPerContract");
+
+  const expectedPremium = BigInt(params.quantity) * BigInt(params.premiumPerContract);
+  return {
+    expectedPremium,
+    maxPremium: applySlippageBps(expectedPremium, params.maxSlippageBps),
+  };
+}
+
+export function buildCloseQuote(params: {
+  expectedPayout: bigint | number;
+  maxSlippageBps: number;
+}): { expectedPayout: bigint; minPayout: bigint } {
+  assertPositiveAmount(params.expectedPayout, "expectedPayout");
+
+  const expectedPayout = BigInt(params.expectedPayout);
+  return {
+    expectedPayout,
+    minPayout: applyMinSlippageBps(expectedPayout, params.maxSlippageBps),
+  };
+}

package/long/remaining-accounts.ts

@@ -0,0 +1,111 @@
+import bs58 from "bs58";
+import type { RemainingAccountInput } from "../shared/remaining-accounts";
+import type { AddressLike, KitRpc } from "../client/types";
+import { PROGRAM_ID } from "../client/program";
+import { fetchWriterPositionsForPool } from "../accounts/list";
+
+/**
+ * Byte-wise comparison of two base58-encoded pubkeys. Matches the on-chain
+ * `Pubkey::cmp` ordering over the 32-byte buffer — base58 string compare is
+ * NOT equivalent because the encoded strings can have different lengths.
+ */
+function comparePubkeyBytes(a: string, b: string): number {
+  const ab = bs58.decode(a);
+  const bb = bs58.decode(b);
+  const len = Math.min(ab.length, bb.length);
+  for (let i = 0; i < len; i++) {
+    if (ab[i]! !== bb[i]!) return ab[i]! - bb[i]!;
+  }
+  return ab.length - bb.length;
+}
+
+/**
+ * FIFO ordering used by both `buy_from_pool` verification and the
+ * `close_long_to_pool` Hamilton redistribution: primary key `createdAt`
+ * ascending, tiebreaker pubkey bytes ascending. MUST stay in sync with the
+ * on-chain comparator in `option-program/programs/option-program/src/pool.rs`.
+ */
+function compareByCreatedAtThenPubkey(
+  a: { createdAt: bigint; address: string },
+  b: { createdAt: bigint; address: string }
+): number {
+  if (a.createdAt < b.createdAt) return -1;
+  if (a.createdAt > b.createdAt) return 1;
+  return comparePubkeyBytes(a.address, b.address);
+}
+
+/**
+ * Returns remaining_accounts for the `buy_from_pool` instruction: active
+ * WriterPositions for the given pool, sorted by (`createdAt` asc, `pubkey` asc).
+ *
+ * The on-chain program verifies this ordering and rejects unsorted lists with
+ * `BuyRemainingAccountsUnsorted`. Positions with no unsold inventory cannot fill
+ * any buy and are excluded.
+ */
+export async function getBuyFromPoolRemainingAccounts(
+  rpc: KitRpc,
+  optionPool: AddressLike,
+  programId?: AddressLike
+): Promise<RemainingAccountInput[]> {
+  const positions = await fetchWriterPositionsForPool(
+    rpc,
+    optionPool,
+    programId ?? PROGRAM_ID
+  );
+
+  const active = positions.filter(
+    (p) =>
+      !p.data.isSettled &&
+      !p.data.isLiquidated &&
+      BigInt(p.data.unsoldQty) > 0n
+  );
+
+  const sorted = [...active].sort((a, b) =>
+    compareByCreatedAtThenPubkey(
+      { createdAt: BigInt(a.data.createdAt), address: String(a.address) },
+      { createdAt: BigInt(b.data.createdAt), address: String(b.address) }
+    )
+  );
+  return sorted.map(({ address }) => ({
+    address,
+    isWritable: true,
+  }));
+}
+
+/**
+ * Returns remaining_accounts for the `close_long_to_pool` instruction: **every
+ * active WriterPosition** for the given pool (sum of `sold_qty` must equal
+ * `OptionPool.total_sold_qty`). The on-chain Hamilton redistribution enforces a
+ * strict completeness check via `CloseLongWritersIncomplete` and fails if the
+ * caller skips any active writer.
+ *
+ * Ordering does not affect correctness on-chain (the Hamilton allocator sorts
+ * remainders itself), but we preserve the same FIFO order used by `buy_from_pool`
+ * so logs and simulations are deterministic.
+ */
+export async function getCloseLongToPoolRemainingAccounts(
+  rpc: KitRpc,
+  optionPool: AddressLike,
+  programId?: AddressLike
+): Promise<RemainingAccountInput[]> {
+  const positions = await fetchWriterPositionsForPool(
+    rpc,
+    optionPool,
+    programId ?? PROGRAM_ID
+  );
+
+  const active = positions.filter(
+    (p) => !p.data.isSettled && !p.data.isLiquidated
+  );
+
+  const sorted = [...active].sort((a, b) =>
+    compareByCreatedAtThenPubkey(
+      { createdAt: BigInt(a.data.createdAt), address: String(a.address) },
+      { createdAt: BigInt(b.data.createdAt), address: String(b.address) }
+    )
+  );
+  return sorted.map(({ address }) => ({
+    address,
+    isWritable: true,
+  }));
+}

package/omlp/builders.ts

@@ -0,0 +1,94 @@
+import {
+  getDepositToPositionInstructionAsync,
+  getWithdrawFromPositionInstructionAsync,
+} from "../generated/instructions";
+import type { Instruction } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction } from "../client/types";
+import { assertPositiveAmount } from "../shared/amounts";
+import { getCloseAccountInstruction, NATIVE_MINT } from "../wsol/instructions";
+
+export interface BuildDepositToPositionParams {
+  vault: AddressLike;
+  lenderTokenAccount: AddressLike;
+  vaultTokenAccount: AddressLike;
+  lender: AddressLike;
+  amount: bigint | number;
+  position?: AddressLike;
+}
+
+export interface BuildWithdrawFromPositionParams {
+  vault: AddressLike;
+  vaultTokenAccount: AddressLike;
+  lenderTokenAccount: AddressLike;
+  lender: AddressLike;
+  amount: bigint | number;
+  position?: AddressLike;
+  unwrapSol?: boolean;
+  vaultMint?: AddressLike;
+}
+
+export async function buildDepositToPositionInstruction(
+  params: BuildDepositToPositionParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.amount, "amount");
+
+  const kitInstruction = await getDepositToPositionInstructionAsync({
+    position: params.position ? toAddress(params.position) : undefined,
+    vault: toAddress(params.vault),
+    lenderTokenAccount: toAddress(params.lenderTokenAccount),
+    vaultTokenAccount: toAddress(params.vaultTokenAccount),
+    lender: toAddress(params.lender) as any,
+    amount: params.amount,
+  });
+
+  return kitInstruction;
+}
+
+export async function buildDepositToPositionTransaction(
+  params: BuildDepositToPositionParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildDepositToPositionInstruction(params);
+  return { instructions: [instruction] };
+}
+
+export async function buildWithdrawFromPositionInstruction(
+  params: BuildWithdrawFromPositionParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.amount, "amount");
+
+  const kitInstruction = await getWithdrawFromPositionInstructionAsync({
+    position: params.position ? toAddress(params.position) : undefined,
+    vault: toAddress(params.vault),
+    vaultTokenAccount: toAddress(params.vaultTokenAccount),
+    lenderTokenAccount: toAddress(params.lenderTokenAccount),
+    lender: toAddress(params.lender) as any,
+    amount: params.amount,
+  });
+
+  return kitInstruction;
+}
+
+export async function buildWithdrawFromPositionTransaction(
+  params: BuildWithdrawFromPositionParams
+): Promise<BuiltTransaction> {
+  const withdrawInstruction = await buildWithdrawFromPositionInstruction(params);
+  const instructions: Instruction<string>[] = [withdrawInstruction];
+
+  const shouldUnwrapSol =
+    params.unwrapSol === true &&
+    params.vaultMint !== undefined &&
+    toAddress(params.vaultMint) === toAddress(NATIVE_MINT);
+
+  if (shouldUnwrapSol) {
+    instructions.push(
+      getCloseAccountInstruction(
+        params.lenderTokenAccount,
+        params.lender,
+        params.lender
+      )
+    );
+  }
+
+  return { instructions };
+}