viem-tx-sim 0.1.0

package/dist/internal/rpc.js

@@ -0,0 +1,124 @@
+import { numberToHex } from "viem";
+import { AccessListUnsupportedError } from "../errors.js";
+/** Returns the block selector for RPC calls; `blockNumber` takes precedence over `blockTag`. */
+export function blockOptionsSpread(args) {
+    return args.blockNumber !== undefined
+        ? { blockNumber: args.blockNumber }
+        : args.blockTag !== undefined
+            ? { blockTag: args.blockTag }
+            : {};
+}
+export function buildCallParameters(args) {
+    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 } : {}) });
+}
+export async function createAccessList(args) {
+    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) } : {}),
+    };
+    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, cause) {
+    if (cause instanceof Error && cause.message)
+        return `${prefix}: ${cause.message}`;
+    return prefix;
+}
+function isExecutionRevert(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    return /execution reverted|Execution reverted/i.test(cause.message);
+}
+function isRpcExecutionRevert(error) {
+    const message = typeof error === "string" ? error : error?.message;
+    return message !== undefined && /execution reverted|Execution reverted/i.test(message);
+}
+async function requestAccessList(client, request, block) {
+    return client.request({
+        method: "eth_createAccessList",
+        params: [request, block],
+    });
+}
+export function emitDebug(debug, event) {
+    if (typeof debug === "function") {
+        debug(event);
+        return;
+    }
+    if (debug === true || envDebugEnabled()) {
+        console.debug(formatDebugEvent(event));
+    }
+}
+export async function withRpcDebug(debug, event, run) {
+    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() {
+    const env = globalThis.process
+        ?.env;
+    return env?.VIEM_TX_SIM_DEBUG_RPC === "1" || env?.DEBUG_RPC === "1";
+}
+function formatDebugEvent(event) {
+    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) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Array.isArray(value))
+        return `[${value.map(formatValue).join(",")}]`;
+    return String(value);
+}
+//# sourceMappingURL=rpc.js.map

package/dist/internal/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/internal/rpc.ts"],"names":[],"mappings":"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"}

package/dist/internal/simulator.d.ts

@@ -0,0 +1,33 @@
+import type { Abi, Address, StateOverride } from "viem";
+import type { SimulatedCall, SimulationResult, TokenSlotOverride } from "../types.js";
+import type { RpcCallArgs } from "./rpc.js";
+type ProbeData = {
+    observedTokens: Address[];
+    candidates: Address[];
+    maxTokenOutflows: readonly bigint[];
+    maxNativeOutflow: bigint;
+    allowanceCheckpoints: readonly bigint[];
+};
+export type SimulatorResult = SimulationResult & {
+    probeData: ProbeData;
+};
+export declare 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>;
+export declare function discoverCandidateAddresses(args: RpcCallArgs & {
+    from: Address;
+    calls: readonly SimulatedCall[];
+}): Promise<Address[]>;
+type StateOverrideEntry = StateOverride[number];
+export {};
+//# sourceMappingURL=simulator.d.ts.map

package/dist/internal/simulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulator.d.ts","sourceRoot":"","sources":["../../src/internal/simulator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAO,aAAa,EAAE,MAAM,MAAM,CAAC;AAU7D,OAAO,KAAK,EAEV,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAWrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAS5C,KAAK,SAAS,GAAG;IACf,cAAc,EAAE,OAAO,EAAE,CAAC;IAC1B,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG;IAC/C,SAAS,EAAE,SAAS,CAAC;CACtB,CAAC;AAUF,wBAAsB,YAAY,CAChC,IAAI,EAAE,WAAW,GAAG;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,mBAAmB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,eAAe,CAAC,EAAE,SAAS;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB,GACA,OAAO,CAAC,eAAe,CAAC,CAmH1B;AAED,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,WAAW,GAAG;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CACjC,GACA,OAAO,CAAC,OAAO,EAAE,CAAC,CAsBpB;AA8BD,KAAK,kBAAkB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC"}

package/dist/internal/simulator.js

@@ -0,0 +1,199 @@
+import { decodeErrorResult, decodeFunctionResult, encodeFunctionData, parseAbi, slice, size, } from "viem";
+import { InvalidSimulationInputError, StateOverrideUnsupportedError } from "../errors.js";
+import { txSimulatorRuntimeBytecode } from "../generated/txSimulatorBytecode.js";
+import { MAX_UINT256, addressKey, getCallData, normalizeAddress, uint256Hex, uniqueAddresses, } from "./data.js";
+import { blockOptionsSpread, buildCallParameters, createAccessList, formatRpcError, withRpcDebug, } from "./rpc.js";
+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) {
+    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;
+    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 = [];
+    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) {
+    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);
+}
+function decodeRevert(data, errorAbi) {
+    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, args) {
+    if (name === "Error")
+        return String(args[0]);
+    if (name === "Panic")
+        return `Panic(${String(args[0])})`;
+    return `${name}(${args.map((arg) => String(arg)).join(", ")})`;
+}
+function buildStateOverride(entries) {
+    const merged = new Map();
+    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) => {
+        if (entry.stateDiff?.length === 0) {
+            return {
+                address: entry.address,
+                code: entry.code,
+                balance: entry.balance,
+            };
+        }
+        return entry;
+    });
+}
+function tokenSlotOverridesToStateDiff(overrides) {
+    const byAddress = new Map();
+    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()];
+}
+//# sourceMappingURL=simulator.js.map

