@eco-incorp/sauce 0.99.0

package/sdk/dist/chains/canonical.d.ts

@@ -0,0 +1,326 @@
+/**
+ * CANONICAL CHAIN REGISTRY — identity only, additive, zero runtime coupling.
+ *
+ * `chains` (./index.ts) is EVM-only and has no `slug`; `../deployments/` knows
+ * chain SLUGS but only for the 12 chains in the v12 deploy record, and only
+ * gated on whether the stack is LIVE there. Neither answers the plain question
+ * "what is this chain called, and what kind of VM does it run" for the full
+ * union — including the 5 v12-only EVM chains and Solana, which have no
+ * `chains` entry at all.
+ *
+ * This module is a flat, hand-maintained data table answering exactly that
+ * question, for both EVM and SVM chains in ONE numeric id space. It carries no
+ * rpcUrls / nativeCurrency / blockExplorerUrls / testnet — those already live on
+ * `chains` for the ids that have them; a consumer needing that data still goes
+ * through `getChain(id)`, which returns `undefined` for the 5 v12-only EVM
+ * chains and for Solana.
+ *
+ * Deliberately NOT wired to `../deployments/` or `../protocols/` — no import
+ * cycle, no runtime coupling. `v12ChainSlug`/`v12LiveChainSlugs` answer
+ * "can I cook here", a LIVENESS question; this module answers "what is this
+ * chain called", an IDENTITY question. Ronin (2020) is registered here even
+ * though its v12 deploy failed — see `test/chains-canonical.test.ts` for the
+ * pinned proof that the two layers are intentionally decoupled.
+ *
+ * MAINTENANCE NOTE: this table is hand-maintained, not derived. A chain added
+ * to `chains` (./index.ts) or to `V12_EVM_CHAINS` (../deployments/v12.generated.ts,
+ * rewritten by `sync-engine-artifacts` on every engine repin) will fail
+ * `test/chains-canonical.test.ts` until a matching entry is added here — that is
+ * the intended fail-closed behavior, not a test to relax.
+ */
+export type ChainKind = "evm" | "svm";
+/**
+ * Identity-only record for one chain: what it is called and what kind of VM it
+ * runs. Deliberately NOT a superset of `Chain` (../core/types.js) — see the
+ * module doc comment above for why.
+ */
+export interface CanonicalChain {
+    /** Numeric chain id. EVM chain id, or the eco-routes SVM id for Solana. */
+    readonly id: number;
+    /** Stable lowercase kebab-case key. For the 12 chains in the v12 deploy record this IS that record's `name`. */
+    readonly slug: string;
+    /** Canonical display name. For every id present in `chains`, this is byte-identical to `chains[id].name`. */
+    readonly name: string;
+    readonly kind: ChainKind;
+    /** Additional accepted spellings. Matched case- and punctuation-insensitively, same as `slug` and `name`. */
+    readonly aliases: readonly string[];
+}
+export declare const CANONICAL_CHAINS: readonly [{
+    readonly id: 1;
+    readonly slug: "ethereum";
+    readonly name: "Ethereum";
+    readonly kind: "evm";
+    readonly aliases: readonly ["mainnet", "eth"];
+}, {
+    readonly id: 10;
+    readonly slug: "optimism";
+    readonly name: "Optimism";
+    readonly kind: "evm";
+    readonly aliases: readonly ["op", "op-mainnet"];
+}, {
+    readonly id: 56;
+    readonly slug: "bsc";
+    readonly name: "BNB Chain";
+    readonly kind: "evm";
+    readonly aliases: readonly ["bnb", "binance-smart-chain", "bnb-smart-chain"];
+}, {
+    readonly id: 137;
+    readonly slug: "polygon";
+    readonly name: "Polygon";
+    readonly kind: "evm";
+    readonly aliases: readonly ["matic", "polygon-pos"];
+}, {
+    readonly id: 8453;
+    readonly slug: "base";
+    readonly name: "Base";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 42161;
+    readonly slug: "arbitrum";
+    readonly name: "Arbitrum One";
+    readonly kind: "evm";
+    readonly aliases: readonly ["arb"];
+}, {
+    readonly id: 42220;
+    readonly slug: "celo";
+    readonly name: "Celo";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 25;
+    readonly slug: "cronos";
+    readonly name: "Cronos";
+    readonly kind: "evm";
+    readonly aliases: readonly ["cro"];
+}, {
+    readonly id: 100;
+    readonly slug: "gnosis";
+    readonly name: "Gnosis";
+    readonly kind: "evm";
+    readonly aliases: readonly ["xdai", "gnosis-chain"];
+}, {
+    readonly id: 122;
+    readonly slug: "fuse";
+    readonly name: "Fuse";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 169;
+    readonly slug: "manta";
+    readonly name: "Manta Pacific";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 204;
+    readonly slug: "opbnb";
+    readonly name: "opBNB";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 250;
+    readonly slug: "fantom";
+    readonly name: "Fantom";
+    readonly kind: "evm";
+    readonly aliases: readonly ["ftm", "opera", "fantom-opera"];
+}, {
+    readonly id: 288;
+    readonly slug: "boba";
+    readonly name: "Boba";
+    readonly kind: "evm";
+    readonly aliases: readonly ["boba-network"];
+}, {
+    readonly id: 324;
+    readonly slug: "zksync";
+    readonly name: "zkSync Era";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 369;
+    readonly slug: "pulsechain";
+    readonly name: "PulseChain";
+    readonly kind: "evm";
+    readonly aliases: readonly ["pls"];
+}, {
+    readonly id: 1088;
+    readonly slug: "metis";
+    readonly name: "Metis";
+    readonly kind: "evm";
+    readonly aliases: readonly ["andromeda", "metis-andromeda"];
+}, {
+    readonly id: 1116;
+    readonly slug: "core";
+    readonly name: "Core";
+    readonly kind: "evm";
+    readonly aliases: readonly ["coredao", "core-dao"];
+}, {
+    readonly id: 1284;
+    readonly slug: "moonbeam";
+    readonly name: "Moonbeam";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 1329;
+    readonly slug: "sei";
+    readonly name: "Sei";
+    readonly kind: "evm";
+    readonly aliases: readonly ["sei-evm"];
+}, {
+    readonly id: 2222;
+    readonly slug: "kava";
+    readonly name: "Kava";
+    readonly kind: "evm";
+    readonly aliases: readonly ["kava-evm"];
+}, {
+    readonly id: 5000;
+    readonly slug: "mantle";
+    readonly name: "Mantle";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 7000;
+    readonly slug: "zetachain";
+    readonly name: "ZetaChain";
+    readonly kind: "evm";
+    readonly aliases: readonly ["zeta"];
+}, {
+    readonly id: 8217;
+    readonly slug: "klaytn";
+    readonly name: "Klaytn";
+    readonly kind: "evm";
+    readonly aliases: readonly ["kaia"];
+}, {
+    readonly id: 9001;
+    readonly slug: "evmos";
+    readonly name: "Evmos";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 34443;
+    readonly slug: "mode";
+    readonly name: "Mode";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 43114;
+    readonly slug: "avalanche";
+    readonly name: "Avalanche C-Chain";
+    readonly kind: "evm";
+    readonly aliases: readonly ["avax"];
+}, {
+    readonly id: 59144;
+    readonly slug: "linea";
+    readonly name: "Linea";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 80094;
+    readonly slug: "berachain";
+    readonly name: "Berachain";
+    readonly kind: "evm";
+    readonly aliases: readonly ["bera"];
+}, {
+    readonly id: 81457;
+    readonly slug: "blast";
+    readonly name: "Blast";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 534352;
+    readonly slug: "scroll";
+    readonly name: "Scroll";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 7777777;
+    readonly slug: "zora";
+    readonly name: "Zora";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 1313161554;
+    readonly slug: "aurora";
+    readonly name: "Aurora";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 130;
+    readonly slug: "unichain";
+    readonly name: "Unichain";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 143;
+    readonly slug: "monad";
+    readonly name: "Monad";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 146;
+    readonly slug: "sonic";
+    readonly name: "Sonic";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 2020;
+    readonly slug: "ronin";
+    readonly name: "Ronin";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 9745;
+    readonly slug: "plasma";
+    readonly name: "Plasma";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 57073;
+    readonly slug: "ink";
+    readonly name: "Ink";
+    readonly kind: "evm";
+    readonly aliases: readonly [];
+}, {
+    readonly id: 1399811149;
+    readonly slug: "solana";
+    readonly name: "Solana";
+    readonly kind: "svm";
+    readonly aliases: readonly ["sol", "mainnet-beta", "solana-mainnet"];
+}];
+/** The literal slug union — what the fluent accessor and route shortcuts key their builder types off. */
+export type ChainSlug = (typeof CANONICAL_CHAINS)[number]["slug"];
+/** Widened alias for ordinary iteration/mapping. */
+export declare const canonicalChains: readonly CanonicalChain[];
+/** The ONE normalizer: lowercased, trimmed, punctuation/whitespace stripped. */
+export declare function normalizeChainKey(input: string): string;
+/** O(1) lookup by numeric chain id. */
+export declare function chainById(id: number): CanonicalChain | undefined;
+/** Exact slug match only (no normalization) — for callers that already hold a canonical slug. */
+export declare function chainBySlug(slug: string): CanonicalChain | undefined;
+/** Normalized lookup across slug + name + aliases — resolves a human/legacy chain-name string. */
+export declare function chainByAlias(nameOrAlias: string): CanonicalChain | undefined;
+/** Anything resolvable to a chain: a numeric id, a native-`bigint` id (eco-routes uses these), a
+ *  slug/name/alias string, or an already-resolved `CanonicalChain`. */
+export type ChainRef = number | bigint | string | CanonicalChain;
+/** Unified front door: number/bigint -> chainById, string -> chainBySlug then chainByAlias, CanonicalChain -> identity. */
+export declare function resolveChain(ref: ChainRef): CanonicalChain | undefined;
+/** `resolveChain` or throw, mirroring `requireV12Deployment`'s existing throw-with-the-known-set style. */
+export declare function requireChain(ref: ChainRef): CanonicalChain;
+/** Resolves `ref` then tests `kind === 'evm'`. False for an unresolvable ref. */
+export declare function isEvm(ref: ChainRef): boolean;
+/** Resolves `ref` then tests `kind === 'svm'`. False for an unresolvable ref. */
+export declare function isSvm(ref: ChainRef): boolean;
+/** Narrowing guard for a value already resolved. */
+export declare function isEvmChain(c: CanonicalChain): c is CanonicalChain & {
+    kind: "evm";
+};
+/** Narrowing guard for a value already resolved. */
+export declare function isSvmChain(c: CanonicalChain): c is CanonicalChain & {
+    kind: "svm";
+};
+/** Every EVM chain, id-ascending. */
+export declare function evmChains(): CanonicalChain[];
+/** Every SVM chain, id-ascending. */
+export declare function svmChains(): CanonicalChain[];
+/** Every slug, id-ascending — for building the fluent accessor's key set. */
+export declare function canonicalChainSlugs(): ChainSlug[];
+//# sourceMappingURL=canonical.d.ts.map

