viem-tx-sim 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 frontier159
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# viem-tx-sim
+
+RPC-only transaction simulation helpers for [viem](https://viem.sh) applications: preview the asset changes of a transaction (or an ERC-5792 batch) before anyone signs it, using nothing but standard JSON-RPC.
+
+## Motivation
+
+Credit to the [apoorv X thread](https://x.com/apoorveth/status/2041544070481449266), transcribed in [motivation.md](https://github.com/frontier159/viem-tx-sim/blob/main/docs/motivation.md).
+
+Every wallet shows "asset changes" before you sign. Most do it by sending your data to a centralized simulation API — a single point of failure and a privacy leak. viem-tx-sim makes the EVM do the work itself:
+
+1. `eth_createAccessList` dry-runs each call and returns every contract the transaction touches — those become candidate tokens, with no token lists or indexers.
+2. One `eth_call` with state overrides injects a never-deployed `TxSimulator` contract **at the user's own address** and executes the calls. Because the simulator runs as the user, `address(this)` and `msg.sender` are the real account, so balance reads, allowance checks, and `msg.sender`-gated logic behave exactly as they would in the real transaction. Batch calls run sequentially in one EVM context, so an approval in call 1 is visible to a swap in call 2.
+
+That is two RPC calls for a single-call transaction, or N + 1 calls for an N-call batch. Zero servers, zero trust assumptions. See [docs/motivation.md](https://github.com/frontier159/viem-tx-sim/blob/main/docs/motivation.md) for the design's origin story, including how Permit2's ERC-1271 path and proxy-token storage are handled.
+
+## Getting started
+
+```sh
+pnpm add viem-tx-sim viem
+```
+
+This package is ESM-only (no CommonJS build) and requires Node 20 or newer. `viem` is a peer dependency, so install it alongside `viem-tx-sim` as shown above.
+
+Pre-release consumers can install from git with `pnpm add github:frontier159/viem-tx-sim`; the `prepare` script builds `dist/` with `tsc` from committed contract bytecode, so Foundry is not needed at install time.
+
+Simulate depositing 1,000 USDS into the sUSDS ERC-4626 vault on mainnet — an approve followed by a deposit, as one atomic batch:
+
+```ts
+import { createPublicClient, encodeFunctionData, http, parseAbi, parseUnits } from "viem";
+import { mainnet } from "viem/chains";
+import { DEFAULT_SIMULATION_GAS_LIMIT, TxSimulator } from "viem-tx-sim";
+
+const USDS = "0xdC035D45d973E3EC169d2276DDab16f1e407384F";
+const SUSDS = "0xa3931d71877C0E7a3148CB7Eb4463524FEc27fbD";
+
+const client = createPublicClient({ chain: mainnet, transport: http(RPC_URL) });
+const sim = TxSimulator.create({ client, gas: DEFAULT_SIMULATION_GAS_LIMIT });
+
+const user = "0xYourAddress"; // no key or signing involved — any address can be simulated
+const assets = parseUnits("1000", 18);
+
+const result = await sim.simulate({
+  from: user,
+  calls: [
+    {
+      to: USDS,
+      data: encodeFunctionData({
+        abi: parseAbi(["function approve(address spender, uint256 amount) returns (bool)"]),
+        functionName: "approve",
+        args: [SUSDS, assets],
+      }),
+    },
+    {
+      to: SUSDS,
+      data: encodeFunctionData({
+        abi: parseAbi(["function deposit(uint256 assets, address receiver) returns (uint256 shares)"]),
+        functionName: "deposit",
+        args: [assets, user],
+      }),
+    },
+  ],
+});
+
+console.log(result.status); // "success"
+console.log(result.assetBalanceDeltas);
+// [
+//   { asset: "0xdC03...384F", delta: -1000000000000000000000n }, // 1,000 USDS out
+//   { asset: "0xa393...7fbD", delta: 9xx...n },                  // sUSDS shares in
+// ]
+```
+
+Deltas are raw `bigint` amounts in each token's own units, observed from chain state alone. A revert is returned as `status: "reverted"`, never thrown; checking `status` gives typed access to `revertData` and `failingCallIndex`.
+
+`sim.simulate()` runs against the account's real balances and does not retry or forge state by itself. If `user` doesn't actually hold 1,000 USDS (say you're previewing for a view-only address), prepare and pass a balance override — see the next section. `DEFAULT_SIMULATION_GAS_LIMIT` is exported for callers that want to pass or display the default 16M simulation gas budget.
+
+## Preparing balance and allowance overrides
+
+Override preparation is explicit and cacheable. Preparation returns ready-to-use `TokenSlotOverride[]` entries, so pass them into a single simulation run:
+
+```ts
+import { TxSimulator } from "viem-tx-sim";
+
+const sim = TxSimulator.create({ client });
+const balanceOverrides = await sim.prepareBalanceOverrides({
+  from,
+  tokens: [token],
+});
+const allowanceOverrides = await sim.prepareAllowanceOverrides({
+  from,
+  pairs: [{ token, spender }],
+});
+
+const result = await sim.simulate({
+  from,
+  calls: [{ to, data }],
+  tokenSlotOverrides: [...balanceOverrides.slots, ...allowanceOverrides.slots],
+});
+```
+
+Prepared balance overrides are reusable per token/owner, and prepared allowance overrides are reusable per token/owner/spender for the block/state you trust. Preparation pre-sets `amount` to the exported `OVERRIDE_TOKEN_AMOUNT` sentinel, a non-max `10^50` value chosen so standard ERC-20 allowance decrements remain observable. Handcrafted override amounts must be below `uint256.max`; max allowance skips decrements, and max balances can overflow on incoming transfers. Deltas for real holdings still work for rebasing tokens like stETH; only dealing hypothetical balances can fail, reported in `unresolved`.
+
+## Estimating asset requirements (optional)
+
+When you don't already know which balances and approvals a transaction needs, `sim.estimateAssetRequirements()` measures them by forging generous state and observing per-call balance and allowance changes. Returned amounts are estimates measured under forged state and should be padded; pairs whose allowance is set inside the batch (approve or permit) are excluded, and measured allowance decreases are sanity-bounded by the token's gross outflow. Measurements discarded by that bound are reported under `unresolved.allowances`.
+
+```ts
+import { TxSimulator } from "viem-tx-sim";
+
+const sim = TxSimulator.create({ client });
+const requirements = await sim.estimateAssetRequirements({ from, calls });
+// requirements.allowances -> [{ token, spender, amount }]
+// requirements.balances   -> [{ token, amount }]
+// requirements.slots      -> feed to sim.simulate({ ..., tokenSlotOverrides })
+
+const result = await sim.simulate({
+  from,
+  calls,
+  tokenSlotOverrides: requirements.slots,
+});
+```
+
+## Debugging
+
+Enable logging per simulation call:
+
+```ts
+import { TxSimulator } from "viem-tx-sim";
+
+const sim = TxSimulator.create({ client });
+const result = await sim.simulate({
+  from,
+  calls: [{ to, data, value: 0n }],
+  debug: true,
+});
+```
+
+Or pass a callback to collect structured events:
+
+```ts
+await sim.simulate({
+  from,
+  calls: [{ to, data }],
+  debug: (event) => {
+    console.debug(event.method, event.step, event.phase, event.durationMs);
+  },
+});
+```
+
+## Decoding Reverts
+
+Reverted simulations always return raw `revertData` and, when present, a `revertSelector`.
+Pass custom errors as `errorAbi` on `TxSimulator.create({ client, errorAbi })` or on a single `sim.simulate({ ..., errorAbi })` call to populate `revertError` and human-readable `revertReason`.
+For example: `errorAbi: parseAbi(["error InsufficientBalance(uint256 have, uint256 want)"])`.
+
+## Known limitations
+
+Situations the simulation does not cover, or where the preview can differ from real execution. None of these throw — they show up as wrong or missing deltas, or as a simulated revert where the real transaction would succeed (or vice versa).
+
+**The account has code during simulation.** Injecting `TxSimulator` at `from` is the core trick, and it is visible on-chain logic:
+
+- Contracts that gate on "is the caller an EOA" via `extcodesize(msg.sender) == 0` see a contract during simulation and may take a different branch than the real transaction.
+- Receiving ERC-721/1155 tokens via `safeTransferFrom`/`safeMint` succeeds: `TxSimulator` implements `onERC721Received`, `onERC1155Received`, and `onERC1155BatchReceived`, so safe transfers into the simulated account match real execution for EOAs and contract wallets.
+- ERC-777 `send` to the simulated account reverts unless the account has a real ERC-1820 registration on-chain.
+- Permit2-style signature checks are handled for EOAs: the injected `isValidSignature` performs the same ECDSA recovery the real `ecrecover` path would.
+
+**Smart-contract wallets (e.g. a Gnosis Safe) are treated as plain senders.** Using a Safe as `from` works: the code override replaces the wallet's bytecode but keeps its storage, ETH, and token balances, and every call executes with `msg.sender` = the wallet. What is *not* modeled is the wallet itself:
+
+- The injected `isValidSignature` **replaces the wallet's own ERC-1271 validation** and only accepts EOA-style signatures recovering to `from`. Flows that require the wallet's real contract-signature logic (Permit2 permits or orders signed by the Safe itself) simulate as reverted. This is intentional — the goal is simulating downstream protocol behavior, not the wallet's signing machinery.
+- Guards, modules, owner thresholds, nonces, and `operation=DELEGATECALL` batches are outside the simulation. A transaction guard that would block the real execution is invisible to the preview.
+- `tx.origin` is the `from` address during simulation; in real execution it is the submitting EOA.
+
+**An adversarial contract can detect it is being simulated** — via the code at `from`, the recognizable forged balances, or `eth_call` context — and behave differently in the real transaction. This is inherent to state-override simulation (centralized simulation APIs share it). Treat the preview as best-effort insight, not a security guarantee against malicious contracts.
+
+**Results are estimates against one block's state.** Deltas and estimated asset requirements reflect the chosen block; prices, liquidity, and allowances move before the real transaction lands. Pad amounts accordingly. Amounts from `sim.estimateAssetRequirements()` are additionally measured under forged (very large) balances, so contracts that branch on the account's real balance can be measured on the wrong branch.
+
+**Asset coverage is native + `balanceOf(address)`.** Deltas track ETH and anything answering ERC-20-style `balanceOf` (an ERC-721 shows up as a count delta, without token IDs). ERC-1155 balances (`balanceOf(address,uint256)`) are not tracked. Tokens whose balance is computed rather than stored in one slot per holder (rebasing/share-based tokens like stETH) cannot be forged — override preparation verifies slots before writing and reports them in the `unresolved` list.
+
+**Candidate discovery follows the dry run.** Token candidates come from `eth_createAccessList` on the *unforged* calls; if that dry run reverts early, contracts that would only be touched later are not discovered, and their deltas are missed. Forging (or `estimateAssetRequirements()`, which measures after forging) avoids most of this.
+
+**RPC provider requirements.** The provider must support `eth_createAccessList` (including returning the access list for reverting calls) and `eth_call` with state overrides. Missing support surfaces as `AccessListUnsupportedError` / `StateOverrideUnsupportedError`.
+
+**Not a gas estimator.** The simulation runs under `DEFAULT_SIMULATION_GAS_LIMIT` by default and the injected code changes gas accounting; use `eth_estimateGas` on the real transaction for gas.
+
+## Development
+
+Use Node.js 20 or newer with pnpm 10. With `proto`:
+
+```sh
+proto use pnpm 10.18.3 --pin
+pnpm install
+```
+
+Or, if your Node installation has Corepack:
+
+```sh
+corepack enable
+corepack prepare pnpm@10.18.3 --activate
+pnpm install
+```
+
+If your version manager still selects pnpm 11 under Node 20, either switch pnpm to 10 or switch Node to 22.13+.
+
+Building and testing requires [Foundry](https://getfoundry.sh) (`forge` compiles `TxSimulator.sol`, `anvil` backs the test suite):
+
+```sh
+pnpm build
+pnpm test
+```
+
+Run `pnpm verify` to execute the full local gate that CI runs: lint, typecheck, build, and tests.
+
+To see every RPC call the simulator makes during tests:
+
+```sh
+pnpm test:debug
+```
+
+To run the opt-in mainnet RPC integration test:
+
+```sh
+MAINNET_RPC_URL=$MAINNET_RPC_URL pnpm test:mainnet
+```
+
+Set `MAINNET_BLOCK_NUMBER` to override the pinned default block.
+
+## Scope
+
+V1 returns raw balance deltas only. Token metadata, token lists, indexers, centralized simulation APIs, approval UX, and price enrichment are intentionally out of scope.

package/contracts/TxSimulator.sol

@@ -0,0 +1,305 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {IERC1271Like} from "./interfaces/IERC1271Like.sol";
+
+contract TxSimulator is IERC1271Like {
+    bytes4 internal constant ERC1271_MAGIC_VALUE = 0x1626ba7e;
+    bytes4 internal constant ERC1271_INVALID_VALUE = 0xffffffff;
+    bytes4 internal constant BALANCE_OF_SELECTOR = 0x70a08231;
+    bytes4 internal constant ALLOWANCE_SELECTOR = 0xdd62ed3e;
+    uint256 internal constant MAX_INT256 = 2 ** 255 - 1;
+
+    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;
+    }
+
+    struct TokenState {
+        uint256[] beforeBalances;
+        uint256[] minBalances;
+        bool[] isToken;
+        address[] observedScratch;
+        uint256 observedCount;
+    }
+
+    struct ExecutionState {
+        bool[] isToken;
+        uint256[] minBalances;
+        uint256[] checkpoints;
+        uint256 stride;
+    }
+
+    function simulate(SimulatedCall[] calldata calls, address[] calldata candidates, AllowanceProbe[] calldata probes)
+        external
+        returns (SimulationResult memory result)
+    {
+        uint256 nativeBefore = address(this).balance;
+        TokenState memory tokenState = _snapshotTokens(candidates);
+
+        result.allowanceCheckpoints = new uint256[](probes.length * (calls.length + 1));
+        ExecutionState memory executionState = ExecutionState({
+            isToken: tokenState.isToken,
+            minBalances: tokenState.minBalances,
+            checkpoints: result.allowanceCheckpoints,
+            stride: calls.length + 1
+        });
+        uint256 nativeMin;
+        (result.success, result.failingCallIndex, result.revertData, nativeMin) =
+            _executeCalls(calls, candidates, probes, executionState, nativeBefore);
+
+        result.nativeDelta = _signedDelta(address(this).balance, nativeBefore);
+        result.observedTokens = _trimAddresses(tokenState.observedScratch, tokenState.observedCount);
+        result.maxNativeOutflow = nativeBefore >= nativeMin ? nativeBefore - nativeMin : 0;
+        _writeTokenResults(candidates, tokenState, result);
+    }
+
+    function isValidSignature(bytes32 hash, bytes calldata signature) external view returns (bytes4) {
+        return _recover(hash, signature) == address(this) ? ERC1271_MAGIC_VALUE : ERC1271_INVALID_VALUE;
+    }
+
+    function onERC721Received(address, address, uint256, bytes calldata) external pure returns (bytes4) {
+        return 0x150b7a02;
+    }
+
+    function onERC1155Received(address, address, uint256, uint256, bytes calldata) external pure returns (bytes4) {
+        return 0xf23a6e61;
+    }
+
+    function onERC1155BatchReceived(address, address, uint256[] calldata, uint256[] calldata, bytes calldata)
+        external
+        pure
+        returns (bytes4)
+    {
+        return 0xbc197c81;
+    }
+
+    receive() external payable {}
+
+    function _snapshotTokens(address[] calldata candidates) internal view returns (TokenState memory tokenState) {
+        tokenState.beforeBalances = new uint256[](candidates.length);
+        tokenState.minBalances = new uint256[](candidates.length);
+        tokenState.isToken = new bool[](candidates.length);
+        tokenState.observedScratch = new address[](candidates.length);
+
+        for (uint256 i = 0; i < candidates.length; ++i) {
+            (bool ok, uint256 balance) = _tryBalanceOf(candidates[i], address(this));
+            if (ok) {
+                tokenState.isToken[i] = true;
+                tokenState.beforeBalances[i] = balance;
+                tokenState.minBalances[i] = balance;
+                tokenState.observedScratch[tokenState.observedCount++] = candidates[i];
+            }
+        }
+    }
+
+    function _writeTokenResults(
+        address[] calldata candidates,
+        TokenState memory tokenState,
+        SimulationResult memory result
+    ) internal view {
+        result.maxTokenOutflows = new uint256[](candidates.length);
+        address[] memory deltaTokensScratch = new address[](candidates.length);
+        int256[] memory tokenDeltasScratch = new int256[](candidates.length);
+        uint256 deltaCount = 0;
+
+        for (uint256 i = 0; i < candidates.length; ++i) {
+            if (!tokenState.isToken[i]) continue;
+
+            if (tokenState.beforeBalances[i] >= tokenState.minBalances[i]) {
+                result.maxTokenOutflows[i] = tokenState.beforeBalances[i] - tokenState.minBalances[i];
+            }
+
+            (bool ok, uint256 afterBalance) = _tryBalanceOf(candidates[i], address(this));
+            if (!ok) continue;
+
+            int256 delta = _signedDelta(afterBalance, tokenState.beforeBalances[i]);
+            if (delta != 0) {
+                deltaTokensScratch[deltaCount] = candidates[i];
+                tokenDeltasScratch[deltaCount] = delta;
+                ++deltaCount;
+            }
+        }
+
+        result.deltaTokens = _trimAddresses(deltaTokensScratch, deltaCount);
+        result.tokenDeltas = _trimInts(tokenDeltasScratch, deltaCount);
+    }
+
+    function _executeCalls(
+        SimulatedCall[] calldata calls,
+        address[] calldata candidates,
+        AllowanceProbe[] calldata probes,
+        ExecutionState memory executionState,
+        uint256 nativeBefore
+    ) internal returns (bool success, uint256 failingCallIndex, bytes memory revertData, uint256 nativeMin) {
+        success = true;
+        failingCallIndex = type(uint256).max;
+        nativeMin = nativeBefore;
+        if (probes.length > 0) {
+            _recordAllowanceCheckpoints(probes, executionState.stride, 0, executionState.checkpoints);
+        }
+
+        for (uint256 i = 0; i < calls.length; ++i) {
+            (bool ok, bytes memory callRevertData) = _executeCall(calls[i]);
+            if (!ok) {
+                success = false;
+                failingCallIndex = i;
+                revertData = callRevertData;
+                if (probes.length > 0) {
+                    _fillRemainingCheckpoints(probes.length, executionState.stride, i, executionState.checkpoints);
+                }
+                break;
+            }
+
+            uint256 nativeAfter = address(this).balance;
+            if (nativeAfter < nativeMin) nativeMin = nativeAfter;
+            _updateMinBalances(candidates, executionState.isToken, executionState.minBalances);
+            if (probes.length > 0) {
+                _recordAllowanceCheckpoints(probes, executionState.stride, i + 1, executionState.checkpoints);
+            }
+        }
+    }
+
+    function _executeCall(SimulatedCall calldata call_) internal returns (bool ok, bytes memory revertData) {
+        // forge-lint: disable-next-line(low-level-calls, arbitrary-send-eth, calls-loop)
+        return call_.to.call{value: call_.value}(call_.data);
+    }
+
+    function _updateMinBalances(address[] calldata candidates, bool[] memory isToken, uint256[] memory minBalances)
+        internal
+        view
+    {
+        for (uint256 i = 0; i < candidates.length; ++i) {
+            if (!isToken[i]) continue;
+
+            (bool ok, uint256 afterBalance) = _tryBalanceOf(candidates[i], address(this));
+            if (ok && afterBalance < minBalances[i]) minBalances[i] = afterBalance;
+        }
+    }
+
+    function _recordAllowanceCheckpoints(
+        AllowanceProbe[] calldata probes,
+        uint256 stride,
+        uint256 offset,
+        uint256[] memory checkpoints
+    ) internal view {
+        for (uint256 i = 0; i < probes.length; ++i) {
+            (bool ok, uint256 allowance) = _tryAllowance(probes[i].token, address(this), probes[i].spender);
+            checkpoints[i * stride + offset] = ok ? allowance : 0;
+        }
+    }
+
+    function _fillRemainingCheckpoints(
+        uint256 probeCount,
+        uint256 stride,
+        uint256 lastOffset,
+        uint256[] memory checkpoints
+    ) internal pure {
+        for (uint256 i = 0; i < probeCount; ++i) {
+            uint256 last = checkpoints[i * stride + lastOffset];
+            for (uint256 offset = lastOffset + 1; offset < stride; ++offset) {
+                checkpoints[i * stride + offset] = last;
+            }
+        }
+    }
+
+    function _tryBalanceOf(address token, address owner) internal view returns (bool ok, uint256 balance) {
+        // forge-lint: disable-next-line(low-level-calls, calls-loop)
+        (bool success, bytes memory data) = token.staticcall(abi.encodeWithSelector(BALANCE_OF_SELECTOR, owner));
+        if (!success || data.length < 32) return (ok, balance);
+        ok = success;
+        balance = abi.decode(data, (uint256));
+    }
+
+    function _tryAllowance(address token, address owner, address spender)
+        internal
+        view
+        returns (bool ok, uint256 allowance)
+    {
+        // forge-lint: disable-next-line(low-level-calls, calls-loop)
+        (bool success, bytes memory data) = token.staticcall(abi.encodeWithSelector(ALLOWANCE_SELECTOR, owner, spender));
+        if (!success || data.length < 32) return (ok, allowance);
+        ok = success;
+        allowance = abi.decode(data, (uint256));
+    }
+
+    function _signedDelta(uint256 afterBalance, uint256 beforeBalance) internal pure returns (int256) {
+        if (afterBalance >= beforeBalance) {
+            uint256 positiveDiff = afterBalance - beforeBalance;
+            if (positiveDiff > MAX_INT256) return type(int256).max;
+            // forge-lint: disable-next-line(unsafe-typecast)
+            return int256(positiveDiff);
+        }
+
+        uint256 negativeDiff = beforeBalance - afterBalance;
+        if (negativeDiff > MAX_INT256) return type(int256).min;
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return -int256(negativeDiff);
+    }
+
+    function _trimAddresses(address[] memory input, uint256 length) internal pure returns (address[] memory output) {
+        output = new address[](length);
+        for (uint256 i = 0; i < length; ++i) {
+            output[i] = input[i];
+        }
+    }
+
+    function _trimInts(int256[] memory input, uint256 length) internal pure returns (int256[] memory output) {
+        output = new int256[](length);
+        for (uint256 i = 0; i < length; ++i) {
+            output[i] = input[i];
+        }
+    }
+
+    function _recover(bytes32 hash, bytes calldata signature) internal pure returns (address signer) {
+        if (signature.length == 65) {
+            bytes32 r;
+            bytes32 s;
+            uint8 v;
+            // forge-lint: disable-next-line(inline-assembly)
+            assembly {
+                r := calldataload(signature.offset)
+                s := calldataload(add(signature.offset, 0x20))
+                v := byte(0, calldataload(add(signature.offset, 0x40)))
+            }
+            if (v < 27) v += 27;
+            if (v != 27 && v != 28) return address(0);
+            return ecrecover(hash, v, r, s);
+        }
+
+        if (signature.length == 64) {
+            bytes32 r;
+            bytes32 vs;
+            // forge-lint: disable-next-line(inline-assembly)
+            assembly {
+                r := calldataload(signature.offset)
+                vs := calldataload(add(signature.offset, 0x20))
+            }
+            bytes32 s = bytes32(uint256(vs) & 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff);
+            // forge-lint: disable-next-line(unsafe-typecast)
+            uint8 v = uint8((uint256(vs) >> 255) + 27);
+            return ecrecover(hash, v, r, s);
+        }
+
+        return address(0);
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Default gas budget for simulator `eth_call` executions.
+ *
+ * The injected simulator changes gas accounting, so this is intentionally a generous execution
+ * budget rather than a gas estimate for the real transaction.
+ */
+export declare const DEFAULT_SIMULATION_GAS_LIMIT = 16000000n;
+/**
+ * Default forged token balance or allowance written by slot overrides.
+ *
+ * This is deliberately below `uint256.max`: standard ERC-20 implementations skip allowance
+ * decrements at exactly max allowance, which would hide required approvals during measurement.
+ */
+export declare const OVERRIDE_TOKEN_AMOUNT: bigint;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,YAAc,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAa,CAAC"}

package/dist/constants.js

@@ -0,0 +1,15 @@
+/**
+ * Default gas budget for simulator `eth_call` executions.
+ *
+ * The injected simulator changes gas accounting, so this is intentionally a generous execution
+ * budget rather than a gas estimate for the real transaction.
+ */
+export const DEFAULT_SIMULATION_GAS_LIMIT = 16000000n;
+/**
+ * Default forged token balance or allowance written by slot overrides.
+ *
+ * This is deliberately below `uint256.max`: standard ERC-20 implementations skip allowance
+ * decrements at exactly max allowance, which would hide required approvals during measurement.
+ */
+export const OVERRIDE_TOKEN_AMOUNT = 10n ** 50n;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,SAAW,CAAC;AAExD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,IAAI,GAAG,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/** Base class for typed infrastructure and input errors thrown by viem-tx-sim. */
+export declare class TxSimError extends Error {
+    readonly name: string;
+}
+/**
+ * Thrown when the RPC endpoint cannot run `eth_createAccessList` for a non-transaction-revert reason.
+ *
+ * Transaction execution reverts during access-list creation are normalized to an empty access list;
+ * this error means provider capability or infrastructure failure. Try another RPC endpoint that
+ * supports EIP-2930 access lists for historical/state-overridden calls.
+ */
+export declare class AccessListUnsupportedError extends TxSimError {
+    readonly name = "AccessListUnsupportedError";
+    constructor(message?: string);
+}
+/**
+ * Thrown when the RPC endpoint cannot execute `eth_call` with state overrides or returns bad output.
+ *
+ * This is usually a provider capability issue, including unsupported state overrides or simulator
+ * output that cannot be decoded. Retrying the same request generally will not help unless the RPC
+ * failure was transient; use a provider with state-override support.
+ */
+export declare class StateOverrideUnsupportedError extends TxSimError {
+    readonly name = "StateOverrideUnsupportedError";
+    constructor(message?: string);
+}
+/**
+ * Thrown for caller-side input bugs, such as an empty call batch.
+ *
+ * This is not an RPC/provider issue and should be fixed before retrying.
+ */
+export declare class InvalidSimulationInputError extends TxSimError {
+    readonly name = "InvalidSimulationInputError";
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,EAAE,MAAM,CAAgB;CAC/C;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,UAAU;IACxD,SAAkB,IAAI,gCAAgC;gBAE1C,OAAO,SAA4E;CAGhG;AAED;;;;;;GAMG;AACH,qBAAa,6BAA8B,SAAQ,UAAU;IAC3D,SAAkB,IAAI,mCAAmC;gBAGvD,OAAO,SAAgF;CAI1F;AAED;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;IACzD,SAAkB,IAAI,iCAAiC;CACxD"}

package/dist/errors.js

@@ -0,0 +1,39 @@
+/** Base class for typed infrastructure and input errors thrown by viem-tx-sim. */
+export class TxSimError extends Error {
+    name = "TxSimError";
+}
+/**
+ * Thrown when the RPC endpoint cannot run `eth_createAccessList` for a non-transaction-revert reason.
+ *
+ * Transaction execution reverts during access-list creation are normalized to an empty access list;
+ * this error means provider capability or infrastructure failure. Try another RPC endpoint that
+ * supports EIP-2930 access lists for historical/state-overridden calls.
+ */
+export class AccessListUnsupportedError extends TxSimError {
+    name = "AccessListUnsupportedError";
+    constructor(message = "RPC endpoint does not support eth_createAccessList for this simulation.") {
+        super(message);
+    }
+}
+/**
+ * Thrown when the RPC endpoint cannot execute `eth_call` with state overrides or returns bad output.
+ *
+ * This is usually a provider capability issue, including unsupported state overrides or simulator
+ * output that cannot be decoded. Retrying the same request generally will not help unless the RPC
+ * failure was transient; use a provider with state-override support.
+ */
+export class StateOverrideUnsupportedError extends TxSimError {
+    name = "StateOverrideUnsupportedError";
+    constructor(message = "RPC endpoint does not support eth_call state overrides for this simulation.") {
+        super(message);
+    }
+}
+/**
+ * Thrown for caller-side input bugs, such as an empty call batch.
+ *
+ * This is not an RPC/provider issue and should be fixed before retrying.
+ */
+export class InvalidSimulationInputError extends TxSimError {
+    name = "InvalidSimulationInputError";
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,OAAO,UAAW,SAAQ,KAAK;IACjB,IAAI,GAAW,YAAY,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,MAAM,OAAO,0BAA2B,SAAQ,UAAU;IACtC,IAAI,GAAG,4BAA4B,CAAC;IAEtD,YAAY,OAAO,GAAG,yEAAyE;QAC7F,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,6BAA8B,SAAQ,UAAU;IACzC,IAAI,GAAG,+BAA+B,CAAC;IAEzD,YACE,OAAO,GAAG,6EAA6E;QAEvF,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,2BAA4B,SAAQ,UAAU;IACvC,IAAI,GAAG,6BAA6B,CAAC;CACxD"}