sally-defi-ts-sdk 0.3.2

package/src/permit2.ts

@@ -0,0 +1,169 @@
+/**
+ * Permit2 + EIP-2612 signature approvals.
+ *
+ * Two distinct things live here:
+ *
+ * - **EIP-2612** (`signPermit2612`) — the token-native `permit(owner,spender,
+ *   value,nonce,deadline,v,r,s)`. Used by {@link Token.permit} so a swap can
+ *   authorise the proxy with a *signature* instead of a separate `approve` tx, on
+ *   tokens that support it (USDC, DAI-family wrappers, many others).
+ *
+ * - **Permit2** (`Permit2`, `0x000000000022D473030F116dDEE9F6B43aC78BA3`) —
+ *   Uniswap's universal approval contract. Sally's controller uses it
+ *   *internally* for the V4 PositionManager pull; user swaps do not require it.
+ *
+ * Both produce EIP-712 signatures via ethers; nothing is broadcast here.
+ */
+
+import { Contract, getAddress, Signature, type Signer } from "ethers";
+import type { SallyClient } from "./client.js";
+
+// Canonical Permit2, identical on every EVM chain (CREATE2).
+export const PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+export const MAX_UINT160 = 2n ** 160n - 1n;
+export const MAX_UINT48 = 2n ** 48n - 1n;
+
+// --------------------------------------------------------------------------- //
+// EIP-2612
+// --------------------------------------------------------------------------- //
+/** Sign an EIP-2612 `Permit` and return `[v, r, s]` (v number, r/s 0x-hex bytes32). */
+export async function signPermit2612(
+  account: Signer,
+  opts: {
+    token: string;
+    tokenName: string;
+    version: string;
+    chainId: number;
+    owner: string;
+    spender: string;
+    value: bigint;
+    nonce: number;
+    deadline: number;
+  },
+): Promise<[number, string, string]> {
+  const domain = {
+    name: opts.tokenName,
+    version: opts.version,
+    chainId: opts.chainId,
+    verifyingContract: getAddress(opts.token),
+  };
+  const types = {
+    Permit: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "nonce", type: "uint256" },
+      { name: "deadline", type: "uint256" },
+    ],
+  };
+  const message = {
+    owner: getAddress(opts.owner),
+    spender: getAddress(opts.spender),
+    value: opts.value,
+    nonce: opts.nonce,
+    deadline: opts.deadline,
+  };
+  const sig = await account.signTypedData(domain, types, message);
+  const split = Signature.from(sig);
+  return [split.v, split.r, split.s];
+}
+
+// --------------------------------------------------------------------------- //
+// Permit2 (AllowanceTransfer — PermitSingle)
+// --------------------------------------------------------------------------- //
+/** Sign a Permit2 `PermitSingle` and return the 65-byte signature (0x-hex). */
+export async function signPermitSingle(
+  account: Signer,
+  opts: {
+    chainId: number;
+    token: string;
+    spender: string;
+    amount: bigint;
+    expiration: number | bigint;
+    nonce: number | bigint;
+    sigDeadline: number | bigint;
+  },
+): Promise<string> {
+  const domain = {
+    name: "Permit2",
+    chainId: opts.chainId,
+    verifyingContract: PERMIT2_ADDRESS,
+  };
+  const types = {
+    PermitDetails: [
+      { name: "token", type: "address" },
+      { name: "amount", type: "uint160" },
+      { name: "expiration", type: "uint48" },
+      { name: "nonce", type: "uint48" },
+    ],
+    PermitSingle: [
+      { name: "details", type: "PermitDetails" },
+      { name: "spender", type: "address" },
+      { name: "sigDeadline", type: "uint256" },
+    ],
+  };
+  const message = {
+    details: {
+      token: getAddress(opts.token),
+      amount: opts.amount,
+      expiration: opts.expiration,
+      nonce: opts.nonce,
+    },
+    spender: getAddress(opts.spender),
+    sigDeadline: opts.sigDeadline,
+  };
+  return account.signTypedData(domain, types, message);
+}
+
+// Minimal Permit2 ABI for allowance reads + approve.
+export const PERMIT2_ABI = [
+  {
+    name: "allowance", type: "function", stateMutability: "view",
+    inputs: [
+      { name: "user", type: "address" }, { name: "token", type: "address" },
+      { name: "spender", type: "address" },
+    ],
+    outputs: [
+      { name: "amount", type: "uint160" }, { name: "expiration", type: "uint48" },
+      { name: "nonce", type: "uint48" },
+    ],
+  },
+  {
+    name: "approve", type: "function", stateMutability: "nonpayable",
+    inputs: [
+      { name: "token", type: "address" }, { name: "spender", type: "address" },
+      { name: "amount", type: "uint160" }, { name: "expiration", type: "uint48" },
+    ],
+    outputs: [],
+  },
+] as const;
+
+/** Thin helper around the canonical Permit2 contract for advanced flows. */
+export class Permit2 {
+  private _c: SallyClient;
+  readonly address: string;
+  readonly contract: Contract;
+
+  constructor(client: SallyClient) {
+    this._c = client;
+    this.address = getAddress(PERMIT2_ADDRESS);
+    this.contract = new Contract(this.address, PERMIT2_ABI as any, client.w3);
+  }
+
+  async allowance(owner: string, token: string, spender: string): Promise<[bigint, number, number]> {
+    const r = await this.contract.allowance(getAddress(owner), getAddress(token), getAddress(spender));
+    return [BigInt(r[0]), Number(r[1]), Number(r[2])];
+  }
+
+  /** On-chain `Permit2.approve` (after the token is approved to Permit2). */
+  async approveToken(
+    token: string,
+    spender: string,
+    amount: bigint = MAX_UINT160,
+    expiration: bigint = MAX_UINT48,
+    tx: Record<string, any> = {},
+  ): Promise<any> {
+    const fn = this.contract.getFunction("approve");
+    return this._c.send(fn, [getAddress(token), getAddress(spender), amount, expiration], tx);
+  }
+}

