@circle-fin/provider-cctp-v2 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.6.1
+
+### Patch Changes
+
+- Add support for Solana as a forwarder destination
+
+## 1.6.0
+
+### Minor Changes
+
+- Add support for EIP-5792 batched transactions in the bridge flow
+
+### Patch Changes
+
+- Enable forwarder destination support for Codex, Plume, and XDC chains on both mainnet and testnet
+- Update HyperEVM explorer URLs to use the official Hyperliquid explorer
+
 ## 1.5.0
 
 ### Minor Changes

package/index.cjs

@@ -1066,7 +1066,7 @@ const Codex = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1109,7 +1109,7 @@ const CodexTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1371,7 +1371,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -1416,7 +1416,7 @@ const HyperEVMTestnet = defineChain({
     },
     chainId: 998,
     isTestnet: true,
-    explorerUrl: 'https://testnet.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid-testnet.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid-testnet.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
@@ -2062,7 +2062,7 @@ const Plume = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2107,7 +2107,7 @@ const PlumeTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2479,7 +2479,7 @@ const Solana = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2526,7 +2526,7 @@ const SolanaDevnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2885,7 +2885,7 @@ const XDC = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2929,7 +2929,7 @@ const XDCApothem = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -9509,7 +9509,184 @@ zod.z
 })
     .passthrough();
 
