@elizaos/app-core 2.0.0-alpha.10

package/src/components/avatar/mixamoVRMRigMap.ts

@@ -0,0 +1,62 @@
+import type { VRMHumanBoneName } from "@pixiv/three-vrm";
+
+// Mixamo -> VRM humanoid bone mapping.
+// Keys are normalized to `mixamorig<JointName>`.
+export const mixamoVRMRigMap: Record<string, VRMHumanBoneName> = {
+  mixamorigHips: "hips",
+  mixamorigSpine: "spine",
+  mixamorigSpine1: "chest",
+  mixamorigSpine2: "upperChest",
+  mixamorigNeck: "neck",
+  mixamorigHead: "head",
+
+  mixamorigLeftShoulder: "leftShoulder",
+  mixamorigLeftArm: "leftUpperArm",
+  mixamorigLeftForeArm: "leftLowerArm",
+  mixamorigLeftHand: "leftHand",
+  mixamorigLeftHandThumb1: "leftThumbMetacarpal",
+  mixamorigLeftHandThumb2: "leftThumbProximal",
+  mixamorigLeftHandThumb3: "leftThumbDistal",
+  mixamorigLeftHandIndex1: "leftIndexProximal",
+  mixamorigLeftHandIndex2: "leftIndexIntermediate",
+  mixamorigLeftHandIndex3: "leftIndexDistal",
+  mixamorigLeftHandMiddle1: "leftMiddleProximal",
+  mixamorigLeftHandMiddle2: "leftMiddleIntermediate",
+  mixamorigLeftHandMiddle3: "leftMiddleDistal",
+  mixamorigLeftHandRing1: "leftRingProximal",
+  mixamorigLeftHandRing2: "leftRingIntermediate",
+  mixamorigLeftHandRing3: "leftRingDistal",
+  mixamorigLeftHandPinky1: "leftLittleProximal",
+  mixamorigLeftHandPinky2: "leftLittleIntermediate",
+  mixamorigLeftHandPinky3: "leftLittleDistal",
+
+  mixamorigRightShoulder: "rightShoulder",
+  mixamorigRightArm: "rightUpperArm",
+  mixamorigRightForeArm: "rightLowerArm",
+  mixamorigRightHand: "rightHand",
+  mixamorigRightHandPinky1: "rightLittleProximal",
+  mixamorigRightHandPinky2: "rightLittleIntermediate",
+  mixamorigRightHandPinky3: "rightLittleDistal",
+  mixamorigRightHandRing1: "rightRingProximal",
+  mixamorigRightHandRing2: "rightRingIntermediate",
+  mixamorigRightHandRing3: "rightRingDistal",
+  mixamorigRightHandMiddle1: "rightMiddleProximal",
+  mixamorigRightHandMiddle2: "rightMiddleIntermediate",
+  mixamorigRightHandMiddle3: "rightMiddleDistal",
+  mixamorigRightHandIndex1: "rightIndexProximal",
+  mixamorigRightHandIndex2: "rightIndexIntermediate",
+  mixamorigRightHandIndex3: "rightIndexDistal",
+  mixamorigRightHandThumb1: "rightThumbMetacarpal",
+  mixamorigRightHandThumb2: "rightThumbProximal",
+  mixamorigRightHandThumb3: "rightThumbDistal",
+
+  mixamorigLeftUpLeg: "leftUpperLeg",
+  mixamorigLeftLeg: "leftLowerLeg",
+  mixamorigLeftFoot: "leftFoot",
+  mixamorigLeftToeBase: "leftToes",
+
+  mixamorigRightUpLeg: "rightUpperLeg",
+  mixamorigRightLeg: "rightLowerLeg",
+  mixamorigRightFoot: "rightFoot",
+  mixamorigRightToeBase: "rightToes",
+};

package/src/components/avatar/retargetMixamoFbxToVrm.ts

