@crewhaus/tool-chainread 0.7.0 → 0.8.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+CrewHaus Factory
+Copyright 2026 Max Meier
+
+This product includes software developed by Max Meier
+(operating as StudioMax — https://studiomax.io) and contributors.
+
+The CrewHaus name and logo are trademarks of Max Meier. See
+https://github.com/crewhaus/factory/blob/main/TRADEMARK.md for the
+use-of-marks policy.

package/README.md

@@ -333,18 +333,33 @@ IPv4-mapped, IPv4-translated, NAT64's `64:ff9b::/96` (which is exactly what a DN
 resolver answers for an IPv4-only name), 6to4's `2002::/16`, the deprecated
 IPv4-compatible form — is resolved to the IPv4 it carries and judged on that.
 
-A local anvil or hardhat node is the obvious casualty, so an **operator** can permit it:
+With no configuration these tools may dial any public RPC origin. A spec narrows that
+to a list, and a compiled bundle, `crewhaus run` and `crewhaus eval` apply it at boot:
+
+```yaml
+tool_config:
+  chainread:
+    allowed_origins: [https://mainnet.base.org]   # the ONLY origins these tools dial
+```
+
+A `model_pool` candidate may carry the same block under its own `tool_config`. It
+narrows the calls that model makes and never widens them: an origin must be on the
+candidate's list AND on the agent's list, when there is one. A spec that sets the
+list only on a candidate is held to it on that candidate's calls. `EvmRpcHealth`
+reports it as `modelAllowedOrigins`.
+
+A spec cannot open loopback or the private ranges: `allow_private_hosts` in the block
+is refused, because a spec can come from a template or a pull request. A local anvil
+or hardhat node is the casualty; a host that runs one opens it in code:
 
 ```ts
 import { setRpcEndpointPolicy } from "@crewhaus/tool-chainread";
 
 setRpcEndpointPolicy({ allowPrivateHosts: true }); // a local devnet
-setRpcEndpointPolicy({ allowedOrigins: ["https://mainnet.base.org"] }); // stricter still
 ```
 
