@epicentral/sos-sdk 0.12.0-beta → 0.12.2-beta

package/README.md

@@ -442,7 +442,8 @@ const tx = await buildBuyFromPoolMarketOrderTransactionWithDerivation({
 
 ### Buy premium semantics (market orders)
 
-- Premium is paid in the **option pool underlying** token; `buyer_payment_account` must match that mint (see program `buy_from_pool`).
+- Premium is paid in **`premium_vault.mint`** (on-chain source of truth). For **new** pools: underlying when physical (`collateral == underlying`), collateral mint when cash (e.g. USDC). **Legacy** cash pools may still use SOL premium vault — resolve mint from chain before building `buyer_payment_account`.
+- `buyer_payment_account.mint` must match `premium_vault.mint`; pass `payment_mint` to `buy_from_pool`.
 - `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`:

package/generated/instructions/buyFromPool.ts

@@ -65,6 +65,7 @@ export type BuyFromPoolInstruction<
     "Sysvar1nstructions1111111111111111111111111",
   TAccountBuyerPosition extends string | AccountMeta<string> = string,
   TAccountBuyerOptionAccount extends string | AccountMeta<string> = string,
+  TAccountPaymentMint extends string | AccountMeta<string> = string,
   TAccountBuyerPaymentAccount extends string | AccountMeta<string> = string,
   TAccountEscrowLongAccount extends string | AccountMeta<string> = string,
   TAccountPremiumVault extends string | AccountMeta<string> = string,
@@ -111,6 +112,9 @@ export type BuyFromPoolInstruction<
       TAccountBuyerOptionAccount extends string
         ? WritableAccount<TAccountBuyerOptionAccount>
         : TAccountBuyerOptionAccount,
+      TAccountPaymentMint extends string
+        ? ReadonlyAccount<TAccountPaymentMint>
+        : TAccountPaymentMint,
       TAccountBuyerPaymentAccount extends string
         ? WritableAccount<TAccountBuyerPaymentAccount>
         : TAccountBuyerPaymentAccount,
@@ -191,6 +195,7 @@ export type BuyFromPoolAsyncInput<
   TAccountInstructionsSysvar extends string = string,
   TAccountBuyerPosition extends string = string,
   TAccountBuyerOptionAccount extends string = string,
+  TAccountPaymentMint extends string = string,
   TAccountBuyerPaymentAccount extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
@@ -220,6 +225,8 @@ export type BuyFromPoolAsyncInput<
   buyerPosition?: Address<TAccountBuyerPosition>;
   /** Buyer's LONG token account (receives LONG tokens) */
   buyerOptionAccount?: Address<TAccountBuyerOptionAccount>;
+  /** Premium payment mint (must match premium_vault.mint on-chain) */
+  paymentMint: Address<TAccountPaymentMint>;
   /** Buyer's payment account (source of premium) */
   buyerPaymentAccount: Address<TAccountBuyerPaymentAccount>;
   /** Pool's LONG escrow (source of LONG tokens) */
@@ -247,6 +254,7 @@ export async function getBuyFromPoolInstructionAsync<
   TAccountInstructionsSysvar extends string,
   TAccountBuyerPosition extends string,
   TAccountBuyerOptionAccount extends string,
+  TAccountPaymentMint extends string,
   TAccountBuyerPaymentAccount extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
@@ -268,6 +276,7 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -291,6 +300,7 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -329,6 +339,7 @@ export async function getBuyFromPoolInstructionAsync<
       value: input.buyerOptionAccount ?? null,
       isWritable: true,
     },
+    paymentMint: { value: input.paymentMint ?? null, isWritable: false },
     buyerPaymentAccount: {
       value: input.buyerPaymentAccount ?? null,
       isWritable: true,
@@ -433,6 +444,7 @@ export async function getBuyFromPoolInstructionAsync<
       getAccountMeta(accounts.instructionsSysvar),
       getAccountMeta(accounts.buyerPosition),
       getAccountMeta(accounts.buyerOptionAccount),
+      getAccountMeta(accounts.paymentMint),
       getAccountMeta(accounts.buyerPaymentAccount),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
@@ -458,6 +470,7 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -480,6 +493,7 @@ export type BuyFromPoolInput<
   TAccountInstructionsSysvar extends string = string,
   TAccountBuyerPosition extends string = string,
   TAccountBuyerOptionAccount extends string = string,
+  TAccountPaymentMint extends string = string,
   TAccountBuyerPaymentAccount extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
@@ -509,6 +523,8 @@ export type BuyFromPoolInput<
   buyerPosition: Address<TAccountBuyerPosition>;
   /** Buyer's LONG token account (receives LONG tokens) */
   buyerOptionAccount: Address<TAccountBuyerOptionAccount>;
+  /** Premium payment mint (must match premium_vault.mint on-chain) */
+  paymentMint: Address<TAccountPaymentMint>;
   /** Buyer's payment account (source of premium) */
   buyerPaymentAccount: Address<TAccountBuyerPaymentAccount>;
   /** Pool's LONG escrow (source of LONG tokens) */
@@ -536,6 +552,7 @@ export function getBuyFromPoolInstruction<
   TAccountInstructionsSysvar extends string,
   TAccountBuyerPosition extends string,
   TAccountBuyerOptionAccount extends string,
+  TAccountPaymentMint extends string,
   TAccountBuyerPaymentAccount extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
@@ -557,6 +574,7 @@ export function getBuyFromPoolInstruction<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -579,6 +597,7 @@ export function getBuyFromPoolInstruction<
   TAccountInstructionsSysvar,
   TAccountBuyerPosition,
   TAccountBuyerOptionAccount,
+  TAccountPaymentMint,
   TAccountBuyerPaymentAccount,
   TAccountEscrowLongAccount,
   TAccountPremiumVault,
@@ -616,6 +635,7 @@ export function getBuyFromPoolInstruction<
       value: input.buyerOptionAccount ?? null,
       isWritable: true,
     },
+    paymentMint: { value: input.paymentMint ?? null, isWritable: false },
     buyerPaymentAccount: {
       value: input.buyerPaymentAccount ?? null,
       isWritable: true,
@@ -677,6 +697,7 @@ export function getBuyFromPoolInstruction<
       getAccountMeta(accounts.instructionsSysvar),
       getAccountMeta(accounts.buyerPosition),
       getAccountMeta(accounts.buyerOptionAccount),
+      getAccountMeta(accounts.paymentMint),
       getAccountMeta(accounts.buyerPaymentAccount),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
@@ -702,6 +723,7 @@ export function getBuyFromPoolInstruction<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -739,18 +761,20 @@ export type ParsedBuyFromPoolInstruction<
     buyerPosition: TAccountMetas[8];
     /** Buyer's LONG token account (receives LONG tokens) */
     buyerOptionAccount: TAccountMetas[9];
+    /** Premium payment mint (must match premium_vault.mint on-chain) */
+    paymentMint: TAccountMetas[10];
     /** Buyer's payment account (source of premium) */
-    buyerPaymentAccount: TAccountMetas[10];
+    buyerPaymentAccount: TAccountMetas[11];
     /** Pool's LONG escrow (source of LONG tokens) */
-    escrowLongAccount: TAccountMetas[11];
+    escrowLongAccount: TAccountMetas[12];
     /** Pool's premium vault (receives premium) */
-    premiumVault: TAccountMetas[12];
+    premiumVault: TAccountMetas[13];
     /** Collateral pool (settlement mint for buyer position tracking) */
-    collateralPool: TAccountMetas[13];
-    buyer: TAccountMetas[14];
-    tokenProgram: TAccountMetas[15];
-    associatedTokenProgram: TAccountMetas[16];
-    systemProgram: TAccountMetas[17];
+    collateralPool: TAccountMetas[14];
+    buyer: TAccountMetas[15];
+    tokenProgram: TAccountMetas[16];
+    associatedTokenProgram: TAccountMetas[17];
+    systemProgram: TAccountMetas[18];
   };
   data: BuyFromPoolInstructionData;
 };
