@epicentral/sos-sdk 0.3.0-alpha.2 → 0.4.0-alpha.1

package/README.md

@@ -88,7 +88,11 @@ Borrow/repay for writers: use `buildOptionMintTransactionWithDerivation` (with v
 
 ## Unwind with Loan Repayment
 
-When a writer unwinds an unsold short that had borrowed from the OMLP pool, the program repays lenders from the collateral vault inside `unwind_writer_unsold` (burn LONG+SHORT, repay loans, then return collateral to writer) in one instruction.
+When a writer unwinds an unsold short that had borrowed from the OMLP pool, the program now repays in this order inside `unwind_writer_unsold`:
+
+1. Collateral vault funds first.
+2. Writer fallback wallet source (`writerRepaymentAccount`) for any shortfall.
+3. If combined funds cannot cover principal + interest + protocol fees, unwind fails with a protocol custom error (not a generic SPL `0x1`).
 
 Use **`buildUnwindWriterUnsoldWithLoanRepayment`** so that:
 
@@ -97,12 +101,51 @@ Use **`buildUnwindWriterUnsoldWithLoanRepayment`** so that:
 3. `remaining_accounts` = **[PoolLoan₁, PoolLoan₂, ...]** only (capped at 20 loans per tx).
 4. One transaction burns, repays lenders from collateral vault, and returns collateral to the writer.
 
+Use **`preflightUnwindWriterUnsold`** before building the transaction to get:
+
+- Per-loan principal/interest/protocol-fee breakdown.
+- Aggregate owed, collateral-vault available, wallet fallback required, and shortfall.
+- `canRepayFully` so UI can block early with actionable messaging.
+
 If there are no active pool loans for that vault, the API still works and passes empty `remaining_accounts`.
 
 **Alternative (repay then unwind):** For writers with more than ~20 active loans, (1) build `repay_pool_loan_from_collateral` instructions first to reduce loans, then (2) unwind with the remaining loans.
 
 **Stuck loan (InsufficientEscrowBalance):** When standard repay fails with `InsufficientEscrowBalance` (escrow underfunded or drained), use `buildRepayPoolLoanFromWalletInstruction` or `buildRepayPoolLoanFromWalletTransaction`. Same accounts as `buildRepayPoolLoanInstruction`; maker pays full principal + interest + fees from their wallet.
 
+### Recommended Preflight + Unwind
+
+```ts
+import {
+  preflightUnwindWriterUnsold,
+  buildUnwindWriterUnsoldWithLoanRepayment,
+} from "@epicentral/sos-sdk";
+
+const preflight = await preflightUnwindWriterUnsold({
+  underlyingAsset,
+  optionType,
+  strikePrice,
+  expirationDate,
+  writer,
+  unwindQty,
+  rpc,
+});
+
+if (!preflight.canRepayFully) {
+  throw new Error(`Unwind blocked. Shortfall: ${preflight.summary.shortfall.toString()}`);
+}
+
+const tx = await buildUnwindWriterUnsoldWithLoanRepayment({
+  underlyingAsset,
+  optionType,
+  strikePrice,
+  expirationDate,
+  writer,
+  unwindQty,
+  rpc,
+});
+```
+
 ## Usage Examples
 
 ### Buy from pool (with derivation)

package/generated/errors/optionProgram.ts

@@ -184,6 +184,12 @@ export const OPTION_PROGRAM_ERROR__INVALID_ESCROW_MINT = 0x17c2; // 6082
 export const OPTION_PROGRAM_ERROR__ACCOUNT_FROZEN = 0x17c3; // 6083
 /** InvalidAccount: Invalid account - does not match expected account */
 export const OPTION_PROGRAM_ERROR__INVALID_ACCOUNT = 0x17c4; // 6084
+/** UnwindRepayAccountsMissing: Unwind repayment accounts are required when active pool loans exist */
+export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_ACCOUNTS_MISSING = 0x17c5; // 6085
+/** UnwindRepayWalletSourceMissing: Writer repayment account is required for unwind shortfall fallback */
+export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_WALLET_SOURCE_MISSING = 0x17c6; // 6086
+/** UnwindRepayInsufficientTotalFunds: Insufficient total funds to fully repay unwind loans (principal + interest + protocol fees) */
+export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_INSUFFICIENT_TOTAL_FUNDS = 0x17c7; // 6087
 
 export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__ACCOUNT_FROZEN
@@ -270,6 +276,9 @@ export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__UNAUTHORIZED_OMLP
   | typeof OPTION_PROGRAM_ERROR__UNDERLYING_ASSET_MISMATCH
   | typeof OPTION_PROGRAM_ERROR__UNHEALTHY_POSITION
+  | typeof OPTION_PROGRAM_ERROR__UNWIND_REPAY_ACCOUNTS_MISSING
+  | typeof OPTION_PROGRAM_ERROR__UNWIND_REPAY_INSUFFICIENT_TOTAL_FUNDS
+  | typeof OPTION_PROGRAM_ERROR__UNWIND_REPAY_WALLET_SOURCE_MISSING
   | typeof OPTION_PROGRAM_ERROR__VALIDATION_REQUIRED;
 
 let optionProgramErrorMessages: Record<OptionProgramError, string> | undefined;
@@ -359,6 +368,9 @@ if (process.env.NODE_ENV !== "production") {
     [OPTION_PROGRAM_ERROR__UNAUTHORIZED_OMLP]: `Unauthorized to perform this OMLP action`,
     [OPTION_PROGRAM_ERROR__UNDERLYING_ASSET_MISMATCH]: `Underlying asset mismatch - market data or mint does not match option`,
     [OPTION_PROGRAM_ERROR__UNHEALTHY_POSITION]: `Health ratio below liquidation threshold`,
+    [OPTION_PROGRAM_ERROR__UNWIND_REPAY_ACCOUNTS_MISSING]: `Unwind repayment accounts are required when active pool loans exist`,
+    [OPTION_PROGRAM_ERROR__UNWIND_REPAY_INSUFFICIENT_TOTAL_FUNDS]: `Insufficient total funds to fully repay unwind loans (principal + interest + protocol fees)`,
+    [OPTION_PROGRAM_ERROR__UNWIND_REPAY_WALLET_SOURCE_MISSING]: `Writer repayment account is required for unwind shortfall fallback`,
     [OPTION_PROGRAM_ERROR__VALIDATION_REQUIRED]: `Must call option_validate before borrow/settlement`,
   };
 }

