@epicentral/sos-sdk 0.9.0-beta

package/accounts/resolve-option.ts

@@ -0,0 +1,104 @@
+import type { Address } from "@solana/kit";
+import { OptionType } from "../generated/types";
+import { toAddress } from "../client/program";
+import type { AddressLike, KitRpc } from "../client/types";
+import {
+  deriveCollateralPoolPda,
+  deriveLongMintPda,
+  deriveMarketDataPda,
+  deriveMintAuthorityPda,
+  deriveOptionAccountPda,
+  deriveOptionPoolPda,
+  deriveShortMintPda,
+} from "./pdas";
+import { fetchCollateralPool, fetchOptionAccount, fetchOptionPool } from "./fetchers";
+
+export interface ResolveOptionAccountsParams {
+  underlyingAsset: AddressLike;
+  optionType: OptionType;
+  strikePrice: number;
+  expirationDate: bigint | number;
+  programId?: AddressLike;
+  rpc?: KitRpc;
+}
+
+export interface ResolvedOptionAccounts {
+  optionAccount: Address;
+  longMint: Address;
+  shortMint: Address;
+  optionPool: Address;
+  marketData: Address;
+  collateralPool: Address;
+  mintAuthority: Address;
+  underlyingMint?: Address;
+  escrowLongAccount?: Address;
+  premiumVault?: Address;
+  collateralVault?: Address;
+  optionPoolData?: Awaited<ReturnType<typeof fetchOptionPool>>;
+  optionAccountData?: Awaited<ReturnType<typeof fetchOptionAccount>>;
+  collateralPoolData?: Awaited<ReturnType<typeof fetchCollateralPool>>;
+}
+
+/**
+ * Resolves all derived and optionally fetched accounts for an option.
+ * Given option identity (underlyingAsset, optionType, strikePrice, expirationDate),
+ * returns PDAs and, when rpc is provided, fetches OptionPool and CollateralPool
+ * to expose escrowLongAccount, premiumVault, collateralVault, underlyingMint.
+ */
+export async function resolveOptionAccounts(
+  params: ResolveOptionAccountsParams
+): Promise<ResolvedOptionAccounts> {
+  const programId = params.programId;
+
+  const [optionAccount] = await deriveOptionAccountPda({
+    underlyingAsset: params.underlyingAsset,
+    optionType: params.optionType,
+    strikePrice: params.strikePrice,
+    expirationDate: params.expirationDate,
+    programId,
+  });
+
+  const [longMint] = await deriveLongMintPda(optionAccount, programId);
+  const [shortMint] = await deriveShortMintPda(optionAccount, programId);
+  const [optionPool] = await deriveOptionPoolPda(optionAccount, programId);
+  const [marketData] = await deriveMarketDataPda(params.underlyingAsset, programId);
+  const [collateralPool] = await deriveCollateralPoolPda(optionAccount, programId);
+  const [mintAuthority] = await deriveMintAuthorityPda(programId);
+
+  const result: ResolvedOptionAccounts = {
+    optionAccount,
+    longMint,
+    shortMint,
+    optionPool,
+    marketData,
+    collateralPool,
+    mintAuthority,
+  };
+
+  if (params.rpc) {
+    const [optionPoolFetched, optionAccountFetched, collateralPoolFetched] =
+      await Promise.all([
+        fetchOptionPool(params.rpc, optionPool),
+        fetchOptionAccount(params.rpc, optionAccount),
+        fetchCollateralPool(params.rpc, collateralPool),
+      ]);
+
+    if (optionPoolFetched) {
+      result.optionPoolData = optionPoolFetched;
+      result.escrowLongAccount = optionPoolFetched.escrowLongAccount;
+      result.premiumVault = optionPoolFetched.premiumVault;
+      result.underlyingMint = optionPoolFetched.underlyingMint;
+    }
+
+    if (optionAccountFetched) {
+      result.optionAccountData = optionAccountFetched;
+    }
+
+    if (collateralPoolFetched) {
+      result.collateralPoolData = collateralPoolFetched;
+      result.collateralVault = collateralPoolFetched.collateralVault;
+    }
+  }
+
+  return result;
+}