package/dist/internal/simulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulator.js","sourceRoot":"","sources":["../../src/internal/simulator.ts"],"names":[],"mappings":"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"}

package/dist/internal/slots.d.ts

@@ -0,0 +1,7 @@
+import type { PreparedAllowanceOverrides, PreparedBalanceOverrides, PrepareAllowanceOverridesArgs, PrepareBalanceOverridesArgs } from "../types.js";
+import type { ClientArgs } from "./rpc.js";
+/** @internal Implements `TxSimulator.prepareBalanceOverrides`. Prefer the instance API from the package root. */
+export declare function prepareBalanceOverrides(args: PrepareBalanceOverridesArgs & ClientArgs): Promise<PreparedBalanceOverrides>;
+/** @internal Implements `TxSimulator.prepareAllowanceOverrides`. Prefer the instance API from the package root. */
+export declare function prepareAllowanceOverrides(args: PrepareAllowanceOverridesArgs & ClientArgs): Promise<PreparedAllowanceOverrides>;
+//# sourceMappingURL=slots.d.ts.map

package/dist/internal/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../src/internal/slots.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,EAC7B,2BAA2B,EAE5B,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,UAAU,CAAC;AAaxD,iHAAiH;AACjH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,2BAA2B,GAAG,UAAU,GAC7C,OAAO,CAAC,wBAAwB,CAAC,CAkBnC;AAED,mHAAmH;AACnH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,6BAA6B,GAAG,UAAU,GAC/C,OAAO,CAAC,0BAA0B,CAAC,CAcrC"}

package/dist/internal/slots.js

@@ -0,0 +1,129 @@
+import { encodeAbiParameters, keccak256 } from "viem";
+import { OVERRIDE_TOKEN_AMOUNT } from "../constants.js";
+import { addressKey, uint256Hex } from "./data.js";
+import { discoverAllowanceSlot, discoverBalanceSlot, readAllowance } from "./probes.js";
+import { blockOptionsSpread } from "./rpc.js";
+// Orchestration
+/** @internal Implements `TxSimulator.prepareBalanceOverrides`. Prefer the instance API from the package root. */
+export async function prepareBalanceOverrides(args) {
+    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) {
+    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(value) {
+    return value !== undefined;
+}
+function withOverrideAmount(slot) {
+    return { ...slot, amount: OVERRIDE_TOKEN_AMOUNT };
+}
+async function prepareAllowanceOverridesWithInference(args) {
+    const slots = 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) {
+    const groupsByToken = new Map();
+    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) {
+    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) {
+    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, baseSlot) {
+    return keccak256(encodeAbiParameters([{ type: "address" }, { type: "uint256" }], [key, typeof baseSlot === "bigint" ? baseSlot : BigInt(baseSlot)]));
+}
+function allowanceSlotFor(owner, spender, base) {
+    return mappingSlot(spender, mappingSlot(owner, base));
+}
+function inferAllowanceBaseSlot(args) {
+    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;
+}
+//# sourceMappingURL=slots.js.map

package/dist/internal/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.js","sourceRoot":"","sources":["../../src/internal/slots.ts"],"names":[],"mappings":"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"}

package/dist/txSimulator.d.ts

@@ -0,0 +1,83 @@
+import type { PreparedAllowanceOverrides, PreparedBalanceOverrides, PrepareAllowanceOverridesArgs, PrepareBalanceOverridesArgs, EstimateAssetRequirementsArgs, EstimatedAssetRequirements, SimulateArgs, SimulationResult, TxSimulatorConfig } from "./types.js";
+/**
+ * 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 declare 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;
+};
+//# sourceMappingURL=txSimulator.d.ts.map

package/dist/txSimulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"txSimulator.d.ts","sourceRoot":"","sources":["../src/txSimulator.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,EAC7B,2BAA2B,EAC3B,6BAA6B,EAC7B,0BAA0B,EAC1B,YAAY,EAEZ,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAQpB;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE5D;;;;;;;;OAQG;IACH,uBAAuB,EAAE,CAAC,IAAI,EAAE,2BAA2B,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAElG;;;;;;;;OAQG;IACH,yBAAyB,EAAE,CACzB,IAAI,EAAE,6BAA6B,KAChC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEzC;;;;;;;;;;;OAWG;IACH,yBAAyB,EAAE,CACzB,IAAI,EAAE,6BAA6B,KAChC,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC1C;AAED,iFAAiF;AACjF,eAAO,MAAM,WAAW;IACtB;;;;;;;;;;;OAWG;kBACW,iBAAiB,GAAG,WAAW;CA6B9C,CAAC"}