package/src/previews.ts

@@ -0,0 +1,95 @@
+/**
+ * Transaction previews for sign-externally mode.
+ *
+ * A {@link TxPreview} is what you inspect before signing with your own wallet:
+ * the fully-populated **unsigned** transaction, the ABI-decoded function + args,
+ * the simulated on-chain result (`eth_call`, decoded per the ABI), the decoded
+ * revert reason if it would fail, and the gas estimate. It answers "what happens
+ * to my wallet if I broadcast this?" — without holding your key.
+ */
+
+import type { SwapPlan } from "./safety.js";
+
+/** Inspectable, simulated, unsigned transaction. */
+export class TxPreview {
+  unsignedTx: Record<string, any>; // sign with your own wallet, then broadcastTransaction
+  sender: string;
+  to: string;
+  function: string; // decoded function name
+  args: Record<string, any>; // decoded named arguments
+  value: bigint;
+  simulatedReturn: any; // decoded eth_call result (null if it reverts)
+  revert: string | null; // decoded revert reason if it would revert
+  gas: bigint | null; // estimated gas (null if it reverts)
+
+  constructor(opts: {
+    unsignedTx: Record<string, any>;
+    sender: string;
+    to: string;
+    function: string;
+    args?: Record<string, any>;
+    value?: bigint;
+    simulatedReturn?: any;
+    revert?: string | null;
+    gas?: bigint | null;
+  }) {
+    this.unsignedTx = opts.unsignedTx;
+    this.sender = opts.sender;
+    this.to = opts.to;
+    this.function = opts.function;
+    this.args = opts.args ?? {};
+    this.value = opts.value ?? 0n;
+    this.simulatedReturn = opts.simulatedReturn ?? null;
+    this.revert = opts.revert ?? null;
+    this.gas = opts.gas ?? null;
+  }
+
+  get willRevert(): boolean {
+    return this.revert !== null;
+  }
+
+  summary(): string {
+    if (this.willRevert) {
+      return `TxPreview(${this.function} -> WOULD REVERT: ${this.revert})`;
+    }
+    return (
+      `TxPreview(${this.function} on ${this.to.slice(0, 10)}…  ` +
+      `returns=${this.simulatedReturn}  gas~${this.gas}  value=${this.value})`
+    );
+  }
+}
+
+/**
+ * A swap prepared for external signing.
+ *
+ * Inspect `plan` to see the wallet effect (expected output, min received, price
+ * impact, honeypot/tax screen), then sign + broadcast the unsigned txs yourself —
+ * `approveTx` first (if `needsApproval`), then `swapTx`.
+ */
+export class SwapBuild {
+  plan: SwapPlan;
+  swapTx: Record<string, any>; // unsigned executeHybridSwap
+  approveTx: Record<string, any> | null; // unsigned ERC-20 approve (if needed)
+  needsApproval: boolean;
+
+  constructor(opts: {
+    plan: SwapPlan;
+    swapTx: Record<string, any>;
+    approveTx?: Record<string, any> | null;
+    needsApproval?: boolean;
+  }) {
+    this.plan = opts.plan;
+    this.swapTx = opts.swapTx;
+    this.approveTx = opts.approveTx ?? null;
+    this.needsApproval = opts.needsApproval ?? false;
+  }
+
+  get isSafe(): boolean {
+    return this.plan?.isSafe ?? false;
+  }
+
+  summary(): string {
+    const appr = this.needsApproval ? " +approve" : "";
+    return `SwapBuild(${this.plan.summary()}${appr})`;
+  }
+}