-Bound at boot by the runtime, exactly like `setEvmAdapterResolver` in `tool-evm`, and
-deliberately **not** a field in any tool's input schema: a gate a model can open for
-itself is not a gate. `EvmRpcHealth` reports the policy it is operating under.
+Neither is a field in any tool's input schema: a gate a model can open for itself is
+not a gate. `EvmRpcHealth` reports the policy it is operating under.
 
 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. It covers the same ground

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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 { _setDnsLookup, type ChainreadConfigInput, type DnsLookupFn, type RpcEndpointPolicy, RpcEndpointError, getRpcEndpointPolicy, registerChainreadConfig, 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";

package/dist/index.js

@@ -42,7 +42,7 @@ import { buildTool } from "@crewhaus/tool-builder";
 import { z } from "zod";
 import { fetchBlock, headNumber, searchBlockAtTimestamp, } from "./lib/blocks";
 import { nowMs, sleep } from "./lib/clock";
-import { getRpcEndpointPolicy } from "./lib/endpoint";
+import { callOrigins, getRpcEndpointPolicy } from "./lib/endpoint";
 import { UNKNOWN_UNITS, collectHistory } from "./lib/history";
 import { projectLog, scanLogs } from "./lib/logs";
 import { ChainReadError, hexToBigint, isAddress, isBlockTag, isHash32, json, lowerHex, requireObject, toBigint, toHexQuantity, unixToIso, } from "./lib/quantity";
@@ -50,7 +50,7 @@ import { callOrThrow, openRpc } from "./lib/rpc";
 import { decodeApproval, decodeTransfer, feeBreakdown, projectReceipt, projectTransaction, } from "./lib/transfers";
 export { _setFetch, openRpc } from "./lib/rpc";
 export { _setClock, virtualClock } from "./lib/clock";
-export { _setDnsLookup, RpcEndpointError, getRpcEndpointPolicy, setRpcEndpointPolicy, } from "./lib/endpoint";
+export { _setDnsLookup, RpcEndpointError, getRpcEndpointPolicy, registerChainreadConfig, setRpcEndpointPolicy, } from "./lib/endpoint";
 export { ChainReadError } from "./lib/quantity";
 export { parseSuggestedSpan, shouldNarrow } from "./lib/logs";
 export { collectHistory, toMinorUnits, } from "./lib/history";
@@ -93,9 +93,11 @@ const blockField = z
 const addressField = z.string().length(42).describe("a 0x-prefixed 20-byte address");
 const hashField = z.string().length(66).describe("a 0x-prefixed 32-byte hash");
 async function client(input, ctx) {
+    const narrowTo = callOrigins(ctx?.toolConfig);
     return openRpc(input.rpcUrl, {
         ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),
         ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        ...(narrowTo !== undefined ? { allowedOrigins: narrowTo } : {}),
     });
 }
 /**
@@ -150,6 +152,7 @@ async function resolveBlockNumber(rpc, value, what) {
 // ---------------------------------------------------------------------------
 export const evmGetBlock = buildTool({
     name: "EvmGetBlock",
+    operativeArgs: [{ field: "rpcUrl", kind: "url" }],
     description: "Read one block's header from a JSON-RPC endpoint — number, hash, parent, timestamp (unix and ISO), gas limit and usage, base fee and transaction count — by number, by tag, or by block hash. Use it to anchor anything that needs a block: a historical read, a confirmation count, or the time a range covers. It picks getBlockByHash or getBlockByNumber from the shape of what you pass, reports a chain with no base fee as legacy rather than putting a null into your fee arithmetic, and answers a block that does not exist with found:false rather than an error, because that is a fact about the chain and not a failure.",
     inputSchema: z
         .object({
@@ -197,6 +200,7 @@ export const evmGetBlock = buildTool({
 });
 export const evmBlockAtTimestamp = buildTool({
     name: "EvmBlockAtTimestamp",
+    operativeArgs: [{ field: "rpcUrl", kind: "url" }],
     description: "Find the block a chain was at, at a given moment: the LAST block whose timestamp is at or before the one you name, together with the block after it so the answer can be checked. Use it to pin a historical read — an end-of-quarter balance, the state before an incident — to a block number, instead of guessing from an average block time. A timestamp before the chain's first block is refused rather than answered with block zero, a timestamp at or past the head returns the head and says so, and a chain whose block timestamps run backwards is refused rather than searched, because a binary search there has no single right answer.",
     inputSchema: z
         .object({
@@ -275,6 +279,10 @@ export function parseTimestamp(value) {
 }
 export const evmRpcHealth = buildTool({
     name: "EvmRpcHealth",
+    operativeArgs: [
+        { field: "rpcUrl", kind: "url" },
+        { field: "compareWith", kind: "url" },
+    ],
     description: "Probe a JSON-RPC endpoint and report what it is and what it can serve: chain id, head block and how old that head is, and whether it keeps archive state. Use it before trusting a chain read, and to compare several endpoints against each other — two endpoints reporting different chain ids is a misconfiguration that would otherwise show up as impossible data. Archive support is decided by reading a historic balance and interpreting the failure, and when the evidence does not settle it — a chain too short to tell, an error that means something else — it reports unknown rather than false, because 'we could not tell' and 'it does not' lead to different decisions.",
     inputSchema: z
         .object({
@@ -337,7 +345,7 @@ export const evmRpcHealth = buildTool({
                 unreachableIf: "the chainId or head probe failed",
                 archiveUnknownIf: "the probe block is within 128 blocks of the head, or the error was not a pruning error",
             },
-            policy: describePolicy(),
+            policy: describePolicy(ctx),
         });
     },
 });
@@ -358,9 +366,11 @@ async function probeEndpoint(url, ctx, timeoutMs, archiveProbeBlock, staleAfter)
     const errors = [];
     let rpc;
     try {
+        const narrowTo = callOrigins(ctx?.toolConfig);
         rpc = await openRpc(url, {
             ...(ctx?.signal !== undefined ? { signal: ctx.signal } : {}),
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(narrowTo !== undefined ? { allowedOrigins: narrowTo } : {}),
         });
     }
     catch (err) {
@@ -492,15 +502,25 @@ function safeOrigin(url) {
         return "(unparseable url)";
     }
 }
-function describePolicy() {
+function describePolicy(ctx) {
     const policy = getRpcEndpointPolicy();
+    let narrowedTo = null;
+    try {
+        narrowedTo = callOrigins(ctx?.toolConfig) ?? null;
+    }
+    catch {
+        // Already reported on each endpoint by the probe that tried to use it.
+    }
     return {
         allowPrivateHosts: policy.allowPrivateHosts === true,
         allowedOrigins: policy.allowedOrigins ?? null,
+        // This model's own tool_config block, which narrows the list above.
+        modelAllowedOrigins: narrowedTo,
     };
 }
 export const evmNonceStatus = buildTool({
     name: "EvmNonceStatus",
+    operativeArgs: [{ field: "rpcUrl", kind: "url" }],
     description: "Compare an account's latest and pending nonce and say what that means: clear, transactions waiting, a nonce gap, or — when the evidence does not support a verdict — unknown. Use it before sending anything from an account a harness manages, and to find out why a broadcast seems stuck. Pass the transaction hashes you broadcast and it will tell you which are mined, which are still in this endpoint's mempool and which it has never heard of. It degrades loudly: many endpoints do not track a public mempool and answer the pending nonce with the latest one, so a confident 'clear' from those would be wrong, and this reports the endpoint's mempool visibility instead of guessing.",
     inputSchema: z
         .object({
@@ -611,6 +631,7 @@ export const evmNonceStatus = buildTool({
 });
 export const evmWaitForReceipt = buildTool({
     name: "EvmWaitForReceipt",
+    operativeArgs: [{ field: "rpcUrl", kind: "url" }],
     description: "Wait, with a deadline, for a transaction to be mined, and report which of three things happened: it was mined and succeeded, it was mined and REVERTED, or the deadline passed with it still unmined. Use it after broadcasting anything. The three outcomes are the point — a reverted transaction has a receipt with status 0x0, so a tool that reports 'no receipt' for it tells a caller to broadcast again, which is how a failed transaction becomes two. It also tells a transaction this endpoint has never seen apart from one it is holding in its mempool, and can wait for a number of confirmations or for the chain's own safe/finalized tag instead of a block count.",
     inputSchema: z
         .object({
@@ -760,6 +781,7 @@ async function settlement(rpc, receiptBlock, finality, wanted) {
 }
 export const evmTransactionSummary = buildTool({
     name: "EvmTransactionSummary",
+    operativeArgs: [{ field: "rpcUrl", kind: "url" }],
     description: "Explain one transaction in bookkeeping terms: who sent it, what it called, which tokens and how much native value moved, which approvals it granted, what it cost in fees, and the net change for an address you name. Use it to reconcile or to explain a transaction without reading raw logs. It is explicit about its own blind spots, in the output and not only in the docs: a receipt carries logs and no trace, so native value moved by a CONTRACT during the call is invisible here and the net deltas say so. Fees are computed from the fields the receipt actually has, so an OP-stack L1 data fee is added and an Arbitrum L1 charge is not double-counted.",
     inputSchema: z
         .object({
@@ -892,6 +914,7 @@ function netDeltas(who, tx, receipt, movements, fees) {
 }
 export const evmEventScan = buildTool({
     name: "EvmEventScan",
+    operativeArgs: [{ field: "rpcUrl", kind: "url" }],
     description: "Collect every log matching a filter across a block range, paging around whatever limits the endpoint imposes, and refuse rather than return a set it cannot prove is complete. Use it to find what happened onchain over a period — transfers to an address, every emission of one event — without hand-writing the paging. Public endpoints cap log queries and disagree about how: some answer with an error naming a smaller range, and some silently return the first N logs of a range that held more. The first is handled by halving and retrying; the second is caught by re-querying a suspicious chunk in halves and comparing the counts, because a missing log is an event that, to everything downstream, did not happen.",
     inputSchema: z
         .object({
@@ -1047,6 +1070,7 @@ const unitsField = z
     .strict();
 export const onchainTransactionsSync = buildTool({
     name: "OnchainTransactionsSync",
+    operativeArgs: [{ field: "rpcUrl", kind: "url" }],
     description: "Pull one address's onchain history over a block range and return it as the same normalized rows a bank statement parses into, so a wallet can be reconciled against a ledger instead of read as raw logs. It emits the row shape StatementParse produces and LedgerReconcile consumes — id, date, description, amountMinor, direction, reference, balanceMinor — with the exact uint256 kept alongside each row rather than rounded into it. Use it to close the books on a wallet, or to sync incrementally: it returns a cursor pinned to the block it actually finished at. It refuses rather than under-reporting, the way EvmEventScan does, and it says in the output which movements it cannot see at all: internal native transfers need a trace, and ERC-1155 is not collected.",
     inputSchema: z
         .object({

package/dist/lib/endpoint.d.ts

@@ -11,8 +11,8 @@
  * 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
+ * OPERATOR opened them — `setRpcEndpointPolicy`, bound at boot from the spec's
+ * `tool_config.chainread` block (which can only narrow it), or by a host. It is
  * deliberately not a field in any tool's input schema: a gate a model can open
  * for itself is not a gate.
  *
@@ -43,8 +43,36 @@ export type RpcEndpointPolicy = {
      */
     readonly allowedOrigins?: ReadonlyArray<string>;
 };
