@crewhaus/tool-chainread 0.7.0

package/dist/lib/rpc.js

@@ -0,0 +1,330 @@
+/**
+ * One JSON-RPC request, done carefully, and the only way out of this package.
+ *
+ * Three properties the code below exists to hold:
+ *
+ *   1. **Nothing here can send a transaction.** Every method name goes through
+ *      `assertReadOnlyMethod` from `@crewhaus/chain-adapter-base` — the same
+ *      allow-list the adapters use — before a socket is opened. That makes the
+ *      "this package only reads" claim structural rather than a promise about
+ *      the call sites: `eth_sendRawTransaction` throws here even if some
+ *      future edit asks for it. `index.test.ts` asserts it.
+ *   2. **Failures are returned, not thrown.** A tool that polls, pages or
+ *      probes several endpoints needs to branch on WHY a call failed — a
+ *      halve-and-retry on a range cap is right, a halve-and-retry on a 401 is
+ *      a denial-of-service against somebody's endpoint. `RpcOutcome` keeps
+ *      those apart. The refusals a caller can fix (a bad URL, a write method)
+ *      still throw, because they are not something to branch on.
+ *   3. **The URL never appears in an error.** Provider keys live in the path —
+ *      `…/v2/<key>` on Alchemy, `…/v3/<key>` on Infura — so messages carry the
+ *      origin only. An error that quotes the endpoint is how a key reaches a
+ *      transcript.
+ */
+import { assertReadOnlyMethod } from "@crewhaus/chain-adapter-base";
+import { vetEndpoint } from "./endpoint";
+import { ChainReadError } from "./quantity";
+export const DEFAULT_TIMEOUT_MS = 20_000;
+export const MAX_TIMEOUT_MS = 120_000;
+/**
+ * 16 MB. A single `eth_getLogs` page of ten thousand logs is a few megabytes;
+ * this is generous enough that no honest answer hits it and small enough that a
+ * broken endpoint streaming forever cannot pin the process.
+ */
+export const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+const USER_AGENT = "crewhaus-tool-chainread (+https://github.com/crewhaus/factory)";
+/**
+ * Dial the vetted IP while keeping the real hostname for the Host header and
+ * TLS SNI, so virtual hosting and certificate validation still work. Mirrors
+ * `tool-containers`' dialer rather than re-deriving it: resolving in the guard
+ * and letting `fetch` re-resolve at connect time is the rebinding TOCTOU the
+ * guard exists to close.
+ *
+ * This function is the one place in the package a test never executes, because
+ * executing it means opening a socket.
+ */
+const pinnedFetch = async (req, pinnedIp) => {
+    const original = new URL(req.url);
+    const host = original.hostname;
+    const unbracketed = host.replace(/^\[/, "").replace(/\]$/, "");
+    if (pinnedIp === "" || unbracketed === pinnedIp)
+        return globalThis.fetch(req);
+    const pinnedUrl = new URL(original.toString());
+    pinnedUrl.hostname = pinnedIp.includes(":") ? `[${pinnedIp}]` : pinnedIp;
+    const headers = new Headers(req.headers);
+    headers.set("host", original.port === "" ? host : `${host}:${original.port}`);
+    // Re-read the body as a string rather than forwarding the Request's stream:
+    // a streaming body needs duplex support that runtimes disagree about, and a
+    // JSON-RPC envelope is a few hundred bytes.
+    const body = await req.text();
+    const init = {
+        method: req.method,
+        headers,
+        body,
+        signal: req.signal,
+        redirect: "manual",
+        tls: { serverName: host },
+    };
+    return globalThis.fetch(pinnedUrl.toString(), init);
+};
+let rpcFetch = pinnedFetch;
+/**
+ * Test seam — `_setFetch(undefined)` restores the production dialer. A suite
+ * that sets it must restore it, or the next file in the same bun process
+ * inherits the stub.
+ */
+export function _setFetch(fn) {
+    rpcFetch = fn ?? pinnedFetch;
+}
+/**
+ * Vet the URL once, then reuse the verdict for every call on it.
+ *
+ * `EvmEventScan` issues dozens of requests against one endpoint and
+ * `EvmWaitForReceipt` issues one per poll; re-resolving the host each time
+ * would be a DNS query per call, and — worse — would let the answer change
+ * mid-scan, which is precisely the rebinding the pin defends against.
+ */
+export async function openRpc(rawUrl, options = {}) {
+    const endpoint = await vetEndpoint(rawUrl);
+    return clientFor(endpoint, options);
+}
+function clientFor(endpoint, options) {
+    const timeoutMs = Math.min(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const origin = endpoint.url.origin;
+    let nextId = 1;
+    const client = {
+        origin,
+        calls: 0,
+        async call(method, params) {
+            assertReadOnlyMethod(origin, method);
+            client.calls += 1;
+            return request(endpoint, {
+                id: nextId++,
+                method,
+                params,
+                timeoutMs,
+                maxBytes,
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            });
+        },
+    };
+    return client;
+}
+async function request(endpoint, spec) {
+    const origin = endpoint.url.origin;
+    const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: spec.id,
+        method: spec.method,
+        params: spec.params,
+    });
+    const timer = new AbortController();
+    const handle = setTimeout(() => timer.abort(new Error("deadline")), spec.timeoutMs);
+    const onOuterAbort = () => timer.abort();
+    spec.signal?.addEventListener("abort", onOuterAbort, { once: true });
+    try {
+        let res;
+        try {
+            res = await rpcFetch(new Request(endpoint.url.toString(), {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    accept: "application/json",
+                    "user-agent": USER_AGENT,
+                },
+                body,
+                redirect: "manual",
+                signal: timer.signal,
+            }), endpoint.pinnedIp);
+        }
+        catch (err) {
+            const error = err;
+            const aborted = error?.name === "AbortError" || timer.signal.aborted;
+            // The caller's own signal and our deadline both surface as an abort, and
+            // they are different situations: one means the run is shutting down, the
+            // other means this endpoint is slow. Only the second is worth retrying.
+            if (aborted && spec.signal?.aborted === true) {
+                return {
+                    ok: false,
+                    kind: "timeout",
+                    message: `the run was cancelled while ${origin} was answering ${spec.method}`,
+                };
+            }
+            if (aborted) {
+                return {
+                    ok: false,
+                    kind: "timeout",
+                    message: `${origin} did not answer ${spec.method} within ${spec.timeoutMs}ms`,
+                };
+            }
+            return {
+                ok: false,
+                kind: "transport",
+                message: `could not reach ${origin}: ${error?.message ?? String(err)}`,
+            };
+        }
+        // A redirect is not followed. An RPC endpoint that 302s is either
+        // misconfigured or pointing somewhere the guard never vetted, and the
+        // second is the whole reason `redirect: "manual"` is set.
+        if (res.status >= 300 && res.status < 400) {
+            return {
+                ok: false,
+                kind: "status",
+                status: res.status,
+                message: `${origin} answered ${res.status} with a redirect — refusing to follow it to a host that was never vetted`,
+            };
+        }
+        let text;
+        try {
+            text = await readCapped(res, spec.maxBytes);
+        }
+        catch (err) {
+            if (err instanceof BodyTooLarge) {
+                return {
+                    ok: false,
+                    kind: "tooLarge",
+                    message: `${origin} sent more than ${spec.maxBytes} bytes for ${spec.method} — refusing to parse a prefix of it`,
+                };
+            }
+            return {
+                ok: false,
+                kind: "transport",
+                message: `${origin} closed the connection while sending ${spec.method}`,
+            };
+        }
+        if (res.status < 200 || res.status >= 300) {
+            // Providers rate-limit with 429 and a JSON-RPC body, so the status is
+            // reported alongside whatever the body said rather than instead of it.
+            return {
+                ok: false,
+                kind: "status",
+                status: res.status,
+                message: `${origin} answered HTTP ${res.status} for ${spec.method}: ${snippet(text)}`,
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return {
+                ok: false,
+                kind: "malformed",
+                message: `${origin} answered ${spec.method} with something that is not JSON: ${snippet(text)}`,
+            };
+        }
+        if (Array.isArray(parsed)) {
+            return {
+                ok: false,
+                kind: "malformed",
+                message: `${origin} answered a single ${spec.method} request with a batch array`,
+            };
+        }
+        if (typeof parsed !== "object" || parsed === null) {
+            return {
+                ok: false,
+                kind: "malformed",
+                message: `${origin} answered ${spec.method} with ${snippet(text)}, not a JSON-RPC envelope`,
+            };
+        }
+        const envelope = parsed;
+        const rpcErr = envelope["error"];
+        if (rpcErr !== undefined && rpcErr !== null) {
+            const asObject = typeof rpcErr === "object" ? rpcErr : {};
+            const code = typeof asObject["code"] === "number" ? asObject["code"] : undefined;
+            // Capped here rather than where it is read. This string is the one field
+            // in the exchange the endpoint fills in freely, it arrives inside a body
+            // allowed up to `maxBytes`, and from here it goes into a refusal, a tool
+            // result and a model's context. A provider's longest real message is a
+            // sentence and a suggested range.
+            const message = typeof asObject["message"] === "string"
+                ? capMessage(asObject["message"])
+                : snippet(text);
+            return {
+                ok: false,
+                kind: "rpcError",
+                message,
+                ...(code !== undefined ? { code } : {}),
+                ...(asObject["data"] !== undefined ? { data: asObject["data"] } : {}),
+            };
+        }
+        if (!("result" in envelope)) {
+            return {
+                ok: false,
+                kind: "malformed",
+                message: `${origin} answered ${spec.method} with neither a result nor an error`,
+            };
+        }
+        return { ok: true, result: envelope["result"] };
+    }
+    finally {
+        clearTimeout(handle);
+        spec.signal?.removeEventListener("abort", onOuterAbort);
+    }
+}
+class BodyTooLarge extends Error {
+}
+/**
+ * Read a body with a ceiling, WHILE reading.
+ *
+ * `await res.text()` would buffer whatever arrives first and check afterwards,
+ * which is no ceiling at all against an endpoint that streams. Stopping at the
+ * cap and refusing is also why the result is never parsed as a prefix: half a
+ * log array parses to a plausible SHORTER answer, which is the failure mode
+ * this whole package is organised against.
+ */
+async function readCapped(res, maxBytes) {
+    const body = res.body;
+    if (body === null)
+        return "";
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value === undefined)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes)
+                throw new BodyTooLarge();
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(joined);
+}
+/** The longest JSON-RPC error message this package will carry. */
+export const MAX_ERROR_MESSAGE_CHARS = 2_000;
+function capMessage(text) {
+    return text.length <= MAX_ERROR_MESSAGE_CHARS
+        ? text
+        : `${text.slice(0, MAX_ERROR_MESSAGE_CHARS)}… (truncated from ${text.length} characters)`;
+}
+/** Enough of a body to recognise it, never enough to paste a secret into a transcript. */
+function snippet(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > 200 ? `${flat.slice(0, 200)}…` : flat;
+}
+/** Turn a failed outcome into the refusal a tool throws, with the reason kept. */
+export function failed(outcome, what) {
+    const code = outcome.code === undefined ? "" : ` (code ${outcome.code})`;
+    return new ChainReadError(`${what}: ${outcome.message}${code} [${outcome.kind}]`);
+}
+/** Call, or throw the refusal. For the steps where there is nothing to fall back to. */
+export async function callOrThrow(client, method, params, what) {
+    const outcome = await client.call(method, params);
+    if (!outcome.ok)
+        throw failed(outcome, what);
+    return outcome.result;
+}

