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

package/README.md

@@ -90,11 +90,23 @@ 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 now repays in this order inside `unwind_writer_unsold`:
+When a writer unwinds an unsold short that had borrowed from the OMLP pool, the program repays proportionally to the unwind ratio inside `unwind_writer_unsold`:
 
+**Proportional Repayment (partial unwinds):**
+- Unwind ratio = `unwind_qty / written_qty`
+- Principal repaid = `total_loan_principal * unwind_ratio`
+- Interest repaid = `total_accrued_interest * unwind_ratio`
+- Protocol fees repaid = `total_accrued_fees * unwind_ratio`
+
+**Repayment order:**
 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`).
+3. If combined funds cannot cover proportional principal + interest + protocol fees, unwind fails with a protocol custom error (not a generic SPL `0x1`).
+
+**Collateral Return:**
+- Proportional collateral share = `(collateral_deposited * unwind_qty) / written_qty`
+- Returnable collateral = `proportional_share - amount_already_repaid_from_vault`
+- If vault lacks sufficient post-repayment balance, fails with `InsufficientCollateralVault` (6090)
 
 Use **`buildUnwindWriterUnsoldWithLoanRepayment`** so that:
 
@@ -106,7 +118,10 @@ Use **`buildUnwindWriterUnsoldWithLoanRepayment`** so that:
 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.
+- **Proportional obligations** for partial unwinds (principal, interest, fees, total owed).
+- **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.
 
 If there are no active pool loans for that vault, the API still works and passes empty `remaining_accounts`.
@@ -198,14 +213,18 @@ const tx = await buildBuyFromPoolMarketOrderTransactionWithDerivation({
   - Convenience for SOL/WSOL: `slippageBufferLamports`
   - Default buffer: `500_000` base units (0.0005 SOL lamports)
 
-### Buy liquidity errors (6041)
+### Buy liquidity errors (6041 split into 6042/6043)
+
+The program uses distinct error codes for liquidity failures:
+
+- `InsufficientPoolAggregateLiquidity` (6042) – `option_pool.total_available < quantity`
+- `InsufficientWriterPositionLiquidity` (6043) – remaining writer-position accounts cannot cover full quantity in the smallest-first fill loop
+
+**Ghost Liquidity:** When `total_available` appears sufficient but active writer positions cannot cover the request. This happens when positions are settled/liquidated but still counted in the aggregate. The SDK now filters inactive positions, and the program skips them in the fill loop.
 
-- `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.
+**Recommended client flow:**
+  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.
 
 ### Unwind with loan repayment
 

package/generated/errors/optionProgram.ts

@@ -98,98 +98,104 @@ export const OPTION_PROGRAM_ERROR__PRICE_IMPACT_TOO_HIGH = 0x1797; // 6039
 export const OPTION_PROGRAM_ERROR__SLIPPAGE_TOLERANCE_EXCEEDED = 0x1798; // 6040
 /** InsufficientPoolLiquidity: Insufficient pool liquidity available */
 export const OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_LIQUIDITY = 0x1799; // 6041
+/** InsufficientPoolAggregateLiquidity: Insufficient aggregate pool liquidity for requested quantity */
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_AGGREGATE_LIQUIDITY = 0x179a; // 6042
+/** InsufficientWriterPositionLiquidity: Insufficient active writer liquidity to fill requested quantity */
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_WRITER_POSITION_LIQUIDITY = 0x179b; // 6043
 /** InsufficientUserBalance: Insufficient user balance for withdrawal */
-export const OPTION_PROGRAM_ERROR__INSUFFICIENT_USER_BALANCE = 0x179a; // 6042
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_USER_BALANCE = 0x179c; // 6044
 /** UnhealthyPosition: Health ratio below liquidation threshold */
-export const OPTION_PROGRAM_ERROR__UNHEALTHY_POSITION = 0x179b; // 6043
+export const OPTION_PROGRAM_ERROR__UNHEALTHY_POSITION = 0x179d; // 6045
 /** UnauthorizedOmlp: Unauthorized to perform this OMLP action */
-export const OPTION_PROGRAM_ERROR__UNAUTHORIZED_OMLP = 0x179c; // 6044
+export const OPTION_PROGRAM_ERROR__UNAUTHORIZED_OMLP = 0x179e; // 6046
 /** InvalidTenor: Invalid loan tenor */
-export const OPTION_PROGRAM_ERROR__INVALID_TENOR = 0x179d; // 6045
+export const OPTION_PROGRAM_ERROR__INVALID_TENOR = 0x179f; // 6047
 /** InvalidRate: Invalid interest rate */
-export const OPTION_PROGRAM_ERROR__INVALID_RATE = 0x179e; // 6046
+export const OPTION_PROGRAM_ERROR__INVALID_RATE = 0x17a0; // 6048
 /** NotForeclosable: Loan is not eligible for foreclosure */
-export const OPTION_PROGRAM_ERROR__NOT_FORECLOSABLE = 0x179f; // 6047
+export const OPTION_PROGRAM_ERROR__NOT_FORECLOSABLE = 0x17a1; // 6049
 /** InsufficientVaultLiquidity: Vault has insufficient liquidity */
