viem-tx-sim 0.1.0

package/src/internal/simulator.ts

@@ -0,0 +1,306 @@
+import type { Abi, Address, Hex, StateOverride } from "viem";
+import {
+  decodeErrorResult,
+  decodeFunctionResult,
+  encodeFunctionData,
+  parseAbi,
+  slice,
+  size,
+} from "viem";
+
+import type {
+  AssetBalanceDelta,
+  SimulatedCall,
+  SimulationResult,
+  TokenSlotOverride,
+} from "../types.js";
+import { InvalidSimulationInputError, StateOverrideUnsupportedError } from "../errors.js";
+import { txSimulatorRuntimeBytecode } from "../generated/txSimulatorBytecode.js";
+import {
+  MAX_UINT256,
+  addressKey,
+  getCallData,
+  normalizeAddress,
+  uint256Hex,
+  uniqueAddresses,
+} from "./data.js";
+import type { RpcCallArgs } from "./rpc.js";
+import {
+  blockOptionsSpread,
+  buildCallParameters,
+  createAccessList,
+  formatRpcError,
+  withRpcDebug,
+} from "./rpc.js";
+
+type ProbeData = {
+  observedTokens: Address[];
+  candidates: Address[];
+  maxTokenOutflows: readonly bigint[];
+  maxNativeOutflow: bigint;
+  allowanceCheckpoints: readonly bigint[];
+};
+
+export type SimulatorResult = SimulationResult & {
+  probeData: ProbeData;
+};
+
+const txSimulatorAbi = parseAbi([
+  "struct SimulatedCall { address to; uint256 value; bytes data; }",
+  "struct AllowanceProbe { address token; address spender; }",
+  "struct SimulationResult { bool success; uint256 failingCallIndex; bytes revertData; int256 nativeDelta; address[] observedTokens; address[] deltaTokens; int256[] tokenDeltas; uint256[] maxTokenOutflows; uint256 maxNativeOutflow; uint256[] allowanceCheckpoints; }",
+  "function simulate(SimulatedCall[] calls, address[] candidates, AllowanceProbe[] probes) returns (SimulationResult)",
+  "function isValidSignature(bytes32 hash, bytes signature) view returns (bytes4)",
+]);
+
+export async function runSimulator(
+  args: RpcCallArgs & {
+    from: Address;
+    calls: readonly SimulatedCall[];
+    candidates: readonly Address[];
+    tokenSlotOverrides?: readonly TokenSlotOverride[];
+    extraStateOverrides?: readonly StateOverrideEntry[];
+    allowanceProbes?: readonly { token: Address; spender: Address }[];
+    debugStep?: string;
+    errorAbi?: Abi;
+  },
+): Promise<SimulatorResult> {
+  const candidates = uniqueAddresses(args.candidates);
+  const data = encodeFunctionData({
+    abi: txSimulatorAbi,
+    functionName: "simulate",
+    args: [
+      args.calls.map((call) => ({
+        to: call.to,
+        value: call.value ?? 0n,
+        data: call.data,
+      })),
+      candidates,
+      args.allowanceProbes ?? [],
+    ],
+  });
+
+  const stateOverride = buildStateOverride([
+    { address: args.from, code: txSimulatorRuntimeBytecode },
+    ...tokenSlotOverridesToStateDiff(args.tokenSlotOverrides ?? []),
+    ...(args.extraStateOverrides ?? []),
+  ]);
+
+  let callData: Hex;
+  try {
+    const result = await withRpcDebug(
+      args.debug,
+      {
+        method: "eth_call",
+        step: args.debugStep ?? "txSimulator.simulate",
+        details: {
+          from: args.from,
+          calls: args.calls.length,
+          candidates: candidates.length,
+          storageOverrides: args.tokenSlotOverrides?.length ?? 0,
+          stateOverrideAccounts: stateOverride.length,
+        },
+      },
+      () =>
+        args.client.call(
+          buildCallParameters({
+            account: args.from,
+            to: args.from,
+            data,
+            gas: args.gas,
+            stateOverride,
+            ...blockOptionsSpread(args),
+          }),
+        ),
+    );
+    callData = getCallData(result);
+  } catch (cause) {
+    throw new StateOverrideUnsupportedError(
+      formatRpcError("eth_call with state override failed", cause),
+    );
+  }
+
+  let result;
+  try {
+    result = decodeFunctionResult({
+      abi: txSimulatorAbi,
+      functionName: "simulate",
+      data: callData,
+    });
+  } catch (cause) {
+    throw new StateOverrideUnsupportedError(
+      formatRpcError("eth_call returned undecodable simulator output", cause),
+    );
+  }
+
+  const assetBalanceDeltas: AssetBalanceDelta[] = [];
+  if (result.nativeDelta !== 0n) {
+    assetBalanceDeltas.push({ asset: "native", delta: result.nativeDelta });
+  }
+
+  for (let i = 0; i < result.deltaTokens.length; ++i) {
+    const token = result.deltaTokens[i];
+    const delta = result.tokenDeltas[i];
+    if (token && delta !== undefined && delta !== 0n) {
+      assetBalanceDeltas.push({ asset: token, delta });
+    }
+  }
+
+  const probeData = {
+    observedTokens: uniqueAddresses(result.observedTokens),
+    candidates,
+    maxTokenOutflows: result.maxTokenOutflows,
+    maxNativeOutflow: result.maxNativeOutflow,
+    allowanceCheckpoints: result.allowanceCheckpoints,
+  };
+
+  if (!result.success) {
+    const decodedRevert = decodeRevert(result.revertData, args.errorAbi);
+    return {
+      status: "reverted",
+      assetBalanceDeltas,
+      revertData: result.revertData,
+      ...(decodedRevert.revertReason !== undefined
+        ? { revertReason: decodedRevert.revertReason }
+        : {}),
+      ...(decodedRevert.revertError !== undefined
+        ? { revertError: decodedRevert.revertError }
+        : {}),
+      ...(decodedRevert.revertSelector !== undefined
+        ? { revertSelector: decodedRevert.revertSelector }
+        : {}),
+      failingCallIndex: Number(result.failingCallIndex),
+      probeData,
+    };
+  }
+
+  return {
+    status: "success",
+    assetBalanceDeltas,
+    probeData,
+  };
+}
+
+export async function discoverCandidateAddresses(
+  args: RpcCallArgs & {
+    from: Address;
+    calls: readonly SimulatedCall[];
+  },
+): Promise<Address[]> {
+  const accessLists = await Promise.all(
+    args.calls.map((call) =>
+      createAccessList({
+        client: args.client,
+        from: args.from,
+        to: call.to,
+        data: call.data,
+        value: call.value ?? 0n,
+        gas: args.gas,
+        debug: args.debug,
+        debugStep: "candidateDiscovery.accessList",
+        ...blockOptionsSpread(args),
+      }),
+    ),
+  );
+  const candidates = args.calls.flatMap((call, index) => [
+    call.to,
+    ...(accessLists[index] ?? []).map((entry) => entry.address),
+  ]);
+
+  return uniqueAddresses(candidates);
+}
+
+type DecodedRevert = {
+  revertReason?: string;
+  revertError?: { name: string; args: readonly unknown[] };
+  revertSelector?: Hex;
+};
+
+function decodeRevert(data: Hex | undefined, errorAbi?: Abi): DecodedRevert {
+  if (!data || data === "0x") return {};
+
+  const revertSelector = size(data) >= 4 ? slice(data, 0, 4) : undefined;
+  try {
+    const decoded = decodeErrorResult({ abi: errorAbi ?? [], data });
+    return {
+      revertReason: formatReason(decoded.errorName, decoded.args ?? []),
+      revertError: { name: decoded.errorName, args: decoded.args ?? [] },
+      ...(revertSelector !== undefined ? { revertSelector } : {}),
+    };
+  } catch {
+    return revertSelector !== undefined ? { revertSelector } : {};
+  }
+}
+
+function formatReason(name: string, args: readonly unknown[]): string {
+  if (name === "Error") return String(args[0]);
+  if (name === "Panic") return `Panic(${String(args[0])})`;
+  return `${name}(${args.map((arg) => String(arg)).join(", ")})`;
+}
+
+type StateOverrideEntry = StateOverride[number];
+
+type MutableStateOverrideEntry = {
+  address: Address;
+  code?: Hex;
+  balance?: bigint;
+  stateDiff?: {
+    slot: Hex;
+    value: Hex;
+  }[];
+};
+
+function buildStateOverride(entries: readonly StateOverrideEntry[]): StateOverride {
+  const merged = new Map<string, MutableStateOverrideEntry>();
+
+  for (const entry of entries) {
+    const normalized = normalizeAddress(entry.address);
+    const key = addressKey(normalized);
+    const existing = merged.get(key) ?? { address: normalized, stateDiff: [] };
+
+    if (entry.code) existing.code = entry.code;
+    if (entry.balance !== undefined) existing.balance = entry.balance;
+    if (entry.stateDiff) {
+      const bySlot = new Map(
+        (existing.stateDiff ?? []).map((item) => [item.slot.toLowerCase(), item]),
+      );
+      for (const diff of entry.stateDiff) bySlot.set(diff.slot.toLowerCase(), diff);
+      existing.stateDiff = [...bySlot.values()];
+    }
+
+    merged.set(key, existing);
+  }
+
+  return [...merged.values()].map((entry): StateOverrideEntry => {
+    if (entry.stateDiff?.length === 0) {
+      return {
+        address: entry.address,
+        code: entry.code,
+        balance: entry.balance,
+      };
+    }
+    return entry;
+  });
+}
+
+function tokenSlotOverridesToStateDiff(overrides: readonly TokenSlotOverride[]): StateOverride {
+  const byAddress = new Map<string, MutableStateOverrideEntry>();
+
+  for (const override of overrides) {
+    if (override.amount === MAX_UINT256) {
+      throw new InvalidSimulationInputError(
+        "tokenSlotOverrides amount must be below uint256 max: max-allowance skips ERC-20 decrements and max-balance overflows incoming transfers. Use OVERRIDE_TOKEN_AMOUNT.",
+      );
+    }
+    const normalized = normalizeAddress(override.token);
+    const key = addressKey(normalized);
+    const entry = byAddress.get(key) ?? { address: normalized, stateDiff: [] };
+    entry.stateDiff?.push({
+      slot: override.slot,
+      value: uint256Hex(override.amount),
+    });
+    byAddress.set(key, entry);
+  }
+
+  return [...byAddress.values()];
+}

