@circle-fin/app-kit 1.13.0 → 1.14.0

package/estimateBridge.mjs

@@ -30,8 +30,8 @@ if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
 import { z } from 'zod';
 import pino from 'pino';
 import { formatUnits as formatUnits$1, parseUnits as parseUnits$1 } from '@ethersproject/units';
-import { hexlify, hexZeroPad, concat } from '@ethersproject/bytes';
-import '@ethersproject/abi';
+import { hexlify, hexZeroPad, isHexString, concat } from '@ethersproject/bytes';
+import { Interface, defaultAbiCoder } from '@ethersproject/abi';
 import { getAddress, isAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
 import { PublicKey } from '@solana/web3.js';
@@ -3658,8 +3658,45 @@ var EarnChain;
  * This program handles minting operations for Gateway transactions
  * on Solana devnet.
  */ const GATEWAY_MINTER_SOLANA_DEVNET = 'GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr';
-/** TokenMessengerWithFees address shared by enabled EVM mainnet sources. */ const TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET = '0x71f54F818671cD0D7ea140Da213e5C8b5C92a408';
-/** TokenMessengerWithFees address shared by enabled EVM testnet sources. */ const TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET = '0x8745D906D67C346E5eb1aEEED38Eb87F34DF0C0A';
+/**
+ * The `TokenMessengerWithFees` proxy contract address for EVM mainnet networks
+ * (all chains except Edge).
+ *
+ * Deployed at a CREATE3-derived address; identical across all mainnet EVM
+ * source chains. Present on any chain that supports the prepaid FORWARD path
+ * via `depositForBurnWithHookAndFees`.
+ */ const TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET = '0x71f54F818671cD0D7ea140Da213e5C8b5C92a408';
+/**
+ * The `TokenMessengerWithFees` proxy contract address for EVM testnet networks.
+ *
+ * Identical across all testnet EVM source chains. Present on any testnet chain
+ * that supports the prepaid FORWARD path via `depositForBurnWithHookAndFees`.
+ */ const TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET = '0x8745D906D67C346E5eb1aEEED38Eb87F34DF0C0A';
+/**
+ * The `DepositForHandler` proxy contract address for EVM mainnet networks.
+ *
+ * The handler the GenericExecutor calls on a fast-deposit destination chain to
+ * run a cross-chain deposit into the GatewayWallet. Deployed at the same
+ * address across all mainnet EVM destination chains.
+ */ const DEPOSIT_FOR_HANDLER_EVM_MAINNET = '0x16529813203f77E036576666336554a1210dce4D';
+/**
+ * The `DepositForHandler` proxy contract address for EVM testnet networks.
+ *
+ * Identical across all testnet EVM destination chains.
+ */ const DEPOSIT_FOR_HANDLER_EVM_TESTNET = '0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48';
+/**
+ * The `GenericExecutor` proxy contract address for EVM mainnet networks.
+ *
+ * The GenericExecutor is the `mintRecipient` and `destinationCaller` on the
+ * destination chain for the CCTP v2 prepaid FORWARD path. It receives the CCTP
+ * mint and calls the `DepositForHandler` to complete the fast deposit.
+ * Deployed at the same address across all mainnet EVM destination chains.
+ */ const GENERIC_EXECUTOR_EVM_MAINNET = '0xFa7be2f04F3Ad4ca969260729c6d45B5625984A7';
+/**
+ * The `GenericExecutor` proxy contract address for EVM testnet networks.
+ *
+ * Identical across all testnet EVM destination chains.
+ */ const GENERIC_EXECUTOR_EVM_TESTNET = '0xEdC81040756AcCfF070c21D37b265b9D0b5Ba45e';
 
 /**
  * Arc Testnet chain definition
@@ -3718,9 +3755,8 @@ var EarnChain;
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
                 minter: GATEWAY_MINTER_EVM_TESTNET,
-                // DepositForHandler the GenericExecutor calls to run a fast cross-chain
-                // deposit into the GatewayWallet above.
-                depositForHandler: '0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48'
+                depositForHandler: DEPOSIT_FOR_HANDLER_EVM_TESTNET,
+                genericExecutor: GENERIC_EXECUTOR_EVM_TESTNET
             }
         },
         forwarderSupported: {
@@ -3915,7 +3951,9 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_MAINNET,
-                minter: GATEWAY_MINTER_EVM_MAINNET
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+                depositForHandler: DEPOSIT_FOR_HANDLER_EVM_MAINNET,
+                genericExecutor: GENERIC_EXECUTOR_EVM_MAINNET
             }
         },
         forwarderSupported: {
@@ -3979,7 +4017,9 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
-                minter: GATEWAY_MINTER_EVM_TESTNET
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+                depositForHandler: DEPOSIT_FOR_HANDLER_EVM_TESTNET,
+                genericExecutor: GENERIC_EXECUTOR_EVM_TESTNET
             }
         },
         forwarderSupported: {
@@ -4292,6 +4332,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4337,6 +4378,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4382,6 +4424,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x98706A006bc632Df31CAdFCBD43F38887ce2ca5c',
+                tokenMessengerWithFees: '0x3Ac96675F9a3E6922713e041645D82f3561d3686',
                 messageTransmitter: '0x5b61381Fc9e58E70EfC13a4A97516997019198ee',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4427,6 +4470,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4775,6 +4819,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4822,6 +4867,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5103,6 +5149,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5148,6 +5195,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 64,
                 fastConfirmations: 1
@@ -5193,6 +5241,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 64,
                 fastConfirmations: 1
@@ -5494,6 +5543,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5540,6 +5590,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5847,7 +5898,9 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_MAINNET,
-                minter: GATEWAY_MINTER_EVM_MAINNET
+                minter: GATEWAY_MINTER_EVM_MAINNET,
+                depositForHandler: DEPOSIT_FOR_HANDLER_EVM_MAINNET,
+                genericExecutor: GENERIC_EXECUTOR_EVM_MAINNET
             }
         },
         forwarderSupported: {
@@ -5912,7 +5965,9 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
-                minter: GATEWAY_MINTER_EVM_TESTNET
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+                depositForHandler: DEPOSIT_FOR_HANDLER_EVM_TESTNET,
+                genericExecutor: GENERIC_EXECUTOR_EVM_TESTNET
             }
         },
         forwarderSupported: {
@@ -6998,18 +7053,48 @@ var Chains = /*#__PURE__*/Object.freeze({
     return chain.cctp?.contracts.v2 !== undefined;
 }
 
+/**
+ * Chains the Fee Service accepts as a SOURCE for source-paid ("receive-exact")
+ * CCTP v2 fees. An explicit allowlist is required because the
+ * `TokenMessengerWithFees` wrapper address is now shared with the fast-deposit
+ * forwarder path, so wrapper presence no longer implies source-fee support.
+ * Keep in sync with backend coverage.
+ */ const SOURCE_FEE_SUPPORTED_ALLOWLIST = new Set([
+    // Mainnet
+    Blockchain.Ethereum,
+    Blockchain.Base,
+    Blockchain.Arbitrum,
+    Blockchain.Unichain,
+    Blockchain.Optimism,
+    Blockchain.Codex,
+    Blockchain.Ink,
+    Blockchain.Plume,
+    Blockchain.Linea,
+    Blockchain.World_Chain,
+    // Testnet counterparts
+    Blockchain.Ethereum_Sepolia,
+    Blockchain.Base_Sepolia,
+    Blockchain.Arbitrum_Sepolia,
+    Blockchain.Unichain_Sepolia,
+    Blockchain.Optimism_Sepolia,
+    Blockchain.Codex_Testnet,
+    Blockchain.Ink_Testnet,
+    Blockchain.Plume_Testnet,
+    Blockchain.Linea_Sepolia,
+    Blockchain.World_Chain_Sepolia
+]);
 /**
  * Check whether a chain supports source-paid ("receive-exact") CCTP v2 fees.
  *
- * A chain supports source-paid fees when its CCTP v2 configuration carries a
- * deployed `TokenMessengerWithFees` wrapper address. Bridge Kit routes
- * `feePayment: 'source'` transfers through this wrapper via
- * `depositForBurnWithHookAndFees`, so a chain without the wrapper cannot be a
- * source for receive-exact bridging.
+ * A chain qualifies when it supports CCTP v2, carries a `TokenMessengerWithFees`
+ * wrapper, and is in {@link SOURCE_FEE_SUPPORTED_ALLOWLIST}.
  *
- * @param chain - The chain definition to check.
- * @returns `true` when the chain has a `tokenMessengerWithFees` wrapper
- *   configured, `false` otherwise.
+ * @param chain - The chain definition to check. A nullish or non-object value
+ *   returns `false` rather than throwing, since consumers may call from plain
+ *   JavaScript.
+ * @returns `true` when the chain supports CCTP v2, carries a
+ *   `TokenMessengerWithFees` wrapper, and is on the source-fee allowlist;
+ *   `false` otherwise.
  *
  * @example
  * ```typescript
@@ -7019,11 +7104,18 @@ var Chains = /*#__PURE__*/Object.freeze({
  * hasSourceFeeSupport(Chains.Solana) // false
  * ```
  */ function hasSourceFeeSupport(chain) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for nullish/non-object input from plain JS
+    if (chain === null || typeof chain !== 'object') {
+        return false;
+    }
     if (!isCCTPV2Supported(chain)) {
         return false;
     }
     const wrapper = chain.cctp.contracts.v2.tokenMessengerWithFees;
-    return typeof wrapper === 'string' && wrapper.length > 0;
+    if (typeof wrapper !== 'string' || wrapper.length === 0) {
+        return false;
+    }
+    return SOURCE_FEE_SUPPORTED_ALLOWLIST.has(chain.chain);
 }
 
 /**
@@ -7076,6 +7168,73 @@ var Chains = /*#__PURE__*/Object.freeze({
     return typeof contractAddress === 'string' && contractAddress.trim().length > 0;
 }
 
+/**
+ * Check whether a given chain supports Gateway protocol version 1.
+ *
+ * This type guard function examines a chain definition to determine if it has Gateway v1
+ * contract configurations. It checks that the chain has a gateway object with a
+ * `contracts.v1` entry present.
+ *
+ * @param chain - The chain definition to check for Gateway v1 support
+ * @returns `true` if `chain.gateway?.contracts?.v1` is defined, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isGatewayV1Supported, Base } from '@core/chains'
+ *
+ * if (isGatewayV1Supported(Base)) {
+ *   // TypeScript knows Base.gateway is defined here
+ *   console.log('Gateway domain:', Base.gateway.domain)
+ *   console.log('Wallet address:', Base.gateway.contracts.v1.wallet)
+ *   console.log('Minter address:', Base.gateway.contracts.v1.minter)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Usage in conditional flow
+ * function getGatewayWalletAddress(chain: ChainDefinition): string | null {
+ *   if (isGatewayV1Supported(chain)) {
+ *     return chain.gateway.contracts.v1.wallet
+ *   }
+ *   return null
+ * }
+ * ```
+ */ function isGatewayV1Supported(chain) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- JS consumers may pass a gateway object without contracts
+    return chain.gateway?.contracts?.v1 !== undefined;
+}
+
+/**
+ * Temporary allowlist of chains permitted to initiate Gateway fast deposits.
+ * Only chains keyed here are eligible; all others are rejected. Using the
+ * {@link Blockchain} enum keeps entries type-safe and catches typos at compile
+ * time. Remove this allowlist once roll-out is complete.
+ */ new Set([
+    // Mainnet
+    Blockchain.Ethereum,
+    Blockchain.Base,
+    Blockchain.Arbitrum,
+    Blockchain.Unichain,
+    Blockchain.Optimism,
+    Blockchain.Codex,
+    Blockchain.Ink,
+    Blockchain.Plume,
+    Blockchain.Linea,
+    Blockchain.World_Chain,
+    // Testnet counterparts
+    Blockchain.Ethereum_Sepolia,
+    Blockchain.Base_Sepolia,
+    Blockchain.Arbitrum_Sepolia,
+    Blockchain.Unichain_Sepolia,
+    Blockchain.Optimism_Sepolia,
+    Blockchain.Codex_Testnet,
+    Blockchain.Ink_Testnet,
+    Blockchain.Plume_Testnet,
+    Blockchain.Linea_Sepolia,
+    Blockchain.World_Chain_Sepolia
+]);
+
 /**
  * Zod schema for validating Gateway v1 contract addresses.
  *
@@ -7097,7 +7256,10 @@ var Chains = /*#__PURE__*/Object.freeze({
     }).min(1, 'Gateway minter address cannot be empty.'),
     depositForHandler: z.string({
         invalid_type_error: 'Gateway depositForHandler address must be a string.'
-    }).min(1, 'Gateway depositForHandler address cannot be empty.').optional()
+    }).min(1, 'Gateway depositForHandler address cannot be empty.').optional(),
+    genericExecutor: z.string({
+        invalid_type_error: 'Gateway genericExecutor address must be a string.'
+    }).min(1, 'Gateway genericExecutor address cannot be empty.').optional()
 }).strict() // Reject any additional properties not defined in the schema
 ;
 /**
@@ -9968,6 +10130,9 @@ const swapTokenEnumSchema = z.enum([
  * The ASCII string "cctp-forward" (12 bytes) that identifies a forwarding request.
  * This prefix is right-padded to 24 bytes in the final hookData.
  */ const CCTP_FORWARD_MAGIC_PREFIX = 'cctp-forward';
