@circle-fin/app-kit 1.12.1 → 1.14.0

package/estimateBridge.mjs

@@ -30,9 +30,9 @@ 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 } from '@ethersproject/bytes';
-import '@ethersproject/abi';
-import { getAddress } from '@ethersproject/address';
+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';
 import 'bn.js';
@@ -785,6 +785,32 @@ class KitError extends Error {
         type: 'ONCHAIN'
     }
 };
+/**
+ * Standardized error definitions for LIQUIDITY type errors.
+ *
+ * LIQUIDITY errors indicate that an upstream provider or AMM cannot fulfill
+ * the requested swap size due to insufficient liquidity at the moment.
+ * These are typically transient — retrying later or reducing the amount
+ * may succeed once liquidity replenishes.
+ *
+ * @example
+ * ```typescript
+ * import { LiquidityError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...LiquidityError.INSUFFICIENT_LIQUIDITY,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'Insufficient liquidity for the requested swap',
+ *   cause: { trace: { token: '0xA0b86991...' } }
+ * })
+ * ```
+ */ const LiquidityError = {
+    /** Upstream provider has a route but cannot fulfill the requested size right now */ INSUFFICIENT_LIQUIDITY: {
+        code: 6001,
+        name: 'LIQUIDITY_INSUFFICIENT',
+        type: 'LIQUIDITY'
+    }
+};
 /**
  * Standardized error definitions for RPC type errors.
  *
@@ -832,7 +858,10 @@ class KitError extends Error {
         type: 'NETWORK'
     },
     /** Network request timeout */ TIMEOUT: {
-        code: 3002},
+        code: 3002,
+        name: 'NETWORK_TIMEOUT',
+        type: 'NETWORK'
+    },
     /** Circle relayer failed to process the forwarding/mint transaction */ RELAYER_FORWARD_FAILED: {
         code: 3003,
         name: 'NETWORK_RELAYER_FORWARD_FAILED',
@@ -843,6 +872,58 @@ class KitError extends Error {
         name: 'NETWORK_RELAYER_PENDING',
         type: 'NETWORK'
     }};
+/**
+ * Standardized error definitions for RATE_LIMIT type errors.
+ *
+ * RATE_LIMIT errors indicate API throttling, request frequency limits errors.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimitError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...RateLimitError.RATE_LIMIT_EXCEEDED,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'Rate limit exceeded, please retry later',
+ *   cause: { trace: { error: '429 Too Many Requests' } }
+ * })
+ * ```
+ */ const RateLimitError = {
+    /** Rate limit exceeded */ RATE_LIMIT_EXCEEDED: {
+        code: 7001,
+        name: 'RATE_LIMIT_EXCEEDED',
+        type: 'RATE_LIMIT'
+    }
+};
+/**
+ * Standardized error definitions for SERVICE type errors.
+ *
+ * SERVICE errors indicate internal service failures, HTTP 5xx errors,
+ * or backend processing issues that are retryable.
+ *
+ * @example
+ * ```typescript
+ * import { ServiceError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...ServiceError.INTERNAL_ERROR,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'Service encountered an internal error (500)',
+ *   cause: { trace: { statusCode: 500 } }
+ * })
+ * ```
+ */ const ServiceError = {
+    /** Internal server error (HTTP 5xx) */ INTERNAL_ERROR: {
+        code: 8001,
+        name: 'SERVICE_INTERNAL_ERROR',
+        type: 'SERVICE'
+    },
+    /** Unknown or unclassified error that cannot be categorized */ UNKNOWN_ERROR: {
+        code: 8002,
+        name: 'SERVICE_UNKNOWN_ERROR',
+        type: 'SERVICE'
+    }
+};
 
 /**
  * Creates error for network type mismatch between source and destination.
@@ -2214,6 +2295,32 @@ class KitError extends Error {
     }
     return false;
 }
+/**
+ * Type guard to check if error is KitError with RATE_LIMIT type.
+ *
+ * RATE_LIMIT errors indicate API throttling or request frequency limits.
+ * These errors are typically RETRYABLE after a delay.
+ *
+ * @param error - Unknown error to check
+ * @returns True if error is KitError with RATE_LIMIT type
+ *
+ * @example
+ * ```typescript
+ * import { isRateLimitError } from '@core/errors'
+ *
+ * try {
+ *   await kit.bridge(params)
+ * } catch (error) {
+ *   if (isRateLimitError(error)) {
+ *     console.log('Rate limited, retrying in 60s')
+ *     await sleep(60000)
+ *     retry()
+ *   }
+ * }
+ * ```
+ */ function isRateLimitError(error) {
+    return isKitError(error) && error.type === ERROR_TYPES.RATE_LIMIT;
+}
 /**
  * Safely extracts error message from any error type.
  *
@@ -2463,6 +2570,478 @@ class KitError extends Error {
     return chain;
 }
 
+/**
+ * Proxy-specific structured error codes carried in `responseBody.code`.
+ *
+ * These are NOT HTTP status codes — they are application-level identifiers
+ * the stablecoin-kits-proxy emits inside JSON error bodies so the kit can
+ * distinguish conditions that share the same HTTP status (e.g. a 400 caused
+ * by an out-of-range swap amount vs. a generic validation failure).
+ *
+ * @internal
+ */ const ProxyErrorCode = {
+    /** Swap amount outside the upstream provider's accepted bounds (HTTP 400) */ INVALID_SWAP_AMOUNT: 331017,
+    /** Upstream liquidity insufficient for the requested size (HTTP 503) */ LOW_LIQUIDITY: 331018
+};
+/**
+ * Parses raw HTTP API errors into structured KitError instances.
+ *
+ * This function uses pattern matching to identify common HTTP error types
+ * and converts them into standardized KitError format. It handles errors
+ * from fetch, HTTP status codes, timeouts, and network failures.
+ *
+ * The parser recognizes the following error patterns:
+ * - Client errors (4xx) - validation, authentication, not found
+ * - Server errors (5xx) - service unavailability
+ * - Timeout errors
+ * - Network connectivity errors
+ * - Rate limiting
+ *
+ * Unrecognized errors are treated as fatal `SERVICE` errors, as their
+ * cause and recoverability are unknown.
+ *
+ * @param error - The raw error from the API call
+ * @param context - Context information including operation name
+ * @returns A structured KitError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const response = await fetch(url)
+ * } catch (error) {
+ *   throw parseApiError(error, { operation: 'getQuote' })
+ * }
+ * ```
+ */ function parseApiError(error, context) {
+    // If it's already a KitError, return it as-is
+    if (error instanceof KitError) {
+        return error;
+    }
+    const msg = getErrorMessage(error);
+    const statusCode = extractHttpStatusCode(msg);
+    const serviceName = context.service ?? 'Stablecoin Service';
+    const operation = context.operation ?? 'API';
+    const responseBody = extractResponseBody(error);
+    // Rate limit errors (429)
+    if (statusCode === 429 || /too many requests|rate limit exceeded/i.test(msg)) {
+        return handleRateLimitError(serviceName, operation, error);
+    }
+    // HTTP 4xx Client Errors
+    if (statusCode !== null && statusCode >= 400 && statusCode < 500) {
+        return handleClientError(statusCode, serviceName, operation, error, msg, responseBody);
+    }
+    // HTTP 5xx Server Errors
+    if (statusCode !== null && statusCode >= 500 && statusCode < 600) {
+        return handleServerError(statusCode, serviceName, operation, error, responseBody);
+    }
+    // Timeout errors
+    if (/timeout|timed out/i.test(msg)) {
+        return handleTimeoutError(serviceName, operation, error);
+    }
+    // Network connectivity errors
+    if (/connection (refused|failed)|network|ENOTFOUND|ECONNREFUSED|ETIMEDOUT/i.test(msg)) {
+        return handleConnectionError(serviceName, operation, error);
+    }
+    // Fallback: Unknown error - use UNKNOWN_ERROR with fatal recoverability since we don't know what the error is
+    return new KitError({
+        ...ServiceError.UNKNOWN_ERROR,
+        recoverability: 'FATAL',
+        message: `${serviceName} ${operation} failed: ${msg.length > 0 ? msg : 'Unknown error'}`,
+        cause: {
+            trace: error
+        }
+    });
+}
+/**
+ * Handles HTTP 4xx client errors and maps them to appropriate KitError instances.
+ *
+ * @param statusCode - The HTTP status code
+ * @param serviceName - The name of the service
+ * @param operation - The operation name
+ * @param error - The raw error object
+ * @param msg - The message extracted from the error
+ * @param responseBody - The parsed JSON response body from the server, if available
+ * @returns A KitError instance
+ */ function handleClientError(statusCode, serviceName, operation, error, msg, responseBody) {
+    const detail = extractDetailFromBody(responseBody) ?? msg;
+    switch(statusCode){
+        // 401/403 - Authentication/Authorization
+        case 401:
+        case 403:
+            return new KitError({
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: `${serviceName} ${operation} failed: Invalid or missing API key or authorization`,
+                cause: {
+                    trace: error
+                }
+            });
+        // 404 - Not found - unsupported route OR stop-limit / slippage constraint not met
+        case 404:
+            if (isSlippageConstraintFailure(responseBody)) {
+                return new KitError({
+                    ...InputError.SLIPPAGE_CONSTRAINT_NOT_MET,
+                    recoverability: 'RETRYABLE',
+                    message: `${serviceName} ${operation} failed: ${detail}. ` + 'Try increasing slippageBps or adjusting stopLimit.',
+                    cause: {
+                        trace: error
+                    }
+                });
+            }
+            return new KitError({
+                ...InputError.UNSUPPORTED_ROUTE,
+                recoverability: 'FATAL',
+                message: `${serviceName} ${operation} failed: Route or resource not found. Details: ${detail}`,
+                cause: {
+                    trace: error
+                }
+            });
+        // 422 Unprocessable Entity
+        // Proxy service is mapping 422 to INSUFFICIENT_SWAP_AMOUNT
+        case 422:
+            return new KitError({
+                ...InputError.INSUFFICIENT_SWAP_AMOUNT,
+                recoverability: 'FATAL',
+                message: `${serviceName} ${operation} failed: ${detail}`,
+                cause: {
+                    trace: error
+                }
+            });
+        // 400 Bad Request - Invalid token, amount-out-of-range, or validation failed
+        // Proxy maps 400 to UNSUPPORTED_TOKEN | AMOUNT_OUT_OF_RANGE | VALIDATION_FAILED
+        case 400:
+            if (responseBody?.code === ProxyErrorCode.INVALID_SWAP_AMOUNT) {
+                const amountErr = extractAmountError(responseBody);
+                return new KitError({
+                    ...InputError.AMOUNT_OUT_OF_RANGE,
+                    recoverability: 'FATAL',
+                    message: `${serviceName} ${operation} failed: ${detail}`,
+                    cause: {
+                        trace: {
+                            rawError: error,
+                            minAmount: amountErr?.minAmount,
+                            maxAmount: amountErr?.maxAmount,
+                            token: amountErr?.token
+                        }
+                    }
+                });
+            }
+            return new KitError({
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: `${serviceName} ${operation} failed: ${detail}`,
+                cause: {
+                    trace: error
+                }
+            });
+        default:
+            // Other 4xx errors - treat as validation failures
+            return new KitError({
+                ...InputError.VALIDATION_FAILED,
+                recoverability: 'FATAL',
+                message: `${serviceName} ${operation} failed: ${detail}`,
+                cause: {
+                    trace: error
+                }
+            });
+    }
+}
+/**
+ * Pattern that matches proxy response body text indicating the 404 was
+ * caused by a slippage / price constraint rather than a truly unsupported
+ * route. Kept case-insensitive so future proxy wording changes are tolerated.
+ *
+ * @internal
+ */ const SLIPPAGE_BODY_PATTERN = /slippage|stop.?limit|price.?impact|minimum.?output|SLIPPAGE_CONSTRAINT_NOT_MET/i;
+/**
+ * Determine whether a 404 was caused by an unmet slippage or price
+ * constraint rather than a genuinely unsupported route.
+ *
+ * Detection relies on the proxy response body containing slippage-related
+ * language or a structured reason code. This avoids false positives that
+ * would occur if we guessed based on request parameters alone (a user
+ * can set `slippageBps` and still hit a truly unsupported route).
+ *
+ * @param responseBody - The parsed JSON body returned by the proxy
+ * @returns `true` when the 404 should be treated as a slippage constraint failure
+ * @internal
+ */ function isSlippageConstraintFailure(responseBody) {
+    if (responseBody === undefined) {
+        return false;
+    }
+    const textsToCheck = [
+        responseBody.externalMessage,
+        responseBody.message,
+        extractDetailFromBody(responseBody)
+    ];
+    return textsToCheck.some((t)=>typeof t === 'string' && SLIPPAGE_BODY_PATTERN.test(t));
+}
+/**
+ * Handles HTTP 5xx server errors and maps them to appropriate KitError instances.
+ *
+ * Recognizes proxy-specific structured codes in `responseBody.code` and routes
+ * known conditions (e.g. {@link ProxyErrorCode.LOW_LIQUIDITY} on 503) to their
+ * dedicated KitError. Falls back to a generic retryable `SERVICE_INTERNAL_ERROR`
+ * when no specific code is present.
+ *
+ * @param statusCode - The HTTP status code
+ * @param serviceName - The name of the service
+ * @param operation - The operation name
+ * @param error - The raw error object
+ * @param responseBody - The parsed JSON response body from the server, if available
+ * @returns A KitError instance
+ */ function handleServerError(statusCode, serviceName, operation, error, responseBody) {
+    // 503 + 331018 = upstream liquidity insufficient (proxy)
+    if (statusCode === 503 && responseBody?.code === ProxyErrorCode.LOW_LIQUIDITY) {
+        const amountErr = extractAmountError(responseBody);
+        const detail = extractDetailFromBody(responseBody) ?? getErrorMessage(error);
+        return new KitError({
+            ...LiquidityError.INSUFFICIENT_LIQUIDITY,
+            recoverability: 'RETRYABLE',
+            message: `${serviceName} ${operation} failed: ${detail}`,
+            cause: {
+                trace: {
+                    rawError: error,
+                    minAmount: amountErr?.minAmount,
+                    maxAmount: amountErr?.maxAmount,
+                    token: amountErr?.token
+                }
+            }
+        });
+    }
+    return new KitError({
+        ...ServiceError.INTERNAL_ERROR,
+        recoverability: 'RETRYABLE',
+        message: `${serviceName} ${operation} failed: Server error (${statusCode.toString()})`,
+        cause: {
+            trace: error
+        }
+    });
+}
+/**
+ * Handles network connection errors and maps them to appropriate KitError instances.
+ *
+ * @param serviceName - The name of the service
+ * @param operation - The operation name
+ * @param error - The raw error object
+ * @returns A KitError instance
+ */ function handleConnectionError(serviceName, operation, error) {
+    return new KitError({
+        ...NetworkError.CONNECTION_FAILED,
+        recoverability: 'RETRYABLE',
+        message: `${serviceName} ${operation} failed: Network connection error`,
+        cause: {
+            trace: error
+        }
+    });
+}
+/**
+ * Handles rate limit errors and maps them to appropriate KitError instances.
+ *
+ * @param serviceName - The name of the service
+ * @param operation - The operation name
+ * @param error - The raw error object
+ * @returns A KitError instance
+ */ function handleRateLimitError(serviceName, operation, error) {
+    return new KitError({
+        ...RateLimitError.RATE_LIMIT_EXCEEDED,
+        recoverability: 'RETRYABLE',
+        message: `${serviceName} ${operation} failed: Too many requests, please retry later`,
+        cause: {
+            trace: error
+        }
+    });
+}
+/**
+ * Handles timeout errors and maps them to appropriate KitError instances.
+ *
+ * @param serviceName - The name of the service
+ * @param operation - The operation name
+ * @param error - The raw error object
+ * @returns A KitError instance
+ */ function handleTimeoutError(serviceName, operation, error) {
+    return new KitError({
+        ...NetworkError.TIMEOUT,
+        recoverability: 'RETRYABLE',
+        message: `${serviceName} ${operation} failed: Request timeout`,
+        cause: {
+            trace: error
+        }
+    });
+}
+/**
+ * Type guard that narrows an unknown error to one carrying a non-null
+ * object `responseBody` property (attached by `makeApiRequest`).
+ *
+ * @param error - The raw error from the HTTP layer
+ * @returns `true` when `error.responseBody` is a non-null object
+ * @internal
+ */ function hasResponseBody(error) {
+    return typeof error === 'object' && error !== null && 'responseBody' in error && typeof error['responseBody'] === 'object' && error['responseBody'] !== null;
+}
+/**
+ * Extract the `responseBody` property that `makeApiRequest` attaches to
+ * HTTP error instances when the server returns a JSON body.
+ *
+ * @param error - The raw error from the HTTP layer
+ * @returns The parsed body cast to {@link ApiErrorResponseBody}, or undefined
+ * @throws Never. Returns `undefined` when the error does not carry a valid
+ *   `responseBody`.
+ * @internal
+ */ function extractResponseBody(error) {
+    if (!hasResponseBody(error)) {
+        return undefined;
+    }
+    return error.responseBody;
+}
+/**
+ * Extract a field name from an {@link ApiFieldError}.
+ *
+ * The proxy service may provide the field name as a plain `field` string
+ * or as a `path` array (e.g. `["tokenInChain"]`). This helper resolves
+ * whichever is available, preferring `field` when both exist.
+ *
+ * @param entry - A single error entry from the `errors` array
+ * @returns The field name, or `undefined` when neither is available
+ * @internal
+ */ function extractFieldName(entry) {
+    if (typeof entry.field === 'string' && entry.field.length > 0) {
+        return entry.field;
+    }
+    if (Array.isArray(entry.path) && entry.path.length > 0) {
+        const first = entry.path[0];
+        if (typeof first === 'string' && first.length > 0) {
+            return first;
+        }
+    }
+    return undefined;
+}
+/**
+ * Join field-level error entries into a single human-readable string.
+ *
+ * Each entry is formatted as `"field: message"` when a field name is
+ * available (via `field` or `path`), or just the message otherwise.
+ * Entries without a usable message (including amount-bound entries that
+ * only carry `minAmount`/`maxAmount`/`token`) are skipped.
+ *
+ * @param errors - The `errors` array from the response body
+ * @returns A joined string, or `undefined` when no usable entries exist
+ * @internal
+ */ function joinFieldErrors(errors) {
+    const parts = errors.map((entry)=>{
+        if (!isFieldEntry(entry)) {
+            return undefined;
+        }
+        const fieldMsg = typeof entry.message === 'string' && entry.message.length > 0 ? entry.message : undefined;
+        if (fieldMsg === undefined) {
+            return undefined;
+        }
+        const fieldName = extractFieldName(entry);
+        return fieldName === undefined ? fieldMsg : `${fieldName}: ${fieldMsg}`;
+    }).filter((s)=>s !== undefined);
+    return parts.length > 0 ? parts.join('; ') : undefined;
+}
+/**
+ * Narrow an {@link ApiErrorItem} to the field-error shape used for
+ * validation messages. Amount-bound entries (which carry no `message`)
+ * are excluded.
+ *
+ * @internal
+ */ function isFieldEntry(entry) {
+    return 'message' in entry || 'field' in entry || 'path' in entry;
+}
+/**
+ * Narrow an {@link ApiErrorItem} to the amount-bound shape emitted by the
+ * proxy for {@link ProxyErrorCode.INVALID_SWAP_AMOUNT}.
+ *
+ * @internal
+ */ function isAmountEntry(entry) {
+    return 'minAmount' in entry || 'maxAmount' in entry || 'token' in entry;
+}
+/**
+ * Extract the first amount-bound entry from a response body, if any.
+ *
+ * @internal
+ */ function extractAmountError(body) {
+    if (body === undefined || !Array.isArray(body.errors)) {
+        return undefined;
+    }
+    return body.errors.find(isAmountEntry);
+}
+/**
+ * Derive a human-readable detail string from an {@link ApiErrorResponseBody}.
+ *
+ * Resolution order:
+ * 1. `body.externalMessage` -- the user-facing string the proxy intends
+ *    consumers to display (e.g. "No route found that satisfies the
+ *    requested stop limit"). Preferred when available.
+ * 2. `body.message` **and** `body.errors` -- when both are present the
+ *    top-level message is combined with the field-level detail so
+ *    developers see the full picture
+ *    (e.g. `"Validation error: tokenInChain: Invalid input; amount: …"`).
+ * 3. `body.message` alone -- used as-is.
+ * 4. `body.errors` alone -- field-level entries joined with "; ".
+ * 5. `undefined` -- caller should fall back to the raw HTTP status text.
+ *
+ * @param body - The parsed response body, may be undefined
+ * @returns A detail string, or undefined when no useful info is available
+ * @internal
+ */ function extractDetailFromBody(body) {
+    if (body === undefined) {
+        return undefined;
+    }
+    const externalMessage = typeof body.externalMessage === 'string' && body.externalMessage.length > 0 ? body.externalMessage : undefined;
+    if (externalMessage !== undefined) {
+        return externalMessage;
+    }
+    const topMessage = typeof body.message === 'string' && body.message.length > 0 ? body.message : undefined;
+    const fieldDetail = Array.isArray(body.errors) && body.errors.length > 0 ? joinFieldErrors(body.errors) : undefined;
+    if (topMessage !== undefined && fieldDetail !== undefined) {
+        return `${topMessage}: ${fieldDetail}`;
+    }
+    return topMessage ?? fieldDetail;
+}
+/**
+ * Extracts the HTTP status code from an error message.
+ *
+ * Attempts to parse HTTP status codes from common error message formats,
+ * such as "HTTP 404" or "Status: 500".
+ *
+ * @param msg - The error message to extract from
+ * @returns The extracted HTTP status code, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const code = extractHttpStatusCode('HTTP 404')
+ * // Returns: 404
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const code = extractHttpStatusCode('Status: 500 Internal Server Error')
+ * // Returns: 500
+ * ```
+ */ function extractHttpStatusCode(msg) {
+    // Pattern: "HTTP 404" or "HTTP 404 - some message" or "Status: 404"
+    const patterns = [
+        /HTTP (\d{3})/i,
+        /Status:\s*(\d{3})/i,
+        /^(\d{3}) -/
+    ];
+    for (const pattern of patterns){
+        const match = pattern.exec(msg);
+        const codeStr = match?.at(1);
+        if (codeStr !== undefined) {
+            const code = Number.parseInt(codeStr, 10);
+            // Validate it's a valid HTTP status code
+            if (code >= 100 && code < 600) {
+                return code;
+            }
+        }
+    }
+    return null;
+}
+
 /**
  * @packageDocumentation
  * @module ChainDefinitions
@@ -2534,6 +3113,8 @@ class KitError extends Error {
     Blockchain["Optimism_Sepolia"] = "Optimism_Sepolia";
     Blockchain["Pharos"] = "Pharos";
     Blockchain["Pharos_Testnet"] = "Pharos_Testnet";
+    Blockchain["Plasma"] = "Plasma";
+    Blockchain["Plasma_Testnet"] = "Plasma_Testnet";
     Blockchain["Polkadot_Asset_Hub"] = "Polkadot_Asset_Hub";
     Blockchain["Polkadot_Westmint"] = "Polkadot_Westmint";
     Blockchain["Plume"] = "Plume";
@@ -2603,6 +3184,7 @@ var BridgeChain;
     BridgeChain["Morph"] = "Morph";
     BridgeChain["Optimism"] = "Optimism";
     BridgeChain["Pharos"] = "Pharos";
+    BridgeChain["Plasma"] = "Plasma";
     BridgeChain["Plume"] = "Plume";
     BridgeChain["Polygon"] = "Polygon";
     BridgeChain["Sei"] = "Sei";
@@ -2629,6 +3211,7 @@ var BridgeChain;
     BridgeChain["Morph_Testnet"] = "Morph_Testnet";
     BridgeChain["Optimism_Sepolia"] = "Optimism_Sepolia";
     BridgeChain["Pharos_Testnet"] = "Pharos_Testnet";
+    BridgeChain["Plasma_Testnet"] = "Plasma_Testnet";
     BridgeChain["Plume_Testnet"] = "Plume_Testnet";
     BridgeChain["Polygon_Amoy_Testnet"] = "Polygon_Amoy_Testnet";
     BridgeChain["Sei_Testnet"] = "Sei_Testnet";
@@ -3075,17 +3658,56 @@ var EarnChain;
  * This program handles minting operations for Gateway transactions
  * on Solana devnet.
  */ const GATEWAY_MINTER_SOLANA_DEVNET = 'GATEmKK2ECL1brEngQZWCgMWPbvrEYqsV6u29dAaHavr';
