@rhinestone/shared-configs 1.7.15 → 1.7.17

package/dist/scripts/validation.js

@@ -1,23 +1,291 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyChainNetworks = classifyChainNetworks;
 exports.validateChainConfig = validateChainConfig;
 exports.formatValidationIssues = formatValidationIssues;
+// 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']);
+// 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);
 /**
- * Validates a chain registry for configuration problems.
+ * 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"`);
+    }
+    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;
+}
+/**
+ * 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 };
+}
+/**
+ * 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":""}