+/**
+ * Maximum value of the 32-bit `version` field in a `cctp-forward` frame.
+ */ const MAX_UINT32 = 0xffffffff;
 /**
  * CCTP forwarding version number.
  *
@@ -10044,6 +10209,76 @@ function buildForwardingHookData() {
     cachedHookDataHex = '0x' + Array.from(buffer).map((b)=>b.toString(16).padStart(2, '0')).join('');
     return cachedHookDataHex;
 }
+/**
+ * Build a `cctp-forward` hookData frame with a versioned header and an appended
+ * opaque payload.
+ *
+ * Produces the 32-byte `cctp-forward` header (24-byte ASCII magic + `uint32`
+ * version + `uint32` `dataLength = 0`) followed by `payload` appended verbatim.
+ * Unlike {@link buildForwardingHookData} — which emits only the fixed,
+ * version-0 empty frame — this lets the caller set the frame `version` and
+ * carry an inner payload such as a GenericExecutor blob.
+ *
+ * @remarks
+ * The forwarder reads only the 32-byte header to decide that a hook is
+ * forwardable, then strips it before the inner payload is consumed downstream
+ * (e.g. the GenericExecutor `abi.decode`s the appended blob, never the frame).
+ * `dataLength` stays `0` because the appended bytes are opaque to the forwarder
+ * — it is not the payload's length.
+ *
+ * @param version - The `uint32` frame version (e.g. `1` for the GenericExecutor
+ *   FORWARD path). Must be an integer in `[0, 0xFFFFFFFF]`.
+ * @param payload - A 0x-prefixed hex string appended after the header (e.g. the
+ *   bare GenericExecutor blob from `buildDepositForGenericExecutorPayload`).
+ * @returns A 0x-prefixed hex string: the 32-byte frame followed by `payload`.
+ * @throws {KitError} If `version` is out of `uint32` range or `payload` is not
+ *   a 0x-prefixed hex string (INPUT_VALIDATION_FAILED).
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   buildDepositForGenericExecutorPayload,
+ *   buildForwardingHookDataWithPayload,
+ *   padAddressToBytes32,
+ * } from '@core/utils'
+ *
+ * const { hookData: geBlob } = buildDepositForGenericExecutorPayload({
+ *   dappId: 'gateway_deposit',
+ *   domainId: 26,
+ *   handler: '0xHandlerAddressOnDestinationChain',
+ *   params: [USDC_ARC, user, 0],
+ *   recoveryAddress: padAddressToBytes32(user),
+ * })
+ *
+ * // Wrap for the prepaid Quote-API FORWARD path (frame version 1).
+ * const hookData = buildForwardingHookDataWithPayload(1, geBlob)
+ * ```
+ */ function buildForwardingHookDataWithPayload(version, payload) {
+    if (!Number.isInteger(version) || version < 0 || version > MAX_UINT32) {
+        throw createValidationFailedError$1('version', version, 'Expected an integer in the uint32 range [0, 4294967295]');
+    }
+    if (!isHexString(payload)) {
+        throw createValidationFailedError$1('payload', payload, 'Expected a 0x-prefixed hex string');
+    }
+    // `isHexString` accepts odd-length hex (e.g. '0xabc'); catch it here so it
+    // surfaces as a KitError rather than ethers' raw "hex data is odd-length"
+    // from `concat` below.
+    if (payload.length % 2 !== 0) {
+        throw createValidationFailedError$1('payload', payload, 'Expected an even-length (whole-byte) hex string');
+    }
+    // 32-byte header: 24-byte magic + uint32 version + uint32 dataLength (0).
+    const frame = new Uint8Array(32);
+    frame.set(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX), 0);
+    const view = new DataView(frame.buffer);
+    view.setUint32(24, version, false) // big-endian
+    ;
+    view.setUint32(28, CCTP_FORWARD_PAYLOAD_LENGTH, false) // big-endian, 0
+    ;
+    return hexlify(concat([
+        frame,
+        payload
+    ]));
+}
 /**
  * Build a `cctp-forward` hookData frame that instructs Circle's Orbit relayer to
  * create the recipient's Associated Token Account (ATA) before minting on Solana.
@@ -10121,6 +10356,43 @@ function buildForwardingHookData() {
     ]));
 }
 
+/**
+ * `version` field of the GenericExecutor hookData, in both the
+ * `circle-generic-executor` header (`uint32`) and the ABI tuple (`uint8`). The
+ * executor reverts if it is not `1`.
+ *
+ * @see https://circlepay.atlassian.net/wiki/spaces/~712020cd79585b52ea4353b4720c277fbfcca6/pages/3049291839
+ */ const GENERIC_EXECUTOR_HOOK_DATA_VERSION = 1;
+/**
+ * ASCII magic that prefixes a GenericExecutor hookData blob.
+ *
+ * The executor auto-detects its payload by this string. It is left-aligned and
+ * zero-padded to 24 bytes in the header, mirroring the `cctp-forward` frame
+ * layout (magic + `uint32` version + `uint32` dataLength).
+ */ const GENERIC_EXECUTOR_MAGIC_PREFIX = 'circle-generic-executor';
+/**
+ * Prepend the 32-byte `circle-generic-executor` header to the ABI tuple.
+ *
+ * Header layout (mirrors the `cctp-forward` frame): 24-byte zero-padded ASCII
+ * magic + `uint32` version + `uint32` dataLength. Unlike the `cctp-forward`
+ * frame (which the forwarder strips and so carries `dataLength = 0`), this
+ * header's dataLength is the byte length of the ABI tuple that follows, since
+ * the executor consumes both.
+ */ function prependGenericExecutorHeader(abiTuple) {
+    const header = new Uint8Array(32);
+    header.set(new TextEncoder().encode(GENERIC_EXECUTOR_MAGIC_PREFIX), 0);
+    // Byte length of the ABI tuple that the header announces.
+    const tupleByteLength = (abiTuple.length - 2) / 2;
+    const view = new DataView(header.buffer);
+    view.setUint32(24, GENERIC_EXECUTOR_HOOK_DATA_VERSION, false) // big-endian
+    ;
+    view.setUint32(28, tupleByteLength, false) // big-endian
+    ;
+    return hexlify(concat([
+        header,
+        abiTuple
+    ]));
+}
 /**
  * Left-pad a 20-byte EVM address to a 32-byte (`bytes32`) hex string.
  *
@@ -10146,6 +10418,309 @@ function buildForwardingHookData() {
     // matches ABI-decoded output.
     return hexZeroPad(getAddress(address), 32).toLowerCase();
 }
+/**
+ * Encode the bare GenericExecutor + DepositForHandler payload for a CCTP v2
+ * fast-transfer deposit into a dApp.
+ *
+ * Builds the layers inner→outer:
+ * 1. dApp calldata — the dApp function selector + ABI params, with each amount
+ *    slot left as the caller-supplied placeholder.
+ * 2. handler calldata — `(depositContract, approvalTarget, depositCalldata, amountIndices)`
+ *    for `DepositForHandler`.
+ * 3. ABI tuple — `(uint8 version, bytes32 recoveryAddress, address handler, bytes handlerCalldata)`.
+ *    No handler selector travels on the wire; the executor applies a fixed one.
+ * 4. header — the 32-byte `circle-generic-executor` magic frame prepended to the
+ *    tuple, by which the executor auto-detects the payload.
+ *
+ * The returned `hookData` is the bare GenericExecutor blob (header ‖ tuple) — the
+ * exact bytes the executor consumes. It carries no `cctp-forward` envelope. For
+ * the prepaid Quote-API FORWARD path, wrap it with
+ * {@link buildForwardingHookDataWithPayload}; the forwarder strips that envelope
+ * before the executor reads the blob.
+ *
+ * @param options - See {@link BuildDepositForGenericExecutorPayloadParams}.
+ * @returns The encoded {@link DepositForGenericExecutorPayload} layers.
+ * @throws {KitError} If `options` is not an object, `dappId` is unknown,
+ *   `config.deployments` is not an array, neither `domainId` nor
+ *   `destinationChain` resolves a domain (or the two disagree), no deployment
+ *   exists for the resolved domain, the deposit contract cannot be resolved (a
+ *   built-in deployment supplied without a `destinationChain`), no `handler` is
+ *   supplied and it cannot be resolved from `destinationChain`,
+ *   `recoveryAddress`/`handler`/contract addresses are malformed,
+ *   `config.function` is not a valid Solidity function signature, `params`
+ *   length does not match the dApp signature, `params` values fail ABI encoding
+ *   (type mismatch), `config.dynamicAmountIndices` is not an array, or an amount
+ *   index is out of range (all INPUT_VALIDATION_FAILED).
+ *
+ * @example Encode a 1-click cross-chain Circle Gateway deposit
+ * ```typescript
+ * import { buildDepositForGenericExecutorPayload, padAddressToBytes32 } from '@core/utils'
+ * import { ArcTestnet } from '@core/chains'
+ *
+ * const user = '0x75275Aff2D01699D922f045b69ed291311209738'
+ * const usdcArc = '0x3600000000000000000000000000000000000000'
+ * const { hookData } = buildDepositForGenericExecutorPayload({
+ *   dappId: 'gateway_deposit',
+ *   destinationChain: ArcTestnet, // resolves the GatewayWallet + DepositForHandler
+ *   // depositFor(address token, address depositor, uint256 value), amount idx [2]
+ *   params: [usdcArc, user, 0],
+ *   recoveryAddress: padAddressToBytes32(user),
+ * })
+ *
+ * // Pass hookData straight into the CCTP v2 fast transfer.
+ * console.log(hookData)
+ * ```
+ */ function buildDepositForGenericExecutorPayload(options) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for plain-JS callers
+    if (options === null || typeof options !== 'object') {
+        throw createValidationFailedError$1('options', options, 'Expected an options object');
+    }
+    const { dappId, params: dappParams } = options;
+    const registry = options.config ?? DAPP_CONFIG;
+    // Look up the dApp before resolving the deposit contract or handler, so an
+    // unknown dApp reports the actionable "Unknown dApp" error rather than an
+    // unresolved-handler error.
+    const config = registry[dappId];
+    if (config === undefined) {
+        throw createValidationFailedError$1('dappId', dappId, `Unknown dApp. Known dApps: ${Object.keys(registry).join(', ')}`);
+    }
+    if (!Array.isArray(config.deployments)) {
+        throw createValidationFailedError$1('deployments', config.deployments, `Expected an array of deployments for dApp '${dappId}'`);
+    }
+    // Array.isArray narrows to `any[]`; re-assert the concrete type.
+    const deployments = config.deployments;
+    // Destination CCTP domain: taken from `destinationChain` when supplied (the
+    // chain is the (network, domain) key), else the explicit `domainId`.
+    const domainId = resolveDomainId(options);
+    const deployment = deployments.find((d)=>d.domainId === domainId);
+    if (deployment === undefined) {
+        throw createValidationFailedError$1('domainId', domainId, `No '${dappId}' deployment for domain ${String(domainId)}`);
+    }
+    if (!Array.isArray(dappParams)) {
+        throw createValidationFailedError$1('params', dappParams, 'Expected an array of ABI-ordered parameters');
+    }
+    if (!isHexString(options.recoveryAddress, 32)) {
+        throw createValidationFailedError$1('recoveryAddress', options.recoveryAddress, 'Expected a 0x-prefixed 32-byte (bytes32) hex string');
+    }
+    // Deposit contract: the deployment's own address, or — for the built-in
+    // gateway_deposit deployment, which carries none — the destination chain's
+    // GatewayWallet, so the address lives only in @core/chains.
+    const resolvedDepositContract = resolveDepositContract(deployment, options, dappId);
+    // Handler: an explicit `handler` always wins; otherwise resolve the
+    // DepositForHandler from `destinationChain`. The chain is the (network, domain)
+    // key, so a shared CCTP domain (Arc is 26 on both testnet and mainnet) can
+    // never resolve the wrong network's handler and strand funds.
+    const handler = resolveDepositForHandler(options, domainId);
+    if (!isAddress(handler)) {
+        throw createValidationFailedError$1('handler', handler, 'Expected a valid EVM address');
+    }
+    const depositContract = assertAddress(resolvedDepositContract, 'depositContract');
+    const approvalTarget = assertAddress(deployment.approvalTarget ?? resolvedDepositContract, 'approvalTarget');
+    // 1. dApp calldata: selector + ABI-encoded params (amount slots stay as placeholders).
+    let dappInterface;
+    try {
+        dappInterface = new Interface([
+            `function ${config.function}`
+        ]);
+    } catch  {
+        throw createValidationFailedError$1('function', config.function, 'Expected a valid Solidity function signature');
+    }
+    const rawFragment = dappInterface.fragments[0];
+    /* v8 ignore start -- defensive: guards against unexpected library behavior */ if (rawFragment === undefined || rawFragment.type !== 'function') {
+        throw createValidationFailedError$1('function', config.function, 'Expected a valid Solidity function signature');
+    }
+    /* v8 ignore stop */ const fragment = rawFragment;
+    if (dappParams.length !== fragment.inputs.length) {
+        throw createValidationFailedError$1('params', dappParams, `'${config.function}' expects ${String(fragment.inputs.length)} params, got ${String(dappParams.length)}`);
+    }
+    let depositCalldata;
+    try {
+        depositCalldata = dappInterface.encodeFunctionData(fragment, dappParams);
+    } catch  {
+        throw createValidationFailedError$1('params', dappParams, 'ABI encoding failed — check that each param matches the expected Solidity type');
+    }
+    if (!Array.isArray(config.dynamicAmountIndices)) {
+        throw createValidationFailedError$1('dynamicAmountIndices', config.dynamicAmountIndices, `Expected an array of amount indices for dApp '${dappId}'`);
+    }
+    // Array.isArray narrows to `any[]`; re-assert the concrete type.
+    const dynamicAmountIndices = config.dynamicAmountIndices;
+    // Amount byte offsets in depositCalldata: 4 (selector) + paramIndex * 32.
+    const amountIndices = dynamicAmountIndices.map((paramIndex)=>{
+        if (!Number.isInteger(paramIndex) || paramIndex < 0 || paramIndex >= fragment.inputs.length) {
+            throw createValidationFailedError$1('dynamicAmountIndices', paramIndex, `Index out of range for '${config.function}' (${String(fragment.inputs.length)} params)`);
+        }
+        return BigInt(4 + paramIndex * 32);
+    });
+    // 2. Handler layer.
+    const handlerCalldata = defaultAbiCoder.encode([
+        'address',
+        'address',
+        'bytes',
+        'uint256[]'
+    ], [
+        depositContract,
+        approvalTarget,
+        depositCalldata,
+        amountIndices
+    ]);
+    // 3. Executor ABI tuple. No handler selector travels on the wire — the
+    //    executor applies a fixed selector internally.
+    const executorTuple = defaultAbiCoder.encode([
+        'uint8',
+        'bytes32',
+        'address',
+        'bytes'
+    ], [
+        GENERIC_EXECUTOR_HOOK_DATA_VERSION,
+        options.recoveryAddress,
+        getAddress(handler),
+        handlerCalldata
+    ]);
+    // 4. Prepend the circle-generic-executor magic header; this is the final
+    //    bare GE blob the executor consumes.
+    const hookData = prependGenericExecutorHeader(executorTuple);
+    return {
+        hookData,
+        handlerCalldata,
+        depositCalldata,
+        amountIndices,
+        depositContract,
+        approvalTarget
+    };
+}
+/**
+ * Config key of the built-in Circle Gateway deposit dApp. Its deposit contract
+ * is the destination chain's GatewayWallet, resolved from `destinationChain`
+ * (not a hardcoded address), so this is the only dApp whose deployment may omit
+ * `depositContract`.
+ */ const GATEWAY_DEPOSIT_DAPP_ID = 'gateway_deposit';
+/**
+ * Built-in dApp registry. Adding a new `depositFor`-style dApp is a config entry
+ * here (or via {@link BuildDepositForGenericExecutorPayloadParams.config}).
+ *
+ * @remarks
+ * Only dApps with confirmed deployment addresses and active callers are included.
+ * The built-in `gateway_deposit` entry omits `depositContract` — it is resolved
+ * from the destination chain's GatewayWallet (`@core/chains`) rather than
+ * duplicated here. Pass a custom registry via `config` for unlisted dApps.
+ */ const DAPP_CONFIG = {
+    // Circle Gateway: depositFor(address token, address depositor, uint256 value)
+    [GATEWAY_DEPOSIT_DAPP_ID]: {
+        function: 'depositFor(address,address,uint256)',
+        dynamicAmountIndices: [
+            2
+        ],
+        deployments: [
+            // Arc Testnet (CCTP domain 26). The deposit contract is the chain's
+            // GatewayWallet, resolved from `destinationChain` (@core/chains) rather
+            // than duplicated here.
+            {
+                domainId: 26
+            }
+        ]
+    }
+};
+/**
+ * Resolve the destination CCTP domain for an encode request.
+ *
+ * Prefers {@link BuildDepositForGenericExecutorPayloadParams.destinationChain}
+ * (`chain.cctp.domain`) — the chain is the (network, domain) key. Falls back to
+ * an explicit `domainId`. When both are supplied they must agree.
+ *
+ * @param options - The encode request.
+ * @returns The destination CCTP domain.
+ * @throws {KitError} If no domain is available, or `domainId` disagrees with
+ *   `destinationChain` (INPUT_VALIDATION_FAILED).
+ * @internal
+ */ function resolveDomainId(options) {
+    const chain = options.destinationChain;
+    if (chain !== undefined) {
+        const chainDomain = chain.cctp?.domain;
+        if (chainDomain !== undefined) {
+            if (options.domainId !== undefined && options.domainId !== chainDomain) {
+                throw createValidationFailedError$1('domainId', options.domainId, `does not match destinationChain '${chain.name}' CCTP domain ` + String(chainDomain));
+            }
+            return chainDomain;
+        }
+    }
+    if (options.domainId !== undefined) {
+        return options.domainId;
+    }
+    throw createValidationFailedError$1('domainId', options.domainId, "Provide 'domainId', or a 'destinationChain' with a CCTP domain");
+}
+/**
+ * Resolve the deposit contract the handler calls.
+ *
+ * Uses the deployment's own `depositContract` when present. Only the built-in
+ * {@link GATEWAY_DEPOSIT_DAPP_ID} may omit it: its deposit contract is the
+ * destination chain's Gateway v1 wallet, resolved from
+ * {@link BuildDepositForGenericExecutorPayloadParams.destinationChain} so the
+ * address is owned once in `@core/chains`. Any other dApp that omits
+ * `depositContract` is a config error and fails here rather than silently
+ * targeting the GatewayWallet.
+ *
+ * @param deployment - The resolved dApp deployment.
+ * @param options - The encode request.
+ * @param dappId - The dApp key, checked against {@link GATEWAY_DEPOSIT_DAPP_ID}.
+ * @returns The deposit contract address (unvalidated; the caller checks it).
+ * @throws {KitError} If a non-`gateway_deposit` deployment omits
+ *   `depositContract`, or if `gateway_deposit` has no Gateway v1
+ *   `destinationChain` to resolve one (INPUT_VALIDATION_FAILED).
+ * @internal
+ */ function resolveDepositContract(deployment, options, dappId) {
+    if (deployment.depositContract !== undefined) {
+        return deployment.depositContract;
+    }
+    // Only gateway_deposit may omit its address (it targets the chain's
+    // GatewayWallet). Any other addressless deployment is a config mistake and
+    // must fail rather than silently resolve to the GatewayWallet.
+    if (dappId !== GATEWAY_DEPOSIT_DAPP_ID) {
+        throw createValidationFailedError$1('depositContract', dappId, `dApp '${dappId}' must declare a 'depositContract'; only the built-in ` + `'${GATEWAY_DEPOSIT_DAPP_ID}' resolves its address from the ` + "destination chain's GatewayWallet");
+    }
+    const chain = options.destinationChain;
+    if (chain === undefined || !isGatewayV1Supported(chain)) {
+        throw createValidationFailedError$1('depositContract', dappId, `'${GATEWAY_DEPOSIT_DAPP_ID}' needs a 'destinationChain' with Gateway v1 ` + 'support to resolve its GatewayWallet, or an explicit deployment address');
+    }
+    return chain.gateway.contracts.v1.wallet;
+}
+/**
+ * Resolve the `DepositForHandler` address for an encode request.
+ *
+ * An explicit `options.handler` always wins. Otherwise the handler is resolved
+ * from {@link BuildDepositForGenericExecutorPayloadParams.destinationChain}
+ * (`chain.gateway.contracts.v1.depositForHandler`). The chain is the (network,
+ * domain) key, so a CCTP domain shared across a chain's testnet and mainnet
+ * cannot resolve the wrong network's handler; a missing chain or an unregistered
+ * handler throws rather than guessing.
+ *
+ * @param options - The encode request.
+ * @param domainId - The resolved destination domain, reported in the error.
+ * @returns The resolved handler address (unvalidated; the caller checks it).
+ * @throws {KitError} If `handler` is omitted and cannot be resolved
+ *   (INPUT_VALIDATION_FAILED).
+ * @internal
+ */ function resolveDepositForHandler(options, domainId) {
+    if (options.handler !== undefined) {
+        return options.handler;
+    }
+    const chain = options.destinationChain;
+    if (chain === undefined) {
+        throw createValidationFailedError$1('handler', domainId, "No 'handler' supplied; pass 'handler' explicitly, or a " + "'destinationChain' whose Gateway config registers a DepositForHandler");
+    }
+    const registered = isGatewayV1Supported(chain) ? chain.gateway.contracts.v1.depositForHandler : undefined;
+    if (registered === undefined) {
+        throw createValidationFailedError$1('handler', domainId, `No DepositForHandler registered for domain ${String(domainId)} on ` + `chain '${chain.name}'; pass 'handler' explicitly`);
+    }
+    return registered;
+}
+/**
+ * Validate and checksum an EVM address, throwing a consistent validation error.
+ */ function assertAddress(address, field) {
+    if (!isAddress(address)) {
+        throw createValidationFailedError$1(field, address, 'Expected a valid EVM address');
+    }
+    return getAddress(address);
+}
 
 /**
  * Configuration for {@link retryAsync}.
@@ -10235,7 +10810,7 @@ function resolveOptions(options) {
  * allowlisted {@link ClientLogPayload} fields (and the allowlisted
  * sub-fields of `errorDetails` / `clientContext`) are copied across.
  * A regressing upstream mapper — or a plain-JS caller that bypasses the
- * type — therefore cannot exfiltrate stray properties (secrets, PII,
+ * type — therefore cannot exfiltrate stray properties (secrets,
  * raw error stacks) through the analytics channel. Optional fields are
  * only included when present so the serialised shape matches the
  * server's strict schema.
@@ -10258,6 +10833,9 @@ function resolveOptions(options) {
     if (payload.destinationChain !== undefined) safe['destinationChain'] = payload.destinationChain;
     if (payload.tokenIn !== undefined) safe['tokenIn'] = payload.tokenIn;
     if (payload.tokenOut !== undefined) safe['tokenOut'] = payload.tokenOut;
+    if (payload.amountIn !== undefined) safe['amountIn'] = payload.amountIn;
+    if (payload.durationMs !== undefined) safe['durationMs'] = payload.durationMs;
+    if (payload.sourceAddress !== undefined) safe['sourceAddress'] = payload.sourceAddress;
     if (payload.txHash !== undefined) safe['txHash'] = payload.txHash;
     if (payload.correlationId !== undefined) safe['correlationId'] = payload.correlationId;
     if (payload.errorDetails !== undefined) {
@@ -10454,14 +11032,28 @@ function resolveOptions(options) {
 }
 
 /**
- * Soft signal for the case where building or emitting a telemetry payload
- * threw — for example, a buggy `TelemetryContextResolver`, a regression in
+ * Emit a stable console warning when building or emitting a telemetry payload
+ * throws — for example, a buggy `TelemetryContextResolver`, a regression in
  * `extractErrorDetails`, or a synchronous failure inside `emitAnalyticsLog`
- * before it could swallow the error itself. Logged with a stable prefix so
- * consumers can grep for it. We deliberately do not re-throw: the caller's
- * original operation error must always win.
+ * before it could swallow the error itself. Uses a stable prefix so the
+ * drop is discoverable via grep. Never re-throws: the caller's original
+ * operation error must always win.
  *
  * @internal
+ *
+ * @param eventType - The telemetry event type that was being emitted.
+ * @param cause - The error or value that caused the drop.
+ *
+ * @example
+ * ```typescript
+ * import { warnTelemetryDrop } from '@core/utils'
+ *
+ * try {
+ *   void emitAnalyticsLog(payload)
+ * } catch (err) {
+ *   warnTelemetryDrop('my_event', err)
+ * }
+ * ```
  */ function warnTelemetryDrop(eventType, cause) {
     try {
         // Pass `cause` as the second console.warn argument rather than
@@ -10501,6 +11093,9 @@ function resolveOptions(options) {
         ...context?.tokenOut != null && {
             tokenOut: context.tokenOut
         },
+        ...context?.amountIn != null && {
+            amountIn: context.amountIn
+        },
         ...context?.txHash != null && {
             txHash: context.txHash
         },
@@ -10602,7 +11197,7 @@ function resolveOptions(options) {
     const stepEntry = stepEventMap.find(([name])=>name === failedStep?.name);
     // `failedStep.errorMessage` is intentionally **not** copied into the payload.
     // Provider messages are unbounded and frequently contain operator data
-    // (addresses, signatures, partial intent payloads, raw RPC responses). The
+    // (signatures, partial intent payloads, raw RPC responses). The
     // step name plus the surrounding context fields already identify *which*
     // phase failed; the *why* is left to the corresponding step-level logs that
     // the provider emits separately. The thrown-error path (`extractErrorDetails`
@@ -10619,7 +11214,7 @@ function resolveOptions(options) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.14.0";
+var version$3 = "1.14.1";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -12313,7 +12908,7 @@ var TransferSpeed;
  * })
  * ```
  */ function createLogger(options, stream) {
-    const { redact, ...pinoOptions } = {};
+    const { redact, ...pinoOptions } = options ?? {};
     // Build redaction config
     const redactConfig = buildRedactConfig(redact);
     // Build final pino options, only include redact if defined
@@ -13667,6 +14262,8 @@ const CUSTOM_BURN_GAS_ESTIMATE_EVM = 201_525n // p99 and max are same here: 201_
 ;
 const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_839n) / 2 = 237_401n
 ;
+/** Gas units consumed by `depositForBurnWithHookAndFees` on an EVM chain (prepaid-FORWARD path). */ const DEPOSIT_FOR_BURN_WITH_FEES_GAS_ESTIMATE_EVM = 626_584n // avg of the last 10 txns
+;
 // Gas FLOORS, not ceilings — kept separate from the fee-estimate averages
 // above. `executePreparedChainRequest` submits
 // max(estimate * buffer, floor), so a chain whose real cost exceeds the floor
@@ -15948,7 +16545,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$2 = "1.12.0";
+var version$2 = "1.13.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -16654,6 +17251,9 @@ var pkg$2 = {
     }
 }
 
+const logger = createLogger({
+    name: 'provider-cctp-v2'
+});
 function isPlainObject(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         return false;
@@ -17016,6 +17616,116 @@ function assertCCTPV2Config(config) {
         return estimateResult;
     }
     /**
+   * Estimate source-chain gas for a prepaid-FORWARD deposit burn via
+   * `TokenMessengerWithFees.depositForBurnWithHookAndFees`.
+   *
+   * Builds a size-correct GenericExecutor hookData placeholder — using the
+   * pre-validated `contracts.executor` and `contracts.depositForHandler` — so
+   * the EVM calldata length matches production. Attempts a live
+   * `eth_estimateGas` via the adapter's `cctp.v2.depositForBurnWithFees`
+   * action and falls back to the static
+   * {@link DEPOSIT_FOR_BURN_WITH_FEES_GAS_ESTIMATE_EVM} constant when the live
+   * RPC call fails.
+   *
+   * Gateway eligibility is the caller's responsibility: validate the
+   * destination chain with `resolveGatewayExecutorContracts` (UBK) before
+   * calling this method.
+   *
+   * @param params - Estimation parameters including adapter, chains, amount,
+   *   the signed fee quote returned by the Quote API, and the pre-validated
+   *   Gateway executor contracts resolved by the caller.
+   * @returns Promise resolving to the estimated (or fallback) gas cost.
+   * @throws KitError `SERVICE_INTERNAL_ERROR` (FATAL) if `dstChain`'s
+   *   `usdcAddress` is `null`.
+   *
+   * @example
+   * ```typescript
+   * const contracts = resolveGatewayExecutorContracts(srcChain, dstChain)
+   * const gasEstimate = await CCTPV2BridgingProvider.estimateDepositBurn({
+   *   adapter: evmAdapter,
+   *   srcChain: Ethereum,
+   *   dstChain: ArcTestnet,
+   *   amountMinorUnits: 100_000_000n,
+   *   refundAddress: '0xUserWallet',
+   *   signedQuote: quote.signedQuote,
+   *   feeToken: quote.feeToken,
+   *   feeTotalAmount: BigInt(quote.feeTotalAmount),
+   *   resolvedContext,
+   *   contracts,
+   * })
+   * ```
+   */ static async estimateDepositBurn(params) {
+        const { adapter, srcChain, dstChain, amountMinorUnits, refundAddress, signedQuote, feeToken, feeTotalAmount, resolvedContext, contracts } = params;
+        const { executor, depositForHandler } = contracts;
+        if (dstChain.usdcAddress === null) {
+            throw new KitError({
+                ...ServiceError.INTERNAL_ERROR,
+                recoverability: 'FATAL',
+                message: `Destination chain ${dstChain.name} has no USDC address configured`
+            });
+        }
+        // Build a size-correct hookData for eth_estimateGas. The EVM uses calldata
+        // length to compute gas, so the byte layout must match production even
+        // though field values are not final.
+        const { hookData: geBlob } = buildDepositForGenericExecutorPayload({
+            dappId: 'gateway_deposit',
+            destinationChain: dstChain,
+            handler: depositForHandler,
+            params: [
+                dstChain.usdcAddress,
+                refundAddress,
+                0n
+            ],
+            recoveryAddress: padAddressToBytes32(refundAddress),
+            // Override deployments only — spread the canonical function signature
+            // and amount indices from DAPP_CONFIG so they stay in sync.
+            config: {
+                gateway_deposit: {
+                    ...DAPP_CONFIG.gateway_deposit,
+                    deployments: [
+                        {
+                            domainId: dstChain.cctp.domain
+                        }
+                    ]
+                }
+            }
+        });
+        const hookData = buildForwardingHookDataWithPayload(GENERIC_EXECUTOR_HOOK_DATA_VERSION, geBlob);
+        // Coupling guard: the prepaid FORWARD path always requests a FORWARD fee
+        // item, so the hookData must carry a `cctp-forward` frame — matches the
+        // assertion in `prepareDepositForBurn`.
+        assertForwardHookData(hookData);
+        try {
+            const prepared = await adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
+                fromChain: srcChain,
+                toChain: dstChain,
+                amount: amountMinorUnits,
+                mintRecipient: executor,
+                destinationCaller: executor,
+                claim: {
+                    signedQuote,
+                    refundAddress
+                },
+                feeToken,
+                feeTotalAmount,
+                hookData
+            }, resolvedContext);
+            return await prepared.estimate(undefined);
+        } catch (err) {
+            logger.debug('estimateDepositBurn: live eth_estimateGas failed, using static fallback', {
+                err,
+                chain: srcChain.name
+            });
+            try {
+                return await adapter.calculateTransactionFee(DEPOSIT_FOR_BURN_WITH_FEES_GAS_ESTIMATE_EVM, undefined, srcChain);
+            } catch (feeErr) {
+                throw createRpcEndpointError(srcChain.name, {
+                    rawError: feeErr
+                });
+            }
+        }
+    }
+    /**
    * Extracts OperationContext from bridge parameters for a given wallet context.
    *
    * This method extracts the chain and address information from the wallet context
@@ -17642,6 +18352,99 @@ function assertCCTPV2Config(config) {
         return await source.adapter.prepareAction('cctp.v2.depositForBurn', actionParams, resolvedContext);
     }
     /**
+   * Prepare the source-chain `depositForBurnWithHookAndFees` call for the
+   * GenericExecutor FORWARD path.
+   *
+   * Exposed as a public static method so the UBK fast-deposit flow can invoke
+   * it directly without holding a provider instance. The byte layout mirrors
+   * {@link CCTPV2BridgingProvider.estimateDepositBurn} so gas estimates and the
+   * executed call agree.
+   *
+   * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+   * @param params - Burn parameters including adapter, chains, deposit action,
+   *   amount, signer address, signed fee quote, and pre-resolved adapter context.
+   * @returns The prepared `depositForBurnWithHookAndFees` burn transaction.
+   * @throws {KitError} `UNSUPPORTED_ROUTE` when `dstChain` lacks a
+   *   GenericExecutor or DepositForHandler, or the `deposit.dappId` is unknown.
+   *
+   * @example
+   * ```typescript
+   * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+   * import { Ethereum, ArcTestnet } from '@core/chains'
+   *
+   * const prepared = await CCTPV2BridgingProvider.prepareDepositForBurn({
+   *   adapter,
+   *   srcChain: Ethereum,
+   *   dstChain: ArcTestnet,
+   *   deposit: { dappId: 'gateway_deposit', params: [usdcAddress, recipient, 0n] },
+   *   amountMinorUnits: 100_000_000n,
+   *   refundAddress: '0xSender...',
+   *   signedQuote: quote.signedQuote,
+   *   feeToken: quote.feeToken,
+   *   feeTotalAmount: BigInt(quote.feeTotalAmount),
+   *   resolvedContext,
+   * })
+   * const txHash = await prepared.execute()
+   * ```
+   */ static async prepareDepositForBurn(params) {
+        const { adapter, srcChain, dstChain, deposit, amountMinorUnits, refundAddress, signedQuote, feeToken, feeTotalAmount, resolvedContext } = params;
+        // Resolve executor and depositForHandler from the destination chain's
+        // gateway config. Throw an unsupported-route error if either is absent.
+        const executor = dstChain.gateway?.contracts?.v1?.genericExecutor;
+        const depositForHandler = dstChain.gateway?.contracts?.v1?.depositForHandler;
+        if (!executor || !depositForHandler) {
+            throw createUnsupportedRouteError(srcChain.name, dstChain.name);
+        }
+        // Resolve the canonical dApp config (function signature + amount indices)
+        // for THIS deposit's `dappId`. Reject an unknown `dappId` rather than
+        // encoding the wrong ABI selector, which would burn on the source but
+        // revert in the executor call on the destination.
+        const dappConfig = DAPP_CONFIG[deposit.dappId];
+        if (dappConfig === undefined) {
+            throw createUnsupportedRouteError(srcChain.name, dstChain.name);
+        }
+        // Build the bare GenericExecutor payload, then wrap it in the `cctp-forward`
+        // frame required by the prepaid-FORWARD wrapper.
+        const { hookData: geBlob } = buildDepositForGenericExecutorPayload({
+            dappId: deposit.dappId,
+            destinationChain: dstChain,
+            handler: depositForHandler,
+            params: deposit.params,
+            recoveryAddress: padAddressToBytes32(refundAddress),
+            config: {
+                [deposit.dappId]: {
+                    ...dappConfig,
+                    deployments: [
+                        {
+                            domainId: dstChain.cctp.domain
+                        }
+                    ]
+                }
+            }
+        });
+        const hookData = buildForwardingHookDataWithPayload(GENERIC_EXECUTOR_HOOK_DATA_VERSION, geBlob);
+        // 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`.
+        assertForwardHookData(hookData);
+        // Source-chain burn: `mintRecipient` AND `destinationCaller` are both the
+        // executor; fees are prepaid against the signed quote.
+        return adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
+            fromChain: srcChain,
+            toChain: dstChain,
+            amount: amountMinorUnits,
+            mintRecipient: executor,
+            destinationCaller: executor,
+            hookData,
+            claim: {
+                signedQuote,
+                refundAddress
+            },
+            feeToken,
+            feeTotalAmount
+        }, resolvedContext);
+    }
+    /**
    * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
    *
    * Build the source-chain `depositForBurnWithHookAndFees` call. Fees are
@@ -17906,9 +18709,13 @@ function assertCCTPV2Config(config) {
 
 /**
  * Base URL for Circle's Quote API (hosted in Iris) on mainnet/production.
+ *
+ * @internal
  */ const IRIS_API_BASE_URL = 'https://iris-api.circle.com';
 /**
  * Base URL for Circle's Quote API (hosted in Iris) on testnet/sandbox.
+ *
+ * @internal
  */ const IRIS_API_SANDBOX_BASE_URL = 'https://iris-api-sandbox.circle.com';
 /**
  * Native fee-token sentinel (the zero address).
@@ -17916,19 +18723,25 @@ function assertCCTPV2Config(config) {
  * When `feeToken` is the zero address the quote prices fees in the source
  * chain's native gas token (paid as `msg.value` on-chain). Pass a USDC token
  * address instead to denominate fees in USDC.
+ *
+ * @internal
  */ const NATIVE_FEE_TOKEN = '0x0000000000000000000000000000000000000000';
 /**
  * API path prefix for the CCTP v2 USDC burn quote endpoint.
  *
  * The full path is `${QUOTE_BURN_USDC_PATH}/{sourceDomain}/{destinationDomain}`;
  * `usdc` is a fixed literal, not a token parameter.
+ *
+ * @internal
  */ const QUOTE_BURN_USDC_PATH = '/v2/quote/burn/usdc';
 /**
  * API path prefix for the CCTP v2 USDC quote validate endpoint.
  *
  * The full path is `${QUOTE_VALIDATE_USDC_PATH}/{sourceDomain}`; accepts a
- * `POST { abiSignature, args }` body and returns whether the signed quote is
- * currently claimable together with its authoritative expiry status.
+ * `POST { abiSignature, args }` body and returns `claimable`, `failedChecks`,
+ * and the decoded `expiry`, `feeToken`, and `feeTotalAmount`.
+ *
+ * @internal
  */ const QUOTE_VALIDATE_USDC_PATH = '/v2/quote/validate/usdc';
 /**
  * Default polling configuration for Quote API calls.
@@ -17945,13 +18758,19 @@ function assertCCTPV2Config(config) {
  * `Content-Type: application/json` and adds `User-Agent` in Node. Browser
  * requests omit a user-agent header to avoid a CORS preflight, so duplicating
  * either header here would be dead configuration.
+ *
+ * @internal
  */ const FEE_QUOTE_DEFAULT_CONFIG = {
     timeout: 15_000,
     maxRetries: 1,
     retryDelay: 200
 };
 
