@epicentral/sos-sdk 0.1.0

package/long/builders.ts

@@ -0,0 +1,126 @@
+import {
+  getBuyFromPoolInstructionAsync,
+  getCloseLongToPoolInstructionAsync,
+} from "../generated/instructions";
+import type { Instruction } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction } from "../client/types";
+import { assertPositiveAmount } from "../shared/amounts";
+import { invariant } from "../shared/errors";
+import {
+  appendRemainingAccounts,
+  type RemainingAccountInput,
+} from "../shared/remaining-accounts";
+
+export interface BuildBuyFromPoolParams {
+  optionPool: AddressLike;
+  optionAccount: AddressLike;
+  longMint: AddressLike;
+  underlyingMint: AddressLike;
+  marketData: AddressLike;
+  priceUpdate: AddressLike;
+  buyer: AddressLike;
+  buyerPaymentAccount: AddressLike;
+  escrowLongAccount: AddressLike;
+  premiumVault: AddressLike;
+  quantity: bigint | number;
+  premiumAmount: bigint | number;
+  buyerPosition?: AddressLike;
+  buyerOptionAccount?: AddressLike;
+  remainingAccounts?: RemainingAccountInput[];
+}
+
+export interface BuildCloseLongToPoolParams {
+  optionPool: AddressLike;
+  optionAccount: AddressLike;
+  collateralPool: AddressLike;
+  underlyingMint: AddressLike;
+  longMint: AddressLike;
+  escrowLongAccount: AddressLike;
+  premiumVault: AddressLike;
+  marketData: AddressLike;
+  priceUpdate: AddressLike;
+  buyer: AddressLike;
+  buyerLongAccount: AddressLike;
+  buyerPayoutAccount: AddressLike;
+  collateralVault: AddressLike;
+  quantity: bigint | number;
+  minPayoutAmount: bigint | number;
+  buyerPosition?: AddressLike;
+  omlpVault?: AddressLike;
+  remainingAccounts?: RemainingAccountInput[];
+}
+
+export async function buildBuyFromPoolInstruction(
+  params: BuildBuyFromPoolParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.quantity, "quantity");
+  assertPositiveAmount(params.premiumAmount, "premiumAmount");
+
+  const kitInstruction = await getBuyFromPoolInstructionAsync({
+    optionPool: toAddress(params.optionPool),
+    optionAccount: toAddress(params.optionAccount),
+    longMint: toAddress(params.longMint),
+    underlyingMint: toAddress(params.underlyingMint),
+    marketData: toAddress(params.marketData),
+    priceUpdate: toAddress(params.priceUpdate),
+    buyer: toAddress(params.buyer) as any,
+    buyerPosition: params.buyerPosition ? toAddress(params.buyerPosition) : undefined,
+    buyerOptionAccount: params.buyerOptionAccount
+      ? toAddress(params.buyerOptionAccount)
+      : undefined,
+    buyerPaymentAccount: toAddress(params.buyerPaymentAccount),
+    escrowLongAccount: toAddress(params.escrowLongAccount),
+    premiumVault: toAddress(params.premiumVault),
+    quantity: params.quantity,
+    premiumAmount: params.premiumAmount,
+  });
+
+  return appendRemainingAccounts(kitInstruction, params.remainingAccounts);
+}
+
+export async function buildBuyFromPoolTransaction(
+  params: BuildBuyFromPoolParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildBuyFromPoolInstruction(params);
+  return { instructions: [instruction] };
+}
+
+export async function buildCloseLongToPoolInstruction(
+  params: BuildCloseLongToPoolParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.quantity, "quantity");
+  invariant(
+    BigInt(params.minPayoutAmount) >= 0n,
+    "minPayoutAmount must be greater than or equal to zero."
+  );
+
+  const kitInstruction = await getCloseLongToPoolInstructionAsync({
+    optionPool: toAddress(params.optionPool),
+    optionAccount: toAddress(params.optionAccount),
+    collateralPool: toAddress(params.collateralPool),
+    underlyingMint: toAddress(params.underlyingMint),
+    longMint: toAddress(params.longMint),
+    escrowLongAccount: toAddress(params.escrowLongAccount),
+    premiumVault: toAddress(params.premiumVault),
+    marketData: toAddress(params.marketData),
+    priceUpdate: toAddress(params.priceUpdate),
+    buyer: toAddress(params.buyer) as any,
+    buyerLongAccount: toAddress(params.buyerLongAccount),
+    buyerPayoutAccount: toAddress(params.buyerPayoutAccount),
+    collateralVault: toAddress(params.collateralVault),
+    buyerPosition: params.buyerPosition ? toAddress(params.buyerPosition) : undefined,
+    omlpVault: params.omlpVault ? toAddress(params.omlpVault) : undefined,
+    quantity: params.quantity,
+    minPayoutAmount: params.minPayoutAmount,
+  });
+
+  return appendRemainingAccounts(kitInstruction, params.remainingAccounts);
+}
+
+export async function buildCloseLongToPoolTransaction(
+  params: BuildCloseLongToPoolParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildCloseLongToPoolInstruction(params);
+  return { instructions: [instruction] };
+}

