@epicentral/sos-sdk 0.9.0-beta

package/short/builders.ts

@@ -0,0 +1,874 @@
+import {
+  getLiquidateWriterPositionRescueInstructionAsync,
+  getOptionMintInstructionAsync,
+  getSettleMakerCollateralInstructionAsync,
+  getSyncWriterPositionInstruction,
+  getUnwindWriterUnsoldInstructionAsync,
+  type OptionType,
+} from "../generated";
+import type { Instruction, TransactionSigner } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction, KitRpc } from "../client/types";
+import { fetchMarketDataAccount, fetchVault, fetchWriterPosition } from "../accounts/fetchers";
+import { fetchPoolLoansByMaker } from "../accounts/list";
+import { resolveOptionAccounts } from "../accounts/resolve-option";
+import {
+  deriveAssociatedTokenAddress,
+  deriveMakerCollateralSharePda,
+  deriveMetadataPda,
+  deriveVaultPda,
+  deriveWriterPositionPda,
+} from "../accounts/pdas";
+import { assertNonNegativeAmount, assertPositiveAmount } from "../shared/amounts";
+import { invariant } from "../shared/errors";
+import {
+  appendRemainingAccounts,
+  type RemainingAccountInput,
+} from "../shared/remaining-accounts";
+import {
+  getCloseAccountInstruction,
+  getCreateAssociatedTokenIdempotentInstructionWithAddress,
+} from "../wsol/instructions";
+import { preflightUnwindWriterUnsold, writerPositionHasOngoingPoolLoanDebt } from "./preflight";
+import {
+  buildSwitchboardQuoteInstruction,
+  feedIdBytesToHex,
+  inferSwitchboardNetwork,
+  INSTRUCTIONS_SYSVAR_ADDRESS,
+  SLOT_HASHES_SYSVAR_ADDRESS,
+  SWITCHBOARD_DEFAULT_DEVNET_QUEUE,
+} from "../oracle/switchboard";
+import { applySlippageBps } from "../long/quotes";
+import { getGlobalTradeConfig } from "../shared/trade-config";
+
+export interface BuildOptionMintParams {
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  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;
+  maxRequiredCollateralAmount?: bigint | number;
+  maker: AddressLike;
+  makerCollateralAccount: AddressLike;
+  underlyingMint: AddressLike;
+  /** Queue account required by direct Switchboard quote verification. */
+  switchboardQueue?: AddressLike;
+  longMetadataAccount?: AddressLike;
+  shortMetadataAccount?: AddressLike;
+  optionAccount?: AddressLike;
+  longMint?: AddressLike;
+  shortMint?: AddressLike;
+  mintAuthority?: AddressLike;
+  makerLongAccount?: AddressLike;
+  makerShortAccount?: AddressLike;
+  marketData?: AddressLike;
+  optionPool?: AddressLike;
+  escrowLongAccount?: AddressLike;
+  premiumVault?: AddressLike;
+  collateralPool?: AddressLike;
+  collateralVault?: AddressLike;
+  writerPosition?: AddressLike;
+  vault?: AddressLike;
+  vaultTokenAccount?: AddressLike;
+  escrowState?: AddressLike;
+  escrowAuthority?: AddressLike;
+  escrowTokenAccount?: AddressLike;
+  poolLoan?: AddressLike;
+  /**
+   * When true (default), appends an SPL CloseAccount instruction after option_mint to close the
+   * maker's LONG token account (reclaim rent). The program transfers all LONG to escrow, so the
+   * maker's LONG ATA is left with zero balance and can be closed in the same transaction.
+   */
+  closeMakerLongAccount?: boolean;
+  remainingAccounts?: RemainingAccountInput[];
+}
+
+/** Max PoolLoans per unwind to stay under 64-account tx limit (~18 named + ~20 loans) */
+const MAX_POOL_LOANS_PER_UNWIND = 20;
+
+export interface BuildUnwindWriterUnsoldParams {
+  optionPool: AddressLike;
+  optionAccount: AddressLike;
+  /** Market data PDA (`["market_data", underlying_asset]`). */
+  marketData: AddressLike;
+  longMint: AddressLike;
+  shortMint: AddressLike;
+  escrowLongAccount: AddressLike;
+  writerShortAccount: AddressLike;
+  collateralVault: AddressLike;
+  /** Pool premium vault (source of theta-first debt repayment + leftover theta release). */
+  premiumVault: AddressLike;
+  writerCollateralAccount: AddressLike;
+  writer: AddressLike;
+  unwindQty: bigint | number;
+  collateralPool?: AddressLike;
+  writerPosition?: AddressLike;
+  omlpVaultState?: AddressLike;
+  omlpVault?: AddressLike;
+  feeWallet?: AddressLike;
+  remainingAccounts?: RemainingAccountInput[];
+}
+
+export interface BuildSyncWriterPositionParams {
+  optionPool: AddressLike;
+  optionAccount: AddressLike;
+  writerPosition: AddressLike;
+}
+
+export interface BuildSettleMakerCollateralParams {
+  optionAccount: AddressLike;
+  collateralVault: AddressLike;
+  makerCollateralAccount: AddressLike;
+  /** OMLP Vault token account (destination for principal+interest). */
+  omlpVault: AddressLike;
+  /** OMLP Vault state PDA (mut: updates `total_loans`, `total_liquidity`, `acc_interest_per_share_fp`). */
+  omlpVaultState: AddressLike;
+  poolLoan: AddressLike;
+  maker: AddressLike;
+  makerCollateralShare?: AddressLike;
+  collateralPool?: AddressLike;
+}
+
+export async function buildOptionMintInstruction(
+  params: BuildOptionMintParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.quantity, "quantity");
+  assertNonNegativeAmount(params.makerCollateralAmount, "makerCollateralAmount");
+  assertNonNegativeAmount(params.borrowedAmount, "borrowedAmount");
+  invariant(params.strikePrice > 0, "strikePrice must be greater than zero.");
+  invariant(params.underlyingSymbol.length > 0, "underlyingSymbol is required.");
+
+  const borrowedAmount = BigInt(params.borrowedAmount);
+  const globalTradeConfig = getGlobalTradeConfig();
+  const maxRequiredCollateralAmount =
+    params.maxRequiredCollateralAmount !== undefined
+      ? BigInt(params.maxRequiredCollateralAmount)
+      : globalTradeConfig.slippageBps !== undefined
+        ? applySlippageBps(
+            BigInt(params.makerCollateralAmount) + borrowedAmount,
+            globalTradeConfig.slippageBps
+          )
+        : BigInt(params.makerCollateralAmount) + borrowedAmount;
+  if (borrowedAmount > 0n) {
+    invariant(!!params.vault, "vault is required when borrowedAmount > 0");
+    invariant(
+      !!params.vaultTokenAccount,
+      "vaultTokenAccount is required when borrowedAmount > 0"
+    );
+    invariant(!!params.escrowState, "escrowState is required when borrowedAmount > 0");
+    invariant(
+      !!params.escrowAuthority,
+      "escrowAuthority is required when borrowedAmount > 0"
+    );
+    invariant(
+      !!params.escrowTokenAccount,
+      "escrowTokenAccount is required when borrowedAmount > 0"
+    );
+    invariant(!!params.poolLoan, "poolLoan is required when borrowedAmount > 0");
+  }
+
+  const [derivedLongMetadata, derivedShortMetadata] = await Promise.all([
+    params.longMint ? deriveMetadataPda(params.longMint) : Promise.resolve(undefined),
+    params.shortMint ? deriveMetadataPda(params.shortMint) : Promise.resolve(undefined),
+  ]);
+  const longMetadata = params.longMetadataAccount ?? derivedLongMetadata?.[0];
+  const shortMetadata = params.shortMetadataAccount ?? derivedShortMetadata?.[0];
+
+  invariant(
+    !!longMetadata && !!shortMetadata,
+    "longMetadataAccount and shortMetadataAccount are required (or provide longMint/shortMint to derive)."
+  );
+
+  const kitInstruction = await getOptionMintInstructionAsync({
+    optionAccount: params.optionAccount ? toAddress(params.optionAccount) : undefined,
+    longMint: params.longMint ? toAddress(params.longMint) : undefined,
+    shortMint: params.shortMint ? toAddress(params.shortMint) : undefined,
+    mintAuthority: params.mintAuthority ? toAddress(params.mintAuthority) : undefined,
+    makerLongAccount: params.makerLongAccount
+      ? toAddress(params.makerLongAccount)
+      : undefined,
+    makerShortAccount: params.makerShortAccount
+      ? toAddress(params.makerShortAccount)
+      : undefined,
+    longMetadataAccount: toAddress(longMetadata!),
+    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)
+      : undefined,
+    premiumVault: params.premiumVault ? toAddress(params.premiumVault) : undefined,
+    collateralPool: params.collateralPool ? toAddress(params.collateralPool) : undefined,
+    collateralVault: params.collateralVault ? toAddress(params.collateralVault) : undefined,
+    makerCollateralAccount: toAddress(params.makerCollateralAccount),
+    writerPosition: params.writerPosition ? toAddress(params.writerPosition) : undefined,
+    vault: params.vault ? toAddress(params.vault) : undefined,
+    vaultTokenAccount: params.vaultTokenAccount
+      ? toAddress(params.vaultTokenAccount)
+      : undefined,
+    escrowState: params.escrowState ? toAddress(params.escrowState) : undefined,
+    escrowAuthority: params.escrowAuthority ? toAddress(params.escrowAuthority) : undefined,
+    escrowTokenAccount: params.escrowTokenAccount
+      ? toAddress(params.escrowTokenAccount)
+      : undefined,
+    poolLoan: params.poolLoan ? toAddress(params.poolLoan) : undefined,
+    maker: toAddress(params.maker) as any,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    quantity: params.quantity,
+    underlyingAsset: toAddress(params.underlyingAsset),
+    underlyingSymbol: params.underlyingSymbol,
+    collateralMintArg: toAddress(params.collateralMint ?? params.underlyingMint),
+    makerCollateralAmount: params.makerCollateralAmount,
+    borrowedAmount: params.borrowedAmount,
+    maxRequiredCollateralAmount,
+  });
+
+  const quoteVerificationAccounts: RemainingAccountInput[] = [
+    {
+      address: params.switchboardQueue ?? SWITCHBOARD_DEFAULT_DEVNET_QUEUE,
+      isWritable: false,
+    },
+    {
+      address: SLOT_HASHES_SYSVAR_ADDRESS,
+      isWritable: false,
+    },
+    {
+      address: INSTRUCTIONS_SYSVAR_ADDRESS,
+      isWritable: false,
+    },
+  ];
+
+  return appendRemainingAccounts(kitInstruction, [
+    ...quoteVerificationAccounts,
+    ...(params.remainingAccounts ?? []),
+  ]);
+}
+
+export async function buildOptionMintTransaction(
+  params: BuildOptionMintParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildOptionMintInstruction(params);
+  const instructions: Instruction<string>[] = [instruction];
+
+  const shouldCloseMakerLong =
+    params.closeMakerLongAccount !== false && params.makerLongAccount != null;
+  if (shouldCloseMakerLong) {
+    instructions.push(
+      getCloseAccountInstruction(
+        params.makerLongAccount!,
+        params.maker,
+        params.maker
+      )
+    );
+  }
+
+  return { instructions };
+}
+
+export interface BuildOptionMintTransactionWithDerivationParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  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;
+  maxRequiredCollateralAmount?: bigint | number;
+  maker: AddressLike;
+  /**
+   * Optional. When omitted, the SDK derives the maker's collateral ATA for collateralMint
+   * (or underlyingMint if collateralMint is not provided).
+   */
+  makerCollateralAccount?: AddressLike;
+  rpc: KitRpc;
+  rpcEndpoint?: string;
+  programId?: AddressLike;
+  vault?: AddressLike;
+  vaultTokenAccount?: AddressLike;
+  escrowState?: AddressLike;
+  escrowAuthority?: AddressLike;
+  escrowTokenAccount?: AddressLike;
+  poolLoan?: AddressLike;
+  remainingAccounts?: RemainingAccountInput[];
+  disableSwitchboardCrank?: boolean;
+  switchboardCrossbarUrl?: string;
+  switchboardNumSignatures?: number;
+  /**
+   * 0-based index of this Switchboard quote ix inside the **final** transaction after the
+   * wallet prepends compute-budget instructions (see `Queue.fetchQuoteIx` `instructionIdx`).
+   * Kit `sendInstructions` prepends **only** `SetComputeUnitLimit` before these ixs → default **1**.
+   * Use **0** if nothing is prepended; **2** if both limit and priority fee compute-budget ixs run first.
+   */
+  switchboardQuoteInstructionIndex?: number;
+  /**
+   * When true, omits the collateral ATA create-idempotent instruction from the mint transaction.
+   * Send that ix in a prior transaction (e.g. with leverage setup) so quote + option_mint stays
+   * under Solana's 1232-byte versioned-transaction limit when OMLP accounts are present.
+   */
+  skipCreateCollateralAta?: boolean;
+}
+
+export async function buildOptionMintTransactionWithDerivation(
+  params: BuildOptionMintTransactionWithDerivationParams
+): Promise<BuiltTransaction> {
+  const borrowedAmount = BigInt(params.borrowedAmount);
+  if (borrowedAmount > 0n) {
+    invariant(!!params.vault, "vault is required when borrowedAmount > 0");
+    invariant(
+      !!params.vaultTokenAccount,
+      "vaultTokenAccount is required when borrowedAmount > 0"
+    );
+    invariant(!!params.escrowState, "escrowState is required when borrowedAmount > 0");
+    invariant(
+      !!params.escrowAuthority,
+      "escrowAuthority is required when borrowedAmount > 0"
+    );
+    invariant(
+      !!params.escrowTokenAccount,
+      "escrowTokenAccount is required when borrowedAmount > 0"
+    );
+    invariant(!!params.poolLoan, "poolLoan is required when borrowedAmount > 0");
+  }
+
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const underlyingMint = resolved.underlyingMint ?? params.underlyingMint;
+  const collateralMint = params.collateralMint ?? underlyingMint;
+  const existingCollateralMint = resolved.collateralPoolData?.collateralMint;
+  if (
+    existingCollateralMint &&
+    toAddress(existingCollateralMint) !== toAddress(collateralMint)
+  ) {
+    invariant(
+      false,
+      `Collateral pool mint mismatch. Option market is already collateralized with ${toAddress(
+        existingCollateralMint
+      )}, but request used ${toAddress(collateralMint)}.`
+    );
+  }
+
+  const collateralVault =
+    resolved.collateralVault ??
+    (await deriveAssociatedTokenAddress(resolved.collateralPool, collateralMint, true));
+
+  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, collateralMint);
+  const marketDataAccount = await fetchMarketDataAccount(params.rpc, resolved.marketData);
+  invariant(
+    !!marketDataAccount,
+    "Market data account not found for resolved option market."
+  );
+  const switchboardFeedId = feedIdBytesToHex(
+    Uint8Array.from(marketDataAccount.switchboardFeedId as unknown as Uint8Array)
+  );
+
+  const [writerPositionPdaForIx] = await deriveWriterPositionPda(
+    resolved.optionPool,
+    params.maker,
+    params.programId
+  );
+
+  // option_mint + borrow: `sync_collateral_pool_debt` requires
+  //   snapshot.active_loan_count == writer.active_loan_count
+  // after the writer block (+1 for this borrow). The named `pool_loan` is the new loan from
+  // TX A. gPA can return more PoolLoans than `writer.active_loan_count` (on-chain desync
+  // or stale actives). We pass exactly `activeLoanCount` pre-ix prior loans, excluding the
+  // new `pool_loan`, matching `writer_position` (and preferring same vault) with canonical
+  // `toAddress` equality. Prefer *higher* `nonce` first so we do not pick a stale low-nonce
+  // account that the sync path skips (discriminator / borrow_mut), which yields under-count
+  // and 6102.
+  let priorActivePoolLoans: RemainingAccountInput[] = [];
+  if (borrowedAmount > 0n) {
+    const wp = toAddress(writerPositionPdaForIx);
+    const newLoan = toAddress(params.poolLoan!);
+    const vaultPda = toAddress(params.vault!);
+    const [writerPos, activeLoans] = await Promise.all([
+      fetchWriterPosition(params.rpc, writerPositionPdaForIx),
+      fetchPoolLoansByMaker(params.rpc, params.maker),
+    ]);
+    const priorCount = writerPos?.activeLoanCount ?? 0;
+    const forWriter = (l: (typeof activeLoans)[0]) =>
+      toAddress(l.data.writerPosition) === wp && toAddress(l.address) !== newLoan;
+    const sortByNonceDesc = (
+      a: (typeof activeLoans)[0],
+      b: (typeof activeLoans)[0]
+    ) => {
+      if (a.data.nonce > b.data.nonce) return -1;
+      if (a.data.nonce < b.data.nonce) return 1;
+      return String(a.address).localeCompare(String(b.address));
+    };
+    const withVault = activeLoans
+      .filter(
+        (l) => forWriter(l) && toAddress(l.data.vault) === vaultPda
+      )
+      .sort(sortByNonceDesc);
+    const withoutVault = activeLoans.filter(forWriter).sort(sortByNonceDesc);
+    const candidates =
+      withVault.length >= priorCount ? withVault : withoutVault;
+    priorActivePoolLoans = candidates
+      .slice(0, priorCount)
+      .map((l) => ({ address: l.address, isWritable: true }));
+  }
+
+  const tx = await buildOptionMintTransaction({
+    ...params,
+    underlyingAsset: params.underlyingAsset,
+    underlyingMint,
+    collateralMint,
+    makerCollateralAccount,
+    optionAccount: resolved.optionAccount,
+    longMint: resolved.longMint,
+    shortMint: resolved.shortMint,
+    mintAuthority: resolved.mintAuthority,
+    makerLongAccount,
+    makerShortAccount,
+    marketData: resolved.marketData,
+    optionPool: resolved.optionPool,
+    escrowLongAccount: resolved.escrowLongAccount,
+    premiumVault: resolved.premiumVault,
+    collateralPool: resolved.collateralPool,
+    collateralVault,
+    writerPosition: writerPositionPdaForIx,
+    vault: params.vault,
+    vaultTokenAccount: params.vaultTokenAccount,
+    escrowState: params.escrowState,
+    escrowAuthority: params.escrowAuthority,
+    escrowTokenAccount: params.escrowTokenAccount,
+    poolLoan: params.poolLoan,
+    switchboardQueue: SWITCHBOARD_DEFAULT_DEVNET_QUEUE,
+    remainingAccounts: [...priorActivePoolLoans, ...(params.remainingAccounts ?? [])],
+  });
+
+  const createAtaIx =
+    params.skipCreateCollateralAta === true
+      ? null
+      : await getCreateAssociatedTokenIdempotentInstructionWithAddress(
+          params.maker,
+          params.maker,
+          collateralMint,
+          makerCollateralAccount
+        );
+
+  const actionTx = {
+    instructions:
+      createAtaIx !== null ? [createAtaIx, ...tx.instructions] : [...tx.instructions],
+  };
+
+  if (params.disableSwitchboardCrank) {
+    return actionTx;
+  }
+
+  invariant(
+    !!params.rpcEndpoint,
+    "rpcEndpoint is required to fetch Switchboard quote instructions."
+  );
+  const quoteNetwork = await inferSwitchboardNetwork(params.rpc);
+  const quote = await buildSwitchboardQuoteInstruction({
+    rpcEndpoint: params.rpcEndpoint,
+    feedIdHex: switchboardFeedId,
+    network: quoteNetwork,
+    crossbarUrl: params.switchboardCrossbarUrl,
+    numSignatures: params.switchboardNumSignatures,
+    instructionIdx: params.switchboardQuoteInstructionIndex ?? 1,
+  });
+
+  return {
+    instructions: [quote.instruction, ...actionTx.instructions],
+  };
+}
+
+export async function buildUnwindWriterUnsoldInstruction(
+  params: BuildUnwindWriterUnsoldParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.unwindQty, "unwindQty");
+
+  const kitInstruction = await getUnwindWriterUnsoldInstructionAsync(
+    {
+      optionPool: toAddress(params.optionPool),
+      optionAccount: toAddress(params.optionAccount),
+      marketData: toAddress(params.marketData),
+      collateralPool: params.collateralPool ? toAddress(params.collateralPool) : undefined,
+      writerPosition: params.writerPosition ? toAddress(params.writerPosition) : undefined,
+      longMint: toAddress(params.longMint),
+      shortMint: toAddress(params.shortMint),
+      escrowLongAccount: toAddress(params.escrowLongAccount),
+      writerShortAccount: toAddress(params.writerShortAccount),
+      collateralVault: toAddress(params.collateralVault),
+      premiumVault: toAddress(params.premiumVault),
+      writerCollateralAccount: toAddress(params.writerCollateralAccount),
+      omlpVaultState: params.omlpVaultState ? toAddress(params.omlpVaultState) : undefined,
+      omlpVault: params.omlpVault ? toAddress(params.omlpVault) : undefined,
+      feeWallet: params.feeWallet ? toAddress(params.feeWallet) : undefined,
+      writer: toAddress(params.writer) as any,
+      unwindQty: params.unwindQty,
+    } as any
+  );
+
+  return appendRemainingAccounts(kitInstruction, params.remainingAccounts);
+}
+
+export async function buildUnwindWriterUnsoldTransaction(
+  params: BuildUnwindWriterUnsoldParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildUnwindWriterUnsoldInstruction(params);
+  return { instructions: [instruction] };
+}
+
+export interface BuildUnwindWriterUnsoldTransactionWithDerivationParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  writer: AddressLike;
+  unwindQty: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+  omlpVaultState?: AddressLike;
+  omlpVault?: AddressLike;
+  feeWallet?: AddressLike;
+  /**
+   * When repaying pool loans: [PoolLoan₁, PoolLoan₂, ...] (all writable).
+   * omlpVaultState, omlpVault, feeWallet must also be passed.
+   * Prefer {@link buildUnwindWriterUnsoldWithLoanRepayment} to build this automatically.
+   */
+  remainingAccounts?: RemainingAccountInput[];
+}
+
+export interface BuildUnwindWriterUnsoldWithLoanRepaymentParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  writer: AddressLike;
+  unwindQty: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+  /** Override when pool fetch is not used; otherwise resolved from option pool. */
+  underlyingMint?: AddressLike;
+}
+
+/**
+ * Builds an unwind_writer_unsold transaction that also repays any active pool loans
+ * for the option's underlying vault. When a writer unwinds an unsold short that had
+ * borrowed from OMLP, the program repays lenders from the collateral vault (burn,
+ * repay, then return collateral to writer) in one instruction.
+ *
+ * Passes omlpVaultState (Vault PDA), omlpVault, feeWallet as named accounts.
+ * remaining_accounts: [PoolLoan₁, PoolLoan₂, ...] only (capped at 20).
+ * If no active pool loans exist, still passes vault accounts so the API works for all unwinds.
+ */
+export async function buildUnwindWriterUnsoldWithLoanRepayment(
+  params: BuildUnwindWriterUnsoldWithLoanRepaymentParams
+): Promise<BuiltTransaction> {
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const underlyingMint = params.underlyingMint ?? resolved.underlyingMint;
+  invariant(
+    !!underlyingMint,
+    "underlyingMint is required; ensure rpc is provided and option pool is initialized, or pass underlyingMint."
+  );
+
+  const [vaultPda] = await deriveVaultPda(underlyingMint, params.programId);
+  const vaultPdaStr = toAddress(vaultPda);
+
+  const [writerPositionAddress] = await deriveWriterPositionPda(
+    resolved.optionPool,
+    params.writer,
+    params.programId
+  );
+
+  const [loans, vault, writerPosition] = await Promise.all([
+    fetchPoolLoansByMaker(params.rpc, params.writer),
+    fetchVault(params.rpc, vaultPda),
+    fetchWriterPosition(params.rpc, writerPositionAddress),
+  ]);
+
+  invariant(!!writerPosition, "Writer position not found for unwind.");
+
+  const wpAddr = toAddress(writerPositionAddress);
+  const vaultLoansAll = loans.filter(
+    (item) => toAddress(item.data.vault) === vaultPdaStr && Number(item.data.status) === 1
+  );
+  const matchingLoans = writerPositionHasOngoingPoolLoanDebt(writerPosition)
+    ? vaultLoansAll.filter((item) => toAddress(item.data.writerPosition) === wpAddr)
+    : [];
+
+  // Mirror preflight: pick exactly `activeLoanCount` loans (top-N by nonce DESC) and verify
+  // their principal sum matches `writer.borrowed_principal`. Orphan status==1 PoolLoans
+  // not tracked by the writer would otherwise inflate `snapshot.active_loan_count` and
+  // trip the on-chain MaintenanceLoansIncomplete invariant.
+  const sortByNonceDesc = (
+    a: (typeof matchingLoans)[number],
+    b: (typeof matchingLoans)[number]
+  ) => {
+    if (a.data.nonce > b.data.nonce) return -1;
+    if (a.data.nonce < b.data.nonce) return 1;
+    return String(a.address).localeCompare(String(b.address));
+  };
+  const vaultLoans = writerPositionHasOngoingPoolLoanDebt(writerPosition)
+    ? matchingLoans.slice().sort(sortByNonceDesc).slice(0, writerPosition.activeLoanCount)
+    : [];
+
+  if (writerPositionHasOngoingPoolLoanDebt(writerPosition)) {
+    invariant(
+      vaultLoans.length === writerPosition.activeLoanCount,
+      `Expected ${writerPosition.activeLoanCount} active pool loan(s) for this writer position; only found ${matchingLoans.length} matching. Refresh positions.`
+    );
+    const selectedPrincipalSum = vaultLoans.reduce(
+      (sum, item) => sum + BigInt(item.data.principal),
+      0n
+    );
+    const writerBorrowedPrincipal = BigInt(writerPosition.borrowedPrincipal);
+    invariant(
+      selectedPrincipalSum === writerBorrowedPrincipal,
+      `Active pool loan principal mismatch: top-${writerPosition.activeLoanCount} loans sum to ${selectedPrincipalSum} but writer.borrowed_principal=${writerBorrowedPrincipal}. On-chain state is inconsistent (orphan PoolLoans). Use the keeper rescue path.`
+    );
+  }
+
+  invariant(
+    vaultLoans.length <= MAX_POOL_LOANS_PER_UNWIND,
+    `Too many active pool loans for unwind: ${vaultLoans.length}. Max supported in one unwind is ${MAX_POOL_LOANS_PER_UNWIND}.`
+  );
+
+  const remainingAccounts: RemainingAccountInput[] = vaultLoans.map((item) => ({
+    address: item.address,
+    isWritable: true,
+  }));
+
+  const omlpVault = await deriveAssociatedTokenAddress(vaultPda, underlyingMint);
+  const feeWallet = vault
+    ? await deriveAssociatedTokenAddress(vault.feeWallet, underlyingMint)
+    : undefined;
+
+  // Theta-hedge model: if proportional debt cannot be covered by
+  // `theta_available + proportional_collateral`, the on-chain path reverts
+  // with `LiquidationInsufficientCollateralForDebt`. Writer-wallet fallback
+  // has been removed; the keeper-gated rescue ix handles insolvent
+  // positions instead.
+  const preflight = await preflightUnwindWriterUnsold({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    writer: params.writer,
+    unwindQty: params.unwindQty,
+    rpc: params.rpc,
+    programId: params.programId,
+    underlyingMint,
+  });
+  invariant(
+    preflight.canRepayRequestedSlice,
+    `Unwind cannot repay the requested slice from collateral vault + theta. required=${preflight.summary.proportionalTotalOwed} collateral_available=${preflight.summary.collateralVaultAvailable}. Use liquidate_writer_position_rescue if the position is insolvent.`
+  );
+
+  return await buildUnwindWriterUnsoldTransactionWithDerivation({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    writer: params.writer,
+    unwindQty: preflight.effectiveUnwindQty,
+    rpc: params.rpc,
+    programId: params.programId,
+    omlpVaultState: vaultPda,
+    omlpVault,
+    feeWallet,
+    remainingAccounts,
+  });
+}
+
+export async function buildUnwindWriterUnsoldTransactionWithDerivation(
+  params: BuildUnwindWriterUnsoldTransactionWithDerivationParams
+): Promise<BuiltTransaction> {
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  invariant(
+    !!resolved.escrowLongAccount &&
+      !!resolved.premiumVault &&
+      !!resolved.collateralVault &&
+      !!resolved.underlyingMint,
+    "Option pool and collateral pool must exist; ensure rpc is provided and pools are initialized."
+  );
+
+  const [writerShortAccount, writerCollateralAccount, writerPosition] =
+    await Promise.all([
+      deriveAssociatedTokenAddress(params.writer, resolved.shortMint),
+      deriveAssociatedTokenAddress(params.writer, resolved.underlyingMint),
+      deriveWriterPositionPda(resolved.optionPool, params.writer, params.programId),
+    ]);
+
+  return buildUnwindWriterUnsoldTransaction({
+    optionPool: resolved.optionPool,
+    optionAccount: resolved.optionAccount,
+    marketData: resolved.marketData,
+    longMint: resolved.longMint,
+    shortMint: resolved.shortMint,
+    escrowLongAccount: resolved.escrowLongAccount!,
+    writerShortAccount,
+    collateralVault: resolved.collateralVault!,
+    premiumVault: resolved.premiumVault!,
+    writerCollateralAccount,
+    writer: params.writer,
+    unwindQty: params.unwindQty,
+    collateralPool: resolved.collateralPool,
+    writerPosition: writerPosition[0],
+    omlpVaultState: params.omlpVaultState,
+    omlpVault: params.omlpVault,
+    feeWallet: params.feeWallet,
+    remainingAccounts: params.remainingAccounts,
+  });
+}
+
+export function buildSyncWriterPositionInstruction(
+  params: BuildSyncWriterPositionParams
+): Instruction<string> {
+  const kitInstruction = getSyncWriterPositionInstruction({
+    optionPool: toAddress(params.optionPool),
+    optionAccount: toAddress(params.optionAccount),
+    writerPosition: toAddress(params.writerPosition),
+  });
+  return kitInstruction;
+}
+
+export function buildSyncWriterPositionTransaction(
+  params: BuildSyncWriterPositionParams
+): BuiltTransaction {
+  const instruction = buildSyncWriterPositionInstruction(params);
+  return { instructions: [instruction] };
+}
+
+export async function buildSettleMakerCollateralInstruction(
+  params: BuildSettleMakerCollateralParams
+): Promise<Instruction<string>> {
+  const makerCollateralShare =
+    params.makerCollateralShare ??
+    (params.collateralPool
+      ? (await deriveMakerCollateralSharePda(params.collateralPool, params.maker))[0]
+      : undefined);
+
+  invariant(
+    !!makerCollateralShare,
+    "makerCollateralShare is required (or provide collateralPool + maker to derive)."
+  );
+
+  const kitInstruction = await getSettleMakerCollateralInstructionAsync({
+    optionAccount: toAddress(params.optionAccount),
+    collateralPool: params.collateralPool ? toAddress(params.collateralPool) : undefined,
+    makerCollateralShare: toAddress(makerCollateralShare),
+    collateralVault: toAddress(params.collateralVault),
+    makerCollateralAccount: toAddress(params.makerCollateralAccount),
+    omlpVault: toAddress(params.omlpVault),
+    omlpVaultState: toAddress(params.omlpVaultState),
+    poolLoan: toAddress(params.poolLoan),
+  });
+  return kitInstruction;
+}
+
+export async function buildSettleMakerCollateralTransaction(
+  params: BuildSettleMakerCollateralParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildSettleMakerCollateralInstruction(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
+ * transaction will revert with `RescueUnauthorized` if the signer's pubkey
+ * does not match the vault's keeper.
+ */
+export interface BuildLiquidateWriterPositionRescueParams {
+  optionPool: AddressLike;
+  optionAccount: AddressLike;
+  /** Market data PDA (`["market_data", underlying_asset]`). */
+  marketData: AddressLike;
+  collateralPool: AddressLike;
+  writerPosition: AddressLike;
+  longMint: AddressLike;
+  escrowLongAccount: AddressLike;
+  /** OMLP Vault state PDA (mut: decrements total_loans, writes bad_debt_lamports). */
+  omlpVault: AddressLike;
+  collateralVault: AddressLike;
+  premiumVault: AddressLike;
+  omlpVaultTokenAccount: AddressLike;
+  feeWallet: AddressLike;
+  /** Vault keeper — must sign and match `Vault::keeper`. */
+  keeper: TransactionSigner<string>;
+  /** Every active PoolLoan for this writer/vault (SDK: loadWriterLoans). */
+  remainingAccounts?: RemainingAccountInput[];
+}
+
+export async function buildLiquidateWriterPositionRescueInstruction(
+  params: BuildLiquidateWriterPositionRescueParams
+): Promise<Instruction<string>> {
+  const kitInstruction = await getLiquidateWriterPositionRescueInstructionAsync({
+    optionPool: toAddress(params.optionPool),
+    optionAccount: toAddress(params.optionAccount),
+    marketData: toAddress(params.marketData),
+    collateralPool: toAddress(params.collateralPool),
+    writerPosition: toAddress(params.writerPosition),
+    longMint: toAddress(params.longMint),
+    escrowLongAccount: toAddress(params.escrowLongAccount),
+    omlpVault: toAddress(params.omlpVault),
+    collateralVault: toAddress(params.collateralVault),
+    premiumVault: toAddress(params.premiumVault),
+    omlpVaultTokenAccount: toAddress(params.omlpVaultTokenAccount),
+    feeWallet: toAddress(params.feeWallet),
+    keeper: params.keeper as any,
+  });
+  return appendRemainingAccounts(kitInstruction, params.remainingAccounts);
+}
+
+export async function buildLiquidateWriterPositionRescueTransaction(
+  params: BuildLiquidateWriterPositionRescueParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildLiquidateWriterPositionRescueInstruction(params);
+  return { instructions: [instruction] };
+}