@circle-fin/bridge-kit 1.1.2 → 1.3.0

package/chains.cjs

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -24,10 +24,16 @@ var zod = require('zod');
 // Blockchain Enum
 // -----------------------------------------------------------------------------
 /**
- * Enumeration of all blockchains supported by this library.
+ * Enumeration of all blockchains known to this library.
+ *
+ * This enum contains every blockchain that has a chain definition, regardless
+ * of whether bridging is currently supported. For chains that support bridging
+ * via CCTPv2, see {@link BridgeChain}.
+ *
  * @enum
  * @category Enums
- * @description Provides string identifiers for each supported blockchain.
+ * @description Provides string identifiers for each blockchain with a definition.
+ * @see {@link BridgeChain} for the subset of chains that support CCTPv2 bridging.
  */
 var Blockchain;
 (function (Blockchain) {
@@ -87,6 +93,95 @@ var Blockchain;
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(Blockchain || (Blockchain = {}));
+// -----------------------------------------------------------------------------
+// Bridge Chain Enum (CCTPv2 Supported Chains)
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support cross-chain bridging via CCTPv2.
+ *
+ * The enum is derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active CCTPv2 support. When new chains gain CCTPv2 support,
+ * they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of bridging-supported chains.
+ * - Use this enum (or its string literals) in `kit.bridge()` calls for type safety.
+ * - Attempting to use a chain not in this enum will produce a TypeScript compile error.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // ✅ Valid - autocomplete suggests only supported chains
+ * await kit.bridge({
+ *   from: { adapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter, chain: BridgeChain.Base },
+ *   amount: '100'
+ * })
+ *
+ * // ✅ Also valid - string literals work with autocomplete
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter, chain: 'Base_Sepolia' },
+ *   amount: '100'
+ * })
+ *
+ * // ❌ Compile error - Algorand is not in BridgeChain
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100'
+ * })
+ * ```
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link BridgeChainIdentifier} for the type that accepts these values.
+ */
+exports.BridgeChain = void 0;
+(function (BridgeChain) {
+    // Mainnet chains with CCTPv2 support
+    BridgeChain["Arbitrum"] = "Arbitrum";
+    BridgeChain["Avalanche"] = "Avalanche";
+    BridgeChain["Base"] = "Base";
+    BridgeChain["Codex"] = "Codex";
+    BridgeChain["Ethereum"] = "Ethereum";
+    BridgeChain["HyperEVM"] = "HyperEVM";
+    BridgeChain["Ink"] = "Ink";
+    BridgeChain["Linea"] = "Linea";
+    BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Plume"] = "Plume";
+    BridgeChain["Polygon"] = "Polygon";
+    BridgeChain["Sei"] = "Sei";
+    BridgeChain["Solana"] = "Solana";
+    BridgeChain["Sonic"] = "Sonic";
+    BridgeChain["Unichain"] = "Unichain";
+    BridgeChain["World_Chain"] = "World_Chain";
+    BridgeChain["XDC"] = "XDC";
+    // Testnet chains with CCTPv2 support
+    BridgeChain["Arc_Testnet"] = "Arc_Testnet";
+    BridgeChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
+    BridgeChain["Avalanche_Fuji"] = "Avalanche_Fuji";
+    BridgeChain["Base_Sepolia"] = "Base_Sepolia";
+    BridgeChain["Codex_Testnet"] = "Codex_Testnet";
+    BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
+    BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    BridgeChain["Ink_Testnet"] = "Ink_Testnet";
+    BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    BridgeChain["Plume_Testnet"] = "Plume_Testnet";
+    BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
+    BridgeChain["Sei_Testnet"] = "Sei_Testnet";
+    BridgeChain["Solana_Devnet"] = "Solana_Devnet";
+    BridgeChain["Sonic_Testnet"] = "Sonic_Testnet";
+    BridgeChain["Unichain_Sepolia"] = "Unichain_Sepolia";
+    BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
+    BridgeChain["XDC_Apothem"] = "XDC_Apothem";
+})(exports.BridgeChain || (exports.BridgeChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -2265,6 +2360,44 @@ zod.z.union([
     zod.z.nativeEnum(Blockchain),
     chainDefinitionSchema,
 ]);
+/**
+ * Zod schema for validating bridge chain identifiers.
+ *
+ * This schema validates that the provided chain is supported for CCTPv2 bridging.
+ * It accepts either a BridgeChain enum value, a string matching a BridgeChain value,
+ * or a ChainDefinition for a supported chain.
+ *
+ * Use this schema when validating chain parameters for bridge operations to ensure
+ * only CCTPv2-supported chains are accepted at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { bridgeChainIdentifierSchema } from '@core/chains/validation'
+ * import { BridgeChain, Chains } from '@core/chains'
+ *
+ * // Valid - BridgeChain enum value
+ * bridgeChainIdentifierSchema.parse(BridgeChain.Ethereum)
+ *
+ * // Valid - string literal
+ * bridgeChainIdentifierSchema.parse('Base_Sepolia')
+ *
+ * // Valid - ChainDefinition (validated by CCTP support)
+ * bridgeChainIdentifierSchema.parse(Chains.Solana)
+ *
+ * // Invalid - Algorand is not in BridgeChain (throws ZodError)
+ * bridgeChainIdentifierSchema.parse('Algorand')
+ * ```
+ *
+ * @see {@link BridgeChain} for the enum of supported chains.
+ */
+zod.z.union([
+    zod.z.string().refine((val) => val in exports.BridgeChain, (val) => ({
+        message: `Chain "${val}" is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
+    })),
+    chainDefinitionSchema.refine((chainDef) => chainDef.chain in exports.BridgeChain, (chainDef) => ({
+        message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
+    })),
+]);
 
 exports.Arbitrum = Arbitrum;
 exports.ArbitrumSepolia = ArbitrumSepolia;

package/chains.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -17,10 +17,16 @@
  */
 
 /**
- * Enumeration of all blockchains supported by this library.
+ * Enumeration of all blockchains known to this library.
+ *
+ * This enum contains every blockchain that has a chain definition, regardless
+ * of whether bridging is currently supported. For chains that support bridging
+ * via CCTPv2, see {@link BridgeChain}.
+ *
  * @enum
  * @category Enums
- * @description Provides string identifiers for each supported blockchain.
+ * @description Provides string identifiers for each blockchain with a definition.
+ * @see {@link BridgeChain} for the subset of chains that support CCTPv2 bridging.
  */
 declare enum Blockchain {
     Algorand = "Algorand",
@@ -79,6 +85,89 @@ declare enum Blockchain {
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
+/**
+ * Enumeration of blockchains that support cross-chain bridging via CCTPv2.
+ *
+ * The enum is derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active CCTPv2 support. When new chains gain CCTPv2 support,
+ * they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of bridging-supported chains.
+ * - Use this enum (or its string literals) in `kit.bridge()` calls for type safety.
+ * - Attempting to use a chain not in this enum will produce a TypeScript compile error.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // ✅ Valid - autocomplete suggests only supported chains
+ * await kit.bridge({
+ *   from: { adapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter, chain: BridgeChain.Base },
+ *   amount: '100'
+ * })
+ *
+ * // ✅ Also valid - string literals work with autocomplete
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter, chain: 'Base_Sepolia' },
+ *   amount: '100'
+ * })
+ *
+ * // ❌ Compile error - Algorand is not in BridgeChain
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100'
+ * })
+ * ```
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link BridgeChainIdentifier} for the type that accepts these values.
+ */
+declare enum BridgeChain {
+    Arbitrum = "Arbitrum",
+    Avalanche = "Avalanche",
+    Base = "Base",
+    Codex = "Codex",
+    Ethereum = "Ethereum",
+    HyperEVM = "HyperEVM",
+    Ink = "Ink",
+    Linea = "Linea",
+    Optimism = "Optimism",
+    Plume = "Plume",
+    Polygon = "Polygon",
+    Sei = "Sei",
+    Solana = "Solana",
+    Sonic = "Sonic",
+    Unichain = "Unichain",
+    World_Chain = "World_Chain",
+    XDC = "XDC",
+    Arc_Testnet = "Arc_Testnet",
+    Arbitrum_Sepolia = "Arbitrum_Sepolia",
+    Avalanche_Fuji = "Avalanche_Fuji",
+    Base_Sepolia = "Base_Sepolia",
+    Codex_Testnet = "Codex_Testnet",
+    Ethereum_Sepolia = "Ethereum_Sepolia",
+    HyperEVM_Testnet = "HyperEVM_Testnet",
+    Ink_Testnet = "Ink_Testnet",
+    Linea_Sepolia = "Linea_Sepolia",
+    Optimism_Sepolia = "Optimism_Sepolia",
+    Plume_Testnet = "Plume_Testnet",
+    Polygon_Amoy_Testnet = "Polygon_Amoy_Testnet",
+    Sei_Testnet = "Sei_Testnet",
+    Solana_Devnet = "Solana_Devnet",
+    Sonic_Testnet = "Sonic_Testnet",
+    Unichain_Sepolia = "Unichain_Sepolia",
+    World_Chain_Sepolia = "World_Chain_Sepolia",
+    XDC_Apothem = "XDC_Apothem"
+}
 
 /**
  * Arc Testnet chain definition
@@ -1522,4 +1611,4 @@ declare const XDCApothem: {
     };
 };
 
-export { Arbitrum, ArbitrumSepolia, ArcTestnet, Avalanche, AvalancheFuji, Base, BaseSepolia, Codex, CodexTestnet, Ethereum, EthereumSepolia, HyperEVM, HyperEVMTestnet, Ink, InkTestnet, Linea, LineaSepolia, Optimism, OptimismSepolia, Plume, PlumeTestnet, Polygon, PolygonAmoy, Sei, SeiTestnet, Solana, SolanaDevnet, Sonic, SonicTestnet, Unichain, UnichainSepolia, WorldChain, WorldChainSepolia, XDC, XDCApothem };
+export { Arbitrum, ArbitrumSepolia, ArcTestnet, Avalanche, AvalancheFuji, Base, BaseSepolia, BridgeChain, Codex, CodexTestnet, Ethereum, EthereumSepolia, HyperEVM, HyperEVMTestnet, Ink, InkTestnet, Linea, LineaSepolia, Optimism, OptimismSepolia, Plume, PlumeTestnet, Polygon, PolygonAmoy, Sei, SeiTestnet, Solana, SolanaDevnet, Sonic, SonicTestnet, Unichain, UnichainSepolia, WorldChain, WorldChainSepolia, XDC, XDCApothem };

package/chains.mjs

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025, Circle Internet Group, Inc. All rights reserved.
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -22,10 +22,16 @@ import { z } from 'zod';
 // Blockchain Enum
 // -----------------------------------------------------------------------------
 /**
- * Enumeration of all blockchains supported by this library.
+ * Enumeration of all blockchains known to this library.
+ *
+ * This enum contains every blockchain that has a chain definition, regardless
+ * of whether bridging is currently supported. For chains that support bridging
+ * via CCTPv2, see {@link BridgeChain}.
+ *
  * @enum
  * @category Enums
- * @description Provides string identifiers for each supported blockchain.
+ * @description Provides string identifiers for each blockchain with a definition.
+ * @see {@link BridgeChain} for the subset of chains that support CCTPv2 bridging.
  */
 var Blockchain;
 (function (Blockchain) {
@@ -85,6 +91,95 @@ var Blockchain;
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(Blockchain || (Blockchain = {}));
+// -----------------------------------------------------------------------------
+// Bridge Chain Enum (CCTPv2 Supported Chains)
+// -----------------------------------------------------------------------------
+/**
+ * Enumeration of blockchains that support cross-chain bridging via CCTPv2.
+ *
+ * The enum is derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active CCTPv2 support. When new chains gain CCTPv2 support,
+ * they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of bridging-supported chains.
+ * - Use this enum (or its string literals) in `kit.bridge()` calls for type safety.
+ * - Attempting to use a chain not in this enum will produce a TypeScript compile error.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // ✅ Valid - autocomplete suggests only supported chains
+ * await kit.bridge({
+ *   from: { adapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter, chain: BridgeChain.Base },
+ *   amount: '100'
+ * })
+ *
+ * // ✅ Also valid - string literals work with autocomplete
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter, chain: 'Base_Sepolia' },
+ *   amount: '100'
+ * })
+ *
+ * // ❌ Compile error - Algorand is not in BridgeChain
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100'
+ * })
+ * ```
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link BridgeChainIdentifier} for the type that accepts these values.
+ */
+var BridgeChain;
+(function (BridgeChain) {
+    // Mainnet chains with CCTPv2 support
+    BridgeChain["Arbitrum"] = "Arbitrum";
+    BridgeChain["Avalanche"] = "Avalanche";
+    BridgeChain["Base"] = "Base";
+    BridgeChain["Codex"] = "Codex";
+    BridgeChain["Ethereum"] = "Ethereum";
+    BridgeChain["HyperEVM"] = "HyperEVM";
+    BridgeChain["Ink"] = "Ink";
+    BridgeChain["Linea"] = "Linea";
+    BridgeChain["Optimism"] = "Optimism";
+    BridgeChain["Plume"] = "Plume";
+    BridgeChain["Polygon"] = "Polygon";
+    BridgeChain["Sei"] = "Sei";
+    BridgeChain["Solana"] = "Solana";
+    BridgeChain["Sonic"] = "Sonic";
+    BridgeChain["Unichain"] = "Unichain";
+    BridgeChain["World_Chain"] = "World_Chain";
+    BridgeChain["XDC"] = "XDC";
+    // Testnet chains with CCTPv2 support
+    BridgeChain["Arc_Testnet"] = "Arc_Testnet";
+    BridgeChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
+    BridgeChain["Avalanche_Fuji"] = "Avalanche_Fuji";
+    BridgeChain["Base_Sepolia"] = "Base_Sepolia";
+    BridgeChain["Codex_Testnet"] = "Codex_Testnet";
+    BridgeChain["Ethereum_Sepolia"] = "Ethereum_Sepolia";
+    BridgeChain["HyperEVM_Testnet"] = "HyperEVM_Testnet";
+    BridgeChain["Ink_Testnet"] = "Ink_Testnet";
+    BridgeChain["Linea_Sepolia"] = "Linea_Sepolia";
+    BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
+    BridgeChain["Plume_Testnet"] = "Plume_Testnet";
+    BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
+    BridgeChain["Sei_Testnet"] = "Sei_Testnet";
+    BridgeChain["Solana_Devnet"] = "Solana_Devnet";
+    BridgeChain["Sonic_Testnet"] = "Sonic_Testnet";
+    BridgeChain["Unichain_Sepolia"] = "Unichain_Sepolia";
+    BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
+    BridgeChain["XDC_Apothem"] = "XDC_Apothem";
+})(BridgeChain || (BridgeChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -2263,6 +2358,44 @@ z.union([
     z.nativeEnum(Blockchain),
     chainDefinitionSchema,
 ]);
+/**
+ * Zod schema for validating bridge chain identifiers.
+ *
+ * This schema validates that the provided chain is supported for CCTPv2 bridging.
+ * It accepts either a BridgeChain enum value, a string matching a BridgeChain value,
+ * or a ChainDefinition for a supported chain.
+ *
+ * Use this schema when validating chain parameters for bridge operations to ensure
+ * only CCTPv2-supported chains are accepted at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { bridgeChainIdentifierSchema } from '@core/chains/validation'
+ * import { BridgeChain, Chains } from '@core/chains'
+ *
+ * // Valid - BridgeChain enum value
+ * bridgeChainIdentifierSchema.parse(BridgeChain.Ethereum)
+ *
+ * // Valid - string literal
+ * bridgeChainIdentifierSchema.parse('Base_Sepolia')
+ *
+ * // Valid - ChainDefinition (validated by CCTP support)
+ * bridgeChainIdentifierSchema.parse(Chains.Solana)
+ *
+ * // Invalid - Algorand is not in BridgeChain (throws ZodError)
+ * bridgeChainIdentifierSchema.parse('Algorand')
+ * ```
+ *
+ * @see {@link BridgeChain} for the enum of supported chains.
+ */
+z.union([
+    z.string().refine((val) => val in BridgeChain, (val) => ({
+        message: `Chain "${val}" is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
+    })),
+    chainDefinitionSchema.refine((chainDef) => chainDef.chain in BridgeChain, (chainDef) => ({
+        message: `Chain "${chainDef.name}" (${chainDef.chain}) is not supported for bridging. Only chains in the BridgeChain enum support CCTPv2 bridging.`,
+    })),
+]);
 
-export { Arbitrum, ArbitrumSepolia, ArcTestnet, Avalanche, AvalancheFuji, Base, BaseSepolia, Codex, CodexTestnet, Ethereum, EthereumSepolia, HyperEVM, HyperEVMTestnet, Ink, InkTestnet, Linea, LineaSepolia, Optimism, OptimismSepolia, Plume, PlumeTestnet, Polygon, PolygonAmoy, Sei, SeiTestnet, Solana, SolanaDevnet, Sonic, SonicTestnet, Unichain, UnichainSepolia, WorldChain, WorldChainSepolia, XDC, XDCApothem };
+export { Arbitrum, ArbitrumSepolia, ArcTestnet, Avalanche, AvalancheFuji, Base, BaseSepolia, BridgeChain, Codex, CodexTestnet, Ethereum, EthereumSepolia, HyperEVM, HyperEVMTestnet, Ink, InkTestnet, Linea, LineaSepolia, Optimism, OptimismSepolia, Plume, PlumeTestnet, Polygon, PolygonAmoy, Sei, SeiTestnet, Solana, SolanaDevnet, Sonic, SonicTestnet, Unichain, UnichainSepolia, WorldChain, WorldChainSepolia, XDC, XDCApothem };
 //# sourceMappingURL=chains.mjs.map