package/long/exercise.ts

@@ -0,0 +1,49 @@
+import { getOptionExerciseInstruction } from "../generated/instructions";
+import type { Instruction } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction } from "../client/types";
+
+export interface BuildOptionExerciseParams {
+  optionAccount: AddressLike;
+  positionAccount: AddressLike;
+  marketData: AddressLike;
+  underlyingMint: AddressLike;
+  priceUpdate: AddressLike;
+  buyerPaymentAccount: AddressLike;
+  makerCollateralAccount: AddressLike;
+  escrowState: AddressLike;
+  escrowTokenAccount: AddressLike;
+  escrowAuthority: AddressLike;
+  buyer: AddressLike;
+  tokenProgram?: AddressLike;
+}
+
+export function buildOptionExerciseInstruction(
+  params: BuildOptionExerciseParams
+): Instruction<string> {
+  return getOptionExerciseInstruction({
+    optionAccount: toAddress(params.optionAccount),
+    positionAccount: toAddress(params.positionAccount),
+    marketData: toAddress(params.marketData),
+    underlyingMint: toAddress(params.underlyingMint),
+    priceUpdate: toAddress(params.priceUpdate),
+    buyerPaymentAccount: toAddress(params.buyerPaymentAccount),
+    makerCollateralAccount: toAddress(params.makerCollateralAccount),
+    escrowState: toAddress(params.escrowState),
+    escrowTokenAccount: toAddress(params.escrowTokenAccount),
+    escrowAuthority: toAddress(params.escrowAuthority),
+    buyer: toAddress(params.buyer) as any,
+    tokenProgram: params.tokenProgram ? toAddress(params.tokenProgram) : undefined,
+  });
+}
+
+/**
+ * Builds an option exercise transaction instruction set.
+ * Use `priceUpdate` from a fresh Pyth receiver update for accurate exercise pricing.
+ */
+export function buildOptionExerciseTransaction(
+  params: BuildOptionExerciseParams
+): BuiltTransaction {
+  const instruction = buildOptionExerciseInstruction(params);
+  return { instructions: [instruction] };
+}

package/long/quotes.ts

@@ -0,0 +1,48 @@
+import { assertPositiveAmount } from "../shared/amounts";
+import { SdkValidationError } from "../shared/errors";
+
+export function applySlippageBps(amount: bigint | number, slippageBps: number): bigint {
+  if (slippageBps < 0) {
+    throw new SdkValidationError("slippageBps cannot be negative.");
+  }
+
+  const base = BigInt(amount);
+  return (base * BigInt(10_000 + slippageBps)) / 10_000n;
+}
+
+export function applyMinSlippageBps(amount: bigint | number, slippageBps: number): bigint {
+  if (slippageBps < 0) {
+    throw new SdkValidationError("slippageBps cannot be negative.");
+  }
+
+  const base = BigInt(amount);
+  return (base * BigInt(10_000 - slippageBps)) / 10_000n;
+}
+
+export function buildBuyQuote(params: {
+  quantity: bigint | number;
+  premiumPerContract: bigint | number;
+  maxSlippageBps: number;
+}): { expectedPremium: bigint; maxPremium: bigint } {
+  assertPositiveAmount(params.quantity, "quantity");
+  assertPositiveAmount(params.premiumPerContract, "premiumPerContract");
+
+  const expectedPremium = BigInt(params.quantity) * BigInt(params.premiumPerContract);
+  return {
+    expectedPremium,
+    maxPremium: applySlippageBps(expectedPremium, params.maxSlippageBps),
+  };
+}
+
+export function buildCloseQuote(params: {
+  expectedPayout: bigint | number;
+  maxSlippageBps: number;
+}): { expectedPayout: bigint; minPayout: bigint } {
+  assertPositiveAmount(params.expectedPayout, "expectedPayout");
+
+  const expectedPayout = BigInt(params.expectedPayout);
+  return {
+    expectedPayout,
+    minPayout: applyMinSlippageBps(expectedPayout, params.maxSlippageBps),
+  };
+}