@@ -0,0 +1,144 @@
+import type { VRM, VRMHumanBoneName } from "@pixiv/three-vrm";
+import * as THREE from "three";
+import { mixamoVRMRigMap } from "./mixamoVRMRigMap";
+
+function normalizeMixamoRigName(name: string): string {
+  const pipe = name.lastIndexOf("|");
+  const base = pipe >= 0 ? name.slice(pipe + 1) : name;
+  const colon = base.indexOf(":");
+  if (colon >= 0) {
+    const ns = base.slice(0, colon);
+    const rest = base.slice(colon + 1);
+    if (ns === "mixamorig") return `mixamorig${rest}`;
+    return rest;
+  }
+  return base;
+}
+
+function isVrm0(vrm: VRM): boolean {
+  const mv = String(vrm.meta?.metaVersion ?? "");
+  return mv.startsWith("0");
+}
+
+function findNode(
+  scene: THREE.Object3D,
+  rawName: string,
+  normalizedName: string,
+): THREE.Object3D | null {
+  return (
+    scene.getObjectByName(rawName) ??
+    scene.getObjectByName(normalizedName) ??
+    scene.getObjectByName(
+      rawName.includes(":") ? (rawName.split(":")[1] ?? rawName) : rawName,
+    ) ??
+    null
+  );
+}
+
+/**
+ * Retarget a Mixamo FBX animation clip onto a VRM.
+ * Quaternion tracks are converted into VRM space and position tracks are
+ * scaled by hips height ratio.
+ */
+export function retargetMixamoFbxToVrm(
+  sourceScene: THREE.Group,
+  sourceClip: THREE.AnimationClip,
+  vrm: VRM,
+): THREE.AnimationClip {
+  sourceScene.updateMatrixWorld(true);
+  vrm.scene.updateMatrixWorld(true);
+
+  const tracks: THREE.KeyframeTrack[] = [];
+  const restRotationInverse = new THREE.Quaternion();
+  const parentRestWorldRotation = new THREE.Quaternion();
+  const q = new THREE.Quaternion();
+
+  const motionHipsNode = findNode(
+    sourceScene,
+    "mixamorigHips",
+    "mixamorigHips",
+  );
+  const motionHipsHeight = Math.abs(motionHipsNode?.position.y ?? 0);
+  const vrmHipsHeight = Math.abs(
+    vrm.humanoid?.normalizedRestPose.hips?.position?.[1] ?? 0,
+  );
+  const hipsPositionScale =
+    motionHipsHeight > 1e-6 && vrmHipsHeight > 1e-6
+      ? vrmHipsHeight / motionHipsHeight
+      : 1;
+
+  for (const track of sourceClip.tracks) {
+    const parts = track.name.split(".");
+    const rawRigName = parts[0];
+    const propertyName = parts[1];
+    if (!rawRigName || !propertyName) continue;
+    const normalizedRigName = normalizeMixamoRigName(rawRigName);
+    const vrmBoneName = mixamoVRMRigMap[normalizedRigName];
+    if (!vrmBoneName) continue;
+
+    const vrmNode = vrm.humanoid?.getNormalizedBoneNode(
+      vrmBoneName as VRMHumanBoneName,
+    );
+    if (!vrmNode) continue;
+
+    const mixamoRigNode = findNode(sourceScene, rawRigName, normalizedRigName);
+    if (!mixamoRigNode || !mixamoRigNode.parent) continue;
+
+    mixamoRigNode.getWorldQuaternion(restRotationInverse).invert();
+    mixamoRigNode.parent.getWorldQuaternion(parentRestWorldRotation);
+
+    if (
+      propertyName === "quaternion" &&
+      track instanceof THREE.QuaternionKeyframeTrack
+    ) {
+      const values = track.values.slice();
+      for (let i = 0; i < values.length; i += 4) {
+        q.fromArray(values, i);
+        q.premultiply(parentRestWorldRotation).multiply(restRotationInverse);
+        q.toArray(values, i);
+      }
+
+      tracks.push(
+        new THREE.QuaternionKeyframeTrack(
+          `${vrmNode.name}.quaternion`,
+          track.times,
+          values.map((v, i) => (isVrm0(vrm) && i % 2 === 0 ? -v : v)),
+        ),
+      );
+      continue;
+    }
+
+    // Keep position-track behavior aligned with Girlfie runtime.
+    if (
+      propertyName === "position" &&
+      track instanceof THREE.VectorKeyframeTrack
+    ) {
+      const values = track.values.map(
+        (v, i) => (isVrm0(vrm) && i % 3 !== 1 ? -v : v) * hipsPositionScale,
+      );
+      tracks.push(
+        new THREE.VectorKeyframeTrack(
+          `${vrmNode.name}.position`,
+          track.times,
+          values,
+        ),
+      );
+    }
+  }
+
+  const hasHipsTrack = tracks.some((track) =>
+    track.name.startsWith(
+      `${vrm.humanoid?.getNormalizedBoneNode("hips" as VRMHumanBoneName)?.name ?? "__missing__"}.`,
+    ),
+  );
+  if (!hasHipsTrack) {
+    throw new Error(
+      `Idle FBX retargeting failed: no hips bone track found (mapped ${tracks.length} tracks). ` +
+        "Expected Mixamo bone names like mixamorigHips/mixamorigSpine...",
+    );
+  }
+
+  const clip = new THREE.AnimationClip("idle", sourceClip.duration, tracks);
+  clip.optimize();
+  return clip;
+}

