@crewhaus/tool-token 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

@@ -116,6 +116,16 @@ own `getEthBalance` to stay in that snapshot. `batch: false` reads them
 one at a time for chains with no Multicall3 deployment, and says in the answer
 that the result is not a snapshot.
 
+**Which Multicall3 is the operator's choice.** A batch is one `eth_call`, and
+every answer in it — decimals, balances, the block number — is whatever that
+contract returns, so a contract that fakes `aggregate3` can make a decimals
+mismatch read as verified. Batches go to the canonical deployment
+(`0xcA11bde05977b3631167028862bE2a173976CA11`) unless `tool_config.token.multicall3`
+names another for the chain; a call's `multicall3Address` is accepted only when
+it is that same address, and anything else is refused before any read. Every
+batched answer says who served it: `aggregator: { address, source }`, with
+`source` either `canonical` or `config`.
+
 A sub-call inside that batch is a contract call like any other, and one that
 does not answer is **not a zero**. A `getEthBalance` that came back empty —
 an aggregator without the helper, a sub-call out of gas — is reported as
@@ -136,7 +146,34 @@ not promised by this paragraph.
 ## No dialling code at all
 
 There is no RPC client and no HTTP client in this package. Both boundaries are
-injected:
+injected, and a compiled bundle, `crewhaus run` and `crewhaus eval` bind them at
+boot from the spec:
+
+```yaml
+chains:                              # the chain reader
+  - id: "1"
+    kind: evm
+    rpcUrls: [$ETH_RPC_URL]          # read from the environment, never compiled in
+    finality: { kind: finalized }
+
+tool_config:
+  token:
+    metadata_origins: [https://ipfs.io]   # the only origins a tokenURI is read from
+    multicall3:                           # only where the canonical deployment is absent
+      "324": "0xF9cda624FBC7e059355ce98a31693d299FACd963"
+```
+
+Without a `chains` block, a chain read refuses and names the block to write.
+These tools name a chain by its EIP-155 id, so declare it under that id in
+decimal (`id: "1"`, `id: "8453"`); a chain declared as `mainnet` is refused
+with the ids the spec does declare.
+Without `metadata_origins`, metadata is not fetched, and the answer says why.
+The metadata fetch goes through `@crewhaus/tool-http`'s gate: https only, the
+SSRF refusal, no redirects, a byte cap. The caller's own `allowedHosts` and
+`ipfsGateway` still decide what is attempted; this list decides what can be
+dialled, and a model cannot widen it.
+
+A host that builds its own wiring can still call the seams directly:
 
 ```ts
 import { _setChainReader, chainReaderFromAdapters, _setMetadataFetch } from "@crewhaus/tool-token";
@@ -168,5 +205,6 @@ A tool that cannot say no is not finished. These say no, with the reason:
 - an `ipfs://` URI that resolves outside the gateway it was given
 - an `https://` metadata host nobody allow-listed, and any `http://` URI
 - a metadata document over the byte cap — refused rather than parsed as a prefix
+- a `multicall3Address` other than the canonical deployment or the one the operator configured
 - a Multicall3 address that answers with something other than results
 - a block tag that is not one, and a token id that is not a `uint256`

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import type { RegisteredTool } from "@crewhaus/tool-catalog";
 export { type ChainRead, type ChainReadMethod, type ChainReader, READ_METHODS, TokenError, _setChainReader, chainReaderFromAdapters, hasChainReader, } from "./lib/chain";
+export { type Aggregator, type TokenConfigInput, bindTokenChains, registerTokenConfig, } from "./lib/boot";
 export { type MetadataFetch, type MetadataResponse, type UriPlan, DEFAULT_MAX_METADATA_BYTES, _setMetadataFetch, planUri, } from "./lib/uri";
 export { type Candidate, type TokenList, type TokenListEntry, confusableSkeleton, findCandidates, textConcerns, } from "./lib/lists";
 export declare const tokenResolve: RegisteredTool;

package/dist/index.js

@@ -30,20 +30,25 @@
  *
  * There is no RPC client and no HTTP client in this package. Chain reads
  * leave through `_setChainReader` and metadata fetches through
- * `_setMetadataFetch`; the runtime binds both at boot and every test drives
+ * `_setMetadataFetch`. A bundle binds them at boot from the spec —
+ * `bindTokenChains` from its `chains` block, `registerTokenConfig` from
+ * `tool_config.token.metadata_origins` (`lib/boot.ts`) — and every test drives
  * them from recorded answers, so the suite cannot reach the network even by
  * accident.
  */
 import { createHash } from "node:crypto";
+import { CHAINS_BLOCK_EXAMPLE } from "@crewhaus/chain-adapter-base";
 import { buildTool } from "@crewhaus/tool-builder";
 import { MULTICALL3_ADDRESS } from "@crewhaus/tool-onchain";
 import { z } from "zod";
+import { resolveAggregator } from "./lib/boot";
 import { TokenError, hasChainReader, nativeBalanceCall, readCalls, readHasCode, readNativeBalance, } from "./lib/chain";
 import { INTERFACE_ID, SELECTOR, addressWord, bytes4Word, callData, decodeAddressValue, decodeBool, decodeStringish, decodeUint, padTokenIdHex, uintWord, } from "./lib/erc";
 import { ADDRESS_SHAPE, confusableSkeleton, findCandidates, fingerprintLists, textConcerns, } from "./lib/lists";
 import { MAX_FORMATTABLE_DECIMALS, checkAddress, formatUnits } from "./lib/onchain";
 import { DEFAULT_MAX_METADATA_BYTES, decodeDataUri, fetchDocument, planUri, referencedUrls, } from "./lib/uri";
 export { READ_METHODS, TokenError, _setChainReader, chainReaderFromAdapters, hasChainReader, } from "./lib/chain";