package/client/lookup-table.ts

@@ -0,0 +1,114 @@
+import { address, type Address } from "@solana/kit";
+import { fetchAddressLookupTable } from "@solana-program/address-lookup-table";
+import { PROGRAM_ID } from "./program";
+import type { KitRpc } from "./types";
+
+export const LOOKUP_TABLE_ADDRESSES: Record<"devnet" | "mainnet", Address | null> = {
+  devnet: address("9KB5MPdCHNNZ6MvjZv5JKqkzjyDMiFLcQonmQj3hAuee"),
+  mainnet: null,
+};
+
+export const LOOKUP_TABLE_ADDRESS: Address | null = LOOKUP_TABLE_ADDRESSES.devnet;
+
+export type LookupTableNetwork = "devnet" | "mainnet";
+
+export function detectNetwork(rpcUrl: string): LookupTableNetwork {
+  const lower = rpcUrl.toLowerCase();
+  return lower.includes("mainnet") ? "mainnet" : "devnet";
+}
+
+export function getLookupTableAddressForNetwork(
+  network: "devnet" | "mainnet"
+): Address | null {
+  return LOOKUP_TABLE_ADDRESSES[network];
+}
+
+export async function getLookupTableAccount(
+  rpc: KitRpc,
+  lookupTableAddress: Address | null
+): Promise<unknown | null> {
+  if (!lookupTableAddress) return null;
+  const rpcWithLookupTable = rpc as KitRpc & {
+    getAddressLookupTable: (address: Address) => { send: () => Promise<{ value: unknown | null }> };
+  };
+  const result = await rpcWithLookupTable.getAddressLookupTable(lookupTableAddress).send();
+  return result.value ?? null;
+}
+
+/** Result of verifying that a lookup table is correct for the current option program */
+export interface VerifyLookupTableResult {
+  /** True if the lookup table exists on-chain and contains the current program ID */
+  valid: boolean;
+  /** Whether the lookup table account was found on-chain */
+  foundOnChain: boolean;
+  /** Whether the Option Program ID is present in the table's addresses */
+  programIdInTable: boolean;
+  /** If valid is false, addresses that were required but missing from the table */
+  missingAddresses?: Address[];
+  /** Human-readable reason when valid is false */
+  reason?: string;
+}
+
+/**
+ * Verifies that the given lookup table is correct for the current Option Program.
+ * Ensures:
+ * 1. The lookup table exists on-chain
+ * 2. The table contains the current program ID (from client/program)
+ *
+ * Use this before sending transactions to avoid using a stale or wrong ALT.
+ *
+ * @param rpc - RPC client (must support getAddressLookupTable)
+ * @param lookupTableAddress - ALT address to verify (e.g. from getLookupTableAddressForNetwork)
+ * @param requiredAddresses - Optional extra addresses that must be in the table (e.g. key PDAs). PROGRAM_ID is always required.
+ * @returns Verification result with valid flag and details
+ */
+export async function verifyLookupTableForProgram(
+  rpc: KitRpc,
+  lookupTableAddress: Address | null,
+  requiredAddresses?: Address[]
+): Promise<VerifyLookupTableResult> {
+  if (!lookupTableAddress) {
+    return {
+      valid: false,
+      foundOnChain: false,
+      programIdInTable: false,
+      reason: "No lookup table address configured for this network",
+    };
+  }
+
+  let tableAddresses: Address[];
+  try {
+    const { data } = await fetchAddressLookupTable(rpc, lookupTableAddress);
+    tableAddresses = data.addresses as Address[];
+  } catch {
+    return {
+      valid: false,
+      foundOnChain: false,
+      programIdInTable: false,
+      reason: "Lookup table not found on-chain or RPC error",
+    };
+  }
+
+  const programIdStr = PROGRAM_ID;
+  const set = new Set(tableAddresses.map((a) => (typeof a === "string" ? a : String(a))));
+  const programIdInTable = set.has(programIdStr);
+
+  const required = requiredAddresses ?? [];
+  const allRequired = [programIdStr as Address, ...required];
+  const missingAddresses = allRequired.filter(
+    (addr) => !set.has(typeof addr === "string" ? addr : String(addr))
+  );
+
+  const valid = programIdInTable && missingAddresses.length === 0;
+
+  return {
+    valid,
+    foundOnChain: true,
+    programIdInTable,
+    ...(missingAddresses.length > 0 && { missingAddresses: missingAddresses as Address[] }),
+    ...(!valid &&
+      (!programIdInTable
+        ? { reason: "Lookup table does not contain the current Option Program ID" }
+        : { reason: `Lookup table is missing required addresses: ${missingAddresses.join(", ")}` })),
+  };
+}

