@b3dotfun/sdk 0.1.70-alpha.2 → 0.1.70-alpha.21

package/node_modules/@b3/chain-registry/src/index.ts

@@ -0,0 +1,672 @@
+import chainsData from "../chains.json" with { type: "json" };
+
+export interface ManualToken {
+  address: `0x${string}`;
+  symbol: string;
+  decimals: number;
+  name: string;
+  logoUrl?: string;
+}
+
+/**
+ * Known integration tags that can appear in `ChainDefinition.integrations`.
+ * Adding a new integration → extend this union. Consumers calling
+ * `chainsByIntegration("foo")` get autocomplete + typo safety.
+ */
+export type KnownIntegration =
+  | "aerodrome"
+  | "anyspend"
+  | "cow-swap"
+  | "evm-log"
+  | "morpho"
+  | "railgun"
+  | "x402"
+  | "zerodev";
+
+/** A chain's canonical/hub stablecoin(s). Bounded (1–3 per chain), not a general token registry —
+ *  the first entry is the chain's primary quote stablecoin. */
+export interface StablecoinRef {
+  symbol: string;
+  address: string;
+}
+
+export interface ChainDefinition {
+  chainId: number;
+  key: string;
+  name: string;
+  network: string;
+  /**
+   * DexScreener API chain id. Set explicitly for every registry chain known to
+   * be supported, even when equal to `network`; absence leaves provider routing
+   * opaque instead of guessing a slug.
+   */
+  dexscreenerNetwork?: string;
+  type: "evm" | "solana";
+  isTestnet: boolean;
+  integrations: KnownIntegration[];
+  /** Canonical stablecoins on this chain; `stablecoins[0]` is the hub. Optional — filled per chain
+   *  as needed (Robinhood/4663 → USDG for B3-5081). TS-only; Go does not consume it. */
+  stablecoins?: StablecoinRef[];
+  nativeCurrency: {
+    name: string;
+    symbol: string;
+    decimals: number;
+  };
+  explorer: string;
+  rpcEnvKey: string | null;
+  fallbackRpc: string | null;
+  quicknodeSlug: string | null;
+  quicknodeRpcPath?: string;
+  coingecko: {
+    platform: string;
+    nativeCoinId: string;
+  } | null;
+  /**
+   * GeckoTerminal network slug (differs from `coingecko.platform`: GT uses
+   * "eth", CoinGecko uses "ethereum"). Used for on-chain pool lookups and
+   * OHLCV charts. Null when GeckoTerminal does not index this chain.
+   */
+  geckoTerminalNetwork?: string | null;
+  trustwalletSlug: string | null;
+  logoUrl: string | null;
+  tags: string[];
+  manualTokens?: ManualToken[];
+  /**
+   * Wrapped-native token address (ERC-20 or SPL).
+   * Used for market lookups on the native coin and for DEX routing that needs
+   * a wrapped form of the gas token.
+   */
+  wrappedNative?: string;
+  wrappedNativeCurrency?: {
+    name: string;
+    symbol: string;
+    decimals: number;
+  };
+}
+
+export type TokenIdentityKind = "native" | "wrapped-native" | "contract";
+export type TokenIdentityMatch = "canonical" | "exact" | "ranked";
+export type PairTokenSide = "base" | "quote";
+export const TOKEN_RESOLVER_SCHEMA_VERSION = 1 as const;
+
+export interface TokenResolverContractEnvelope {
+  schemaVersion: typeof TOKEN_RESOLVER_SCHEMA_VERSION;
+}
+
+export interface ResolvedTokenIdentity {
+  kind: TokenIdentityKind;
+  matchedBy: TokenIdentityMatch;
+  chainId: string;
+  address: string | null;
+  marketAddress: string;
+  name: string;
+  symbol: string;
+  nativeSymbol: string | null;
+}
+
+export interface TokenIdentityCandidate {
+  chainId: string;
+  /** DexScreener provider chain id used for follow-up market/detail requests. */
+  providerChainId?: string;
+  tokenAddress: string;
+  name: string;
+  symbol: string;
+  pairSide: PairTokenSide;
+  identity: ResolvedTokenIdentity;
+}
+
+export interface NativeAssetDefinition {
+  chainId: number;
+  chain: string;
+  dexscreenerChain: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+  wrapped: {
+    address: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+  };
+}
+
+export const chains: ChainDefinition[] = chainsData as unknown as ChainDefinition[];
+
+function chainIdentifierKey(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/-(?:chain|network|mainnet)$/, "");
+}
+
+const PROVIDER_CHAIN_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+export interface DexScreenerChainIdentity {
+  /** Canonical B3 chain id for known chains; opaque provider id otherwise. */
+  identityChainId: string;
+  /** Exact DexScreener path/query chain id. */
+  providerChainId: string;
+  chainType: ChainDefinition["type"] | null;
+  registryChainId: number | null;
+}
+
+let chainByIdentifier: ReadonlyMap<string, ChainDefinition> = new Map();
+
+export function resolveChainIdentifier(value: string): ChainDefinition | null {
+  return chainByIdentifier.get(chainIdentifierKey(value)) ?? null;
+}
+
+export function chainTypeForIdentifier(value: string): ChainDefinition["type"] | null {
+  return resolveChainIdentifier(value)?.type ?? null;
+}
+/**
+ * Translate any registry alias to its DexScreener id while preserving valid
+ * provider-native ids for chains the local registry does not know.
+ */
+export function resolveDexScreenerChainIdentifier(value: string): DexScreenerChainIdentity | null {
+  const chain = resolveChainIdentifier(value);
+  if (chain?.dexscreenerNetwork) {
+    return {
+      identityChainId: chain.network,
+      providerChainId: chain.dexscreenerNetwork.toLowerCase(),
+      chainType: chain.type,
+      registryChainId: chain.chainId,
+    };
+  }
+
+  // A registry chain that has not declared its DexScreener id is UNKNOWN, not opaque.
+  // Echoing the input back hands the caller a numeric chain id or a registry alias as if
+  // it were a provider slug, and DexScreener answers those with 200 + [].
+  if (chain) {
+    return null;
+  }
+
+  const providerChainId = value.trim().toLowerCase();
+  if (!PROVIDER_CHAIN_ID_PATTERN.test(providerChainId)) {
+    return null;
+  }
+  return {
+    identityChainId: providerChainId,
+    providerChainId,
+    chainType: null,
+    registryChainId: null,
+  };
+}
+
+export function validateChainDefinitions(
+  definitions: readonly ChainDefinition[],
+): ReadonlyMap<string, ChainDefinition> {
+  const identifiers = new Map<string, ChainDefinition>();
+  const chainIds = new Map<number, ChainDefinition>();
+
+  for (const chain of definitions) {
+    if (
+      !Number.isSafeInteger(chain.chainId) ||
+      chain.chainId <= 0 ||
+      !chain.key?.trim() ||
+      !chain.name?.trim() ||
+      !chain.network?.trim() ||
+      (chain.type !== "evm" && chain.type !== "solana")
+    ) {
+      throw new Error(`Invalid chain definition: ${JSON.stringify(chain)}`);
+    }
+
+    const existingChainId = chainIds.get(chain.chainId);
+    if (existingChainId && existingChainId.network !== chain.network) {
+      throw new Error(
+        `Chain id ${chain.chainId} is claimed by both "${existingChainId.network}" and "${chain.network}"`,
+      );
+    }
+    chainIds.set(chain.chainId, chain);
+
+    if (chain.dexscreenerNetwork && !PROVIDER_CHAIN_ID_PATTERN.test(chain.dexscreenerNetwork)) {
+      throw new Error(`Invalid DexScreener network for "${chain.network}": ${chain.dexscreenerNetwork}`);
+    }
+    if (chain.wrappedNative && tokenAddressFamily(chain.wrappedNative) !== chain.type) {
+      throw new Error(`Invalid wrapped-native address for "${chain.network}": ${chain.wrappedNative}`);
+    }
+    if (chain.wrappedNativeCurrency) {
+      if (
+        !chain.wrappedNative ||
+        !chain.dexscreenerNetwork?.trim() ||
+        !chain.wrappedNativeCurrency.name?.trim() ||
+        !chain.wrappedNativeCurrency.symbol?.trim() ||
+        !Number.isSafeInteger(chain.wrappedNativeCurrency.decimals) ||
+        chain.wrappedNativeCurrency.decimals < 0
+      ) {
+        throw new Error(`Incomplete wrapped-native metadata for "${chain.network}"`);
+      }
+    }
+
+    for (const identifier of [
+      chain.network,
+      chain.key,
+      chain.name,
+      String(chain.chainId),
+      ...(chain.dexscreenerNetwork ? [chain.dexscreenerNetwork] : []),
+    ]) {
+      const key = chainIdentifierKey(identifier);
+      const existing = identifiers.get(key);
+      if (existing && existing.chainId !== chain.chainId) {
+        throw new Error(`Chain identifier "${key}" is claimed by both "${existing.network}" and "${chain.network}"`);
+      }
+      identifiers.set(key, chain);
+    }
+  }
+
+  const productionSolana = definitions.filter(chain => chain.type === "solana" && !chain.isTestnet);
+  if (productionSolana.length !== 1) {
+    throw new Error(`Expected one production Solana definition, found ${productionSolana.length}`);
+  }
+  const solana = productionSolana[0];
+  if (
+    solana.chainId !== 7565164 ||
+    solana.network !== "solana" ||
+    solana.name !== "Solana" ||
+    solana.nativeCurrency.name !== "SOL" ||
+    solana.nativeCurrency.symbol !== "SOL" ||
+    solana.nativeCurrency.decimals !== 9 ||
+    solana.dexscreenerNetwork !== "solana" ||
+    solana.wrappedNative !== "So11111111111111111111111111111111111111112" ||
+    solana.wrappedNativeCurrency?.name !== "Wrapped SOL" ||
+    solana.wrappedNativeCurrency.symbol !== "wSOL" ||
+    solana.wrappedNativeCurrency.decimals !== 9
+  ) {
+    throw new Error("Canonical Solana SOL/wSOL metadata is invalid");
+  }
+
+  return identifiers;
+}
+
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const SOLANA_ADDRESS_PATTERN = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+function decodedBase58Length(value: string): number {
+  let leadingZeroBytes = 0;
+  while (value.charAt(leadingZeroBytes) === "1") {
+    leadingZeroBytes++;
+  }
+
+  let decoded = 0n;
+  for (let index = leadingZeroBytes; index < value.length; index++) {
+    decoded = decoded * 58n + BigInt(BASE58_ALPHABET.indexOf(value.charAt(index)));
+  }
+
+  let significantBytes = 0;
+  while (decoded > 0n) {
+    decoded >>= 8n;
+    significantBytes++;
+  }
+  return leadingZeroBytes + significantBytes;
+}
+
+export function isSolanaAddress(value: string): boolean {
+  return SOLANA_ADDRESS_PATTERN.test(value) && decodedBase58Length(value) === 32;
+}
+
+export function isEvmTokenAddress(value: string): boolean {
+  return /^0x[0-9a-fA-F]{40}$/.test(value);
+}
+
+export function tokenAddressFamily(value: string): ChainDefinition["type"] | null {
+  if (isEvmTokenAddress(value)) return "evm";
+  if (isSolanaAddress(value)) return "solana";
+  return null;
+}
+const OPAQUE_PROVIDER_TOKEN_PATTERN = /^[^\s\u0000-\u001F\u007F]{16,256}$/;
+const SHORT_NAMESPACED_TOKEN_PATTERN = /^[^\s\u0000-\u001F\u007F]{1,256}::[^\s\u0000-\u001F\u007F]+$/;
+
+/** Address/coin identifier accepted from a bounded DexScreener provider row. */
+export function isProviderTokenAddress(value: string): boolean {
+  if (value.length === 0 || value.length > 256) {
+    return false;
+  }
+  return (
+    tokenAddressFamily(value) !== null ||
+    OPAQUE_PROVIDER_TOKEN_PATTERN.test(value) ||
+    SHORT_NAMESPACED_TOKEN_PATTERN.test(value)
+  );
+}
+
+chainByIdentifier = validateChainDefinitions(chains);
+
+export const nativeAssets: readonly NativeAssetDefinition[] = chains.flatMap(chain => {
+  if (chain.isTestnet || !chain.dexscreenerNetwork || !chain.wrappedNative || !chain.wrappedNativeCurrency) {
+    return [];
+  }
+
+  return [
+    {
+      chainId: chain.chainId,
+      chain: chain.network,
+      dexscreenerChain: chain.dexscreenerNetwork,
+      name: chain.name,
+      symbol: chain.nativeCurrency.symbol,
+      decimals: chain.nativeCurrency.decimals,
+      wrapped: {
+        address: chain.wrappedNative,
+        name: chain.wrappedNativeCurrency.name,
+        symbol: chain.wrappedNativeCurrency.symbol,
+        decimals: chain.wrappedNativeCurrency.decimals,
+      },
+    },
+  ];
+});
+
+/** Solana asset identities whose ticker/name may short-circuit text search.
+ * Deliberately narrower than `nativeAssets`: B3-5071 must not change EVM
+ * ticker routing while establishing canonical SOL/wSOL resolution. */
+export const CANONICAL_NAME_ASSETS: readonly NativeAssetDefinition[] = nativeAssets.filter(
+  asset => asset.chain === "solana",
+);
+
+export function matchCanonicalNativeAssetText(
+  asset: NativeAssetDefinition,
+  value: string,
+): "native" | "wrapped-native" | null {
+  const normalized = value.trim().replace(/^\$/, "").toLowerCase();
+  if (normalized === asset.symbol.toLowerCase() || normalized === asset.name.toLowerCase()) {
+    return "native";
+  }
+  if (normalized === asset.wrapped.symbol.toLowerCase() || normalized === asset.wrapped.name.toLowerCase()) {
+    return "wrapped-native";
+  }
+  return null;
+}
+
+const solanaNativeAsset = nativeAssets.find(asset => asset.chain === "solana");
+if (!solanaNativeAsset) {
+  throw new Error("SOLANA native asset definition missing");
+}
+export const SOLANA_NATIVE_ASSET: NativeAssetDefinition = solanaNativeAsset;
+
+export function createNativeTokenIdentity(asset: NativeAssetDefinition): ResolvedTokenIdentity {
+  return {
+    kind: "native",
+    matchedBy: "canonical",
+    chainId: asset.chain,
+    address: null,
+    marketAddress: asset.wrapped.address,
+    name: asset.name,
+    symbol: asset.symbol,
+    nativeSymbol: asset.symbol,
+  };
+}
+
+export function createWrappedNativeTokenIdentity(
+  asset: NativeAssetDefinition,
+  matchedBy: "canonical" | "exact",
+): ResolvedTokenIdentity {
+  return {
+    kind: "wrapped-native",
+    matchedBy,
+    chainId: asset.chain,
+    address: asset.wrapped.address,
+    marketAddress: asset.wrapped.address,
+    name: asset.wrapped.name,
+    symbol: asset.wrapped.symbol,
+    nativeSymbol: asset.symbol,
+  };
+}
+
+export function looksLikeTokenAddress(value: string): boolean {
+  return tokenAddressFamily(value) !== null;
+}
+
+/**
+ * User input likely to be a provider token address. Canonical EVM/Solana
+ * formats and explicit namespaced coin types qualify; arbitrary long labels do not.
+ */
+export function looksLikeProviderTokenAddress(value: string): boolean {
+  if (looksLikeTokenAddress(value)) {
+    return true;
+  }
+  return SHORT_NAMESPACED_TOKEN_PATTERN.test(value);
+}
+
+export function isTokenAddressForChain(chainId: string, value: string): boolean {
+  const chainType = chainTypeForIdentifier(chainId);
+  return chainType !== null && tokenAddressFamily(value) === chainType;
+}
+
+export function tokenAddressKey(chainId: string, value: string): string {
+  const chainType = chainTypeForIdentifier(chainId);
+  return chainType === "evm" || (chainType === null && isEvmTokenAddress(value)) ? value.toLowerCase() : value;
+}
+
+export function isResolvedTokenIdentity(value: unknown): value is ResolvedTokenIdentity {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const identity = value as Record<string, unknown>;
+  if (
+    !["native", "wrapped-native", "contract"].includes(identity.kind as string) ||
+    !["canonical", "exact", "ranked"].includes(identity.matchedBy as string) ||
+    typeof identity.chainId !== "string" ||
+    resolveDexScreenerChainIdentifier(identity.chainId) === null ||
+    typeof identity.marketAddress !== "string" ||
+    !isProviderTokenAddress(identity.marketAddress) ||
+    typeof identity.name !== "string" ||
+    identity.name.trim().length === 0 ||
+    typeof identity.symbol !== "string" ||
+    identity.symbol.trim().length === 0
+  ) {
+    return false;
+  }
+
+  const chainType = chainTypeForIdentifier(identity.chainId);
+  if (chainType && tokenAddressFamily(identity.marketAddress) !== chainType) {
+    return false;
+  }
+
+  if (identity.kind === "native") {
+    return (
+      identity.matchedBy === "canonical" &&
+      identity.address === null &&
+      typeof identity.nativeSymbol === "string" &&
+      identity.nativeSymbol.trim().length > 0
+    );
+  }
+
+  if (identity.kind === "wrapped-native") {
+    return (
+      (identity.matchedBy === "canonical" || identity.matchedBy === "exact") &&
+      typeof identity.address === "string" &&
+      isProviderTokenAddress(identity.address) &&
+      (!chainType || tokenAddressFamily(identity.address) === chainType) &&
+      tokenAddressKey(identity.chainId, identity.address) ===
+        tokenAddressKey(identity.chainId, identity.marketAddress) &&
+      typeof identity.nativeSymbol === "string" &&
+      identity.nativeSymbol.trim().length > 0
+    );
+  }
+
+  return (
+    (identity.matchedBy === "exact" || identity.matchedBy === "ranked") &&
+    typeof identity.address === "string" &&
+    isProviderTokenAddress(identity.address) &&
+    (!chainType || tokenAddressFamily(identity.address) === chainType) &&
+    tokenAddressKey(identity.chainId, identity.address) === tokenAddressKey(identity.chainId, identity.marketAddress) &&
+    identity.nativeSymbol === null
+  );
+}
+
+export function isRegistryResolvedTokenIdentity(value: unknown): value is ResolvedTokenIdentity {
+  if (!isResolvedTokenIdentity(value)) {
+    return false;
+  }
+
+  if (value.kind === "native") {
+    return nativeAssets.some(
+      asset =>
+        value.chainId === asset.chain &&
+        tokenAddressKey(asset.chain, value.marketAddress) === tokenAddressKey(asset.chain, asset.wrapped.address) &&
+        value.name === asset.name &&
+        value.symbol === asset.symbol &&
+        value.nativeSymbol === asset.symbol,
+    );
+  }
+
+  if (value.kind === "wrapped-native") {
+    const address = value.address;
+    if (typeof address !== "string") {
+      return false;
+    }
+    return nativeAssets.some(
+      asset =>
+        value.chainId === asset.chain &&
+        tokenAddressKey(asset.chain, address) === tokenAddressKey(asset.chain, asset.wrapped.address) &&
+        tokenAddressKey(asset.chain, value.marketAddress) === tokenAddressKey(asset.chain, asset.wrapped.address) &&
+        value.name === asset.wrapped.name &&
+        value.symbol === asset.wrapped.symbol &&
+        value.nativeSymbol === asset.symbol,
+    );
+  }
+
+  const chainType = chainTypeForIdentifier(value.chainId);
+  return (
+    (!chainType || tokenAddressFamily(value.marketAddress) === chainType) &&
+    !nativeAssets.some(
+      asset =>
+        value.chainId === asset.chain &&
+        tokenAddressKey(asset.chain, value.marketAddress) === tokenAddressKey(asset.chain, asset.wrapped.address),
+    )
+  );
+}
+
+export function isTokenIdentityCandidate(value: unknown): value is TokenIdentityCandidate {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  const identity = candidate.identity;
+  if (!isResolvedTokenIdentity(identity)) {
+    return false;
+  }
+
+  const chainType = chainTypeForIdentifier(identity.chainId);
+  return (
+    (!("providerChainId" in candidate) ||
+      (typeof candidate.providerChainId === "string" && candidate.providerChainId.trim().length > 0)) &&
+    (candidate.pairSide === "base" || candidate.pairSide === "quote") &&
+    candidate.chainId === identity.chainId &&
+    typeof candidate.tokenAddress === "string" &&
+    isProviderTokenAddress(candidate.tokenAddress) &&
+    (!chainType || tokenAddressFamily(candidate.tokenAddress) === chainType) &&
+    tokenAddressKey(identity.chainId, candidate.tokenAddress) ===
+      tokenAddressKey(identity.chainId, identity.marketAddress) &&
+    candidate.name === identity.name &&
+    candidate.symbol === identity.symbol
+  );
+}
+
+export function isRegistryTokenIdentityCandidate(value: unknown): value is TokenIdentityCandidate {
+  return isTokenIdentityCandidate(value) && isRegistryResolvedTokenIdentity(value.identity);
+}
+
+export const evmChains = chains.filter(c => c.type === "evm");
+
+export const chainById = new Map(chains.map(c => [c.chainId, c]));
+
+export const CHAIN_IDS: Record<string, number> = Object.fromEntries(chains.map(c => [c.key, c.chainId]));
+
+export const CHAIN_NAMES: Record<number, string> = Object.fromEntries(chains.map(c => [c.chainId, c.name]));
+
+export const CHAIN_ID_TO_NETWORK: Record<number, string> = Object.fromEntries(chains.map(c => [c.chainId, c.network]));
+
+export const FALLBACK_RPC_URLS: Record<number, string> = Object.fromEntries(
+  chains.filter(c => c.fallbackRpc).map(c => [c.chainId, c.fallbackRpc!]),
+);
+
+export const BLOCK_EXPLORERS: Record<number, string> = Object.fromEntries(chains.map(c => [c.chainId, c.explorer]));
+
+export const COINGECKO_MAPPINGS: Record<number, { platform: string; nativeCoinId: string }> = Object.fromEntries(
+  chains.filter(c => c.coingecko).map(c => [c.chainId, c.coingecko!]),
+);
+
+export const TRUSTWALLET_SLUGS: Record<number, string> = Object.fromEntries(
+  chains.filter(c => c.trustwalletSlug).map(c => [c.chainId, c.trustwalletSlug!]),
+);
+
+export const CHAIN_TAG_MAP: Record<string, number> = Object.fromEntries(
+  chains.flatMap(c => c.tags.map(tag => [tag, c.chainId])),
+);
+
+export const LOGO_URLS: Record<number, string> = Object.fromEntries(
+  chains.filter(c => c.logoUrl).map(c => [c.chainId, c.logoUrl!]),
+);
+
+export function buildQuicknodeUrl(subdomain: string, key: string, chain: ChainDefinition): string | null {
+  if (chain.quicknodeSlug === null) return null;
+  const network = chain.quicknodeSlug === "" ? "" : `.${chain.quicknodeSlug}`;
+  const path = chain.quicknodeRpcPath ?? "";
+  return `https://${subdomain}${network}.quiknode.pro/${key}${path}`;
+}
+
+export function buildQuicknodeRpcMap(subdomain: string, key: string): Record<number, string> {
+  return Object.fromEntries(
+    chains.filter(c => c.quicknodeSlug !== null).map(c => [c.chainId, buildQuicknodeUrl(subdomain, key, c)!]),
+  );
+}
+
+export function chainsByIntegration(integration: KnownIntegration): ChainDefinition[] {
+  return chains.filter(c => c.integrations.includes(integration));
+}
+
+export function chainIdsByIntegration(integration: KnownIntegration): number[] {
+  return chainsByIntegration(integration).map(c => c.chainId);
+}
+
+export function chainNamesByIntegration(integration: KnownIntegration): Record<number, string> {
+  return Object.fromEntries(chainsByIntegration(integration).map(c => [c.chainId, c.name]));
+}
+
+export const ZERODEV_SUPPORTED_CHAINS: ChainDefinition[] = chainsByIntegration("zerodev");
+
+/**
+ * Chains tagged with the "anyspend" integration AND of EVM type — the set
+ * consumed by SDK `supportedChains` / `supportedChainsTW` for AnySpend's
+ * wallet-switch gate (`useUnifiedChainSwitchAndExecute`). Solana (also tagged
+ * anyspend) is excluded here because it's handled by Phantom-based flows that
+ * key off `RELAY_SOLANA_MAINNET_CHAIN_ID`, not viem.
+ */
+export const ANYSPEND_EVM_CHAINS: ChainDefinition[] = chainsByIntegration("anyspend").filter(c => c.type === "evm");
+
+// Validate at module init: every anyspend EVM chain must have a fallbackRpc.
+// The SDK transformers (toViemChain / toThirdwebChain) assume this invariant
+// holds — catching a missing RPC here is far better than throwing on first
+// pay-button click in production.
+{
+  const missingRpc = ANYSPEND_EVM_CHAINS.filter(c => !c.fallbackRpc);
+  if (missingRpc.length > 0) {
+    throw new Error(
+      `chain-registry: anyspend EVM chains missing fallbackRpc: ${missingRpc.map(c => `${c.chainId} (${c.key})`).join(", ")}`,
+    );
+  }
+}
+
+/**
+ * Chain IDs that declare `manualTokens` — their holdings must be enumerated
+ * from that list rather than discovered, so balance/metadata for them comes
+ * from RPC + CoinGecko instead of a portfolio indexer.
+ */
+export const MANUAL_CHAIN_IDS: ReadonlySet<number> = new Set(
+  chains.filter(c => c.manualTokens && c.manualTokens.length > 0).map(c => c.chainId),
+);
+
+export function hasManualTokens(chainId: number): boolean {
+  return MANUAL_CHAIN_IDS.has(chainId);
+}
+
+export function getManualTokens(chainId: number): ManualToken[] {
+  return chainById.get(chainId)?.manualTokens ?? [];
+}
+
+export function findManualToken(chainId: number, address: string): ManualToken | null {
+  const lower = address.toLowerCase();
+  const tokens = getManualTokens(chainId);
+  return tokens.find(t => t.address.toLowerCase() === lower) ?? null;
+}