-var version = "1.5.0";
+/**
+ * Check whether the source adapter supports EIP-5792 atomic batching and
+ * the consumer has not explicitly opted out via `config.batchTransactions`.
+ *
+ * @param params - Bridge parameters (used for adapter and config access).
+ * @returns `true` when batched execution should be attempted.
+ *
+ * @example
+ * ```typescript
+ * const useBatched = await shouldUseBatchedExecution(params)
+ * if (useBatched) {
+ *   // take the batched approve + burn path
+ * }
+ * ```
+ */
+async function shouldUseBatchedExecution(params) {
+    if (params.config?.batchTransactions === false) {
+        return false;
+    }
+    const { chain } = params.source;
+    if (chain.type !== 'evm') {
+        return false;
+    }
+    const adapter = params.source
+        .adapter;
+    if (typeof adapter.supportsAtomicBatch !== 'function' ||
+        typeof adapter.batchExecute !== 'function') {
+        return false;
+    }
+    try {
+        return await adapter.supportsAtomicBatch(chain);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Execute the approve and burn steps as a single EIP-5792 batched call.
+ *
+ * Prepare both `PreparedChainRequest` objects upfront, extract their raw
+ * call data via `getCallData()`, submit both via `adapter.batchExecute()`,
+ * then map the individual receipts back to standard {@link BridgeStep}
+ * objects so downstream consumers (event callbacks, result tracking) are
+ * unaffected.
+ *
+ * @param params - The CCTP v2 bridge parameters.
+ * @param provider - The CCTP v2 bridging provider.
+ * @returns Approve and burn steps with a shared context containing the burn tx hash.
+ * @throws {@link KitError} when the source chain is not EVM.
+ * @throws {@link KitError} when calldata extraction (`getCallData`) is not supported
+ *   by the prepared requests.
+ * @remarks
+ * Errors that occur after the batch has been submitted to the wallet
+ * (e.g. polling timeout, insufficient receipts) are **not thrown** — they
+ * are captured as `state: 'error'` on the returned steps to prevent
+ * accidental double-spend on retry.
+ *
+ * @example
+ * ```typescript
+ * const { approveStep, burnStep, context } = await executeBatchedApproveAndBurn(
+ *   params,
+ *   provider,
+ * )
+ * result.steps.push(approveStep, burnStep)
+ * ```
+ */
+async function executeBatchedApproveAndBurn(params, provider) {
+    // Double-unknown cast: Adapter<TFrom> has no structural overlap with
+    // BatchCapableAdapter (a duck-typed interface for EIP-5792 methods).
+    // A direct cast fails because TS cannot prove the intersection; the
+    // runtime capability check below guards against unsupported adapters.
+    const adapter = params.source.adapter;
+    const sourceChain = params.source.chain;
+    if (sourceChain.type !== 'evm') {
+        throw new KitError({
+            ...InputError.INVALID_CHAIN,
+            recoverability: 'FATAL',
+            message: 'Batched execution is only supported on EVM chains.',
+        });
+    }
+    const chain = sourceChain;
+    // customFee.value is in base units (integer string) at this point.
+    const customFee = BigInt(params.config?.customFee?.value ?? '0');
+    const amountBigInt = BigInt(params.amount);
+    const approvalAmount = (amountBigInt + customFee).toString();
+    const [approveRequest, burnRequest] = await Promise.all([
+        provider.approve(params.source, approvalAmount),
+        provider.burn(params),
+    ]);
+    if (approveRequest.type !== 'evm' ||
+        burnRequest.type !== 'evm' ||
+        !approveRequest.getCallData ||
+        !burnRequest.getCallData) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ACTION,
+            recoverability: 'FATAL',
+            message: 'Batched execution requires EVM prepared requests with getCallData() support.',
+        });
+    }
+    const approveCallData = approveRequest.getCallData();
+    const burnCallData = burnRequest.getCallData();
+    // batchExecute may throw before submission (wallet declined) but never
+    // after — post-submission errors are returned as empty receipts.
+    const batchResult = await adapter.batchExecute([approveCallData, burnCallData], chain);
+    const approveReceipt = batchResult.receipts[0];
+    const burnReceipt = batchResult.receipts[1];
+    const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain);
+    const burnStep = await buildBatchedStep('burn', burnReceipt, batchResult.batchId, adapter, chain);
+    if (burnStep.state !== 'error' && !burnStep.txHash) {
+        burnStep.state = 'error';
+        burnStep.errorMessage =
+            'Batched burn step completed but no transaction hash was returned.';
+    }
+    const context = { burnTxHash: burnStep.txHash ?? '' };
+    return { approveStep, burnStep, context };
+}
+/**
+ * Build a {@link BridgeStep} from a single receipt within a batch.
+ *
+ * Map the raw receipt from `batchExecute` into a standard `BridgeStep`,
+ * waiting for on-chain confirmation via `adapter.waitForTransaction`.
+ * All errors are captured on the step (never thrown) so the caller
+ * can inspect each step independently.
+ *
+ * @param name - Human-readable step name (e.g. `'approve'`, `'burn'`).
+ * @param receipt - Per-call receipt from `batchExecute`, or `undefined`
+ *   when the wallet returned fewer receipts than submitted calls.
+ * @param batchId - Wallet-assigned batch identifier.
+ * @param adapter - The batch-capable adapter (used for confirmation).
+ * @param chain - The EVM chain the batch was executed on.
+ * @returns A fully-populated bridge step with state, tx hash and explorer URL.
+ *
+ * @internal
+ */
+async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
+    const step = {
+        name,
+        state: 'pending',
+        batched: true,
+        batchId,
+    };
+    if (!receipt) {
+        step.state = 'error';
+        step.errorMessage = `No receipt returned for ${name} in batch ${batchId}.`;
+        return step;
+    }
+    step.txHash = receipt.txHash;
+    if (receipt.txHash) {
+        step.explorerUrl = buildExplorerUrl(chain, receipt.txHash);
+    }
+    if (receipt.status !== 'success') {
+        step.state = 'error';
+        step.errorMessage = `${name} call failed within batch ${batchId}.`;
+        return step;
+    }
+    if (!receipt.txHash) {
+        step.state = 'error';
+        step.errorMessage = `${name} succeeded in batch but returned an empty transaction hash.`;
+        return step;
+    }
+    try {
+        const transaction = await adapter.waitForTransaction(receipt.txHash, { confirmations: 1 }, chain);
+        step.state = transaction.blockNumber === undefined ? 'error' : 'success';
+        step.data = transaction;
+        if (transaction.blockNumber === undefined) {
+            step.errorMessage = 'Transaction was not confirmed on-chain.';
+        }
+    }
+    catch (err) {
+        step.state = 'error';
+        step.error = err;
+        step.errorMessage =
+            err instanceof Error ? err.message : 'Unknown error during confirmation.';
+    }
+    return step;
+}
+
+var version = "1.6.1";
 var pkg = {
 	version: version};
 
