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

package/README.md

@@ -1,177 +1,164 @@
 # @epicentral/sos-sdk
 
-Solana Option Standard SDK. A frontend-first SDK for native options trading on Solana, built by Epicentral Labs.
+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.
 
-Uses `@solana/kit` types (`Address`, `Instruction`, `Rpc`) across the public API.
-
-## Install
+## Installation
 
 ```bash
-pnpm add @epicentral/sos-sdk @solana/kit decimal.js
+pnpm add @epicentral/sos-sdk
 ```
 
+Peer dependencies: `@solana/kit` (and your RPC client). The SDK uses `KitRpc` for account resolution and fetches.
+
 ## Overview
 
-- **LONG** — Buy from pool, close to pool, exercise options.
-- **SHORT** — Mint options, unwind, sync, settle, claim premium, close option.
-- **Pool** — Deposit, withdraw, borrow, repay liquidity.
-- **OMLP** — Lender deposit and withdraw.
-- **Accounts** — PDA derivation and account fetchers for options, pools, vaults.
+The SDK supports two main flows:
 
-Each flow exposes `build*Instruction` for single instruction composition and `build*Transaction` for full-flow `Instruction[]` construction.
+- **Long (buyer)** – Buy options from the pool, close positions, exercise.
+- **Short (writer)** – Mint options (write), unwind unsold, settle collateral, claim theta.
 
-## Usage
+Additional modules:
 
-### Build + send (recommended)
+- **OMLP** – Option Maker Liquidity Pool. Lenders deposit; writers borrow to collateralize shorts.
+- **WSOL** – Helpers for wrapping/unwrapping SOL and creating token accounts.
 
-```ts
-import {
-  buildBuyFromPoolTransaction,
-  sendBuiltTransaction,
-} from "@epicentral/sos-sdk";
+## High-Level Functions and Instructions
 
-const built = await buildBuyFromPoolTransaction(params);
-const signature = await sendBuiltTransaction({
-  rpc,
-  rpcSubscriptions,
-  feePayer: walletSigner,
-  instructions: built.instructions,
-});
-```
+### Accounts, PDAs, and Fetchers
 
-### Build + send (manual)
+| 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. |
 
-```ts
-import {
-  appendTransactionMessageInstructions,
-  createTransactionMessage,
-  pipe,
-  sendAndConfirmTransactionFactory,
-  setTransactionMessageFeePayerSigner,
-  setTransactionMessageLifetimeUsingBlockhash,
-  signTransactionMessageWithSigners,
-} from "@solana/kit";
-import { buildBuyFromPoolTransaction } from "@epicentral/sos-sdk";
-
-const built = await buildBuyFromPoolTransaction(params);
-const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
-
-const txMessage = pipe(
-  createTransactionMessage({ version: 0 }),
-  (tx) => setTransactionMessageFeePayerSigner(walletSigner, tx),
-  (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
-  (tx) => appendTransactionMessageInstructions(built.instructions, tx)
-);
-
-const signedTx = await signTransactionMessageWithSigners(txMessage);
-await sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions })(signedTx, {
-  commitment: "confirmed",
-});
-```
+### Long (Buyer) Flows
 
-### LONG
+| Function | Description |
+|----------|-------------|
+| `buildBuyFromPoolTransactionWithDerivation` | Builds buy-from-pool transaction; resolves accounts from option identity. |
+| `buildCloseLongToPoolTransactionWithDerivation` | Builds close-long-to-pool transaction. |
+| `getBuyFromPoolRemainingAccounts` | Builds remaining_accounts for buy (writer positions, etc.). |
 
-```ts
-import {
-  buildBuyFromPoolTransaction,
-  buildCloseLongToPoolTransaction,
-  buildOptionExerciseTransaction,
-} from "@epicentral/sos-sdk";
+### Short (Writer) Flows
 
-// Open LONG
-const openLong = await buildBuyFromPoolTransaction(openLongParams);
+| Function | Description |
+|----------|-------------|
+| `buildOptionMintTransactionWithDerivation` | Builds option mint (write) transaction. |
+| `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. |
+| `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). |
 
-// Close LONG
-const closeLong = await buildCloseLongToPoolTransaction(closeLongParams);
+### OMLP (Lending)
 
-// Exercise LONG
-const exercise = buildOptionExerciseTransaction({ optionAccount, positionAccount, /* ... */ });
-```
+| Function | Description |
+|----------|-------------|
+| `buildDepositToPositionTransaction` | Deposits liquidity to OMLP. |
+| `buildWithdrawFromPositionTransaction` | Withdraws liquidity. |
+| `withdrawAllFromPosition` | Withdraws full position (omlp/service). |
+| `withdrawInterestFromPosition` | Withdraws accrued interest only (omlp/service). |
 
-### SHORT
+Borrow/repay for writers: use `buildOptionMintTransactionWithDerivation` (with vault/poolLoan) and `buildRepayPoolLoanFromCollateralInstruction` or `buildUnwindWriterUnsoldWithLoanRepayment`.
 
-```ts
-import {
-  buildOptionMintTransaction,
-  buildUnwindWriterUnsoldTransaction,
-  buildSyncWriterPositionTransaction,
-  buildSettleMakerCollateralTransaction,
-  buildClaimPremiumTransaction,
-  buildCloseOptionTransaction,
-} from "@epicentral/sos-sdk";
-import { OptionType } from "@epicentral/sos-sdk";
+### WSOL / Token Helpers
 
-// Mint (open SHORT)
-const built = await buildOptionMintTransaction({
-  optionType: OptionType.Call,
-  strikePrice,
-  expirationDate,
-  quantity,
-  underlyingAsset,
-  underlyingSymbol,
-  makerCollateralAmount,
-  borrowedAmount,
-  maker,
-  makerCollateralAccount,
-  underlyingMint,
-});
+| Function | Description |
+|----------|-------------|
+| `getWrapSOLInstructions` | Wraps SOL to WSOL. |
+| `getUnwrapSOLInstructions` | Unwraps WSOL to SOL. |
+| `getCreateAssociatedTokenIdempotentInstructionWithAddress` | Creates ATA if missing (idempotent). |
+| `NATIVE_MINT` | WSOL mint address. |
 
-// Unwind / Sync / Settle
-const unwind = await buildUnwindWriterUnsoldTransaction(unwindParams);
-const sync = buildSyncWriterPositionTransaction(syncParams);
-const settle = await buildSettleMakerCollateralTransaction(settleParams);
+## Unwind with Loan Repayment
 
-// Claim premium / close option
-const claim = await buildClaimPremiumTransaction({ optionPool, makerPaymentAccount, premiumVault, maker });
-const close = buildCloseOptionTransaction({ optionAccount, optionMint, makerOptionAccount, maker });
-```
+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.
+
+Use **`buildUnwindWriterUnsoldWithLoanRepayment`** so that:
+
+1. Active pool loans for the option’s underlying vault are fetched.
+2. `omlpVaultState` (Vault PDA), `omlpVault`, and `feeWallet` are passed as named accounts.
+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.
+
+If there are no active pool loans for that vault, the API still works and passes empty `remaining_accounts`.
 
