@coffer_so/sdk 1.0.0

package/src/clients/PoolFactoryClient.ts

@@ -0,0 +1,110 @@
+import { ComputeBudgetProgram, Keypair, PublicKey, TransactionInstruction } from "@solana/web3.js";
+import BN from "bn.js";
+import { CofferConfig } from "../config";
+import { SdkResult, err, ok } from "../types/result";
+import { BuiltTx, DeployPoolParams } from "../types/tx";
+import {
+  buildDeployPoolTx,
+  buildInitializeCubicPoolIx,
+  buildPoolInitializeConfigIx,
+} from "./tx-builders";
+import { derivePoolPda } from "../utils/pda";
+
+export interface PoolFactoryClientParams {
+  config: CofferConfig;
+}
+
+export interface InitializeConfigParams {
+  payer: PublicKey;
+  defaultProtocolFeeRate: number;
+}
+
+/**
+ * Builds transactions for protocol governance / pool deployment. Consumed
+ * by the deploy-pool UI flow and by the backend's admin tools.
+ */
+export class PoolFactoryClient {
+  readonly config: CofferConfig;
+
+  constructor(params: PoolFactoryClientParams) {
+    this.config = params.config;
+  }
+
+  /**
+   * Deploy a new pool atop an existing `CubicPoolConfig`. Caller is
+   * responsible for funding `params.payer` with enough SOL to cover rent
+   * for the pool account and the BPT mint PDA.
+   *
+   * Returns the `pool` and `bptMint` pubkeys it WILL create (derived PDAs)
+   * plus the signable tx.
+   */
+  buildDeployPoolTx(params: DeployPoolParams): SdkResult<BuiltTx & { pool: PublicKey; bptMint: PublicKey }> {
+    if (params.tokens.length < 2 || params.tokens.length > 10) {
+      return err("invalid_input", "tokens.length must be in [2, 10]");
+    }
+    if (params.tokens.length !== params.weightsBps.length) {
+      return err("invalid_input", "tokens/weightsBps length mismatch");
+    }
+    if (params.tokens.length !== params.virtualBalances.length) {
+      return err("invalid_input", "tokens/virtualBalances length mismatch");
+    }
+    const sum = params.weightsBps.reduce((a, b) => a + b, 0);
+    if (sum !== 10_000) return err("invalid_input", `weights must sum to 10000 (got ${sum})`);
+    for (const vb of params.virtualBalances) {
+      if (vb.isZero()) return err("invalid_input", "virtualBalances must all be > 0");
+    }
+
+    const [pool] = derivePoolPda(this.config.programs.cubicPool, params.configKey, params.poolId);
+    const [bptMint] = PublicKey.findProgramAddressSync(
+      [Buffer.from("bpt_mint"), pool.toBuffer()],
+      this.config.programs.cubicPool
+    );
+    try {
+      const tx = buildDeployPoolTx(this.config, params);
+      return ok({ ...tx, pool, bptMint });
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build deploy-pool tx", e);
+    }
+  }
+
+  /**
+   * Initialize a new `CubicPoolConfig`, through the protocol-admin wrapper.
+   *
+   * Routed via `protocol_admin::pool_initialize_config` rather than
+   * `cubic_pool::initialize_config` directly: post-audit the latter requires
+   * the Treasury PDA to SIGN (H-01), and a PDA signature can only come from
+   * the owning program's `invoke_signed`. Building the direct instruction
+   * yields a transaction no wallet can ever satisfy.
+   *
+   * `params.payer` must be the current `Treasury.admin` — it is the human
+   * signer the wrapper authenticates. The returned `configKeypair` is the
+   * second required signer (the config account is `init`, not a PDA).
+   */
+  buildInitializeConfigTx(params: InitializeConfigParams): SdkResult<
+    BuiltTx & { configKeypair: Keypair }
+  > {
+    try {
+      const configKeypair = Keypair.generate();
+      const ix = buildPoolInitializeConfigIx(this.config, {
+        config: configKeypair.publicKey,
+        admin: params.payer,
+        defaultProtocolFeeRate: params.defaultProtocolFeeRate,
+      });
+      return ok({
+        instructions: [ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }), ix],
+        suggestedCuLimit: 200_000,
+        configKeypair,
+      });
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build initialize_config tx", e);
+    }
+  }
+
+  /**
+   * Low-level: return the raw `initialize_cubic_pool` ix without a CU
+   * budget or wrapping. Useful for combining with other ixs in the same tx.
+   */
+  initializeCubicPoolIx(params: DeployPoolParams): TransactionInstruction {
+    return buildInitializeCubicPoolIx(this.config, params);
+  }
+}

