@rhinestone/shared-configs 1.7.17 → 1.9.0

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

@@ -10,6 +10,7 @@ function validChain(overrides = {}) {
         name: "Ethereum",
         vmType: "evm",
         network: "mainnet",
+        stack: "vanilla",
         nativeToken,
         wrappedNativeToken: { ...nativeToken, symbol: "WETH" },
         tokens: [{ ...nativeToken, balanceSlot: null, approvalSlot: null }],
@@ -213,3 +214,85 @@ function errorsFor(chain) {
         (0, bun_test_1.expect)(Object.keys(chains)).toHaveLength(Object.keys(index_1.chainRegistry).length);
     });
 });
+(0, bun_test_1.describe)("classifyChainStacks", () => {
+    const nets = (mainnets, testnets = []) => ({ mainnets, testnets });
+    // The common case: nothing is authored anywhere. viem already knows what Base
+    // is, so the value is read off its definition and cannot drift from it.
+    (0, bun_test_1.it)("derives the stack from viem's own chain definition", () => {
+        const { chains, issues } = (0, validation_1.classifyChainStacks)({ "8453": validChain({ name: "Base" }), "42161": validChain({ name: "Arbitrum One" }) }, nets([
+            { id: 8453, viemChain: "base" },
+            { id: 42161, viemChain: "arbitrum" },
+        ]));
+        (0, bun_test_1.expect)(chains["8453"].stack).toBe("op-stack");
+        // viem's arbitrum carries no formatters — Orbit is genuinely vanilla here.
+        (0, bun_test_1.expect)(chains["42161"].stack).toBe("vanilla");
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    // The whole reason the field exists, and the reason it is not defaulted: this
+    // is the shape of a chain added faster than viem ships it, and guessing
+    // "vanilla" for an OP-stack L2 would misprice its gas with no error anywhere.
+    (0, bun_test_1.it)("refuses to guess for an EVM chain viem does not ship", () => {
+        const { chains, issues } = (0, validation_1.classifyChainStacks)({ "1234": validChain({ name: "Newchain" }) }, nets([{ id: 1234 }]));
+        (0, bun_test_1.expect)(chains["1234"].stack).toBeUndefined();
+        (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("author `stack`");
+    });
+    (0, bun_test_1.it)("takes the authored stack for a chain viem does not ship", () => {
+        const { chains, issues } = (0, validation_1.classifyChainStacks)({ "1234": validChain({ name: "Newchain" }) }, nets([{ id: 1234, stack: "op-stack" }]));
+        (0, bun_test_1.expect)(chains["1234"].stack).toBe("op-stack");
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    (0, bun_test_1.it)("rejects an authored value outside the union", () => {
+        const { chains, issues } = (0, validation_1.classifyChainStacks)({ "1234": validChain({ name: "Newchain" }) }, nets([{ id: 1234, stack: "orbit" }]));
+        (0, bun_test_1.expect)(chains["1234"].stack).toBeUndefined();
+        (0, bun_test_1.expect)(issues[0]?.message).toContain('"orbit" is not one of');
+    });
+    // Authoring may agree with viem, never override it: for a chain viem ships,
+    // viem's definition is what the consumer actually uses.
+    (0, bun_test_1.it)("rejects an authored stack that contradicts viem", () => {
+        const { issues } = (0, validation_1.classifyChainStacks)({ "8453": validChain({ name: "Base" }) }, nets([{ id: 8453, viemChain: "base", stack: "vanilla" }]));
+        (0, bun_test_1.expect)(issues[0]?.severity).toBe("error");
+        (0, bun_test_1.expect)(issues[0]?.message).toContain("contradicts viem");
+    });
+    (0, bun_test_1.it)("errors when viemChain names an export viem does not have", () => {
+        const { issues } = (0, validation_1.classifyChainStacks)({ "1234": validChain({ name: "Nope" }) }, nets([{ id: 1234, viemChain: "definitelyNotAChain" }]));
+        (0, bun_test_1.expect)(issues[0]?.message).toContain("no export");
+    });
+    // Non-EVM and virtual chains are never built as viem chains, so they must not
+    // be forced to declare a stack — that would be authoring noise on 3 of 24
+    // entries for a value nothing reads.
+    (0, bun_test_1.it)("stamps vanilla for non-EVM and virtual chains without authoring", () => {
+        const { chains, issues } = (0, validation_1.classifyChainStacks)({
+            "792703809": validChain({ name: "Solana", vmType: "svm" }),
+            "1337": validChain({ name: "HyperCore", virtual: true }),
+        }, nets([{ id: 792703809 }, { id: 1337 }]));
+        (0, bun_test_1.expect)(chains["792703809"].stack).toBe("vanilla");
+        (0, bun_test_1.expect)(chains["1337"].stack).toBe("vanilla");
+        (0, bun_test_1.expect)(issues).toEqual([]);
+    });
+    // Same invariant classifyChainNetworks holds for `network`: the field is
+    // present if and only if it was derived here, so the structural check in
+    // validateChainConfig stays an independent second gate rather than re-reading
+    // whatever the jsonnet happened to emit.
+    (0, bun_test_1.it)("ignores a stack carried in on the input, including when it then fails", () => {
+        const { chains } = (0, validation_1.classifyChainStacks)({ "8453": validChain({ name: "Base", stack: "zksync" }) }, nets([{ id: 8453, viemChain: "base" }]));
+        (0, bun_test_1.expect)(chains["8453"].stack).toBe("op-stack");
+        const { chains: failed } = (0, validation_1.classifyChainStacks)({ "1234": validChain({ name: "Newchain", stack: "op-stack" }) }, nets([{ id: 1234 }]));
+        (0, bun_test_1.expect)(failed["1234"].stack).toBeUndefined();
+    });
+    (0, bun_test_1.it)("stamps every chain in the real registry", () => {
+        const { chains, issues } = (0, validation_1.classifyChainStacks)(index_1.chainRegistry, 
+        // The real network entries are not exported, so re-derive from the
+        // registry: every EVM chain in it is one viem ships today, which is the
+        // property that keeps the field authored nowhere.
+        nets(Object.keys(index_1.chainRegistry).map((id) => ({
+            id: Number(id),
+            stack: "vanilla",
+        }))));
+        (0, bun_test_1.expect)(issues.filter((i) => i.severity === "error")).toEqual([]);
+        for (const entry of Object.values(chains)) {
+            (0, bun_test_1.expect)(entry.stack).toBeDefined();
+        }
+    });
+});

package/dist/scripts/generate.js

@@ -88,7 +88,7 @@ function renderChains(chainRegistry, mainnets, testnets) {
     }
     return [
         "// Auto-generated by scripts/generate.ts. Do not edit manually.",
-        'import type { ChainNetwork, PegGroup, ProviderName, SettlementLayer, SupportedChain, SwapQuoter, SwapQuoterConfig, VmType } from "./types";',
+        'import type { ChainNetwork, ChainStack, PegGroup, ProviderName, SettlementLayer, SupportedChain, SwapQuoter, SwapQuoterConfig, VmType } from "./types";',
         "",
         "interface Token {",
         "  /** EVM: 0x-prefixed hex. SVM: base58 SPL mint. TVM: base58 (T-prefixed). */",
@@ -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;",
         "}",
         "",
@@ -114,6 +116,8 @@ function renderChains(chainRegistry, mainnets, testnets) {
         "  vmType: VmType;",
         "  /** Whether this chain is a mainnet or a testnet. */",
         "  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;",
         "  /** True for virtual chains (e.g. HyperCore) that settle on another chain. */",
@@ -360,7 +364,11 @@ async function generate() {
     // registry that reaches configs/chains.json — and from there the published
     // facts artifact and the read-client's bundled fallback — carries the
     // classification rather than leaving it implicit in the network maps.
-    const { chains: classifiedChains, issues: classificationIssues } = (0, validation_1.classifyChainNetworks)(output.chains, output.mainnets, output.testnets);
+    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];
     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

@@ -1,5 +1,17 @@
 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[];
@@ -10,6 +22,8 @@ export interface ChainData {
     /** 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;
@@ -51,6 +65,38 @@ export declare function classifyChainNetworks(chains: ChainRegistry, mainnets: R
     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.
  *

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,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,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;oFACgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAqJD,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;;;;;;;;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":"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,8 +1,46 @@
 "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
@@ -29,6 +67,7 @@ const SWAP_QUOTERS = new Set([
 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.
@@ -60,6 +99,14 @@ function structuralProblems(chain) {
     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')) {
@@ -241,6 +288,129 @@ function classifyChainNetworks(chains, mainnets, testnets) {
     }
     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.
  *

package/dist/src/chains.d.ts

@@ -1,4 +1,4 @@
-import type { ChainNetwork, PegGroup, ProviderName, SettlementLayer, SupportedChain, SwapQuoter, SwapQuoterConfig, VmType } from "./types";
+import type { ChainNetwork, ChainStack, PegGroup, ProviderName, SettlementLayer, SupportedChain, SwapQuoter, SwapQuoterConfig, VmType } from "./types";
 interface Token {
     /** EVM: 0x-prefixed hex. SVM: base58 SPL mint. TVM: base58 (T-prefixed). */
     address: string;
@@ -8,6 +8,8 @@ interface Token {
     pegGroup?: PegGroup;
     balanceSlot: number | null;
     approvalSlot: number | null;
+    /** Bridge layers that can carry this token on this chain, when known. */
+    settlementLayers?: SettlementLayer[];
     unpriced?: boolean;
 }
 interface NativeToken {
@@ -21,6 +23,8 @@ interface Chain {
     vmType: VmType;
     /** Whether this chain is a mainnet or a testnet. */
     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;
     /** True for virtual chains (e.g. HyperCore) that settle on another chain. */

package/dist/src/chains.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAE3I,UAAU,KAAK;IACb,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,WAAW;IACnB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,EAAE,YAAY,CAAC;IACtB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,kBAAkB,EAAE,WAAW,CAAC;IAChC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC;CAClE;AAED,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,KAAK,CAg0CzC,CAAC;AAEF,OAAO,EAAE,MAAM,EAAE,CAAC;AAClB,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../../src/chains.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEvJ,UAAU,KAAK;IACb,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,WAAW;IACnB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,EAAE,YAAY,CAAC;IACtB,0EAA0E;IAC1E,KAAK,EAAE,UAAU,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,kBAAkB,EAAE,WAAW,CAAC;IAChC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC;CAClE;AAED,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,KAAK,CA2iDzC,CAAC;AAEF,OAAO,EAAE,MAAM,EAAE,CAAC;AAClB,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC"}