@epicentral/sos-sdk 0.9.0-beta

package/omlp/service.ts

@@ -0,0 +1,136 @@
+/**
+ * OMLP (Option Maker Liquidity Pool) service – V2 pool-based API only.
+ * Exposes: depositToPosition, withdrawFromPosition, withdrawAllFromPosition, withdrawInterestFromPosition.
+ * Borrow/repay use short/pool (buildBorrowFromPool*, buildRepayPoolLoan*). Legacy offer-based instructions are not exposed.
+ */
+import { fetchLenderPosition, fetchVault } from "../accounts/fetchers";
+import type { KitRpc } from "../client/types";
+import {
+  buildDepositToPositionTransaction,
+  buildWithdrawFromPositionTransaction,
+  type BuildDepositToPositionParams,
+  type BuildWithdrawFromPositionParams,
+} from "./builders";
+
+const INTEREST_FP_SCALE = 1_000_000_000_000n;
+
+function positiveDiff(a: bigint, b: bigint): bigint {
+  return a > b ? a - b : 0n;
+}
+
+function calculatePendingInterest(
+  deposited: bigint,
+  vaultAccInterestPerShareFp: bigint,
+  positionInterestIndexSnapshotFp: bigint
+): bigint {
+  const deltaFp = positiveDiff(
+    vaultAccInterestPerShareFp,
+    positionInterestIndexSnapshotFp
+  );
+
+  return (deposited * deltaFp) / INTEREST_FP_SCALE;
+}
+
+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 pendingInterest = calculatePendingInterest(
+    position.deposited,
+    vault.accInterestPerShareFp,
+    position.interestIndexSnapshotFp
+  );
+  const userMax = position.deposited + unclaimedInterest + pendingInterest;
+  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,
+    vaultMint: vault.mint,
+  });
+  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 pendingInterest = calculatePendingInterest(
+    position.deposited,
+    vault.accInterestPerShareFp,
+    position.interestIndexSnapshotFp
+  );
+  const totalClaimableInterest = unclaimedInterest + pendingInterest;
+  const poolAvailable = positiveDiff(vault.totalLiquidity, vault.totalLoans);
+  const amount =
+    totalClaimableInterest < poolAvailable
+      ? totalClaimableInterest
+      : poolAvailable;
+  if (amount <= 0n) {
+    throw new Error("No claimable interest available right now.");
+  }
+
+  const built = await buildWithdrawFromPositionTransaction({
+    ...params,
+    amount,
+    vaultMint: vault.mint,
+  });
+  return { instructions: built.instructions, amount };
+}
+
+export const omlpBuilders = {
+  buildDepositToPositionTransaction,
+  buildWithdrawFromPositionTransaction,
+};

package/oracle/switchboard.ts

