@crewhaus/tool-chaincall 0.7.0

package/dist/lib/proxy.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Telling a proxy from a contract, and a fact from a claim.
+ *
+ * Proxy detection has no single specification. Four different mechanisms are
+ * in wide use and they disagree about where the implementation address even
+ * lives, so this file reports SIGNALS and only then tries to reconcile them:
+ *
+ *   - **EIP-1967** puts it in a fixed storage slot. That is state, read with
+ *     `eth_getStorageAt`, and it is a fact about the contract.
+ *   - **EIP-1967 beacon** puts a beacon address in a different fixed slot;
+ *     the implementation is whatever that beacon's `implementation()`
+ *     returns right now, which makes it a fact plus one hop.
+ *   - **EIP-1167** carries the target inside the runtime bytecode. Also a
+ *     fact, and the only one that does not need a second read.
+ *   - **EIP-1822** uses `keccak256("PROXIABLE")` as the slot.
+ *
+ * And **EIP-2535 diamonds** have no single implementation at all: each
+ * selector routes to a different facet. There is no address to report, so
+ * none is invented — the answer is "unresolved, and here is why", because a
+ * wrong implementation address means the caller fetches the wrong ABI and
+ * every call it composes afterwards is wrong.
+ *
+ * ERC-165 is on the other side of the line. `supportsInterface` is the
+ * contract answering a question about itself, and a contract can lie or
+ * simply be wrong. It is never reported as verification.
+ */
+/** `keccak256("eip1967.proxy.implementation") - 1`. */
+export declare const EIP1967_IMPLEMENTATION_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+/** `keccak256("eip1967.proxy.admin") - 1`. */
+export declare const EIP1967_ADMIN_SLOT = "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
+/** `keccak256("eip1967.proxy.beacon") - 1`. */
+export declare const EIP1967_BEACON_SLOT = "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50";
+/** `keccak256("PROXIABLE")`, the EIP-1822 slot. */
+export declare const EIP1822_SLOT = "0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bec8";
+/**
+ * Read an EIP-1167 clone's target out of its bytecode, or null.
+ *
+ * Only the canonical form matches. The optimized "vanity" variants that
+ * shave bytes by pushing a shorter address do not, and a near-match is
+ * reported as no match rather than as a guess: these 45 bytes are the one
+ * place a proxy's target can be read with no second call, so a pattern that
+ * is almost right is a pattern whose address is almost right.
+ */
+export declare function minimalProxyTarget(code: string): string | null;
+/**
+ * Interface ids this package probes by default, with what each one means.
+ *
+ * The ids come from their EIPs. Three of them are single-function
+ * interfaces, so the id IS that function's selector and `lib.test.ts`
+ * recomputes them; the rest are XORs of several selectors and are carried as
+ * published constants.
+ */
+export declare const KNOWN_INTERFACES: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+    /** The single function this id is the selector of, when there is one. */
+    readonly singleFunction?: string;
+}>;
+/** The DiamondLoupe id, which changes what "the implementation" even means. */
+export declare const DIAMOND_LOUPE_ID = "0x48e2b093";
+/**
+ * The reserved id every ERC-165 contract must answer FALSE for.
+ *
+ * This is the whole compliance test, and skipping it is how a claim list
+ * becomes fiction: a contract whose fallback returns a non-zero word answers
+ * `true` to every `supportsInterface` call ever made. Its claims then say
+ * nothing at all, and a list of eleven interfaces it "supports" is eleven
+ * wrong facts that a caller has no way to spot.
+ */
+export declare const ERC165_INVALID_ID = "0xffffffff";
+export type ProxySignal = {
+    readonly kind: "eip1967" | "eip1967-beacon" | "eip1167-minimal" | "eip1822" | "diamond";
+    /** The implementation this signal points at, when it points at one. */
+    readonly implementation: string | null;
+    /** Where it was read from, in enough detail to go and check. */
+    readonly source: string;
+    /** Whether the value came from storage/bytecode (fact) or a view call. */
+    readonly evidence: "storage" | "bytecode" | "call";
+};
+export type ProxyVerdict = {
+    readonly isProxy: boolean;
+    readonly resolved: boolean;
+    readonly kind: string;
+    readonly implementation: string | null;
+    readonly signals: ReadonlyArray<ProxySignal>;
+    /** Present whenever `resolved` is false, saying what to do instead. */
+    readonly unresolvedReason?: string;
+};
+/**
+ * Reconcile the signals into one answer, or decline to.
+ *
+ * Two signals naming two different implementations is the case this exists
+ * for. It happens — a clone of a proxy, a half-migrated upgrade, a contract
+ * that writes the 1967 slot for tooling while actually dispatching somewhere
+ * else — and picking one is how a caller ends up with an ABI that decodes
+ * the wrong contract's storage. So: one implementation, or none and a
+ * reason.
+ */
+export declare function reconcileProxy(signals: ReadonlyArray<ProxySignal>): ProxyVerdict;