-export const OPTION_PROGRAM_ERROR__INSUFFICIENT_VAULT_LIQUIDITY = 0x17a0; // 6048
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_VAULT_LIQUIDITY = 0x17a2; // 6050
 /** InsufficientLoanCollateral: Collateral insufficient for loan */
-export const OPTION_PROGRAM_ERROR__INSUFFICIENT_LOAN_COLLATERAL = 0x17a1; // 6049
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_LOAN_COLLATERAL = 0x17a3; // 6051
 /** OracleTooStale: Oracle price is stale - cannot validate */
-export const OPTION_PROGRAM_ERROR__ORACLE_TOO_STALE = 0x17a2; // 6050
+export const OPTION_PROGRAM_ERROR__ORACLE_TOO_STALE = 0x17a4; // 6052
 /** ValidationRequired: Must call option_validate before borrow/settlement */
-export const OPTION_PROGRAM_ERROR__VALIDATION_REQUIRED = 0x17a3; // 6051
+export const OPTION_PROGRAM_ERROR__VALIDATION_REQUIRED = 0x17a5; // 6053
 /** HealthCalculationFailed: Health ratio calculation failed */
-export const OPTION_PROGRAM_ERROR__HEALTH_CALCULATION_FAILED = 0x17a4; // 6052
+export const OPTION_PROGRAM_ERROR__HEALTH_CALCULATION_FAILED = 0x17a6; // 6054
 /** ContractAlreadySettled: Contract already settled */
-export const OPTION_PROGRAM_ERROR__CONTRACT_ALREADY_SETTLED = 0x17a5; // 6053
+export const OPTION_PROGRAM_ERROR__CONTRACT_ALREADY_SETTLED = 0x17a7; // 6055
 /** NoYieldAvailable: No yield available to claim */
-export const OPTION_PROGRAM_ERROR__NO_YIELD_AVAILABLE = 0x17a6; // 6054
+export const OPTION_PROGRAM_ERROR__NO_YIELD_AVAILABLE = 0x17a8; // 6056
 /** UnauthorizedAccess: Unauthorized access - you don't own this resource */
-export const OPTION_PROGRAM_ERROR__UNAUTHORIZED_ACCESS = 0x17a7; // 6055
+export const OPTION_PROGRAM_ERROR__UNAUTHORIZED_ACCESS = 0x17a9; // 6057
 /** InsufficientQuantity: Insufficient quantity available in ask position */
-export const OPTION_PROGRAM_ERROR__INSUFFICIENT_QUANTITY = 0x17a8; // 6056
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_QUANTITY = 0x17aa; // 6058
 /** NothingToClaim: Nothing to claim - no unclaimed premium */
-export const OPTION_PROGRAM_ERROR__NOTHING_TO_CLAIM = 0x17a9; // 6057
+export const OPTION_PROGRAM_ERROR__NOTHING_TO_CLAIM = 0x17ab; // 6059
 /** PoolNotActive: Pool is not active */
-export const OPTION_PROGRAM_ERROR__POOL_NOT_ACTIVE = 0x17aa; // 6058
+export const OPTION_PROGRAM_ERROR__POOL_NOT_ACTIVE = 0x17ac; // 6060
 /** PoolAlreadyExists: Pool already exists for this option */
-export const OPTION_PROGRAM_ERROR__POOL_ALREADY_EXISTS = 0x17ab; // 6059
+export const OPTION_PROGRAM_ERROR__POOL_ALREADY_EXISTS = 0x17ad; // 6061
 /** PoolNotExercised: Pool has not been exercised yet */
-export const OPTION_PROGRAM_ERROR__POOL_NOT_EXERCISED = 0x17ac; // 6060
+export const OPTION_PROGRAM_ERROR__POOL_NOT_EXERCISED = 0x17ae; // 6062
 /** AlreadySettled: Maker's collateral share has already been settled */
-export const OPTION_PROGRAM_ERROR__ALREADY_SETTLED = 0x17ad; // 6061
+export const OPTION_PROGRAM_ERROR__ALREADY_SETTLED = 0x17af; // 6063
 /** InsufficientPoolCollateral: Insufficient collateral in pool for exercise */
-export const OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_COLLATERAL = 0x17ae; // 6062
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_COLLATERAL = 0x17b0; // 6064
 /** CollateralPoolNotFound: Collateral pool does not exist */
-export const OPTION_PROGRAM_ERROR__COLLATERAL_POOL_NOT_FOUND = 0x17af; // 6063
+export const OPTION_PROGRAM_ERROR__COLLATERAL_POOL_NOT_FOUND = 0x17b1; // 6065
 /** NoCollateralToWithdraw: No collateral to withdraw */
-export const OPTION_PROGRAM_ERROR__NO_COLLATERAL_TO_WITHDRAW = 0x17b0; // 6064
+export const OPTION_PROGRAM_ERROR__NO_COLLATERAL_TO_WITHDRAW = 0x17b2; // 6066
 /** OptionNotExpired: Option has not expired yet - cannot settle */
