@epicentral/sos-sdk 0.5.0-alpha.1 → 0.5.0-alpha.10

package/README.md

@@ -50,14 +50,14 @@ Additional modules:
 | `buildBuyFromPoolMarketOrderTransactionWithDerivation` | High-level market-order buy builder (refetches pool + remaining accounts, applies premium cap buffer). |
 | `buildBuyFromPoolTransactionWithDerivation` | Builds buy-from-pool transaction; resolves accounts from option identity. |
 | `preflightBuyFromPoolMarketOrder` | Buy preflight helper for liquidity + remaining-account coverage checks. |
-| `buildCloseLongToPoolTransactionWithDerivation` | Builds close-long-to-pool transaction. |
+| `buildCloseLongToPoolTransactionWithDerivation` | Builds close-long-to-pool transaction; by default appends CloseAccount for buyer LONG ATA and unwraps WSOL payout when underlying is SOL. |
 | `getBuyFromPoolRemainingAccounts` | Builds remaining_accounts for buy (writer positions, etc.). |
 
 ### Short (Writer) Flows
 
 | Function | Description |
 |----------|-------------|
-| `buildOptionMintTransactionWithDerivation` | Builds option mint (write) transaction. Supports multi-collateral: use `collateralMint` to back positions with any supported asset (USDC, BTC, SOL, etc.). |
+| `buildOptionMintTransactionWithDerivation` | Builds option mint (write) transaction. By default appends CloseAccount for the maker's LONG token account after mint (reclaim rent). Supports multi-collateral: use `collateralMint` to back positions with any supported asset (USDC, BTC, SOL, etc.). |
 | `buildUnwindWriterUnsoldTransactionWithDerivation` | Builds unwind unsold transaction. |
 | `buildUnwindWriterUnsoldWithLoanRepayment` | **Unwind + repay pool loans in one tx.** Use when closing unsold shorts that borrowed from OMLP. |
 | `buildSyncWriterPositionTransaction` | Syncs writer position with pool accumulators. |
@@ -73,12 +73,29 @@ Additional modules:
 | Function | Description |
 |----------|-------------|
 | `buildDepositToPositionTransaction` | Deposits liquidity to OMLP. |
-| `buildWithdrawFromPositionTransaction` | Withdraws liquidity. |
-| `withdrawAllFromPosition` | Withdraws full position (omlp/service). |
-| `withdrawInterestFromPosition` | Withdraws accrued interest only (omlp/service). |
+| `buildWithdrawFromPositionTransaction` | Withdraws liquidity; supports optional same-tx WSOL unwrap via `unwrapSol` + `vaultMint`. |
+| `withdrawAllFromPosition` | Withdraws full position (principal + proportional interest, including pending index accrual, capped by pool liquidity). |
+| `withdrawInterestFromPosition` | Withdraws interest only (realized + pending index accrual, capped by pool liquidity). |
 
 Borrow/repay for writers: use `buildOptionMintTransactionWithDerivation` (with vault/poolLoan) and `buildRepayPoolLoanFromCollateralInstruction` or `buildUnwindWriterUnsoldWithLoanRepayment`.
 
+### Token account closing (option mint and close long)
+
+- **Option mint (seller/writer):** After `option_mint`, all LONG tokens go to the pool escrow; the maker's LONG ATA is left with zero balance. The SDK **automatically appends an SPL CloseAccount instruction** (when `closeMakerLongAccount` is not set to `false`) so the maker reclaims rent. Use `buildOptionMintTransaction` or `buildOptionMintTransactionWithDerivation`; pass `closeMakerLongAccount: false` to skip closing the LONG ATA.
+- **Close long (buyer):** When the buyer closes or exercises early via `close_long_to_pool`, LONG tokens are returned to the pool and payout is sent to the buyer's payout ATA. The SDK can:
+  - **Close the buyer's LONG token account** after the close instruction so rent is reclaimed. Use `closeLongTokenAccount: true` (default for `buildCloseLongToPoolTransactionWithDerivation`); set to `false` for **partial** closes (the LONG ATA still holds remaining tokens).
+  - **Unwrap WSOL payout** when the option underlying is SOL: append CloseAccount on the payout ATA so the buyer receives native SOL. Use `unwrapPayoutSol: true` (default for WSOL in the derivation builder); set to `false` to keep payout as WSOL.
+
+### OMLP withdraw behavior
+
+- Interest is allocated proportionally via the vault interest-per-share index.
+- On-chain `withdraw_from_position` syncs pending interest before transferring funds, so a lender withdrawal automatically includes their proportional earned interest when available.
+- `withdrawAllFromPosition` and `withdrawInterestFromPosition` compute pending interest from `accInterestPerShareFp` and `interestIndexSnapshotFp`, then cap by `poolAvailable = totalLiquidity - totalLoans`.
+- Optional WSOL unwrap in the same transaction:
+  - Set `unwrapSol: true` and provide `vaultMint`.
+  - If `vaultMint === NATIVE_MINT`, SDK appends a `CloseAccount` after withdraw to unwrap WSOL ATA to native SOL.
+  - For non-WSOL mints, the same builder remains token-agnostic and does not append unwrap instructions.
+
 ### WSOL / Token Helpers
 
 | Function | Description |
