@epicentral/sos-sdk 0.10.5-beta → 0.11.0-beta

package/README.md

@@ -63,8 +63,12 @@ Additional modules:
 | `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` | Expiry Phase A: keeper-signed lender repayment and maker-share snapshot. Repays one active loan's principal + accrued interest to OMLP from collateral vault, and initializes the maker settlement share from `WriterPosition` when older mints do not yet have one. Writers with multiple loans for the expired option call it once per loan; maker residual is claimed separately. |
-| `getClaimMakerRemainingInstructionAsync` | Expiry Phase C generated instruction: returns remaining maker collateral after Phase B buyer payouts complete. |
+| `buildSettleMakerCollateralTransaction` | Expiry Phase A: keeper-signed lender repayment and maker-share snapshot. Repays one active loan's principal + accrued interest to OMLP from collateral vault, and initializes the maker settlement share from `WriterPosition` when older mints do not yet have one. Writers with multiple loans for the expired option call it once per loan; maker residual is prepared/claimed separately. |
+| `buildPrepareBuyerSettlementInstruction` | Expiry Phase B (prepare): keeper snapshots a buyer’s capped expiry claim into `BuyerSettlementClaim` PDAs; **does not** transfer to the buyer’s wallet (non-custodial OPX path). |
+| `buildClaimBuyerSettlementInstruction` | Expiry Phase B (claim): **buyer-signed** instruction that transfers the prepared payout from the collateral vault to the buyer’s ATA and closes the position. |
+| `buildPrepareMakerSettlementInstruction` | Expiry Phase C (prepare): keeper snapshots maker residual into `MakerSettlementClaim` after Phase B completes. |
+| `buildClaimMakerSettlementInstruction` | Expiry Phase C (claim): **maker-signed** instruction that transfers prepared residual collateral to the maker. |
+| `getClaimMakerRemainingInstructionAsync` | **Legacy** Phase C: direct vault → maker transfer in one keeper call (still on-chain). Prefer prepare/claim for user-controlled settlement. |
 | `buildCloseOptionTransaction` | Closes option token account. |
 | `buildClaimThetaTransaction` | Claims theta (time-decay share) for writer. |
 | `buildRepayPoolLoanFromCollateralInstruction` | Repays pool loan from collateral (short/pool). |
@@ -81,17 +85,17 @@ Additional modules:
   - No maker transaction signer is required by this instruction format.
   - On-chain repayment (`collateral_vault` -> `omlp_vault`) is signed by the `collateral_pool` PDA.
   - Lender repayment is sourced from collateral vault funds, not maker wallet funds.
-  - Expiry residual maker collateral is returned later by `claim_maker_remaining` after buyer payout Phase B.
+  - After Phase B, maker residual is returned via **prepare/claim** (`prepare_maker_settlement` → `claim_maker_settlement`) or the legacy **`claim_maker_remaining`** instruction.
 
 ### Expiry Settlement
 
-Expiry settlement is lender-first and split across three instructions:
+Expiry settlement is **lender-first**, then buyer phase, then maker phase. **OPX uses a non-custodial prepare/claim path:** keepers only **prepare** snapshots and phase progress; **users sign** claim transactions to receive tokens.
 
