@epicentral/sos-sdk 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,239 @@
+# SDK (Frontend-First)
+
+This SDK is organized by feature and wraps the Codama-generated client for the `option_program`.
+It is Kit-native and uses `@solana/kit` types (`Address`, `Instruction`, `Rpc`) across the public API.
+The package entrypoint is `@epicentral/sos-sdk`.
+
+## Install
+
+```bash
+pnpm add @solana/kit decimal.js
+```
+
+In this repository, the SDK source lives at `epicentral/sos-sdk` and is packaged as
+`@epicentral/sos-sdk`.
+
+## Structure
+
+- `client/` shared program constants and address helpers for the option program.
+- `accounts/` PDA derivation and account fetch helpers.
+- `long/` LONG buy/close/exercise/quote builders.
+- `short/` SHORT mint/unwind/sync/settle plus premium/pool/loan builders.
+- `omlp/` lender deposit/withdraw instruction builders.
+- `shared/` common amount, error, and remaining account helpers.
+- `generated/` Codama-generated client (bundled; do not edit).
+
+## Updating the bundled client
+
+The SDK bundles the program client in `generated/`. From the **option-program** repo root:
+
+1. Regenerate the client: `yarn generate:client`.
+2. Sync into the SDK and copy to the standalone repo: `yarn sync:sdk`.
+
+Or run the full pipeline: `yarn generate:client:with-sdk`. The script copies the client into `epicentral/sos-sdk/generated` and then copies the entire SDK to the standalone repo (default `../sos-sdk`) so you can commit from there. Override the standalone path with `STANDALONE_SDK_PATH=/path/to/sos-sdk yarn sync:sdk`.
+
+## Usage model
+
+Each flow exposes:
+
+- `build*Instruction(params)` for single instruction composition.
+- `build*Transaction(params)` for one-flow `Instruction[]` construction.
+- optional domain services for multi-step flows (no send/confirm).
+
+## Core examples
+
+### Build + send (app-owned)
+
+```ts
+import {
+  appendTransactionMessageInstructions,
+  createTransactionMessage,
+  getSignatureFromTransaction,
+  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",
+});
+
+const signature = getSignatureFromTransaction(signedTx);
+```
+
+### Build + send (SDK helper)
+
+```ts
+import {
+  buildBuyFromPoolTransaction,
+  sendBuiltTransaction,
+} from "@epicentral/sos-sdk";
+
+const built = await buildBuyFromPoolTransaction(params);
+const signature = await sendBuiltTransaction({
+  rpc,
+  rpcSubscriptions,
+  feePayer: walletSigner,
+  instructions: built.instructions,
+});
+```
+
+### Open LONG / close LONG
+
+```ts
+import {
+  buildBuyFromPoolTransaction,
+  buildCloseLongToPoolTransaction,
+} from "@epicentral/sos-sdk";
+
+const openLong = await buildBuyFromPoolTransaction(openLongParams);
+const closeLong = await buildCloseLongToPoolTransaction(closeLongParams);
+```
+
+### Exercise LONG
+
+```ts
+import { buildOptionExerciseTransaction } from "@epicentral/sos-sdk";
+
+const exercise = buildOptionExerciseTransaction({
+  optionAccount,
+  positionAccount,
+  marketData,
+  underlyingMint,
+  priceUpdate,
+  buyerPaymentAccount,
+  makerCollateralAccount,
+  escrowState,
+  escrowTokenAccount,
+  escrowAuthority,
+  buyer,
+});
+```
+
+### Open SHORT (option mint)
+
+```ts
+import { buildOptionMintTransaction, OptionType } from "@epicentral/sos-sdk";
+
+const built = await buildOptionMintTransaction({
+  optionType: OptionType.Call,
+  strikePrice,
+  expirationDate,
+  quantity,
+  underlyingAsset,
+  underlyingSymbol,
+  makerCollateralAmount,
+  borrowedAmount,
+  maker,
+  makerCollateralAccount,
+  underlyingMint,
+});
+```
+
+### Unwind / Sync / Settle SHORT
+
+```ts
+import {
+  buildSettleMakerCollateralTransaction,
+  buildSyncWriterPositionTransaction,
+  buildUnwindWriterUnsoldTransaction,
+} from "@epicentral/sos-sdk";
+
+const unwind = await buildUnwindWriterUnsoldTransaction(unwindParams);
+const sync = buildSyncWriterPositionTransaction(syncParams);
+const settle = await buildSettleMakerCollateralTransaction(settleParams);
+```
+
+### Claim premium / close option
+
+```ts
+import {
+  buildClaimPremiumTransaction,
+  buildCloseOptionTransaction,
+} from "@epicentral/sos-sdk";
+
+const claim = await buildClaimPremiumTransaction({
+  optionPool,
+  makerPaymentAccount,
+  premiumVault,
+  maker,
+});
+
+const close = buildCloseOptionTransaction({
+  optionAccount,
+  optionMint,
+  makerOptionAccount,
+  maker,
+});
+```
+
+### Pool liquidity / borrow / repay
+
+```ts
+import {
+  buildBorrowFromPoolTransaction,
+  buildDepositToPoolTransaction,
+  buildRepayPoolLoanTransaction,
+  buildWithdrawFromPoolTransaction,
+} from "@epicentral/sos-sdk";
+
+const deposit = await buildDepositToPoolTransaction(depositToPoolParams);
+const withdraw = await buildWithdrawFromPoolTransaction(withdrawFromPoolParams);
+const borrow = await buildBorrowFromPoolTransaction(borrowFromPoolParams);
+const repay = await buildRepayPoolLoanTransaction(repayPoolLoanParams);
+```
+
+Repayment source behavior:
+
+- `buildRepayPoolLoanTransaction`: principal is repaid from `escrowTokenAccount`; accrued interest + protocol fees are repaid from `makerTokenAccount`.
+- `buildRepayPoolLoanFromCollateralTransaction`: full repayment is sourced from `collateralVault`.
+
+### OMLP deposit/withdraw
+
+```ts
+import {
+  buildDepositToPositionTransaction,
+  buildWithdrawFromPositionTransaction,
+} from "@epicentral/sos-sdk";
+
+const deposit = await buildDepositToPositionTransaction(
+  { vault, lenderTokenAccount, vaultTokenAccount, lender, amount }
+);
+
+const withdraw = await buildWithdrawFromPositionTransaction(
+  { vault, vaultTokenAccount, lenderTokenAccount, lender, amount }
+);
+```
+
+### Replace Anchor reads with SDK fetchers
+
+```ts
+import { fetchOptionAccount, fetchOptionPool, fetchVault } from "@epicentral/sos-sdk";
+
+const option = await fetchOptionAccount(rpc, optionAddress);
+const pool = await fetchOptionPool(rpc, optionPoolAddress);
+const vault = await fetchVault(rpc, vaultAddress);
+```
+
+## Migration notes
+
+- This SDK is the only frontend integration surface for this repository.
+- Legacy `frontend/constants`, `frontend/services`, and `frontend/utils` modules were removed.
+- Replace Anchor `program.account.*` reads with SDK fetchers.
+- Replace Anchor `program.methods.*` writes with SDK builders.
+- App code should own message building, signing, send, and confirmation via `@solana/kit`.
+- `long/service.ts` and `short/service.ts` were removed in favor of direct builder calls.

