@crewhaus/tool-chainread 0.7.0

package/dist/lib/blocks.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Block headers, and the search over their timestamps.
+ *
+ * The search is the reason this file is not three lines long. "Which block was
+ * the chain at on 1 March?" is asked by every reconciliation, every
+ * backtest and every "what did the contract hold at the end of the quarter",
+ * and the answer is used as a `blockTag` in later reads — so a wrong answer is
+ * not a wrong number on a screen, it is a whole report computed against the
+ * wrong state.
+ *
+ * The invariant is written down in one place, here, and the result carries the
+ * evidence for it:
+ *
+ *     the returned block is the LAST block whose timestamp is <= the target,
+ *     and the block after it has a timestamp > the target.
+ *
+ * Both halves are checked before the answer is returned. Half an invariant —
+ * "a block at or before the timestamp" — is satisfied by the genesis block,
+ * which is why it is not the contract.
+ */
+import { type BlockTag } from "./quantity";
+import { type RpcClient } from "./rpc";
+export type BlockSelector = {
+    readonly kind: "number";
+    readonly value: bigint;
+} | {
+    readonly kind: "tag";
+    readonly tag: BlockTag;
+} | {
+    readonly kind: "hash";
+    readonly hash: string;
+};
+/**
+ * A block header, projected.
+ *
+ * Every quantity is a decimal STRING. `gasUsed` fits in a double today and
+ * `baseFeePerGas` does not always — and having two conventions in one object is
+ * how the wrong one gets copied into the next file.
+ */
+export type BlockSummary = {
+    /** `null` only for the pending block, which has not been assigned one yet. */
+    readonly number: string | null;
+    readonly hash: string | null;
+    readonly parentHash: string | null;
+    readonly timestamp: string;
+    readonly timestampIso: string | null;
+    readonly gasLimit: string | null;
+    readonly gasUsed: string | null;
+    /**
+     * `null` on a pre-1559 block and on chains that never adopted it. Reported
+     * next to `feeMarket` so a caller reads "this chain has no base fee" rather
+     * than putting a null into a fee calculation.
+     */
+    readonly baseFeePerGas: string | null;
+    readonly feeMarket: "eip1559" | "legacy";
+    readonly miner: string | null;
+    readonly transactionCount: number | null;
+    readonly transactions?: ReadonlyArray<string>;
+    readonly pending: boolean;
+};
+export declare function selectorToRpc(selector: BlockSelector): {
+    readonly method: string;
+    readonly params: ReadonlyArray<unknown>;
+};
+export declare function describeSelector(selector: BlockSelector): string;
+/**
+ * Fetch one header, or `null` when the chain has no such block.
+ *
+ * A node answers an unknown block with `result: null` and no error, which is
+ * the one JSON-RPC shape that most resembles success. Collapsing it into an
+ * exception would lose the distinction a caller needs: "block 99999999 does not
+ * exist yet" is an answer about the chain, while "the endpoint refused" is not.
+ */
+export declare function fetchBlock(client: RpcClient, selector: BlockSelector): Promise<BlockSummary | null>;
+export declare function projectBlock(raw: Record<string, unknown>): BlockSummary;
+/** The head block number, read once so a scan or a search works against a fixed chain tip. */
+export declare function headNumber(client: RpcClient): Promise<bigint>;
+export type TimestampSearch = {
+    readonly outcome: "found";
+    /** The last block at or before the target. */
+    readonly at: BlockSummary;
+    /** The first block strictly after it, or `null` when the target is at or past the head. */
+    readonly next: BlockSummary | null;
+    readonly atHead: boolean;
+    readonly probes: number;
+} | {
+    /** Every block in the bracket is later than the target — there is nothing at or before it. */
+    readonly outcome: "beforeRange";
+    readonly first: BlockSummary;
+    readonly probes: number;
+};
+/**
+ * Binary search for the last block at or before `target`.
+ *
+ * Deliberately NOT interpolated. Estimating a block from an average block time
+ * converges in fewer probes on a chain with a steady block time and badly on
+ * one that changed (Ethereum before and after the Merge is two different
+ * chains by this measure), and the failure mode of a bad estimate is extra
+ * probes at best and a wrong bracket at worst. Bisection over twenty million
+ * blocks is twenty-five probes, every one of which narrows a bracket that is
+ * provably still correct. When a caller already knows roughly where to look,
+ * `fromBlock`/`toBlock` cut the bracket and the probe count with it.
+ *
+ * Non-decreasing timestamps are the assumption the whole search rests on, and
+ * the assumption is CHECKED rather than trusted: every sample is compared with
+ * every other, and a pair that goes backwards is a refusal naming both blocks.
+ * A chain where that happens is a chain where "the block at 09:00" has more
+ * than one answer, and picking one silently is the lie.
+ */
+export declare function searchBlockAtTimestamp(client: RpcClient, target: bigint, bracket: {
+    readonly low: bigint;
+    readonly high: bigint;
+}, maxProbes?: number): Promise<TimestampSearch>;