package/src/safety.ts

@@ -0,0 +1,152 @@
+/**
+ * Swap-safety configuration and the inspectable {@link SwapPlan}.
+ *
+ * The SDK never lets funds move on a route it has not (a) integrity-checked and
+ * (b) — when possible — simulated end-to-end. {@link SwapPlan} is the artifact of
+ * that work: the chosen route, every candidate it beat, the realized output from
+ * an on-chain simulation, the slippage floor, price-impact and the honeypot/tax
+ * probe. `execute` builds a plan, enforces {@link SafetyConfig}, sends, then
+ * asserts the received balance actually grew by `minOut` (trust the chain).
+ */
+
+import type { SwapPath, TokenInfo } from "./types.js";
+
+// Defaults aligned with mainstream SDKs (Uniswap interface / 1inch).
+export const DEFAULT_SLIPPAGE_BPS = 50; // 0.5%
+export const DEFAULT_DEADLINE_SECS = 1200; // 20 min
+export const DEFAULT_PROBE_VALUE = 10n ** 16n; // 0.01 native, for the getTokenInfos honeypot probe
+
+/** Tunable guard rails. Pass one to `new SallyClient(..., { safety })` or per call. */
+export class SafetyConfig {
+  readonly slippageBps: number;
+  readonly deadlineSecs: number;
+  // price impact (bps of expected-at-marginal-price)
+  readonly priceImpactWarnBps: number;
+  readonly priceImpactBlockBps: number;
+  // transfer tax (bps), measured by the getTokenInfos round-trip probe
+  readonly taxWarnBps: number;
+  readonly taxBlockBps: number;
+  // toggles
+  readonly checkIntegrity: boolean;
+  readonly checkHoneypot: boolean;
+  readonly simulate: boolean;
+  readonly balanceDeltaAssert: boolean;
+  readonly probeValue: bigint;
+  // approval: exact-amount by default (safer than infinite approve)
+  readonly unlimitedApproval: boolean;
+
+  constructor(opts: Partial<SafetyConfigFields> = {}) {
+    this.slippageBps = opts.slippageBps ?? DEFAULT_SLIPPAGE_BPS;
+    this.deadlineSecs = opts.deadlineSecs ?? DEFAULT_DEADLINE_SECS;
+    this.priceImpactWarnBps = opts.priceImpactWarnBps ?? 500; // 5%  -> warning
+    this.priceImpactBlockBps = opts.priceImpactBlockBps ?? 1500; // 15% -> hard block
+    this.taxWarnBps = opts.taxWarnBps ?? 1000; // 10%
+    this.taxBlockBps = opts.taxBlockBps ?? 5000; // 50%
+    this.checkIntegrity = opts.checkIntegrity ?? true;
+    this.checkHoneypot = opts.checkHoneypot ?? true;
+    this.simulate = opts.simulate ?? true;
+    this.balanceDeltaAssert = opts.balanceDeltaAssert ?? true;
+    this.probeValue = opts.probeValue ?? DEFAULT_PROBE_VALUE;
+    this.unlimitedApproval = opts.unlimitedApproval ?? false;
+  }
+
+  /** Return a copy with some fields overridden (mirrors dataclasses.replace). */
+  replace(opts: Partial<SafetyConfigFields>): SafetyConfig {
+    return new SafetyConfig({ ...this.fields(), ...opts });
+  }
+
+  private fields(): SafetyConfigFields {
+    return {
+      slippageBps: this.slippageBps,
+      deadlineSecs: this.deadlineSecs,
+      priceImpactWarnBps: this.priceImpactWarnBps,
+      priceImpactBlockBps: this.priceImpactBlockBps,
+      taxWarnBps: this.taxWarnBps,
+      taxBlockBps: this.taxBlockBps,
+      checkIntegrity: this.checkIntegrity,
+      checkHoneypot: this.checkHoneypot,
+      simulate: this.simulate,
+      balanceDeltaAssert: this.balanceDeltaAssert,
+      probeValue: this.probeValue,
+      unlimitedApproval: this.unlimitedApproval,
+    };
+  }
+}
+
+export interface SafetyConfigFields {
+  slippageBps: number;
+  deadlineSecs: number;
+  priceImpactWarnBps: number;
+  priceImpactBlockBps: number;
+  taxWarnBps: number;
+  taxBlockBps: number;
+  checkIntegrity: boolean;
+  checkHoneypot: boolean;
+  simulate: boolean;
+  balanceDeltaAssert: boolean;
+  probeValue: bigint;
+  unlimitedApproval: boolean;
+}
+
+/** One quoted route plus its simulated realized output (null if it reverted). */
+export class RouteCandidate {
+  label: string;
+  route: SwapPath;
+  quotedOut: bigint;
+  simulatedOut: bigint | null;
+  integrityProblems: string[];
+
+  constructor(label: string, route: SwapPath, quotedOut: bigint, simulatedOut: bigint | null = null, integrityProblems: string[] = []) {
+    this.label = label;
+    this.route = route;
+    this.quotedOut = quotedOut;
+    this.simulatedOut = simulatedOut;
+    this.integrityProblems = integrityProblems;
+  }
+
+  get usable(): boolean {
+    return this.integrityProblems.length === 0 && (this.simulatedOut === null || this.simulatedOut > 0n);
+  }
+
+  /** Ranking key: realized output if simulated, else the quote. */
+  get score(): bigint {
+    return this.simulatedOut !== null ? this.simulatedOut : this.quotedOut;
+  }
+}
+
+/** A fully-vetted swap, ready to execute (or inspect/reject). */
+export class SwapPlan {
+  constructor(
+    public tokenIn: string,
+    public tokenOut: string,
+    public amountIn: bigint,
+    public route: SwapPath,
+    public quotedOut: bigint,
+    public simulatedOut: bigint | null,
+    public minOut: bigint,
+    public priceImpactBps: number | null,
+    public tokenSafety: TokenInfo | null,
+    public candidates: RouteCandidate[],
+    public warnings: string[] = [],
+    public blockReasons: string[] = [],
+  ) {}
+
+  get isSafe(): boolean {
+    return this.blockReasons.length === 0;
+  }
+
+  /** Best available estimate of output (simulated if present, else quoted). */
+  get expectedOut(): bigint {
+    return this.simulatedOut !== null ? this.simulatedOut : this.quotedOut;
+  }
+
+  summary(): string {
+    const sim = this.simulatedOut !== null ? `${this.simulatedOut}` : "n/a";
+    return (
+      `SwapPlan(${this.amountIn} ${this.tokenIn.slice(0, 8)}… -> ${this.tokenOut.slice(0, 8)}…  ` +
+      `out~${this.expectedOut} sim=${sim} min=${this.minOut} ` +
+      `impact=${this.priceImpactBps}bps steps=${this.route.stepCount} ` +
+      `${this.isSafe ? "SAFE" : "BLOCKED:" + this.blockReasons.join(",")})`
+    );
+  }
+}

