sally-defi-ts-sdk 0.3.2

package/src/aio/modules/swap.ts

@@ -0,0 +1,347 @@
+/**
+ * Async hybrid swaps — quote, compare, simulate, guard, execute.
+ *
+ * Mirrors the sync {@link Swap}, but quoting and simulation of the candidate
+ * routes run concurrently via `Promise.all` (the async client's main payoff,
+ * matching the Python `asyncio.gather`).
+ */
+
+import { Contract, getAddress } from "ethers";
+import type { AsyncSallyClient } 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 AsyncExecuteOptions {
+  slippageBps?: number | null;
+  minOutput?: bigint | null;
+  path?: SwapPath | null;
+  referral?: string;
+  deadline?: number | null;
+  config?: SafetyConfig | null;
+  approval?: "approve" | "permit" | "none";
+  force?: boolean;
+  tx?: Record<string, any>;
+}
+
+export class AsyncSwap {
+  private _c: AsyncSallyClient;
+  private _swap: Contract;
+  private _wnative: string | null = null;
+
+  constructor(client: AsyncSallyClient) {
+    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 ----------------------------------------------------------- //
+  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 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,
+      ]),
+    );
+  }
+
+  private async _quoteNamed(
+    label: string,
+    tokenIn: string,
+    tokenOut: string,
+    amountIn: bigint,
+  ): Promise<SwapPath | null> {
+    const fns: Record<string, () => Promise<any>> = {
+      best: () => this._c.call(this._swap.getFunction("getBestSwapPath"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+      deep: () =>
+        this._c.call(this._c.lensContract.getFunction("getBestSwapPathDeep"), [
+          this._a(tokenIn),
+          this._a(tokenOut),
+          amountIn,
+        ]),
+      v2: () => this._c.call(this._swap.getFunction("getSwapPathV2"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+      v3: () => this._c.call(this._swap.getFunction("getSwapPathV3"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+      v4: () => this._c.call(this._swap.getFunction("getSwapPathV4"), [this._a(tokenIn), this._a(tokenOut), amountIn]),
+    };
+    let r: any;
+    try {
+      r = await fns[label]();
+    } catch (exc) {
+      if (exc instanceof SallyError) return null;
+      throw exc;
+    }
+    const route = SwapPath.fromRaw(r);
+    return route.stepCount ? route : null;
+  }
+
+  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);
+  }
+
+  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;
+  }
+
+  async deadline(secs: number | null = null): Promise<number> {
+    const s = secs !== null ? secs : new SafetyConfig().deadlineSecs;
+    return Math.floor(Date.now() / 1000) + s;
+  }
+
+  async candidates(tokenIn: string, tokenOut: string, amountIn: bigint): Promise<RouteCandidate[]> {
+    tokenIn = this._a(tokenIn);
+    tokenOut = this._a(tokenOut);
+    const labels = ["best", "deep", "v2", "v3", "v4"];
+    const routes = await Promise.all(labels.map((x) => this._quoteNamed(x, tokenIn, tokenOut, amountIn)));
+    const out: RouteCandidate[] = [];
+    const seen = new Set<string>();
+    for (let i = 0; i < labels.length; i++) {
+      const route = routes[i];
+      if (route === null) 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(labels[i], route, route.estimatedAmountOut));
+    }
+    return out;
+  }
+
+  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;
+    }
+  }
+
+  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;
+    return expected > 0n ? Math.max(0, pyRound((Number(expected - realized) / Number(expected)) * 10_000)) : null;
+  }
+
+  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();
+    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}`);
+    }
+
+    if (cfg.checkIntegrity) {
+      for (const c of cands) {
+        c.integrityProblems = c.route.checkIntegrity(tokenIn, tokenOut, wnative);
+      }
+    }
+
+    if (cfg.simulate && sender != null) {
+      const sims = await Promise.all(
+        cands.map((c) => (c.usable ? this.simulateRoute(c.route, amountIn, { value, sender }) : Promise.resolve(null))),
+      );
+      cands.forEach((c, i) => {
+        if (c.usable) c.simulatedOut = sims[i];
+      });
+    }
+
+    const usable = cands.filter((c) => c.usable);
+    const best = (usable.length ? usable : cands).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);
+    }
+
+    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) blockReasons.push("honeypot");
+        const tax = Math.max(safety.buyTaxBps, safety.sellTaxBps);
+        if (tax >= cfg.taxBlockBps) blockReasons.push(`tax_${tax}bps`);
+        else if (tax >= cfg.taxWarnBps) warnings.push(`high_tax_${tax}bps`);
+      } else {
+        warnings.push("safety_probe_unavailable");
+      }
+    }
+
+    const realized = best.score;
+    const impact = await this._priceImpactBps(quoteIn, tokenOut, amountIn, realized);
+    if (impact !== null) {
+      if (impact >= cfg.priceImpactBlockBps) blockReasons.push(`price_impact_${impact}bps`);
+      else if (impact >= cfg.priceImpactWarnBps) warnings.push(`price_impact_${impact}bps`);
+    }
+
+    return new SwapPlan(
+      tokenIn,
+      tokenOut,
+      amountIn,
+      best.route,
+      best.quotedOut,
+      best.simulatedOut,
+      this.minOut(realized, slippageBps),
+      impact,
+      safety,
+      cands,
+      warnings,
+      blockReasons,
+    );
+  }
+
+  async execute(tokenIn: string, tokenOut: string, amountIn: bigint, opts: AsyncExecuteOptions = {}): Promise<any> {
+    const cfg = opts.config ?? this._c.safety;
+    const referral = opts.referral ?? ZERO;
+    const approval = opts.approval ?? "approve";
+    const force = opts.force ?? false;
+    const txOpts = opts.tx ?? {};
+
+    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();
+
+    // Async approval supports "approve" (exact) and "none"; EIP-2612 permit is
+    // sync-only, so "permit" degrades to a plain approve here (made observable).
+    if (approval === "permit") {
+      console.warn(
+        "approval='permit' is not implemented on the async client; " +
+          "falling back to a plain approve. Use the sync client for EIP-2612 permit.",
+      );
+    }
+    if (!nativeIn && approval !== "none") {
+      const spender = this._c.addresses["swap"];
+      const amount = cfg.unlimitedApproval ? MAX_UINT256 : amountIn;
+      await this._c.token(tokenIn).ensureAllowance(spender, amount);
+    }
+
+    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;
+      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);
+      plan = new SwapPlan(
+        tokenIn,
+        tokenOut,
+        amountIn,
+        path,
+        path.estimatedAmountOut,
+        sim,
+        floor,
+        null,
+        null,
+        [],
+        [],
+        reasons,
+      );
+    }
+
+    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 : await this.deadline(cfg.deadlineSecs);
+
+    const track = !isNative(tokenOut) && tokenOut.toLowerCase() !== wnative.toLowerCase();
+    const before = track ? await this._c.token(tokenOut).balanceOf(this._c.address!) : 0n;
+
+    const fn = this._swap.getFunction("executeHybridSwap");
+    const args = [plan.route.toTuple(), amountIn, minOut, deadline, this._a(referral)];
+    const receipt = await this._c.send(fn, args, { value, ...txOpts });
+
+    if (track && cfg.balanceDeltaAssert) {
+      const gained = (await this._c.token(tokenOut).balanceOf(this._c.address!)) - before;
+      if (gained < minOut) {
+        throw new SallySafetyError(
+          `received ${gained} < min_out ${minOut} (balance-delta check failed)`,
+          ["balance_delta"],
+        );
+      }
+    }
+    return receipt;
+  }
+}

package/src/aio/modules/wallet.ts

@@ -0,0 +1,34 @@
+/** Async wallet balances. */
+
+import { Contract, getAddress } from "ethers";
+import type { AsyncSallyClient } from "../client.js";
+import { WalletBalance } from "../../types.js";
+
+export class AsyncWallet {
+  private _c: AsyncSallyClient;
+  private _lens: Contract;
+
+  constructor(client: AsyncSallyClient) {
+    this._c = client;
+    this._lens = client.lensContract;
+  }
+
+  private _addrs(tokens: string[]): string[] {
+    return tokens.map((t) => getAddress(t));
+  }
+
+  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));
+  }
+
+  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));
+  }
+
+  async totalUsd(wallet: string, tokens: string[]): Promise<number> {
+    const bals = await this.balances(wallet, tokens);
+    return bals.reduce((acc, b) => acc + b.usdValueFloat, 0);
+  }
+}

package/src/aio/token.ts

@@ -0,0 +1,59 @@
+/** Async ERC-20 helper (mirror of {@link Token}). */
+
+import { Contract, getAddress } from "ethers";
+import type { AsyncSallyClient } from "./client.js";
+import { ERC20_ABI, MAX_UINT256, TokenAmount } from "../token.js";
+
+export class AsyncToken {
+  readonly client: AsyncSallyClient;
+  readonly address: string;
+  readonly contract: Contract;
+  private _decimals: number | null = null;
+
+  constructor(client: AsyncSallyClient, address: string) {
+    this.client = client;
+    this.address = getAddress(address);
+    this.contract = new Contract(this.address, ERC20_ABI as any, client.w3);
+  }
+
+  async decimals(): Promise<number> {
+    if (this._decimals === null) {
+      this._decimals = Number(await this.contract.decimals());
+    }
+    return this._decimals;
+  }
+
+  async symbol(): Promise<string> {
+    try {
+      return await this.contract.symbol();
+    } catch {
+      return "?";
+    }
+  }
+
+  async balanceOf(owner: string): Promise<bigint> {
+    return BigInt(await this.contract.balanceOf(getAddress(owner)));
+  }
+
+  async allowance(owner: string, spender: string): Promise<bigint> {
+    return BigInt(await this.contract.allowance(getAddress(owner), getAddress(spender)));
+  }
+
+  async toRaw(human: string | number | bigint): Promise<bigint> {
+    return TokenAmount.fromHuman(human, await this.decimals()).raw;
+  }
+
+  async approve(spender: string, amount: bigint = MAX_UINT256, tx: Record<string, any> = {}): Promise<any> {
+    const fn = this.contract.getFunction("approve");
+    return this.client.send(fn, [getAddress(spender), amount], tx);
+  }
+
+  /** Approve exactly `amount` if the current allowance is insufficient. */
+  async ensureAllowance(spender: string, amount: bigint, tx: Record<string, any> = {}): Promise<any> {
+    const owner = this.client.requireAddress();
+    if ((await this.allowance(owner, spender)) >= amount) {
+      return null;
+    }
+    return this.approve(spender, amount, tx);
+  }
+}