-export const OPTION_PROGRAM_ERROR__OPTION_NOT_EXPIRED = 0x17b1; // 6065
+export const OPTION_PROGRAM_ERROR__OPTION_NOT_EXPIRED = 0x17b3; // 6067
 /** SupplyLimitExceeded: Deposit would exceed vault supply limit */
-export const OPTION_PROGRAM_ERROR__SUPPLY_LIMIT_EXCEEDED = 0x17b2; // 6066
+export const OPTION_PROGRAM_ERROR__SUPPLY_LIMIT_EXCEEDED = 0x17b4; // 6068
 /** InvalidFeeWallet: Invalid fee wallet - must match protocol constant */
-export const OPTION_PROGRAM_ERROR__INVALID_FEE_WALLET = 0x17b3; // 6067
+export const OPTION_PROGRAM_ERROR__INVALID_FEE_WALLET = 0x17b5; // 6069
 /** InvalidProtocolFee: Invalid protocol fee rate */
-export const OPTION_PROGRAM_ERROR__INVALID_PROTOCOL_FEE = 0x17b4; // 6068
+export const OPTION_PROGRAM_ERROR__INVALID_PROTOCOL_FEE = 0x17b6; // 6070
 /** UnderlyingAssetMismatch: Underlying asset mismatch - market data or mint does not match option */
-export const OPTION_PROGRAM_ERROR__UNDERLYING_ASSET_MISMATCH = 0x17b5; // 6069
+export const OPTION_PROGRAM_ERROR__UNDERLYING_ASSET_MISMATCH = 0x17b7; // 6071
 /** InvalidMint: Invalid token mint - does not match expected underlying asset */
-export const OPTION_PROGRAM_ERROR__INVALID_MINT = 0x17b6; // 6070
+export const OPTION_PROGRAM_ERROR__INVALID_MINT = 0x17b8; // 6072
 /** BatchSizeExceeded: Batch size exceeds maximum allowed (10 positions) */
-export const OPTION_PROGRAM_ERROR__BATCH_SIZE_EXCEEDED = 0x17b7; // 6071
+export const OPTION_PROGRAM_ERROR__BATCH_SIZE_EXCEEDED = 0x17b9; // 6073
 /** NoPositionsProvided: No positions provided in batch */
-export const OPTION_PROGRAM_ERROR__NO_POSITIONS_PROVIDED = 0x17b8; // 6072
+export const OPTION_PROGRAM_ERROR__NO_POSITIONS_PROVIDED = 0x17ba; // 6074
 /** PositionOptionMismatch: Position account does not belong to this option */
-export const OPTION_PROGRAM_ERROR__POSITION_OPTION_MISMATCH = 0x17b9; // 6073
+export const OPTION_PROGRAM_ERROR__POSITION_OPTION_MISMATCH = 0x17bb; // 6075
 /** OptionPoolMismatch: Option account does not match the option pool's option account */
-export const OPTION_PROGRAM_ERROR__OPTION_POOL_MISMATCH = 0x17ba; // 6074
+export const OPTION_PROGRAM_ERROR__OPTION_POOL_MISMATCH = 0x17bc; // 6076
 /** InvalidSeed: Invalid seed - must be exactly 32 bytes */
-export const OPTION_PROGRAM_ERROR__INVALID_SEED = 0x17bb; // 6075
+export const OPTION_PROGRAM_ERROR__INVALID_SEED = 0x17bd; // 6077
 /** InvalidAuthority: Invalid authority - does not match escrow authority */
-export const OPTION_PROGRAM_ERROR__INVALID_AUTHORITY = 0x17bc; // 6076
+export const OPTION_PROGRAM_ERROR__INVALID_AUTHORITY = 0x17be; // 6078
 /** EscrowAccountRequired: Escrow accounts required when borrowed_amount > 0 */
-export const OPTION_PROGRAM_ERROR__ESCROW_ACCOUNT_REQUIRED = 0x17bd; // 6077
+export const OPTION_PROGRAM_ERROR__ESCROW_ACCOUNT_REQUIRED = 0x17bf; // 6079
 /** InvalidEscrowMaker: Escrow state maker does not match instruction maker */
-export const OPTION_PROGRAM_ERROR__INVALID_ESCROW_MAKER = 0x17be; // 6078
+export const OPTION_PROGRAM_ERROR__INVALID_ESCROW_MAKER = 0x17c0; // 6080
 /** EscrowMintMismatch: Escrow collateral mint does not match collateral pool mint */
-export const OPTION_PROGRAM_ERROR__ESCROW_MINT_MISMATCH = 0x17bf; // 6079
+export const OPTION_PROGRAM_ERROR__ESCROW_MINT_MISMATCH = 0x17c1; // 6081
 /** InsufficientEscrowBalance: Insufficient balance in escrow token account */
-export const OPTION_PROGRAM_ERROR__INSUFFICIENT_ESCROW_BALANCE = 0x17c0; // 6080
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_ESCROW_BALANCE = 0x17c2; // 6082
 /** InvalidEscrowOwner: Escrow token account owner mismatch */
