@circle-fin/provider-cctp-v2 0.0.2-alpha.7 → 1.0.0

package/README.md

@@ -5,8 +5,9 @@
 [![npm version](https://badge.fury.io/js/@circle-fin%2Fprovider-cctp-v2.svg)](https://badge.fury.io/js/@circle-fin%2Fprovider-cctp-v2)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Discord](https://img.shields.io/discord/473781666251538452?label=Discord&logo=discord)](https://discord.com/invite/buildoncircle)
 
-**Circle's Cross-Chain Transfer Protocol v2 provider for Stablecoin Kits**
+**Circle's Cross-Chain Transfer Protocol v2 provider for Bridge Kit**
 
 _Native USDC bridging across 34 chains using Circle's battle-tested protocols._
 
@@ -20,19 +21,19 @@ _Native USDC bridging across 34 chains using Circle's battle-tested protocols._
     - [Why CCTPv2 Provider?](#why-cctpv2-provider)
   - [Installation](#installation)
   - [Quick Start](#quick-start)
-    - [Option 1: With Bridging Kit (Recommended)](#option-1-with-bridging-kit-recommended)
+    - [Option 1: With Bridge Kit (Recommended)](#option-1-with-bridge-kit-recommended)
     - [Option 2: Direct Provider Usage](#option-2-direct-provider-usage)
   - [Features](#features)
   - [Supported Chains \& Routes](#supported-chains--routes)
-    - [Mainnet Chains (12 chains)](#mainnet-chains-12-chains)
-    - [Testnet Chains (12 chains)](#testnet-chains-12-chains)
+    - [Mainnet Chains](#mainnet-chains)
+    - [Testnet Chains](#testnet-chains)
   - [Usage Examples](#usage-examples)
     - [Basic Bridge Operation](#basic-bridge-operation)
     - [Route Validation](#route-validation)
     - [Bridge Configurations](#bridge-configurations)
   - [Error Handling](#error-handling)
   - [Bridge Process](#bridge-process)
-  - [Integration with Bridging Kit](#integration-with-bridging-kit)
+  - [Integration with Bridge Kit](#integration-with-bridge-kit)
   - [API Reference](#api-reference)
     - [Core Methods](#core-methods)
     - [Transfer Parameters](#transfer-parameters)
@@ -42,9 +43,9 @@ _Native USDC bridging across 34 chains using Circle's battle-tested protocols._
 
 ## Overview
 
-The CCTPv2 Bridging Provider is a strongly-typed implementation of Circle's Cross-Chain Transfer Protocol (CCTP) version 2 that enables **native USDC bridging** between 24+ supported blockchain networks.
+The CCTPv2 Bridging Provider is a strongly-typed implementation of Circle's Cross-Chain Transfer Protocol (CCTP) version 2 that enables **native USDC bridging** between 34+ supported blockchain networks.
 
-While primarily designed to power the [Bridging Kit](https://www.npmjs.com/package/@circle-fin/bridging-kit), this provider can also be used **directly in applications** that need fine-grained control over the CCTP transfer process or want to integrate CCTP without the full Stablecoin Kits framework.
+While primarily designed to power the [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit), this provider can also be used **directly in applications** that need fine-grained control over the CCTP transfer process or want to integrate CCTP without the full Stablecoin Kits framework.
 
 ### Why CCTPv2 Provider?
 
@@ -62,21 +63,21 @@ npm install @circle-fin/provider-cctp-v2
 yarn add @circle-fin/provider-cctp-v2
 ```
 
-> **Note**: This provider is included by default with the [Bridging Kit](https://www.npmjs.com/package/@circle-fin/bridging-kit). You can import this provider if you need to do a custom CCTP integration.
+> **Note**: This provider is included by default with the [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit). You can import this provider if you need to do a custom CCTP integration.
 
 ## Quick Start
 
-### Option 1: With Bridging Kit (Recommended)
+### Option 1: With Bridge Kit (Recommended)
 
 ```typescript
-import { BridgingKit } from '@circle-fin/bridging-kit'
+import { BridgeKit } from '@circle-fin/bridge-kit'
 
 // Provider included by default
-const kit = new BridgingKit()
+const kit = new BridgeKit()
 
 const result = await kit.bridge({
-  source: { adapter: sourceAdapter },
-  destination: { adapter: destAdapter },
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: { adapter: destAdapter, chain: 'Base' },
   amount: '100.50',
 })
 ```
@@ -113,16 +114,16 @@ const isSupported = provider.supportsRoute('Ethereum', 'Base', 'USDC')
 
 // Get bridge estimate
 const estimate = await provider.estimate({
-  source: { adapter: sourceAdapter },
-  destination: { adapter: destAdapter },
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: { adapter: destAdapter, chain: 'Base' },
   amount: '100.50',
   config: { transferSpeed: 'FAST' },
 })
 
 // Execute bridge operation with custom logic
 const result = await provider.bridge({
-  source: { adapter: sourceAdapter },
-  destination: { adapter: destAdapter },
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: { adapter: destAdapter, chain: 'Base' },
   amount: '100.50',
   config: { transferSpeed: 'FAST' },
 })
@@ -141,92 +142,14 @@ const result = await provider.bridge({
 
 The provider supports **544 total bridge routes** across these chains:
 
-### Mainnet Chains (17 chains)
+### Mainnet Chains
 
 **Arbitrum**, **Avalanche**, **Base**, **Codex**, **Ethereum**, **HyperEVM**, **Ink**, **Linea**, **OP Mainnet**, **Plume**, **Polygon PoS**, **Sei**, **Solana**, **Sonic**, **Unichain**, **World Chain**, **XDC**
 
-### Testnet Chains (17 chains)
+### Testnet Chains
 
 **Arbitrum Sepolia**, **Avalanche Fuji**, **Base Sepolia**, **Codex Testnet**, **Ethereum Sepolia**, **HyperEVM Testnet**, **Ink Testnet**, **Linea Sepolia**, **OP Sepolia**, **Plume Testnet**, **Polygon PoS Amoy**, **Sei Testnet**, **Solana Devnet**, **Sonic Testnet**, **Unichain Sepolia**, **World Chain Sepolia**, **XDC Apothem**
 
-## Usage Examples
-
-### Basic Bridge Operation
-
-```typescript
-import { BridgingKit } from '@circle-fin/bridging-kit'
-import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
-import { createPublicClient, createWalletClient, http } from 'viem'
-import { mainnet, base } from 'viem/chains'
-import { privateKeyToAccount } from 'viem/accounts'
-
-const account = privateKeyToAccount(process.env.PRIVATE_KEY)
-const kit = new BridgingKit() // CCTPv2 provider included by default
-
-const ethereumAdapter = new ViemAdapter({
-  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
-  walletClient: createWalletClient({
-    account,
-    chain: mainnet,
-    transport: http(),
-  }),
-})
-
-const baseAdapter = new ViemAdapter({
-  publicClient: createPublicClient({ chain: base, transport: http() }),
-  walletClient: createWalletClient({ account, chain: base, transport: http() }),
-})
-
-const result = await kit.bridge({
-  source: { adapter: ethereumAdapter },
-  destination: { adapter: baseAdapter },
-  amount: '100.50',
-  config: { transferSpeed: 'FAST' },
-})
-```
-
-### Route Validation
-
-```typescript
-import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
-import { BridgingKit } from '@circle-fin/bridging-kit'
-
-const provider = new CCTPV2BridgingProvider()
-const kit = new BridgingKit()
-
-// Check if a route is supported
-const isSupported = provider.supportsRoute('Ethereum', 'Base', 'USDC')
-console.log('Ethereum → Base:', isSupported ? '✅' : '❌')
-
-// Validate before bridging
-const sourceChain = 'Ethereum'
-const destChain = 'Base'
-if (!kit.supportsRoute(sourceChain, destChain, 'USDC')) {
-  throw new Error('Route not supported')
-}
-```
-
-### Bridge Configurations
-
-```typescript
-// Using the same kit and adapters from the examples above
-// Fast bridge (higher fees, faster processing)
-const fastResult = await kit.bridge({
-  source: { adapter: ethereumAdapter },
-  destination: { adapter: baseAdapter },
-  amount: '50.0',
-  config: { transferSpeed: 'FAST' },
-})
-
-// Slow bridge (lower fees, longer processing)
-const slowResult = await kit.bridge({
-  source: { adapter: ethereumAdapter },
-  destination: { adapter: baseAdapter },
-  amount: '50.0',
-  config: { transferSpeed: 'SLOW' },
-})
-```
-
 ## Error Handling
 
 The provider implements thoughtful error handling for different scenarios:
@@ -234,8 +157,8 @@ The provider implements thoughtful error handling for different scenarios:
 ```typescript
 // Using the same kit and adapters from the examples above
 const params = {
-  source: { adapter: ethereumAdapter },
-  destination: { adapter: baseAdapter },
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: { adapter: destAdapter, chain: 'Base' },
   amount: '100.50',
 }
 
@@ -276,12 +199,12 @@ The CCTPv2 provider handles the complete cross-chain bridging flow:
 
 Each step is tracked and can be monitored through the Provider's event system. Transaction details for each step include explorer URLs for easy verification on block explorers.
 
-## Integration with Bridging Kit
+## Integration with Bridge Kit
 
-This provider is designed specifically for the [Bridging Kit](https://www.npmjs.com/package/@circle-fin/bridging-kit):
+This provider is designed specifically for the [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit):
 
 ```typescript
-import { BridgingKit } from '@circle-fin/bridging-kit'
+import { BridgeKit } from '@circle-fin/bridge-kit'
 import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
 import { createPublicClient, createWalletClient, http } from 'viem'
 import { mainnet, base } from 'viem/chains'
@@ -290,7 +213,7 @@ import { privateKeyToAccount } from 'viem/accounts'
 const account = privateKeyToAccount(process.env.PRIVATE_KEY)
 
 // Provider is included by default
-const kit = new BridgingKit()
+const kit = new BridgeKit()
 
 const sourceAdapter = new ViemAdapter({
   publicClient: createPublicClient({ chain: mainnet, transport: http() }),
@@ -315,31 +238,12 @@ kit.on('mint', (event) => console.log('Mint:', event.values.txHash))
 
 // Execute transfer
 const result = await kit.bridge({
-  source: { adapter: sourceAdapter },
-  destination: { adapter: destAdapter },
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: { adapter: destAdapter, chain: 'Base' },
   amount: '25.0',
 })
 ```
 
-## API Reference
-
-### Core Methods
-
-- `supportsRoute(source, destination, token)` - Check if transfer route is supported
-- `bridge(params)` - Execute cross-chain bridge operation
-- `estimate(params)` - Get cost estimates for transfer
-
-### Transfer Parameters
-
-```typescript
-interface BridgeParams {
-  source: WalletContextWithFlexibleChain
-  destination: WalletContextWithFlexibleChain
-  amount: string
-  config?: BridgeConfig
-}
-```
-
 ## Development
 
 This package is part of the Stablecoin Kits monorepo.

package/index.cjs.js

@@ -18,6 +18,17 @@
 
 'use strict';
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for @solana/spl-token and other Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 var zod = require('zod');
 var bytes = require('@ethersproject/bytes');
 var address = require('@ethersproject/address');
@@ -2152,7 +2163,7 @@ var Chains = {
  *
  * @example
  * ```typescript
- * import { isCCTPV2Supported } from '@circle-fin/bridging-kit'
+ * import { isCCTPV2Supported } from '@circle-fin/bridge-kit'
  *
  * const isSupported = isCCTPV2Supported(ethChainDefinition)
  * console.log(isSupported) // true
@@ -2244,6 +2255,11 @@ const baseChainDefinitionSchema = zod.z.object({
     eurcAddress: zod.z.string().nullable(),
     usdcAddress: zod.z.string().nullable(),
     cctp: zod.z.any().nullable(), // We'll accept any CCTP config structure
+    kitContracts: zod.z
+        .object({
+        bridge: zod.z.string().optional(),
+    })
+        .optional(),
 });
 /**
  * Zod schema for validating EVM chain definitions specifically.
@@ -2275,13 +2291,15 @@ const baseChainDefinitionSchema = zod.z.object({
  * }
  * ```
  */
-const evmChainDefinitionSchema = baseChainDefinitionSchema.extend({
+const evmChainDefinitionSchema = baseChainDefinitionSchema
+    .extend({
     type: zod.z.literal('evm'),
     chainId: zod.z.number({
         required_error: 'EVM chains must have a chainId. Please provide a valid EVM chain ID.',
         invalid_type_error: 'EVM chain ID must be a number.',
     }),
-});
+})
+    .strict(); //// Reject any additional properties not defined in the schema
 /**
  * Zod schema for validating non-EVM chain definitions.
  * This schema extends the base schema with non-EVM specific properties.
@@ -2301,7 +2319,7 @@ const nonEvmChainDefinitionSchema = baseChainDefinitionSchema
         'polkadot',
     ]),
 })
-    .strict(); // Reject additional properties like chainId
+    .strict(); // Reject any additional properties not defined in the schema
 /**
  * Discriminated union schema for all chain definitions.
  * This schema validates different chain types based on their 'type' field.
@@ -2574,8 +2592,8 @@ class BridgingProvider {
  *
  * @example
  * ```typescript
- * setKitIdentifier('bridging-kit', '1.2.3')
- * getUserAgent() // "bridging-kit/1.2.3 (node/18.16.0)"
+ * setKitIdentifier('bridge-kit', '1.2.3')
+ * getUserAgent() // "bridge-kit/1.2.3 (node/18.16.0)"
  * ```
  *
  * @returns The Stablecoin Kits SDK user agent string.
@@ -2610,7 +2628,7 @@ function getRuntime() {
 /**
  * Get the user agent string for Stablecoin Kits SDK (universal, sync).
  *
- * @returns The user agent string, e.g., "bridging-kit/1.2.3 (node/18.16.0)"
+ * @returns The user agent string, e.g., "bridge-kit/1.2.3 (node/18.16.0)"
  */
 function getUserAgent() {
     if (cachedUserAgent !== undefined)
@@ -4188,67 +4206,48 @@ class KitError extends Error {
 }
 
 /**
- * Standardized error codes for INPUT type errors.
+ * Standardized error definitions for INPUT type errors.
+ *
+ * Each entry combines the numeric error code with its corresponding
+ * string name to ensure consistency when creating error instances.
  *
  * Error codes follow a hierarchical numbering scheme where the first digit
  * indicates the error category (1 = INPUT) and subsequent digits provide
  * specific error identification within that category.
  *
+ *
  * @example
  * ```typescript
- * import { InputErrorCode, InputErrorName } from '@core/errors'
+ * import { InputError } from '@core/errors'
  *
  * const error = new KitError({
- *   code: InputErrorCode.NETWORK_MISMATCH,
- *   name: InputErrorName.NETWORK_MISMATCH,
+ *   ...InputError.NETWORK_MISMATCH,
  *   recoverability: 'FATAL',
  *   message: 'Source and destination networks must be different'
  * })
+ *
+ * // Access code and name individually if needed
+ * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
+ * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
  * ```
  */
-var InputErrorCode;
-(function (InputErrorCode) {
+const InputError = {
     /** Network type mismatch between chains (mainnet vs testnet) */
-    InputErrorCode[InputErrorCode["NETWORK_MISMATCH"] = 1001] = "NETWORK_MISMATCH";
-    /** Invalid amount format or value (negative, zero, or malformed) */
-    InputErrorCode[InputErrorCode["INVALID_AMOUNT"] = 1002] = "INVALID_AMOUNT";
+    NETWORK_MISMATCH: {
+        code: 1001,
+        name: 'INPUT_NETWORK_MISMATCH',
+    },
     /** Unsupported or invalid bridge route configuration */
-    InputErrorCode[InputErrorCode["UNSUPPORTED_ROUTE"] = 1003] = "UNSUPPORTED_ROUTE";
-    /** Invalid wallet or contract address format */
-    InputErrorCode[InputErrorCode["INVALID_ADDRESS"] = 1004] = "INVALID_ADDRESS";
-    /** Invalid or unsupported chain identifier */
-    InputErrorCode[InputErrorCode["INVALID_CHAIN"] = 1005] = "INVALID_CHAIN";
+    UNSUPPORTED_ROUTE: {
+        code: 1003,
+        name: 'INPUT_UNSUPPORTED_ROUTE',
+    },
     /** General validation failure for complex validation rules */
-    InputErrorCode[InputErrorCode["VALIDATION_FAILED"] = 1098] = "VALIDATION_FAILED";
-})(InputErrorCode || (InputErrorCode = {}));
-/**
- * Standardized error names for INPUT type errors.
- *
- * These names correspond 1:1 with InputErrorCode and should always
- * be used together to ensure consistency across error instances.
- *
- * @example
- * ```typescript
- * import { InputErrorCode, InputErrorName } from '@core/errors'
- *
- * // Use matching code and name enums
- * const error = new KitError({
- *   code: InputErrorCode.NETWORK_MISMATCH,
- *   name: InputErrorName.NETWORK_MISMATCH,
- *   recoverability: 'FATAL',
- *   message: 'Network mismatch detected'
- * })
- * ```
- */
-var InputErrorName;
-(function (InputErrorName) {
-    InputErrorName["NETWORK_MISMATCH"] = "INPUT_NETWORK_MISMATCH";
-    InputErrorName["INVALID_AMOUNT"] = "INPUT_INVALID_AMOUNT";
-    InputErrorName["UNSUPPORTED_ROUTE"] = "INPUT_UNSUPPORTED_ROUTE";
-    InputErrorName["INVALID_ADDRESS"] = "INPUT_INVALID_ADDRESS";
-    InputErrorName["INVALID_CHAIN"] = "INPUT_INVALID_CHAIN";
-    InputErrorName["VALIDATION_FAILED"] = "INPUT_VALIDATION_FAILED";
-})(InputErrorName || (InputErrorName = {}));
+    VALIDATION_FAILED: {
+        code: 1098,
+        name: 'INPUT_VALIDATION_FAILED',
+    },
+};
 
 /**
  * Creates error for network type mismatch between source and destination.
@@ -4275,8 +4274,7 @@ function createNetworkMismatchError(sourceChain, destChain) {
     const sourceNetworkType = sourceChain.isTestnet ? 'testnet' : 'mainnet';
     const destNetworkType = destChain.isTestnet ? 'testnet' : 'mainnet';
     const errorDetails = {
-        code: InputErrorCode.NETWORK_MISMATCH,
-        name: InputErrorName.NETWORK_MISMATCH,
+        ...InputError.NETWORK_MISMATCH,
         recoverability: 'FATAL',
         message: `Cannot bridge between ${sourceChain.name} (${sourceNetworkType}) and ${destChain.name} (${destNetworkType}). Source and destination networks must both be testnet or both be mainnet.`,
         cause: {
@@ -4305,8 +4303,7 @@ function createNetworkMismatchError(sourceChain, destChain) {
  */
 function createUnsupportedRouteError(source, destination) {
     const errorDetails = {
-        code: InputErrorCode.UNSUPPORTED_ROUTE,
-        name: InputErrorName.UNSUPPORTED_ROUTE,
+        ...InputError.UNSUPPORTED_ROUTE,
         recoverability: 'FATAL',
         message: `Route from ${source} to ${destination} is not supported.`,
         cause: {
@@ -4353,8 +4350,7 @@ function createValidationFailedError(field, value, reason) {
         valueString = String(value);
     }
     const errorDetails = {
-        code: InputErrorCode.VALIDATION_FAILED,
-        name: InputErrorName.VALIDATION_FAILED,
+        ...InputError.VALIDATION_FAILED,
         recoverability: 'FATAL',
         message: `Validation failed for '${field}': ${valueString} - ${reason}.`,
         cause: {
@@ -4518,15 +4514,21 @@ mintAddress) => {
         return rawAddress;
     }
     else {
-        const [{ getAssociatedTokenAddress }, { PublicKey }] = await Promise.all([
-            import('@solana/spl-token'),
-            import('@solana/web3.js'),
-        ]);
         // Solana: derive the associated token account
-        const owner = new PublicKey(rawAddress);
-        const mintPub = new PublicKey(mintAddress);
-        const ata = await getAssociatedTokenAddress(mintPub, owner);
-        return ata.toBase58();
+        // Use dynamic import to avoid loading Solana dependencies for EVM-only users
+        try {
+            const [{ PublicKey }, { getAssociatedTokenAddressSync }] = await Promise.all([
+                import('@solana/web3.js'),
+                import('@solana/spl-token'),
+            ]);
+            const owner = new PublicKey(rawAddress);
+            const mintPub = new PublicKey(mintAddress);
+            const ata = getAssociatedTokenAddressSync(mintPub, owner);
+            return ata.toBase58();
+        }
+        catch {
+            throw new Error('Failed to derive Solana token account. Please ensure @solana/web3.js and @solana/spl-token are installed: npm install @solana/web3.js @solana/spl-token');
+        }
     }
 };
 
@@ -4764,6 +4766,7 @@ async function bridgeFetchAttestation({ params, provider, }, txHash) {
             ...step,
             state: 'error',
             error: err,
+            data: undefined,
         };
     }
     return step;
@@ -4946,12 +4949,29 @@ async function bridge(params, provider) {
                 throw new Error(`${name} step failed: ${errorDetails}`);
             }
             context = updateContext?.(step);
-            provider.actionDispatcher?.dispatch(name, {
+            const actionValues = {
                 protocol: 'cctp',
                 version: 'v2',
-                method: name,
-                values: step.data,
-            });
+                values: step,
+            };
+            // use a switch statement for type safety to separate the different step types
+            switch (name) {
+                case 'approve':
+                case 'burn':
+                case 'mint':
+                    provider.actionDispatcher?.dispatch(name, {
+                        ...actionValues,
+                        method: name,
+                    });
+                    break;
+                case 'fetchAttestation':
+                    provider.actionDispatcher?.dispatch(name, {
+                        ...actionValues,
+                        method: name,
+                        values: step,
+                    });
+                    break;
+            }
             result.steps.push(step);
         }
         catch (error) {
@@ -5207,7 +5227,6 @@ base58StringSchema.refine((value) => value.length >= 86 && value.length <= 88, '
 zod.z.object({
     prepare: zod.z.function(),
     waitForTransaction: zod.z.function(),
-    getChain: zod.z.function(),
     getAddress: zod.z.function(),
 });
 
@@ -5730,9 +5749,9 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      *
      * @param params - The bridge parameters containing source, destination, amount, and optional config.
      * @returns A promise resolving to the bridge result, including transaction details, step states, and explorer URLs.
-     * @throws {ValidationError} If the parameters are invalid
-     * @throws {BridgeError} If the bridge operation fails
-     * @throws {UnsupportedRouteError} If the route is not supported
+     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {BridgeError} When the bridge operation fails.
+     * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
      * ```typescript
@@ -5794,9 +5813,14 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      * chains, as well as any applicable protocol fees.
      *
      * @param params - The bridge parameters containing source, destination, amount, and optional config.
-     * @returns Promise resolving to detailed cost breakdown including gas estimates and protocol fees
-     * @throws {ValidationError} If the parameters are invalid
-     * @throws {UnsupportedRouteError} If the route is not supported
+     * @returns Promise resolving to detailed cost breakdown including:
+     *          - `gasFees`: Array of gas estimates for each step (Approve, Burn, Mint)
+     *            - Gas amounts in native token smallest units (wei for ETH, lamports for SOL, etc.)
+     *          - `fees`: Array of protocol and kit fees
+     *            - Provider fees in USDC decimal units (e.g., "0.1" USDC)
+     *            - Kit fees in USDC decimal units if configured
+     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
      * ```typescript
@@ -6063,6 +6087,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             message: attestation.message,
             attestation: attestation.attestation,
             eventNonce: attestation.eventNonce,
+            destinationAddress: destination.address,
         };
         // Single call with or without context
         if (resolvedContext) {
@@ -6176,28 +6201,29 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         return false;
     }
     /**
-     * This method determines the appropriate maximum fee for a cross-chain bridge operation
-     * based on the configured bridge speed and chain requirements.
+     * Determines the appropriate maximum fee for a cross-chain bridge operation.
      *
      * For FAST bridge operations, it calculates a dynamic fee based on the bridge amount
      * and fast bridge burn fee, or uses a provided maxFee if specified.
      *
      * For SLOW bridge operations, it returns 0 as there are no additional fees.
      *
-     * @param sourceChain - The source chain definition where the bridge originates
-     * @param destinationChain - The destination chain definition where tokens will be minted
-     * @param amount - The bridge amount in minor units (e.g., "1000000" for 1 USDC)
-     * @param config - Optional bridge configuration including speed and fee settings
-     * @returns The maximum fee to be used for the bridge operation
+     * @param params - The bridge parameters object containing:
+     *   - `source`: The source wallet context with chain definition and adapter
+     *   - `destination`: The destination wallet context with chain definition and adapter
+     *   - `amount`: The bridge amount in minor units (e.g., "1000000" for 1 USDC)
+     *   - `config`: Optional bridge configuration including transferSpeed and maxFee settings
+     * @returns The maximum fee to be used for the bridge operation in minor units
      *
      * @example
      * ```typescript
-     * const maxFee = await provider.getMaxFee(
-     *   sourceChain,
-     *   destinationChain,
-     *   '1000000', // 1 USDC
-     *   { transferSpeed: 'FAST' }
-     * )
+     * const maxFee = await provider.getMaxFee({
+     *   source: { adapter: sourceAdapter, chain: Chains.Ethereum, address: '0x...' },
+     *   destination: { adapter: destAdapter, chain: Chains.Base, address: '0x...' },
+     *   amount: '1000000', // 1 USDC
+     *   token: 'USDC',
+     *   config: { transferSpeed: TransferSpeed.FAST }
+     * })
      * console.log('Max fee:', maxFee)
      * ```
      */
@@ -6264,8 +6290,11 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         // Get the min finality threshold based on the transfer speed
         const minFinalityThreshold = CCTPv2MinFinalityThreshold[transferSpeed];
         // Calculate the max fee
-        const maxFee = await this.getMaxFee(params);
-        const mintRecipient = await getMintRecipientAccount(destination.chain.type, destination.address ?? (await destination.adapter.getAddress()), destination.chain.usdcAddress);
+        const [maxFee, mintRecipient] = await Promise.all([
+            this.getMaxFee(params),
+            getMintRecipientAccount(destination.chain.type, destination.address ??
+                (await destination.adapter.getAddress(destination.chain)), destination.chain.usdcAddress),
+        ]);
         const actionParams = {
             fromChain: source.chain,
             toChain: destination.chain,

package/index.d.ts

@@ -1167,6 +1167,14 @@ interface CCTPv2ActionMap {
          * Destination chain definition where tokens will be minted.
          */
         readonly toChain: ChainDefinitionWithCCTPv2;
+        /**
+         * Optional destination wallet address on the destination chain to receive minted USDC.
+         *
+         * When provided (e.g., for Solana), the mint instruction will derive the
+         * recipient's Associated Token Account (ATA) from this address instead of
+         * the adapter's default address.
+         */
+        readonly destinationAddress?: string;
     };
     /**
      * Initiate a cross-chain USDC transfer using a custom bridge contract with preapproval funnel.
@@ -1524,7 +1532,7 @@ interface USDCActionMap {
 /**
  * Central registry of all available action namespaces and their operations.
  *
- * Define the complete action map structure used throughout the bridging kit.
+ * Define the complete action map structure used throughout the bridge kit.
  * Each top-level key represents a namespace (e.g., 'token', 'usdc') containing
  * related operations. The structure supports arbitrary nesting depth through
  * the recursive utility types provided in this module.
@@ -1617,7 +1625,7 @@ type NestedValue<T, K extends string> = K extends `${infer First}.${infer Rest}`
  *
  * @remarks
  * This type serves as the canonical source for all valid action identifiers
- * in the bridging kit. It ensures compile-time validation of action keys
+ * in the bridge kit. It ensures compile-time validation of action keys
  * and enables type-safe action dispatching throughout the application.
  *
  * @see {@link ActionPayload} for extracting parameter types
@@ -1986,26 +1994,6 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * ```
      */
     capabilities?: TAdapterCapabilities;
-    /**
-     * Default chain for operations when none is explicitly provided.
-     *
-     * This allows adapters to have sensible defaults for chain operations,
-     * reducing the need for explicit chain specification in every call.
-     *
-     * @remarks
-     * This is optional for backward compatibility and because some adapter types
-     * (like developer-controlled adapters) may not have meaningful defaults.
-     *
-     * @example
-     * ```typescript
-     * // User-controlled adapter with default chain
-     * defaultChain = Ethereum
-     *
-     * // Developer-controlled adapter (no default)
-     * defaultChain = undefined
-     * ```
-     */
-    defaultChain?: ChainDefinition;
     /**
      * Registry of available actions for this adapter.
      *
@@ -2119,16 +2107,6 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * @returns A promise that resolves to the blockchain address as a string.
      */
     abstract getAddress(chain?: ChainDefinition): Promise<string>;
-    /**
-     * Retrieves the {@link ChainDefinition} object that describes the blockchain
-     * this adapter is configured to interact with.
-     *
-     * This includes information such as the chain ID, name, native currency, etc.,
-     * as defined by the `ChainDefinition` type.
-     *
-     * @returns A promise that resolves to the {@link ChainDefinition} for the current chain.
-     */
-    abstract getChain(): Promise<ChainDefinition>;
     /**
      * Switches the adapter to operate on the specified chain.
      *
@@ -2173,17 +2151,14 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * - **Browser wallet adapters**: Request chain switch via EIP-1193 or equivalent
      * - **Multi-entity adapters**: Validate chain support (operations are contextual)
      *
-     * @param chain - The target chain for operations. If not provided, uses the adapter's defaultChain.
+     * @param chain - The target chain for operations.
      * @returns A promise that resolves when the adapter is operating on the specified chain.
      * @throws When the target chain is not supported or chain switching fails.
      *
      * @remarks
-     * This method replaces the pattern of calling `getChain()` to check current chain and then
-     * manually switching. It provides a declarative "ensure this chain" interface for operations.
-     *
-     * **Backward Compatibility**: The default implementation provides basic validation but
-     * doesn't perform actual chain switching. Concrete adapter implementations should override
-     * this method to provide proper chain switching logic.
+     * This method always calls `switchToChain()` to ensure consistency across all adapter types.
+     * The underlying implementations handle idempotent switching efficiently (e.g., browser wallets
+     * gracefully handle switching to the current chain, private key adapters recreate lightweight clients).
      *
      * @example
      * ```typescript
@@ -2197,7 +2172,7 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * await circleWalletsAdapter.ensureChain(Ethereum)
      * ```
      */
-    ensureChain(chain?: ChainDefinition): Promise<void>;
+    ensureChain(targetChain: ChainDefinition): Promise<void>;
     /**
      * Validate that the target chain is supported by this adapter.
      *
@@ -2264,7 +2239,7 @@ interface ApiPollingConfig {
  *
  * @example
  * ```typescript
- * import { Actionable } from '@circle/bridging-kit/utils';
+ * import { Actionable } from '@circle-fin/bridge-kit/utils';
  *
  * // Define your action types
  * type TransferActions = {
@@ -2584,7 +2559,7 @@ interface EstimateResult {
     }[];
     /** Array of protocol and service fees for the transfer */
     fees: {
-        /** The type of fee - either from the bridging kit or the underlying provider */
+        /** The type of fee - either from the bridge kit or the underlying provider */
         type: 'kit' | 'provider';
         /** The token in which the fee is charged (currently only USDC) */
         token: 'USDC';
@@ -2647,10 +2622,9 @@ interface BridgeConfig {
 interface CustomFee {
     /**
      * The absolute fee to charge for the transfer.
-     * Provide the amount in the token's smallest unit (e.g., USDC uses 6 decimals)
-     * as a base-10 numeric string. This is not a percentage.
-     *
-     * For example: to charge 1 USDC, pass `'1000000'`.
+     * Provide the amount as a base-10 numeric string representing the integer amount of the token (not in smallest units).
+     * For example: to charge 1 USDC or 1 USDC, pass `'1'`.
+     * This is not a percentage.
      *
      * Note: passing `'0'` results in no fee being charged.
      */
@@ -3125,6 +3099,7 @@ type BridgeFetchAttestationStep = BridgeStep &
  | {
     state: 'pending';
     txHash?: string;
+    data?: undefined;
 }
 /**
  * The error state of the fetch attestation step.
@@ -3132,6 +3107,7 @@ type BridgeFetchAttestationStep = BridgeStep &
  | {
     state: 'error';
     error: unknown;
+    data?: undefined;
 });
 
 /**
@@ -3349,9 +3325,9 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      *
      * @param params - The bridge parameters containing source, destination, amount, and optional config.
      * @returns A promise resolving to the bridge result, including transaction details, step states, and explorer URLs.
-     * @throws {ValidationError} If the parameters are invalid
-     * @throws {BridgeError} If the bridge operation fails
-     * @throws {UnsupportedRouteError} If the route is not supported
+     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {BridgeError} When the bridge operation fails.
+     * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
      * ```typescript
@@ -3396,9 +3372,14 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * chains, as well as any applicable protocol fees.
      *
      * @param params - The bridge parameters containing source, destination, amount, and optional config.
-     * @returns Promise resolving to detailed cost breakdown including gas estimates and protocol fees
-     * @throws {ValidationError} If the parameters are invalid
-     * @throws {UnsupportedRouteError} If the route is not supported
+     * @returns Promise resolving to detailed cost breakdown including:
+     *          - `gasFees`: Array of gas estimates for each step (Approve, Burn, Mint)
+     *            - Gas amounts in native token smallest units (wei for ETH, lamports for SOL, etc.)
+     *          - `fees`: Array of protocol and kit fees
+     *            - Provider fees in USDC decimal units (e.g., "0.1" USDC)
+     *            - Kit fees in USDC decimal units if configured
+     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
      * ```typescript
@@ -3576,28 +3557,29 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      */
     supportsRoute(source: ChainDefinition, destination: ChainDefinition, token: 'USDC'): boolean;
     /**
-     * This method determines the appropriate maximum fee for a cross-chain bridge operation
-     * based on the configured bridge speed and chain requirements.
+     * Determines the appropriate maximum fee for a cross-chain bridge operation.
      *
      * For FAST bridge operations, it calculates a dynamic fee based on the bridge amount
      * and fast bridge burn fee, or uses a provided maxFee if specified.
      *
      * For SLOW bridge operations, it returns 0 as there are no additional fees.
      *
-     * @param sourceChain - The source chain definition where the bridge originates
-     * @param destinationChain - The destination chain definition where tokens will be minted
-     * @param amount - The bridge amount in minor units (e.g., "1000000" for 1 USDC)
-     * @param config - Optional bridge configuration including speed and fee settings
-     * @returns The maximum fee to be used for the bridge operation
+     * @param params - The bridge parameters object containing:
+     *   - `source`: The source wallet context with chain definition and adapter
+     *   - `destination`: The destination wallet context with chain definition and adapter
+     *   - `amount`: The bridge amount in minor units (e.g., "1000000" for 1 USDC)
+     *   - `config`: Optional bridge configuration including transferSpeed and maxFee settings
+     * @returns The maximum fee to be used for the bridge operation in minor units
      *
      * @example
      * ```typescript
-     * const maxFee = await provider.getMaxFee(
-     *   sourceChain,
-     *   destinationChain,
-     *   '1000000', // 1 USDC
-     *   { transferSpeed: 'FAST' }
-     * )
+     * const maxFee = await provider.getMaxFee({
+     *   source: { adapter: sourceAdapter, chain: Chains.Ethereum, address: '0x...' },
+     *   destination: { adapter: destAdapter, chain: Chains.Base, address: '0x...' },
+     *   amount: '1000000', // 1 USDC
+     *   token: 'USDC',
+     *   config: { transferSpeed: TransferSpeed.FAST }
+     * })
      * console.log('Max fee:', maxFee)
      * ```
      */

package/index.mjs

@@ -16,6 +16,17 @@
  * limitations under the License.
  */
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for @solana/spl-token and other Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 import { z } from 'zod';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
 import { getAddress } from '@ethersproject/address';
@@ -2146,7 +2157,7 @@ var Chains = /*#__PURE__*/Object.freeze({
  *
  * @example
  * ```typescript
- * import { isCCTPV2Supported } from '@circle-fin/bridging-kit'
+ * import { isCCTPV2Supported } from '@circle-fin/bridge-kit'
  *
  * const isSupported = isCCTPV2Supported(ethChainDefinition)
  * console.log(isSupported) // true
@@ -2238,6 +2249,11 @@ const baseChainDefinitionSchema = z.object({
     eurcAddress: z.string().nullable(),
     usdcAddress: z.string().nullable(),
     cctp: z.any().nullable(), // We'll accept any CCTP config structure
+    kitContracts: z
+        .object({
+        bridge: z.string().optional(),
+    })
+        .optional(),
 });
 /**
  * Zod schema for validating EVM chain definitions specifically.
@@ -2269,13 +2285,15 @@ const baseChainDefinitionSchema = z.object({
  * }
  * ```
  */
-const evmChainDefinitionSchema = baseChainDefinitionSchema.extend({
+const evmChainDefinitionSchema = baseChainDefinitionSchema
+    .extend({
     type: z.literal('evm'),
     chainId: z.number({
         required_error: 'EVM chains must have a chainId. Please provide a valid EVM chain ID.',
         invalid_type_error: 'EVM chain ID must be a number.',
     }),
-});
+})
+    .strict(); //// Reject any additional properties not defined in the schema
 /**
  * Zod schema for validating non-EVM chain definitions.
  * This schema extends the base schema with non-EVM specific properties.
@@ -2295,7 +2313,7 @@ const nonEvmChainDefinitionSchema = baseChainDefinitionSchema
         'polkadot',
     ]),
 })
-    .strict(); // Reject additional properties like chainId
+    .strict(); // Reject any additional properties not defined in the schema
 /**
  * Discriminated union schema for all chain definitions.
  * This schema validates different chain types based on their 'type' field.
@@ -2568,8 +2586,8 @@ class BridgingProvider {
  *
  * @example
  * ```typescript
- * setKitIdentifier('bridging-kit', '1.2.3')
- * getUserAgent() // "bridging-kit/1.2.3 (node/18.16.0)"
+ * setKitIdentifier('bridge-kit', '1.2.3')
+ * getUserAgent() // "bridge-kit/1.2.3 (node/18.16.0)"
  * ```
  *
  * @returns The Stablecoin Kits SDK user agent string.
@@ -2604,7 +2622,7 @@ function getRuntime() {
 /**
  * Get the user agent string for Stablecoin Kits SDK (universal, sync).
  *
- * @returns The user agent string, e.g., "bridging-kit/1.2.3 (node/18.16.0)"
+ * @returns The user agent string, e.g., "bridge-kit/1.2.3 (node/18.16.0)"
  */
 function getUserAgent() {
     if (cachedUserAgent !== undefined)
@@ -4182,67 +4200,48 @@ class KitError extends Error {
 }
 
 /**
- * Standardized error codes for INPUT type errors.
+ * Standardized error definitions for INPUT type errors.
+ *
+ * Each entry combines the numeric error code with its corresponding
+ * string name to ensure consistency when creating error instances.
  *
  * Error codes follow a hierarchical numbering scheme where the first digit
  * indicates the error category (1 = INPUT) and subsequent digits provide
  * specific error identification within that category.
  *
+ *
  * @example
  * ```typescript
- * import { InputErrorCode, InputErrorName } from '@core/errors'
+ * import { InputError } from '@core/errors'
  *
  * const error = new KitError({
- *   code: InputErrorCode.NETWORK_MISMATCH,
- *   name: InputErrorName.NETWORK_MISMATCH,
+ *   ...InputError.NETWORK_MISMATCH,
  *   recoverability: 'FATAL',
  *   message: 'Source and destination networks must be different'
  * })
+ *
+ * // Access code and name individually if needed
+ * console.log(InputError.NETWORK_MISMATCH.code)  // 1001
+ * console.log(InputError.NETWORK_MISMATCH.name)  // 'INPUT_NETWORK_MISMATCH'
  * ```
  */
-var InputErrorCode;
-(function (InputErrorCode) {
+const InputError = {
     /** Network type mismatch between chains (mainnet vs testnet) */
-    InputErrorCode[InputErrorCode["NETWORK_MISMATCH"] = 1001] = "NETWORK_MISMATCH";
-    /** Invalid amount format or value (negative, zero, or malformed) */
-    InputErrorCode[InputErrorCode["INVALID_AMOUNT"] = 1002] = "INVALID_AMOUNT";
+    NETWORK_MISMATCH: {
+        code: 1001,
+        name: 'INPUT_NETWORK_MISMATCH',
+    },
     /** Unsupported or invalid bridge route configuration */
-    InputErrorCode[InputErrorCode["UNSUPPORTED_ROUTE"] = 1003] = "UNSUPPORTED_ROUTE";
-    /** Invalid wallet or contract address format */
-    InputErrorCode[InputErrorCode["INVALID_ADDRESS"] = 1004] = "INVALID_ADDRESS";
-    /** Invalid or unsupported chain identifier */
-    InputErrorCode[InputErrorCode["INVALID_CHAIN"] = 1005] = "INVALID_CHAIN";
+    UNSUPPORTED_ROUTE: {
+        code: 1003,
+        name: 'INPUT_UNSUPPORTED_ROUTE',
+    },
     /** General validation failure for complex validation rules */
-    InputErrorCode[InputErrorCode["VALIDATION_FAILED"] = 1098] = "VALIDATION_FAILED";
-})(InputErrorCode || (InputErrorCode = {}));
-/**
- * Standardized error names for INPUT type errors.
- *
- * These names correspond 1:1 with InputErrorCode and should always
- * be used together to ensure consistency across error instances.
- *
- * @example
- * ```typescript
- * import { InputErrorCode, InputErrorName } from '@core/errors'
- *
- * // Use matching code and name enums
- * const error = new KitError({
- *   code: InputErrorCode.NETWORK_MISMATCH,
- *   name: InputErrorName.NETWORK_MISMATCH,
- *   recoverability: 'FATAL',
- *   message: 'Network mismatch detected'
- * })
- * ```
- */
-var InputErrorName;
-(function (InputErrorName) {
-    InputErrorName["NETWORK_MISMATCH"] = "INPUT_NETWORK_MISMATCH";
-    InputErrorName["INVALID_AMOUNT"] = "INPUT_INVALID_AMOUNT";
-    InputErrorName["UNSUPPORTED_ROUTE"] = "INPUT_UNSUPPORTED_ROUTE";
-    InputErrorName["INVALID_ADDRESS"] = "INPUT_INVALID_ADDRESS";
-    InputErrorName["INVALID_CHAIN"] = "INPUT_INVALID_CHAIN";
-    InputErrorName["VALIDATION_FAILED"] = "INPUT_VALIDATION_FAILED";
-})(InputErrorName || (InputErrorName = {}));
+    VALIDATION_FAILED: {
+        code: 1098,
+        name: 'INPUT_VALIDATION_FAILED',
+    },
+};
 
 /**
  * Creates error for network type mismatch between source and destination.
@@ -4269,8 +4268,7 @@ function createNetworkMismatchError(sourceChain, destChain) {
     const sourceNetworkType = sourceChain.isTestnet ? 'testnet' : 'mainnet';
     const destNetworkType = destChain.isTestnet ? 'testnet' : 'mainnet';
     const errorDetails = {
-        code: InputErrorCode.NETWORK_MISMATCH,
-        name: InputErrorName.NETWORK_MISMATCH,
+        ...InputError.NETWORK_MISMATCH,
         recoverability: 'FATAL',
         message: `Cannot bridge between ${sourceChain.name} (${sourceNetworkType}) and ${destChain.name} (${destNetworkType}). Source and destination networks must both be testnet or both be mainnet.`,
         cause: {
@@ -4299,8 +4297,7 @@ function createNetworkMismatchError(sourceChain, destChain) {
  */
 function createUnsupportedRouteError(source, destination) {
     const errorDetails = {
-        code: InputErrorCode.UNSUPPORTED_ROUTE,
-        name: InputErrorName.UNSUPPORTED_ROUTE,
+        ...InputError.UNSUPPORTED_ROUTE,
         recoverability: 'FATAL',
         message: `Route from ${source} to ${destination} is not supported.`,
         cause: {
@@ -4347,8 +4344,7 @@ function createValidationFailedError(field, value, reason) {
         valueString = String(value);
     }
     const errorDetails = {
-        code: InputErrorCode.VALIDATION_FAILED,
-        name: InputErrorName.VALIDATION_FAILED,
+        ...InputError.VALIDATION_FAILED,
         recoverability: 'FATAL',
         message: `Validation failed for '${field}': ${valueString} - ${reason}.`,
         cause: {
@@ -4512,15 +4508,21 @@ mintAddress) => {
         return rawAddress;
     }
     else {
-        const [{ getAssociatedTokenAddress }, { PublicKey }] = await Promise.all([
-            import('@solana/spl-token'),
-            import('@solana/web3.js'),
-        ]);
         // Solana: derive the associated token account
-        const owner = new PublicKey(rawAddress);
-        const mintPub = new PublicKey(mintAddress);
-        const ata = await getAssociatedTokenAddress(mintPub, owner);
-        return ata.toBase58();
+        // Use dynamic import to avoid loading Solana dependencies for EVM-only users
+        try {
+            const [{ PublicKey }, { getAssociatedTokenAddressSync }] = await Promise.all([
+                import('@solana/web3.js'),
+                import('@solana/spl-token'),
+            ]);
+            const owner = new PublicKey(rawAddress);
+            const mintPub = new PublicKey(mintAddress);
+            const ata = getAssociatedTokenAddressSync(mintPub, owner);
+            return ata.toBase58();
+        }
+        catch {
+            throw new Error('Failed to derive Solana token account. Please ensure @solana/web3.js and @solana/spl-token are installed: npm install @solana/web3.js @solana/spl-token');
+        }
     }
 };
 
@@ -4758,6 +4760,7 @@ async function bridgeFetchAttestation({ params, provider, }, txHash) {
             ...step,
             state: 'error',
             error: err,
+            data: undefined,
         };
     }
     return step;
@@ -4940,12 +4943,29 @@ async function bridge(params, provider) {
                 throw new Error(`${name} step failed: ${errorDetails}`);
             }
             context = updateContext?.(step);
-            provider.actionDispatcher?.dispatch(name, {
+            const actionValues = {
                 protocol: 'cctp',
                 version: 'v2',
-                method: name,
-                values: step.data,
-            });
+                values: step,
+            };
+            // use a switch statement for type safety to separate the different step types
+            switch (name) {
+                case 'approve':
+                case 'burn':
+                case 'mint':
+                    provider.actionDispatcher?.dispatch(name, {
+                        ...actionValues,
+                        method: name,
+                    });
+                    break;
+                case 'fetchAttestation':
+                    provider.actionDispatcher?.dispatch(name, {
+                        ...actionValues,
+                        method: name,
+                        values: step,
+                    });
+                    break;
+            }
             result.steps.push(step);
         }
         catch (error) {
@@ -5201,7 +5221,6 @@ base58StringSchema.refine((value) => value.length >= 86 && value.length <= 88, '
 z.object({
     prepare: z.function(),
     waitForTransaction: z.function(),
-    getChain: z.function(),
     getAddress: z.function(),
 });
 
@@ -5724,9 +5743,9 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      *
      * @param params - The bridge parameters containing source, destination, amount, and optional config.
      * @returns A promise resolving to the bridge result, including transaction details, step states, and explorer URLs.
-     * @throws {ValidationError} If the parameters are invalid
-     * @throws {BridgeError} If the bridge operation fails
-     * @throws {UnsupportedRouteError} If the route is not supported
+     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {BridgeError} When the bridge operation fails.
+     * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
      * ```typescript
@@ -5788,9 +5807,14 @@ class CCTPV2BridgingProvider extends BridgingProvider {
      * chains, as well as any applicable protocol fees.
      *
      * @param params - The bridge parameters containing source, destination, amount, and optional config.
-     * @returns Promise resolving to detailed cost breakdown including gas estimates and protocol fees
-     * @throws {ValidationError} If the parameters are invalid
-     * @throws {UnsupportedRouteError} If the route is not supported
+     * @returns Promise resolving to detailed cost breakdown including:
+     *          - `gasFees`: Array of gas estimates for each step (Approve, Burn, Mint)
+     *            - Gas amounts in native token smallest units (wei for ETH, lamports for SOL, etc.)
+     *          - `fees`: Array of protocol and kit fees
+     *            - Provider fees in USDC decimal units (e.g., "0.1" USDC)
+     *            - Kit fees in USDC decimal units if configured
+     * @throws {ValidationError} When the parameters are invalid.
+     * @throws {UnsupportedRouteError} When the route is not supported.
      *
      * @example
      * ```typescript
@@ -6057,6 +6081,7 @@ class CCTPV2BridgingProvider extends BridgingProvider {
             message: attestation.message,
             attestation: attestation.attestation,
             eventNonce: attestation.eventNonce,
+            destinationAddress: destination.address,
         };
         // Single call with or without context
         if (resolvedContext) {
@@ -6170,28 +6195,29 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         return false;
     }
     /**
-     * This method determines the appropriate maximum fee for a cross-chain bridge operation
-     * based on the configured bridge speed and chain requirements.
+     * Determines the appropriate maximum fee for a cross-chain bridge operation.
      *
      * For FAST bridge operations, it calculates a dynamic fee based on the bridge amount
      * and fast bridge burn fee, or uses a provided maxFee if specified.
      *
      * For SLOW bridge operations, it returns 0 as there are no additional fees.
      *
-     * @param sourceChain - The source chain definition where the bridge originates
-     * @param destinationChain - The destination chain definition where tokens will be minted
-     * @param amount - The bridge amount in minor units (e.g., "1000000" for 1 USDC)
-     * @param config - Optional bridge configuration including speed and fee settings
-     * @returns The maximum fee to be used for the bridge operation
+     * @param params - The bridge parameters object containing:
+     *   - `source`: The source wallet context with chain definition and adapter
+     *   - `destination`: The destination wallet context with chain definition and adapter
+     *   - `amount`: The bridge amount in minor units (e.g., "1000000" for 1 USDC)
+     *   - `config`: Optional bridge configuration including transferSpeed and maxFee settings
+     * @returns The maximum fee to be used for the bridge operation in minor units
      *
      * @example
      * ```typescript
-     * const maxFee = await provider.getMaxFee(
-     *   sourceChain,
-     *   destinationChain,
-     *   '1000000', // 1 USDC
-     *   { transferSpeed: 'FAST' }
-     * )
+     * const maxFee = await provider.getMaxFee({
+     *   source: { adapter: sourceAdapter, chain: Chains.Ethereum, address: '0x...' },
+     *   destination: { adapter: destAdapter, chain: Chains.Base, address: '0x...' },
+     *   amount: '1000000', // 1 USDC
+     *   token: 'USDC',
+     *   config: { transferSpeed: TransferSpeed.FAST }
+     * })
      * console.log('Max fee:', maxFee)
      * ```
      */
@@ -6258,8 +6284,11 @@ class CCTPV2BridgingProvider extends BridgingProvider {
         // Get the min finality threshold based on the transfer speed
         const minFinalityThreshold = CCTPv2MinFinalityThreshold[transferSpeed];
         // Calculate the max fee
-        const maxFee = await this.getMaxFee(params);
-        const mintRecipient = await getMintRecipientAccount(destination.chain.type, destination.address ?? (await destination.adapter.getAddress()), destination.chain.usdcAddress);
+        const [maxFee, mintRecipient] = await Promise.all([
+            this.getMaxFee(params),
+            getMintRecipientAccount(destination.chain.type, destination.address ??
+                (await destination.adapter.getAddress(destination.chain)), destination.chain.usdcAddress),
+        ]);
         const actionParams = {
             fromChain: source.chain,
             toChain: destination.chain,

package/package.json

@@ -1,18 +1,32 @@
 {
   "name": "@circle-fin/provider-cctp-v2",
-  "version": "0.0.2-alpha.7",
+  "version": "1.0.0",
   "main": "./index.cjs.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
-    "@solana/web3.js": "^1.90.0",
-    "@solana/spl-token": "0.4.13",
-    "abitype": "1.0.8",
+    "@coral-xyz/anchor": "^0.31.1",
+    "bs58": "6.0.0",
+    "buffer": "^6.0.3",
+    "abitype": "^1.1.0",
+    "@solana/web3.js": "^1.98.4",
+    "@solana/spl-token": "0.4.14",
     "zod": "3.25.67",
     "@ethersproject/address": "^5.8.0",
     "@ethersproject/bytes": "^5.8.0",
-    "@ethersproject/units": "^5.8.0",
-    "bs58": "6.0.0"
+    "@ethersproject/units": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@solana/spl-token": "^0.4.13",
+    "@solana/web3.js": "^1.98.2"
+  },
+  "peerDependenciesMeta": {
+    "@solana/spl-token": {
+      "optional": true
+    },
+    "@solana/web3.js": {
+      "optional": true
+    }
   },
   "exports": {
     "./package.json": "./package.json",