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

package/long/builders.ts

@@ -36,6 +36,7 @@ import {
   inferSwitchboardNetwork,
   prependSwitchboardQuote,
 } from "../oracle/switchboard";
+import { deriveVolatilityQuoteAddressFromMarketData } from "../oracle/volatility-quote";
 import { fetchWriterPositionsForPool } from "../accounts/list";
 import { getGlobalTradeConfig } from "../shared/trade-config";
 
@@ -45,6 +46,8 @@ export interface BuildBuyFromPoolParams {
   longMint: AddressLike;
   underlyingMint: AddressLike;
   marketData: AddressLike;
+  /** Authority-updated Switchboard HV quote PDA (see deriveVolatilityQuoteAddressFromMarketData). */
+  volatilityQuoteAccount: AddressLike;
   /** Program `switchboard_queue` — use {@link getDefaultSwitchboardQueueAddress} for the cluster. */
   switchboardQueue: AddressLike;
   buyer: AddressLike;
@@ -92,6 +95,8 @@ export interface BuildCloseLongToPoolParams {
   escrowLongAccount: AddressLike;
   premiumVault: AddressLike;
   marketData: AddressLike;
+  /** Authority-updated Switchboard HV quote PDA (see deriveVolatilityQuoteAddressFromMarketData). */
+  volatilityQuoteAccount: AddressLike;
   switchboardQueue: AddressLike;
   buyer: AddressLike;
   buyerLongAccount: AddressLike;
@@ -131,6 +136,7 @@ export async function buildBuyFromPoolInstruction(
     longMint: toAddress(params.longMint),
     underlyingMint: toAddress(params.underlyingMint),
     marketData: toAddress(params.marketData),
+    volatilityQuoteAccount: toAddress(params.volatilityQuoteAccount),
     switchboardQueue: toAddress(params.switchboardQueue),
     buyer: toAddress(params.buyer) as any,
     buyerPosition: params.buyerPosition ? toAddress(params.buyerPosition) : undefined,
@@ -217,6 +223,8 @@ export interface BuildBuyFromPoolTransactionWithDerivationParams {
    * Use **1** if only SetComputeUnitLimit is prepended (e.g. `omitComputeUnitPriceInstruction`); **0** if no CU prepend.
    */
   switchboardQuoteInstructionIndex?: number;
+  /** Optional override — derived from on-chain market data when omitted. */
+  volatilityQuoteAccount?: AddressLike;
 }
 
 const DEFAULT_MARKET_ORDER_SLIPPAGE_BUFFER_BASE_UNITS = 500_000n;
@@ -303,12 +311,22 @@ export async function buildBuyFromPoolTransactionWithDerivation(
     }),
   ]);
 