package/sdk/dist/chains/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/chains/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;AAEtC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gHAAgH;IAChH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6GAA6G;IAC7G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,6GAA6G;IAC7G,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwEiB,CAAC;AAE/C,yGAAyG;AACzG,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,oDAAoD;AACpD,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAAqB,CAAC;AAM3E,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKvD;AAWD,uCAAuC;AACvC,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEhE;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEpE;AAED,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED;uEACuE;AACvE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;AAEjE,2HAA2H;AAC3H,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS,CAUtE;AAED,2GAA2G;AAC3G,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,cAAc,CAO1D;AAED,iFAAiF;AACjF,wBAAgB,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAE5C;AAED,iFAAiF;AACjF,wBAAgB,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAE5C;AAED,oDAAoD;AACpD,wBAAgB,UAAU,CAAC,CAAC,EAAE,cAAc,GAAG,CAAC,IAAI,cAAc,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAEnF;AAED,oDAAoD;AACpD,wBAAgB,UAAU,CAAC,CAAC,EAAE,cAAc,GAAG,CAAC,IAAI,cAAc,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAEnF;AAED,qCAAqC;AACrC,wBAAgB,SAAS,IAAI,cAAc,EAAE,CAK5C;AAED,qCAAqC;AACrC,wBAAgB,SAAS,IAAI,cAAc,EAAE,CAK5C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,SAAS,EAAE,CAIjD"}

