@cubee_ee/sdk 0.1.0

package/src/clients/CubeBackendClient.ts

@@ -0,0 +1,193 @@
+import { SdkResult, err, ok } from "../types/result";
+import { PoolSummary } from "../types/pool";
+import { safeCall } from "../utils/retry";
+
+export interface CubeBackendClientParams {
+  apiEndpoint: string;
+  apiKey?: string;
+  defaultHeaders?: Record<string, string>;
+}
+
+export type StatsKind =
+  | "tvl"
+  | "volume"
+  | "swap_count"
+  | "avg_swap"
+  | "median_swap"
+  | "fees_lp"
+  | "fees_protocol"
+  | "users_total"
+  | "dau"
+  | "mau"
+  | "deposits"
+  | "removals";
+
+export type StatsWindow = "1d" | "7d" | "30d" | "all";
+
+export interface StatsSeriesPoint {
+  t: number;
+  v: number;
+}
+export interface StatsSeries {
+  points: StatsSeriesPoint[];
+}
+
+export interface PriceMap {
+  [mint: string]: number;
+}
+
+/**
+ * REST wrapper around the Cube backend. Every method is a SdkResult; no
+ * exceptions escape. If a request fails, the result carries a
+ * human-readable error plus the original cause.
+ */
+export class CubeBackendClient {
+  private readonly endpoint: string;
+  private readonly headers: Record<string, string>;
+
+  constructor(params: CubeBackendClientParams) {
+    this.endpoint = params.apiEndpoint.replace(/\/$/, "");
+    this.headers = {
+      "Content-Type": "application/json",
+      ...(params.apiKey ? { Authorization: `Bearer ${params.apiKey}` } : {}),
+      ...(params.defaultHeaders ?? {}),
+    };
+  }
+
+  listPools(): Promise<SdkResult<PoolSummary[]>> {
+    return this.get<PoolSummary[]>("/api/pools");
+  }
+
+  getPool(addr: string): Promise<SdkResult<PoolSummary>> {
+    return this.get<PoolSummary>(`/api/pools/${addr}`);
+  }
+
+  /**
+   * Raw pool-list response in the same envelope the backend returns
+   * (`{ data, hasMore, totalCount }`). Kept so the frontend's React
+   * Query hooks can map directly.
+   */
+  listPoolsRaw(
+    limit: number,
+    offset: number
+  ): Promise<SdkResult<{ data: unknown[]; hasMore: boolean; totalCount: number }>> {
+    const qs = new URLSearchParams({ limit: String(limit), offset: String(offset) });
+    return this.getEnvelope(`/api/pools?${qs.toString()}`);
+  }
+
+  getPoolRaw(addr: string): Promise<SdkResult<unknown>> {
+    return this.getDataField<unknown>(`/api/pools/${addr}`);
+  }
+
+  createPool<T>(body: unknown): Promise<SdkResult<T>> {
+    return this.postDataField<T>("/api/pools", body);
+  }
+
+  getPoolsByTokenPair<T>(tokenA: string, tokenB: string): Promise<SdkResult<T>> {
+    const qs = new URLSearchParams({ tokenA, tokenB });
+    return this.getDataField<T>(`/api/pools/by-pair?${qs.toString()}`);
+  }
+
+  getPlatformStats<T>(): Promise<SdkResult<T>> {
+    return this.getDataField<T>("/api/pools/stats");
+  }
+
+  getPortfolio<T>(owner: string): Promise<SdkResult<T>> {
+    return this.getDataField<T>(`/api/pools/portfolio?owner=${encodeURIComponent(owner)}`);
+  }
+
+  getAllTokens<T>(): Promise<SdkResult<T>> {
+    return this.getDataField<T>("/api/pools/tokens");
+  }
+
+  getTopTokens<T>(limit: number = 20): Promise<SdkResult<T>> {
+    return this.getDataField<T>(`/api/pools/top-tokens?limit=${limit}`);
+  }
+
+  getPoolTxStats<T>(addr: string): Promise<SdkResult<T>> {
+    return this.getDataField<T>(`/api/pools/${addr}/tx-stats`);
+  }
+
+  getTransactions<T>(addr: string, limit: number = 20, offset: number = 0): Promise<SdkResult<T>> {
+    const qs = new URLSearchParams({ limit: String(limit), offset: String(offset) });
+    return this.getDataField<T>(`/api/pools/${addr}/transactions?${qs.toString()}`);
+  }
+
+  getSwapRoute<T>(
+    tokenIn: string,
+    tokenOut: string,
+    amountIn: string
+  ): Promise<SdkResult<T>> {
+    const qs = new URLSearchParams({ tokenIn, tokenOut, amountIn });
+    return this.getDataField<T>(`/api/swap/route?${qs.toString()}`);
+  }
+
+  getTokenPrices(mints: string[]): Promise<SdkResult<PriceMap>> {
+    const qs = new URLSearchParams({ mints: mints.join(",") });
+    return this.get<PriceMap>(`/api/prices?${qs.toString()}`);
+  }
+
+  getStats(
+    kind: StatsKind,
+    window: StatsWindow = "7d",
+    poolAddr?: string,
+    unit: "usd" | "token" = "usd"
+  ): Promise<SdkResult<StatsSeries>> {
+    const qs = new URLSearchParams({ window, unit });
+    if (poolAddr) qs.set("pool", poolAddr);
+    return this.get<StatsSeries>(`/api/stats/${kind}?${qs.toString()}`);
+  }
+
+  /** Generic GET with retry. Callers that need it for other endpoints. */
+  get<T>(path: string): Promise<SdkResult<T>> {
+    return this.request<T>("GET", path);
+  }
+
+  post<T>(path: string, body: unknown): Promise<SdkResult<T>> {
+    return this.request<T>("POST", path, body);
+  }
+
+  private async request<T>(
+    method: "GET" | "POST",
+    path: string,
+    body?: unknown
+  ): Promise<SdkResult<T>> {
+    const url = `${this.endpoint}${path}`;
+    const fetchOpts: RequestInit = {
+      method,
+      headers: this.headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    };
+    const raw = await safeCall(async () => {
+      const res = await fetch(url, fetchOpts);
+      if (!res.ok) {
+        throw new Error(`${method} ${path} → HTTP ${res.status} ${res.statusText}`);
+      }
+      return (await res.json()) as T;
+    });
+    if (!raw.ok) return raw;
+    return ok(raw.data);
+  }
+
+  /**
+   * Fetch a response envelope of the form `{ data: T, ... }` and unwrap
+   * the `.data` field. The existing Cube backend wraps most endpoints
+   * this way.
+   */
+  private async getDataField<T>(path: string): Promise<SdkResult<T>> {
+    const res = await this.get<{ data: T }>(path);
+    if (!res.ok) return res;
+    return ok(res.data?.data);
+  }
+
+  private async postDataField<T>(path: string, body: unknown): Promise<SdkResult<T>> {
+    const res = await this.post<{ data: T }>(path, body);
+    if (!res.ok) return res;
+    return ok(res.data?.data);
+  }
+
+  /** Fetch the full envelope (for endpoints that return meta alongside data). */
+  private async getEnvelope<T>(path: string): Promise<SdkResult<T>> {
+    return this.get<T>(path);
+  }
+}

