sally-defi-ts-sdk 0.3.2

package/src/deployment.ts

@@ -0,0 +1,132 @@
+/**
+ * Single source of truth loader.
+ *
+ * All addresses and ABIs come from the bundled `deployment.json` (addresses +
+ * ABIs only, derived from the contracts' deployment artifact). Nothing is
+ * hard-coded here — if the deployment changes, drop in a new JSON and everything
+ * downstream follows.
+ *
+ * The `_guide` header of that file documents the v2.0.2 routing model:
+ *
+ * - The frontend (and this SDK) only ever calls the **two proxies**.
+ * - Every *Lens* view is callable through the **SwapController proxy** via a
+ *   read-only fallback, and every *Sidecar* view through the **LiquidityController
+ *   proxy**. So we bind the Lens ABI to the swap-proxy address and the Sidecar ABI
+ *   to the liq-proxy address — no separate Lens/Sidecar address needed at runtime.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export type AbiItem = Record<string, any>;
+export type Abi = AbiItem[];
+
+export const DEPLOYMENT_FILE = "deployment.json";
+
+// Friendly chain aliases -> the key used inside the deployment JSON.
+const CHAIN_ALIASES: Record<string, string> = {
+  base: "base",
+  "8453": "base",
+  bsc: "bsc",
+  binance: "bsc",
+  bnb: "bsc",
+  "56": "bsc",
+};
+
+let _rawCache: Record<string, any> | null = null;
+
+/** Parse and cache the bundled deployment JSON. */
+function raw(): Record<string, any> {
+  if (_rawCache === null) {
+    const path = fileURLToPath(new URL("./data/deployment.json", import.meta.url));
+    _rawCache = JSON.parse(readFileSync(path, "utf-8")) as Record<string, any>;
+  }
+  return _rawCache;
+}
+
+/** Release tag of the bundled deployment, e.g. `v2.0.2`. */
+export function release(): string {
+  return raw()["_guide"]["release"];
+}
+
+/** Canonical chain keys present in the deployment (`base`, `bsc`). */
+export function supportedChains(): string[] {
+  return Object.keys(raw()["chains"]);
+}
+
+/** Map an alias / chain-id to the canonical deployment key. */
+export function normalizeChain(chain: string | number): string {
+  const key = CHAIN_ALIASES[String(chain).toLowerCase()];
+  if (key === undefined) {
+    const supported = [...new Set(Object.keys(CHAIN_ALIASES))].sort();
+    throw new Error(`Unknown chain ${JSON.stringify(chain)}. Supported: ${JSON.stringify(supported)}`);
+  }
+  return key;
+}
+
+/** Raw deployment node for one chain. */
+export function chain(chainKey: string | number): Record<string, any> {
+  return raw()["chains"][normalizeChain(chainKey)];
+}
+
+export function chainId(chainKey: string | number): number {
+  return Number(chain(chainKey)["chainId"]);
+}
+
+// --------------------------------------------------------------------------- //
+// Addresses
+// --------------------------------------------------------------------------- //
+/**
+ * All well-known addresses for a chain, checksummed by the caller.
+ *
+ * `lens` and `sidecar` map to the *proxy* addresses on purpose: in v2.0.2 their
+ * views are served through the proxies via fallback. The dedicated Lens/Sidecar
+ * addresses are exposed separately as `lens_direct` / `sidecar_direct` for the
+ * rare case you want to bypass the proxy.
+ */
+export function addresses(chainKey: string | number): Record<string, string> {
+  const c = chain(chainKey);
+  const swapProxy: string = c["swapController"]["proxy"];
+  const liqProxy: string = c["liquidityController"]["proxy"];
+  const out: Record<string, string> = {
+    swap: swapProxy,
+    liquidity: liqProxy,
+    lens: swapProxy, // Lens views via swap proxy fallback
+    sidecar: liqProxy, // Sidecar views via liq proxy fallback
+    treasury: c["treasury"],
+    lens_direct: c["lens"]["address"],
+    sidecar_direct: c["liquidityController"]["liqUtilsSidecar"],
+    swap_impl: c["swapController"]["impl"],
+    liquidity_impl: c["liquidityController"]["impl"],
+  };
+  if ("utilsV4" in c) {
+    out["utils_v4"] = c["utilsV4"];
+  }
+  return out;
+}
+
+// --------------------------------------------------------------------------- //
+// ABIs
+// --------------------------------------------------------------------------- //
+/**
+ * Return the ABI for a logical component.
+ *
+ * Components: `swap`, `liquidity`, `lens`, `sidecar`, `treasury`.
+ */
+export function abi(chainKey: string | number, component: string): Abi {
+  const c = chain(chainKey);
+  switch (component) {
+    case "swap":
+      return c["swapController"]["abi"];
+    case "liquidity":
+      return c["liquidityController"]["abi"];
+    case "lens":
+      return c["lens"]["abi"];
+    case "sidecar":
+      return c["liquidityController"]["liqUtilsSidecarAbi"];
+    case "treasury":
+      return c["treasuryAbi"];
+    default:
+      throw new Error(`Unknown ABI component ${JSON.stringify(component)}`);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,215 @@
+/**
+ * Typed errors and on-chain revert decoding.
+ *
+ * ethers surfaces a reverting call as a `CALL_EXCEPTION` carrying the raw revert
+ * `data` (4-byte selector + payload) but does not always decode custom Solidity
+ * errors against an ABI it doesn't know. We build a `selector -> error-ABI` table
+ * from every Sally ABI so a revert turns into a readable {@link SallyRevert} with
+ * the error name and decoded args instead of an opaque hex blob.
+ */
+
+import { AbiCoder, ErrorFragment } from "ethers";
+import * as deployment from "./deployment.js";
+
+export class SallyError extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = "SallyError";
+  }
+}
+
+/** Bad/missing configuration (no signer, unknown chain, …). */
+export class SallyConfigError extends SallyError {
+  constructor(message?: string) {
+    super(message);
+    this.name = "SallyConfigError";
+  }
+}
+
+/**
+ * A swap route failed an integrity check (mismatched/wrong-pool path).
+ *
+ * Raised *before* any funds move when a quoted route would send tokens through a
+ * path that does not start at `tokenIn` / end at `tokenOut` or whose hops do not
+ * chain — i.e. the guard against funds landing in the wrong pool.
+ */
+export class SallyRouteError extends SallyError {
+  constructor(message?: string) {
+    super(message);
+    this.name = "SallyRouteError";
+  }
+}
+
+/**
+ * A safety preflight blocked the swap (honeypot, excessive tax, impact).
+ */
+export class SallySafetyError extends SallyError {
+  readonly reasons: string[];
+
+  constructor(message: string, reasons: string[] | null = null) {
+    super(message);
+    this.name = "SallySafetyError";
+    this.reasons = reasons ?? [];
+  }
+}
+
+/**
+ * An on-chain call/transaction reverted.
+ *
+ * Public fields mirror the Python `SallyRevert` 1:1:
+ *  - `name`: decoded custom-error name (or `Error` / `Panic` / `"SallyRevert"`
+ *    when unknown — Python uses `None` there; JS keeps a string for branding).
+ *  - `argsDecoded`: decoded error arguments (Python `args_decoded`).
+ *  - `selector`: the 4-byte selector hex.
+ *  - `message`: the raw `Error(string)` / panic message (Python `.message`).
+ *
+ * `toString()` produces Python's `str(exc)` form: `"<name>: <detail>"`.
+ */
+export class SallyRevert extends SallyError {
+  readonly argsDecoded: readonly any[];
+  readonly selector: string | null;
+  private readonly _label: string;
+
+  constructor(
+    name: string | null,
+    args: readonly any[] = [],
+    selector: string | null = null,
+    message: string | null = null,
+  ) {
+    // Error.message holds the raw revert message (Python `.message`), or "".
+    super(message ?? "");
+    // Python sets `self.name` to the decoded error name; keep a string for JS.
+    this.name = name ?? "SallyRevert";
+    this.argsDecoded = args;
+    this.selector = selector;
+    this._label = name || "revert";
+  }
+
+  override toString(): string {
+    const detail = this.message ? this.message : this.argsDecoded.length ? formatArgs(this.argsDecoded) : "";
+    return `${this._label}${detail ? ": " + detail : ""}`;
+  }
+}
+
+function formatArgs(args: readonly any[]): string {
+  return `(${args.map((a) => (typeof a === "bigint" ? a.toString() : String(a))).join(", ")})`;
+}
+
+// Standard selectors defined by Solidity itself.
+const ERROR_STRING = "0x08c379a0"; // Error(string)
+const PANIC = "0x4e487b71"; // Panic(uint256)
+
+const PANIC_CODES: Record<number, string> = {
+  0x01: "assert(false)",
+  0x11: "arithmetic overflow/underflow",
+  0x12: "division or modulo by zero",
+  0x21: "invalid enum conversion",
+  0x22: "incorrectly encoded storage byte array",
+  0x31: "pop on empty array",
+  0x32: "array index out of bounds",
+  0x41: "out of memory",
+  0x51: "call to invalid internal function",
+};
+
+const _tableCache = new Map<string, Map<string, Record<string, any>>>();
+
+/** Map `0x<selector>` -> error ABI across all components of a chain. */
+function selectorTable(chainKey: string): Map<string, Record<string, any>> {
+  const cached = _tableCache.get(chainKey);
+  if (cached) return cached;
+  const table = new Map<string, Record<string, any>>();
+  for (const component of ["swap", "liquidity", "lens", "sidecar", "treasury"]) {
+    for (const item of deployment.abi(chainKey, component)) {
+      if (item["type"] !== "error") continue;
+      let sel: string;
+      try {
+        sel = ErrorFragment.from(item).selector.toLowerCase();
+      } catch {
+        continue;
+      }
+      if (!table.has(sel)) table.set(sel, item);
+    }
+  }
+  _tableCache.set(chainKey, table);
+  return table;
+}
+
+const coder = AbiCoder.defaultAbiCoder();
+
+/** Turn raw revert `data` (0x-hex) into a typed {@link SallyRevert}. */
+export function decodeRevert(chainKey: string, data: string | null | undefined): SallyRevert {
+  if (!data || !data.startsWith("0x") || data.length < 10) {
+    return new SallyRevert(null, [], data ?? null);
+  }
+
+  const selector = data.slice(0, 10).toLowerCase();
+  const payload = "0x" + data.slice(10);
+
+  if (selector === ERROR_STRING) {
+    let msg: string | null = null;
+    try {
+      msg = String(coder.decode(["string"], payload)[0]);
+    } catch {
+      msg = null;
+    }
+    return new SallyRevert("Error", [], selector, msg);
+  }
+
+  if (selector === PANIC) {
+    let msg: string | null = null;
+    try {
+      const code = Number(coder.decode(["uint256"], payload)[0]);
+      msg = PANIC_CODES[code] ?? `panic 0x${code.toString(16).padStart(2, "0")}`;
+    } catch {
+      msg = null;
+    }
+    return new SallyRevert("Panic", [], selector, msg);
+  }
+
+  const err = selectorTable(chainKey).get(selector);
+  if (err !== undefined) {
+    const types = (err["inputs"] ?? []).map((i: Record<string, any>) => i["type"]);
+    let args: any[] = [];
+    if (types.length) {
+      try {
+        args = [...coder.decode(types, payload)];
+      } catch {
+        args = [];
+      }
+    }
+    return new SallyRevert(err["name"], args, selector);
+  }
+
+  return new SallyRevert(null, [], selector);
+}
+
+/** Extract raw revert data (0x-hex) from the many shapes ethers throws. */
+function extractRevertData(exc: any): string | null {
+  if (exc == null) return null;
+  const candidates = [
+    exc.data,
+    exc.info?.error?.data,
+    exc.error?.data,
+    exc.error?.error?.data,
+    exc.revert?.data,
+  ];
+  for (const c of candidates) {
+    if (typeof c === "string" && c.startsWith("0x")) return c;
+  }
+  return null;
+}
+
+/** Convert an ethers contract error into a {@link SallyRevert} if possible. */
+export function wrapWeb3Error(chainKey: string, exc: any): SallyError {
+  const data = extractRevertData(exc);
+  if (data) {
+    return decodeRevert(chainKey, data);
+  }
+  // CALL_EXCEPTION without decodable data, or a plain require-string revert.
+  const code = exc?.code;
+  if (code === "CALL_EXCEPTION") {
+    const msg = exc?.reason ?? exc?.shortMessage ?? exc?.message ?? String(exc);
+    return new SallyRevert("Error", [], null, msg);
+  }
+  return new SallyError(exc?.message ?? String(exc));
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Sally DeFi SDK — one client for CrossHybrid swaps & liquidity on Base + BSC.
+ *
+ * Fully on-chain: every read (prices, routes, positions, balances, honeypot
+ * screen) is a direct `eth_call` to the contracts. No Sally API, no Graph Node /
+ * subgraph, no indexer, no backend — the only thing in the data path is your RPC
+ * and the chain.
+ *
+ * Quickstart:
+ * ```ts
+ * import { SallyClient, Base } from "sally-defi-ts-sdk";
+ * const sally = new SallyClient("base", "https://mainnet.base.org");
+ * (await sally.prices.usd(Base.USDC)).asFloat;          // display price
+ * const quote = await sally.swap.quote(Base.WETH, Base.USDC, 10n ** 18n);
+ * quote.estimatedAmountOut;
+ * ```
+ *
+ * To send transactions, give the client a signer:
+ * ```ts
+ * const sally = new SallyClient("base", RPC, { privateKey: "0x…" });
+ * await sally.swap.execute(Base.WETH, Base.USDC, 10n ** 17n, { slippageBps: 50 });
+ * ```
+ *
+ * Everything reads from the bundled `deployment.json` (addresses + ABIs only,
+ * derived from the contracts' deployment artifact). Addresses/ABIs are never
+ * hard-coded.
+ */
+
+export const __version__ = "0.3.2";
+
+import * as constants from "./constants.js";
+import * as deployment from "./deployment.js";
+
+export { constants, deployment };
+
+export { SallyClient } from "./client.js";
+export type { SallyClientOptions } from "./client.js";
+export {
+  SallyConfigError,
+  SallyError,
+  SallyRevert,
+  SallyRouteError,
+  SallySafetyError,
+  decodeRevert,
+  wrapWeb3Error,
+} from "./errors.js";
+export { PERMIT2_ADDRESS, Permit2, signPermit2612, signPermitSingle } from "./permit2.js";
+export { SwapBuild, TxPreview } from "./previews.js";
+export { RouteCandidate, SafetyConfig, SwapPlan } from "./safety.js";
+export type { SafetyConfigFields } from "./safety.js";
+export {
+  ERC20_ABI,
+  MAX_UINT256,
+  NATIVE,
+  Token,
+  TokenAmount,
+  ZERO,
+  humanToRaw,
+  isNative,
+  rawToHuman,
+} from "./token.js";
+export {
+  ClaimableFees,
+  Lock,
+  LockKind,
+  PoolVersion,
+  PriceResult,
+  ReferralFeeTokens,
+  SwapPath,
+  SwapStep,
+  TokenInfo,
+  V2PoolState,
+  V2Position,
+  V3PoolState,
+  V3Position,
+  V4PoolState,
+  V4Position,
+  WalletBalance,
+} from "./types.js";
+
+// Convenience re-exports of the well-known token tables.
+export { Base, Bsc, NATIVE_TOKEN, PrivateRelays, ZERO_ADDRESS } from "./constants.js";
+
+// Module namespace classes (so callers can type their handles if they wish).
+export { Prices } from "./modules/prices.js";
+export { Swap } from "./modules/swap.js";
+export { Wallet } from "./modules/wallet.js";
+export { Liquidity } from "./modules/liquidity.js";
+export { Fees } from "./modules/fees.js";
+export type { ExecuteOptions } from "./modules/swap.js";

package/src/modules/fees.ts

@@ -0,0 +1,78 @@
+/**
+ * Referral & batch-fee accounting (SwapController side).
+ *
+ * Both controllers track referral/batch fees independently. This namespace reads
+ * and claims on the **swap** controller; the liquidity controller's equivalents
+ * live on `client.liquidity` (`claimReferralFees` / `claimBatchFees`).
+ */
+
+import { Contract, getAddress } from "ethers";
+import type { SallyClient } from "../client.js";
+import { ReferralFeeTokens } from "../types.js";
+
+export class Fees {
+  private _c: SallyClient;
+  private _swap: Contract;
+
+  constructor(client: SallyClient) {
+    this._c = client;
+    this._swap = client.swapContract;
+  }
+
+  private _a(x: string): string {
+    return getAddress(x);
+  }
+
+  // -- reads ------------------------------------------------------------- //
+  async referralTokenCount(user: string): Promise<number> {
+    return Number(await this._c.call(this._swap.getFunction("getReferralFeeTokenCount"), [this._a(user)]));
+  }
+
+  /**
+   * Paged referral-fee balances. `getReferralFeeTokens(user, start, stop)`.
+   *
+   * `stop=0` auto-resolves to the current max index.
+   */
+  async referralTokens(user: string, start = 0, stop = 0): Promise<ReferralFeeTokens> {
+    if (stop === 0) {
+      stop = Math.max(await this.referralTokenCount(this._a(user)), 1);
+    }
+    const r = await this._c.call(this._swap.getFunction("getReferralFeeTokens"), [this._a(user), start, stop]);
+    return ReferralFeeTokens.fromRaw(r);
+  }
+
+  async totalReferralOwed(user: string): Promise<bigint> {
+    return BigInt(await this._c.call(this._swap.getFunction("totalReferralOwed"), [this._a(user)]));
+  }
+
+  async referralFee(user: string, token: string): Promise<bigint> {
+    return BigInt(await this._c.call(this._swap.getFunction("referralFees"), [this._a(user), this._a(token)]));
+  }
+
+  async batchFee(token: string): Promise<bigint> {
+    return BigInt(await this._c.call(this._swap.getFunction("batchFees"), [this._a(token)]));
+  }
+
+  async feeBasisPoints(): Promise<bigint> {
+    return BigInt(await this._c.call(this._swap.getFunction("feeBasisPoints"), []));
+  }
+
+  async feeThreshold(): Promise<bigint> {
+    return BigInt(await this._c.call(this._swap.getFunction("feeThreshold"), []));
+  }
+
+  /** Fee split for an amount. `getSwapFee(amount) -> [fee, net]`. */
+  async swapFee(amount: bigint): Promise<[bigint, bigint]> {
+    const r = await this._c.call(this._swap.getFunction("getSwapFee"), [amount]);
+    return [BigInt(r[0]), BigInt(r[1])];
+  }
+
+  // -- claims ------------------------------------------------------------ //
+  async claimReferral(tokens: string[], tx: Record<string, any> = {}): Promise<any> {
+    return this._c.send(this._swap.getFunction("claimReferralFees"), [tokens.map((t) => this._a(t))], tx);
+  }
+
+  async claimBatch(tokens: string[], tx: Record<string, any> = {}): Promise<any> {
+    return this._c.send(this._swap.getFunction("claimBatchFees"), [tokens.map((t) => this._a(t))], tx);
+  }
+}