@@ -179,7 +196,8 @@ Use **`preflightUnwindWriterUnsold`** before building the transaction to get:
 - **Collateral return calculation** (proportional share, returnable amount).
 - Collateral-vault available, wallet fallback required, and shortfall.
 - **Top-up UX fields:** `collateralVaultShortfall`, `needsWalletTopUp`.
-- `canRepayFully` so UI can block early with actionable messaging.
+- WSOL repay metadata: `solTopUpRequired`, `topUpRequiredForRepay`, `nativeSolAvailable`.
+- `canRepayFully`, which now reflects effective repay solvency (including native SOL top-up capacity for WSOL paths).
 
 If there are no active pool loans for that vault, the API still works and passes empty `remaining_accounts`.
 
@@ -205,10 +223,6 @@ const preflight = await preflightUnwindWriterUnsold({
   rpc,
 });
 
-if (!preflight.canRepayFully) {
-  throw new Error(`Unwind blocked. Shortfall: ${preflight.summary.shortfall.toString()}`);
-}
-
 const tx = await buildUnwindWriterUnsoldWithLoanRepayment({
   underlyingAsset,
   optionType,
@@ -217,9 +231,15 @@ const tx = await buildUnwindWriterUnsoldWithLoanRepayment({
   writer,
   unwindQty,
   rpc,
+  includeWrapForShortfall: true, // for WSOL paths, auto-wrap net top-up when needed
+  writerSigner: walletSigner,    // required when wrapping is needed
 });
 ```
 
+Notes:
+- For WSOL underlyings, the builder wraps only the net required amount: `max(0, walletFallbackRequired - walletFallbackAvailable)`.
+- If repayment is still insolvent after considering vault + fallback + native SOL top-up capacity, the builder throws an actionable insolvency error.
+
 ## Usage Examples
 
 ### Buy From Pool (market order, high-level)
@@ -283,6 +303,25 @@ The program uses distinct error codes for liquidity failures:
   1. Run `preflightBuyFromPoolMarketOrder` for UX gating (checks both pool and active writer liquidity).
   2. Build via `buildBuyFromPoolMarketOrderTransactionWithDerivation` – it refetches pool + remaining accounts and asserts active writer liquidity >= requested quantity before building.
 
+### Framework deserialization errors (`#3003`)
+
+If simulation fails with `custom program error: #3003`, this usually means account deserialization failed before business logic (`60xx`) ran.
+
+Check these first:
+
+- `buyer_position` account shape/size (`146` bytes expected).
+- `market_data` account shape/size (`128` bytes expected).
+- `priceUpdate` is a valid Pyth Receiver `PriceUpdateV2` account.
+- Account list/order matches the generated instruction layout.
+
+This is different from liquidity failures (`6042/6043`) and should be debugged as an account wiring/layout issue.
+
+### Oracle inputs (asset-agnostic)
+
+- Keep oracle handling universal across assets.
+- Provide `priceUpdate` for the selected underlying and allow program-side validation against `market_data.pyth_feed_id`.
+- Avoid hardcoding a single feed/account address in shared SDK integration flows.
+
 ### Unwind with loan repayment
 
 ```ts

package/client/lookup-table.ts

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

package/generated/programs/optionProgram.ts

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

package/long/builders.ts

@@ -17,7 +17,11 @@ import {
   type RemainingAccountInput,
 } from "../shared/remaining-accounts";
 import type { OptionType } from "../generated/types";
-import { getCreateAssociatedTokenIdempotentInstructionWithAddress, NATIVE_MINT } from "../wsol/instructions";
+import {
+  getCloseAccountInstruction,
+  getCreateAssociatedTokenIdempotentInstructionWithAddress,
+  NATIVE_MINT,
+} from "../wsol/instructions";
 import { fetchOptionPool } from "../accounts/fetchers";
 import { getBuyFromPoolRemainingAccounts } from "./remaining-accounts";
 import { fetchWriterPositionsForPool } from "../accounts/list";
@@ -58,6 +62,16 @@ export interface BuildCloseLongToPoolParams {
   minPayoutAmount: bigint | number;
   buyerPosition?: AddressLike;
   omlpVault?: AddressLike;
+  /**
+   * When true, appends an SPL CloseAccount to close the buyer's LONG token account after close_long_to_pool (reclaim rent).
+   * Set to true only when closing the entire position; for partial closes the LONG ATA still holds remaining tokens.
+   */
+  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.
+   */
+  unwrapPayoutSol?: boolean;
   remainingAccounts?: RemainingAccountInput[];
 }
 
@@ -347,7 +361,32 @@ export async function buildCloseLongToPoolTransaction(
   params: BuildCloseLongToPoolParams
 ): Promise<BuiltTransaction> {
   const instruction = await buildCloseLongToPoolInstruction(params);
-  return { instructions: [instruction] };
+  const instructions = [instruction];
+
+  if (params.closeLongTokenAccount === true) {
+    instructions.push(
+      getCloseAccountInstruction(
+        params.buyerLongAccount,
+        params.buyer,
+        params.buyer
+      )
+    );
+  }
+
+  const shouldUnwrapPayout =
+    params.unwrapPayoutSol === true &&
+    toAddress(params.underlyingMint) === toAddress(NATIVE_MINT);
+  if (shouldUnwrapPayout) {
+    instructions.push(
+      getCloseAccountInstruction(
+        params.buyerPayoutAccount,
+        params.buyer,
+        params.buyer
+      )
+    );
+  }
+
+  return { instructions };
 }
 
 export interface BuildCloseLongToPoolTransactionWithDerivationParams {
@@ -365,6 +404,16 @@ export interface BuildCloseLongToPoolTransactionWithDerivationParams {
   programId?: AddressLike;
   buyerPosition?: AddressLike;
   omlpVault?: AddressLike;
+  /**
+   * When true (default), appends CloseAccount for the buyer's LONG token account after close_long_to_pool.
+   * Set to false when doing a partial close (LONG ATA still holds remaining tokens).
+   */
+  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.
+   */
+  unwrapPayoutSol?: boolean;
   remainingAccounts?: RemainingAccountInput[];
 }
 
@@ -396,6 +445,13 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
         params.programId
       ))[0];
 
+  const isWsolUnderlying =
+    toAddress(resolved.underlyingMint!) === toAddress(NATIVE_MINT);
+  const closeLongTokenAccount =
+    params.closeLongTokenAccount !== false;
+  const unwrapPayoutSol =
+    params.unwrapPayoutSol !== false && isWsolUnderlying;
+
   return buildCloseLongToPoolTransaction({
     optionPool: resolved.optionPool,
     optionAccount: resolved.optionAccount,
@@ -414,6 +470,8 @@ export async function buildCloseLongToPoolTransactionWithDerivation(
     minPayoutAmount: params.minPayoutAmount,
     buyerPosition,
     omlpVault: params.omlpVault,
+    closeLongTokenAccount,
+    unwrapPayoutSol,
     remainingAccounts: params.remainingAccounts,
   });
 }

package/omlp/builders.ts

@@ -6,6 +6,7 @@ import type { Instruction } from "@solana/kit";
 import { toAddress } from "../client/program";
 import type { AddressLike, BuiltTransaction } from "../client/types";
 import { assertPositiveAmount } from "../shared/amounts";
+import { getCloseAccountInstruction, NATIVE_MINT } from "../wsol/instructions";
 
 export interface BuildDepositToPositionParams {
   vault: AddressLike;
@@ -23,6 +24,8 @@ export interface BuildWithdrawFromPositionParams {
   lender: AddressLike;
   amount: bigint | number;
   position?: AddressLike;
+  unwrapSol?: boolean;
+  vaultMint?: AddressLike;
 }
 
 export async function buildDepositToPositionInstruction(
@@ -69,6 +72,23 @@ export async function buildWithdrawFromPositionInstruction(
 export async function buildWithdrawFromPositionTransaction(
   params: BuildWithdrawFromPositionParams
 ): Promise<BuiltTransaction> {
-  const instruction = await buildWithdrawFromPositionInstruction(params);
-  return { instructions: [instruction] };
+  const withdrawInstruction = await buildWithdrawFromPositionInstruction(params);
+  const instructions: Instruction<string>[] = [withdrawInstruction];
+
+  const shouldUnwrapSol =
+    params.unwrapSol === true &&
+    params.vaultMint !== undefined &&
+    toAddress(params.vaultMint) === toAddress(NATIVE_MINT);
+
+  if (shouldUnwrapSol) {
+    instructions.push(
+      getCloseAccountInstruction(
+        params.lenderTokenAccount,
+        params.lender,
+        params.lender
+      )
+    );
+  }
+
+  return { instructions };
 }

package/omlp/service.ts

@@ -12,10 +12,25 @@ import {
   type BuildWithdrawFromPositionParams,
 } from "./builders";
 
+const INTEREST_FP_SCALE = 1_000_000_000_000n;
+
 function positiveDiff(a: bigint, b: bigint): bigint {
   return a > b ? a - b : 0n;
 }
 
+function calculatePendingInterest(
+  deposited: bigint,
+  vaultAccInterestPerShareFp: bigint,
+  positionInterestIndexSnapshotFp: bigint
+): bigint {
+  const deltaFp = positiveDiff(
+    vaultAccInterestPerShareFp,
+    positionInterestIndexSnapshotFp
+  );
+
+  return (deposited * deltaFp) / INTEREST_FP_SCALE;
+}
+
 export async function depositToPosition(
   params: BuildDepositToPositionParams
 ) {
@@ -50,14 +65,23 @@ export async function withdrawAllFromPosition(
     position.totalInterestEarned,
     position.interestClaimed
   );
-  const userMax = position.deposited + unclaimedInterest;
+  const pendingInterest = calculatePendingInterest(
+    position.deposited,
+    vault.accInterestPerShareFp,
+    position.interestIndexSnapshotFp
+  );
+  const userMax = position.deposited + unclaimedInterest + pendingInterest;
   const poolAvailable = positiveDiff(vault.totalLiquidity, vault.totalLoans);
   const amount = userMax < poolAvailable ? userMax : poolAvailable;
   if (amount <= 0n) {
     throw new Error("No withdrawable balance available right now.");
   }
 
-  const built = await buildWithdrawFromPositionTransaction({ ...params, amount });
+  const built = await buildWithdrawFromPositionTransaction({
+    ...params,
+    amount,
+    vaultMint: vault.mint,
+  });
   return { instructions: built.instructions, amount };
 }
 
@@ -83,13 +107,26 @@ export async function withdrawInterestFromPosition(
     position.totalInterestEarned,
     position.interestClaimed
   );
+  const pendingInterest = calculatePendingInterest(
+    position.deposited,
+    vault.accInterestPerShareFp,
+    position.interestIndexSnapshotFp
+  );
+  const totalClaimableInterest = unclaimedInterest + pendingInterest;
   const poolAvailable = positiveDiff(vault.totalLiquidity, vault.totalLoans);
-  const amount = unclaimedInterest < poolAvailable ? unclaimedInterest : poolAvailable;
+  const amount =
+    totalClaimableInterest < poolAvailable
+      ? totalClaimableInterest
+      : poolAvailable;
   if (amount <= 0n) {
     throw new Error("No claimable interest available right now.");
   }
 
-  const built = await buildWithdrawFromPositionTransaction({ ...params, amount });
+  const built = await buildWithdrawFromPositionTransaction({
+    ...params,
+    amount,
+    vaultMint: vault.mint,
+  });
   return { instructions: built.instructions, amount };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.5.0-alpha.1",
+  "version": "0.5.0-alpha.10",
   "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

@@ -25,6 +25,7 @@ import {
   type RemainingAccountInput,
 } from "../shared/remaining-accounts";
 import {
+  getCloseAccountInstruction,
   NATIVE_MINT,
   getCreateAssociatedTokenIdempotentInstructionWithAddress,
   getWrapSOLInstructions,
@@ -75,6 +76,12 @@ export interface BuildOptionMintParams {
   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[];
 }
 
@@ -213,7 +220,21 @@ export async function buildOptionMintTransaction(
   params: BuildOptionMintParams
 ): Promise<BuiltTransaction> {
   const instruction = await buildOptionMintInstruction(params);
-  return { instructions: [instruction] };
+  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 {
@@ -468,6 +489,7 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
   const writerRepaymentAccount =
     params.writerRepaymentAccount ??
     (await deriveAssociatedTokenAddress(params.writer, underlyingMint));
+  const writerDefaultRepaymentAta = await deriveAssociatedTokenAddress(params.writer, underlyingMint);
 
   const preflight = await preflightUnwindWriterUnsold({
     underlyingAsset: params.underlyingAsset,
@@ -480,10 +502,22 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     programId: params.programId,
     underlyingMint,
   });
+  const isWsolPath = toAddress(underlyingMint) === toAddress(NATIVE_MINT);
+  const lamportsToWrap =
+    preflight.summary.walletFallbackRequired > preflight.summary.walletFallbackAvailable
+      ? preflight.summary.walletFallbackRequired - preflight.summary.walletFallbackAvailable
+      : 0n;
+
   invariant(
     preflight.canRepayFully,
-    `Unwind cannot fully repay loans: shortfall=${preflight.summary.shortfall}`
+    `Unwind cannot fully repay loans: required=${preflight.summary.proportionalTotalOwed} available_now=${preflight.summary.collateralVaultAvailable + preflight.summary.walletFallbackAvailable} native_sol_available=${preflight.summary.nativeSolAvailable} remaining_shortfall=${preflight.summary.proportionalTotalOwed - (preflight.summary.collateralVaultAvailable + preflight.summary.walletFallbackAvailable + preflight.summary.nativeSolAvailable)}`
   );
+  if (isWsolPath && lamportsToWrap > 0n && !params.includeWrapForShortfall) {
+    invariant(
+      false,
+      `Unwind requires WSOL top-up of ${lamportsToWrap} lamports. Rebuild with includeWrapForShortfall=true and writerSigner.`
+    );
+  }
 
   const unwindTx = await buildUnwindWriterUnsoldTransactionWithDerivation({
     underlyingAsset: params.underlyingAsset,
@@ -501,11 +535,11 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     remainingAccounts,
   });
 
-  if (
-    params.includeWrapForShortfall &&
-    toAddress(underlyingMint) === toAddress(NATIVE_MINT) &&
-    preflight.summary.walletFallbackRequired > 0n
-  ) {
+  if (params.includeWrapForShortfall && isWsolPath && lamportsToWrap > 0n) {
+    invariant(
+      toAddress(writerRepaymentAccount) === toAddress(writerDefaultRepaymentAta),
+      "WSOL auto-wrap requires writerRepaymentAccount to be the writer WSOL ATA."
+    );
     invariant(
       !!params.writerSigner,
       "writerSigner is required when includeWrapForShortfall=true for WSOL shortfall top-up."
@@ -513,7 +547,7 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     const wrapInstructions = await getWrapSOLInstructions({
       payer: params.writerSigner,
       owner: params.writer,
-      lamports: preflight.summary.walletFallbackRequired,
+      lamports: lamportsToWrap,
     });
     return {
       instructions: [...wrapInstructions, ...unwindTx.instructions],

package/short/preflight.ts

@@ -6,6 +6,7 @@ import { fetchPoolLoansByMaker } from "../accounts/list";
 import { deriveAssociatedTokenAddress, deriveVaultPda, deriveWriterPositionPda } from "../accounts/pdas";
 import { resolveOptionAccounts } from "../accounts/resolve-option";
 import { invariant } from "../shared/errors";
+import { NATIVE_MINT } from "../wsol/instructions";
 
 const TOKEN_ACCOUNT_AMOUNT_OFFSET = 64;
 const BPS_DENOMINATOR = 10_000n;
@@ -78,6 +79,10 @@ export interface UnwindPreflightSummary {
   /** For top-up UX: explicit shortfall fields */
   collateralVaultShortfall: bigint;
   needsWalletTopUp: boolean;
+  /** WSOL-only top-up metadata */
+  solTopUpRequired: bigint;
+  topUpRequiredForRepay: boolean;
+  nativeSolAvailable: bigint;
 }
 
 export interface UnwindPreflightResult {
@@ -111,9 +116,11 @@ export async function preflightUnwindWriterUnsold(
   const underlyingMint = params.underlyingMint ?? resolved.underlyingMint;
   const [vaultPda] = await deriveVaultPda(underlyingMint, params.programId);
   const vaultPdaAddress = toAddress(vaultPda);
+  const writerAddress = toAddress(params.writer);
+  const writerDefaultRepaymentAta = await deriveAssociatedTokenAddress(params.writer, underlyingMint);
   const writerRepaymentAccount =
     params.writerRepaymentAccount ??
-    (await deriveAssociatedTokenAddress(params.writer, underlyingMint));
+    writerDefaultRepaymentAta;
   const writerRepaymentAddress = toAddress(writerRepaymentAccount);
   const [writerPositionAddress] = await deriveWriterPositionPda(
     resolved.optionPool,
@@ -162,6 +169,9 @@ export async function preflightUnwindWriterUnsold(
         shortfall: 0n,
         collateralVaultShortfall: 0n,
         needsWalletTopUp: false,
+        solTopUpRequired: 0n,
+        topUpRequiredForRepay: false,
+        nativeSolAvailable: 0n,
       },
     };
   }
@@ -192,6 +202,9 @@ export async function preflightUnwindWriterUnsold(
         shortfall: 0n,
         collateralVaultShortfall: 0n,
         needsWalletTopUp: false,
+        solTopUpRequired: 0n,
+        topUpRequiredForRepay: false,
+        nativeSolAvailable: 0n,
       },
     };
   }
@@ -242,10 +255,15 @@ export async function preflightUnwindWriterUnsold(
     { principal: 0n, interest: 0n, fees: 0n, owed: 0n }
   );
 
-  const [collateralVaultAvailable, walletFallbackAvailable] = await Promise.all([
+  const isWsolRepaymentPath = toAddress(underlyingMint) === toAddress(NATIVE_MINT);
+  const canTopUpByWrapping =
+    isWsolRepaymentPath && writerRepaymentAddress === toAddress(writerDefaultRepaymentAta);
+  const [collateralVaultAvailable, walletFallbackAvailable, nativeBalanceResponse] = await Promise.all([
     fetchTokenAmount(params.rpc, resolved.collateralVault!),
     fetchTokenAmount(params.rpc, writerRepaymentAddress),
+    canTopUpByWrapping ? params.rpc.getBalance(writerAddress).send() : Promise.resolve({ value: 0n }),
   ]);
+  const nativeSolAvailable = nativeBalanceResponse.value;
 
   // Calculate proportional obligations for partial unwinds
   const writtenQty = toBigInt(writerPosition.writtenQty);
@@ -270,6 +288,12 @@ export async function preflightUnwindWriterUnsold(
     proportionalTotalOwed > collateralVaultAvailable ? proportionalTotalOwed - collateralVaultAvailable : 0n;
   const totalAvailable = collateralVaultAvailable + walletFallbackAvailable;
   const shortfall = proportionalTotalOwed > totalAvailable ? proportionalTotalOwed - totalAvailable : 0n;
+  const solTopUpRequired =
+    walletFallbackRequired > walletFallbackAvailable ? walletFallbackRequired - walletFallbackAvailable : 0n;
+  const topUpRequiredForRepay = solTopUpRequired > 0n;
+  const effectiveTotalAvailable = totalAvailable + (canTopUpByWrapping ? nativeSolAvailable : 0n);
+  const effectiveShortfall =
+    proportionalTotalOwed > effectiveTotalAvailable ? proportionalTotalOwed - effectiveTotalAvailable : 0n;
 
   // For top-up UX: explicit collateral vault shortfall
   const collateralVaultShortfall = returnableCollateral > collateralVaultAvailable
@@ -279,8 +303,11 @@ export async function preflightUnwindWriterUnsold(
 
   return {
     canUnwind: true,
-    canRepayFully: shortfall === 0n,
-    reason: shortfall === 0n ? undefined : "Insufficient combined collateral vault + writer fallback funds",
+    canRepayFully: effectiveShortfall === 0n,
+    reason:
+      effectiveShortfall === 0n
+        ? undefined
+        : "Insufficient combined collateral vault + wallet fallback funds (including SOL top-up capacity for WSOL)",
     writerPositionAddress: String(writerPositionAddress),
     writerRepaymentAccount: String(writerRepaymentAddress),
     collateralVaultAddress: String(resolved.collateralVault),
@@ -303,6 +330,9 @@ export async function preflightUnwindWriterUnsold(
       shortfall,
       collateralVaultShortfall,
       needsWalletTopUp,
+      solTopUpRequired,
+      topUpRequiredForRepay,
+      nativeSolAvailable,
     },
   };
 }