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

package/README.md

@@ -287,13 +287,24 @@ Use `calculateRequiredCollateral` to estimate collateral needs before minting:
 ```ts
 import { calculateRequiredCollateral } from "@epicentral/sos-sdk";
 
-const required = calculateRequiredCollateral(
-  1_000_000n,      // 1 contract in base units
-  150.0,           // $150 strike price
-  145.23,          // Current spot price (USD)
-  6                // USDC decimals
+// Cash-settled SOL call backed by USDC (~$1 collateral price)
+const requiredUsdc = calculateRequiredCollateral(
+  1_000_000n,
+  150.0,
+  1.0,
+  6,
+  "cash"
+);
+// ~15_000_000_000 micro-USDC for 1 contract at $150 strike
+
+// Physical SOL collateral (underlying spot)
+const requiredSol = calculateRequiredCollateral(
+  1_000_000n,
+  150.0,
+  145.23,
+  9,
+  "physical"
 );
-// Returns: USDC base units needed
 ```
 
 ## Unwind with Loan Repayment (theta-hedge model)
@@ -567,19 +578,22 @@ The SDK exports `calculateRequiredCollateral` for pre-flight collateral estimati
 import { calculateRequiredCollateral } from "@epicentral/sos-sdk";
 
 const required = calculateRequiredCollateral(
-  1_000_000n,      // 1 contract in base units
-  150.0,           // $150 strike price
-  145.23,          // Current spot price (USD)
-  9                // Token decimals (9 for SOL)
+  1_000_000n,
+  150.0,
+  145.23,
+  9,
+  "physical"
 );
-// Returns: token base units needed (e.g., 103_280_000_000 lamports for ~103.28 SOL)
 ```
 
 **Formula:**
 ```
 contracts     = quantity / 1_000_000
 usd_value     = contracts * 100 * strike_price