-1. `settle_maker_collateral` (Phase A) for every non-liquidated maker. Lender repayment is paid to the loan vault's ATA for the pool collateral mint, so devnet fake SOL/USDC pools and mainnet WSOL pools use the same mint-safe path. The keeper pays rent to create the maker settlement share if the writer was opened through `option_mint` before that share existed. If a writer has multiple active `PoolLoan` accounts for that expired option, keepers submit one Phase A transaction per loan; the maker share is not marked Phase A settled until all are repaid.
-2. `auto_exercise_expired` / `auto_exercise_all_expired` (Phase B) for buyers, capped by `eligible_maker_pot`; options with zero buyer positions are considered buyer-settled so maker claims do not stall. The single and batch paths take the collateral/settlement mint so cash-settled payouts use the correct token decimals; batch remaining accounts must pair each position with that buyer's token account for the same mint.
-3. `claim_maker_remaining` (Phase C) for makers after `phase_b_complete`, returning residual collateral in the pool collateral mint.
+1. **`settle_maker_collateral` (Phase A)** — For every non-liquidated maker: repay OMLP principal + interest from the collateral vault; snapshot `eligible_maker_pot` / `post_debt_collateral`. One transaction per active `PoolLoan` when a writer has multiple loans.
+2. **Phase B (buyers)** — **Recommended:** `prepare_buyer_settlement` (keeper, per position) records capped payouts on `BuyerSettlementClaim` and advances `phase_b_complete` when all buyer rows are processed; then **`claim_buyer_settlement` (buyer signer)** performs the vault → buyer ATA transfer. Payouts are capped by `eligible_maker_pot` with the same pro-rata scaling as before. **Legacy:** `auto_exercise_expired` / `auto_exercise_all_expired` still exist and can transfer directly from the vault to buyer ATAs in the same instruction when invoked (custodial keeper pattern).
+3. **Phase C (makers)** — **Recommended:** `prepare_maker_settlement` (keeper) then **`claim_maker_settlement` (maker signer)**. **Legacy:** `claim_maker_remaining` still performs a direct residual transfer when called.
 
-New program errors exposed in the IDL: `LenderRepaymentNotComplete`, `BuyerPayoutNotComplete`, and `MakerLiquidated`.
+New / related program errors include `LenderRepaymentNotComplete`, `BuyerPayoutNotComplete`, `MakerLiquidated`, and claim-state errors such as `SettlementClaimNotPrepared` / `SettlementClaimAlreadyClaimed` (see IDL).
 
 ### OMLP (Lending)
 

package/generated/programs/optionProgram.ts

@@ -14,10 +14,6 @@ import {
   type ReadonlyUint8Array,
 } from "@solana/kit";
 import {
-  parseBuyFromPoolInstruction,
-  parseCloseLongToPoolInstruction,
-  parseOptionMintInstruction,
-  parseUnwindWriterUnsoldInstruction,
   type ParsedAcceptAdminInstruction,
   type ParsedAutoExerciseAllExpiredInstruction,
   type ParsedAutoExerciseExpiredInstruction,
@@ -938,36 +934,3 @@ export type ParsedOptionProgramInstruction<
   | ({
       instructionType: OptionProgramInstruction.WriteToPool;
     } & ParsedWriteToPoolInstruction<TProgram>);
-
-
-export function parseOptionProgramInstruction<
-  TProgram extends string = "AVJa9h5aEZ5F4nwJGeoy4kmmiPy1pijrapEspZC5pRYg",
->(
-  instruction: Parameters<typeof parseBuyFromPoolInstruction>[0],
-): ParsedOptionProgramInstruction<TProgram> {
-  const instructionType = identifyOptionProgramInstruction(instruction);
-  switch (instructionType) {
-    case OptionProgramInstruction.BuyFromPool:
-      return {
-        instructionType,
-        ...parseBuyFromPoolInstruction(instruction),
-      } as ParsedOptionProgramInstruction<TProgram>;
-    case OptionProgramInstruction.CloseLongToPool:
-      return {
-        instructionType,
-        ...parseCloseLongToPoolInstruction(instruction),
-      } as ParsedOptionProgramInstruction<TProgram>;
-    case OptionProgramInstruction.OptionMint:
-      return {
-        instructionType,
-        ...parseOptionMintInstruction(instruction),
-      } as ParsedOptionProgramInstruction<TProgram>;
-    case OptionProgramInstruction.UnwindWriterUnsold:
-      return {
-        instructionType,
-        ...parseUnwindWriterUnsoldInstruction(instruction),
-      } as ParsedOptionProgramInstruction<TProgram>;
-    default:
-      throw new Error("Unsupported optionProgram instruction parser.");
-  }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.10.5-beta",
+  "version": "0.11.0-beta",
   "private": false,
   "description": "Solana Option Standard SDK. The frontend-first SDK for Native Options Trading on Solana. Created by Epicentral Labs.",
   "type": "module",