package/dist/lib/blocks.js

@@ -0,0 +1,192 @@
+/**
+ * Block headers, and the search over their timestamps.
+ *
+ * The search is the reason this file is not three lines long. "Which block was
+ * the chain at on 1 March?" is asked by every reconciliation, every
+ * backtest and every "what did the contract hold at the end of the quarter",
+ * and the answer is used as a `blockTag` in later reads — so a wrong answer is
+ * not a wrong number on a screen, it is a whole report computed against the
+ * wrong state.
+ *
+ * The invariant is written down in one place, here, and the result carries the
+ * evidence for it:
+ *
+ *     the returned block is the LAST block whose timestamp is <= the target,
+ *     and the block after it has a timestamp > the target.
+ *
+ * Both halves are checked before the answer is returned. Half an invariant —
+ * "a block at or before the timestamp" — is satisfied by the genesis block,
+ * which is why it is not the contract.
+ */
+import { ChainReadError, field, hexToBigint, lowerHex, optionalHexToBigint, requireObject, toHexQuantity, unixToIso, } from "./quantity";
+import { callOrThrow } from "./rpc";
+export function selectorToRpc(selector) {
+    if (selector.kind === "hash") {
+        return { method: "eth_getBlockByHash", params: [selector.hash, false] };
+    }
+    const tag = selector.kind === "tag" ? selector.tag : toHexQuantity(selector.value);
+    return { method: "eth_getBlockByNumber", params: [tag, false] };
+}
+export function describeSelector(selector) {
+    if (selector.kind === "hash")
+        return `block ${selector.hash}`;
+    if (selector.kind === "tag")
+        return `block "${selector.tag}"`;
+    return `block ${selector.value}`;
+}
+/**
+ * Fetch one header, or `null` when the chain has no such block.
+ *
+ * A node answers an unknown block with `result: null` and no error, which is
+ * the one JSON-RPC shape that most resembles success. Collapsing it into an
+ * exception would lose the distinction a caller needs: "block 99999999 does not
+ * exist yet" is an answer about the chain, while "the endpoint refused" is not.
+ */
+export async function fetchBlock(client, selector) {
+    const { method, params } = selectorToRpc(selector);
+    // Always the hash list, never the hydrated bodies. Nothing in this package
+    // reads a transaction out of a block — `EvmTransactionSummary` fetches the
+    // one it was asked about — and hydrating pulls a megabyte of transaction
+    // objects to throw all but their hashes away.
+    const raw = await callOrThrow(client, method, params, `reading ${describeSelector(selector)}`);
+    if (raw === null || raw === undefined)
+        return null;
+    return projectBlock(requireObject(raw, `the answer for ${describeSelector(selector)}`));
+}
+export function projectBlock(raw) {
+    const numberField = raw["number"];
+    const pending = numberField === null || numberField === undefined;
+    const base = optionalHexToBigint(raw["baseFeePerGas"], "baseFeePerGas");
+    const timestamp = hexToBigint(raw["timestamp"], "block timestamp");
+    const txs = raw["transactions"];
+    // A node asked for the hash list answers with strings, and one that hydrates
+    // anyway answers with objects. Reading only the first shape is how
+    // `includeTransactions` became a field that silently returned nothing: the
+    // hashes were there, in a form this did not recognise.
+    const hashes = Array.isArray(txs) ? hashesOf(txs) : undefined;
+    return {
+        number: pending ? null : hexToBigint(numberField, "block number").toString(),
+        hash: typeof raw["hash"] === "string" ? lowerHex(raw["hash"], "block hash") : null,
+        parentHash: typeof raw["parentHash"] === "string" ? lowerHex(raw["parentHash"], "parentHash") : null,
+        timestamp: timestamp.toString(),
+        timestampIso: unixToIso(timestamp),
+        gasLimit: optionalHexToBigint(raw["gasLimit"], "gasLimit")?.toString() ?? null,
+        gasUsed: optionalHexToBigint(raw["gasUsed"], "gasUsed")?.toString() ?? null,
+        baseFeePerGas: base === null ? null : base.toString(),
+        feeMarket: base === null ? "legacy" : "eip1559",
+        miner: typeof raw["miner"] === "string" ? lowerHex(raw["miner"], "miner") : null,
+        transactionCount: Array.isArray(txs) ? txs.length : null,
+        ...(hashes !== undefined ? { transactions: hashes } : {}),
+        pending,
+    };
+}
+/** The hashes out of a `transactions` array, in either of the two shapes a node sends. */
+function hashesOf(txs) {
+    const out = [];
+    for (const entry of txs) {
+        if (typeof entry === "string") {
+            out.push(entry.toLowerCase());
+            continue;
+        }
+        const hash = typeof entry === "object" && entry !== null ? field(entry, "hash") : undefined;
+        if (typeof hash !== "string")
+            return undefined;
+        out.push(hash.toLowerCase());
+    }
+    return out;
+}
+/** The head block number, read once so a scan or a search works against a fixed chain tip. */
+export async function headNumber(client) {
+    const raw = await callOrThrow(client, "eth_blockNumber", [], "reading the head block number");
+    return hexToBigint(raw, "eth_blockNumber");
+}
+/**
+ * Binary search for the last block at or before `target`.
+ *
+ * Deliberately NOT interpolated. Estimating a block from an average block time
+ * converges in fewer probes on a chain with a steady block time and badly on
+ * one that changed (Ethereum before and after the Merge is two different
+ * chains by this measure), and the failure mode of a bad estimate is extra
+ * probes at best and a wrong bracket at worst. Bisection over twenty million
+ * blocks is twenty-five probes, every one of which narrows a bracket that is
+ * provably still correct. When a caller already knows roughly where to look,
+ * `fromBlock`/`toBlock` cut the bracket and the probe count with it.
+ *
+ * Non-decreasing timestamps are the assumption the whole search rests on, and
+ * the assumption is CHECKED rather than trusted: every sample is compared with
+ * every other, and a pair that goes backwards is a refusal naming both blocks.
+ * A chain where that happens is a chain where "the block at 09:00" has more
+ * than one answer, and picking one silently is the lie.
+ */
+export async function searchBlockAtTimestamp(client, target, bracket, maxProbes = 64) {
+    const samples = [];
+    let probes = 0;
+    const probe = async (number) => {
+        probes += 1;
+        if (probes > maxProbes) {
+            throw new ChainReadError(`the timestamp search used more than ${maxProbes} probes over blocks ${bracket.low}–${bracket.high} — the bracket is implausibly wide or the endpoint is answering inconsistently`);
+        }
+        const block = await fetchBlock(client, { kind: "number", value: number });
+        if (block === null) {
+            throw new ChainReadError(`block ${number} is inside the search bracket ${bracket.low}–${bracket.high} but the endpoint says it does not exist — the bracket is wrong, or this endpoint is not serving the whole chain`);
+        }
+        record(samples, { number, timestamp: BigInt(block.timestamp) });
+        return block;
+    };
+    let low = bracket.low;
+    let high = bracket.high;
+    if (low > high) {
+        throw new ChainReadError(`search bracket is inverted: ${low} > ${high}`);
+    }
+    const lowBlock = await probe(low);
+    if (BigInt(lowBlock.timestamp) > target) {
+        // Nothing at or before the target exists in this bracket. For the default
+        // bracket that means the timestamp predates genesis; returning block 0
+        // anyway — "the earliest block we have" — is the answer a caller would
+        // silently use to query state that did not exist.
+        return { outcome: "beforeRange", first: lowBlock, probes };
+    }
+    if (high === low) {
+        return { outcome: "found", at: lowBlock, next: null, atHead: true, probes };
+    }
+    const highBlock = await probe(high);
+    if (BigInt(highBlock.timestamp) <= target) {
+        // The target is at or past the tip of the bracket. The head is the honest
+        // answer and `next: null` says why there is nothing after it: this answer
+        // will change as the chain advances.
+        return { outcome: "found", at: highBlock, next: null, atHead: true, probes };
+    }
+    // Invariant from here: timestamp(low) <= target < timestamp(high).
+    let lowSummary = lowBlock;
+    let highSummary = highBlock;
+    while (high - low > 1n) {
+        const mid = low + (high - low) / 2n;
+        const midBlock = await probe(mid);
+        if (BigInt(midBlock.timestamp) <= target) {
+            low = mid;
+            lowSummary = midBlock;
+        }
+        else {
+            high = mid;
+            highSummary = midBlock;
+        }
+    }
+    return { outcome: "found", at: lowSummary, next: highSummary, atHead: false, probes };
+}
+/**
+ * Keep the samples, and refuse the moment two of them disagree about time's
+ * direction. Cheap: the search takes at most a few dozen samples, so the
+ * pairwise comparison is free next to one RPC round trip.
+ */
+function record(samples, next) {
+    for (const seen of samples) {
+        const earlier = seen.number < next.number ? seen : next;
+        const later = seen.number < next.number ? next : seen;
+        if (earlier.number === later.number)
+            continue;
+        if (earlier.timestamp > later.timestamp) {
+            throw new ChainReadError(`this chain's block timestamps go backwards — block ${earlier.number} is stamped ${earlier.timestamp} but the later block ${later.number} is stamped ${later.timestamp}. A binary search over timestamps has no single right answer here, so this refuses rather than returning one of several.`);
+        }
+    }
+    samples.push(next);
+}