package/src/internal/slots.ts

@@ -0,0 +1,211 @@
+import type { Address, Hex } from "viem";
+import { encodeAbiParameters, keccak256 } from "viem";
+
+import { OVERRIDE_TOKEN_AMOUNT } from "../constants.js";
+import type {
+  PreparedAllowanceOverrides,
+  PreparedBalanceOverrides,
+  PrepareAllowanceOverridesArgs,
+  PrepareBalanceOverridesArgs,
+  TokenSlotOverride,
+} from "../types.js";
+import { addressKey, uint256Hex } from "./data.js";
+import { discoverAllowanceSlot, discoverBalanceSlot, readAllowance } from "./probes.js";
+import type { ClientArgs, RpcCallArgs } from "./rpc.js";
+import { blockOptionsSpread } from "./rpc.js";
+
+type SlotFact = {
+  token: Address;
+  slot: Hex;
+};
+
+type AllowanceSlotFact = SlotFact & {
+  spender: Address;
+};
+
+// Orchestration
+/** @internal Implements `TxSimulator.prepareBalanceOverrides`. Prefer the instance API from the package root. */
+export async function prepareBalanceOverrides(
+  args: PrepareBalanceOverridesArgs & ClientArgs,
+): Promise<PreparedBalanceOverrides> {
+  const slots = await Promise.all(
+    args.tokens.map((token) =>
+      discoverBalanceSlot({
+        client: args.client,
+        token,
+        owner: args.from,
+        sentinel: OVERRIDE_TOKEN_AMOUNT,
+        gas: args.gas,
+        debug: args.debug,
+        ...blockOptionsSpread(args),
+      }),
+    ),
+  );
+  return {
+    slots: slots.filter(isDefined).map(withOverrideAmount),
+    unresolved: args.tokens.filter((_, index) => slots[index] === undefined),
+  };
+}
+
+/** @internal Implements `TxSimulator.prepareAllowanceOverrides`. Prefer the instance API from the package root. */
+export async function prepareAllowanceOverrides(
+  args: PrepareAllowanceOverridesArgs & ClientArgs,
+): Promise<PreparedAllowanceOverrides> {
+  const slots = await prepareAllowanceOverridesWithInference({
+    client: args.client,
+    from: args.from,
+    pairs: args.pairs,
+    sentinel: OVERRIDE_TOKEN_AMOUNT,
+    gas: args.gas,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+  });
+  return {
+    slots: slots.filter(isDefined).map(withOverrideAmount),
+    unresolved: args.pairs.filter((_, index) => slots[index] === undefined),
+  };
+}
+
+function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}
+
+function withOverrideAmount<T extends SlotFact>(slot: T): T & TokenSlotOverride {
+  return { ...slot, amount: OVERRIDE_TOKEN_AMOUNT };
+}
+
+// Inference internals
+type AllowancePair = {
+  token: Address;
+  spender: Address;
+};
+
+type IndexedAllowancePair = AllowancePair & {
+  index: number;
+};
+
+async function prepareAllowanceOverridesWithInference(
+  args: RpcCallArgs & {
+    from: Address;
+    pairs: readonly AllowancePair[];
+    sentinel: bigint;
+  },
+): Promise<(AllowanceSlotFact | undefined)[]> {
+  const slots: (AllowanceSlotFact | undefined)[] = Array.from({ length: args.pairs.length });
+  const groups = groupPairsByToken(args.pairs);
+
+  await Promise.all(
+    groups.map(async (pairs) => {
+      const firstPair = pairs[0];
+      if (firstPair === undefined) return;
+
+      const firstSlot = await probeAllowanceSlot({ ...args, ...firstPair });
+      slots[firstPair.index] = firstSlot;
+      const baseSlot =
+        firstSlot === undefined
+          ? undefined
+          : inferAllowanceBaseSlot({
+              probedSlot: firstSlot.slot,
+              owner: args.from,
+              spender: firstPair.spender,
+            });
+
+      await Promise.all(
+        pairs.slice(1).map(async (pair) => {
+          slots[pair.index] =
+            baseSlot === undefined
+              ? await probeAllowanceSlot({ ...args, ...pair })
+              : await computeAllowanceSlot({ ...args, ...pair, baseSlot });
+        }),
+      );
+    }),
+  );
+
+  return slots;
+}
+
+function groupPairsByToken(pairs: readonly AllowancePair[]): IndexedAllowancePair[][] {
+  const groupsByToken = new Map<string, IndexedAllowancePair[]>();
+  for (let index = 0; index < pairs.length; ++index) {
+    const pair = pairs[index];
+    if (pair === undefined) continue;
+    const key = addressKey(pair.token);
+    const group = groupsByToken.get(key) ?? [];
+    group.push({ ...pair, index });
+    groupsByToken.set(key, group);
+  }
+  return [...groupsByToken.values()];
+}
+
+async function probeAllowanceSlot(
+  args: RpcCallArgs & {
+    from: Address;
+    token: Address;
+    spender: Address;
+    sentinel: bigint;
+  },
+): Promise<AllowanceSlotFact | undefined> {
+  return discoverAllowanceSlot({
+    client: args.client,
+    token: args.token,
+    owner: args.from,
+    spender: args.spender,
+    sentinel: args.sentinel,
+    gas: args.gas,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+  });
+}
+
+async function computeAllowanceSlot(
+  args: RpcCallArgs & {
+    from: Address;
+    token: Address;
+    spender: Address;
+    baseSlot: bigint;
+    sentinel: bigint;
+  },
+): Promise<AllowanceSlotFact | undefined> {
+  const slot = allowanceSlotFor(args.from, args.spender, args.baseSlot);
+  const allowance = await readAllowance({
+    client: args.client,
+    token: args.token,
+    owner: args.from,
+    spender: args.spender,
+    stateOverride: [
+      { address: args.token, stateDiff: [{ slot, value: uint256Hex(args.sentinel) }] },
+    ],
+    gas: args.gas,
+    debug: args.debug,
+    debugStep: "allowanceSlot.computedVerify",
+    ...blockOptionsSpread(args),
+  });
+  if (allowance === args.sentinel) return { token: args.token, spender: args.spender, slot };
+  return probeAllowanceSlot(args);
+}
+
+// Layout math
+function mappingSlot(key: Address, baseSlot: Hex | bigint): Hex {
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: "address" }, { type: "uint256" }],
+      [key, typeof baseSlot === "bigint" ? baseSlot : BigInt(baseSlot)],
+    ),
+  );
+}
+
+function allowanceSlotFor(owner: Address, spender: Address, base: bigint): Hex {
+  return mappingSlot(spender, mappingSlot(owner, base));
+}
+
+function inferAllowanceBaseSlot(args: {
+  probedSlot: Hex;
+  owner: Address;
+  spender: Address;
+}): bigint | undefined {
+  const target = args.probedSlot.toLowerCase();
+  for (let base = 0n; base <= 64n; ++base) {
+    if (allowanceSlotFor(args.owner, args.spender, base).toLowerCase() === target) return base;
+  }
+  return undefined;
+}

