@circle-fin/bridge-kit 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @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
+
+- **Enhanced bridge estimate response**: `EstimateResult` now includes `token`, `amount`, `source`, `destination` fields to provide complete transfer information alongside cost estimates.
+- Export error handling utilities and constants.
+
+New exports include:
+
+- Error type guards: isKitError, isBalanceError, isOnchainError, isRpcError, isNetworkError, isRetryableError, isFatalError
+- Error constants: BalanceError, OnchainError, RpcError, NetworkError, InputError
+- Utility: getErrorCode, getErrorMessage
+
 ## 1.2.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

@@ -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
  *
@@ -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

@@ -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
  *
@@ -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

@@ -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
  *
@@ -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,