@@ -763,7 +787,7 @@ export function parseBuyFromPoolInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedBuyFromPoolInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 18) {
+  if (instruction.accounts.length < 19) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -786,6 +810,7 @@ export function parseBuyFromPoolInstruction<
       instructionsSysvar: getNextAccount(),
       buyerPosition: getNextAccount(),
       buyerOptionAccount: getNextAccount(),
+      paymentMint: getNextAccount(),
       buyerPaymentAccount: getNextAccount(),
       escrowLongAccount: getNextAccount(),
       premiumVault: getNextAccount(),

package/generated/instructions/optionMint.ts

@@ -350,7 +350,7 @@ export type OptionMintAsyncInput<
   optionPool?: Address<TAccountOptionPool>;
   /** Pool's escrow for holding LONG tokens (for buyers to purchase) */
   escrowLongAccount?: Address<TAccountEscrowLongAccount>;
-  /** Pool's vault for collecting premiums (in underlying asset) */
+  /** Pool vault for premiums (underlying when physical, collateral mint for cash) */
   premiumVault?: Address<TAccountPremiumVault>;
   /** Collateral pool for this option */
   collateralPool?: Address<TAccountCollateralPool>;
@@ -707,7 +707,7 @@ export async function getOptionMintInstructionAsync<
           ]),
         ),
         getAddressEncoder().encode(
-          expectAddress(accounts.underlyingMint.value),
+          expectAddress(accounts.collateralMint.value),
         ),
       ],
     });
