@circle-fin/app-kit 1.9.0 → 1.11.0

package/bridge.cjs

@@ -18,13 +18,24 @@
 
 'use strict';
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+const { Buffer } = require('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 pino = require('pino');
 var units = require('@ethersproject/units');
 var bytes = require('@ethersproject/bytes');
+require('@ethersproject/abi');
 var address = require('@ethersproject/address');
 var bs58 = require('bs58');
-require('@ethersproject/abi');
 var web3_js = require('@solana/web3.js');
 require('bn.js');
 require('@coral-xyz/anchor');
@@ -51,6 +62,27 @@ var bs58__default = /*#__PURE__*/_interopDefault(bs58);
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Return the SDK User-Agent request header only when running in Node.js.
+ *
+ * Browsers forbid manually setting `User-Agent`, and a custom fallback header
+ * can trigger CORS preflight. Non-Node server runtimes also omit this optional
+ * attribution header because they cannot set it reliably.
+ *
+ * @returns A User-Agent header in Node.js, or an empty object otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { getNodeUserAgentHeader } from '@core/utils'
+ *
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
+ * }
+ * ```
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -3101,7 +3133,10 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
-                minter: GATEWAY_MINTER_EVM_TESTNET
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+                // DepositForHandler the GenericExecutor calls to run a fast cross-chain
+                // deposit into the GatewayWallet above.
+                depositForHandler: '0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48'
             }
         },
         forwarderSupported: {
@@ -6219,7 +6254,10 @@ var Chains = {
     minter: zod.z.string({
         required_error: 'Gateway minter address is required. Please provide a valid contract address.',
         invalid_type_error: 'Gateway minter address must be a string.'
-    }).min(1, 'Gateway minter address cannot be empty.')
+    }).min(1, 'Gateway minter address cannot be empty.'),
+    depositForHandler: zod.z.string({
+        invalid_type_error: 'Gateway depositForHandler address must be a string.'
+    }).min(1, 'Gateway depositForHandler address cannot be empty.').optional()
 }).strict() // Reject any additional properties not defined in the schema
 ;
 /**
@@ -6741,21 +6779,31 @@ const swapTokenEnumSchema = zod.z.enum([
  * returning the appropriate address based on the requested contract type.
  *
  * @param chain - The chain definition to resolve the contract address for
- * @param contractType - The type of contract address to resolve ('tokenMessenger' or 'messageTransmitter')
+ * @param contractType - The type of contract address to resolve ('tokenMessenger', 'messageTransmitter', or 'tokenMessengerWithFees')
  * @returns The contract address for the specified contract type
  * @throws Error when chain does not support CCTP v2 or has unsupported contract configuration
+ * @throws Error when 'tokenMessengerWithFees' is requested but not configured on the chain
  */ const resolveCCTPV2ContractAddress = (chain, contractType)=>{
     // Handle custom bridge contract for tokenMessenger (burn transaction)
-    if (hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
+    if (contractType === 'tokenMessenger' && hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
         return chain.kitContracts.bridge;
     }
     // At this point we know CCTP v2 is supported, so contracts exist
     const cctpConfig = chain.cctp;
     const contracts = cctpConfig.contracts.v2;
+    // The `TokenMessengerWithFees` wrapper (prepaid FORWARD path) is an optional
+    // deployment carried alongside both split and merged configurations.
+    if (contractType === 'tokenMessengerWithFees') {
+        const wrapper = contracts.tokenMessengerWithFees;
+        if (wrapper === undefined || wrapper === '') {
+            throw new Error(`TokenMessengerWithFees is not configured on chain ${chain.name}. The prepaid FORWARD path is unavailable on this chain.`);
+        }
+        return wrapper;
+    }
     // Handle different contract types with explicit type checking
     switch(contracts.type){
         case 'split':
-            return contracts.tokenMessenger ;
+            return contractType === 'tokenMessenger' ? contracts.tokenMessenger : contracts.messageTransmitter;
         case 'merged':
             return contracts.contract;
         default:
@@ -7461,13 +7509,12 @@ const swapTokenEnumSchema = zod.z.enum([
         headers: {
             ...DEFAULT_CONFIG$1.headers,
             ...config.headers ?? {},
-            // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
-            // This is why we use the 'X-User-Agent' header instead.
-            ...typeof window === 'undefined' ? {
-                'User-Agent': getUserAgent()
-            } : {
-                'X-User-Agent': getUserAgent()
-            }
+            // Browsers forbid setting a user-agent request header, and the custom
+            // fallback header the SDK used instead trips CORS preflight against the
+            // Circle APIs (it isn't in their `Access-Control-Allow-Headers`),
+            // blocking the request. So send the SDK user agent only in Node;
+            // browsers omit it entirely.
+            ...getNodeUserAgentHeader()
         }
     };
     let lastError;
@@ -9253,6 +9300,7 @@ function resolveOptions(options) {
     if (payload.tokenIn !== undefined) safe['tokenIn'] = payload.tokenIn;
     if (payload.tokenOut !== undefined) safe['tokenOut'] = payload.tokenOut;
     if (payload.txHash !== undefined) safe['txHash'] = payload.txHash;
+    if (payload.correlationId !== undefined) safe['correlationId'] = payload.correlationId;
     if (payload.errorDetails !== undefined) {
         const errorDetails = {
             ...payload.errorDetails.errorCode !== undefined && {
@@ -9323,18 +9371,15 @@ function resolveOptions(options) {
         timeoutHandle.unref();
     }
     try {
-        const isNode = isNodeEnvironment();
-        const userAgent = getUserAgent();
         await fetch(getLogsUrl(), {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                // Browser restricts setting User-Agent; use X-User-Agent instead.
-                ...isNode ? {
-                    'User-Agent': userAgent
-                } : {
-                    'X-User-Agent': userAgent
-                }
+                // Browsers forbid setting a user-agent request header, and the custom
+                // fallback header the SDK used instead trips CORS preflight (it isn't
+                // in the telemetry endpoint's `Access-Control-Allow-Headers`), so send
+                // it only in Node; browsers omit it entirely.
+                ...getNodeUserAgentHeader()
             },
             body: JSON.stringify(toSafePayload(payload)),
             signal: controller.signal
@@ -9465,7 +9510,7 @@ function resolveOptions(options) {
         // discards the stack trace, nested `cause`, and any custom Error
         // properties — exactly the context an on-call needs when a
         // resolver-closure regression triggers this path.
-        console.warn(`[stablecoin-kits telemetry] dropped error event '${eventType}':`, cause);
+        console.warn(`[stablecoin-kits telemetry] dropped event '${eventType}':`, cause);
     } catch  {
     // console.warn itself throwing is the user's environment; nothing more we
     // can do without risking the original operation error.
@@ -9481,7 +9526,9 @@ function resolveOptions(options) {
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -9497,6 +9544,9 @@ function resolveOptions(options) {
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
@@ -9610,7 +9660,7 @@ function resolveOptions(options) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.12.0";
+var version$3 = "1.12.2";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -12114,6 +12164,150 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     return false;
 };
 
+/**
+ * The zero address, denoting a native-currency fee in a signed quote.
+ */ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+/**
+ * Resolve the fee payment channel for a prepaid-FORWARD burn via `TokenMessengerWithFees`.
+ *
+ * Determines the native `msg.value` and the ERC-20 approvals required, honouring
+ * the quote's `feeToken`:
+ * - Native fee (`feeToken` is the zero address): attach exactly `feeTotalAmount`
+ *   as `msg.value`; approve only the burn amount.
+ * - ERC-20 fee equal to the burn token (both USDC — the `isBurnTokenFee` case):
+ *   approve a single combined `amount + feeTotalAmount` and skip the redundant
+ *   second approval.
+ * - ERC-20 fee different from the burn token: approve the burn amount and the fee
+ *   amount separately.
+ *
+ * This encodes only balance/allowance intent; it does not fetch balances. The
+ * caller is responsible for a balance preflight against the fresh quote.
+ *
+ * @param params - The fee token, burn token, burn amount, and total fee amount.
+ * @returns The resolved fee payment plan.
+ * @throws KitError if `amount` or `feeTotalAmount` is negative.
+ *
+ * @example
+ * ```typescript
+ * // Native fee
+ * resolveFeePayment({
+ *   feeToken: '0x0000000000000000000000000000000000000000',
+ *   burnToken: '0xUSDC...',
+ *   amount: 1_000_000n,
+ *   feeTotalAmount: 3_500_000n,
+ * })
+ * // → { isNativeFee: true, isBurnTokenFee: false, nativeValue: 3_500_000n,
+ * //     approvals: [{ token: '0xUSDC...', amount: 1_000_000n }] }
+ * ```
+ */ const resolveFeePayment = (params)=>{
+    const { feeToken, burnToken, amount, feeTotalAmount } = params;
+    if (typeof amount !== 'bigint' || amount < 0n) {
+        throw createValidationFailedError$1('amount', amount, 'Must be a non-negative bigint');
+    }
+    if (typeof feeTotalAmount !== 'bigint' || feeTotalAmount < 0n) {
+        throw createValidationFailedError$1('feeTotalAmount', feeTotalAmount, 'Must be a non-negative bigint');
+    }
+    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS;
+    const isBurnTokenFee = !isNativeFee && feeToken.toLowerCase() === burnToken.toLowerCase();
+    if (isNativeFee) {
+        return {
+            isNativeFee: true,
+            isBurnTokenFee: false,
+            nativeValue: feeTotalAmount,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount
+                }
+            ]
+        };
+    }
+    if (isBurnTokenFee) {
+        // Fee and burn draw on the same token — a single combined approval covers
+        // both; the redundant second approval is skipped.
+        return {
+            isNativeFee: false,
+            isBurnTokenFee: true,
+            nativeValue: 0n,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount: amount + feeTotalAmount
+                }
+            ]
+        };
+    }
+    return {
+        isNativeFee: false,
+        isBurnTokenFee: false,
+        nativeValue: 0n,
+        approvals: [
+            {
+                token: burnToken,
+                amount
+            },
+            {
+                token: feeToken,
+                amount: feeTotalAmount
+            }
+        ]
+    };
+};
+
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ *
+ * Encoded with `TextEncoder` (a browser-safe Web API) rather than `Buffer.from`
+ * so this module-level constant does not reference the Node `Buffer` global at
+ * import time. App Kit inlines this provider into its bundle without a Buffer polyfill, and a
+ * bare `Buffer` here crashes browser bundles (e.g. Vite) on load — even for apps
+ * that never touch the prepaid FORWARD path. Mirrors `buildForwardingHookData`.
+ */ const CCTP_FORWARD_MAGIC_HEX = Array.from(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX)).map((byte)=>byte.toString(16).padStart(2, '0')).join('');
+/**
+ * Determine whether a hookData blob begins with the `cctp-forward` envelope.
+ *
+ * The prepaid FORWARD path requires the GenericExecutor blob to be wrapped in a
+ * `cctp-forward` frame; without it the wrapper reverts `ForwardFeeWithoutHook`.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @returns True when the hookData starts with the `cctp-forward` magic.
+ *
+ * @example
+ * ```typescript
+ * hasForwardHook('0x636374702d666f7277617264...') // true
+ * hasForwardHook('0xdeadbeef') // false
+ * ```
+ */ const hasForwardHook = (hookData)=>{
+    if (typeof hookData !== 'string') {
+        return false;
+    }
+    const normalized = (hookData.startsWith('0x') ? hookData.slice(2) : hookData).toLowerCase();
+    return normalized.startsWith(CCTP_FORWARD_MAGIC_HEX);
+};
+/**
+ * Assert that a hookData blob is forward-friendly for the prepaid FORWARD path.
+ *
+ * The prepaid FORWARD path always requests a FORWARD fee item, so the wrapper
+ * requires the hookData to start with a `cctp-forward` frame. Validating this
+ * before the burn surfaces the guaranteed `ForwardFeeWithoutHook` revert as a
+ * typed input error instead of an on-chain failure.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @throws KitError (`INPUT_VALIDATION_FAILED`) if the hookData is missing or lacks
+ *   the `cctp-forward` frame.
+ *
+ * @example
+ * ```typescript
+ * assertForwardHookData(geForwardHookData) // ok
+ * assertForwardHookData('0xdeadbeef') // throws — would revert ForwardFeeWithoutHook
+ * ```
+ */ const assertForwardHookData = (hookData)=>{
+    if (!hasForwardHook(hookData)) {
+        throw createValidationFailedError$1('hookData', hookData, 'Prepaid FORWARD burns require a cctp-forward-wrapped hookData; without it the TokenMessengerWithFees wrapper reverts ForwardFeeWithoutHook');
+    }
+};
+
 /**
  * Type guard to validate the forwardFee object structure.
  *
@@ -13045,6 +13239,109 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
     }
 }
 
+/**
+ * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
+ *
+ * Validates the full public-boundary input before any field destructuring,
+ * `BigInt()` coercion, or adapter preparation runs, so malformed JS-caller
+ * inputs always produce typed `KitError` validation failures.
+ *
+ * Checks performed (in order):
+ * - `params` must be a non-null plain object
+ * - `source` — valid CCTP v2 wallet context (via `assertCCTPv2WalletContext`)
+ * - `destinationChain` — present and supports CCTP v2
+ * - source and destination chains must both be testnet or both mainnet
+ * - source and destination chains must differ
+ * - `executor` — non-empty string
+ * - `amount` — bigint or non-empty string coercible to bigint
+ * - `feeTotalAmount` — bigint or non-empty string coercible to bigint
+ * - `feeToken` — valid EVM address (`0x` + 40 hex chars)
+ * - `claim.signedQuote` — valid `0x`-prefixed hex string
+ * - `claim.refundAddress` — valid EVM address
+ * - `hookData` — valid `0x`-prefixed hex string when present
+ *
+ * @param params - The value to validate.
+ * @throws {KitError} If any field is missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * assertBurnWithFeesParams(params)
+ * // params is now typed as BurnWithFeesParams and safe to use
+ * const { source, destinationChain, amount } = params
+ * ```
+ */ function assertBurnWithFeesParams(params) {
+    if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+        throw createValidationFailedError$1('params', params, 'Must be a non-null plain object');
+    }
+    const p = params;
+    // Source wallet context
+    assertCCTPv2WalletContext(p['source']);
+    const source = p['source'];
+    // destinationChain
+    const destinationChain = p['destinationChain'];
+    if (destinationChain === null || destinationChain === undefined || typeof destinationChain !== 'object') {
+        throw createValidationFailedError$1('destinationChain', destinationChain, 'Must be a chain definition object');
+    }
+    if (!isCCTPV2Supported(destinationChain)) {
+        throw createValidationFailedError$1('destinationChain', destinationChain, 'destinationChain must support CCTP v2');
+    }
+    const dest = destinationChain;
+    // Testnet / mainnet mismatch
+    if (source.chain.isTestnet !== dest.isTestnet) {
+        throw createNetworkMismatchError(source.chain, dest);
+    }
+    // Same-chain guard
+    if (source.chain.name === dest.name) {
+        throw createUnsupportedRouteError(source.chain.name, dest.name);
+    }
+    // executor
+    const executor = p['executor'];
+    if (typeof executor !== 'string' || executor === '') {
+        throw createValidationFailedError$1('executor', executor, 'A GenericExecutor address is required (used for both mintRecipient and destinationCaller)');
+    }
+    // amount
+    const rawAmount = p['amount'];
+    if (typeof rawAmount !== 'bigint' && typeof rawAmount !== 'string' || rawAmount === '') {
+        throw createValidationFailedError$1('amount', rawAmount, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawAmount);
+    } catch  {
+        throw createValidationFailedError$1('amount', rawAmount, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeTotalAmount
+    const rawFee = p['feeTotalAmount'];
+    if (typeof rawFee !== 'bigint' && typeof rawFee !== 'string' || rawFee === '') {
+        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawFee);
+    } catch  {
+        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeToken
+    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
+        throw createValidationFailedError$1('feeToken', p['feeToken'], 'Must be a valid EVM address (use the zero address for a native fee)');
+    }
+    // claim
+    const rawClaim = p['claim'];
+    if (rawClaim === null || typeof rawClaim !== 'object' || Array.isArray(rawClaim)) {
+        throw createValidationFailedError$1('claim', rawClaim, 'Must be an object with signedQuote and refundAddress');
+    }
+    const claim = rawClaim;
+    if (!hexStringSchema.safeParse(claim['signedQuote']).success) {
+        throw createValidationFailedError$1('claim.signedQuote', claim['signedQuote'], 'Must be a valid hex string starting with 0x');
+    }
+    if (!evmAddressSchema.safeParse(claim['refundAddress']).success) {
+        throw createValidationFailedError$1('claim.refundAddress', claim['refundAddress'], 'Must be a valid EVM address');
+    }
+    // hookData (optional)
+    const hookData = p['hookData'];
+    if (hookData !== undefined && hookData !== '' && !hexStringSchema.safeParse(hookData).success) {
+        throw createValidationFailedError$1('hookData', hookData, 'Must be a valid hex string starting with 0x');
+    }
+}
+
 /**
  * CCTP bridge step names that can occur in the bridging flow.
  *
@@ -14253,10 +14550,15 @@ const mockAttestationMessage = {
     const burnCallData = burnRequest.getCallData();
     // batchExecute may throw before submission (wallet declined) but never
     // after — post-submission errors are returned as empty receipts.
+    // The sender is threaded for adapters whose execution is routed through a
+    // signing strategy (which has no wallet account to read it from); the
+    // wallet-client path ignores it.
     const batchResult = await adapter.batchExecute([
         approveCallData,
         burnCallData
-    ], chain);
+    ], chain, {
+        fromAddress: params.source.address
+    });
     const approveReceipt = batchResult.receipts[0];
     const burnReceipt = batchResult.receipts[1];
     const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
@@ -14399,7 +14701,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$2 = "1.9.0";
+var version$2 = "1.10.1";
 var pkg$2 = {
 	version: version$2};
 
@@ -15554,7 +15856,7 @@ function assertCCTPV2Config(config) {
             throw new Error(`Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
         }
         // Resolve spender address with proper error handling
-        const spenderAddress = resolveCCTPV2ContractAddress(chain);
+        const spenderAddress = resolveCCTPV2ContractAddress(chain, 'tokenMessenger');
         // Prepare action parameters
         const actionParams = {
             amount: BigInt(amount),
@@ -16034,6 +16336,106 @@ function assertCCTPV2Config(config) {
         return await source.adapter.prepareAction('cctp.v2.depositForBurn', actionParams, resolvedContext);
     }
     /**
+   * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
+   *
+   * Builds the source-chain `depositForBurnWithHookAndFees` call for the
+   * GenericExecutor FORWARD path: fees are collected up front on the source chain
+   * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
+   * the GenericExecutor, and the GE `hookData` is passed through unchanged.
+   *
+   * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
+   * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+   * `claim` are produced elsewhere and passed in here:
+   * - `hookData`: `buildForwardingHookDataWithPayload(version,
+   *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
+   * - `claim.signedQuote` / `feeToken` / `feeTotalAmount`: from `fetchFeeQuote`
+   *   (`@circle-fin/provider-fee-v1`), whose FORWARD item must be bound to the
+   *   SAME `hookData` and executor `destinationCaller` used here.
+   *
+   * The returned approvals and burn are NOT executed — the caller executes the
+   * approvals first (in order) and then the burn. The fee payment channel matches
+   * the quote's `feeToken`:
+   * - Native fee: exactly `feeTotalAmount` is attached as the burn's `msg.value`;
+   *   only the burn amount is approved.
+   * - USDC fee (same token as the burn): a single combined `amount + feeTotalAmount`
+   *   approval covers both; the redundant second approval is skipped.
+   *
+   * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+   * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
+   * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
+   * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
+   *   support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
+   *   a bigint or a numeric string coercible to bigint, the hookData lacks a
+   *   `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
+   *   context cannot be resolved.
+   *
+   * @example
+   * ```typescript
+   * const { approvals, burn } = await provider.burnWithFees({
+   *   source,
+   *   destinationChain: Arc,
+   *   amount: 1_000_000n,
+   *   executor: genericExecutorAddress,
+   *   hookData: geForwardHookData,
+   *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
+   *   feeToken: '0x0000000000000000000000000000000000000000', // native
+   *   feeTotalAmount: 3_500_000n,
+   * })
+   * for (const approval of approvals) await approval.execute()
+   * const txHash = await burn.execute()
+   * ```
+   */ async burnWithFees(params) {
+        assertBurnWithFeesParams(params);
+        const { source, destinationChain, executor, hookData, claim, feeToken } = params;
+        const amount = BigInt(params.amount);
+        const feeTotalAmount = BigInt(params.feeTotalAmount);
+        // Coupling guard: the prepaid FORWARD path always requests a FORWARD fee item,
+        // so the hookData must carry a cctp-forward frame; otherwise the wrapper
+        // reverts ForwardFeeWithoutHook. Surface it as a typed input error up front.
+        assertForwardHookData(hookData);
+        const burnToken = source.chain.usdcAddress;
+        const feePayment = resolveFeePayment({
+            feeToken,
+            burnToken,
+            amount,
+            feeTotalAmount
+        });
+        // Resolve operation context from the source wallet context.
+        const operationContext = this.extractOperationContext(source);
+        let resolvedContext;
+        try {
+            resolvedContext = await resolveOperationContext(source.adapter, operationContext);
+        } catch (error) {
+            throw createValidationFailedError$1('source.adapter', undefined, `Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const context = resolvedContext;
+        const wrapperAddress = resolveCCTPV2ContractAddress(source.chain, 'tokenMessengerWithFees');
+        // Build the ERC-20 approvals to the wrapper (burn token, plus a distinct fee
+        // token only when the fee is not paid in the burn token).
+        const approvals = await Promise.all(feePayment.approvals.map(async (approval)=>source.adapter.prepareAction('token.approve', {
+                tokenAddress: approval.token,
+                delegate: wrapperAddress,
+                amount: approval.amount
+            }, context)));
+        // Build the burn: mintRecipient AND destinationCaller are both the executor.
+        const burn = await source.adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
+            fromChain: source.chain,
+            toChain: destinationChain,
+            amount,
+            mintRecipient: executor,
+            destinationCaller: executor,
+            hookData,
+            claim,
+            feeToken,
+            feeTotalAmount
+        }, context);
+        return {
+            approvals,
+            burn,
+            feePayment
+        };
+    }
+    /**
    * Waits for a transaction to be mined and confirmed on the blockchain.
    *
    * This method should block until the transaction is confirmed on the blockchain.
@@ -16913,7 +17315,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.3.2";
+var version$1 = "1.5.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -16978,7 +17380,10 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
     }).min(1, 'kitKey must be a non-empty string').optional(),
     provider: zod.z.string({
         invalid_type_error: 'provider must be a string'
-    }).min(1, 'provider must be a non-empty string').optional()
+    }).min(1, 'provider must be a non-empty string').optional(),
+    batchTransactions: zod.z.boolean({
+        invalid_type_error: 'batchTransactions must be a boolean'
+    }).optional()
 });
 /**
  * Zod schema for adapter context.
@@ -17417,7 +17822,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
      * Circle Stablecoin Service API Key.
      * Must be a valid API key format.
-     */ apiKey: apiKeySchema
+     */ apiKey: apiKeySchema.optional()
 }).superRefine(requireCrossChainQuoteToAddress);
 /**
  * Zod schema for validating CreateSwapRequest parameters.
@@ -17475,7 +17880,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
    * Circle Stablecoin Service API Key.
    * Must be a valid API key format.
-   */ apiKey: apiKeySchema
+   */ apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetSwapStatusResponse data.
@@ -17511,7 +17916,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     toChain: zod.z.string({
         invalid_type_error: 'toChain must be a string'
     }).min(1, 'toChain must be a non-empty string if provided').optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating CreateSwapResponse payloads.
@@ -17520,13 +17925,15 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'fee token is required',
         invalid_type_error: 'fee token must be a string'
     }).min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema
+    amount: feeAmountSchema,
+    decimals: zod.z.number().int('fee token decimals must be an integer').nonnegative('fee token decimals must be a non-negative integer').optional(),
+    symbol: zod.z.string({
+        invalid_type_error: 'fee token symbol must be a string'
+    }).min(1, 'fee token symbol must be a non-empty string').optional()
 });
 /**
  * Developer fee item schema with basis field.
- */ const createSwapDeveloperFeeItemSchema = zod.z.object({
-    token: zod.z.string().min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema,
+ */ const createSwapDeveloperFeeItemSchema = createSwapFeeItemSchema.extend({
     basis: zod.z.enum([
         'inputAmount',
         'estimatedAmount'
@@ -17618,7 +18025,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     addresses: zod.z.array(zod.z.string({
         invalid_type_error: 'addresses entries must be strings'
     }).min(1, 'addresses entries must be non-empty strings')).min(1, 'addresses must contain at least one entry when provided').max(MAX_RATE_ADDRESSES_PER_REQUEST, `addresses supports at most ${String(MAX_RATE_ADDRESSES_PER_REQUEST)} values per request`).optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetTokenRatesResponse payloads.
@@ -17649,6 +18056,16 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'estimatedAmount is required',
         invalid_type_error: 'estimatedAmount must be a string'
     }).min(1, 'estimatedAmount must be a non-empty string'),
+    // Per-swap join key echoed back verbatim on success telemetry. Optional so a
+    // not-yet-upgraded service (no field) still validates during rollout. A
+    // malformed/non-UUID value is coerced to `undefined` (no telemetry id) rather
+    // than throwing: this is a telemetry-only field (stripped from the developer
+    // result, never used for control flow), so it must not be able to abort the
+    // swap via `parseCreateSwapResponse().parse()`. Mirrors the best-effort,
+    // never-throw contract of the rest of the telemetry stack. Implemented with
+    // `preprocess` rather than Zod's `.catch()` because static analysis misreads
+    // `.catch` on the schema chain as an unhandled Promise (S7785).
+    correlationId: zod.z.preprocess((value)=>zod.z.string().uuid().safeParse(value).success ? value : undefined, zod.z.string().optional()),
     config: createSwapRequestBaseSchema.shape.config.optional(),
     fees: createSwapFeesSchema.optional(),
     transaction: createSwapTransactionSchema
@@ -18841,7 +19258,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.2.2";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -18971,7 +19388,11 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     asset: zod.z.string(),
     assetAddress: zod.z.string(),
     lltv: zod.z.number(),
-    supplyUsd: zod.z.number()
+    supplyUsd: zod.z.number(),
+    // Optional during the expand/contract window (a backend that predates the
+    // field omits the key), mirroring the `.optional()` facets on the base
+    // schema; `null` when the product exposes no per-market allocation (V2).
+    allocationPct: zod.z.number().nullable().optional()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -18985,7 +19406,74 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     ])
 });
 /**
- * Zod schema for a single vault info object in the API response.
+ * Zod schema for the manager (curator) facet in the API response.
+ *
+ * @internal
+ */ const managerSchema = zod.z.object({
+    name: zod.z.string(),
+    address: zod.z.string().optional(),
+    // Only 'curator' is emitted today (Morpho V1/V2). Additional manager roles
+    // are added here as the providers that emit them land, rather than shipped
+    // speculatively.
+    type: zod.z.enum([
+        'curator'
+    ])
+});
+/**
+ * Zod schema for the APY profile facet in the API response.
+ *
+ * @internal
+ */ const apyProfileSchema = zod.z.object({
+    current: zod.z.number(),
+    native: zod.z.number().nullable(),
+    d7: zod.z.number().nullable(),
+    d30: zod.z.number().nullable(),
+    d90: zod.z.number().nullable(),
+    rewardShare: zod.z.number().nullable(),
+    source: zod.z.string().optional(),
+    asOf: zod.z.string().optional()
+});
+/**
+ * Zod schema for the fee split facet in the API response.
+ *
+ * @internal
+ */ const feeInfoSchema = zod.z.object({
+    performance: zod.z.number().nullable(),
+    management: zod.z.number().nullable()
+});
+/**
+ * Zod schema for the liquidity profile facet in the API response.
+ *
+ * `totalSupply` is the outstanding vault share tokens (ERC4626 totalSupply);
+ * it is validated as a raw JSON amount, like `totalDeposits`/`available`.
+ *
+ * @internal
+ */ const liquidityProfileSchema = zod.z.object({
+    totalDeposits: amountJsonSchema,
+    available: amountJsonSchema,
+    totalSupply: amountJsonSchema,
+    status: zod.z.enum([
+        'active',
+        'low_liquidity'
+    ])
+});
+/**
+ * Zod schema for the risk signals facet in the API response.
+ *
+ * @internal
+ */ const riskSignalsSchema = zod.z.object({
+    circleSentinel: zod.z.boolean(),
+    warnings: zod.z.array(vaultWarningSchema).optional(),
+    earnKitWarnings: zod.z.array(zod.z.string()).optional()
+});
+/**
+ * Zod schema for the universal earn-opportunity base in the API response.
+ *
+ * Retains every existing deprecated flat field (kept validated through the
+ * expand/contract window so default-strip does not drop them) and adds the
+ * new nested facets. The nested facets are `.optional()` during the
+ * transition so the SDK still validates against a not-yet-fully-deployed
+ * backend; they become required after Expand ships.
  *
  * @internal
  */ const vaultInfoResponseSchema = zod.z.object({
@@ -19010,6 +19498,96 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     warnings: zod.z.array(vaultWarningSchema).optional(),
     earnKitWarnings: zod.z.array(zod.z.string()).optional()
 });
+/**
+ * Shared base schema: existing flat fields (kept) plus the new nested
+ * facets and neutral identity. Facets are `.optional()` during the
+ * transition; flip to required once the backend is confirmed emitting.
+ *
+ * @internal
+ */ const earnBaseSchema = vaultInfoResponseSchema.extend({
+    address: zod.z.string().optional(),
+    asOf: zod.z.string().optional(),
+    manager: managerSchema.nullable().optional(),
+    apyProfile: apyProfileSchema.optional(),
+    fee: feeInfoSchema.optional(),
+    liquidityProfile: liquidityProfileSchema.optional(),
+    riskSignals: riskSignalsSchema.optional()
+});
+/**
+ * Zod schema for the `vault` opportunity variant.
+ *
+ * @internal
+ */ const vaultOpportunitySchema = earnBaseSchema.extend({
+    productType: zod.z.literal('vault'),
+    collateral: zod.z.array(collateralSchema)
+});
+/**
+ * Discriminated union over `productType`. Add union members here as new
+ * product types (e.g. `lending_market`, `rwa_token`) land.
+ *
+ * @internal
+ */ const earnOpportunityVariants = [
+    vaultOpportunitySchema
+];
+/** @internal */ const earnOpportunitySchema = zod.z.discriminatedUnion('productType', earnOpportunityVariants);
+/** Product types this SDK version knows how to parse. */ const knownProductTypes = new Set(earnOpportunityVariants.map((variant)=>variant.shape.productType.value));
+/**
+ * Tolerant list parser for earn opportunities.
+ *
+ * `z.discriminatedUnion` throws on an unrecognized discriminant and
+ * `z.array` fails the whole array if any element fails. Two migration-window
+ * cases are smoothed over here so neither breaks an already-shipped SDK:
+ *
+ * - A backend that predates `productType` omits it entirely. `'vault'` was the
+ *   only opportunity type then, so default a missing discriminant to `'vault'`
+ *   rather than dropping every vault the backend returns.
+ * - A future backend adds a *second* `productType` this SDK version does not
+ *   know. Drop those elements (a present-but-unrecognized discriminant) instead
+ *   of rejecting the whole list.
+ *
+ * Only the drop above is a *tolerant* case. Anything that is not a plain object
+ * with a present-but-unknown string `productType` — `null`, `undefined`,
+ * primitives, or an object whose `productType` is malformed — is passed through
+ * untouched so `z.array(earnOpportunitySchema)` reports it as a normal
+ * validation failure. It is deliberately not silently dropped (which would hide
+ * malformed backend data) and never throws here (an unguarded property read on
+ * a non-object would escape `safeParse` as a raw `TypeError` instead of a
+ * `ZodError`).
+ *
+ * @internal
+ */ const earnOpportunityListSchema = zod.z.preprocess((raw)=>{
+    if (!Array.isArray(raw)) {
+        return raw;
+    }
+    // Array.isArray narrows `raw` to `any[]`; view it as `unknown[]` so the
+    // map/filter chain stays type-safe and no `any` leaks into the return.
+    const entries = raw;
+    return entries.map((entry)=>{
+        // Only touch plain objects; non-objects fall through to fail validation.
+        if (typeof entry !== 'object' || entry === null) {
+            return entry;
+        }
+        const record = entry;
+        // Older backend predating productType: default to the only type then.
+        return record.productType === undefined ? {
+            ...record,
+            productType: 'vault'
+        } : record;
+    }).filter((entry)=>{
+        // Drop ONLY a present-but-unknown string discriminant (a future
+        // productType this SDK version doesn't know). Everything else —
+        // non-objects, a non-string productType — flows through to
+        // z.array(earnOpportunitySchema) and fails/passes validation normally.
+        if (typeof entry !== 'object' || entry === null) {
+            return true;
+        }
+        const productType = entry.productType;
+        if (typeof productType !== 'string') {
+            return true;
+        }
+        return knownProductTypes.has(productType);
+    });
+}, zod.z.array(earnOpportunitySchema));
 // ---------------------------------------------------------------------------
 // Position response schema
 // ---------------------------------------------------------------------------
@@ -19139,6 +19717,7 @@ const positionPnlSchema = zod.z.discriminatedUnion('status', [
  *
  * @internal
  */ const depositPayloadSchema = zod.z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: depositExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -19230,6 +19809,21 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     amount: amountJsonSchema,
     vaultAddress: hexAddressSchema
 }).passthrough();
+/** @internal */ const bridgeQuoteExpirySchema = zod.z.discriminatedUnion('mode', [
+    zod.z.object({
+        mode: zod.z.literal('TIMESTAMP'),
+        expiresAt: zod.z.string().datetime({
+            offset: true
+        })
+    }),
+    zod.z.object({
+        mode: zod.z.literal('BLOCK_NUMBER'),
+        expiresAtBlock: zod.z.number().int(),
+        blockEstimatedAt: zod.z.string().datetime({
+            offset: true
+        }).optional()
+    })
+]).optional().catch(undefined);
 /**
  * Zod schema for the bridge deposit prepare payload.
  *
@@ -19241,6 +19835,10 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     execId: bridgeDepositExecIdSchema,
     erc3009TypedData: bridgeDepositPreparedBundleSchema,
     expiresAt: zod.z.string().datetime(),
+    quoteIssuedAt: zod.z.string().datetime({
+        offset: true
+    }).optional().catch(undefined),
+    quoteExpiry: bridgeQuoteExpirySchema,
     review: bridgeDepositPrepareReviewSchema
 });
 /**
@@ -19306,6 +19904,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
  *
  * @internal
  */ const withdrawPayloadSchema = zod.z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: withdrawExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -19319,6 +19918,27 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     data: withdrawPayloadSchema
 });
 // ---------------------------------------------------------------------------
+// Transaction report response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for the transaction report payload inside the API `data` envelope.
+ *
+ * The Earn Service returns an empty payload (`{"data":{}}`) on success, so the
+ * schema accepts any object shape and does not require specific fields.
+ *
+ * @internal
+ */ const transactionReportPayloadSchema = zod.z.object({}).passthrough();
+/**
+ * Zod schema for the `POST /v1/earnKit/transactions/report` API response.
+ *
+ * The Earn Service API wraps the transaction report payload in a `data`
+ * envelope.
+ *
+ * @internal
+ */ zod.z.object({
+    data: transactionReportPayloadSchema
+});
+// ---------------------------------------------------------------------------
 // Claim rewards response schema
 // ---------------------------------------------------------------------------
 /**
@@ -19379,6 +19999,30 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     token: zod.z.string(),
     amount: amountJsonSchema
 });
+/**
+ * Zod schema for a native gas-fee entry in an EarnKit quote response.
+ *
+ * The Earn Service backend estimates gas server-side and returns one entry per
+ * action (`Approve`, `Deposit`, `Withdraw`). A successful estimate carries
+ * `fees` in the SDK `EstimatedGas` shape (`{ gas, gasPrice, fee }`), each a raw
+ * integer string in the chain's native base units. When the backend cannot
+ * estimate an action it returns `fees: null` with an `error` message instead.
+ *
+ * The schema deliberately validates almost nothing beyond the envelope: `name`
+ * is optional and `fees` is entirely unvalidated (`unknown`). ALL validation
+ * of `fees` — that it is an object at all, and that `gas`, `gasPrice`, and
+ * `fee` are parseable integer strings — is deferred to {@link toQuoteGasFees},
+ * which degrades a malformed entry to a `fees: null` soft failure. This is
+ * intentional: gas is best-effort, so a single unparseable gas entry (a wrong
+ * type such as `fees: 123` or `fees: 'bad'`, a missing field, or a non-numeric
+ * `fee`) must never fail Zod validation and reject the entire quote.
+ *
+ * @internal
+ */ const quoteGasFeeSchema = zod.z.object({
+    name: zod.z.string().optional(),
+    fees: zod.z.unknown(),
+    error: zod.z.string().optional()
+}).passthrough();
 /**
  * Zod schema for the inner deposit quote payload.
  *
@@ -19394,7 +20038,8 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     expectedShares: amountJsonSchema,
     sharePrice: zod.z.string(),
     currentApy: zod.z.number(),
-    fees: zod.z.array(feeSchema).optional()
+    fees: zod.z.array(feeSchema).optional(),
+    gasFees: zod.z.array(quoteGasFeeSchema).optional()
 });
 /**
  * Zod schema for the `POST /v1/earnKit/deposit/quote` API response.
@@ -19421,6 +20066,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     sharePrice: zod.z.string(),
     maxWithdrawable: amountJsonSchema,
     fees: zod.z.array(feeSchema),
+    gasFees: zod.z.array(quoteGasFeeSchema).optional(),
     warnings: zod.z.array(zod.z.string()).optional()
 });
 /**
@@ -19478,7 +20124,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
  *
  * @internal
  */ const getVaultsPayloadSchema = zod.z.object({
-    vaults: zod.z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     errors: zod.z.array(vaultErrorSchema)
 });
 /**
@@ -19508,7 +20154,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
  *
  * @internal
  */ const exploreVaultsPayloadSchema = zod.z.object({
-    vaults: zod.z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     pagination: explorePaginationSchema
 });
 /**
@@ -20076,6 +20722,8 @@ function hasCrossChainDepositQuoteShape(params) {
     config: earnConfigSchema.optional()
 });
 
+/** SDK name used in telemetry payloads. */ resolveKitSdkName(pkg.name);
+
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg.name}/${pkg.version}`);