package/generated/instructions/unwindWriterUnsold.ts

@@ -66,6 +66,7 @@ export type UnwindWriterUnsoldInstruction<
   TAccountOmlpVaultState extends string | AccountMeta<string> = string,
   TAccountOmlpVault extends string | AccountMeta<string> = string,
   TAccountFeeWallet extends string | AccountMeta<string> = string,
+  TAccountWriterRepaymentAccount extends string | AccountMeta<string> = string,
   TAccountWriter extends string | AccountMeta<string> = string,
   TAccountTokenProgram extends string | AccountMeta<string> =
     "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
@@ -115,6 +116,9 @@ export type UnwindWriterUnsoldInstruction<
       TAccountFeeWallet extends string
         ? WritableAccount<TAccountFeeWallet>
         : TAccountFeeWallet,
+      TAccountWriterRepaymentAccount extends string
+        ? WritableAccount<TAccountWriterRepaymentAccount>
+        : TAccountWriterRepaymentAccount,
       TAccountWriter extends string
         ? WritableSignerAccount<TAccountWriter> &
             AccountSignerMeta<TAccountWriter>
@@ -182,6 +186,7 @@ export type UnwindWriterUnsoldAsyncInput<
   TAccountOmlpVaultState extends string = string,
   TAccountOmlpVault extends string = string,
   TAccountFeeWallet extends string = string,
+  TAccountWriterRepaymentAccount extends string = string,
   TAccountWriter extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountSystemProgram extends string = string,
@@ -212,6 +217,8 @@ export type UnwindWriterUnsoldAsyncInput<
   omlpVault?: Address<TAccountOmlpVault>;
   /** Protocol fee wallet (receives protocol fees) - optional */
   feeWallet?: Address<TAccountFeeWallet>;