@@ -924,7 +924,7 @@ export type OptionMintInput<
   optionPool: Address<TAccountOptionPool>;
   /** Pool's escrow for holding LONG tokens (for buyers to purchase) */
   escrowLongAccount: Address<TAccountEscrowLongAccount>;
-  /** Pool's vault for collecting premiums (in underlying asset) */
+  /** Pool vault for premiums (underlying when physical, collateral mint for cash) */
   premiumVault: Address<TAccountPremiumVault>;
   /** Collateral pool for this option */
   collateralPool: Address<TAccountCollateralPool>;
@@ -1278,7 +1278,7 @@ export type ParsedOptionMintInstruction<
     optionPool: TAccountMetas[11];
     /** Pool's escrow for holding LONG tokens (for buyers to purchase) */
     escrowLongAccount: TAccountMetas[12];
-    /** Pool's vault for collecting premiums (in underlying asset) */
+    /** Pool vault for premiums (underlying when physical, collateral mint for cash) */
     premiumVault: TAccountMetas[13];
     /** Collateral pool for this option */
     collateralPool: TAccountMetas[14];

package/long/builders.ts

@@ -10,7 +10,8 @@ import {
   deriveAssociatedTokenAddress,
   deriveBuyerPositionPda,
 } from "../accounts/pdas";