package/src/txSimulator.ts

@@ -0,0 +1,176 @@
+import { DEFAULT_SIMULATION_GAS_LIMIT } from "./constants.js";
+import { InvalidSimulationInputError } from "./errors.js";
+import { estimateAssetRequirements } from "./internal/requirements.js";
+import { blockOptionsSpread, type ClientArgs } from "./internal/rpc.js";
+import { discoverCandidateAddresses, runSimulator } from "./internal/simulator.js";
+import { prepareAllowanceOverrides, prepareBalanceOverrides } from "./internal/slots.js";
+import type {
+  PreparedAllowanceOverrides,
+  PreparedBalanceOverrides,
+  PrepareAllowanceOverridesArgs,
+  PrepareBalanceOverridesArgs,
+  EstimateAssetRequirementsArgs,
+  EstimatedAssetRequirements,
+  SimulateArgs,
+  SimulatedCall,
+  SimulationResult,
+  TxSimulatorConfig,
+} from "./types.js";
+
+type BoundCallDefaults = {
+  gas?: bigint;
+  debug?: TxSimulatorConfig["debug"];
+  errorAbi?: TxSimulatorConfig["errorAbi"];
+};
+
+/**
+ * Bound transaction simulator for one viem public client.
+ *
+ * Bind the RPC client once, then pass `from` per call so applications can switch accounts without
+ * rebuilding the simulator. Per-call `gas` and `debug` override defaults supplied to
+ * {@link TxSimulator.create}.
+ */
+export interface TxSimulator {
+  /**
+   * Simulates one call or sequential batch and returns raw native/token balance deltas.
+   *
+   * This uses `eth_createAccessList` for candidate discovery and one `eth_call` with state
+   * overrides that injects the simulator at `from`. It does not automatically forge balances or
+   * allowances; preparation methods return ready-to-use `tokenSlotOverrides` for view-only or
+   * unfunded accounts. Transaction reverts return `status: "reverted"` instead of throwing.
+   *
+   * @throws InvalidSimulationInputError when `calls` is empty.
+   * @throws AccessListUnsupportedError when the RPC endpoint cannot provide access lists.
+   * @throws StateOverrideUnsupportedError when the RPC endpoint cannot execute state overrides or
+   * returns undecodable simulator output.
+   *
+   * @example
+   * ```ts
+   * const sim = TxSimulator.create({ client });
+   * const result = await sim.simulate({
+   *   from,
+   *   calls: [{ to, data, value: 0n }],
+   * });
+   * ```
+   */
+  simulate: (args: SimulateArgs) => Promise<SimulationResult>;
+
+  /**
+   * Prepares ERC-20 balance overrides for `from`.
+   *
+   * Each token is probed with RPC-only access lists and sentinel state overrides. Tokens the
+   * simulator cannot `deal` by verified storage write are returned in `unresolved` rather than
+   * thrown.
+   *
+   * @throws StateOverrideUnsupportedError when the RPC endpoint cannot execute state overrides.
+   */
+  prepareBalanceOverrides: (args: PrepareBalanceOverridesArgs) => Promise<PreparedBalanceOverrides>;
+
+  /**
+   * Prepares ERC-20 allowance overrides for `from` and the requested token/spender pairs.
+   *
+   * Standard Solidity allowance layouts are inferred after one verified probe per token where
+   * possible; non-standard layouts fall back to per-pair probing. Pairs the simulator cannot `deal`
+   * via verified storage write are returned in `unresolved` rather than thrown.
+   *
+   * @throws StateOverrideUnsupportedError when the RPC endpoint cannot execute state overrides.
+   */
+  prepareAllowanceOverrides: (
+    args: PrepareAllowanceOverridesArgs,
+  ) => Promise<PreparedAllowanceOverrides>;
+
+  /**
+   * Estimates the balances and approvals needed to execute the observed path.
+   *
+   * Use this when the tokens or spenders are not known ahead of time. Returned amounts are estimated
+   * under forged balances/allowances and should be padded before display or transaction assembly;
+   * unreliable measurements are reported under `unresolved`.
+   *
+   * @throws InvalidSimulationInputError when `calls` is empty.
+   * @throws AccessListUnsupportedError when the RPC endpoint cannot provide access lists.
+   * @throws StateOverrideUnsupportedError when the RPC endpoint cannot execute state overrides or
+   * returns undecodable simulator output.
+   */
+  estimateAssetRequirements: (
+    args: EstimateAssetRequirementsArgs,
+  ) => Promise<EstimatedAssetRequirements>;
+}
+
+/** Factory for {@link TxSimulator} instances bound to one viem public client. */
+export const TxSimulator = {
+  /**
+   * Creates a simulator with optional default gas and debug settings.
+   *
+   * `gas` defaults to `DEFAULT_SIMULATION_GAS_LIMIT`; `debug` may be `true` for console logging or a
+   * callback for structured events. Per-call `gas` and `debug` take precedence over these defaults.
+   *
+   * @example
+   * ```ts
+   * const sim = TxSimulator.create({ client, debug: true });
+   * const result = await sim.simulate({ from, calls });
+   * ```
+   */
+  create(bound: TxSimulatorConfig): TxSimulator {
+    const defaults = (args: BoundCallDefaults) => {
+      const gas = args.gas ?? bound.gas ?? DEFAULT_SIMULATION_GAS_LIMIT;
+      const debug = args.debug ?? bound.debug;
+
+      return {
+        gas,
+        ...(debug !== undefined ? { debug } : {}),
+      };
+    };
+    const revertDefaults = (args: BoundCallDefaults) => {
+      const errorAbi = [...(bound.errorAbi ?? []), ...(args.errorAbi ?? [])];
+
+      return {
+        ...defaults(args),
+        ...(errorAbi.length > 0 ? { errorAbi } : {}),
+      };
+    };
+
+    return {
+      simulate: (args) => runSimulate({ ...args, ...revertDefaults(args), client: bound.client }),
+      prepareBalanceOverrides: (args) =>
+        prepareBalanceOverrides({ ...args, ...defaults(args), client: bound.client }),
+      prepareAllowanceOverrides: (args) =>
+        prepareAllowanceOverrides({ ...args, ...defaults(args), client: bound.client }),
+      estimateAssetRequirements: (args) =>
+        estimateAssetRequirements({ ...args, ...revertDefaults(args), client: bound.client }),
+    };
+  },
+};
+
+async function runSimulate(args: SimulateArgs & ClientArgs): Promise<SimulationResult> {
+  if (args.calls.length === 0) {
+    throw new InvalidSimulationInputError("simulate requires at least one call.");
+  }
+
+  const calls = args.calls.map((call) => ({
+    to: call.to,
+    data: call.data,
+    value: call.value ?? 0n,
+  })) satisfies SimulatedCall[];
+  const candidateAddresses = await discoverCandidateAddresses({
+    client: args.client,
+    from: args.from,
+    calls,
+    ...blockOptionsSpread(args),
+    gas: args.gas,
+    ...(args.debug !== undefined ? { debug: args.debug } : {}),
+  });
+
+  const tokenSlotOverrides = args.tokenSlotOverrides ?? [];
+
+  return runSimulator({
+    client: args.client,
+    from: args.from,
+    calls,
+    candidates: [...candidateAddresses, ...tokenSlotOverrides.map((slot) => slot.token)],
+    tokenSlotOverrides,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+    gas: args.gas,
+    ...(args.errorAbi !== undefined ? { errorAbi: args.errorAbi } : {}),
+  });
+}