@epicentral/sos-sdk 0.11.2-beta → 0.12.1-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)
@@ -431,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`:
@@ -567,19 +579,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

@@ -65,9 +65,11 @@ 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,
+  TAccountCollateralPool extends string | AccountMeta<string> = string,
   TAccountBuyer extends string | AccountMeta<string> = string,
   TAccountTokenProgram extends string | AccountMeta<string> =
     "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
@@ -110,6 +112,9 @@ export type BuyFromPoolInstruction<
       TAccountBuyerOptionAccount extends string
         ? WritableAccount<TAccountBuyerOptionAccount>
         : TAccountBuyerOptionAccount,
+      TAccountPaymentMint extends string
+        ? ReadonlyAccount<TAccountPaymentMint>
+        : TAccountPaymentMint,
       TAccountBuyerPaymentAccount extends string
         ? WritableAccount<TAccountBuyerPaymentAccount>
         : TAccountBuyerPaymentAccount,
@@ -119,6 +124,9 @@ export type BuyFromPoolInstruction<
       TAccountPremiumVault extends string
         ? WritableAccount<TAccountPremiumVault>
         : TAccountPremiumVault,
+      TAccountCollateralPool extends string
+        ? ReadonlyAccount<TAccountCollateralPool>
+        : TAccountCollateralPool,
       TAccountBuyer extends string
         ? WritableSignerAccount<TAccountBuyer> &
             AccountSignerMeta<TAccountBuyer>
@@ -187,9 +195,11 @@ 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,
+  TAccountCollateralPool extends string = string,
   TAccountBuyer extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountAssociatedTokenProgram extends string = string,
@@ -215,12 +225,16 @@ 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) */
   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>;
@@ -240,9 +254,11 @@ 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,
+  TAccountCollateralPool extends string,
   TAccountBuyer extends string,
   TAccountTokenProgram extends string,
   TAccountAssociatedTokenProgram extends string,
@@ -260,9 +276,11 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -282,9 +300,11 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -319,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,
@@ -328,6 +349,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 +404,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">;
@@ -408,9 +444,11 @@ 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),
+      getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.buyer),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.associatedTokenProgram),
@@ -432,9 +470,11 @@ export async function getBuyFromPoolInstructionAsync<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -453,9 +493,11 @@ 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,
+  TAccountCollateralPool extends string = string,
   TAccountBuyer extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountAssociatedTokenProgram extends string = string,
@@ -481,12 +523,16 @@ 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) */
   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>;
@@ -506,9 +552,11 @@ export function getBuyFromPoolInstruction<
   TAccountInstructionsSysvar extends string,
   TAccountBuyerPosition extends string,
   TAccountBuyerOptionAccount extends string,
+  TAccountPaymentMint extends string,
   TAccountBuyerPaymentAccount extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
+  TAccountCollateralPool extends string,
   TAccountBuyer extends string,
   TAccountTokenProgram extends string,
   TAccountAssociatedTokenProgram extends string,
@@ -526,9 +574,11 @@ export function getBuyFromPoolInstruction<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -547,9 +597,11 @@ export function getBuyFromPoolInstruction<
   TAccountInstructionsSysvar,
   TAccountBuyerPosition,
   TAccountBuyerOptionAccount,
+  TAccountPaymentMint,
   TAccountBuyerPaymentAccount,
   TAccountEscrowLongAccount,
   TAccountPremiumVault,
+  TAccountCollateralPool,
   TAccountBuyer,
   TAccountTokenProgram,
   TAccountAssociatedTokenProgram,
@@ -583,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,
@@ -592,6 +645,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: {
@@ -643,9 +697,11 @@ export function getBuyFromPoolInstruction<
       getAccountMeta(accounts.instructionsSysvar),
       getAccountMeta(accounts.buyerPosition),
       getAccountMeta(accounts.buyerOptionAccount),
+      getAccountMeta(accounts.paymentMint),
       getAccountMeta(accounts.buyerPaymentAccount),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
+      getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.buyer),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.associatedTokenProgram),
@@ -667,9 +723,11 @@ export function getBuyFromPoolInstruction<
     TAccountInstructionsSysvar,
     TAccountBuyerPosition,
     TAccountBuyerOptionAccount,
+    TAccountPaymentMint,
     TAccountBuyerPaymentAccount,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
+    TAccountCollateralPool,
     TAccountBuyer,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -703,16 +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];
-    buyer: TAccountMetas[13];
-    tokenProgram: TAccountMetas[14];
-    associatedTokenProgram: TAccountMetas[15];
-    systemProgram: TAccountMetas[16];
+    premiumVault: TAccountMetas[13];
+    /** Collateral pool (settlement mint for buyer position tracking) */
+    collateralPool: TAccountMetas[14];
+    buyer: TAccountMetas[15];
+    tokenProgram: TAccountMetas[16];
+    associatedTokenProgram: TAccountMetas[17];
+    systemProgram: TAccountMetas[18];
   };
   data: BuyFromPoolInstructionData;
 };
@@ -725,7 +787,7 @@ export function parseBuyFromPoolInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedBuyFromPoolInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 17) {
+  if (instruction.accounts.length < 19) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -748,9 +810,11 @@ export function parseBuyFromPoolInstruction<
       instructionsSysvar: getNextAccount(),
       buyerPosition: getNextAccount(),
       buyerOptionAccount: getNextAccount(),
+      paymentMint: getNextAccount(),
       buyerPaymentAccount: getNextAccount(),
       escrowLongAccount: getNextAccount(),
       premiumVault: getNextAccount(),
+      collateralPool: getNextAccount(),
       buyer: getNextAccount(),
       tokenProgram: getNextAccount(),
       associatedTokenProgram: getNextAccount(),