@circle-fin/bridge-kit 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @circle-fin/bridge-kit
 
+## 1.4.0
+
+### Minor Changes
+
+- Add optional filtering to `getSupportedChains()` method to filter chains by type (EVM, Solana) and network (mainnet/testnet)
+
 ## 1.3.0
 
 ### Minor Changes

package/QUICKSTART.md

@@ -1421,7 +1421,7 @@ const attestation = await retryWithBackoff(
 
 ## Next Steps
 
-- **Explore Examples**: Check out the [examples directory](https://github.com/circlefin/stablecoin-kits-private/tree/main/examples) for more detailed implementations
+- **Explore Examples**: Check out the [examples directory](https://github.com/crcl-main/stablecoin-kits-private/tree/main/examples) for more detailed implementations
 - **Join the community**: Connect with other developers on [discord](https://discord.com/invite/buildoncircle) building on Circle's stablecoin infrastructure
 
 Ready to start bridging? Let's make cross-chain bridging as easy as a single function call! 🌉

package/README.md

@@ -194,26 +194,50 @@ const resultWithDifferentAdapter = await kit.bridge({
 
 **Best for**: Production applications, better reliability, custom configuration
 
+Bridging involves **two chains** (source and destination), and both require properly configured RPC endpoints. Use dynamic RPC mapping by chain ID to support multiple chains in a single adapter:
+
 ```typescript
-import { createPublicClient, http } from 'viem'
+import 'dotenv/config'
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { Ethereum, Base } from '@circle-fin/bridge-kit/chains'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createPublicClient, http, fallback } from 'viem'
+
+// Define RPCs mapped by chain ID
+const RPC_BY_CHAIN_ID: Record<number, string[]> = {
+  // The array allows providing multiple RPC URLs for fallback, e.g.,
+  // `[ "https://primary-rpc-url.com/...", "https://secondary-rpc-url.com/..." ]`
+  [Ethereum.chainId]: [
+    `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
+  ],
+  [Base.chainId]: [
+    `https://base-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
+  ],
+}
 
-// Production-ready setup with custom RPC endpoints
 const adapter = createViemAdapterFromPrivateKey({
-  privateKey: process.env.PRIVATE_KEY as string,
-  getPublicClient: ({ chain }) =>
-    createPublicClient({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  getPublicClient: ({ chain }) => {
+    const rpcUrls = RPC_BY_CHAIN_ID[chain.id]
+    if (!rpcUrls) {
+      throw new Error(`No RPC configured for chainId=${chain.id}`)
+    }
+    return createPublicClient({
       chain,
-      transport: http(
-        `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
-        {
-          retryCount: 3,
-          timeout: 10000,
-        },
+      transport: fallback(
+        rpcUrls.map((url) =>
+          http(url, {
+            timeout: 10_000,
+            retryCount: 3,
+          }),
+        ),
       ),
-    }),
+    })
+  },
 })
 
