@epicentral/sos-sdk 0.5.0-alpha.6 → 0.5.0-alpha.8

package/README.md

@@ -179,7 +179,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 +206,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 +214,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)

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("FhUHHULWJr1maH33Ec4zdR6dCG7pFX2i31o85KvNyCim"),
+  devnet: address("ApcccYeyDGBieh7fGospRV7v2pJ3UjmZEMKU8V7D3eBE"),
   mainnet: null,
 };
 

package/generated/programs/optionProgram.ts

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

package/package.json

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

@@ -468,6 +468,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 +481,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 +514,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 +526,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,
     },
   };
 }