@epicentral/sos-sdk 0.9.0-beta

package/.env.example

@@ -0,0 +1 @@
+NPM_TOKEN=EnterNpmTokenHere

package/AGENTS.md

@@ -0,0 +1,7 @@
+# Multi-repo context
+
+This repo is the **canonical** `@epicentral/sos-sdk` package (npm). Full workspace instructions (how **option-program**, **sos-sdk**, and **solana-opx** relate, versioning, sync workflow) live in **[`AGENTS.md`](../solana-opx/AGENTS.md)** when repos are siblings, or open `solana-opx/AGENTS.md` from the Cursor multi-root workspace.
+
+Package manager for this repo: **`npm`**.
+
+When SDK changes must be consumed by OPX: see **`solana-opx/.cursor/rules/program-sdk-opx-sync.mdc`** — consumers using `file:../sos-sdk` need **`pnpm install`** in **solana-opx** after pulls.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Epicentral Labs, DAO LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,568 @@
+# @epicentral/sos-sdk
+
+TypeScript/JavaScript SDK for the Solana Option Standard (SOS) program. The frontend-first SDK for native options trading on Solana. Built with `@solana/kit` and related Solana libraries.
+
+## Installation
+
+```bash
+pnpm add @epicentral/sos-sdk
+```
+
+Peer dependencies: `@solana/kit` (and your RPC client). The SDK uses `KitRpc` for account resolution and fetches.
+
+## Overview
+
+The SDK supports two main flows:
+
+- **Long (buyer)** – Buy options from the pool, close positions, exercise.
+- **Short (writer)** – Mint options (write), unwind unsold, settle collateral, claim theta.
+
+Additional modules:
+
+- **OMLP** – Option Maker Liquidity Pool. Lenders deposit; writers borrow to collateralize shorts.
+- **WSOL** – Helpers for wrapping/unwrapping SOL and creating token accounts.
+
+## High-Level Functions and Instructions
+
+### Accounts, PDAs, and Fetchers
+
+| Function | Description |
+|----------|-------------|
+| `resolveOptionAccounts` | Resolves option pool, mints, vaults, and collateral accounts from option identity (underlying, type, strike, expiration). |
+| `deriveVaultPda` | Derives OMLP vault PDA from mint. |
+| `derivePoolLoanPdaFromVault` | Derives PoolLoan PDA from vault, maker, nonce (canonical; matches program). |
+| `derivePoolLoanPda` | *(Deprecated)* Legacy derivation; use `derivePoolLoanPdaFromVault`. |
+| `deriveWriterPositionPda` | Derives writer position PDA from option pool and writer. |
+| `deriveAssociatedTokenAddress` | Derives ATA for owner + mint. |
+| `fetchVault` | Fetches vault account by address. |
+| `fetchPoolLoansByMaker` | Fetches active pool loans for a maker. |
+| `fetchOptionPool` | Fetches option pool account. |
+| `fetchWriterPositionsByWriter` | Fetches writer positions for a writer. |
+| `fetchWriterPositionsForPool` | Fetches writer positions for an option pool. |
+| `fetchPositionAccountsByBuyer` | Fetches buyer position accounts. |
+| `fetchAllOptionPools` | Fetches all option pools. |
+| `fetchAllVaults` | Fetches all vaults. |
+
+### Long (Buyer) Flows
+
+| 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. |
+| `preflightCloseLongToPool` | Close-long preflight: verifies `sum(active WriterPosition.sold_qty) == OptionPool.total_sold_qty` so the on-chain Hamilton completeness check will pass. |
+| `buildCloseLongToPoolTransactionWithDerivation` | Builds close-long-to-pool transaction; auto-populates the complete active WriterPosition set, appends CloseAccount for buyer LONG ATA, and unwraps WSOL payout when underlying is SOL. |
+| `getBuyFromPoolRemainingAccounts` | Builds `remaining_accounts` for `buy_from_pool`: active WriterPositions sorted by `(createdAt asc, pubkey asc)` (FIFO; matches the on-chain ordering check). |
+| `getCloseLongToPoolRemainingAccounts` | Builds `remaining_accounts` for `close_long_to_pool`: **every** active WriterPosition for the pool (required for the Hamilton sum-check). |
+
+### Short (Writer) Flows
+
+| Function | Description |
+|----------|-------------|
+| `buildOptionMintTransactionWithDerivation` | Builds option mint (write) transaction. By default appends CloseAccount for the maker's LONG token account after mint (reclaim rent). Supports multi-collateral: use `collateralMint` to back positions with any supported asset (USDC, BTC, SOL, etc.). |
+| `buildUnwindWriterUnsoldTransactionWithDerivation` | Builds unwind unsold transaction. |
+| `buildUnwindWriterUnsoldWithLoanRepayment` | **Unwind + repay pool loans in one tx.** Use when closing unsold shorts that borrowed from OMLP. |
+| `buildSyncWriterPositionTransaction` | Syncs writer position with pool accumulators. |
+| `buildSettleMakerCollateralTransaction` | Settles maker collateral after buyer closes (repays principal + accrued interest to OMLP from collateral vault first, then returns remainder to maker). |
+| `buildCloseOptionTransaction` | Closes option token account. |
+| `buildClaimThetaTransaction` | Claims theta (time-decay share) for writer. |
+| `buildRepayPoolLoanFromCollateralInstruction` | Repays pool loan from collateral (short/pool). |
+| `buildRepayPoolLoanInstruction` | Repays pool loan with external funds (short/pool). |
+| `buildRepayPoolLoanFromWalletInstruction` | Repays pool loan from maker's wallet (stuck loan recovery). |
+
+### Seller Close Signers
+
+- `buildUnwindWriterUnsoldWithLoanRepayment` / `buildUnwindWriterUnsoldTransactionWithDerivation`
+  - Requires `writer` transaction signer.
+  - On-chain transfers for lender repayment and collateral return are authorized by program PDAs (`collateral_pool` / `option_pool`) where applicable.
+- `buildSettleMakerCollateralTransaction`
+  - No maker transaction signer is required by this instruction format.
+  - On-chain repayment (`collateral_vault` -> `omlp_vault`) and maker return are signed by the `collateral_pool` PDA.
+  - Lender repayment is sourced from collateral vault funds, not maker wallet funds.
+
+### OMLP (Lending)
+
+| Function | Description |
+|----------|-------------|
+| `buildDepositToPositionTransaction` | Deposits liquidity to OMLP. |
+| `buildWithdrawFromPositionTransaction` | Withdraws liquidity; supports optional same-tx WSOL unwrap via `unwrapSol` + `vaultMint`. |
+| `withdrawAllFromPosition` | Withdraws full position (principal + proportional interest, including pending index accrual, capped by pool liquidity). |
+| `withdrawInterestFromPosition` | Withdraws interest only (realized + pending index accrual, capped by pool liquidity). |
+
+Borrow/repay for writers: use `buildOptionMintTransactionWithDerivation` (with vault/poolLoan) and `buildRepayPoolLoanFromCollateralInstruction` or `buildUnwindWriterUnsoldWithLoanRepayment`.
+
+**PoolLoan ↔ WriterPosition:** Each `PoolLoan` stores `writer_position` (the `WriterPosition` PDA for that option pool + maker). `borrow_from_pool` records it; `option_mint` checks it matches the mint’s writer account. Clients should filter loans with `loan.writerPosition === writerPositionAddress` (same vault, active status). Standard repay instructions require `optionPool` and `writerPosition` accounts that match the loan.
+
+The Codama **`generated/instructions`** module also exposes **admin vault tuning** IXs gated by protocol `config.admin`: besides fee / leverage / supply / borrow-cap updates, you can rotate `Vault::fee_wallet` (`omlpUpdateFeeWallet`), change liquidation threshold (`omlpUpdateLiquidationThreshold`), and update the interest-rate kink curve (`omlpUpdateInterestModel`).
+
+### Transaction size and Address Lookup Tables
+
+Option mint (and buy/close) transactions exceed Solana's 1232-byte limit without compression. If you see **"encoding overruns Uint8Array"** when minting, pass `network` to `sendBuiltTransaction`:
+
+```ts
+await sendBuiltTransaction({
+  instructions: tx.instructions,
+  rpc,
+  rpcSubscriptions,
+  feePayer: walletSigner,
+  network: "devnet",  // or "mainnet" — auto-includes lookup table when configured
+});
+```
+
+Or pass `addressLookupTableAddresses: [getLookupTableAddressForNetwork("devnet")]` when non-null. Mainnet lookup table is `null` by default; create one via `yarn update:lookuptable` for mainnet.
+
+### Token account closing (option mint and close long)
+
+- **Option mint (seller/writer):** After `option_mint`, all LONG tokens go to the pool escrow; the maker's LONG ATA is left with zero balance. The SDK **automatically appends an SPL CloseAccount instruction** (when `closeMakerLongAccount` is not set to `false`) so the maker reclaims rent. Use `buildOptionMintTransaction` or `buildOptionMintTransactionWithDerivation`; pass `closeMakerLongAccount: false` to skip closing the LONG ATA.
+- **Close long (buyer):** When the buyer closes or exercises early via `close_long_to_pool`, LONG tokens are returned to the pool and payout is sent to the buyer's payout ATA. The SDK can:
+  - **Close the buyer's LONG token account** after the close instruction so rent is reclaimed. Use `closeLongTokenAccount: true` (default for `buildCloseLongToPoolTransactionWithDerivation`); set to `false` for **partial** closes (the LONG ATA still holds remaining tokens).
+  - **Unwrap WSOL payout** when the option underlying is SOL: append CloseAccount on the payout ATA so the buyer receives native SOL. Use `unwrapPayoutSol: true` (default for WSOL in the derivation builder); set to `false` to keep payout as WSOL.
+
+### Partial Close: Buyers
+
+`close_long_to_pool` already supports any partial quantity on-chain. To close fewer contracts than the full position:
+
+```ts
+import { buildCloseLongToPoolTransactionWithDerivation, preflightCloseLongToPool } from "@epicentral/sos-sdk";
+
+const fullPositionQty = 5; // contracts held
+const closeQty = 2;        // contracts to sell back
+
+const preflight = await preflightCloseLongToPool({
+  underlyingAsset, optionType, strikePrice, expirationDate,
+  quantity: BigInt(Math.floor(closeQty * 1e6)),
+  rpc, programId,
+});
+if (!preflight.canClose) throw new Error(preflight.reason);
+
+const built = await buildCloseLongToPoolTransactionWithDerivation({
+  underlyingAsset, optionType, strikePrice, expirationDate,
+  buyer, buyerLongAccount, buyerPayoutAccount,
+  quantity: BigInt(Math.floor(closeQty * 1e6)),
+  minPayoutAmount: 0n,
+  // Keep the LONG ATA open — it still holds remaining tokens after the partial close.
+  closeLongTokenAccount: false,
+  rpc, rpcEndpoint,
+});
+```
+
+For the **final close** (closing the last remaining contracts), use the default `closeLongTokenAccount: true` so the buyer's LONG ATA is closed and rent is reclaimed.
+
+### Partial Unwind: Writers
+
+`unwind_writer_unsold` supports any quantity ≤ `unsoldQty`. To unwind fewer contracts than the full unsold position:
+
+```ts
+import { buildUnwindWriterUnsoldWithLoanRepayment, preflightUnwindWriterUnsold } from "@epicentral/sos-sdk";
+
+const fullUnsoldQty = 10_000_000n; // 10 contracts in base units
+const partialUnwindQty = 3_000_000n; // 3 contracts to unwind
+
+const preflight = await preflightUnwindWriterUnsold({
+  underlyingAsset, optionType, strikePrice, expirationDate,
+  writer, unwindQty: partialUnwindQty, rpc, programId,
+});
+if (!preflight.canUnwind) throw new Error(preflight.reason);
+// Use preflight.effectiveUnwindQty (may be capped by available qty)
+const built = await buildUnwindWriterUnsoldWithLoanRepayment({
+  underlyingAsset, optionType, strikePrice, expirationDate,
+  writer, unwindQty: preflight.effectiveUnwindQty, rpc, programId,
+});
+```
+
+**Writer sold exposure:** Writers can only unwind `unsoldQty`. Sold contracts (filled by buyers) are not unwindable until buyers sell back via `close_long_to_pool`, which converts sold inventory back to unsold. On-chain `unwind_writer_unsold` enforces `unwindQty ≤ unsoldQty` and repays loan principal, interest, and fees proportionally to the unwind slice.
+
+### OMLP withdraw behavior
+
+- Interest is allocated proportionally via the vault interest-per-share index.
+- On-chain `withdraw_from_position` syncs pending interest before transferring funds, so a lender withdrawal automatically includes their proportional earned interest when available.
+- `withdrawAllFromPosition` and `withdrawInterestFromPosition` compute pending interest from `accInterestPerShareFp` and `interestIndexSnapshotFp`, then cap by `poolAvailable = totalLiquidity - totalLoans`.
+- Optional WSOL unwrap in the same transaction:
+  - Set `unwrapSol: true` and provide `vaultMint`.
+  - If `vaultMint === NATIVE_MINT`, SDK appends a `CloseAccount` after withdraw to unwrap WSOL ATA to native SOL.
+  - For non-WSOL mints, the same builder remains token-agnostic and does not append unwrap instructions.
+
+### WSOL / Token Helpers
+
+| Function | Description |
+|----------|-------------|
+| `getWrapSOLInstructions` | Wraps SOL to WSOL. |
+| `getUnwrapSOLInstructions` | Unwraps WSOL to SOL. |
+| `getCreateAssociatedTokenIdempotentInstructionWithAddress` | Creates ATA if missing (idempotent). |
+| `NATIVE_MINT` | WSOL mint address. |
+
+### Oracle / Switchboard
+
+| Function | Description |
+|----------|-------------|
+| `resolveSwitchboardFeedFromMarketData` | Resolves Switchboard feed address from market data account. |
+| `resolveSwitchboardFeedIdFromMarketData` | Resolves Switchboard feed ID (hex) from market data account. |
+| `buildSwitchboardQuoteInstruction` | Builds a direct quote instruction (ed25519 verify ix) for quote-path transactions. |
+| `buildSwitchboardPullFeedUpdate` | Low-level helper that fetches Switchboard pull-feed update instructions. |
+| `buildSwitchboardQuoteWeb3JsInstruction` | Same as `buildSwitchboardQuoteInstruction` but returns a legacy web3.js instruction (Anchor scripts). |
+| `buildSwitchboardCrank` | Returns Kit-native crank instructions plus lookup tables for the configured feed (legacy / non-oracle paths). |
+| `prependSwitchboardCrank` | Prepends crank instructions/ALTs to a built SDK transaction. |
+| `prependSwitchboardQuote` | Prepends the verified quote ix at transaction index `0`. |
+| `getDefaultSwitchboardQueueAddress` | Returns the default Switchboard on-demand queue for `devnet` or `mainnet` (use as program `switchboard_queue`). |
+
+**Devnet / on-demand quote:** Trade and validation flows prepend `buildSwitchboardQuoteInstruction` (Crossbar / `Queue.fetchQuoteIx`), not a crank update. Pass **`getDefaultSwitchboardQueueAddress(network)`** (or `SWITCHBOARD_DEFAULT_DEVNET_QUEUE` on devnet) as **`switchboard_queue`** on program instructions — do not thread **`quote.queueAddress`** from the quote result; the default queue is the single obvious source of truth and matches Switchboard’s default queue for the cluster. `buildSwitchboardCrank` remains for legacy or non-oracle paths.
+
+Long-open / long-close / `option_mint` derivation builders prepend `buildSwitchboardQuoteInstruction` by default (`rpcEndpoint` required). OMLP deposit/withdraw may still use crank prepends where those instructions do not consume oracle accounts.
+
+See [Frontend Switchboard Integration](../../docs/FRONTEND_SWITCHBOARD_INTEGRATION.md) for full setup and usage.
+
+### Global Trade Config
+
+Use the shared trade config helpers to set SDK-wide defaults for slippage and compute-budget settings:
+
+- `setGlobalTradeConfig`
+- `updateGlobalTradeConfig`
+- `getGlobalTradeConfig`
+- `resetGlobalTradeConfig`
+
+These defaults are used by the high-level builders unless an action-specific override is provided. `option_mint` also forwards a max-collateral bound on-chain so signer delays cannot silently widen required collateral past the configured tolerance.
+
+## Multi-Collateral Settlement
+
+The SDK supports universal multi-collateral settlement, allowing writers to use ANY supported asset as collateral for options (not just the underlying). This enables:
+
+- **Capital Efficiency**: Writers use whatever assets they hold (USDC, BTC, SOL, BONK, etc.)
+- **No Forced Conversions**: No swap fees or slippage to get the "correct" collateral
+- **Lender Flexibility**: Lend any supported asset, earn yield in that asset
+
+### How it works
+
+When minting an option, specify `collateralMint` to choose the backing asset:
+
+```ts
+import {
+  buildOptionMintTransactionWithDerivation,
+  OptionType,
+} from "@epicentral/sos-sdk";
+
+// Write SOL calls backed by USDC
+const tx = await buildOptionMintTransactionWithDerivation({
+  underlyingAsset: SOL_MINT,
+  optionType: OptionType.Call,
+  strikePrice: 150.0,
+  expirationDate: BigInt(1735689600),
+  quantity: 1_000_000,           // 1 contract
+  underlyingMint: SOL_MINT,
+  underlyingSymbol: "SOL",
+  collateralMint: USDC_MINT,     // Back with USDC instead of SOL
+  makerCollateralAmount: 780_000_000,  // $780 (10% of $7,800)
+  borrowedAmount: 7_020_000_000,       // $7,020 (90% borrowed)
+  maker: walletAddress,
+  rpc,
+});
+```
+
+**Key points:**
+- `collateralMint` defaults to `underlyingMint` if not provided (backwards compatible)
+- OMLP vault routing is based on `collateralMint` - the vault must exist for the collateral asset
+- At settlement, buyers receive payout in the collateral currency that backed the position
+- The `WriterPosition` account tracks `collateralMint` and `settlementMint` for each position
+
+### Collateral Calculation
+
+Use `calculateRequiredCollateral` to estimate collateral needs before minting:
+
+```ts
+import { calculateRequiredCollateral } from "@epicentral/sos-sdk";
+
+const required = calculateRequiredCollateral(
+  1_000_000n,      // 1 contract in base units
+  150.0,           // $150 strike price
+  145.23,          // Current spot price (USD)
+  6                // USDC decimals
+);
+// Returns: USDC base units needed
+```
+
+## Unwind with Loan Repayment (theta-hedge model)
+
+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` under a **theta-first, full-repay-or-revert** model.
+
+**Proportional Repayment (partial unwinds):**
+- Unwind ratio = `unwind_qty / written_qty`
+- Principal, interest, and protocol fees are sliced by the unwind ratio against the pool's full, accrued debt snapshot.
+
+**Repayment waterfall (on-chain):**
+1. `writer_position.realize_theta(pool.acc_theta_per_oi_fp)` — pending theta becomes `theta_balance`.
+2. `theta_to_debt = min(theta_balance, proportional_debt)` paid from `premium_vault` (only when `premium_vault.mint == omlp_vault.mint`).
+3. `collateral_to_debt = proportional_debt - theta_to_debt` paid from `collateral_vault`. If the writer's proportional collateral share cannot cover it, the instruction reverts with `LiquidationInsufficientCollateralForDebt` — keepers route the position to `liquidate_writer_position_rescue`.
+4. Leftover theta (`theta_balance - theta_to_debt`) is transferred to the writer from `premium_vault`.
+5. Unlocked collateral (`proportional_share - collateral_to_debt`) is transferred to the writer from `collateral_vault`.
+
+> **There is no wallet fallback path.** Writers do not top up from their own wallet during unwind; the protocol always closes the book via theta + collateral (or routes to the keeper rescue instruction on insolvency).
+
+**Collateral Return:**
+- Proportional collateral share = `(collateral_deposited * unwind_qty) / written_qty`
+- Returnable collateral = `proportional_share - collateral_to_debt`
+- Insolvent writer (proportional_share < collateral_to_debt) ⇒ `LiquidationInsufficientCollateralForDebt` (6099)
+- Drained vault (collateral_vault.amount < collateral_to_debt) ⇒ `InsufficientCollateralVault` (6090)
+
+Use **`buildUnwindWriterUnsoldWithLoanRepayment`** so that:
+
+1. Active pool loans for the option's underlying vault are fetched.
+2. `omlpVaultState` (Vault PDA), `omlpVault`, `feeWallet`, and `premiumVault` are passed as named accounts.
+3. `remaining_accounts` = **[PoolLoan₁, PoolLoan₂, ...]** only (capped at 20 loans per tx).
+4. One transaction burns LONG+SHORT, repays lenders theta-first, pays protocol fees, and returns leftover theta + unlocked collateral to the writer.
+
+Use **`preflightUnwindWriterUnsold`** before building the transaction to get:
+
+- Per-loan principal / interest / protocol-fee breakdown.
+- **Proportional obligations** for the slice (principal, interest, fees, total owed).
+- **Theta hedge breakdown**: `thetaAvailable`, `thetaToDebt`, `collateralToDebt`, `premiumMintMatchesCollateralMint`.
+- **Collateral return**: `proportionalCollateralShare`, `returnableCollateral`.
+- **Shortfalls**: `collateralClaimShortfall` (writer underwater — rescue required), `collateralVaultShortfall` (vault drained), `needsRescue`.
+- `canRepayRequestedSlice` — `true` when the slice will settle without rescue.
+- Deprecated compatibility fields: `canRepayFully` mirrors `canRepayRequestedSlice`; `writerRepaymentAccount` resolves to the writer's default underlying ATA but is **not used on-chain** anymore.
+
+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. **Note: this is for the standalone repay flow, not unwind** — unwind itself has no wallet fallback.
+
+### Recommended Preflight + Unwind
+
+```ts
+import {
+  preflightUnwindWriterUnsold,
+  buildUnwindWriterUnsoldWithLoanRepayment,
+} from "@epicentral/sos-sdk";
+
+const preflight = await preflightUnwindWriterUnsold({
+  underlyingAsset,
+  optionType,
+  strikePrice,
+  expirationDate,
+  writer,
+  unwindQty,
+  rpc,
+});
+
+if (preflight.summary.needsRescue) {
+  // Writer is underwater — route to keeper rescue path instead of unwind.
+  // See buildLiquidateWriterPositionRescueInstruction.
+  throw new Error(preflight.reason);
+}
+
+const tx = await buildUnwindWriterUnsoldWithLoanRepayment({
+  underlyingAsset,
+  optionType,
+  strikePrice,
+  expirationDate,
+  writer,
+  unwindQty,
+  rpc,
+});
+```
+
+Error codes to watch (see `generated/errors/optionProgram.ts`):
+
+- `MaintenanceBufferBreached` (6098) — position breaches the OMLP maintenance buffer at call time.
+- `LiquidationInsufficientCollateralForDebt` (6099) — writer is underwater; use the rescue ix.
+- `ThetaClaimDisabled` (6100) — legacy client still calling `claim_theta` (removed).
+- `MaintenanceLoansIncomplete` (6101) — `remaining_accounts` missing active pool loans.
+- `RescueUnauthorized` (6102) — rescue ix caller is not the vault keeper.
+- `InvalidLoanRepayment` (6103) — repayment exceeded synced balances (slot race).
+- `RescuePreconditionsNotMet` (6104) — rescue called on a solvent position.
+
+## Usage Examples
+
+### Buy From Pool (market order, high-level)
+
+```ts
+import {
+  buildBuyFromPoolMarketOrderTransactionWithDerivation,
+  preflightBuyFromPoolMarketOrder,
+  OptionType,
+} from "@epicentral/sos-sdk";
+
+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,
+  expirationDate: BigInt(1735689600),
+  buyer: walletAddress,
+  // Must be the buyer's ATA for option_pool.underlying_mint (same mint as `quotedPremiumTotal` base units).
+  buyerPaymentAccount: buyerUnderlyingAta,
+  quantity: 1_000_000,
+  quotedPremiumTotal: 50_000,
+  slippageBufferBaseUnits: 500_000n,
+  rpc,
+  rpcEndpoint: "https://api.devnet.solana.com",
+});
+```
+
+### Buy premium semantics (market orders)
+
+- Premium is paid in the **option pool underlying** token; `buyer_payment_account` must match that mint (see program `buy_from_pool`).
+- `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` **underlying** base units when using global trade-config slippage (not lamports unless underlying is SOL/WSOL)
+
+### 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 FIFO fill loop
+- `BuyRemainingAccountsUnsorted` (6096) – `remaining_accounts` not sorted by `(createdAt asc, pubkey asc)`
+
+`option_pool.total_available` is the on-chain aggregate of LONG in pool escrow that may be sold via `buy_from_pool` (increments on writer deposit and on buyer `close_long_to_pool` recycle, decrements on buy and on unwind/liquidation). Client UX often combines it with writer `unsold_qty` (e.g. `min`). `buy_from_pool` fills writers strictly FIFO — the SDK sorts by `(createdAt asc, pubkey asc)` in `getBuyFromPoolRemainingAccounts` and the program verifies the same ordering on-chain.
+
+**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 (FIFO-sorted) and asserts active writer liquidity >= requested quantity before building.
+
+### Close-long errors (Hamilton recycle)
+
+`close_long_to_pool` returns closed LONG tokens to the pool escrow and redistributes the recovered `sold_qty` back to writers as `unsold_qty` using a Hamilton largest-remainder allocation. The program enforces a **strict completeness** check against the full active writer set:
+
+- `CloseLongWritersIncomplete` (6095) – `sum(passed WriterPosition.sold_qty) != OptionPool.total_sold_qty`
+- `CloseLongNoSoldInventory` (6096) – `OptionPool.total_sold_qty == 0` or no WriterPositions passed (also raised when close quantity exceeds `total_open_interest_qty`, which is a pre-check in `close_long_to_pool` that keeps the post-close utilization used by marginal IV non-negative)
+- `CloseLongDuplicateWriter` (6097) – duplicate `WriterPosition` pubkeys in `remaining_accounts`
+
+Use `getCloseLongToPoolRemainingAccounts` to build the complete active set, or let `buildCloseLongToPoolTransactionWithDerivation` populate it automatically. Run `preflightCloseLongToPool` to catch data-staleness mismatches before submit.
+
+### Pool pricing: marginal IV + lender-senior payout cap
+
+**`buy_from_pool` / `close_long_to_pool` price against marginal utilization, not stored IV.** Premium / payout BS inputs use σ evaluated at the pool state *after* the trade:
+
+| Leg | σ utilization |
+|-----|--------------|
+| `buy_from_pool`         | `(total_open_interest_qty + quantity) / total_deposited` |
+| `close_long_to_pool`    | `(total_open_interest_qty − quantity) / total_deposited` |
+| `OptionAccount.implied_volatility` | refreshed to **post-state** σ after counter updates (indexer display) |
+
+Stored `implied_volatility` is the right number for option-chain displays, but **not** the right σ to quote the current trade. Callers quoting previews client-side should mirror this using `calculateKinkImpliedVolatility(hv, totalDeposited, totalOpenInterestQty ± tradeQty)` in OPX (`kink-implied-volatility.ts`). This closes the same-slot round-trip arbitrage where buying pulled σ up but an immediate close was previously priced against the **same pre-trade stored σ** — buyers now always pay σ_high (post-buy OI) and receive σ_low (post-close OI), so churn loses money with unchanged oracle and time.
+
+**`close_long_to_pool` caps buyer payouts at maker equity.** The collateral-leg budget is now the `min` of:
+
+1. `total_maker_contribution − total_interest_owed` (stakeholder maker-equity formula; `total_interest_owed` includes fees via `sync_collateral_pool_debt`).
+2. `total_collateral − (total_borrowed + total_interest_owed)` (principal-safe budget).
+
+Both are saturating. `total_collateral` continues to back cash-covered / solvency checks, but it is **not** the buyer payout budget — that protection prevents buyers from draining the lender-owned sleeve of the collateral vault.
+
+Preflight / `min_payout_amount` simulation impact:
+
+- The previous `max_payable = premium_capacity + total_collateral` upper bound is no longer the chain-truth capacity. Callers that simulate exact proceeds must use the new cap.
+- Low-risk heuristic for UX: approximate `collateral_capacity ≈ min(total_maker_contribution − total_interest_owed, total_collateral − total_borrowed − total_interest_owed)`; feed the result into the same `compute_close_payout_split` formula the program uses for the premium-first split.
+- For pools without borrow (`total_borrowed == 0`), the cap collapses to `total_maker_contribution − 0 = total_maker_contribution` (fees/interest are zero too), which matches the previous behavior.
+
+Full write-up, golden vectors, and parity matrix live in `option-program/docs/PRICING_PARITY.md` — **"Marginal IV for pool buy/close"** and **"Lender seniority: buyer payouts must not use borrowed funds"**.
+
+### Framework deserialization errors (`#3003`)
+
+If simulation fails with `custom program error: #3003`, this usually means account deserialization failed before business logic (`60xx`) ran.
+
+Check these first:
+
+- `buyer_position` account shape/size (`146` bytes expected).
+- `market_data` account shape/size (`128` bytes expected).
+- Price-sensitive instructions use **verified quotes**: pass `rpcEndpoint` so the SDK can prepend `buildSwitchboardQuoteInstruction` at ix `0` (unless `disableSwitchboardCrank`). Ensure `market_data.switchboard_feed_id` holds the 32-byte feed ID hash.
+- For `option_mint`, the three oracle accounts are passed via **remaining_accounts** (queue, SlotHashes, Instructions sysvars); other updated instructions take them as named accounts.
+- `write_to_pool`, `unwind_writer_unsold`, and `liquidate_writer_position_rescue` include the **`market_data` PDA** (read-only, after `option_account`) for in-tx IV refresh; `resolveOptionAccounts` / `deriveMarketDataPda` supply it.
+- Account list/order matches the generated instruction layout.
+
+This is different from liquidity failures (`6042/6043`) and should be debugged as an account wiring/layout issue.
+
+### Oracle inputs (asset-agnostic)
+
+- Keep oracle handling universal across assets.
+- Use the market-configured `switchboard_feed_id` as source-of-truth.
+- On-chain verification uses the feed ID in the Switchboard quote at transaction index `0`; the program checks queue + sysvars + quote proof.
+- Avoid hardcoding a single feed/account address in shared SDK integration flows.
+
+### Price update freshness (required for accurate payouts)
+
+The program verifies a **Switchboard quote instruction at tx index 0** and reads the price for the configured `switchboard_feed_id` for:
+
+- **Buy / close / validate / exercise / liquidation / auto-exercise:** Black-Scholes or intrinsic math uses that verified spot.
+
+The SDK prepends `buildSwitchboardQuoteInstruction` by default for these builders (same pattern as `option_mint`).
+
+- **Mainnet / devnet:** fetch the quote immediately before submit; quotes age out after a bounded slot window (`SWITCHBOARD_QUOTE_MAX_AGE_SLOTS` on-chain).
+
+**Note:** Pull-feed-only crank prepends are deprecated for these program paths; use the quote + named oracle accounts (or `remaining_accounts` for `option_mint`).
+
+### Unwind with loan repayment
+
+```ts
+import {
+  buildUnwindWriterUnsoldWithLoanRepayment,
+  OptionType,
+} from "@epicentral/sos-sdk";
+
+const tx = await buildUnwindWriterUnsoldWithLoanRepayment({
+  underlyingAsset: "...",
+  optionType: OptionType.Call,
+  strikePrice: 100_000,
+  expirationDate: BigInt(1735689600),
+  writer: walletAddress,
+  unwindQty: 500_000,
+  rpc,
+});
+```
+
+## Types and Exports
+
+Key types exported from the package:
+
+- `OptionType` – Call or Put.
+- `BuiltTransaction` – `{ instructions: Instruction[] }`.
+- `AddressLike` – `string | Address`.
+- `KitRpc` – RPC client type for fetches.
+- `RemainingAccountInput` – `{ address, isWritable, isSigner? }`.
+
+PDAs, fetchers, and builders are exported from the package root.
+
+## Program Compatibility
+
+The SDK targets the Solana Option Standard program. Use `PROGRAM_ID` (or `getProgramId()`) from the package for the program address. Pass `programId` in builder params when using a different deployment.
+
+## Collateral Calculation Helper
+
+The SDK exports `calculateRequiredCollateral` for pre-flight collateral estimation:
+
+```ts
+import { calculateRequiredCollateral } from "@epicentral/sos-sdk";
+
+const required = calculateRequiredCollateral(
+  1_000_000n,      // 1 contract in base units
+  150.0,           // $150 strike price
+  145.23,          // Current spot price (USD)
+  9                // Token decimals (9 for SOL)
+);
+// Returns: token base units needed (e.g., 103_280_000_000 lamports for ~103.28 SOL)
+```
+
+**Formula:**
+```
+contracts     = quantity / 1_000_000
+usd_value     = contracts * 100 * strike_price
+collateral    = (usd_value / spot_price) * 10^token_decimals
+```
+
+This matches the on-chain formula in `Vault::calculate_required_collateral` and can be used to display required collateral to users before submitting an `option_mint` transaction.