+  /** Writer wallet source for shortfall fallback during unwind loan repayment - optional */
+  writerRepaymentAccount?: Address<TAccountWriterRepaymentAccount>;
   writer: TransactionSigner<TAccountWriter>;
   tokenProgram?: Address<TAccountTokenProgram>;
   systemProgram?: Address<TAccountSystemProgram>;
@@ -232,6 +239,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
   TAccountOmlpVaultState extends string,
   TAccountOmlpVault extends string,
   TAccountFeeWallet extends string,
+  TAccountWriterRepaymentAccount extends string,
   TAccountWriter extends string,
   TAccountTokenProgram extends string,
   TAccountSystemProgram extends string,
@@ -251,6 +259,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
     TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
+    TAccountWriterRepaymentAccount,
     TAccountWriter,
     TAccountTokenProgram,
     TAccountSystemProgram
@@ -272,6 +281,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
     TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
+    TAccountWriterRepaymentAccount,
     TAccountWriter,
     TAccountTokenProgram,
     TAccountSystemProgram
@@ -305,6 +315,10 @@ export async function getUnwindWriterUnsoldInstructionAsync<
     omlpVaultState: { value: input.omlpVaultState ?? null, isWritable: true },
     omlpVault: { value: input.omlpVault ?? null, isWritable: true },
     feeWallet: { value: input.feeWallet ?? null, isWritable: true },
+    writerRepaymentAccount: {
+      value: input.writerRepaymentAccount ?? null,
+      isWritable: true,
+    },
     writer: { value: input.writer ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
     systemProgram: { value: input.systemProgram ?? null, isWritable: false },
@@ -372,6 +386,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
       getAccountMeta(accounts.omlpVaultState),
       getAccountMeta(accounts.omlpVault),
       getAccountMeta(accounts.feeWallet),
+      getAccountMeta(accounts.writerRepaymentAccount),
       getAccountMeta(accounts.writer),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.systemProgram),
@@ -395,6 +410,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
     TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
+    TAccountWriterRepaymentAccount,
     TAccountWriter,
     TAccountTokenProgram,
     TAccountSystemProgram
@@ -415,6 +431,7 @@ export type UnwindWriterUnsoldInput<
   TAccountOmlpVaultState extends string = string,
   TAccountOmlpVault extends string = string,
   TAccountFeeWallet extends string = string,
+  TAccountWriterRepaymentAccount extends string = string,
   TAccountWriter extends string = string,
   TAccountTokenProgram extends string = string,
   TAccountSystemProgram extends string = string,
@@ -445,6 +462,8 @@ export type UnwindWriterUnsoldInput<
   omlpVault?: Address<TAccountOmlpVault>;
   /** Protocol fee wallet (receives protocol fees) - optional */
   feeWallet?: Address<TAccountFeeWallet>;
+  /** Writer wallet source for shortfall fallback during unwind loan repayment - optional */
+  writerRepaymentAccount?: Address<TAccountWriterRepaymentAccount>;
   writer: TransactionSigner<TAccountWriter>;
   tokenProgram?: Address<TAccountTokenProgram>;
   systemProgram?: Address<TAccountSystemProgram>;
@@ -465,6 +484,7 @@ export function getUnwindWriterUnsoldInstruction<
   TAccountOmlpVaultState extends string,
   TAccountOmlpVault extends string,
   TAccountFeeWallet extends string,
+  TAccountWriterRepaymentAccount extends string,
   TAccountWriter extends string,
   TAccountTokenProgram extends string,
   TAccountSystemProgram extends string,
@@ -484,6 +504,7 @@ export function getUnwindWriterUnsoldInstruction<
     TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
+    TAccountWriterRepaymentAccount,
     TAccountWriter,
     TAccountTokenProgram,
     TAccountSystemProgram
@@ -504,6 +525,7 @@ export function getUnwindWriterUnsoldInstruction<
   TAccountOmlpVaultState,
   TAccountOmlpVault,
   TAccountFeeWallet,