package/client/program.ts

@@ -0,0 +1,13 @@
+import { address, type Address } from "@solana/kit";
+import { OPTION_PROGRAM_PROGRAM_ADDRESS } from "../generated/programs";
+import type { AddressLike } from "./types";
+
+export const PROGRAM_ADDRESS = OPTION_PROGRAM_PROGRAM_ADDRESS;
+export const PROGRAM_ID = address(OPTION_PROGRAM_PROGRAM_ADDRESS);
+export const getProgramId = (): Address => PROGRAM_ID;
+export const getProgramIdString = (): string => PROGRAM_ID;
+
+export function toAddress(value: AddressLike): Address {
+  return typeof value === "string" ? address(value) : value;
+}
+export { address };

package/client/types.ts

@@ -0,0 +1,9 @@
+import type { Address, Instruction, Rpc, SolanaRpcApi } from "@solana/kit";
+
+export type AddressLike = Address | string;
+export type KitRpc = Rpc<SolanaRpcApi>;
+
+export interface BuiltTransaction {
+  instructions: Instruction<string>[];
+  addressLookupTableAddresses?: AddressLike[];
+}

package/generated/accounts/collateralPool.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 {
+  assertAccountExists,
+  assertAccountsExist,
+  combineCodec,
+  decodeAccount,
+  fetchEncodedAccount,
+  fetchEncodedAccounts,
+  fixDecoderSize,
+  fixEncoderSize,
+  getAddressDecoder,
+  getAddressEncoder,
+  getBooleanDecoder,
+  getBooleanEncoder,
+  getBytesDecoder,
+  getBytesEncoder,
+  getI64Decoder,
+  getI64Encoder,
+  getStructDecoder,
+  getStructEncoder,
+  getU32Decoder,
+  getU32Encoder,
+  getU64Decoder,
+  getU64Encoder,
+  getU8Decoder,
+  getU8Encoder,
+  transformEncoder,
+  type Account,
+  type Address,
+  type EncodedAccount,
+  type FetchAccountConfig,
+  type FetchAccountsConfig,
+  type FixedSizeCodec,
+  type FixedSizeDecoder,
+  type FixedSizeEncoder,
+  type MaybeAccount,
+  type MaybeEncodedAccount,
+  type ReadonlyUint8Array,
+} from "@solana/kit";
+
+export const COLLATERAL_POOL_DISCRIMINATOR = new Uint8Array([
+  186, 4, 253, 240, 93, 243, 212, 195,
+]);
+
+export function getCollateralPoolDiscriminatorBytes() {
+  return fixEncoderSize(getBytesEncoder(), 8).encode(
+    COLLATERAL_POOL_DISCRIMINATOR,
+  );
+}
+
+export type CollateralPool = {
+  discriminator: ReadonlyUint8Array;
+  optionAccount: Address;
+  collateralMint: Address;
+  collateralVault: Address;
+  totalCollateral: bigint;
+  totalMakerContribution: bigint;
+  totalBorrowed: bigint;
+  totalInterestOwed: bigint;
+  totalExercisedValue: bigint;
+  totalLenderRepaid: bigint;
+  totalMakerReturned: bigint;
+  makerCount: number;
+  isExercised: boolean;
+  isFullySettled: boolean;
+  createdAt: bigint;
+  lastUpdated: bigint;
+  bump: number;
+};
+
+export type CollateralPoolArgs = {
+  optionAccount: Address;
+  collateralMint: Address;
+  collateralVault: Address;
+  totalCollateral: number | bigint;
+  totalMakerContribution: number | bigint;
+  totalBorrowed: number | bigint;
+  totalInterestOwed: number | bigint;
+  totalExercisedValue: number | bigint;
+  totalLenderRepaid: number | bigint;
+  totalMakerReturned: number | bigint;
+  makerCount: number;
+  isExercised: boolean;
+  isFullySettled: boolean;
+  createdAt: number | bigint;
+  lastUpdated: number | bigint;
+  bump: number;
+};
+
+/** Gets the encoder for {@link CollateralPoolArgs} account data. */
+export function getCollateralPoolEncoder(): FixedSizeEncoder<CollateralPoolArgs> {
+  return transformEncoder(
+    getStructEncoder([
+      ["discriminator", fixEncoderSize(getBytesEncoder(), 8)],
+      ["optionAccount", getAddressEncoder()],
+      ["collateralMint", getAddressEncoder()],
+      ["collateralVault", getAddressEncoder()],
+      ["totalCollateral", getU64Encoder()],
+      ["totalMakerContribution", getU64Encoder()],
+      ["totalBorrowed", getU64Encoder()],
+      ["totalInterestOwed", getU64Encoder()],
+      ["totalExercisedValue", getU64Encoder()],
+      ["totalLenderRepaid", getU64Encoder()],
+      ["totalMakerReturned", getU64Encoder()],
+      ["makerCount", getU32Encoder()],
+      ["isExercised", getBooleanEncoder()],
+      ["isFullySettled", getBooleanEncoder()],
+      ["createdAt", getI64Encoder()],
+      ["lastUpdated", getI64Encoder()],
+      ["bump", getU8Encoder()],
+    ]),
+    (value) => ({ ...value, discriminator: COLLATERAL_POOL_DISCRIMINATOR }),
+  );
+}
+
+/** Gets the decoder for {@link CollateralPool} account data. */
+export function getCollateralPoolDecoder(): FixedSizeDecoder<CollateralPool> {
+  return getStructDecoder([
+    ["discriminator", fixDecoderSize(getBytesDecoder(), 8)],
+    ["optionAccount", getAddressDecoder()],
+    ["collateralMint", getAddressDecoder()],
+    ["collateralVault", getAddressDecoder()],
+    ["totalCollateral", getU64Decoder()],
+    ["totalMakerContribution", getU64Decoder()],
+    ["totalBorrowed", getU64Decoder()],
+    ["totalInterestOwed", getU64Decoder()],
+    ["totalExercisedValue", getU64Decoder()],
+    ["totalLenderRepaid", getU64Decoder()],
+    ["totalMakerReturned", getU64Decoder()],
+    ["makerCount", getU32Decoder()],
+    ["isExercised", getBooleanDecoder()],
+    ["isFullySettled", getBooleanDecoder()],
+    ["createdAt", getI64Decoder()],
+    ["lastUpdated", getI64Decoder()],
+    ["bump", getU8Decoder()],
+  ]);
+}
+
+/** Gets the codec for {@link CollateralPool} account data. */
+export function getCollateralPoolCodec(): FixedSizeCodec<
+  CollateralPoolArgs,
+  CollateralPool
+> {
+  return combineCodec(getCollateralPoolEncoder(), getCollateralPoolDecoder());
+}
+
+export function decodeCollateralPool<TAddress extends string = string>(
+  encodedAccount: EncodedAccount<TAddress>,
+): Account<CollateralPool, TAddress>;
+export function decodeCollateralPool<TAddress extends string = string>(
+  encodedAccount: MaybeEncodedAccount<TAddress>,
+): MaybeAccount<CollateralPool, TAddress>;
+export function decodeCollateralPool<TAddress extends string = string>(
+  encodedAccount: EncodedAccount<TAddress> | MaybeEncodedAccount<TAddress>,
+): Account<CollateralPool, TAddress> | MaybeAccount<CollateralPool, TAddress> {
+  return decodeAccount(
+    encodedAccount as MaybeEncodedAccount<TAddress>,
+    getCollateralPoolDecoder(),
+  );
+}
+
+export async function fetchCollateralPool<TAddress extends string = string>(
+  rpc: Parameters<typeof fetchEncodedAccount>[0],
+  address: Address<TAddress>,
+  config?: FetchAccountConfig,
+): Promise<Account<CollateralPool, TAddress>> {
+  const maybeAccount = await fetchMaybeCollateralPool(rpc, address, config);
+  assertAccountExists(maybeAccount);
+  return maybeAccount;
+}
+
+export async function fetchMaybeCollateralPool<
+  TAddress extends string = string,
+>(
+  rpc: Parameters<typeof fetchEncodedAccount>[0],
+  address: Address<TAddress>,
+  config?: FetchAccountConfig,
+): Promise<MaybeAccount<CollateralPool, TAddress>> {
+  const maybeAccount = await fetchEncodedAccount(rpc, address, config);
+  return decodeCollateralPool(maybeAccount);
+}
+
+export async function fetchAllCollateralPool(
+  rpc: Parameters<typeof fetchEncodedAccounts>[0],
+  addresses: Array<Address>,
+  config?: FetchAccountsConfig,
+): Promise<Account<CollateralPool>[]> {
+  const maybeAccounts = await fetchAllMaybeCollateralPool(
+    rpc,
+    addresses,
+    config,
+  );
+  assertAccountsExist(maybeAccounts);
+  return maybeAccounts;
+}
+
+export async function fetchAllMaybeCollateralPool(
+  rpc: Parameters<typeof fetchEncodedAccounts>[0],
+  addresses: Array<Address>,
+  config?: FetchAccountsConfig,
+): Promise<MaybeAccount<CollateralPool>[]> {
+  const maybeAccounts = await fetchEncodedAccounts(rpc, addresses, config);
+  return maybeAccounts.map((maybeAccount) =>
+    decodeCollateralPool(maybeAccount),
+  );
+}
+
+export function getCollateralPoolSize(): number {
+  return 183;
+}

