@rhinestone/shared-configs 1.8.0 → 1.10.0

package/dist/scripts/__tests__/validation.test.js

@@ -11,6 +11,12 @@ function validChain(overrides = {}) {
         vmType: "evm",
         network: "mainnet",
         stack: "vanilla",
+        caip2: "eip155:1",
+        explorer: {
+            url: "https://etherscan.io",
+            addressPath: "/address/",
+            txPath: "/tx/",
+        },
         nativeToken,
         wrappedNativeToken: { ...nativeToken, symbol: "WETH" },
         tokens: [{ ...nativeToken, balanceSlot: null, approvalSlot: null }],
@@ -53,9 +59,26 @@ function errorsFor(chain) {
         ["a non-boolean virtual flag", { virtual: "true" }],
         ["a missing network", { network: undefined }],
         ["an unknown network", { network: "devnet" }],
+        // `explorer` is required (nullable) in the public ChainEntry, so the build
+        // gate has to reject what the type says cannot happen.
+        ["a missing explorer", { explorer: undefined }],
+        ["an explorer that is not an object", { explorer: "https://etherscan.io" }],
+        ["an explorer missing txPath", {
+                explorer: { url: "https://etherscan.io", addressPath: "/address/" },
+            }],
+        // Links are built by concatenation, so the slash convention is load-bearing.
+        ["an explorer path with no leading slash", {
+                explorer: { url: "https://etherscan.io", addressPath: "address/", txPath: "/tx/" },
+            }],
+        ["an explorer url with a trailing slash", {
+                explorer: { url: "https://etherscan.io/", addressPath: "/address/", txPath: "/tx/" },
+            }],
     ])("rejects %s", (_label, overrides) => {
         (0, bun_test_1.expect)(errorsFor(validChain(overrides)).length).toBeGreaterThan(0);
     });
+    (0, bun_test_1.it)("accepts a null explorer, the answer for a chain that has none", () => {
+        (0, bun_test_1.expect)(errorsFor(validChain({ explorer: null }))).toEqual([]);
+    });
     (0, bun_test_1.it)("names the offending value so the build failure is actionable", () => {
         const [error] = errorsFor(validChain({ settlementLayers: ["TELEPORT"] }));
         (0, bun_test_1.expect)(error.message).toContain("TELEPORT");
@@ -214,6 +237,149 @@ function errorsFor(chain) {
         (0, bun_test_1.expect)(Object.keys(chains)).toHaveLength(Object.keys(index_1.chainRegistry).length);
     });
 });
