@coffer_so/sdk 1.0.0

package/src/types/result.ts

@@ -0,0 +1,51 @@
+/**
+ * Result returned by high-level client reads, quotes and transaction builders.
+ * Raw builders, parsers, math functions and Anchor instruction methods may
+ * throw. Use `if (res.ok) { ... } else { ... }` for result-based methods.
+ */
+export type SdkResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: SdkError };
+
+export interface SdkError {
+  /** Stable machine-readable code. */
+  code: SdkErrorCode;
+  /** Human-readable message, safe to show to end users. */
+  humanMessage: string;
+  /** Original error for debugging; never render this to end users. */
+  cause?: unknown;
+}
+
+export type SdkErrorCode =
+  | "rpc_unavailable"
+  | "rpc_timeout"
+  | "rpc_rate_limited"
+  | "account_not_found"
+  | "invalid_input"
+  | "math_overflow"
+  | "parse_failure"
+  | "backend_unavailable"
+  | "backend_invalid_response"
+  | "insufficient_funds"
+  | "pool_disabled"
+  | "swaps_disabled"
+  | "selloff_window_full"
+  | "token_swaps_disabled"
+  | "unsupported_pool_state"
+  | "unsupported_token_extension"
+  | "slippage_exceeded"
+  | "simulation_failed"
+  | "tx_build_failed"
+  | "alt_fetch_failed"
+  | "auth_failed"
+  | "unknown";
+
+export const ok = <T>(data: T): SdkResult<T> => ({ ok: true, data });
+export const err = (
+  code: SdkErrorCode,
+  humanMessage: string,
+  cause?: unknown
+): SdkResult<never> => ({
+  ok: false,
+  error: { code, humanMessage, cause },
+});

package/src/types/tx.ts

