@circle-fin/bridge-kit 1.1.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @circle-fin/bridge-kit
 
+## 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
+
+- Add computeFee function to CustomFeePolicy that receives human-readable amounts (e.g., '100' for 100 USDC), deprecate calculateFee which receives smallest-unit amounts
+- Enhanced decimal format validation to standardize on strict dot (.) decimal separators. Amount, maxFee, and customFee fields now use a unified dot-decimal format. Supported examples include "1000.50" and "1.5"
+- Introduce the `BridgeChain` enum and `BridgeChainIdentifier` type to restrict chain selection to only CCTPv2-supported chains. This provides IDE autocomplete limited to valid bridge chains and ensures that passing an unsupported chain triggers a compile-time error.
+
+### Patch Changes
+
+- Updated BridgeKit to return `BridgeResults` in human readable units for `bridge()` and `retry()`. For example, when printing out the results of a `kit.bridge()` call with 1 USDC, the result's `amount` attribute will now show `'1.0'` instead of `'1000000'`.
+- Validation errors now use standardized error codes for consistent error handling. All validation failures return the same `KitError` structure as other SDK errors.
+
+  **Migration:** If you're catching validation errors, update your error handling:
+  - Check `error.code === 1098` instead of `instanceof ValidationError`
+  - Access details via `error.cause?.trace?.validationErrors` instead of `error.errors`
+
+  The legacy `ValidationError` class remains available for backward compatibility.
+
+- Documented the exact custom-fee flow across Bridge Kit’s README and JSDoc.
+  Clarified that kit-level and per-transfer custom fees are added to the transfer debit before CCTPv2 runs.
+
 ## 1.1.2
 
 ### Patch Changes

package/QUICKSTART.md