package/src/clients/RpcClient.ts

@@ -0,0 +1,195 @@
+import { Commitment, Connection, PublicKey } from "@solana/web3.js";
+import { SdkResult } from "../types/result";
+import { RetryOptions } from "../utils/retry";
+import { err, ok } from "../types/result";
+import { toSdkError } from "../utils/errors";
+
+export interface RpcClientParams {
+  endpoint?: string;
+  /** Ordered endpoint list. If provided, it is used as-is. */
+  endpoints?: string[];
+  /** Extra endpoints appended after `endpoint`. Ignored when `endpoints` is set. */
+  fallbackEndpoints?: string[];
+  apiKey?: string;
+  commitment?: Commitment;
+  /** Optional headers (e.g. for Helius/Triton auth). */
+  headers?: Record<string, string>;
+  /** Per-endpoint timeout before the next RPC endpoint is tried. */
+  timeoutMs?: number;
+  /** Backoff schedule between endpoint attempts. Defaults to no delay. */
+  backoffMs?: number[];
+  /** Test hook for injecting lightweight fake connections. */
+  connectionFactory?: (endpoint: string) => Pick<
+    Connection,
+    "getAccountInfo" | "getMultipleAccountsInfo" | "getSlot"
+  >;
+}
+
+/**
+ * Thin wrapper around `@solana/web3.js` Connection with built-in retry +
+ * human-readable error mapping. Every public method returns a SdkResult<T>.
+ */
+export class RpcClient {
+  readonly endpoints: string[];
+  private readonly connections: Array<Pick<
+    Connection,
+    "getAccountInfo" | "getMultipleAccountsInfo" | "getSlot"
+  >>;
+  private readonly defaultCommitment: Commitment;
+  private readonly timeoutMs: number;
+  private readonly backoffMs: number[];
+  private activeEndpointIndex = 0;
+
+  constructor(params: RpcClientParams) {
+    this.defaultCommitment = params.commitment ?? "confirmed";
+    this.timeoutMs = params.timeoutMs ?? 2_000;
+    this.backoffMs = params.backoffMs ?? [];
+    this.endpoints = normalizeEndpoints(params);
+    if (this.endpoints.length === 0) {
+      throw new Error("RpcClient requires at least one endpoint");
+    }
+    this.connections = this.endpoints.map((endpoint) =>
+      params.connectionFactory
+        ? params.connectionFactory(endpoint)
+        : new Connection(endpoint, {
+            commitment: this.defaultCommitment,
+            httpHeaders: params.headers,
+          })
+    );
+  }
+
+  get connection(): Connection {
+    return this.connections[this.activeEndpointIndex] as Connection;
+  }
+
+  call<T>(
+    fn: (conn: Connection) => Promise<T>,
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<T>> {
+    return this.callWithFallback((conn) => fn(conn as Connection), retry);
+  }
+
+  getAccountInfo(
+    pk: PublicKey,
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<{ data: Buffer; owner: PublicKey; lamports: number } | null>> {
+    return this.callWithFallback(async (conn) => {
+      const info = await conn.getAccountInfo(pk, this.defaultCommitment);
+      if (!info) return null;
+      return {
+        data: info.data,
+        owner: info.owner,
+        lamports: info.lamports,
+      };
+    }, retry);
+  }
+
+  getMultipleAccountsInfo(
+    pks: PublicKey[],
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<(Buffer | null)[]>> {
+    return this.callWithFallback(async (conn) => {
+      const infos = await conn.getMultipleAccountsInfo(pks, this.defaultCommitment);
+      return infos.map((i) => (i ? i.data : null));
+    }, retry);
+  }
+
+  getMultipleAccountsWithInfo(
+    pks: PublicKey[],
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<({ data: Buffer; owner: PublicKey; lamports: number } | null)[]>> {
+    return this.callWithFallback(async (conn) => {
+      const infos = await conn.getMultipleAccountsInfo(pks, this.defaultCommitment);
+      return infos.map((i) => i ? { data: i.data, owner: i.owner, lamports: i.lamports } : null);
+    }, retry);
+  }
+
+  getSlot(retry: RetryOptions = {}): Promise<SdkResult<number>> {
+    return this.callWithFallback((conn) => conn.getSlot(this.defaultCommitment), retry);
+  }
+
+  private async callWithFallback<T>(
+    operation: (conn: Pick<Connection, "getAccountInfo" | "getMultipleAccountsInfo" | "getSlot">) => Promise<T>,
+    retry: RetryOptions = {}
+  ): Promise<SdkResult<T>> {
+    const attempts = Math.max(1, retry.attempts ?? this.connections.length);
+    const timeoutMs = retry.timeoutMs ?? this.timeoutMs;
+    const shouldRetry = retry.shouldRetry ?? defaultShouldRetry;
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt < attempts; attempt++) {
+      const endpointIndex = (this.activeEndpointIndex + attempt) % this.connections.length;
+      try {
+        const data = await withTimeout(operation(this.connections[endpointIndex]), timeoutMs);
+        this.activeEndpointIndex = endpointIndex;
+        return ok(data);
+      } catch (e) {
+        lastError = e;
+        if (!shouldRetry(e)) break;
+        if (attempt < attempts - 1) {
+          const delay = this.backoffMs[Math.min(attempt, this.backoffMs.length - 1)] ?? 0;
+          if (delay > 0) await sleep(delay);
+        }
+      }
+    }
+
+    const sdkError = toSdkError(lastError);
+    return err(sdkError.code, sdkError.humanMessage, lastError);
+  }
+}
+
+function normalizeEndpoints(params: RpcClientParams): string[] {
+  if (params.endpoints && params.endpoints.length > 0) {
+    return dedupe(params.endpoints);
+  }
+  const primary = params.endpoint
+    ? params.apiKey
+      ? appendApiKey(params.endpoint, params.apiKey)
+      : params.endpoint
+    : undefined;
+  return dedupe([primary, ...(params.fallbackEndpoints ?? [])].filter(Boolean) as string[]);
+}
+
+function dedupe(endpoints: string[]): string[] {
+  return Array.from(new Set(endpoints));
+}
+
+function defaultShouldRetry(e: unknown): boolean {
+  const sdkError = toSdkError(e);
+  return (
+    sdkError.code === "rpc_timeout" ||
+    sdkError.code === "rpc_unavailable" ||
+    sdkError.code === "rpc_rate_limited"
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const h = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    p.then(
+      (v) => {
+        clearTimeout(h);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(h);
+        reject(e);
+      }
+    );
+  });
+}
+
+function appendApiKey(endpoint: string, apiKey: string): string {
+  try {
+    const u = new URL(endpoint);
+    u.searchParams.set("api-key", apiKey);
+    return u.toString();
+  } catch {
+    const sep = endpoint.includes("?") ? "&" : "?";
+    return `${endpoint}${sep}api-key=${encodeURIComponent(apiKey)}`;
+  }
+}

package/src/clients/SingleTokenDepositClient.ts

@@ -0,0 +1,143 @@
+import { Commitment, PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+import { CofferConfig } from "../config";
+import { PoolInfo } from "../types/pool";
+import { SdkResult, err, ok } from "../types/result";
+import {
+  BuiltTx,
+  SingleTokenDepositParams,
+  SingleTokenDepositQuote,
+} from "../types/tx";
+import { deriveHelperPda } from "../utils/pda";
+import { buildSingleTokenDepositTx, buildSingleTokenDepositTxs } from "./tx-builders";
+import { RpcClient } from "./RpcClient";
+import { CubicPoolClient } from "./CubicPoolClient";
+import { describeUnsupportedToken } from "../utils/extensions";
+
+function unsupportedMessage(pool: PoolInfo, op: string): string {
+  return `${op} refused: ${(pool.unsupportedTokenIndices ?? []).filter(i => !pool.tokens[i].actualBalance.isZero()).map((i) => describeUnsupportedToken(pool.tokens[i])).join("; ")}. The cubic-pool program cannot transfer such tokens.`;
+}
+
+export interface SingleTokenDepositClientParams {
+  config: CofferConfig;
+  poolAddress: PublicKey;
+  /** Optional — reuses an existing one if provided. */
+  rpc?: RpcClient | {
+    endpoint?: string;
+    endpoints?: string[];
+    fallbackEndpoints?: string[];
+    apiKey?: string;
+    commitment?: Commitment;
+    timeoutMs?: number;
+  };
+  /**
+   * Optional parent pool client — lets the deposit client reuse an already
+   * synced PoolInfo instead of making a fresh RPC round-trip.
+   */
+  poolClient?: CubicPoolClient;
+}
+
+/**
+ * Convenience class that wraps the single-token deposit flow end-to-end:
+ * quoting, transaction building, and helper-PDA derivation.
+ *
+ * Most consumers don't need to instantiate this directly — they can call
+ * `CubicPoolClient.singleTokenDeposit.*` which proxies here.
+ */
+export class SingleTokenDepositClient {
+  readonly config: CofferConfig;
+  readonly poolAddress: PublicKey;
+  private readonly poolClient: CubicPoolClient;
+
+  constructor(params: SingleTokenDepositClientParams) {
+    this.config = params.config;
+    this.poolAddress = params.poolAddress;
+    this.poolClient =
+      params.poolClient ??
+      new CubicPoolClient({
+        config: params.config,
+        poolAddress: params.poolAddress,
+        rpc:
+          params.rpc ??
+          {
+            endpoints: params.config.defaults.rpcEndpoints,
+            commitment: params.config.defaults.rpcCommitment,
+            timeoutMs: params.config.defaults.rpcTimeoutMs,
+          },
+      });
+  }
+
+  /** Derived helper PDA for this pool. */
+  helperPda(): PublicKey {
+    return deriveHelperPda(this.config.programs.singleTokenLiquidity, this.poolAddress)[0];
+  }
+
+  /** Ensure pool state is loaded; populates the underlying CubicPoolClient cache. */
+  async sync(): Promise<SdkResult<PoolInfo>> {
+    return this.poolClient.sync();
+  }
+
+  /** Off-chain estimate of the deposit outcome. */
+  quote(
+    tokenInIndex: number,
+    amountIn: BN,
+    slippageHundredthsBps?: number,
+    nowSeconds?: number,
+    helperBalances?: BN[]
+  ): SdkResult<SingleTokenDepositQuote> {
+    return this.poolClient.quoteSingleTokenDeposit(tokenInIndex, amountIn, slippageHundredthsBps, nowSeconds, helperBalances);
+  }
+
+  /**
+   * Build a ready-to-sign transaction. Includes idempotent helper-ATA
+   * creates.
+   *
+   * ⚠ Single-transaction form. It only fits for small pools — the ATA
+   * creates cost 5 CPI frames each and the zap itself uses 52 of the
+   * 64-frame budget at N=10. Use {@link buildTxs} for anything larger.
+   */
+  buildTx(params: SingleTokenDepositParams): SdkResult<BuiltTx> {
+    const pool = this.poolClient.getCached();
+    if (!pool) return err("invalid_input", "Call sync() first to populate pool state");
+    if (!Number.isInteger(params.tokenInIndex) || params.tokenInIndex < 0 || params.tokenInIndex >= pool.tokenCount) {
+      return err("invalid_input", "Invalid tokenInIndex");
+    }
+    if (params.amountIn.lten(0)) return err("invalid_input", "amountIn must be > 0");
+    if ((pool.unsupportedTokenIndices ?? []).some(i => !pool.tokens[i].actualBalance.isZero())) {
+      return err("unsupported_token_extension", unsupportedMessage(pool, "deposit_single_token"));
+    }
+    try {
+      const tx = buildSingleTokenDepositTx(this.config, pool, params);
+      return ok(tx);
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build single-token deposit tx", e);
+    }
+  }
+
+  /**
+   * Build the deposit as two transactions: `setup` (idempotent ATA creates)
+   * then `deposit`. Required for large pools; safe for all of them.
+   *
+   * Send `setup` and let it confirm before sending `deposit` — an ALT
+   * cannot be referenced in the same slot it was extended, and the two
+   * legs must not share an instruction-trace budget.
+   */
+  buildTxs(
+    params: SingleTokenDepositParams
+  ): SdkResult<{ setup: BuiltTx | null; deposit: BuiltTx }> {
+    const pool = this.poolClient.getCached();
+    if (!pool) return err("invalid_input", "Call sync() first to populate pool state");
+    if (!Number.isInteger(params.tokenInIndex) || params.tokenInIndex < 0 || params.tokenInIndex >= pool.tokenCount) {
+      return err("invalid_input", "Invalid tokenInIndex");
+    }
+    if (params.amountIn.lten(0)) return err("invalid_input", "amountIn must be > 0");
+    if ((pool.unsupportedTokenIndices ?? []).some(i => !pool.tokens[i].actualBalance.isZero())) {
+      return err("unsupported_token_extension", unsupportedMessage(pool, "deposit_single_token"));
+    }
+    try {
+      return ok(buildSingleTokenDepositTxs(this.config, pool, params));
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build single-token deposit txs", e);
+    }
+  }
+}

package/src/clients/contract-instructions.ts

@@ -0,0 +1,115 @@
+import { BorshInstructionCoder, Idl } from "@coral-xyz/anchor";
+import { AccountMeta, PublicKey, TransactionInstruction } from "@solana/web3.js";
+import BN from "bn.js";
+import { CofferConfig } from "../config";
+import { IDLS } from "../idl";
+import { ContractInstructionMap, ContractProgram } from "../types/contracts";
+
+type InstructionName<P extends ContractProgram> = keyof ContractInstructionMap[P] & string;
+export type ContractInstructionArgs<P extends ContractProgram, I extends InstructionName<P>> =
+  ContractInstructionMap[P][I] extends { args: infer A } ? A : never;
+export type ContractInstructionAccounts<P extends ContractProgram, I extends InstructionName<P>> =
+  ContractInstructionMap[P][I] extends { accounts: infer A } ? A : never;
+
+const coders = new Map<ContractProgram, BorshInstructionCoder>();
+
+/**
+ * Build any instruction exposed by the three deployed contracts. Argument and
+ * account names use the exact snake_case names from the shipped IDLs; all fixed
+ * accounts are explicit. Integer widths, argument fields, account order and
+ * signer/writable flags are checked or derived from those IDLs.
+ *
+ * This only builds an instruction. Required signatures, authority constraints,
+ * remaining-account layouts and transaction size still apply. A Treasury PDA
+ * can sign only during CPI: use the corresponding protocolAdmin wrapper for
+ * governance, rather than sending a cubicPool instruction with a PDA signer.
+ */
+export function buildContractInstruction<P extends ContractProgram, I extends InstructionName<P>>(
+  config: CofferConfig,
+  program: P,
+  instruction: I,
+  args: ContractInstructionArgs<P, I>,
+  accounts: ContractInstructionAccounts<P, I>,
+  remainingAccounts: AccountMeta[] = [],
+): TransactionInstruction {
+  const idl = IDLS[program];
+  const schema = (idl.instructions as any[]).find((ix) => ix.name === instruction);
+  if (!schema) throw new Error(`Unknown ${program} instruction: ${instruction}`);
+  validateFields(args, schema.args, idl, `${program}.${instruction}`);
+  const supplied = accounts as Record<string, PublicKey>;
+  assertObjectFields(supplied, schema.accounts.map((a: any) => a.name), "accounts");
+  const keys: AccountMeta[] = schema.accounts.map((a: any) => ({
+    pubkey: publicKey(supplied[a.name], `accounts.${a.name}`),
+    isSigner: a.signer === true,
+    isWritable: a.writable === true,
+  }));
+  for (const meta of remainingAccounts) {
+    if (typeof meta.isSigner !== "boolean" || typeof meta.isWritable !== "boolean") {
+      throw new Error("remainingAccounts must contain explicit signer and writable flags");
+    }
+    keys.push({ ...meta, pubkey: publicKey(meta.pubkey, "remainingAccounts.pubkey") });
+  }
+  let coder = coders.get(program);
+  if (!coder) {
+    coder = new BorshInstructionCoder(idl as unknown as Idl);
+    coders.set(program, coder);
+  }
+  return new TransactionInstruction({
+    programId: config.programs[program],
+    keys,
+    data: coder.encode(instruction, args as any),
+  });
+}
+
+function publicKey(value: any, path: string): PublicKey {
+  if (!value || typeof value.toBuffer !== "function") throw new Error(`${path} must be a PublicKey`);
+  const bytes = value.toBuffer();
+  if (bytes.length !== 32) throw new Error(`${path} must be a 32-byte PublicKey`);
+  return new PublicKey(bytes);
+}
+
+function assertObjectFields(value: unknown, expected: string[], path: string): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object`);
+  const names = Object.keys(value);
+  for (const key of expected) if (!Object.prototype.hasOwnProperty.call(value, key)) throw new Error(`${path}.${key} is required`);
+  for (const key of names) if (!expected.includes(key)) throw new Error(`${path}.${key} is not in the contract ABI`);
+}
+
+function validateFields(value: unknown, fields: any[], idl: any, path: string): void {
+  assertObjectFields(value, fields.map((f) => f.name), path);
+  for (const field of fields) validateType(value[field.name], field.type, idl, `${path}.${field.name}`);
+}
+
+function validateType(value: any, type: any, idl: any, path: string): void {
+  if (typeof type === "string") {
+    if (type === "pubkey") { publicKey(value, path); return; }
+    if (type === "bool") { if (typeof value !== "boolean") throw new Error(`${path} must be boolean`); return; }
+    if (type === "bytes") { if (!Buffer.isBuffer(value)) throw new Error(`${path} must be a Buffer`); return; }
+    const integer = /^([ui])(\d+)$/.exec(type);
+    if (integer) {
+      const width = Number(integer[2]);
+      const signed = integer[1] === "i";
+      if (width > 32 ? !BN.isBN(value) : !Number.isSafeInteger(value)) throw new Error(`${path} must be ${width > 32 ? "BN" : "an integer"} (${type})`);
+      const n = BN.isBN(value) ? value : new BN(value);
+      const min = signed ? new BN(1).shln(width - 1).neg() : new BN(0);
+      const max = new BN(1).shln(signed ? width - 1 : width).subn(1);
+      if (n.lt(min) || n.gt(max)) throw new Error(`${path} is outside ${type}`);
+      return;
+    }
+    throw new Error(`Unsupported ABI primitive ${type}`);
+  }
+  if (type.option) { if (value !== null) validateType(value, type.option, idl, path); return; }
+  if (type.vec || type.array) {
+    if (!Array.isArray(value)) throw new Error(`${path} must be an array`);
+    if (type.array && value.length !== type.array[1]) throw new Error(`${path} must have ${type.array[1]} entries`);
+    value.forEach((v, i) => validateType(v, type.vec ?? type.array[0], idl, `${path}[${i}]`));
+    return;
+  }
+  if (type.defined) {
+    const definition = idl.types.find((t: any) => t.name === type.defined.name);
+    if (!definition || definition.type.kind !== "struct") throw new Error(`Unsupported ABI type ${type.defined.name}`);
+    validateFields(value, definition.type.fields, idl, path);
+    return;
+  }
+  throw new Error(`Unsupported ABI type at ${path}`);
+}

package/src/clients/index.ts

@@ -0,0 +1,9 @@
+export * from "./RpcClient";
+export * from "./CofferBackendClient";
+export * from "./CubicPoolClient";
+export * from "./tx-builders";
+export * from "./versioned";
+export * from "./SingleTokenDepositClient";
+export * from "./PoolFactoryClient";
+export * from "./AdminClient";
+export * from "./contract-instructions";

package/src/clients/quote-math.ts

@@ -0,0 +1,81 @@
+import BN from "bn.js";
+import { PoolInfo, PoolTokenInfo } from "../types/pool";
+import { calcOutGivenIn, calcSpotOut } from "../math/cubicMath";
+import { calculateSwapFee, calculateProtocolFee } from "../math/slippage";
+import { checkAndAdvanceSelloff } from "../math/maxSelloff";
+import { calcSurgeFeeAmount } from "../math/surgeFee";
+
+const U64_MAX = (1n << 64n) - 1n;
+export function u64(value: bigint, label: string): bigint {
+  if (value < 0n || value > U64_MAX) throw new Error(`${label} must fit u64`);
+  return value;
+}
+const bi = (value: BN | undefined): bigint => BigInt(value?.toString() ?? "0");
+
+/** Compute one deployed-contract swap against a snapshot, optionally advance a private zap copy. */
+export function simulatePoolSwap(pool: PoolInfo, tokenInIndex: number, tokenOutIndex: number, amountIn: bigint, now: bigint, mutate = false) {
+  if (!Number.isInteger(tokenInIndex) || !Number.isInteger(tokenOutIndex) || tokenInIndex === tokenOutIndex ||
+      tokenInIndex < 0 || tokenOutIndex < 0 || tokenInIndex >= pool.tokenCount || tokenOutIndex >= pool.tokenCount) {
+    throw new Error("InvalidTokenIndex");
+  }
+  if (!pool.poolEnabled) throw new Error("PoolDisabled");
+  if (!pool.swapsEnabled) throw new Error("SwapsDisabled");
+  u64(amountIn, "amountIn");
+  if (amountIn === 0n) throw new Error("ZeroAmount");
+  const input = pool.tokens[tokenInIndex], output = pool.tokens[tokenOutIndex];
+  if (!input.isActive) throw new Error("TokenInactive");
+  const virtualBalanceIn = bi(input.virtualBalance), virtualBalanceOut = bi(output.virtualBalance);
+  const actualBalanceOut = bi(output.actualBalance);
+  if (input.maxSelloffPct > 0 && [input.maxSelloffPeriodLength, input.previousSelloff, input.currentSelloff,
+      input.windowStartTimestamp, input.selloffVbSnapshot].some(v => v === undefined)) {
+    throw new Error("Selloff state missing: sync the pool before quoting");
+  }
+  const window = checkAndAdvanceSelloff({
+    state: { previousSelloff: bi(input.previousSelloff), currentSelloff: bi(input.currentSelloff),
+      windowStartTimestamp: bi(input.windowStartTimestamp), selloffVbSnapshot: bi(input.selloffVbSnapshot) },
+    maxSelloffPct: input.maxSelloffPct, period: input.maxSelloffPeriodLength ?? 0,
+    amountIn, virtualBalance: virtualBalanceIn, now,
+  });
+  const feeAmount = calculateSwapFee(amountIn, pool.swapFeeRate);
+  const protocolFeeAmount = calculateProtocolFee(feeAmount, pool.protocolFeeRate);
+  const amountInAfterFee = amountIn - feeAmount;
+  const weightInBps = BigInt(input.weightBps), weightOutBps = BigInt(output.weightBps);
+  const grossAmountOut = calcOutGivenIn({ virtualBalanceIn, virtualBalanceOut, weightInBps, weightOutBps, amountIn: amountInAfterFee, actualBalanceOut });
+  const surgeFeeAmount = calcSurgeFeeAmount({ window,
+    thresholdPct: input.variableFeeThresholdPct ?? 0, slopeLowPct: input.variableFeeSlopeLowPct ?? 0,
+    slopeMidPct: input.variableFeeSlopeMidPct ?? 0, slopeHighPct: input.variableFeeSlopeHighPct ?? 0,
+    kinkPct: input.variableFeeKinkPct ?? 0, amountInAfterFee, amountOut: grossAmountOut,
+    virtualBalanceIn, virtualBalanceOut, weightInBps, weightOutBps, actualBalanceOut });
+  const amountOut = grossAmountOut - surgeFeeAmount;
+  const netInput = amountIn - protocolFeeAmount;
+  const actualInAfter = u64(bi(input.actualBalance) + netInput, "input actual balance");
+  const virtualInAfter = u64(virtualBalanceIn + netInput, "input virtual balance");
+  const actualOutAfter = u64(actualBalanceOut - grossAmountOut, "output actual balance");
+  const virtualOutAfter = u64(virtualBalanceOut - grossAmountOut, "output virtual balance");
+  const inputFees = u64(bi(input.protocolFeesOwed) + protocolFeeAmount, "input fees");
+  const outputFees = u64(bi(output.protocolFeesOwed) + surgeFeeAmount, "output fees");
+  if (mutate) {
+    input.actualBalance = new BN(actualInAfter.toString()); input.virtualBalance = new BN(virtualInAfter.toString());
+    output.actualBalance = new BN(actualOutAfter.toString()); output.virtualBalance = new BN(virtualOutAfter.toString());
+    input.protocolFeesOwed = new BN(inputFees.toString()); output.protocolFeesOwed = new BN(outputFees.toString());
+    if (window) {
+      input.previousSelloff = new BN(window.previousSelloff.toString()); input.currentSelloff = new BN(window.currentSelloff.toString());
+      input.windowStartTimestamp = new BN(window.windowStartTimestamp.toString()); input.selloffVbSnapshot = new BN(window.vbSnapshot.toString());
+    }
+  }
+  const spotOut = calcSpotOut({ virtualBalanceIn, virtualBalanceOut, weightInBps, weightOutBps, amountIn: amountInAfterFee });
+  // `window` is exposed for display math (post-trade fill %, span-average
+  // surge pct) — null when the input token has no sell-off cap configured.
+  return { amountOut, grossAmountOut, feeAmount, protocolFeeAmount, surgeFeeAmount, spotOut, window };
+}
+
+/** Clock from sync; callers may supply the transaction's expected Unix timestamp explicitly. */
+export function quoteTimestamp(pool: PoolInfo, nowSeconds?: number): bigint {
+  const now = nowSeconds ?? pool.chainTimestamp;
+  if (now === undefined) {
+    if (pool.tokens.some(t => t.maxSelloffPct > 0)) throw new Error("Chain timestamp missing: sync or supply nowSeconds");
+    return 0n;
+  }
+  if (!Number.isSafeInteger(now) || now < 0) throw new Error("Invalid quote timestamp");
+  return BigInt(now);
+}