@epicentral/sos-sdk 0.12.1-beta → 0.13.0-beta

package/generated/instructions/updateImpliedVolatility.ts

@@ -48,6 +48,7 @@ export type UpdateImpliedVolatilityInstruction<
   TAccountOptionAccount extends string | AccountMeta<string> = string,
   TAccountOptionPool extends string | AccountMeta<string> = string,
   TAccountMarketData extends string | AccountMeta<string> = string,
+  TAccountVolatilityQuoteAccount extends string | AccountMeta<string> = string,
   TAccountKeeper extends string | AccountMeta<string> = string,
   TRemainingAccounts extends readonly AccountMeta<string>[] = [],
 > = Instruction<TProgram> &
@@ -63,6 +64,9 @@ export type UpdateImpliedVolatilityInstruction<
       TAccountMarketData extends string
         ? ReadonlyAccount<TAccountMarketData>
         : TAccountMarketData,
+      TAccountVolatilityQuoteAccount extends string
+        ? ReadonlyAccount<TAccountVolatilityQuoteAccount>
+        : TAccountVolatilityQuoteAccount,
       TAccountKeeper extends string
         ? ReadonlySignerAccount<TAccountKeeper> &
             AccountSignerMeta<TAccountKeeper>
@@ -107,6 +111,7 @@ export type UpdateImpliedVolatilityInput<
   TAccountOptionAccount extends string = string,
   TAccountOptionPool extends string = string,
   TAccountMarketData extends string = string,
+  TAccountVolatilityQuoteAccount extends string = string,
   TAccountKeeper extends string = string,
 > = {
   /** The option account to update IV for */
@@ -115,6 +120,7 @@ export type UpdateImpliedVolatilityInput<
   optionPool: Address<TAccountOptionPool>;
   /** Market data - provides baseline historical volatility */
   marketData: Address<TAccountMarketData>;
+  volatilityQuoteAccount: Address<TAccountVolatilityQuoteAccount>;
   /** Keeper/anyone can call this instruction (permissionless update) */
   keeper: TransactionSigner<TAccountKeeper>;
 };
@@ -123,6 +129,7 @@ export function getUpdateImpliedVolatilityInstruction<
   TAccountOptionAccount extends string,
   TAccountOptionPool extends string,
   TAccountMarketData extends string,
+  TAccountVolatilityQuoteAccount extends string,
   TAccountKeeper extends string,
   TProgramAddress extends Address = typeof OPTION_PROGRAM_PROGRAM_ADDRESS,
 >(
@@ -130,6 +137,7 @@ export function getUpdateImpliedVolatilityInstruction<
     TAccountOptionAccount,
     TAccountOptionPool,
     TAccountMarketData,
+    TAccountVolatilityQuoteAccount,
     TAccountKeeper
   >,
   config?: { programAddress?: TProgramAddress },
@@ -138,6 +146,7 @@ export function getUpdateImpliedVolatilityInstruction<
   TAccountOptionAccount,
   TAccountOptionPool,
   TAccountMarketData,
+  TAccountVolatilityQuoteAccount,
   TAccountKeeper
 > {
   // Program address.
@@ -149,6 +158,10 @@ export function getUpdateImpliedVolatilityInstruction<
     optionAccount: { value: input.optionAccount ?? null, isWritable: true },
     optionPool: { value: input.optionPool ?? null, isWritable: false },
     marketData: { value: input.marketData ?? null, isWritable: false },
+    volatilityQuoteAccount: {
+      value: input.volatilityQuoteAccount ?? null,
+      isWritable: false,
+    },
     keeper: { value: input.keeper ?? null, isWritable: false },
   };
   const accounts = originalAccounts as Record<
@@ -162,6 +175,7 @@ export function getUpdateImpliedVolatilityInstruction<
       getAccountMeta(accounts.optionAccount),
       getAccountMeta(accounts.optionPool),
       getAccountMeta(accounts.marketData),
+      getAccountMeta(accounts.volatilityQuoteAccount),
       getAccountMeta(accounts.keeper),
     ],
     data: getUpdateImpliedVolatilityInstructionDataEncoder().encode({}),
@@ -171,6 +185,7 @@ export function getUpdateImpliedVolatilityInstruction<
     TAccountOptionAccount,
     TAccountOptionPool,
     TAccountMarketData,