-### Pool
+**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.
+
+## Usage Examples
+
+### Buy from pool (with derivation)
 
 ```ts
 import {
-  buildDepositToPoolTransaction,
-  buildWithdrawFromPoolTransaction,
-  buildBorrowFromPoolTransaction,
-  buildRepayPoolLoanTransaction,
+  buildBuyFromPoolTransactionWithDerivation,
+  resolveOptionAccounts,
+  OptionType,
 } from "@epicentral/sos-sdk";
 
-const deposit = await buildDepositToPoolTransaction(depositToPoolParams);
-const withdraw = await buildWithdrawFromPoolTransaction(withdrawFromPoolParams);
-const borrow = await buildBorrowFromPoolTransaction(borrowFromPoolParams);
-const repay = await buildRepayPoolLoanTransaction(repayPoolLoanParams);
+const tx = await buildBuyFromPoolTransactionWithDerivation({
+  underlyingAsset: "...",
+  optionType: OptionType.Call,
+  strikePrice: 100_000,
+  expirationDate: BigInt(1735689600),
+  buyer: walletAddress,
+  buyerPaymentAccount: buyerUsdcAta,
+  priceUpdate: pythPriceFeed,
+  quantity: 1_000_000,
+  premiumAmount: 50_000,
+  rpc,
+});
 ```
 
-### OMLP
+### Unwind with loan repayment
 
 ```ts
 import {
-  buildDepositToPositionTransaction,
-  buildWithdrawFromPositionTransaction,
+  buildUnwindWriterUnsoldWithLoanRepayment,
+  OptionType,
 } from "@epicentral/sos-sdk";
 
-const deposit = await buildDepositToPositionTransaction({
-  vault,
-  lenderTokenAccount,
-  vaultTokenAccount,
-  lender,
-  amount,
-});
-const withdraw = await buildWithdrawFromPositionTransaction({
-  vault,
-  vaultTokenAccount,
-  lenderTokenAccount,
-  lender,
-  amount,
+const tx = await buildUnwindWriterUnsoldWithLoanRepayment({
+  underlyingAsset: "...",
+  optionType: OptionType.Call,
+  strikePrice: 100_000,
+  expirationDate: BigInt(1735689600),
+  writer: walletAddress,
+  unwindQty: 500_000,
+  rpc,
 });
 ```
 
-### Fetch accounts
+## Types and Exports
 