-import { assertNonNegativeAmount, assertPositiveAmount } from "../shared/amounts";
+import { assertNonNegativeAmount, assertPositiveAmount, getPremiumMint } from "../shared/amounts";
+import { fetchTokenAccountMint } from "../shared/balances";
 import { invariant } from "../shared/errors";
 import {
   appendRemainingAccounts,
@@ -47,6 +48,8 @@ export interface BuildBuyFromPoolParams {
   /** Program `switchboard_queue` — use {@link getDefaultSwitchboardQueueAddress} for the cluster. */
   switchboardQueue: AddressLike;
   buyer: AddressLike;
+  /** Premium payment mint — must match on-chain premium_vault.mint. */
+  paymentMint: AddressLike;
   buyerPaymentAccount: AddressLike;
   escrowLongAccount: AddressLike;
   premiumVault: AddressLike;
@@ -57,6 +60,29 @@ export interface BuildBuyFromPoolParams {
   remainingAccounts?: RemainingAccountInput[];
 }
 
+async function resolveBuyPaymentAccounts(
+  params: {
+    rpc: KitRpc;
+    buyer: AddressLike;
+    premiumVault: AddressLike;
+    underlyingMint: AddressLike;
+    collateralMint?: AddressLike;
+    paymentMint?: AddressLike;
+    buyerPaymentAccount?: AddressLike;
+  }
+): Promise<{ paymentMint: AddressLike; buyerPaymentAccount: AddressLike }> {
+  const onChainPremiumMint = await fetchTokenAccountMint(params.rpc, params.premiumVault);
+  const paymentMint = params.paymentMint ?? onChainPremiumMint;
+  invariant(
+    toAddress(paymentMint) === toAddress(onChainPremiumMint),
+    "paymentMint must match on-chain premium_vault.mint"
+  );
+  const buyerPaymentAccount =
+    params.buyerPaymentAccount ??
+    (await deriveAssociatedTokenAddress(params.buyer, paymentMint));
+  return { paymentMint, buyerPaymentAccount };
+}
+
 export interface BuildCloseLongToPoolParams {
   optionPool: AddressLike;
   optionAccount: AddressLike;
@@ -84,10 +110,12 @@ export interface BuildCloseLongToPoolParams {
    */
   closeLongTokenAccount?: boolean;
   /**
-   * When true and underlying is WSOL, appends an SPL CloseAccount to unwrap the payout ATA so the buyer receives native SOL.
-   * Ignored when underlyingMint is not WSOL.
+   * When true and settlement is physical (collateral mint == underlying) with WSOL underlying,
+   * appends CloseAccount to unwrap the payout WSOL ATA to native SOL.
    */
   unwrapPayoutSol?: boolean;
+  /** When false, skips idempotent create-ATA for payout accounts (default: true). */
+  createPayoutAtas?: boolean;
   remainingAccounts?: RemainingAccountInput[];
 }
 
@@ -110,6 +138,7 @@ export async function buildBuyFromPoolInstruction(
       ? toAddress(params.buyerOptionAccount)
       : undefined,
     buyerPaymentAccount: toAddress(params.buyerPaymentAccount),
+    paymentMint: toAddress(params.paymentMint),
     escrowLongAccount: toAddress(params.escrowLongAccount),
     premiumVault: toAddress(params.premiumVault),
     quantity: params.quantity,
@@ -125,13 +154,13 @@ export async function buildBuyFromPoolInstruction(
  * first-time buyers succeed without a separate setup step.
  */
 export async function buildBuyFromPoolTransaction(
-  params: BuildBuyFromPoolParams
+  params: BuildBuyFromPoolParams & { createPaymentAta?: boolean }
 ): Promise<BuiltTransaction> {
   const buyerOptionAccountAddress = params.buyerOptionAccount
     ? toAddress(params.buyerOptionAccount)
     : await deriveAssociatedTokenAddress(params.buyer, params.longMint);
 
-  const createAtaIx =
+  const createLongAtaIx =
     await getCreateAssociatedTokenIdempotentInstructionWithAddress(
       params.buyer,
       params.buyer,
@@ -139,8 +168,22 @@ export async function buildBuyFromPoolTransaction(
       buyerOptionAccountAddress
     );
 
+  const instructions: Instruction<string>[] = [createLongAtaIx];
+
+  if (params.createPaymentAta !== false) {
+    const createPaymentAtaIx =
+      await getCreateAssociatedTokenIdempotentInstructionWithAddress(
+        params.buyer,
+        params.buyer,
+        params.paymentMint,
+        toAddress(params.buyerPaymentAccount)
+      );
+    instructions.push(createPaymentAtaIx);
+  }
+
   const buyFromPoolIx = await buildBuyFromPoolInstruction(params);
-  return { instructions: [createAtaIx, buyFromPoolIx] };
+  instructions.push(buyFromPoolIx);
+  return { instructions };
 }
 
 export interface BuildBuyFromPoolTransactionWithDerivationParams {
@@ -149,7 +192,10 @@ export interface BuildBuyFromPoolTransactionWithDerivationParams {
   strikePrice: number;
   expirationDate: bigint | number;
   buyer: AddressLike;
-  buyerPaymentAccount: AddressLike;
+  /** Optional — derived from on-chain premium_vault.mint when omitted. */
+  buyerPaymentAccount?: AddressLike;
+  /** Optional — derived from on-chain premium_vault.mint when omitted. */
+  paymentMint?: AddressLike;
   /** When `disableSwitchboardCrank` is true, optional explicit queue (else devnet/mainnet default). */
   switchboardQueue?: AddressLike;
   quantity: bigint | number;
@@ -235,7 +281,7 @@ export async function buildBuyFromPoolTransactionWithDerivation(
     "Option pool must exist; ensure rpc is provided and pool is initialized."
   );
 
-  const [buyerPosition, buyerOptionAccount] = await Promise.all([
+  const [buyerPosition, buyerOptionAccount, paymentAccounts] = await Promise.all([
     params.buyerPosition
       ? Promise.resolve(params.buyerPosition)
       : deriveBuyerPositionPda(
@@ -246,8 +292,35 @@ export async function buildBuyFromPoolTransactionWithDerivation(
     params.buyerOptionAccount
       ? Promise.resolve(params.buyerOptionAccount)
       : deriveAssociatedTokenAddress(params.buyer, resolved.longMint),
+    resolveBuyPaymentAccounts({
+      rpc: params.rpc,
+      buyer: params.buyer,
+      premiumVault: resolved.premiumVault!,
+      underlyingMint: resolved.underlyingMint!,
+      collateralMint: resolved.collateralPoolData?.collateralMint,
+      paymentMint: params.paymentMint,
+      buyerPaymentAccount: params.buyerPaymentAccount,
+    }),
   ]);
 
+  const buyParams = {
+    optionPool: resolved.optionPool,
+    optionAccount: resolved.optionAccount,
+    longMint: resolved.longMint,
+    underlyingMint: resolved.underlyingMint!,
+    marketData: resolved.marketData,
+    buyer: params.buyer,
+    paymentMint: paymentAccounts.paymentMint,
+    buyerPaymentAccount: paymentAccounts.buyerPaymentAccount,
+    escrowLongAccount: resolved.escrowLongAccount!,
+    premiumVault: resolved.premiumVault!,
+    quantity: params.quantity,
+    premiumAmount: params.premiumAmount,
+    buyerPosition,
+    buyerOptionAccount,
+    remainingAccounts: params.remainingAccounts,
+  };
+
   const marketDataAccount = await fetchMarketDataAccount(params.rpc, resolved.marketData);
   invariant(
     !!marketDataAccount,
@@ -263,21 +336,8 @@ export async function buildBuyFromPoolTransactionWithDerivation(
       ? toAddress(params.switchboardQueue)
       : getDefaultSwitchboardQueueAddress(network);
     return buildBuyFromPoolTransaction({
-      optionPool: resolved.optionPool,
-      optionAccount: resolved.optionAccount,
-      longMint: resolved.longMint,
-      underlyingMint: resolved.underlyingMint!,
-      marketData: resolved.marketData,
+      ...buyParams,
       switchboardQueue,
-      buyer: params.buyer,
-      buyerPaymentAccount: params.buyerPaymentAccount,
-      escrowLongAccount: resolved.escrowLongAccount!,
-      premiumVault: resolved.premiumVault!,
-      quantity: params.quantity,
-      premiumAmount: params.premiumAmount,
-      buyerPosition,
-      buyerOptionAccount,
-      remainingAccounts: params.remainingAccounts,
     });
   }
 
@@ -296,21 +356,8 @@ export async function buildBuyFromPoolTransactionWithDerivation(
   });
 
   const actionTx = await buildBuyFromPoolTransaction({
-    optionPool: resolved.optionPool,
-    optionAccount: resolved.optionAccount,
-    longMint: resolved.longMint,
-    underlyingMint: resolved.underlyingMint!,
-    marketData: resolved.marketData,
+    ...buyParams,
     switchboardQueue: getDefaultSwitchboardQueueAddress(network),
-    buyer: params.buyer,
-    buyerPaymentAccount: params.buyerPaymentAccount,
-    escrowLongAccount: resolved.escrowLongAccount!,
-    premiumVault: resolved.premiumVault!,
-    quantity: params.quantity,
-    premiumAmount: params.premiumAmount,
-    buyerPosition,
-    buyerOptionAccount,
-    remainingAccounts: params.remainingAccounts,
   });
 
   return prependSwitchboardQuote(quote, actionTx);
@@ -345,7 +392,7 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
     rpc: params.rpc,
   });
 
-  const [refetchedPool, remainingAccounts, buyerPosition, buyerOptionAccount] =
+  const [refetchedPool, remainingAccounts, buyerPosition, buyerOptionAccount, paymentAccounts] =
     await Promise.all([
       fetchOptionPool(params.rpc, resolved.optionPool),
       getBuyFromPoolRemainingAccounts(params.rpc, resolved.optionPool, params.programId),
@@ -359,6 +406,15 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
       params.buyerOptionAccount
         ? Promise.resolve(params.buyerOptionAccount)
         : deriveAssociatedTokenAddress(params.buyer, resolved.longMint),
+      resolveBuyPaymentAccounts({
+        rpc: params.rpc,
+        buyer: params.buyer,
+        premiumVault: resolved.premiumVault!,
+        underlyingMint: resolved.underlyingMint!,
+        collateralMint: resolved.collateralPoolData?.collateralMint,
+        paymentMint: params.paymentMint,
+        buyerPaymentAccount: params.buyerPaymentAccount,
+      }),
     ]);
 
   invariant(
@@ -392,18 +448,36 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
   const onchainPad = (q: bigint) =>
     (q * BigInt(POOL_BUY_MAX_PREMIUM_ONCHAIN_PAD_BPS)) / 10_000n;
   const slippageBuffer = hasExplicitSlippageBuffer
-    ? normalizeMarketOrderSlippageBuffer(params, refetchedPool.underlyingMint) +
+    ? normalizeMarketOrderSlippageBuffer(params, paymentAccounts.paymentMint) +
         onchainPad(quotePremium)
     : globalTradeConfig.slippageBps !== undefined
       ? applySlippageBps(
           quotePremium,
           globalTradeConfig.slippageBps + POOL_BUY_MAX_PREMIUM_ONCHAIN_PAD_BPS
         ) - quotePremium
-      : normalizeMarketOrderSlippageBuffer(params, refetchedPool.underlyingMint) +
+      : normalizeMarketOrderSlippageBuffer(params, paymentAccounts.paymentMint) +
         onchainPad(quotePremium);
   const maxPremiumAmount = quotePremium + slippageBuffer;
   assertPositiveAmount(maxPremiumAmount, "maxPremiumAmount");
 
+  const marketBuyParams = {
+    optionPool: resolved.optionPool,
+    optionAccount: resolved.optionAccount,
+    longMint: resolved.longMint,
+    underlyingMint: refetchedPool.underlyingMint,
+    marketData: resolved.marketData,
+    buyer: params.buyer,
+    paymentMint: paymentAccounts.paymentMint,
+    buyerPaymentAccount: paymentAccounts.buyerPaymentAccount,
+    escrowLongAccount: refetchedPool.escrowLongAccount,
+    premiumVault: refetchedPool.premiumVault,
+    quantity: params.quantity,
+    premiumAmount: maxPremiumAmount,
+    buyerPosition,
+    buyerOptionAccount,
+    remainingAccounts,
+  };
+
   const marketDataAccount = await fetchMarketDataAccount(params.rpc, resolved.marketData);
   invariant(
     !!marketDataAccount,
@@ -419,21 +493,8 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
       ? toAddress(params.switchboardQueue)
       : getDefaultSwitchboardQueueAddress(network);
     return buildBuyFromPoolTransaction({
-      optionPool: resolved.optionPool,
-      optionAccount: resolved.optionAccount,
-      longMint: resolved.longMint,
-      underlyingMint: refetchedPool.underlyingMint,
-      marketData: resolved.marketData,
+      ...marketBuyParams,
       switchboardQueue,
-      buyer: params.buyer,
-      buyerPaymentAccount: params.buyerPaymentAccount,
-      escrowLongAccount: refetchedPool.escrowLongAccount,
-      premiumVault: refetchedPool.premiumVault,
-      quantity: params.quantity,
-      premiumAmount: maxPremiumAmount,
-      buyerPosition,
-      buyerOptionAccount,
-      remainingAccounts,
     });
   }
 
@@ -452,21 +513,8 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
   });
 
   const actionTx = await buildBuyFromPoolTransaction({
-    optionPool: resolved.optionPool,
-    optionAccount: resolved.optionAccount,
-    longMint: resolved.longMint,
-    underlyingMint: refetchedPool.underlyingMint,
-    marketData: resolved.marketData,
+    ...marketBuyParams,
     switchboardQueue: getDefaultSwitchboardQueueAddress(network),
-    buyer: params.buyer,
-    buyerPaymentAccount: params.buyerPaymentAccount,
-    escrowLongAccount: refetchedPool.escrowLongAccount,
-    premiumVault: refetchedPool.premiumVault,
-    quantity: params.quantity,
-    premiumAmount: maxPremiumAmount,
-    buyerPosition,
-    buyerOptionAccount,
-    remainingAccounts,
   });
 
   return prependSwitchboardQuote(quote, actionTx);
@@ -508,10 +556,36 @@ export async function buildCloseLongToPoolInstruction(
 }
 
 export async function buildCloseLongToPoolTransaction(
-  params: BuildCloseLongToPoolParams
+  params: BuildCloseLongToPoolParams & { createPayoutAtas?: boolean }
 ): Promise<BuiltTransaction> {
+  const collateralMint = params.collateralMint ?? params.underlyingMint;
+  const isPhysicalSettlement =
+    toAddress(collateralMint) === toAddress(params.underlyingMint);
+  const instructions: Instruction<string>[] = [];
+
+  if (params.createPayoutAtas !== false) {
+    instructions.push(
+      await getCreateAssociatedTokenIdempotentInstructionWithAddress(
+        params.buyer,
+        params.buyer,
+        toAddress(collateralMint),
+        toAddress(params.buyerPayoutAccount)
+      )
+    );
+    if (!isPhysicalSettlement) {
+      instructions.push(
+        await getCreateAssociatedTokenIdempotentInstructionWithAddress(
+          params.buyer,
+          params.buyer,
+          toAddress(params.underlyingMint),
+          toAddress(params.buyerUnderlyingPayoutAccount)
+        )
+      );
+    }
+  }
+
   const instruction = await buildCloseLongToPoolInstruction(params);
-  const instructions = [instruction];
+  instructions.push(instruction);
 
   if (params.closeLongTokenAccount === true) {
     instructions.push(
@@ -563,10 +637,12 @@ export interface BuildCloseLongToPoolTransactionWithDerivationParams {
    */
   closeLongTokenAccount?: boolean;
   /**
-   * When true (default for WSOL underlying), appends CloseAccount to unwrap payout WSOL ATA to native SOL.
-   * Only applies when option underlying is WSOL.
+   * When true, unwraps physical-settlement WSOL payout to native SOL after close.
+   * Defaults to true only for physical WSOL pools; cash-settled pools default to false.
    */
   unwrapPayoutSol?: boolean;
+  /** When false, skips idempotent create-ATA for payout accounts (default: true). */
+  createPayoutAtas?: boolean;
   remainingAccounts?: RemainingAccountInput[];
   disableSwitchboardCrank?: boolean;
   switchboardCrossbarUrl?: string;
@@ -619,10 +695,13 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
 
   const isWsolUnderlying =
     toAddress(resolved.underlyingMint!) === toAddress(NATIVE_MINT);
+  const isPhysicalSettlement =
+    toAddress(collateralMint) === toAddress(resolved.underlyingMint!);
   const closeLongTokenAccount =
     params.closeLongTokenAccount !== false;
   const unwrapPayoutSol =
-    params.unwrapPayoutSol !== false && isWsolUnderlying;
+    params.unwrapPayoutSol ??
+    (isWsolUnderlying && isPhysicalSettlement);
 
   // close_long_to_pool requires a complete set of active WriterPositions so the
   // program can run the strict Hamilton completeness check. Auto-populate if
@@ -670,6 +749,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
       buyerPosition,
       closeLongTokenAccount,
       unwrapPayoutSol,
+      createPayoutAtas: params.createPayoutAtas,
       remainingAccounts,
     });
   }
@@ -709,6 +789,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
     buyerPosition,
     closeLongTokenAccount,
     unwrapPayoutSol,
+    createPayoutAtas: params.createPayoutAtas,
     remainingAccounts,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.12.0-beta",
+  "version": "0.12.2-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/amounts.ts

@@ -1,4 +1,5 @@
 import Decimal from "decimal.js";
+import type { AddressLike } from "../client/types";
 import { SdkValidationError } from "./errors";
 
 export function toBaseUnits(amount: Decimal.Value, decimals: number): bigint {
@@ -72,3 +73,42 @@ export function calculateRequiredCollateralLegacy(
     "physical"
   );
 }
+
+/**
+ * Premium payment mint for a pool: underlying when physical, collateral when cash.
+ * For **existing** pools, prefer on-chain `premium_vault.mint` (legacy cash may differ).
+ */
+export function getPremiumMint(
+  underlyingMint: AddressLike,
+  collateralMint: AddressLike
+): string {
+  const underlying = String(underlyingMint);
+  const collateral = String(collateralMint);
+  return underlying === collateral ? underlying : collateral;
+}
+
+/**
+ * Convert BS premium USD to payment-mint base units.
+ * - **Cash:** `premiumUsd × 10^decimals` (~$1 stable collateral)
+ * - **Physical:** `(premiumUsd / underlyingSpot) × 10^decimals`
+ */
+export function convertPremiumUsdToBaseUnits(
+  premiumUsd: number,
+  settlementMode: SettlementMode,
+  underlyingSpot: number,
+  tokenDecimals: number
+): bigint {
+  if (!Number.isFinite(premiumUsd) || premiumUsd <= 0) {
+    return 0n;
+  }
+  const scale = 10 ** tokenDecimals;
+  if (settlementMode === "cash") {
+    return BigInt(Math.ceil(premiumUsd * scale - Number.EPSILON));
+  }
+  if (!Number.isFinite(underlyingSpot) || underlyingSpot <= 0) {
+    return 0n;
+  }
+  return BigInt(
+    Math.ceil((premiumUsd / underlyingSpot) * scale - Number.EPSILON)
+  );
+}

package/shared/balances.ts

@@ -1,27 +1,62 @@
 import type { Address } from "@solana/kit";
+import { getAddressDecoder } from "@solana/kit";
 import { deriveAssociatedTokenAddress } from "../accounts/pdas";
 import { toAddress } from "../client/program";
 import type { AddressLike, KitRpc } from "../client/types";
 import { NATIVE_MINT } from "../wsol/instructions";
 
-/** SPL Token account data: amount field offset (u64 LE). */
+/** SPL Token account data: mint at offset 0 (32 bytes); amount at offset 64 (u64 LE). */
+const TOKEN_ACCOUNT_MINT_OFFSET = 0;
 const TOKEN_ACCOUNT_AMOUNT_OFFSET = 64;
 
+function decodeTokenAccountData(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const data = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) data[i] = binary.charCodeAt(i);
+  return data;
+}
+
+function decodeTokenAccountMint(data: Uint8Array): Address | null {
+  if (data.length < TOKEN_ACCOUNT_MINT_OFFSET + 32) return null;
+  return getAddressDecoder().decode(
+    data.subarray(TOKEN_ACCOUNT_MINT_OFFSET, TOKEN_ACCOUNT_MINT_OFFSET + 32)
+  );
+}
+
 function decodeTokenAccountAmount(data: Uint8Array): bigint {
   if (data.length < TOKEN_ACCOUNT_AMOUNT_OFFSET + 8) return BigInt(0);
   const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
   return view.getBigUint64(TOKEN_ACCOUNT_AMOUNT_OFFSET, true);
 }
 
-async function fetchTokenAccountBalance(rpc: KitRpc, ata: Address): Promise<bigint> {
+async function fetchTokenAccountData(rpc: KitRpc, ata: Address): Promise<Uint8Array | null> {
   const response = await rpc.getAccountInfo(ata, { encoding: "base64" }).send();
   const accountInfo = response.value;
-  if (!accountInfo) return BigInt(0);
+  if (!accountInfo) return null;
   const [b64] = accountInfo.data;
-  if (!b64) return BigInt(0);
-  const binary = atob(b64);
-  const data = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) data[i] = binary.charCodeAt(i);
+  if (!b64) return null;
+  return decodeTokenAccountData(b64);
+}
+
+/** Read the mint pubkey from an SPL token account address. */
+export async function fetchTokenAccountMint(
+  rpc: KitRpc,
+  tokenAccount: AddressLike
+): Promise<Address> {
+  const data = await fetchTokenAccountData(rpc, toAddress(tokenAccount));
+  if (!data) {
+    throw new Error(`Token account not found: ${String(tokenAccount)}`);
+  }
+  const mint = decodeTokenAccountMint(data);
+  if (!mint) {
+    throw new Error(`Invalid token account data: ${String(tokenAccount)}`);
+  }
+  return mint;
+}
+
+async function fetchTokenAccountBalance(rpc: KitRpc, ata: Address): Promise<bigint> {
+  const data = await fetchTokenAccountData(rpc, ata);
+  if (!data) return BigInt(0);
   return decodeTokenAccountAmount(data);
 }
 

package/short/preflight.ts

@@ -6,6 +6,7 @@ import { fetchPoolLoansByMaker } from "../accounts/list";
 import { deriveAssociatedTokenAddress, deriveVaultPda, deriveWriterPositionPda } from "../accounts/pdas";
 import { resolveOptionAccounts } from "../accounts/resolve-option";
 import { invariant } from "../shared/errors";
+import { fetchTokenAccountMint } from "../shared/balances";
 
 const TOKEN_ACCOUNT_AMOUNT_OFFSET = 64;
 const BPS_DENOMINATOR = 10_000n;
@@ -251,9 +252,10 @@ export async function preflightUnwindWriterUnsold(
   const collateralPoolData = resolved.collateralPoolData;
 
   const underlyingMint = params.underlyingMint ?? resolved.underlyingMint;
-  const [vaultPda] = await deriveVaultPda(underlyingMint, params.programId);
+  const collateralMint = collateralPoolData.collateralMint ?? underlyingMint;
+  const [vaultPda] = await deriveVaultPda(collateralMint, params.programId);
   const vaultPdaAddress = toAddress(vaultPda);
-  const writerDefaultRepaymentAta = await deriveAssociatedTokenAddress(params.writer, underlyingMint);
+  const writerDefaultRepaymentAta = await deriveAssociatedTokenAddress(params.writer, collateralMint);
   // `writerRepaymentAccount` stays in the result for ABI compatibility with
   // existing callers (e.g. wallet-fallback UX from pre-convergence), but it
   // is not used on-chain anymore.
@@ -455,12 +457,12 @@ export async function preflightUnwindWriterUnsold(
   const thetaAvailable = computeThetaBalance(writerPosition, optionPoolData.accThetaPerOiFp);
 
   // Theta can only offset debt when premium_vault.mint == omlp_vault.mint.
-  // In OPX, premium_vault.mint == option_pool.underlying_mint (enforced via
-  // `buyer_payment_account.mint == option_pool.underlying_mint`), and the
-  // OMLP vault is derived for the collateral mint. They match when the
-  // collateral pool's collateral_mint equals the option pool's underlying_mint.
+  const premiumVaultMint = await fetchTokenAccountMint(
+    params.rpc,
+    resolved.premiumVault!
+  );
   const premiumMintMatchesCollateralMint =
-    toAddress(optionPoolData.underlyingMint) === toAddress(collateralPoolData.collateralMint);
+    toAddress(premiumVaultMint) === toAddress(collateralPoolData.collateralMint);
 
   const thetaToDebt = premiumMintMatchesCollateralMint
     ? minBigInt(thetaAvailable, proportionalTotalOwed)