@@ -0,0 +1,278 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import BN from "bn.js";
+
+export interface SwapParams {
+  user: PublicKey;
+  tokenInIndex: number;
+  tokenOutIndex: number;
+  amountIn: BN;
+  /** Hundredths-bps; omit to use SDK config default. */
+  slippageHundredthsBps?: number;
+  /** Optional explicit minimum; overrides slippage-derived value. */
+  minAmountOut?: BN;
+}
+
+export interface SwapQuote {
+  tokenInIndex: number;
+  tokenOutIndex: number;
+  amountIn: BN;
+  amountOut: BN;
+  /** Output before the sell-off surge fee (equals amountOut + surgeFeeAmount). */
+  grossAmountOut?: BN;
+  /** Spot-based upper bound on amountOut; useful for price-impact UI. */
+  spotOut: BN;
+  /** Absolute price impact in hundredths of basis point. */
+  priceImpactHbps: number;
+  feeAmount: BN;
+  protocolFeeAmount: BN;
+  /** Minimum amount_out to pass to the swap ix given the quoted slippage. */
+  minAmountOut: BN;
+  /** Variable sell-off surge fee taken from the output. `0` when no surge. */
+  surgeFeeAmount: BN;
+  /** Static fee (in PERCENT_SCALE units) + surge pct, for UI display. */
+  effectiveFeePct: number;
+  /** Post-trade window fill in PERCENT_SCALE units. `0` when window disabled. */
+  windowFillPct: number;
+}
+
+export interface AddLiquidityParams {
+  user: PublicKey;
+  /**
+   * Per-token spend CEILING, one entry per pool token, in raw units.
+   *
+   * ⚠ As of v5.1 (audit M-4 / I-1) this is an upper bound, **not** an exact
+   * amount. The program computes the largest strictly-proportional basket
+   * that fits inside this vector, deposits that, and leaves the rest in the
+   * user's wallet. Passing `[100, 100]` to a 1:9 pool deposits `[11, 100]`,
+   * not `[100, 100]`.
+   *
+   * Consequences for callers:
+   *  - Do not render these as "amount you will deposit". Show the quoted
+   *    proportional basket and treat this vector as a spend limit.
+   *  - Balance checks should validate against the ceiling (that is the most
+   *    that can be pulled), but post-tx accounting must read the
+   *    `LiquidityAdded` event's `tokenAmounts` for what actually moved.
+   *  - Length must equal `pool.tokenCount` or the program reverts with
+   *    `InvalidArrayLength` (6064).
+   */
+  tokenAmounts: BN[];
+  /**
+   * Slippage floor on BPT minted. Required and must be > 0 — this is the
+   * only guard on the join, since `tokenAmounts` is now a ceiling rather
+   * than a commitment.
+   */
+  minimumBptAmount?: BN;
+}
+
+/**
+ * Result of `CubicPoolClient.quoteAddLiquidity`. Mirrors
+ * `cubic-pool/add_liquidity.rs`: the program crops the caller's ceiling
+ * vector to the single limiting ratio `min_i(amount_i / actual_i)`, pulls
+ * `depositAmounts` and leaves `refundAmounts` in the wallet.
+ */
+export interface AddLiquidityQuote {
+  /** The ceiling vector that was quoted (echo of the input). */
+  tokenAmounts: BN[];
+  /** What the program will actually pull per token (proportional basket). */
+  depositAmounts: BN[];
+  /** `tokenAmounts - depositAmounts`; stays in the user's wallet. */
+  refundAmounts: BN[];
+  /** BPT the program will mint for this basket at the synced state. */
+  bptOut: BN;
+  /** `bptOut` after the quoted slippage; pass as `minimumBptAmount`. */
+  minimumBptAmount: BN;
+  /** Index of the token that limits the basket (smallest amount/balance). */
+  limitingTokenIndex: number;
+}
+
+export interface RemoveLiquidityParams {
+  user: PublicKey;
+  bptAmount: BN;
+  minimumTokenAmounts?: BN[];
+}
+
+/**
+ * Single-token deposit ("zap"): deposit one token, the helper swaps it into
+ * the pool's proportions and joins on your behalf.
+ *
+ * Supported on pools of up to 10 tokens as of v5.1 (was 5 — the old cap was
+ * a heap-exhaustion limit, audit SF-3). Beyond 10 the program rejects with
+ * `PoolTooLargeForZap`.
+ *
+ * This deployed build does not account for Token-2022 transfer fees. The SDK
+ * rejects transfer-fee mints and other runtime-incompatible extensions before
+ * building a deposit. Plain Token-2022 mints and compatible extensions work.
+ */
+export interface SingleTokenDepositParams {
+  user: PublicKey;
+  tokenInIndex: number;
+  amountIn: BN;
+  /**
+   * Used only by the off-chain quote to derive `minimumBptAmount`. There is
+   * no per-call slippage argument on the instruction any more — the single
+   * `minimumBptAmount` floor bounds the entire zap, and per-leg swaps run
+   * with `min_out = 0` (which is what keeps the route correct under the
+   * path-dependent surge fee).
+   */
+  slippageHundredthsBps?: number;
+  /**
+   * Required, must be > 0. The only slippage guard on the whole route:
+   * internal swaps + surge fees + the join.
+   */
+  minimumBptAmount?: BN;
+}
+
+/** Quote includes the helperBalances supplied to the quote call, or assumes
+ * zero balances when omitted. Re-read helper ATAs and pool state before signing. */
+export interface SingleTokenDepositQuote {
+  tokenInIndex: number;
+  amountIn: BN;
+  /** Per-token allocations (sum = amountIn). */
+  allocations: BN[];
+  /** Per-leg expected swap out. `0` for sidelined tokens. */
+  expectedOuts: BN[];
+  /** Per-leg min_out derived from slippage. */
+  minOuts: BN[];
+  /** Estimated actual pool credits after both helper and pool proportional cropping. */
+  depositedAmounts: BN[];
+  /** Helper-held excess returned to the user after add_liquidity. */
+  refundAmounts: BN[];
+  /** Projected new BPT from the complete swap-and-join sequence at quoted state/time. */
+  estimatedBpt: BN;
+  /** Indices of tokens excluded from the deposit (actBal == 0). */
+  sidelinedTokenIndices: number[];
+}
+
+export interface BuiltTx {
+  instructions: TransactionInstruction[];
+  /** Accounts that should sign (user is implicit). */
+  extraSigners?: PublicKey[];
+  /** Suggested CU limit — caller decides whether to prepend ComputeBudget ix. */
+  suggestedCuLimit: number;
+}
+
+export interface DeployPoolParams {
+  payer: PublicKey;
+  configKey: PublicKey;
+  poolId: BN;
+  /**
+   * Pool's token mints, in the same order as `weightsBps`/`virtualBalances`.
+   * There is no `tokens` field in the on-chain `initialize_cubic_pool` ix
+   * data — the program derives the token set solely from remaining_accounts
+   * (one mint per token). The SDK still requires this array so it can build
+   * that remaining_accounts list in the right order.
+   */
+  tokens: PublicKey[];
+  weightsBps: number[];
+  virtualBalances: BN[];
+  swapFeeRate: number;
+  /** SPL Token program to use for the BPT mint (classic SPL Token recommended). */
+  bptTokenProgram?: PublicKey;
+  /**
+   * Optional creator-chosen Token-2022 banned-extensions bitmap. Omit
+   * (`undefined`/`null`) to inherit the config default. Set a bitmap to vet
+   * THIS pool's tokens against it and store it on the pool. `0` clears the
+   * configurable default; the hard floor and runtime restrictions still apply.
+   *
+   * ⚠ A permissive policy (un-banning PermanentDelegate / TransferHook /
+   * TransferFee) makes the pool drainable/abusable by the token issuer —
+   * surface this to the user before deploying.
+   */
+  bannedExtensions?: BN | number | null;
+}
+
+// ============================================================
+// Range manager
+// ============================================================
+
+/**
+ * One compare-and-swap entry in a `range_manager_update`.
+ *
+ * ⚠ `expectedCurrent` was inserted **between** `index` and `newValue` in
+ * v5.1 (audit M-6). It is not optional padding and it is not appended at
+ * the end: the on-chain struct is `{ index: u8, expected_current: u64,
+ * new_value: u64 }` in exactly that order.
+ */
+export interface TokenChange {
+  /** Token index within the pool, `0 .. tokenCount-1`. */
+  index: number;
+  /**
+   * The value the caller believes is currently stored for this token —
+   * `virtualBalance` for a `vbChanges` entry, `weightBps` (as a BN) for a
+   * `weightChanges` entry.
+   *
+   * The program compares this against the live value and reverts the whole
+   * instruction with `RangeManagerStaleValue` (6061) on any mismatch. This
+   * makes every update a compare-and-swap: two managers racing, or a bot
+   * replaying a stale quote, can no longer clobber each other's writes.
+   *
+   * It must come from the same pool read that produced `newValue`. Do not
+   * synthesise it, and do not carry it across a re-read — on a stale
+   * failure, re-read the pool and recompute both fields together.
+   */
+  expectedCurrent: BN;
+  /** The value to write if `expectedCurrent` still matches. */
+  newValue: BN;
+}
+
+export interface RangeManagerUpdateParams {
+  /** Must be the pool's configured `range_manager` and it must be enabled. */
+  authority: PublicKey;
+  /** Sparse virtual-balance changes. May be empty. */
+  vbChanges?: TokenChange[];
+  /**
+   * Sparse normalized-weight changes (basis points). May be empty. The
+   * resulting weight vector must still sum to 10_000.
+   */
+  weightChanges?: TokenChange[];
+}
+
+export interface SetRangeManagerParams {
+  /**
+   * Pool's governance config account. New in v5.1 (audit L-1) — it is
+   * PREPENDED before `pool` in the account list.
+   */
+  config: PublicKey;
+  /** Pool admin, or config protocol admin for disable-only with the same manager. */
+  authority: PublicKey;
+  /** Pubkey allowed to call `range_manager_update`. */
+  newManager: PublicKey;
+  /** Gate flag; `false` blocks the manager even when the pubkey is set. */
+  enabled: boolean;
+}
+
+export interface SetRangeManagerConfigParams {
+  /** Pool-admin only. */
+  authority: PublicKey;
+  /** Max per-update virtual-balance change, `PERCENT_SCALE` (10_000 = 100%). */
+  maxVbChangePct: number;
+  /** Max per-update weight change, same units. */
+  maxWeightChangePct: number;
+  minUpdateIntervalSecs: number;
+  /**
+   * Absolute UPPER bound on `virtual_balance / actual_balance`, in basis
+   * points (10_000 = 1.0×). `0` disables the band. New in v5.1 (M-2/SF-20).
+   *
+   * The per-update percentage caps velocity, not distance — 5% steps
+   * compound to ~131× in 100 updates. This is the distance limit.
+   */
+  maxLeverageBps: number;
+  /**
+   * Absolute LOWER bound on the same ratio, same units. `0` disables the
+   * floor. New in v5.1.
+   */
+  minLeverageBps: number;
+}
+
+/** Per-token sell-off policy, in pool order. Percent fields use 10,000 = 100%,
+ * except feeKinkPct, which is a whole percent (0 disables the kink).
+ */
+export interface SelloffParams {
+  maxSelloffPct: number;
+  periodLength: number;
+  feeThresholdPct: number;
+  feeSlopeLowPct: number;
+  feeSlopeHighPct: number;
+  feeSlopeMidPct: number;
+  feeKinkPct: number;
+}