-```ts
-import { fetchOptionAccount, fetchOptionPool, fetchVault } from "@epicentral/sos-sdk";
+Key types exported from the package:
 
-const option = await fetchOptionAccount(rpc, optionAddress);
-const pool = await fetchOptionPool(rpc, optionPoolAddress);
-const vault = await fetchVault(rpc, vaultAddress);
-```
+- `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.

package/accounts/pdas.ts

@@ -258,6 +258,39 @@ export async function deriveEscrowAuthorityPda(
   });
 }
 
+/**
+ * Derives the PoolLoan PDA using the canonical seeds: vault, maker, nonce.
+ * Matches the program's derivation in omlp_context.rs (BorrowFromPool).
+ *
+ * @param vault - OMLP vault PDA (from deriveVaultPda)
+ * @param maker - Writer/borrower pubkey
+ * @param nonce - Loan nonce (u64)
+ * @param programId - Optional program ID
+ */
+export async function derivePoolLoanPdaFromVault(
+  vault: AddressLike,
+  maker: AddressLike,
+  nonce: bigint | number,
+  programId: AddressLike = PROGRAM_ID
+): Promise<readonly [Address, number]> {
+  const addressEncoder = getAddressEncoder();
+  return getProgramDerivedAddress({
+    programAddress: toAddress(programId),
+    seeds: [
+      new TextEncoder().encode("pool_loan"),
+      addressEncoder.encode(toAddress(vault)),
+      addressEncoder.encode(toAddress(maker)),
+      u64ToLeBytes(nonce),
+    ],
+  });
+}
+
+/**
+ * Derives the PoolLoan PDA using writer position and nonce.
+ *
+ * @deprecated This derivation does not match the program. Use {@link derivePoolLoanPdaFromVault}
+ * with (vault, maker, nonce) instead. Program seeds are: pool_loan, vault, maker, nonce (u64 le).
+ */
 export async function derivePoolLoanPda(
   writerPosition: AddressLike,
   nonce: bigint | number,

package/generated/instructions/index.ts

@@ -31,6 +31,7 @@ export * from "./optionMint";
 export * from "./optionValidate";
 export * from "./repayPoolLoan";
 export * from "./repayPoolLoanFromCollateral";
+export * from "./repayPoolLoanFromWallet";
 export * from "./settleMakerCollateral";
 export * from "./syncWriterPosition";
 export * from "./transferAdmin";

package/generated/instructions/repayPoolLoanFromWallet.ts

@@ -0,0 +1,483 @@
+/**
+ * This code was AUTOGENERATED using the Codama library.
+ * Please DO NOT EDIT THIS FILE, instead use visitors
+ * to add features, then rerun Codama to update it.
+ *
+ * @see https://github.com/codama-idl/codama
+ */
+
+import {
+  combineCodec,
+  fixDecoderSize,
+  fixEncoderSize,
+  getAddressEncoder,
+  getBytesDecoder,
+  getBytesEncoder,
+  getProgramDerivedAddress,
+  getStructDecoder,
+  getStructEncoder,
+  transformEncoder,
+  type AccountMeta,
+  type AccountSignerMeta,
+  type Address,
+  type FixedSizeCodec,
+  type FixedSizeDecoder,
+  type FixedSizeEncoder,
+  type Instruction,
+  type InstructionWithAccounts,
+  type InstructionWithData,
+  type ReadonlyAccount,
+  type ReadonlySignerAccount,
+  type ReadonlyUint8Array,
+  type TransactionSigner,
+  type WritableAccount,
+} from "@solana/kit";
+import { OPTION_PROGRAM_PROGRAM_ADDRESS } from "../programs";
+import {
+  expectAddress,
+  getAccountMetaFactory,
+  type ResolvedAccount,
+} from "../shared";
+
+export const REPAY_POOL_LOAN_FROM_WALLET_DISCRIMINATOR = new Uint8Array([
+  78, 130, 135, 90, 211, 21, 247, 247,
+]);
+
+export function getRepayPoolLoanFromWalletDiscriminatorBytes() {
+  return fixEncoderSize(getBytesEncoder(), 8).encode(
+    REPAY_POOL_LOAN_FROM_WALLET_DISCRIMINATOR,
+  );
+}
+
+export type RepayPoolLoanFromWalletInstruction<
+  TProgram extends string = typeof OPTION_PROGRAM_PROGRAM_ADDRESS,
+  TAccountPoolLoan extends string | AccountMeta<string> = string,
+  TAccountVault extends string | AccountMeta<string> = string,
+  TAccountVaultTokenAccount extends string | AccountMeta<string> = string,
+  TAccountEscrowState extends string | AccountMeta<string> = string,
+  TAccountEscrowAuthority extends string | AccountMeta<string> = string,
+  TAccountEscrowTokenAccount extends string | AccountMeta<string> = string,
+  TAccountMakerTokenAccount extends string | AccountMeta<string> = string,
+  TAccountFeeWalletTokenAccount extends string | AccountMeta<string> = string,
+  TAccountMaker extends string | AccountMeta<string> = string,
+  TAccountTokenProgram extends string | AccountMeta<string> =
+    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+  TRemainingAccounts extends readonly AccountMeta<string>[] = [],
+> = Instruction<TProgram> &
+  InstructionWithData<ReadonlyUint8Array> &
+  InstructionWithAccounts<
+    [
+      TAccountPoolLoan extends string
+        ? WritableAccount<TAccountPoolLoan>
+        : TAccountPoolLoan,
+      TAccountVault extends string
+        ? WritableAccount<TAccountVault>
+        : TAccountVault,
+      TAccountVaultTokenAccount extends string
+        ? WritableAccount<TAccountVaultTokenAccount>
+        : TAccountVaultTokenAccount,
+      TAccountEscrowState extends string
+        ? ReadonlyAccount<TAccountEscrowState>
+        : TAccountEscrowState,
+      TAccountEscrowAuthority extends string
+        ? ReadonlyAccount<TAccountEscrowAuthority>
+        : TAccountEscrowAuthority,
+      TAccountEscrowTokenAccount extends string
+        ? WritableAccount<TAccountEscrowTokenAccount>
+        : TAccountEscrowTokenAccount,
+      TAccountMakerTokenAccount extends string
+        ? WritableAccount<TAccountMakerTokenAccount>
+        : TAccountMakerTokenAccount,
+      TAccountFeeWalletTokenAccount extends string
+        ? WritableAccount<TAccountFeeWalletTokenAccount>
+        : TAccountFeeWalletTokenAccount,
+      TAccountMaker extends string
+        ? ReadonlySignerAccount<TAccountMaker> &
+            AccountSignerMeta<TAccountMaker>
+        : TAccountMaker,
+      TAccountTokenProgram extends string
+        ? ReadonlyAccount<TAccountTokenProgram>
+        : TAccountTokenProgram,
+      ...TRemainingAccounts,
+    ]
+  >;
+
+export type RepayPoolLoanFromWalletInstructionData = {
+  discriminator: ReadonlyUint8Array;
+};
+
+export type RepayPoolLoanFromWalletInstructionDataArgs = {};
+
+export function getRepayPoolLoanFromWalletInstructionDataEncoder(): FixedSizeEncoder<RepayPoolLoanFromWalletInstructionDataArgs> {
+  return transformEncoder(
+    getStructEncoder([["discriminator", fixEncoderSize(getBytesEncoder(), 8)]]),
+    (value) => ({
+      ...value,
+      discriminator: REPAY_POOL_LOAN_FROM_WALLET_DISCRIMINATOR,
+    }),
+  );
+}
+
+export function getRepayPoolLoanFromWalletInstructionDataDecoder(): FixedSizeDecoder<RepayPoolLoanFromWalletInstructionData> {
+  return getStructDecoder([
+    ["discriminator", fixDecoderSize(getBytesDecoder(), 8)],
+  ]);
+}
+
+export function getRepayPoolLoanFromWalletInstructionDataCodec(): FixedSizeCodec<
+  RepayPoolLoanFromWalletInstructionDataArgs,
+  RepayPoolLoanFromWalletInstructionData
+> {
+  return combineCodec(
+    getRepayPoolLoanFromWalletInstructionDataEncoder(),
+    getRepayPoolLoanFromWalletInstructionDataDecoder(),
+  );
+}
+
+export type RepayPoolLoanFromWalletAsyncInput<
+  TAccountPoolLoan extends string = string,
+  TAccountVault extends string = string,
+  TAccountVaultTokenAccount extends string = string,
+  TAccountEscrowState extends string = string,
+  TAccountEscrowAuthority extends string = string,
+  TAccountEscrowTokenAccount extends string = string,
+  TAccountMakerTokenAccount extends string = string,
+  TAccountFeeWalletTokenAccount extends string = string,
+  TAccountMaker extends string = string,
+  TAccountTokenProgram extends string = string,
+> = {
+  poolLoan: Address<TAccountPoolLoan>;
+  vault: Address<TAccountVault>;
+  vaultTokenAccount: Address<TAccountVaultTokenAccount>;
+  escrowState: Address<TAccountEscrowState>;
+  escrowAuthority?: Address<TAccountEscrowAuthority>;
+  escrowTokenAccount: Address<TAccountEscrowTokenAccount>;
+  makerTokenAccount: Address<TAccountMakerTokenAccount>;
+  feeWalletTokenAccount: Address<TAccountFeeWalletTokenAccount>;
+  maker: TransactionSigner<TAccountMaker>;
+  tokenProgram?: Address<TAccountTokenProgram>;
+};
+
+export async function getRepayPoolLoanFromWalletInstructionAsync<
+  TAccountPoolLoan extends string,
+  TAccountVault extends string,
+  TAccountVaultTokenAccount extends string,
+  TAccountEscrowState extends string,
+  TAccountEscrowAuthority extends string,
+  TAccountEscrowTokenAccount extends string,
+  TAccountMakerTokenAccount extends string,
+  TAccountFeeWalletTokenAccount extends string,
+  TAccountMaker extends string,
+  TAccountTokenProgram extends string,
+  TProgramAddress extends Address = typeof OPTION_PROGRAM_PROGRAM_ADDRESS,
+>(
+  input: RepayPoolLoanFromWalletAsyncInput<
+    TAccountPoolLoan,
+    TAccountVault,
+    TAccountVaultTokenAccount,
+    TAccountEscrowState,
+    TAccountEscrowAuthority,
+    TAccountEscrowTokenAccount,
+    TAccountMakerTokenAccount,
+    TAccountFeeWalletTokenAccount,
+    TAccountMaker,
+    TAccountTokenProgram
+  >,
+  config?: { programAddress?: TProgramAddress },
+): Promise<
+  RepayPoolLoanFromWalletInstruction<
+    TProgramAddress,
+    TAccountPoolLoan,
+    TAccountVault,
+    TAccountVaultTokenAccount,
+    TAccountEscrowState,
+    TAccountEscrowAuthority,
+    TAccountEscrowTokenAccount,
+    TAccountMakerTokenAccount,
+    TAccountFeeWalletTokenAccount,
+    TAccountMaker,
+    TAccountTokenProgram
+  >
+> {
+  // Program address.
+  const programAddress =
+    config?.programAddress ?? OPTION_PROGRAM_PROGRAM_ADDRESS;
+
+  // Original accounts.
+  const originalAccounts = {
+    poolLoan: { value: input.poolLoan ?? null, isWritable: true },
+    vault: { value: input.vault ?? null, isWritable: true },
+    vaultTokenAccount: {
+      value: input.vaultTokenAccount ?? null,
+      isWritable: true,
+    },
+    escrowState: { value: input.escrowState ?? null, isWritable: false },
+    escrowAuthority: {
+      value: input.escrowAuthority ?? null,
+      isWritable: false,
+    },
+    escrowTokenAccount: {
+      value: input.escrowTokenAccount ?? null,
+      isWritable: true,
+    },
+    makerTokenAccount: {
+      value: input.makerTokenAccount ?? null,
+      isWritable: true,
+    },
+    feeWalletTokenAccount: {
+      value: input.feeWalletTokenAccount ?? null,
+      isWritable: true,
+    },
+    maker: { value: input.maker ?? null, isWritable: false },
+    tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
+  };
+  const accounts = originalAccounts as Record<
+    keyof typeof originalAccounts,
+    ResolvedAccount
+  >;
+
+  // Resolve default values.
+  if (!accounts.escrowAuthority.value) {
+    accounts.escrowAuthority.value = await getProgramDerivedAddress({
+      programAddress,
+      seeds: [
+        getBytesEncoder().encode(
+          new Uint8Array([
+            101, 115, 99, 114, 111, 119, 95, 97, 117, 116, 104, 111, 114, 105,
+            116, 121, 95, 118, 50,
+          ]),
+        ),
+        getAddressEncoder().encode(expectAddress(accounts.escrowState.value)),
+      ],
+    });
+  }
+  if (!accounts.tokenProgram.value) {
+    accounts.tokenProgram.value =
+      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" as Address<"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA">;
+  }
+
+  const getAccountMeta = getAccountMetaFactory(programAddress, "programId");
+  return Object.freeze({
+    accounts: [
+      getAccountMeta(accounts.poolLoan),
+      getAccountMeta(accounts.vault),
+      getAccountMeta(accounts.vaultTokenAccount),
+      getAccountMeta(accounts.escrowState),
+      getAccountMeta(accounts.escrowAuthority),
+      getAccountMeta(accounts.escrowTokenAccount),
+      getAccountMeta(accounts.makerTokenAccount),
+      getAccountMeta(accounts.feeWalletTokenAccount),
+      getAccountMeta(accounts.maker),
+      getAccountMeta(accounts.tokenProgram),
+    ],
+    data: getRepayPoolLoanFromWalletInstructionDataEncoder().encode({}),
+    programAddress,
+  } as RepayPoolLoanFromWalletInstruction<
+    TProgramAddress,
+    TAccountPoolLoan,
+    TAccountVault,
+    TAccountVaultTokenAccount,
+    TAccountEscrowState,
+    TAccountEscrowAuthority,
+    TAccountEscrowTokenAccount,
+    TAccountMakerTokenAccount,
+    TAccountFeeWalletTokenAccount,
+    TAccountMaker,
+    TAccountTokenProgram
+  >);
+}
+
+export type RepayPoolLoanFromWalletInput<
+  TAccountPoolLoan extends string = string,
+  TAccountVault extends string = string,
+  TAccountVaultTokenAccount extends string = string,
+  TAccountEscrowState extends string = string,
+  TAccountEscrowAuthority extends string = string,
+  TAccountEscrowTokenAccount extends string = string,
+  TAccountMakerTokenAccount extends string = string,
+  TAccountFeeWalletTokenAccount extends string = string,
+  TAccountMaker extends string = string,
+  TAccountTokenProgram extends string = string,
+> = {
+  poolLoan: Address<TAccountPoolLoan>;
+  vault: Address<TAccountVault>;
+  vaultTokenAccount: Address<TAccountVaultTokenAccount>;
+  escrowState: Address<TAccountEscrowState>;
+  escrowAuthority: Address<TAccountEscrowAuthority>;
+  escrowTokenAccount: Address<TAccountEscrowTokenAccount>;
+  makerTokenAccount: Address<TAccountMakerTokenAccount>;
+  feeWalletTokenAccount: Address<TAccountFeeWalletTokenAccount>;
+  maker: TransactionSigner<TAccountMaker>;
+  tokenProgram?: Address<TAccountTokenProgram>;
+};
+
+export function getRepayPoolLoanFromWalletInstruction<
+  TAccountPoolLoan extends string,
+  TAccountVault extends string,
+  TAccountVaultTokenAccount extends string,
+  TAccountEscrowState extends string,
+  TAccountEscrowAuthority extends string,
+  TAccountEscrowTokenAccount extends string,
+  TAccountMakerTokenAccount extends string,
+  TAccountFeeWalletTokenAccount extends string,
+  TAccountMaker extends string,
+  TAccountTokenProgram extends string,
+  TProgramAddress extends Address = typeof OPTION_PROGRAM_PROGRAM_ADDRESS,
+>(
+  input: RepayPoolLoanFromWalletInput<
+    TAccountPoolLoan,
+    TAccountVault,
+    TAccountVaultTokenAccount,
+    TAccountEscrowState,
+    TAccountEscrowAuthority,
+    TAccountEscrowTokenAccount,
+    TAccountMakerTokenAccount,
+    TAccountFeeWalletTokenAccount,
+    TAccountMaker,
+    TAccountTokenProgram
+  >,
+  config?: { programAddress?: TProgramAddress },
+): RepayPoolLoanFromWalletInstruction<
+  TProgramAddress,
+  TAccountPoolLoan,
+  TAccountVault,
+  TAccountVaultTokenAccount,
+  TAccountEscrowState,
+  TAccountEscrowAuthority,
+  TAccountEscrowTokenAccount,
+  TAccountMakerTokenAccount,
+  TAccountFeeWalletTokenAccount,
+  TAccountMaker,
+  TAccountTokenProgram
+> {
+  // Program address.
+  const programAddress =
+    config?.programAddress ?? OPTION_PROGRAM_PROGRAM_ADDRESS;
+
+  // Original accounts.
+  const originalAccounts = {
+    poolLoan: { value: input.poolLoan ?? null, isWritable: true },
+    vault: { value: input.vault ?? null, isWritable: true },
+    vaultTokenAccount: {
+      value: input.vaultTokenAccount ?? null,
+      isWritable: true,
+    },
+    escrowState: { value: input.escrowState ?? null, isWritable: false },
+    escrowAuthority: {
+      value: input.escrowAuthority ?? null,
+      isWritable: false,
+    },
+    escrowTokenAccount: {
+      value: input.escrowTokenAccount ?? null,
+      isWritable: true,
+    },
+    makerTokenAccount: {
+      value: input.makerTokenAccount ?? null,
+      isWritable: true,
+    },
+    feeWalletTokenAccount: {
+      value: input.feeWalletTokenAccount ?? null,
+      isWritable: true,
+    },
+    maker: { value: input.maker ?? null, isWritable: false },
+    tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
+  };
+  const accounts = originalAccounts as Record<
+    keyof typeof originalAccounts,
+    ResolvedAccount
+  >;
+
+  // Resolve default values.
+  if (!accounts.tokenProgram.value) {
+    accounts.tokenProgram.value =
+      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" as Address<"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA">;
+  }
+
+  const getAccountMeta = getAccountMetaFactory(programAddress, "programId");
+  return Object.freeze({
+    accounts: [
+      getAccountMeta(accounts.poolLoan),
+      getAccountMeta(accounts.vault),
+      getAccountMeta(accounts.vaultTokenAccount),
+      getAccountMeta(accounts.escrowState),
+      getAccountMeta(accounts.escrowAuthority),
+      getAccountMeta(accounts.escrowTokenAccount),
+      getAccountMeta(accounts.makerTokenAccount),
+      getAccountMeta(accounts.feeWalletTokenAccount),
+      getAccountMeta(accounts.maker),
+      getAccountMeta(accounts.tokenProgram),
+    ],
+    data: getRepayPoolLoanFromWalletInstructionDataEncoder().encode({}),
+    programAddress,
+  } as RepayPoolLoanFromWalletInstruction<
+    TProgramAddress,
+    TAccountPoolLoan,
+    TAccountVault,
+    TAccountVaultTokenAccount,
+    TAccountEscrowState,
+    TAccountEscrowAuthority,
+    TAccountEscrowTokenAccount,
+    TAccountMakerTokenAccount,
+    TAccountFeeWalletTokenAccount,
+    TAccountMaker,
+    TAccountTokenProgram
+  >);
+}
+
+export type ParsedRepayPoolLoanFromWalletInstruction<
+  TProgram extends string = typeof OPTION_PROGRAM_PROGRAM_ADDRESS,
+  TAccountMetas extends readonly AccountMeta[] = readonly AccountMeta[],
+> = {
+  programAddress: Address<TProgram>;
+  accounts: {
+    poolLoan: TAccountMetas[0];
+    vault: TAccountMetas[1];
+    vaultTokenAccount: TAccountMetas[2];
+    escrowState: TAccountMetas[3];
+    escrowAuthority: TAccountMetas[4];
+    escrowTokenAccount: TAccountMetas[5];
+    makerTokenAccount: TAccountMetas[6];
+    feeWalletTokenAccount: TAccountMetas[7];
+    maker: TAccountMetas[8];
+    tokenProgram: TAccountMetas[9];
+  };
+  data: RepayPoolLoanFromWalletInstructionData;
+};
+
+export function parseRepayPoolLoanFromWalletInstruction<
+  TProgram extends string,
+  TAccountMetas extends readonly AccountMeta[],
+>(
+  instruction: Instruction<TProgram> &
+    InstructionWithAccounts<TAccountMetas> &
+    InstructionWithData<ReadonlyUint8Array>,
+): ParsedRepayPoolLoanFromWalletInstruction<TProgram, TAccountMetas> {
+  if (instruction.accounts.length < 10) {
+    // TODO: Coded error.
+    throw new Error("Not enough accounts");
+  }
+  let accountIndex = 0;
+  const getNextAccount = () => {
+    const accountMeta = (instruction.accounts as TAccountMetas)[accountIndex]!;
+    accountIndex += 1;
+    return accountMeta;
+  };
+  return {
+    programAddress: instruction.programAddress,
+    accounts: {
+      poolLoan: getNextAccount(),
+      vault: getNextAccount(),
+      vaultTokenAccount: getNextAccount(),
+      escrowState: getNextAccount(),
+      escrowAuthority: getNextAccount(),
+      escrowTokenAccount: getNextAccount(),
+      makerTokenAccount: getNextAccount(),
+      feeWalletTokenAccount: getNextAccount(),
+      maker: getNextAccount(),
+      tokenProgram: getNextAccount(),
+    },
+    data: getRepayPoolLoanFromWalletInstructionDataDecoder().decode(
+      instruction.data,
+    ),
+  };
+}

package/generated/instructions/unwindWriterUnsold.ts

@@ -63,6 +63,7 @@ export type UnwindWriterUnsoldInstruction<
   TAccountWriterShortAccount extends string | AccountMeta<string> = string,
   TAccountCollateralVault extends string | AccountMeta<string> = string,
   TAccountWriterCollateralAccount extends string | AccountMeta<string> = string,
+  TAccountOmlpVaultState extends string | AccountMeta<string> = string,
   TAccountOmlpVault extends string | AccountMeta<string> = string,
   TAccountFeeWallet extends string | AccountMeta<string> = string,
   TAccountWriter extends string | AccountMeta<string> = string,
@@ -105,6 +106,9 @@ export type UnwindWriterUnsoldInstruction<
       TAccountWriterCollateralAccount extends string
         ? WritableAccount<TAccountWriterCollateralAccount>
         : TAccountWriterCollateralAccount,
+      TAccountOmlpVaultState extends string
+        ? WritableAccount<TAccountOmlpVaultState>
+        : TAccountOmlpVaultState,
       TAccountOmlpVault extends string
         ? WritableAccount<TAccountOmlpVault>
         : TAccountOmlpVault,
@@ -175,6 +179,7 @@ export type UnwindWriterUnsoldAsyncInput<
   TAccountWriterShortAccount extends string = string,
   TAccountCollateralVault extends string = string,
   TAccountWriterCollateralAccount extends string = string,
+  TAccountOmlpVaultState extends string = string,
   TAccountOmlpVault extends string = string,
   TAccountFeeWallet extends string = string,
   TAccountWriter extends string = string,
@@ -201,6 +206,8 @@ export type UnwindWriterUnsoldAsyncInput<
   collateralVault: Address<TAccountCollateralVault>;
   /** Writer's underlying token account (receives returned collateral) */
   writerCollateralAccount: Address<TAccountWriterCollateralAccount>;
+  /** OMLP Vault state PDA (for total_loans, add_interest_to_index) - optional, required when repaying loans */
+  omlpVaultState?: Address<TAccountOmlpVaultState>;
   /** OMLP vault token account (receives loan repayments) - optional */
   omlpVault?: Address<TAccountOmlpVault>;
   /** Protocol fee wallet (receives protocol fees) - optional */
@@ -222,6 +229,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
   TAccountWriterShortAccount extends string,
   TAccountCollateralVault extends string,
   TAccountWriterCollateralAccount extends string,
+  TAccountOmlpVaultState extends string,
   TAccountOmlpVault extends string,
   TAccountFeeWallet extends string,
   TAccountWriter extends string,
@@ -240,6 +248,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
     TAccountWriterShortAccount,
     TAccountCollateralVault,
     TAccountWriterCollateralAccount,
+    TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
     TAccountWriter,
@@ -260,6 +269,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
     TAccountWriterShortAccount,
     TAccountCollateralVault,
     TAccountWriterCollateralAccount,
+    TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
     TAccountWriter,
@@ -292,6 +302,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
       value: input.writerCollateralAccount ?? null,
       isWritable: true,
     },
+    omlpVaultState: { value: input.omlpVaultState ?? null, isWritable: true },
     omlpVault: { value: input.omlpVault ?? null, isWritable: true },
     feeWallet: { value: input.feeWallet ?? null, isWritable: true },
     writer: { value: input.writer ?? null, isWritable: true },
@@ -358,6 +369,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
       getAccountMeta(accounts.writerShortAccount),
       getAccountMeta(accounts.collateralVault),
       getAccountMeta(accounts.writerCollateralAccount),
+      getAccountMeta(accounts.omlpVaultState),
       getAccountMeta(accounts.omlpVault),
       getAccountMeta(accounts.feeWallet),
       getAccountMeta(accounts.writer),
@@ -380,6 +392,7 @@ export async function getUnwindWriterUnsoldInstructionAsync<
     TAccountWriterShortAccount,
     TAccountCollateralVault,
     TAccountWriterCollateralAccount,
+    TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
     TAccountWriter,
@@ -399,6 +412,7 @@ export type UnwindWriterUnsoldInput<
   TAccountWriterShortAccount extends string = string,
   TAccountCollateralVault extends string = string,
   TAccountWriterCollateralAccount extends string = string,
+  TAccountOmlpVaultState extends string = string,
   TAccountOmlpVault extends string = string,
   TAccountFeeWallet extends string = string,
   TAccountWriter extends string = string,
@@ -425,6 +439,8 @@ export type UnwindWriterUnsoldInput<
   collateralVault: Address<TAccountCollateralVault>;
   /** Writer's underlying token account (receives returned collateral) */
   writerCollateralAccount: Address<TAccountWriterCollateralAccount>;
+  /** OMLP Vault state PDA (for total_loans, add_interest_to_index) - optional, required when repaying loans */
+  omlpVaultState?: Address<TAccountOmlpVaultState>;
   /** OMLP vault token account (receives loan repayments) - optional */
   omlpVault?: Address<TAccountOmlpVault>;
   /** Protocol fee wallet (receives protocol fees) - optional */
@@ -446,6 +462,7 @@ export function getUnwindWriterUnsoldInstruction<
   TAccountWriterShortAccount extends string,
   TAccountCollateralVault extends string,
   TAccountWriterCollateralAccount extends string,
+  TAccountOmlpVaultState extends string,
   TAccountOmlpVault extends string,
   TAccountFeeWallet extends string,
   TAccountWriter extends string,
@@ -464,6 +481,7 @@ export function getUnwindWriterUnsoldInstruction<
     TAccountWriterShortAccount,
     TAccountCollateralVault,
     TAccountWriterCollateralAccount,
+    TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
     TAccountWriter,
@@ -483,6 +501,7 @@ export function getUnwindWriterUnsoldInstruction<
   TAccountWriterShortAccount,
   TAccountCollateralVault,
   TAccountWriterCollateralAccount,
+  TAccountOmlpVaultState,
   TAccountOmlpVault,
   TAccountFeeWallet,
   TAccountWriter,
@@ -514,6 +533,7 @@ export function getUnwindWriterUnsoldInstruction<
       value: input.writerCollateralAccount ?? null,
       isWritable: true,
     },
+    omlpVaultState: { value: input.omlpVaultState ?? null, isWritable: true },
     omlpVault: { value: input.omlpVault ?? null, isWritable: true },
     feeWallet: { value: input.feeWallet ?? null, isWritable: true },
     writer: { value: input.writer ?? null, isWritable: true },
@@ -551,6 +571,7 @@ export function getUnwindWriterUnsoldInstruction<
       getAccountMeta(accounts.writerShortAccount),
       getAccountMeta(accounts.collateralVault),
       getAccountMeta(accounts.writerCollateralAccount),
+      getAccountMeta(accounts.omlpVaultState),
       getAccountMeta(accounts.omlpVault),
       getAccountMeta(accounts.feeWallet),
       getAccountMeta(accounts.writer),
@@ -573,6 +594,7 @@ export function getUnwindWriterUnsoldInstruction<
     TAccountWriterShortAccount,
     TAccountCollateralVault,
     TAccountWriterCollateralAccount,
+    TAccountOmlpVaultState,
     TAccountOmlpVault,
     TAccountFeeWallet,
     TAccountWriter,
@@ -607,13 +629,15 @@ export type ParsedUnwindWriterUnsoldInstruction<
     collateralVault: TAccountMetas[8];
     /** Writer's underlying token account (receives returned collateral) */
     writerCollateralAccount: TAccountMetas[9];
+    /** OMLP Vault state PDA (for total_loans, add_interest_to_index) - optional, required when repaying loans */
+    omlpVaultState?: TAccountMetas[10] | undefined;
     /** OMLP vault token account (receives loan repayments) - optional */
-    omlpVault?: TAccountMetas[10] | undefined;
+    omlpVault?: TAccountMetas[11] | undefined;
     /** Protocol fee wallet (receives protocol fees) - optional */
-    feeWallet?: TAccountMetas[11] | undefined;
-    writer: TAccountMetas[12];
-    tokenProgram: TAccountMetas[13];
-    systemProgram: TAccountMetas[14];
+    feeWallet?: TAccountMetas[12] | undefined;
+    writer: TAccountMetas[13];
+    tokenProgram: TAccountMetas[14];
+    systemProgram: TAccountMetas[15];
   };
   data: UnwindWriterUnsoldInstructionData;
 };
@@ -626,7 +650,7 @@ export function parseUnwindWriterUnsoldInstruction<
     InstructionWithAccounts<TAccountMetas> &
     InstructionWithData<ReadonlyUint8Array>,
 ): ParsedUnwindWriterUnsoldInstruction<TProgram, TAccountMetas> {
-  if (instruction.accounts.length < 15) {
+  if (instruction.accounts.length < 16) {
     // TODO: Coded error.
     throw new Error("Not enough accounts");
   }
@@ -655,6 +679,7 @@ export function parseUnwindWriterUnsoldInstruction<
       writerShortAccount: getNextAccount(),
       collateralVault: getNextAccount(),
       writerCollateralAccount: getNextAccount(),
+      omlpVaultState: getNextOptionalAccount(),
       omlpVault: getNextOptionalAccount(),
       feeWallet: getNextOptionalAccount(),
       writer: getNextAccount(),

package/generated/programs/optionProgram.ts

@@ -41,6 +41,7 @@ import {
   parseOptionMintInstruction,
   parseOptionValidateInstruction,
   parseRepayPoolLoanFromCollateralInstruction,
+  parseRepayPoolLoanFromWalletInstruction,
   parseRepayPoolLoanInstruction,
   parseSettleMakerCollateralInstruction,
   parseSyncWriterPositionInstruction,
@@ -74,6 +75,7 @@ import {
   type ParsedOptionMintInstruction,
   type ParsedOptionValidateInstruction,
   type ParsedRepayPoolLoanFromCollateralInstruction,
+  type ParsedRepayPoolLoanFromWalletInstruction,
   type ParsedRepayPoolLoanInstruction,
   type ParsedSettleMakerCollateralInstruction,
   type ParsedSyncWriterPositionInstruction,
@@ -282,6 +284,7 @@ export enum OptionProgramInstruction {
   OptionValidate,
   RepayPoolLoan,
   RepayPoolLoanFromCollateral,
+  RepayPoolLoanFromWallet,
   SettleMakerCollateral,
   SyncWriterPosition,
   TransferAdmin,
@@ -571,6 +574,17 @@ export function identifyOptionProgramInstruction(
   ) {
     return OptionProgramInstruction.RepayPoolLoanFromCollateral;
   }
+  if (
+    containsBytes(
+      data,
+      fixEncoderSize(getBytesEncoder(), 8).encode(
+        new Uint8Array([78, 130, 135, 90, 211, 21, 247, 247]),
+      ),
+      0,
+    )
+  ) {
+    return OptionProgramInstruction.RepayPoolLoanFromWallet;
+  }
   if (
     containsBytes(
       data,
@@ -742,6 +756,9 @@ export type ParsedOptionProgramInstruction<
   | ({
       instructionType: OptionProgramInstruction.RepayPoolLoanFromCollateral;
     } & ParsedRepayPoolLoanFromCollateralInstruction<TProgram>)
+  | ({
+      instructionType: OptionProgramInstruction.RepayPoolLoanFromWallet;
+    } & ParsedRepayPoolLoanFromWalletInstruction<TProgram>)
   | ({
       instructionType: OptionProgramInstruction.SettleMakerCollateral;
     } & ParsedSettleMakerCollateralInstruction<TProgram>)
@@ -947,6 +964,13 @@ export function parseOptionProgramInstruction<TProgram extends string>(
         ...parseRepayPoolLoanFromCollateralInstruction(instruction),
       };
     }
+    case OptionProgramInstruction.RepayPoolLoanFromWallet: {
+      assertIsInstructionWithAccounts(instruction);
+      return {
+        instructionType: OptionProgramInstruction.RepayPoolLoanFromWallet,
+        ...parseRepayPoolLoanFromWalletInstruction(instruction),
+      };
+    }
     case OptionProgramInstruction.SettleMakerCollateral: {
       assertIsInstructionWithAccounts(instruction);
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.2.13",
+  "version": "0.3.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",
@@ -23,6 +23,9 @@
     "decimal.js": "^10.4.3"
   },
   "scripts": {
-    "typecheck": "tsc --project tsconfig.json --noEmit"
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "publish-beta": "dotenv -e .env -- pnpm publish --access public --tag beta",
+    "publish-alpha": "dotenv -e .env -- pnpm publish --access public --tag alpha",
+    "deprecate": "dotenv -e .env -- pnpm exec npm deprecate"
   }
 }

package/short/builders.ts

@@ -8,11 +8,14 @@ import {
 import type { Instruction } from "@solana/kit";
 import { toAddress } from "../client/program";
 import type { AddressLike, BuiltTransaction, KitRpc } from "../client/types";
+import { fetchVault } from "../accounts/fetchers";
+import { fetchPoolLoansByMaker } from "../accounts/list";
 import { resolveOptionAccounts } from "../accounts/resolve-option";
 import {
   deriveAssociatedTokenAddress,
   deriveMakerCollateralSharePda,
   deriveMetadataPda,
+  deriveVaultPda,
   deriveWriterPositionPda,
 } from "../accounts/pdas";
 import { assertNonNegativeAmount, assertPositiveAmount } from "../shared/amounts";
@@ -59,6 +62,9 @@ export interface BuildOptionMintParams {
   remainingAccounts?: RemainingAccountInput[];
 }
 
+/** Max PoolLoans per unwind to stay under 64-account tx limit (~18 named + ~20 loans) */
+const MAX_POOL_LOANS_PER_UNWIND = 20;
+
 export interface BuildUnwindWriterUnsoldParams {
   optionPool: AddressLike;
   optionAccount: AddressLike;
@@ -72,6 +78,7 @@ export interface BuildUnwindWriterUnsoldParams {
   unwindQty: bigint | number;
   collateralPool?: AddressLike;
   writerPosition?: AddressLike;
+  omlpVaultState?: AddressLike;
   omlpVault?: AddressLike;
   feeWallet?: AddressLike;
   remainingAccounts?: RemainingAccountInput[];
@@ -308,6 +315,7 @@ export async function buildUnwindWriterUnsoldInstruction(
     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,
@@ -333,11 +341,96 @@ export interface BuildUnwindWriterUnsoldTransactionWithDerivationParams {
   unwindQty: bigint | number;
   rpc: KitRpc;
   programId?: AddressLike;
+  omlpVaultState?: AddressLike;
   omlpVault?: AddressLike;
   feeWallet?: AddressLike;
+  /**
+   * When repaying pool loans: [PoolLoan₁, PoolLoan₂, ...] (all writable).
+   * omlpVaultState, omlpVault, feeWallet must also be passed.
+   * Prefer {@link buildUnwindWriterUnsoldWithLoanRepayment} to build this automatically.
+   */
   remainingAccounts?: RemainingAccountInput[];
 }
 
+export interface BuildUnwindWriterUnsoldWithLoanRepaymentParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  writer: AddressLike;
+  unwindQty: bigint | number;
+  rpc: KitRpc;
+  programId?: AddressLike;
+  /** Override when pool fetch is not used; otherwise resolved from option pool. */
+  underlyingMint?: AddressLike;
+}
+
+/**
+ * Builds an unwind_writer_unsold transaction that also repays any active pool loans
+ * for the option's underlying vault. When a writer unwinds an unsold short that had
+ * borrowed from OMLP, the program repays lenders from the collateral vault (burn,
+ * repay, then return collateral to writer) in one instruction.
+ *
+ * Passes omlpVaultState (Vault PDA), omlpVault, feeWallet as named accounts.
+ * remaining_accounts: [PoolLoan₁, PoolLoan₂, ...] only (capped at 20).
+ * If no active pool loans exist, still passes vault accounts so the API works for all unwinds.
+ */
+export async function buildUnwindWriterUnsoldWithLoanRepayment(
+  params: BuildUnwindWriterUnsoldWithLoanRepaymentParams
+): Promise<BuiltTransaction> {
+  const resolved = await resolveOptionAccounts({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId: params.programId,
+    rpc: params.rpc,
+  });
+
+  const underlyingMint = params.underlyingMint ?? resolved.underlyingMint;
+  invariant(
+    !!underlyingMint,
+    "underlyingMint is required; ensure rpc is provided and option pool is initialized, or pass underlyingMint."
+  );
+
+  const [vaultPda] = await deriveVaultPda(underlyingMint, params.programId);
+  const vaultPdaStr = toAddress(vaultPda);
+
+  const [loans, vault] = await Promise.all([
+    fetchPoolLoansByMaker(params.rpc, params.writer),
+    fetchVault(params.rpc, vaultPda),
+  ]);
+
+  const vaultLoans = loans
+    .filter((item) => toAddress(item.data.vault) === vaultPdaStr)
+    .slice(0, MAX_POOL_LOANS_PER_UNWIND);
+
+  const remainingAccounts: RemainingAccountInput[] = vaultLoans.map((item) => ({
+    address: item.address,
+    isWritable: true,
+  }));
+
+  const omlpVault = await deriveAssociatedTokenAddress(vaultPda, underlyingMint);
+  const feeWallet = vault
+    ? await deriveAssociatedTokenAddress(vault.feeWallet, underlyingMint)
+    : undefined;
+
+  return buildUnwindWriterUnsoldTransactionWithDerivation({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    writer: params.writer,
+    unwindQty: params.unwindQty,
+    rpc: params.rpc,
+    programId: params.programId,
+    omlpVaultState: vaultPda,
+    omlpVault,
+    feeWallet,
+    remainingAccounts,
+  });
+}
+
 export async function buildUnwindWriterUnsoldTransactionWithDerivation(
   params: BuildUnwindWriterUnsoldTransactionWithDerivationParams
 ): Promise<BuiltTransaction> {
@@ -375,6 +468,7 @@ export async function buildUnwindWriterUnsoldTransactionWithDerivation(
     unwindQty: params.unwindQty,
     collateralPool: resolved.collateralPool,
     writerPosition: writerPosition[0],
+    omlpVaultState: params.omlpVaultState,
     omlpVault: params.omlpVault,
     feeWallet: params.feeWallet,
     remainingAccounts: params.remainingAccounts,

package/short/pool.ts

@@ -2,6 +2,7 @@ import {
   getBorrowFromPoolInstructionAsync,
   getRepayPoolLoanInstructionAsync,
   getRepayPoolLoanFromCollateralInstructionAsync,
+  getRepayPoolLoanFromWalletInstructionAsync,
 } from "../generated/instructions";
 import type { Instruction } from "@solana/kit";
 import { toAddress } from "../client/program";
@@ -114,6 +115,39 @@ export async function buildRepayPoolLoanTransaction(
   return { instructions: [instruction] };
 }
 
+/**
+ * Repay a pool loan entirely from maker's wallet (no escrow used).
+ * Use when standard repay fails with InsufficientEscrowBalance (stuck loan).
+ */
+export async function buildRepayPoolLoanFromWalletInstruction(
+  params: BuildRepayPoolLoanParams
+): Promise<Instruction<string>> {
+  return getRepayPoolLoanFromWalletInstructionAsync({
+    poolLoan: toAddress(params.poolLoan),
+    vault: toAddress(params.vault),
+    vaultTokenAccount: toAddress(params.vaultTokenAccount),
+    escrowState: toAddress(params.escrowState),
+    escrowAuthority: params.escrowAuthority
+      ? toAddress(params.escrowAuthority)
+      : undefined,
+    escrowTokenAccount: toAddress(params.escrowTokenAccount),
+    makerTokenAccount: toAddress(params.makerTokenAccount),
+    feeWalletTokenAccount: toAddress(params.feeWalletTokenAccount),
+    maker: toAddress(params.maker) as any,
+    tokenProgram: params.tokenProgram ? toAddress(params.tokenProgram) : undefined,
+  });
+}
+
+/**
+ * Builds the repay-from-wallet transaction (stuck loan recovery).
+ */
+export async function buildRepayPoolLoanFromWalletTransaction(
+  params: BuildRepayPoolLoanParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildRepayPoolLoanFromWalletInstruction(params);
+  return { instructions: [instruction] };
+}
+
 export async function buildRepayPoolLoanFromCollateralInstruction(
   params: BuildRepayPoolLoanFromCollateralParams
 ): Promise<Instruction<string>> {