viem-tx-sim 0.1.0

package/src/internal/probes.ts

@@ -0,0 +1,221 @@
+import type { Address, Hex, StateOverride } from "viem";
+import { encodeFunctionData, erc20Abi } from "viem";
+
+import { addressKey } from "./data.js";
+import { withRpcDebug } from "./rpc.js";
+import { getCallData, uint256Hex } from "./data.js";
+import type { RpcCallArgs } from "./rpc.js";
+import { blockOptionsSpread, buildCallParameters, createAccessList } from "./rpc.js";
+
+type ProbedSlot = {
+  token: Address;
+  slot: Hex;
+};
+
+type ProbedAllowanceSlot = ProbedSlot & {
+  spender: Address;
+};
+
+async function readBalanceOf(
+  args: RpcCallArgs & {
+    token: Address;
+    owner: Address;
+    stateOverride?: StateOverride;
+    debugStep?: string;
+  },
+): Promise<bigint | undefined> {
+  const data = encodeFunctionData({
+    abi: erc20Abi,
+    functionName: "balanceOf",
+    args: [args.owner],
+  });
+
+  return readUint256Call({
+    client: args.client,
+    account: args.owner,
+    to: args.token,
+    data,
+    stateOverride: args.stateOverride,
+    gas: args.gas,
+    debug: args.debug,
+    debugStep: args.debugStep ?? "erc20.balanceOf",
+    ...blockOptionsSpread(args),
+  });
+}
+
+export async function readAllowance(
+  args: RpcCallArgs & {
+    token: Address;
+    owner: Address;
+    spender: Address;
+    stateOverride?: StateOverride;
+    debugStep?: string;
+  },
+): Promise<bigint | undefined> {
+  const data = encodeFunctionData({
+    abi: erc20Abi,
+    functionName: "allowance",
+    args: [args.owner, args.spender],
+  });
+
+  return readUint256Call({
+    client: args.client,
+    account: args.owner,
+    to: args.token,
+    data,
+    stateOverride: args.stateOverride,
+    gas: args.gas,
+    debug: args.debug,
+    debugStep: args.debugStep ?? "erc20.allowance",
+    ...blockOptionsSpread(args),
+  });
+}
+
+export async function discoverBalanceSlot(
+  args: RpcCallArgs & {
+    token: Address;
+    owner: Address;
+    sentinel: bigint;
+  },
+): Promise<ProbedSlot | undefined> {
+  const data = encodeFunctionData({
+    abi: erc20Abi,
+    functionName: "balanceOf",
+    args: [args.owner],
+  });
+
+  let storageKeys: Hex[];
+  try {
+    const accessList = await createAccessList({
+      client: args.client,
+      from: args.owner,
+      to: args.token,
+      data,
+      gas: args.gas,
+      debug: args.debug,
+      debugStep: "balanceSlot.accessList",
+      ...blockOptionsSpread(args),
+    });
+    storageKeys = accessList
+      .filter((entry) => addressKey(entry.address) === addressKey(args.token))
+      .flatMap((entry) => entry.storageKeys);
+  } catch {
+    return undefined;
+  }
+
+  const sentinelHex = uint256Hex(args.sentinel);
+  for (const slot of storageKeys) {
+    const balance = await readBalanceOf({
+      client: args.client,
+      token: args.token,
+      owner: args.owner,
+      stateOverride: [{ address: args.token, stateDiff: [{ slot, value: sentinelHex }] }],
+      gas: args.gas,
+      debug: args.debug,
+      debugStep: "balanceSlot.verify",
+      ...blockOptionsSpread(args),
+    });
+    if (balance === args.sentinel) return { token: args.token, slot };
+  }
+
+  return undefined;
+}
+
+export async function discoverAllowanceSlot(
+  args: RpcCallArgs & {
+    token: Address;
+    owner: Address;
+    spender: Address;
+    sentinel: bigint;
+  },
+): Promise<ProbedAllowanceSlot | undefined> {
+  const data = encodeFunctionData({
+    abi: erc20Abi,
+    functionName: "allowance",
+    args: [args.owner, args.spender],
+  });
+
+  let storageKeys: Hex[];
+  try {
+    const accessList = await createAccessList({
+      client: args.client,
+      from: args.owner,
+      to: args.token,
+      data,
+      gas: args.gas,
+      debug: args.debug,
+      debugStep: "allowanceSlot.accessList",
+      ...blockOptionsSpread(args),
+    });
+    storageKeys = accessList
+      .filter((entry) => addressKey(entry.address) === addressKey(args.token))
+      .flatMap((entry) => entry.storageKeys);
+  } catch {
+    return undefined;
+  }
+
+  const sentinelHex = uint256Hex(args.sentinel);
+  for (const slot of storageKeys) {
+    const allowance = await readAllowance({
+      client: args.client,
+      token: args.token,
+      owner: args.owner,
+      spender: args.spender,
+      stateOverride: [{ address: args.token, stateDiff: [{ slot, value: sentinelHex }] }],
+      gas: args.gas,
+      debug: args.debug,
+      debugStep: "allowanceSlot.verify",
+      ...blockOptionsSpread(args),
+    });
+    if (allowance === args.sentinel) {
+      return {
+        token: args.token,
+        spender: args.spender,
+        slot,
+      };
+    }
+  }
+
+  return undefined;
+}
+
+async function readUint256Call(
+  args: RpcCallArgs & {
+    account: Address;
+    to: Address;
+    data: Hex;
+    stateOverride?: StateOverride;
+    debugStep: string;
+  },
+): Promise<bigint | undefined> {
+  try {
+    const result = await withRpcDebug(
+      args.debug,
+      {
+        method: "eth_call",
+        step: args.debugStep,
+        details: {
+          account: args.account,
+          to: args.to,
+          stateOverrides: args.stateOverride?.length ?? 0,
+        },
+      },
+      () =>
+        args.client.call(
+          buildCallParameters({
+            account: args.account,
+            to: args.to,
+            data: args.data,
+            stateOverride: args.stateOverride,
+            gas: args.gas,
+            ...blockOptionsSpread(args),
+          }),
+        ),
+    );
+    const data = getCallData(result);
+    if (data.length < 66) return undefined;
+    return BigInt(data);
+  } catch {
+    return undefined;
+  }
+}