package/src/utils/errors.ts

@@ -0,0 +1,210 @@
+import cubicPoolIdl from "../idl/cubic_pool.json";
+import protocolAdminIdl from "../idl/protocol_admin.json";
+import singleTokenLiquidityIdl from "../idl/single_token_liquidity.json";
+import { SdkError, SdkErrorCode } from "../types/result";
+
+/**
+ * Which on-chain program produced an error code.
+ *
+ * Anchor numbers every program's errors from 6000, so a bare custom-error
+ * code is ambiguous across the three Coffer programs — `6030` is
+ * `InvalidTokenProgram` in cubic-pool but `TokenExtensionsUnsupported` in
+ * single-token-liquidity. Pass this to {@link toSdkError} when you know
+ * which program the failing instruction belonged to; without it the
+ * cubic-pool table is used, which is the right default for swap / add /
+ * remove but WRONG for a zap or an admin call.
+ */
+export type CofferProgram = "cubicPool" | "singleTokenLiquidity" | "protocolAdmin";
+
+const ANCHOR_NAME_TO_SDK: Record<string, SdkErrorCode> = {
+  InvalidTokenCount: "invalid_input",
+  InvalidTokenIndex: "invalid_input",
+  InvalidWeights: "invalid_input",
+  InvalidVirtualBalances: "invalid_input",
+  InsufficientLiquidity: "insufficient_funds",
+  SlippageExceeded: "slippage_exceeded",
+  InvalidAmounts: "invalid_input",
+  InsufficientBptOut: "slippage_exceeded",
+  InsufficientTokensOut: "slippage_exceeded",
+  FeeRateMaxExceeded: "invalid_input",
+  ProtocolFeeRateMaxExceeded: "invalid_input",
+  MathOverflow: "math_overflow",
+  MathUnderflow: "math_overflow",
+  DivisionByZero: "math_overflow",
+  TokenMintMismatch: "invalid_input",
+  InvalidTokenDecimals: "invalid_input",
+  AmountOutExceedsBalance: "invalid_input",
+  InvalidBptAmount: "invalid_input",
+  Unauthorized: "invalid_input",
+  InvalidMint: "invalid_input",
+  PoolDisabled: "pool_disabled",
+  SwapsDisabled: "swaps_disabled",
+  MaxSelloffExceeded: "selloff_window_full",
+  TokenInactive: "token_swaps_disabled",
+  PoolMustBeDisabled: "invalid_input",
+  ZeroAmount: "invalid_input",
+  ZeroFeeAmount: "invalid_input",
+  BannedExtension: "invalid_input",
+  TokenProgramMismatch: "invalid_input",
+  UserTokenAccountOwnerMismatch: "invalid_input",
+  InitialLiquidityTooSmall: "invalid_input",
+  InvalidTokenProgram: "invalid_input",
+  InvalidVault: "invalid_input",
+  InvalidSourceOwner: "invalid_input",
+  WouldBreakRentExempt: "invalid_input",
+  PoolAdminDisabled: "invalid_input",
+  ProtocolAdminUnset: "invalid_input",
+  NoPendingAdmin: "invalid_input",
+  NotPendingAdmin: "invalid_input",
+  InvalidPendingAdmin: "invalid_input",
+  ProtocolAdminNotTreasury: "invalid_input",
+
+  // ── cubic-pool 6055–6068, new in v5.1 ────────────────────────────────
+  /** Mint carries a Token-2022 extension this pool's policy forbids. */
+  UnsupportedExtension: "invalid_input",
+  /** Destination requires a memo — include the SPL Memo program account. */
+  MemoProgramMissing: "invalid_input",
+  TransferFeeCalculationMismatch: "invalid_input",
+  /** The whole deposit was eaten by the mint's transfer fee. */
+  AmountFullyConsumedByTransferFee: "invalid_input",
+  /** Only `pool.pool_admin` may make a pool's first (seed) deposit. */
+  SeedDepositNotPoolAdmin: "auth_failed",
+  StldTokenExtensionsUnsupported: "unsupported_pool_state",
+  /**
+   * Compare-and-swap guard on `range_manager_update` failed: the pool moved
+   * between the read and the write. The bot must re-read the pool and retry
+   * with fresh `expectedCurrent` values — it is a retryable race, not a
+   * permanent rejection.
+   */
+  RangeManagerStaleValue: "invalid_input",
+  RangeManagerLeverageBandExceeded: "invalid_input",
+  RangeManagerOverrideMustDisable: "auth_failed",
+  /** An array argument's length != the pool's `token_count`. */
+  InvalidArrayLength: "invalid_input",
+  FirstDepositRequiresNonzero: "invalid_input",
+  TokenLivenessMismatch: "invalid_input",
+  /** Deposit too small to mint a single unit of BPT — increase the amount. */
+  DepositTooSmall: "invalid_input",
+  /** Pool holds no liquidity yet; the pool admin must seed it first. */
+  PoolNotSeeded: "unsupported_pool_state",
+
+  // ── protocol-admin ───────────────────────────────────────────────────
+  /** New admin cannot be the all-zero pubkey. */
+  InvalidAdmin: "invalid_input",
+
+  // ── single-token-liquidity 6030–6032, new in v5.1 ────────────────────
+  /** Zap route can't carry an armed transfer hook's extra accounts. */
+  TokenExtensionsUnsupported: "unsupported_pool_state",
+  InsufficientHelperSol: "insufficient_funds",
+  /** Pool exceeds `STLD_MAX_TOKENS` (10) — use `add_liquidity` instead. */
+  PoolTooLargeForZap: "unsupported_pool_state",
+};
+
+type AnchorIdlError = { code: number; name: string; msg: string };
+type ErrorTable = Record<number, { code: SdkErrorCode; message: string; name: string }>;
+
+function buildErrorTable(errors: AnchorIdlError[]): ErrorTable {
+  return Object.fromEntries(
+    errors.map((anchorError) => [
+      anchorError.code,
+      {
+        code: ANCHOR_NAME_TO_SDK[anchorError.name] ?? "invalid_input",
+        message: anchorError.msg,
+        name: anchorError.name,
+      },
+    ])
+  );
+}
+
+const ERROR_TABLES: Record<CofferProgram, ErrorTable> = {
+  cubicPool: buildErrorTable(cubicPoolIdl.errors as AnchorIdlError[]),
+  protocolAdmin: buildErrorTable(protocolAdminIdl.errors as AnchorIdlError[]),
+  singleTokenLiquidity: buildErrorTable(singleTokenLiquidityIdl.errors as AnchorIdlError[]),
+};
+
+const CONTRACT_ERROR_MAP = ERROR_TABLES.cubicPool;
+
+/**
+ * Convert a raw error (possibly from Anchor, web3.js, or fetch) into a
+ * cleanly-typed SdkError. Used by safeCall wrappers so callers always
+ * get structured errors, never exceptions.
+ *
+ * @param program Which Coffer program the failing instruction belonged to.
+ *   Anchor numbers each program's errors from 6000 independently, so the
+ *   same code means different things in different programs. Defaults to
+ *   `"cubicPool"` (correct for swap / add / remove liquidity). Pass
+ *   `"singleTokenLiquidity"` for zap failures and `"protocolAdmin"` for
+ *   treasury-routed admin calls, or the message will be plausible and wrong.
+ */
+export function toSdkError(cause: unknown, program: CofferProgram = "cubicPool"): SdkError {
+  // Anchor-encoded program errors
+  const msg = extractMessage(cause);
+  const code = extractErrorCode(msg);
+  const table = ERROR_TABLES[program] ?? CONTRACT_ERROR_MAP;
+  if (code !== null && table[code]) {
+    return {
+      code: table[code].code,
+      humanMessage: table[code].message,
+      cause,
+    };
+  }
+  // Common network strings
+  if (/timed? ?out|ETIMEDOUT/i.test(msg)) {
+    return { code: "rpc_timeout", humanMessage: "RPC timed out", cause };
+  }
+  if (/429|rate limit/i.test(msg)) {
+    return { code: "rpc_rate_limited", humanMessage: "RPC rate-limited - slow down", cause };
+  }
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND|Proxy error|-32056|-32052|403/i.test(msg)) {
+    return { code: "rpc_unavailable", humanMessage: "RPC endpoint unreachable", cause };
+  }
+  if (/Account does not exist|account not found/i.test(msg)) {
+    return { code: "account_not_found", humanMessage: "Account does not exist on-chain", cause };
+  }
+  if (/insufficient funds/i.test(msg)) {
+    return { code: "insufficient_funds", humanMessage: "Insufficient funds for this operation", cause };
+  }
+  return { code: "unknown", humanMessage: msg || "Unknown error", cause };
+}
+
+function extractMessage(e: unknown): string {
+  if (!e) return "";
+  if (typeof e === "string") return e;
+  if (e instanceof Error) return e.message;
+  if (typeof e === "object" && e !== null && "message" in e) {
+    return String((e as { message?: string }).message ?? "");
+  }
+  try {
+    return JSON.stringify(e);
+  } catch {
+    return String(e);
+  }
+}
+
+function extractErrorCode(msg: string): number | null {
+  // Anchor error format: "custom program error: 0x1774"
+  const hex = msg.match(/custom program error: 0x([0-9a-fA-F]+)/);
+  if (hex) return parseInt(hex[1], 16);
+  // Anchor SDK format: "Error Number: 6007"
+  const dec = msg.match(/Error Number:\s*(\d+)/);
+  if (dec) return parseInt(dec[1], 10);
+  return null;
+}
+
+/** @internal Exported for tests */
+export function contractErrorMapForTests(program: CofferProgram = "cubicPool"): ErrorTable {
+  return ERROR_TABLES[program];
+}
+
+/**
+ * Look up a program error by its numeric code without needing an exception
+ * to parse. Returns `undefined` for codes the program does not define.
+ */
+export function describeProgramError(
+  code: number,
+  program: CofferProgram = "cubicPool"
+): { name: string; message: string; sdkCode: SdkErrorCode } | undefined {
+  const hit = ERROR_TABLES[program]?.[code];
+  if (!hit) return undefined;
+  return { name: hit.name, message: hit.message, sdkCode: hit.code };
+}