-/** Bind the endpoint policy at boot. Generated daemons call this before registering the tools. */
+/**
+ * Bind the endpoint policy. A compiled bundle, `crewhaus run` and `crewhaus
+ * eval` bind it at boot through {@link registerChainreadConfig}, from the
+ * spec's `tool_config.chainread` block; a host may call it directly.
+ */
 export declare function setRpcEndpointPolicy(next: RpcEndpointPolicy): void;
+/** The spec's `tool_config.chainread` block — or any chainread tool's own key. */
+export type ChainreadConfigInput = {
+    readonly allowed_origins?: ReadonlyArray<string>;
+    readonly allowedOrigins?: ReadonlyArray<string>;
+};
+/**
+ * Deliver the spec's block at boot: `allowed_origins` becomes the ONLY RPC
+ * origins these tools may dial. It can only narrow. Opening loopback and the
+ * private ranges stays out of a spec's reach — a spec may come from a template
+ * or a pull request, and that address is every unauthenticated service on the
+ * box — so a block that tries is refused rather than ignored.
+ */
+export declare function registerChainreadConfig(input: ChainreadConfigInput): void;
+/**
+ * The RPC origins a model-pool candidate's own `tool_config` block narrows
+ * THIS call to (`ToolExecuteContext.toolConfig`), or `undefined` when it sets
+ * none. It narrows only: an origin must be in this list AND in the list bound
+ * at boot, when there is one. A candidate that lists an origin the agent's
+ * block does not is refused there, not widened — the boot list is the
+ * operator's ceiling for every model in the pool. Before 0.7.1 this block was
+ * accepted by `compile --strict` and never read, so a spec that set the list
+ * only on a candidate dialled any public origin (C029).
+ */
+export declare function callOrigins(toolConfig: unknown): ReadonlyArray<string> | undefined;
 /** 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<{
@@ -88,4 +116,4 @@ export type VettedEndpoint = {
  * 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>;
+export declare function vetEndpoint(rawUrl: string, narrowTo?: ReadonlyArray<string>): Promise<VettedEndpoint>;

package/dist/lib/endpoint.js

@@ -11,8 +11,8 @@
  * 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
+ * OPERATOR opened them — `setRpcEndpointPolicy`, bound at boot from the spec's
+ * `tool_config.chainread` block (which can only narrow it), or by a host. It is
  * deliberately not a field in any tool's input schema: a gate a model can open
  * for itself is not a gate.
  *
@@ -30,10 +30,82 @@ export class RpcEndpointError extends CrewhausError {
     }
 }
 let policy = {};
-/** Bind the endpoint policy at boot. Generated daemons call this before registering the tools. */
+/**
+ * Bind the endpoint policy. A compiled bundle, `crewhaus run` and `crewhaus
+ * eval` bind it at boot through {@link registerChainreadConfig}, from the
+ * spec's `tool_config.chainread` block; a host may call it directly.
+ */
 export function setRpcEndpointPolicy(next) {
     policy = next;
 }