+export { bindTokenChains, registerTokenConfig, } from "./lib/boot";
 export { DEFAULT_MAX_METADATA_BYTES, _setMetadataFetch, planUri, } from "./lib/uri";
 export { confusableSkeleton, findCandidates, textConcerns, } from "./lib/lists";
 const json = (value) => JSON.stringify(value);
@@ -69,7 +74,7 @@ const batchField = z
 const multicallField = z
     .string()
     .optional()
-    .describe(`Multicall3's address on this chain; default ${MULTICALL3_ADDRESS}`);
+    .describe(`leave it out: batches go to the canonical Multicall3 (${MULTICALL3_ADDRESS}) or the one the operator configured for the chain, and any other address is refused`);
 // ---------------------------------------------------------------------------
 // shared helpers
 // ---------------------------------------------------------------------------
@@ -298,6 +303,7 @@ const CONCERNING_FLAGS = new Set([
 ]);
 export const tokenResolve = buildTool({
     name: "TokenResolve",
+    operativeArgs: [{ field: "query", kind: "text", within: "chainId" }],
     description: "Turn a token symbol, name or address into ONE checksummed address, confirmed against the contract itself — or refuse and show you why. Use it before any transfer, balance read or approval, because a symbol is not an identifier: nothing stops a second contract calling itself USDC with six decimals and a convincing name, and reputable token lists carry different addresses for the same ticker. When a query could mean more than one address this returns EVERY candidate with resolved:false rather than the first hit or a most-likely, because picking between them is a decision with a wrong answer that costs money. Symbols that differ only by a Cyrillic lookalike or a zero-width space are pulled into the same candidate set on purpose, so an impostor a literal match would miss becomes an ambiguity you have to look at. The contract's own decimals and symbol are compared against what the lists claim, and a decimals mismatch is a refusal rather than a footnote.",
     inputSchema: z
         .object({
@@ -342,7 +348,7 @@ export const tokenResolve = buildTool({
     // through whatever the runtime bound to the seam.
     scope: "external",
     ioCapability: "network",
-    execute: async (input) => {
+    execute: async (input, ctx) => {
         const query = input.query.trim();
         const lists = (input.lists ?? []);
         const policy = input.policy ?? "listed-only";
@@ -413,12 +419,17 @@ export const tokenResolve = buildTool({
         const wantsOnchain = input.confirmOnchain ?? true;
         if (wantsOnchain && !hasChainReader()) {
             if (input.confirmOnchain === true) {
-                throw new TokenError("confirmOnchain was asked for but no chain reader is bound; bind one with _setChainReader() or pass confirmOnchain:false to answer from the lists alone");
+                throw new TokenError(`confirmOnchain was asked for but no chain is configured. Declare one in the spec — ${CHAINS_BLOCK_EXAMPLE} — or pass confirmOnchain:false to answer from the lists alone`);
             }
         }
         const confirm = wantsOnchain && hasChainReader();
         const facts = new Map();
         let blockNumber = null;
+        // Resolved before any read: an aggregator the operator did not name is
+        // refused, not asked.
+        const aggregator = confirm && (input.batch ?? true)
+            ? resolveAggregator(input.chainId, input.multicall3Address, ctx?.toolConfig)
+            : null;
         if (confirm) {
             const calls = [];
             for (const [i, candidate] of candidates.entries()) {
@@ -428,10 +439,8 @@ export const tokenResolve = buildTool({
                 chainId: input.chainId,
                 calls,
                 blockTag,
-                batch: input.batch ?? true,
-                ...(input.multicall3Address !== undefined
-                    ? { multicall3Address: input.multicall3Address }
-                    : {}),
+                batch: aggregator !== null,
+                ...(aggregator !== null ? { multicall3Address: aggregator.address } : {}),
             });
             blockNumber = read.blockNumber;
             for (const [i, candidate] of candidates.entries()) {
@@ -453,7 +462,14 @@ export const tokenResolve = buildTool({
                 flags: flagsFor(candidate, onchain),
             });
         }
-        const shared = { ...base, blockNumber, confirmedOnchain: confirm, candidates: flagged };
+        const shared = {
+            ...base,
+            blockNumber,
+            confirmedOnchain: confirm,
+            // Who answered the batched reads, since every one of them is its word.
+            aggregator,
+            candidates: flagged,
+        };
         if (flagged.length > 1) {
             return json({
                 ...shared,
@@ -521,6 +537,7 @@ export const tokenResolve = buildTool({
 // ---------------------------------------------------------------------------
 export const erc20Balance = buildTool({
     name: "Erc20Balance",
+    operativeArgs: [{ field: "token", kind: "id", within: "chainId" }],
     description: "Read ERC-20 balances, and optionally an allowance, for one or many accounts at one block — with the token's decimals taken from the CONTRACT, never from a list and never defaulted. Use it instead of a raw eth_call: every amount comes back both as exact base units and as a decimal string, so a uint256 never becomes a JS number and eighteen digits of precision never quietly become fifteen. A token whose decimals() reverts is reported as unknown and its balances stay in base units rather than being scaled by an assumed 18, which is how a six-decimal transfer becomes a trillion-fold one. Tokens that answer symbol() with a bytes32 instead of a string — MKR and other 2017-era contracts — are decoded rather than crashed on, and an address with no code at it is refused instead of reporting everyone's balance as zero. Pass \"native\" as the token to read the chain's own currency in the same snapshot. It takes a contract ADDRESS, not a symbol: use TokenResolve first.",
     inputSchema: z
         .object({
@@ -551,10 +568,13 @@ export const erc20Balance = buildTool({
     concurrencySafe: true,
     scope: "external",
     ioCapability: "network",
-    execute: async (input) => {
+    execute: async (input, ctx) => {
         const blockTag = input.blockTag ?? "latest";
         const batch = input.batch ?? true;
-        const multicall = input.multicall3Address ?? MULTICALL3_ADDRESS;
+        const aggregator = batch
+            ? resolveAggregator(input.chainId, input.multicall3Address, ctx?.toolConfig)
+            : null;
+        const multicall = aggregator?.address ?? MULTICALL3_ADDRESS;
         const isNative = input.token.trim().toLowerCase() === "native";
         if (!isNative && !ADDRESS_SHAPE.test(input.token.trim())) {
             throw new TokenError(`Erc20Balance takes a token contract address, not "${input.token}". A symbol is not an identifier — several contracts can claim the same one — so resolve it with TokenResolve first, which returns every candidate when a symbol is ambiguous rather than picking one.`);
@@ -627,6 +647,7 @@ export const erc20Balance = buildTool({
                 blockTag,
                 blockNumber,
                 batched: batch,
+                aggregator,
                 token: { kind: "native", address: null, decimals },
                 balances,
                 warnings,
@@ -701,6 +722,7 @@ export const erc20Balance = buildTool({
             blockTag,
             blockNumber: read.blockNumber,
             batched: read.batched,
+            aggregator,
             token: {
                 kind: "erc20",
                 address: token,
@@ -728,6 +750,10 @@ const INTERFACE_KEYS = {
 };
 export const erc721TokenInfo = buildTool({
     name: "Erc721TokenInfo",
+    operativeArgs: [
+        { field: "contract", kind: "id", within: "chainId" },
+        { field: "ipfsGateway", kind: "url" },
+    ],
     description: "Read one NFT: which standard the contract actually implements, the collection's name and symbol, who owns the token (or an ERC-1155 holder's balance of it), and its tokenURI. Use it to check what an NFT is before buying, listing or transferring it. Metadata is read ONLY when it costs no trust: a data: URI is decoded in-process, an ipfs: URI is fetched through a gateway YOU named, and an https: URI only from a host YOU allow-listed — a URL that came out of contract data is not a reason to dial it, and following one is a server-side request forgery with extra steps. The answer lists every URI it read and every one it skipped, with the reason. ERC-1155's {id} placeholder is substituted with the 64-hex-digit zero-padded form the spec requires and almost everyone gets wrong, ERC-1155 has no ownerOf so ownership is answered as a balance or not at all rather than as a misleading null, and a contract that claims to support the invalid interface id is reported as one whose supportsInterface answers mean nothing.",
     inputSchema: z
         .object({
@@ -792,6 +818,9 @@ export const erc721TokenInfo = buildTool({
         catch {
             throw new TokenError(`"${input.tokenId}" is not a token id; give a decimal or 0x hex uint256 as a string`);
         }
+        const aggregator = (input.batch ?? true)
+            ? resolveAggregator(input.chainId, input.multicall3Address, ctx?.toolConfig)
+            : null;
         const code = (input.checkCode ?? true) ? await readHasCode(input.chainId, contract, blockTag) : null;
         if (code !== null && !code.hasCode) {
             throw new TokenError(`there is no contract at ${contract} at block ${blockTag} — every call to it answers 0x, so an NFT read against it would report no owner and no URI rather than saying this is not a contract`);
@@ -826,10 +855,8 @@ export const erc721TokenInfo = buildTool({
             chainId: input.chainId,
             calls,
             blockTag,
-            batch: input.batch ?? true,
-            ...(input.multicall3Address !== undefined
-                ? { multicall3Address: input.multicall3Address }
-                : {}),
+            batch: aggregator !== null,
+            ...(aggregator !== null ? { multicall3Address: aggregator.address } : {}),
         });
         const says = (key) => {
             const outcome = read.outcomes.get(key);
@@ -1013,6 +1040,7 @@ export const erc721TokenInfo = buildTool({
             blockTag,
             blockNumber: read.blockNumber,
             batched: read.batched,
+            aggregator,
             standard,
             standardSource,
             interfaces,

package/dist/lib/boot.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The two boot bindings this package's seams get in a compiled bundle,
+ * `crewhaus run` and `crewhaus eval` — each from a spec block, each failing
+ * closed without one.
+ *
+ *   - {@link bindTokenChains}: the chain reader, from the spec's `chains`
+ *     block, through the same adapters `tool-evm` reads with.
+ *   - {@link registerTokenConfig}: the metadata fetcher, from
+ *     `tool_config.token.metadata_origins`, the operator's list of origins a
+ *     contract's `tokenURI` may be read from. The caller's own `allowedHosts`
+ *     and `ipfsGateway` still decide what is attempted; this list decides
+ *     what can be dialled, and a model cannot widen it. And the Multicall3
+ *     deployments in `tool_config.token.multicall3`, below.
+ *
+ * Still no dialling code here: the fetch goes through `@crewhaus/tool-http`'s
+ * gate (allow-list, SSRF, no redirects, byte cap), and the chain read through
+ * the adapter.
+ */
+import type { ChainAdapterConfig } from "@crewhaus/chain-adapter-base";
+/** Bind the chain reader from the spec's `chains` block. */
+export declare function bindTokenChains(config: {
+    readonly chains: ReadonlyArray<ChainAdapterConfig>;
+}): void;
+/** The spec's `tool_config.token` block. */
+export type TokenConfigInput = {
+    readonly metadata_origins?: ReadonlyArray<string>;
+    readonly metadataOrigins?: ReadonlyArray<string>;
+    /** chain id → the Multicall3 deployment batches on that chain go to. */
+    readonly multicall3?: Readonly<Record<string, string>>;
+};
+/**
+ * Apply `tool_config.token`: the Multicall3 deployments in `multicall3`, and
+ * the metadata fetcher from `metadata_origins`. Only https origins are
+ * accepted: a metadata document read over plain http is whatever the network
+ * says it is. A block without the list binds no fetcher.
+ */
+export declare function registerTokenConfig(input: TokenConfigInput): void;
+/**
+ * Which contract answers a batched read — decided by the operator, never by
+ * a call.
+ *
+ * A batch is ONE `eth_call` to Multicall3, and every sub-result — decimals,
+ * symbol, balances, allowances, `ownerOf`, the block number — is whatever
+ * that contract returns. Any contract can implement `aggregate3` and return
+ * rows it made up. So a model-supplied aggregator address was a way to make
+ * TokenResolve report a decimals mismatch as `verified: true`, and
+ * Erc20Balance report balances nobody holds.
+ *
+ * The aggregator is the canonical deployment unless the operator names
+ * another for that chain in `tool_config.token.multicall3` (a chain whose
+ * Multicall3 is elsewhere, such as zkSync Era). A call may still pass
+ * `multicall3Address`, which older callers do, but only the address that
+ * would be used anyway is accepted; anything else is refused before a read.
+ */
+/** Who served a batch, as every batched answer reports it. */
+export type Aggregator = {
+    /** EIP-55. */
+    readonly address: string;
+    /** `canonical`: the deterministic deploy. `config`: the operator's tool_config. */
+    readonly source: "canonical" | "config";
+};
+/**
+ * The aggregator a batch on `chainId` goes to, and where that came from. A
+ * `requested` address other than that one is refused: which contract answers
+ * every read is not a per-call choice.
+ */
+export declare function resolveAggregator(chainId: number, requested: string | undefined, toolConfig: unknown): Aggregator;

package/dist/lib/boot.js

@@ -0,0 +1,97 @@
+import { createEvmAdapters } from "@crewhaus/chain-adapter-evm";
+import { guardedGet } from "@crewhaus/tool-http";
+import { MULTICALL3_ADDRESS, parseMulticallMap } from "@crewhaus/tool-onchain";
+import { TokenError, _setChainReader, chainReaderFromAdapters } from "./chain";
+import { _setMetadataFetch } from "./uri";
+/**
+ * The operator's Multicall3 deployments by chain id, from
+ * `tool_config.token.multicall3`. Only {@link registerTokenConfig} writes it.
+ */
+let configured = new Map();
+/** A metadata document is small; a slow host should not hold a call open for long. */
+const METADATA_TIMEOUT_MS = 10_000;
+/** Bind the chain reader from the spec's `chains` block. */
+export function bindTokenChains(config) {
+    const adapters = createEvmAdapters(config.chains);
+    _setChainReader(chainReaderFromAdapters((chainId) => adapters.get(chainId), [...adapters.keys()]));
+}
+/**
+ * Apply `tool_config.token`: the Multicall3 deployments in `multicall3`, and
+ * the metadata fetcher from `metadata_origins`. Only https origins are
+ * accepted: a metadata document read over plain http is whatever the network
+ * says it is. A block without the list binds no fetcher.
+ */
+export function registerTokenConfig(input) {
+    const block = (input ?? {});
+    configured = parseTokenMulticall(block["multicall3"]);
+    if (Object.hasOwn(block, "metadata_origins") && Object.hasOwn(block, "metadataOrigins")) {
+        throw new TokenError("tool_config.token sets both metadata_origins and metadataOrigins. Write the list once, as metadata_origins.");
+    }
+    const raw = block["metadata_origins"] ?? block["metadataOrigins"];
+    if (raw === undefined)
+        return;
+    if (!Array.isArray(raw) || raw.some((o) => typeof o !== "string")) {
+        throw new TokenError('tool_config.token.metadata_origins must be a list of https origins, for example ["https://ipfs.io"].');
+    }
+    const origins = [];
+    for (const origin of raw) {
+        let url;
+        try {
+            url = new URL(origin);
+        }
+        catch {
+            throw new TokenError(`tool_config.token.metadata_origins has "${origin}", which is not an origin. Write it as https://host.`);
+        }
+        if (url.protocol !== "https:") {
+            throw new TokenError(`tool_config.token.metadata_origins has "${url.protocol}//${url.host}", which is not https. Metadata is read over https only.`);
+        }
+        origins.push(url.origin);
+    }
+    _setMetadataFetch(async ({ url, maxBytes, signal }) => {
+        // One byte over the cap, so a document that fills it exactly is told
+        // apart from one that was cut — `fetchDocument` refuses the latter.
+        const got = await guardedGet(url, {
+            allowedOrigins: origins,
+            maxBytes: maxBytes + 1,
+            timeoutMs: METADATA_TIMEOUT_MS,
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        return { status: got.status, contentType: got.contentType, bytes: got.bytes };
+    });
+}
+/** Parse `tool_config.token.multicall3`, refusing a malformed entry by its key. */
+function parseTokenMulticall(input) {
+    try {
+        return parseMulticallMap(input, "tool_config.token.multicall3");
+    }
+    catch (err) {
+        throw new TokenError(err.message);
+    }
+}
+/**
+ * The map one call runs under: the serving candidate's own `tool_config`
+ * block when it has one (it replaces the boot registration, as every
+ * tool_config block does), else the boot registration.
+ */
+function mapFor(toolConfig) {
+    if (typeof toolConfig === "object" && toolConfig !== null && !Array.isArray(toolConfig)) {
+        return parseTokenMulticall(toolConfig["multicall3"]);
+    }
+    return configured;
+}
+/**
+ * The aggregator a batch on `chainId` goes to, and where that came from. A
+ * `requested` address other than that one is refused: which contract answers
+ * every read is not a per-call choice.
+ */
+export function resolveAggregator(chainId, requested, toolConfig) {
+    const override = mapFor(toolConfig).get(String(chainId));
+    const aggregator = override === undefined
+        ? { address: MULTICALL3_ADDRESS, source: "canonical" }
+        : { address: override, source: "config" };
+    if (requested !== undefined &&
+        requested.trim().toLowerCase() !== aggregator.address.toLowerCase()) {
+        throw new TokenError(`multicall3Address ${JSON.stringify(requested.slice(0, 64))} is not the Multicall3 chain ${chainId} reads through (${aggregator.address}). The aggregator answers every read in a batch — decimals, balances, the block number — so which contract that is belongs to the operator: name it in tool_config.token.multicall3 for chain ${chainId}. Or pass batch:false to read each call directly.`);
+    }
+    return aggregator;
+}

package/dist/lib/chain.d.ts

@@ -22,7 +22,7 @@
  * blocks. `getBlockNumber()` rides along in the same batch so the answer says
  * which block it is a snapshot of.
  */
-import type { ChainAdapter } from "@crewhaus/chain-adapter-base";
+import { type ChainAdapter } from "@crewhaus/chain-adapter-base";
 import { CrewhausError } from "@crewhaus/errors";
 import { type RevertReason } from "@crewhaus/tool-onchain";
 /** A refusal this package makes: a bad input, a missing seam, an unreadable answer. */
@@ -59,7 +59,7 @@ export declare function assertReadMethod(method: string): asserts method is Chai
  * bundle has. The adapter applies its own read-only allowlist underneath, so
  * a write method would be refused twice.
  */
-export declare function chainReaderFromAdapters(resolve: (chainId: string) => ChainAdapter | undefined): ChainReader;
+export declare function chainReaderFromAdapters(resolve: (chainId: string) => ChainAdapter | undefined, declared?: ReadonlyArray<string>): ChainReader;
 /** One call in a read, keyed so results are never matched up by position here. */
 export type BatchCall = {
     /** The caller's own label. Results come back in a map under it. */

package/dist/lib/chain.js

@@ -1,3 +1,28 @@
+/**
+ * The one way this package learns anything from a chain — and the reason it
+ * is the only way.
+ *
+ * **There is no dialling code in `@crewhaus/tool-token`.** No URL, no fetch,
+ * no socket. Every chain read leaves through `_setChainReader`, which the
+ * runtime binds at boot and every test in this package drives from recorded
+ * answers. Two things follow, and both are the point:
+ *
+ *   1. A test cannot reach a public RPC endpoint even by accident. There is
+ *      nothing under the seam to reach it with. A suite that dialled a real
+ *      node would fail on a CI runner with no egress and flake on somebody
+ *      else's rate limit.
+ *   2. The set of JSON-RPC methods this package can emit is three, they are
+ *      listed below, and {@link assertReadMethod} refuses anything else
+ *      before it reaches the reader. `eth_sendTransaction` and
+ *      `eth_sendRawTransaction` are not reachable from any code path here;
+ *      `index.test.ts` asserts it.
+ *
+ * Reads are batched through Multicall3 by default, because a hundred balances
+ * read one at a time are a hundred balances from up to a hundred different
+ * blocks. `getBlockNumber()` rides along in the same batch so the answer says
+ * which block it is a snapshot of.
+ */
+import { CHAINS_BLOCK_EXAMPLE } from "@crewhaus/chain-adapter-base";
 import { CrewhausError } from "@crewhaus/errors";
 import { MULTICALL3_ADDRESS, decodeAggregate3, encodeAggregate3, } from "@crewhaus/tool-onchain";
 import { SELECTOR, addressWord, callData, decodeUint } from "./erc";
@@ -15,7 +40,7 @@ export class TokenError extends CrewhausError {
  */
 export const READ_METHODS = Object.freeze(["eth_call", "eth_getBalance", "eth_getCode"]);
 const unbound = async (read) => {
-    throw new TokenError(`no chain reader is bound, so chain ${read.chainId} cannot be read. This package contains no RPC client of its own: the runtime binds one with _setChainReader(), and chainReaderFromAdapters() wires it from the spec's chains[] block in one line.`);
+    throw new TokenError(`no chain is configured, so chain ${read.chainId} cannot be read. Declare it in the spec — ${CHAINS_BLOCK_EXAMPLE}.`);
 };
 let reader = unbound;
 /**
@@ -41,12 +66,18 @@ export function assertReadMethod(method) {
  * bundle has. The adapter applies its own read-only allowlist underneath, so
  * a write method would be refused twice.
  */
-export function chainReaderFromAdapters(resolve) {
+export function chainReaderFromAdapters(resolve, declared) {
     return async (read) => {
         assertReadMethod(read.method);
         const adapter = resolve(String(read.chainId));
         if (adapter === undefined) {
-            throw new TokenError(`no chain adapter is registered for chain ${read.chainId}; declare it in the spec's chains[] block`);
+            // These tools name a chain by its EIP-155 id, and look it up as that
+            // number written in decimal. A chain declared as "mainnet" is there,
+            // just not under the id asked for — so say which ids ARE declared.
+            const known = declared === undefined || declared.length === 0
+                ? ""
+                : ` The spec declares ${declared.map((id) => `"${id}"`).join(", ")}; the token tools look a chain up by its EIP-155 chain id in decimal, so declare it as id: "${read.chainId}".`;
+            throw new TokenError(`no chain is declared with id "${read.chainId}", so chain ${read.chainId} cannot be read.${known === "" ? " Declare it in the spec's chains[] block." : known}`);
         }
         return adapter.rpcRead(read.method, read.params);
     };
@@ -143,7 +174,7 @@ export async function readCalls(opts) {
         rows = decodeAggregate3(asHex(answer, "the Multicall3 batch"), request.callCount);
     }
     catch (err) {
-        throw new TokenError(`the Multicall3 batch at ${request.to} did not answer with results: ${err.message}. If this chain has no Multicall3 deployment at that address, pass multicall3Address, or batch:false to read the calls one at a time.`);
+        throw new TokenError(`the Multicall3 batch at ${request.to} did not answer with results: ${err.message}. If this chain's Multicall3 is deployed elsewhere, the operator names it in tool_config.token.multicall3; or pass batch:false to read the calls one at a time.`);
     }
     for (const [i, call] of packed.entries()) {
         const row = rows[i];

package/dist/lib/uri.js

@@ -27,7 +27,7 @@
  */
 import { Buffer } from "node:buffer";
 const unbound = async (req) => {
-    throw new Error(`no metadata fetcher is bound, so ${req.url} was not read. This package contains no HTTP client of its own: the runtime binds one with _setMetadataFetch(), which is also where redirect, SSRF and timeout policy belongs.`);
+    throw new Error(`no metadata origin is allowed, so ${req.url} was not read. Allow the origin in the spec — tool_config.token: { metadata_origins: [https://ipfs.io] }.`);
 };
 let metadataFetch = unbound;
 /** Bind the metadata fetcher. `undefined` restores the unbound state. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-token",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "Deterministic token and address resolution: ERC-20 and ERC-721 reads with impostor flagging",
   "main": "dist/index.js",
@@ -8,19 +8,22 @@
   "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-onchain": "0.7.0",
-    "@crewhaus/tool-text": "0.7.0",
+    "@crewhaus/chain-adapter-base": "0.8.1",
+    "@crewhaus/chain-adapter-evm": "0.8.1",
+    "@crewhaus/errors": "0.8.1",
+    "@crewhaus/tool-builder": "0.8.1",
+    "@crewhaus/tool-catalog": "0.8.1",
+    "@crewhaus/tool-http": "0.8.1",
+    "@crewhaus/tool-onchain": "0.8.1",
+    "@crewhaus/tool-text": "0.8.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -44,5 +47,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,117 +0,0 @@
-import type { ChainRead, ChainReader } from "./lib/chain";
-/** A 32-byte word from an unsigned integer. */
-export declare const word: (value: bigint) => string;
-export declare const encodeUint: (value: bigint) => string;
-export declare const encodeAddress: (address: string) => string;
-export declare const encodeBool: (value: boolean) => string;
-/** A dynamic `string` return: offset, length, then the bytes, padded. */
-export declare function encodeString(text: string): string;
-/** The pre-standard `bytes32` symbol: the text, left-aligned, NUL-padded. */
-export declare function encodeBytes32String(text: string): string;
-/** `Error(string)` revert data — the selector is the one Solidity emits. */
-export declare function revertWith(message: string): Promise<string>;
-/** What one contract answers for one call. A revert is an answer, not a throw. */
-export type CallAnswer = {
-    readonly ok: boolean;
-    readonly data: string;
-};
-export declare const answers: (data: string) => CallAnswer;
-export declare const reverts: (revertData: string) => CallAnswer;
-/** What a contract without that function returns: nothing at all. */
-export declare const NOTHING: CallAnswer;
-export type ContractHandler = (selector: string, args: string) => CallAnswer;
-export declare const USDC = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
-export declare const IMPOSTOR_USDC = "0x1111111111111111111111111111111111111111";
-export declare const CYRILLIC_USDC = "0x2222222222222222222222222222222222222222";
-export declare const MKR = "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2";
-export declare const BROKEN = "0x3333333333333333333333333333333333333333";
-export declare const NOT_A_CONTRACT = "0x4444444444444444444444444444444444444444";
-export declare const APE_NFT = "0x5555555555555555555555555555555555555555";
-export declare const GAME_1155 = "0x6666666666666666666666666666666666666666";
-export declare const ONCHAIN_NFT = "0x7777777777777777777777777777777777777777";
-export declare const LIAR_165 = "0x8888888888888888888888888888888888888888";
-export declare const ALICE = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
-export declare const BOB = "0x388C818CA8B9251b393131C08a736A67ccB19297";
-export declare const SPENDER = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45";
-/** A plain ERC-20 whose metadata is all well-formed strings. */
-export declare function erc20(opts: {
-    decimals: bigint;
-    symbol: string;
-    name: string;
-    totalSupply: bigint;
-    balances?: Record<string, bigint>;
-    allowances?: Record<string, bigint>;
-    bytes32Metadata?: boolean;
-}): ContractHandler;
-/** An ERC-721 that declares itself properly through ERC-165. */
-export declare function erc721(opts: {
-    name: string;
-    symbol: string;
-    owners: Record<string, string>;
-    tokenUris: Record<string, string>;
-    missingTokenRevert: string;
-    interfaceIds?: ReadonlyArray<string>;
-    answersEverything?: boolean;
-}): ContractHandler;
-/** An ERC-1155, which has no ownerOf and whose uri carries the {id} template. */
-export declare function erc1155(opts: {
-    uriTemplate: string;
-    balances: Record<string, bigint>;
-    interfaceIds?: ReadonlyArray<string>;
-}): ContractHandler;
-export type ChainStub = {
-    readonly reader: ChainReader;
-    /** Every read that left the package, in order, for assertions about what was asked. */
-    readonly reads: ChainRead[];
-};
-export declare function chainStub(opts: {
-    readonly contracts: Record<string, ContractHandler>;
-    readonly nativeBalances?: Record<string, bigint>;
-    readonly code?: Record<string, string>;
-    readonly blockNumber?: bigint;
-    readonly multicall3Address?: string;
-    /** Answer the batch call itself with this instead, to test an unusable answer. */
-    readonly brokenBatchAnswer?: string;
-    /**
-     * A Multicall3-shaped contract that implements `aggregate3` and nothing
-     * else, so `getEthBalance` and `getBlockNumber` reach its fallback and
-     * answer with no data. Real: `multicall3Address` is a caller-supplied
-     * address, and an aggregator that is not the canonical deployment has no
-     * obligation to carry the helpers.
-     */
-    readonly withoutMulticallHelpers?: boolean;
-}): ChainStub;
-export declare const UNISWAP_LIST: {
-    id: string;
-    name: string;
-    tokens: {
-        chainId: number;
-        address: string;
-        symbol: string;
-        name: string;
-        decimals: number;
-    }[];
-};
-/** A second reputable list that happens to carry a different address for USDC. */
-export declare const RIVAL_LIST: {
-    id: string;
-    name: string;
-    tokens: {
-        chainId: number;
-        address: string;
-        symbol: string;
-        name: string;
-        decimals: number;
-    }[];
-};
-/** The Cyrillic \u0421 impostor. It is not the same string, and it looks identical. */
-export declare const CYRILLIC_LIST: {
-    id: string;
-    tokens: {
-        chainId: number;
-        address: string;
-        symbol: string;
-        name: string;
-        decimals: number;
-    }[];
-};

package/dist/fixtures.js

@@ -1,222 +0,0 @@
-/**
- * Recorded chain answers, and a reader stub that serves them.
- *
- * Every test in this package drives `_setChainReader` with one of these. None
- * of them opens a socket, because there is nothing under the seam to open one
- * with — a suite that reached a public RPC endpoint would fail on a CI runner
- * with no egress and flake on somebody else's rate limit.
- *
- * The tokens here are the ones that break naive readers, and they are
- * modelled on real contracts rather than invented:
- *
- *   - a six-decimal stablecoin, the ordinary case;
- *   - a `bytes32` symbol, which is what MKR and other 2017-era tokens return
- *     because the ABI was not settled when they deployed;
- *   - a token whose `decimals()` reverts, which must come back as unknown and
- *     never as 18;
- *   - two impostors claiming a listed ticker, one of them with a Cyrillic \u0421;
- *   - an address with no code at all.
- *
- * The Multicall3 stub does a real ABI round trip through `tool-onchain`'s
- * codec rather than a hand-written fake of one: it decodes the batch this
- * package encoded and encodes the `(bool,bytes)[]` the package decodes. A
- * fixture that faked the encoding would pass against a broken encoder.
- */
-import { MULTICALL3_ADDRESS, abiDecode, abiEncodeCall } from "@crewhaus/tool-onchain";
-import { SELECTOR } from "./lib/erc";
-// ─── encoding helpers ───────────────────────────────────────────────────────
-const hexBody = (value) => value.replace(/^0x/, "");
-/** A 32-byte word from an unsigned integer. */
-export const word = (value) => value.toString(16).padStart(64, "0");
-export const encodeUint = (value) => `0x${word(value)}`;
-export const encodeAddress = (address) => `0x${hexBody(address).toLowerCase().padStart(64, "0")}`;
-export const encodeBool = (value) => encodeUint(value ? 1n : 0n);
-/** A dynamic `string` return: offset, length, then the bytes, padded. */
-export function encodeString(text) {
-    const bytes = new TextEncoder().encode(text);
-    let data = "";
-    for (const b of bytes)
-        data += b.toString(16).padStart(2, "0");
-    const padded = data.padEnd(Math.ceil(bytes.length / 32) * 64, "0");
-    return `0x${word(32n)}${word(BigInt(bytes.length))}${padded}`;
-}
-/** The pre-standard `bytes32` symbol: the text, left-aligned, NUL-padded. */
-export function encodeBytes32String(text) {
-    const bytes = new TextEncoder().encode(text);
-    if (bytes.length > 32)
-        throw new Error(`"${text}" does not fit in a bytes32`);
-    let data = "";
-    for (const b of bytes)
-        data += b.toString(16).padStart(2, "0");
-    return `0x${data.padEnd(64, "0")}`;
-}
-const strip = (call) => `0x${call.slice(10)}`;
-async function encodeCall(signature, args) {
-    const out = await abiEncodeCall.execute({ signature, args });
-    if (typeof out !== "string")
-        throw new Error("AbiEncodeCall did not return a string");
-    return JSON.parse(out).data;
-}
-/** `Error(string)` revert data — the selector is the one Solidity emits. */
-export async function revertWith(message) {
-    return encodeCall("Error(string)", [message]);
-}
-export const answers = (data) => ({ ok: true, data });
-export const reverts = (revertData) => ({ ok: false, data: revertData });
-/** What a contract without that function returns: nothing at all. */
-export const NOTHING = { ok: true, data: "0x" };
-export const USDC = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
-export const IMPOSTOR_USDC = "0x1111111111111111111111111111111111111111";
-export const CYRILLIC_USDC = "0x2222222222222222222222222222222222222222";
-export const MKR = "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2";
-export const BROKEN = "0x3333333333333333333333333333333333333333";
-export const NOT_A_CONTRACT = "0x4444444444444444444444444444444444444444";
-export const APE_NFT = "0x5555555555555555555555555555555555555555";
-export const GAME_1155 = "0x6666666666666666666666666666666666666666";
-export const ONCHAIN_NFT = "0x7777777777777777777777777777777777777777";
-export const LIAR_165 = "0x8888888888888888888888888888888888888888";
-export const ALICE = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
-export const BOB = "0x388C818CA8B9251b393131C08a736A67ccB19297";
-export const SPENDER = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45";
-const addressArg = (args, index = 0) => `0x${args.slice(index * 64 + 24, index * 64 + 64)}`.toLowerCase();
-const uintArg = (args, index = 0) => BigInt(`0x${args.slice(index * 64, index * 64 + 64) || "0"}`);
-/** A plain ERC-20 whose metadata is all well-formed strings. */
-export function erc20(opts) {
-    const text = opts.bytes32Metadata ? encodeBytes32String : encodeString;
-    return (selector, args) => {
-        switch (selector) {
-            case SELECTOR.decimals:
-                return answers(encodeUint(opts.decimals));
-            case SELECTOR.symbol:
-                return answers(text(opts.symbol));
-            case SELECTOR.name:
-                return answers(text(opts.name));
-            case SELECTOR.totalSupply:
-                return answers(encodeUint(opts.totalSupply));
-            case SELECTOR.balanceOf:
-                return answers(encodeUint(opts.balances?.[addressArg(args)] ?? 0n));
-            case SELECTOR.allowance:
-                return answers(encodeUint(opts.allowances?.[`${addressArg(args, 0)}:${addressArg(args, 1)}`] ?? 0n));
-            default:
-                return NOTHING;
-        }
-    };
-}
-/** An ERC-721 that declares itself properly through ERC-165. */
-export function erc721(opts) {
-    const supported = new Set(opts.interfaceIds ?? ["01ffc9a7", "80ac58cd", "5b5e139f"]);
-    return (selector, args) => {
-        if (selector === SELECTOR.supportsInterface) {
-            const id = args.slice(0, 8).toLowerCase();
-            return answers(encodeBool(opts.answersEverything === true || supported.has(id)));
-        }
-        if (selector === SELECTOR.name)
-            return answers(encodeString(opts.name));
-        if (selector === SELECTOR.symbol)
-            return answers(encodeString(opts.symbol));
-        if (selector === SELECTOR.ownerOf) {
-            const owner = opts.owners[uintArg(args).toString()];
-            return owner === undefined ? reverts(opts.missingTokenRevert) : answers(encodeAddress(owner));
-        }
-        if (selector === SELECTOR.tokenURI) {
-            const uri = opts.tokenUris[uintArg(args).toString()];
-            return uri === undefined ? reverts(opts.missingTokenRevert) : answers(encodeString(uri));
-        }
-        return NOTHING;
-    };
-}
-/** An ERC-1155, which has no ownerOf and whose uri carries the {id} template. */
-export function erc1155(opts) {
-    const supported = new Set(opts.interfaceIds ?? ["01ffc9a7", "d9b67a26", "0e89341c"]);
-    return (selector, args) => {
-        if (selector === SELECTOR.supportsInterface) {
-            return answers(encodeBool(supported.has(args.slice(0, 8).toLowerCase())));
-        }
-        if (selector === SELECTOR.uri)
-            return answers(encodeString(opts.uriTemplate));
-        if (selector === SELECTOR.balanceOf1155) {
-            return answers(encodeUint(opts.balances[`${addressArg(args, 0)}:${uintArg(args, 1)}`] ?? 0n));
-        }
-        return NOTHING;
-    };
-}
-export function chainStub(opts) {
-    const reads = [];
-    const multicall = (opts.multicall3Address ?? MULTICALL3_ADDRESS).toLowerCase();
-    const handlerFor = (address) => opts.contracts[address.toLowerCase()];
-    const dispatch = (target, data) => {
-        const selector = data.slice(0, 10).toLowerCase();
-        const args = data.slice(10);
-        if (target.toLowerCase() === multicall) {
-            if (opts.withoutMulticallHelpers === true)
-                return NOTHING;
-            if (selector === SELECTOR.getBlockNumber)
-                return answers(encodeUint(opts.blockNumber ?? 0n));
-            if (selector === SELECTOR.getEthBalance) {
-                return answers(encodeUint(opts.nativeBalances?.[addressArg(args)] ?? 0n));
-            }
-            return NOTHING;
-        }
-        const handler = handlerFor(target);
-        // An address with no code answers every call with nothing. That is the
-        // whole point of the NOT_A_CONTRACT fixture.
-        return handler === undefined ? NOTHING : handler(selector, args);
-    };
-    const reader = async (read) => {
-        reads.push(read);
-        if (read.method === "eth_getCode") {
-            const address = String(read.params[0]).toLowerCase();
-            if (opts.code?.[address] !== undefined)
-                return opts.code[address];
-            return handlerFor(address) === undefined ? "0x" : "0x60806040";
-        }
-        if (read.method === "eth_getBalance") {
-            return encodeUint(opts.nativeBalances?.[String(read.params[0]).toLowerCase()] ?? 0n);
-        }
-        const call = read.params[0];
-        if (call.to.toLowerCase() !== multicall || !call.data.startsWith("0x82ad56cb")) {
-            const answer = dispatch(call.to, call.data);
-            // An unbatched eth_call cannot return a revert as data: the node errors.
-            if (!answer.ok)
-                throw new Error(`execution reverted (${answer.data})`);
-            return answer.data;
-        }
-        if (opts.brokenBatchAnswer !== undefined)
-            return opts.brokenBatchAnswer;
-        const decoded = await abiDecode.execute({
-            data: strip(call.data),
-            types: ["(address,bool,bytes)[]"],
-        });
-        if (typeof decoded !== "string")
-            throw new Error("AbiDecode did not return a string");
-        const [batch] = JSON.parse(decoded).values;
-        const results = batch.map(([to, , callData]) => {
-            const answer = dispatch(to, callData);
-            return [answer.ok, answer.data];
-        });
-        return strip(await encodeCall("f((bool,bytes)[])", [results]));
-    };
-    return { reader, reads };
-}
-// ─── token lists ────────────────────────────────────────────────────────────
-export const UNISWAP_LIST = {
-    id: "uniswap-default",
-    name: "Uniswap Labs Default",
-    tokens: [
-        { chainId: 1, address: USDC, symbol: "USDC", name: "USD Coin", decimals: 6 },
-        { chainId: 1, address: MKR, symbol: "MKR", name: "Maker", decimals: 18 },
-    ],
-};
-/** A second reputable list that happens to carry a different address for USDC. */
-export const RIVAL_LIST = {
-    id: "rival-list",
-    name: "Somebody Else's List",
-    tokens: [{ chainId: 1, address: IMPOSTOR_USDC, symbol: "USDC", name: "USD Coin", decimals: 6 }],
-};
-/** The Cyrillic \u0421 impostor. It is not the same string, and it looks identical. */
-export const CYRILLIC_LIST = {
-    id: "shady-list",
-    tokens: [
-        { chainId: 1, address: CYRILLIC_USDC, symbol: "USD\u0421", name: "USD Coin", decimals: 6 },
-    ],
-};