package/dist/lib/proxy.js

@@ -0,0 +1,152 @@
+/**
+ * Telling a proxy from a contract, and a fact from a claim.
+ *
+ * Proxy detection has no single specification. Four different mechanisms are
+ * in wide use and they disagree about where the implementation address even
+ * lives, so this file reports SIGNALS and only then tries to reconcile them:
+ *
+ *   - **EIP-1967** puts it in a fixed storage slot. That is state, read with
+ *     `eth_getStorageAt`, and it is a fact about the contract.
+ *   - **EIP-1967 beacon** puts a beacon address in a different fixed slot;
+ *     the implementation is whatever that beacon's `implementation()`
+ *     returns right now, which makes it a fact plus one hop.
+ *   - **EIP-1167** carries the target inside the runtime bytecode. Also a
+ *     fact, and the only one that does not need a second read.
+ *   - **EIP-1822** uses `keccak256("PROXIABLE")` as the slot.
+ *
+ * And **EIP-2535 diamonds** have no single implementation at all: each
+ * selector routes to a different facet. There is no address to report, so
+ * none is invented — the answer is "unresolved, and here is why", because a
+ * wrong implementation address means the caller fetches the wrong ABI and
+ * every call it composes afterwards is wrong.
+ *
+ * ERC-165 is on the other side of the line. `supportsInterface` is the
+ * contract answering a question about itself, and a contract can lie or
+ * simply be wrong. It is never reported as verification.
+ */
+/** `keccak256("eip1967.proxy.implementation") - 1`. */
+export const EIP1967_IMPLEMENTATION_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+/** `keccak256("eip1967.proxy.admin") - 1`. */
+export const EIP1967_ADMIN_SLOT = "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
+/** `keccak256("eip1967.proxy.beacon") - 1`. */
+export const EIP1967_BEACON_SLOT = "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50";
+/** `keccak256("PROXIABLE")`, the EIP-1822 slot. */
+export const EIP1822_SLOT = "0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bec8";
+/**
+ * The EIP-1167 minimal proxy's runtime code, with the 20-byte target between
+ * the two halves. 45 bytes exactly.
+ */
+const EIP1167_PREFIX = "363d3d373d3d3d363d73";
+const EIP1167_SUFFIX = "5af43d82803e903d91602b57fd5bf3";
+/**
+ * Read an EIP-1167 clone's target out of its bytecode, or null.
+ *
+ * Only the canonical form matches. The optimized "vanity" variants that
+ * shave bytes by pushing a shorter address do not, and a near-match is
+ * reported as no match rather than as a guess: these 45 bytes are the one
+ * place a proxy's target can be read with no second call, so a pattern that
+ * is almost right is a pattern whose address is almost right.
+ */
+export function minimalProxyTarget(code) {
+    const body = code.replace(/^0x/, "").toLowerCase();
+    if (body.length !== EIP1167_PREFIX.length + 40 + EIP1167_SUFFIX.length)
+        return null;
+    if (!body.startsWith(EIP1167_PREFIX) || !body.endsWith(EIP1167_SUFFIX))
+        return null;
+    return `0x${body.slice(EIP1167_PREFIX.length, EIP1167_PREFIX.length + 40)}`;
+}
+/**
+ * Interface ids this package probes by default, with what each one means.
+ *
+ * The ids come from their EIPs. Three of them are single-function
+ * interfaces, so the id IS that function's selector and `lib.test.ts`
+ * recomputes them; the rest are XORs of several selectors and are carried as
+ * published constants.
+ */
+export const KNOWN_INTERFACES = Object.freeze([
+    { id: "0x01ffc9a7", name: "ERC-165", singleFunction: "supportsInterface(bytes4)" },
+    { id: "0x80ac58cd", name: "ERC-721" },
+    { id: "0x5b5e139f", name: "ERC-721Metadata" },
+    { id: "0x780e9d63", name: "ERC-721Enumerable" },
+    { id: "0xd9b67a26", name: "ERC-1155" },
+    { id: "0x0e89341c", name: "ERC-1155MetadataURI", singleFunction: "uri(uint256)" },
+    {
+        id: "0x2a55205a",
+        name: "ERC-2981 (royalties)",
+        singleFunction: "royaltyInfo(uint256,uint256)",
+    },
+    { id: "0x49064906", name: "ERC-4906 (metadata update)" },
+    { id: "0x1626ba7e", name: "ERC-1271 (contract signatures)" },
+    { id: "0x7965db0b", name: "AccessControl" },
+    { id: "0x48e2b093", name: "EIP-2535 DiamondLoupe" },
+]);
+/** The DiamondLoupe id, which changes what "the implementation" even means. */
+export const DIAMOND_LOUPE_ID = "0x48e2b093";
+/**
+ * The reserved id every ERC-165 contract must answer FALSE for.
+ *
+ * This is the whole compliance test, and skipping it is how a claim list
+ * becomes fiction: a contract whose fallback returns a non-zero word answers
+ * `true` to every `supportsInterface` call ever made. Its claims then say
+ * nothing at all, and a list of eleven interfaces it "supports" is eleven
+ * wrong facts that a caller has no way to spot.
+ */
+export const ERC165_INVALID_ID = "0xffffffff";
+/**
+ * Reconcile the signals into one answer, or decline to.
+ *
+ * Two signals naming two different implementations is the case this exists
+ * for. It happens — a clone of a proxy, a half-migrated upgrade, a contract
+ * that writes the 1967 slot for tooling while actually dispatching somewhere
+ * else — and picking one is how a caller ends up with an ABI that decodes
+ * the wrong contract's storage. So: one implementation, or none and a
+ * reason.
+ */
+export function reconcileProxy(signals) {
+    if (signals.length === 0) {
+        return { isProxy: false, resolved: true, kind: "none", implementation: null, signals };
+    }
+    const diamond = signals.find((s) => s.kind === "diamond");
+    if (diamond !== undefined) {
+        return {
+            isProxy: true,
+            resolved: false,
+            kind: "diamond",
+            implementation: null,
+            signals,
+            unresolvedReason: "this contract CLAIMS the EIP-2535 DiamondLoupe interface (self-reported, via ERC-165), and a diamond routes every selector to a different facet — there is no single implementation to report. Enumerate the facets with facets() and inspect each one. A claim can only make this answer more cautious, never more confident, which is why it is allowed to withdraw an address but never to supply one.",
+        };
+    }
+    const addressed = signals.filter((s) => s.implementation !== null);
+    const distinct = [...new Set(addressed.map((s) => s.implementation.toLowerCase()))];
+    if (distinct.length === 0) {
+        const kinds = signals.map((s) => s.kind).join(", ");
+        return {
+            isProxy: true,
+            resolved: false,
+            kind: signals[0]?.kind ?? "unknown",
+            implementation: null,
+            signals,
+            unresolvedReason: `this contract looks like a proxy (${kinds}) but no implementation address could be read from it`,
+        };
+    }
+    if (distinct.length > 1) {
+        const detail = addressed.map((s) => `${s.implementation} (${s.source})`).join(" and ");
+        return {
+            isProxy: true,
+            resolved: false,
+            kind: "conflicting",
+            implementation: null,
+            signals,
+            unresolvedReason: `two proxy mechanisms on this contract name different implementations — ${detail}. Reporting either one would send you to the wrong ABI, so neither is reported.`,
+        };
+    }
+    const primary = addressed[0];
+    return {
+        isProxy: true,
+        resolved: true,
+        kind: primary.kind,
+        implementation: primary.implementation,
+        signals,
+    };
+}

