@rhinestone/shared-configs 1.7.16 → 1.8.0

package/dist/scripts/validation.d.ts

@@ -1,4 +1,17 @@
-export type SettlementLayer = 'ACROSS' | 'ECO' | 'RELAY' | 'OFT';
+export type SettlementLayer = 'ACROSS' | 'ECO' | 'RELAY' | 'OFT' | 'NEAR' | 'RHINO' | 'CCTP';
+export type ChainNetwork = 'mainnet' | 'testnet';
+/**
+ * Which execution stack a chain runs, for consumers that must build a viem
+ * `Chain` object themselves.
+ *
+ * The value set is deliberately "the stacks viem ships a `chainConfig` for",
+ * not a taxonomy of L2 architectures: the only thing a consumer does with this
+ * is pick the matching `chainConfig` for its formatters/serializers. Arbitrum
+ * Orbit is absent for that reason — viem's own `arbitrum` carries no
+ * formatters, fees or serializers, so an Orbit chain is correctly served as
+ * `vanilla` and an `orbit` value would promise behaviour viem does not have.
+ */
+export type ChainStack = 'op-stack' | 'zksync' | 'celo' | 'vanilla';
 export interface ChainData {
     name: string;
     settlementLayers: SettlementLayer[];
@@ -6,6 +19,11 @@ export interface ChainData {
         symbol: string;
         [key: string]: unknown;
     }>;
+    /** Whether this chain is a mainnet or a testnet. Stamped by
+     * `classifyChainNetworks`, not authored in the jsonnet. */
+    network?: ChainNetwork;
+    /** Execution stack. Stamped by `classifyChainStacks`. */
+    stack?: ChainStack;
     /** Virtual chains (e.g. HyperCore) settle on another chain and have no
      * direct settlement layers of their own — excluded from reachability checks. */
     virtual?: boolean;
@@ -24,9 +42,67 @@ export interface ValidationResult {
     hasErrors: boolean;
 }
 /**
- * Validates a chain registry for configuration problems.
+ * Stamps every chain with its mainnet/testnet classification, derived from which
+ * network map its chain id appears in.
+ *
+ * Why this exists: the split is otherwise implicit in *which file* an id lands in
+ * (configs/mainnets.json vs configs/testnets.json). The package surfaces it as
+ * `mainnetChains` / `MainnetNetwork`, but configs/chains.json — the registry the
+ * facts artifact publishes and the read-client bundles — carried no trace of it.
+ * So a consumer reading facts at runtime could not tell which environment a chain
+ * belonged to, which is exactly what the orchestrator's mainnet/testnet registry
+ * gating keys off: a CDN-added chain would arrive unclassifiable.
+ *
+ * Derived rather than authored per chain in the jsonnet, so it cannot drift from
+ * the membership it describes — "is this a testnet" keeps one source, the network
+ * maps.
+ *
+ * Lives in this module rather than generate.ts because the partition it relies on
+ * is a build-time invariant that has to fail the build, and generate.ts runs its
+ * generator on import, so nothing declared there is testable.
+ */
+export declare function classifyChainNetworks(chains: ChainRegistry, mainnets: Record<string, unknown>, testnets: Record<string, unknown>): {
+    chains: ChainRegistry;
+    issues: ValidationIssue[];
+};
+/** The subset of a generated network entry that stack classification needs. */
+export interface StackNetworkEntry {
+    id: number;
+    /** Absent for non-EVM and virtual chains, and for any chain viem does not ship. */
+    viemChain?: string;
+    /** Authored in config/shared-configs.jsonnet. Only meaningful — and only
+     *  permitted to decide the outcome — when there is no `viemChain`. */
+    stack?: string;
+}
+/**
+ * Stamps `stack` onto every registry entry.
+ *
+ * Derived from viem wherever viem defines the chain, which is every EVM chain
+ * today, so the common case is authored nowhere and cannot drift. The jsonnet's
+ * `stack` is the escape hatch for the case that motivates the field at all: a
+ * chain viem has never heard of, which a consumer has to synthesise with
+ * `defineChain` and therefore needs told which `chainConfig` to apply.
+ *
+ * For such a chain the field is **required, not defaulted**. Defaulting to
+ * `vanilla` would make the single most likely new chain — an OP-stack L2 —
+ * synthesise without OP-stack formatters, so its L1 fee fields would be missing
+ * and its gas silently mispriced. Today's behaviour for an unknown chain is a
+ * loud skip; a silent misprice would be strictly worse, so the decision is
+ * forced here, where a human is adding the chain anyway.
+ */
+export declare function classifyChainStacks(chains: ChainRegistry, networks: {
+    mainnets: StackNetworkEntry[];
+    testnets: StackNetworkEntry[];
+}): {
+    chains: ChainRegistry;
+    issues: ValidationIssue[];
+};
+/**
+ * Validates a chain registry for structural and configuration problems.
  *
  * Checks performed:
+ * - Structure: chain-id keys, and every field of every entry against the
+ *   shapes and unions declared in src/types.ts (error)
  * - Orphaned chains: chains with no settlement layers (error)
  * - Single-layer fragility: chains with exactly one settlement layer (warning)
  */

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

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../scripts/validation.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,KAAK,CAAC;AAEjE,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;oFACgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,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;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,gBAAgB,CAkC3E;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":"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"}

package/dist/scripts/validation.js

@@ -1,23 +1,461 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyChainNetworks = classifyChainNetworks;
+exports.classifyChainStacks = classifyChainStacks;
 exports.validateChainConfig = validateChainConfig;
 exports.formatValidationIssues = formatValidationIssues;
+const celo_1 = require("viem/celo");
+const viemChains = __importStar(require("viem/chains"));
+const op_stack_1 = require("viem/op-stack");
+const zksync_1 = require("viem/zksync");
+// Runtime mirrors of the string unions in src/types.ts. Keeping these in sync
+// is a build-time concern only: an unrecognised value here means the jsonnet
+// introduced a layer/quoter/vm the TS unions don't know about yet, which SHOULD
+// fail the build — consumers switch on these, so the union has to be updated in
+// the same change. (Read-side clients deliberately do NOT check enum values:
+// there, an unknown value means an older consumer is reading a newer artifact,
+// which must keep working.)
+const SETTLEMENT_LAYERS = new Set([
+    'ACROSS',
+    'ECO',
+    'RELAY',
+    'OFT',
+    'NEAR',
+    'RHINO',
+    'CCTP',
+]);
+const SWAP_QUOTERS = new Set([
+    '1inch',
+    '0x',
+    'velora',
+    'kyberswap',
+    'fynd',
+]);
+const VM_TYPES = new Set(['evm', 'svm', 'tvm']);
+const PEG_GROUPS = new Set(['USD', 'ETH']);
+const NETWORKS = new Set(['mainnet', 'testnet']);
+const STACKS = new Set(['op-stack', 'zksync', 'celo', 'vanilla']);
+// Registry keys are chain ids consumers index by directly, so they must be
+// canonical positive integers — no leading zeros, which would let "01" and "1"
+// both address chain 1.
+const CHAIN_ID_KEY = /^[1-9][0-9]*$/;
+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;
+const isAbsentOr = (v, check) => v === undefined || check(v);
+/**
+ * Structural checks on one chain entry, returning human-readable problems.
+ *
+ * This is the exhaustive validation: it runs once, here, against data we just
+ * generated and against unions we ship in the same version. Read-side clients
+ * only sanity-check the envelope, so this is the single place a malformed
+ * registry gets caught before it reaches anyone.
+ */
+function structuralProblems(chain) {
+    const problems = [];
+    if (!isNonEmptyString(chain.name))
+        problems.push('name is not a non-empty string');
+    if (!VM_TYPES.has(chain.vmType)) {
+        problems.push(`unknown vmType ${JSON.stringify(chain.vmType)}`);
+    }
+    // Required, and the only field here the jsonnet does not author — it is
+    // stamped by classifyChainNetworks. Checked anyway, because this is the gate
+    // the published artifact passes through: consumers gate their mainnet vs
+    // testnet registry on it, so an entry reaching the CDN without it would be
+    // unclassifiable at runtime with no way to recover.
+    if (!NETWORKS.has(chain.network)) {
+        problems.push(`network ${JSON.stringify(chain.network)} is not "mainnet" or "testnet"`);
+    }
+    // Same deal as `network`: stamped by classifyChainStacks, not authored, and
+    // checked here anyway because this is the gate the published artifact passes
+    // through. A consumer synthesising a chain object reads this to pick viem's
+    // matching chainConfig, so an entry reaching the CDN without it would be
+    // built with vanilla formatters — silently mispriced rather than absent.
+    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');
+    if (!isAbsentOr(chain.virtual, (v) => typeof v === 'boolean')) {
+        problems.push('virtual is not a boolean');
+    }
+    for (const field of ['nativeToken', 'wrappedNativeToken']) {
+        const token = chain[field];
+        if (!isObject(token)) {
+            problems.push(`${field} is not an object`);
+            continue;
+        }
+        if (typeof token.address !== 'string')
+            problems.push(`${field}.address is not a string`);
+        if (!isNonEmptyString(token.symbol))
+            problems.push(`${field}.symbol is not a non-empty string`);
+        if (!isNonNegativeInt(token.decimals))
+            problems.push(`${field}.decimals is not a non-negative integer`);
+    }
+    if (!Array.isArray(chain.tokens)) {
+        problems.push('tokens is not an array');
+    }
+    else {
+        chain.tokens.forEach((token, i) => {
+            const at = `tokens[${i}]`;
+            if (!isObject(token)) {
+                problems.push(`${at} is not an object`);
+                return;
+            }
+            if (typeof token.address !== 'string')
+                problems.push(`${at}.address is not a string`);
+            if (!isNonEmptyString(token.symbol))
+                problems.push(`${at}.symbol is not a non-empty string`);
+            if (!isNonNegativeInt(token.decimals))
+                problems.push(`${at}.decimals is not a non-negative integer`);
+            // Nullable, but the key must be present — consumers read it directly.
+            for (const slot of ['balanceSlot', 'approvalSlot']) {
+                if (!(token[slot] === null || isNonNegativeInt(token[slot]))) {
+                    problems.push(`${at}.${slot} is not a non-negative integer or null`);
+                }
+            }
+            if (!isAbsentOr(token.priceSymbol, isNonEmptyString))
+                problems.push(`${at}.priceSymbol is not a string`);
+            if (!isAbsentOr(token.unpriced, (v) => typeof v === 'boolean'))
+                problems.push(`${at}.unpriced is not a boolean`);
+            if (!isAbsentOr(token.pegGroup, (v) => PEG_GROUPS.has(v))) {
+                problems.push(`${at}.pegGroup ${JSON.stringify(token.pegGroup)} is not a known peg group`);
+            }
+        });
+    }
+    for (const [field, allowed] of [
+        ['settlementLayers', SETTLEMENT_LAYERS],
+        ['swapQuoters', SWAP_QUOTERS],
+    ]) {
+        const values = chain[field];
+        if (!Array.isArray(values)) {
+            problems.push(`${field} is not an array`);
+            continue;
+        }
+        for (const value of values) {
+            if (!allowed.has(value)) {
+                problems.push(`${field} contains unknown value ${JSON.stringify(value)} — add it to the union in src/types.ts and to validation.ts`);
+            }
+        }
+    }
+    const quoterConfig = chain.swapQuoterConfig;
+    if (quoterConfig !== undefined) {
+        if (!isObject(quoterConfig)) {
+            problems.push('swapQuoterConfig is not an object');
+        }
+        else {
+            for (const [quoter, config] of Object.entries(quoterConfig)) {
+                if (!SWAP_QUOTERS.has(quoter)) {
+                    problems.push(`swapQuoterConfig has unknown quoter ${JSON.stringify(quoter)}`);
+                }
+                if (!isObject(config)) {
+                    problems.push(`swapQuoterConfig.${quoter} is not an object`);
+                }
+                else if (!isAbsentOr(config.slug, isNonEmptyString)) {
+                    problems.push(`swapQuoterConfig.${quoter}.slug is not a string`);
+                }
+            }
+        }
+    }
+    return problems;
+}
 /**
- * Validates a chain registry for configuration problems.
+ * Reinserts an entry's keys in sorted order.
+ *
+ * jsonnet emits its objects key-sorted, so appending a field would leave the one
+ * generated file that gets signed and published non-canonical — the same logical
+ * registry serialising differently depending on how the generator happened to
+ * build the object. Only the top level needs it; nested objects come through
+ * untouched and already sorted.
+ */
+function withSortedKeys(entry) {
+    return Object.fromEntries(Object.entries(entry).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+/**
+ * Stamps every chain with its mainnet/testnet classification, derived from which
+ * network map its chain id appears in.
+ *
+ * Why this exists: the split is otherwise implicit in *which file* an id lands in
+ * (configs/mainnets.json vs configs/testnets.json). The package surfaces it as
+ * `mainnetChains` / `MainnetNetwork`, but configs/chains.json — the registry the
+ * facts artifact publishes and the read-client bundles — carried no trace of it.
+ * So a consumer reading facts at runtime could not tell which environment a chain
+ * belonged to, which is exactly what the orchestrator's mainnet/testnet registry
+ * gating keys off: a CDN-added chain would arrive unclassifiable.
+ *
+ * Derived rather than authored per chain in the jsonnet, so it cannot drift from
+ * the membership it describes — "is this a testnet" keeps one source, the network
+ * maps.
+ *
+ * Lives in this module rather than generate.ts because the partition it relies on
+ * is a build-time invariant that has to fail the build, and generate.ts runs its
+ * generator on import, so nothing declared there is testable.
+ */
+function classifyChainNetworks(chains, mainnets, testnets) {
+    const issues = [];
+    const classified = {};
+    for (const [chainId, chain] of Object.entries(chains)) {
+        const chainName = isNonEmptyString(chain?.name)
+            ? chain.name
+            : '<unnamed>';
+        const inMainnets = Object.hasOwn(mainnets, chainId);
+        const inTestnets = Object.hasOwn(testnets, chainId);
+        // Anything the input already carries under `network` is dropped rather than
+        // trusted: the field is present if and only if it was derived here, from the
+        // maps. That holds on the failure paths too, which is what keeps the
+        // structural check in validateChainConfig an independent second gate — it
+        // rejects an unclassified chain regardless of what the jsonnet emitted.
+        const base = { ...chain };
+        delete base.network;
+        if (inMainnets && inTestnets) {
+            // Nothing downstream can resolve this, and the pre-existing provider merge
+            // (`{...mainnets, ...testnets}`) would silently settle it as a testnet.
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: 'listed in both configs/mainnets.json and configs/testnets.json — cannot be classified',
+            });
+            classified[chainId] = withSortedKeys(base);
+            continue;
+        }
+        if (!inMainnets && !inTestnets) {
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: 'listed in neither configs/mainnets.json nor configs/testnets.json — cannot be classified as mainnet or testnet',
+            });
+            classified[chainId] = withSortedKeys(base);
+            continue;
+        }
+        classified[chainId] = withSortedKeys({
+            ...base,
+            network: inMainnets ? 'mainnet' : 'testnet',
+        });
+    }
+    // The reverse direction: providers configured for a chain the registry does not
+    // define. Harmless today (every consumer iterates the registry, not the network
+    // maps) but it is the same jsonnet drift that makes a chain silently absent, so
+    // it is worth saying out loud rather than leaving to be discovered.
+    for (const [mapName, map] of [
+        ['configs/mainnets.json', mainnets],
+        ['configs/testnets.json', testnets],
+    ]) {
+        for (const chainId of Object.keys(map)) {
+            if (!Object.hasOwn(chains, chainId)) {
+                issues.push({
+                    severity: 'warning',
+                    chainId,
+                    chainName: '<not in registry>',
+                    message: `listed in ${mapName} but absent from the chain registry`,
+                });
+            }
+        }
+    }
+    return { chains: classified, issues };
+}
+const isChainStack = (v) => typeof v === 'string' && STACKS.has(v);
+const STACK_FORMATTERS = [
+    ['op-stack', op_stack_1.chainConfig.formatters],
+    ['zksync', zksync_1.chainConfig.formatters],
+    ['celo', celo_1.chainConfig.formatters],
+];
+/**
+ * Reads the stack straight off viem's own chain definition.
+ *
+ * viem builds a stack-specific chain by spreading its `chainConfig`, so the
+ * `formatters` object is shared by reference with the config it came from —
+ * comparing identity is exact, and needs no list of chain names to maintain.
+ */
+function stackFromViem(viemChainName) {
+    const chain = viemChains[viemChainName];
+    if (!isObject(chain)) {
+        return { problem: `viem/chains has no export "${viemChainName}"` };
+    }
+    const formatters = chain.formatters;
+    if (!formatters)
+        return { stack: 'vanilla' };
+    for (const [stack, reference] of STACK_FORMATTERS) {
+        if (formatters === reference)
+            return { stack };
+    }
+    // viem gave this chain custom formatters from a config this generator does not
+    // know about — a new stack in a viem upgrade. Failing here is the point: the
+    // alternative is publishing it as `vanilla`, which reads as "no special
+    // handling needed" when the opposite was just established.
+    return {
+        problem: `viem's "${viemChainName}" carries formatters from a chainConfig this generator ` +
+            'does not recognise — add it to STACK_FORMATTERS and to the ChainStack union',
+    };
+}
+/**
+ * Stamps `stack` onto every registry entry.
+ *
+ * Derived from viem wherever viem defines the chain, which is every EVM chain
+ * today, so the common case is authored nowhere and cannot drift. The jsonnet's
+ * `stack` is the escape hatch for the case that motivates the field at all: a
+ * chain viem has never heard of, which a consumer has to synthesise with
+ * `defineChain` and therefore needs told which `chainConfig` to apply.
+ *
+ * For such a chain the field is **required, not defaulted**. Defaulting to
+ * `vanilla` would make the single most likely new chain — an OP-stack L2 —
+ * synthesise without OP-stack formatters, so its L1 fee fields would be missing
+ * and its gas silently mispriced. Today's behaviour for an unknown chain is a
+ * loud skip; a silent misprice would be strictly worse, so the decision is
+ * forced here, where a human is adding the chain anyway.
+ */
+function classifyChainStacks(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>';
+        // Same rule as `network`: present if and only if derived here, including on
+        // the failure paths, so the structural check stays an independent gate.
+        const base = { ...chain };
+        delete base.stack;
+        const entry = entriesById.get(chainId);
+        const fail = (message) => {
+            issues.push({ severity: 'error', chainId, chainName, message });
+            stamped[chainId] = withSortedKeys(base);
+        };
+        let authored;
+        if (entry?.stack !== undefined) {
+            if (!isChainStack(entry.stack)) {
+                fail(`stack ${JSON.stringify(entry.stack)} is not one of ${[...STACKS].join(', ')}`);
+                continue;
+            }
+            authored = entry.stack;
+        }
+        if (entry?.viemChain) {
+            const { stack, problem } = stackFromViem(entry.viemChain);
+            if (problem || !stack) {
+                fail(problem ?? 'stack could not be derived from viem');
+                continue;
+            }
+            // Authoring is allowed to agree, never to override: viem's definition is
+            // what the consumer actually uses for a chain viem ships.
+            if (authored !== undefined && authored !== stack) {
+                fail(`stack ${JSON.stringify(authored)} contradicts viem's own "${entry.viemChain}", ` +
+                    `which is ${JSON.stringify(stack)} — drop the override or fix it`);
+                continue;
+            }
+            stamped[chainId] = withSortedKeys({ ...base, stack });
+            continue;
+        }
+        const isEvm = chain.vmType === undefined || chain.vmType === 'evm';
+        const isVirtual = chain.virtual === true;
+        if (isEvm && !isVirtual) {
+            if (authored === undefined) {
+                fail('is an EVM chain with no viem chain entry, so consumers must synthesise it — ' +
+                    `author \`stack\` for it in config/shared-configs.jsonnet (one of ${[...STACKS].join(', ')}). ` +
+                    'It is not defaulted: publishing an OP-stack chain as "vanilla" would drop its ' +
+                    'L1 fee fields and misprice gas with no error anywhere');
+                continue;
+            }
+            stamped[chainId] = withSortedKeys({ ...base, stack: authored });
+            continue;
+        }
+        // Non-EVM (Solana, Tron) and virtual (HyperCore) chains are never built as
+        // viem chains, so the value is inert. Stamped anyway to keep the field
+        // required for every entry rather than optional-in-practice.
+        if (authored !== undefined) {
+            issues.push({
+                severity: 'warning',
+                chainId,
+                chainName,
+                message: `has an authored stack ${JSON.stringify(authored)} but is non-EVM or virtual, ` +
+                    'so it is never synthesised as a viem chain — the value is ignored',
+            });
+        }
+        stamped[chainId] = withSortedKeys({ ...base, stack: 'vanilla' });
+    }
+    return { chains: stamped, issues };
+}
+/**
+ * Validates a chain registry for structural and configuration problems.
  *
  * Checks performed:
+ * - Structure: chain-id keys, and every field of every entry against the
+ *   shapes and unions declared in src/types.ts (error)
  * - Orphaned chains: chains with no settlement layers (error)
  * - Single-layer fragility: chains with exactly one settlement layer (warning)
  */
 function validateChainConfig(chains) {
     const issues = [];
     for (const [chainId, chain] of Object.entries(chains)) {
+        const chainName = isNonEmptyString(chain?.name)
+            ? chain.name
+            : '<unnamed>';
+        if (!CHAIN_ID_KEY.test(chainId)) {
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: 'key is not a canonical chain id (positive integer, no leading zeros)',
+            });
+        }
+        if (!isObject(chain)) {
+            issues.push({
+                severity: 'error',
+                chainId,
+                chainName,
+                message: 'entry is not an object',
+            });
+            continue;
+        }
+        for (const problem of structuralProblems(chain)) {
+            issues.push({ severity: 'error', chainId, chainName, message: problem });
+        }
         // Virtual chains (HyperCore) are reachable via their settlement chain, not
         // a direct settlement layer — the orphaned-chain check doesn't apply.
         if (chain.virtual) {
             continue;
         }
         const layers = chain.settlementLayers;
+        if (!Array.isArray(layers)) {
+            // Already reported structurally; skip the reachability checks below.
+            continue;
+        }
         if (layers.length === 0) {
             issues.push({
                 severity: 'error',

package/dist/src/__tests__/chainFactsClient.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chainFactsClient.test.d.ts.map

package/dist/src/__tests__/chainFactsClient.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chainFactsClient.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/chainFactsClient.test.ts"],"names":[],"mappings":""}