-
 /**
- * Arc Testnet chain definition
- * @remarks
- * This represents the test network for the Arc blockchain,
- * Circle's EVM-compatible Layer-1 designed for stablecoin finance
- * and asset tokenization. Arc uses USDC as the native gas token and
- * features the Malachite Byzantine Fault Tolerant (BFT) consensus
- * engine for sub-second finality.
- */ const ArcTestnet = defineChain({
-    type: 'evm',
+ * 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
+ * @remarks
+ * This represents the test network for the Arc blockchain,
+ * Circle's EVM-compatible Layer-1 designed for stablecoin finance
+ * and asset tokenization. Arc uses USDC as the native gas token and
+ * features the Malachite Byzantine Fault Tolerant (BFT) consensus
+ * engine for sub-second finality.
+ */ const ArcTestnet = defineChain({
+    type: 'evm',
     chain: Blockchain.Arc_Testnet,
     name: 'Arc Testnet',
     title: 'ArcTestnet',
@@ -3112,6 +3734,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -3132,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: {
@@ -3179,6 +3801,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3243,6 +3866,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3307,6 +3931,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -3326,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: {
@@ -3368,6 +3995,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -3389,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: {
@@ -3435,6 +4065,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3499,6 +4130,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3609,6 +4241,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3653,6 +4286,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3698,6 +4332,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -3743,6 +4378,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -3788,6 +4424,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x98706A006bc632Df31CAdFCBD43F38887ce2ca5c',
+                tokenMessengerWithFees: '0x3Ac96675F9a3E6922713e041645D82f3561d3686',
                 messageTransmitter: '0x5b61381Fc9e58E70EfC13a4A97516997019198ee',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3833,6 +4470,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -3884,6 +4522,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 2
@@ -3948,6 +4587,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 2
@@ -4058,6 +4698,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4117,6 +4758,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4177,6 +4819,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4224,6 +4867,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4271,6 +4915,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4318,6 +4963,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4362,6 +5008,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4407,6 +5054,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4453,6 +5101,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4500,6 +5149,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4545,6 +5195,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 64,
                 fastConfirmations: 1
@@ -4590,6 +5241,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 64,
                 fastConfirmations: 1
@@ -4766,6 +5418,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4830,6 +5483,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -4889,6 +5543,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4935,6 +5590,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -4950,6 +5606,98 @@ var EarnChain;
     }
 });
 
+/**
+ * Plasma Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Plasma blockchain.
+ * Plasma is an EVM-equivalent Layer 1 blockchain purpose-built for global
+ * stablecoin payments, with deterministic BFT finality (PlasmaBFT/Fast-HotStuff).
+ */ const Plasma = defineChain({
+    type: 'evm',
+    chain: Blockchain.Plasma,
+    name: 'Plasma',
+    title: 'Plasma Mainnet',
+    nativeCurrency: {
+        name: 'Plasma',
+        symbol: 'XPL',
+        decimals: 18
+    },
+    chainId: 9745,
+    isTestnet: false,
+    explorerUrl: 'https://plasmascan.to/tx/{hash}',
+    rpcEndpoints: [
+        'https://rpc.plasma.to'
+    ],
+    eurcAddress: '0x3EE196E78d4d4248b849B8E1C7F44C5457FAFD2C',
+    usdcAddress: '0x2d661C89D812261039AF9764eceaAee884f5F67F',
+    usdtAddress: null,
+    cctp: {
+        domain: 33,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 3,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * Plasma Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Plasma blockchain.
+ * Plasma is an EVM-equivalent Layer 1 blockchain purpose-built for global
+ * stablecoin payments, with deterministic BFT finality (PlasmaBFT/Fast-HotStuff).
+ */ const PlasmaTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.Plasma_Testnet,
+    name: 'Plasma Testnet',
+    title: 'Plasma Testnet',
+    nativeCurrency: {
+        name: 'Plasma',
+        symbol: 'XPL',
+        decimals: 18
+    },
+    chainId: 9746,
+    isTestnet: true,
+    explorerUrl: 'https://testnet.plasmascan.to/tx/{hash}',
+    rpcEndpoints: [
+        'https://testnet-rpc.plasma.to'
+    ],
+    eurcAddress: '0x98AfA0F93Dd993B736399f9074eDcEBD1985A330',
+    usdcAddress: '0xE67Fb267022cBA8064Dd388CC2FED724F3120D9D',
+    usdtAddress: null,
+    cctp: {
+        domain: 33,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 3,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * Plume Mainnet chain definition
  * @remarks
@@ -4981,6 +5729,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5027,6 +5776,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5128,6 +5878,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 33,
                 fastConfirmations: 13
@@ -5147,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: {
@@ -5193,6 +5946,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 33,
                 fastConfirmations: 13
@@ -5211,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: {
@@ -5252,6 +6008,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5311,6 +6068,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5368,6 +6126,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5426,6 +6185,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 1,
                 fastConfirmations: 1
@@ -5741,6 +6501,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5805,6 +6566,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5862,6 +6624,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cF5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5921,6 +6684,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8fe6b999dc680ccfdd5bf7eb0974218be2542daa',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xe737e5cebeeba77efe34d4aa090756590b1ce275',
                 confirmations: 65,
                 fastConfirmations: 1
@@ -5981,6 +6745,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_MAINNET,
                 messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
                 confirmations: 3,
                 fastConfirmations: 3
@@ -6026,6 +6791,7 @@ var EarnChain;
             v2: {
                 type: 'split',
                 tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                tokenMessengerWithFees: TOKEN_MESSENGER_WITH_FEES_EVM_TESTNET,
                 messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
                 confirmations: 3,
                 fastConfirmations: 1
@@ -6236,6 +7002,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   OptimismSepolia: OptimismSepolia,
   Pharos: Pharos,
   PharosTestnet: PharosTestnet,
+  Plasma: Plasma,
+  PlasmaTestnet: PlasmaTestnet,
   Plume: Plume,
   PlumeTestnet: PlumeTestnet,
   PolkadotAssetHub: PolkadotAssetHub,
@@ -6285,6 +7053,71 @@ 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 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. 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
+ * import { Chains, hasSourceFeeSupport } from '@core/chains'
+ *
+ * hasSourceFeeSupport(Chains.Optimism) // true
+ * 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;
+    if (typeof wrapper !== 'string' || wrapper.length === 0) {
+        return false;
+    }
+    return SOURCE_FEE_SUPPORTED_ALLOWLIST.has(chain.chain);
+}
+
 /**
  * Check if a chain supports a specific type of custom smart contract logic.
  *
@@ -6335,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.
  *
@@ -6356,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
 ;
 /**
@@ -8303,6 +9206,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Noble]: 'uusdc',
         [Blockchain.Optimism]: '0x0b2c639c533813f4aa9d7837caf62653d097ff85',
         [Blockchain.Pharos]: '0xC879C018dB60520F4355C26eD1a6D572cdAC1815',
+        [Blockchain.Plasma]: '0x2d661C89D812261039AF9764eceaAee884f5F67F',
         [Blockchain.Plume]: '0x222365EF19F7947e5484218551B56bb3965Aa7aF',
         [Blockchain.Polkadot_Asset_Hub]: '1337',
         [Blockchain.Polygon]: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359',
@@ -8339,6 +9243,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Noble_Testnet]: 'uusdc',
         [Blockchain.Optimism_Sepolia]: '0x5fd84259d66Cd46123540766Be93DFE6D43130D7',
         [Blockchain.Pharos_Testnet]: '0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B',
+        [Blockchain.Plasma_Testnet]: '0xE67Fb267022cBA8064Dd388CC2FED724F3120D9D',
         [Blockchain.Plume_Testnet]: '0xcB5f30e335672893c7eb944B374c196392C19D18',
         [Blockchain.Polkadot_Westmint]: '31337',
         [Blockchain.Polygon_Amoy_Testnet]: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -8401,6 +9306,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Base]: '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42',
         [Blockchain.Cronos]: '0xA6dE01a2d62C6B5f3525d768f34d276652C554c8',
         [Blockchain.Ethereum]: '0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c',
+        [Blockchain.Plasma]: '0x3EE196E78d4d4248b849B8E1C7F44C5457FAFD2C',
         [Blockchain.Solana]: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
         [Blockchain.World_Chain]: '0x1C60ba0A0eD1019e8Eb035E6daF4155A5cE2380B',
         // =========================================================================
@@ -8409,7 +9315,8 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Arc_Testnet]: '0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a',
         [Blockchain.Base_Sepolia]: '0x808456652fdb597867f38412077A9182bf77359F',
         [Blockchain.Cronos_Testnet]: '0x31f7538adb53cF16350e6B0c89d03D91b7D12c46',
-        [Blockchain.Ethereum_Sepolia]: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4'
+        [Blockchain.Ethereum_Sepolia]: '0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4',
+        [Blockchain.Plasma_Testnet]: '0x98AfA0F93Dd993B736399f9074eDcEBD1985A330'
     }
 };
 
@@ -9223,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.
  *
@@ -9233,6 +10143,16 @@ const swapTokenEnumSchema = z.enum([
  *
  * Set to 0 when no additional Circle-reserved data is needed.
  */ const CCTP_FORWARD_PAYLOAD_LENGTH = 0;
+/**
+ * Length in bytes of a Solana owner (ed25519 / PDA) public key.
+ */ const SOLANA_PUBKEY_LENGTH = 32;
+/**
+ * Byte length of the Solana ATA-creation forwarding payload appended after the
+ * `cctp-forward` frame: `createAta` (1 byte) + `ataOwner` (32 bytes).
+ *
+ * Circle's Orbit relayer decodes exactly this many bytes; see
+ * {@link buildSolanaAtaForwardingHookData}.
+ */ const SOLANA_ATA_FORWARD_PAYLOAD_LENGTH = 1 + SOLANA_PUBKEY_LENGTH;
 /**
  * Build the hookData bytes for CCTP forwarding.
  *
@@ -9289,6 +10209,518 @@ 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.
+ *
+ * When an EVM→Solana bridge is forwarded, the destination mint targets the
+ * recipient's USDC ATA — which does not exist for a fresh wallet. This frame
+ * tells the relayer to prepend an idempotent `createAssociatedTokenAccount`
+ * instruction (the relayer pays the rent) so the mint always succeeds.
+ *
+ * Unlike {@link buildForwardingHookData} (an empty version-0 frame), this emits
+ * a version-0 frame whose 32-bit `dataLength` is set to
+ * {@link SOLANA_ATA_FORWARD_PAYLOAD_LENGTH} (33), followed by the payload the
+ * relayer decodes:
+ * - Byte 0: `createAta` flag, always `1`
+ * - Bytes 1-32: the recipient's 32-byte Solana owner public key (`ataOwner`)
+ *
+ * @remarks
+ * `ataOwner` is the recipient's *wallet* public key, not the derived ATA. The
+ * relayer re-derives the ATA from `ataOwner` and the USDC mint and requires it
+ * to equal the burn's `mintRecipient`, so callers must pass the same owner used
+ * to derive `mintRecipient`. The all-zero key is reserved as "absent owner" and
+ * is rejected.
+ *
+ * @param ataOwner - The recipient's 32-byte Solana owner public key.
+ * @returns A 0x-prefixed hex string: the 32-byte frame followed by the 33-byte
+ *   Solana ATA payload.
+ * @throws {KitError} If `ataOwner` is not exactly 32 bytes, or is the all-zero
+ *   key (INPUT_VALIDATION_FAILED).
+ *
+ * @example
+ * ```typescript
+ * import { PublicKey } from '@solana/web3.js'
+ * import { buildSolanaAtaForwardingHookData } from '@core/utils'
+ *
+ * const owner = new PublicKey('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM')
+ * const hookData = buildSolanaAtaForwardingHookData(owner.toBytes())
+ *
+ * // Use with the forwarded depositForBurnWithHook action so the relayer
+ * // creates the recipient ATA before minting.
+ * await adapter.prepareAction('cctp.v2.depositForBurnWithHook', {
+ *   amount: BigInt('1000000'),
+ *   mintRecipient: '0x...',
+ *   maxFee: BigInt('50000'),
+ *   minFinalityThreshold: 1000,
+ *   fromChain: ethereum,
+ *   toChain: solana,
+ *   hookData,
+ * })
+ * ```
+ */ function buildSolanaAtaForwardingHookData(ataOwner) {
+    if (!(ataOwner instanceof Uint8Array) || ataOwner.length !== SOLANA_PUBKEY_LENGTH) {
+        throw createValidationFailedError$1('ataOwner', ataOwner, `Expected a ${String(SOLANA_PUBKEY_LENGTH)}-byte Solana owner public key`);
+    }
+    if (ataOwner.every((byte)=>byte === 0)) {
+        throw createValidationFailedError$1('ataOwner', ataOwner, 'Expected a non-zero Solana owner public key; the all-zero key is reserved as "absent owner"');
+    }
+    // Inner payload: createAta(1) + ataOwner(32).
+    const payload = new Uint8Array(SOLANA_ATA_FORWARD_PAYLOAD_LENGTH);
+    payload[0] = 1 // createAta = true
+    ;
+    payload.set(ataOwner, 1);
+    // 32-byte header: 24-byte magic + uint32 version(0) + uint32 dataLength(33).
+    // The relayer reads dataLength from the v0 frame to slice the inner payload,
+    // so it MUST reflect the appended byte count (unlike the GenericExecutor path).
+    const frame = new Uint8Array(32);
+    frame.set(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX), 0);
+    const view = new DataView(frame.buffer);
+    view.setUint32(24, CCTP_FORWARD_VERSION, false) // big-endian, 0
+    ;
+    view.setUint32(28, SOLANA_ATA_FORWARD_PAYLOAD_LENGTH, false) // big-endian, 33
+    ;
+    return hexlify(concat([
+        frame,
+        payload
+    ]));
+}
+
+/**
+ * `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.
+ *
+ * Mirrors viem's `pad(address, size 32)` and CCTP's `mintRecipient`
+ * convention. Solana addresses are already 32 bytes and need no padding.
+ *
+ * @param address - A 0x-prefixed 20-byte EVM address.
+ * @returns The address left-zero-padded to a 0x-prefixed 32-byte hex string.
+ * @throws {KitError} If `address` is not a valid EVM address (INPUT_VALIDATION_FAILED).
+ *
+ * @example
+ * ```typescript
+ * import { padAddressToBytes32 } from '@core/utils'
+ *
+ * padAddressToBytes32('0x75275Aff2D01699D922f045b69ed291311209738')
+ * // '0x00000000000000000000000075275aff2d01699d922f045b69ed291311209738'
+ * ```
+ */ function padAddressToBytes32(address) {
+    if (!isAddress(address)) {
+        throw createValidationFailedError$1('address', address, 'Expected a valid 20-byte EVM address');
+    }
+    // bytes32 is raw bytes, not a checksummed address — emit lowercase so it
+    // 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}.
@@ -9378,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.
@@ -9401,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) {
@@ -9597,22 +11032,36 @@ 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
- */ function warnTelemetryDrop(eventType, cause) {
-    try {
-        // Pass `cause` as the second console.warn argument rather than
-        // string-coercing it. `String(err)` (and `err.message` alone)
-        // 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 event '${eventType}':`, cause);
+ *
+ * @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
+        // string-coercing it. `String(err)` (and `err.message` alone)
+        // 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 event '${eventType}':`, cause);
     } catch  {
     // console.warn itself throwing is the user's environment; nothing more we
     // can do without risking the original operation error.
@@ -9644,6 +11093,9 @@ function resolveOptions(options) {
         ...context?.tokenOut != null && {
             tokenOut: context.tokenOut
         },
+        ...context?.amountIn != null && {
+            amountIn: context.amountIn
+        },
         ...context?.txHash != null && {
             txHash: context.txHash
         },
@@ -9745,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`
@@ -9762,7 +11214,7 @@ function resolveOptions(options) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.13.0";
+var version$3 = "1.14.1";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -10143,7 +11595,7 @@ const READ_ACTION_KEY_SET = new Set(READ_ACTION_KEYS);
  * const result = evmAddressSchema.safeParse(validAddress)
  * console.log(result.success) // true
  * ```
- */ const evmAddressSchema = hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
+ */ const evmAddressSchema$1 = hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
 /**
  * Schema for validating transaction hashes.
  *
@@ -10832,6 +12284,10 @@ var TransferSpeed;
     token: z.literal('USDC').optional(),
     config: z.object({
         transferSpeed: z.nativeEnum(TransferSpeed).optional(),
+        feePayment: z.enum([
+            'source',
+            'destination'
+        ]).optional(),
         maxFee: z.string().min(1, 'Required').pipe(createDecimalStringValidator({
             allowZero: true,
             regexMessage: MAX_FEE_FORMAT_ERROR_MESSAGE,
@@ -10839,7 +12295,8 @@ var TransferSpeed;
             maxDecimals: 6
         })(z.string())).optional(),
         customFee: customFeeSchema.optional()
-    }).optional()
+    }).optional(),
+    quote: z.string().regex(/^0x([a-fA-F0-9]{2})+$/, 'must be non-empty 0x hex').optional()
 });
 
 /**
@@ -11451,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
@@ -12014,16 +13471,73 @@ var TransferSpeed;
     };
 }
 
+/**
+ * Dispatch a bridge step event through the provider's action dispatcher.
+ *
+ * Constructs the appropriate action payload and dispatches it to any registered
+ * event listeners. Handles type-safe dispatching for different step types.
+ * When provided, traceId from the invocation context is included for end-to-end correlation.
+ *
+ * @param name - The step name (approve, burn, fetchAttestation, or mint).
+ * @param step - The completed bridge step containing transaction details and explorerUrl.
+ * @param provider - The CCTP v2 provider with action dispatcher.
+ * @param invocation - Optional invocation context containing traceId for correlation.
+ *
+ * @example
+ * ```typescript
+ * const step: BridgeStep = {
+ *   name: 'burn',
+ *   state: 'success',
+ *   txHash: '0xabc...',
+ *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
+ *   data: { ... }
+ * }
+ * dispatchStepEvent('burn', step, provider, invocationContext)
+ * ```
+ */ function dispatchStepEvent(name, step, provider, invocation) {
+    if (!provider.actionDispatcher) {
+        return;
+    }
+    // Extract traceId from invocation context if provided
+    const traceId = invocation?.traceId;
+    const actionValues = {
+        protocol: 'cctp',
+        version: 'v2',
+        ...traceId !== undefined && {
+            traceId
+        },
+        values: step
+    };
+    switch(name){
+        case 'approve':
+        case 'burn':
+        case 'mint':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name
+            });
+            break;
+        case 'fetchAttestation':
+        case 'reAttest':
+            provider.actionDispatcher.dispatch(name, {
+                ...actionValues,
+                method: name,
+                values: step
+            });
+            break;
+    }
+}
+
 /**
  * Base URL for Circle's IRIS API (mainnet/production).
  *
  * The IRIS API provides attestation services for CCTP cross-chain transfers.
- */ const IRIS_API_BASE_URL = 'https://iris-api.circle.com';
+ */ const IRIS_API_BASE_URL$1 = 'https://iris-api.circle.com';
 /**
  * Base URL for Circle's IRIS API (testnet/sandbox).
  *
  * Used for development and testing on testnet chains.
- */ const IRIS_API_SANDBOX_BASE_URL = 'https://iris-api-sandbox.circle.com';
+ */ const IRIS_API_SANDBOX_BASE_URL$1 = 'https://iris-api-sandbox.circle.com';
 
 /**
  * Type guard to validate the API response structure.
@@ -12066,7 +13580,7 @@ const isFastBurnFeeResponse = (data)=>{
  * @param isTestnet - Whether the request is for a testnet chain
  * @returns The complete API URL
  */ function buildFastBurnFeeUrl(sourceDomain, destinationDomain, isTestnet) {
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     return `${baseUrl}/v2/burn/USDC/fees/${sourceDomain.toString()}/${destinationDomain.toString()}`;
 }
 const FAST_TIER_FINALITY_THRESHOLD = 1000;
@@ -12277,6 +13791,77 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     }
 };
 
+/**
+ * Build the forwarding `hookData` for a forwarded (Orbit-relayed) CCTP v2 burn,
+ * tailored to the destination chain.
+ *
+ * For EVM destinations the recipient already holds ERC-20 USDC directly, so the
+ * empty version-0 `cctp-forward` frame is sufficient. For Solana destinations
+ * USDC is held in an Associated Token Account (ATA) that may not exist for a
+ * fresh wallet, so this emits a frame carrying `createAta` + `ataOwner` that
+ * instructs the relayer to create the recipient ATA (idempotently, at the
+ * relayer's expense) before minting.
+ *
+ * `@solana/web3.js` is imported lazily so EVM-only consumers never load Solana
+ * code, mirroring {@link getMintRecipientAccount}.
+ *
+ * @param chainType - The destination blockchain type ('evm' or 'solana').
+ * @param ownerAddress - The recipient's wallet address on the destination chain
+ *   (base58 for Solana). Must be the same owner used to derive `mintRecipient`.
+ * @returns A 0x-prefixed hookData hex string for the forwarded burn.
+ * @throws {KitError} If `chainType` is neither 'evm' nor 'solana', if
+ *   `@solana/web3.js` cannot be loaded, or if `ownerAddress` is not a valid
+ *   Solana public key (all FATAL).
+ *
+ * @example
+ * ```typescript
+ * import { getForwarderHookData } from './getForwarderHookData'
+ *
+ * // EVM: empty forwarding frame
+ * const evmHook = await getForwarderHookData('evm', '0x742d35Cc...')
+ *
+ * // Solana: frame instructing the relayer to create the recipient ATA
+ * const solanaHook = await getForwarderHookData(
+ *   'solana',
+ *   '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+ * )
+ * ```
+ */ const getForwarderHookData = async (/** The destination blockchain type - determines the hookData shape */ chainType, /** The recipient's wallet address (hex for EVM, base58 for Solana) */ ownerAddress)=>{
+    if (chainType === 'evm') {
+        // EVM: the recipient holds USDC directly; no ATA setup is needed.
+        return buildForwardingHookData();
+    }
+    // Fail closed: only EVM and Solana forwarding destinations are supported.
+    // Without this guard any future non-EVM chain type would silently fall
+    // through to the Solana path and mis-encode hookData on a money-movement path.
+    if (chainType !== 'solana') {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Forwarded burns are not supported for destination chain type "${chainType}"`
+        });
+    }
+    // Solana: encode the owner so the relayer creates the recipient ATA.
+    // Resolve @solana/web3.js lazily so EVM-only consumers never load Solana code.
+    const { PublicKey } = await import('@solana/web3.js').catch(()=>{
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: 'Failed to load @solana/web3.js. Please ensure it is installed: npm install @solana/web3.js'
+        });
+    });
+    try {
+        const owner = new PublicKey(ownerAddress);
+        return buildSolanaAtaForwardingHookData(owner.toBytes());
+    } catch (error) {
+        throw new KitError({
+            ...InputError.INVALID_ADDRESS,
+            recoverability: 'FATAL',
+            message: `Failed to build Solana forwarder hookData for recipient "${ownerAddress}": ${error instanceof Error ? error.message : String(error)}`
+        });
+    }
+};
+
 /**
  * Validates and converts a fee value to bigint.
  *
@@ -12379,7 +13964,7 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
 
 /**
  * The zero address, denoting a native-currency fee in a signed quote.
- */ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+ */ const ZERO_ADDRESS$1 = '0x0000000000000000000000000000000000000000';
 /**
  * Resolve the fee payment channel for a prepaid-FORWARD burn via `TokenMessengerWithFees`.
  *
@@ -12420,7 +14005,7 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     if (typeof feeTotalAmount !== 'bigint' || feeTotalAmount < 0n) {
         throw createValidationFailedError$1('feeTotalAmount', feeTotalAmount, 'Must be a non-negative bigint');
     }
-    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS;
+    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS$1;
     const isBurnTokenFee = !isNativeFee && feeToken.toLowerCase() === burnToken.toLowerCase();
     if (isNativeFee) {
         return {
@@ -12558,7 +14143,7 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
  * @param isTestnet - Whether the request is for a testnet chain
  * @returns The complete API URL with forward=true query parameter
  */ function buildForwardingFeeUrl(sourceDomain, destinationDomain, isTestnet) {
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     return `${baseUrl}/v2/burn/USDC/fees/${sourceDomain.toString()}/${destinationDomain.toString()}?forward=true`;
 }
 /**
@@ -12677,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
@@ -13619,7 +15206,7 @@ function hasPendingState(analysis, result) {
  * // => 'https://iris-api-sandbox.circle.com/v2/messages/1?transactionHash=0xdef...'
  * ```
  */ const buildIrisUrl = (sourceDomainId, transactionHash, isTestnet)=>{
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     const url = new URL(`${baseUrl}/v2/messages/${String(sourceDomainId)}`);
     url.searchParams.set('transactionHash', transactionHash);
     return url.toString();
@@ -13787,7 +15374,7 @@ function hasPendingState(analysis, result) {
  * // => 'https://iris-api-sandbox.circle.com/v2/reattest/0xabc'
  * ```
  */ const buildReAttestUrl = (nonce, isTestnet)=>{
-    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL;
+    const baseUrl = isTestnet ? IRIS_API_SANDBOX_BASE_URL$1 : IRIS_API_BASE_URL$1;
     const url = new URL(`${baseUrl}/v2/reattest/${nonce}`);
     return url.toString();
 };
@@ -14242,7 +15829,8 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
  * - `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
+ * - destination — either `executor`, or both `mintRecipient` and
+ *   `destinationCaller`; not both
  * - `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)
@@ -14284,10 +15872,17 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
     if (source.chain.name === dest.name) {
         throw createUnsupportedRouteError(source.chain.name, dest.name);
     }
-    // executor
+    // Destination: GenericExecutor shorthand or explicit recipient + caller.
     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)');
+    const mintRecipient = p['mintRecipient'];
+    const destinationCaller = p['destinationCaller'];
+    const hasExecutor = typeof executor === 'string' && executor !== '';
+    const hasDirectDestination = typeof mintRecipient === 'string' && mintRecipient !== '' && typeof destinationCaller === 'string' && destinationCaller !== '';
+    if (!hasExecutor && !hasDirectDestination) {
+        throw createValidationFailedError$1('destination', undefined, 'Provide executor, or both mintRecipient and destinationCaller');
+    }
+    if (hasExecutor && hasDirectDestination) {
+        throw createValidationFailedError$1('destination', undefined, 'Provide executor or direct destination fields, not both');
     }
     // amount
     const rawAmount = p['amount'];
@@ -14310,7 +15905,7 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
         throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
     }
     // feeToken
-    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
+    if (!evmAddressSchema$1.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
@@ -14322,7 +15917,7 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
     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) {
+    if (!evmAddressSchema$1.safeParse(claim['refundAddress']).success) {
         throw createValidationFailedError$1('claim.refundAddress', claim['refundAddress'], 'Must be a valid EVM address');
     }
     // hookData (optional)
@@ -14704,63 +16299,6 @@ const mockAttestationMessage = {
     });
 }
 
-/**
- * Dispatch a bridge step event through the provider's action dispatcher.
- *
- * Constructs the appropriate action payload and dispatches it to any registered
- * event listeners. Handles type-safe dispatching for different step types.
- * When provided, traceId from the invocation context is included for end-to-end correlation.
- *
- * @param name - The step name (approve, burn, fetchAttestation, or mint).
- * @param step - The completed bridge step containing transaction details and explorerUrl.
- * @param provider - The CCTP v2 provider with action dispatcher.
- * @param invocation - Optional invocation context containing traceId for correlation.
- *
- * @example
- * ```typescript
- * const step: BridgeStep = {
- *   name: 'burn',
- *   state: 'success',
- *   txHash: '0xabc...',
- *   explorerUrl: 'https://sepolia.etherscan.io/tx/0xabc...',
- *   data: { ... }
- * }
- * dispatchStepEvent('burn', step, provider, invocationContext)
- * ```
- */ function dispatchStepEvent(name, step, provider, invocation) {
-    if (!provider.actionDispatcher) {
-        return;
-    }
-    // Extract traceId from invocation context if provided
-    const traceId = invocation?.traceId;
-    const actionValues = {
-        protocol: 'cctp',
-        version: 'v2',
-        ...traceId !== undefined && {
-            traceId
-        },
-        values: step
-    };
-    switch(name){
-        case 'approve':
-        case 'burn':
-        case 'mint':
-            provider.actionDispatcher.dispatch(name, {
-                ...actionValues,
-                method: name
-            });
-            break;
-        case 'fetchAttestation':
-        case 'reAttest':
-            provider.actionDispatcher.dispatch(name, {
-                ...actionValues,
-                method: name,
-                values: step
-            });
-            break;
-    }
-}
-
 /**
  * Check whether the source adapter supports EIP-5792 atomic batching and
  * the consumer has not explicitly opted out via `config.batchTransactions`.
@@ -15007,7 +16545,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$2 = "1.11.0";
+var version$2 = "1.13.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -15713,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;
@@ -15818,6 +17359,34 @@ function assertCCTPV2Config(config) {
         this.config = config;
     }
     /**
+   * Emit a bridge step event through the provider's registered action
+   * dispatcher.
+   *
+   * Kit-level orchestration that drives the burn primitives directly instead
+   * of {@link CCTPV2BridgingProvider.bridge} (for example the receive-exact
+   * source-fee flow) uses this to surface the same `approve`/`burn`/`mint`
+   * events as the standard bridge path. It is a no-op when no dispatcher is
+   * registered.
+   *
+   * @param name - The step name (`approve`, `burn`, `mint`, ...).
+   * @param step - The completed bridge step to broadcast.
+   * @param invocation - Optional invocation context carrying a `traceId` for
+   *   end-to-end correlation.
+   * @returns Nothing.
+   *
+   * @example
+   * ```typescript
+   * const provider = new CCTPV2BridgingProvider()
+   * provider.emitBridgeStep('burn', {
+   *   name: 'burn',
+   *   state: 'success',
+   *   txHash: '0xabc...',
+   * })
+   * ```
+   */ emitBridgeStep(name, step, invocation) {
+        dispatchStepEvent(name, step, this, invocation);
+    }
+    /**
    * Resolves the effective polling configuration for an attestation request.
    *
    * Precedence (lowest to highest): provider `config.attestation`, then the
@@ -16047,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
@@ -16643,8 +18322,11 @@ function assertCCTPV2Config(config) {
         // 2. Forwarder: Does the user want Circle's relayer to handle attestation/mint?
         const useCustomBurn = hasCustomContractSupport(source.chain, 'bridge');
         const useForwarder = destination.useForwarder === true;
-        // Build hookData once if forwarder is enabled (memoized internally)
-        const hookData = useForwarder ? buildForwardingHookData() : undefined;
+        // Build hookData once if forwarder is enabled. EVM destinations get the
+        // empty forwarding frame; Solana destinations get a frame instructing the
+        // relayer to create the recipient's ATA (using the same owner that derived
+        // `mintRecipient`) so the mint succeeds even for a fresh wallet.
+        const hookData = useForwarder ? await getForwarderHookData(destination.chain.type, destinationAddressForMint) : undefined;
         if (useCustomBurn) {
             // Custom burn path: use bridge contract (with or without hook)
             const customBurnParams = {
@@ -16670,15 +18352,109 @@ 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.
    *
-   * 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.
+   * Build the source-chain `depositForBurnWithHookAndFees` call. Fees are
+   * collected up front on the source chain against a signed quote. The
+   * destination may use the GenericExecutor shorthand, or an explicit mint
+   * recipient and destination caller for direct forwarding.
    *
-   * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
-   * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+   * This is the low-level on-chain primitive behind the Unified Balance Kit
+   * `fastCrossChainDeposit` and the Bridge Kit source-fee
+   * (`feePayment: 'source'`) flow. The `hookData` and signed-quote
    * `claim` are produced elsewhere and passed in here:
    * - `hookData`: `buildForwardingHookDataWithPayload(version,
    *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
@@ -16695,32 +18471,48 @@ function assertCCTPV2Config(config) {
    *   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.
+   * @param params - The burn amount, destination, hook data, signed quote, 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.
+   *   support CCTP v2, the destination fields are missing, `amount` or
+   *   `feeTotalAmount` is not a bigint or a numeric string coercible to bigint,
+   *   the hook data lacks a `cctp-forward` frame (guaranteed
+   *   `ForwardFeeWithoutHook`), or the operation context cannot be resolved.
    *
    * @example
    * ```typescript
+   * import {
+   *   CCTPV2BridgingProvider,
+   *   type BurnWithFeesParams,
+   * } from '@circle-fin/provider-cctp-v2'
+   *
+   * declare const source: BurnWithFeesParams['source']
+   * declare const destinationChain: BurnWithFeesParams['destinationChain']
+   * declare const recipient: string
+   * declare const hookData: string
+   * declare const claim: BurnWithFeesParams['claim']
+   *
+   * const provider = new CCTPV2BridgingProvider()
    * const { approvals, burn } = await provider.burnWithFees({
    *   source,
-   *   destinationChain: Arc,
+   *   destinationChain,
    *   amount: 1_000_000n,
-   *   executor: genericExecutorAddress,
-   *   hookData: geForwardHookData,
-   *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
-   *   feeToken: '0x0000000000000000000000000000000000000000', // native
-   *   feeTotalAmount: 3_500_000n,
+   *   mintRecipient: recipient,
+   *   destinationCaller: '0x0000000000000000000000000000000000000000',
+   *   hookData,
+   *   claim,
+   *   feeToken: source.chain.usdcAddress,
+   *   feeTotalAmount: 10_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 { source, destinationChain, hookData, claim, feeToken } = params;
+        const hasExecutor = 'executor' in params && params.executor !== undefined;
+        const mintRecipient = hasExecutor ? params.executor : params.mintRecipient;
+        const destinationCaller = hasExecutor ? params.executor : params.destinationCaller;
         const amount = BigInt(params.amount);
         const feeTotalAmount = BigInt(params.feeTotalAmount);
         // Coupling guard: the prepaid FORWARD path always requests a FORWARD fee item,
@@ -16751,168 +18543,1171 @@ function assertCCTPV2Config(config) {
                 delegate: wrapperAddress,
                 amount: approval.amount
             }, context)));
-        // Build the burn: mintRecipient AND destinationCaller are both the executor.
+        // Build the burn with either the GenericExecutor shorthand or the explicit
+        // direct-forwarding recipient and caller.
         const burn = await source.adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
             fromChain: source.chain,
             toChain: destinationChain,
             amount,
-            mintRecipient: executor,
-            destinationCaller: executor,
+            mintRecipient,
+            destinationCaller,
             hookData,
             claim,
             feeToken,
             feeTotalAmount
         }, context);
         return {
-            approvals,
-            burn,
-            feePayment
+            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.
+   *
+   * @param adapter - The adapter to use for transaction waiting
+   * @param txHash - The hash of the transaction to wait for
+   * @param chain - The chain definition where the transaction was executed
+   * @param config - Optional configuration for transaction waiting (confirmations, timeout)
+   * @returns The hash of the confirmed transaction
+   * @example
+   * ```typescript
+   * const provider = new CCTPV2BridgingProvider()
+   * const txHash = await provider.waitForTransaction(
+   *   adapter,
+   *   '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+   *   Ethereum,
+   * )
+   * console.log('Transaction confirmed:', txHash)
+   * ```
+   */ async waitForTransaction(adapter, txHash, chain, config) {
+        return adapter.waitForTransaction(txHash, config, chain);
+    }
+}
+
+/**
+ * The default providers that will be used in addition to the providers provided
+ * to the BridgeKit constructor.
+ *
+ * @param config - Optional configuration forwarded to the default providers
+ * @returns The default bridging providers
+ */ const getDefaultProviders = (config = {})=>[
+        new CCTPV2BridgingProvider(config.headers ? {
+            headers: config.headers
+        } : {})
+    ];
+
+/**
+ * A helper function to get a function that transforms an amount into a human-readable string or a bigint string.
+ * @param formatDirection - The direction to format the amount in.
+ * @returns A function that transforms an amount into a human-readable string or a bigint string.
+ */ const getAmountTransformer = (formatDirection)=>formatDirection === 'to-human-readable' ? (params)=>formatAmount(params) : (params)=>parseAmount(params).toString();
+/**
+ * Format the bridge result into human-readable string values for the user or bigint string values for internal use.
+ *
+ * @typeParam T - The specific result type (must extend BridgeResult or EstimateResult). Preserves the exact type passed in.
+ * @param result - The bridge result to format.
+ * @param formatDirection - The direction to format the result in.
+ *   - If 'to-human-readable', the result will be converted to human-readable string values.
+ *   - If 'to-internal', the result will be converted to bigint string values (usually for internal use).
+ * @returns The formatted bridge result.
+ *
+ * @example
+ * ```typescript
+ * const result = await kit.bridge({
+ *   amount: '1000000',
+ *   token: 'USDC',
+ *   from: { adapter: adapter, chain: 'Ethereum' },
+ *   to: { adapter: adapter, chain: 'Base' },
+ * })
+ *
+ * // Format the bridge result into human-readable string values for the user
+ * const formattedResultHumanReadable = formatBridgeResult(result, 'to-human-readable')
+ * console.log(formattedResultHumanReadable)
+ *
+ * // Format the bridge result into bigint string values for internal use
+ * const formattedResultInternal = formatBridgeResult(result, 'to-internal')
+ * console.log(formattedResultInternal)
+ * ```
+ */ const formatBridgeResult = (result, formatDirection)=>{
+    const transform = getAmountTransformer(formatDirection);
+    return {
+        ...result,
+        amount: transform({
+            value: result.amount,
+            token: result.token
+        }),
+        ...'config' in result && result.config && Object.keys(result.config).length > 0 && {
+            config: {
+                ...result.config,
+                ...result.config.maxFee && {
+                    maxFee: transform({
+                        value: result.config.maxFee,
+                        token: result.token
+                    })
+                },
+                ...result.config.customFee && {
+                    customFee: {
+                        ...result.config.customFee,
+                        ...result.config.customFee.value && {
+                            value: transform({
+                                value: result.config.customFee.value,
+                                token: result.token
+                            })
+                        }
+                    }
+                }
+            }
+        }
+    };
+};
+
+/**
+ * Register all bridge-kit event type strings with the shared registry so
+ * callers of `withErrorTelemetry` / `emitResultStepErrorTelemetry` are
+ * compile-time checked.
+ *
+ * @internal
+ */ /**
+ * Telemetry event type identifiers for bridge-kit operations.
+ *
+ * @internal
+ */ const BRIDGE_EVENT_TYPES = {
+    BRIDGE: 'bridge_bridge',
+    RETRY: 'bridge_retry',
+    ESTIMATE: 'bridge_estimate'
+};
+/**
+ * Ordered mapping from provider step event names to telemetry event types.
+ *
+ * @remarks
+ * The order matches the CCTP v2 bridge execution sequence. During
+ * `bridge()`, completed step events are counted so the failing step
+ * can be identified by its index.
+ *
+ * @internal
+ */ const BRIDGE_STEP_EVENT_MAP = [
+    [
+        'approve',
+        'bridge_approve'
+    ],
+    [
+        'burn',
+        'bridge_burn'
+    ],
+    [
+        'fetchAttestation',
+        'bridge_fetch_attestation'
+    ],
+    [
+        'mint',
+        'bridge_mint'
+    ]
+];
+
+/**
+ * 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).
+ *
+ * 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 `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.
+ *
+ * A signed quote is short-lived (typically ~2 minutes, varying per chain) and
+ * a feature-flag-disabled source chain returns a
+ * permanent `503 SERVICE_NOT_ENABLED`, so retrying buys little and risks
+ * outliving the quote. The client therefore makes a single attempt
+ * (`maxRetries: 1`) with a 15s timeout, mirroring the reference
+ * implementation; callers refresh by requesting a new quote rather than
+ * relying on transport retries.
+ *
+ * No `headers` are set here: `pollApiWithValidation` always injects
+ * `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.
+ *
+ * @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');
+/**
+ * A 20-byte EVM address in `0x` hex.
+ *
+ * The MVP prepaid-`FORWARD` `burn/usdc` path targets EVM contracts
+ * (`TokenMessengerWithFees` / `GenericExecutor`), so `feeToken` and
+ * `destinationCaller` are constrained to EVM addresses by design. This is an
+ * intentional scope limit, not a permanent one: it can be widened to other
+ * address formats as the fee service expands to more chains.
+ */ const evmAddressSchema = z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'must be a 20-byte 0x address');
+/** Even-length `0x` hex (the empty `0x` is allowed). */ const hexSchema = z.string().regex(/^0x([a-fA-F0-9]{2})*$/, 'must be even-length 0x hex');
+/** Non-empty, even-length `0x` hex. */ const nonEmptyHexSchema = z.string().regex(/^0x([a-fA-F0-9]{2})+$/, 'must be non-empty 0x hex');
+/** A 32-byte `0x` hex hash. */ const bytes32Schema = z.string().regex(/^0x[a-fA-F0-9]{64}$/, 'must be a 32-byte 0x hash');
+/** Decimal string in minor units, allowing zero. */ const numericStringSchema = z.string().regex(/^\d+$/, 'must be a non-negative integer string');
+/** An `https:` URL, used for the optional base-URL override. */ const httpsUrlSchema = z.string().refine((value)=>{
+    try {
+        return new URL(value).protocol === 'https:';
+    } catch  {
+        return false;
+    }
+}, 'must be an https URL');
+const forwardParamsSchema = z.object({
+    hookData: hexSchema.optional(),
+    destinationCaller: evmAddressSchema.optional()
+}).strict();
+const forwardRequestSchema = z.object({
+    type: z.literal('FORWARD'),
+    params: forwardParamsSchema.optional()
+}).strict();
+const preFinalityRequestSchema = z.object({
+    type: z.literal('PRE_FINALITY')
+}).strict();
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * Validates the field types callers actually set, so a plain-JS caller passing
+ * `{ timeout: 'soon' }` is rejected at the boundary rather than failing opaquely
+ * inside the transport. Unknown keys pass through so a future `ApiPollingConfig`
+ * field is forwarded rather than silently dropped.
+ */ const apiPollingConfigSchema = z.object({
+    timeout: z.number().int().positive().optional(),
+    maxRetries: z.number().int().nonnegative().optional(),
+    retryDelay: z.number().int().nonnegative().optional(),
+    backoff: z.enum([
+        'fixed',
+        'exponential'
+    ]).optional(),
+    maxRetryDelayMs: z.number().int().positive().optional(),
+    headers: z.record(z.string()).optional()
+}).passthrough();
+/**
+ * The validatable input for {@link fetchFeeQuote}.
+ *
+ * This is the single source of truth for input validation, including the CCTP
+ * domains and the `isTestnet` environment flag. Validating `isTestnet` at
+ * runtime matters because a plain-JS caller who omits it would otherwise leave
+ * 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(),
+    amount: positiveAmountSchema,
+    feeToken: evmAddressSchema.optional(),
+    requests: feeQuoteRequestsSchema,
+    isTestnet: z.boolean(),
+    baseUrl: httpsUrlSchema.optional(),
+    config: apiPollingConfigSchema.optional()
+}).strict();
+const feeQuoteItemSchema = z.object({
+    type: z.string().min(1),
+    amount: numericStringSchema,
+    args: z.array(z.string()),
+    argsHash: bytes32Schema
+}).passthrough();
+const exchangeRatesSchema = z.object({
+    feeTokenUsd: z.string(),
+    destinationTokenUsd: z.string()
+}).passthrough();
+const metadataSchema = z.object({
+    destinationGasPrice: z.string().optional(),
+    exchangeRates: exchangeRatesSchema.optional()
+}).passthrough();
+/** The `expiry` object the Quote API nests the quote TTL under. */ const expirySchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('TIMESTAMP'),
+        expiresAt: z.number().int().nonnegative()
+    }).passthrough(),
+    z.object({
+        mode: z.literal('BLOCK_NUMBER'),
+        expiresAtBlock: z.number().int().nonnegative(),
+        blockEstimatedAt: z.number().int().nonnegative().optional()
+    }).passthrough()
+]);
+/**
+ * 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.
+    signedQuote: nonEmptyHexSchema,
+    issuedAt: z.number().int().nonnegative(),
+    // The API returns a mode-specific timestamp or source-block deadline.
+    expiry: expirySchema,
+    feeTotalAmount: numericStringSchema,
+    feeToken: evmAddressSchema,
+    nonce: numericStringSchema,
+    items: z.array(feeQuoteItemSchema),
+    metadata: metadataSchema.optional()
+}).passthrough();
+/**
+ * Validate that an unknown value is a signed fee quote.
+ *
+ * @param value - The unknown value to validate.
+ * @returns `true` when the value matches the signed-quote response shape.
+ *
+ * @example
+ * ```typescript
+ * import { isSignedFeeQuote } from '@circle-fin/provider-fee-v1'
+ *
+ * declare const payload: unknown
+ * if (isSignedFeeQuote(payload)) {
+ *   console.log(payload.feeTotalAmount)
+ * }
+ * ```
+ *
+ * @internal
+ */ function isSignedFeeQuote(value) {
+    return signedFeeQuoteSchema.safeParse(value).success;
+}
+/**
+ * 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([
+        z.string(),
+        z.array(z.string())
+    ])),
+    isTestnet: z.boolean(),
+    baseUrl: httpsUrlSchema.optional(),
+    config: apiPollingConfigSchema.optional()
+}).strict();
+const quoteExpiryStatusSchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('TIMESTAMP'),
+        expired: z.boolean(),
+        secondsRemaining: z.number().int().nonnegative(),
+        expiresAt: z.number().int().nonnegative()
+    }).passthrough(),
+    z.object({
+        mode: z.literal('BLOCK_NUMBER'),
+        expired: z.boolean(),
+        secondsRemaining: z.number().int().nonnegative(),
+        expiresAtBlock: z.number().int().nonnegative(),
+        blockEstimatedAt: z.number().int().nonnegative().optional()
+    }).passthrough()
+]);
+const validateQuoteItemSchema = z.object({
+    type: z.string().min(1),
+    argsMatch: z.boolean(),
+    amount: numericStringSchema.optional(),
+    args: z.array(z.string()).optional(),
+    argsHash: bytes32Schema.optional(),
+    computedArgsHash: bytes32Schema.optional()
+}).passthrough();
+/**
+ * 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,
+    feeTotalAmount: numericStringSchema,
+    feeToken: evmAddressSchema,
+    nonce: numericStringSchema,
+    claimable: z.boolean(),
+    // Preserve newly introduced server-side reasons as opaque strings rather
+    // than rejecting the entire safety response before the SDK is updated.
+    failedChecks: z.array(z.string().min(1)),
+    items: z.array(validateQuoteItemSchema)
+}).passthrough();
+/**
+ * Validate that an unknown value is a validate-quote result.
+ *
+ * @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 payload: unknown
+ * if (isValidateQuoteResult(payload)) {
+ *   console.log(payload.claimable, payload.failedChecks)
+ * }
+ * ```
+ *
+ * @internal
+ */ function isValidateQuoteResult(value) {
+    return validateQuoteResultSchema.safeParse(value).success;
+}
+
+/**
+ * Validate that a CCTP domain id is a non-negative integer.
+ *
+ * @param value - The domain id to validate.
+ * @param label - The parameter name, used in the error message.
+ * @returns Nothing.
+ * @throws {@link KitError} When the value is not a non-negative integer.
+ * @internal
+ */ function assertDomain(value, label) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Quote API getFeeQuote failed: ${label} must be a ` + `non-negative integer, received ${String(value)}`,
+            cause: {
+                trace: {
+                    [label]: value
+                }
+            }
+        });
+    }
+}
+/**
+ * Build the Quote API URL for a CCTP v2 USDC burn quote.
+ *
+ * Resolves the environment base URL (or an explicit `baseUrl` override) and
+ * appends the burn/usdc path with the source and destination CCTP domains.
+ * `usdc` is a fixed path literal, not a token parameter.
+ *
+ * @param params - The domains and environment selector.
+ * @returns The fully-qualified Quote API URL.
+ * @throws {@link KitError} When either domain is not a non-negative integer.
+ *
+ * @example
+ * ```typescript
+ * import { buildFeeQuoteUrl } from '@circle-fin/provider-fee-v1'
+ *
+ * const url = buildFeeQuoteUrl({
+ *   sourceDomain: 3,
+ *   destinationDomain: 26,
+ *   isTestnet: false,
+ * })
+ * // => 'https://iris-api.circle.com/v2/quote/burn/usdc/3/26'
+ * ```
+ *
+ * @internal
+ */ function buildFeeQuoteUrl(params) {
+    const { sourceDomain, destinationDomain, isTestnet, baseUrl } = params;
+    assertDomain(sourceDomain, 'sourceDomain');
+    assertDomain(destinationDomain, 'destinationDomain');
+    const resolvedBaseUrl = baseUrl ?? (isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL);
+    return new URL(`${QUOTE_BURN_USDC_PATH}/${String(sourceDomain)}/${String(destinationDomain)}`, resolvedBaseUrl).toString();
+}
+
+/**
+ * Assert that a quote's per-item fee amounts sum to its `feeTotalAmount`.
+ *
+ * A defensive integrity check on the Quote API response, enforced internally
+ * by `fetchFeeQuote`. It does not compare against the destination-side
+ * `feeExecuted`, which is expected to be zero for prepaid forward-only burns.
+ *
+ * @param quote - The signed fee quote to check.
+ * @returns Nothing.
+ * @throws {@link KitError} When the item amounts do not sum to `feeTotalAmount`.
+ * @internal
+ */ function assertFeeItemsSumToTotal(quote) {
+    const itemsTotal = quote.items.reduce((sum, item)=>sum + BigInt(item.amount), 0n);
+    const declaredTotal = BigInt(quote.feeTotalAmount);
+    if (itemsTotal !== declaredTotal) {
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `Quote API getFeeQuote failed: fee items sum ` + `(${itemsTotal.toString()}) does not equal feeTotalAmount ` + `(${declaredTotal.toString()})`,
+            cause: {
+                trace: {
+                    itemsTotal: itemsTotal.toString(),
+                    feeTotalAmount: quote.feeTotalAmount
+                }
+            }
+        });
+    }
+}
+
+/**
+ * Determine whether a Quote API error represents a disabled source chain.
+ *
+ * @param error - The error thrown by the HTTP layer.
+ * @returns `true` when the error contains the `SERVICE_NOT_ENABLED` marker.
+ * @internal
+ */ function isServiceNotEnabled(error) {
+    const body = typeof error === 'object' && error !== null && 'responseBody' in error ? error.responseBody : undefined;
+    if (typeof body === 'object' && body !== null) {
+        const fields = body;
+        const candidates = [
+            fields['errorCode'],
+            fields['code'],
+            fields['message'],
+            fields['externalMessage'],
+            fields['error']
+        ];
+        if (candidates.some((value)=>typeof value === 'string' && value.toUpperCase().includes('SERVICE_NOT_ENABLED'))) {
+            return true;
+        }
+    }
+    return getErrorMessage(error).toUpperCase().includes('SERVICE_NOT_ENABLED');
+}
+
+const SERVICE$1 = 'Quote API';
+const OPERATION$1 = 'getFeeQuote';
+/**
+ * Serialize request items for the wire body.
+ *
+ * `PRE_FINALITY` is emitted with no `params` key, and a `FORWARD` item only
+ * carries the binding fields that are present.
+ *
+ * @param requests - The request items to serialize.
+ * @returns The serialized request items.
+ * @internal
+ */ function serializeRequests(requests) {
+    return requests.map((request)=>{
+        if (request.type === 'PRE_FINALITY') {
+            return {
+                type: 'PRE_FINALITY'
+            };
+        }
+        const params = request.params;
+        if (params === undefined) {
+            return {
+                type: 'FORWARD'
+            };
+        }
+        const forwardParams = {};
+        if (params.hookData !== undefined) {
+            forwardParams.hookData = params.hookData;
+        }
+        if (params.destinationCaller !== undefined) {
+            forwardParams.destinationCaller = params.destinationCaller;
+        }
+        return {
+            type: 'FORWARD',
+            params: forwardParams
+        };
+    });
+}
+/**
+ * Fetch a signed fee quote from Circle's Quote API for a CCTP v2 USDC burn.
+ *
+ * Validates inputs, POSTs to
+ * `/v2/quote/burn/usdc/{sourceDomain}/{destinationDomain}` with a single
+ * attempt (the signed quote is short-lived), and returns the typed quote. A
+ * disabled source chain (`503 SERVICE_NOT_ENABLED`) surfaces as a fatal,
+ * non-retryable error; other failures are mapped to a {@link KitError} via the
+ * shared API error parser.
+ *
+ * @param params - The domains, amount, request items, and environment.
+ * @returns The signed fee quote.
+ * @throws {@link KitError} On invalid input, a disabled source chain, an HTTP
+ *   error, or an invalid response shape.
+ *
+ * @example
+ * ```typescript
+ * import { fetchFeeQuote } from '@circle-fin/provider-fee-v1'
+ *
+ * const quote = await fetchFeeQuote({
+ *   sourceDomain: 3,
+ *   destinationDomain: 26,
+ *   amount: '1000000',
+ *   requests: [{ type: 'FORWARD' }, { type: 'PRE_FINALITY' }],
+ *   isTestnet: false,
+ * })
+ * 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({
+        sourceDomain,
+        destinationDomain,
+        amount,
+        feeToken,
+        requests,
+        isTestnet,
+        baseUrl,
+        config
+    });
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((issue)=>`${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `${SERVICE$1} ${OPERATION$1} failed: ${detail}`,
+            cause: {
+                trace: parsed.error.issues
+            }
+        });
+    }
+    const url = baseUrl === undefined ? buildFeeQuoteUrl({
+        sourceDomain,
+        destinationDomain,
+        isTestnet
+    }) : buildFeeQuoteUrl({
+        sourceDomain,
+        destinationDomain,
+        isTestnet,
+        baseUrl
+    });
+    const body = {
+        amount,
+        feeToken: feeToken ?? NATIVE_FEE_TOKEN,
+        requests: serializeRequests(requests)
+    };
+    const pollingConfig = {
+        ...FEE_QUOTE_DEFAULT_CONFIG,
+        ...config
+    };
+    let quote;
+    try {
+        quote = await pollApiPost(url, body, isSignedFeeQuote, pollingConfig);
+    } catch (error) {
+        // Only one service-specific code (SERVICE_NOT_ENABLED) needs bespoke
+        // mapping, so it is detected inline rather than via a dedicated
+        // `parseFeeQuoteApiError` parser; everything else flows through the shared
+        // `parseApiError`. Promote to a parser if more coded errors appear.
+        if (isServiceNotEnabled(error)) {
+            throw new KitError({
+                ...InputError.UNSUPPORTED_ROUTE,
+                recoverability: 'FATAL',
+                message: `${SERVICE$1} ${OPERATION$1} failed: source chain not enabled for fee ` + `quotes (SERVICE_NOT_ENABLED)`,
+                cause: {
+                    trace: error
+                }
+            });
+        }
+        throw parseApiError(error, {
+            service: SERVICE$1,
+            operation: OPERATION$1
+        });
+    }
+    // Defense-in-depth: a self-consistent quote's per-item fees sum to the
+    // declared total. Enforced here so callers cannot forget the check.
+    assertFeeItemsSumToTotal(quote);
+    return quote;
+}
+
+const SERVICE = 'Quote API';
+const OPERATION = 'validateQuote';
+/**
+ * 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.
+ * @throws {@link KitError} When input, transport, or response validation fails.
+ *
+ * @example
+ * ```typescript
+ * import { validateQuote } from '@circle-fin/provider-fee-v1'
+ *
+ * const result = await validateQuote({
+ *   sourceDomain: 3,
+ *   // The exact function + arguments, in ABI order, that will be burned on-chain.
+ *   abiSignature:
+ *     'depositForBurnWithHookAndFees(uint256,uint32,bytes32,address,bytes32,bytes,(bytes,address))',
+ *   args: [
+ *     '1000000',
+ *     '26',
+ *     '0x0000000000000000000000001111111111111111111111111111111111111111',
+ *     '0x2222222222222222222222222222222222222222',
+ *     '0x0000000000000000000000000000000000000000000000000000000000000000',
+ *     '0x636374702d666f72776172640000000000000000000000000000000000000000',
+ *     ['0x01abcd', '0x3333333333333333333333333333333333333333'],
+ *   ],
+ *   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) {
+        const detail = parsed.error.issues.map((issue)=>`${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new KitError({
+            ...InputError.VALIDATION_FAILED,
+            recoverability: 'FATAL',
+            message: `${SERVICE} ${OPERATION} failed: ${detail}`,
+            cause: {
+                trace: parsed.error.issues
+            }
+        });
+    }
+    const { sourceDomain, abiSignature, args, isTestnet, baseUrl } = parsed.data;
+    // `config` was validated by the schema above; spread the caller's original,
+    // precisely typed `Partial<ApiPollingConfig>` so the merged polling config
+    // stays assignable under `exactOptionalPropertyTypes`.
+    const pollingConfig = {
+        ...FEE_QUOTE_DEFAULT_CONFIG,
+        ...params.config
+    };
+    const resolvedBaseUrl = baseUrl ?? (isTestnet ? IRIS_API_SANDBOX_BASE_URL : IRIS_API_BASE_URL);
+    const url = new URL(`${QUOTE_VALIDATE_USDC_PATH}/${String(sourceDomain)}`, resolvedBaseUrl).toString();
+    try {
+        return await pollApiPost(url, {
+            abiSignature,
+            args
+        }, isValidateQuoteResult, pollingConfig);
+    } catch (error) {
+        if (isServiceNotEnabled(error)) {
+            throw new KitError({
+                ...InputError.UNSUPPORTED_ROUTE,
+                recoverability: 'FATAL',
+                message: `${SERVICE} ${OPERATION} failed: source chain not enabled for ` + `quote validation (SERVICE_NOT_ENABLED)`,
+                cause: {
+                    trace: error
+                }
+            });
+        }
+        throw parseApiError(error, {
+            service: SERVICE,
+            operation: OPERATION
+        });
+    }
+}
+
+/** Refresh timestamp quotes this many seconds before submission. */ const QUOTE_EXPIRY_SAFETY_SECONDS = 30;
+/** ABI signature validated by the Quote API before source-chain submission. */ const BURN_WITH_FEES_ABI_SIGNATURE = 'depositForBurnWithHookAndFees(uint256,uint32,bytes32,address,bytes32,bytes,(bytes,address))';
+/** Unrestricted CCTP destination caller used by the forwarding relayer. */ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+function isQuoteNearEstimatedExpiry(quote) {
+    const currentSeconds = Math.floor(Date.now() / 1_000);
+    const expiresAt = quote.expiry.mode === 'TIMESTAMP' ? quote.expiry.expiresAt : quote.expiry.blockEstimatedAt;
+    // A BLOCK_NUMBER quote may omit the advisory `blockEstimatedAt` estimate; when
+    // it is absent, skip this wall-clock pre-check and defer to the authoritative
+    // source-chain-tip validation performed downstream.
+    if (expiresAt === undefined) {
+        return false;
+    }
+    return expiresAt <= currentSeconds + QUOTE_EXPIRY_SAFETY_SECONDS;
+}
+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");
+    }
+    if (config.customFee !== undefined) {
+        throw createValidationFailedError$1('config.customFee', config.customFee, "Custom fees are not supported with feePayment: 'source'. Remove the " + 'per-call customFee or the kit-level custom fee policy for this route.');
+    }
+}
+function buildQuoteBinding(params) {
+    assertSourceFeeRoute(params);
+    const mintRecipient = params.destination.recipientAddress ?? params.destination.address;
+    const hookData = buildForwardingHookData();
+    const requests = [
+        {
+            type: 'FORWARD',
+            params: {
+                hookData,
+                destinationCaller: ZERO_ADDRESS
+            }
+        }
+    ];
+    if ((params.config.transferSpeed ?? TransferSpeed.FAST) === TransferSpeed.FAST) {
+        requests.push({
+            type: 'PRE_FINALITY'
+        });
+    }
+    return {
+        sourceDomain: params.source.chain.cctp.domain,
+        destinationDomain: params.destination.chain.cctp.domain,
+        isTestnet: params.source.chain.isTestnet,
+        amount: params.amount,
+        mintRecipient,
+        hookData,
+        destinationCaller: ZERO_ADDRESS,
+        feeToken: params.source.chain.usdcAddress,
+        requests
+    };
+}
+async function fetchBoundQuote(binding) {
+    try {
+        const quote = await fetchFeeQuote({
+            sourceDomain: binding.sourceDomain,
+            destinationDomain: binding.destinationDomain,
+            amount: binding.amount,
+            feeToken: binding.feeToken,
+            requests: binding.requests,
+            isTestnet: binding.isTestnet
+        });
+        if (quote.feeToken.toLowerCase() !== binding.feeToken.toLowerCase()) {
+            throw createValidationFailedError$1('feeToken', quote.feeToken, 'Fee Service must return source-chain USDC for source-fee bridging');
+        }
+        return quote;
+    } catch (error) {
+        if (isRateLimitError(error)) {
+            throw new KitError({
+                ...RateLimitError.RATE_LIMIT_EXCEEDED,
+                recoverability: 'RETRYABLE',
+                message: 'Fee Service rate limit exceeded. Retry with caller-managed exponential backoff; Bridge Kit does not retry signed quote requests automatically.',
+                cause: {
+                    trace: error
+                }
+            });
+        }
+        throw error;
+    }
+}
+async function fetchSubmissionQuote(binding) {
+    let quote = await fetchBoundQuote(binding);
+    if (isQuoteNearEstimatedExpiry(quote)) {
+        quote = await fetchBoundQuote(binding);
+    }
+    if (isQuoteNearEstimatedExpiry(quote)) {
+        throw createValidationFailedError$1('quote', undefined, 'Fee Service returned a quote too close to expiry for safe submission');
+    }
+    return quote;
+}
+async function validateBoundQuote(binding, signedQuote, refundAddress) {
+    return validateQuote({
+        sourceDomain: binding.sourceDomain,
+        abiSignature: BURN_WITH_FEES_ABI_SIGNATURE,
+        args: [
+            binding.amount,
+            String(binding.destinationDomain),
+            padAddressToBytes32(binding.mintRecipient),
+            binding.feeToken,
+            padAddressToBytes32(binding.destinationCaller),
+            binding.hookData,
+            [
+                signedQuote,
+                refundAddress
+            ]
+        ],
+        isTestnet: binding.isTestnet
+    });
+}
+function isValidationSafe(binding, signedQuote, validation, expectedQuote) {
+    return validation.claimable && !validation.expiry.expired && validation.expiry.secondsRemaining > QUOTE_EXPIRY_SAFETY_SECONDS && validation.signedQuote.toLowerCase() === signedQuote.toLowerCase() && validation.feeToken.toLowerCase() === binding.feeToken.toLowerCase() && (expectedQuote === undefined || validation.feeTotalAmount === expectedQuote.feeTotalAmount && validation.nonce === expectedQuote.nonce);
+}
+function unsafeQuoteError(validation) {
+    const detail = validation.failedChecks.length > 0 ? ` (${validation.failedChecks.join(', ')})` : '';
+    return createValidationFailedError$1('quote', undefined, `The fee quote is not safe for submission${detail}; ` + 'call estimate again to obtain a valid quote');
+}
+function toExecutionFeeQuote(quote) {
+    return {
+        signedQuote: quote.signedQuote,
+        feeToken: quote.feeToken,
+        feeTotalAmount: quote.feeTotalAmount
+    };
+}
+function toFeeItems(quote) {
+    return quote.items.map((item)=>({
+            type: item.type,
+            amount: formatUnits(item.amount, 6),
+            args: item.args,
+            argsHash: item.argsHash
+        }));
+}
+/**
+ * Estimate a source-fee bridge using a source-denominated signed fee quote.
+ *
+ * @internal
+ */ async function estimateSourceFeeBridge(params) {
+    const binding = buildQuoteBinding(params);
+    const quote = await fetchSubmissionQuote(binding);
+    const feeTotal = formatUnits(quote.feeTotalAmount, 6);
+    return {
+        token: 'USDC',
+        amount: formatUnits(params.amount, 6),
+        source: {
+            address: params.source.address,
+            chain: params.source.chain.chain
+        },
+        destination: {
+            address: params.destination.address,
+            chain: params.destination.chain.chain,
+            ...params.destination.recipientAddress !== undefined && {
+                recipientAddress: params.destination.recipientAddress
+            }
+        },
+        gasFees: [],
+        fees: quote.items.map((item)=>({
+                type: item.type === 'FORWARD' ? 'forwarder' : 'provider',
+                token: 'USDC',
+                amount: formatUnits(item.amount, 6)
+            })),
+        amountReceived: formatUnits(params.amount, 6),
+        feeTotal,
+        feeItems: toFeeItems(quote),
+        totalDebit: formatUnits((BigInt(params.amount) + BigInt(quote.feeTotalAmount)).toString(), 6),
+        quoteExpiry: quote.expiry,
+        quote: quote.signedQuote
+    };
+}
+async function readAllowance(params, delegate) {
+    const operationContext = {
+        chain: params.source.chain,
+        address: params.source.address
+    };
+    const prepared = await params.source.adapter.prepareAction('usdc.allowance', {
+        walletAddress: params.source.address,
+        delegate
+    }, operationContext);
+    return BigInt(String(await prepared.execute()));
+}
+async function executeAndConfirm(request, params, provider) {
+    const txHash = await request.execute();
+    const data = await provider.waitForTransaction(params.source.adapter, txHash, params.source.chain);
+    return {
+        txHash,
+        data
+    };
+}
+async function prepareAndPreflight(params, binding, quote, provider) {
+    assertSourceFeeRoute(params);
+    const totalDebit = (BigInt(params.amount) + BigInt(quote.feeTotalAmount)).toString();
+    const operationContext = {
+        chain: params.source.chain,
+        address: params.source.address
+    };
+    await validateBalanceForTransaction({
+        adapter: params.source.adapter,
+        amount: totalDebit,
+        token: 'USDC',
+        tokenAddress: params.source.chain.usdcAddress,
+        operationContext
+    });
+    const prepared = await provider.burnWithFees({
+        source: params.source,
+        destinationChain: params.destination.chain,
+        amount: params.amount,
+        mintRecipient: binding.mintRecipient,
+        destinationCaller: binding.destinationCaller,
+        hookData: binding.hookData,
+        claim: {
+            signedQuote: quote.signedQuote,
+            refundAddress: params.source.address
+        },
+        feeToken: quote.feeToken,
+        feeTotalAmount: quote.feeTotalAmount
+    });
+    const wrapper = resolveCCTPV2ContractAddress(params.source.chain, 'tokenMessengerWithFees');
+    const allowance = await readAllowance(params, wrapper);
+    if (allowance >= BigInt(totalDebit)) {
+        return {
+            prepared,
+            approveStep: {
+                name: 'approve',
+                state: 'noop'
+            }
         };
     }
-    /**
-   * Waits for a transaction to be mined and confirmed on the blockchain.
-   *
-   * This method should block until the transaction is confirmed on the blockchain.
-   *
-   * @param adapter - The adapter to use for transaction waiting
-   * @param txHash - The hash of the transaction to wait for
-   * @param chain - The chain definition where the transaction was executed
-   * @param config - Optional configuration for transaction waiting (confirmations, timeout)
-   * @returns The hash of the confirmed transaction
-   * @example
-   * ```typescript
-   * const provider = new CCTPV2BridgingProvider()
-   * const txHash = await provider.waitForTransaction(
-   *   adapter,
-   *   '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
-   *   Ethereum,
-   * )
-   * console.log('Transaction confirmed:', txHash)
-   * ```
-   */ async waitForTransaction(adapter, txHash, chain, config) {
-        return adapter.waitForTransaction(txHash, config, chain);
+    let lastApproval;
+    for (const approval of prepared.approvals){
+        lastApproval = await executeAndConfirm(approval, params, provider);
     }
-}
-
-/**
- * The default providers that will be used in addition to the providers provided
- * to the BridgeKit constructor.
- *
- * @param config - Optional configuration forwarded to the default providers
- * @returns The default bridging providers
- */ const getDefaultProviders = (config = {})=>[
-        new CCTPV2BridgingProvider(config.headers ? {
-            headers: config.headers
-        } : {})
-    ];
-
-/**
- * A helper function to get a function that transforms an amount into a human-readable string or a bigint string.
- * @param formatDirection - The direction to format the amount in.
- * @returns A function that transforms an amount into a human-readable string or a bigint string.
- */ const getAmountTransformer = (formatDirection)=>formatDirection === 'to-human-readable' ? (params)=>formatAmount(params) : (params)=>parseAmount(params).toString();
-/**
- * Format the bridge result into human-readable string values for the user or bigint string values for internal use.
- *
- * @typeParam T - The specific result type (must extend BridgeResult or EstimateResult). Preserves the exact type passed in.
- * @param result - The bridge result to format.
- * @param formatDirection - The direction to format the result in.
- *   - If 'to-human-readable', the result will be converted to human-readable string values.
- *   - If 'to-internal', the result will be converted to bigint string values (usually for internal use).
- * @returns The formatted bridge result.
- *
- * @example
- * ```typescript
- * const result = await kit.bridge({
- *   amount: '1000000',
- *   token: 'USDC',
- *   from: { adapter: adapter, chain: 'Ethereum' },
- *   to: { adapter: adapter, chain: 'Base' },
- * })
- *
- * // Format the bridge result into human-readable string values for the user
- * const formattedResultHumanReadable = formatBridgeResult(result, 'to-human-readable')
- * console.log(formattedResultHumanReadable)
- *
- * // Format the bridge result into bigint string values for internal use
- * const formattedResultInternal = formatBridgeResult(result, 'to-internal')
- * console.log(formattedResultInternal)
- * ```
- */ const formatBridgeResult = (result, formatDirection)=>{
-    const transform = getAmountTransformer(formatDirection);
     return {
-        ...result,
-        amount: transform({
-            value: result.amount,
-            token: result.token
-        }),
-        ...'config' in result && result.config && Object.keys(result.config).length > 0 && {
-            config: {
-                ...result.config,
-                ...result.config.maxFee && {
-                    maxFee: transform({
-                        value: result.config.maxFee,
-                        token: result.token
-                    })
-                },
-                ...result.config.customFee && {
-                    customFee: {
-                        ...result.config.customFee,
-                        ...result.config.customFee.value && {
-                            value: transform({
-                                value: result.config.customFee.value,
-                                token: result.token
-                            })
-                        }
-                    }
-                }
+        prepared,
+        approveStep: {
+            name: 'approve',
+            state: 'success',
+            data: lastApproval?.data,
+            ...lastApproval?.txHash !== undefined && {
+                txHash: lastApproval.txHash,
+                explorerUrl: buildExplorerUrl(params.source.chain, lastApproval.txHash)
             }
         }
     };
-};
-
-/**
- * Register all bridge-kit event type strings with the shared registry so
- * callers of `withErrorTelemetry` / `emitResultStepErrorTelemetry` are
- * compile-time checked.
- *
- * @internal
- */ /**
- * Telemetry event type identifiers for bridge-kit operations.
- *
- * @internal
- */ const BRIDGE_EVENT_TYPES = {
-    BRIDGE: 'bridge_bridge',
-    RETRY: 'bridge_retry',
-    ESTIMATE: 'bridge_estimate'
-};
+}
+async function resolveExecutionQuote(binding, suppliedQuote, refundAddress) {
+    if (suppliedQuote === undefined) {
+        const fetchedQuote = await fetchSubmissionQuote(binding);
+        return {
+            quote: toExecutionFeeQuote(fetchedQuote),
+            fetchedQuote
+        };
+    }
+    const validation = await validateBoundQuote(binding, suppliedQuote, refundAddress);
+    if (!isValidationSafe(binding, suppliedQuote, validation)) {
+        throw unsafeQuoteError(validation);
+    }
+    return {
+        quote: toExecutionFeeQuote(validation),
+        fetchedQuote: undefined
+    };
+}
 /**
- * Ordered mapping from provider step event names to telemetry event types.
- *
- * @remarks
- * The order matches the CCTP v2 bridge execution sequence. During
- * `bridge()`, completed step events are counted so the failing step
- * can be identified by its index.
+ * Execute a source-fee bridge while preserving receive-exact semantics.
  *
  * @internal
- */ const BRIDGE_STEP_EVENT_MAP = [
-    [
-        'approve',
-        'bridge_approve'
-    ],
-    [
-        'burn',
-        'bridge_burn'
-    ],
-    [
-        'fetchAttestation',
-        'bridge_fetch_attestation'
-    ],
-    [
-        'mint',
-        'bridge_mint'
-    ]
-];
+ */ async function executeSourceFeeBridge(rawParams, params, provider) {
+    // Narrows `params` to the CCTP v2 route type for the rest of this function.
+    // buildQuoteBinding asserts too, but that narrows its own scope, not this one.
+    assertSourceFeeRoute(params);
+    const binding = buildQuoteBinding(params);
+    const suppliedQuote = rawParams.quote;
+    let { quote, fetchedQuote } = await resolveExecutionQuote(binding, suppliedQuote, params.source.address);
+    let { prepared, approveStep } = await prepareAndPreflight(params, binding, quote, provider);
+    // Validate against the current source-chain tip after approval confirmation.
+    // BLOCK_NUMBER expiries cannot be checked safely with wall-clock time alone.
+    let validation = await validateBoundQuote(binding, quote.signedQuote, params.source.address);
+    if (!isValidationSafe(binding, quote.signedQuote, validation, fetchedQuote)) {
+        if (suppliedQuote === undefined) {
+            fetchedQuote = await fetchSubmissionQuote(binding);
+            quote = toExecutionFeeQuote(fetchedQuote);
+            const refreshedPreparation = await prepareAndPreflight(params, binding, quote, provider);
+            prepared = refreshedPreparation.prepared;
+            if (refreshedPreparation.approveStep.state !== 'noop') {
+                approveStep = refreshedPreparation.approveStep;
+            }
+            validation = await validateBoundQuote(binding, quote.signedQuote, params.source.address);
+            if (!isValidationSafe(binding, quote.signedQuote, validation, fetchedQuote)) {
+                throw unsafeQuoteError(validation);
+            }
+        } else {
+            throw unsafeQuoteError(validation);
+        }
+    }
+    // Surface the same step events as the standard bridge() path so
+    // kit.on('approve'|'burn'|'mint', ...) handlers fire for source-fee bridges.
+    if (approveStep.state !== 'noop') {
+        provider.emitBridgeStep('approve', approveStep);
+    }
+    const burn = await executeAndConfirm(prepared.burn, params, provider);
+    const burnStep = {
+        name: 'burn',
+        state: 'success',
+        txHash: burn.txHash,
+        data: burn.data,
+        explorerUrl: buildExplorerUrl(params.source.chain, burn.txHash)
+    };
+    provider.emitBridgeStep('burn', burnStep);
+    const resultBase = {
+        amount: params.amount,
+        token: 'USDC',
+        config: params.config,
+        provider: provider.name,
+        source: {
+            address: params.source.address,
+            chain: params.source.chain
+        },
+        destination: {
+            address: params.destination.address,
+            chain: params.destination.chain,
+            ...params.destination.recipientAddress !== undefined && {
+                recipientAddress: params.destination.recipientAddress
+            },
+            useForwarder: true
+        }
+    };
+    const attestation = await provider.fetchRelayerMint(params.source, burn.txHash);
+    const forwardTxHash = attestation.forwardTxHash;
+    // The burn already moved funds. If the relayer confirms without a
+    // destination hash, surface an error-state result that preserves the burn
+    // step (so `retry()` can resume the mint) instead of throwing and discarding
+    // the completed burn.
+    if (typeof forwardTxHash !== 'string' || forwardTxHash.trim() === '') {
+        const mintStep = {
+            name: 'mint',
+            state: 'error',
+            forwarded: true,
+            errorCategory: 'failed_offchain',
+            errorMessage: 'Relayer confirmation did not include a destination transaction hash'
+        };
+        provider.emitBridgeStep('mint', mintStep);
+        return {
+            ...resultBase,
+            state: 'error',
+            steps: [
+                approveStep,
+                burnStep,
+                mintStep
+            ]
+        };
+    }
+    const mintStep = {
+        name: 'mint',
+        state: 'success',
+        forwarded: true,
+        txHash: forwardTxHash,
+        explorerUrl: buildExplorerUrl(params.destination.chain, forwardTxHash)
+    };
+    provider.emitBridgeStep('mint', mintStep);
+    return {
+        ...resultBase,
+        state: 'success',
+        steps: [
+            approveStep,
+            burnStep,
+            mintStep
+        ]
+    };
+}
 
 /** SDK name used in telemetry payloads. */ const SDK_NAME = resolveKitSdkName(pkg$3.name);
 /**
@@ -17141,11 +19936,18 @@ function assertCCTPV2Config(config) {
             this.validateNetworkCompatibility(resolvedParams);
             // Merge the custom fee config into the resolved params
             const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
-            // Find a provider that supports this route
-            const provider = this.findProviderForRoute(finalResolvedParams);
-            // Execute the transfer using the provider
-            // Format the bridge result into human-readable string values for the user
-            const result = formatBridgeResult(await provider.bridge(finalResolvedParams), 'to-human-readable');
+            let result;
+            // Execute the explicit source-fee path without changing legacy
+            // useForwarder behavior for callers that did not opt in.
+            if (params.config?.feePayment === 'source') {
+                const sourceFeeProvider = this.findSourceFeeProvider(finalResolvedParams);
+                result = formatBridgeResult(await executeSourceFeeBridge(params, finalResolvedParams, sourceFeeProvider), 'to-human-readable');
+            } else {
+                // Find a provider that supports this route
+                const provider = this.findProviderForRoute(finalResolvedParams);
+                // Execute the transfer using the provider and format the result.
+                result = formatBridgeResult(await provider.bridge(finalResolvedParams), 'to-human-readable');
+            }
             // Emit error telemetry when the provider returns an error state
             // (provider records step failures in the result instead of throwing).
             if (result.state === 'error') {
@@ -17268,42 +20070,7 @@ function assertCCTPV2Config(config) {
             tokenIn: result.token
         });
     }
-    /**
-   * Estimate the cost and fees for a cross-chain USDC bridge operation.
-   *
-   * This method calculates the expected gas fees and protocol costs for bridging
-   * without actually executing the transaction. It performs the same validation
-   * as the bridge method but stops before execution.
-   *
-   * @param params - The bridge parameters for cost estimation, including optional invocation metadata
-   * @returns Promise resolving to detailed cost breakdown including gas estimates
-   * @throws {KitError} When the parameters are invalid.
-   * @throws {UnsupportedRouteError} When the route is not supported.
-   *
-   * @example
-   * ```typescript
-   * // Basic usage
-   * const estimate = await kit.estimate({
-   *   from: { adapter: adapter, chain: 'Ethereum' },
-   *   to: { adapter: adapter, chain: 'Base' },
-   *   amount: '10.50',
-   *   token: 'USDC'
-   * })
-   * console.log('Estimated cost:', estimate.totalCost)
-   *
-   * // With custom invocation metadata
-   * const estimate = await kit.estimate({
-   *   from: { adapter: adapter, chain: 'Ethereum' },
-   *   to: { adapter: adapter, chain: 'Base' },
-   *   amount: '10.50',
-   *   token: 'USDC',
-   *   invocationMeta: {
-   *     traceId: 'custom-trace-id',
-   *     callers: [{ type: 'app', name: 'MyDApp', version: '1.0.0' }],
-   *   },
-   * })
-   * ```
-   */ async estimate(params) {
+    async estimate(params) {
         return withErrorTelemetry(async ()=>{
             // First validate the parameters
             assertBridgeParams(params, bridgeParamsWithChainIdentifierSchema);
@@ -17313,6 +20080,10 @@ function assertCCTPV2Config(config) {
             this.validateNetworkCompatibility(resolvedParams);
             // Merge the custom fee config into the resolved params
             const finalResolvedParams = await this.mergeCustomFeeConfig(resolvedParams);
+            if (params.config?.feePayment === 'source') {
+                this.findSourceFeeProvider(finalResolvedParams);
+                return estimateSourceFeeBridge(finalResolvedParams);
+            }
             // Find a provider that supports this route
             const provider = this.findProviderForRoute(finalResolvedParams);
             // Estimate the transfer using the provider and format amounts to human-readable strings
@@ -17361,6 +20132,9 @@ function assertCCTPV2Config(config) {
    * // Get only chains that support forwarding
    * const forwarderChains = kit.getSupportedChains({ forwarderSupported: true })
    *
+   * // Get only chains that can pay fees on the source chain (receive-exact)
+   * const sourceFeeChains = kit.getSupportedChains({ sourceFeeSupported: true })
+   *
    * console.log('Supported chains:')
    * allChains.forEach(chain => {
    *   console.log(`- ${chain.name} (${chain.type})`)
@@ -17409,6 +20183,10 @@ function assertCCTPV2Config(config) {
                 return options.forwarderSupported ? fs.source || fs.destination : !fs.source && !fs.destination;
             });
         }
+        // Apply source-paid ("receive-exact") fee support filter if provided
+        if (options?.sourceFeeSupported !== undefined) {
+            chains = chains.filter((chain)=>hasSourceFeeSupport(chain) === options.sourceFeeSupported);
+        }
         return chains;
     }
     /**
@@ -17443,6 +20221,20 @@ function assertCCTPV2Config(config) {
         return provider;
     }
     /**
+   * Find the default CCTP v2 provider for a source-fee forwarding route.
+   *
+   * @param params - The resolved provider parameters.
+   * @returns The CCTP v2 provider that supports the forwarded route.
+   * @throws {UnsupportedRouteError} When no source-fee provider supports the route.
+   * @internal
+   */ findSourceFeeProvider(params) {
+        const provider = this.providers.find((candidate)=>candidate instanceof CCTPV2BridgingProvider && candidate.supportsRoute(params.source.chain, params.destination.chain, params.token, true));
+        if (!(provider instanceof CCTPV2BridgingProvider)) {
+            throw createUnsupportedRouteError(params.source.chain.name, params.destination.chain.name);
+        }
+        return provider;
+    }
+    /**
    * Merge custom fee configuration into provider parameters.
    *
    * Prioritizes any custom fee configuration already present on the
@@ -17651,7 +20443,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.5.2";
+var version$1 = "1.6.1";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -17665,7 +20457,7 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
  * Catches obviously malformed addresses at parse time; chain-specific validation
  * is performed in buildServiceParams.
  */ const destinationAddressSchema = z.union([
-    evmAddressSchema,
+    evmAddressSchema$1,
     solanaAddressSchema
 ]);
 /**
@@ -17711,9 +20503,16 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
         message: 'stopLimit must be greater than 0'
     }).optional(),
     customFee: serviceSwapCustomFeeSchema.optional(),
+    apiKey: z.string({
+        invalid_type_error: 'apiKey must be a string'
+    })// Tolerate '' so the `process.env.CIRCLE_API_KEY ?? ''` idiom falls back to
+    // kitKey via resolveApiKey instead of being rejected here.
+    .optional(),
     kitKey: z.string({
         invalid_type_error: 'kitKey must be a string'
-    }).min(1, 'kitKey must be a non-empty string').optional(),
+    })// Tolerate '' so an unset kit-key env var yields the permissionless path,
+    // matching buildServiceParams (which already omits an empty credential).
+    .optional(),
     provider: z.string({
         invalid_type_error: 'provider must be a string'
     }).min(1, 'provider must be a non-empty string').optional(),
@@ -17886,6 +20685,41 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
  *
  * @internal
  */ const MAX_RATE_ADDRESSES_PER_REQUEST = 100;
+/**
+ * Environment prefixes carried by Circle platform API keys.
+ *
+ * A Circle API key is `<ENV>_API_KEY:<keyId>:<keySecret>`, where `<ENV>` is one
+ * of these prefixes.
+ *
+ * @internal
+ */ const API_KEY_ENV_PREFIXES = [
+    'TEST',
+    'LIVE',
+    'SAND',
+    'SANDBOX',
+    'SMOK',
+    'PROD',
+    'STAG',
+    'DEV'
+];
+/**
+ * Accepted credential formats for Stablecoin Service authentication.
+ *
+ * Matches a Circle platform API key (`<ENV>_API_KEY:<keyId>:<keySecret>`) and
+ * the legacy kit key (`KIT_KEY:<keyId>:<keySecret>`). API keys are the
+ * recommended credential; kit keys remain accepted as the legacy path.
+ *
+ * @remarks
+ * This is a local pre-flight check, not the authority — the Stablecoin Service
+ * validates the credential and answers 401 when it rejects one. The prefix list
+ * is therefore deliberately permissive: a valid key carrying a prefix this SDK
+ * has not been taught about should reach the service and be judged there rather
+ * than be refused locally, since refusing locally is indistinguishable from an
+ * outage to the caller. Kept as the single source of truth so the pattern is
+ * not restated per call site.
+ *
+ * @internal
+ */ const API_KEY_PATTERN = new RegExp(`^(?:KIT_KEY|(?:${API_KEY_ENV_PREFIXES.join('|')})_API_KEY)` + ':[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$');
 
 /**
  * Zod schema for validating stop limits.
@@ -17954,13 +20788,14 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
 /**
  * Zod schema for validating API keys.
  *
- * Validates that the API key is a valid API key format.
+ * Accepts a Circle platform API key (`<ENV>_API_KEY:<keyId>:<keySecret>`) and
+ * the legacy kit key (`KIT_KEY:<keyId>:<keySecret>`).
  *
  * @example
  * ```typescript
  * import { apiKeySchema } from '@core/service-client'
  *
- * const result = apiKeySchema.safeParse('KIT_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
+ * const result = apiKeySchema.safeParse('TEST_API_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
  * if (!result.success) {
  *   console.error('Invalid API key format:', result.error.issues)
  * }
@@ -17968,7 +20803,7 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
  */ const apiKeySchema = z.string({
     required_error: 'API key is required',
     invalid_type_error: 'Invalid API key format'
-}).regex(/^KIT_KEY:[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$/, 'Invalid API key format');
+}).regex(API_KEY_PATTERN, 'Invalid API key format');
 /**
  * Zod schema for platform fees configuration.
  *
@@ -18407,6 +21242,40 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     transaction: createSwapTransactionSchema
 });
 
+/**
+ * Resolve the credential to authenticate a Stablecoin Service request with.
+ *
+ * `apiKey` is the supported field; `kitKey` is the deprecated alias kept for
+ * existing integrations. When both are supplied `apiKey` wins, so a caller
+ * migrating field-by-field cannot be silently pinned to a stale credential.
+ *
+ * An empty-string value is treated as absent on either field. Without this, the
+ * common `process.env.CIRCLE_API_KEY ?? ''` idiom (which yields `''` when the
+ * variable is unset) would either shadow a working `kitKey` or, on a bare
+ * `kitKey: ''`, reach downstream validation as an invalid credential instead of
+ * falling through to the permissionless path.
+ *
+ * @param source - Object carrying either credential field, or neither.
+ * @returns The credential to use, or `undefined` for the permissionless
+ *   (keyless) path.
+ *
+ * @example
+ * ```typescript
+ * import { resolveApiKey } from '@core/service-client'
+ *
+ * resolveApiKey({ apiKey: 'TEST_API_KEY:id:secret' }) // 'TEST_API_KEY:id:secret'
+ * resolveApiKey({ kitKey: 'KIT_KEY:id:secret' }) // 'KIT_KEY:id:secret'
+ * resolveApiKey({ apiKey: '', kitKey: 'KIT_KEY:id:secret' }) // 'KIT_KEY:id:secret'
+ * resolveApiKey({ kitKey: '' }) // undefined
+ * resolveApiKey({}) // undefined
+ * ```
+ */ const resolveApiKey = (source)=>{
+    // Treat an empty-string value as absent on either field so the
+    // `env ?? ''` idiom falls through to the next credential (or permissionless).
+    const normalize = (value)=>value !== undefined && value !== '' ? value : undefined;
+    return normalize(source.apiKey) ?? normalize(source.kitKey);
+};
+
 /**
  * Zod schema for validating EVM adapter capabilities.
  *
@@ -18836,7 +21705,7 @@ const abiParameterSchema = z.object({
  */ z.object({
     type: z.literal('evm'),
     abi: abiSchema,
-    address: evmAddressSchema,
+    address: evmAddressSchema$1,
     functionName: z.string({
         required_error: 'Function name is required',
         invalid_type_error: 'Function name must be a string'
@@ -18873,7 +21742,7 @@ const abiParameterSchema = z.object({
  * }
  * ```
  */ z.object({
-    address: evmAddressSchema,
+    address: evmAddressSchema$1,
     value: z.bigint({
         required_error: 'Value is required for native transfers',
         invalid_type_error: 'Value must be a bigint'
@@ -18959,7 +21828,7 @@ z.object({
     signature: evmSignatureSchema,
     tokenInputs: z.array(z.object({
         permitType: z.nativeEnum(PermitType),
-        token: evmAddressSchema,
+        token: evmAddressSchema$1,
         amount: z.bigint().refine((value)=>value >= 0n, {
             message: 'amount must be a non-negative bigint'
         }),
@@ -19379,7 +22248,7 @@ const optionalSwapChainIdentifierField = swapChainIdentifierField.optional();
     /**
      * Fee recipient address (required).
      * Must be a valid EVM address or Solana address.
-     */ recipientAddress: z.string().refine((value)=>evmAddressSchema.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
+     */ recipientAddress: z.string().refine((value)=>evmAddressSchema$1.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
         message: 'recipientAddress must be a valid blockchain address: EVM (0x + 40 hex chars) or Solana (base58, 32-44 chars)'
     })
 }).strict();
@@ -19391,7 +22260,8 @@ const optionalSwapChainIdentifierField = swapChainIdentifierField.optional();
  * - slippageBps: Optional positive number for slippage tolerance
  * - stopLimit: Optional decimal string for minimum output
  * - customFee: Optional fee configuration
- * - kitKey: Optional string identifier
+ * - apiKey: Optional credential string
+ * - kitKey: Optional credential string (deprecated alias for apiKey)
  */ const swapConfigSchema = z.object({
     allowanceStrategy: allowanceStrategySchema.optional(),
     slippageBps: z.number().int().min(0).optional(),
@@ -19401,11 +22271,12 @@ const optionalSwapChainIdentifierField = swapChainIdentifierField.optional();
         attributeName: 'stopLimit'
     })(z.string())).optional(),
     customFee: swapCustomFeeSchema.optional(),
+    apiKey: z.string().optional(),
     kitKey: z.string().optional()
 });
 const swapDestinationSchema = z.object({
     chain: optionalSwapChainIdentifierField,
-    recipientAddress: z.string().refine((value)=>evmAddressSchema.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
+    recipientAddress: z.string().refine((value)=>evmAddressSchema$1.safeParse(value).success || solanaAddressSchema.safeParse(value).success, {
         message: 'recipientAddress must be a valid blockchain address: EVM (0x + 40 hex chars) or Solana (base58, 32-44 chars)'
     }).optional()
 }).strict();
@@ -19594,7 +22465,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.5.1";
+var version = "1.6.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -19666,7 +22537,7 @@ function isNonNegativeBigIntLike(value) {
     }
 }
 const hexSignatureSchema = evmSignatureSchema;
-const hexAddressSchema = evmAddressSchema;
+const hexAddressSchema = evmAddressSchema$1;
 // '0x' prefix + 32 bytes * 2 hex chars.
 const BYTES32_HEX_LENGTH = 66;
 const bridgeFeeTokenSchema = hexAddressSchema;
@@ -20571,7 +23442,7 @@ createTokenRegistry();
  * fast instead of round-tripping to the service.
  *
  * @internal
- */ const recipientEvmAddressSchema = evmAddressSchema.refine((address)=>!ZERO_EVM_ADDRESS_REGEX.test(address), 'address must not be the zero address').refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
+ */ const recipientEvmAddressSchema = evmAddressSchema$1.refine((address)=>!ZERO_EVM_ADDRESS_REGEX.test(address), 'address must not be the zero address').refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
 /**
  * Schema for the adapter context within earn operations.
  *
@@ -20603,19 +23474,39 @@ const sourceAdapterContextSchema = z.object({
 /**
  * Schema for the EarnConfig options.
  *
- * Validate the optional Kit Key field using the standard `apiKeySchema`
- * format (`KIT_KEY:<keyId>:<keySecret>`). When omitted, the SDK
- * operates in permissionless mode. `baseUrl` overrides the Earn Service
- * endpoint (e.g. staging); `batchTransactions: false` opts out of atomic
- * batched execution. Both are forwarded to the provider, so this `.strict()`
- * schema must accept them or a valid config object is rejected.
+ * Validate the *resolved* credential using the standard `apiKeySchema` format
+ * (`<ENV>_API_KEY:<keyId>:<keySecret>`, or a legacy
+ * `KIT_KEY:<keyId>:<keySecret>`). `apiKey` takes precedence over the deprecated
+ * `kitKey`, so a malformed `kitKey` that is being ignored must not fail a config
+ * that supplies a valid `apiKey` (and vice versa) — only the credential that
+ * would actually be sent is format-checked. When neither is supplied the SDK
+ * operates in permissionless mode. `baseUrl` overrides the Earn Service endpoint
+ * (e.g. staging); `batchTransactions: false` opts out of atomic batched
+ * execution. All are forwarded to the provider, so this `.strict()` schema must
+ * accept them or a valid config object is rejected.
  *
  * @internal
  */ const earnConfigSchema = z.object({
-    kitKey: apiKeySchema.optional(),
+    apiKey: z.string().optional(),
+    kitKey: z.string().optional(),
     baseUrl: z.string().optional(),
     batchTransactions: z.boolean().optional()
-}).strict();
+}).strict().superRefine((config, ctx)=>{
+    const credential = resolveApiKey(config);
+    if (credential === undefined) {
+        return;
+    }
+    const result = apiKeySchema.safeParse(credential);
+    if (!result.success) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [
+                credential === config.apiKey ? 'apiKey' : 'kitKey'
+            ],
+            message: result.error.issues[0]?.message ?? 'Invalid API key format'
+        });
+    }
+});
 /**
  * Canonical decimal form: a leading digit with no leading zeros (a single
  * '0' is only allowed immediately before the decimal point). Rejects the
@@ -20687,7 +23578,7 @@ const sourceAdapterContextSchema = z.object({
  * currently supports EVM vault addresses on Arc Testnet.
  *
  * @internal
- */ const vaultAddressSchema = evmAddressSchema.refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
+ */ const vaultAddressSchema = evmAddressSchema$1.refine(isValidEip55Checksum, 'address has an invalid EIP-55 checksum');
 /**
  * Validation schema for VaultQuery.
  *
@@ -20962,7 +23853,7 @@ const sameChainGetDepositQuoteParamsSchema = z.object({
 const crossChainGetDepositQuoteParamsSchema = z.object({
     from: sourceAdapterContextSchema,
     chain: earnBridgeDestinationChainIdentifierSchema,
-    address: evmAddressSchema,
+    address: evmAddressSchema$1,
     vaultAddress: vaultAddressSchema,
     amount: amountSchema,
     transferSpeed: z.enum([