+(0, bun_test_1.describe)("classifyChainCaip2", () => {
+    (0, bun_test_1.it)("derives eip155:<chainId> for a chain that declares none", () => {
+        const { chains, issues } = (0, validation_1.classifyChainCaip2)({
+            "8453": validChain({ name: "Base", caip2: undefined }),
+        });
+        (0, bun_test_1.expect)(chains["8453"].caip2).toBe("eip155:8453");
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    (0, bun_test_1.it)("keeps a declared id for a chain whose key is not an eip155 one", () => {
+        const { chains, issues } = (0, validation_1.classifyChainCaip2)({
+            "792703809": validChain({ name: "Solana", vmType: "svm", caip2: "solana:abc" }),
+        });
+        (0, bun_test_1.expect)(chains["792703809"].caip2).toBe("solana:abc");
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    // The whole reason the field is authored rather than derived: HyperCore's
+    // registry key is 1337, but `eip155:1337` is the Hardhat local chain id.
+    (0, bun_test_1.it)("keeps a virtual EVM chain's declared id instead of deriving from its key", () => {
+        const { chains, issues } = (0, validation_1.classifyChainCaip2)({
+            "1337": validChain({
+                name: "HyperCore",
+                virtual: true,
+                caip2: "hypercore:mainnet",
+            }),
+        });
+        (0, bun_test_1.expect)(chains["1337"].caip2).toBe("hypercore:mainnet");
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    // Deriving here would hand the entry an `eip155:` id that is confidently
+    // wrong — HyperCore's `eip155:1337` failure, reintroduced by the mechanism
+    // meant to prevent it.
+    bun_test_1.it.each([
+        ["a non-EVM chain", { vmType: "svm" }],
+        ["a virtual chain", { virtual: true }],
+    ])("errors when %s declares no caip2, rather than deriving one", (_label, overrides) => {
+        const { issues } = (0, validation_1.classifyChainCaip2)({
+            "424242": validChain({ ...overrides, caip2: undefined }),
+        });
+        (0, bun_test_1.expect)(issues).toHaveLength(1);
+        (0, bun_test_1.expect)(issues[0].severity).toBe("error");
+        (0, bun_test_1.expect)(issues[0].message).toContain("must author its caip2");
+    });
+    (0, bun_test_1.it)("errors when a real EVM chain declares an id that isn't its own", () => {
+        const { issues } = (0, validation_1.classifyChainCaip2)({
+            "8453": validChain({ name: "Base", caip2: "eip155:84532" }),
+        });
+        (0, bun_test_1.expect)(issues).toHaveLength(1);
+        (0, bun_test_1.expect)(issues[0].severity).toBe("error");
+        (0, bun_test_1.expect)(issues[0].message).toContain("eip155:8453");
+    });
+    (0, bun_test_1.it)("errors on a malformed declaration rather than falling back to the derived id", () => {
+        const { chains, issues } = (0, validation_1.classifyChainCaip2)({
+            "1337": validChain({ name: "HyperCore", virtual: true, caip2: "hypercore" }),
+        });
+        // Left as authored, so the structural check rejects it too — silently
+        // publishing eip155:1337 here is the exact failure being guarded against.
+        (0, bun_test_1.expect)(chains["1337"].caip2).toBe("hypercore");
+        (0, bun_test_1.expect)(issues.some((i) => i.message.includes("malformed"))).toBe(true);
+    });
+    // chainIdFromCaip2 is a reverse lookup over this field, so a collision makes
+    // it silently return whichever entry was iterated first.
+    (0, bun_test_1.it)("errors when two chains resolve to the same id", () => {
+        const { issues } = (0, validation_1.classifyChainCaip2)({
+            "1": validChain(),
+            "1337": validChain({ name: "Impostor", virtual: true, caip2: "eip155:1" }),
+        });
+        (0, bun_test_1.expect)(issues.some((i) => i.message.includes("already uses"))).toBe(true);
+    });
+    (0, bun_test_1.it)("leaves the real generated registry issue-free", () => {
+        const { issues } = (0, validation_1.classifyChainCaip2)(index_1.chainRegistry);
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+});
+(0, bun_test_1.describe)("classifyChainExplorers", () => {
+    const nets = (mainnets, testnets = []) => ({ mainnets, testnets });
+    // The classifier's input is pre-stamp, i.e. whatever the jsonnet authored —
+    // which for most chains is nothing. `validChain` carries an explorer so the
+    // structural checks pass, so strip it to exercise the derivation path.
+    const unauthored = (overrides = {}) => validChain({ ...overrides, explorer: undefined });
+    (0, bun_test_1.it)("derives the explorer from viem's own chain definition", () => {
+        const { chains, issues } = (0, validation_1.classifyChainExplorers)({ "8453": unauthored({ name: "Base" }) }, nets([{ id: 8453, viemChain: "base" }]));
+        (0, bun_test_1.expect)(chains["8453"].explorer).toEqual({
+            url: "https://basescan.org",
+            addressPath: "/address/",
+            txPath: "/tx/",
+        });
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    // The regression this exists for: viem's chain 1337 is `localhost`, and
+    // HyperCore's registry key is 1337. Resolving by id would hand HyperCore
+    // Localhost's metadata — the `eip155:1337` mistake from the other direction.
+    (0, bun_test_1.it)("resolves by declared viemChain name, never by chain id", () => {
+        const { chains } = (0, validation_1.classifyChainExplorers)({ "1337": unauthored({ name: "HyperCore", virtual: true }) }, 
+        // No viemChain declared, exactly as the registry has it.
+        nets([{ id: 1337 }]));
+        (0, bun_test_1.expect)(chains["1337"].explorer).toBeNull();
+    });
+    (0, bun_test_1.it)("lets an authored explorer win, for paths viem cannot express", () => {
+        const tronscan = {
+            url: "https://tronscan.org",
+            addressPath: "/#/address/",
+            txPath: "/#/transaction/",
+        };
+        const { chains, issues } = (0, validation_1.classifyChainExplorers)({
+            "728126428": validChain({
+                name: "Tron",
+                vmType: "tvm",
+                explorer: tronscan,
+            }),
+        }, nets([{ id: 728126428 }]));
+        (0, bun_test_1.expect)(chains["728126428"].explorer).toEqual(tronscan);
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    (0, bun_test_1.it)("errors on a malformed authored explorer", () => {
+        const { issues } = (0, validation_1.classifyChainExplorers)({ "1": validChain({ explorer: { url: "https://etherscan.io" } }) }, nets([{ id: 1, viemChain: "mainnet" }]));
+        (0, bun_test_1.expect)(issues).toHaveLength(1);
+        (0, bun_test_1.expect)(issues[0].severity).toBe("error");
+    });
+    // A missing explorer costs a hyperlink, not a wrong answer, so it warns
+    // rather than failing the build.
+    (0, bun_test_1.it)("warns rather than errors when nothing can supply one", () => {
+        const { chains, issues } = (0, validation_1.classifyChainExplorers)({ "424242": unauthored({ name: "Newchain" }) }, nets([{ id: 424242 }]));
+        (0, bun_test_1.expect)(chains["424242"].explorer).toBeNull();
+        (0, bun_test_1.expect)(issues).toHaveLength(1);
+        (0, bun_test_1.expect)(issues[0].severity).toBe("warning");
+    });
+    // Asserted against the shipped registry rather than by re-running the
+    // classifier, so this covers what actually reaches the artifact.
+    (0, bun_test_1.it)("leaves the shipped registry with an explorer on every chain but HyperCore", () => {
+        const withoutExplorer = Object.entries(index_1.chainRegistry)
+            .filter(([, e]) => e.explorer == null)
+            .map(([id]) => id);
+        (0, bun_test_1.expect)(withoutExplorer).toEqual(["1337"]);
+        for (const [id, entry] of Object.entries(index_1.chainRegistry)) {
+            const explorer = entry.explorer;
+            if (explorer === null)
+                continue;
+            (0, bun_test_1.expect)(explorer.url, id).toMatch(/^https:\/\/[^/]+$/);
+            (0, bun_test_1.expect)(explorer.addressPath, id).toMatch(/^\/.*\/$/);
+            (0, bun_test_1.expect)(explorer.txPath, id).toMatch(/^\/.*\/$/);
+        }
+    });
+});
 (0, bun_test_1.describe)("classifyChainStacks", () => {
     const nets = (mainnets, testnets = []) => ({ mainnets, testnets });
     // The common case: nothing is authored anywhere. viem already knows what Base

package/dist/scripts/generate.js

@@ -99,6 +99,8 @@ function renderChains(chainRegistry, mainnets, testnets) {
         "  pegGroup?: PegGroup;",
         "  balanceSlot: number | null;",
         "  approvalSlot: number | null;",
+        "  /** Bridge layers that can carry this token on this chain, when known. */",
+        "  settlementLayers?: SettlementLayer[];",
         "  unpriced?: boolean;",
         "}",
         "",
@@ -109,6 +111,15 @@ function renderChains(chainRegistry, mainnets, testnets) {
         "  decimals: number;",
         "}",
         "",
+        "interface Explorer {",
+        "  /** Origin, no trailing slash. */",
+        "  url: string;",
+        "  /** Path to an address page, with both slashes (`/address/`). */",
+        "  addressPath: string;",
+        "  /** Path to a transaction page, with both slashes (`/tx/`). */",
+        "  txPath: string;",
+        "}",
+        "",
         "interface Chain {",
         "  name: string;",
         "  vmType: VmType;",
@@ -116,8 +127,11 @@ function renderChains(chainRegistry, mainnets, testnets) {
         "  network: ChainNetwork;",
         "  /** Execution stack, for consumers that must synthesise a viem `Chain`. */",
         "  stack: ChainStack;",
-        "  /** CAIP-2 chain identifier; populated for non-eip155 chains only. */",
-        "  caip2?: string;",
+        "  /** CAIP-2 chain identifier. Present on every chain: authored for the",
+        "   *  non-eip155 ones, derived as `eip155:<chainId>` for the rest. */",
+        "  caip2: string;",
+        "  /** Block explorer, or null for a chain that has none (render plain text). */",
+        "  explorer: Explorer | null;",
         "  /** True for virtual chains (e.g. HyperCore) that settle on another chain. */",
         "  virtual?: boolean;",
         "  nativeToken: NativeToken;",
@@ -132,7 +146,7 @@ function renderChains(chainRegistry, mainnets, testnets) {
         `const chains: Record<SupportedChain, Chain> = ${JSON.stringify(chains, null, 2)};`,
         "",
         "export { chains };",
-        "export type { Chain, Token, NativeToken };",
+        "export type { Chain, Token, NativeToken, Explorer };",
     ].join("\n");
 }
 function runJsonnet(yeetRoot) {
@@ -365,8 +379,19 @@ async function generate() {
     const { chains: networkClassified, issues: networkIssues } = (0, validation_1.classifyChainNetworks)(output.chains, output.mainnets, output.testnets);
     // Then the execution stack, for consumers that have to build a viem `Chain`
     // themselves because the chain postdates their pinned viem.
-    const { chains: classifiedChains, issues: stackIssues } = (0, validation_1.classifyChainStacks)(networkClassified, output.networks);
-    const classificationIssues = [...networkIssues, ...stackIssues];
+    const { chains: stackClassified, issues: stackIssues } = (0, validation_1.classifyChainStacks)(networkClassified, output.networks);
+    // Then the canonical CAIP-2 id, so consumers key a chain by the id the wire
+    // uses instead of each deriving `eip155:<id>` for themselves.
+    const { chains: caip2Classified, issues: caip2Issues } = (0, validation_1.classifyChainCaip2)(stackClassified);
+    // Then the block explorer, so a consumer rendering a link for a chain added
+    // after its release does not need a hand-maintained table of its own.
+    const { chains: classifiedChains, issues: explorerIssues } = (0, validation_1.classifyChainExplorers)(caip2Classified, output.networks);
+    const classificationIssues = [
+        ...networkIssues,
+        ...stackIssues,
+        ...caip2Issues,
+        ...explorerIssues,
+    ];
     await (0, promises_1.writeFile)(node_path_1.default.join(configsDir, "chains.json"), `${JSON.stringify(classifiedChains, null, 2)}\n`);
     await (0, promises_1.writeFile)(node_path_1.default.join(configsDir, "mainnets.json"), `${JSON.stringify(output.mainnets, null, 2)}\n`);
     await (0, promises_1.writeFile)(node_path_1.default.join(configsDir, "testnets.json"), `${JSON.stringify(output.testnets, null, 2)}\n`);

package/dist/scripts/validation.d.ts

@@ -65,6 +65,63 @@ export declare function classifyChainNetworks(chains: ChainRegistry, mainnets: R
     chains: ChainRegistry;
     issues: ValidationIssue[];
 };
+/**
+ * Stamps every chain with its canonical CAIP-2 id, deriving `eip155:<chainId>`
+ * for the chains that do not declare one.
+ *
+ * Why this exists: `caip2` was authored only for the chains whose id is not an
+ * EIP-155 one (Solana, Tron, HyperCore), so every consumer that wanted a CAIP-2
+ * id had to carry the same `entry.caip2 ?? \`eip155:${id}\`` fallback — the
+ * orchestrator, deposit-service, the SDK and the indexers each had their own.
+ * A fallback repeated in five places is a rule with five chances to drift, and
+ * the one place it is genuinely load-bearing (HyperCore, whose `eip155:1337`
+ * spelling is wrong) is exactly where getting it wrong is silent.
+ *
+ * Derived rather than authored per chain for the same reason `network` is: an
+ * EVM chain's CAIP-2 id is a restatement of its chain id, so authoring it would
+ * only create a second copy that could disagree with the first.
+ *
+ * Uniqueness is checked because `chainIdFromCaip2` is a reverse lookup over this
+ * field — two chains sharing an id makes that lookup silently return whichever
+ * came first.
+ */
+export declare function classifyChainCaip2(chains: ChainRegistry): {
+    chains: ChainRegistry;
+    issues: ValidationIssue[];
+};
+/**
+ * Where a chain's transactions and addresses can be looked at by a human.
+ * `url` has no trailing slash; the paths carry their own leading and trailing
+ * ones, so a link is `${url}${addressPath}${value}`.
+ */
+export interface ChainExplorer {
+    url: string;
+    addressPath: string;
+    txPath: string;
+}
+/**
+ * Stamps every chain with its block explorer, derived from the chain's viem
+ * definition where it has one and authored in the jsonnet where it does not.
+ *
+ * Resolved by the entry's declared `viemChain` **name**, never by chain id. A
+ * lookup by id is actively wrong here: viem's chain 1337 is `localhost`, so
+ * HyperCore — whose registry key is 1337 — would silently inherit Localhost's
+ * metadata. That is the same mistake as addressing HyperCore by `eip155:1337`,
+ * arrived at from the other direction.
+ *
+ * A missing explorer is not an error. It resolves to `null`, which consumers
+ * render as plain text instead of a link; the cost of not knowing one is a
+ * missing hyperlink, not a wrong answer. It is still worth a warning, because
+ * the usual cause is a chain added without one rather than a chain that
+ * genuinely has none.
+ */
+export declare function classifyChainExplorers(chains: ChainRegistry, networks: {
+    mainnets: StackNetworkEntry[];
+    testnets: StackNetworkEntry[];
+}): {
+    chains: ChainRegistry;
+    issues: ValidationIssue[];
+};
 /** The subset of a generated network entry that stack classification needs. */
 export interface StackNetworkEntry {
     id: number;

package/dist/scripts/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../scripts/validation.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,KAAK,GACL,OAAO,GACP,KAAK,GACL,MAAM,GACN,OAAO,GACP,MAAM,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAC1D;+DAC2D;IAC3D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,yDAAyD;IACzD,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;oFACgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAgKD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEtD,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAiBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAwEtD;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE;IACR,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,GACA;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAyFtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,gBAAgB,CAiE3E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAWvE"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../scripts/validation.ts"],"names":[],"mappings":"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"}

package/dist/scripts/validation.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyChainNetworks = classifyChainNetworks;
+exports.classifyChainCaip2 = classifyChainCaip2;
+exports.classifyChainExplorers = classifyChainExplorers;
 exports.classifyChainStacks = classifyChainStacks;
 exports.validateChainConfig = validateChainConfig;
 exports.formatValidationIssues = formatValidationIssues;
@@ -72,6 +74,18 @@ const STACKS = new Set(['op-stack', 'zksync', 'celo', 'vanilla']);
 // canonical positive integers — no leading zeros, which would let "01" and "1"
 // both address chain 1.
 const CHAIN_ID_KEY = /^[1-9][0-9]*$/;
+// CAIP-2 (https://chainagnostic.org/CAIPs/caip-2): `<namespace>:<reference>`.
+//
+// Deliberately shape-only — the namespace set is not ours to close, and a chain
+// arriving under a namespace this build has never heard of is a new chain, not
+// a malformed one.
+//
+// Deliberately looser than the spec on namespace length too. CAIP-2 caps it at
+// 8 characters; `hypercore` is 9, and that spelling is canonical for us across
+// the orchestrator, the SDK and deposit-service. Tightening this to the spec
+// would fail the build on our own established id, so the bound is the org's,
+// not the spec's.
+const CAIP2 = /^[-a-z0-9]{3,16}:[-_a-zA-Z0-9]{1,32}$/;
 const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
 const isNonNegativeInt = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0;
@@ -107,8 +121,26 @@ function structuralProblems(chain) {
     if (!STACKS.has(chain.stack)) {
         problems.push(`stack ${JSON.stringify(chain.stack)} is not one of ${[...STACKS].join(', ')}`);
     }
-    if (!isAbsentOr(chain.caip2, isNonEmptyString))
-        problems.push('caip2 is not a string');
+    // Same deal as `network` and `stack` for EVM chains, where it is derived
+    // rather than authored — but unlike those two it is authored in the jsonnet
+    // for every chain whose id is not an EIP-155 one. Required either way: it is
+    // the id consumers key a chain by on the wire, and until it was always
+    // present each of them re-derived `eip155:<id>` for itself.
+    if (!CAIP2.test(chain.caip2)) {
+        problems.push(`caip2 ${JSON.stringify(chain.caip2)} is not a "<namespace>:<reference>" identifier`);
+    }
+    // Nullable, but the key has to be present: `null` is the answer for a chain
+    // with no explorer, and absent is not an answer at all. Stamped by
+    // classifyChainExplorers rather than authored for most chains, and checked
+    // here for the same reason as `network` and `stack` — this is the gate the
+    // published artifact passes through, and `ChainEntry` types consumers as
+    // though the key is always there.
+    if (!('explorer' in chain)) {
+        problems.push('explorer is missing (use null for a chain with no explorer)');
+    }
+    else if (chain.explorer !== null && !isChainExplorer(chain.explorer)) {
+        problems.push(`explorer ${JSON.stringify(chain.explorer)} is not null or { url (no trailing slash), addressPath, txPath (both slash-wrapped) }`);
+    }
     if (!isAbsentOr(chain.virtual, (v) => typeof v === 'boolean')) {
         problems.push('virtual is not a boolean');
     }
@@ -288,6 +320,185 @@ function classifyChainNetworks(chains, mainnets, testnets) {
     }
     return { chains: classified, issues };
 }
+/**
+ * Stamps every chain with its canonical CAIP-2 id, deriving `eip155:<chainId>`
+ * for the chains that do not declare one.
+ *
+ * Why this exists: `caip2` was authored only for the chains whose id is not an
+ * EIP-155 one (Solana, Tron, HyperCore), so every consumer that wanted a CAIP-2
+ * id had to carry the same `entry.caip2 ?? \`eip155:${id}\`` fallback — the
+ * orchestrator, deposit-service, the SDK and the indexers each had their own.
+ * A fallback repeated in five places is a rule with five chances to drift, and
+ * the one place it is genuinely load-bearing (HyperCore, whose `eip155:1337`
+ * spelling is wrong) is exactly where getting it wrong is silent.
+ *
+ * Derived rather than authored per chain for the same reason `network` is: an
+ * EVM chain's CAIP-2 id is a restatement of its chain id, so authoring it would
+ * only create a second copy that could disagree with the first.
+ *
+ * Uniqueness is checked because `chainIdFromCaip2` is a reverse lookup over this
+ * field — two chains sharing an id makes that lookup silently return whichever
+ * came first.
+ */
+function classifyChainCaip2(chains) {
+    const issues = [];
+    const classified = {};
+    const seen = new Map();
+    for (const [chainId, chain] of Object.entries(chains)) {
+        const chainName = isNonEmptyString(chain?.name)
+            ? chain.name
+            : '<unnamed>';
+        const declared = chain?.caip2;
+        // A malformed declaration is left exactly as authored rather than replaced
+        // with the derived form: quietly publishing `eip155:1337` for HyperCore is
+        // the precise mistake this field exists to prevent, so the structural check
+        // reports the real value instead.
+        if (declared !== undefined && !(typeof declared === 'string' && CAIP2.test(declared))) {
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: `declares a malformed caip2 ${JSON.stringify(declared)} — expected "<namespace>:<reference>"`,
+            });
+            classified[chainId] = withSortedKeys({ ...chain });
+            continue;
+        }
+        // A real EVM chain — and only a real EVM chain — has an id that is
+        // definitionally `eip155:<chainId>`. Everything else is addressed by an id
+        // the registry key cannot express, so its caip2 has to be authored.
+        const derivable = chain.vmType === 'evm' && chain.virtual !== true;
+        const derived = `eip155:${chainId}`;
+        // Deriving for a non-EVM or virtual entry would hand it an `eip155:` id that
+        // is confidently wrong — the same failure as HyperCore's `eip155:1337`,
+        // reintroduced by the very thing meant to prevent it. So the next svm/tvm or
+        // virtual chain added without an authored caip2 fails the build here rather
+        // than reaching the artifact under a wire id nothing uses.
+        if (declared === undefined && !derivable) {
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: `is ${chain.virtual === true ? 'a virtual chain' : `vmType ${JSON.stringify(chain.vmType)}`} and must author its caip2 — only a non-virtual EVM chain can derive ${JSON.stringify(derived)} from its registry key`,
+            });
+            classified[chainId] = withSortedKeys({ ...chain });
+            continue;
+        }
+        const caip2 = declared === undefined ? derived : declared;
+        // Conversely, a declaration that disagrees with the derivable form is a typo
+        // rather than an override.
+        if (declared !== undefined && derivable && declared !== derived) {
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: `declares caip2 ${JSON.stringify(declared)} but is a non-virtual EVM chain, whose canonical id is ${JSON.stringify(derived)}`,
+            });
+        }
+        const collision = seen.get(caip2);
+        if (collision !== undefined) {
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: `resolves to caip2 ${JSON.stringify(caip2)}, which chain ${collision} already uses — a reverse lookup cannot tell them apart`,
+            });
+        }
+        else {
+            seen.set(caip2, chainId);
+        }
+        classified[chainId] = withSortedKeys({ ...chain, caip2 });
+    }
+    return { chains: classified, issues };
+}
+// Near-universal across EVM explorers (Etherscan, Blockscout and the -scan
+// forks all use these). Tronscan is the exception, and authors its own.
+const DEFAULT_ADDRESS_PATH = '/address/';
+const DEFAULT_TX_PATH = '/tx/';
+// The slash convention is enforced, not assumed: a link is built by plain
+// concatenation, so a path missing its leading slash or a url carrying a
+// trailing one produces a subtly wrong URL rather than an obviously broken one.
+function isChainExplorer(value) {
+    const hasSlashes = (v) => typeof v === 'string' && /^\/.*\/$/.test(v);
+    return (isObject(value) &&
+        typeof value.url === 'string' &&
+        value.url.length > 0 &&
+        !value.url.endsWith('/') &&
+        hasSlashes(value.addressPath) &&
+        hasSlashes(value.txPath));
+}
+/**
+ * Stamps every chain with its block explorer, derived from the chain's viem
+ * definition where it has one and authored in the jsonnet where it does not.
+ *
+ * Resolved by the entry's declared `viemChain` **name**, never by chain id. A
+ * lookup by id is actively wrong here: viem's chain 1337 is `localhost`, so
+ * HyperCore — whose registry key is 1337 — would silently inherit Localhost's
+ * metadata. That is the same mistake as addressing HyperCore by `eip155:1337`,
+ * arrived at from the other direction.
+ *
+ * A missing explorer is not an error. It resolves to `null`, which consumers
+ * render as plain text instead of a link; the cost of not knowing one is a
+ * missing hyperlink, not a wrong answer. It is still worth a warning, because
+ * the usual cause is a chain added without one rather than a chain that
+ * genuinely has none.
+ */
+function classifyChainExplorers(chains, networks) {
+    const issues = [];
+    const stamped = {};
+    const entriesById = new Map();
+    for (const entry of [...networks.mainnets, ...networks.testnets]) {
+        entriesById.set(String(entry.id), entry);
+    }
+    for (const [chainId, chain] of Object.entries(chains)) {
+        const chainName = isNonEmptyString(chain?.name)
+            ? chain.name
+            : '<unnamed>';
+        const authored = chain?.explorer;
+        // Authoring wins outright, unlike `stack` where viem's definition is what
+        // the consumer actually uses. An explorer is presentation: the jsonnet is
+        // the only place a non-default path (Tronscan's `/#/address/`) or a
+        // preferred explorer among several can be expressed.
+        if (authored !== undefined) {
+            if (!isChainExplorer(authored)) {
+                issues.push({
+                    severity: 'error',
+                    chainId,
+                    chainName,
+                    message: `declares a malformed explorer ${JSON.stringify(authored)} — expected { url, addressPath, txPath }`,
+                });
+                stamped[chainId] = withSortedKeys({ ...chain });
+                continue;
+            }
+            stamped[chainId] = withSortedKeys({ ...chain, explorer: authored });
+            continue;
+        }
+        const viemChainName = entriesById.get(chainId)?.viemChain;
+        const url = viemChainName
+            ? viemChains[viemChainName]?.blockExplorers?.default?.url
+            : undefined;
+        if (typeof url !== 'string' || url.length === 0) {
+            issues.push({
+                severity: 'warning',
+                chainId,
+                chainName,
+                message: viemChainName
+                    ? `viem chain "${viemChainName}" ships no block explorer — links will render as plain text until one is authored`
+                    : 'has no viemChain to derive a block explorer from and authors none — links will render as plain text',
+            });
+            stamped[chainId] = withSortedKeys({ ...chain, explorer: null });
+            continue;
+        }
+        stamped[chainId] = withSortedKeys({
+            ...chain,
+            explorer: {
+                url: url.replace(/\/+$/, ''),
+                addressPath: DEFAULT_ADDRESS_PATH,
+                txPath: DEFAULT_TX_PATH,
+            },
+        });
+    }
+    return { chains: stamped, issues };
+}
 const isChainStack = (v) => typeof v === 'string' && STACKS.has(v);
 const STACK_FORMATTERS = [
     ['op-stack', op_stack_1.chainConfig.formatters],

package/dist/src/__tests__/chainFactsClient.test.js

@@ -49,9 +49,19 @@ function bumpedVersion() {
     const [major, minor, patch] = packageVersion_1.PACKAGE_VERSION.split("-")[0].split(".");
     return `${major}.${minor}.${Number(patch) + 1}`;
 }
+// Must produce a genuinely older version for every PACKAGE_VERSION, including
+// the `x.y.0` releases where decrementing the patch has nowhere to go — clamping
+// to 0 there returned PACKAGE_VERSION itself, which the client accepts as the
+// steady state, so the staleness tests asserted the opposite of what they read.
 function olderVersion() {
-    const [major, minor, patch] = packageVersion_1.PACKAGE_VERSION.split("-")[0].split(".");
-    return `${major}.${minor}.${Math.max(0, Number(patch) - 1)}`;
+    const [major, minor, patch] = packageVersion_1.PACKAGE_VERSION.split("-")[0]
+        .split(".")
+        .map(Number);
+    if (patch > 0)
+        return `${major}.${minor}.${patch - 1}`;
+    if (minor > 0)
+        return `${major}.${minor - 1}.0`;
+    return `${major - 1}.0.0`;
 }
 function withEthereum(overrides) {
     return {

package/dist/src/__tests__/chainVirtualization.test.js

@@ -30,10 +30,16 @@ const TRON_CAIP2 = "tron:mainnet";
             (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)(SOLANA_CAIP2)).toBe(index_1.MainnetNetwork.SOLANA);
             (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)(TRON_CAIP2)).toBe(index_1.MainnetNetwork.TRON);
         });
-        (0, bun_test_1.it)("returns undefined for unknown / eip155 caip2 strings", () => {
-            // eip155 references are not registry-backed; callers parse them numerically.
-            (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)("eip155:1")).toBeUndefined();
+        (0, bun_test_1.it)("resolves eip155 caip2 strings, now that every entry carries one", () => {
+            (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)("eip155:1")).toBe(index_1.MainnetNetwork.ETHEREUM);
+            (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)("eip155:999")).toBe(index_1.MainnetNetwork.HYPEREVM);
+        });
+        (0, bun_test_1.it)("returns undefined for ids no chain uses", () => {
+            // 1337 is HyperCore's *registry key*, but its caip2 is `hypercore:mainnet`
+            // — so the eip155 spelling resolves to nothing, which is the point of
+            // reading the field instead of deriving it.
             (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)("eip155:1337")).toBeUndefined();
+            (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)("eip155:999999999")).toBeUndefined();
             (0, bun_test_1.expect)((0, index_1.chainIdFromCaip2)("hypercore:testnet")).toBeUndefined();
         });
     });

package/dist/src/chainVirtualization.d.ts

@@ -9,17 +9,19 @@ export declare function isNonEvmChainId(chainId: number): boolean;
  */
 export declare function getNonEvmChainIds(): number[];
 /**
- * Canonical CAIP-2 string for a chain id. Returns the registry-declared
- * `caip2` when present (non-EVM entries today), otherwise falls back to the
- * `eip155:<chainId>` form. Throws nothing — returns the fallback for any
- * unknown id so callers don't need to special-case absent entries.
+ * Canonical CAIP-2 string for a chain id, read straight off the registry —
+ * every entry carries one (see `classifyChainCaip2`). Falls back to the
+ * `eip155:<chainId>` form for an id the registry does not know, so callers
+ * don't need to special-case an absent entry.
  */
 export declare function getCaip2(chainId: number): string;
 /**
- * Reverse lookup — find the numeric chain id whose registry-declared
- * `caip2` matches the input, or `undefined` if no entry has it. EVM chains
- * (which omit `caip2` in the registry) are NOT covered by this lookup;
- * callers parse `eip155:N` references on their own.
+ * Reverse lookup — the numeric chain id addressed by a CAIP-2 string, or
+ * `undefined` if no registry entry uses it.
+ *
+ * Covers every chain, EVM included: `caip2` is present on all entries, and the
+ * generator rejects two chains resolving to the same one, so this is
+ * unambiguous.
  */
 export declare function chainIdFromCaip2(caip2: string): number | undefined;
 //# sourceMappingURL=chainVirtualization.d.ts.map