+    TAccountVolatilityQuoteAccount,
     TAccountKeeper
   >);
 }
@@ -187,8 +202,9 @@ export type ParsedUpdateImpliedVolatilityInstruction<
     optionPool: TAccountMetas[1];
     /** Market data - provides baseline historical volatility */
     marketData: TAccountMetas[2];
+    volatilityQuoteAccount: TAccountMetas[3];
     /** Keeper/anyone can call this instruction (permissionless update) */
-    keeper: TAccountMetas[3];
+    keeper: TAccountMetas[4];
   };
   data: UpdateImpliedVolatilityInstructionData;
 };
@@ -201,7 +217,7 @@ export function parseUpdateImpliedVolatilityInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedUpdateImpliedVolatilityInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 4) {
+  if (instruction.accounts.length < 5) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -217,6 +233,7 @@ export function parseUpdateImpliedVolatilityInstruction<
       optionAccount: getNextAccount(),
       optionPool: getNextAccount(),
       marketData: getNextAccount(),
+      volatilityQuoteAccount: getNextAccount(),
       keeper: getNextAccount(),
     },
     data: getUpdateImpliedVolatilityInstructionDataDecoder().decode(

package/generated/programs/optionProgram.ts

@@ -34,6 +34,7 @@ import {
   type ParsedLiquidateWriterPositionInstruction,
   type ParsedLiquidateWriterPositionRescueInstruction,
   type ParsedMigrateCollateralPoolV1ToV2Instruction,
+  type ParsedMigrateMarketDataVolOracleInstruction,
   type ParsedOmlpCreateVaultInstruction,
   type ParsedOmlpUpdateFeeWalletInstruction,
   type ParsedOmlpUpdateInterestModelInstruction,
@@ -265,6 +266,7 @@ export enum OptionProgramInstruction {
   LiquidateWriterPosition,
   LiquidateWriterPositionRescue,
   MigrateCollateralPoolV1ToV2,
+  MigrateMarketDataVolOracle,
   OmlpCreateVault,
   OmlpUpdateFeeWallet,
   OmlpUpdateInterestModel,
@@ -516,6 +518,17 @@ export function identifyOptionProgramInstruction(
   ) {
     return OptionProgramInstruction.MigrateCollateralPoolV1ToV2;
   }
+  if (
+    containsBytes(
+      data,
+      fixEncoderSize(getBytesEncoder(), 8).encode(
+        new Uint8Array([230, 102, 218, 98, 194, 231, 97, 241]),
+      ),
+      0,
+    )
+  ) {
+    return OptionProgramInstruction.MigrateMarketDataVolOracle;
+  }
   if (
     containsBytes(
       data,
@@ -859,6 +872,9 @@ export type ParsedOptionProgramInstruction<
   | ({
       instructionType: OptionProgramInstruction.MigrateCollateralPoolV1ToV2;
     } & ParsedMigrateCollateralPoolV1ToV2Instruction<TProgram>)
+  | ({
+      instructionType: OptionProgramInstruction.MigrateMarketDataVolOracle;
+    } & ParsedMigrateMarketDataVolOracleInstruction<TProgram>)
   | ({
       instructionType: OptionProgramInstruction.OmlpCreateVault;
     } & ParsedOmlpCreateVaultInstruction<TProgram>)

package/index.ts

@@ -64,6 +64,12 @@ export {
   type SwitchboardNetwork,
 } from "./oracle/switchboard";
 
+export {
+  deriveVolatilityQuoteAddress,
+  deriveVolatilityQuoteAddressFromMarketData,
+  isVolOracleEnabled,
+} from "./oracle/volatility-quote";
+
 export {
   getWrapSOLInstructions,
   getUnwrapSOLInstructions,

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;
@@ -110,10 +115,12 @@ export interface BuildCloseLongToPoolParams {
    */
   closeLongTokenAccount?: boolean;
   /**
-   * When true and underlying is WSOL, appends an SPL CloseAccount to unwrap the payout ATA so the buyer receives native SOL.
-   * Ignored when underlyingMint is not WSOL.
+   * When true and settlement is physical (collateral mint == underlying) with WSOL underlying,
+   * appends CloseAccount to unwrap the payout WSOL ATA to native SOL.
    */
   unwrapPayoutSol?: boolean;
+  /** When false, skips idempotent create-ATA for payout accounts (default: true). */
+  createPayoutAtas?: boolean;
   remainingAccounts?: RemainingAccountInput[];
 }
 
@@ -129,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,
@@ -215,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;
@@ -301,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,
@@ -319,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)
   );
@@ -458,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,
@@ -476,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)
   );
@@ -539,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),
@@ -554,10 +575,36 @@ export async function buildCloseLongToPoolInstruction(
 }
 
 export async function buildCloseLongToPoolTransaction(
-  params: BuildCloseLongToPoolParams
+  params: BuildCloseLongToPoolParams & { createPayoutAtas?: boolean }
 ): Promise<BuiltTransaction> {
+  const collateralMint = params.collateralMint ?? params.underlyingMint;
+  const isPhysicalSettlement =
+    toAddress(collateralMint) === toAddress(params.underlyingMint);
+  const instructions: Instruction<string>[] = [];
+
+  if (params.createPayoutAtas !== false) {
+    instructions.push(
+      await getCreateAssociatedTokenIdempotentInstructionWithAddress(
+        params.buyer,
+        params.buyer,
+        toAddress(collateralMint),
+        toAddress(params.buyerPayoutAccount)
+      )
+    );
+    if (!isPhysicalSettlement) {
+      instructions.push(
+        await getCreateAssociatedTokenIdempotentInstructionWithAddress(
+          params.buyer,
+          params.buyer,
+          toAddress(params.underlyingMint),
+          toAddress(params.buyerUnderlyingPayoutAccount)
+        )
+      );
+    }
+  }
+
   const instruction = await buildCloseLongToPoolInstruction(params);
-  const instructions = [instruction];
+  instructions.push(instruction);
 
   if (params.closeLongTokenAccount === true) {
     instructions.push(
@@ -609,10 +656,12 @@ export interface BuildCloseLongToPoolTransactionWithDerivationParams {
    */
   closeLongTokenAccount?: boolean;
   /**
-   * When true (default for WSOL underlying), appends CloseAccount to unwrap payout WSOL ATA to native SOL.
-   * Only applies when option underlying is WSOL.
+   * When true, unwraps physical-settlement WSOL payout to native SOL after close.
+   * Defaults to true only for physical WSOL pools; cash-settled pools default to false.
    */
   unwrapPayoutSol?: boolean;
+  /** When false, skips idempotent create-ATA for payout accounts (default: true). */
+  createPayoutAtas?: boolean;
   remainingAccounts?: RemainingAccountInput[];
   disableSwitchboardCrank?: boolean;
   switchboardCrossbarUrl?: string;
@@ -622,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(
@@ -665,10 +716,13 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
 
   const isWsolUnderlying =
     toAddress(resolved.underlyingMint!) === toAddress(NATIVE_MINT);
+  const isPhysicalSettlement =
+    toAddress(collateralMint) === toAddress(resolved.underlyingMint!);
   const closeLongTokenAccount =
     params.closeLongTokenAccount !== false;
   const unwrapPayoutSol =
-    params.unwrapPayoutSol !== false && isWsolUnderlying;
+    params.unwrapPayoutSol ??
+    (isWsolUnderlying && isPhysicalSettlement);
 
   // close_long_to_pool requires a complete set of active WriterPositions so the
   // program can run the strict Hamilton completeness check. Auto-populate if
@@ -686,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)
   );
@@ -705,6 +762,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
       escrowLongAccount: resolved.escrowLongAccount!,
       premiumVault: resolved.premiumVault!,
       marketData: resolved.marketData,
+      volatilityQuoteAccount,
       switchboardQueue,
       buyer: params.buyer,
       buyerLongAccount: params.buyerLongAccount,
@@ -716,6 +774,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
       buyerPosition,
       closeLongTokenAccount,
       unwrapPayoutSol,
+      createPayoutAtas: params.createPayoutAtas,
       remainingAccounts,
     });
   }
@@ -744,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,
@@ -755,6 +815,7 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
     buyerPosition,
     closeLongTokenAccount,
     unwrapPayoutSol,
+    createPayoutAtas: params.createPayoutAtas,
     remainingAccounts,
   });
 

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.1-beta",
+  "version": "0.13.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",
@@ -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