+  const marketDataAccount = await fetchMarketDataAccount(params.rpc, resolved.marketData);
+  invariant(
+    !!marketDataAccount,
+    "Market data account not found for resolved option market."
+  );
+  const volatilityQuoteAccount =
+    params.volatilityQuoteAccount ??
+    deriveVolatilityQuoteAddressFromMarketData(marketDataAccount);
+
   const buyParams = {
     optionPool: resolved.optionPool,
     optionAccount: resolved.optionAccount,
     longMint: resolved.longMint,
     underlyingMint: resolved.underlyingMint!,
     marketData: resolved.marketData,
+    volatilityQuoteAccount,
     buyer: params.buyer,
     paymentMint: paymentAccounts.paymentMint,
     buyerPaymentAccount: paymentAccounts.buyerPaymentAccount,
@@ -321,11 +339,6 @@ export async function buildBuyFromPoolTransactionWithDerivation(
     remainingAccounts: params.remainingAccounts,
   };
 
-  const marketDataAccount = await fetchMarketDataAccount(params.rpc, resolved.marketData);
-  invariant(
-    !!marketDataAccount,
-    "Market data account not found for resolved option market."
-  );
   const feedIdHex = feedIdBytesToHex(
     Uint8Array.from(marketDataAccount.switchboardFeedId as unknown as Uint8Array)
   );
@@ -460,12 +473,22 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
   const maxPremiumAmount = quotePremium + slippageBuffer;
   assertPositiveAmount(maxPremiumAmount, "maxPremiumAmount");
 
+  const marketDataAccount = await fetchMarketDataAccount(params.rpc, resolved.marketData);
+  invariant(
+    !!marketDataAccount,
+    "Market data account not found for resolved option market."
+  );
+  const volatilityQuoteAccount =
+    params.volatilityQuoteAccount ??
+    deriveVolatilityQuoteAddressFromMarketData(marketDataAccount);
+
   const marketBuyParams = {
     optionPool: resolved.optionPool,
     optionAccount: resolved.optionAccount,
     longMint: resolved.longMint,
     underlyingMint: refetchedPool.underlyingMint,
     marketData: resolved.marketData,
+    volatilityQuoteAccount,
     buyer: params.buyer,
     paymentMint: paymentAccounts.paymentMint,
     buyerPaymentAccount: paymentAccounts.buyerPaymentAccount,
@@ -478,11 +501,6 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
     remainingAccounts,
   };
 
-  const marketDataAccount = await fetchMarketDataAccount(params.rpc, resolved.marketData);
-  invariant(
-    !!marketDataAccount,
-    "Market data account not found for resolved option market."
-  );
   const feedIdHex = feedIdBytesToHex(
     Uint8Array.from(marketDataAccount.switchboardFeedId as unknown as Uint8Array)
   );
@@ -541,6 +559,7 @@ export async function buildCloseLongToPoolInstruction(
     escrowLongAccount: toAddress(params.escrowLongAccount),
     premiumVault: toAddress(params.premiumVault),
     marketData: toAddress(params.marketData),
+    volatilityQuoteAccount: toAddress(params.volatilityQuoteAccount),
     switchboardQueue: toAddress(params.switchboardQueue),
     buyer: toAddress(params.buyer) as any,
     buyerLongAccount: toAddress(params.buyerLongAccount),
@@ -652,6 +671,8 @@ export interface BuildCloseLongToPoolTransactionWithDerivationParams {
    * OPX `sendInstructions` prepends only `SetComputeUnitLimit` before program ixs → default **1** (quote after CU limit).
    */
   switchboardQuoteInstructionIndex?: number;
+  /** Optional override — derived from on-chain market data when omitted. */
+  volatilityQuoteAccount?: AddressLike;
 }
 
 export async function buildCloseLongToPoolTransactionWithDerivation(
@@ -719,6 +740,9 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
     !!marketDataAccount,
     "Market data account not found for resolved option market."
   );
+  const volatilityQuoteAccount =
+    params.volatilityQuoteAccount ??
+    deriveVolatilityQuoteAddressFromMarketData(marketDataAccount);
   const feedIdHex = feedIdBytesToHex(
     Uint8Array.from(marketDataAccount.switchboardFeedId as unknown as Uint8Array)
   );
@@ -738,6 +762,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
       escrowLongAccount: resolved.escrowLongAccount!,
       premiumVault: resolved.premiumVault!,
       marketData: resolved.marketData,
+      volatilityQuoteAccount,
       switchboardQueue,
       buyer: params.buyer,
       buyerLongAccount: params.buyerLongAccount,
@@ -778,6 +803,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
     escrowLongAccount: resolved.escrowLongAccount!,
     premiumVault: resolved.premiumVault!,
     marketData: resolved.marketData,
+    volatilityQuoteAccount,
     switchboardQueue: getDefaultSwitchboardQueueAddress(network),
     buyer: params.buyer,
     buyerLongAccount: params.buyerLongAccount,

package/oracle/volatility-quote.ts

@@ -0,0 +1,65 @@
+import { PublicKey } from "@solana/web3.js";
+import { address, type Address } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike } from "../client/types";
+import type { MarketDataAccount } from "../generated/accounts/marketDataAccount";
+
+const ZERO_PUBKEY = "11111111111111111111111111111111";
+const QUOTE_PROGRAM_ID = new PublicKey("orac1eFjzWL5R3RbbdMV68K9H6TaCVVcL6LjvQQWAbz");
+const AUTHORITY_QUOTE_SCHEME_TAG = Buffer.from("AUTH");
+
+function feedIdBytes(feedId: MarketDataAccount["switchboardVolatilityFeedId"]): Uint8Array {
+  return Uint8Array.from(feedId);
+}
+
+function feedIdIsZero(feedId: MarketDataAccount["switchboardVolatilityFeedId"]): boolean {
+  const bytes = feedIdBytes(feedId);
+  return bytes.length === 32 && bytes.every((b) => b === 0);
+}
+
+export function isVolOracleEnabled(
+  marketData: Pick<
+    MarketDataAccount,
+    "switchboardVolatilityFeedId" | "volatilityQuoteAuthority"
+  >
+): boolean {
+  return (
+    !feedIdIsZero(marketData.switchboardVolatilityFeedId) &&
+    String(marketData.volatilityQuoteAuthority) !== ZERO_PUBKEY
+  );
+}
+
+/**
+ * Derives the Switchboard authority quote PDA for an HV feed.
+ */
+export function deriveVolatilityQuoteAddress(
+  authority: AddressLike,
+  switchboardVolatilityFeedId: MarketDataAccount["switchboardVolatilityFeedId"]
+): Address {
+  const authorityPk = new PublicKey(String(toAddress(authority)));
+  const feedHash = Buffer.from(feedIdBytes(switchboardVolatilityFeedId));
+  const [quoteAccount] = PublicKey.findProgramAddressSync(
+    [AUTHORITY_QUOTE_SCHEME_TAG, authorityPk.toBuffer(), feedHash],
+    QUOTE_PROGRAM_ID
+  );
+  return address(quoteAccount.toBase58());
+}
+
+/**
+ * When vol oracle is disabled on market data, returns the system program as a
+ * read-only placeholder (the program skips quote reads in that case).
+ */
+export function deriveVolatilityQuoteAddressFromMarketData(
+  marketData: Pick<
+    MarketDataAccount,
+    "volatilityQuoteAuthority" | "switchboardVolatilityFeedId"
+  >
+): Address {
+  if (!isVolOracleEnabled(marketData)) {
+    return address(ZERO_PUBKEY);
+  }
+  return deriveVolatilityQuoteAddress(
+    marketData.volatilityQuoteAuthority,
+    marketData.switchboardVolatilityFeedId
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.12.2-beta",
+  "version": "0.13.1-beta",
   "private": false,
   "description": "Solana Option Standard SDK. The frontend-first SDK for Native Options Trading on Solana. Created by Epicentral Labs.",
   "type": "module",
@@ -20,11 +20,17 @@
     "@solana-program/system": "^0.11.0",
     "@solana/compat": "^6.1.0",
     "@solana/kit": "^6.1.0",
+    "@solana/web3.js": "^1.98.0",
     "@switchboard-xyz/common": "^5.7.0",
     "@switchboard-xyz/on-demand": "^3.9.0",
     "bs58": "^6.0.0",
     "decimal.js": "^10.4.3"
   },
+  "overrides": {
+    "@switchboard-xyz/on-demand": {
+      "@switchboard-xyz/common": "$@switchboard-xyz/common"
+    }
+  },
   "scripts": {
     "typecheck": "tsc --project tsconfig.json --noEmit",
     "publish-beta": "dotenv -e .env -- pnpm publish --access public --tag beta",

package/shared/option-program-parser.ts

@@ -26,6 +26,7 @@ import {
   parseLiquidateWriterPositionInstruction,
   parseLiquidateWriterPositionRescueInstruction,
   parseMigrateCollateralPoolV1ToV2Instruction,
+  parseMigrateMarketDataVolOracleInstruction,
   parseOmlpCreateVaultInstruction,
   parseOmlpUpdateFeeWalletInstruction,
   parseOmlpUpdateInterestModelInstruction,
@@ -179,6 +180,11 @@ export function parseOptionProgramInstruction<
         parseLiquidateWriterPositionRescueInstruction(instruction),
         instructionType,
       );
+    case OptionProgramInstruction.MigrateMarketDataVolOracle:
+      return withInstructionType(
+        parseMigrateMarketDataVolOracleInstruction(instruction),
+        instructionType,
+      );
     case OptionProgramInstruction.MigrateCollateralPoolV1ToV2:
       return withInstructionType(
         parseMigrateCollateralPoolV1ToV2Instruction(instruction),

package/short/builders.ts

@@ -1,6 +1,7 @@
 import {
   getClaimBuyerSettlementInstructionAsync,
   getClaimMakerSettlementInstructionAsync,
+  getLiquidateWriterPositionInstructionAsync,
   getLiquidateWriterPositionRescueInstructionAsync,
   getOptionMintInstructionAsync,
   getPrepareBuyerSettlementInstructionAsync,
@@ -42,6 +43,7 @@ import {
   SLOT_HASHES_SYSVAR_ADDRESS,
   SWITCHBOARD_DEFAULT_DEVNET_QUEUE,
 } from "../oracle/switchboard";
+import { deriveVolatilityQuoteAddressFromMarketData } from "../oracle/volatility-quote";
 import { applySlippageBps } from "../long/quotes";
 import { getGlobalTradeConfig } from "../shared/trade-config";
 
@@ -75,6 +77,8 @@ export interface BuildOptionMintParams {
   makerLongAccount?: AddressLike;
   makerShortAccount?: AddressLike;
   marketData?: AddressLike;
+  /** Authority-updated Switchboard HV quote PDA (derived from market data when omitted). */
+  volatilityQuoteAccount?: AddressLike;
   optionPool?: AddressLike;
   escrowLongAccount?: AddressLike;
   premiumVault?: AddressLike;
@@ -240,6 +244,10 @@ export async function buildOptionMintInstruction(
     !!longMetadata && !!shortMetadata,
     "longMetadataAccount and shortMetadataAccount are required (or provide longMint/shortMint to derive)."
   );
+  invariant(
+    !!params.volatilityQuoteAccount,
+    "volatilityQuoteAccount is required (use buildOptionMintTransactionWithDerivation or deriveVolatilityQuoteAddressFromMarketData)."
+  );
 
   const kitInstruction = await getOptionMintInstructionAsync(
     {
@@ -256,6 +264,7 @@ export async function buildOptionMintInstruction(
       longMetadataAccount: toAddress(longMetadata!),
       shortMetadataAccount: toAddress(shortMetadata!),
       marketData: params.marketData ? toAddress(params.marketData) : undefined,
+      volatilityQuoteAccount: toAddress(params.volatilityQuoteAccount!),
       underlyingMint: toAddress(params.underlyingMint),
       collateralMint: toAddress(params.collateralMint ?? params.underlyingMint),
       optionPool: params.optionPool ? toAddress(params.optionPool) : undefined,
@@ -383,6 +392,8 @@ export interface BuildOptionMintTransactionWithDerivationParams {
    * under Solana's 1232-byte versioned-transaction limit when OMLP accounts are present.
    */
   skipCreateCollateralAta?: boolean;
+  /** Optional override — derived from on-chain market data when omitted. */
+  volatilityQuoteAccount?: AddressLike;
 }
 
 export async function buildOptionMintTransactionWithDerivation(
@@ -447,6 +458,9 @@ export async function buildOptionMintTransactionWithDerivation(
     !!marketDataAccount,
     "Market data account not found for resolved option market."
   );
+  const volatilityQuoteAccount =
+    params.volatilityQuoteAccount ??
+    deriveVolatilityQuoteAddressFromMarketData(marketDataAccount);
   const switchboardFeedId = feedIdBytesToHex(
     Uint8Array.from(marketDataAccount.switchboardFeedId as unknown as Uint8Array)
   );
@@ -514,6 +528,7 @@ export async function buildOptionMintTransactionWithDerivation(
     makerLongAccount,
     makerShortAccount,
     marketData: resolved.marketData,
+    volatilityQuoteAccount,
     optionPool: resolved.optionPool,
     escrowLongAccount: resolved.escrowLongAccount,
     premiumVault: resolved.premiumVault,
@@ -957,6 +972,84 @@ export async function buildClaimMakerSettlementInstruction(
   });
 }
 
+export interface BuildLiquidateWriterPositionParams {
+  optionPool: AddressLike;
+  optionAccount: AddressLike;
+  /** Market data PDA (`["market_data", underlying_asset]`). */
+  marketData: AddressLike;
+  /** Authority-updated Switchboard HV quote PDA (derived from market data when omitted). */
+  volatilityQuoteAccount?: AddressLike;
+  collateralPool: AddressLike;
+  writerPosition: AddressLike;
+  longMint: AddressLike;
+  escrowLongAccount: AddressLike;
+  underlyingMint: AddressLike;
+  switchboardQueue: AddressLike;
+  /** OMLP Vault state PDA (mut: decrements total_loans, etc.). */
+  omlpVault: AddressLike;
+  collateralVault: AddressLike;
+  premiumVault: AddressLike;
+  omlpVaultTokenAccount: AddressLike;
+  feeWallet: AddressLike;
+  /** Permissionless liquidator signer. */
+  liquidator: TransactionSigner<string>;
+  /** Every active PoolLoan for this writer/vault (SDK: loadWriterLoans). */
+  remainingAccounts?: RemainingAccountInput[];
+  rpc?: KitRpc;
+}
+
+export async function buildLiquidateWriterPositionInstruction(
+  params: BuildLiquidateWriterPositionParams
+): Promise<Instruction<string>> {
+  let volatilityQuoteAccount = params.volatilityQuoteAccount;
+  if (!volatilityQuoteAccount) {
+    invariant(!!params.rpc, "rpc is required when volatilityQuoteAccount is omitted");
+    const marketDataAccount = await fetchMarketDataAccount(params.rpc!, params.marketData);
+    invariant(
+      !!marketDataAccount,
+      "Market data account not found for resolved option market."
+    );
+    volatilityQuoteAccount = deriveVolatilityQuoteAddressFromMarketData(marketDataAccount);
+  }
+
+  const kitInstruction = await getLiquidateWriterPositionInstructionAsync({
+    optionPool: toAddress(params.optionPool),
+    optionAccount: toAddress(params.optionAccount),
+    marketData: toAddress(params.marketData),
+    volatilityQuoteAccount: toAddress(volatilityQuoteAccount),
+    collateralPool: toAddress(params.collateralPool),
+    writerPosition: toAddress(params.writerPosition),
+    longMint: toAddress(params.longMint),
+    escrowLongAccount: toAddress(params.escrowLongAccount),
+    underlyingMint: toAddress(params.underlyingMint),
+    switchboardQueue: toAddress(params.switchboardQueue),
+    omlpVault: toAddress(params.omlpVault),
+    collateralVault: toAddress(params.collateralVault),
+    premiumVault: toAddress(params.premiumVault),
+    omlpVaultTokenAccount: toAddress(params.omlpVaultTokenAccount),
+    feeWallet: toAddress(params.feeWallet),
+    liquidator: params.liquidator as any,
+  });
+  return appendRemainingAccounts(kitInstruction, [
+    {
+      address: SLOT_HASHES_SYSVAR_ADDRESS,
+      isWritable: false,
+    },
+    {
+      address: INSTRUCTIONS_SYSVAR_ADDRESS,
+      isWritable: false,
+    },
+    ...(params.remainingAccounts ?? []),
+  ]);
+}
+
+export async function buildLiquidateWriterPositionTransaction(
+  params: BuildLiquidateWriterPositionParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildLiquidateWriterPositionInstruction(params);
+  return { instructions: [instruction] };
+}
+
 /**
  * Parameters for the permissioned rescue liquidation path. Gated on-chain
  * to `Vault::keeper`; the SDK does not re-verify keeper identity, but the