@@ -0,0 +1,315 @@
+import type { Address, Instruction } from "@solana/kit";
+import { fromLegacyTransactionInstruction } from "@solana/compat";
+import { CrossbarClient } from "@switchboard-xyz/common";
+import {
+  AnchorUtils,
+  ON_DEMAND_DEVNET_PID,
+  ON_DEMAND_MAINNET_PID,
+  Queue,
+} from "@switchboard-xyz/on-demand";
+import { Connection, type TransactionInstruction } from "@solana/web3.js";
+import bs58 from "bs58";
+import { toAddress } from "../client/program";
+import type { AddressLike, BuiltTransaction, KitRpc } from "../client/types";
+import { fetchMarketDataAccount } from "../accounts/fetchers";
+import { invariant } from "../shared/errors";
+
+const DEVNET_GENESIS_HASH = "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG";
+const MAINNET_BETA_GENESIS_HASH = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d";
+
+export type SwitchboardNetwork = "devnet" | "mainnet";
+
+export const SWITCHBOARD_DEFAULT_DEVNET_QUEUE =
+  "EYiAmGSdsQTuCw413V5BzaruWuCCSDgTPtBGvLkXHbe7";
+export const SWITCHBOARD_DEFAULT_MAINNET_QUEUE =
+  "A43DyUGA7s8eXPxqEjJY6EBu1KKbNgfxF8h17VAHn13w";
+export const SLOT_HASHES_SYSVAR_ADDRESS =
+  "SysvarS1otHashes111111111111111111111111111";
+export const INSTRUCTIONS_SYSVAR_ADDRESS =
+  "Sysvar1nstructions1111111111111111111111111";
+
+/**
+ * Default Switchboard on-demand queue for the cluster. Use as `switchboard_queue` on program
+ * instructions that verify the prepended quote ix — same defaults as Switchboard `Queue.loadDefault`,
+ * without threading `quote.queueAddress` from {@link buildSwitchboardQuoteInstruction}.
+ */
+export function getDefaultSwitchboardQueueAddress(
+  network: SwitchboardNetwork
+): Address {
+  return toAddress(
+    network === "mainnet"
+      ? SWITCHBOARD_DEFAULT_MAINNET_QUEUE
+      : SWITCHBOARD_DEFAULT_DEVNET_QUEUE
+  );
+}
+
+const KNOWN_FEED_ID_TO_ACCOUNT: Record<SwitchboardNetwork, Record<string, string>> = {
+  devnet: {
+    "0x822512ee9add93518eca1c105a38422841a76c590db079eebb283deb2c14caa9":
+      "EneYGtye2n7jkSwGvQtwBaY6VBhP2mbizHD2y7hNkGFC",
+    "0x883ea8295f70ae506e894679d124196bb07064ea530cefd835b58c33a5ab6549":
+      "DHB2Ph8CK7PmR3xswqcmDkgQeucnwSZtfnMpnc7mQgkb",
+  },
+  mainnet: {
+    "0x822512ee9add93518eca1c105a38422841a76c590db079eebb283deb2c14caa9":
+      "4Hmd6PdjVA9auCoScE12iaBogfwS4ZXQ6VZoBeqanwWW",
+    "0x883ea8295f70ae506e894679d124196bb07064ea530cefd835b58c33a5ab6549":
+      "GckHmCwSyYvYDTJax4hhTzGMykV5JmgKDSaFkcnWPeU4",
+  },
+};
+
+export async function resolveSwitchboardFeedFromMarketData(
+  rpc: KitRpc,
+  marketData: AddressLike
+): Promise<Address> {
+  const account = await fetchMarketDataAccount(rpc, marketData);
+  invariant(!!account, "Market data account not found.");
+  const feedBytes = Uint8Array.from(
+    account.switchboardFeedId as unknown as Uint8Array
+  );
+  const feedIdHex = feedIdBytesToHex(feedBytes).toLowerCase();
+  const network = await inferSwitchboardNetwork(rpc);
+  const mappedFeedAccount = KNOWN_FEED_ID_TO_ACCOUNT[network][feedIdHex];
+  if (mappedFeedAccount) {
+    return toAddress(mappedFeedAccount);
+  }
+
+  // Backward compatibility for environments still storing feed account pubkey bytes.
+  return toAddress(bs58.encode(Array.from(feedBytes)));
+}
+
+export function feedIdBytesToHex(feedIdBytes: Uint8Array): string {
+  return `0x${Buffer.from(feedIdBytes).toString("hex")}`;
+}
+
+export async function resolveSwitchboardFeedIdFromMarketData(
+  rpc: KitRpc,
+  marketData: AddressLike
+): Promise<string> {
+  const account = await fetchMarketDataAccount(rpc, marketData);
+  invariant(!!account, "Market data account not found.");
+  return feedIdBytesToHex(
+    Uint8Array.from(account.switchboardFeedId as unknown as Uint8Array)
+  );
+}
+
+export interface BuildSwitchboardQuoteInstructionParams {
+  rpcEndpoint: string;
+  feedIdHex: string;
+  network?: SwitchboardNetwork;
+  crossbarUrl?: string;
+  numSignatures?: number;
+  instructionIdx?: number;
+}
+
+export interface SwitchboardQuoteInstructionResult {
+  instruction: Instruction<string>;
+  queueAddress: AddressLike;
+}
+
+export async function buildSwitchboardQuoteInstruction(
+  params: BuildSwitchboardQuoteInstructionParams
+): Promise<SwitchboardQuoteInstructionResult> {
+  const network = params.network ?? "devnet";
+  const normalizedFeedId = params.feedIdHex.startsWith("0x")
+    ? params.feedIdHex
+    : `0x${params.feedIdHex}`;
+
+  const connection = new Connection(params.rpcEndpoint, "processed");
+  const programId =
+    network === "mainnet" ? ON_DEMAND_MAINNET_PID : ON_DEMAND_DEVNET_PID;
+  const program = await AnchorUtils.loadProgramFromConnection(
+    connection,
+    undefined,
+    programId
+  );
+  const queue = await Queue.loadDefault(program);
+
+  const crossbar = params.crossbarUrl
+    ? new CrossbarClient(params.crossbarUrl)
+    : CrossbarClient.default();
+  const quoteIx = await queue.fetchQuoteIx(crossbar, [normalizedFeedId], {
+    numSignatures: params.numSignatures,
+    instructionIdx: params.instructionIdx ?? 0,
+    variableOverrides: {},
+  });
+
+  return {
+    instruction: fromLegacyTransactionInstruction(quoteIx),
+    queueAddress: toAddress(queue.pubkey.toBase58()),
+  };
+}
+
+/** Same as {@link buildSwitchboardQuoteInstruction} but returns a legacy web3.js instruction (for Anchor/web3.js callers). */
+export async function buildSwitchboardQuoteWeb3JsInstruction(
+  params: BuildSwitchboardQuoteInstructionParams
+): Promise<{ instruction: TransactionInstruction; queueAddress: AddressLike }> {
+  const network = params.network ?? "devnet";
+  const normalizedFeedId = params.feedIdHex.startsWith("0x")
+    ? params.feedIdHex
+    : `0x${params.feedIdHex}`;
+
+  const connection = new Connection(params.rpcEndpoint, "processed");
+  const programId =
+    network === "mainnet" ? ON_DEMAND_MAINNET_PID : ON_DEMAND_DEVNET_PID;
+  const program = await AnchorUtils.loadProgramFromConnection(
+    connection,
+    undefined,
+    programId
+  );
+  const queue = await Queue.loadDefault(program);
+
+  const crossbar = params.crossbarUrl
+    ? new CrossbarClient(params.crossbarUrl)
+    : CrossbarClient.default();
+  const quoteIx = await queue.fetchQuoteIx(crossbar, [normalizedFeedId], {
+    numSignatures: params.numSignatures,
+    instructionIdx: params.instructionIdx ?? 0,
+    variableOverrides: {},
+  });
+
+  return {
+    instruction: quoteIx,
+    queueAddress: toAddress(queue.pubkey.toBase58()),
+  };
+}
+
+export interface SwitchboardPullFeedLike<TInstruction = unknown, TLookupTable = unknown> {
+  fetchUpdateIx(args: {
+    crossbarClient: unknown;
+    chain?: "solana";
+    network?: "devnet" | "mainnet";
+  }): Promise<[TInstruction | null, unknown, unknown, TLookupTable[]]>;
+}
+
+export interface BuildSwitchboardPullFeedUpdateParams<
+  TInstruction = unknown,
+  TLookupTable = unknown,
+> {
+  pullFeed: SwitchboardPullFeedLike<TInstruction, TLookupTable>;
+  crossbarClient: unknown;
+  chain?: "solana";
+  network?: "devnet" | "mainnet";
+}
+
+export async function buildSwitchboardPullFeedUpdate<
+  TInstruction = unknown,
+  TLookupTable = unknown,
+>(
+  params: BuildSwitchboardPullFeedUpdateParams<TInstruction, TLookupTable>
+): Promise<{ updateInstructions: TInstruction[]; lookupTables: TLookupTable[] }> {
+  const [pullIx, _responses, _success, luts] = await params.pullFeed.fetchUpdateIx({
+    crossbarClient: params.crossbarClient,
+    chain: params.chain ?? "solana",
+    network: params.network,
+  });
+
+  const updateInstructions: TInstruction[] = pullIx ? [pullIx] : [];
+  return {
+    updateInstructions,
+    lookupTables: luts ?? [],
+  };
+}
+
+export interface BuildSwitchboardCrankParams {
+  rpc: KitRpc;
+  payer: AddressLike;
+  switchboardFeed?: AddressLike;
+  marketData?: AddressLike;
+  network?: SwitchboardNetwork;
+  crossbarUrl?: string;
+  numSignatures?: number;
+}
+
+export interface SwitchboardCrankResult {
+  instructions: Instruction<string>[];
+  addressLookupTableAddresses: AddressLike[];
+}
+
+export async function inferSwitchboardNetwork(
+  rpc: KitRpc
+): Promise<SwitchboardNetwork> {
+  const genesisHash = await rpc.getGenesisHash().send();
+  if (genesisHash === DEVNET_GENESIS_HASH) {
+    return "devnet";
+  }
+  if (genesisHash === MAINNET_BETA_GENESIS_HASH) {
+    return "mainnet";
+  }
+  throw new Error(
+    `Unable to infer Switchboard network from genesis hash: ${genesisHash}`
+  );
+}
+
+export async function buildSwitchboardCrank(
+  params: BuildSwitchboardCrankParams
+): Promise<SwitchboardCrankResult> {
+  const resolvedFeed =
+    params.switchboardFeed ??
+    (params.marketData
+      ? await resolveSwitchboardFeedFromMarketData(params.rpc, params.marketData)
+      : undefined);
+
+  invariant(
+    !!resolvedFeed,
+    "switchboardFeed or marketData is required to build Switchboard crank instructions."
+  );
+
+  const network = params.network ?? (await inferSwitchboardNetwork(params.rpc));
+  const crossbar = params.crossbarUrl
+    ? new CrossbarClient(params.crossbarUrl)
+    : CrossbarClient.default();
+
+  try {
+    const updates = await crossbar.fetchSolanaUpdates(
+      network,
+      [toAddress(resolvedFeed)],
+      toAddress(params.payer),
+      params.numSignatures
+    );
+    const update = updates[0];
+
+    const instructions =
+      update?.pullIxns?.map((instruction) =>
+        fromLegacyTransactionInstruction(instruction)
+      ) ?? [];
+    const addressLookupTableAddresses = update?.lookupTables ?? [];
+
+    return {
+      instructions,
+      addressLookupTableAddresses,
+    };
+  } catch {
+    // Crossbar may return a non-array body or omit pullIxns; @switchboard-xyz/common then throws
+    // (e.g. undefined `.map`). Same outcome as disableSwitchboardCrank: submit the action without
+    // prepended pull-feed instructions.
+    return {
+      instructions: [],
+      addressLookupTableAddresses: [],
+    };
+  }
+}
+
+export function prependSwitchboardCrank(
+  crank: SwitchboardCrankResult,
+  action: BuiltTransaction
+): BuiltTransaction {
+  return {
+    instructions: [...crank.instructions, ...action.instructions],
+    addressLookupTableAddresses: [
+      ...(crank.addressLookupTableAddresses ?? []),
+      ...(action.addressLookupTableAddresses ?? []),
+    ],
+  };
+}
+
+/** Prepend a Switchboard quote ix at index 0 (required for verified_switchboard_quote_price on-chain). */
+export function prependSwitchboardQuote(
+  quote: SwitchboardQuoteInstructionResult,
+  action: BuiltTransaction
+): BuiltTransaction {
+  return {
+    instructions: [quote.instruction, ...action.instructions],
+    addressLookupTableAddresses: [...(action.addressLookupTableAddresses ?? [])],
+  };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@epicentral/sos-sdk",
+  "version": "0.9.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",
+  "sideEffects": false,
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./*": "./*"
+  },
+  "devDependencies": {
+    "dotenv-cli": "^8.0.0"
+  },
+  "dependencies": {
+    "@solana-program/address-lookup-table": "^0.11.0",
+    "@solana-program/compute-budget": "^0.13.0",
+    "@solana-program/system": "^0.11.0",
+    "@solana/compat": "^6.1.0",
+    "@solana/kit": "^6.1.0",
+    "@switchboard-xyz/common": "^5.7.0",
+    "@switchboard-xyz/on-demand": "^3.9.0",
+    "bs58": "^6.0.0",
+    "decimal.js": "^10.4.3"
+  },
+  "scripts": {
+    "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/shared/amounts.ts

@@ -0,0 +1,53 @@
+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.`);
+  }
+}
+
+/**
+ * Calculate required collateral for option position in token base units
+ * Matches on-chain formula: ((qty / 1_000_000) * 100 * strike) / spot * 10^decimals
+ * 
+ * @param quantity - Option quantity in base units (1 contract = 1_000_000)
+ * @param strikePrice - Strike price in USD
+ * @param spotPrice - Current spot price of underlying in USD (from oracle)
+ * @param tokenDecimals - Number of decimals for the underlying token (e.g., 9 for SOL)
+ * @returns Required collateral in token base units
+ */
+export function calculateRequiredCollateral(
+  quantity: bigint | number,
+  strikePrice: number,
+  spotPrice: number,
+  tokenDecimals: number
+): number {
+  // Convert base units to contract count
+  const contracts = Number(quantity) / 1_000_000;
+  const contractSize = 100; // 1 contract = 100 units of underlying
+  
+  // USD value needed for collateral
+  const usdRequired = contracts * contractSize * strikePrice;
+  
+  // Convert USD to token base units
+  const baseUnits = 10 ** tokenDecimals;
+  return (usdRequired / spotPrice) * baseUnits;
+}

package/shared/balances.ts

@@ -0,0 +1,57 @@
+import type { Address } from "@solana/kit";
+import { deriveAssociatedTokenAddress } from "../accounts/pdas";
+import { toAddress } from "../client/program";
+import type { AddressLike, KitRpc } from "../client/types";
+import { NATIVE_MINT } from "../wsol/instructions";
+
+/** SPL Token account data: amount field offset (u64 LE). */
+const TOKEN_ACCOUNT_AMOUNT_OFFSET = 64;
+
+function decodeTokenAccountAmount(data: Uint8Array): bigint {
+  if (data.length < TOKEN_ACCOUNT_AMOUNT_OFFSET + 8) return BigInt(0);
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return view.getBigUint64(TOKEN_ACCOUNT_AMOUNT_OFFSET, true);
+}
+
+async function fetchTokenAccountBalance(rpc: KitRpc, ata: Address): Promise<bigint> {
+  const response = await rpc.getAccountInfo(ata, { encoding: "base64" }).send();
+  const accountInfo = response.value;
+  if (!accountInfo) return BigInt(0);
+  const [b64] = accountInfo.data;
+  if (!b64) return BigInt(0);
+  const binary = atob(b64);
+  const data = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) data[i] = binary.charCodeAt(i);
+  return decodeTokenAccountAmount(data);
+}
+
+/**
+ * Returns the SPL token balance for an owner and mint in base units (smallest units).
+ * Derives the associated token account; returns 0n if the ATA does not exist or has no data.
+ */
+export async function getTokenBalance(
+  owner: AddressLike,
+  mint: AddressLike,
+  rpc: KitRpc
+): Promise<bigint> {
+  const ata = await deriveAssociatedTokenAddress(owner, mint);
+  return fetchTokenAccountBalance(rpc, ata);
+}
+
+/**
+ * Returns native SOL balance (lamports), wrapped SOL (WSOL) balance (base units), and total (native + wrapped).
+ * Use for SOL pools when the UI should show combined "total SOL".
+ */
+export async function getCombinedSOLBalance(
+  owner: AddressLike,
+  rpc: KitRpc
+): Promise<{ native: bigint; wrapped: bigint; total: bigint }> {
+  const ownerAddress = toAddress(owner);
+  const [nativeResponse, wrappedBalance] = await Promise.all([
+    rpc.getBalance(ownerAddress).send(),
+    getTokenBalance(ownerAddress, NATIVE_MINT, rpc),
+  ]);
+  const native = nativeResponse.value;
+  const total = native + wrappedBalance;
+  return { native, wrapped: wrappedBalance, total };
+}

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/trade-config.ts

@@ -0,0 +1,27 @@
+export interface TradeConfig {
+  slippageBps?: number;
+  computeUnitLimit?: number;
+  computeUnitPriceMicroLamports?: number;
+}
+
+let globalTradeConfig: TradeConfig = {};
+
+export function setGlobalTradeConfig(config: TradeConfig): void {
+  globalTradeConfig = { ...config };
+}
+
+export function updateGlobalTradeConfig(config: Partial<TradeConfig>): void {
+  globalTradeConfig = { ...globalTradeConfig, ...config };
+}
+
+export function getGlobalTradeConfig(): TradeConfig {
+  return { ...globalTradeConfig };
+}
+
+export function resetGlobalTradeConfig(): void {
+  globalTradeConfig = {};
+}
+
+export function resolveTradeConfig(overrides?: Partial<TradeConfig>): TradeConfig {
+  return { ...globalTradeConfig, ...overrides };
+}