-collateral    = (usd_value / spot_price) * 10^token_decimals
+physical      = (usd_value / underlying_spot) * 10^decimals
+cash          = usd_value * 10^collateral_decimals   // conversionPrice ≈ $1 for USDC
 ```
 
+`buildCloseLongToPoolTransactionWithDerivation` auto-derives `buyerPayoutAccount` (collateral mint) and `buyerUnderlyingPayoutAccount` (premium leg) when omitted.
+
 This matches the on-chain formula in `Vault::calculate_required_collateral` and can be used to display required collateral to users before submitting an `option_mint` transaction.

package/generated/instructions/buyFromPool.ts

@@ -68,6 +68,7 @@ export type BuyFromPoolInstruction<
   TAccountBuyerPaymentAccount extends string | AccountMeta<string> = string,
   TAccountEscrowLongAccount extends string | AccountMeta<string> = string,
   TAccountPremiumVault extends string | AccountMeta<string> = string,
+  TAccountCollateralPool extends string | AccountMeta<string> = string,
   TAccountBuyer extends string | AccountMeta<string> = string,
   TAccountTokenProgram extends string | AccountMeta<string> =
     "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
@@ -119,6 +120,9 @@ export type BuyFromPoolInstruction<
       TAccountPremiumVault extends string
         ? WritableAccount<TAccountPremiumVault>
         : TAccountPremiumVault,
+      TAccountCollateralPool extends string
+        ? ReadonlyAccount<TAccountCollateralPool>
+        : TAccountCollateralPool,
       TAccountBuyer extends string
         ? WritableSignerAccount<TAccountBuyer> &
             AccountSignerMeta<TAccountBuyer>
@@ -190,6 +194,7 @@ export type BuyFromPoolAsyncInput<
   TAccountBuyerPaymentAccount extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
+  TAccountCollateralPool extends string = string,
   TAccountBuyer extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountAssociatedTokenProgram extends string = string,
@@ -221,6 +226,8 @@ export type BuyFromPoolAsyncInput<
   escrowLongAccount: Address<TAccountEscrowLongAccount>;
   /** Pool's premium vault (receives premium) */
   premiumVault: Address<TAccountPremiumVault>;
+  /** Collateral pool (settlement mint for buyer position tracking) */
+  collateralPool?: Address<TAccountCollateralPool>;
   buyer: TransactionSigner<TAccountBuyer>;
   tokenProgram?: Address<TAccountTokenProgram>;
   associatedTokenProgram?: Address<TAccountAssociatedTokenProgram>;
@@ -243,6 +250,7 @@ export async function getBuyFromPoolInstructionAsync<
   TAccountBuyerPaymentAccount extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
+  TAccountCollateralPool extends string,
   TAccountBuyer extends string,
   TAccountTokenProgram extends string,
   TAccountAssociatedTokenProgram extends string,
@@ -263,6 +271,7 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -285,6 +294,7 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -328,6 +338,7 @@ export async function getBuyFromPoolInstructionAsync<
       isWritable: true,
     },
     premiumVault: { value: input.premiumVault ?? null, isWritable: true },
+    collateralPool: { value: input.collateralPool ?? null, isWritable: false },
     buyer: { value: input.buyer ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
     associatedTokenProgram: {
@@ -382,6 +393,20 @@ export async function getBuyFromPoolInstructionAsync<
       ],
     });
   }
+  if (!accounts.collateralPool.value) {
+    accounts.collateralPool.value = await getProgramDerivedAddress({
+      programAddress,
+      seeds: [
+        getBytesEncoder().encode(
+          new Uint8Array([
+            99, 111, 108, 108, 97, 116, 101, 114, 97, 108, 95, 112, 111, 111,
+            108,
+          ]),
+        ),
+        getAddressEncoder().encode(expectAddress(accounts.optionAccount.value)),
+      ],
+    });
+  }
   if (!accounts.tokenProgram.value) {
     accounts.tokenProgram.value =
       "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" as Address<"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA">;
@@ -411,6 +436,7 @@ export async function getBuyFromPoolInstructionAsync<
       getAccountMeta(accounts.buyerPaymentAccount),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
+      getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.buyer),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.associatedTokenProgram),
@@ -435,6 +461,7 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -456,6 +483,7 @@ export type BuyFromPoolInput<
   TAccountBuyerPaymentAccount extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
+  TAccountCollateralPool extends string = string,
   TAccountBuyer extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountAssociatedTokenProgram extends string = string,
@@ -487,6 +515,8 @@ export type BuyFromPoolInput<
   escrowLongAccount: Address<TAccountEscrowLongAccount>;
   /** Pool's premium vault (receives premium) */
   premiumVault: Address<TAccountPremiumVault>;
+  /** Collateral pool (settlement mint for buyer position tracking) */
+  collateralPool: Address<TAccountCollateralPool>;
   buyer: TransactionSigner<TAccountBuyer>;
   tokenProgram?: Address<TAccountTokenProgram>;
   associatedTokenProgram?: Address<TAccountAssociatedTokenProgram>;
@@ -509,6 +539,7 @@ export function getBuyFromPoolInstruction<
   TAccountBuyerPaymentAccount extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
+  TAccountCollateralPool extends string,
   TAccountBuyer extends string,
   TAccountTokenProgram extends string,
   TAccountAssociatedTokenProgram extends string,
@@ -529,6 +560,7 @@ export function getBuyFromPoolInstruction<
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -550,6 +582,7 @@ export function getBuyFromPoolInstruction<
   TAccountBuyerPaymentAccount,
   TAccountEscrowLongAccount,
   TAccountPremiumVault,
+  TAccountCollateralPool,
   TAccountBuyer,
   TAccountTokenProgram,
   TAccountAssociatedTokenProgram,
@@ -592,6 +625,7 @@ export function getBuyFromPoolInstruction<
       isWritable: true,
     },
     premiumVault: { value: input.premiumVault ?? null, isWritable: true },
+    collateralPool: { value: input.collateralPool ?? null, isWritable: false },
     buyer: { value: input.buyer ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
     associatedTokenProgram: {
@@ -646,6 +680,7 @@ export function getBuyFromPoolInstruction<
       getAccountMeta(accounts.buyerPaymentAccount),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
+      getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.buyer),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.associatedTokenProgram),
@@ -670,6 +705,7 @@ export function getBuyFromPoolInstruction<
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -709,10 +745,12 @@ export type ParsedBuyFromPoolInstruction<
     escrowLongAccount: TAccountMetas[11];
     /** Pool's premium vault (receives premium) */
     premiumVault: TAccountMetas[12];
-    buyer: TAccountMetas[13];
-    tokenProgram: TAccountMetas[14];
-    associatedTokenProgram: TAccountMetas[15];
-    systemProgram: TAccountMetas[16];
+    /** Collateral pool (settlement mint for buyer position tracking) */
+    collateralPool: TAccountMetas[13];
+    buyer: TAccountMetas[14];
+    tokenProgram: TAccountMetas[15];
+    associatedTokenProgram: TAccountMetas[16];
+    systemProgram: TAccountMetas[17];
   };
   data: BuyFromPoolInstructionData;
 };
@@ -725,7 +763,7 @@ export function parseBuyFromPoolInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedBuyFromPoolInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 17) {
+  if (instruction.accounts.length < 18) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -751,6 +789,7 @@ export function parseBuyFromPoolInstruction<
       buyerPaymentAccount: getNextAccount(),
       escrowLongAccount: getNextAccount(),
       premiumVault: getNextAccount(),
+      collateralPool: getNextAccount(),
       buyer: getNextAccount(),
       tokenProgram: getNextAccount(),
       associatedTokenProgram: getNextAccount(),

package/generated/instructions/closeLongToPool.ts

@@ -57,6 +57,7 @@ export type CloseLongToPoolInstruction<
   TAccountOptionAccount extends string | AccountMeta<string> = string,
   TAccountCollateralPool extends string | AccountMeta<string> = string,
   TAccountUnderlyingMint extends string | AccountMeta<string> = string,
+  TAccountCollateralMint extends string | AccountMeta<string> = string,
   TAccountLongMint extends string | AccountMeta<string> = string,
   TAccountEscrowLongAccount extends string | AccountMeta<string> = string,
   TAccountPremiumVault extends string | AccountMeta<string> = string,
@@ -69,6 +70,8 @@ export type CloseLongToPoolInstruction<
   TAccountBuyerPosition extends string | AccountMeta<string> = string,
   TAccountBuyerLongAccount extends string | AccountMeta<string> = string,
   TAccountBuyerPayoutAccount extends string | AccountMeta<string> = string,
+  TAccountBuyerUnderlyingPayoutAccount extends string | AccountMeta<string> =
+    string,
   TAccountCollateralVault extends string | AccountMeta<string> = string,
   TAccountBuyer extends string | AccountMeta<string> = string,
   TAccountTokenProgram extends string | AccountMeta<string> =
@@ -92,6 +95,9 @@ export type CloseLongToPoolInstruction<
       TAccountUnderlyingMint extends string
         ? ReadonlyAccount<TAccountUnderlyingMint>
         : TAccountUnderlyingMint,
+      TAccountCollateralMint extends string
+        ? ReadonlyAccount<TAccountCollateralMint>
+        : TAccountCollateralMint,
       TAccountLongMint extends string
         ? WritableAccount<TAccountLongMint>
         : TAccountLongMint,
@@ -122,6 +128,9 @@ export type CloseLongToPoolInstruction<
       TAccountBuyerPayoutAccount extends string
         ? WritableAccount<TAccountBuyerPayoutAccount>
         : TAccountBuyerPayoutAccount,
+      TAccountBuyerUnderlyingPayoutAccount extends string
+        ? WritableAccount<TAccountBuyerUnderlyingPayoutAccount>
+        : TAccountBuyerUnderlyingPayoutAccount,
       TAccountCollateralVault extends string
         ? WritableAccount<TAccountCollateralVault>
         : TAccountCollateralVault,
@@ -184,6 +193,7 @@ export type CloseLongToPoolAsyncInput<
   TAccountOptionAccount extends string = string,
   TAccountCollateralPool extends string = string,
   TAccountUnderlyingMint extends string = string,
+  TAccountCollateralMint extends string = string,
   TAccountLongMint extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
@@ -194,6 +204,7 @@ export type CloseLongToPoolAsyncInput<
   TAccountBuyerPosition extends string = string,
   TAccountBuyerLongAccount extends string = string,
   TAccountBuyerPayoutAccount extends string = string,
+  TAccountBuyerUnderlyingPayoutAccount extends string = string,
   TAccountCollateralVault extends string = string,
   TAccountBuyer extends string = string,
   TAccountTokenProgram extends string = string,
@@ -207,6 +218,8 @@ export type CloseLongToPoolAsyncInput<
   collateralPool?: Address<TAccountCollateralPool>;
   /** Underlying token mint (for decimal handling) */
   underlyingMint: Address<TAccountUnderlyingMint>;
+  /** Collateral mint (settlement currency for collateral-vault payout leg) */
+  collateralMint: Address<TAccountCollateralMint>;
   /** LONG token mint (for transfer validation) */
   longMint: Address<TAccountLongMint>;
   /** Pool LONG escrow (destination when buyer closes back to pool) */
@@ -222,8 +235,10 @@ export type CloseLongToPoolAsyncInput<
   buyerPosition?: Address<TAccountBuyerPosition>;
   /** Buyer's LONG token account (source of tokens to return) */
   buyerLongAccount: Address<TAccountBuyerLongAccount>;
-  /** Buyer's underlying token account (receives payout) */
+  /** Buyer's settlement token account (receives collateral-vault payout leg) */
   buyerPayoutAccount: Address<TAccountBuyerPayoutAccount>;
+  /** Buyer's underlying token account (receives premium-vault payout leg; same ATA when physical) */
+  buyerUnderlyingPayoutAccount: Address<TAccountBuyerUnderlyingPayoutAccount>;
   /** Collateral vault (source of payout) */
   collateralVault: Address<TAccountCollateralVault>;
   buyer: TransactionSigner<TAccountBuyer>;
@@ -238,6 +253,7 @@ export async function getCloseLongToPoolInstructionAsync<
   TAccountOptionAccount extends string,
   TAccountCollateralPool extends string,
   TAccountUnderlyingMint extends string,
+  TAccountCollateralMint extends string,
   TAccountLongMint extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
@@ -248,6 +264,7 @@ export async function getCloseLongToPoolInstructionAsync<
   TAccountBuyerPosition extends string,
   TAccountBuyerLongAccount extends string,
   TAccountBuyerPayoutAccount extends string,
+  TAccountBuyerUnderlyingPayoutAccount extends string,
   TAccountCollateralVault extends string,
   TAccountBuyer extends string,
   TAccountTokenProgram extends string,
@@ -259,6 +276,7 @@ export async function getCloseLongToPoolInstructionAsync<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountLongMint,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -269,6 +287,7 @@ export async function getCloseLongToPoolInstructionAsync<
     TAccountBuyerPosition,
     TAccountBuyerLongAccount,
     TAccountBuyerPayoutAccount,
+    TAccountBuyerUnderlyingPayoutAccount,
     TAccountCollateralVault,
     TAccountBuyer,
     TAccountTokenProgram,
@@ -282,6 +301,7 @@ export async function getCloseLongToPoolInstructionAsync<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountLongMint,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -292,6 +312,7 @@ export async function getCloseLongToPoolInstructionAsync<
     TAccountBuyerPosition,
     TAccountBuyerLongAccount,
     TAccountBuyerPayoutAccount,
+    TAccountBuyerUnderlyingPayoutAccount,
     TAccountCollateralVault,
     TAccountBuyer,
     TAccountTokenProgram,
@@ -308,6 +329,7 @@ export async function getCloseLongToPoolInstructionAsync<
     optionAccount: { value: input.optionAccount ?? null, isWritable: true },
     collateralPool: { value: input.collateralPool ?? null, isWritable: true },
     underlyingMint: { value: input.underlyingMint ?? null, isWritable: false },
+    collateralMint: { value: input.collateralMint ?? null, isWritable: false },
     longMint: { value: input.longMint ?? null, isWritable: true },
     escrowLongAccount: {
       value: input.escrowLongAccount ?? null,
@@ -336,6 +358,10 @@ export async function getCloseLongToPoolInstructionAsync<
       value: input.buyerPayoutAccount ?? null,
       isWritable: true,
     },
+    buyerUnderlyingPayoutAccount: {
+      value: input.buyerUnderlyingPayoutAccount ?? null,
+      isWritable: true,
+    },
     collateralVault: { value: input.collateralVault ?? null, isWritable: true },
     buyer: { value: input.buyer ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
@@ -400,6 +426,7 @@ export async function getCloseLongToPoolInstructionAsync<
       getAccountMeta(accounts.optionAccount),
       getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.underlyingMint),
+      getAccountMeta(accounts.collateralMint),
       getAccountMeta(accounts.longMint),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
@@ -410,6 +437,7 @@ export async function getCloseLongToPoolInstructionAsync<
       getAccountMeta(accounts.buyerPosition),
       getAccountMeta(accounts.buyerLongAccount),
       getAccountMeta(accounts.buyerPayoutAccount),
+      getAccountMeta(accounts.buyerUnderlyingPayoutAccount),
       getAccountMeta(accounts.collateralVault),
       getAccountMeta(accounts.buyer),
       getAccountMeta(accounts.tokenProgram),
@@ -425,6 +453,7 @@ export async function getCloseLongToPoolInstructionAsync<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountLongMint,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -435,6 +464,7 @@ export async function getCloseLongToPoolInstructionAsync<
     TAccountBuyerPosition,
     TAccountBuyerLongAccount,
     TAccountBuyerPayoutAccount,
+    TAccountBuyerUnderlyingPayoutAccount,
     TAccountCollateralVault,
     TAccountBuyer,
     TAccountTokenProgram,
@@ -447,6 +477,7 @@ export type CloseLongToPoolInput<
   TAccountOptionAccount extends string = string,
   TAccountCollateralPool extends string = string,
   TAccountUnderlyingMint extends string = string,
+  TAccountCollateralMint extends string = string,
   TAccountLongMint extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
@@ -457,6 +488,7 @@ export type CloseLongToPoolInput<
   TAccountBuyerPosition extends string = string,
   TAccountBuyerLongAccount extends string = string,
   TAccountBuyerPayoutAccount extends string = string,
+  TAccountBuyerUnderlyingPayoutAccount extends string = string,
   TAccountCollateralVault extends string = string,
   TAccountBuyer extends string = string,
   TAccountTokenProgram extends string = string,
@@ -470,6 +502,8 @@ export type CloseLongToPoolInput<
   collateralPool: Address<TAccountCollateralPool>;
   /** Underlying token mint (for decimal handling) */
   underlyingMint: Address<TAccountUnderlyingMint>;
+  /** Collateral mint (settlement currency for collateral-vault payout leg) */
+  collateralMint: Address<TAccountCollateralMint>;
   /** LONG token mint (for transfer validation) */
   longMint: Address<TAccountLongMint>;
   /** Pool LONG escrow (destination when buyer closes back to pool) */
@@ -485,8 +519,10 @@ export type CloseLongToPoolInput<
   buyerPosition: Address<TAccountBuyerPosition>;
   /** Buyer's LONG token account (source of tokens to return) */
   buyerLongAccount: Address<TAccountBuyerLongAccount>;
-  /** Buyer's underlying token account (receives payout) */
+  /** Buyer's settlement token account (receives collateral-vault payout leg) */
   buyerPayoutAccount: Address<TAccountBuyerPayoutAccount>;
+  /** Buyer's underlying token account (receives premium-vault payout leg; same ATA when physical) */
+  buyerUnderlyingPayoutAccount: Address<TAccountBuyerUnderlyingPayoutAccount>;
   /** Collateral vault (source of payout) */
   collateralVault: Address<TAccountCollateralVault>;
   buyer: TransactionSigner<TAccountBuyer>;
@@ -501,6 +537,7 @@ export function getCloseLongToPoolInstruction<
   TAccountOptionAccount extends string,
   TAccountCollateralPool extends string,
   TAccountUnderlyingMint extends string,
+  TAccountCollateralMint extends string,
   TAccountLongMint extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
@@ -511,6 +548,7 @@ export function getCloseLongToPoolInstruction<
   TAccountBuyerPosition extends string,
   TAccountBuyerLongAccount extends string,
   TAccountBuyerPayoutAccount extends string,
+  TAccountBuyerUnderlyingPayoutAccount extends string,
   TAccountCollateralVault extends string,
   TAccountBuyer extends string,
   TAccountTokenProgram extends string,
@@ -522,6 +560,7 @@ export function getCloseLongToPoolInstruction<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountLongMint,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -532,6 +571,7 @@ export function getCloseLongToPoolInstruction<
     TAccountBuyerPosition,
     TAccountBuyerLongAccount,
     TAccountBuyerPayoutAccount,
+    TAccountBuyerUnderlyingPayoutAccount,
     TAccountCollateralVault,
     TAccountBuyer,
     TAccountTokenProgram,
@@ -544,6 +584,7 @@ export function getCloseLongToPoolInstruction<
   TAccountOptionAccount,
   TAccountCollateralPool,
   TAccountUnderlyingMint,
+  TAccountCollateralMint,
   TAccountLongMint,
   TAccountEscrowLongAccount,
   TAccountPremiumVault,
@@ -554,6 +595,7 @@ export function getCloseLongToPoolInstruction<
   TAccountBuyerPosition,
   TAccountBuyerLongAccount,
   TAccountBuyerPayoutAccount,
+  TAccountBuyerUnderlyingPayoutAccount,
   TAccountCollateralVault,
   TAccountBuyer,
   TAccountTokenProgram,
@@ -569,6 +611,7 @@ export function getCloseLongToPoolInstruction<
     optionAccount: { value: input.optionAccount ?? null, isWritable: true },
     collateralPool: { value: input.collateralPool ?? null, isWritable: true },
     underlyingMint: { value: input.underlyingMint ?? null, isWritable: false },
+    collateralMint: { value: input.collateralMint ?? null, isWritable: false },
     longMint: { value: input.longMint ?? null, isWritable: true },
     escrowLongAccount: {
       value: input.escrowLongAccount ?? null,
@@ -597,6 +640,10 @@ export function getCloseLongToPoolInstruction<
       value: input.buyerPayoutAccount ?? null,
       isWritable: true,
     },
+    buyerUnderlyingPayoutAccount: {
+      value: input.buyerUnderlyingPayoutAccount ?? null,
+      isWritable: true,
+    },
     collateralVault: { value: input.collateralVault ?? null, isWritable: true },
     buyer: { value: input.buyer ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
@@ -635,6 +682,7 @@ export function getCloseLongToPoolInstruction<
       getAccountMeta(accounts.optionAccount),
       getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.underlyingMint),
+      getAccountMeta(accounts.collateralMint),
       getAccountMeta(accounts.longMint),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
@@ -645,6 +693,7 @@ export function getCloseLongToPoolInstruction<
       getAccountMeta(accounts.buyerPosition),
       getAccountMeta(accounts.buyerLongAccount),
       getAccountMeta(accounts.buyerPayoutAccount),
+      getAccountMeta(accounts.buyerUnderlyingPayoutAccount),
       getAccountMeta(accounts.collateralVault),
       getAccountMeta(accounts.buyer),
       getAccountMeta(accounts.tokenProgram),
@@ -660,6 +709,7 @@ export function getCloseLongToPoolInstruction<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountLongMint,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -670,6 +720,7 @@ export function getCloseLongToPoolInstruction<
     TAccountBuyerPosition,
     TAccountBuyerLongAccount,
     TAccountBuyerPayoutAccount,
+    TAccountBuyerUnderlyingPayoutAccount,
     TAccountCollateralVault,
     TAccountBuyer,
     TAccountTokenProgram,
@@ -691,28 +742,32 @@ export type ParsedCloseLongToPoolInstruction<
     collateralPool: TAccountMetas[2];
     /** Underlying token mint (for decimal handling) */
     underlyingMint: TAccountMetas[3];
+    /** Collateral mint (settlement currency for collateral-vault payout leg) */
+    collateralMint: TAccountMetas[4];
     /** LONG token mint (for transfer validation) */
-    longMint: TAccountMetas[4];
+    longMint: TAccountMetas[5];
     /** Pool LONG escrow (destination when buyer closes back to pool) */
-    escrowLongAccount: TAccountMetas[5];
+    escrowLongAccount: TAccountMetas[6];
     /** Premium vault (first source of buyer payout) */
-    premiumVault: TAccountMetas[6];
+    premiumVault: TAccountMetas[7];
     /** Market data account (provides risk-free rate and switchboard_feed_id) */
-    marketData: TAccountMetas[7];
-    switchboardQueue: TAccountMetas[8];
-    slotHashesSysvar: TAccountMetas[9];
-    instructionsSysvar: TAccountMetas[10];
+    marketData: TAccountMetas[8];
+    switchboardQueue: TAccountMetas[9];
+    slotHashesSysvar: TAccountMetas[10];
+    instructionsSysvar: TAccountMetas[11];
     /** Buyer's position account */
-    buyerPosition: TAccountMetas[11];
+    buyerPosition: TAccountMetas[12];
     /** Buyer's LONG token account (source of tokens to return) */
-    buyerLongAccount: TAccountMetas[12];
-    /** Buyer's underlying token account (receives payout) */
-    buyerPayoutAccount: TAccountMetas[13];
+    buyerLongAccount: TAccountMetas[13];
+    /** Buyer's settlement token account (receives collateral-vault payout leg) */
+    buyerPayoutAccount: TAccountMetas[14];
+    /** Buyer's underlying token account (receives premium-vault payout leg; same ATA when physical) */
+    buyerUnderlyingPayoutAccount: TAccountMetas[15];
     /** Collateral vault (source of payout) */
-    collateralVault: TAccountMetas[14];
-    buyer: TAccountMetas[15];
-    tokenProgram: TAccountMetas[16];
-    systemProgram: TAccountMetas[17];
+    collateralVault: TAccountMetas[16];
+    buyer: TAccountMetas[17];
+    tokenProgram: TAccountMetas[18];
+    systemProgram: TAccountMetas[19];
   };
   data: CloseLongToPoolInstructionData;
 };
@@ -725,7 +780,7 @@ export function parseCloseLongToPoolInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedCloseLongToPoolInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 18) {
+  if (instruction.accounts.length < 20) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -742,6 +797,7 @@ export function parseCloseLongToPoolInstruction<
       optionAccount: getNextAccount(),
       collateralPool: getNextAccount(),
       underlyingMint: getNextAccount(),
+      collateralMint: getNextAccount(),
       longMint: getNextAccount(),
       escrowLongAccount: getNextAccount(),
       premiumVault: getNextAccount(),
@@ -752,6 +808,7 @@ export function parseCloseLongToPoolInstruction<
       buyerPosition: getNextAccount(),
       buyerLongAccount: getNextAccount(),
       buyerPayoutAccount: getNextAccount(),
+      buyerUnderlyingPayoutAccount: getNextAccount(),
       collateralVault: getNextAccount(),
       buyer: getNextAccount(),
       tokenProgram: getNextAccount(),

package/generated/instructions/unwindWriterUnsold.ts

@@ -222,9 +222,9 @@ export type UnwindWriterUnsoldAsyncInput<
    */
   premiumVault: Address<TAccountPremiumVault>;
   /**
-   * Writer's token account for returned collateral + any leftover theta.
-   * Must be the underlying_mint so leftover theta (denominated in
-   * premium_vault.mint == underlying_mint) can be deposited here.
+   * Writer's token account for returned collateral (collateral_pool mint).
+   * Leftover theta from premium_vault is only transferred here when
+   * premium_vault.mint matches this account (physical settlement).
    */
   writerCollateralAccount: Address<TAccountWriterCollateralAccount>;
   /** OMLP Vault state PDA (for total_loans, add_interest_to_index) - optional, required when repaying loans */
@@ -480,9 +480,9 @@ export type UnwindWriterUnsoldInput<
    */
   premiumVault: Address<TAccountPremiumVault>;
   /**
-   * Writer's token account for returned collateral + any leftover theta.
-   * Must be the underlying_mint so leftover theta (denominated in
-   * premium_vault.mint == underlying_mint) can be deposited here.
+   * Writer's token account for returned collateral (collateral_pool mint).
+   * Leftover theta from premium_vault is only transferred here when
+   * premium_vault.mint matches this account (physical settlement).
    */
   writerCollateralAccount: Address<TAccountWriterCollateralAccount>;
   /** OMLP Vault state PDA (for total_loans, add_interest_to_index) - optional, required when repaying loans */
@@ -693,9 +693,9 @@ export type ParsedUnwindWriterUnsoldInstruction<
      */
     premiumVault: TAccountMetas[10];
     /**
-     * Writer's token account for returned collateral + any leftover theta.
-     * Must be the underlying_mint so leftover theta (denominated in
-     * premium_vault.mint == underlying_mint) can be deposited here.
+     * Writer's token account for returned collateral (collateral_pool mint).
+     * Leftover theta from premium_vault is only transferred here when
+     * premium_vault.mint matches this account (physical settlement).
      */
     writerCollateralAccount: TAccountMetas[11];
     /** OMLP Vault state PDA (for total_loans, add_interest_to_index) - optional, required when repaying loans */

package/long/builders.ts

@@ -69,7 +69,11 @@ export interface BuildCloseLongToPoolParams {
   switchboardQueue: AddressLike;
   buyer: AddressLike;
   buyerLongAccount: AddressLike;
+  /** Settlement-mint ATA (collateral pool mint). */
   buyerPayoutAccount: AddressLike;
+  /** Underlying-mint ATA for premium-vault leg (same as buyerPayout when physical). */
+  buyerUnderlyingPayoutAccount: AddressLike;
+  collateralMint?: AddressLike;
   collateralVault: AddressLike;
   quantity: bigint | number;
   minPayoutAmount: bigint | number;
@@ -477,11 +481,14 @@ export async function buildCloseLongToPoolInstruction(
     "minPayoutAmount must be greater than or equal to zero."
   );
 
+  const collateralMint = params.collateralMint ?? params.underlyingMint;
+
   const kitInstruction = await getCloseLongToPoolInstructionAsync({
     optionPool: toAddress(params.optionPool),
     optionAccount: toAddress(params.optionAccount),
     collateralPool: toAddress(params.collateralPool),
     underlyingMint: toAddress(params.underlyingMint),
+    collateralMint: toAddress(collateralMint),
     longMint: toAddress(params.longMint),
     escrowLongAccount: toAddress(params.escrowLongAccount),
     premiumVault: toAddress(params.premiumVault),
@@ -490,6 +497,7 @@ export async function buildCloseLongToPoolInstruction(
     buyer: toAddress(params.buyer) as any,
     buyerLongAccount: toAddress(params.buyerLongAccount),
     buyerPayoutAccount: toAddress(params.buyerPayoutAccount),
+    buyerUnderlyingPayoutAccount: toAddress(params.buyerUnderlyingPayoutAccount),
     collateralVault: toAddress(params.collateralVault),
     buyerPosition: params.buyerPosition ? toAddress(params.buyerPosition) : undefined,
     quantity: params.quantity,
@@ -521,7 +529,7 @@ export async function buildCloseLongToPoolTransaction(
   if (shouldUnwrapPayout) {
     instructions.push(
       getCloseAccountInstruction(
-        params.buyerPayoutAccount,
+        params.buyerUnderlyingPayoutAccount,
         params.buyer,
         params.buyer
       )
@@ -538,7 +546,10 @@ export interface BuildCloseLongToPoolTransactionWithDerivationParams {
   expirationDate: bigint | number;
   buyer: AddressLike;
   buyerLongAccount: AddressLike;
-  buyerPayoutAccount: AddressLike;
+  /** Optional — derived from collateral pool mint when omitted. */
+  buyerPayoutAccount?: AddressLike;
+  /** Optional — derived from underlying mint when omitted. */
+  buyerUnderlyingPayoutAccount?: AddressLike;
   switchboardQueue?: AddressLike;
   quantity: bigint | number;
   minPayoutAmount: bigint | number;
@@ -595,6 +606,17 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
         params.programId
       ))[0];
 
+  const collateralMint =
+    resolved.collateralPoolData?.collateralMint ?? resolved.underlyingMint!;
+  const [buyerPayoutAccount, buyerUnderlyingPayoutAccount] = await Promise.all([
+    params.buyerPayoutAccount
+      ? Promise.resolve(params.buyerPayoutAccount)
+      : deriveAssociatedTokenAddress(params.buyer, collateralMint),
+    params.buyerUnderlyingPayoutAccount
+      ? Promise.resolve(params.buyerUnderlyingPayoutAccount)
+      : deriveAssociatedTokenAddress(params.buyer, resolved.underlyingMint!),
+  ]);
+
   const isWsolUnderlying =
     toAddress(resolved.underlyingMint!) === toAddress(NATIVE_MINT);
   const closeLongTokenAccount =
@@ -632,6 +654,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
       optionAccount: resolved.optionAccount,
       collateralPool: resolved.collateralPool,
       underlyingMint: resolved.underlyingMint!,
+      collateralMint,
       longMint: resolved.longMint,
       escrowLongAccount: resolved.escrowLongAccount!,
       premiumVault: resolved.premiumVault!,
@@ -639,7 +662,8 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
       switchboardQueue,
       buyer: params.buyer,
       buyerLongAccount: params.buyerLongAccount,
-      buyerPayoutAccount: params.buyerPayoutAccount,
+      buyerPayoutAccount,
+      buyerUnderlyingPayoutAccount,
       collateralVault: resolved.collateralVault!,
       quantity: params.quantity,
       minPayoutAmount: params.minPayoutAmount,
@@ -669,6 +693,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
     optionAccount: resolved.optionAccount,
     collateralPool: resolved.collateralPool,
     underlyingMint: resolved.underlyingMint!,
+    collateralMint,
     longMint: resolved.longMint,
     escrowLongAccount: resolved.escrowLongAccount!,
     premiumVault: resolved.premiumVault!,
@@ -676,7 +701,8 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
     switchboardQueue: getDefaultSwitchboardQueueAddress(network),
     buyer: params.buyer,
     buyerLongAccount: params.buyerLongAccount,
-    buyerPayoutAccount: params.buyerPayoutAccount,
+    buyerPayoutAccount,
+    buyerUnderlyingPayoutAccount,
     collateralVault: resolved.collateralVault!,
     quantity: params.quantity,
     minPayoutAmount: params.minPayoutAmount,

package/package.json

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

@@ -24,30 +24,51 @@ export function assertNonNegativeAmount(value: bigint | number, label: string):
   }
 }
 
+export type SettlementMode = "physical" | "cash";
+
 /**
- * Calculate required collateral for option position in token base units
- * Matches on-chain formula: ((qty / 1_000_000) * 100 * strike) / spot * 10^decimals
- * 
- * @param quantity - Option quantity in base units (1 contract = 1_000_000)
- * @param strikePrice - Strike price in USD
- * @param spotPrice - Current spot price of underlying in USD (from oracle)
- * @param tokenDecimals - Number of decimals for the underlying token (e.g., 9 for SOL)
- * @returns Required collateral in token base units
+ * Calculate required collateral in **collateral mint** base units.
+ * Matches on-chain `Vault::calculate_required_collateral`:
+ * `((qty / 1_000_000) * 100 * strike) / conversionPrice * 10^decimals`.
+ *
+ * - **Physical:** pass underlying oracle spot + underlying/collateral decimals.
+ * - **Cash** (e.g. USDC backing SOL): pass collateral USD price (~1 for stables) + collateral decimals.
  */
 export function calculateRequiredCollateral(
   quantity: bigint | number,
   strikePrice: number,
-  spotPrice: number,
-  tokenDecimals: number
+  conversionPrice: number,
+  tokenDecimals: number,
+  settlementMode: SettlementMode = "physical"
 ): number {
-  // Convert base units to contract count
+  if (conversionPrice <= 0 || !Number.isFinite(conversionPrice)) {
+    return Number.POSITIVE_INFINITY;
+  }
+
   const contracts = Number(quantity) / 1_000_000;
-  const contractSize = 100; // 1 contract = 100 units of underlying
-  
-  // USD value needed for collateral
+  const contractSize = 100;
   const usdRequired = contracts * contractSize * strikePrice;
-  
-  // Convert USD to token base units
   const baseUnits = 10 ** tokenDecimals;
-  return (usdRequired / spotPrice) * baseUnits;
+
+  if (settlementMode === "cash") {
+    return usdRequired * baseUnits;
+  }
+
+  return (usdRequired / conversionPrice) * baseUnits;
+}
+
+/** @deprecated Use `calculateRequiredCollateral` with explicit settlement mode. */
+export function calculateRequiredCollateralLegacy(
+  quantity: bigint | number,
+  strikePrice: number,
+  spotPrice: number,
+  tokenDecimals: number
+): number {
+  return calculateRequiredCollateral(
+    quantity,
+    strikePrice,
+    spotPrice,
+    tokenDecimals,
+    "physical"
+  );
 }

package/short/builders.ts

@@ -666,7 +666,9 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     "underlyingMint is required; ensure rpc is provided and option pool is initialized, or pass underlyingMint."
   );
 
-  const [vaultPda] = await deriveVaultPda(underlyingMint, params.programId);
+  const collateralMint =
+    resolved.collateralPoolData?.collateralMint ?? underlyingMint;
+  const [vaultPda] = await deriveVaultPda(collateralMint, params.programId);
   const vaultPdaStr = toAddress(vaultPda);
 
   const [writerPositionAddress] = await deriveWriterPositionPda(
@@ -733,9 +735,9 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     isWritable: true,
   }));
 
-  const omlpVault = await deriveAssociatedTokenAddress(vaultPda, underlyingMint);
+  const omlpVault = await deriveAssociatedTokenAddress(vaultPda, collateralMint);
   const feeWallet = vault
-    ? await deriveAssociatedTokenAddress(vault.feeWallet, underlyingMint)
+    ? await deriveAssociatedTokenAddress(vault.feeWallet, collateralMint)
     : undefined;
 
   // Theta-hedge model: if proportional debt cannot be covered by
@@ -795,10 +797,14 @@ export async function buildUnwindWriterUnsoldTransactionWithDerivation(
     "Option pool and collateral pool must exist; ensure rpc is provided and pools are initialized."
   );
 
+  const collateralMint =
+    resolved.collateralPoolData?.collateralMint ?? resolved.underlyingMint;
+  invariant(!!collateralMint, "collateral mint is required for unwind.");
+
   const [writerShortAccount, writerCollateralAccount, writerPosition] =
     await Promise.all([
       deriveAssociatedTokenAddress(params.writer, resolved.shortMint),
-      deriveAssociatedTokenAddress(params.writer, resolved.underlyingMint),
+      deriveAssociatedTokenAddress(params.writer, collateralMint),
       deriveWriterPositionPda(resolved.optionPool, params.writer, params.programId),
     ]);