@epicentral/sos-sdk 0.4.0-alpha.1 → 0.4.0-alpha.2

package/README.md

@@ -47,7 +47,9 @@ Additional modules:
 
 | Function | Description |
 |----------|-------------|
+| `buildBuyFromPoolMarketOrderTransactionWithDerivation` | High-level market-order buy builder (refetches pool + remaining accounts, applies premium cap buffer). |
 | `buildBuyFromPoolTransactionWithDerivation` | Builds buy-from-pool transaction; resolves accounts from option identity. |
+| `preflightBuyFromPoolMarketOrder` | Buy preflight helper for liquidity + remaining-account coverage checks. |
 | `buildCloseLongToPoolTransactionWithDerivation` | Builds close-long-to-pool transaction. |
 | `getBuyFromPoolRemainingAccounts` | Builds remaining_accounts for buy (writer positions, etc.). |
 
@@ -148,16 +150,31 @@ const tx = await buildUnwindWriterUnsoldWithLoanRepayment({
 
 ## Usage Examples
 
-### Buy from pool (with derivation)
+### Buy From Pool (market order, high-level)
 
 ```ts
 import {
-  buildBuyFromPoolTransactionWithDerivation,
-  resolveOptionAccounts,
+  buildBuyFromPoolMarketOrderTransactionWithDerivation,
+  preflightBuyFromPoolMarketOrder,
   OptionType,
 } from "@epicentral/sos-sdk";
 
-const tx = await buildBuyFromPoolTransactionWithDerivation({
+const preflight = await preflightBuyFromPoolMarketOrder({
+  underlyingAsset: "...",
+  optionType: OptionType.Call,
+  strikePrice: 100_000,
+  expirationDate: BigInt(1735689600),
+  quantity: 1_000_000,
+  rpc,
+  quotedPremiumTotal: 50_000,
+  slippageBufferBaseUnits: 500_000n,
+});
+
+if (!preflight.canBuy) {
+  throw new Error(preflight.reason ?? "Buy preflight failed");
+}
+
+const tx = await buildBuyFromPoolMarketOrderTransactionWithDerivation({
   underlyingAsset: "...",
   optionType: OptionType.Call,
   strikePrice: 100_000,
@@ -166,11 +183,30 @@ const tx = await buildBuyFromPoolTransactionWithDerivation({
   buyerPaymentAccount: buyerUsdcAta,
   priceUpdate: pythPriceFeed,
   quantity: 1_000_000,
-  premiumAmount: 50_000,
+  quotedPremiumTotal: 50_000,
+  slippageBufferBaseUnits: 500_000n,
   rpc,
 });
 ```
 
+### Buy premium semantics (market orders)
+
+- `premiumAmount` / `max_premium_amount` is a **max premium cap**, not an exact premium target.
+- Program computes premium on-chain at execution time and fails with `SlippageToleranceExceeded` if computed premium exceeds the cap.
+- High-level market builder computes cap as `quotedPremiumTotal + buffer`:
+  - Canonical: `slippageBufferBaseUnits`
+  - Convenience for SOL/WSOL: `slippageBufferLamports`
+  - Default buffer: `500_000` base units (0.0005 SOL lamports)
+
+### Buy liquidity errors (6041)
+
+- `InsufficientPoolLiquidity` can happen when:
+  - `option_pool.total_available < quantity`, or
+  - remaining writer-position accounts cannot cover full quantity in the smallest-first fill loop.
+- Recommended client flow:
+  1. Run `preflightBuyFromPoolMarketOrder` for UX gating.
+  2. Build via `buildBuyFromPoolMarketOrderTransactionWithDerivation` so pool + remaining accounts are refetched immediately before build.
+
 ### Unwind with loan repayment
 
 ```ts

package/client/lookup-table.ts

@@ -4,7 +4,7 @@ import { PROGRAM_ID } from "./program";
 import type { KitRpc } from "./types";
 
 export const LOOKUP_TABLE_ADDRESSES: Record<"devnet" | "mainnet", Address | null> = {
-  devnet: address("HsoWoDfW4yXVaXE31tEz167cjQn79TeXYxggSrXvRvri"),
+  devnet: address("B7kctbAQDEHT8gJcqRB3Bjkv4EkxMCZecy2H6EQNLQPo"),
   mainnet: null,
 };
 

package/index.ts

@@ -16,6 +16,7 @@ export * from "./shared/transactions";
 
 export * from "./long/builders";
 export * from "./long/exercise";
+export * from "./long/preflight";
 export * from "./long/quotes";
 export {
   getBuyFromPoolRemainingAccounts,

package/long/builders.ts

@@ -10,14 +10,16 @@ import {
   deriveAssociatedTokenAddress,
   deriveBuyerPositionPda,
 } from "../accounts/pdas";
-import { assertPositiveAmount } from "../shared/amounts";
+import { assertNonNegativeAmount, assertPositiveAmount } from "../shared/amounts";
 import { invariant } from "../shared/errors";
 import {
   appendRemainingAccounts,
   type RemainingAccountInput,
 } from "../shared/remaining-accounts";
 import type { OptionType } from "../generated/types";
-import { getCreateAssociatedTokenIdempotentInstructionWithAddress } from "../wsol/instructions";
+import { getCreateAssociatedTokenIdempotentInstructionWithAddress, NATIVE_MINT } from "../wsol/instructions";
+import { fetchOptionPool } from "../accounts/fetchers";
+import { getBuyFromPoolRemainingAccounts } from "./remaining-accounts";
 
 export interface BuildBuyFromPoolParams {
   optionPool: AddressLike;
@@ -127,6 +129,42 @@ export interface BuildBuyFromPoolTransactionWithDerivationParams {
   remainingAccounts?: RemainingAccountInput[];
 }
 
+const DEFAULT_MARKET_ORDER_SLIPPAGE_BUFFER_BASE_UNITS = 500_000n;
+
+interface MarketOrderBufferLikeParams {
+  slippageBufferBaseUnits?: bigint | number;
+  slippageBufferLamports?: bigint | number;
+}
+
+function normalizeMarketOrderSlippageBuffer(
+  params: MarketOrderBufferLikeParams,
+  underlyingMint: AddressLike
+): bigint {
+  const hasBaseUnits = params.slippageBufferBaseUnits !== undefined;
+  const hasLamports = params.slippageBufferLamports !== undefined;
+
+  invariant(
+    !(hasBaseUnits && hasLamports),
+    "Provide only one of slippageBufferBaseUnits or slippageBufferLamports."
+  );
+
+  if (hasBaseUnits) {
+    assertNonNegativeAmount(params.slippageBufferBaseUnits!, "slippageBufferBaseUnits");
+    return BigInt(params.slippageBufferBaseUnits!);
+  }
+
+  if (hasLamports) {
+    assertNonNegativeAmount(params.slippageBufferLamports!, "slippageBufferLamports");
+    invariant(
+      String(toAddress(underlyingMint)) === String(NATIVE_MINT),
+      "slippageBufferLamports is only supported for SOL/WSOL underlyings. Use slippageBufferBaseUnits for other assets."
+    );
+    return BigInt(params.slippageBufferLamports!);
+  }
+
+  return DEFAULT_MARKET_ORDER_SLIPPAGE_BUFFER_BASE_UNITS;
+}
+
 export async function buildBuyFromPoolTransactionWithDerivation(
   params: BuildBuyFromPoolTransactionWithDerivationParams
 ): Promise<BuiltTransaction> {
@@ -178,6 +216,82 @@ export async function buildBuyFromPoolTransactionWithDerivation(
   });
 }
 
+export interface BuildBuyFromPoolMarketOrderParams
+  extends Omit<
+      BuildBuyFromPoolTransactionWithDerivationParams,
+      "premiumAmount" | "remainingAccounts"
+    >,
+    MarketOrderBufferLikeParams {
+  quotedPremiumTotal: bigint | number;
+}
+
+/**
+ * High-level market-order buy builder.
+ * Refetches option pool and remaining writer-position accounts right before
+ * build and sets max premium = quotedPremiumTotal + slippage buffer.
+ */
+export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
+  params: BuildBuyFromPoolMarketOrderParams
+): Promise<BuiltTransaction> {
+  assertPositiveAmount(params.quantity, "quantity");
+  assertPositiveAmount(params.quotedPremiumTotal, "quotedPremiumTotal");
+
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const [refetchedPool, remainingAccounts, buyerPosition, buyerOptionAccount] =
+    await Promise.all([
+      fetchOptionPool(params.rpc, resolved.optionPool),
+      getBuyFromPoolRemainingAccounts(params.rpc, resolved.optionPool, params.programId),
+      params.buyerPosition
+        ? Promise.resolve(params.buyerPosition)
+        : deriveBuyerPositionPda(
+            params.buyer,
+            resolved.optionAccount,
+            params.programId
+          ).then(([addr]) => addr),
+      params.buyerOptionAccount
+        ? Promise.resolve(params.buyerOptionAccount)
+        : deriveAssociatedTokenAddress(params.buyer, resolved.longMint),
+    ]);
+
+  invariant(
+    !!refetchedPool,
+    "Option pool must exist; ensure rpc is provided and pool is initialized."
+  );
+
+  const slippageBuffer = normalizeMarketOrderSlippageBuffer(
+    params,
+    refetchedPool.underlyingMint
+  );
+  const maxPremiumAmount = BigInt(params.quotedPremiumTotal) + slippageBuffer;
+  assertPositiveAmount(maxPremiumAmount, "maxPremiumAmount");
+
+  return buildBuyFromPoolTransaction({
+    optionPool: resolved.optionPool,
+    optionAccount: resolved.optionAccount,
+    longMint: resolved.longMint,
+    underlyingMint: refetchedPool.underlyingMint,
+    marketData: resolved.marketData,
+    priceUpdate: params.priceUpdate,
+    buyer: params.buyer,
+    buyerPaymentAccount: params.buyerPaymentAccount,
+    escrowLongAccount: refetchedPool.escrowLongAccount,
+    premiumVault: refetchedPool.premiumVault,
+    quantity: params.quantity,
+    premiumAmount: maxPremiumAmount,
+    buyerPosition,
+    buyerOptionAccount,
+    remainingAccounts,
+  });
+}
+
 export async function buildCloseLongToPoolInstruction(
   params: BuildCloseLongToPoolParams
 ): Promise<Instruction<string>> {

package/long/preflight.ts

@@ -0,0 +1,114 @@
+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."
+  );
+
+  const availableWriterPositions = writerPositions.filter(
+    ({ data }) => toBigInt(data.unsoldQty) > 0n
+  );
+  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;
+}

package/package.json

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