sally-defi-ts-sdk 0.3.2

package/src/client.ts

@@ -0,0 +1,526 @@
+/**
+ * The one object users hold: {@link SallyClient}.
+ *
+ * Every read is a direct `eth_call` to the on-chain contracts through your RPC —
+ * no API, no subgraph / Graph Node, no backend in the data path.
+ *
+ * Reads work with just an RPC URL. Writes need a signer — pass a `privateKey`, a
+ * 12/24-word `mnemonic`, or an ethers `Wallet`/`HDNodeWallet`. To sign with your
+ * **own** wallet instead, pass only `address` (no key) and use the build/preview
+ * API: every action can return a fully-populated, ABI-decoded, simulated
+ * *unsigned* transaction you sign and broadcast yourself.
+ *
+ * Feature namespaces:
+ *
+ *     client.prices      USD / spot pricing + token safety
+ *     client.swap        quote + execute hybrid swaps (+ build/preview)
+ *     client.wallet      balances with live USD valuation
+ *     client.liquidity   add / remove / lock / harvest / positions
+ *     client.fees        referral + batch fee accounting
+ */
+
+import {
+  Contract,
+  HDNodeWallet,
+  JsonRpcProvider,
+  Network,
+  Wallet,
+  getAddress,
+  type Signer,
+} from "ethers";
+
+import * as deployment from "./deployment.js";
+import { SallyConfigError, SallyError, SallyRevert, wrapWeb3Error } from "./errors.js";
+import { SafetyConfig } from "./safety.js";
+import { Token } from "./token.js";
+import { TxPreview } from "./previews.js";
+import { Permit2 } from "./permit2.js";
+import { Prices } from "./modules/prices.js";
+import { Swap } from "./modules/swap.js";
+import { Wallet as WalletModule } from "./modules/wallet.js";
+import { Liquidity } from "./modules/liquidity.js";
+import { Fees } from "./modules/fees.js";
+
+// Process-wide nonce locks keyed by signer address, so concurrent sends from the
+// same account — even across different SallyClient instances — serialize.
+const _NONCE_LOCKS = new Map<string, AsyncMutex>();
+
+function lockFor(address: string | null): AsyncMutex {
+  if (address === null) return new AsyncMutex(); // read-only client: lock unused
+  const key = address.toLowerCase();
+  let lock = _NONCE_LOCKS.get(key);
+  if (!lock) {
+    lock = new AsyncMutex();
+    _NONCE_LOCKS.set(key, lock);
+  }
+  return lock;
+}
+
+/** Minimal async mutex: serialize an async critical section. */
+class AsyncMutex {
+  private _chain: Promise<void> = Promise.resolve();
+
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    const prev = this._chain;
+    let release!: () => void;
+    this._chain = new Promise<void>((res) => (release = res));
+    await prev;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+}
+
+export interface SallyClientOptions {
+  privateKey?: string | null;
+  mnemonic?: string | null;
+  accountIndex?: number;
+  account?: Signer | null;
+  address?: string | null;
+  poa?: boolean | null;
+  safety?: SafetyConfig | null;
+  privateRpcUrl?: string | null;
+  gasMultiplier?: number;
+}
+
+/** A contract method handle (from `contract.getFunction(name)`). */
+type Fn = any;
+
+export class SallyClient {
+  readonly chainKey: string;
+  readonly chainId: number;
+  safety: SafetyConfig;
+  privateRpcUrl: string | null;
+  private _privateW3: JsonRpcProvider | null = null;
+  w3: JsonRpcProvider;
+  gasMultiplier: number;
+  account: Signer | null = null;
+  protected _sender: string | null = null;
+  private _sendLock: AsyncMutex;
+  addresses: Record<string, string>;
+
+  // lazy namespace + contract caches
+  private _cache: Record<string, any> = {};
+
+  constructor(chain: string | number = "base", rpcUrl?: string | null, opts: SallyClientOptions = {}) {
+    this.chainKey = deployment.normalizeChain(chain);
+    this.chainId = deployment.chainId(this.chainKey);
+    this.safety = opts.safety ?? new SafetyConfig();
+    this.privateRpcUrl = opts.privateRpcUrl ?? process.env.SALLY_PRIVATE_RPC_URL ?? null;
+    this.gasMultiplier = opts.gasMultiplier ?? 1.25;
+
+    rpcUrl = rpcUrl ?? process.env.SALLY_RPC_URL ?? null;
+    if (!rpcUrl) {
+      throw new SallyConfigError(
+        "No rpcUrl given and SALLY_RPC_URL is unset. " +
+          "Pass rpcUrl='https://…' or set the env var.",
+      );
+    }
+    // Static network so construction never triggers a chainId auto-detect call.
+    const network = Network.from(this.chainId);
+    this.w3 = new JsonRpcProvider(rpcUrl, network, { staticNetwork: network });
+
+    // POA: ethers handles non-standard extraData natively; flag kept for parity.
+    void (opts.poa ?? this.chainKey === "bsc");
+
+    // Signer resolution: account > privateKey > mnemonic. `address` (no key)
+    // enables sign-externally mode.
+    const key = opts.privateKey ?? process.env.SALLY_PRIVATE_KEY ?? null;
+    const phrase = opts.mnemonic ?? process.env.SALLY_MNEMONIC ?? null;
+    if (opts.account != null) {
+      this.account = opts.account;
+    } else if (key) {
+      this.account = new Wallet(key);
+    } else if (phrase) {
+      const idx = opts.accountIndex ?? 0;
+      this.account = HDNodeWallet.fromPhrase(phrase, undefined, `m/44'/60'/0'/0/${idx}`);
+    }
+    this._sender = this.account
+      ? this._accountAddress(this.account)
+      : opts.address
+        ? getAddress(opts.address)
+        : null;
+    this._sendLock = lockFor(this._sender);
+
+    this.addresses = Object.fromEntries(
+      Object.entries(deployment.addresses(this.chainKey)).map(([k, v]) => [
+        k,
+        v.startsWith("0x") ? getAddress(v) : v,
+      ]),
+    );
+  }
+
+  private _accountAddress(acc: Signer): string {
+    // Wallet/HDNodeWallet expose `.address` synchronously.
+    return getAddress((acc as any).address);
+  }
+
+  // ------------------------------------------------------------------ //
+  // Connection / identity
+  // ------------------------------------------------------------------ //
+  async isConnected(): Promise<boolean> {
+    try {
+      await this.w3.getBlockNumber();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Sender address — from the signer, or the keyless `address` mode. */
+  get address(): string | null {
+    return this._sender;
+  }
+
+  get canSign(): boolean {
+    return this.account !== null;
+  }
+
+  /** The sender address (needs a signer OR keyless `address`). */
+  requireAddress(): string {
+    if (!this._sender) {
+      throw new SallyConfigError(
+        "This action needs a sender. Create the client with privateKey=…, " +
+          "mnemonic=…, or address='0x…' (sign-externally mode).",
+      );
+    }
+    return this._sender;
+  }
+
+  /** The local signing account (needs a key/mnemonic, not just `address`). */
+  requireSigner(): Signer {
+    if (this.account === null) {
+      throw new SallyConfigError(
+        "This action signs a transaction and needs a key. Pass privateKey=… " +
+          "or mnemonic=…, or use buildOnly=true / .preview() to sign externally.",
+      );
+    }
+    return this.account;
+  }
+
+  /** Return a new client on the same RPC/config but with a different signer. */
+  withAccount(privateKey: string): SallyClient {
+    const c: SallyClient = Object.create(SallyClient.prototype);
+    Object.assign(c, this);
+    (c as any).account = new Wallet(privateKey);
+    (c as any)._sender = c._accountAddress(c.account!);
+    (c as any)._sendLock = lockFor(c._sender);
+    (c as any)._privateW3 = null;
+    (c as any)._cache = {};
+    return c;
+  }
+
+  // ------------------------------------------------------------------ //
+  // Contracts (proxy-fallback aware)
+  // ------------------------------------------------------------------ //
+  private _contract(address: string, component: string): Contract {
+    return new Contract(getAddress(address), deployment.abi(this.chainKey, component) as any, this.w3);
+  }
+
+  private _cached<T>(key: string, make: () => T): T {
+    if (!(key in this._cache)) this._cache[key] = make();
+    return this._cache[key];
+  }
+
+  get swapContract(): Contract {
+    return this._cached("swapContract", () => this._contract(this.addresses["swap"], "swap"));
+  }
+
+  get liquidityContract(): Contract {
+    return this._cached("liquidityContract", () => this._contract(this.addresses["liquidity"], "liquidity"));
+  }
+
+  /** Lens ABI bound to the **swap proxy** (v2.0.2 read-fallback). */
+  get lensContract(): Contract {
+    return this._cached("lensContract", () => this._contract(this.addresses["lens"], "lens"));
+  }
+
+  /** Sidecar ABI bound to the **liq proxy** (v2.0.2 read-fallback). */
+  get sidecarContract(): Contract {
+    return this._cached("sidecarContract", () => this._contract(this.addresses["sidecar"], "sidecar"));
+  }
+
+  token(address: string): Token {
+    return new Token(this, address);
+  }
+
+  // ------------------------------------------------------------------ //
+  // Call / simulate / send
+  // ------------------------------------------------------------------ //
+  /** Execute a read (`eth_call`). Decodes reverts into SallyRevert. */
+  async call(fn: Fn, args: any[] = [], opts: { value?: bigint; sender?: string | null } = {}): Promise<any> {
+    const overrides: Record<string, any> = {};
+    if (opts.value) overrides.value = opts.value;
+    const sender = opts.sender ?? this.address;
+    if (sender) overrides.from = sender;
+    try {
+      return await fn.staticCall(...args, overrides);
+    } catch (exc) {
+      throw wrapWeb3Error(this.chainKey, exc);
+    }
+  }
+
+  /** Dry-run a state-changing call without sending (revert-safe preview). */
+  async simulate(fn: Fn, args: any[] = [], opts: { value?: bigint } = {}): Promise<any> {
+    return this.call(fn, args, { value: opts.value, sender: this.address });
+  }
+
+  async estimateGas(fn: Fn, args: any[] = [], opts: { value?: bigint } = {}): Promise<bigint> {
+    const overrides: Record<string, any> = { from: this.requireAddress() };
+    if (opts.value) overrides.value = opts.value;
+    try {
+      return BigInt(await fn.estimateGas(...args, overrides));
+    } catch (exc) {
+      throw wrapWeb3Error(this.chainKey, exc);
+    }
+  }
+
+  /** Build a fully-populated, signable EIP-1559 transaction. */
+  async buildTx(fn: Fn, args: any[] = [], opts: { value?: bigint; gas?: bigint | null } = {}): Promise<Record<string, any>> {
+    const sender = this.requireAddress();
+    const overrides: Record<string, any> = { from: sender };
+    if (opts.value) overrides.value = opts.value;
+    let tx: Record<string, any>;
+    try {
+      tx = { ...(await fn.populateTransaction(...args, overrides)) };
+    } catch (exc) {
+      throw wrapWeb3Error(this.chainKey, exc);
+    }
+
+    tx.nonce = await this.w3.getTransactionCount(sender, "pending");
+    tx.chainId = this.chainId;
+    if (opts.value) tx.value = opts.value;
+
+    // EIP-1559 fees (fall back to legacy gasPrice on chains without baseFee).
+    const latest = await this.w3.getBlock("latest");
+    const feeData = await this.w3.getFeeData();
+    if (latest && latest.baseFeePerGas != null) {
+      let tip = feeData.maxPriorityFeePerGas;
+      if (tip == null) tip = 1_000_000_000n; // 1 gwei fallback
+      tx.maxPriorityFeePerGas = tip;
+      tx.maxFeePerGas = tip + 2n * latest.baseFeePerGas;
+      tx.type = 2;
+      delete tx.gasPrice;
+    } else {
+      tx.gasPrice = feeData.gasPrice ?? 0n;
+      tx.type = 0;
+    }
+
+    // Gas estimate + safety buffer (state-dependent txs can cost more at
+    // execution than at estimation). Explicit `gas` overrides below.
+    let gas = opts.gas ?? null;
+    if (gas === null) {
+      gas = await this.estimateGas(fn, args, { value: opts.value });
+      if (this.gasMultiplier && this.gasMultiplier !== 1.0) {
+        gas = (gas * BigInt(Math.round(this.gasMultiplier * 1000))) / 1000n;
+      }
+    }
+    tx.gasLimit = gas;
+    delete tx.gas;
+    return tx;
+  }
+
+  /**
+   * Build -> sign -> send a transaction.
+   *
+   * With `buildOnly=true` returns the fully-populated **unsigned** tx (no key
+   * required — only a sender `address`); sign and broadcast it with your own
+   * wallet. Otherwise: with `wait=true` (default) returns the mined receipt and
+   * raises SallyRevert on a failed (status 0) tx; with `wait=false` returns the
+   * tx hash. `simulate=true` does a cheap `eth_call` first so reverts surface
+   * *before* you spend gas.
+   *
+   * `private` broadcasts through `privateRpcUrl` (a private mempool / MEV-relay).
+   * `timeout` (seconds) bounds the receipt wait.
+   */
+  async send(
+    fn: Fn,
+    args: any[] = [],
+    opts: {
+      value?: bigint;
+      gas?: bigint | null;
+      wait?: boolean;
+      simulate?: boolean;
+      private?: boolean | null;
+      timeout?: number;
+      buildOnly?: boolean;
+    } = {},
+  ): Promise<any> {
+    const value = opts.value ?? 0n;
+    const wait = opts.wait ?? true;
+    const simulate = opts.simulate ?? true;
+    const timeout = opts.timeout ?? 180;
+
+    if (simulate) {
+      await this.simulate(fn, args, { value });
+    }
+    if (opts.buildOnly) {
+      return this.buildTx(fn, args, { value, gas: opts.gas ?? null });
+    }
+
+    const account = this.requireSigner();
+    const usePrivate = opts.private == null ? this.privateRpcUrl !== null : opts.private;
+    // Hold the per-signer lock across nonce-fetch → broadcast so concurrent sends
+    // from one account get distinct, sequential nonces.
+    const txh: string = await this._sendLock.run(async () => {
+      const tx = await this.buildTx(fn, args, { value, gas: opts.gas ?? null });
+      const raw = await account.signTransaction(tx as any);
+      let hash: string;
+      if (usePrivate) {
+        hash = await this._broadcastPrivate(raw);
+      } else {
+        const resp = await this.w3.broadcastTransaction(raw);
+        hash = resp.hash;
+      }
+      return hash;
+    });
+    if (!wait) return txh;
+
+    let receipt;
+    try {
+      receipt = await this.w3.waitForTransaction(txh, 1, timeout * 1000);
+    } catch (exc) {
+      receipt = null;
+    }
+    if (receipt === null) {
+      const where = usePrivate ? "private relay" : "public mempool";
+      throw new SallyError(
+        `tx ${txh} not mined within ${timeout}s via ${where}. It may have been ` +
+          `dropped/not included — check the hash before resubmitting.`,
+      );
+    }
+    if (receipt.status !== 1) {
+      // A receipt carries no revert data; replay the tx at its block to recover it.
+      throw await this._decodeFailedTx(txh, receipt);
+    }
+    return receipt;
+  }
+
+  private async _decodeFailedTx(txh: string, receipt: any): Promise<SallyError> {
+    try {
+      const tx = await this.w3.getTransaction(txh);
+      if (tx) {
+        const callTx = {
+          from: tx.from,
+          to: tx.to,
+          data: tx.data,
+          value: tx.value,
+          gasLimit: tx.gasLimit,
+        };
+        await this.w3.call({ ...callTx, blockTag: receipt.blockNumber - 1 });
+      }
+    } catch (exc: any) {
+      const err = wrapWeb3Error(this.chainKey, exc);
+      return new SallyError(`tx ${txh} reverted on-chain: ${err.toString()}`);
+    }
+    return new SallyRevert("Error", [], null, `tx ${txh} reverted on-chain`);
+  }
+
+  // ------------------------------------------------------------------ //
+  // Preview (sign-externally): build + simulate + ABI-decode, no key
+  // ------------------------------------------------------------------ //
+  /** ABI-decode a contract call into `[functionName, { arg: value }]`. */
+  decodeCall(fn: Fn, args: any[] = []): [string, Record<string, any>] {
+    const fragment = fn.fragment ?? {};
+    const inputs = fragment.inputs ?? [];
+    const out: Record<string, any> = {};
+    inputs.forEach((inp: any, n: number) => {
+      out[inp.name || `arg${n}`] = args[n];
+    });
+    return [fragment.name ?? "?", out];
+  }
+
+  /**
+   * Build an unsigned tx + simulate + decode — see it before you broadcast.
+   *
+   * Returns a {@link TxPreview} with the unsigned transaction (sign it with your
+   * own wallet), the decoded function/args, the simulated `eth_call` result, the
+   * decoded revert reason if it would fail, and the gas estimate. Needs only a
+   * sender `address` — no key.
+   */
+  async preview(fn: Fn, args: any[] = [], opts: { value?: bigint } = {}): Promise<TxPreview> {
+    const value = opts.value ?? 0n;
+    const sender = this.requireAddress();
+    const [name, decodedArgs] = this.decodeCall(fn, args);
+
+    let simulated: any = null;
+    let revert: string | null = null;
+    let gas: bigint | null = null;
+    let to = this.addresses["swap"];
+    try {
+      simulated = await this.call(fn, args, { value, sender });
+      gas = await this.estimateGas(fn, args, { value });
+    } catch (exc: any) {
+      if (exc instanceof SallyConfigError) throw exc;
+      revert = String(exc); // Python: str(exc) — SallyRevert renders "<name>: <detail>"
+    }
+
+    let unsigned: Record<string, any> = {};
+    if (revert === null) {
+      unsigned = await this.buildTx(fn, args, { value });
+      if (unsigned.to) to = unsigned.to;
+    }
+    return new TxPreview({
+      unsignedTx: unsigned,
+      sender,
+      to: String(to),
+      function: name,
+      args: decodedArgs,
+      value,
+      simulatedReturn: simulated,
+      revert,
+      gas,
+    });
+  }
+
+  /** POST the raw tx to the private relay; return the tx hash. */
+  private async _broadcastPrivate(rawTx: string): Promise<string> {
+    if (!this.privateRpcUrl) {
+      throw new SallyConfigError(
+        "private=true but no privateRpcUrl configured. Pass " +
+          "new SallyClient(..., { privateRpcUrl: 'https://rpc.flashbots.net/fast' }).",
+      );
+    }
+    if (this._privateW3 === null) {
+      this._privateW3 = new JsonRpcProvider(this.privateRpcUrl, Network.from(this.chainId), {
+        staticNetwork: Network.from(this.chainId),
+      });
+    }
+    const resp = await this._privateW3.broadcastTransaction(rawTx);
+    return resp.hash;
+  }
+
+  // ------------------------------------------------------------------ //
+  // Namespaces (lazy)
+  // ------------------------------------------------------------------ //
+  get prices(): Prices {
+    return this._cached("prices", () => new Prices(this));
+  }
+
+  get swap(): Swap {
+    return this._cached("swap", () => new Swap(this));
+  }
+
+  get wallet(): WalletModule {
+    return this._cached("wallet", () => new WalletModule(this));
+  }
+
+  get liquidity(): Liquidity {
+    return this._cached("liquidity", () => new Liquidity(this));
+  }
+
+  get fees(): Fees {
+    return this._cached("fees", () => new Fees(this));
+  }
+
+  get permit2(): Permit2 {
+    return this._cached("permit2", () => new Permit2(this));
+  }
+
+  toString(): string {
+    const who = this.address ?? "read-only";
+    return `<SallyClient chain=${this.chainKey} id=${this.chainId} signer=${who}>`;
+  }
+}

package/src/constants.ts

@@ -0,0 +1,43 @@
+/**
+ * Well-known token addresses, handy for examples and tests.
+ *
+ * These are convenience constants only — the SDK itself never depends on them.
+ */
+
+import { NATIVE, ZERO } from "./token.js";
+
+// Base (chain 8453)
+export const Base = {
+  WETH: "0x4200000000000000000000000000000000000006",
+  USDC: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  USDbC: "0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA",
+  DAI: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
+  cbBTC: "0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf",
+} as const;
+
+// BSC (chain 56)
+export const Bsc = {
+  WBNB: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
+  USDT: "0x55d398326f99059fF775485246999027B3197955",
+  USDC: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+  CAKE: "0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82",
+} as const;
+
+export const NATIVE_TOKEN = NATIVE;
+export const ZERO_ADDRESS = ZERO;
+
+/**
+ * Known private-mempool / MEV-protection relay RPCs.
+ *
+ * Pass one as `new SallyClient(..., { privateRpcUrl: PrivateRelays.X })`.
+ * Flashbots Protect is Ethereum-L1 only; BSC has 48.club / bloXroute; Base's
+ * sequencer is centralized (limited public-mempool MEV), so a private relay
+ * matters most on L1 — verify your chain actually has one before relying on it.
+ */
+export const PrivateRelays = {
+  FLASHBOTS_FAST: "https://rpc.flashbots.net/fast", // ETH mainnet
+  FLASHBOTS: "https://rpc.flashbots.net", // ETH mainnet
+  MEVBLOCKER: "https://rpc.mevblocker.io", // ETH mainnet
+  BSC_48CLUB: "https://rpc.48.club", // BSC
+  BSC_BLOXROUTE: "https://bsc.rpc.blxrbdn.com", // BSC
+} as const;