-export const OPTION_PROGRAM_ERROR__INVALID_ESCROW_OWNER = 0x17c1; // 6081
+export const OPTION_PROGRAM_ERROR__INVALID_ESCROW_OWNER = 0x17c3; // 6083
 /** InvalidEscrowMint: Escrow token account mint mismatch */
-export const OPTION_PROGRAM_ERROR__INVALID_ESCROW_MINT = 0x17c2; // 6082
+export const OPTION_PROGRAM_ERROR__INVALID_ESCROW_MINT = 0x17c4; // 6084
 /** AccountFrozen: Token account is frozen and cannot be burned */
-export const OPTION_PROGRAM_ERROR__ACCOUNT_FROZEN = 0x17c3; // 6083
+export const OPTION_PROGRAM_ERROR__ACCOUNT_FROZEN = 0x17c5; // 6085
 /** InvalidAccount: Invalid account - does not match expected account */
-export const OPTION_PROGRAM_ERROR__INVALID_ACCOUNT = 0x17c4; // 6084
+export const OPTION_PROGRAM_ERROR__INVALID_ACCOUNT = 0x17c6; // 6086
 /** UnwindRepayAccountsMissing: Unwind repayment accounts are required when active pool loans exist */
-export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_ACCOUNTS_MISSING = 0x17c5; // 6085
+export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_ACCOUNTS_MISSING = 0x17c7; // 6087
 /** UnwindRepayWalletSourceMissing: Writer repayment account is required for unwind shortfall fallback */
-export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_WALLET_SOURCE_MISSING = 0x17c6; // 6086
+export const OPTION_PROGRAM_ERROR__UNWIND_REPAY_WALLET_SOURCE_MISSING = 0x17c8; // 6088
 /** 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 const OPTION_PROGRAM_ERROR__UNWIND_REPAY_INSUFFICIENT_TOTAL_FUNDS = 0x17c9; // 6089
+/** InsufficientCollateralVault: Collateral vault has insufficient funds for unwind collateral return */
+export const OPTION_PROGRAM_ERROR__INSUFFICIENT_COLLATERAL_VAULT = 0x17ca; // 6090
 
 export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__ACCOUNT_FROZEN
@@ -208,13 +214,16 @@ export type OptionProgramError =
   | typeof OPTION_PROGRAM_ERROR__HEALTH_CALCULATION_FAILED
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_BALANCE
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_COLLATERAL
+  | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_COLLATERAL_VAULT
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_ESCROW_BALANCE
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_LOAN_COLLATERAL
+  | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_AGGREGATE_LIQUIDITY
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_COLLATERAL
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_LIQUIDITY
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_QUANTITY
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_USER_BALANCE
   | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_VAULT_LIQUIDITY
+  | typeof OPTION_PROGRAM_ERROR__INSUFFICIENT_WRITER_POSITION_LIQUIDITY
   | typeof OPTION_PROGRAM_ERROR__INVALID_ACCOUNT
   | typeof OPTION_PROGRAM_ERROR__INVALID_AUTHORITY
   | typeof OPTION_PROGRAM_ERROR__INVALID_BUYER_AUTHORITY
@@ -300,13 +309,16 @@ if (process.env.NODE_ENV !== "production") {
     [OPTION_PROGRAM_ERROR__HEALTH_CALCULATION_FAILED]: `Health ratio calculation failed`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_BALANCE]: `Insufficient balance for premium payment`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_COLLATERAL]: `Insufficient collateral provided`,
+    [OPTION_PROGRAM_ERROR__INSUFFICIENT_COLLATERAL_VAULT]: `Collateral vault has insufficient funds for unwind collateral return`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_ESCROW_BALANCE]: `Insufficient balance in escrow token account`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_LOAN_COLLATERAL]: `Collateral insufficient for loan`,
+    [OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_AGGREGATE_LIQUIDITY]: `Insufficient aggregate pool liquidity for requested quantity`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_COLLATERAL]: `Insufficient collateral in pool for exercise`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_POOL_LIQUIDITY]: `Insufficient pool liquidity available`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_QUANTITY]: `Insufficient quantity available in ask position`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_USER_BALANCE]: `Insufficient user balance for withdrawal`,
     [OPTION_PROGRAM_ERROR__INSUFFICIENT_VAULT_LIQUIDITY]: `Vault has insufficient liquidity`,
+    [OPTION_PROGRAM_ERROR__INSUFFICIENT_WRITER_POSITION_LIQUIDITY]: `Insufficient active writer liquidity to fill requested quantity`,
     [OPTION_PROGRAM_ERROR__INVALID_ACCOUNT]: `Invalid account - does not match expected account`,
     [OPTION_PROGRAM_ERROR__INVALID_AUTHORITY]: `Invalid authority - does not match escrow authority`,
     [OPTION_PROGRAM_ERROR__INVALID_BUYER_AUTHORITY]: `Invalid buyer authority`,

package/generated/instructions/liquidateWriterPosition.ts

