@crewhaus/tool-chainread 0.7.0

package/dist/fixtures.js

@@ -0,0 +1,309 @@
+/** A deterministic 32-byte hash from a label, so fixtures are readable in a diff. */
+export function hash32(label) {
+    const hex = [...label].map((c) => c.charCodeAt(0).toString(16).padStart(2, "0")).join("");
+    return `0x${(hex + "0".repeat(64)).slice(0, 64)}`;
+}
+/** A deterministic 20-byte address from a label. */
+export function address20(label) {
+    const hex = [...label].map((c) => c.charCodeAt(0).toString(16).padStart(2, "0")).join("");
+    return `0x${(hex + "0".repeat(40)).slice(0, 40)}`;
+}
+const hex = (value) => `0x${value.toString(16)}`;
+export const TOKEN = address20("token");
+export const ALICE = address20("alice");
+export const BOB = address20("bob");
+export const ROUTER = address20("router");
+export const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+export const APPROVAL_TOPIC = "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925";
+export function topicFor(address) {
+    return `0x${"0".repeat(24)}${address.slice(2)}`;
+}
+export function word(value) {
+    return value.toString(16).padStart(64, "0");
+}
+export function makeChain(options = {}) {
+    const count = options.blocks ?? 100;
+    const start = options.startTimestamp ?? 1700000000n;
+    const step = options.blockTime ?? 12n;
+    const blocks = [];
+    for (let i = 0; i < count; i++) {
+        const number = BigInt(i);
+        blocks.push({
+            number,
+            timestamp: start + number * step,
+            hash: hash32(`block-${i}`),
+            baseFeePerGas: options.baseFee === undefined ? 1000000000n : options.baseFee,
+        });
+    }
+    return {
+        chainId: options.chainId ?? 8453n,
+        blocks,
+        logs: [],
+        txs: new Map(),
+        receipts: new Map(),
+        nonces: new Map(),
+        head: BigInt(count - 1),
+        safe: BigInt(Math.max(0, count - 32)),
+        finalized: BigInt(Math.max(0, count - 64)),
+    };
+}
+/** Add `count` ERC-20 Transfer logs to one block, from ALICE to BOB. */
+export function addTransferLogs(chain, blockNumber, count, token = TOKEN) {
+    const existing = chain.logs.filter((l) => l.blockNumber === blockNumber).length;
+    for (let i = 0; i < count; i++) {
+        chain.logs.push({
+            blockNumber,
+            logIndex: existing + i,
+            address: token,
+            topics: [TRANSFER_TOPIC, topicFor(ALICE), topicFor(BOB)],
+            data: `0x${word(BigInt(1_000 + i))}`,
+            transactionHash: hash32(`tx-${blockNumber}-${i}`),
+        });
+    }
+}
+export function blockOf(chain, number) {
+    return chain.blocks.find((b) => b.number === number);
+}
+function renderBlock(chain, block, hydrate) {
+    const txs = [...chain.txs.values()].filter((t) => t.blockNumber === block.number);
+    return {
+        number: hex(block.number),
+        hash: block.hash,
+        parentHash: block.number === 0n ? hash32("genesis-parent") : hash32(`block-${block.number - 1n}`),
+        timestamp: hex(block.timestamp),
+        gasLimit: hex(30000000n),
+        gasUsed: hex(15000000n),
+        ...(block.baseFeePerGas === null ? {} : { baseFeePerGas: hex(block.baseFeePerGas) }),
+        miner: address20("miner"),
+        transactions: hydrate ? txs.map((t) => renderTx(t)) : txs.map((t) => t.hash),
+    };
+}
+function renderTx(tx) {
+    return {
+        hash: tx.hash,
+        from: tx.from,
+        to: tx.to,
+        value: hex(tx.value),
+        nonce: hex(tx.nonce),
+        input: tx.input,
+        gas: hex(210000n),
+        gasPrice: hex(1500000000n),
+        maxFeePerGas: hex(2000000000n),
+        maxPriorityFeePerGas: hex(100000000n),
+        type: "0x2",
+        blockNumber: tx.blockNumber === null ? null : hex(tx.blockNumber),
+        blockHash: tx.blockNumber === null ? null : hash32(`block-${tx.blockNumber}`),
+        transactionIndex: tx.blockNumber === null ? null : "0x0",
+    };
+}
+function renderLog(log) {
+    return {
+        address: log.address,
+        topics: log.topics,
+        data: log.data,
+        blockNumber: hex(log.blockNumber),
+        blockHash: hash32(`block-${log.blockNumber}`),
+        transactionHash: log.transactionHash,
+        transactionIndex: "0x0",
+        logIndex: hex(BigInt(log.logIndex)),
+        removed: false,
+    };
+}
+function renderReceipt(receipt) {
+    return {
+        transactionHash: receipt.hash,
+        blockNumber: hex(receipt.blockNumber),
+        blockHash: hash32(`block-${receipt.blockNumber}`),
+        transactionIndex: hex(BigInt(receipt.transactionIndex ?? 0)),
+        gasUsed: hex(receipt.gasUsed),
+        ...(receipt.status === null ? {} : { status: receipt.status }),
+        ...(receipt.root === undefined ? {} : { root: receipt.root }),
+        ...(receipt.effectiveGasPrice === null
+            ? {}
+            : { effectiveGasPrice: hex(receipt.effectiveGasPrice) }),
+        ...(receipt.l1Fee === undefined ? {} : { l1Fee: hex(receipt.l1Fee) }),
+        ...(receipt.gasUsedForL1 === undefined ? {} : { gasUsedForL1: hex(receipt.gasUsedForL1) }),
+        contractAddress: receipt.contractAddress ?? null,
+        logs: receipt.logs.map(renderLog),
+    };
+}
+/** Build an endpoint that serves `chain`, misbehaving in whatever way `options` says. */
+export function rpcStub(chain, options = {}) {
+    const requests = [];
+    const stub = {
+        requests,
+        count: (method) => requests.filter((r) => r.method === method).length,
+        fetch: async (req) => {
+            if (options.unreachable === true)
+                throw new TypeError("connect ECONNREFUSED");
+            const body = (await req.json());
+            const params = body.params ?? [];
+            requests.push({ method: body.method, params });
+            if (options.httpStatus !== undefined && options.httpStatus !== 200) {
+                return new Response(`{"error":"rate limited"}`, { status: options.httpStatus });
+            }
+            const answer = dispatch(chain, options, body.method, params);
+            const envelope = "error" in answer
+                ? { jsonrpc: "2.0", id: body.id, error: answer.error }
+                : { jsonrpc: "2.0", id: body.id, result: answer.result };
+            return new Response(JSON.stringify(envelope), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        },
+    };
+    return stub;
+}
+function dispatch(chain, options, method, params) {
+    switch (method) {
+        case "eth_chainId":
+            return { result: hex(chain.chainId) };
+        case "net_version":
+            return { result: chain.chainId.toString() };
+        case "eth_blockNumber":
+            return { result: hex(chain.head) };
+        case "eth_getBlockByNumber": {
+            const tag = params[0];
+            const hydrate = params[1] === true;
+            const number = resolveTag(chain, options, tag);
+            if (number === null)
+                return { result: null };
+            const block = blockOf(chain, number);
+            if (block === undefined)
+                return { result: null };
+            const rendered = renderBlock(chain, block, hydrate);
+            // The pending block is the head's contents with no identity yet: a node
+            // answers it with number and hash both null.
+            if (tag === "pending")
+                return { result: { ...rendered, number: null, hash: null } };
+            return { result: rendered };
+        }
+        case "eth_getBlockByHash": {
+            const wanted = params[0].toLowerCase();
+            const block = chain.blocks.find((b) => b.hash === wanted);
+            return { result: block === undefined ? null : renderBlock(chain, block, params[1] === true) };
+        }
+        case "eth_getTransactionByHash": {
+            const tx = chain.txs.get(params[0].toLowerCase());
+            return { result: tx === undefined ? null : renderTx(tx) };
+        }
+        case "eth_getTransactionReceipt": {
+            const receipt = chain.receipts.get(params[0].toLowerCase());
+            return { result: receipt === undefined ? null : renderReceipt(receipt) };
+        }
+        case "eth_getTransactionCount": {
+            const who = params[0].toLowerCase();
+            const account = chain.nonces.get(who) ?? { latest: 0n, pending: 0n };
+            const tag = params[1];
+            if (typeof tag === "string" && tag.startsWith("0x")) {
+                // A HISTORICAL nonce, which is account state and not a counter the node
+                // keeps lying around: a pruned endpoint refuses it exactly as it
+                // refuses a historical balance, and a sync that proves its block
+                // coverage against this has to cope with both answers.
+                const at = BigInt(tag);
+                if (options.archive === "no" && chain.head - at > 128n) {
+                    return { error: { code: -32000, message: "missing trie node 0xabc (path )" } };
+                }
+                const mined = [...chain.txs.values()].filter((t) => t.blockNumber !== null && t.from.toLowerCase() === who);
+                // Derived from the chain's own transactions so the two answers cannot
+                // disagree by accident: a test that wants them to disagree says so.
+                const base = chain.nonces.has(who) ? account.latest : BigInt(mined.length);
+                const after = mined.filter((t) => t.blockNumber > at).length;
+                const value = base - BigInt(after);
+                return { result: hex(value < 0n ? 0n : value) };
+            }
+            const wantsPending = tag === "pending";
+            // An endpoint with no mempool view answers both tags with the mined
+            // count, which is the case that makes a naive "pending === latest means
+            // clear" read wrong.
+            if (wantsPending && options.mempoolAware !== false)
+                return { result: hex(account.pending) };
+            return { result: hex(account.latest) };
+        }
+        case "eth_getBalance": {
+            const at = params[1];
+            const number = at.startsWith("0x") && at.length < 20 ? BigInt(at) : chain.head;
+            if (options.archive === "no" && chain.head - number > 128n) {
+                return { error: { code: -32000, message: "missing trie node 0xabc (path )" } };
+            }
+            if (options.archive === "error" && chain.head - number > 128n) {
+                return { error: { code: -32601, message: "the method eth_getBalance does not exist" } };
+            }
+            return { result: hex(1234000000000000000n) };
+        }
+        case "eth_getLogs":
+            return getLogs(chain, options, params[0]);
+        default:
+            return { error: { code: -32601, message: `the method ${method} does not exist` } };
+    }
+}
+function resolveTag(chain, options, tag) {
+    if (tag === "latest")
+        return chain.head;
+    if (tag === "earliest")
+        return 0n;
+    if (tag === "pending")
+        return chain.head;
+    if (tag === "safe" || tag === "finalized") {
+        if (options.noFinalityTags === true)
+            return null;
+        return tag === "safe" ? chain.safe : chain.finalized;
+    }
+    return BigInt(tag);
+}
+function getLogs(chain, options, filter) {
+    const from = BigInt(filter["fromBlock"]);
+    const to = BigInt(filter["toBlock"]);
+    const span = to - from + 1n;
+    if (options.maxRangeBlocks !== undefined && span > options.maxRangeBlocks) {
+        // Alchemy's shape: it names a range that would have worked, in hex.
+        const suggestedTo = from + options.maxRangeBlocks - 1n;
+        return {
+            error: {
+                code: -32600,
+                message: `Log response size exceeded. You can make eth_getLogs requests with up to a ${options.maxRangeBlocks} block range; based on your parameters this block range should work: [${hex(from)}, ${hex(suggestedTo)}]`,
+            },
+        };
+    }
+    const addressFilter = filter["address"];
+    const addresses = addressFilter === undefined
+        ? null
+        : new Set((Array.isArray(addressFilter) ? addressFilter : [addressFilter]).map((a) => String(a).toLowerCase()));
+    const topics = filter["topics"];
+    const matched = chain.logs
+        .filter((log) => log.blockNumber >= from && log.blockNumber <= to)
+        .filter((log) => addresses === null || addresses.has(log.address.toLowerCase()))
+        .filter((log) => topicsMatch(log, topics))
+        .sort((a, b) => a.blockNumber === b.blockNumber
+        ? a.logIndex - b.logIndex
+        : a.blockNumber < b.blockNumber
+            ? -1
+            : 1);
+    if (options.maxResults !== undefined && matched.length > options.maxResults) {
+        return {
+            error: {
+                code: -32005,
+                message: `query returned more than ${options.maxResults} results`,
+            },
+        };
+    }
+    if (options.silentLogCap !== undefined && matched.length > options.silentLogCap) {
+        // The dangerous one: a 200, a well-formed array, and nothing saying it is
+        // short. This is what the scanner has to catch without being told.
+        return { result: matched.slice(0, options.silentLogCap).map(renderLog) };
+    }
+    return { result: matched.map(renderLog) };
+}
+function topicsMatch(log, topics) {
+    if (topics === undefined)
+        return true;
+    return topics.every((position, index) => {
+        if (position === null)
+            return true;
+        const actual = log.topics[index];
+        if (actual === undefined)
+            return false;
+        const wanted = Array.isArray(position) ? position : [position];
+        return wanted.some((t) => String(t).toLowerCase() === actual.toLowerCase());
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { type BlockSelector } from "./lib/blocks";
+export { _setFetch, type RpcFetch, type RpcOutcome, openRpc } from "./lib/rpc";
+export { _setClock, type Clock, virtualClock } from "./lib/clock";
+export { _setDnsLookup, type DnsLookupFn, type RpcEndpointPolicy, RpcEndpointError, getRpcEndpointPolicy, setRpcEndpointPolicy, } from "./lib/endpoint";
+export { ChainReadError } from "./lib/quantity";
+export { parseSuggestedSpan, shouldNarrow, type RawLog } from "./lib/logs";
+export { type AssetUnits, type HistoryReport, type ParkedRow, type RowDetail, type SentProof, collectHistory, toMinorUnits, } from "./lib/history";
+export { TRANSFER_TOPIC, APPROVAL_TOPIC, APPROVAL_FOR_ALL_TOPIC, TRANSFER_SINGLE_TOPIC, TOPIC_SIGNATURES, addressToTopic, decodeApproval, decodeTransfer, feeBreakdown, topicToAddress, } from "./lib/transfers";
+/**
+ * Work out what a caller meant by a block.
+ *
+ * A tag, a 32-byte hash and a hex number all arrive as strings, and the hash is
+ * distinguished by LENGTH — 66 characters including the prefix. Guessing wrong
+ * sends `eth_getBlockByNumber` a hash, which most nodes answer with `null`:
+ * "no such block" for a block that exists.
+ */
+export declare function parseBlockInput(value: string | number, what: string): BlockSelector;
+export declare const evmGetBlock: RegisteredTool;
+export declare const evmBlockAtTimestamp: RegisteredTool;
+/**
+ * Seconds, or an ISO instant, but never milliseconds.
+ *
+ * `Date.now()` pasted into a tool that wants seconds is a timestamp in the year
+ * 55000, which every search resolves to "at or past the head" and answers with
+ * the head block — a wrong answer that looks completely ordinary. So the
+ * thousand-fold mistake is refused by name.
+ */
+export declare function parseTimestamp(value: string | number): bigint;
+export declare const evmRpcHealth: RegisteredTool;
+export declare const evmNonceStatus: RegisteredTool;
+export declare const evmWaitForReceipt: RegisteredTool;
+export declare const evmTransactionSummary: RegisteredTool;
+export declare const evmEventScan: RegisteredTool;
+export declare const onchainTransactionsSync: RegisteredTool;
+/** Every tool this package registers, in the order a catalog should list them. */
+export declare const CHAINREAD_TOOLS: ReadonlyArray<RegisteredTool>;