package/src/components/avatar/retargetMixamoGltfToVrm.ts

@@ -0,0 +1,119 @@
+import type { VRM, VRMHumanBoneName } from "@pixiv/three-vrm";
+import * as THREE from "three";
+import { mixamoVRMRigMap } from "./mixamoVRMRigMap";
+
+function normalizeMixamoRigName(name: string): string {
+  const pipe = name.lastIndexOf("|");
+  const base = pipe >= 0 ? name.slice(pipe + 1) : name;
+  const colon = base.indexOf(":");
+  if (colon >= 0) {
+    const ns = base.slice(0, colon);
+    const rest = base.slice(colon + 1);
+    if (ns === "mixamorig") return `mixamorig${rest}`;
+    return rest;
+  }
+  return base;
+}
+
+function isVrm0(vrm: VRM): boolean {
+  const mv = String(vrm.meta?.metaVersion ?? "");
+  return mv.startsWith("0");
+}
+
+function findNode(
+  scene: THREE.Object3D,
+  rawName: string,
+  normalizedName: string,
+): THREE.Object3D | null {
+  return (
+    scene.getObjectByName(rawName) ??
+    scene.getObjectByName(normalizedName) ??
+    scene.getObjectByName(
+      rawName.includes(":") ? (rawName.split(":")[1] ?? rawName) : rawName,
+    ) ??
+    null
+  );
+}
+
+/**
+ * Retarget a Mixamo-style GLB animation clip onto a VRM.
+ * Position tracks are ignored to avoid root motion.
+ */
+export function retargetMixamoGltfToVrm(
+  animation: { scene: THREE.Group; animations: THREE.AnimationClip[] },
+  vrm: VRM,
+  clipName?: string,
+): THREE.AnimationClip {
+  animation.scene.updateMatrixWorld(true);
+  vrm.scene.updateMatrixWorld(true);
+
+  const sourceClip = animation.animations[0];
+  if (!sourceClip) {
+    throw new Error("GLB contains no animation clips");
+  }
+
+  const tracks: Array<THREE.QuaternionKeyframeTrack> = [];
+  const restRotationInverse = new THREE.Quaternion();
+  const parentRestWorldRotation = new THREE.Quaternion();
+  const q = new THREE.Quaternion();
+
+  for (const track of sourceClip.tracks) {
+    const parts = track.name.split(".");
+    const rawRigName = parts[0];
+    const propertyName = parts[1];
+    if (!rawRigName || !propertyName) continue;
+    if (propertyName !== "quaternion") continue;
+    if (!(track instanceof THREE.QuaternionKeyframeTrack)) continue;
+
+    const normalizedRigName = normalizeMixamoRigName(rawRigName);
+    const vrmBoneName = mixamoVRMRigMap[normalizedRigName];
+    if (!vrmBoneName) continue;
+
+    const vrmNode = vrm.humanoid?.getNormalizedBoneNode(
+      vrmBoneName as VRMHumanBoneName,
+    );
+    if (!vrmNode) continue;
+
+    const mixamoRigNode = findNode(
+      animation.scene,
+      rawRigName,
+      normalizedRigName,
+    );
+    if (!mixamoRigNode || !mixamoRigNode.parent) continue;
+
+    mixamoRigNode.getWorldQuaternion(restRotationInverse).invert();
+    mixamoRigNode.parent.getWorldQuaternion(parentRestWorldRotation);
+
+    const values = track.values.slice();
+    for (let i = 0; i < values.length; i += 4) {
+      q.fromArray(values, i);
+      q.premultiply(parentRestWorldRotation).multiply(restRotationInverse);
+      q.toArray(values, i);
+    }
+
+    tracks.push(
+      new THREE.QuaternionKeyframeTrack(
+        `${vrmNode.name}.quaternion`,
+        track.times,
+        values.map((v, i) => (isVrm0(vrm) && i % 2 === 0 ? -v : v)),
+      ),
+    );
+  }
+
+  const hasHipsTrack = tracks.some((track) =>
+    track.name.startsWith(
+      `${vrm.humanoid?.getNormalizedBoneNode("hips" as VRMHumanBoneName)?.name ?? "__missing__"}.`,
+    ),
+  );
+  if (!hasHipsTrack) {
+    throw new Error(
+      `Retargeting failed: no hips bone track found (mapped ${tracks.length} tracks). ` +
+        "Expected Mixamo bone names like mixamorigHips/mixamorigSpine...",
+    );
+  }
+
+  const name = clipName ?? sourceClip.name ?? "retargeted";
+  const clip = new THREE.AnimationClip(name, sourceClip.duration, tracks);
+  clip.optimize();
+  return clip;
+}