@@ -55,6 +55,8 @@ export type LiquidateWriterPositionInstruction<
   TAccountOptionAccount extends string | AccountMeta<string> = string,
   TAccountCollateralPool extends string | AccountMeta<string> = string,
   TAccountWriterPosition extends string | AccountMeta<string> = string,
+  TAccountLongMint extends string | AccountMeta<string> = string,
+  TAccountEscrowLongAccount extends string | AccountMeta<string> = string,
   TAccountOmlpVault extends string | AccountMeta<string> = string,
   TAccountUnderlyingMint extends string | AccountMeta<string> = string,
   TAccountMarketData extends string | AccountMeta<string> = string,
@@ -84,6 +86,12 @@ export type LiquidateWriterPositionInstruction<
       TAccountWriterPosition extends string
         ? WritableAccount<TAccountWriterPosition>
         : TAccountWriterPosition,
+      TAccountLongMint extends string
+        ? WritableAccount<TAccountLongMint>
+        : TAccountLongMint,
+      TAccountEscrowLongAccount extends string
+        ? WritableAccount<TAccountEscrowLongAccount>
+        : TAccountEscrowLongAccount,
       TAccountOmlpVault extends string
         ? WritableAccount<TAccountOmlpVault>
         : TAccountOmlpVault,
@@ -156,6 +164,8 @@ export type LiquidateWriterPositionAsyncInput<
   TAccountOptionAccount extends string = string,
   TAccountCollateralPool extends string = string,
   TAccountWriterPosition extends string = string,
+  TAccountLongMint extends string = string,
+  TAccountEscrowLongAccount extends string = string,
   TAccountOmlpVault extends string = string,
   TAccountUnderlyingMint extends string = string,
   TAccountMarketData extends string = string,
@@ -175,6 +185,10 @@ export type LiquidateWriterPositionAsyncInput<
   collateralPool?: Address<TAccountCollateralPool>;
   /** Writer's position to liquidate */
   writerPosition: Address<TAccountWriterPosition>;
+  /** LONG token mint (for burning unsold tokens) */
+  longMint: Address<TAccountLongMint>;
+  /** Pool's LONG escrow account (holds unsold LONG tokens to burn) */
+  escrowLongAccount: Address<TAccountEscrowLongAccount>;
   /** OMLP Vault (for repayment tracking) */
   omlpVault: Address<TAccountOmlpVault>;
   /** Underlying token mint (for decimal handling) */
@@ -200,6 +214,8 @@ export async function getLiquidateWriterPositionInstructionAsync<
   TAccountOptionAccount extends string,
   TAccountCollateralPool extends string,
   TAccountWriterPosition extends string,
+  TAccountLongMint extends string,
+  TAccountEscrowLongAccount extends string,
   TAccountOmlpVault extends string,
   TAccountUnderlyingMint extends string,
   TAccountMarketData extends string,
@@ -217,6 +233,8 @@ export async function getLiquidateWriterPositionInstructionAsync<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountWriterPosition,
+    TAccountLongMint,
+    TAccountEscrowLongAccount,
     TAccountOmlpVault,
     TAccountUnderlyingMint,
     TAccountMarketData,
@@ -236,6 +254,8 @@ export async function getLiquidateWriterPositionInstructionAsync<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountWriterPosition,
+    TAccountLongMint,
+    TAccountEscrowLongAccount,
     TAccountOmlpVault,
     TAccountUnderlyingMint,
     TAccountMarketData,
@@ -258,6 +278,11 @@ export async function getLiquidateWriterPositionInstructionAsync<
     optionAccount: { value: input.optionAccount ?? null, isWritable: true },
     collateralPool: { value: input.collateralPool ?? null, isWritable: true },
     writerPosition: { value: input.writerPosition ?? null, isWritable: true },
+    longMint: { value: input.longMint ?? null, isWritable: true },
+    escrowLongAccount: {
+      value: input.escrowLongAccount ?? null,
+      isWritable: true,
+    },
     omlpVault: { value: input.omlpVault ?? null, isWritable: true },
     underlyingMint: { value: input.underlyingMint ?? null, isWritable: false },
     marketData: { value: input.marketData ?? null, isWritable: false },
@@ -308,6 +333,8 @@ export async function getLiquidateWriterPositionInstructionAsync<
       getAccountMeta(accounts.optionAccount),
       getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.writerPosition),
+      getAccountMeta(accounts.longMint),
+      getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.omlpVault),
       getAccountMeta(accounts.underlyingMint),
       getAccountMeta(accounts.marketData),
@@ -327,6 +354,8 @@ export async function getLiquidateWriterPositionInstructionAsync<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountWriterPosition,
+    TAccountLongMint,
+    TAccountEscrowLongAccount,
     TAccountOmlpVault,
     TAccountUnderlyingMint,
     TAccountMarketData,
@@ -345,6 +374,8 @@ export type LiquidateWriterPositionInput<
   TAccountOptionAccount extends string = string,
   TAccountCollateralPool extends string = string,
   TAccountWriterPosition extends string = string,
