sally-defi-ts-sdk 0.3.2

package/src/modules/swap.ts

@@ -0,0 +1,502 @@
+/**
+ * Hybrid swaps — quote, compare, simulate, guard, execute.
+ *
+ * The high-level {@link Swap.execute} does the safe thing by default:
+ *
+ * 1. **approve** the input (exact amount, not infinite) to the swap proxy,
+ * 2. **enumerate** candidate routes (best / deep / per-version),
+ * 3. **integrity-check** each so funds can never enter a wrong/mismatched pool,
+ * 4. **simulate** every candidate on-chain (`eth_call` of the real
+ *    `executeHybridSwap`, which returns the realized output) and pick the best,
+ * 5. **honeypot/tax preflight** the output token via the `getTokenInfos` probe,
+ * 6. set `minOut` from the *simulated* output and a slippage floor,
+ * 7. send, then **assert the received balance grew by >= minOut** (trust the chain).
+ *
+ * Use {@link Swap.plan} to get the same vetted {@link SwapPlan} without sending.
+ */
+
+import { Contract, getAddress } from "ethers";
+import type { SallyClient } from "../client.js";
+import { SallyError, SallyRouteError, SallySafetyError } from "../errors.js";
+import { RouteCandidate, SafetyConfig, SwapPlan } from "../safety.js";
+import { MAX_UINT256, ZERO, isNative } from "../token.js";
+import { SwapPath, TokenInfo } from "../types.js";
+import { pyRound } from "../util.js";
+
+const MAX_DEADLINE = 2n ** 256n - 1n;
+
+export interface ExecuteOptions {
+  slippageBps?: number | null;
+  minOutput?: bigint | null;
+  path?: SwapPath | null;
+  referral?: string;
+  deadline?: number | null;
+  config?: SafetyConfig | null;
+  approval?: "approve" | "permit" | "none";
+  force?: boolean;
+  buildOnly?: boolean;
+  tx?: Record<string, any>;
+}
+
+export class Swap {
+  private _c: SallyClient;
+  private _swap: Contract;
+  private _wnative: string | null = null;
+
+  constructor(client: SallyClient) {
+    this._c = client;
+    this._swap = client.swapContract;
+  }
+
+  private _a(x: string): string {
+    return getAddress(x);
+  }
+
+  async wnative(): Promise<string> {
+    if (this._wnative === null) {
+      this._wnative = String(await this._c.call(this._swap.getFunction("wnative"), []));
+    }
+    return this._wnative;
+  }
+
+  // -- quoting ----------------------------------------------------------- //
+  /** Best cross-version route for `amountIn`. `getBestSwapPath`. */
+  async quote(tokenIn: string, tokenOut: string, amountIn: bigint): Promise<SwapPath> {
+    return SwapPath.fromRaw(
+      await this._c.call(this._swap.getFunction("getBestSwapPath"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+    );
+  }
+
+  async quoteV2(tokenIn: string, tokenOut: string, amountIn: bigint): Promise<SwapPath> {
+    return SwapPath.fromRaw(
+      await this._c.call(this._swap.getFunction("getSwapPathV2"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+    );
+  }
+
+  async quoteV3(tokenIn: string, tokenOut: string, amountIn: bigint): Promise<SwapPath> {
+    return SwapPath.fromRaw(
+      await this._c.call(this._swap.getFunction("getSwapPathV3"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+    );
+  }
+
+  async quoteV4(tokenIn: string, tokenOut: string, amountIn: bigint): Promise<SwapPath> {
+    return SwapPath.fromRaw(
+      await this._c.call(this._swap.getFunction("getSwapPathV4"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+    );
+  }
+
+  /** Deeper, more exhaustive route search. `getBestSwapPathDeep` (Lens). */
+  async quoteDeep(tokenIn: string, tokenOut: string, amountIn: bigint): Promise<SwapPath> {
+    return SwapPath.fromRaw(
+      await this._c.call(this._c.lensContract.getFunction("getBestSwapPathDeep"), [
+        this._a(tokenIn),
+        this._a(tokenOut),
+        amountIn,
+      ]),
+    );
+  }
+
+  // -- token safety probe ------------------------------------------------ //
+  /** Honeypot / buy-sell-tax round-trip probe. `getTokenInfos`. */
+  async tokenInfo(token: string, opts: { probeValue?: bigint | null } = {}): Promise<TokenInfo> {
+    let probeValue = opts.probeValue ?? null;
+    if (probeValue === null) probeValue = new SafetyConfig().probeValue;
+    const raw = await this._swap.getFunction("getTokenInfos").staticCall(this._a(token), {
+      from: ZERO,
+      value: probeValue,
+    });
+    return TokenInfo.fromRaw(raw);
+  }
+
+  // -- protocol config reads -------------------------------------------- //
+  async perHopSlippageBps(): Promise<number> {
+    return Number(await this._c.call(this._swap.getFunction("perHopSlippageBps"), []));
+  }
+
+  /** Stablecoins the protocol prices against. `getUsdStables`. */
+  async usdStables(): Promise<string[]> {
+    const r = await this._c.call(this._swap.getFunction("getUsdStables"), []);
+    return [...r].map((a) => String(a));
+  }
+
+  async poolManagerV4(): Promise<string> {
+    return String(await this._c.call(this._swap.getFunction("poolManagerV4"), []));
+  }
+
+  // -- helpers ----------------------------------------------------------- //
+  /**
+   * Slippage floor: `amountOut * (1 - bps/10000)`.
+   *
+   * Clamped to >= 1 when the output is positive, so integer flooring on a tiny
+   * output can never produce `minOut == 0` (which would disable the on-chain
+   * slippage guard and expose the swap to a 100% sandwich).
+   */
+  static minOut(amountOut: bigint | SwapPath | null, slippageBps: number): bigint {
+    const out: bigint = amountOut instanceof SwapPath ? amountOut.estimatedAmountOut : (amountOut ?? 0n);
+    const floor = (out * BigInt(10_000 - slippageBps)) / 10_000n;
+    return out > 0n ? (floor > 1n ? floor : 1n) : 0n;
+  }
+
+  minOut(amountOut: bigint | SwapPath | null, slippageBps: number): bigint {
+    return Swap.minOut(amountOut, slippageBps);
+  }
+
+  deadline(secs: number | null = null): number {
+    // Wall-clock based (like the Uniswap SDK): robust even if the node reports a
+    // stale `latest` block while mining ahead.
+    const s = secs !== null ? secs : new SafetyConfig().deadlineSecs;
+    return Math.floor(Date.now() / 1000) + s;
+  }
+
+  /** All distinct quoted routes (best / deep / per-version), deduped by pools. */
+  async candidates(tokenIn: string, tokenOut: string, amountIn: bigint): Promise<RouteCandidate[]> {
+    tokenIn = this._a(tokenIn);
+    tokenOut = this._a(tokenOut);
+    const out: RouteCandidate[] = [];
+    const seen = new Set<string>();
+    const fns: [string, (a: string, b: string, c: bigint) => Promise<SwapPath>][] = [
+      ["best", (a, b, c) => this.quote(a, b, c)],
+      ["deep", (a, b, c) => this.quoteDeep(a, b, c)],
+      ["v2", (a, b, c) => this.quoteV2(a, b, c)],
+      ["v3", (a, b, c) => this.quoteV3(a, b, c)],
+      ["v4", (a, b, c) => this.quoteV4(a, b, c)],
+    ];
+    for (const [label, fn] of fns) {
+      let route: SwapPath;
+      try {
+        route = await fn(tokenIn, tokenOut, amountIn);
+      } catch (exc) {
+        if (exc instanceof SallyError) continue;
+        throw exc;
+      }
+      if (route.stepCount === 0) continue;
+      const key = JSON.stringify([
+        route.poolAddresses.map((p) => p.toLowerCase()),
+        route.stepCount,
+        route.estimatedAmountOut.toString(),
+      ]);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(new RouteCandidate(label, route, route.estimatedAmountOut));
+    }
+    return out;
+  }
+
+  /**
+   * `eth_call` the real `executeHybridSwap` and return realized output.
+   *
+   * Returns `null` if the route reverts. Requires `sender` to hold the input
+   * token + allowance (or `value` for native in) — exactly what `execute`
+   * arranges before planning.
+   */
+  async simulateRoute(
+    route: SwapPath,
+    amountIn: bigint,
+    opts: { value?: bigint; sender?: string | null } = {},
+  ): Promise<bigint | null> {
+    const value = opts.value ?? 0n;
+    const sender = opts.sender ?? this._c.address;
+    if (sender == null) return null;
+    try {
+      const r = await this._swap.getFunction("executeHybridSwap").staticCall(
+        route.toTuple(),
+        amountIn,
+        0,
+        MAX_DEADLINE,
+        ZERO,
+        { from: sender, value },
+      );
+      return BigInt(r);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Impact vs the marginal (small-trade) price, in bps. null if unknown. */
+  private async _priceImpactBps(
+    tokenIn: string,
+    tokenOut: string,
+    amountIn: bigint,
+    realized: bigint,
+  ): Promise<number | null> {
+    const probe = amountIn / 1000n > 1n ? amountIn / 1000n : 1n;
+    let probeOut: bigint;
+    try {
+      probeOut = (await this.quote(tokenIn, tokenOut, probe)).estimatedAmountOut;
+    } catch (exc) {
+      if (exc instanceof SallyError) return null;
+      throw exc;
+    }
+    if (probeOut <= 0n || realized <= 0n) return null;
+    const expected = (probeOut * amountIn) / probe;
+    if (expected <= 0n) return null;
+    return Math.max(0, pyRound((Number(expected - realized) / Number(expected)) * 10_000));
+  }
+
+  /**
+   * Honeypot/tax probe on the output token + price-impact check.
+   *
+   * Returns `[tokenSafety, priceImpactBps, blockReasons, warnings]`. Shared by
+   * `plan` and the supplied-path branch of `execute` so neither is a safety bypass.
+   */
+  private async _safetyPreflight(
+    quoteIn: string,
+    tokenOut: string,
+    amountIn: bigint,
+    realized: bigint,
+    cfg: SafetyConfig,
+  ): Promise<[TokenInfo | null, number | null, string[], string[]]> {
+    const blocks: string[] = [];
+    const warns: string[] = [];
+    let safety: TokenInfo | null = null;
+    if (cfg.checkHoneypot && !isNative(tokenOut)) {
+      try {
+        safety = await this.tokenInfo(tokenOut, { probeValue: cfg.probeValue });
+      } catch {
+        safety = null;
+      }
+      if (safety !== null && safety.buySuccess) {
+        if (safety.isHoneypot) blocks.push("honeypot");
+        const tax = Math.max(safety.buyTaxBps, safety.sellTaxBps);
+        if (tax >= cfg.taxBlockBps) blocks.push(`tax_${tax}bps`);
+        else if (tax >= cfg.taxWarnBps) warns.push(`high_tax_${tax}bps`);
+      } else {
+        warns.push("safety_probe_unavailable");
+      }
+    }
+
+    const impact = await this._priceImpactBps(quoteIn, tokenOut, amountIn, realized);
+    if (impact !== null) {
+      if (impact >= cfg.priceImpactBlockBps) blocks.push(`price_impact_${impact}bps`);
+      else if (impact >= cfg.priceImpactWarnBps) warns.push(`price_impact_${impact}bps`);
+    }
+    return [safety, impact, blocks, warns];
+  }
+
+  // -- planning ---------------------------------------------------------- //
+  /** Build a fully-vetted {@link SwapPlan} without sending anything. */
+  async plan(
+    tokenIn: string,
+    tokenOut: string,
+    amountIn: bigint,
+    opts: { slippageBps?: number | null; config?: SafetyConfig | null; sender?: string | null } = {},
+  ): Promise<SwapPlan> {
+    const cfg = opts.config ?? this._c.safety;
+    const slippageBps = opts.slippageBps == null ? cfg.slippageBps : opts.slippageBps;
+    tokenIn = this._a(tokenIn);
+    tokenOut = this._a(tokenOut);
+    const nativeIn = isNative(tokenIn);
+    const value = nativeIn ? amountIn : 0n;
+    const sender = opts.sender ?? this._c.address;
+
+    const wnative = await this.wnative();
+    // Routes are quoted in wrapped-native terms; the contract wraps the native
+    // value itself at execution. Integrity still maps the native sentinel back.
+    const quoteIn = nativeIn ? this._a(wnative) : tokenIn;
+
+    const cands = await this.candidates(quoteIn, tokenOut, amountIn);
+    if (cands.length === 0) {
+      throw new SallyError(`No route found ${tokenIn} -> ${tokenOut} for ${amountIn}`);
+    }
+
+    // integrity — guards against funds entering the wrong pool
+    if (cfg.checkIntegrity) {
+      for (const c of cands) {
+        c.integrityProblems = c.route.checkIntegrity(tokenIn, tokenOut, wnative);
+      }
+    }
+
+    // simulate each usable candidate end-to-end
+    if (cfg.simulate && sender != null) {
+      for (const c of cands) {
+        if (c.usable) {
+          c.simulatedOut = await this.simulateRoute(c.route, amountIn, { value, sender });
+        }
+      }
+    }
+
+    const usable = cands.filter((c) => c.usable);
+    const pool = usable.length ? usable : cands;
+    const best = pool.reduce((a, b) => (b.score > a.score ? b : a));
+
+    const blockReasons: string[] = [];
+    const warnings: string[] = [];
+
+    if (usable.length === 0) blockReasons.push("no_valid_route");
+    if (best.integrityProblems.length) {
+      blockReasons.push("integrity");
+      warnings.push(...best.integrityProblems);
+    }
+
+    const realized = best.score;
+    const [safety, impact, sblocks, swarns] = await this._safetyPreflight(quoteIn, tokenOut, amountIn, realized, cfg);
+    blockReasons.push(...sblocks);
+    warnings.push(...swarns);
+
+    return new SwapPlan(
+      tokenIn,
+      tokenOut,
+      amountIn,
+      best.route,
+      best.quotedOut,
+      best.simulatedOut,
+      this.minOut(realized, slippageBps),
+      impact,
+      safety,
+      cands,
+      warnings,
+      blockReasons,
+    );
+  }
+
+  // -- execution --------------------------------------------------------- //
+  /**
+   * Plan (vet + simulate), enforce guards, send, verify balance delta.
+   *
+   * `approval`: `"approve"` (default, exact-amount ERC-20 approve), `"permit"`
+   * (EIP-2612 signature where supported, else approve), or `"none"` (assume
+   * allowance already set). With `buildOnly=true` nothing is sent: returns a
+   * {@link SwapBuild}. Set `force=true` to bypass safety blocks (NOT recommended).
+   */
+  async execute(tokenIn: string, tokenOut: string, amountIn: bigint, opts: ExecuteOptions = {}): Promise<any> {
+    let cfg = opts.config ?? this._c.safety;
+    const referral = opts.referral ?? ZERO;
+    const approval = opts.approval ?? "approve";
+    const force = opts.force ?? false;
+    const buildOnly = opts.buildOnly ?? false;
+    const txOpts = opts.tx ?? {};
+
+    const me = this._c.requireAddress();
+    tokenIn = this._a(tokenIn);
+    tokenOut = this._a(tokenOut);
+    const nativeIn = isNative(tokenIn);
+    const value = nativeIn ? amountIn : 0n;
+    const wnative = await this.wnative();
+
+    // 1) authorise the input first so the simulation's transferFrom succeeds.
+    let approveTx: Record<string, any> | null = null;
+    let needsApproval = false;
+    if (!nativeIn && approval !== "none") {
+      const spender = this._c.addresses["swap"];
+      const amount = cfg.unlimitedApproval ? MAX_UINT256 : amountIn;
+      const tok = this._c.token(tokenIn);
+      if (buildOnly) {
+        // Don't send: build the unsigned approve tx if allowance is short.
+        if ((await tok.allowance(me, spender)) < amount) {
+          needsApproval = true;
+          approveTx = await tok.buildApprove(spender, amount);
+          // The swap eth_call can't pull tokens yet → vet via quote, not sim.
+          cfg = cfg.replace({ simulate: false });
+        }
+      } else {
+        let usedPermit = false;
+        if (approval === "permit" && (await tok.supportsPermit())) {
+          if ((await tok.allowance(me, spender)) < amount) {
+            try {
+              await tok.permit(spender, amount);
+              usedPermit = true;
+            } catch {
+              // Some tokens advertise nonces but reject EIP-2612 permits
+              // (non-standard impls). Fall back to a plain approve.
+              usedPermit = false;
+            }
+          } else {
+            usedPermit = true;
+          }
+        }
+        if (!usedPermit) {
+          await tok.ensureAllowance(spender, amount);
+        }
+      }
+    }
+
+    // 2) plan (unless a fixed path was supplied)
+    let plan: SwapPlan;
+    if (opts.path == null) {
+      plan = await this.plan(tokenIn, tokenOut, amountIn, {
+        slippageBps: opts.slippageBps ?? null,
+        config: cfg,
+      });
+    } else {
+      const path = opts.path;
+      const problems = cfg.checkIntegrity ? path.checkIntegrity(tokenIn, tokenOut, wnative) : [];
+      if (problems.length && !force) {
+        throw new SallyRouteError(`supplied path failed integrity: ${problems}`);
+      }
+      const sim = cfg.simulate ? await this.simulateRoute(path, amountIn, { value }) : null;
+      const sb = opts.slippageBps != null ? opts.slippageBps : cfg.slippageBps;
+      // If we simulated and the supplied path REVERTS, block — do not fall back
+      // to the caller's unvalidated quote (which could set minOut to 0).
+      const reasons: string[] = problems.length ? ["integrity"] : [];
+      if (cfg.simulate && sim === null) reasons.push("no_valid_route");
+      const floor = sim !== null ? this.minOut(sim, sb) : this.minOut(path, sb);
+      // A zero floor disables the on-chain slippage guard — block regardless of
+      // which safety toggles are off.
+      if (floor === 0n) reasons.push("zero_min_out");
+      // Run the SAME honeypot/tax + price-impact preflight as plan().
+      const quoteIn = nativeIn ? this._a(wnative) : tokenIn;
+      const realized = sim !== null ? sim : path.estimatedAmountOut;
+      const [safety, impact, sblocks, swarns] = await this._safetyPreflight(
+        quoteIn,
+        tokenOut,
+        amountIn,
+        realized,
+        cfg,
+      );
+      plan = new SwapPlan(
+        tokenIn,
+        tokenOut,
+        amountIn,
+        path,
+        path.estimatedAmountOut,
+        sim,
+        floor,
+        impact,
+        safety,
+        [],
+        swarns,
+        [...reasons, ...sblocks],
+      );
+    }
+
+    // 3) enforce guards
+    if (!plan.isSafe && !force) {
+      if (plan.blockReasons.includes("integrity") || plan.blockReasons.includes("no_valid_route")) {
+        throw new SallyRouteError(`route rejected: ${plan.blockReasons} ${plan.warnings}`);
+      }
+      throw new SallySafetyError(`swap blocked: ${plan.blockReasons}`, plan.blockReasons);
+    }
+
+    const minOut = opts.minOutput != null ? opts.minOutput : plan.minOut;
+    const deadline = opts.deadline != null ? opts.deadline : this.deadline(cfg.deadlineSecs);
+
+    // 4) balance-delta baseline (ERC-20 out only). Skip for native AND wrapped-
+    //    native out: Sally may pay out unwrapped native, so an ERC-20 balanceOf
+    //    would not move — the contract's own minOut guard still protects there.
+    const track = !isNative(tokenOut) && tokenOut.toLowerCase() !== wnative.toLowerCase();
+    const before = track ? await this._c.token(tokenOut).balanceOf(me) : 0n;
+
+    // 5) build the chosen, vetted route
+    const fn = this._swap.getFunction("executeHybridSwap");
+    const args = [plan.route.toTuple(), amountIn, minOut, deadline, this._a(referral)];
+    if (buildOnly) {
+      // Sign-externally: return the vetted plan + unsigned txs, send nothing.
+      const { SwapBuild } = await import("../previews.js");
+      const swapTx = await this._c.send(fn, args, { value, simulate: false, buildOnly: true });
+      return new SwapBuild({ plan, swapTx, approveTx, needsApproval });
+    }
+    const receipt = await this._c.send(fn, args, { value, ...txOpts });
+
+    // 6) trust the chain: received balance must have grown by >= minOut
+    if (track && cfg.balanceDeltaAssert) {
+      const gained = (await this._c.token(tokenOut).balanceOf(me)) - before;
+      if (gained < minOut) {
+        throw new SallySafetyError(
+          `received ${gained} < min_out ${minOut} (balance-delta check failed)`,
+          ["balance_delta"],
+        );
+      }
+    }
+    return receipt;
+  }
+}

package/src/modules/wallet.ts

@@ -0,0 +1,37 @@
+/** Wallet balance reads with live USD valuation (Lens via swap proxy). */
+
+import { Contract, getAddress } from "ethers";
+import type { SallyClient } from "../client.js";
+import { WalletBalance } from "../types.js";
+
+export class Wallet {
+  private _c: SallyClient;
+  private _lens: Contract;
+
+  constructor(client: SallyClient) {
+    this._c = client;
+    this._lens = client.lensContract;
+  }
+
+  private _addrs(tokens: string[]): string[] {
+    return tokens.map((t) => getAddress(t));
+  }
+
+  /** Balances + USD value for `tokens`. `getWalletBalance`. */
+  async balances(wallet: string, tokens: string[]): Promise<WalletBalance[]> {
+    const r = await this._c.call(this._lens.getFunction("getWalletBalance"), [getAddress(wallet), this._addrs(tokens)]);
+    return [...r].map((x) => WalletBalance.fromRaw(x));
+  }
+
+  /** Same but the gas-lean variant. `getWalletBalanceRaw`. */
+  async balancesRaw(wallet: string, tokens: string[]): Promise<WalletBalance[]> {
+    const r = await this._c.call(this._lens.getFunction("getWalletBalanceRaw"), [getAddress(wallet), this._addrs(tokens)]);
+    return [...r].map((x) => WalletBalance.fromRaw(x));
+  }
+
+  /** Sum of USD value across `tokens` (float, human units). */
+  async totalUsd(wallet: string, tokens: string[]): Promise<number> {
+    const bals = await this.balances(wallet, tokens);
+    return bals.reduce((acc, b) => acc + b.usdValueFloat, 0);
+  }
+}