package/src/token.ts

@@ -0,0 +1,254 @@
+/**
+ * ERC-20 helpers: metadata, balances, approvals and human <-> raw amounts.
+ *
+ * Anything with non-18 decimals (USDC = 6, WBTC = 8) needs explicit scaling.
+ * {@link TokenAmount} carries the decimals with the value so you never multiply
+ * by the wrong power.
+ */
+
+import { Contract, getAddress } from "ethers";
+import type { SallyClient } from "./client.js";
+
+// The native gas token sentinel used across DeFi for ETH/BNB.
+export const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+export const ZERO = "0x0000000000000000000000000000000000000000";
+export const MAX_UINT256 = 2n ** 256n - 1n;
+
+// Minimal ERC-20 ABI — enough for reads + approve.
+export const ERC20_ABI = [
+  { name: "name", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+  { name: "symbol", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+  { name: "decimals", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+  { name: "totalSupply", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "uint256" }] },
+  { name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "a", type: "address" }], outputs: [{ type: "uint256" }] },
+  { name: "allowance", type: "function", stateMutability: "view", inputs: [{ name: "o", type: "address" }, { name: "s", type: "address" }], outputs: [{ type: "uint256" }] },
+  { name: "approve", type: "function", stateMutability: "nonpayable", inputs: [{ name: "s", type: "address" }, { name: "v", type: "uint256" }], outputs: [{ type: "bool" }] },
+  { name: "transfer", type: "function", stateMutability: "nonpayable", inputs: [{ name: "t", type: "address" }, { name: "v", type: "uint256" }], outputs: [{ type: "bool" }] },
+  // EIP-2612
+  { name: "nonces", type: "function", stateMutability: "view", inputs: [{ name: "o", type: "address" }], outputs: [{ type: "uint256" }] },
+  { name: "DOMAIN_SEPARATOR", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "bytes32" }] },
+  { name: "version", type: "function", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+  {
+    name: "permit", type: "function", stateMutability: "nonpayable", inputs: [
+      { name: "owner", type: "address" }, { name: "spender", type: "address" },
+      { name: "value", type: "uint256" }, { name: "deadline", type: "uint256" },
+      { name: "v", type: "uint8" }, { name: "r", type: "bytes32" }, { name: "s", type: "bytes32" },
+    ], outputs: [],
+  },
+] as const;
+
+export function isNative(address: string): boolean {
+  return address.toLowerCase() === NATIVE.toLowerCase() || address.toLowerCase() === ZERO.toLowerCase();
+}
+
+/**
+ * Convert a human amount to raw base units. Sub-unit precision is truncated
+ * toward zero (e.g. `0.0000001` of a 6-decimal token -> `0` raw), matching
+ * Python's `int()` semantics.
+ */
+export function humanToRaw(amount: string | number | bigint, decimals: number): bigint {
+  if (typeof amount === "bigint") return amount * 10n ** BigInt(decimals);
+  let s = typeof amount === "number" ? numberToPlainString(amount) : String(amount).trim();
+  let neg = false;
+  if (s.startsWith("-")) {
+    neg = true;
+    s = s.slice(1);
+  } else if (s.startsWith("+")) {
+    s = s.slice(1);
+  }
+  let [intPart, fracPart = ""] = s.split(".");
+  if (intPart === "") intPart = "0";
+  // Truncate toward zero: keep at most `decimals` fractional digits.
+  fracPart = fracPart.slice(0, decimals).padEnd(decimals, "0");
+  const combined = `${intPart}${fracPart}`.replace(/^0+(?=\d)/, "");
+  let result = BigInt(combined || "0");
+  if (neg) result = -result;
+  return result;
+}
+
+/** Render `number` without scientific notation so BigInt parsing is exact. */
+function numberToPlainString(n: number): string {
+  if (Number.isInteger(n)) return n.toFixed(0);
+  const s = String(n);
+  if (!/e/i.test(s)) return s;
+  // Expand exponent notation (e.g. 1e-7) into plain decimal.
+  const [mantissa, expRaw] = s.split(/e/i);
+  const exp = Number(expRaw);
+  const sign = mantissa.startsWith("-") ? "-" : "";
+  const digits = mantissa.replace("-", "").replace(".", "");
+  const pointIdx = (mantissa.replace("-", "").indexOf(".") === -1)
+    ? mantissa.replace("-", "").length
+    : mantissa.replace("-", "").indexOf(".");
+  let newPoint = pointIdx + exp;
+  if (newPoint <= 0) {
+    return `${sign}0.${"0".repeat(-newPoint)}${digits}`;
+  }
+  if (newPoint >= digits.length) {
+    return `${sign}${digits}${"0".repeat(newPoint - digits.length)}`;
+  }
+  return `${sign}${digits.slice(0, newPoint)}.${digits.slice(newPoint)}`;
+}
+
+/** Convert raw base units back to a human float. */
+export function rawToHuman(raw: bigint, decimals: number): number {
+  return Number(raw) / 10 ** decimals;
+}
+
+/**
+ * A token amount that knows its own decimals.
+ *
+ * `TokenAmount.fromHuman("1.5", 6).raw`  ->  1500000n  (1.5 USDC)
+ */
+export class TokenAmount {
+  constructor(public readonly raw: bigint, public readonly decimals: number) {}
+
+  static fromHuman(amount: string | number | bigint, decimals: number): TokenAmount {
+    return new TokenAmount(humanToRaw(amount, decimals), decimals);
+  }
+
+  get human(): number {
+    return rawToHuman(this.raw, this.decimals);
+  }
+
+  toBigInt(): bigint {
+    return this.raw;
+  }
+}
+
+/** A live ERC-20 bound to a client. Metadata is fetched lazily and cached. */
+export class Token {
+  readonly client: SallyClient;
+  readonly address: string;
+  readonly contract: Contract;
+  private _decimals: number | null = null;
+  private _symbol: string | null = null;
+
+  constructor(client: SallyClient, address: string) {
+    this.client = client;
+    this.address = getAddress(address);
+    this.contract = new Contract(this.address, ERC20_ABI as any, client.w3);
+  }
+
+  // -- metadata --------------------------------------------------------- //
+  async decimals(): Promise<number> {
+    if (this._decimals === null) {
+      this._decimals = Number(await this.contract.decimals());
+    }
+    return this._decimals;
+  }
+
+  async symbol(): Promise<string> {
+    if (this._symbol === null) {
+      try {
+        this._symbol = await this.contract.symbol();
+      } catch {
+        this._symbol = "?";
+      }
+    }
+    return this._symbol!;
+  }
+
+  // -- reads ------------------------------------------------------------ //
+  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 toHuman(raw: bigint): Promise<number> {
+    return rawToHuman(raw, await this.decimals());
+  }
+
+  // -- writes ----------------------------------------------------------- //
+  /** Approve `spender` (defaults to unlimited). Returns a receipt. */
+  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);
+  }
+
+  /** Unsigned ERC-20 approve tx (for sign-externally mode). */
+  async buildApprove(spender: string, amount: bigint = MAX_UINT256): Promise<Record<string, any>> {
+    const fn = this.contract.getFunction("approve");
+    return this.client.send(fn, [getAddress(spender), amount], { simulate: false, buildOnly: true });
+  }
+
+  /**
+   * Approve only if the current allowance is insufficient (idempotent).
+   *
+   * Approves exactly `amount` (pass `MAX_UINT256` for unlimited) — never silently
+   * escalates to infinite.
+   */
+  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);
+  }
+
+  // -- EIP-2612 permit -------------------------------------------------- //
+  /** True if the token exposes EIP-2612 `nonces` + `DOMAIN_SEPARATOR`. */
+  async supportsPermit(): Promise<boolean> {
+    try {
+      await this.contract.nonces(ZERO);
+      await this.contract.DOMAIN_SEPARATOR();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async _permitVersion(): Promise<string> {
+    try {
+      return String(await this.contract.version());
+    } catch {
+      return "1";
+    }
+  }
+
+  /**
+   * Set an allowance via an EIP-2612 signature (one `permit` tx, no approve).
+   *
+   * `value` is required (pass `MAX_UINT256` explicitly for unlimited) so an
+   * infinite allowance is never granted by accident. Requires the client's signer
+   * to own the tokens. Returns the receipt.
+   */
+  async permit(
+    spender: string,
+    value: bigint,
+    opts: { deadline?: number; tx?: Record<string, any> } = {},
+  ): Promise<any> {
+    const { signPermit2612 } = await import("./permit2.js");
+
+    const owner = this.client.requireAddress();
+    const account = this.client.account;
+    if (account === null) throw new Error("permit requires a signer");
+    spender = getAddress(spender);
+    let deadline = opts.deadline;
+    if (deadline === undefined) {
+      const block = await this.client.w3.getBlock("latest");
+      deadline = Number(block!.timestamp) + 1200;
+    }
+    const nonce = Number(await this.contract.nonces(owner));
+    const name = await this.contract.name();
+    const [v, r, s] = await signPermit2612(account, {
+      token: this.address,
+      tokenName: name,
+      version: await this._permitVersion(),
+      chainId: this.client.chainId,
+      owner,
+      spender,
+      value,
+      nonce,
+      deadline,
+    });
+    const fn = this.contract.getFunction("permit");
+    return this.client.send(fn, [owner, spender, value, deadline, v, r, s], opts.tx ?? {});
+  }
+}