+  TAccountLongMint extends string = string,
+  TAccountEscrowLongAccount extends string = string,
   TAccountOmlpVault extends string = string,
   TAccountUnderlyingMint extends string = string,
   TAccountMarketData extends string = string,
@@ -364,6 +395,10 @@ export type LiquidateWriterPositionInput<
   collateralPool: Address<TAccountCollateralPool>;
   /** Writer's position to liquidate */
   writerPosition: Address<TAccountWriterPosition>;
+  /** LONG token mint (for burning unsold tokens) */
+  longMint: Address<TAccountLongMint>;
+  /** Pool's LONG escrow account (holds unsold LONG tokens to burn) */
+  escrowLongAccount: Address<TAccountEscrowLongAccount>;
   /** OMLP Vault (for repayment tracking) */
   omlpVault: Address<TAccountOmlpVault>;
   /** Underlying token mint (for decimal handling) */
@@ -389,6 +424,8 @@ export function getLiquidateWriterPositionInstruction<
   TAccountOptionAccount extends string,
   TAccountCollateralPool extends string,
   TAccountWriterPosition extends string,
+  TAccountLongMint extends string,
+  TAccountEscrowLongAccount extends string,
   TAccountOmlpVault extends string,
   TAccountUnderlyingMint extends string,
   TAccountMarketData extends string,
@@ -406,6 +443,8 @@ export function getLiquidateWriterPositionInstruction<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountWriterPosition,
+    TAccountLongMint,
+    TAccountEscrowLongAccount,
     TAccountOmlpVault,
     TAccountUnderlyingMint,
     TAccountMarketData,
@@ -424,6 +463,8 @@ export function getLiquidateWriterPositionInstruction<
   TAccountOptionAccount,
   TAccountCollateralPool,
   TAccountWriterPosition,
+  TAccountLongMint,
+  TAccountEscrowLongAccount,
   TAccountOmlpVault,
   TAccountUnderlyingMint,
   TAccountMarketData,
@@ -445,6 +486,11 @@ export function getLiquidateWriterPositionInstruction<
     optionAccount: { value: input.optionAccount ?? null, isWritable: true },
     collateralPool: { value: input.collateralPool ?? null, isWritable: true },
     writerPosition: { value: input.writerPosition ?? null, isWritable: true },
+    longMint: { value: input.longMint ?? null, isWritable: true },
+    escrowLongAccount: {
+      value: input.escrowLongAccount ?? null,
+      isWritable: true,
+    },
     omlpVault: { value: input.omlpVault ?? null, isWritable: true },
     underlyingMint: { value: input.underlyingMint ?? null, isWritable: false },
     marketData: { value: input.marketData ?? null, isWritable: false },
@@ -481,6 +527,8 @@ export function getLiquidateWriterPositionInstruction<
       getAccountMeta(accounts.optionAccount),
       getAccountMeta(accounts.collateralPool),
       getAccountMeta(accounts.writerPosition),
+      getAccountMeta(accounts.longMint),
+      getAccountMeta(accounts.escrowLongAccount),
       getAccountMeta(accounts.omlpVault),
       getAccountMeta(accounts.underlyingMint),
       getAccountMeta(accounts.marketData),
@@ -500,6 +548,8 @@ export function getLiquidateWriterPositionInstruction<
     TAccountOptionAccount,
     TAccountCollateralPool,
     TAccountWriterPosition,
+    TAccountLongMint,
+    TAccountEscrowLongAccount,
     TAccountOmlpVault,
     TAccountUnderlyingMint,
     TAccountMarketData,
@@ -527,24 +577,28 @@ export type ParsedLiquidateWriterPositionInstruction<
     collateralPool: TAccountMetas[2];
     /** Writer's position to liquidate */
     writerPosition: TAccountMetas[3];
+    /** LONG token mint (for burning unsold tokens) */
+    longMint: TAccountMetas[4];
+    /** Pool's LONG escrow account (holds unsold LONG tokens to burn) */
+    escrowLongAccount: TAccountMetas[5];
     /** OMLP Vault (for repayment tracking) */
-    omlpVault: TAccountMetas[4];
+    omlpVault: TAccountMetas[6];
     /** Underlying token mint (for decimal handling) */
-    underlyingMint: TAccountMetas[5];
+    underlyingMint: TAccountMetas[7];
     /** Market data account (provides pyth_feed_id for price check) */
-    marketData: TAccountMetas[6];
+    marketData: TAccountMetas[8];
     /** Pyth price update account for current underlying price */
-    priceUpdate: TAccountMetas[7];
+    priceUpdate: TAccountMetas[9];
     /** Collateral vault (source of repayments) */
-    collateralVault: TAccountMetas[8];
+    collateralVault: TAccountMetas[10];
     /** OMLP vault token account (receives loan repayments) */
-    omlpVaultTokenAccount: TAccountMetas[9];
+    omlpVaultTokenAccount: TAccountMetas[11];
     /** Protocol fee wallet (receives liquidation fees) */