package/src/clients/CubicPoolClient.ts

@@ -0,0 +1,492 @@
+import { PublicKey, Commitment } from "@solana/web3.js";
+import BN from "bn.js";
+import { CubeConfig } from "../config";
+import { PoolInfo, PoolTokenInfo } from "../types/pool";
+import { SdkResult, err, ok } from "../types/result";
+import { SwapQuote, SingleTokenDepositQuote } from "../types/tx";
+import { CubicPoolEvent } from "../types/events";
+import { RpcClient } from "./RpcClient";
+import { decodePoolAccount } from "../parsers/poolAccount";
+import { decodeMintAccount } from "../parsers/mintAccount";
+import { parseCubicPoolEvents } from "../parsers/events";
+import { deriveAta, deriveBptMint, deriveHelperPda } from "../utils/pda";
+import { resolveKnownToken } from "../config/tokens";
+import {
+  calcBptOutGivenExactTokensIn,
+  calcOutGivenIn,
+  calcSpotOut,
+  calcTokensOutGivenBptIn,
+} from "../math/cubicMath";
+import { applySlippage, applySwapFee, priceImpactHbps } from "../math/slippage";
+import { capDepositAmountsToLpRatio, computeAllocations } from "../math/singleToken";
+import {
+  buildAddLiquidityTx,
+  buildRemoveLiquidityTx,
+  buildSingleTokenDepositTx,
+  buildSwapTx,
+} from "./tx-builders";
+import {
+  AddLiquidityParams,
+  BuiltTx,
+  RemoveLiquidityParams,
+  SingleTokenDepositParams,
+  SwapParams,
+} from "../types/tx";
+import { SingleTokenDepositClient } from "./SingleTokenDepositClient";
+
+export interface CubicPoolClientParams {
+  config: CubeConfig;
+  poolAddress: PublicKey;
+  rpc:
+    | RpcClient
+    | {
+        endpoint: string;
+        apiKey?: string;
+        commitment?: Commitment;
+      };
+}
+
+/**
+ * Per-pool client. Fetch the state with `sync()`, then call any of the
+ * quote / buildTx methods off the cached snapshot.
+ */
+export class CubicPoolClient {
+  readonly config: CubeConfig;
+  readonly poolAddress: PublicKey;
+  readonly rpc: RpcClient;
+
+  private cache: PoolInfo | undefined;
+
+  constructor(params: CubicPoolClientParams) {
+    this.config = params.config;
+    this.poolAddress = params.poolAddress;
+    this.rpc =
+      params.rpc instanceof RpcClient
+        ? params.rpc
+        : new RpcClient({
+            endpoint: params.rpc.endpoint,
+            apiKey: params.rpc.apiKey,
+            commitment: params.rpc.commitment ?? params.config.defaults.rpcCommitment,
+          });
+  }
+
+  /** Last-fetched pool state. `undefined` before first `sync()`. */
+  getCached(): PoolInfo | undefined {
+    return this.cache;
+  }
+
+  /**
+   * Fetch and decode the pool account + BPT mint + per-token mint decimals.
+   * Safe to call repeatedly; subsequent calls replace the cache.
+   */
+  async sync(): Promise<SdkResult<PoolInfo>> {
+    const poolInfo = await this.rpc.getAccountInfo(this.poolAddress);
+    if (!poolInfo.ok) return poolInfo;
+    if (poolInfo.data === null) {
+      return err("account_not_found", `Pool ${this.poolAddress.toBase58()} does not exist on-chain`);
+    }
+    let raw;
+    try {
+      raw = decodePoolAccount(poolInfo.data.data);
+    } catch (e) {
+      return err("parse_failure", "Could not decode pool account", e);
+    }
+    const n = raw.tokenCount;
+    const mintAddrs = raw.tokenMints.slice(0, n);
+    const [bptMint, _bptBump] = deriveBptMint(this.config.programs.cubicPool, this.poolAddress);
+
+    const mintInfos = await this.rpc.getMultipleAccountsInfo([bptMint, ...mintAddrs]);
+    if (!mintInfos.ok) return mintInfos;
+    const [bptMintData, ...tokenMintDatas] = mintInfos.data;
+    if (!bptMintData) {
+      return err("account_not_found", "BPT mint account missing");
+    }
+    let bptMintAcc;
+    try {
+      bptMintAcc = decodeMintAccount(bptMintData);
+    } catch (e) {
+      return err("parse_failure", "Could not decode BPT mint", e);
+    }
+    const tokens: PoolTokenInfo[] = [];
+    for (let i = 0; i < n; i++) {
+      const mintRaw = tokenMintDatas[i];
+      if (!mintRaw) {
+        return err("account_not_found", `Mint account missing for token index ${i}`);
+      }
+      let mintAcc;
+      try {
+        mintAcc = decodeMintAccount(mintRaw);
+      } catch (e) {
+        return err("parse_failure", `Could not decode mint ${mintAddrs[i].toBase58()}`, e);
+      }
+      const actualBalance = raw.actualBalances[i];
+      const virtualBalance = raw.virtualBalances[i];
+      const concentration =
+        virtualBalance.isZero() ? 0 : actualBalance.mul(new BN(1_000_000)).div(virtualBalance).toNumber() / 1_000_000;
+      tokens.push({
+        index: i,
+        mint: raw.tokenMints[i],
+        tokenProgram: raw.tokenPrograms[i],
+        decimals: mintAcc.decimals,
+        weightBps: raw.normalizedWeights[i].toNumber(),
+        virtualBalance,
+        actualBalance,
+        protocolFeesOwed: raw.protocolFeesOwed[i],
+        vault: deriveAta(this.poolAddress, raw.tokenMints[i], raw.tokenPrograms[i]),
+        metadata:
+          this.config.tokens?.[raw.tokenMints[i].toBase58()] ??
+          resolveKnownToken(raw.tokenMints[i].toBase58()),
+        concentration,
+      });
+    }
+
+    const info: PoolInfo = {
+      address: this.poolAddress,
+      config: raw.config,
+      bump: raw.bump,
+      poolId: raw.poolId,
+      tokenCount: n,
+      tokens,
+      bptMint,
+      bptTotalSupply: bptMintAcc.supply,
+      swapFeeRate: raw.swapFeeRate,
+      protocolFeeRate: raw.protocolFeeRate,
+      poolEnabled: raw.poolEnabled,
+      swapsEnabled: raw.swapsEnabled,
+      createdAt: raw.createdAt.toNumber(),
+      syncedAt: Date.now(),
+    };
+    this.cache = info;
+    return ok(info);
+  }
+
+  /** Derived helper PDA for this pool (used by single-token-deposit). */
+  helperPda(): PublicKey {
+    return deriveHelperPda(this.config.programs.singleTokenLiquidity, this.poolAddress)[0];
+  }
+
+  // ---------- Quote helpers (pure, require sync()) ----------
+
+  /**
+   * Quote a swap. Requires the cache to be populated (call `sync()` first).
+   * Returns exact on-chain math result + spot bound + price impact +
+   * slippage-derived minAmountOut.
+   */
+  quoteSwap(
+    tokenInIndex: number,
+    tokenOutIndex: number,
+    amountIn: BN,
+    slippageHundredthsBps?: number
+  ): SdkResult<SwapQuote> {
+    const pool = this.requireCache();
+    if (!pool.ok) return pool;
+    const { tokens, swapFeeRate, protocolFeeRate } = pool.data;
+    if (
+      tokenInIndex < 0 ||
+      tokenInIndex >= tokens.length ||
+      tokenOutIndex < 0 ||
+      tokenOutIndex >= tokens.length ||
+      tokenInIndex === tokenOutIndex
+    ) {
+      return err("invalid_input", "Invalid tokenInIndex / tokenOutIndex");
+    }
+    const inTok = tokens[tokenInIndex];
+    const outTok = tokens[tokenOutIndex];
+    const slip = slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps;
+
+    try {
+      const amountBI = BigInt(amountIn.toString());
+      const amountAfterFee = applySwapFee(amountBI, swapFeeRate);
+      const feeAmount = amountBI - amountAfterFee;
+      const protocolFeeAmount =
+        (feeAmount * BigInt(protocolFeeRate)) / BigInt(10_000);
+
+      // Mirror cubic-pool's swap.rs: raw virtual balances drive the math,
+      // lp_actual_out caps the output amount. Using lp_virtual here would
+      // diverge from the on-chain quote on pools with pending protocol fees.
+      const virtIn = BigInt(inTok.virtualBalance.toString());
+      const virtOut = BigInt(outTok.virtualBalance.toString());
+      const actualOut = BigInt(outTok.actualBalance.toString());
+      const pfoOut = BigInt(outTok.protocolFeesOwed.toString());
+      const lpActualOut = actualOut > pfoOut ? actualOut - pfoOut : 0n;
+
+      const amountOut = calcOutGivenIn({
+        virtualBalanceIn: virtIn,
+        weightInBps: BigInt(inTok.weightBps),
+        virtualBalanceOut: virtOut,
+        weightOutBps: BigInt(outTok.weightBps),
+        amountIn: amountAfterFee,
+        actualBalanceOut: lpActualOut,
+      });
+
+      const spotOut = calcSpotOut({
+        virtualBalanceIn: virtIn,
+        weightInBps: BigInt(inTok.weightBps),
+        virtualBalanceOut: virtOut,
+        weightOutBps: BigInt(outTok.weightBps),
+        amountIn: amountAfterFee,
+      });
+
+      const minAmountOut = applySlippage(amountOut, slip);
+      const impact = priceImpactHbps(spotOut, amountOut);
+      return ok({
+        tokenInIndex,
+        tokenOutIndex,
+        amountIn,
+        amountOut: new BN(amountOut.toString()),
+        spotOut: new BN(spotOut.toString()),
+        priceImpactHbps: impact,
+        feeAmount: new BN(feeAmount.toString()),
+        protocolFeeAmount: new BN(protocolFeeAmount.toString()),
+        minAmountOut: new BN(minAmountOut.toString()),
+      });
+    } catch (e) {
+      return err("math_overflow", "Swap quote math overflow", e);
+    }
+  }
+
+  /**
+   * Quote a single-token deposit: split amountIn by W-based shares, quote
+   * each swap leg, estimate resulting BPT.
+   */
+  quoteSingleTokenDeposit(
+    tokenInIndex: number,
+    amountIn: BN,
+    slippageHundredthsBps?: number
+  ): SdkResult<SingleTokenDepositQuote> {
+    const poolRes = this.requireCache();
+    if (!poolRes.ok) return poolRes;
+    const pool = poolRes.data;
+    if (tokenInIndex < 0 || tokenInIndex >= pool.tokens.length) {
+      return err("invalid_input", "Invalid tokenInIndex");
+    }
+    const inTok = pool.tokens[tokenInIndex];
+    if (inTok.actualBalance.isZero()) {
+      return err("invalid_input", "Input token is sidelined (actualBalance=0); pick a live token");
+    }
+    const slip = slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps;
+
+    try {
+      const actualBalances = pool.tokens.map((t) => BigInt(t.actualBalance.toString()));
+      const virtualBalances = pool.tokens.map((t) => BigInt(t.virtualBalance.toString()));
+      const protocolFeesOwed = pool.tokens.map((t) => BigInt(t.protocolFeesOwed.toString()));
+      const weightsBps = pool.tokens.map((t) => t.weightBps);
+      const amountInBI = BigInt(amountIn.toString());
+      // Mirror the helper contract: weight by LP-accessible balances
+      // (actual - protocolFeesOwed). This avoids the heavy 2-token optimizer
+      // which used to live here but exceeded the program's BPF CU budget.
+      const lpAccessibleBalances = actualBalances.map((actual, i) =>
+        actual > protocolFeesOwed[i] ? actual - protocolFeesOwed[i] : 0n
+      );
+      const alloc = computeAllocations({
+        actualBalances: lpAccessibleBalances,
+        virtualBalances,
+        weightsBps,
+        amountIn: amountInBI,
+        tokenInIndex,
+      });
+
+      const expectedOuts: BN[] = [];
+      const minOuts: BN[] = [];
+      const sidelined: number[] = [];
+      const simActual = [...actualBalances];
+      const simVirtual = [...virtualBalances];
+      const simProtocolFees = [...protocolFeesOwed];
+      const depositAmounts = pool.tokens.map(() => 0n);
+      let remainingInput = amountInBI;
+      for (let i = 0; i < pool.tokens.length; i++) {
+        if (actualBalances[i] === 0n) {
+          sidelined.push(i);
+          expectedOuts.push(new BN(0));
+          minOuts.push(new BN(0));
+          continue;
+        }
+        if (i === tokenInIndex || alloc.allocations[i] === 0n) {
+          expectedOuts.push(new BN(0));
+          minOuts.push(new BN(0));
+          continue;
+        }
+        const swapAmount = alloc.allocations[i];
+        remainingInput -= swapAmount;
+        const amountAfterFee = applySwapFee(swapAmount, pool.swapFeeRate);
+        const feeAmount = swapAmount - amountAfterFee;
+        const protocolFeeAmount =
+          (feeAmount * BigInt(pool.protocolFeeRate)) / 10_000n;
+        // Match cubic-pool/swap.rs exactly: it uses RAW virtual balances and
+        // takes lp_actual_out only as the output cap. Earlier the SDK used
+        // LP-virtuals here (and the helper did too), causing slippage drift
+        // on pools with pending protocol fees.
+        const lpActualOut =
+          simActual[i] > simProtocolFees[i] ? simActual[i] - simProtocolFees[i] : 0n;
+        const out = calcOutGivenIn({
+          virtualBalanceIn: simVirtual[tokenInIndex],
+          weightInBps: BigInt(weightsBps[tokenInIndex]),
+          virtualBalanceOut: simVirtual[i],
+          weightOutBps: BigInt(weightsBps[i]),
+          amountIn: amountAfterFee,
+          actualBalanceOut: lpActualOut,
+        });
+        const min = applySlippage(out > 0n ? out - 1n : 0n, slip);
+        expectedOuts.push(new BN(out.toString()));
+        minOuts.push(new BN(min.toString()));
+
+        simActual[tokenInIndex] += swapAmount;
+        simVirtual[tokenInIndex] += amountAfterFee;
+        simProtocolFees[tokenInIndex] += protocolFeeAmount;
+        simActual[i] -= out;
+        simVirtual[i] -= out;
+        depositAmounts[i] = out;
+      }
+      depositAmounts[tokenInIndex] = remainingInput;
+
+      const capped = capDepositAmountsToLpRatio({
+        helperBalances: depositAmounts,
+        actualBalances: simActual,
+        protocolFeesOwed: simProtocolFees,
+      });
+      const estBpt = calcBptOutGivenExactTokensIn(
+        capped.lpBalancesForAdd,
+        capped.depositAmounts,
+        BigInt(pool.bptTotalSupply.toString())
+      );
+
+      return ok({
+        tokenInIndex,
+        amountIn,
+        allocations: alloc.allocations.map((b) => new BN(b.toString())),
+        expectedOuts,
+        minOuts,
+        depositedAmounts: capped.depositAmounts.map((b) => new BN(b.toString())),
+        refundAmounts: capped.refundAmounts.map((b) => new BN(b.toString())),
+        estimatedBpt: new BN(estBpt.toString()),
+        sidelinedTokenIndices: sidelined,
+      });
+    } catch (e) {
+      return err("math_overflow", "Single-token deposit quote failed", e);
+    }
+  }
+
+  /** Proportional-withdraw quote for a given BPT amount. */
+  quoteRemove(bptIn: BN): SdkResult<{ tokenOuts: BN[] }> {
+    const poolRes = this.requireCache();
+    if (!poolRes.ok) return poolRes;
+    const pool = poolRes.data;
+    if (pool.bptTotalSupply.isZero()) {
+      return err("invalid_input", "Pool has zero BPT supply");
+    }
+    try {
+      // Match cubic-pool/remove_liquidity.rs exactly: it computes
+      // token_amounts as `actual_balances[i] * bpt_amount / bpt_supply`
+      // against the raw stored actual (no protocol-fee subtraction). Use
+      // the same input here so the SDK quote equals what the contract
+      // actually transfers.
+      const bals = pool.tokens.map((t) => BigInt(t.actualBalance.toString()));
+      const outs = calcTokensOutGivenBptIn(bals, BigInt(bptIn.toString()), BigInt(pool.bptTotalSupply.toString()));
+      return ok({ tokenOuts: outs.map((o) => new BN(o.toString())) });
+    } catch (e) {
+      return err("math_overflow", "Remove quote failed", e);
+    }
+  }
+
+  // ---------- Transaction builders ----------
+  //
+  // For external SDK users, deposit/swap/remove are one-call operations via
+  // the CubicPoolClient. The `singleTokenDeposit` field is a proxy into the
+  // dedicated SingleTokenDepositClient as the user expects: importing this
+  // class is enough, no need to know the helper program exists.
+
+  /** Build a swap transaction. Requires `sync()` first. */
+  buildSwapTx(params: SwapParams): SdkResult<BuiltTx> {
+    const poolRes = this.requireCache();
+    if (!poolRes.ok) return poolRes;
+    const slip = params.slippageHundredthsBps ?? this.config.defaults.slippageHundredthsBps;
+    const minOut = params.minAmountOut
+      ? params.minAmountOut
+      : (() => {
+          const q = this.quoteSwap(params.tokenInIndex, params.tokenOutIndex, params.amountIn, slip);
+          return q.ok ? q.data.minAmountOut : new BN(0);
+        })();
+    try {
+      const tx = buildSwapTx(this.config, poolRes.data, { ...params, minAmountOut: minOut });
+      return ok(tx);
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build swap tx", e);
+    }
+  }
+
+  /** Build a proportional add-liquidity transaction. Requires `sync()` first. */
+  buildAddLiquidityTx(params: AddLiquidityParams): SdkResult<BuiltTx> {
+    const poolRes = this.requireCache();
+    if (!poolRes.ok) return poolRes;
+    if (params.tokenAmounts.length !== poolRes.data.tokenCount) {
+      return err("invalid_input", "tokenAmounts length must equal pool.tokenCount");
+    }
+    try {
+      return ok(buildAddLiquidityTx(this.config, poolRes.data, params));
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build add_liquidity tx", e);
+    }
+  }
+
+  /** Build a proportional remove-liquidity transaction. Requires `sync()` first. */
+  buildRemoveLiquidityTx(params: RemoveLiquidityParams): SdkResult<BuiltTx> {
+    const poolRes = this.requireCache();
+    if (!poolRes.ok) return poolRes;
+    if (
+      params.minimumTokenAmounts &&
+      params.minimumTokenAmounts.length !== poolRes.data.tokenCount
+    ) {
+      return err("invalid_input", "minimumTokenAmounts length must equal pool.tokenCount");
+    }
+    try {
+      return ok(buildRemoveLiquidityTx(this.config, poolRes.data, params));
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build remove_liquidity tx", e);
+    }
+  }
+
+  /**
+   * Build a single-token deposit transaction (swaps + add_liquidity via the
+   * helper program + BPT forward to user). Requires `sync()` first.
+   */
+  buildSingleTokenDepositTx(params: SingleTokenDepositParams): SdkResult<BuiltTx> {
+    const poolRes = this.requireCache();
+    if (!poolRes.ok) return poolRes;
+    if (params.amountIn.lten(0)) return err("invalid_input", "amountIn must be > 0");
+    try {
+      return ok(buildSingleTokenDepositTx(this.config, poolRes.data, params));
+    } catch (e) {
+      return err("tx_build_failed", "Failed to build single-token deposit tx", e);
+    }
+  }
+
+  /** Proxy into the dedicated SingleTokenDepositClient for consumers who
+   *  want the quote/build methods exposed on a focused object. */
+  get singleTokenDeposit(): SingleTokenDepositClient {
+    if (!this._std) {
+      this._std = new SingleTokenDepositClient({
+        config: this.config,
+        poolAddress: this.poolAddress,
+        poolClient: this,
+      });
+    }
+    return this._std;
+  }
+  private _std?: SingleTokenDepositClient;
+
+  // ---------- Event helpers ----------
+
+  /** Parse logs from a confirmed transaction into typed events. */
+  parseEventsFromLogs(logs: string[]): CubicPoolEvent[] {
+    return parseCubicPoolEvents(logs);
+  }
+
+  // ---------- Internals ----------
+
+  private requireCache(): SdkResult<PoolInfo> {
+    if (!this.cache) {
+      return err("invalid_input", "Call `sync()` first to populate pool state");
+    }
+    return ok(this.cache);
+  }
+}