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

package/README.md

@@ -47,7 +47,9 @@ Additional modules:
 
 | Function | Description |
 |----------|-------------|
+| `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. |
 | `getBuyFromPoolRemainingAccounts` | Builds remaining_accounts for buy (writer positions, etc.). |
 
@@ -88,7 +90,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,24 +103,78 @@ 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)
+### Buy From Pool (market order, high-level)
 
 ```ts
 import {
-  buildBuyFromPoolTransactionWithDerivation,
-  resolveOptionAccounts,
+  buildBuyFromPoolMarketOrderTransactionWithDerivation,
+  preflightBuyFromPoolMarketOrder,
   OptionType,
 } from "@epicentral/sos-sdk";
 
-const tx = await buildBuyFromPoolTransactionWithDerivation({
+const preflight = await preflightBuyFromPoolMarketOrder({
+  underlyingAsset: "...",
+  optionType: OptionType.Call,
+  strikePrice: 100_000,
+  expirationDate: BigInt(1735689600),
+  quantity: 1_000_000,
+  rpc,
+  quotedPremiumTotal: 50_000,
+  slippageBufferBaseUnits: 500_000n,
+});
+
+if (!preflight.canBuy) {
+  throw new Error(preflight.reason ?? "Buy preflight failed");
+}
+
+const tx = await buildBuyFromPoolMarketOrderTransactionWithDerivation({
   underlyingAsset: "...",
   optionType: OptionType.Call,
   strikePrice: 100_000,
@@ -123,11 +183,30 @@ const tx = await buildBuyFromPoolTransactionWithDerivation({
   buyerPaymentAccount: buyerUsdcAta,
   priceUpdate: pythPriceFeed,
   quantity: 1_000_000,
-  premiumAmount: 50_000,
+  quotedPremiumTotal: 50_000,
+  slippageBufferBaseUnits: 500_000n,
   rpc,
 });
 ```
 
+### Buy premium semantics (market orders)
+
+- `premiumAmount` / `max_premium_amount` is a **max premium cap**, not an exact premium target.
+- Program computes premium on-chain at execution time and fails with `SlippageToleranceExceeded` if computed premium exceeds the cap.
+- High-level market builder computes cap as `quotedPremiumTotal + buffer`:
+  - Canonical: `slippageBufferBaseUnits`
+  - Convenience for SOL/WSOL: `slippageBufferLamports`
+  - Default buffer: `500_000` base units (0.0005 SOL lamports)
+
+### Buy liquidity errors (6041)
+
+- `InsufficientPoolLiquidity` can happen when:
+  - `option_pool.total_available < quantity`, or
+  - remaining writer-position accounts cannot cover full quantity in the smallest-first fill loop.
+- Recommended client flow:
+  1. Run `preflightBuyFromPoolMarketOrder` for UX gating.
+  2. Build via `buildBuyFromPoolMarketOrderTransactionWithDerivation` so pool + remaining accounts are refetched immediately before build.
+
 ### 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("HsoWoDfW4yXVaXE31tEz167cjQn79TeXYxggSrXvRvri"),
+  devnet: address("B7kctbAQDEHT8gJcqRB3Bjkv4EkxMCZecy2H6EQNLQPo"),
   mainnet: null,
 };
 

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

@@ -16,6 +16,7 @@ export * from "./shared/transactions";
 
 export * from "./long/builders";
 export * from "./long/exercise";
+export * from "./long/preflight";
 export * from "./long/quotes";
 export {
   getBuyFromPoolRemainingAccounts,
@@ -25,6 +26,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/long/builders.ts

@@ -10,14 +10,16 @@ import {
   deriveAssociatedTokenAddress,
   deriveBuyerPositionPda,
 } from "../accounts/pdas";
-import { assertPositiveAmount } from "../shared/amounts";
+import { assertNonNegativeAmount, assertPositiveAmount } from "../shared/amounts";
 import { invariant } from "../shared/errors";
 import {
   appendRemainingAccounts,
   type RemainingAccountInput,
 } from "../shared/remaining-accounts";
 import type { OptionType } from "../generated/types";
-import { getCreateAssociatedTokenIdempotentInstructionWithAddress } from "../wsol/instructions";
+import { getCreateAssociatedTokenIdempotentInstructionWithAddress, NATIVE_MINT } from "../wsol/instructions";
+import { fetchOptionPool } from "../accounts/fetchers";
+import { getBuyFromPoolRemainingAccounts } from "./remaining-accounts";
 
 export interface BuildBuyFromPoolParams {
   optionPool: AddressLike;
@@ -127,6 +129,42 @@ export interface BuildBuyFromPoolTransactionWithDerivationParams {
   remainingAccounts?: RemainingAccountInput[];
 }
 
+const DEFAULT_MARKET_ORDER_SLIPPAGE_BUFFER_BASE_UNITS = 500_000n;
+
+interface MarketOrderBufferLikeParams {
+  slippageBufferBaseUnits?: bigint | number;
+  slippageBufferLamports?: bigint | number;
+}
+
+function normalizeMarketOrderSlippageBuffer(
+  params: MarketOrderBufferLikeParams,
+  underlyingMint: AddressLike
+): bigint {
+  const hasBaseUnits = params.slippageBufferBaseUnits !== undefined;
+  const hasLamports = params.slippageBufferLamports !== undefined;
+
+  invariant(
+    !(hasBaseUnits && hasLamports),
+    "Provide only one of slippageBufferBaseUnits or slippageBufferLamports."
+  );
+
+  if (hasBaseUnits) {
+    assertNonNegativeAmount(params.slippageBufferBaseUnits!, "slippageBufferBaseUnits");
+    return BigInt(params.slippageBufferBaseUnits!);
+  }
+
+  if (hasLamports) {
+    assertNonNegativeAmount(params.slippageBufferLamports!, "slippageBufferLamports");
+    invariant(
+      String(toAddress(underlyingMint)) === String(NATIVE_MINT),
+      "slippageBufferLamports is only supported for SOL/WSOL underlyings. Use slippageBufferBaseUnits for other assets."
+    );
+    return BigInt(params.slippageBufferLamports!);
+  }
+
+  return DEFAULT_MARKET_ORDER_SLIPPAGE_BUFFER_BASE_UNITS;
+}
+
 export async function buildBuyFromPoolTransactionWithDerivation(
   params: BuildBuyFromPoolTransactionWithDerivationParams
 ): Promise<BuiltTransaction> {
@@ -178,6 +216,82 @@ export async function buildBuyFromPoolTransactionWithDerivation(
   });
 }
 
+export interface BuildBuyFromPoolMarketOrderParams
+  extends Omit<
+      BuildBuyFromPoolTransactionWithDerivationParams,
+      "premiumAmount" | "remainingAccounts"
+    >,
+    MarketOrderBufferLikeParams {
+  quotedPremiumTotal: bigint | number;
+}
+
+/**
+ * High-level market-order buy builder.
+ * Refetches option pool and remaining writer-position accounts right before
+ * build and sets max premium = quotedPremiumTotal + slippage buffer.
+ */
+export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
+  params: BuildBuyFromPoolMarketOrderParams
+): Promise<BuiltTransaction> {
+  assertPositiveAmount(params.quantity, "quantity");
+  assertPositiveAmount(params.quotedPremiumTotal, "quotedPremiumTotal");
+
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const [refetchedPool, remainingAccounts, buyerPosition, buyerOptionAccount] =
+    await Promise.all([
+      fetchOptionPool(params.rpc, resolved.optionPool),
+      getBuyFromPoolRemainingAccounts(params.rpc, resolved.optionPool, params.programId),
+      params.buyerPosition
+        ? Promise.resolve(params.buyerPosition)
+        : deriveBuyerPositionPda(
+            params.buyer,
+            resolved.optionAccount,
+            params.programId
+          ).then(([addr]) => addr),
+      params.buyerOptionAccount
+        ? Promise.resolve(params.buyerOptionAccount)
+        : deriveAssociatedTokenAddress(params.buyer, resolved.longMint),
+    ]);
+
+  invariant(
+    !!refetchedPool,
+    "Option pool must exist; ensure rpc is provided and pool is initialized."
+  );
+
+  const slippageBuffer = normalizeMarketOrderSlippageBuffer(
+    params,
+    refetchedPool.underlyingMint
+  );
+  const maxPremiumAmount = BigInt(params.quotedPremiumTotal) + slippageBuffer;
+  assertPositiveAmount(maxPremiumAmount, "maxPremiumAmount");
+
+  return buildBuyFromPoolTransaction({
+    optionPool: resolved.optionPool,
+    optionAccount: resolved.optionAccount,
+    longMint: resolved.longMint,
+    underlyingMint: refetchedPool.underlyingMint,
+    marketData: resolved.marketData,
+    priceUpdate: params.priceUpdate,
+    buyer: params.buyer,
+    buyerPaymentAccount: params.buyerPaymentAccount,
+    escrowLongAccount: refetchedPool.escrowLongAccount,
+    premiumVault: refetchedPool.premiumVault,
+    quantity: params.quantity,
+    premiumAmount: maxPremiumAmount,
+    buyerPosition,
+    buyerOptionAccount,
+    remainingAccounts,
+  });
+}
+
 export async function buildCloseLongToPoolInstruction(
   params: BuildCloseLongToPoolParams
 ): Promise<Instruction<string>> {

package/long/preflight.ts

@@ -0,0 +1,114 @@
+import type { AddressLike, KitRpc } from "../client/types";
+import type { OptionType } from "../generated/types";
+import { fetchWriterPositionsForPool } from "../accounts/list";
+import { resolveOptionAccounts } from "../accounts/resolve-option";
+import { fetchOptionPool } from "../accounts/fetchers";
+import { assertNonNegativeAmount, assertPositiveAmount } from "../shared/amounts";
+import { invariant } from "../shared/errors";
+
+function toBigInt(value: bigint | number): bigint {
+  return typeof value === "bigint" ? value : BigInt(value);
+}
+
+export interface PreflightBuyFromPoolMarketOrderParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  quantity: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+  quotedPremiumTotal?: bigint | number;
+  slippageBufferBaseUnits?: bigint | number;
+}
+
+export interface BuyFromPoolMarketOrderPremiumSummary {
+  quotedPremiumTotal: bigint;
+  slippageBufferBaseUnits: bigint;
+  maxPremiumAmount: bigint;
+}
+
+export interface PreflightBuyFromPoolMarketOrderResult {
+  canBuy: boolean;
+  reason?: string;
+  poolTotalAvailable: bigint;
+  requestedQuantity: bigint;
+  remainingAccountsCount: number;
+  remainingUnsoldAggregate: bigint;
+  premium?: BuyFromPoolMarketOrderPremiumSummary;
+}
+
+export async function preflightBuyFromPoolMarketOrder(
+  params: PreflightBuyFromPoolMarketOrderParams
+): Promise<PreflightBuyFromPoolMarketOrderResult> {
+  assertPositiveAmount(params.quantity, "quantity");
+  const requestedQuantity = toBigInt(params.quantity);
+
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const [optionPool, writerPositions] = await Promise.all([
+    fetchOptionPool(params.rpc, resolved.optionPool),
+    fetchWriterPositionsForPool(params.rpc, resolved.optionPool, params.programId),
+  ]);
+
+  invariant(
+    !!optionPool,
+    "Option pool must exist; ensure rpc is provided and pool is initialized."
+  );
+
+  const availableWriterPositions = writerPositions.filter(
+    ({ data }) => toBigInt(data.unsoldQty) > 0n
+  );
+  const remainingUnsoldAggregate = availableWriterPositions.reduce(
+    (acc, { data }) => acc + toBigInt(data.unsoldQty),
+    0n
+  );
+  const poolTotalAvailable = toBigInt(optionPool.totalAvailable);
+
+  const hasPoolLiquidity = poolTotalAvailable >= requestedQuantity;
+  const hasWriterCoverage = remainingUnsoldAggregate >= requestedQuantity;
+
+  let reason: string | undefined;
+  if (!hasPoolLiquidity) {
+    reason = "Pool total_available is less than requested quantity.";
+  } else if (!hasWriterCoverage) {
+    reason =
+      "Remaining writer-position liquidity is insufficient to fully fill requested quantity.";
+  }
+
+  const result: PreflightBuyFromPoolMarketOrderResult = {
+    canBuy: hasPoolLiquidity && hasWriterCoverage,
+    reason,
+    poolTotalAvailable,
+    requestedQuantity,
+    remainingAccountsCount: availableWriterPositions.length,
+    remainingUnsoldAggregate,
+  };
+
+  if (params.quotedPremiumTotal !== undefined) {
+    assertPositiveAmount(params.quotedPremiumTotal, "quotedPremiumTotal");
+    if (params.slippageBufferBaseUnits !== undefined) {
+      assertNonNegativeAmount(params.slippageBufferBaseUnits, "slippageBufferBaseUnits");
+    }
+    const quotedPremiumTotal = toBigInt(params.quotedPremiumTotal);
+    const slippageBufferBaseUnits =
+      params.slippageBufferBaseUnits !== undefined
+        ? toBigInt(params.slippageBufferBaseUnits)
+        : 0n;
+
+    result.premium = {
+      quotedPremiumTotal,
+      slippageBufferBaseUnits,
+      maxPremiumAmount: quotedPremiumTotal + slippageBufferBaseUnits,
+    };
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.3.0-alpha.2",
+  "version": "0.4.0-alpha.2",
   "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,
+    },
+  };
+}