package/accounts/fetchers.ts

@@ -0,0 +1,140 @@
+import {
+  getCollateralPoolDecoder,
+  getLenderPositionDecoder,
+  getMakerPoolShareDecoder,
+  getMarketDataAccountDecoder,
+  getOptionAccountDecoder,
+  getOptionPoolDecoder,
+  getPoolLoanDecoder,
+  getPositionAccountDecoder,
+  getVaultDecoder,
+  getWriterPositionDecoder,
+  type CollateralPool,
+  type LenderPosition,
+  type MakerPoolShare,
+  type MarketDataAccount,
+  type OptionAccount,
+  type OptionPool,
+  type PoolLoan,
+  type PositionAccount,
+  type Vault,
+  type WriterPosition,
+} from "../generated/accounts";
+import type { Address } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike, KitRpc } from "../client/types";
+
+async function fetchRawAccount(
+  rpc: KitRpc,
+  address: AddressLike
+): Promise<Uint8Array | null> {
+  const response = await rpc.getAccountInfo(toAddress(address), { encoding: "base64" }).send();
+  const accountInfo = response.value;
+  if (!accountInfo) return null;
+  const [data] = accountInfo.data;
+  const binary = atob(data);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+async function decodeAccount<T>(
+  rpc: KitRpc,
+  address: AddressLike,
+  decoder: { decode: (value: Uint8Array) => T }
+): Promise<T | null> {
+  const data = await fetchRawAccount(rpc, address);
+  if (!data) return null;
+  return decoder.decode(data);
+}
+
+export async function fetchOptionAccount(
+  rpc: KitRpc,
+  optionAccount: AddressLike
+): Promise<OptionAccount | null> {
+  return decodeAccount(rpc, optionAccount, getOptionAccountDecoder());
+}
+
+export async function fetchOptionPool(
+  rpc: KitRpc,
+  optionPool: AddressLike
+): Promise<OptionPool | null> {
+  return decodeAccount(rpc, optionPool, getOptionPoolDecoder());
+}
+
+export async function fetchCollateralPool(
+  rpc: KitRpc,
+  collateralPool: AddressLike
+): Promise<CollateralPool | null> {
+  return decodeAccount(rpc, collateralPool, getCollateralPoolDecoder());
+}
+
+export async function fetchWriterPosition(
+  rpc: KitRpc,
+  writerPosition: AddressLike
+): Promise<WriterPosition | null> {
+  return decodeAccount(rpc, writerPosition, getWriterPositionDecoder());
+}
+
+export async function fetchLenderPosition(
+  rpc: KitRpc,
+  lenderPosition: AddressLike
+): Promise<LenderPosition | null> {
+  return decodeAccount(rpc, lenderPosition, getLenderPositionDecoder());
+}
+
+export async function fetchBuyerPosition(
+  rpc: KitRpc,
+  buyerPosition: AddressLike
+): Promise<PositionAccount | null> {
+  return decodeAccount(rpc, buyerPosition, getPositionAccountDecoder());
+}
+
+export async function fetchVault(
+  rpc: KitRpc,
+  vault: AddressLike
+): Promise<Vault | null> {
+  return decodeAccount(rpc, vault, getVaultDecoder());
+}
+
+export async function fetchMarketDataAccount(
+  rpc: KitRpc,
+  marketData: AddressLike
+): Promise<MarketDataAccount | null> {
+  return decodeAccount(rpc, marketData, getMarketDataAccountDecoder());
+}
+
+export async function fetchMakerPoolShare(
+  rpc: KitRpc,
+  makerPoolShare: AddressLike
+): Promise<MakerPoolShare | null> {
+  return decodeAccount(rpc, makerPoolShare, getMakerPoolShareDecoder());
+}
+
+export async function fetchPoolLoan(
+  rpc: KitRpc,
+  poolLoan: AddressLike
+): Promise<PoolLoan | null> {
+  return decodeAccount(rpc, poolLoan, getPoolLoanDecoder());
+}
+
+export async function accountExists(
+  rpc: KitRpc,
+  address: AddressLike
+): Promise<boolean> {
+  const response = await rpc.getAccountInfo(toAddress(address), { encoding: "base64" }).send();
+  return response.value !== null;
+}
+
+export async function fetchManyAccounts(
+  rpc: KitRpc,
+  addresses: AddressLike[]
+): Promise<Array<{ address: Address; exists: boolean }>> {
+  const keys = addresses.map((value) => toAddress(value));
+  const response = await rpc.getMultipleAccounts(keys, { encoding: "base64" }).send();
+  const infos = response.value;
+  return keys.map((key, index) => ({
+    address: key,
+    exists: infos[index] !== null,
+  }));
+}

package/accounts/list.ts

@@ -0,0 +1,152 @@
+import bs58 from "bs58";
+import type { Address } from "@solana/kit";
+import {
+  MAKER_POOL_SHARE_DISCRIMINATOR,
+  OPTION_POOL_DISCRIMINATOR,
+  POOL_LOAN_DISCRIMINATOR,
+  POSITION_ACCOUNT_DISCRIMINATOR,
+  VAULT_DISCRIMINATOR,
+  WRITER_POSITION_DISCRIMINATOR,
+  getMakerPoolShareDecoder,
+  getOptionPoolDecoder,
+  getPoolLoanDecoder,
+  getPositionAccountDecoder,
+  getVaultDecoder,
+  getWriterPositionDecoder,
+  type MakerPoolShare,
+  type OptionPool,
+  type PoolLoan,
+  type PositionAccount,
+  type Vault,
+  type WriterPosition,
+} from "../generated/accounts";
+import { PROGRAM_ID, toAddress } from "../client/program";
+import type { AddressLike, KitRpc } from "../client/types";
+
+const DISCRIMINATOR_OFFSET = 0n;
+const OWNER_OFFSET = 8n;
+const ACTIVE_POOL_LOAN_STATUS = 1;
+
+type ListedAccount<T> = {
+  address: Address;
+  data: T;
+};
+
+type ProgramAccountResponse = {
+  pubkey: Address;
+  account: {
+    data: [string, string];
+  };
+};
+
+function decodeBase64Data(data: string): Uint8Array {
+  const binary = atob(data);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function discriminatorFilter(discriminator: Uint8Array) {
+  return {
+    memcmp: {
+      offset: DISCRIMINATOR_OFFSET,
+      encoding: "base58",
+      bytes: bs58.encode(discriminator),
+    },
+  } as const;
+}
+
+function ownerFilter(owner: AddressLike) {
+  return {
+    memcmp: {
+      offset: OWNER_OFFSET,
+      encoding: "base58",
+      bytes: toAddress(owner),
+    },
+  } as const;
+}
+
+async function fetchAndDecodeProgramAccounts<T>(
+  rpc: KitRpc,
+  decoder: { decode: (value: Uint8Array) => T },
+  filters: ReadonlyArray<unknown>
+): Promise<Array<ListedAccount<T>>> {
+  const response = await rpc
+    .getProgramAccounts(PROGRAM_ID, {
+      encoding: "base64",
+      filters: filters as never,
+    })
+    .send();
+
+  const rawAccounts = Array.isArray(response)
+    ? (response as Array<ProgramAccountResponse>)
+    : (response as { value: Array<ProgramAccountResponse> }).value;
+
+  return rawAccounts.map(({ pubkey, account }) => {
+    const [base64Data] = account.data;
+    return {
+      address: pubkey,
+      data: decoder.decode(decodeBase64Data(base64Data)),
+    };
+  });
+}
+
+export async function fetchMakerPoolSharesByMaker(
+  rpc: KitRpc,
+  maker: AddressLike
+): Promise<Array<ListedAccount<MakerPoolShare>>> {
+  return fetchAndDecodeProgramAccounts(rpc, getMakerPoolShareDecoder(), [
+    discriminatorFilter(MAKER_POOL_SHARE_DISCRIMINATOR),
+    ownerFilter(maker),
+  ]);
+}
+
+export async function fetchWriterPositionsByWriter(
+  rpc: KitRpc,
+  writer: AddressLike
+): Promise<Array<ListedAccount<WriterPosition>>> {
+  return fetchAndDecodeProgramAccounts(rpc, getWriterPositionDecoder(), [
+    discriminatorFilter(WRITER_POSITION_DISCRIMINATOR),
+    ownerFilter(writer),
+  ]);
+}
+
+export async function fetchPositionAccountsByBuyer(
+  rpc: KitRpc,
+  buyer: AddressLike
+): Promise<Array<ListedAccount<PositionAccount>>> {
+  return fetchAndDecodeProgramAccounts(rpc, getPositionAccountDecoder(), [
+    discriminatorFilter(POSITION_ACCOUNT_DISCRIMINATOR),
+    ownerFilter(buyer),
+  ]);
+}
+
+export async function fetchPoolLoansByMaker(
+  rpc: KitRpc,
+  maker: AddressLike
+): Promise<Array<ListedAccount<PoolLoan>>> {
+  const decoded = await fetchAndDecodeProgramAccounts(rpc, getPoolLoanDecoder(), [
+    discriminatorFilter(POOL_LOAN_DISCRIMINATOR),
+    ownerFilter(maker),
+  ]);
+  return decoded.filter(
+    (item: { address: Address; data: PoolLoan }) =>
+      item.data.status === ACTIVE_POOL_LOAN_STATUS
+  );
+}
+
+export async function fetchAllOptionPools(
+  rpc: KitRpc
+): Promise<Array<ListedAccount<OptionPool>>> {
+  return fetchAndDecodeProgramAccounts(rpc, getOptionPoolDecoder(), [
+    discriminatorFilter(OPTION_POOL_DISCRIMINATOR),
+  ]);
+}
+
+export async function fetchAllVaults(
+  rpc: KitRpc
+): Promise<Array<ListedAccount<Vault>>> {
+  return fetchAndDecodeProgramAccounts(rpc, getVaultDecoder(), [
+    discriminatorFilter(VAULT_DISCRIMINATOR),
+  ]);
+}