-/** Decimal string in token minor units, constrained to be strictly positive. */ const positiveAmountSchema = z.string().regex(/^\d+$/, 'must be a non-negative integer string')// Re-check the digit shape here: zod still runs this refinement when the
+/**
+ * Decimal string in token minor units, constrained to be strictly positive.
+ *
+ * @internal
+ */ const positiveAmountSchema = z.string().regex(/^\d+$/, 'must be a non-negative integer string')// Re-check the digit shape here: zod still runs this refinement when the
 // regex check above fails ("dirty"), so guard BigInt() against throwing on a
 // non-numeric value before comparing.
 .refine((value)=>/^\d+$/.test(value) && BigInt(value) > 0n, 'must be greater than zero');
@@ -17986,11 +18805,19 @@ const forwardRequestSchema = z.object({
 const preFinalityRequestSchema = z.object({
     type: z.literal('PRE_FINALITY')
 }).strict();
-/** A single quote request item (`FORWARD` or `PRE_FINALITY`). */ const feeQuoteRequestSchema = z.discriminatedUnion('type', [
+/**
+ * A single quote request item (`FORWARD` or `PRE_FINALITY`).
+ *
+ * @internal
+ */ const feeQuoteRequestSchema = z.discriminatedUnion('type', [
     forwardRequestSchema,
     preFinalityRequestSchema
 ]);
-/** A non-empty list of quote request items with unique types. */ const feeQuoteRequestsSchema = z.array(feeQuoteRequestSchema).min(1, 'at least one request item is required').refine((items)=>new Set(items.map((item)=>item.type)).size === items.length, 'request item types must be unique');
+/**
+ * A non-empty list of quote request items with unique types.
+ *
+ * @internal
+ */ const feeQuoteRequestsSchema = z.array(feeQuoteRequestSchema).min(1, 'at least one request item is required').refine((items)=>new Set(items.map((item)=>item.type)).size === items.length, 'request item types must be unique');
 /**
  * A structured `Partial<ApiPollingConfig>` polling override.
  *
@@ -18018,6 +18845,8 @@ const preFinalityRequestSchema = z.object({
  * it `undefined`, which is falsy and silently selects the production base URL.
  * (`buildFeeQuoteUrl` independently re-validates the domains for standalone
  * callers.)
+ *
+ * @internal
  */ const fetchFeeQuoteInputSchema = z.object({
     sourceDomain: z.number().int().nonnegative(),
     destinationDomain: z.number().int().nonnegative(),
@@ -18053,7 +18882,11 @@ const metadataSchema = z.object({
         blockEstimatedAt: z.number().int().nonnegative().optional()
     }).passthrough()
 ]);
-/** Schema for a signed fee quote returned by the Quote API. */ const signedFeeQuoteSchema = z.object({
+/**
+ * Schema for a signed fee quote returned by the Quote API.
+ *
+ * @internal
+ */ const signedFeeQuoteSchema = z.object({
     // The runtime YAML spec maps signedQuote to a looser `hex` (which allows
     // an empty `0x`); we keep the stricter non-empty form. Do not relax
     // without a reason.
@@ -18082,10 +18915,16 @@ const metadataSchema = z.object({
  *   console.log(payload.feeTotalAmount)
  * }
  * ```
+ *
+ * @internal
  */ function isSignedFeeQuote(value) {
     return signedFeeQuoteSchema.safeParse(value).success;
 }
-/** Validate input to {@link validateQuote}. */ const validateQuoteInputSchema = z.object({
+/**
+ * Validates input to {@link validateQuote}.
+ *
+ * @internal
+ */ const validateQuoteInputSchema = z.object({
     sourceDomain: z.number().int().nonnegative(),
     abiSignature: z.string().min(1),
     args: z.array(z.union([
@@ -18120,11 +18959,13 @@ const validateQuoteItemSchema = z.object({
     computedArgsHash: bytes32Schema.optional()
 }).passthrough();
 /**
- * Schema for a response from the Quote API validation endpoint.
+ * Schema for a validate-quote result returned by the Iris `/validate/usdc/:sourceDomain` endpoint.
  *
  * The endpoint takes the source domain as a URL path parameter and does not
  * return it in the response body, so `sourceDomain` is intentionally not part
  * of this schema.
+ *
+ * @internal
  */ const validateQuoteResultSchema = z.object({
     signedQuote: nonEmptyHexSchema,
     expiry: quoteExpiryStatusSchema,
@@ -18138,20 +18979,22 @@ const validateQuoteItemSchema = z.object({
     items: z.array(validateQuoteItemSchema)
 }).passthrough();
 /**
- * Validate a Quote API validation response.
+ * Validate that an unknown value is a validate-quote result.
  *
- * @param value - The unknown response value.
- * @returns `true` when the value has the expected validation response shape.
+ * @param value - The unknown value to validate.
+ * @returns `true` when the value matches the validate-quote response shape.
  *
  * @example
  * ```typescript
  * import { isValidateQuoteResult } from '@circle-fin/provider-fee-v1'
  *
- * declare const response: unknown
- * if (isValidateQuoteResult(response)) {
- *   console.log(response.claimable)
+ * declare const payload: unknown
+ * if (isValidateQuoteResult(payload)) {
+ *   console.log(payload.claimable, payload.failedChecks)
  * }
  * ```
+ *
+ * @internal
  */ function isValidateQuoteResult(value) {
     return validateQuoteResultSchema.safeParse(value).success;
 }
@@ -18200,6 +19043,8 @@ const validateQuoteItemSchema = z.object({
  * })
  * // => 'https://iris-api.circle.com/v2/quote/burn/usdc/3/26'
  * ```
+ *
+ * @internal
  */ function buildFeeQuoteUrl(params) {
     const { sourceDomain, destinationDomain, isTestnet, baseUrl } = params;
     assertDomain(sourceDomain, 'sourceDomain');
@@ -18326,6 +19171,8 @@ const OPERATION$1 = 'getFeeQuote';
  * })
  * console.log(quote.feeTotalAmount, quote.expiry)
  * ```
+ *
+ * @internal
  */ async function fetchFeeQuote(params) {
     const { sourceDomain, destinationDomain, amount, requests, feeToken, isTestnet, baseUrl, config } = params;
     const parsed = fetchFeeQuoteInputSchema.safeParse({
@@ -18400,7 +19247,13 @@ const OPERATION$1 = 'getFeeQuote';
 const SERVICE = 'Quote API';
 const OPERATION = 'validateQuote';
 /**
- * Validate a signed quote against a complete source-chain contract call.
+ * Validate a signed fee quote against a full on-chain call via Circle's Iris
+ * `/v2/quote/validate/usdc/:sourceDomain` endpoint.
+ *
+ * POSTs the ABI function signature and the encoded call arguments to Iris,
+ * which verifies the signature, checks expiry, confirms the argsHash committed
+ * in the quote matches the submitted args, and returns `claimable` plus the
+ * decoded `expiry`, `feeToken`, and `feeTotalAmount`.
  *
  * @param params - The source domain, ABI signature, call arguments, and environment.
  * @returns The claimability, binding checks, and authoritative expiry status.
@@ -18427,7 +19280,12 @@ const OPERATION = 'validateQuote';
  *   isTestnet: false,
  * })
  * console.log(result.claimable, result.expiry.secondsRemaining)
+ * if (!result.claimable) {
+ *   console.error('Quote rejected:', result.failedChecks)
+ * }
  * ```
+ *
+ * @internal
  */ async function validateQuote(params) {
     const parsed = validateQuoteInputSchema.safeParse(params);
     if (!parsed.success) {
@@ -18490,9 +19348,14 @@ function isQuoteNearEstimatedExpiry(quote) {
 }
 function assertSourceFeeRoute(params) {
     const { source, destination, config } = params;
+    // Keep these checks explicit so a successful assertion guarantees the CCTP
+    // v2 narrowing; hasSourceFeeSupport returns a plain boolean.
     if (source.chain.type !== 'evm' || destination.chain.type !== 'evm' || !isCCTPV2Supported(source.chain) || !isCCTPV2Supported(destination.chain)) {
         throw createUnsupportedRouteError(source.chain.name, destination.chain.name);
     }
+    if (!hasSourceFeeSupport(source.chain)) {
+        throw createValidationFailedError$1('config.feePayment', 'source', `Source-paid ("receive-exact") fees are not supported from ${source.chain.name}. ` + 'Use the default destination-paid fees for this source chain');
+    }
     const useForwarder = destination.useForwarder;
     if (useForwarder !== true) {
         throw createValidationFailedError$1('to.useForwarder', useForwarder, "feePayment: 'source' requires useForwarder: true");
@@ -19580,7 +20443,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.6.0";
+var version$1 = "1.6.1";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -21602,7 +22465,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.6.0";
+var version = "1.6.1";
 var pkg = {
 	name: name,
 	version: version};