package/src/internal/requirements.ts

@@ -0,0 +1,240 @@
+import type { Address, Hex } from "viem";
+import { decodeFunctionData, parseAbi } from "viem";
+
+import { InvalidSimulationInputError } from "../errors.js";
+import type {
+  AllowanceSlotPair,
+  EstimatedAssetRequirements,
+  EstimateAssetRequirementsArgs,
+  SimulatedCall,
+} from "../types.js";
+import { prepareAllowanceOverrides, prepareBalanceOverrides } from "./slots.js";
+import { addressKey, uniqueAddresses } from "./data.js";
+import type { ClientArgs } from "./rpc.js";
+import { blockOptionsSpread } from "./rpc.js";
+import { discoverCandidateAddresses, runSimulator } from "./simulator.js";
+
+const allowanceSettingAbi = parseAbi([
+  "function approve(address spender, uint256 amount) returns (bool)",
+  "function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)",
+]);
+
+type AllowanceProbe = {
+  token: Address;
+  spender: Address;
+};
+
+/** @internal Implements {@link TxSimulator.estimateAssetRequirements}. Prefer the instance API from the package root. */
+export async function estimateAssetRequirements(
+  args: EstimateAssetRequirementsArgs & ClientArgs,
+): Promise<EstimatedAssetRequirements> {
+  if (args.calls.length === 0) {
+    throw new InvalidSimulationInputError("estimateAssetRequirements 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,
+    gas: args.gas,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+  });
+  const recon = await runSimulator({
+    client: args.client,
+    from: args.from,
+    calls,
+    candidates: candidateAddresses,
+    allowanceProbes: [],
+    gas: args.gas,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+    ...(args.errorAbi !== undefined ? { errorAbi: args.errorAbi } : {}),
+  });
+  const tokens = recon.probeData.observedTokens;
+  const spenders = uniqueAddresses([...calls.map((call) => call.to), ...candidateAddresses]).filter(
+    (address) => addressKey(address) !== addressKey(args.from),
+  );
+
+  const balanceOverrides = await prepareBalanceOverrides({
+    client: args.client,
+    from: args.from,
+    tokens,
+    gas: args.gas,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+  });
+  const allowanceOverrides = await prepareAllowanceOverrides({
+    client: args.client,
+    from: args.from,
+    pairs: allowancePairs(tokens, spenders),
+    gas: args.gas,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+  });
+  const balanceSlots = balanceOverrides.slots;
+  const allowanceSlots = allowanceOverrides.slots;
+  const allowanceProbes = allowanceSlots.map((slot) => ({
+    token: slot.token,
+    spender: slot.spender,
+  }));
+  const tokenSlotOverrides = [...balanceSlots, ...allowanceSlots];
+  const measurement = await runSimulator({
+    client: args.client,
+    from: args.from,
+    calls,
+    candidates: candidateAddresses,
+    tokenSlotOverrides,
+    allowanceProbes,
+    gas: args.gas,
+    debug: args.debug,
+    ...blockOptionsSpread(args),
+    ...(args.errorAbi !== undefined ? { errorAbi: args.errorAbi } : {}),
+  });
+  const measuredAllowances = requiredAllowances(
+    args.from,
+    calls,
+    allowanceProbes,
+    measurement.probeData.allowanceCheckpoints,
+    measurement.probeData.candidates,
+    measurement.probeData.maxTokenOutflows,
+  );
+
+  const shared = {
+    native: measurement.probeData.maxNativeOutflow,
+    balances: requiredBalances(
+      measurement.probeData.candidates,
+      tokens,
+      measurement.probeData.maxTokenOutflows,
+    ),
+    allowances: measuredAllowances.allowances,
+    slots: tokenSlotOverrides,
+    unresolved: {
+      balanceSlots: balanceOverrides.unresolved,
+      allowanceSlots: allowanceOverrides.unresolved,
+      allowances: measuredAllowances.discarded,
+    },
+  };
+
+  if (measurement.status === "reverted") {
+    return {
+      status: "reverted",
+      ...shared,
+      revertData: measurement.revertData,
+      ...(measurement.revertReason !== undefined ? { revertReason: measurement.revertReason } : {}),
+      ...(measurement.revertError !== undefined ? { revertError: measurement.revertError } : {}),
+      ...(measurement.revertSelector !== undefined
+        ? { revertSelector: measurement.revertSelector }
+        : {}),
+      failingCallIndex: measurement.failingCallIndex,
+    };
+  }
+
+  return { status: "success", ...shared };
+}
+
+function allowancePairs(
+  tokens: readonly Address[],
+  spenders: readonly Address[],
+): AllowanceSlotPair[] {
+  return tokens.flatMap((token) =>
+    spenders
+      .filter((spender) => addressKey(token) !== addressKey(spender))
+      .map((spender) => ({ token, spender })),
+  );
+}
+
+function requiredBalances(
+  candidates: readonly Address[],
+  tokens: readonly Address[],
+  maxTokenOutflows: readonly bigint[],
+): EstimatedAssetRequirements["balances"] {
+  const tokenKeys = new Set(tokens.map(addressKey));
+  const balances: EstimatedAssetRequirements["balances"] = [];
+  for (let i = 0; i < candidates.length; ++i) {
+    const amount = maxTokenOutflows[i] ?? 0n;
+    const token = candidates[i];
+    if (token !== undefined && amount > 0n && tokenKeys.has(addressKey(token))) {
+      balances.push({ token, amount });
+    }
+  }
+  return balances;
+}
+
+function requiredAllowances(
+  owner: Address,
+  calls: readonly SimulatedCall[],
+  probes: readonly AllowanceProbe[],
+  checkpoints: readonly bigint[],
+  candidates: readonly Address[],
+  maxTokenOutflows: readonly bigint[],
+): {
+  allowances: EstimatedAssetRequirements["allowances"];
+  discarded: AllowanceSlotPair[];
+} {
+  const allowances: EstimatedAssetRequirements["allowances"] = [];
+  const discarded: AllowanceSlotPair[] = [];
+  const stride = calls.length + 1;
+
+  for (let probeIndex = 0; probeIndex < probes.length; ++probeIndex) {
+    const probe = probes[probeIndex];
+    if (probe === undefined) continue;
+
+    const firstAllowanceSetIndex = firstInBatchAllowanceSetIndex(calls, owner, probe);
+    const limit = firstAllowanceSetIndex ?? calls.length;
+    let amount = 0n;
+    for (let callIndex = 0; callIndex < limit; ++callIndex) {
+      const before = checkpoints[probeIndex * stride + callIndex] ?? 0n;
+      const after = checkpoints[probeIndex * stride + callIndex + 1] ?? 0n;
+      if (before > after) amount += before - after;
+    }
+    if (amount > tokenOutflow(probe.token, candidates, maxTokenOutflows)) {
+      discarded.push({ token: probe.token, spender: probe.spender });
+      continue;
+    }
+    if (amount > 0n) allowances.push({ token: probe.token, spender: probe.spender, amount });
+  }
+
+  return { allowances, discarded };
+}
+
+function firstInBatchAllowanceSetIndex(
+  calls: readonly SimulatedCall[],
+  owner: Address,
+  probe: AllowanceProbe,
+): number | undefined {
+  for (let i = 0; i < calls.length; ++i) {
+    const call = calls[i];
+    if (call === undefined || addressKey(call.to) !== addressKey(probe.token)) continue;
+    if (isAllowanceSetForSpender(call.data, owner, probe.spender)) return i;
+  }
+  return undefined;
+}
+
+function isAllowanceSetForSpender(data: Hex, owner: Address, spender: Address): boolean {
+  try {
+    const decoded = decodeFunctionData({ abi: allowanceSettingAbi, data });
+    if (decoded.functionName === "approve")
+      return addressKey(decoded.args[0]) === addressKey(spender);
+    return (
+      addressKey(decoded.args[0]) === addressKey(owner) &&
+      addressKey(decoded.args[1]) === addressKey(spender)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function tokenOutflow(
+  token: Address,
+  candidates: readonly Address[],
+  maxTokenOutflows: readonly bigint[],
+): bigint {
+  const index = candidates.findIndex((candidate) => addressKey(candidate) === addressKey(token));
+  return index === -1 ? 0n : (maxTokenOutflows[index] ?? 0n);
+}

package/src/internal/rpc.ts

@@ -0,0 +1,207 @@
+import type {
+  AccessList,
+  Address,
+  BlockTag,
+  CallParameters,
+  Hex,
+  PublicClient,
+  StateOverride,
+} from "viem";
+import { numberToHex } from "viem";
+
+import { AccessListUnsupportedError } from "../errors.js";
+import type { SimulationDebug, SimulationDebugEvent } from "../types.js";
+
+// Internal RPC layer: shared argument types, call-shaping helpers, then RPC wrappers.
+// Add new RPC methods here so debug and infrastructure-error behavior stays consistent.
+export type BlockOptions = {
+  blockNumber?: bigint;
+  blockTag?: BlockTag;
+};
+
+/** Attaches the bound viem client to public per-call args for internal implementations. */
+export type ClientArgs = { client: PublicClient };
+
+export type RpcCallArgs = {
+  client: PublicClient;
+  gas?: bigint;
+  debug?: SimulationDebug;
+} & BlockOptions;
+
+/** Returns the block selector for RPC calls; `blockNumber` takes precedence over `blockTag`. */
+export function blockOptionsSpread(args: BlockOptions): BlockOptions {
+  return args.blockNumber !== undefined
+    ? { blockNumber: args.blockNumber }
+    : args.blockTag !== undefined
+      ? { blockTag: args.blockTag }
+      : {};
+}
+
+export function buildCallParameters(
+  args: {
+    account: Address;
+    to: Address;
+    data: Hex;
+    gas?: bigint;
+    stateOverride?: StateOverride;
+  } & BlockOptions,
+): CallParameters {
+  const base = {
+    account: args.account,
+    to: args.to,
+    data: args.data,
+    ...(args.stateOverride !== undefined ? { stateOverride: args.stateOverride } : {}),
+    ...(args.gas !== undefined ? { gas: args.gas } : {}),
+  };
+  return (
+    args.blockNumber !== undefined
+      ? { ...base, blockNumber: args.blockNumber }
+      : { ...base, ...(args.blockTag !== undefined ? { blockTag: args.blockTag } : {}) }
+  ) satisfies CallParameters;
+}
+
+export type AccessListEntry = AccessList[number];
+
+type AccessListRpcRequest = {
+  from: Address;
+  to: Address;
+  data: Hex;
+  value?: Hex;
+  gas?: Hex;
+};
+
+type AccessListRpcResult = {
+  accessList?: AccessList;
+  gasUsed?: Hex;
+  error?: string | { message?: string };
+};
+
+export async function createAccessList(
+  args: RpcCallArgs & {
+    from: Address;
+    to: Address;
+    data: Hex;
+    value?: bigint;
+    debugStep?: string;
+  },
+): Promise<AccessList> {
+  const request = {
+    from: args.from,
+    to: args.to,
+    data: args.data,
+    ...(args.value !== undefined ? { value: numberToHex(args.value) } : {}),
+    ...(args.gas !== undefined ? { gas: numberToHex(args.gas) } : {}),
+  } satisfies AccessListRpcRequest;
+  const block =
+    args.blockNumber !== undefined ? numberToHex(args.blockNumber) : (args.blockTag ?? "latest");
+
+  try {
+    const result = await withRpcDebug(
+      args.debug,
+      {
+        method: "eth_createAccessList",
+        step: args.debugStep ?? "createAccessList",
+        details: {
+          from: args.from,
+          to: args.to,
+          hasValue: (args.value ?? 0n) > 0n,
+          hasGas: args.gas !== undefined,
+        },
+      },
+      () => requestAccessList(args.client, request, block),
+    );
+    if (result.accessList !== undefined) return result.accessList;
+    if (isRpcExecutionRevert(result.error)) return [];
+    throw new Error(formatRpcError("eth_createAccessList returned no access list", result.error));
+  } catch (cause) {
+    if (isExecutionRevert(cause)) return [];
+    throw new AccessListUnsupportedError(formatRpcError("eth_createAccessList failed", cause));
+  }
+}
+
+export function formatRpcError(prefix: string, cause: unknown): string {
+  if (cause instanceof Error && cause.message) return `${prefix}: ${cause.message}`;
+  return prefix;
+}
+
+function isExecutionRevert(cause: unknown): boolean {
+  if (!(cause instanceof Error)) return false;
+  return /execution reverted|Execution reverted/i.test(cause.message);
+}
+
+function isRpcExecutionRevert(error: AccessListRpcResult["error"]): boolean {
+  const message = typeof error === "string" ? error : error?.message;
+  return message !== undefined && /execution reverted|Execution reverted/i.test(message);
+}
+
+async function requestAccessList(
+  client: PublicClient,
+  request: AccessListRpcRequest,
+  block: Hex | BlockTag,
+): Promise<AccessListRpcResult> {
+  return client.request<{
+    Method: "eth_createAccessList";
+    Parameters: [transaction: AccessListRpcRequest, block: Hex | BlockTag];
+    ReturnType: AccessListRpcResult;
+  }>({
+    method: "eth_createAccessList",
+    params: [request, block],
+  });
+}
+
+export function emitDebug(debug: SimulationDebug | undefined, event: SimulationDebugEvent): void {
+  if (typeof debug === "function") {
+    debug(event);
+    return;
+  }
+
+  if (debug === true || envDebugEnabled()) {
+    console.debug(formatDebugEvent(event));
+  }
+}
+
+export async function withRpcDebug<T>(
+  debug: SimulationDebug | undefined,
+  event: Omit<SimulationDebugEvent, "phase">,
+  run: () => Promise<T>,
+): Promise<T> {
+  const startedAt = Date.now();
+  emitDebug(debug, { ...event, phase: "start" });
+
+  try {
+    const result = await run();
+    emitDebug(debug, { ...event, phase: "success", durationMs: Date.now() - startedAt });
+    return result;
+  } catch (error) {
+    emitDebug(debug, {
+      ...event,
+      phase: "error",
+      durationMs: Date.now() - startedAt,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+}
+
+function envDebugEnabled(): boolean {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process
+    ?.env;
+  return env?.VIEM_TX_SIM_DEBUG_RPC === "1" || env?.DEBUG_RPC === "1";
+}
+
+function formatDebugEvent(event: SimulationDebugEvent): string {
+  const parts = [
+    `[viem-tx-sim] ${event.phase} ${event.method}`,
+    `step=${event.step}`,
+    ...(event.durationMs === undefined ? [] : [`durationMs=${event.durationMs}`]),
+    ...Object.entries(event.details ?? {}).map(([key, value]) => `${key}=${formatValue(value)}`),
+    ...(event.error ? [`error=${event.error}`] : []),
+  ];
+  return parts.join(" ");
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return `[${value.map(formatValue).join(",")}]`;
+  return String(value);
+}