-    feeWallet: TAccountMetas[10];
+    feeWallet: TAccountMetas[12];
     /** Liquidator/keeper (permissionless - anyone can call) */
-    liquidator: TAccountMetas[11];
-    tokenProgram: TAccountMetas[12];
-    systemProgram: TAccountMetas[13];
+    liquidator: TAccountMetas[13];
+    tokenProgram: TAccountMetas[14];
+    systemProgram: TAccountMetas[15];
   };
   data: LiquidateWriterPositionInstructionData;
 };
@@ -557,7 +611,7 @@ export function parseLiquidateWriterPositionInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedLiquidateWriterPositionInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 14) {
+  if (instruction.accounts.length < 16) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -574,6 +628,8 @@ export function parseLiquidateWriterPositionInstruction<
       optionAccount: getNextAccount(),
       collateralPool: getNextAccount(),
       writerPosition: getNextAccount(),
+      longMint: getNextAccount(),
+      escrowLongAccount: getNextAccount(),
       omlpVault: getNextAccount(),
       underlyingMint: getNextAccount(),
       marketData: getNextAccount(),

package/generated/programs/optionProgram.ts

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

package/long/builders.ts

@@ -20,6 +20,7 @@ import type { OptionType } from "../generated/types";
 import { getCreateAssociatedTokenIdempotentInstructionWithAddress, NATIVE_MINT } from "../wsol/instructions";
 import { fetchOptionPool } from "../accounts/fetchers";
 import { getBuyFromPoolRemainingAccounts } from "./remaining-accounts";
+import { fetchWriterPositionsForPool } from "../accounts/list";
 
 export interface BuildBuyFromPoolParams {
   optionPool: AddressLike;
@@ -266,6 +267,24 @@ export async function buildBuyFromPoolMarketOrderTransactionWithDerivation(
     "Option pool must exist; ensure rpc is provided and pool is initialized."
   );
 
+  // Build-time coverage assertion: verify active writer liquidity >= requested quantity
+  // This catches data staleness between preflight and build
+  const quantity = BigInt(params.quantity);
+  const writerPositions = await fetchWriterPositionsForPool(
+    params.rpc,
+    resolved.optionPool,
+    params.programId
+  );
+  const activeUnsoldTotal = writerPositions
+    .filter((p) => !p.data.isSettled && !p.data.isLiquidated && p.data.unsoldQty > 0n)
+    .reduce((sum, p) => sum + p.data.unsoldQty, 0n);
+
+  invariant(
+    activeUnsoldTotal >= quantity,
+    `Insufficient active writer liquidity: available=${activeUnsoldTotal}, requested=${quantity}. ` +
+    `This may indicate data staleness - please refresh and retry.`
+  );
+
   const slippageBuffer = normalizeMarketOrderSlippageBuffer(
     params,
     refetchedPool.underlyingMint

package/long/preflight.ts

@@ -63,9 +63,13 @@ export async function preflightBuyFromPoolMarketOrder(
     "Option pool must exist; ensure rpc is provided and pool is initialized."
   );
 
-  const availableWriterPositions = writerPositions.filter(
-    ({ data }) => toBigInt(data.unsoldQty) > 0n
+  // Filter out inactive positions (settled, liquidated, or zero unsold)
+  const activeWriterPositions = writerPositions.filter(
+    ({ data }) => !data.isSettled && !data.isLiquidated && toBigInt(data.unsoldQty) > 0n
   );
+
+  // Use active positions for coverage calculation
+  const availableWriterPositions = activeWriterPositions;
   const remainingUnsoldAggregate = availableWriterPositions.reduce(
     (acc, { data }) => acc + toBigInt(data.unsoldQty),
     0n

package/long/remaining-accounts.ts

@@ -19,7 +19,20 @@ export async function getBuyFromPoolRemainingAccounts(
     optionPool,
     programId ?? PROGRAM_ID
   );
-  const sorted = [...positions].sort((a, b) => {
+
+  // Filter out inactive positions (settled, liquidated, or zero unsold)
+  const activePositions = positions.filter((p) => {
+    const isActive = !p.data.isSettled && !p.data.isLiquidated && p.data.unsoldQty > 0;
+    if (!isActive) {
+      console.log(
+        `Filtering out inactive writer position: ${p.address}, ` +
+        `isSettled=${p.data.isSettled}, isLiquidated=${p.data.isLiquidated}, unsoldQty=${p.data.unsoldQty}`
+      );
+    }
+    return isActive;
+  });
+
+  const sorted = [...activePositions].sort((a, b) => {
     const aQty = a.data.unsoldQty;
     const bQty = b.data.unsoldQty;
     return aQty < bQty ? -1 : aQty > bQty ? 1 : 0;

package/package.json

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

@@ -63,10 +63,21 @@ export interface UnwindPreflightSummary {
   totalInterest: bigint;
   totalProtocolFees: bigint;
   totalOwed: bigint;
+  /** Proportional obligations for partial unwind (based on unwind ratio) */
+  proportionalPrincipal: bigint;
+  proportionalInterest: bigint;
+  proportionalProtocolFees: bigint;
+  proportionalTotalOwed: bigint;
+  /** Collateral return calculation */
+  proportionalCollateralShare: bigint;
+  returnableCollateral: bigint;
   collateralVaultAvailable: bigint;
   walletFallbackAvailable: bigint;
   walletFallbackRequired: bigint;
   shortfall: bigint;
+  /** For top-up UX: explicit shortfall fields */
+  collateralVaultShortfall: bigint;
+  needsWalletTopUp: boolean;
 }
 
 export interface UnwindPreflightResult {
@@ -139,10 +150,18 @@ export async function preflightUnwindWriterUnsold(
         totalInterest: 0n,
         totalProtocolFees: 0n,
         totalOwed: 0n,
+        proportionalPrincipal: 0n,
+        proportionalInterest: 0n,
+        proportionalProtocolFees: 0n,
+        proportionalTotalOwed: 0n,
+        proportionalCollateralShare: 0n,
+        returnableCollateral: 0n,
         collateralVaultAvailable: 0n,
         walletFallbackAvailable: 0n,
         walletFallbackRequired: 0n,
         shortfall: 0n,
+        collateralVaultShortfall: 0n,
+        needsWalletTopUp: false,
       },
     };
   }
@@ -161,10 +180,18 @@ export async function preflightUnwindWriterUnsold(
         totalInterest: 0n,
         totalProtocolFees: 0n,
         totalOwed: 0n,
+        proportionalPrincipal: 0n,
+        proportionalInterest: 0n,
+        proportionalProtocolFees: 0n,
+        proportionalTotalOwed: 0n,
+        proportionalCollateralShare: 0n,
+        returnableCollateral: 0n,
         collateralVaultAvailable: 0n,
         walletFallbackAvailable: 0n,
         walletFallbackRequired: 0n,
         shortfall: 0n,
+        collateralVaultShortfall: 0n,
+        needsWalletTopUp: false,
       },
     };
   }
@@ -220,10 +247,35 @@ export async function preflightUnwindWriterUnsold(
     fetchTokenAmount(params.rpc, writerRepaymentAddress),
   ]);
 
+  // Calculate proportional obligations for partial unwinds
+  const writtenQty = toBigInt(writerPosition.writtenQty);
+  const unwindRatio = writtenQty > 0n ? (unwindQty * 1_000_000n) / writtenQty : 0n; // Basis points precision
+  const unwindRatioDecimal = Number(unwindRatio) / 1_000_000; // Convert to decimal
+
+  // Proportional obligations (for partial unwind logic)
+  const proportionalPrincipal = writtenQty > 0n ? (totals.principal * unwindQty) / writtenQty : 0n;
+  const proportionalInterest = writtenQty > 0n ? (totals.interest * unwindQty) / writtenQty : 0n;
+  const proportionalProtocolFees = writtenQty > 0n ? (totals.fees * unwindQty) / writtenQty : 0n;
+  const proportionalTotalOwed = proportionalPrincipal + proportionalInterest + proportionalProtocolFees;
+
+  // Collateral return calculation (proportional share minus proportional obligations)
+  const collateralDeposited = toBigInt(writerPosition.collateralDeposited);
+  const proportionalCollateralShare = writtenQty > 0n ? (collateralDeposited * unwindQty) / writtenQty : 0n;
+  const returnableCollateral = proportionalCollateralShare > proportionalTotalOwed
+    ? proportionalCollateralShare - proportionalTotalOwed
+    : 0n;
+
+  // Calculate shortfall against proportional obligations
   const walletFallbackRequired =
-    totals.owed > collateralVaultAvailable ? totals.owed - collateralVaultAvailable : 0n;
+    proportionalTotalOwed > collateralVaultAvailable ? proportionalTotalOwed - collateralVaultAvailable : 0n;
   const totalAvailable = collateralVaultAvailable + walletFallbackAvailable;
-  const shortfall = totals.owed > totalAvailable ? totals.owed - totalAvailable : 0n;
+  const shortfall = proportionalTotalOwed > totalAvailable ? proportionalTotalOwed - totalAvailable : 0n;
+
+  // For top-up UX: explicit collateral vault shortfall
+  const collateralVaultShortfall = returnableCollateral > collateralVaultAvailable
+    ? returnableCollateral - collateralVaultAvailable
+    : 0n;
+  const needsWalletTopUp = collateralVaultShortfall > 0n && walletFallbackAvailable < collateralVaultShortfall;
 
   return {
     canUnwind: true,
@@ -239,10 +291,18 @@ export async function preflightUnwindWriterUnsold(
       totalInterest: totals.interest,
       totalProtocolFees: totals.fees,
       totalOwed: totals.owed,
+      proportionalPrincipal,
+      proportionalInterest,
+      proportionalProtocolFees,
+      proportionalTotalOwed,
+      proportionalCollateralShare,
+      returnableCollateral,
       collateralVaultAvailable,
       walletFallbackAvailable,
       walletFallbackRequired,
       shortfall,
+      collateralVaultShortfall,
+      needsWalletTopUp,
     },
   };
 }