package/omlp/builders.ts

@@ -0,0 +1,74 @@
+import {
+  getDepositToPositionInstructionAsync,
+  getWithdrawFromPositionInstructionAsync,
+} from "../generated/instructions";
+import type { Instruction } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction } from "../client/types";
+import { assertPositiveAmount } from "../shared/amounts";
+
+export interface BuildDepositToPositionParams {
+  vault: AddressLike;
+  lenderTokenAccount: AddressLike;
+  vaultTokenAccount: AddressLike;
+  lender: AddressLike;
+  amount: bigint | number;
+  position?: AddressLike;
+}
+
+export interface BuildWithdrawFromPositionParams {
+  vault: AddressLike;
+  vaultTokenAccount: AddressLike;
+  lenderTokenAccount: AddressLike;
+  lender: AddressLike;
+  amount: bigint | number;
+  position?: AddressLike;
+}
+
+export async function buildDepositToPositionInstruction(
+  params: BuildDepositToPositionParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.amount, "amount");
+
+  const kitInstruction = await getDepositToPositionInstructionAsync({
+    position: params.position ? toAddress(params.position) : undefined,
+    vault: toAddress(params.vault),
+    lenderTokenAccount: toAddress(params.lenderTokenAccount),
+    vaultTokenAccount: toAddress(params.vaultTokenAccount),
+    lender: toAddress(params.lender) as any,
+    amount: params.amount,
+  });
+
+  return kitInstruction;
+}
+
+export async function buildDepositToPositionTransaction(
+  params: BuildDepositToPositionParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildDepositToPositionInstruction(params);
+  return { instructions: [instruction] };
+}
+
+export async function buildWithdrawFromPositionInstruction(
+  params: BuildWithdrawFromPositionParams
+): Promise<Instruction<string>> {
+  assertPositiveAmount(params.amount, "amount");
+
+  const kitInstruction = await getWithdrawFromPositionInstructionAsync({
+    position: params.position ? toAddress(params.position) : undefined,
+    vault: toAddress(params.vault),
+    vaultTokenAccount: toAddress(params.vaultTokenAccount),
+    lenderTokenAccount: toAddress(params.lenderTokenAccount),
+    lender: toAddress(params.lender) as any,
+    amount: params.amount,
+  });
+
+  return kitInstruction;
+}
+
+export async function buildWithdrawFromPositionTransaction(
+  params: BuildWithdrawFromPositionParams
+): Promise<BuiltTransaction> {
+  const instruction = await buildWithdrawFromPositionInstruction(params);
+  return { instructions: [instruction] };
+}

package/omlp/service.ts