package/dist/lib/clock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Time, injected.
+ *
+ * Two tools here need a clock: `EvmWaitForReceipt` sleeps between polls and
+ * stops at a deadline, and `EvmRpcHealth` reports how old the head block is.
+ * Both would otherwise be untestable without a real wait — and a test that
+ * waits is a test that is slow on a good day and flaky on a loaded CI box.
+ *
+ * With the seam, the deadline test costs nothing and asserts the thing that
+ * matters (how many polls happened and why it stopped) rather than how long it
+ * took. No test in this package asserts wall-clock time.
+ */
+export type Clock = {
+    /** Milliseconds since the epoch. */
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+};
+/** Test seam — `_setClock(undefined)` restores the real one. */
+export declare function _setClock(next: Clock | undefined): void;
+export declare function nowMs(): number;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * A clock a test drives: `now` only moves when something sleeps.
+ *
+ * Exported from the package's fixtures rather than kept in one test file
+ * because three suites need it. Sleeping advances the virtual clock and
+ * returns immediately, so a fifteen-minute deadline costs microseconds and the
+ * poll count is exactly what the code decided rather than what the machine had
+ * time for.
+ */
+export declare function virtualClock(startMs?: number): Clock & {
+    readonly sleeps: number[];
+    advance(ms: number): void;
+};