+  TAccountWriterRepaymentAccount,
   TAccountWriter,
   TAccountTokenProgram,
   TAccountSystemProgram
@@ -536,6 +558,10 @@ export function getUnwindWriterUnsoldInstruction<
     omlpVaultState: { value: input.omlpVaultState ?? null, isWritable: true },
     omlpVault: { value: input.omlpVault ?? null, isWritable: true },
     feeWallet: { value: input.feeWallet ?? null, isWritable: true },
+    writerRepaymentAccount: {
+      value: input.writerRepaymentAccount ?? null,
+      isWritable: true,
+    },
     writer: { value: input.writer ?? null, isWritable: true },
     tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
     systemProgram: { value: input.systemProgram ?? null, isWritable: false },
@@ -574,6 +600,7 @@ export function getUnwindWriterUnsoldInstruction<
       getAccountMeta(accounts.omlpVaultState),
       getAccountMeta(accounts.omlpVault),
       getAccountMeta(accounts.feeWallet),
+      getAccountMeta(accounts.writerRepaymentAccount),
       getAccountMeta(accounts.writer),
       getAccountMeta(accounts.tokenProgram),
       getAccountMeta(accounts.systemProgram),
@@ -597,6 +624,7 @@ export function getUnwindWriterUnsoldInstruction<
     TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
+    TAccountWriterRepaymentAccount,
     TAccountWriter,
     TAccountTokenProgram,
     TAccountSystemProgram
@@ -635,9 +663,11 @@ export type ParsedUnwindWriterUnsoldInstruction<
     omlpVault?: TAccountMetas[11] | undefined;
     /** Protocol fee wallet (receives protocol fees) - optional */
     feeWallet?: TAccountMetas[12] | undefined;
-    writer: TAccountMetas[13];
-    tokenProgram: TAccountMetas[14];
-    systemProgram: TAccountMetas[15];
+    /** Writer wallet source for shortfall fallback during unwind loan repayment - optional */
+    writerRepaymentAccount?: TAccountMetas[13] | undefined;
+    writer: TAccountMetas[14];
+    tokenProgram: TAccountMetas[15];
+    systemProgram: TAccountMetas[16];
   };
   data: UnwindWriterUnsoldInstructionData;
 };