@@ -56,7 +56,7 @@ Before diving into the examples, it's important to understand the two address co
 
 ```typescript
 // User-controlled example - address resolved automatically
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY,
   // addressContext: 'user-controlled' is the default
 })
@@ -84,7 +84,7 @@ await kit.bridge({
 
 ```typescript
 // Developer-controlled example - explicit address control
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY,
   capabilities: {
     addressContext: 'developer-controlled',
@@ -190,14 +190,14 @@ The factory methods make getting started incredibly simple. Plus, you can create
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 // Initialize the kit (CCTPv2 provider included by default)
 const kit = new BridgeKit()
 
 // Create ONE adapter that can work across chains!
 // Uses 'user-controlled' by default - addresses resolved automatically
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -222,12 +222,12 @@ const result = await kit.bridge({
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
 
 // Create adapter with explicit address control
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   capabilities: {
     addressContext: 'developer-controlled', // Explicit address control
@@ -257,13 +257,13 @@ const result = await kit.bridge({
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 import { createPublicClient, http } from 'viem'
 
 const kit = new BridgeKit()
 
 // Production-ready setup with custom RPC endpoints
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   capabilities: {
     addressContext: 'user-controlled', // Explicit for clarity in production
@@ -296,13 +296,13 @@ For browser environments with wallet providers like MetaMask:
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromProvider } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromProvider } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
 
 // Create adapters from browser wallet providers
 // Browser wallets are typically user-controlled (one connected address)
-const adapter = await createAdapterFromProvider({
+const adapter = await createViemAdapterFromProvider({
   provider: window.ethereum,
   capabilities: {
     addressContext: 'user-controlled', // Browser wallets = user-controlled
@@ -412,7 +412,7 @@ type AdapterContext = { adapter: Adapter; chain: ChainIdentifier }
 **Chain-agnostic adapter creation**:
 
 ```typescript
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   chain: 'Ethereum',
 })
@@ -527,6 +527,122 @@ interface BridgeConfig {
 - **FAST**: Optimized for speed with potentially higher fees
 - **SLOW**: Optimized for cost with zero transfer fees but longer confirmation times
 
+## Custom Fees
+
+### Understanding How Custom Fees Work
+
+Custom fees allow you to charge developer fees on cross-chain USDC transfers. **The custom fee is added on top of the transfer amount.** The wallet signs for `amount + customFee`, the custom fee is split (10% to Circle, 90% to your `recipientAddress`) on the source chain, and the entire transfer amount continues through CCTPv2 unchanged.
+
+### Step-by-Step Example: 1,000 USDC Transfer with 10 USDC Custom Fee
+
+```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}`,
+})
+
+// User wants to transfer 1,000 USDC
+// You want to charge a 10 USDC custom fee
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '1000', // ← Amount forwarded to CCTPv2
+  config: {
+    customFee: {
+      value: '10', // ← Additional debit on top of the transfer amount
+      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+    },
+  },
+})
+```
+
+#### Breakdown of What Happens:
+
+| Stage                                 | Amount     | Description                                        |
+| ------------------------------------- | ---------- | -------------------------------------------------- |
+| **Wallet debit**                      | 1,010 USDC | User signs for transfer (1,000) + custom fee (10)  |
+| **Custom fee → Circle (10%)**         | 1 USDC     | Automatically routed to Circle on the source chain |
+| **Custom fee → Your recipient (90%)** | 9 USDC     | Sent to `0x742d35Cc...bEb0`                        |
+| **Forwarded to CCTPv2**               | 1,000 USDC | Transfer amount proceeds unchanged                 |
+| **CCTPv2 fee (FAST 1 bps example)**   | -0.1 USDC  | Protocol fee taken from the transfer amount        |
+| **Destination receives**              | 999.9 USDC | Amount minted on Base                              |
+
+**Summary:**
+
+- **Circle receives:** 10% of the custom fee (1 USDC in this example).
+- **You receive:** 90% of the custom fee (9 USDC).
+- **User receives:** Transfer amount minus the CCTPv2 protocol fee (999.9 USDC).
+- **Important:** Circle only participates in the 10% share when a custom fee is present. If you do not configure a custom fee for a transfer, Circle does not collect any additional amount.
+- **Total user debit:** 1,010.1 USDC (1,000 transfer + 10 custom fee + 0.1 protocol fee).
+
+### Per-Transfer Custom Fee
+
+Add a one-off fee directly inside `bridge` parameters:
+
+```typescript
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '100',
+  config: {
+    customFee: {
+      value: '1', // 1 USDC fee
+      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+    },
+  },
+})
+
+// Result (Fast Transfer):
+// - Wallet signs for 101 USDC (100 transfer + 1 custom fee)
+// - Custom fee split: 0.1 USDC to Circle, 0.9 USDC to your recipientAddress wallet
+// - 100 USDC forwarded to CCTPv2
+// - CCTPv2 fee: 0.01 USDC (1 bps)
+// - User receives: 99.99 USDC
+```
+
+### Kit-Level Fee Policy
+
+Set a global fee policy for all transfers:
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+
+const kit = new BridgeKit()
+
+kit.setCustomFeePolicy({
+  computeFee: (params) => {
+    const amount = parseFloat(params.amount)
+
+    // Example: Charge 1% fee
+    const feePercentage = 0.01
+    const fee = amount * feePercentage
+
+    // Return human-readable fee (e.g., '10' for 10 USDC)
+    return fee.toFixed(6)
+  },
+  resolveFeeRecipientAddress: (feePayoutChain) => {
+    // Return address for the source chain
+    if (feePayoutChain.type === 'solana') {
+      return 'YourSolanaAddressBase58Encoded...'
+    }
+    return '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0'
+  },
+})
+
+// Now all transfers automatically include the custom fee
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '1000',
+})
+// Custom fee (10 USDC) calculated and charged automatically
+```
+
+> **Note**: The `calculateFee` function is deprecated. Use `computeFee` instead, which receives human-readable amounts (e.g., `'100'` for 100 USDC) rather than smallest-unit amounts.
+
 ## Examples
 
 ### Example 1: EVM to EVM Transfer (Ethereum → Base)
@@ -535,13 +651,13 @@ interface BridgeConfig {
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
 
 // Create ONE adapter that can work across chains
 // Uses user-controlled by default - addresses resolved automatically
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -588,12 +704,12 @@ async function evmToEvmTransfer() {
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
 
 // Create adapter with explicit address control for enterprise use
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   capabilities: {
     addressContext: 'developer-controlled', // Enterprise/multi-address mode
@@ -632,7 +748,7 @@ async function enterpriseEvmToEvmTransfer() {
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 import { SolanaAdapter } from '@circle-fin/adapter-solana'
 import { Connection, Keypair } from '@solana/web3.js'
 import bs58 from 'bs58'
@@ -640,7 +756,7 @@ import bs58 from 'bs58'
 const kit = new BridgeKit()
 
 // Create EVM adapter (Ethereum) using factory method
-const ethereumAdapter = createAdapterFromPrivateKey({
+const ethereumAdapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   chain: 'Ethereum',
 })
@@ -686,12 +802,12 @@ async function evmToSolanaTransfer() {
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
 
 // Create ONE adapter that can work across chains
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
   chain: 'Ethereum',
 })
@@ -821,10 +937,10 @@ retry<
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -850,14 +966,14 @@ if (result.state === 'error') {
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey as createEvmAdapter } from '@circle-fin/adapter-viem-v2'
-import { createAdapterFromPrivateKey as createSolAdapter } from '@circle-fin/adapter-solana'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createSolanaAdapterFromPrivateKey } from '@circle-fin/adapter-solana'
 
 const kit = new BridgeKit()
-const evm = createEvmAdapter({
+const evm = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
-const sol = createSolAdapter({
+const sol = createSolanaAdapterFromPrivateKey({
   privateKey: process.env.SOL_PRIVATE_KEY as string,
 })
 
@@ -889,10 +1005,10 @@ if (result.state === 'error') {
 
 ```typescript
 import { BridgeKit, BridgeResult } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })
 
@@ -941,7 +1057,7 @@ if (result.state === 'error') {
 const mintStep = result.steps.find((s) => s.name === 'mint')
 if (result.state === 'error' && mintStep?.state === 'error') {
   // Recreate destination adapter with updated gas settings as needed
-  const dest = createAdapterFromPrivateKey({
+  const dest = createViemAdapterFromPrivateKey({
     privateKey: process.env.PRIVATE_KEY as `0x${string}`,
     // Provide a higher-priority RPC or adjust client gas policies here if supported by your setup
   })

package/README.md

@@ -36,6 +36,10 @@ _Making cross-chain stablecoin (USDC, and soon more tokens) transfers as simple
       - [3. **BridgeConfig** - Transfer Settings](#3-bridgeconfig---transfer-settings)
     - [Complete Example with All Options](#complete-example-with-all-options)
     - [Bridge Speed Configuration](#bridge-speed-configuration)
+  - [Custom Fees](#custom-fees)
+    - [How Custom Fees Work](#how-custom-fees-work)
+    - [1000 USDC Transfer Example](#1000-usdc-transfer-example)
+    - [Kit-Level Fee Policies](#kit-level-fee-policies)
   - [Error Handling](#error-handling)
   - [Retrying Failed Transfers](#retrying-failed-transfers)
   - [Examples](#examples)
@@ -133,13 +137,13 @@ The factory methods make it incredibly easy to get started with **built-in relia
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 // Initialize the kit
 const kit = new BridgeKit()
 
 // Create ONE adapter that works across all chains!
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as string,
 })
 
@@ -171,7 +175,7 @@ const result = await kit.bridge({
 })
 
 // Or use a different adapter for the destination chain
-const baseAdapter = createAdapterFromPrivateKey({
+const baseAdapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as string,
 })
 
@@ -194,7 +198,7 @@ const resultWithDifferentAdapter = await kit.bridge({
 import { createPublicClient, http } from 'viem'
 
 // Production-ready setup with custom RPC endpoints
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as string,
   getPublicClient: ({ chain }) =>
     createPublicClient({
@@ -222,10 +226,10 @@ const result = await kit.bridge({
 **Best for**: Browser applications, wallet integrations, user-controlled transactions
 
 ```typescript
-import { createAdapterFromProvider } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromProvider } from '@circle-fin/adapter-viem-v2'
 
 // Create adapters from browser wallet providers
-const adapter = await createAdapterFromProvider({
+const adapter = await createViemAdapterFromProvider({
   provider: window.ethereum,
 })
 
@@ -312,7 +316,7 @@ The Bridge Kit supports different configuration patterns to match your use case:
 
 ```typescript
 // Create chain-agnostic adapter
-const adapter = createAdapterFromPrivateKey({...})
+const adapter = createViemAdapterFromPrivateKey({...})
 
 // Always specify chain explicitly for clarity
 const adapterContext = { adapter, chain: 'Ethereum' }
@@ -360,6 +364,118 @@ const result = await kit.bridge({
 })
 ```
 
+## Custom Fees
+
+Bridge Kit allows you to charge custom developer fees on cross-chain USDC transfers. Understanding how these fees interact with wallet debits and CCTPv2 protocol fees is crucial for correct implementation.
+
+### How Custom Fees Work
+
+Custom fees are **added on top of the transfer amount**, not taken out of it. The wallet signs for `transfer amount + custom fee`, so the user must have enough balance for both values. The entire transfer amount continues through CCTPv2 unchanged, while the custom fee is split on the source chain:
+
+- **10%** of the custom fee is automatically routed to Circle.
+- **90%** is sent to your `recipientAddress`.
+- **Important:** Circle only takes the 10% share when a custom fee is actually charged. If you omit a custom fee, Circle does not collect anything beyond the protocol fee.
+
+After the custom fee is collected, the transfer amount (e.g., 1,000 USDC) proceeds through CCTPv2, where the protocol applies its own fee (1–14 bps in FAST mode, 0% in STANDARD).
+
+**Fee Flow (1,000 USDC transfer + 10 USDC custom fee):**
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│ User signs: 1,000 USDC transfer + 10 USDC custom fee = 1,010  │
+└──────────────────────┬────────────────────────────────────────┘
+                       │
+                       ▼
+┌───────────────────────────────────────────────────────────────┐
+│ Custom fee distribution (source chain)                        │
+│  - 1 USDC (10%) → Circle                                      │
+│  - 9 USDC (90%) → Your fee recipient                          │
+└──────────────────────┬────────────────────────────────────────┘
+                       │
+                       ▼
+┌───────────────────────────────────────────────────────────────┐
+│ CCTPv2 processes full transfer amount (1,000 USDC)            │
+│  - Protocol fee example (FAST 1 bps): 0.1 USDC                │
+│  - Destination receives: 999.9 USDC                           │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### 1,000 USDC Transfer Example
+
+**Scenario:** Transfer 1,000 USDC from Ethereum to Base with a 10 USDC custom fee.
+
+```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}`,
+})
+
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '1000', // Transfer amount forwarded to CCTPv2
+  config: {
+    customFee: {
+      value: '10', // Additional debit charged on top of the transfer amount
+      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+    },
+  },
+})
+```
+
+**What happens on-chain:**
+
+| Stage                         | Amount     | Description                                            |
+| ----------------------------- | ---------- | ------------------------------------------------------ |
+| **Transfer amount**           | 1,000 USDC | Forwarded to CCTPv2 without reduction                  |
+| **Custom fee debit**          | +10 USDC   | Wallet signs for 1,010 USDC total                      |
+| **Custom fee → Circle (10%)** | 1 USDC     | Automatically routed to Circle                         |
+| **Custom fee → You (90%)**    | 9 USDC     | Sent to `0x742d35Cc...bEb0` (your fee recipient)       |
+| **CCTPv2 fee (FAST 1 bps)\*** | -0.1 USDC  | Protocol fee taken from the 1,000 USDC transfer amount |
+| **Destination receives**      | 999.9 USDC | Amount minted on Base after protocol fee               |
+
+\* \_CCTPv2 FAST transfers charge 1–14 bps depending on the route; STANDARD transfers charge 0 bps.
+
+### Kit-Level Fee Policies
+
+For dynamic fee calculation across all transfers, use kit-level policies:
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+
+const kit = new BridgeKit()
+
+kit.setCustomFeePolicy({
+  computeFee: (params) => {
+    const amount = parseFloat(params.amount)
+
+    const feePercentage = 0.01 // 1%
+    const calculatedFee = amount * feePercentage
+
+    // Return human-readable fee (e.g., '10' for 10 USDC)
+    return calculatedFee.toFixed(6)
+  },
+  resolveFeeRecipientAddress: (feePayoutChain) => {
+    // Return appropriate address for source chain
+    return feePayoutChain.type === 'solana'
+      ? 'SolanaAddressBase58...'
+      : '0xEvmAddress...'
+  },
+})
+
+// All subsequent bridges will use this policy
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '1000', // Custom fee calculated automatically
+})
+```
+
+> **Note**: The `calculateFee` function is deprecated. Use `computeFee` instead, which receives human-readable amounts (e.g., `'100'` for 100 USDC) rather than smallest-unit amounts.
+
 ## Error Handling
 
 The kit uses a thoughtful error handling approach:
@@ -369,10 +485,10 @@ The kit uses a thoughtful error handling approach:
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as string,
 })
 
@@ -415,10 +531,10 @@ retry<
 
 ```typescript
 import { BridgeKit } from '@circle-fin/bridge-kit'
-import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
 
 const kit = new BridgeKit()
-const adapter = createAdapterFromPrivateKey({
+const adapter = createViemAdapterFromPrivateKey({
   privateKey: process.env.PRIVATE_KEY as `0x${string}`,
 })