@circle-fin/app-kit 1.1.0 → 1.2.0

package/index.mjs

@@ -4224,7 +4224,7 @@ const Codex = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -4267,7 +4267,7 @@ const CodexTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -4529,7 +4529,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',
@@ -4574,7 +4574,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',
@@ -5220,7 +5220,7 @@ const Plume = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -5265,7 +5265,7 @@ const PlumeTestnet = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -6043,7 +6043,7 @@ const XDC = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -6087,7 +6087,7 @@ const XDCApothem = defineChain({
         },
         forwarderSupported: {
             source: true,
-            destination: false,
+            destination: true,
         },
     },
     kitContracts: {
@@ -9200,7 +9200,7 @@ function buildForwardingHookData() {
 }
 
 var name$1 = "@circle-fin/bridge-kit";
-var version$2 = "1.7.0";
+var version$2 = "1.8.0";
 var pkg$2 = {
 	name: name$1,
 	version: version$2};
@@ -13290,7 +13290,184 @@ function dispatchStepEvent(name, step, provider, invocation) {
     }
 }
 
-var version$1 = "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 = "1.6.0";
 var pkg$1 = {
 	version: version$1};
 
@@ -13319,6 +13496,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.
  *
@@ -13352,9 +13590,7 @@ function resolveBridgeInvocation(invocationMeta) {
  * ```
  */
 async function bridge$1(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',
@@ -13367,11 +13603,9 @@ async function bridge$1(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,
             }),
@@ -13380,29 +13614,38 @@ async function bridge$1(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);
@@ -16034,7 +16277,7 @@ const createBridgeKit = (context) => {
 };
 
 var name = "@circle-fin/swap-kit";
-var version = "1.0.1";
+var version = "1.0.2";
 var pkg = {
 	name: name,
 	version: version};
@@ -25019,8 +25262,8 @@ const adapterContextSchema = z.object({
  * Schema for validating send parameters.
  * Ensure required fields are present and properly typed. Parameters must include:
  * - A valid `amount` (non-empty numeric string \> 0; supports "," or "." decimal separators and thousands separators).
- * - A valid `from` context (an adapter or full adapter context).
- * - A valid `to` context (an adapter or a destination chain identifier string).
+ * - A valid `from` context (an adapter context with `adapter` and `chain`).
+ * - A valid `to` destination (an adapter instance or a wallet address string).
  * - An optional `token` selection: 'USDC' (default), 'USDT', 'NATIVE', or a custom token address string.
  *
  * @returns Zod schema validating a send parameters object.
@@ -25033,7 +25276,7 @@ const adapterContextSchema = z.object({
  * const params = {
  *   amount: '100.50',
  *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
- *   to: 'Avalanche', // or { adapter: destAdapter, chain: 'Avalanche' }
+ *   to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // or destAdapter
  *   token: 'USDC',
  * }
  *
@@ -25092,7 +25335,7 @@ const sendParamsSchema = z.object({
  * The validation includes:
  * - Basic parameter structure and types.
  * - Amount validation (non-empty decimal string strictly greater than 0).
- * - Recipient validation (either an address string or an adapter+chain object).
+ * - Recipient validation (either an address string or an adapter instance).
  * - Adapter shape validation (required methods present).
  * - Optional config validation (when provided).
  *
@@ -25103,7 +25346,7 @@ const sendParamsSchema = z.object({
  * ```typescript
  * // Narrow unknown input to SendParams
  * const input: unknown = {
- *   from: sourceAdapter,
+ *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
  *   to: '0x742d35Cc6634C0532925a3b8D1a7aDBa359cfA7',
  *   amount: '1'
  * }
@@ -25122,7 +25365,7 @@ const tokens = createTokenRegistry();
  * Prepare a chain request to send USDC, USDT, native gas tokens, or custom ERC-20/SPL tokens.
  *
  * Validate inputs, obtain the sender address from the `from` adapter, resolve the recipient
- * from `to` (explicit address string or adapter context), and normalize the human‑readable
+ * from `to` (explicit address string or adapter), and normalize the human‑readable
  * `amount` into token units.
  *
  * For known token aliases, uses dedicated transfer actions
@@ -25233,7 +25476,7 @@ const prepareSend = async (params) => {
  * For custom token addresses, uses the generic token.transfer action with dynamically
  * fetched decimals.
  *
- * @param params - The send parameters: source context, destination (address or adapter context),
+ * @param params - The send parameters: source context, destination (address or adapter),
  * human-readable `amount`, and optional `token` ('USDC' | 'USDT' | 'NATIVE' or custom address, defaults to 'USDC').
  * @returns A BridgeStep object with transaction details including hash, status, and explorer URL.
  * @throws KitError INPUT_VALIDATION_FAILED if parameters are invalid.
@@ -25295,17 +25538,17 @@ const send = async (params) => {
  * Estimate the network fees to send USDC, USDT, or a supported native token.
  *
  * Prepare the send operation (including validating inputs and resolving the recipient when
- * provided as an adapter context) and return an {@link EstimatedGas} object. This function does
+ * provided as an adapter) and return an {@link EstimatedGas} object. This function does
  * not submit any transaction.
  *
  * @remarks
  * - Selects the transfer handler based on `token` ('USDC' by default, 'USDT', or 'NATIVE').
- * - When `to` is an adapter context, the recipient address is derived from the adapter.
+ * - When `to` is an {@link Adapter}, the recipient address is derived from the adapter.
  * - Rejects transfers where the resolved `to` equals the source `from` address.
  * - Interprets `amount` as a human-readable decimal string (USDC and USDT scaled to 6 decimals,
  *   native EVM value typically scaled to 18 decimals).
  *
- * @param params - The send parameters: source context, destination (address or adapter context),
+ * @param params - The send parameters: source context, destination (address or adapter),
  * human-readable `amount`, and optional `token` ('USDC' | 'USDT' | 'NATIVE', defaults to 'USDC').
  * @returns The estimated gas information including `gas`, `gasPrice`, and total `fee`.
  * @throws Error If parameters are invalid.
@@ -25707,10 +25950,10 @@ class AppKit {
      *
      * @example
      * ```typescript
-     * // Send USDC to another adapter
+     * // Send USDC to a recipient adapter (same chain)
      * const result = await kit.send({
-     *   from: sourceAdapter,
-     *   to: { adapter: destAdapter, chain: 'Polygon' },
+     *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+     *   to: recipientAdapter,
      *   amount: '100.50',
      *   token: 'USDC'
      * })
@@ -25721,7 +25964,7 @@ class AppKit {
      * ```typescript
      * // Send a custom token to an explicit address
      * const result = await kit.send({
-     *   from: sourceAdapter,
+     *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
      *   to: '0x742d35Cc4634C0532925a3b8D1d7',
      *   amount: '100.50',
      *   token: '0x6B175474E89094C44Da98b954EedeAC495271d0F' // DAI on Ethereum
@@ -25733,8 +25976,8 @@ class AppKit {
      * ```typescript
      * // Send USDT to an explicit address
      * const result = await kit.send({
-     *   from: sourceAdapter,
-     *   to: { address: '0x742d35Cc4634C0532925a3b8D1d7', chain: 'Polygon' },
+     *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+     *   to: '0x742d35Cc4634C0532925a3b8D1d7',
      *   amount: '50.25',
      *   token: 'USDT'
      * })
@@ -25760,8 +26003,8 @@ class AppKit {
      * @example
      * ```typescript
      * const estimate = await kit.estimateSend({
-     *   from: sourceAdapter,
-     *   to: { adapter: destAdapter, chain: 'Polygon' },
+     *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+     *   to: recipientAdapter,
      *   amount: '100.50',
      *   token: 'USDC'
      * })
@@ -25772,8 +26015,8 @@ class AppKit {
      * @example
      * ```typescript
      * const estimate = await kit.estimateSend({
-     *   from: sourceAdapter,
-     *   to: { adapter: destAdapter, chain: 'Polygon' },
+     *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+     *   to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      *   amount: '50.0',
      *   token: 'USDT'
      * })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/app-kit",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "engines": {
     "node": ">=16.0.0"
   },
@@ -8,8 +8,8 @@
   "module": "./index.mjs",
   "types": "./index.d.ts",
   "dependencies": {
-    "@circle-fin/bridge-kit": "1.7.0",
-    "@circle-fin/swap-kit": "1.0.1",
+    "@circle-fin/bridge-kit": "1.8.0",
+    "@circle-fin/swap-kit": "1.0.2",
     "zod": "3.25.67",
     "@ethersproject/address": "^5.8.0",
     "@ethersproject/bytes": "^5.8.0",
@@ -63,6 +63,7 @@
     "index.*",
     "README.md",
     "QUICKSTART.md",
+    "CHANGELOG.md",
     "package.json",
     "LICENSE"
   ],