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

package/README.md

@@ -64,6 +64,7 @@ Additional modules:
 | `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). |
 
 ### OMLP (Lending)
 
@@ -87,18 +88,20 @@ 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 borrowed amount must be repaid to the pool, not sent to the writer.
+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. `remaining_accounts` are built in the correct order: **[Vault PDA, PoolLoan₁, PoolLoan₂, ...]** (all writable).
-3. OMLP vault token account and fee wallet are resolved.
-4. One transaction both unwinds and repays the pool loan(s).
+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`.
 
-**Alternative (repay then unwind):** For flexibility, you can (1) build `repay_pool_loan_from_collateral` instructions via `buildRepayPoolLoanFromCollateralInstruction`, then (2) build `unwind_writer_unsold` without 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.
 
 ## Usage Examples
 

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.3.0-alpha.1",
+  "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",

package/short/builders.ts

@@ -62,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;
@@ -75,6 +78,7 @@ export interface BuildUnwindWriterUnsoldParams {
   unwindQty: bigint | number;
   collateralPool?: AddressLike;
   writerPosition?: AddressLike;
+  omlpVaultState?: AddressLike;
   omlpVault?: AddressLike;
   feeWallet?: AddressLike;
   remainingAccounts?: RemainingAccountInput[];
@@ -311,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,
@@ -336,10 +341,12 @@ export interface BuildUnwindWriterUnsoldTransactionWithDerivationParams {
   unwindQty: bigint | number;
   rpc: KitRpc;
   programId?: AddressLike;
+  omlpVaultState?: AddressLike;
   omlpVault?: AddressLike;
   feeWallet?: AddressLike;
   /**
-   * When repaying pool loans: [Vault PDA, PoolLoan₁, PoolLoan₂, ...] (all writable).
+   * When repaying pool loans: [PoolLoan₁, PoolLoan₂, ...] (all writable).
+   * omlpVaultState, omlpVault, feeWallet must also be passed.
    * Prefer {@link buildUnwindWriterUnsoldWithLoanRepayment} to build this automatically.
    */
   remainingAccounts?: RemainingAccountInput[];
@@ -361,11 +368,12 @@ export interface BuildUnwindWriterUnsoldWithLoanRepaymentParams {
 /**
  * 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, borrowed funds are repaid to the pool (not sent to the writer).
+ * borrowed from OMLP, the program repays lenders from the collateral vault (burn,
+ * repay, then return collateral to writer) in one instruction.
  *
- * remaining_accounts order: [Vault PDA, PoolLoan₁, PoolLoan₂, ...] (all writable).
- * If no active pool loans exist for this vault, still passes omlpVault and feeWallet
- * so the API can be used for all unwinds.
+ * 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
@@ -393,14 +401,14 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     fetchVault(params.rpc, vaultPda),
   ]);
 
-  const vaultLoans = loans.filter(
-    (item) => toAddress(item.data.vault) === vaultPdaStr
-  );
+  const vaultLoans = loans
+    .filter((item) => toAddress(item.data.vault) === vaultPdaStr)
+    .slice(0, MAX_POOL_LOANS_PER_UNWIND);
 
-  const remainingAccounts: RemainingAccountInput[] = [
-    { address: vaultPda, isWritable: true },
-    ...vaultLoans.map((item) => ({ address: item.address, isWritable: true })),
-  ];
+  const remainingAccounts: RemainingAccountInput[] = vaultLoans.map((item) => ({
+    address: item.address,
+    isWritable: true,
+  }));
 
   const omlpVault = await deriveAssociatedTokenAddress(vaultPda, underlyingMint);
   const feeWallet = vault
@@ -416,6 +424,7 @@ export async function buildUnwindWriterUnsoldWithLoanRepayment(
     unwindQty: params.unwindQty,
     rpc: params.rpc,
     programId: params.programId,
+    omlpVaultState: vaultPda,
     omlpVault,
     feeWallet,
     remainingAccounts,
@@ -459,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>> {