@@ -0,0 +1,94 @@
+import { fetchLenderPosition, fetchVault } from "../accounts/fetchers";
+import type { KitRpc } from "../client/types";
+import {
+  buildDepositToPositionTransaction,
+  buildWithdrawFromPositionTransaction,
+  type BuildDepositToPositionParams,
+  type BuildWithdrawFromPositionParams,
+} from "./builders";
+
+function positiveDiff(a: bigint, b: bigint): bigint {
+  return a > b ? a - b : 0n;
+}
+
+export async function depositToPosition(
+  params: BuildDepositToPositionParams
+) {
+  return buildDepositToPositionTransaction(params);
+}
+
+export async function withdrawFromPosition(
+  params: BuildWithdrawFromPositionParams
+) {
+  return buildWithdrawFromPositionTransaction(params);
+}
+
+export async function withdrawAllFromPosition(
+  rpc: KitRpc,
+  params: Omit<BuildWithdrawFromPositionParams, "amount"> & {
+    position: NonNullable<BuildWithdrawFromPositionParams["position"]>;
+  }
+): Promise<{ instructions: Awaited<ReturnType<typeof buildWithdrawFromPositionTransaction>>["instructions"]; amount: bigint }> {
+  const [position, vault] = await Promise.all([
+    fetchLenderPosition(rpc, params.position),
+    fetchVault(rpc, params.vault),
+  ]);
+
+  if (!position) {
+    throw new Error("Lender position not found. Provide position PDA or deposit first.");
+  }
+  if (!vault) {
+    throw new Error("Vault account not found.");
+  }
+
+  const unclaimedInterest = positiveDiff(
+    position.totalInterestEarned,
+    position.interestClaimed
+  );
+  const userMax = position.deposited + unclaimedInterest;
+  const poolAvailable = positiveDiff(vault.totalLiquidity, vault.totalLoans);
+  const amount = userMax < poolAvailable ? userMax : poolAvailable;
+  if (amount <= 0n) {
+    throw new Error("No withdrawable balance available right now.");
+  }
+
+  const built = await buildWithdrawFromPositionTransaction({ ...params, amount });
+  return { instructions: built.instructions, amount };
+}
+
+export async function withdrawInterestFromPosition(
+  rpc: KitRpc,
+  params: Omit<BuildWithdrawFromPositionParams, "amount"> & {
+    position: NonNullable<BuildWithdrawFromPositionParams["position"]>;
+  }
+): Promise<{ instructions: Awaited<ReturnType<typeof buildWithdrawFromPositionTransaction>>["instructions"]; amount: bigint }> {
+  const [position, vault] = await Promise.all([
+    fetchLenderPosition(rpc, params.position),
+    fetchVault(rpc, params.vault),
+  ]);
+
+  if (!position) {
+    throw new Error("Lender position not found. Provide position PDA or deposit first.");
+  }
+  if (!vault) {
+    throw new Error("Vault account not found.");
+  }
+
+  const unclaimedInterest = positiveDiff(
+    position.totalInterestEarned,
+    position.interestClaimed
+  );
+  const poolAvailable = positiveDiff(vault.totalLiquidity, vault.totalLoans);
+  const amount = unclaimedInterest < poolAvailable ? unclaimedInterest : poolAvailable;
+  if (amount <= 0n) {
+    throw new Error("No claimable interest available right now.");
+  }
+
+  const built = await buildWithdrawFromPositionTransaction({ ...params, amount });
+  return { instructions: built.instructions, amount };
+}
+
+export const omlpBuilders = {
+  buildDepositToPositionTransaction,
+  buildWithdrawFromPositionTransaction,
+};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@epicentral/sos-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Solana Option Standard SDK. The frontend-first SDK for Native Options Trading on Solana. Created by Epicentral Labs.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./*": "./*"
+  },
+  "scripts": {
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@solana/kit": "^6.1.0",
+    "bs58": "^6.0.0",
+    "decimal.js": "^10.4.3"
+  }
+}

package/shared/amounts.ts

@@ -0,0 +1,32 @@
+import Decimal from "decimal.js";
+import { SdkValidationError } from "./errors";
+
+export function toBaseUnits(amount: Decimal.Value, decimals: number): bigint {
+  const scaled = new Decimal(amount).mul(new Decimal(10).pow(decimals));
+  return BigInt(scaled.floor().toFixed(0));
+}
+
+export function fromBaseUnits(amount: bigint | number, decimals: number): Decimal {
+  return new Decimal(amount.toString()).div(new Decimal(10).pow(decimals));
+}
+
+export function assertPositiveAmount(value: bigint | number, label: string): void {
+  const bigintValue = typeof value === "bigint" ? value : BigInt(value);
+  if (bigintValue <= 0n) {
+    throw new SdkValidationError(`${label} must be greater than zero.`);
+  }
+}
+
+export function assertNonNegativeAmount(value: bigint | number, label: string): void {
+  const bigintValue = typeof value === "bigint" ? value : BigInt(value);
+  if (bigintValue < 0n) {
+    throw new SdkValidationError(`${label} cannot be negative.`);
+  }
+}
+
+export function calculateRequiredCollateral(
+  quantity: bigint | number,
+  strikePrice: number
+): number {
+  return Number(quantity) * 100 * strikePrice;
+}

package/shared/errors.ts

@@ -0,0 +1,12 @@
+export class SdkValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SdkValidationError";
+  }
+}
+
+export function invariant(condition: boolean, message: string): asserts condition {
+  if (!condition) {
+    throw new SdkValidationError(message);
+  }
+}

package/shared/remaining-accounts.ts

@@ -0,0 +1,41 @@
+import { AccountRole, type AccountMeta, type Instruction } from "@solana/kit";
+import { toAddress } from "../client/program";
+import type { AddressLike } from "../client/types";
+
+export interface RemainingAccountInput {
+  address: AddressLike;
+  isWritable: boolean;
+  isSigner?: boolean;
+}
+
+function toAccountRole(input: RemainingAccountInput): AccountRole {
+  if (input.isWritable) {
+    return input.isSigner ? AccountRole.WRITABLE_SIGNER : AccountRole.WRITABLE;
+  }
+
+  return input.isSigner ? AccountRole.READONLY_SIGNER : AccountRole.READONLY;
+}
+
+export function appendRemainingAccounts(
+  instruction: Instruction<string>,
+  remainingAccounts: RemainingAccountInput[] | undefined
+): Instruction<string> {
+  if (!remainingAccounts?.length) {
+    return instruction;
+  }
+
+  const extras = remainingAccounts.map(
+    (account) =>
+      ({
+        address: toAddress(account.address),
+        role: toAccountRole(account),
+      }) as AccountMeta<string>
+  );
+
+  const existingAccounts = instruction.accounts ?? [];
+
+  return {
+    ...instruction,
+    accounts: [...existingAccounts, ...extras],
+  };
+}

package/shared/transactions.ts

@@ -0,0 +1,49 @@
+import {
+  appendTransactionMessageInstructions,
+  createTransactionMessage,
+  getSignatureFromTransaction,
+  pipe,
+  sendAndConfirmTransactionFactory,
+  setTransactionMessageFeePayerSigner,
+  setTransactionMessageLifetimeUsingBlockhash,
+  signTransactionMessageWithSigners,
+  type RpcSubscriptions,
+  type SolanaRpcSubscriptionsApi,
+  type TransactionSigner,
+} from "@solana/kit";
+import type { BuiltTransaction, KitRpc } from "../client/types";
+
+export interface SendBuiltTransactionParams extends BuiltTransaction {
+  rpc: KitRpc;
+  rpcSubscriptions: RpcSubscriptions<SolanaRpcSubscriptionsApi>;
+  feePayer: TransactionSigner<string>;
+  commitment?: "processed" | "confirmed" | "finalized";
+}
+
+/**
+ * Sends a built SDK transaction with common Solana Kit defaults.
+ * The caller still controls the RPC clients and fee-payer signer.
+ */
+export async function sendBuiltTransaction(
+  params: SendBuiltTransactionParams
+): Promise<string> {
+  const commitment = params.commitment ?? "confirmed";
+  const { value: latestBlockhash } = await params.rpc.getLatestBlockhash().send();
+
+  const txMessage = pipe(
+    createTransactionMessage({ version: 0 }),
+    (tx) => setTransactionMessageFeePayerSigner(params.feePayer, tx),
+    (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
+    (tx) => appendTransactionMessageInstructions(params.instructions, tx)
+  );
+
+  const signedTx = await signTransactionMessageWithSigners(txMessage);
+  const sendAndConfirm = sendAndConfirmTransactionFactory({
+    rpc: params.rpc,
+    rpcSubscriptions: params.rpcSubscriptions,
+  });
+  type SendableTransaction = Parameters<typeof sendAndConfirm>[0];
+
+  await sendAndConfirm(signedTx as SendableTransaction, { commitment });
+  return getSignatureFromTransaction(signedTx);
+}