-// Same simple usage, but with production-grade RPC
+const kit = new BridgeKit()
+
 const result = await kit.bridge({
   from: { adapter, chain: 'Ethereum' },
   to: { adapter, chain: 'Base' },
@@ -221,13 +245,22 @@ const result = await kit.bridge({
 })
 ```
 
+**Best practices:**
+
+- **Use paid RPC providers** (Alchemy, Infura, QuickNode) for improved reliability
+- **Implement `fallback()` transport** for automatic failover between endpoints
+- **Configure timeout and retry options** to handle network variability
+
 ### 🌐 Browser/Wallet Provider Support
 
 **Best for**: Browser applications, wallet integrations, user-controlled transactions
 
 ```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
 import { createViemAdapterFromProvider } from '@circle-fin/adapter-viem-v2'
 
+const kit = new BridgeKit()
+
 // Create adapters from browser wallet providers
 const adapter = await createViemAdapterFromProvider({
   provider: window.ethereum,
@@ -254,10 +287,10 @@ import { privateKeyToAccount } from 'viem/accounts'
 
 const account = privateKeyToAccount(process.env.PRIVATE_KEY as string)
 
-// Chain-specific RPC URLs
-const rpcUrls = {
-  [Ethereum.id]: 'https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY',
-  [Base.id]: 'https://base-mainnet.g.alchemy.com/v2/YOUR_KEY',
+// Chain-specific RPC URLs mapped by chain ID
+const rpcUrls: Record<number, string> = {
+  [Ethereum.chainId]: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
+  [Base.chainId]: 'https://base-mainnet.g.alchemy.com/v2/YOUR_KEY',
 }
 
 // Create one multi-chain adapter with chain-specific RPC configuration
@@ -445,8 +478,12 @@ For dynamic fee calculation across all transfers, use kit-level policies:
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
+const adapter = createViemAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+})
 
 kit.setCustomFeePolicy({
   computeFee: (params) => {

package/chains.cjs

@@ -366,8 +366,11 @@ const ArcTestnet = defineChain({
     name: 'Arc Testnet',
     title: 'ArcTestnet',
     nativeCurrency: {
-        name: 'Arc',
-        symbol: 'Arc',
+        name: 'USDC',
+        symbol: 'USDC',
+        // Arc uses native USDC with 18 decimals for gas payments (EVM standard).
+        // Note: The ERC-20 USDC contract at usdcAddress uses 6 decimals.
+        // See: https://docs.arc.network/arc/references/contract-addresses
         decimals: 18,
     },
     chainId: 5042002,

package/chains.d.ts

@@ -184,8 +184,8 @@ declare const ArcTestnet: {
     readonly name: "Arc Testnet";
     readonly title: "ArcTestnet";
     readonly nativeCurrency: {
-        readonly name: "Arc";
-        readonly symbol: "Arc";
+        readonly name: "USDC";
+        readonly symbol: "USDC";
         readonly decimals: 18;
     };
     readonly chainId: 5042002;

package/chains.mjs

@@ -364,8 +364,11 @@ const ArcTestnet = defineChain({
     name: 'Arc Testnet',
     title: 'ArcTestnet',
     nativeCurrency: {
-        name: 'Arc',
-        symbol: 'Arc',
+        name: 'USDC',
+        symbol: 'USDC',
+        // Arc uses native USDC with 18 decimals for gas payments (EVM standard).
+        // Note: The ERC-20 USDC contract at usdcAddress uses 6 decimals.
+        // See: https://docs.arc.network/arc/references/contract-addresses
         decimals: 18,
     },
     chainId: 5042002,

package/index.cjs

@@ -482,6 +482,12 @@ const InputError = {
         name: 'INPUT_INVALID_CHAIN',
         type: 'INPUT',
     },
+    /** Invalid or unknown token (symbol not found, missing decimals, etc.) */
+    INVALID_TOKEN: {
+        code: 1006,
+        name: 'INPUT_INVALID_TOKEN',
+        type: 'INPUT',
+    },
     /** General validation failure for complex validation rules */
     VALIDATION_FAILED: {
         code: 1098,
@@ -1264,8 +1270,11 @@ const ArcTestnet = defineChain({
     name: 'Arc Testnet',
     title: 'ArcTestnet',
     nativeCurrency: {
-        name: 'Arc',
-        symbol: 'Arc',
+        name: 'USDC',
+        symbol: 'USDC',
+        // Arc uses native USDC with 18 decimals for gas payments (EVM standard).
+        // Note: The ERC-20 USDC contract at usdcAddress uses 6 decimals.
+        // See: https://docs.arc.network/arc/references/contract-addresses
         decimals: 18,
     },
     chainId: 5042002,
@@ -4630,7 +4639,7 @@ const parseAmount = (params) => {
 };
 
 var name = "@circle-fin/bridge-kit";
-var version = "1.3.0";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -5907,7 +5916,7 @@ class BridgeKit {
         return formatBridgeResult(await provider.estimate(finalResolvedParams), 'to-human-readable');
     }
     /**
-     * Get all chains supported by any provider in the kit.
+     * Get all chains supported by any provider in the kit, with optional filtering.
      *
      * Aggregate and deduplicate the supported chains from all registered providers.
      * This provides a comprehensive list of chains that can be used as either source
@@ -5917,6 +5926,7 @@ class BridgeKit {
      * ensuring each chain appears only once in the result regardless of how many
      * providers support it.
      *
+     * @param options - Optional filtering options to narrow down the returned chains
      * @returns Array of unique chain definitions supported by the registered providers
      *
      * @example
@@ -5924,19 +5934,56 @@ class BridgeKit {
      * import { BridgeKit } from '@circle-fin/bridge-kit'
      *
      * const kit = new BridgeKit()
-     * const chains = kit.getSupportedChains()
+     *
+     * // Get all supported chains (no filtering)
+     * const allChains = kit.getSupportedChains()
+     *
+     * // Get only EVM chains
+     * const evmChains = kit.getSupportedChains({ chainType: 'evm' })
+     *
+     * // Get EVM and Solana chains
+     * const evmAndSolana = kit.getSupportedChains({ chainType: ['evm', 'solana'] })
+     *
+     * // Get only mainnet chains
+     * const mainnets = kit.getSupportedChains({ isTestnet: false })
+     *
+     * // Get only EVM mainnet chains
+     * const evmMainnets = kit.getSupportedChains({ chainType: 'evm', isTestnet: false })
      *
      * console.log('Supported chains:')
-     * chains.forEach(chain => {
+     * allChains.forEach(chain => {
      *   console.log(`- ${chain.name} (${chain.type})`)
      * })
      * ```
      */
-    getSupportedChains() {
+    getSupportedChains(options) {
         const supportedChains = this.providers.flatMap((p) => p.supportedChains);
         // Deduplicate chains by using chain identifiers as object keys
         // Later duplicates will override earlier ones, keeping only the last occurrence
-        return Object.values(Object.fromEntries(supportedChains.map((chain) => [chain.chain, chain])));
+        let chains = Object.values(Object.fromEntries(supportedChains.map((chain) => [chain.chain, chain])));
+        // Apply chain type filter if provided
+        if (options?.chainType !== undefined) {
+            // Validate at runtime since JS consumers can bypass TypeScript's narrow type.
+            const supportedChainTypes = ['evm', 'solana'];
+            const chainTypeInput = options.chainType;
+            const chainTypeValues = Array.isArray(chainTypeInput)
+                ? chainTypeInput
+                : [chainTypeInput];
+            if (!chainTypeValues.every((chainType) => supportedChainTypes.includes(chainType))) {
+                const listFormatter = new Intl.ListFormat('en', {
+                    style: 'long',
+                    type: 'conjunction',
+                });
+                throw createValidationFailedError$1('options.chainType', options.chainType, `Supported chain types include: ${listFormatter.format(supportedChainTypes)}`);
+            }
+            const chainTypes = new Set(chainTypeValues);
+            chains = chains.filter((chain) => chainTypes.has(chain.type));
+        }
+        // Apply testnet filter if provided
+        if (options?.isTestnet !== undefined) {
+            chains = chains.filter((chain) => chain.isTestnet === options.isTestnet);
+        }
+        return chains;
     }
     /**
      * Validate that source and destination chains are on the same network type.