package/dist/lib/clock.js

@@ -0,0 +1,55 @@
+const realClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(new Error("aborted"));
+            return;
+        }
+        const handle = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(handle);
+            reject(new Error("aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    }),
+};
+let clock = realClock;
+/** Test seam — `_setClock(undefined)` restores the real one. */
+export function _setClock(next) {
+    clock = next ?? realClock;
+}
+export function nowMs() {
+    return clock.now();
+}
+export function sleep(ms, signal) {
+    return clock.sleep(ms, signal);
+}
+/**
+ * A clock a test drives: `now` only moves when something sleeps.
+ *
+ * Exported from the package's fixtures rather than kept in one test file
+ * because three suites need it. Sleeping advances the virtual clock and
+ * returns immediately, so a fifteen-minute deadline costs microseconds and the
+ * poll count is exactly what the code decided rather than what the machine had
+ * time for.
+ */
+export function virtualClock(startMs = 1_700_000_000_000) {
+    let current = startMs;
+    const sleeps = [];
+    return {
+        sleeps,
+        now: () => current,
+        advance(ms) {
+            current += ms;
+        },
+        async sleep(ms, signal) {
+            if (signal?.aborted === true)
+                throw new Error("aborted");
+            sleeps.push(ms);
+            current += ms;
+        },
+    };
+}

package/dist/lib/endpoint.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Which endpoints this package is willing to dial.
+ *
+ * Every other networked package here — `tool-registry`, `tool-containers` —
+ * builds its URLs from constants, so a model never picks a host. This one
+ * cannot: reading a chain the caller names means the caller names the RPC URL,
+ * and an unguarded `fetch(input.rpcUrl)` is a server-side request forgery
+ * primitive with a model holding the steering wheel. `http://169.254.169.254/`
+ * is the cloud metadata service; `http://127.0.0.1:6379/` is somebody's Redis.
+ *
+ * So the host is vetted before the socket opens, the vetted IP is what gets
+ * dialled (resolving here and letting `fetch` re-resolve at connect time is a
+ * DNS-rebinding TOCTOU), and the loopback/private ranges are refused unless an
+ * OPERATOR opened them — `setRpcEndpointPolicy` is bound at boot by the
+ * runtime, exactly like `setEvmAdapterResolver` in `tool-evm`. It is
+ * deliberately not a field in any tool's input schema: a gate a model can open
+ * for itself is not a gate.
+ *
+ * This is a narrower guard than `@crewhaus/tool-fetch`'s `assertNotSsrf`, which
+ * is the repo's canonical one and is not a dependency of this package. What is
+ * here covers the same ground for this package's one shape of request — a
+ * single origin, no redirects followed, no credentials attached — and the
+ * README says so rather than implying parity.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export declare class RpcEndpointError extends CrewhausError {
+    readonly name = "RpcEndpointError";
+    constructor(message: string);
+}
+/** What the runtime may loosen at boot. Nothing here is reachable from a tool's input. */
+export type RpcEndpointPolicy = {
+    /**
+     * Permit loopback and private-range endpoints. A local anvil or hardhat node
+     * at `http://127.0.0.1:8545` is the reason this exists, and it is the whole
+     * reason it is off by default: that address is also every unauthenticated
+     * service on the box the agent happens to be running on.
+     */
+    readonly allowPrivateHosts?: boolean;
+    /**
+     * When set, the ONLY origins that may be dialled, e.g.
+     * `["https://mainnet.base.org"]`. An operator that knows its endpoints should
+     * set this; it turns the guard from a deny-list into an allow-list.
+     */
+    readonly allowedOrigins?: ReadonlyArray<string>;
+};
+/** Bind the endpoint policy at boot. Generated daemons call this before registering the tools. */
+export declare function setRpcEndpointPolicy(next: RpcEndpointPolicy): void;
+/** Read the policy back — for `EvmRpcHealth`, which reports the posture it is operating under. */
+export declare function getRpcEndpointPolicy(): RpcEndpointPolicy;
+export type DnsLookupFn = (host: string) => Promise<{
+    readonly address: string;
+    readonly family: number;
+}>;
+export declare function _setDnsLookup(fn: DnsLookupFn | undefined): void;
+/**
+ * Canonicalise an IPv4 literal.
+ *
+ * `inet_aton` forms are the classic allow-list bypass: `0177.0.0.1`,
+ * `0x7f.0.0.1`, `2130706433` and `127.1` are all 127.0.0.1, and a check that
+ * only understands dotted-decimal waves every one of them through. Returns
+ * `null` when the string is not an IPv4 literal at all.
+ */
+export declare function normalizeIpv4(raw: string): string | null;
+/**
+ * Expand an IPv6 literal to its eight 16-bit groups, or `null` when the string
+ * is not one.
+ *
+ * Classifying IPv6 by its TEXT is where the bypasses live, because one address
+ * has many spellings and the one a check was written against is rarely the one
+ * that arrives. `http://[::ffff:169.254.169.254]/` never reaches a guard in
+ * that form: the WHATWG URL parser re-serialises the embedded quad as hex
+ * pieces, so what the guard sees is `::ffff:a9fe:a9fe`. Normalising to numbers
+ * first means the prefix tests below are arithmetic, and spelling stops
+ * mattering.
+ */
+export declare function parseIpv6(raw: string): ReadonlyArray<number> | null;
+/** Ranges that are never a public RPC endpoint. */
+export declare function isPrivateIp(address: string): boolean;
+export type VettedEndpoint = {
+    readonly url: URL;
+    /** The address the socket must go to. Empty when there is nothing to pin. */
+    readonly pinnedIp: string;
+};
+/**
+ * Validate an RPC URL and resolve the address to pin the connection to.
+ *
+ * Throws `RpcEndpointError` for everything a caller could have got wrong, with
+ * the reason in the message, because every one of these is a refusal a model
+ * should read and act on rather than retry.
+ */
+export declare function vetEndpoint(rawUrl: string): Promise<VettedEndpoint>;