package/src/components/chainConfig.ts

@@ -0,0 +1,380 @@
+/**
+ * Central chain configuration registry.
+ *
+ * Every chain-specific constant (explorer URLs, native token details,
+ * gas thresholds, stablecoin addresses, logo URLs, address validation)
+ * lives here so that UI components and hooks can derive values from
+ * a single source of truth rather than scattering inline constants.
+ */
+
+/* ── Types ─────────────────────────────────────────────────────────── */
+
+export type ChainKey =
+  | "bsc"
+  | "avax"
+  | "solana"
+  | "ethereum"
+  | "base"
+  | "arbitrum"
+  | "optimism"
+  | "polygon";
+
+export interface Stablecoin {
+  symbol: string;
+  address: string;
+}
+
+export interface ChainConfig {
+  /** Unique identifier used as filter key and in storage keys. */
+  chainKey: ChainKey;
+  /** Human-readable chain name. */
+  name: string;
+  /** Native gas-token symbol (e.g. BNB, AVAX, SOL). */
+  nativeSymbol: string;
+  /** Native token decimals. */
+  nativeDecimals: number;
+  /** Whether this is an EVM-compatible chain. */
+  isEvm: boolean;
+
+  /* ── Explorer ──────────────────────────────── */
+
+  /** Base URL of the chain's block explorer. */
+  explorerBaseUrl: string;
+  /** Path template for token pages — `{address}` is replaced. */
+  explorerTokenPath: string;
+  /** Path template for transaction pages — `{hash}` is replaced. */
+  explorerTxPath: string;
+
+  /* ── Logos ──────────────────────────────────── */
+
+  /** URL for the native gas-token logo. */
+  nativeLogoUrl: string;
+  /** TrustWallet assets CDN slug (e.g. `smartchain`, `avalanchec`). */
+  trustWalletSlug: string | null;
+
+  /* ── Gas ────────────────────────────────────── */
+
+  /** Minimum native balance to consider the wallet "trade-ready". */
+  gasReadyThreshold: number;
+  /** Reserve kept aside from max-balance swaps. */
+  swapGasReserve: number;
+
+  /* ── Stablecoins ───────────────────────────── */
+
+  /** Well-known stablecoin contract addresses on this chain. */
+  stablecoins: Stablecoin[];
+
+  /* ── Address ───────────────────────────────── */
+
+  /** Regex to validate an address on this chain. */
+  addressRegex: RegExp;
+
+  /* ── DexScreener ───────────────────────────── */
+
+  /** Chain ID used by the DexScreener API. */
+  dexScreenerChainId: string;
+
+  /* ── Variants ──────────────────────────────── */
+
+  /** Alternative chain name strings that resolve to this config. */
+  nameVariants: string[];
+
+  /* ── Branding ──────────────────────────────── */
+
+  /** Brand color for the chain (hex string, e.g. `"#627eea"`). */
+  color: string;
+}
+
+/* ── Registry ──────────────────────────────────────────────────────── */
+
+const HEX_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+const SOLANA_ADDRESS_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+export const CHAIN_CONFIGS: Record<ChainKey, ChainConfig> = {
+  bsc: {
+    chainKey: "bsc",
+    name: "BSC",
+    nativeSymbol: "BNB",
+    nativeDecimals: 18,
+    isEvm: true,
+    explorerBaseUrl: "https://bscscan.com",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/smartchain/info/logo.png",
+    trustWalletSlug: "smartchain",
+    gasReadyThreshold: 0.005,
+    swapGasReserve: 0.002,
+    stablecoins: [
+      { symbol: "USDT", address: "0x55d398326f99059fF775485246999027B3197955" },
+      { symbol: "USDC", address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d" },
+    ],
+    addressRegex: HEX_ADDRESS_RE,
+    dexScreenerChainId: "bsc",
+    nameVariants: ["bsc", "bnb chain", "bnb smart chain"],
+    color: "#f3ba2f",
+  },
+
+  avax: {
+    chainKey: "avax",
+    name: "Avalanche",
+    nativeSymbol: "AVAX",
+    nativeDecimals: 18,
+    isEvm: true,
+    explorerBaseUrl: "https://snowtrace.io",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/avalanchec/info/logo.png",
+    trustWalletSlug: "avalanchec",
+    gasReadyThreshold: 0.01,
+    swapGasReserve: 0.005,
+    stablecoins: [
+      { symbol: "USDT", address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7" },
+      { symbol: "USDC", address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E" },
+    ],
+    addressRegex: HEX_ADDRESS_RE,
+    dexScreenerChainId: "avalanche",
+    nameVariants: ["avax", "avalanche", "c-chain", "avalanche c-chain"],
+    color: "#e84142",
+  },
+
+  solana: {
+    chainKey: "solana",
+    name: "Solana",
+    nativeSymbol: "SOL",
+    nativeDecimals: 9,
+    isEvm: false,
+    explorerBaseUrl: "https://solscan.io",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/solana/info/logo.png",
+    trustWalletSlug: "solana",
+    gasReadyThreshold: 0.01,
+    swapGasReserve: 0.005,
+    stablecoins: [
+      {
+        symbol: "USDC",
+        address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      },
+    ],
+    addressRegex: SOLANA_ADDRESS_RE,
+    dexScreenerChainId: "solana",
+    nameVariants: ["solana", "sol"],
+    color: "#9945ff",
+  },
+
+  ethereum: {
+    chainKey: "ethereum",
+    name: "Ethereum",
+    nativeSymbol: "ETH",
+    nativeDecimals: 18,
+    isEvm: true,
+    explorerBaseUrl: "https://etherscan.io",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/info/logo.png",
+    trustWalletSlug: "ethereum",
+    gasReadyThreshold: 0.005,
+    swapGasReserve: 0.002,
+    stablecoins: [
+      { symbol: "USDT", address: "0xdAC17F958D2ee523a2206206994597C13D831ec7" },
+      { symbol: "USDC", address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+    ],
+    addressRegex: HEX_ADDRESS_RE,
+    dexScreenerChainId: "ethereum",
+    nameVariants: ["ethereum", "mainnet", "eth"],
+    color: "#627eea",
+  },
+
+  base: {
+    chainKey: "base",
+    name: "Base",
+    nativeSymbol: "ETH",
+    nativeDecimals: 18,
+    isEvm: true,
+    explorerBaseUrl: "https://basescan.org",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/base/info/logo.png",
+    trustWalletSlug: "base",
+    gasReadyThreshold: 0.005,
+    swapGasReserve: 0.001,
+    stablecoins: [
+      { symbol: "USDC", address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
+    ],
+    addressRegex: HEX_ADDRESS_RE,
+    dexScreenerChainId: "base",
+    nameVariants: ["base"],
+    color: "#0052ff",
+  },
+
+  arbitrum: {
+    chainKey: "arbitrum",
+    name: "Arbitrum",
+    nativeSymbol: "ETH",
+    nativeDecimals: 18,
+    isEvm: true,
+    explorerBaseUrl: "https://arbiscan.io",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/info/logo.png",
+    trustWalletSlug: null,
+    gasReadyThreshold: 0.005,
+    swapGasReserve: 0.001,
+    stablecoins: [
+      { symbol: "USDC", address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" },
+    ],
+    addressRegex: HEX_ADDRESS_RE,
+    dexScreenerChainId: "arbitrum",
+    nameVariants: ["arbitrum"],
+    color: "#12aaff",
+  },
+
+  optimism: {
+    chainKey: "optimism",
+    name: "Optimism",
+    nativeSymbol: "ETH",
+    nativeDecimals: 18,
+    isEvm: true,
+    explorerBaseUrl: "https://optimistic.etherscan.io",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/info/logo.png",
+    trustWalletSlug: null,
+    gasReadyThreshold: 0.005,
+    swapGasReserve: 0.001,
+    stablecoins: [
+      { symbol: "USDC", address: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" },
+    ],
+    addressRegex: HEX_ADDRESS_RE,
+    dexScreenerChainId: "optimism",
+    nameVariants: ["optimism"],
+    color: "#ff0420",
+  },
+
+  polygon: {
+    chainKey: "polygon",
+    name: "Polygon",
+    nativeSymbol: "MATIC",
+    nativeDecimals: 18,
+    isEvm: true,
+    explorerBaseUrl: "https://polygonscan.com",
+    explorerTokenPath: "/token/{address}",
+    explorerTxPath: "/tx/{hash}",
+    nativeLogoUrl:
+      "https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/polygon/info/logo.png",
+    trustWalletSlug: "polygon",
+    gasReadyThreshold: 0.5,
+    swapGasReserve: 0.1,
+    stablecoins: [
+      { symbol: "USDT", address: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F" },
+      { symbol: "USDC", address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359" },
+    ],
+    addressRegex: HEX_ADDRESS_RE,
+    dexScreenerChainId: "polygon",
+    nameVariants: ["polygon"],
+    color: "#8247e5",
+  },
+};
+
+/* ── Lookup helpers ────────────────────────────────────────────────── */
+
+/** Pre-built lookup table: lowercase variant → ChainConfig. */
+const _variantMap = new Map<string, ChainConfig>();
+for (const config of Object.values(CHAIN_CONFIGS)) {
+  for (const variant of config.nameVariants) {
+    _variantMap.set(variant.toLowerCase(), config);
+  }
+}
+
+/** Resolve a chain name (case-insensitive, trimmed) to its config. */
+export function getChainConfig(chainName: string): ChainConfig | null {
+  return _variantMap.get(chainName.trim().toLowerCase()) ?? null;
+}
+
+/**
+ * Resolve a chain name string to a `ChainKey`.
+ * Returns `null` for unrecognised chains.
+ */
+export function resolveChainKey(chainName: string): ChainKey | null {
+  const config = getChainConfig(chainName);
+  return config?.chainKey ?? null;
+}
+
+/**
+ * Build the explorer URL for a token on the given chain.
+ * Returns `null` if the chain is unknown or the address is invalid.
+ */
+export function getExplorerTokenUrl(
+  chainName: string,
+  address: string,
+): string | null {
+  const config = getChainConfig(chainName);
+  if (!config) return null;
+  const trimmed = address.trim();
+  if (!config.addressRegex.test(trimmed)) return null;
+  return `${config.explorerBaseUrl}${config.explorerTokenPath.replace("{address}", trimmed)}`;
+}
+
+/**
+ * Build the explorer URL for a transaction on the given chain.
+ * Returns `null` if the chain is unknown.
+ */
+export function getExplorerTxUrl(
+  chainName: string,
+  hash: string,
+): string | null {
+  const config = getChainConfig(chainName);
+  if (!config) return null;
+  return `${config.explorerBaseUrl}${config.explorerTxPath.replace("{hash}", hash.trim())}`;
+}
+
+/**
+ * Get the native token logo URL for a chain, or `null` if unknown.
+ */
+export function getNativeLogoUrl(chainName: string): string | null {
+  return getChainConfig(chainName)?.nativeLogoUrl ?? null;
+}
+
+/**
+ * Get the TrustWallet CDN logo URL for a contract token on the given chain.
+ * Returns `null` if the chain has no TrustWallet slug or no contract address.
+ */
+export function getContractLogoUrl(
+  chainName: string,
+  contractAddress: string | null,
+): string | null {
+  if (!contractAddress) return null;
+  const config = getChainConfig(chainName);
+  if (!config?.trustWalletSlug) return null;
+  return `https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/${config.trustWalletSlug}/assets/${contractAddress}/logo.png`;
+}
+
+/**
+ * Resolve a stablecoin address on a given chain by symbol.
+ * Returns `null` if not found.
+ */
+export function getStablecoinAddress(
+  chainName: string,
+  symbol: string,
+): string | null {
+  const config = getChainConfig(chainName);
+  if (!config) return null;
+  const upper = symbol.trim().toUpperCase();
+  return config.stablecoins.find((s) => s.symbol === upper)?.address ?? null;
+}
+
+/** The primary chains we want to support prominently. */
+export const PRIMARY_CHAIN_KEYS: ChainKey[] = [
+  "ethereum",
+  "base",
+  "bsc",
+  "avax",
+  "solana",
+];