package/generated/accounts/config.ts

@@ -0,0 +1,156 @@
+/**
+ * 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 {
+  assertAccountExists,
+  assertAccountsExist,
+  combineCodec,
+  decodeAccount,
+  fetchEncodedAccount,
+  fetchEncodedAccounts,
+  fixDecoderSize,
+  fixEncoderSize,
+  getAddressDecoder,
+  getAddressEncoder,
+  getBytesDecoder,
+  getBytesEncoder,
+  getOptionDecoder,
+  getOptionEncoder,
+  getStructDecoder,
+  getStructEncoder,
+  getU8Decoder,
+  getU8Encoder,
+  transformEncoder,
+  type Account,
+  type Address,
+  type Codec,
+  type Decoder,
+  type EncodedAccount,
+  type Encoder,
+  type FetchAccountConfig,
+  type FetchAccountsConfig,
+  type MaybeAccount,
+  type MaybeEncodedAccount,
+  type Option,
+  type OptionOrNullable,
+  type ReadonlyUint8Array,
+} from "@solana/kit";
+
+export const CONFIG_DISCRIMINATOR = new Uint8Array([
+  155, 12, 170, 224, 30, 250, 204, 130,
+]);
+
+export function getConfigDiscriminatorBytes() {
+  return fixEncoderSize(getBytesEncoder(), 8).encode(CONFIG_DISCRIMINATOR);
+}
+
+export type Config = {
+  discriminator: ReadonlyUint8Array;
+  /** Current admin authority (governance multisig or hot wallet) */
+  admin: Address;
+  /** Optional pending admin for two-step transfer */
+  pendingAdmin: Option<Address>;
+  /** Protocol flags (reserved for future use: pausing, etc.) */
+  flags: number;
+  /** PDA bump */
+  bump: number;
+};
+
+export type ConfigArgs = {
+  /** Current admin authority (governance multisig or hot wallet) */
+  admin: Address;
+  /** Optional pending admin for two-step transfer */
+  pendingAdmin: OptionOrNullable<Address>;
+  /** Protocol flags (reserved for future use: pausing, etc.) */
+  flags: number;
+  /** PDA bump */
+  bump: number;
+};
+
+/** Gets the encoder for {@link ConfigArgs} account data. */
+export function getConfigEncoder(): Encoder<ConfigArgs> {
+  return transformEncoder(
+    getStructEncoder([
+      ["discriminator", fixEncoderSize(getBytesEncoder(), 8)],
+      ["admin", getAddressEncoder()],
+      ["pendingAdmin", getOptionEncoder(getAddressEncoder())],
+      ["flags", getU8Encoder()],
+      ["bump", getU8Encoder()],
+    ]),
+    (value) => ({ ...value, discriminator: CONFIG_DISCRIMINATOR }),
+  );
+}
+
+/** Gets the decoder for {@link Config} account data. */
+export function getConfigDecoder(): Decoder<Config> {
+  return getStructDecoder([
+    ["discriminator", fixDecoderSize(getBytesDecoder(), 8)],
+    ["admin", getAddressDecoder()],
+    ["pendingAdmin", getOptionDecoder(getAddressDecoder())],
+    ["flags", getU8Decoder()],
+    ["bump", getU8Decoder()],
+  ]);
+}
+
+/** Gets the codec for {@link Config} account data. */
+export function getConfigCodec(): Codec<ConfigArgs, Config> {
+  return combineCodec(getConfigEncoder(), getConfigDecoder());
+}
+
+export function decodeConfig<TAddress extends string = string>(
+  encodedAccount: EncodedAccount<TAddress>,
+): Account<Config, TAddress>;
+export function decodeConfig<TAddress extends string = string>(
+  encodedAccount: MaybeEncodedAccount<TAddress>,
+): MaybeAccount<Config, TAddress>;
+export function decodeConfig<TAddress extends string = string>(
+  encodedAccount: EncodedAccount<TAddress> | MaybeEncodedAccount<TAddress>,
+): Account<Config, TAddress> | MaybeAccount<Config, TAddress> {
+  return decodeAccount(
+    encodedAccount as MaybeEncodedAccount<TAddress>,
+    getConfigDecoder(),
+  );
+}
+
+export async function fetchConfig<TAddress extends string = string>(
+  rpc: Parameters<typeof fetchEncodedAccount>[0],
+  address: Address<TAddress>,
+  config?: FetchAccountConfig,
+): Promise<Account<Config, TAddress>> {
+  const maybeAccount = await fetchMaybeConfig(rpc, address, config);
+  assertAccountExists(maybeAccount);
+  return maybeAccount;
+}
+
+export async function fetchMaybeConfig<TAddress extends string = string>(
+  rpc: Parameters<typeof fetchEncodedAccount>[0],
+  address: Address<TAddress>,
+  config?: FetchAccountConfig,
+): Promise<MaybeAccount<Config, TAddress>> {
+  const maybeAccount = await fetchEncodedAccount(rpc, address, config);
+  return decodeConfig(maybeAccount);
+}
+
+export async function fetchAllConfig(
+  rpc: Parameters<typeof fetchEncodedAccounts>[0],
+  addresses: Array<Address>,
+  config?: FetchAccountsConfig,
+): Promise<Account<Config>[]> {
+  const maybeAccounts = await fetchAllMaybeConfig(rpc, addresses, config);
+  assertAccountsExist(maybeAccounts);
+  return maybeAccounts;
+}
+
+export async function fetchAllMaybeConfig(
+  rpc: Parameters<typeof fetchEncodedAccounts>[0],
+  addresses: Array<Address>,
+  config?: FetchAccountsConfig,
+): Promise<MaybeAccount<Config>[]> {
+  const maybeAccounts = await fetchEncodedAccounts(rpc, addresses, config);
+  return maybeAccounts.map((maybeAccount) => decodeConfig(maybeAccount));
+}