@@ -650,7 +680,7 @@ export function parseUnwindWriterUnsoldInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedUnwindWriterUnsoldInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 16) {
+  if (instruction.accounts.length < 17) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -682,6 +712,7 @@ export function parseUnwindWriterUnsoldInstruction<
       omlpVaultState: getNextOptionalAccount(),
       omlpVault: getNextOptionalAccount(),
       feeWallet: getNextOptionalAccount(),
+      writerRepaymentAccount: getNextOptionalAccount(),
       writer: getNextAccount(),
       tokenProgram: getNextAccount(),
       systemProgram: getNextAccount(),

package/generated/programs/optionProgram.ts

@@ -88,7 +88,7 @@ import {
 } from "../instructions";
 
 export const OPTION_PROGRAM_PROGRAM_ADDRESS =
-  "AoLSsFTxnpa488AYf3RS2bwrv53zZY9aFYSFCAheek8q" as Address<"AoLSsFTxnpa488AYf3RS2bwrv53zZY9aFYSFCAheek8q">;
+  "818mtjAGCGMfFAmnuQummzyFweVw1odD7gcAT32iTjDz" as Address<"818mtjAGCGMfFAmnuQummzyFweVw1odD7gcAT32iTjDz">;
 
 export enum OptionProgramAccount {
   CollateralPool,
@@ -679,7 +679,7 @@ export function identifyOptionProgramInstruction(
 }
 
 export type ParsedOptionProgramInstruction<
-  TProgram extends string = "AoLSsFTxnpa488AYf3RS2bwrv53zZY9aFYSFCAheek8q",
+  TProgram extends string = "818mtjAGCGMfFAmnuQummzyFweVw1odD7gcAT32iTjDz",
 > =
   | ({
       instructionType: OptionProgramInstruction.AcceptAdmin;

package/index.ts

@@ -25,6 +25,7 @@ export * from "./short/builders";
 export * from "./short/claim-theta";
 export * from "./short/close-option";
 export * from "./short/pool";
+export * from "./short/preflight";
 
 export * from "./omlp/builders";
 export * from "./omlp/service";

package/package.json

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

package/short/builders.ts

@@ -5,7 +5,7 @@ import {
   getUnwindWriterUnsoldInstructionAsync,
   type OptionType,
 } from "../generated";
-import type { Instruction } from "@solana/kit";
+import type { Instruction, TransactionSigner } from "@solana/kit";
 import { toAddress } from "../client/program";
 import type { AddressLike, BuiltTransaction, KitRpc } from "../client/types";
 import { fetchVault } from "../accounts/fetchers";
@@ -24,7 +24,12 @@ import {
   appendRemainingAccounts,
   type RemainingAccountInput,
 } from "../shared/remaining-accounts";
-import { getCreateAssociatedTokenIdempotentInstructionWithAddress } from "../wsol/instructions";
+import {
+  NATIVE_MINT,
+  getCreateAssociatedTokenIdempotentInstructionWithAddress,
+  getWrapSOLInstructions,
+} from "../wsol/instructions";
+import { preflightUnwindWriterUnsold } from "./preflight";
 
 export interface BuildOptionMintParams {
   optionType: OptionType;
@@ -81,6 +86,7 @@ export interface BuildUnwindWriterUnsoldParams {
   omlpVaultState?: AddressLike;
   omlpVault?: AddressLike;
   feeWallet?: AddressLike;
+  writerRepaymentAccount?: AddressLike;
   remainingAccounts?: RemainingAccountInput[];
 }
 
@@ -304,23 +310,28 @@ export async function buildUnwindWriterUnsoldInstruction(
 ): Promise<Instruction<string>> {
   assertPositiveAmount(params.unwindQty, "unwindQty");
 
-  const kitInstruction = await getUnwindWriterUnsoldInstructionAsync({
-    optionPool: toAddress(params.optionPool),
-    optionAccount: toAddress(params.optionAccount),
-    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),
-    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,
-  });
+  const kitInstruction = await getUnwindWriterUnsoldInstructionAsync(
+    {
+      optionPool: toAddress(params.optionPool),
+      optionAccount: toAddress(params.optionAccount),
+      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),
+      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,
+      writerRepaymentAccount: params.writerRepaymentAccount
+        ? toAddress(params.writerRepaymentAccount)
+        : undefined,
+      writer: toAddress(params.writer) as any,
+      unwindQty: params.unwindQty,
+    } as any
+  );
 
   return appendRemainingAccounts(kitInstruction, params.remainingAccounts);
 }
@@ -344,6 +355,7 @@ export interface BuildUnwindWriterUnsoldTransactionWithDerivationParams {
   omlpVaultState?: AddressLike;
   omlpVault?: AddressLike;
   feeWallet?: AddressLike;
+  writerRepaymentAccount?: AddressLike;
   /**
    * When repaying pool loans: [PoolLoan₁, PoolLoan₂, ...] (all writable).
    * omlpVaultState, omlpVault, feeWallet must also be passed.
@@ -363,6 +375,15 @@ export interface BuildUnwindWriterUnsoldWithLoanRepaymentParams {
   programId?: AddressLike;
   /** Override when pool fetch is not used; otherwise resolved from option pool. */
   underlyingMint?: AddressLike;
+  /** Optional explicit fallback source account. Defaults to writer ATA for underlying mint. */
+  writerRepaymentAccount?: AddressLike;
+  /**
+   * When true and underlying mint is WSOL, prepend wrap instructions for the
+   * detected wallet shortfall before unwind.
+   */
+  includeWrapForShortfall?: boolean;
+  /** Signer required when includeWrapForShortfall=true for WSOL paths. */
+  writerSigner?: TransactionSigner<string>;
 }
 
 /**
@@ -414,8 +435,27 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
   const feeWallet = vault
     ? await deriveAssociatedTokenAddress(vault.feeWallet, underlyingMint)
     : undefined;
+  const writerRepaymentAccount =
+    params.writerRepaymentAccount ??
+    (await deriveAssociatedTokenAddress(params.writer, underlyingMint));
 
-  return buildUnwindWriterUnsoldTransactionWithDerivation({
+  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.canRepayFully,
+    `Unwind cannot fully repay loans: shortfall=${preflight.summary.shortfall}`
+  );
+
+  const unwindTx = await buildUnwindWriterUnsoldTransactionWithDerivation({
     underlyingAsset: params.underlyingAsset,
     optionType: params.optionType,
     strikePrice: params.strikePrice,
@@ -427,8 +467,30 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     omlpVaultState: vaultPda,
     omlpVault,
     feeWallet,
+    writerRepaymentAccount,
     remainingAccounts,
   });
+
+  if (
+    params.includeWrapForShortfall &&
+    toAddress(underlyingMint) === toAddress(NATIVE_MINT) &&
+    preflight.summary.walletFallbackRequired > 0n
+  ) {
+    invariant(
+      !!params.writerSigner,
+      "writerSigner is required when includeWrapForShortfall=true for WSOL shortfall top-up."
+    );
+    const wrapInstructions = await getWrapSOLInstructions({
+      payer: params.writerSigner,
+      owner: params.writer,
+      lamports: preflight.summary.walletFallbackRequired,
+    });
+    return {
+      instructions: [...wrapInstructions, ...unwindTx.instructions],
+    };
+  }
+
+  return unwindTx;
 }
 
 export async function buildUnwindWriterUnsoldTransactionWithDerivation(
@@ -471,6 +533,7 @@ export async function buildUnwindWriterUnsoldTransactionWithDerivation(
     omlpVaultState: params.omlpVaultState,
     omlpVault: params.omlpVault,
     feeWallet: params.feeWallet,
+    writerRepaymentAccount: params.writerRepaymentAccount,
     remainingAccounts: params.remainingAccounts,
   });
 }

package/short/preflight.ts

@@ -0,0 +1,248 @@
+import { toAddress } from "../client/program";
+import type { AddressLike, KitRpc } from "../client/types";
+import type { OptionType } from "../generated";
+import { fetchCollateralPool, fetchVault, fetchWriterPosition } from "../accounts/fetchers";
+import { fetchPoolLoansByMaker } from "../accounts/list";
+import { deriveAssociatedTokenAddress, deriveVaultPda, deriveWriterPositionPda } from "../accounts/pdas";
+import { resolveOptionAccounts } from "../accounts/resolve-option";
+import { invariant } from "../shared/errors";
+
+const TOKEN_ACCOUNT_AMOUNT_OFFSET = 64;
+const BPS_DENOMINATOR = 10_000n;
+
+function readTokenAccountAmount(data: Uint8Array): bigint {
+  if (data.length < TOKEN_ACCOUNT_AMOUNT_OFFSET + 8) return 0n;
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return view.getBigUint64(TOKEN_ACCOUNT_AMOUNT_OFFSET, true);
+}
+
+async function fetchTokenAmount(rpc: KitRpc, tokenAccount: AddressLike): Promise<bigint> {
+  const response = await rpc.getAccountInfo(toAddress(tokenAccount), { encoding: "base64" }).send();
+  const info = response.value;
+  if (!info) return 0n;
+  const [base64Data] = info.data;
+  if (!base64Data) return 0n;
+  const decoded = atob(base64Data);
+  const bytes = new Uint8Array(decoded.length);
+  for (let i = 0; i < decoded.length; i++) bytes[i] = decoded.charCodeAt(i);
+  return readTokenAccountAmount(bytes);
+}
+
+function toBigInt(value: bigint | number): bigint {
+  return typeof value === "bigint" ? value : BigInt(value);
+}
+
+export interface PreflightUnwindWriterUnsoldParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  writer: AddressLike;
+  unwindQty: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+  underlyingMint?: AddressLike;
+  writerRepaymentAccount?: AddressLike;
+}
+
+export interface UnwindLoanBreakdown {
+  loanAddress: string;
+  principal: bigint;
+  accruedInterest: bigint;
+  accruedProtocolFees: bigint;
+  newlyAccruedInterest: bigint;
+  newlyAccruedProtocolFees: bigint;
+  totalInterest: bigint;
+  totalProtocolFees: bigint;
+  totalOwed: bigint;
+}
+
+export interface UnwindPreflightSummary {
+  activeLoanCount: number;
+  totalPrincipal: bigint;
+  totalInterest: bigint;
+  totalProtocolFees: bigint;
+  totalOwed: bigint;
+  collateralVaultAvailable: bigint;
+  walletFallbackAvailable: bigint;
+  walletFallbackRequired: bigint;
+  shortfall: bigint;
+}
+
+export interface UnwindPreflightResult {
+  canUnwind: boolean;
+  canRepayFully: boolean;
+  reason?: string;
+  writerPositionAddress: string;
+  writerRepaymentAccount: string;
+  collateralVaultAddress: string;
+  loans: Array<UnwindLoanBreakdown>;
+  summary: UnwindPreflightSummary;
+}
+
+export async function preflightUnwindWriterUnsold(
+  params: PreflightUnwindWriterUnsoldParams
+): Promise<UnwindPreflightResult> {
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  invariant(
+    !!resolved.collateralVault && !!resolved.collateralPool && !!resolved.underlyingMint,
+    "Option/collateral pool state is required for unwind preflight."
+  );
+
+  const underlyingMint = params.underlyingMint ?? resolved.underlyingMint;
+  const [vaultPda] = await deriveVaultPda(underlyingMint, params.programId);
+  const vaultPdaAddress = toAddress(vaultPda);
+  const writerRepaymentAccount =
+    params.writerRepaymentAccount ??
+    (await deriveAssociatedTokenAddress(params.writer, underlyingMint));
+  const writerRepaymentAddress = toAddress(writerRepaymentAccount);
+  const [writerPositionAddress] = await deriveWriterPositionPda(
+    resolved.optionPool,
+    params.writer,
+    params.programId
+  );
+
+  const [writerPosition, collateralPool, vault, loans, currentSlot] = await Promise.all([
+    fetchWriterPosition(params.rpc, writerPositionAddress),
+    fetchCollateralPool(params.rpc, resolved.collateralPool),
+    fetchVault(params.rpc, vaultPda),
+    fetchPoolLoansByMaker(params.rpc, params.writer),
+    params.rpc.getSlot().send(),
+  ]);
+
+  invariant(!!writerPosition, "Writer position is required for unwind preflight.");
+  invariant(!!collateralPool, "Collateral pool is required for unwind preflight.");
+  invariant(!!vault, "Vault state is required for unwind preflight.");
+
+  const unwindQty = toBigInt(params.unwindQty);
+  const unsoldQty = toBigInt(writerPosition.unsoldQty);
+  if (unwindQty <= 0n) {
+    return {
+      canUnwind: false,
+      canRepayFully: false,
+      reason: "unwindQty must be > 0",
+      writerPositionAddress: String(writerPositionAddress),
+      writerRepaymentAccount: String(writerRepaymentAddress),
+      collateralVaultAddress: String(resolved.collateralVault),
+      loans: [],
+      summary: {
+        activeLoanCount: 0,
+        totalPrincipal: 0n,
+        totalInterest: 0n,
+        totalProtocolFees: 0n,
+        totalOwed: 0n,
+        collateralVaultAvailable: 0n,
+        walletFallbackAvailable: 0n,
+        walletFallbackRequired: 0n,
+        shortfall: 0n,
+      },
+    };
+  }
+  if (unwindQty > unsoldQty) {
+    return {
+      canUnwind: false,
+      canRepayFully: false,
+      reason: "unwindQty exceeds writer unsold quantity",
+      writerPositionAddress: String(writerPositionAddress),
+      writerRepaymentAccount: String(writerRepaymentAddress),
+      collateralVaultAddress: String(resolved.collateralVault),
+      loans: [],
+      summary: {
+        activeLoanCount: 0,
+        totalPrincipal: 0n,
+        totalInterest: 0n,
+        totalProtocolFees: 0n,
+        totalOwed: 0n,
+        collateralVaultAvailable: 0n,
+        walletFallbackAvailable: 0n,
+        walletFallbackRequired: 0n,
+        shortfall: 0n,
+      },
+    };
+  }
+
+  const slotNow = toBigInt(currentSlot);
+  const protocolFeeBps = BigInt(vault.protocolFeeBps);
+  const slotsPerYear = 63_072_000n;
+  const loanBreakdown: Array<UnwindLoanBreakdown> = [];
+
+  for (const loan of loans) {
+    if (toAddress(loan.data.vault) !== vaultPdaAddress || Number(loan.data.status) !== 1) continue;
+    const principal = toBigInt(loan.data.principal);
+    const accruedInterest = toBigInt(loan.data.accruedInterest);
+    const accruedProtocolFees = toBigInt(loan.data.accruedProtocolFees);
+    const rateBps = BigInt(loan.data.rateBps);
+    const lastUpdateSlot = toBigInt(loan.data.lastUpdateSlot);
+    const slotsElapsed = slotNow > lastUpdateSlot ? slotNow - lastUpdateSlot : 0n;
+    const newlyAccruedInterest =
+      slotsElapsed > 0n ? (principal * rateBps * slotsElapsed) / BPS_DENOMINATOR / slotsPerYear : 0n;
+    const newlyAccruedProtocolFees =
+      slotsElapsed > 0n
+        ? (principal * protocolFeeBps * slotsElapsed) / BPS_DENOMINATOR / slotsPerYear
+        : 0n;
+    const totalInterest = accruedInterest + newlyAccruedInterest;
+    const totalProtocolFees = accruedProtocolFees + newlyAccruedProtocolFees;
+    const totalOwed = principal + totalInterest + totalProtocolFees;
+
+    loanBreakdown.push({
+      loanAddress: String(loan.address),
+      principal,
+      accruedInterest,
+      accruedProtocolFees,
+      newlyAccruedInterest,
+      newlyAccruedProtocolFees,
+      totalInterest,
+      totalProtocolFees,
+      totalOwed,
+    });
+  }
+
+  const totals = loanBreakdown.reduce(
+    (acc, item) => ({
+      principal: acc.principal + item.principal,
+      interest: acc.interest + item.totalInterest,
+      fees: acc.fees + item.totalProtocolFees,
+      owed: acc.owed + item.totalOwed,
+    }),
+    { principal: 0n, interest: 0n, fees: 0n, owed: 0n }
+  );
+
+  const [collateralVaultAvailable, walletFallbackAvailable] = await Promise.all([
+    fetchTokenAmount(params.rpc, resolved.collateralVault!),
+    fetchTokenAmount(params.rpc, writerRepaymentAddress),
+  ]);
+
+  const walletFallbackRequired =
+    totals.owed > collateralVaultAvailable ? totals.owed - collateralVaultAvailable : 0n;
+  const totalAvailable = collateralVaultAvailable + walletFallbackAvailable;
+  const shortfall = totals.owed > totalAvailable ? totals.owed - totalAvailable : 0n;
+
+  return {
+    canUnwind: true,
+    canRepayFully: shortfall === 0n,
+    reason: shortfall === 0n ? undefined : "Insufficient combined collateral vault + writer fallback funds",
+    writerPositionAddress: String(writerPositionAddress),
+    writerRepaymentAccount: String(writerRepaymentAddress),
+    collateralVaultAddress: String(resolved.collateralVault),
+    loans: loanBreakdown,
+    summary: {
+      activeLoanCount: loanBreakdown.length,
+      totalPrincipal: totals.principal,
+      totalInterest: totals.interest,
+      totalProtocolFees: totals.fees,
+      totalOwed: totals.owed,
+      collateralVaultAvailable,
+      walletFallbackAvailable,
+      walletFallbackRequired,
+      shortfall,
+    },
+  };
+}