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

package/README.md

@@ -1,177 +1,161 @@
 # @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). |
 
-// 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 borrowed amount must be repaid to the pool, not sent to the writer.
+
+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).
 
-### Pool
+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.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicentral/sos-sdk",
-  "version": "0.2.13",
+  "version": "0.3.0-alpha.1",
   "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";
@@ -335,9 +338,90 @@ export interface BuildUnwindWriterUnsoldTransactionWithDerivationParams {
   programId?: AddressLike;
   omlpVault?: AddressLike;
   feeWallet?: AddressLike;
+  /**
+   * When repaying pool loans: [Vault PDA, PoolLoan₁, PoolLoan₂, ...] (all writable).
+   * 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, borrowed funds are repaid to the pool (not sent to the writer).
+ *
+ * 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.
+ */
+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
+  );
+
+  const remainingAccounts: RemainingAccountInput[] = [
+    { address: vaultPda, isWritable: true },
+    ...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,
+    omlpVault,
+    feeWallet,
+    remainingAccounts,
+  });
+}
+
 export async function buildUnwindWriterUnsoldTransactionWithDerivation(
   params: BuildUnwindWriterUnsoldTransactionWithDerivationParams
 ): Promise<BuiltTransaction> {