@epicentral/sos-sdk 0.4.0-alpha.3 → 0.5.0-alpha.2

package/README.md

@@ -57,7 +57,7 @@ Additional modules:
 
 | Function | Description |
 |----------|-------------|
-| `buildOptionMintTransactionWithDerivation` | Builds option mint (write) transaction. |
+| `buildOptionMintTransactionWithDerivation` | Builds option mint (write) transaction. Supports multi-collateral: use `collateralMint` to back positions with any supported asset (USDC, BTC, SOL, etc.). |
 | `buildUnwindWriterUnsoldTransactionWithDerivation` | Builds unwind unsold transaction. |
 | `buildUnwindWriterUnsoldWithLoanRepayment` | **Unwind + repay pool loans in one tx.** Use when closing unsold shorts that borrowed from OMLP. |
 | `buildSyncWriterPositionTransaction` | Syncs writer position with pool accumulators. |
@@ -88,6 +88,63 @@ Borrow/repay for writers: use `buildOptionMintTransactionWithDerivation` (with v
 | `getCreateAssociatedTokenIdempotentInstructionWithAddress` | Creates ATA if missing (idempotent). |
 | `NATIVE_MINT` | WSOL mint address. |
 
+## Multi-Collateral Settlement
+
+The SDK supports universal multi-collateral settlement, allowing writers to use ANY supported asset as collateral for options (not just the underlying). This enables:
+
+- **Capital Efficiency**: Writers use whatever assets they hold (USDC, BTC, SOL, BONK, etc.)
+- **No Forced Conversions**: No swap fees or slippage to get the "correct" collateral
+- **Lender Flexibility**: Lend any supported asset, earn yield in that asset
+
+### How it works
+
+When minting an option, specify `collateralMint` to choose the backing asset:
+
+```ts
+import {
+  buildOptionMintTransactionWithDerivation,
+  OptionType,
+} from "@epicentral/sos-sdk";
+
+// Write SOL calls backed by USDC
+const tx = await buildOptionMintTransactionWithDerivation({
+  underlyingAsset: SOL_MINT,
+  optionType: OptionType.Call,
+  strikePrice: 150.0,
+  expirationDate: BigInt(1735689600),
+  quantity: 1_000_000,           // 1 contract
+  underlyingMint: SOL_MINT,
+  underlyingSymbol: "SOL",
+  collateralMint: USDC_MINT,     // Back with USDC instead of SOL
+  makerCollateralAmount: 780_000_000,  // $780 (10% of $7,800)
+  borrowedAmount: 7_020_000_000,       // $7,020 (90% borrowed)
+  maker: walletAddress,
+  rpc,
+});
+```
+
+**Key points:**
+- `collateralMint` defaults to `underlyingMint` if not provided (backwards compatible)
+- OMLP vault routing is based on `collateralMint` - the vault must exist for the collateral asset
+- At settlement, buyers receive payout in the collateral currency that backed the position
+- The `WriterPosition` account tracks `collateralMint` and `settlementMint` for each position
+
+### Collateral Calculation
+
+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
+);
+// Returns: USDC base units needed
+```
+
 ## Unwind with Loan Repayment
 
 When a writer unwinds an unsold short that had borrowed from the OMLP pool, the program repays proportionally to the unwind ratio inside `unwind_writer_unsold`:
@@ -260,3 +317,28 @@ PDAs, fetchers, and builders are exported from the package root.
 ## Program Compatibility
 
 The SDK targets the Solana Option Standard program. Use `PROGRAM_ID` (or `getProgramId()`) from the package for the program address. Pass `programId` in builder params when using a different deployment.
+
+## Collateral Calculation Helper
+
+The SDK exports `calculateRequiredCollateral` for pre-flight collateral estimation:
+
+```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)
+  9                // Token decimals (9 for SOL)
+);
+// 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
+```
+
+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/client/lookup-table.ts

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

package/generated/accounts/positionAccount.ts

@@ -62,6 +62,12 @@ export type PositionAccount = {
   isClosed: boolean;
   isExercised: boolean;
   pnl: bigint;
+  /**
+   * Collateral mint used for settlement (e.g., USDC, BTC, SOL)
+   * Tracks which currency the buyer will receive at exercise/close
+   * Matches the WriterPosition.collateral_mint of the writer(s) who filled this position
+   */
+  collateralMint: Address;
 };
 
 export type PositionAccountArgs = {
@@ -74,6 +80,12 @@ export type PositionAccountArgs = {
   isClosed: boolean;
   isExercised: boolean;
   pnl: number | bigint;
+  /**
+   * Collateral mint used for settlement (e.g., USDC, BTC, SOL)
+   * Tracks which currency the buyer will receive at exercise/close
+   * Matches the WriterPosition.collateral_mint of the writer(s) who filled this position
+   */
+  collateralMint: Address;
 };
 
 /** Gets the encoder for {@link PositionAccountArgs} account data. */
@@ -90,6 +102,7 @@ export function getPositionAccountEncoder(): FixedSizeEncoder<PositionAccountArg
       ["isClosed", getBooleanEncoder()],
       ["isExercised", getBooleanEncoder()],
       ["pnl", getI64Encoder()],
+      ["collateralMint", getAddressEncoder()],
     ]),
     (value) => ({ ...value, discriminator: POSITION_ACCOUNT_DISCRIMINATOR }),
   );
@@ -108,6 +121,7 @@ export function getPositionAccountDecoder(): FixedSizeDecoder<PositionAccount> {
     ["isClosed", getBooleanDecoder()],
     ["isExercised", getBooleanDecoder()],
     ["pnl", getI64Decoder()],
+    ["collateralMint", getAddressDecoder()],
   ]);
 }
 
@@ -183,5 +197,5 @@ export async function fetchAllMaybePositionAccount(
 }
 
 export function getPositionAccountSize(): number {
-  return 114;
+  return 146;
 }

package/generated/accounts/writerPosition.ts

@@ -63,6 +63,16 @@ export type WriterPosition = {
   optionPool: Address;
   /** Reference to the option account */
   optionAccount: Address;
+  /**
+   * Mint used for collateral backing this position (e.g., USDC, BTC, SOL)
+   * Can differ from the underlying asset - enables multi-collateral system
+   */
+  collateralMint: Address;
+  /**
+   * Mint used for settlement (same as collateral_mint)
+   * Buyers receive payout in this currency
+   */
+  settlementMint: Address;
   /** Total contracts written (minted) by this writer */
   writtenQty: bigint;
   /** Total contracts sold to buyers (open interest from this writer) */
@@ -115,6 +125,16 @@ export type WriterPositionArgs = {
   optionPool: Address;
   /** Reference to the option account */
   optionAccount: Address;
+  /**
+   * Mint used for collateral backing this position (e.g., USDC, BTC, SOL)
+   * Can differ from the underlying asset - enables multi-collateral system
+   */
+  collateralMint: Address;
+  /**
+   * Mint used for settlement (same as collateral_mint)
+   * Buyers receive payout in this currency
+   */
+  settlementMint: Address;
   /** Total contracts written (minted) by this writer */
   writtenQty: number | bigint;
   /** Total contracts sold to buyers (open interest from this writer) */
@@ -168,6 +188,8 @@ export function getWriterPositionEncoder(): FixedSizeEncoder<WriterPositionArgs>
       ["writerAuthority", getAddressEncoder()],
       ["optionPool", getAddressEncoder()],
       ["optionAccount", getAddressEncoder()],
+      ["collateralMint", getAddressEncoder()],
+      ["settlementMint", getAddressEncoder()],
       ["writtenQty", getU64Encoder()],
       ["soldQty", getU64Encoder()],
       ["unsoldQty", getU64Encoder()],
@@ -203,6 +225,8 @@ export function getWriterPositionDecoder(): FixedSizeDecoder<WriterPosition> {
     ["writerAuthority", getAddressDecoder()],
     ["optionPool", getAddressDecoder()],
     ["optionAccount", getAddressDecoder()],
+    ["collateralMint", getAddressDecoder()],
+    ["settlementMint", getAddressDecoder()],
     ["writtenQty", getU64Decoder()],
     ["soldQty", getU64Decoder()],
     ["unsoldQty", getU64Decoder()],
@@ -299,5 +323,5 @@ export async function fetchAllMaybeWriterPosition(
 }
 
 export function getWriterPositionSize(): number {
-  return 300;
+  return 364;
 }

package/generated/errors/optionProgram.ts

@@ -196,6 +196,12 @@ export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_WALLET_SOURCE_MISSING = 0x17c8;
 export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_INSUFFICIENT_TOTAL_FUNDS = 0x17c9; // 6089
 /** InsufficientCollateralVault: Collateral vault has insufficient funds for unwind collateral return */
 export const OPTION_PROGRAM_ERROR__INSUFFICIENT_COLLATERAL_VAULT = 0x17ca; // 6090
+/** InvalidVaultMint: Invalid vault mint - does not match expected collateral mint */
+export const OPTION_PROGRAM_ERROR__INVALID_VAULT_MINT = 0x17cb; // 6091
+/** InvalidCollateralMint: Invalid collateral mint - not supported or no vault exists */
+export const OPTION_PROGRAM_ERROR__INVALID_COLLATERAL_MINT = 0x17cc; // 6092
+/** CollateralMismatch: Collateral mint mismatch - position uses different collateral type */
+export const OPTION_PROGRAM_ERROR__COLLATERAL_MISMATCH = 0x17cd; // 6093
 
 export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__ACCOUNT_FROZEN
@@ -203,6 +209,7 @@ export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__ARITHMETIC_OVERFLOW
   | typeof OPTION_PROGRAM_ERROR__ARITHMETIC_UNDERFLOW
   | typeof OPTION_PROGRAM_ERROR__BATCH_SIZE_EXCEEDED
+  | typeof OPTION_PROGRAM_ERROR__COLLATERAL_MISMATCH
   | typeof OPTION_PROGRAM_ERROR__COLLATERAL_POOL_NOT_FOUND
   | typeof OPTION_PROGRAM_ERROR__CONTRACT_ALREADY_SETTLED
   | typeof OPTION_PROGRAM_ERROR__DIVISION_BY_ZERO
@@ -227,6 +234,7 @@ export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__INVALID_ACCOUNT
   | typeof OPTION_PROGRAM_ERROR__INVALID_AUTHORITY
   | typeof OPTION_PROGRAM_ERROR__INVALID_BUYER_AUTHORITY
+  | typeof OPTION_PROGRAM_ERROR__INVALID_COLLATERAL_MINT
   | typeof OPTION_PROGRAM_ERROR__INVALID_ESCROW_AUTHORITY
   | typeof OPTION_PROGRAM_ERROR__INVALID_ESCROW_MAKER
   | typeof OPTION_PROGRAM_ERROR__INVALID_ESCROW_MINT
@@ -248,6 +256,7 @@ export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__INVALID_TENOR
   | typeof OPTION_PROGRAM_ERROR__INVALID_TIME_TO_EXPIRATION
   | typeof OPTION_PROGRAM_ERROR__INVALID_UNDERLYING_PRICE
+  | typeof OPTION_PROGRAM_ERROR__INVALID_VAULT_MINT
   | typeof OPTION_PROGRAM_ERROR__INVALID_VOLATILITY
   | typeof OPTION_PROGRAM_ERROR__LOW_ORACLE_PRICE_CONFIDENCE
   | typeof OPTION_PROGRAM_ERROR__MARKET_CLOSED
@@ -298,6 +307,7 @@ if (process.env.NODE_ENV !== "production") {
     [OPTION_PROGRAM_ERROR__ARITHMETIC_OVERFLOW]: `Arithmetic overflow occurred`,
     [OPTION_PROGRAM_ERROR__ARITHMETIC_UNDERFLOW]: `Arithmetic underflow occurred`,
     [OPTION_PROGRAM_ERROR__BATCH_SIZE_EXCEEDED]: `Batch size exceeds maximum allowed (10 positions)`,
+    [OPTION_PROGRAM_ERROR__COLLATERAL_MISMATCH]: `Collateral mint mismatch - position uses different collateral type`,
     [OPTION_PROGRAM_ERROR__COLLATERAL_POOL_NOT_FOUND]: `Collateral pool does not exist`,
     [OPTION_PROGRAM_ERROR__CONTRACT_ALREADY_SETTLED]: `Contract already settled`,
     [OPTION_PROGRAM_ERROR__DIVISION_BY_ZERO]: `Division by zero`,
@@ -322,6 +332,7 @@ if (process.env.NODE_ENV !== "production") {
     [OPTION_PROGRAM_ERROR__INVALID_ACCOUNT]: `Invalid account - does not match expected account`,
     [OPTION_PROGRAM_ERROR__INVALID_AUTHORITY]: `Invalid authority - does not match escrow authority`,
     [OPTION_PROGRAM_ERROR__INVALID_BUYER_AUTHORITY]: `Invalid buyer authority`,
+    [OPTION_PROGRAM_ERROR__INVALID_COLLATERAL_MINT]: `Invalid collateral mint - not supported or no vault exists`,
     [OPTION_PROGRAM_ERROR__INVALID_ESCROW_AUTHORITY]: `Invalid escrow authority`,
     [OPTION_PROGRAM_ERROR__INVALID_ESCROW_MAKER]: `Escrow state maker does not match instruction maker`,
     [OPTION_PROGRAM_ERROR__INVALID_ESCROW_MINT]: `Escrow token account mint mismatch`,
@@ -343,6 +354,7 @@ if (process.env.NODE_ENV !== "production") {
     [OPTION_PROGRAM_ERROR__INVALID_TENOR]: `Invalid loan tenor`,
     [OPTION_PROGRAM_ERROR__INVALID_TIME_TO_EXPIRATION]: `Time to expiration must be positive`,
     [OPTION_PROGRAM_ERROR__INVALID_UNDERLYING_PRICE]: `Underlying price is invalid`,
+    [OPTION_PROGRAM_ERROR__INVALID_VAULT_MINT]: `Invalid vault mint - does not match expected collateral mint`,
     [OPTION_PROGRAM_ERROR__INVALID_VOLATILITY]: `Volatility must be greater than zero`,
     [OPTION_PROGRAM_ERROR__LOW_ORACLE_PRICE_CONFIDENCE]: `Oracle price confidence is too low`,
     [OPTION_PROGRAM_ERROR__MARKET_CLOSED]: `Market is closed`,

package/generated/instructions/optionMint.ts

@@ -79,6 +79,7 @@ export type OptionMintInstruction<
   TAccountShortMetadataAccount extends string | AccountMeta<string> = string,
   TAccountMarketData extends string | AccountMeta<string> = string,
   TAccountUnderlyingMint extends string | AccountMeta<string> = string,
+  TAccountCollateralMint extends string | AccountMeta<string> = string,
   TAccountOptionPool extends string | AccountMeta<string> = string,
   TAccountEscrowLongAccount extends string | AccountMeta<string> = string,
   TAccountPremiumVault extends string | AccountMeta<string> = string,
@@ -92,6 +93,7 @@ export type OptionMintInstruction<
   TAccountEscrowAuthority extends string | AccountMeta<string> = string,
   TAccountEscrowTokenAccount extends string | AccountMeta<string> = string,
   TAccountPoolLoan extends string | AccountMeta<string> = string,
+  TAccountPriceUpdate extends string | AccountMeta<string> = string,
   TAccountMaker extends string | AccountMeta<string> = string,
   TAccountTokenProgram extends string | AccountMeta<string> =
     "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
@@ -138,6 +140,9 @@ export type OptionMintInstruction<
       TAccountUnderlyingMint extends string
         ? ReadonlyAccount<TAccountUnderlyingMint>
         : TAccountUnderlyingMint,
+      TAccountCollateralMint extends string
+        ? ReadonlyAccount<TAccountCollateralMint>
+        : TAccountCollateralMint,
       TAccountOptionPool extends string
         ? WritableAccount<TAccountOptionPool>
         : TAccountOptionPool,
@@ -177,6 +182,9 @@ export type OptionMintInstruction<
       TAccountPoolLoan extends string
         ? WritableAccount<TAccountPoolLoan>
         : TAccountPoolLoan,
+      TAccountPriceUpdate extends string
+        ? ReadonlyAccount<TAccountPriceUpdate>
+        : TAccountPriceUpdate,
       TAccountMaker extends string
         ? WritableSignerAccount<TAccountMaker> &
             AccountSignerMeta<TAccountMaker>
@@ -208,6 +216,7 @@ export type OptionMintInstructionData = {
   quantity: bigint;
   underlyingAsset: Address;
   underlyingSymbol: string;
+  collateralMint: Address;
   makerCollateralAmount: bigint;
   borrowedAmount: bigint;
 };
@@ -219,6 +228,7 @@ export type OptionMintInstructionDataArgs = {
   quantity: number | bigint;
   underlyingAsset: Address;
   underlyingSymbol: string;
+  collateralMint: Address;
   makerCollateralAmount: number | bigint;
   borrowedAmount: number | bigint;
 };
@@ -236,6 +246,7 @@ export function getOptionMintInstructionDataEncoder(): Encoder<OptionMintInstruc
         "underlyingSymbol",
         addEncoderSizePrefix(getUtf8Encoder(), getU32Encoder()),
       ],
+      ["collateralMint", getAddressEncoder()],
       ["makerCollateralAmount", getU64Encoder()],
       ["borrowedAmount", getU64Encoder()],
     ]),
@@ -255,6 +266,7 @@ export function getOptionMintInstructionDataDecoder(): Decoder<OptionMintInstruc
       "underlyingSymbol",
       addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder()),
     ],
+    ["collateralMint", getAddressDecoder()],
     ["makerCollateralAmount", getU64Decoder()],
     ["borrowedAmount", getU64Decoder()],
   ]);
@@ -281,6 +293,7 @@ export type OptionMintAsyncInput<
   TAccountShortMetadataAccount extends string = string,
   TAccountMarketData extends string = string,
   TAccountUnderlyingMint extends string = string,
+  TAccountCollateralMint extends string = string,
   TAccountOptionPool extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
@@ -294,6 +307,7 @@ export type OptionMintAsyncInput<
   TAccountEscrowAuthority extends string = string,
   TAccountEscrowTokenAccount extends string = string,
   TAccountPoolLoan extends string = string,
+  TAccountPriceUpdate extends string = string,
   TAccountMaker extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountAssociatedTokenProgram extends string = string,
@@ -325,8 +339,14 @@ export type OptionMintAsyncInput<
   shortMetadataAccount: Address<TAccountShortMetadataAccount>;
   /** Market data account - provides baseline historical volatility for initial IV */
   marketData?: Address<TAccountMarketData>;
-  /** Underlying asset mint (e.g., WSOL) - required for collateral and pool initialization */
+  /** Underlying asset mint (e.g., WSOL) - required for pricing and pool initialization */
   underlyingMint: Address<TAccountUnderlyingMint>;
+  /**
+   * Collateral mint (e.g., USDC, BTC, SOL) - Writer's choice for backing the position
+   * Can differ from underlying_mint - enables multi-collateral settlement
+   * OMLP vault routing is based on this mint
+   */
+  collateralMint: Address<TAccountCollateralMint>;
   /** Option pool - aggregated liquidity pool for this option */
   optionPool?: Address<TAccountOptionPool>;
   /** Pool's escrow for holding LONG tokens (for buyers to purchase) */
@@ -353,6 +373,11 @@ export type OptionMintAsyncInput<
   escrowTokenAccount?: Address<TAccountEscrowTokenAccount>;
   /** Pool loan account (optional - only required if borrowing) */
   poolLoan?: Address<TAccountPoolLoan>;
+  /**
+   * Pyth price update account for collateral calculation
+   * Required to convert USD collateral requirement to token units
+   */
+  priceUpdate: Address<TAccountPriceUpdate>;
   maker: TransactionSigner<TAccountMaker>;
   tokenProgram?: Address<TAccountTokenProgram>;
   associatedTokenProgram?: Address<TAccountAssociatedTokenProgram>;
@@ -365,6 +390,7 @@ export type OptionMintAsyncInput<
   quantity: OptionMintInstructionDataArgs["quantity"];
   underlyingAsset: OptionMintInstructionDataArgs["underlyingAsset"];
   underlyingSymbol: OptionMintInstructionDataArgs["underlyingSymbol"];
+  collateralMintArg: OptionMintInstructionDataArgs["collateralMint"];
   makerCollateralAmount: OptionMintInstructionDataArgs["makerCollateralAmount"];
   borrowedAmount: OptionMintInstructionDataArgs["borrowedAmount"];
 };
@@ -380,6 +406,7 @@ export async function getOptionMintInstructionAsync<
   TAccountShortMetadataAccount extends string,
   TAccountMarketData extends string,
   TAccountUnderlyingMint extends string,
+  TAccountCollateralMint extends string,
   TAccountOptionPool extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
@@ -393,6 +420,7 @@ export async function getOptionMintInstructionAsync<
   TAccountEscrowAuthority extends string,
   TAccountEscrowTokenAccount extends string,
   TAccountPoolLoan extends string,
+  TAccountPriceUpdate extends string,
   TAccountMaker extends string,
   TAccountTokenProgram extends string,
   TAccountAssociatedTokenProgram extends string,
@@ -412,6 +440,7 @@ export async function getOptionMintInstructionAsync<
     TAccountShortMetadataAccount,
     TAccountMarketData,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountOptionPool,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -425,6 +454,7 @@ export async function getOptionMintInstructionAsync<
     TAccountEscrowAuthority,
     TAccountEscrowTokenAccount,
     TAccountPoolLoan,
+    TAccountPriceUpdate,
     TAccountMaker,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -446,6 +476,7 @@ export async function getOptionMintInstructionAsync<
     TAccountShortMetadataAccount,
     TAccountMarketData,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountOptionPool,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -459,6 +490,7 @@ export async function getOptionMintInstructionAsync<
     TAccountEscrowAuthority,
     TAccountEscrowTokenAccount,
     TAccountPoolLoan,
+    TAccountPriceUpdate,
     TAccountMaker,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -495,6 +527,7 @@ export async function getOptionMintInstructionAsync<
     },
     marketData: { value: input.marketData ?? null, isWritable: false },
     underlyingMint: { value: input.underlyingMint ?? null, isWritable: false },
+    collateralMint: { value: input.collateralMint ?? null, isWritable: false },
     optionPool: { value: input.optionPool ?? null, isWritable: true },
     escrowLongAccount: {
       value: input.escrowLongAccount ?? null,
@@ -523,6 +556,7 @@ export async function getOptionMintInstructionAsync<
       isWritable: true,
     },
     poolLoan: { value: input.poolLoan ?? null, isWritable: true },
+    priceUpdate: { value: input.priceUpdate ?? null, isWritable: false },
     maker: { value: input.maker ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
     associatedTokenProgram: {
@@ -542,7 +576,7 @@ export async function getOptionMintInstructionAsync<
   >;
 
   // Original args.
-  const args = { ...input };
+  const args = { ...input, collateralMint: input.collateralMintArg };
 
   // Resolve default values.
   if (!accounts.optionAccount.value) {
@@ -771,6 +805,7 @@ export async function getOptionMintInstructionAsync<
       getAccountMeta(accounts.shortMetadataAccount),
       getAccountMeta(accounts.marketData),
       getAccountMeta(accounts.underlyingMint),
+      getAccountMeta(accounts.collateralMint),
       getAccountMeta(accounts.optionPool),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
@@ -784,6 +819,7 @@ export async function getOptionMintInstructionAsync<
       getAccountMeta(accounts.escrowAuthority),
       getAccountMeta(accounts.escrowTokenAccount),
       getAccountMeta(accounts.poolLoan),
+      getAccountMeta(accounts.priceUpdate),
       getAccountMeta(accounts.maker),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.associatedTokenProgram),
@@ -807,6 +843,7 @@ export async function getOptionMintInstructionAsync<
     TAccountShortMetadataAccount,
     TAccountMarketData,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountOptionPool,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -820,6 +857,7 @@ export async function getOptionMintInstructionAsync<
     TAccountEscrowAuthority,
     TAccountEscrowTokenAccount,
     TAccountPoolLoan,
+    TAccountPriceUpdate,
     TAccountMaker,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -840,6 +878,7 @@ export type OptionMintInput<
   TAccountShortMetadataAccount extends string = string,
   TAccountMarketData extends string = string,
   TAccountUnderlyingMint extends string = string,
+  TAccountCollateralMint extends string = string,
   TAccountOptionPool extends string = string,
   TAccountEscrowLongAccount extends string = string,
   TAccountPremiumVault extends string = string,
@@ -853,6 +892,7 @@ export type OptionMintInput<
   TAccountEscrowAuthority extends string = string,
   TAccountEscrowTokenAccount extends string = string,
   TAccountPoolLoan extends string = string,
+  TAccountPriceUpdate extends string = string,
   TAccountMaker extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountAssociatedTokenProgram extends string = string,
@@ -884,8 +924,14 @@ export type OptionMintInput<
   shortMetadataAccount: Address<TAccountShortMetadataAccount>;
   /** Market data account - provides baseline historical volatility for initial IV */
   marketData: Address<TAccountMarketData>;
-  /** Underlying asset mint (e.g., WSOL) - required for collateral and pool initialization */
+  /** Underlying asset mint (e.g., WSOL) - required for pricing and pool initialization */
   underlyingMint: Address<TAccountUnderlyingMint>;
+  /**
+   * Collateral mint (e.g., USDC, BTC, SOL) - Writer's choice for backing the position
+   * Can differ from underlying_mint - enables multi-collateral settlement
+   * OMLP vault routing is based on this mint
+   */
+  collateralMint: Address<TAccountCollateralMint>;
   /** Option pool - aggregated liquidity pool for this option */
   optionPool: Address<TAccountOptionPool>;
   /** Pool's escrow for holding LONG tokens (for buyers to purchase) */
@@ -912,6 +958,11 @@ export type OptionMintInput<
   escrowTokenAccount?: Address<TAccountEscrowTokenAccount>;
   /** Pool loan account (optional - only required if borrowing) */
   poolLoan?: Address<TAccountPoolLoan>;
+  /**
+   * Pyth price update account for collateral calculation
+   * Required to convert USD collateral requirement to token units
+   */
+  priceUpdate: Address<TAccountPriceUpdate>;
   maker: TransactionSigner<TAccountMaker>;
   tokenProgram?: Address<TAccountTokenProgram>;
   associatedTokenProgram?: Address<TAccountAssociatedTokenProgram>;
@@ -924,6 +975,7 @@ export type OptionMintInput<
   quantity: OptionMintInstructionDataArgs["quantity"];
   underlyingAsset: OptionMintInstructionDataArgs["underlyingAsset"];
   underlyingSymbol: OptionMintInstructionDataArgs["underlyingSymbol"];
+  collateralMintArg: OptionMintInstructionDataArgs["collateralMint"];
   makerCollateralAmount: OptionMintInstructionDataArgs["makerCollateralAmount"];
   borrowedAmount: OptionMintInstructionDataArgs["borrowedAmount"];
 };
@@ -939,6 +991,7 @@ export function getOptionMintInstruction<
   TAccountShortMetadataAccount extends string,
   TAccountMarketData extends string,
   TAccountUnderlyingMint extends string,
+  TAccountCollateralMint extends string,
   TAccountOptionPool extends string,
   TAccountEscrowLongAccount extends string,
   TAccountPremiumVault extends string,
@@ -952,6 +1005,7 @@ export function getOptionMintInstruction<
   TAccountEscrowAuthority extends string,
   TAccountEscrowTokenAccount extends string,
   TAccountPoolLoan extends string,
+  TAccountPriceUpdate extends string,
   TAccountMaker extends string,
   TAccountTokenProgram extends string,
   TAccountAssociatedTokenProgram extends string,
@@ -971,6 +1025,7 @@ export function getOptionMintInstruction<
     TAccountShortMetadataAccount,
     TAccountMarketData,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountOptionPool,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -984,6 +1039,7 @@ export function getOptionMintInstruction<
     TAccountEscrowAuthority,
     TAccountEscrowTokenAccount,
     TAccountPoolLoan,
+    TAccountPriceUpdate,
     TAccountMaker,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -1004,6 +1060,7 @@ export function getOptionMintInstruction<
   TAccountShortMetadataAccount,
   TAccountMarketData,
   TAccountUnderlyingMint,
+  TAccountCollateralMint,
   TAccountOptionPool,
   TAccountEscrowLongAccount,
   TAccountPremiumVault,
@@ -1017,6 +1074,7 @@ export function getOptionMintInstruction<
   TAccountEscrowAuthority,
   TAccountEscrowTokenAccount,
   TAccountPoolLoan,
+  TAccountPriceUpdate,
   TAccountMaker,
   TAccountTokenProgram,
   TAccountAssociatedTokenProgram,
@@ -1052,6 +1110,7 @@ export function getOptionMintInstruction<
     },
     marketData: { value: input.marketData ?? null, isWritable: false },
     underlyingMint: { value: input.underlyingMint ?? null, isWritable: false },
+    collateralMint: { value: input.collateralMint ?? null, isWritable: false },
     optionPool: { value: input.optionPool ?? null, isWritable: true },
     escrowLongAccount: {
       value: input.escrowLongAccount ?? null,
@@ -1080,6 +1139,7 @@ export function getOptionMintInstruction<
       isWritable: true,
     },
     poolLoan: { value: input.poolLoan ?? null, isWritable: true },
+    priceUpdate: { value: input.priceUpdate ?? null, isWritable: false },
     maker: { value: input.maker ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
     associatedTokenProgram: {
@@ -1099,7 +1159,7 @@ export function getOptionMintInstruction<
   >;
 
   // Original args.
-  const args = { ...input };
+  const args = { ...input, collateralMint: input.collateralMintArg };
 
   // Resolve default values.
   if (!accounts.tokenProgram.value) {
@@ -1136,6 +1196,7 @@ export function getOptionMintInstruction<
       getAccountMeta(accounts.shortMetadataAccount),
       getAccountMeta(accounts.marketData),
       getAccountMeta(accounts.underlyingMint),
+      getAccountMeta(accounts.collateralMint),
       getAccountMeta(accounts.optionPool),
       getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.premiumVault),
@@ -1149,6 +1210,7 @@ export function getOptionMintInstruction<
       getAccountMeta(accounts.escrowAuthority),
       getAccountMeta(accounts.escrowTokenAccount),
       getAccountMeta(accounts.poolLoan),
+      getAccountMeta(accounts.priceUpdate),
       getAccountMeta(accounts.maker),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.associatedTokenProgram),
@@ -1172,6 +1234,7 @@ export function getOptionMintInstruction<
     TAccountShortMetadataAccount,
     TAccountMarketData,
     TAccountUnderlyingMint,
+    TAccountCollateralMint,
     TAccountOptionPool,
     TAccountEscrowLongAccount,
     TAccountPremiumVault,
@@ -1185,6 +1248,7 @@ export function getOptionMintInstruction<
     TAccountEscrowAuthority,
     TAccountEscrowTokenAccount,
     TAccountPoolLoan,
+    TAccountPriceUpdate,
     TAccountMaker,
     TAccountTokenProgram,
     TAccountAssociatedTokenProgram,
@@ -1224,40 +1288,51 @@ export type ParsedOptionMintInstruction<
     shortMetadataAccount: TAccountMetas[7];
     /** Market data account - provides baseline historical volatility for initial IV */
     marketData: TAccountMetas[8];
-    /** Underlying asset mint (e.g., WSOL) - required for collateral and pool initialization */
+    /** Underlying asset mint (e.g., WSOL) - required for pricing and pool initialization */
     underlyingMint: TAccountMetas[9];
+    /**
+     * Collateral mint (e.g., USDC, BTC, SOL) - Writer's choice for backing the position
+     * Can differ from underlying_mint - enables multi-collateral settlement
+     * OMLP vault routing is based on this mint
+     */
+    collateralMint: TAccountMetas[10];
     /** Option pool - aggregated liquidity pool for this option */
-    optionPool: TAccountMetas[10];
+    optionPool: TAccountMetas[11];
     /** Pool's escrow for holding LONG tokens (for buyers to purchase) */
-    escrowLongAccount: TAccountMetas[11];
+    escrowLongAccount: TAccountMetas[12];
     /** Pool's vault for collecting premiums (in underlying asset) */
-    premiumVault: TAccountMetas[12];
+    premiumVault: TAccountMetas[13];
     /** Collateral pool for this option */
-    collateralPool: TAccountMetas[13];
+    collateralPool: TAccountMetas[14];
     /** Collateral vault (ATA holding collateral) */
-    collateralVault: TAccountMetas[14];
+    collateralVault: TAccountMetas[15];
     /** Maker's collateral account (source of maker's own collateral) */
-    makerCollateralAccount: TAccountMetas[15];
+    makerCollateralAccount: TAccountMetas[16];
     /** Writer's unified position account (single source of truth) */
-    writerPosition: TAccountMetas[16];
+    writerPosition: TAccountMetas[17];
     /** OMLP vault (optional - only required if borrowing) */
-    vault?: TAccountMetas[17] | undefined;
+    vault?: TAccountMetas[18] | undefined;
     /** Vault's token account (optional - only required if borrowing) */
-    vaultTokenAccount?: TAccountMetas[18] | undefined;
+    vaultTokenAccount?: TAccountMetas[19] | undefined;
     /** Escrow state PDA (optional - only required if borrowing) */
-    escrowState?: TAccountMetas[19] | undefined;
+    escrowState?: TAccountMetas[20] | undefined;
     /** Escrow authority PDA (optional - only required if borrowing) */
-    escrowAuthority?: TAccountMetas[20] | undefined;
+    escrowAuthority?: TAccountMetas[21] | undefined;
     /** Escrow token account (optional - only required if borrowing) */
-    escrowTokenAccount?: TAccountMetas[21] | undefined;
+    escrowTokenAccount?: TAccountMetas[22] | undefined;
     /** Pool loan account (optional - only required if borrowing) */
-    poolLoan?: TAccountMetas[22] | undefined;
-    maker: TAccountMetas[23];
-    tokenProgram: TAccountMetas[24];
-    associatedTokenProgram: TAccountMetas[25];
-    tokenMetadataProgram: TAccountMetas[26];
-    systemProgram: TAccountMetas[27];
-    rent: TAccountMetas[28];
+    poolLoan?: TAccountMetas[23] | undefined;
+    /**
+     * Pyth price update account for collateral calculation
+     * Required to convert USD collateral requirement to token units
+     */
+    priceUpdate: TAccountMetas[24];
+    maker: TAccountMetas[25];
+    tokenProgram: TAccountMetas[26];
+    associatedTokenProgram: TAccountMetas[27];
+    tokenMetadataProgram: TAccountMetas[28];
+    systemProgram: TAccountMetas[29];
+    rent: TAccountMetas[30];
   };
   data: OptionMintInstructionData;
 };
@@ -1270,7 +1345,7 @@ export function parseOptionMintInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedOptionMintInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 29) {
+  if (instruction.accounts.length < 31) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -1299,6 +1374,7 @@ export function parseOptionMintInstruction<
       shortMetadataAccount: getNextAccount(),
       marketData: getNextAccount(),
       underlyingMint: getNextAccount(),
+      collateralMint: getNextAccount(),
       optionPool: getNextAccount(),
       escrowLongAccount: getNextAccount(),
       premiumVault: getNextAccount(),
@@ -1312,6 +1388,7 @@ export function parseOptionMintInstruction<
       escrowAuthority: getNextOptionalAccount(),
       escrowTokenAccount: getNextOptionalAccount(),
       poolLoan: getNextOptionalAccount(),
+      priceUpdate: getNextAccount(),
       maker: getNextAccount(),
       tokenProgram: getNextAccount(),
       associatedTokenProgram: getNextAccount(),

package/package.json

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

package/shared/amounts.ts

@@ -24,9 +24,30 @@ export function assertNonNegativeAmount(value: bigint | number, label: string):
   }
 }
 
+/**
+ * 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
+ */
 export function calculateRequiredCollateral(
   quantity: bigint | number,
-  strikePrice: number
+  strikePrice: number,
+  spotPrice: number,
+  tokenDecimals: number
 ): number {
-  return Number(quantity) * 100 * strikePrice;
+  // Convert base units to contract count
+  const contracts = Number(quantity) / 1_000_000;
+  const contractSize = 100; // 1 contract = 100 units of underlying
+  
+  // USD value needed for collateral
+  const usdRequired = contracts * contractSize * strikePrice;
+  
+  // Convert USD to token base units
+  const baseUnits = 10 ** tokenDecimals;
+  return (usdRequired / spotPrice) * baseUnits;
 }

package/short/builders.ts

@@ -38,11 +38,22 @@ export interface BuildOptionMintParams {
   quantity: bigint | number;
   underlyingAsset: AddressLike;
   underlyingSymbol: string;
+  /**
+   * Collateral mint (e.g., USDC, BTC, SOL) - Writer's choice for backing the position.
+   * Can differ from underlying asset - enables multi-collateral settlement.
+   * OMLP vault routing is based on this mint. Defaults to underlyingMint if not provided.
+   */
+  collateralMint?: AddressLike;
   makerCollateralAmount: bigint | number;
   borrowedAmount: bigint | number;
   maker: AddressLike;
   makerCollateralAccount: AddressLike;
   underlyingMint: AddressLike;
+  /**
+   * Pyth price update account for collateral calculation.
+   * Required to convert USD collateral requirement to token units.
+   */
+  priceUpdate: AddressLike;
   longMetadataAccount?: AddressLike;
   shortMetadataAccount?: AddressLike;
   optionAccount?: AddressLike;
@@ -162,6 +173,7 @@ export async function buildOptionMintInstruction(
     shortMetadataAccount: toAddress(shortMetadata!),
     marketData: params.marketData ? toAddress(params.marketData) : undefined,
     underlyingMint: toAddress(params.underlyingMint),
+    collateralMint: toAddress(params.collateralMint ?? params.underlyingMint),
     optionPool: params.optionPool ? toAddress(params.optionPool) : undefined,
     escrowLongAccount: params.escrowLongAccount
       ? toAddress(params.escrowLongAccount)
@@ -181,6 +193,7 @@ export async function buildOptionMintInstruction(
       ? toAddress(params.escrowTokenAccount)
       : undefined,
     poolLoan: params.poolLoan ? toAddress(params.poolLoan) : undefined,
+    priceUpdate: toAddress(params.priceUpdate),
     maker: toAddress(params.maker) as any,
     optionType: params.optionType,
     strikePrice: params.strikePrice,
@@ -188,6 +201,7 @@ export async function buildOptionMintInstruction(
     quantity: params.quantity,
     underlyingAsset: toAddress(params.underlyingAsset),
     underlyingSymbol: params.underlyingSymbol,
+    collateralMintArg: toAddress(params.collateralMint ?? params.underlyingMint),
     makerCollateralAmount: params.makerCollateralAmount,
     borrowedAmount: params.borrowedAmount,
   });
@@ -210,11 +224,25 @@ export interface BuildOptionMintTransactionWithDerivationParams {
   quantity: bigint | number;
   underlyingMint: AddressLike;
   underlyingSymbol: string;
+  /**
+   * Collateral mint (e.g., USDC, BTC, SOL) - Writer's choice for backing the position.
+   * Can differ from underlying asset - enables multi-collateral settlement.
+   * OMLP vault routing is based on this mint. Defaults to underlyingMint if not provided.
+   */
+  collateralMint?: AddressLike;
   makerCollateralAmount: bigint | number;
   borrowedAmount: bigint | number;
   maker: AddressLike;
-  /** Optional. When omitted, the SDK derives the maker's collateral ATA for underlyingMint. */
+  /**
+   * Optional. When omitted, the SDK derives the maker's collateral ATA for collateralMint
+   * (or underlyingMint if collateralMint is not provided).
+   */
   makerCollateralAccount?: AddressLike;
+  /**
+   * Pyth price update account for collateral calculation.
+   * Required to convert USD collateral requirement to token units.
+   */
+  priceUpdate: AddressLike;
   rpc: KitRpc;
   programId?: AddressLike;
   vault?: AddressLike;
@@ -258,18 +286,20 @@ export async function buildOptionMintTransactionWithDerivation(
   });
 
   const underlyingMint = resolved.underlyingMint ?? params.underlyingMint;
+  const collateralMint = params.collateralMint ?? underlyingMint;
   const [makerLongAccount, makerShortAccount] = await Promise.all([
     deriveAssociatedTokenAddress(params.maker, resolved.longMint),
     deriveAssociatedTokenAddress(params.maker, resolved.shortMint),
   ]);
   const makerCollateralAccount = params.makerCollateralAccount
     ? toAddress(params.makerCollateralAccount)
-    : await deriveAssociatedTokenAddress(params.maker, underlyingMint);
+    : await deriveAssociatedTokenAddress(params.maker, collateralMint);
 
   const tx = await buildOptionMintTransaction({
     ...params,
     underlyingAsset: params.underlyingAsset,
     underlyingMint,
+    collateralMint,
     makerCollateralAccount,
     optionAccount: resolved.optionAccount,
     longMint: resolved.longMint,
@@ -296,7 +326,7 @@ export async function buildOptionMintTransactionWithDerivation(
     await getCreateAssociatedTokenIdempotentInstructionWithAddress(
       params.maker,
       params.maker,
-      underlyingMint,
+      collateralMint,
       makerCollateralAccount
     );