@@ -9538,6 +9715,67 @@ function resolveBridgeInvocation(invocationMeta) {
     };
     return extendInvocationContext(resolveInvocationContext(invocationMeta, defaults), BRIDGE_CALLER);
 }
+/**
+ * Execute the batched approve + burn path via EIP-5792.
+ *
+ * Mutate `result` with step data and error state as needed. Return the
+ * batch context on success, or `undefined` when the batch failed (in
+ * which case `result.state` is set to `'error'`).
+ *
+ * @internal
+ * @param params - Bridge parameters (read-only).
+ * @param provider - The CCTP v2 bridging provider (read-only).
+ * @param result - Bridge result object — **mutated in place** with step
+ *   data and, on failure, `state: 'error'` plus an `error` payload.
+ * @param invocation - Invocation context for telemetry (read-only).
+ * @returns The step context on success, or `undefined` when the batch failed.
+ */
+async function executeBatchedPath(params, provider, result, invocation) {
+    // IMPORTANT: once executeBatchedApproveAndBurn is called, we NEVER
+    // fall back to sequential. The wallet may have already signed &
+    // submitted the batch; retrying as individual txs would double-spend.
+    try {
+        const { approveStep, burnStep, context: batchContext, } = await executeBatchedApproveAndBurn(params, provider);
+        for (const step of [approveStep, burnStep]) {
+            const stepName = step.name;
+            if (step.state === 'error') {
+                ensureStepErrorMessage(step.name, step);
+                result.steps.push(step);
+                result.state = 'error';
+                dispatchStepEvent(stepName, step, provider, invocation);
+                return undefined;
+            }
+            dispatchStepEvent(stepName, step, provider, invocation);
+            result.steps.push(step);
+        }
+        return batchContext;
+    }
+    catch (error_) {
+        // Only handles pre-submission failures (prepare rejected, wallet
+        // declined, etc.). batchExecute never throws after sendCalls succeeds.
+        result.state = 'error';
+        result.steps.push({
+            name: 'batch',
+            state: 'error',
+            batched: true,
+            error: error_,
+            errorMessage: error_ instanceof Error
+                ? error_.message
+                : 'Batched approve + burn failed.',
+        });
+        return undefined;
+    }
+}
+/**
+ * Ensure `step.errorMessage` is populated when an error object exists.
+ *
+ * @internal
+ */
+function ensureStepErrorMessage(name, step) {
+    if (!step.errorMessage && step.error) {
+        step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
+    }
+}
 /**
  * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
  *
@@ -9571,9 +9809,7 @@ function resolveBridgeInvocation(invocationMeta) {
  * ```
  */
 async function bridge(params, provider) {
-    // Check if forwarder is enabled (on destination)
     const useForwarder = params.destination.useForwarder === true;
-    // Resolve invocation metadata to full context for event dispatching
     const invocation = resolveBridgeInvocation(params.invocationMeta);
     const result = {
         state: 'pending',
@@ -9586,11 +9822,9 @@ async function bridge(params, provider) {
         destination: {
             address: params.destination.address,
             chain: params.destination.chain,
-            // Preserve recipientAddress
             ...(params.destination.recipientAddress && {
                 recipientAddress: params.destination.recipientAddress,
             }),
-            // Preserve useForwarder
             ...(useForwarder && {
                 useForwarder: true,
             }),
@@ -9599,29 +9833,38 @@ async function bridge(params, provider) {
         config: params.config,
         provider: provider.name,
     };
-    // Context shared between steps
     let context = undefined;
-    // Create step executors based on useForwarder config
+    let useBatched = false;
+    try {
+        useBatched = await shouldUseBatchedExecution(params);
+    }
+    catch {
+        // Silently fall back to sequential
+    }
     const executors = createStepExecutors(useForwarder);
-    // Execute each step in sequence
-    for (const { name, executor, updateContext } of executors) {
+    if (useBatched) {
+        const batchContext = await executeBatchedPath(params, provider, result, invocation);
+        if (result.state === 'error') {
+            return result;
+        }
+        context = batchContext;
+    }
+    const stepsToRun = useBatched
+        ? executors.filter(({ name }) => name !== 'approve' && name !== 'burn')
+        : executors;
+    for (const { name, executor, updateContext } of stepsToRun) {
         try {
             const step = await executor(params, provider, context);
             if (step.state === 'error') {
-                // Ensure errorMessage is set with proper formatting if not already present
-                if (!step.errorMessage && step.error) {
-                    step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
-                }
+                ensureStepErrorMessage(name, step);
                 result.steps.push(step);
                 result.state = 'error';
-                // Dispatch event even for error steps
                 dispatchStepEvent(name, step, provider, invocation);
                 return result;
             }
-            // Merge new context with existing context to preserve data from previous steps
             const newContext = updateContext?.(step);
             if (newContext) {
-                context = { ...(context ?? {}), ...newContext };
+                context = { ...context, ...newContext };
             }
             dispatchStepEvent(name, step, provider, invocation);
             result.steps.push(step);

package/index.d.ts

@@ -665,6 +665,32 @@ interface EvmExecuteOverrides extends EvmEstimateOverrides {
      */
     nonce?: number;
 }
+/**
+ * Raw EVM call data tuple for a single contract interaction.
+ *
+ * Represents the minimal data needed to submit an EVM transaction:
+ * the target contract address, the ABI-encoded calldata, and an
+ * optional native token value. Used by EIP-5792 batched execution
+ * to compose multiple calls into a single `wallet_sendCalls` request.
+ *
+ * @interface EvmCallData
+ *
+ * @example
+ * ```typescript
+ * const callData: EvmCallData = {
+ *   to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   data: '0x095ea7b3000000000000000000000000...',
+ * }
+ * ```
+ */
+interface EvmCallData {
+    /** The target contract address. */
+    to: `0x${string}`;
+    /** The ABI-encoded function calldata. */
+    data: `0x${string}`;
+    /** Optional native token value to send with the call. */
+    value?: bigint | undefined;
+}
 /**
  * Prepared contract execution for EVM chains.
  *
@@ -693,6 +719,28 @@ interface EvmPreparedChainRequest {
      * @throws If the execution fails
      */
     execute(overrides?: EvmExecuteOverrides): Promise<string>;
+    /**
+     * Return the raw call tuple without executing or estimating.
+     *
+     * Expose the `{ to, data, value }` triple that would be sent on-chain so
+     * callers can feed it into EIP-5792 `wallet_sendCalls` or other batching
+     * mechanisms. This method is optional -- adapters that do not support
+     * calldata extraction (e.g. Ethers v6) may omit it.
+     *
+     * @returns The raw EVM call data for this prepared request.
+     * @throws Never — synchronous accessor with no failure path.
+     * @since 2.0.0
+     *
+     * @example
+     * ```typescript
+     * const prepared = await adapter.prepare(params, ctx)
+     * if (prepared.getCallData) {
+     *   const { to, data, value } = prepared.getCallData()
+     *   console.log('Target:', to, 'Data:', data)
+     * }
+     * ```
+     */
+    getCallData?(): EvmCallData;
 }
 /**
  * Union type for all supported prepared contract executions.
@@ -4417,6 +4465,21 @@ interface BridgeStep {
      * - `undefined`: Not applicable (non-mint steps)
      */
     forwarded?: boolean;
+    /**
+     * Whether this step was executed as part of an EIP-5792 batched
+     * `wallet_sendCalls` request.
+     *
+     * - `true`: The step was included in a batched call bundle
+     * - `undefined`: The step was executed individually (sequential flow)
+     */
+    batched?: boolean | undefined;
+    /**
+     * The wallet-assigned batch identifier from `wallet_sendCalls`.
+     *
+     * Present only when {@link batched} is `true`. Can be used with
+     * `wallet_getCallsStatus` to query the status of the entire bundle.
+     */
+    batchId?: string | undefined;
     /** Optional human-readable error message */
     errorMessage?: string;
     /** Optional raw error object (can be Viem/Ethers/Chain error) */
@@ -4561,6 +4624,24 @@ interface BridgeConfig {
      * @defaultValue TransferSpeed.FAST
      */
     transferSpeed?: TransferSpeed | `${TransferSpeed}` | undefined;
+    /**
+     * Enable or disable EIP-5792 batched transaction execution.
+     *
+     * When `true` (or `undefined` / omitted), the bridge will attempt to batch
+     * the approve and burn calls into a single `wallet_sendCalls` request if
+     * the connected wallet supports it. Set to `false` to explicitly opt out
+     * and always use the sequential approve -> burn flow.
+     *
+     * @defaultValue `undefined` (batching attempted when the wallet supports it)
+     *
+     * @example
+     * ```typescript
+     * const config: BridgeConfig = {
+     *   batchTransactions: false, // force sequential flow
+     * }
+     * ```
+     */
+    batchTransactions?: boolean | undefined;
     /**
      * The maximum fee to pay for the burn operation.
      *

package/index.mjs

@@ -1059,7 +1059,7 @@ const Codex = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1102,7 +1102,7 @@ const CodexTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -1364,7 +1364,7 @@ const HyperEVM = defineChain({
     },
     chainId: 999,
     isTestnet: false,
-    explorerUrl: 'https://hyperevmscan.io/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0xb88339CB7199b77E23DB6E890353E22632Ba630f',
@@ -1409,7 +1409,7 @@ const HyperEVMTestnet = defineChain({
     },
     chainId: 998,
     isTestnet: true,
-    explorerUrl: 'https://testnet.hyperliquid.xyz/explorer/tx/{hash}',
+    explorerUrl: 'https://app.hyperliquid-testnet.xyz/explorer/tx/{hash}',
     rpcEndpoints: ['https://rpc.hyperliquid-testnet.xyz/evm'],
     eurcAddress: null,
     usdcAddress: '0x2B3370eE501B4a559b57D449569354196457D8Ab',
@@ -2055,7 +2055,7 @@ const Plume = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2100,7 +2100,7 @@ const PlumeTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2472,7 +2472,7 @@ const Solana = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2519,7 +2519,7 @@ const SolanaDevnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2878,7 +2878,7 @@ const XDC = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -2922,7 +2922,7 @@ const XDCApothem = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -9502,7 +9502,184 @@ z
 })
     .passthrough();
 
-var version = "1.5.0";
+/**
+ * Check whether the source adapter supports EIP-5792 atomic batching and
+ * the consumer has not explicitly opted out via `config.batchTransactions`.
+ *
+ * @param params - Bridge parameters (used for adapter and config access).
+ * @returns `true` when batched execution should be attempted.
+ *
+ * @example
+ * ```typescript
+ * const useBatched = await shouldUseBatchedExecution(params)
+ * if (useBatched) {
+ *   // take the batched approve + burn path
+ * }
+ * ```
+ */
+async function shouldUseBatchedExecution(params) {
+    if (params.config?.batchTransactions === false) {
+        return false;
+    }
+    const { chain } = params.source;
+    if (chain.type !== 'evm') {
+        return false;
+    }
+    const adapter = params.source
+        .adapter;
+    if (typeof adapter.supportsAtomicBatch !== 'function' ||
+        typeof adapter.batchExecute !== 'function') {
+        return false;
+    }
+    try {
+        return await adapter.supportsAtomicBatch(chain);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Execute the approve and burn steps as a single EIP-5792 batched call.
+ *
+ * Prepare both `PreparedChainRequest` objects upfront, extract their raw
+ * call data via `getCallData()`, submit both via `adapter.batchExecute()`,
+ * then map the individual receipts back to standard {@link BridgeStep}
+ * objects so downstream consumers (event callbacks, result tracking) are
+ * unaffected.
+ *
+ * @param params - The CCTP v2 bridge parameters.
+ * @param provider - The CCTP v2 bridging provider.
+ * @returns Approve and burn steps with a shared context containing the burn tx hash.
+ * @throws {@link KitError} when the source chain is not EVM.
+ * @throws {@link KitError} when calldata extraction (`getCallData`) is not supported
+ *   by the prepared requests.
+ * @remarks
+ * Errors that occur after the batch has been submitted to the wallet
+ * (e.g. polling timeout, insufficient receipts) are **not thrown** — they
+ * are captured as `state: 'error'` on the returned steps to prevent
+ * accidental double-spend on retry.
+ *
+ * @example
+ * ```typescript
+ * const { approveStep, burnStep, context } = await executeBatchedApproveAndBurn(
+ *   params,
+ *   provider,
+ * )
+ * result.steps.push(approveStep, burnStep)
+ * ```
+ */
+async function executeBatchedApproveAndBurn(params, provider) {
+    // Double-unknown cast: Adapter<TFrom> has no structural overlap with
+    // BatchCapableAdapter (a duck-typed interface for EIP-5792 methods).
+    // A direct cast fails because TS cannot prove the intersection; the
+    // runtime capability check below guards against unsupported adapters.
+    const adapter = params.source.adapter;
+    const sourceChain = params.source.chain;
+    if (sourceChain.type !== 'evm') {
+        throw new KitError({
+            ...InputError.INVALID_CHAIN,
+            recoverability: 'FATAL',
+            message: 'Batched execution is only supported on EVM chains.',
+        });
+    }
+    const chain = sourceChain;
+    // customFee.value is in base units (integer string) at this point.
+    const customFee = BigInt(params.config?.customFee?.value ?? '0');
+    const amountBigInt = BigInt(params.amount);
+    const approvalAmount = (amountBigInt + customFee).toString();
+    const [approveRequest, burnRequest] = await Promise.all([
+        provider.approve(params.source, approvalAmount),
+        provider.burn(params),
+    ]);
+    if (approveRequest.type !== 'evm' ||
+        burnRequest.type !== 'evm' ||
+        !approveRequest.getCallData ||
+        !burnRequest.getCallData) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ACTION,
+            recoverability: 'FATAL',
+            message: 'Batched execution requires EVM prepared requests with getCallData() support.',
+        });
+    }
+    const approveCallData = approveRequest.getCallData();
+    const burnCallData = burnRequest.getCallData();
+    // batchExecute may throw before submission (wallet declined) but never
+    // after — post-submission errors are returned as empty receipts.
+    const batchResult = await adapter.batchExecute([approveCallData, burnCallData], chain);
+    const approveReceipt = batchResult.receipts[0];
+    const burnReceipt = batchResult.receipts[1];
+    const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain);
+    const burnStep = await buildBatchedStep('burn', burnReceipt, batchResult.batchId, adapter, chain);
+    if (burnStep.state !== 'error' && !burnStep.txHash) {
+        burnStep.state = 'error';
+        burnStep.errorMessage =
+            'Batched burn step completed but no transaction hash was returned.';
+    }
+    const context = { burnTxHash: burnStep.txHash ?? '' };
+    return { approveStep, burnStep, context };
+}
+/**
+ * Build a {@link BridgeStep} from a single receipt within a batch.
+ *
+ * Map the raw receipt from `batchExecute` into a standard `BridgeStep`,
+ * waiting for on-chain confirmation via `adapter.waitForTransaction`.
+ * All errors are captured on the step (never thrown) so the caller
+ * can inspect each step independently.
+ *
+ * @param name - Human-readable step name (e.g. `'approve'`, `'burn'`).
+ * @param receipt - Per-call receipt from `batchExecute`, or `undefined`
+ *   when the wallet returned fewer receipts than submitted calls.
+ * @param batchId - Wallet-assigned batch identifier.
+ * @param adapter - The batch-capable adapter (used for confirmation).
+ * @param chain - The EVM chain the batch was executed on.
+ * @returns A fully-populated bridge step with state, tx hash and explorer URL.
+ *
+ * @internal
+ */
+async function buildBatchedStep(name, receipt, batchId, adapter, chain) {
+    const step = {
+        name,
+        state: 'pending',
+        batched: true,
+        batchId,
+    };
+    if (!receipt) {
+        step.state = 'error';
+        step.errorMessage = `No receipt returned for ${name} in batch ${batchId}.`;
+        return step;
+    }
+    step.txHash = receipt.txHash;
+    if (receipt.txHash) {
+        step.explorerUrl = buildExplorerUrl(chain, receipt.txHash);
+    }
+    if (receipt.status !== 'success') {
+        step.state = 'error';
+        step.errorMessage = `${name} call failed within batch ${batchId}.`;
+        return step;
+    }
+    if (!receipt.txHash) {
+        step.state = 'error';
+        step.errorMessage = `${name} succeeded in batch but returned an empty transaction hash.`;
+        return step;
+    }
+    try {
+        const transaction = await adapter.waitForTransaction(receipt.txHash, { confirmations: 1 }, chain);
+        step.state = transaction.blockNumber === undefined ? 'error' : 'success';
+        step.data = transaction;
+        if (transaction.blockNumber === undefined) {
+            step.errorMessage = 'Transaction was not confirmed on-chain.';
+        }
+    }
+    catch (err) {
+        step.state = 'error';
+        step.error = err;
+        step.errorMessage =
+            err instanceof Error ? err.message : 'Unknown error during confirmation.';
+    }
+    return step;
+}
+
+var version = "1.6.1";
 var pkg = {
 	version: version};
 
@@ -9531,6 +9708,67 @@ function resolveBridgeInvocation(invocationMeta) {
     };
     return extendInvocationContext(resolveInvocationContext(invocationMeta, defaults), BRIDGE_CALLER);
 }
+/**
+ * Execute the batched approve + burn path via EIP-5792.
+ *
+ * Mutate `result` with step data and error state as needed. Return the
+ * batch context on success, or `undefined` when the batch failed (in
+ * which case `result.state` is set to `'error'`).
+ *
+ * @internal
+ * @param params - Bridge parameters (read-only).
+ * @param provider - The CCTP v2 bridging provider (read-only).
+ * @param result - Bridge result object — **mutated in place** with step
+ *   data and, on failure, `state: 'error'` plus an `error` payload.
+ * @param invocation - Invocation context for telemetry (read-only).
+ * @returns The step context on success, or `undefined` when the batch failed.
+ */
+async function executeBatchedPath(params, provider, result, invocation) {
+    // IMPORTANT: once executeBatchedApproveAndBurn is called, we NEVER
+    // fall back to sequential. The wallet may have already signed &
+    // submitted the batch; retrying as individual txs would double-spend.
+    try {
+        const { approveStep, burnStep, context: batchContext, } = await executeBatchedApproveAndBurn(params, provider);
+        for (const step of [approveStep, burnStep]) {
+            const stepName = step.name;
+            if (step.state === 'error') {
+                ensureStepErrorMessage(step.name, step);
+                result.steps.push(step);
+                result.state = 'error';
+                dispatchStepEvent(stepName, step, provider, invocation);
+                return undefined;
+            }
+            dispatchStepEvent(stepName, step, provider, invocation);
+            result.steps.push(step);
+        }
+        return batchContext;
+    }
+    catch (error_) {
+        // Only handles pre-submission failures (prepare rejected, wallet
+        // declined, etc.). batchExecute never throws after sendCalls succeeds.
+        result.state = 'error';
+        result.steps.push({
+            name: 'batch',
+            state: 'error',
+            batched: true,
+            error: error_,
+            errorMessage: error_ instanceof Error
+                ? error_.message
+                : 'Batched approve + burn failed.',
+        });
+        return undefined;
+    }
+}
+/**
+ * Ensure `step.errorMessage` is populated when an error object exists.
+ *
+ * @internal
+ */
+function ensureStepErrorMessage(name, step) {
+    if (!step.errorMessage && step.error) {
+        step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
+    }
+}
 /**
  * Execute a cross-chain USDC bridge using the CCTP v2 protocol.
  *
@@ -9564,9 +9802,7 @@ function resolveBridgeInvocation(invocationMeta) {
  * ```
  */
 async function bridge(params, provider) {
-    // Check if forwarder is enabled (on destination)
     const useForwarder = params.destination.useForwarder === true;
-    // Resolve invocation metadata to full context for event dispatching
     const invocation = resolveBridgeInvocation(params.invocationMeta);
     const result = {
         state: 'pending',
@@ -9579,11 +9815,9 @@ async function bridge(params, provider) {
         destination: {
             address: params.destination.address,
             chain: params.destination.chain,
-            // Preserve recipientAddress
             ...(params.destination.recipientAddress && {
                 recipientAddress: params.destination.recipientAddress,
             }),
-            // Preserve useForwarder
             ...(useForwarder && {
                 useForwarder: true,
             }),
@@ -9592,29 +9826,38 @@ async function bridge(params, provider) {
         config: params.config,
         provider: provider.name,
     };
-    // Context shared between steps
     let context = undefined;
-    // Create step executors based on useForwarder config
+    let useBatched = false;
+    try {
+        useBatched = await shouldUseBatchedExecution(params);
+    }
+    catch {
+        // Silently fall back to sequential
+    }
     const executors = createStepExecutors(useForwarder);
-    // Execute each step in sequence
-    for (const { name, executor, updateContext } of executors) {
+    if (useBatched) {
+        const batchContext = await executeBatchedPath(params, provider, result, invocation);
+        if (result.state === 'error') {
+            return result;
+        }
+        context = batchContext;
+    }
+    const stepsToRun = useBatched
+        ? executors.filter(({ name }) => name !== 'approve' && name !== 'burn')
+        : executors;
+    for (const { name, executor, updateContext } of stepsToRun) {
         try {
             const step = await executor(params, provider, context);
             if (step.state === 'error') {
-                // Ensure errorMessage is set with proper formatting if not already present
-                if (!step.errorMessage && step.error) {
-                    step.errorMessage = `${name} step failed: ${getErrorMessage(step.error)}`;
-                }
+                ensureStepErrorMessage(name, step);
                 result.steps.push(step);
                 result.state = 'error';
-                // Dispatch event even for error steps
                 dispatchStepEvent(name, step, provider, invocation);
                 return result;
             }
-            // Merge new context with existing context to preserve data from previous steps
             const newContext = updateContext?.(step);
             if (newContext) {
-                context = { ...(context ?? {}), ...newContext };
+                context = { ...context, ...newContext };
             }
             dispatchStepEvent(name, step, provider, invocation);
             result.steps.push(step);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/provider-cctp-v2",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Circle's official Cross-Chain Transfer Protocol v2 provider for native USDC bridging",
   "keywords": [
     "circle",