+/**
+ * Deliver the spec's block at boot: `allowed_origins` becomes the ONLY RPC
+ * origins these tools may dial. It can only narrow. Opening loopback and the
+ * private ranges stays out of a spec's reach — a spec may come from a template
+ * or a pull request, and that address is every unauthenticated service on the
+ * box — so a block that tries is refused rather than ignored.
+ */
+export function registerChainreadConfig(input) {
+    const origins = originsOf(input);
+    if (origins === undefined)
+        return;
+    setRpcEndpointPolicy({ ...policy, allowedOrigins: origins });
+}
+/**
+ * The RPC origins a model-pool candidate's own `tool_config` block narrows
+ * THIS call to (`ToolExecuteContext.toolConfig`), or `undefined` when it sets
+ * none. It narrows only: an origin must be in this list AND in the list bound
+ * at boot, when there is one. A candidate that lists an origin the agent's
+ * block does not is refused there, not widened — the boot list is the
+ * operator's ceiling for every model in the pool. Before 0.7.1 this block was
+ * accepted by `compile --strict` and never read, so a spec that set the list
+ * only on a candidate dialled any public origin (C029).
+ */
+export function callOrigins(toolConfig) {
+    if (toolConfig === undefined || toolConfig === null)
+        return undefined;
+    if (typeof toolConfig !== "object" || Array.isArray(toolConfig)) {
+        throw new RpcEndpointError("this model's tool_config block for the chain readers is not a mapping; write allowed_origins under it.");
+    }
+    return originsOf(toolConfig);
+}
+/** A block's allowed_origins, checked and reduced to origins; `undefined` when it sets none. */
+function originsOf(input) {
+    const block = (input ?? {});
+    for (const key of ["allow_private_hosts", "allowPrivateHosts"]) {
+        if (Object.hasOwn(block, key)) {
+            throw new RpcEndpointError(`tool_config.chainread.${key} is not accepted: a spec cannot open loopback or private addresses. Remove it, and list the public RPC origins under allowed_origins.`);
+        }
+    }
+    if (Object.hasOwn(block, "allowed_origins") && Object.hasOwn(block, "allowedOrigins")) {
+        throw new RpcEndpointError("tool_config.chainread sets both allowed_origins and allowedOrigins. Write the list once, as allowed_origins.");
+    }
+    const raw = block["allowed_origins"] ?? block["allowedOrigins"];
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || raw.some((o) => typeof o !== "string")) {
+        throw new RpcEndpointError('tool_config.chainread.allowed_origins must be a list of origins, for example ["https://mainnet.base.org"].');
+    }
+    const origins = raw.map((o, i) => {
+        let url;
+        try {
+            url = new URL(o);
+        }
+        catch {
+            // Named by position, never by value: an entry that fails to parse is
+            // most often a keyed provider URL written without its scheme, and the
+            // key is in its path — the rule vetEndpoint keeps for rpcUrl.
+            throw new RpcEndpointError(`tool_config.chainread.allowed_origins[${i}] is not an origin — ${/^[a-z][a-z0-9+.-]*:\/\//i.test(o)
+                ? "check the host and the port"
+                : "it must start with https:// (or http://)"}. Write it as https://host[:port]; the value is not repeated here, because a provider keeps its key in the path.`);
+        }
+        if (url.protocol !== "https:" && url.protocol !== "http:") {
+            throw new RpcEndpointError(`tool_config.chainread.allowed_origins has "${url.protocol}//${url.host}", which is not http(s). Write it as https://host[:port].`);
+        }
+        return url.origin;
+    });
+    return origins;
+}
 /** Read the policy back — for `EvmRpcHealth`, which reports the posture it is operating under. */
 export function getRpcEndpointPolicy() {
     return policy;
@@ -257,13 +329,18 @@ export function isPrivateIp(address) {
  * the reason in the message, because every one of these is a refusal a model
  * should read and act on rather than retry.
  */
-export async function vetEndpoint(rawUrl) {
+export async function vetEndpoint(rawUrl, narrowTo) {
     let url;
     try {
         url = new URL(rawUrl);
     }
     catch {
-        throw new RpcEndpointError(`"${rawUrl}" is not a URL`);
+        // Nothing of the value is repeated: a provider key lives in the path, and
+        // a URL that fails to parse is most often a keyed URL missing its scheme
+        // (rpc.ts, invariant 3). The hint is read from the shape alone.
+        throw new RpcEndpointError(`rpcUrl is not an absolute URL — ${/^[a-z][a-z0-9+.-]*:\/\//i.test(rawUrl)
+            ? "check the host and the port"
+            : "it must start with https:// (or http://)"}. The value is not repeated here, because a provider keeps its key in the path.`);
     }
     if (url.protocol !== "https:" && url.protocol !== "http:") {
         throw new RpcEndpointError(`refusing scheme "${url.protocol.replace(":", "")}" — an RPC endpoint is http(s); a websocket is a different transport this package does not speak`);
@@ -277,6 +354,9 @@ export async function vetEndpoint(rawUrl) {
     if (allowed !== undefined && !allowed.includes(url.origin)) {
         throw new RpcEndpointError(`refusing "${url.origin}" — the operator's rpc allow-list is ${allowed.length === 0 ? "empty" : allowed.join(", ")}`);
     }
+    if (narrowTo !== undefined && !narrowTo.includes(url.origin)) {
+        throw new RpcEndpointError(`refusing "${url.origin}" — this model's rpc allow-list (its own tool_config block) is ${narrowTo.length === 0 ? "empty" : narrowTo.join(", ")}`);
+    }
     const host = url.hostname.toLowerCase();
     const allowPrivate = policy.allowPrivateHosts === true;
     if (!allowPrivate && (host === "localhost" || host.endsWith(".localhost"))) {

package/dist/lib/rpc.d.ts

@@ -36,6 +36,8 @@ export type RpcClientOptions = {
     readonly signal?: AbortSignal;
     readonly timeoutMs?: number;
     readonly maxBytes?: number;
+    /** A per-call allow-list that narrows the boot one (see `callOrigins`). */
+    readonly allowedOrigins?: ReadonlyArray<string>;
 };
 export type RpcClient = {
     /** Scheme + host + port. Safe to print; the path, which may hold a key, is not. */
@@ -55,6 +57,14 @@ export type RpcClient = {
 export declare function openRpc(rawUrl: string, options?: RpcClientOptions): Promise<RpcClient>;
 /** The longest JSON-RPC error message this package will carry. */
 export declare const MAX_ERROR_MESSAGE_CHARS = 2000;
+/**
+ * Take an endpoint's path and query out of a message this package did not
+ * write — a dialler's error, which may quote the URL it could not reach, the
+ * pinned-IP spelling of it included. The origin is kept (every message here
+ * names it anyway); the path and the query, where a provider keeps its key,
+ * become `<redacted>`.
+ */
+export declare function withoutPath(message: string, url: URL): string;
 /** Turn a failed outcome into the refusal a tool throws, with the reason kept. */
 export declare function failed(outcome: Extract<RpcOutcome, {
     ok: false;

package/dist/lib/rpc.js

@@ -21,6 +21,7 @@
  *      transcript.
  */
 import { assertReadOnlyMethod } from "@crewhaus/chain-adapter-base";
+import { fetchRaw, readResponseBounded } from "@crewhaus/tool-safety/streams";
 import { vetEndpoint } from "./endpoint";
 import { ChainReadError } from "./quantity";
 export const DEFAULT_TIMEOUT_MS = 20_000;
@@ -46,8 +47,13 @@ const pinnedFetch = async (req, pinnedIp) => {
     const original = new URL(req.url);
     const host = original.hostname;
     const unbracketed = host.replace(/^\[/, "").replace(/\]$/, "");
+    // Both branches keep the body RAW (`fetchRaw`, Bun's `decompress: false`):
+    // otherwise Bun inflates a gzip, deflate, br or zstd reply in native code
+    // before any reader sees a byte, and a 260 KB gzip of zeros cost about
+    // 1 GB of RSS before `maxBytes` fired (C093). `readCapped` decodes it,
+    // under the cap.
     if (pinnedIp === "" || unbracketed === pinnedIp)
-        return globalThis.fetch(req);
+        return fetchRaw(req);
     const pinnedUrl = new URL(original.toString());
     pinnedUrl.hostname = pinnedIp.includes(":") ? `[${pinnedIp}]` : pinnedIp;
     const headers = new Headers(req.headers);
@@ -64,7 +70,7 @@ const pinnedFetch = async (req, pinnedIp) => {
         redirect: "manual",
         tls: { serverName: host },
     };
-    return globalThis.fetch(pinnedUrl.toString(), init);
+    return fetchRaw(pinnedUrl.toString(), init);
 };
 let rpcFetch = pinnedFetch;
 /**
@@ -84,7 +90,7 @@ export function _setFetch(fn) {
  * mid-scan, which is precisely the rebinding the pin defends against.
  */
 export async function openRpc(rawUrl, options = {}) {
-    const endpoint = await vetEndpoint(rawUrl);
+    const endpoint = await vetEndpoint(rawUrl, options.allowedOrigins);
     return clientFor(endpoint, options);
 }
 function clientFor(endpoint, options) {
@@ -160,7 +166,9 @@ async function request(endpoint, spec) {
             return {
                 ok: false,
                 kind: "transport",
-                message: `could not reach ${origin}: ${error?.message ?? String(err)}`,
+                // The dialler's message is somebody else's string, and one that
+                // quotes the URL it could not reach quotes the key in its path.
+                message: `could not reach ${origin}: ${withoutPath(error?.message ?? String(err), endpoint.url)}`,
             };
         }
         // A redirect is not followed. An RPC endpoint that 302s is either
@@ -176,9 +184,16 @@ async function request(endpoint, spec) {
         }
         let text;
         try {
-            text = await readCapped(res, spec.maxBytes);
+            text = await readCapped(res, spec.maxBytes, timer.signal);
         }
         catch (err) {
+            if (err instanceof BodyUnreadable) {
+                return {
+                    ok: false,
+                    kind: "malformed",
+                    message: `${origin} answered ${spec.method} with a body that ${err.message}`,
+                };
+            }
             if (err instanceof BodyTooLarge) {
                 return {
                     ok: false,
@@ -264,45 +279,38 @@ async function request(endpoint, spec) {
 }
 class BodyTooLarge extends Error {
 }
+class BodyUnreadable extends Error {
+}
 /**
- * Read a body with a ceiling, WHILE reading.
+ * Read a body with a ceiling on its DECODED size, 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.
+ * which is no ceiling at all against an endpoint that streams — and a
+ * compressed body is inflated by the runtime before any reader sees it, so
+ * it arrives raw (see `pinnedFetch`) and is decoded here, with the decoder
+ * stopped at the cap. 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);
-        }
+async function readCapped(res, maxBytes, signal) {
+    const read = await readResponseBounded(res, { maxBytes, signal });
+    if (read.ok) {
+        if (read.truncated)
+            throw new BodyTooLarge();
+        return read.text;
     }
-    finally {
-        reader.releaseLock();
-    }
-    const joined = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        joined.set(chunk, offset);
-        offset += chunk.byteLength;
+    switch (read.code) {
+        case "unsupported-encoding":
+            throw new BodyUnreadable("uses a stack of content-encodings this package cannot decode within its cap");
+        case "decode-error":
+        case "auto-decompressed":
+            throw new BodyUnreadable("is labelled as compressed but could not be decoded");
+        default:
+            // Aborted, stalled, or the connection closed: the caller reports these
+            // as the transport failures they are.
+            throw new Error(read.reason);
     }
-    return new TextDecoder().decode(joined);
 }
 /** The longest JSON-RPC error message this package will carry. */
 export const MAX_ERROR_MESSAGE_CHARS = 2_000;
@@ -316,6 +324,26 @@ function snippet(text) {
     const flat = text.replace(/\s+/g, " ").trim();
     return flat.length > 200 ? `${flat.slice(0, 200)}…` : flat;
 }
+/**
+ * Take an endpoint's path and query out of a message this package did not
+ * write — a dialler's error, which may quote the URL it could not reach, the
+ * pinned-IP spelling of it included. The origin is kept (every message here
+ * names it anyway); the path and the query, where a provider keeps its key,
+ * become `<redacted>`.
+ */
+export function withoutPath(message, url) {
+    let out = message.split(url.href).join(url.origin);
+    const pieces = [
+        [`${url.pathname}${url.search}`, "/<redacted>"],
+        [url.pathname, "/<redacted>"],
+        [url.search, "?<redacted>"],
+    ];
+    for (const [piece, mask] of pieces) {
+        if (piece.length > 1)
+            out = out.split(piece).join(mask);
+    }
+    return out;
+}
 /** 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})`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-chainread",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "Deterministic EVM chain reads over a public RPC: blocks, transactions, receipts, logs, nonces, and an address's history as reconciler rows",
   "main": "dist/index.js",
@@ -8,19 +8,21 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/chain-adapter-base": "0.7.0",
-    "@crewhaus/errors": "0.7.0",
-    "@crewhaus/tool-builder": "0.7.0",
-    "@crewhaus/tool-catalog": "0.7.0",
-    "@crewhaus/tool-money": "0.7.0",
-    "@crewhaus/tool-onchain": "0.7.0",
+    "@crewhaus/chain-adapter-base": "0.8.1",
+    "@crewhaus/errors": "0.8.1",
+    "@crewhaus/tool-builder": "0.8.1",
+    "@crewhaus/tool-catalog": "0.8.1",
+    "@crewhaus/tool-money": "0.8.1",
+    "@crewhaus/tool-onchain": "0.8.1",
+    "@crewhaus/tool-safety": "0.8.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -44,5 +46,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
 }

package/dist/fixtures.d.ts

@@ -1,123 +0,0 @@
-/**
- * A recorded chain, and an RPC endpoint that serves it.
- *
- * No test in this package opens a socket. The stub below answers the ten
- * JSON-RPC methods these tools use, from data built here, and its knobs are the
- * ways a real public endpoint misbehaves: a block-span cap that errors with a
- * suggested range, a result cap that errors, a result cap that SILENTLY
- * truncates, a pruned archive, a mempool the endpoint cannot see, and an HTTP
- * layer that rate-limits. Those knobs are the fixtures that matter — the happy
- * path is the easy half.
- *
- * Every request is recorded in `requests`, so a test can assert what a tool
- * actually asked for: that a scan halved its range, that a search spent the
- * probes it claimed, that a poll stopped when it said it did.
- */
-import type { RpcFetch } from "./lib/rpc";
-/** A deterministic 32-byte hash from a label, so fixtures are readable in a diff. */
-export declare function hash32(label: string): string;
-/** A deterministic 20-byte address from a label. */
-export declare function address20(label: string): string;
-export declare const TOKEN: string;
-export declare const ALICE: string;
-export declare const BOB: string;
-export declare const ROUTER: string;
-export declare const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
-export declare const APPROVAL_TOPIC = "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925";
-export declare function topicFor(address: string): string;
-export declare function word(value: bigint): string;
-export type FixtureBlock = {
-    readonly number: bigint;
-    readonly timestamp: bigint;
-    readonly hash: string;
-    readonly baseFeePerGas: bigint | null;
-};
-export type FixtureLog = {
-    readonly blockNumber: bigint;
-    readonly logIndex: number;
-    readonly address: string;
-    readonly topics: ReadonlyArray<string>;
-    readonly data: string;
-    readonly transactionHash: string;
-};
-export type FixtureTx = {
-    readonly hash: string;
-    readonly from: string;
-    readonly to: string | null;
-    readonly value: bigint;
-    readonly nonce: bigint;
-    readonly input: string;
-    readonly blockNumber: bigint | null;
-};
-export type FixtureReceipt = {
-    readonly hash: string;
-    readonly blockNumber: bigint;
-    readonly status: "0x1" | "0x0" | null;
-    readonly gasUsed: bigint;
-    readonly effectiveGasPrice: bigint | null;
-    readonly l1Fee?: bigint;
-    readonly gasUsedForL1?: bigint;
-    readonly root?: string;
-    /** Set only by a contract creation, which is the one case a transaction has no `to`. */
-    readonly contractAddress?: string;
-    /** The transaction's place in its block, as the chain numbers it. Default 0. */
-    readonly transactionIndex?: number;
-    readonly logs: ReadonlyArray<FixtureLog>;
-};
-export type Chain = {
-    readonly chainId: bigint;
-    blocks: FixtureBlock[];
-    logs: FixtureLog[];
-    txs: Map<string, FixtureTx>;
-    receipts: Map<string, FixtureReceipt>;
-    /** address → { latest, pending } nonce. */
-    nonces: Map<string, {
-        latest: bigint;
-        pending: bigint;
-    }>;
-    head: bigint;
-    /** Tagged blocks the chain serves; a chain that serves neither is the pre-Merge case. */
-    safe: bigint | null;
-    finalized: bigint | null;
-};
-export type ChainOptions = {
-    readonly chainId?: bigint;
-    readonly blocks?: number;
-    readonly startTimestamp?: bigint;
-    readonly blockTime?: bigint;
-    readonly baseFee?: bigint | null;
-};
-export declare function makeChain(options?: ChainOptions): Chain;
-/** Add `count` ERC-20 Transfer logs to one block, from ALICE to BOB. */
-export declare function addTransferLogs(chain: Chain, blockNumber: bigint, count: number, token?: string): void;
-export declare function blockOf(chain: Chain, number: bigint): FixtureBlock | undefined;
-export type StubOptions = {
-    /** Error when a getLogs span exceeds this, naming a range that would have worked. */
-    readonly maxRangeBlocks?: bigint;
-    /** Error when more than this many logs match — the "query returned more than N results" family. */
-    readonly maxResults?: number;
-    /** Return the first N matches and say nothing. This is the one that needs catching. */
-    readonly silentLogCap?: number;
-    /** `no` prunes historic state; `error` fails the probe for an unrelated reason. */
-    readonly archive?: "yes" | "no" | "error";
-    /** When false, the pending nonce equals the latest one however full the mempool is. */
-    readonly mempoolAware?: boolean;
-    /** Answer every request with this HTTP status instead. */
-    readonly httpStatus?: number;
-    /** Throw from the dialer, as an unreachable host does. */
-    readonly unreachable?: boolean;
-    /** Serve neither `safe` nor `finalized`, as a pre-Merge or minimal endpoint does. */
-    readonly noFinalityTags?: boolean;
-};
-export type RpcStub = {
-    readonly fetch: RpcFetch;
-    /** Every request, in order: `{ method, params }`. */
-    readonly requests: Array<{
-        readonly method: string;
-        readonly params: ReadonlyArray<unknown>;
-    }>;
-    /** Requests for one method, for the assertions that count probes or polls. */
-    count(method: string): number;
-};
-/** Build an endpoint that serves `chain`, misbehaving in whatever way `options` says. */
-export declare function rpcStub(chain: Chain, options?: StubOptions): RpcStub;

package/dist/fixtures.js

@@ -1,309 +0,0 @@
-/** 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());
-    });
-}