package/sdk/dist/chains/canonical.js

@@ -0,0 +1,191 @@
+/**
+ * CANONICAL CHAIN REGISTRY — identity only, additive, zero runtime coupling.
+ *
+ * `chains` (./index.ts) is EVM-only and has no `slug`; `../deployments/` knows
+ * chain SLUGS but only for the 12 chains in the v12 deploy record, and only
+ * gated on whether the stack is LIVE there. Neither answers the plain question
+ * "what is this chain called, and what kind of VM does it run" for the full
+ * union — including the 5 v12-only EVM chains and Solana, which have no
+ * `chains` entry at all.
+ *
+ * This module is a flat, hand-maintained data table answering exactly that
+ * question, for both EVM and SVM chains in ONE numeric id space. It carries no
+ * rpcUrls / nativeCurrency / blockExplorerUrls / testnet — those already live on
+ * `chains` for the ids that have them; a consumer needing that data still goes
+ * through `getChain(id)`, which returns `undefined` for the 5 v12-only EVM
+ * chains and for Solana.
+ *
+ * Deliberately NOT wired to `../deployments/` or `../protocols/` — no import
+ * cycle, no runtime coupling. `v12ChainSlug`/`v12LiveChainSlugs` answer
+ * "can I cook here", a LIVENESS question; this module answers "what is this
+ * chain called", an IDENTITY question. Ronin (2020) is registered here even
+ * though its v12 deploy failed — see `test/chains-canonical.test.ts` for the
+ * pinned proof that the two layers are intentionally decoupled.
+ *
+ * MAINTENANCE NOTE: this table is hand-maintained, not derived. A chain added
+ * to `chains` (./index.ts) or to `V12_EVM_CHAINS` (../deployments/v12.generated.ts,
+ * rewritten by `sync-engine-artifacts` on every engine repin) will fail
+ * `test/chains-canonical.test.ts` until a matching entry is added here — that is
+ * the intended fail-closed behavior, not a test to relax.
+ */
+export const CANONICAL_CHAINS = [
+    // --- EVM, present in `chains` AND in the v12 deploy record (7) — slug === V12_EVM_CHAINS[id].name ---
+    { id: 1, slug: "ethereum", name: "Ethereum", kind: "evm", aliases: ["mainnet", "eth"] },
+    { id: 10, slug: "optimism", name: "Optimism", kind: "evm", aliases: ["op", "op-mainnet"] },
+    {
+        id: 56,
+        slug: "bsc",
+        name: "BNB Chain",
+        kind: "evm",
+        aliases: ["bnb", "binance-smart-chain", "bnb-smart-chain"],
+    },
+    { id: 137, slug: "polygon", name: "Polygon", kind: "evm", aliases: ["matic", "polygon-pos"] },
+    { id: 8453, slug: "base", name: "Base", kind: "evm", aliases: [] },
+    { id: 42161, slug: "arbitrum", name: "Arbitrum One", kind: "evm", aliases: ["arb"] },
+    { id: 42220, slug: "celo", name: "Celo", kind: "evm", aliases: [] },
+    // --- EVM, present only in `chains` (26) ---
+    { id: 25, slug: "cronos", name: "Cronos", kind: "evm", aliases: ["cro"] },
+    { id: 100, slug: "gnosis", name: "Gnosis", kind: "evm", aliases: ["xdai", "gnosis-chain"] },
+    { id: 122, slug: "fuse", name: "Fuse", kind: "evm", aliases: [] },
+    { id: 169, slug: "manta", name: "Manta Pacific", kind: "evm", aliases: [] },
+    { id: 204, slug: "opbnb", name: "opBNB", kind: "evm", aliases: [] },
+    {
+        id: 250,
+        slug: "fantom",
+        name: "Fantom",
+        kind: "evm",
+        aliases: ["ftm", "opera", "fantom-opera"],
+    },
+    { id: 288, slug: "boba", name: "Boba", kind: "evm", aliases: ["boba-network"] },
+    { id: 324, slug: "zksync", name: "zkSync Era", kind: "evm", aliases: [] },
+    { id: 369, slug: "pulsechain", name: "PulseChain", kind: "evm", aliases: ["pls"] },
+    {
+        id: 1088,
+        slug: "metis",
+        name: "Metis",
+        kind: "evm",
+        aliases: ["andromeda", "metis-andromeda"],
+    },
+    { id: 1116, slug: "core", name: "Core", kind: "evm", aliases: ["coredao", "core-dao"] },
+    { id: 1284, slug: "moonbeam", name: "Moonbeam", kind: "evm", aliases: [] },
+    { id: 1329, slug: "sei", name: "Sei", kind: "evm", aliases: ["sei-evm"] },
+    { id: 2222, slug: "kava", name: "Kava", kind: "evm", aliases: ["kava-evm"] },
+    { id: 5000, slug: "mantle", name: "Mantle", kind: "evm", aliases: [] },
+    { id: 7000, slug: "zetachain", name: "ZetaChain", kind: "evm", aliases: ["zeta"] },
+    { id: 8217, slug: "klaytn", name: "Klaytn", kind: "evm", aliases: ["kaia"] },
+    { id: 9001, slug: "evmos", name: "Evmos", kind: "evm", aliases: [] },
+    { id: 34443, slug: "mode", name: "Mode", kind: "evm", aliases: [] },
+    { id: 43114, slug: "avalanche", name: "Avalanche C-Chain", kind: "evm", aliases: ["avax"] },
+    { id: 59144, slug: "linea", name: "Linea", kind: "evm", aliases: [] },
+    { id: 80094, slug: "berachain", name: "Berachain", kind: "evm", aliases: ["bera"] },
+    { id: 81457, slug: "blast", name: "Blast", kind: "evm", aliases: [] },
+    { id: 534352, slug: "scroll", name: "Scroll", kind: "evm", aliases: [] },
+    { id: 7777777, slug: "zora", name: "Zora", kind: "evm", aliases: [] },
+    { id: 1313161554, slug: "aurora", name: "Aurora", kind: "evm", aliases: [] },
+    // --- EVM, present only in V12_EVM_CHAINS (6) — NOT in `chains`; slug copied from the deploy record ---
+    { id: 130, slug: "unichain", name: "Unichain", kind: "evm", aliases: [] },
+    { id: 143, slug: "monad", name: "Monad", kind: "evm", aliases: [] },
+    { id: 146, slug: "sonic", name: "Sonic", kind: "evm", aliases: [] },
+    { id: 2020, slug: "ronin", name: "Ronin", kind: "evm", aliases: [] },
+    { id: 9745, slug: "plasma", name: "Plasma", kind: "evm", aliases: [] },
+    { id: 57073, slug: "ink", name: "Ink", kind: "evm", aliases: [] },
+    // --- SVM (1) ---
+    {
+        id: 1399811149,
+        slug: "solana",
+        name: "Solana",
+        kind: "svm",
+        aliases: ["sol", "mainnet-beta", "solana-mainnet"],
+    },
+];
+/** Widened alias for ordinary iteration/mapping. */
+export const canonicalChains = CANONICAL_CHAINS;
+const byId = new Map(canonicalChains.map((c) => [c.id, c]));
+const bySlug = new Map(canonicalChains.map((c) => [c.slug, c]));
+/** The ONE normalizer: lowercased, trimmed, punctuation/whitespace stripped. */
+export function normalizeChainKey(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, "");
+}
+const byAlias = new Map();
+for (const c of canonicalChains) {
+    byAlias.set(normalizeChainKey(c.slug), c);
+    byAlias.set(normalizeChainKey(c.name), c);
+    for (const alias of c.aliases) {
+        byAlias.set(normalizeChainKey(alias), c);
+    }
+}
+/** O(1) lookup by numeric chain id. */
+export function chainById(id) {
+    return byId.get(id);
+}
+/** Exact slug match only (no normalization) — for callers that already hold a canonical slug. */
+export function chainBySlug(slug) {
+    return bySlug.get(slug);
+}
+/** Normalized lookup across slug + name + aliases — resolves a human/legacy chain-name string. */
+export function chainByAlias(nameOrAlias) {
+    return byAlias.get(normalizeChainKey(nameOrAlias));
+}
+/** Unified front door: number/bigint -> chainById, string -> chainBySlug then chainByAlias, CanonicalChain -> identity. */
+export function resolveChain(ref) {
+    if (typeof ref === "number")
+        return chainById(ref);
+    // eco-routes chain ids are natively bigint (e.g. Solana 1399811149n); accept
+    // them here so an svm id resolves to its svm record instead of falling
+    // through to the object case and silently mis-classifying as evm downstream.
+    if (typeof ref === "bigint") {
+        return ref >= 0n && ref <= BigInt(Number.MAX_SAFE_INTEGER) ? chainById(Number(ref)) : undefined;
+    }
+    if (typeof ref === "string")
+        return chainBySlug(ref) ?? chainByAlias(ref);
+    return typeof ref === "object" && ref !== null ? ref : undefined;
+}
+/** `resolveChain` or throw, mirroring `requireV12Deployment`'s existing throw-with-the-known-set style. */
+export function requireChain(ref) {
+    const found = resolveChain(ref);
+    if (found === undefined) {
+        const known = canonicalChains.map((c) => c.slug).join(", ");
+        throw new Error(`Unknown chain '${String(ref)}' (known slugs: ${known})`);
+    }
+    return found;
+}
+/** Resolves `ref` then tests `kind === 'evm'`. False for an unresolvable ref. */
+export function isEvm(ref) {
+    return resolveChain(ref)?.kind === "evm";
+}
+/** Resolves `ref` then tests `kind === 'svm'`. False for an unresolvable ref. */
+export function isSvm(ref) {
+    return resolveChain(ref)?.kind === "svm";
+}
+/** Narrowing guard for a value already resolved. */
+export function isEvmChain(c) {
+    return c.kind === "evm";
+}
+/** Narrowing guard for a value already resolved. */
+export function isSvmChain(c) {
+    return c.kind === "svm";
+}
+/** Every EVM chain, id-ascending. */
+export function evmChains() {
+    return canonicalChains
+        .filter(isEvmChain)
+        .slice()
+        .sort((a, b) => a.id - b.id);
+}
+/** Every SVM chain, id-ascending. */
+export function svmChains() {
+    return canonicalChains
+        .filter(isSvmChain)
+        .slice()
+        .sort((a, b) => a.id - b.id);
+}
+/** Every slug, id-ascending — for building the fluent accessor's key set. */
+export function canonicalChainSlugs() {
+    return CANONICAL_CHAINS.slice()
+        .sort((a, b) => a.id - b.id)
+        .map((c) => c.slug);
+}
+//# sourceMappingURL=canonical.js.map

package/sdk/dist/chains/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/chains/canonical.ts"],"names":[],"mappings":"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"}

package/sdk/dist/chains/index.d.ts

@@ -0,0 +1,7 @@
+import type { Chain } from "../core/types.js";
+/** All supported EVM chains */
+export declare const chains: Record<number, Chain>;
+export declare function getChain(chainId: number): Chain | undefined;
+export declare function getAllChainIds(): number[];
+export * from "./canonical.js";
+//# sourceMappingURL=index.d.ts.map

package/sdk/dist/chains/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chains/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,+BAA+B;AAC/B,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CA4QxC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAE3D;AAED,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,cAAc,gBAAgB,CAAC"}