@circle-fin/app-kit 1.2.1 → 1.4.0

package/chains.mjs

@@ -166,8 +166,9 @@ var Blockchain;
 /**
  * Enum representing chains that support same-chain swaps through the Swap Kit.
  *
- * Unlike the full {@link Blockchain} enum, SwapChain includes only mainnet
- * networks where adapter contracts are deployed (CCTPv2 support).
+ * Unlike the full {@link Blockchain} enum, SwapChain includes mainnet
+ * networks and explicitly whitelisted testnets (e.g., {@link Arc_Testnet})
+ * where adapter contracts are deployed (CCTPv2 support).
  *
  * Dynamic validation via {@link isSwapSupportedChain} ensures chains
  * automatically work when adapter contracts and supported tokens are deployed.
@@ -212,6 +213,8 @@ var SwapChain;
     SwapChain["XDC"] = "XDC";
     SwapChain["HyperEVM"] = "HyperEVM";
     SwapChain["Monad"] = "Monad";
+    // Testnet chains with swap support
+    SwapChain["Arc_Testnet"] = "Arc_Testnet";
 })(SwapChain || (SwapChain = {}));
 // -----------------------------------------------------------------------------
 // Bridge Chain Enum (CCTPv2 Supported Chains)
@@ -308,6 +311,82 @@ var BridgeChain;
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
 })(BridgeChain || (BridgeChain = {}));
+// -----------------------------------------------------------------------------
+// Unified Balance Chain Enum (Gateway V1 Supported Chains)
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support Gateway V1 operations
+ * (deposit, spend, balance, delegate, removeFund).
+ *
+ * Derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active Gateway V1 contract support. When new chains
+ * gain Gateway V1 support, they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of Gateway-supported chains.
+ * - Use this enum (or its string literals) in unified-balance-kit calls
+ *   for type safety.
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link UnifiedBalanceChainIdentifier} for the type that accepts these values.
+ */
+var UnifiedBalanceChain;
+(function (UnifiedBalanceChain) {
+    // Mainnet chains with Gateway V1 support
+    UnifiedBalanceChain["Arbitrum"] = "Arbitrum";
+    UnifiedBalanceChain["Avalanche"] = "Avalanche";
+    UnifiedBalanceChain["Base"] = "Base";
+    UnifiedBalanceChain["Ethereum"] = "Ethereum";
+    UnifiedBalanceChain["HyperEVM"] = "HyperEVM";
+    UnifiedBalanceChain["Optimism"] = "Optimism";
+    UnifiedBalanceChain["Polygon"] = "Polygon";
+    UnifiedBalanceChain["Sei"] = "Sei";
+    UnifiedBalanceChain["Solana"] = "Solana";
+    UnifiedBalanceChain["Sonic"] = "Sonic";
+    UnifiedBalanceChain["Unichain"] = "Unichain";
+    UnifiedBalanceChain["World_Chain"] = "World_Chain";
+    // Testnet chains with Gateway V1 support
+    UnifiedBalanceChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
+    UnifiedBalanceChain["Arc_Testnet"] = "Arc_Testnet";
+    UnifiedBalanceChain["Avalanche_Fuji"] = "Avalanche_Fuji";
+    UnifiedBalanceChain["Base_Sepolia"] = "Base_Sepolia";
+    UnifiedBalanceChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
+    UnifiedBalanceChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    UnifiedBalanceChain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    UnifiedBalanceChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
+    UnifiedBalanceChain["Sei_Testnet"] = "Sei_Testnet";
+    UnifiedBalanceChain["Solana_Devnet"] = "Solana_Devnet";
+    UnifiedBalanceChain["Sonic_Testnet"] = "Sonic_Testnet";
+    UnifiedBalanceChain["Unichain_Sepolia"] = "Unichain_Sepolia";
+    UnifiedBalanceChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
+})(UnifiedBalanceChain || (UnifiedBalanceChain = {}));
+// Earn Chain Enum
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support earn (vault deposit/withdraw)
+ * operations through the Earn Kit.
+ *
+ * Currently only Ethereum mainnet is supported. Additional chains
+ * will be added as vault protocol support expands.
+ *
+ * @example
+ * ```typescript
+ * import { EarnChain } from '@core/chains'
+ *
+ * const result = await earnKit.deposit({
+ *   from: { adapter, chain: EarnChain.Ethereum },
+ *   vaultAddress: '0x...',
+ *   amount: '100',
+ * })
+ * ```
+ */
+var EarnChain;
+(function (EarnChain) {
+    EarnChain["Ethereum"] = "Ethereum";
+})(EarnChain || (EarnChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -610,6 +689,70 @@ const BRIDGE_CONTRACT_EVM_MAINNET = '0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0'
  * on EVM-compatible chains. Use this address for mainnet adapter integrations.
  */
 const ADAPTER_CONTRACT_EVM_MAINNET = '0x7FB8c7260b63934d8da38aF902f87ae6e284a845';
+/**
+ * The adapter contract address for EVM testnet networks.
+ *
+ * This contract serves as an adapter for integrating with various protocols
+ * on EVM-compatible testnet chains. Use this address for testnet adapter
+ * integrations (e.g., Arc Testnet).
+ */
+const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
+/**
+ * The GatewayWallet contract address for EVM mainnet networks.
+ *
+ * This contract manages wallet operations for Gateway transactions
+ * on mainnet environments across EVM-compatible chains.
+ */
+const GATEWAY_WALLET_EVM_MAINNET = '0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE';
+/**
+ * The GatewayMinter contract address for EVM mainnet networks.
+ *
+ * This contract handles minting operations for Gateway transactions
+ * on mainnet environments across EVM-compatible chains.
+ */
+const GATEWAY_MINTER_EVM_MAINNET = '0x2222222d7164433c4C09B0b0D809a9b52C04C205';
+/**
+ * The GatewayWallet contract address for EVM testnet networks.
+ *
+ * This contract manages wallet operations for Gateway transactions
+ * on testnet environments across EVM-compatible chains.
+ */
+const GATEWAY_WALLET_EVM_TESTNET = '0x0077777d7EBA4688BDeF3E311b846F25870A19B9';
+/**
+ * The GatewayMinter contract address for EVM testnet networks.
+ *
+ * This contract handles minting operations for Gateway transactions
+ * on testnet environments across EVM-compatible chains.
+ */
+const GATEWAY_MINTER_EVM_TESTNET = '0x0022222ABE238Cc2C7Bb1f21003F0a260052475B';
+/**
+ * The GatewayWallet program address for Solana mainnet.
+ *
+ * This program manages wallet operations for Gateway transactions
+ * on Solana mainnet.
+ */
+const GATEWAY_WALLET_SOLANA_MAINNET = 'GATEwy4YxeiEbRJLwB6dXgg7q61e6zBPrMzYj5h1pRXQ';
+/**
+ * The GatewayMinter program address for Solana mainnet.
+ *
+ * This program handles minting operations for Gateway transactions
+ * on Solana mainnet.
+ */
+const GATEWAY_MINTER_SOLANA_MAINNET = 'GATEm5SoBJiSw1v2Pz1iPBgUYkXzCUJ27XSXhDfSyzVZ';
+/**
+ * The GatewayWallet program address for Solana devnet.
+ *
+ * This program manages wallet operations for Gateway transactions
+ * on Solana devnet.
+ */
+const GATEWAY_WALLET_SOLANA_DEVNET = 'GATEwdfmYNELfp5wDmmR6noSr2vHnAfBPMm2PvCzX5vu';
+/**
+ * The GatewayMinter program address for Solana devnet.
+ *
+ * This program handles minting operations for Gateway transactions
+ * on Solana devnet.
+ */
+const GATEWAY_MINTER_SOLANA_DEVNET = 'GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr';
 
 /**
  * Arc Testnet chain definition
@@ -658,6 +801,20 @@ const ArcTestnet = defineChain({
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
+    },
+    gateway: {
+        domain: 26,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
 });
 
@@ -709,6 +866,19 @@ const Arbitrum = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 3,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -758,6 +928,19 @@ const ArbitrumSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 3,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -808,6 +991,19 @@ const Avalanche = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 1,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -857,6 +1053,19 @@ const AvalancheFuji = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 1,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -907,6 +1116,19 @@ const Base = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 6,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -956,6 +1178,19 @@ const BaseSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 6,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1200,7 +1435,10 @@ const Ethereum = defineChain({
     chainId: 1,
     isTestnet: false,
     explorerUrl: 'https://etherscan.io/tx/{hash}',
-    rpcEndpoints: ['https://eth.merkle.io', 'https://ethereum.publicnode.com'],
+    rpcEndpoints: [
+        'https://ethereum-rpc.publicnode.com',
+        'https://ethereum.publicnode.com',
+    ],
     eurcAddress: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
     usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
     usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
@@ -1230,6 +1468,19 @@ const Ethereum = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 0,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1250,7 +1501,7 @@ const EthereumSepolia = defineChain({
     chainId: 11155111,
     isTestnet: true,
     explorerUrl: 'https://sepolia.etherscan.io/tx/{hash}',
-    rpcEndpoints: ['https://sepolia.drpc.org'],
+    rpcEndpoints: ['https://ethereum-sepolia-rpc.publicnode.com'],
     eurcAddress: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4',
     usdcAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
     usdtAddress: null,
@@ -1279,6 +1530,19 @@ const EthereumSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 0,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1348,7 +1612,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -1373,6 +1637,19 @@ const HyperEVM = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 19,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1417,6 +1694,19 @@ const HyperEVMTestnet = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 19,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -1951,6 +2241,19 @@ const Optimism = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 2,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2000,6 +2303,19 @@ const OptimismSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 2,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2188,6 +2504,19 @@ const Polygon = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 7,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2237,6 +2566,19 @@ const PolygonAmoy = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 7,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2283,6 +2625,19 @@ const Sei = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 16,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2327,6 +2682,19 @@ const SeiTestnet = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 16,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2371,6 +2739,19 @@ const Sonic = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 13,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2414,6 +2795,19 @@ const SonicTestnet = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 13,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2462,6 +2856,19 @@ const Solana = defineChain({
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
     },
+    gateway: {
+        domain: 5,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_SOLANA_MAINNET,
+                minter: GATEWAY_MINTER_SOLANA_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
+    },
 });
 
 /**
@@ -2510,6 +2917,19 @@ const SolanaDevnet = defineChain({
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
     },
     rpcEndpoints: ['https://api.devnet.solana.com'],
+    gateway: {
+        domain: 5,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_SOLANA_DEVNET,
+                minter: GATEWAY_MINTER_SOLANA_DEVNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
+    },
 });
 
 /**
@@ -2684,6 +3104,19 @@ const Unichain = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 10,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2733,6 +3166,19 @@ const UnichainSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 10,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2777,6 +3223,19 @@ const WorldChain = defineChain({
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
         adapter: ADAPTER_CONTRACT_EVM_MAINNET,
     },
+    gateway: {
+        domain: 14,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_MAINNET,
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2823,6 +3282,19 @@ const WorldChainSepolia = defineChain({
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
     },
+    gateway: {
+        domain: 14,
+        contracts: {
+            v1: {
+                wallet: GATEWAY_WALLET_EVM_TESTNET,
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+            },
+        },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
+    },
 });
 
 /**
@@ -2964,6 +3436,87 @@ defineChain({
     cctp: null,
 });
 
+/**
+ * Zod schema for validating Gateway v1 contract addresses.
+ *
+ * @example
+ * ```typescript
+ * gatewayV1ContractsSchema.parse({
+ *   wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *   minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ * })
+ * ```
+ */
+const gatewayV1ContractsSchema = z
+    .object({
+    wallet: z
+        .string({
+        required_error: 'Gateway wallet address is required. Please provide a valid contract address.',
+        invalid_type_error: 'Gateway wallet address must be a string.',
+    })
+        .min(1, 'Gateway wallet address cannot be empty.'),
+    minter: z
+        .string({
+        required_error: 'Gateway minter address is required. Please provide a valid contract address.',
+        invalid_type_error: 'Gateway minter address must be a string.',
+    })
+        .min(1, 'Gateway minter address cannot be empty.'),
+})
+    .strict(); // Reject any additional properties not defined in the schema
+/**
+ * Zod schema for validating the versioned Gateway contracts map.
+ *
+ * @description Mirrors the {@link GatewayContracts} type: a partial map of
+ * protocol versions to their contract addresses, following the same pattern
+ * as {@link CCTPContracts}.
+ *
+ * @example
+ * ```typescript
+ * gatewayContractsSchema.parse({
+ *   v1: {
+ *     wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *     minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ *   }
+ * })
+ * ```
+ */
+const gatewayContractsSchema = z
+    .object({
+    v1: gatewayV1ContractsSchema.optional(),
+})
+    .strict(); // Reject any additional properties not defined in the schema
+/**
+ * Zod schema for validating the full Gateway configuration.
+ *
+ * @description Mirrors the {@link GatewayConfig} type: a domain number plus
+ * a versioned contracts map, following the same pattern as {@link CCTPConfig}.
+ *
+ * @example
+ * ```typescript
+ * gatewayConfigSchema.parse({
+ *   domain: 6,
+ *   contracts: {
+ *     v1: {
+ *       wallet: '0x1234567890abcdef1234567890abcdef12345678',
+ *       minter: '0xabcdef1234567890abcdef1234567890abcdef12'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+const gatewayConfigSchema = z
+    .object({
+    domain: z.number({
+        required_error: 'Gateway domain is required. Please provide a valid domain number.',
+        invalid_type_error: 'Gateway domain must be a number.',
+    }),
+    contracts: gatewayContractsSchema,
+    forwarderSupported: z.object({
+        source: z.boolean(),
+        destination: z.boolean(),
+    }),
+})
+    .strict(); // Reject any additional properties not defined in the schema
 /**
  * Base schema for common chain definition properties.
  * This contains all properties shared between EVM and non-EVM chains.
@@ -3002,6 +3555,7 @@ const baseChainDefinitionSchema = z.object({
         adapter: z.string().optional(),
     })
         .optional(),
+    gateway: gatewayConfigSchema.optional(),
 });
 /**
  * Zod schema for validating EVM chain definitions specifically.
@@ -3175,6 +3729,77 @@ z.union([
         message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
     })),
 ]);
+/**
+ * Zod schema for validating earn-specific chain identifiers.
+ *
+ * Validate that the provided chain is supported for earn (vault
+ * deposit/withdraw) operations. Currently only Ethereum is
+ * supported.
+ *
+ * Accept an EarnChain enum value, a matching string literal, or
+ * a ChainDefinition for a supported chain.
+ *
+ * @example
+ * ```typescript
+ * import { earnChainIdentifierSchema } from '@core/chains'
+ * import { EarnChain, Ethereum } from '@core/chains'
+ *
+ * // Valid
+ * earnChainIdentifierSchema.parse(EarnChain.Ethereum)
+ * earnChainIdentifierSchema.parse('Ethereum')
+ * earnChainIdentifierSchema.parse(Ethereum)
+ *
+ * // Invalid (throws ZodError)
+ * earnChainIdentifierSchema.parse('Solana')
+ * ```
+ */
+z.union([
+    z.string().refine((val) => val in EarnChain, (val) => ({
+        message: `"${val}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+    z.nativeEnum(EarnChain),
+    chainDefinitionSchema.refine((chain) => chain.chain in EarnChain, (chain) => ({
+        message: `"${chain.chain}" is not a supported earn chain. ` +
+            `Supported chains: ${Object.values(EarnChain).join(', ')}`,
+    })),
+]);
+/**
+ * Zod schema for validating unified balance chain identifiers.
+ *
+ * This schema validates that the provided chain is supported for unified balance operations.
+ * It accepts either a UnifiedBalanceChain enum value, a string matching a UnifiedBalanceChain value,
+ * or a ChainDefinition for a supported chain.
+ *
+ * Use this schema when validating chain parameters for unified balance operations to ensure
+ * only Gateway V1-supported chains are accepted at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { unifiedBalanceChainIdentifierSchema } from '@core/chains/validation'
+ * import { UnifiedBalanceChain, Chains } from '@core/chains'
+ *
+ * // Valid - UnifiedBalanceChain enum value
+ * unifiedBalanceChainIdentifierSchema.parse(UnifiedBalanceChain.Ethereum)
+ *
+ * // Valid - string literal
+ * unifiedBalanceChainIdentifierSchema.parse('Ethereum')
+ *
+ * // Invalid - Algorand is not in UnifiedBalanceChain (throws ZodError)
+ * unifiedBalanceChainIdentifierSchema.parse('Algorand')
+ * ```
+ *
+ * @see {@link UnifiedBalanceChain} for the enum of supported chains.
+ */
+const supportedUnifiedBalanceChains = Object.keys(UnifiedBalanceChain).join(', ');
+z.union([
+    z.string().refine((val) => val in UnifiedBalanceChain, (val) => ({
+        message: `Chain "${val}" is not supported for unified balance operations. Supported chains: ${supportedUnifiedBalanceChains}.`,
+    })),
+    chainDefinitionSchema.refine((chainDef) => chainDef.chain in UnifiedBalanceChain, (chainDef) => ({
+        message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for unified balance operations. Supported chains: ${supportedUnifiedBalanceChains}.`,
+    })),
+]);
 
 /**
  * @packageDocumentation