package/dist/lib/transfers.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Turning one transaction into bookkeeping: what moved, who paid, and — the
+ * part most summaries get wrong — what is not visible from here at all.
+ *
+ * A receipt contains logs and nothing else. Native value that a CONTRACT sent
+ * during the call leaves no log; it is only visible in a trace, and
+ * `debug_traceTransaction` is not on any public endpoint's free tier and is not
+ * on this package's read-only allow-list. So the summary reports the top-level
+ * `value` and says, in the output and not only in the README, that internal
+ * transfers are excluded. A net delta that claims to be complete and is not is
+ * worse than no net delta: it reconciles.
+ *
+ * The event topics below are constants because computing them needs Keccak and
+ * this package has no hasher of its own. They are not TRUSTED as constants —
+ * `lib.test.ts` recomputes every one of them with `FunctionSelector` from
+ * `@crewhaus/tool-onchain` and fails if a digit is off. A mistyped topic is a
+ * filter that silently matches nothing, which is the same failure as a missing
+ * log.
+ */
+import type { RawLog } from "./logs";
+/** `Transfer(address,address,uint256)` — ERC-20 and ERC-721 share it. */
+export declare const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+/** `Approval(address,address,uint256)`. */
+export declare const APPROVAL_TOPIC = "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925";
+/** `ApprovalForAll(address,address,bool)` — the blanket ERC-721/1155 approval. */
+export declare const APPROVAL_FOR_ALL_TOPIC = "0x17307eab39ab6107e8899845ad3d59bd9653f200f220920489ca2b5937696c31";
+/** `TransferSingle(address,address,address,uint256,uint256)` — ERC-1155. */
+export declare const TRANSFER_SINGLE_TOPIC = "0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62";
+/** The signatures the constants above are the Keccak of, so the test can recompute them. */
+export declare const TOPIC_SIGNATURES: Readonly<Record<string, string>>;
+/** The low 20 bytes of a 32-byte topic word, which is how an indexed address is stored. */
+export declare function topicToAddress(topic: string): string;
+/**
+ * The inverse: an address as the 32-byte topic word a log filter matches on.
+ *
+ * Left-padded to 32 bytes and lowercased, because `eth_getLogs` compares topics
+ * as fixed-width words and an unpadded or mixed-case one matches nothing — a
+ * filter that silently returns an empty set, which reads exactly like an
+ * address that never moved anything.
+ */
+export declare function addressToTopic(address: string): string;
+export type TokenMovement = {
+    readonly standard: "erc20" | "erc721" | "erc1155";
+    readonly token: string;
+    readonly from: string;
+    readonly to: string;
+    /** Base units for ERC-20, the token id for ERC-721. Always a decimal string. */
+    readonly amount: string;
+    readonly tokenId?: string;
+    readonly logIndex: number;
+};
+export type ApprovalEvent = {
+    readonly kind: "approval" | "approvalForAll";
+    readonly token: string;
+    readonly owner: string;
+    readonly spender: string;
+    /** For `approval`: the allowance in base units. `unlimited` marks the max-uint256 pattern. */
+    readonly amount?: string;
+    readonly unlimited?: boolean;
+    readonly approved?: boolean;
+    readonly logIndex: number;
+};
+/**
+ * An ERC-20 transfer and an ERC-721 transfer are the same event with different
+ * indexing: the token id is indexed, the amount is not. So three topics means
+ * fungible and four means a specific NFT — the only signal there is, and
+ * reading a token id as an amount is how an NFT becomes "1e-18 of a token".
+ */
+export declare function decodeTransfer(log: RawLog): TokenMovement | null;
+export declare function decodeApproval(log: RawLog): ApprovalEvent | null;
+export type TransactionView = {
+    readonly hash: string;
+    readonly from: string;
+    readonly to: string | null;
+    readonly value: string;
+    readonly nonce: string;
+    readonly input: string;
+    readonly selector: string | null;
+    readonly gas: string | null;
+    readonly gasPrice: string | null;
+    readonly maxFeePerGas: string | null;
+    readonly maxPriorityFeePerGas: string | null;
+    readonly type: string | null;
+    readonly blockNumber: string | null;
+    readonly blockHash: string | null;
+    readonly contractCreation: boolean;
+};
+export declare function projectTransaction(raw: Record<string, unknown>): TransactionView;
+/**
+ * What a receipt says happened.
+ *
+ * `status` has three values here, not two. `0x1` and `0x0` are the chain's
+ * answer; `unknown` is for a pre-Byzantium receipt, which carries a state
+ * `root` instead of a status and simply does not record whether the call
+ * reverted. Mapping that third case onto "failed" would invent a revert, and
+ * onto "succeeded" would hide one.
+ */
+export type ReceiptView = {
+    readonly status: "success" | "reverted" | "unknown";
+    readonly statusReason?: string;
+    readonly blockNumber: string;
+    readonly blockHash: string;
+    readonly transactionIndex: number | null;
+    readonly gasUsed: string;
+    readonly effectiveGasPrice: string | null;
+    readonly contractAddress: string | null;
+    readonly logs: ReadonlyArray<RawLog>;
+};
+export declare function projectReceipt(raw: Record<string, unknown>, projectLog: (value: unknown) => RawLog): ReceiptView;
+export type FeeBreakdown = {
+    /** Which chain family's fee arithmetic was applied, inferred from the receipt's own fields. */
+    readonly model: "eip1559" | "op-stack" | "arbitrum" | "unknown";
+    readonly gasUsed: string;
+    readonly effectiveGasPrice: string | null;
+    readonly executionFeeWei: string | null;
+    /** The OP-stack L1 data fee, which is a separate charge and is NOT in gasUsed. */
+    readonly l1FeeWei: string | null;
+    readonly totalFeeWei: string | null;
+    readonly note: string;
+};
+/**
+ * `gasUsed * effectiveGasPrice` is the whole fee on L1 and is WRONG on a
+ * rollup, in two different directions.
+ *
+ * OP-stack chains charge a separate L1 data fee that appears as `l1Fee` on the
+ * receipt and is not included in `gasUsed`; leaving it out understates the cost
+ * of a Base or Optimism transaction by most of the cost. Arbitrum folds its L1
+ * component INTO `gasUsed` and reports the share as `gasUsedForL1`, so the
+ * simple product is right there and adding anything would double-count.
+ *
+ * Both are detected from fields the receipt either has or does not, rather than
+ * from a chain id table that goes stale every time a new rollup ships.
+ */
+export declare function feeBreakdown(receipt: Record<string, unknown>, view: ReceiptView): FeeBreakdown;