package/dist/lib/rpc.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The one place this package talks to a chain, and the gate it talks through.
+ *
+ * Every JSON-RPC method dispatched from anywhere in this package passes
+ * `assertReadOnlyMethod` from `@crewhaus/chain-adapter-base` FIRST. That
+ * allowlist is the repo's existing statement of what a read is, and putting
+ * it at this chokepoint means a bug three files away cannot dispatch
+ * `eth_sendRawTransaction` — it would have to get past a check it never
+ * sees. Nothing here signs, and there is nowhere to put a key.
+ *
+ * The seam is `ChainRpc`: one function, `(method, params) -> result`. It sits
+ * ABOVE the dialler on purpose, the same way `tool-registry`'s does, so a
+ * test that installs a stub never resolves a name, never opens a socket and
+ * never needs egress. The production binding is a resolver the runtime sets
+ * at boot from the spec's `chains[]` block, exactly as `@crewhaus/tool-evm`
+ * does — this package holds no endpoint list of its own and there is no
+ * caller-supplied URL anywhere in it.
+ */
+import type { ChainAdapter } from "@crewhaus/chain-adapter-base";
+import { CrewhausError } from "@crewhaus/errors";
+/** A refusal raised by this package: a bad input, a broken promise, a limit. */
+export declare class ChainCallError extends CrewhausError {
+    readonly name = "ChainCallError";
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * A JSON-RPC read. `params` is the wire array; the return is the wire
+ * `result`, undecoded, because every caller here wants different bytes out
+ * of it.
+ */
+export type ChainRpc = (method: string, params: ReadonlyArray<unknown>, opts?: {
+    readonly signal?: AbortSignal;
+}) => Promise<unknown>;
+/** Boot-time binding: chain id in, transport out. */
+export type ChainRpcResolver = (chainId: string) => ChainRpc | undefined;
+/**
+ * Bind the per-chain transports at boot. A generated daemon calls this once,
+ * wiring each declared chain to its adapter; `undefined` unbinds.
+ */
+export declare function setChainRpcResolver(fn: ChainRpcResolver | undefined): void;
+/**
+ * Adapt a `ChainAdapter` into the seam, so the runtime can hand these tools
+ * the same adapters `tool-evm` already gets. `rpcRead` keeps its own
+ * allowlist and boundary classification; this does not replace either.
+ */
+export declare function chainRpcFromAdapter(adapter: ChainAdapter): ChainRpc;
+/**
+ * Test-only injection point, the convention every networked package here
+ * follows: one transport for every chain id. `undefined` unbinds, and a
+ * suite that sets it must restore it, or the next file in the same bun
+ * process inherits a stub.
+ */
+export declare function _setRpc(fn: ChainRpc | undefined): void;
+/** Find the transport for a chain, or say what the operator has to wire. */
+export declare function resolveRpc(chainId: string, toolName: string): ChainRpc;
+/**
+ * Dispatch one read.
+ *
+ * The allowlist check is here rather than at each call site because a check
+ * you have to remember is a check that gets forgotten. `assertReadOnlyMethod`
+ * throws a `ChainAdapterError`, which is deliberately NOT rewrapped: a
+ * write-class method reaching this line is a defect in this package and
+ * should arrive at the log looking like one.
+ *
+ * The signal is both passed down AND raced against. `ChainAdapter.rpcRead`
+ * takes no signal, so a transport built on one cannot be cancelled — and a
+ * `timeoutMs` that bounds nothing is a promise this package should not be
+ * making. Racing means the TOOL returns on time; the request underneath it
+ * may still be in flight, which is the honest limit of a seam whose other
+ * side does not accept a signal.
+ */
+export declare function rpcRead(rpc: ChainRpc, chainId: string, method: string, params: ReadonlyArray<unknown>, signal?: AbortSignal): Promise<unknown>;
+/** The JSON-RPC error object, as much of it as a thrown value tends to carry. */
+export type RpcErrorShape = {
+    readonly code?: number;
+    readonly message?: string;
+    readonly data?: unknown;
+};
+/**
+ * Pull the JSON-RPC error out of whatever the transport threw. Providers
+ * differ: some throw the error object, some an `Error` with `.code` and
+ * `.data` attached, some an `Error` wrapping one under `.cause` or `.error`.
+ */
+export declare function rpcError(err: unknown): RpcErrorShape;
+/** True when the failure is the caller's or the runtime's cancellation. */
+export declare function isAbort(err: unknown, signal?: AbortSignal): boolean;
+/**
+ * -32601 and the strings providers use instead of it.
+ *
+ * This is the one predicate `EvmSimulateBundle` degrades on, so it has to be
+ * narrow in both directions. A node that has never heard of `eth_simulateV1`
+ * is a reason to answer a lesser question; a node that timed out, or that
+ * rejected the parameters, or whose simulation reverted, is NOT — degrading
+ * on those would turn a transient fault into a quietly weaker answer that
+ * still looks like an answer.
+ */
+export declare function isMethodUnsupported(err: unknown, signal?: AbortSignal): boolean;
+/** A one-line description of a node failure, for a refusal message. */
+export declare function rpcErrorText(err: unknown): string;
+export type Deadline = {
+    readonly signal: AbortSignal;
+    /** Clear the timer. Always call it, or the process keeps a handle alive. */
+    cancel(): void;
+};
+/**
+ * A deadline that also honours the runtime's own cancellation. Every tool
+ * here opens one before its first byte and cancels it in a `finally`: a tool
+ * that fans out over several round trips can hang in several places.
+ */
+export declare function startDeadline(ms: number, outer?: AbortSignal): Deadline;

package/dist/lib/rpc.js

@@ -0,0 +1,190 @@
+import { assertReadOnlyMethod } from "@crewhaus/chain-adapter-base";
+import { CrewhausError } from "@crewhaus/errors";
+/** A refusal raised by this package: a bad input, a broken promise, a limit. */
+export class ChainCallError extends CrewhausError {
+    name = "ChainCallError";
+    constructor(message, cause) {
+        super("tool", message, cause);
+    }
+}
+let resolver;
+/**
+ * Bind the per-chain transports at boot. A generated daemon calls this once,
+ * wiring each declared chain to its adapter; `undefined` unbinds.
+ */
+export function setChainRpcResolver(fn) {
+    resolver = fn;
+}
+/**
+ * Adapt a `ChainAdapter` into the seam, so the runtime can hand these tools
+ * the same adapters `tool-evm` already gets. `rpcRead` keeps its own
+ * allowlist and boundary classification; this does not replace either.
+ */
+export function chainRpcFromAdapter(adapter) {
+    return (method, params) => adapter.rpcRead(method, params);
+}
+/**
+ * Test-only injection point, the convention every networked package here
+ * follows: one transport for every chain id. `undefined` unbinds, and a
+ * suite that sets it must restore it, or the next file in the same bun
+ * process inherits a stub.
+ */
+export function _setRpc(fn) {
+    resolver = fn === undefined ? undefined : () => fn;
+}
+/** Find the transport for a chain, or say what the operator has to wire. */
+export function resolveRpc(chainId, toolName) {
+    if (resolver === undefined) {
+        throw new ChainCallError(`${toolName}: no chain transport is bound — the runtime must call setChainRpcResolver() at boot with the chains from spec.chains[]`);
+    }
+    const rpc = resolver(chainId);
+    if (rpc === undefined) {
+        throw new ChainCallError(`${toolName}: no chain is configured for chainId "${chainId}" — declare it in spec.chains[]`);
+    }
+    return rpc;
+}
+/** The rejection a cancelled read produces. `isAbort` recognises it. */
+function abortError(signal) {
+    const reason = signal.reason;
+    const message = reason instanceof Error ? reason.message : "the read was cancelled";
+    return Object.assign(new Error(message), { name: "AbortError" });
+}
+/**
+ * Dispatch one read.
+ *
+ * The allowlist check is here rather than at each call site because a check
+ * you have to remember is a check that gets forgotten. `assertReadOnlyMethod`
+ * throws a `ChainAdapterError`, which is deliberately NOT rewrapped: a
+ * write-class method reaching this line is a defect in this package and
+ * should arrive at the log looking like one.
+ *
+ * The signal is both passed down AND raced against. `ChainAdapter.rpcRead`
+ * takes no signal, so a transport built on one cannot be cancelled — and a
+ * `timeoutMs` that bounds nothing is a promise this package should not be
+ * making. Racing means the TOOL returns on time; the request underneath it
+ * may still be in flight, which is the honest limit of a seam whose other
+ * side does not accept a signal.
+ */
+export async function rpcRead(rpc, chainId, method, params, signal) {
+    assertReadOnlyMethod(chainId, method);
+    // Checked before dispatch, not after: a cancelled run should not be the
+    // reason a node sees one more request.
+    if (signal?.aborted === true)
+        throw abortError(signal);
+    const call = rpc(method, params, signal === undefined ? {} : { signal });
+    if (signal === undefined)
+        return call;
+    let onAbort;
+    try {
+        return await Promise.race([
+            call,
+            new Promise((_, reject) => {
+                onAbort = () => reject(abortError(signal));
+                signal.addEventListener("abort", onAbort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : undefined;
+}
+/**
+ * Pull the JSON-RPC error out of whatever the transport threw. Providers
+ * differ: some throw the error object, some an `Error` with `.code` and
+ * `.data` attached, some an `Error` wrapping one under `.cause` or `.error`.
+ */
+export function rpcError(err) {
+    const seen = new Set();
+    let node = err;
+    for (let depth = 0; depth < 4 && node !== undefined && node !== null; depth++) {
+        if (seen.has(node))
+            break;
+        seen.add(node);
+        const record = asRecord(node);
+        if (record === undefined)
+            break;
+        const code = record["code"];
+        const message = record["message"];
+        if (typeof code === "number") {
+            return {
+                code,
+                ...(typeof message === "string" ? { message } : {}),
+                ...(record["data"] !== undefined ? { data: record["data"] } : {}),
+            };
+        }
+        node = record["error"] ?? record["cause"];
+    }
+    const record = asRecord(err);
+    const message = record?.["message"];
+    return typeof message === "string" ? { message } : { message: String(err) };
+}
+/** True when the failure is the caller's or the runtime's cancellation. */
+export function isAbort(err, signal) {
+    if (signal?.aborted === true)
+        return true;
+    const record = asRecord(err);
+    return record?.["name"] === "AbortError" || record?.["name"] === "TimeoutError";
+}
+/**
+ * -32601 and the strings providers use instead of it.
+ *
+ * This is the one predicate `EvmSimulateBundle` degrades on, so it has to be
+ * narrow in both directions. A node that has never heard of `eth_simulateV1`
+ * is a reason to answer a lesser question; a node that timed out, or that
+ * rejected the parameters, or whose simulation reverted, is NOT — degrading
+ * on those would turn a transient fault into a quietly weaker answer that
+ * still looks like an answer.
+ */
+export function isMethodUnsupported(err, signal) {
+    if (isAbort(err, signal))
+        return false;
+    const { code, message } = rpcError(err);
+    // -32601 is "method not found". -32004 is the "method not supported" code
+    // several providers return instead; Geth and Erigon both use -32601.
+    if (code === -32601 || code === -32004)
+        return true;
+    if (code !== undefined && code !== -32000 && code !== -32601 && code !== -32004)
+        return false;
+    const text = (message ?? "").toLowerCase();
+    if (text.includes("revert") || text.includes("insufficient funds"))
+        return false;
+    return (/\bmethod\b[^.]{0,40}\bnot (?:found|supported|available|implemented|enabled)\b/.test(text) ||
+        /\bunsupported method\b/.test(text) ||
+        /\bunknown method\b/.test(text) ||
+        /\bdoes not exist\/is not available\b/.test(text));
+}
+/** A one-line description of a node failure, for a refusal message. */
+export function rpcErrorText(err) {
+    const { code, message } = rpcError(err);
+    const text = message ?? String(err);
+    return code === undefined ? text : `${text} (code ${code})`;
+}
+/**
+ * A deadline that also honours the runtime's own cancellation. Every tool
+ * here opens one before its first byte and cancels it in a `finally`: a tool
+ * that fans out over several round trips can hang in several places.
+ */
+export function startDeadline(ms, outer) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(new Error(`deadline of ${ms}ms elapsed`)), ms);
+    const onOuter = () => ctrl.abort(outer?.reason);
+    if (outer !== undefined) {
+        if (outer.aborted)
+            ctrl.abort(outer.reason);
+        else
+            outer.addEventListener("abort", onOuter, { once: true });
+    }
+    return {
+        signal: ctrl.signal,
+        cancel: () => {
+            clearTimeout(timer);
+            outer?.removeEventListener("abort", onOuter);
+        },
+    };
+}

package/dist/lib/simulate.d.ts

@@ -0,0 +1,68 @@
+import type { RevertReason } from "@crewhaus/tool-onchain";
+/** One call in a bundle. No signature, no nonce, no key: nothing is sent. */
+export type SimCall = {
+    readonly from?: string;
+    readonly to: string;
+    readonly data?: string;
+    /** Native value in wei, as a decimal string. */
+    readonly value?: string;
+    /** Gas cap for this call, as a decimal string. */
+    readonly gas?: string;
+};
+export type SimLog = {
+    readonly address: string;
+    readonly topics: ReadonlyArray<string>;
+    readonly data: string;
+};
+export type SimCallResult = {
+    readonly index: number;
+    readonly status: "success" | "reverted";
+    /** Absent when the node returned no gas figure. Never defaulted to "0". */
+    readonly gasUsed?: string;
+    readonly returnData: string;
+    readonly revert?: RevertReason;
+    /**
+     * Present only when the node returned a log list for this call, and only in
+     * `eth_simulateV1` mode. An empty array means "this call emitted nothing";
+     * the key being ABSENT means the node did not report logs at all, which is
+     * a different fact and must not be collapsed into the first one.
+     */
+    readonly logs?: ReadonlyArray<SimLog>;
+    /** The node's own message for a call that failed before execution. */
+    readonly error?: string;
+};
+/** The wire object for one call, with absent fields omitted rather than nulled. */
+export declare function toWireCall(call: SimCall, index: number): Record<string, unknown>;
+export type SimulatedBlock = {
+    readonly blockNumber: string;
+    readonly calls: ReadonlyArray<SimCallResult>;
+};
+/**
+ * Read the one block `eth_simulateV1` returns for a one-block bundle.
+ *
+ * The call count is checked before anything is read out of it, for the same
+ * reason a Multicall3 blob's count is: results are positional, and a node
+ * that returned fewer than were sent would otherwise have every later result
+ * attributed to the wrong call.
+ */
+export declare function parseSimulateV1(raw: unknown, expectedCalls: number): SimulatedBlock;
+/**
+ * Read an `eth_call` refusal as a revert when it carries revert bytes.
+ *
+ * Geth-family nodes answer a reverted `eth_call` with error code 3 and the
+ * revert data in `error.data`. Everything else — a bad parameter, a node
+ * that cannot serve the block — has no such bytes, and is not a revert.
+ */
+export declare function revertFromCallError(err: unknown): RevertReason | undefined;
+/**
+ * The chaining limitation, worded for what the fallback actually did.
+ *
+ * "Every call was evaluated against the same unmodified block" is only true
+ * when the calls carried a block NUMBER. Sending a tag once per call lets the
+ * head move between them, which is the same silent inconsistency `EvmMulticall`
+ * refuses to produce — so when the height could not be pinned the sentence
+ * says that instead of asserting a block they may not share.
+ */
+export declare function unchainedLimitation(pinnedBlock: string | null): string;
+/** What a fallback result is missing, said in full rather than implied. */
+export declare const FALLBACK_LIMITATIONS: ReadonlyArray<string>;