@circle-fin/provider-cctp-v2 1.9.0 → 1.10.1

package/index.d.ts

@@ -373,6 +373,14 @@ interface CCTPSplitConfig {
     type: 'split';
     tokenMessenger: string;
     messageTransmitter: string;
+    /**
+     * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
+     *
+     * Optional. Present only on chains that support the prepaid FORWARD path
+     * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
+     * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
+     */
+    tokenMessengerWithFees?: string;
     confirmations: number;
 }
 /**
@@ -393,6 +401,14 @@ interface CCTPSplitConfig {
 interface CCTPMergedConfig {
     type: 'merged';
     contract: string;
+    /**
+     * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
+     *
+     * Optional. Present only on chains that support the prepaid FORWARD path
+     * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
+     * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
+     */
+    tokenMessengerWithFees?: string;
     confirmations: number;
 }
 /**
@@ -527,6 +543,21 @@ interface GatewayV1Contracts {
      * @example "0xabcdef1234567890abcdef1234567890abcdef12"
      */
     minter: string;
+    /**
+     * The address of the `DepositForHandler` contract.
+     *
+     * @description Optional. The handler the GenericExecutor calls on this chain
+     * to run a fast cross-chain deposit into the {@link GatewayV1Contracts.wallet}.
+     * Present only on chains that are fast-deposit destinations; other Gateway
+     * chains omit it.
+     *
+     * Address format varies by blockchain:
+     * - EVM chains: 40-character hexadecimal with 0x prefix (e.g., "0x1234...")
+     * - Solana: Base58-encoded 32-byte address (e.g., "9WzDX...")
+     *
+     * @example "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48"
+     */
+    depositForHandler?: string;
 }
 /**
  * Versioned map of Gateway contract configurations.
@@ -1765,6 +1796,110 @@ interface CCTPv2ActionMap {
          */
         hookData: string;
     };
+    /**
+     * Initiate a prepaid cross-chain USDC transfer through the `TokenMessengerWithFees` wrapper.
+     *
+     * Burn USDC on the source chain while collecting all fees up front against a
+     * signed quote. The wrapper collects the fee via `FeeManager`, then delegates
+     * to the unmodified `TokenMessengerV2`. When `hookData` is provided (the
+     * GenericExecutor FORWARD path) the wrapper's `depositForBurnWithHookAndFees`
+     * contract method is used; otherwise `depositForBurnWithFees` is used.
+     *
+     * @remarks
+     * SDK/contract naming: this SDK action is `depositForBurnWithFees` but, when a
+     * `hookData` is present, it dispatches to the `depositForBurnWithHookAndFees`
+     * contract method on `TokenMessengerWithFees` (NOT on `TokenMessengerV2`).
+     *
+     * Fee payment channel (must match the quote's `feeToken`):
+     * - Native fee (`feeToken` is the zero address): exactly `feeTotalAmount` is
+     *   attached as `msg.value`.
+     * - ERC-20 fee (e.g. USDC): no value is attached; the caller must first approve
+     *   the wrapper for `feeTotalAmount` (see the provider's fee approval helper).
+     *
+     * @remarks
+     * Unlike `depositForBurn`, the `TokenMessengerWithFees` contract methods do NOT
+     * take `maxFee` or `minFinalityThreshold` — fee and finality behavior are
+     * derived from the signed quote — so those fields are omitted from this action.
+     *
+     * @example
+     * ```typescript
+     * await adapter.action('cctp.v2.depositForBurnWithFees', {
+     *   amount: BigInt('1000000'),
+     *   mintRecipient: executorAddress,     // GenericExecutor (bytes32)
+     *   destinationCaller: executorAddress, // GenericExecutor (bytes32)
+     *   fromChain: ethereum,
+     *   toChain: arc,
+     *   hookData: geForwardHookData,        // cctp-forward-wrapped GenericExecutor blob
+     *   claim: { signedQuote: '0x...', refundAddress: '0x...' },
+     *   feeToken: '0x0000000000000000000000000000000000000000', // native
+     *   feeTotalAmount: 3500000n,
+     * })
+     * ```
+     */
+    depositForBurnWithFees: Omit<CCTPv2ActionMap['depositForBurn'], 'maxFee' | 'minFinalityThreshold'> & {
+        /**
+         * Optional hex-encoded hook data for the GenericExecutor FORWARD path.
+         *
+         * When present, the `depositForBurnWithHookAndFees` contract method is used
+         * and the blob must be wrapped in the `cctp-forward` envelope (the wrapper
+         * rejects a FORWARD fee quote whose hook lacks it). When omitted, the plain
+         * `depositForBurnWithFees` contract method is used.
+         */
+        hookData?: string;
+        /**
+         * Signed fee quote claim passed to the `TokenMessengerWithFees` wrapper.
+         *
+         * `signedQuote` is the `[uint8 0x01][abi.encode(Quote)]` blob returned by the
+         * Fee Quote service; `refundAddress` receives any fee overpayment refund.
+         */
+        claim: QuoteClaim;
+        /**
+         * Fee token from the signed quote.
+         *
+         * The zero address (`0x000…0`) means the fee is paid in native currency and
+         * is attached as `msg.value`. Any other address (e.g. USDC) means an ERC-20
+         * fee that must be approved to the wrapper beforehand. This is independent of
+         * `burnToken`, which is always USDC.
+         */
+        feeToken: string;
+        /**
+         * Total fee amount from the signed quote, in `feeToken` minor units.
+         *
+         * Firm only until the quote's `expiresAt`. For a native fee this is the exact
+         * `msg.value`; for an ERC-20 fee this is the amount approved to the wrapper.
+         */
+        feeTotalAmount: bigint;
+    };
+}
+/**
+ * Signed fee quote claim consumed by the `TokenMessengerWithFees` wrapper.
+ *
+ * Mirrors the on-chain `IFeeManager.QuoteClaim` struct.
+ *
+ * @example
+ * ```typescript
+ * const claim: QuoteClaim = {
+ *   signedQuote: '0x01...', // [uint8 0x01][abi.encode(Quote)]
+ *   refundAddress: '0xUserWallet...',
+ * }
+ * ```
+ */
+interface QuoteClaim {
+    /**
+     * Opaque signed quote bytes (`0x` hex) from the fee-quote service
+     * (`SignedFeeQuote.signedQuote` returned by `fetchFeeQuote`). Pass verbatim;
+     * do not decode.
+     *
+     * The quote binds the FORWARD fee item to the on-chain call via `argsHash`;
+     * passing a quote that does not match the burn args reverts `QuoteArgsMismatch`.
+     */
+    signedQuote: string;
+    /**
+     * Address that receives any refund of overpaid fees.
+     *
+     * Typically the user wallet that authorized the burn.
+     */
+    refundAddress: string;
 }
 
 /**
@@ -4208,6 +4343,116 @@ interface TokenRegistry {
     entries(): TokenDefinition[];
 }
 
+/**
+ * Valid recoverability values for error handling strategies.
+ *
+ * - FATAL errors are thrown immediately (invalid inputs, insufficient funds)
+ * - RETRYABLE errors are returned when a flow fails to start but could work later
+ * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
+ */
+declare const RECOVERABILITY_VALUES: readonly ["RETRYABLE", "RESUMABLE", "FATAL"];
+/**
+ * Error handling strategy for different types of failures.
+ *
+ * - FATAL errors are thrown immediately (invalid inputs, insufficient funds)
+ * - RETRYABLE errors are returned when a flow fails to start but could work later
+ * - RESUMABLE errors are returned when a flow fails mid-execution but can be continued
+ */
+type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
+/**
+ * Array of valid error type values for validation.
+ * Derived from ERROR_TYPES const object.
+ */
+declare const ERROR_TYPE_VALUES: ("INPUT" | "BALANCE" | "ONCHAIN" | "RPC" | "NETWORK" | "RATE_LIMIT" | "SERVICE" | "LIQUIDITY" | "UNKNOWN")[];
+/**
+ * Error type indicating the category of the error.
+ */
+type ErrorType = (typeof ERROR_TYPE_VALUES)[number];
+/**
+ * Structured error details with consistent properties for programmatic handling.
+ *
+ * This interface provides a standardized format for all errors in the
+ * App Kits system, enabling developers to handle different error
+ * types consistently and provide appropriate user feedback.
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorDetails = {
+ *   code: 1001,
+ *   name: "INPUT_NETWORK_MISMATCH",
+ *   type: "INPUT",
+ *   recoverability: "FATAL",
+ *   message: "Source and destination networks must be different",
+ *   cause: {
+ *     trace: { sourceChain: "ethereum", destChain: "ethereum" }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorDetails = {
+ *   code: 9001,
+ *   name: "BALANCE_INSUFFICIENT_TOKEN",
+ *   type: "BALANCE",
+ *   recoverability: "FATAL",
+ *   message: "Insufficient USDC balance on Ethereum",
+ *   cause: {
+ *     trace: { token: "USDC", chain: "Ethereum" }
+ *   }
+ * }
+ * ```
+ */
+interface ErrorDetails {
+    /** Numeric identifier following standardized ranges (see error code registry) */
+    code: number;
+    /** Human-readable ID (e.g., "INPUT_NETWORK_MISMATCH", "BALANCE_INSUFFICIENT_TOKEN") */
+    name: string;
+    /** Error category indicating where the error originated */
+    type: ErrorType;
+    /** Error handling strategy */
+    recoverability: Recoverability;
+    /** User-friendly explanation with context */
+    message: string;
+    /** Raw error details, context, or the original error that caused this one. */
+    cause?: {
+        /**
+         * Free-form error payload from the underlying system.
+         *
+         * The shape is **not uniform across error codes**: most codes set `trace`
+         * to the raw underlying error, while a few set a structured wrapper object
+         * `{ rawError, ...extras }` (e.g. `INPUT_AMOUNT_OUT_OF_RANGE` and
+         * `LIQUIDITY_INSUFFICIENT` add `minAmount` / `maxAmount` / `token`).
+         * Consumers must branch on `error.code` before reading structured fields off
+         * `trace`, and should treat the raw error as the fallback for all other codes.
+         */
+        trace?: unknown;
+    };
+}
+
+declare class KitError extends Error implements ErrorDetails {
+    /** Numeric identifier following standardized ranges (1000+ for INPUT errors) */
+    readonly code: number;
+    /** Human-readable ID (e.g., "NETWORK_MISMATCH") */
+    readonly name: string;
+    /** Error category indicating where the error originated */
+    readonly type: ErrorType;
+    /** Error handling strategy */
+    readonly recoverability: Recoverability;
+    /** Raw error details, context, or the original error that caused this one. */
+    readonly cause?: {
+        /** Free-form error payload from underlying system */
+        trace?: unknown;
+    };
+    /**
+     * Create a new KitError instance.
+     *
+     * @param details - The error details object containing all required properties.
+     * @throws \{TypeError\} When details parameter is missing or invalid.
+     */
+    constructor(details: ErrorDetails);
+}
+
 /**
  * Structured fields that can be attached to log entries.
  */
@@ -6194,101 +6439,530 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
 }
 
 /**
- * Configuration options for the CCTP v2 provider.
+ * Get the token account address where USDC will be minted for the recipient.
  *
- * @remarks
- * This interface defines all configurable aspects of the CCTP v2 provider:
- * - attestation: Settings for the attestation fetching process
- * - headers: Custom HTTP headers sent with every Circle attestation API request
+ * For EVM chains, the recipient address directly holds ERC20 tokens, so the raw
+ * address is returned as-is. For Solana, USDC is held in Associated Token Accounts
+ * (ATAs), so this function derives the ATA address for the given owner and USDC mint.
+ *
+ * @param chainType - The type of blockchain ('evm' or 'solana').
+ * @param rawAddress - The recipient's wallet address on the destination chain.
+ * @param mint - The USDC mint address (only used for Solana chains).
+ * @returns The address where USDC tokens will be minted (raw address for EVM, ATA for Solana).
+ *
+ * @example
+ * ```typescript
+ * import { getMintRecipientAccount } from './getMintRecipientAccount'
+ *
+ * // EVM: returns the same address
+ * const evmAccount = await getMintRecipientAccount(
+ *   'evm',
+ *   '0x742d35Cc6634C0532925a3b8D89C7DA5C3cfa',
+ *   'N/A'
+ * )
+ *
+ * // Solana: derives the Associated Token Account
+ * const solanaAccount = await getMintRecipientAccount(
+ *   'solana',
+ *   '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+ * )
+ * ```
  */
-interface CCTPV2Config {
-    /** Configuration for the attestation fetching process */
-    attestation?: Partial<ApiPollingConfig>;
-    /**
-     * Custom HTTP headers sent with every Circle attestation (Iris) API request
-     * made by the provider (attestation fetch, re-attestation, and relayer mint
-     * status polling).
-     *
-     * @remarks
-     * Headers are merged on top of the defaults (such as `Content-Type`) without
-     * removing them. The header is forwarded as-is to Circle's API; the SDK does
-     * not interpret it.
-     *
-     * Precedence (lowest to highest): provider defaults, then these
-     * `config.headers`, then any per-call `config.headers` passed to
-     * {@link CCTPV2BridgingProvider.fetchAttestation},
-     * {@link CCTPV2BridgingProvider.fetchRelayerMint}, or
-     * {@link CCTPV2BridgingProvider.reAttest}.
-     */
-    headers?: Record<string, string>;
-}
+declare const getMintRecipientAccount: (
+/** The blockchain type - determines how token accounts are handled */
+chainType: ChainType, 
+/** The recipient's wallet address (hex format for EVM, base58 for Solana) */
+rawAddress: string, 
+/** The USDC mint address (ignored for EVM chains, required base58 address for Solana) */
+mintAddress: string) => Promise<string>;
+
 /**
- * Concrete implementation of BridgingProvider for Circle's Cross-Chain Transfer Protocol (CCTP) version 2.
+ * Validates and converts a fee value to bigint.
  *
- * This provider handles cross-chain bridging using CCTP v2 contracts, which enable native USDC
- * bridging between supported blockchain networks. The provider supports burn-and-mint operations
- * with built-in validation, fee estimation, and transaction monitoring.
+ * This utility performs:
+ * 1. Conversion from string or number to bigint
+ * 2. Validation that the value is non-negative
  *
- * The CCTPv2 provider is designed to be:
- * - **Type-safe**: Full TypeScript support with comprehensive validation
- * - **Flexible**: Support for both FAST and SLOW bridge configurations
- * - **Reliable**: Built-in error handling and recovery mechanisms
- * - **Observable**: Rich event emission for monitoring and debugging
+ * @param value - The fee value to validate and convert (string or number)
+ * @param fieldName - The name of the field for error messages
+ * @returns The validated fee as a bigint
+ * @throws {KitError} If the value cannot be converted to bigint or is negative
  *
  * @example
  * ```typescript
- * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
- * import { createEvmAdapter } from '@circle-fin/adapter-viem-v2'
+ * const fee = validateAndConvertFee('1000000', 'minimumFee')
+ * console.log(fee) // 1000000n
  *
- * const provider = new CCTPV2BridgingProvider()
+ * const fee2 = validateAndConvertFee(500, 'forwardingFee')
+ * console.log(fee2) // 500n
+ * ```
+ */
+declare function validateAndConvertFee(value: number | string, fieldName: string): bigint;
+
+/** A block number value that can be provided as bigint, number, or string. */
+type BlockNumberInput = bigint | number | string | undefined;
+/**
+ * Determines whether an attestation has expired based on the current block number.
  *
- * // Check route support
- * const isSupported = provider.supportsRoute('Ethereum', 'Base', 'USDC')
+ * An attestation expires when the destination chain's current block number is greater
+ * than or equal to the expiration block specified in the attestation message.
+ * Slow transfers and re-attested messages have `expirationBlock: '0'` and never expire.
  *
- * // Create adapters
- * const sourceAdapter = createEvmAdapter({ privateKey: '0x...' })
- * const destAdapter = createEvmAdapter({ privateKey: '0x...' })
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns `true` if the attestation has expired, `false` if still valid or never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
  *
- * // Prepare bridge parameters
- * const params: BridgeParams = {
- *   source: { adapter: sourceAdapter, chain: 'Ethereum' },
- *   destination: { adapter: destAdapter, chain: 'Base' },
- *   amount: '10.50',
- *   token: 'USDC',
- *   config: {
- *     transferSpeed: 'FAST',
- *   },
- * }
+ * @example
+ * ```typescript
+ * import { isAttestationExpired } from '@circle-fin/cctp-v2-provider'
  *
- * // Estimate bridge costs
- * const estimate = await provider.estimate(params)
- * console.log('Estimated cost:', estimate.totalCost)
+ * // Check if attestation is expired on EVM chain
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const expired = isAttestationExpired(attestation, currentBlock)
  *
- * // Execute bridge operation (when implemented)
- * const result = await provider.bridge(params)
- * console.log('Bridge completed!')
+ * if (expired) {
+ *   const freshAttestation = await provider.reAttest(source, burnTxHash)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check on Solana
+ * const slot = await adapter.getConnection(destinationChain).getSlot()
+ * const expired = isAttestationExpired(attestation, slot)
  * ```
  */
-declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> implements ICCTPV2BridgingProvider {
-    /** The name of the provider */
-    readonly name = "CCTPV2BridgingProvider";
-    /**
-     * The chains that this provider supports.
-     */
-    supportedChains: ChainDefinition[];
-    /**
-     * The provider's configuration.
-     */
-    private readonly config;
-    /**
-     * Creates a new instance of the CCTP v2 bridging provider.
-     *
-     * @param config - Optional configuration overrides for the provider
-     */
-    constructor(config?: CCTPV2Config);
-    /**
-     * Resolves the effective polling configuration for an attestation request.
-     *
+declare const isAttestationExpired: (attestation: AttestationMessage, currentBlockNumber: BlockNumberInput) => boolean;
+/**
+ * Calculates the number of blocks remaining until an attestation expires.
+ *
+ * Returns the difference between the expiration block and the current block number.
+ * Returns `null` if the attestation has `expirationBlock: '0'` (never expires).
+ * Returns `0n` or a negative bigint if the attestation has already expired.
+ *
+ * @param attestation - The attestation message containing expiration block information
+ * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
+ * @returns The number of blocks until expiry as a bigint, or `null` if the attestation never expires
+ * @throws KitError If currentBlockNumber or expirationBlock is invalid
+ *
+ * @example
+ * ```typescript
+ * import { getBlocksUntilExpiry } from '@circle-fin/cctp-v2-provider'
+ *
+ * const publicClient = await adapter.getPublicClient(destinationChain)
+ * const currentBlock = await publicClient.getBlockNumber()
+ * const blocksRemaining = getBlocksUntilExpiry(attestation, currentBlock)
+ *
+ * if (blocksRemaining === null) {
+ *   console.log('Attestation never expires')
+ * } else if (blocksRemaining <= 0n) {
+ *   console.log('Attestation has expired')
+ * } else {
+ *   console.log(`${blocksRemaining} blocks until expiry`)
+ * }
+ * ```
+ */
+declare const getBlocksUntilExpiry: (attestation: AttestationMessage, currentBlockNumber: BlockNumberInput) => bigint | null;
+/**
+ * Determines whether a mint failure was caused by an expired attestation.
+ *
+ * This function inspects the error thrown during a mint operation to detect
+ * if the failure is due to the attestation's expiration block being exceeded.
+ * When this returns `true`, the caller should use `reAttest()` to obtain a
+ * fresh attestation before retrying the mint.
+ *
+ * @param error - The error thrown during the mint operation
+ * @returns `true` if the error indicates the attestation has expired, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isMintFailureRelatedToAttestation } from '@circle-fin/cctp-v2-provider'
+ *
+ * try {
+ *   await mintRequest.execute()
+ * } catch (error) {
+ *   if (isMintFailureRelatedToAttestation(error)) {
+ *     // Attestation expired - get a fresh one
+ *     const freshAttestation = await provider.reAttest(source, burnTxHash)
+ *     const newMintRequest = await provider.mint(source, destination, freshAttestation)
+ *     await newMintRequest.execute()
+ *   } else {
+ *     throw error
+ *   }
+ * }
+ * ```
+ */
+declare const isMintFailureRelatedToAttestation: (error: unknown) => boolean;
+
+/**
+ * An ERC-20 approval required before a prepaid-FORWARD burn.
+ *
+ * @example
+ * ```typescript
+ * const approval: FeeApproval = {
+ *   token: '0xUSDC...',
+ *   amount: 1_003_500_000n,
+ * }
+ * ```
+ */
+interface FeeApproval {
+    /**
+     * Token address to approve (the burn token and/or the ERC-20 fee token).
+     */
+    token: string;
+    /**
+     * Amount to approve to the `TokenMessengerWithFees` wrapper, in token minor units.
+     */
+    amount: bigint;
+}
+/**
+ * The resolved fee payment channel for a prepaid-FORWARD burn.
+ *
+ * @example
+ * ```typescript
+ * const plan: FeePaymentPlan = {
+ *   isNativeFee: false,
+ *   isBurnTokenFee: true,
+ *   nativeValue: 0n,
+ *   approvals: [{ token: '0xUSDC...', amount: 1_003_500_000n }],
+ * }
+ * ```
+ */
+interface FeePaymentPlan {
+    /**
+     * True when the fee is paid in native currency (`feeToken` is the zero address).
+     */
+    isNativeFee: boolean;
+    /**
+     * True when the fee token is the same token being burned (both USDC).
+     *
+     * In this case a single, combined approval covers both the burn and the fee,
+     * so the redundant second approval is skipped.
+     */
+    isBurnTokenFee: boolean;
+    /**
+     * Native value to attach as `msg.value`.
+     *
+     * Exactly `feeTotalAmount` for a native fee; `0n` for an ERC-20 fee.
+     */
+    nativeValue: bigint;
+    /**
+     * ERC-20 approvals required before the burn, each to the `TokenMessengerWithFees`
+     * wrapper.
+     *
+     * - Native fee: a single approval of `amount` for the burn token.
+     * - ERC-20 fee equal to the burn token: a single approval of `amount + feeTotalAmount`.
+     * - ERC-20 fee different from the burn token: two approvals — `amount` for the
+     *   burn token and `feeTotalAmount` for the fee token.
+     */
+    approvals: FeeApproval[];
+}
+/**
+ * Parameters for {@link resolveFeePayment}.
+ */
+interface ResolveFeePaymentParams {
+    /**
+     * Fee token from the signed quote. The zero address denotes a native fee.
+     */
+    feeToken: string;
+    /**
+     * The token being burned (always USDC on the burn path).
+     */
+    burnToken: string;
+    /**
+     * Amount of the burn token to burn, in minor units.
+     */
+    amount: bigint;
+    /**
+     * Total fee amount from the signed quote, in `feeToken` minor units.
+     */
+    feeTotalAmount: bigint;
+}
+/**
+ * Resolve the fee payment channel for a prepaid-FORWARD burn via `TokenMessengerWithFees`.
+ *
+ * Determines the native `msg.value` and the ERC-20 approvals required, honouring
+ * the quote's `feeToken`:
+ * - Native fee (`feeToken` is the zero address): attach exactly `feeTotalAmount`
+ *   as `msg.value`; approve only the burn amount.
+ * - ERC-20 fee equal to the burn token (both USDC — the `isBurnTokenFee` case):
+ *   approve a single combined `amount + feeTotalAmount` and skip the redundant
+ *   second approval.
+ * - ERC-20 fee different from the burn token: approve the burn amount and the fee
+ *   amount separately.
+ *
+ * This encodes only balance/allowance intent; it does not fetch balances. The
+ * caller is responsible for a balance preflight against the fresh quote.
+ *
+ * @param params - The fee token, burn token, burn amount, and total fee amount.
+ * @returns The resolved fee payment plan.
+ * @throws KitError if `amount` or `feeTotalAmount` is negative.
+ *
+ * @example
+ * ```typescript
+ * // Native fee
+ * resolveFeePayment({
+ *   feeToken: '0x0000000000000000000000000000000000000000',
+ *   burnToken: '0xUSDC...',
+ *   amount: 1_000_000n,
+ *   feeTotalAmount: 3_500_000n,
+ * })
+ * // → { isNativeFee: true, isBurnTokenFee: false, nativeValue: 3_500_000n,
+ * //     approvals: [{ token: '0xUSDC...', amount: 1_000_000n }] }
+ * ```
+ */
+declare const resolveFeePayment: (params: ResolveFeePaymentParams) => FeePaymentPlan;
+
+/**
+ * Custom errors reverted by the `TokenMessengerWithFees` wrapper on the prepaid
+ * FORWARD path.
+ *
+ * - `IncorrectNativePayment` — `msg.value` did not equal the quoted native fee.
+ * - `ForwardFeeWithoutHook` — the quote has a FORWARD item but the hookData lacks
+ *   a `cctp-forward` frame.
+ * - `ForwardHookWithoutFee` — the hookData has a `cctp-forward` frame but the quote
+ *   omits a FORWARD item.
+ * - `QuoteArgsMismatch` — the signed quote's `argsHash` does not match the on-chain
+ *   call arguments (wrong hookData/destinationCaller/amount/etc.).
+ * - `InvalidQuoteSigner` — the signed quote was not signed by a recognized signer.
+ */
+declare const PREPAID_FORWARD_REVERT_NAMES: readonly ["IncorrectNativePayment", "ForwardFeeWithoutHook", "ForwardHookWithoutFee", "QuoteArgsMismatch", "InvalidQuoteSigner"];
+/**
+ * A `TokenMessengerWithFees` custom revert name.
+ */
+type PrepaidForwardRevertName = (typeof PREPAID_FORWARD_REVERT_NAMES)[number];
+/**
+ * Determine whether a hookData blob begins with the `cctp-forward` envelope.
+ *
+ * The prepaid FORWARD path requires the GenericExecutor blob to be wrapped in a
+ * `cctp-forward` frame; without it the wrapper reverts `ForwardFeeWithoutHook`.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @returns True when the hookData starts with the `cctp-forward` magic.
+ *
+ * @example
+ * ```typescript
+ * hasForwardHook('0x636374702d666f7277617264...') // true
+ * hasForwardHook('0xdeadbeef') // false
+ * ```
+ */
+declare const hasForwardHook: (hookData: string | undefined) => boolean;
+/**
+ * Assert that a hookData blob is forward-friendly for the prepaid FORWARD path.
+ *
+ * The prepaid FORWARD path always requests a FORWARD fee item, so the wrapper
+ * requires the hookData to start with a `cctp-forward` frame. Validating this
+ * before the burn surfaces the guaranteed `ForwardFeeWithoutHook` revert as a
+ * typed input error instead of an on-chain failure.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @throws KitError (`INPUT_VALIDATION_FAILED`) if the hookData is missing or lacks
+ *   the `cctp-forward` frame.
+ *
+ * @example
+ * ```typescript
+ * assertForwardHookData(geForwardHookData) // ok
+ * assertForwardHookData('0xdeadbeef') // throws — would revert ForwardFeeWithoutHook
+ * ```
+ */
+declare const assertForwardHookData: (hookData: string | undefined) => void;
+/**
+ * Map a raw error thrown while submitting a prepaid-FORWARD burn to a typed error.
+ *
+ * Inspects the error for a known `TokenMessengerWithFees` custom revert name and,
+ * when found, returns a structured {@link KitError} describing it. Returns
+ * `undefined` when the error is not a recognized wrapper revert so the caller can
+ * fall through to generic blockchain-error parsing.
+ *
+ * @param error - The error thrown by transaction simulation or execution.
+ * @param chain - The source chain name, for the error message.
+ * @returns A typed {@link KitError} for a recognized wrapper revert, else `undefined`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await prepared.execute()
+ * } catch (error) {
+ *   throw mapPrepaidForwardError(error, 'Ethereum') ?? parseBlockchainError(error, { chain: 'Ethereum' })
+ * }
+ * ```
+ */
+declare const mapPrepaidForwardError: (error: unknown, chain: string) => KitError | undefined;
+
+/**
+ * Configuration options for the CCTP v2 provider.
+ *
+ * @remarks
+ * This interface defines all configurable aspects of the CCTP v2 provider:
+ * - attestation: Settings for the attestation fetching process
+ * - headers: Custom HTTP headers sent with every Circle attestation API request
+ */
+interface CCTPV2Config {
+    /** Configuration for the attestation fetching process */
+    attestation?: Partial<ApiPollingConfig>;
+    /**
+     * Custom HTTP headers sent with every Circle attestation (Iris) API request
+     * made by the provider (attestation fetch, re-attestation, and relayer mint
+     * status polling).
+     *
+     * @remarks
+     * Headers are merged on top of the defaults (such as `Content-Type`) without
+     * removing them. The header is forwarded as-is to Circle's API; the SDK does
+     * not interpret it.
+     *
+     * Precedence (lowest to highest): provider defaults, then these
+     * `config.headers`, then any per-call `config.headers` passed to
+     * {@link CCTPV2BridgingProvider.fetchAttestation},
+     * {@link CCTPV2BridgingProvider.fetchRelayerMint}, or
+     * {@link CCTPV2BridgingProvider.reAttest}.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Parameters for a prepaid-FORWARD burn via {@link CCTPV2BridgingProvider.burnWithFees}.
+ *
+ * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+ */
+interface BurnWithFeesParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
+    /**
+     * Source wallet context (adapter + CCTP v2 source chain).
+     */
+    source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>;
+    /**
+     * Destination chain definition (provides the destination CCTP domain).
+     */
+    destinationChain: ChainDefinitionWithCCTPv2;
+    /**
+     * Amount of USDC to burn, in minor units.
+     */
+    amount: string | bigint;
+    /**
+     * The GenericExecutor address on the destination chain.
+     *
+     * Used for BOTH `mintRecipient` and `destinationCaller` (padded to bytes32 by
+     * the underlying action): the executor mints to itself and is the only account
+     * allowed to complete the transfer.
+     */
+    executor: string;
+    /**
+     * The `cctp-forward`-wrapped GenericExecutor hookData blob.
+     *
+     * Produced with `@core/utils`: wrap the bare blob from
+     * `buildDepositForGenericExecutorPayload(...).hookData` with
+     * `buildForwardingHookDataWithPayload(version, bareBlob)`. It must begin with
+     * the `cctp-forward` frame, or the wrapper reverts `ForwardFeeWithoutHook`.
+     *
+     * Pass the SAME wrapped bytes here that were bound to the FORWARD fee quote
+     * (`fetchFeeQuote` FORWARD `params.hookData`); mismatched bytes revert
+     * `QuoteArgsMismatch`. Do not pass the bare (`circle-generic-executor`) blob.
+     */
+    hookData: string;
+    /**
+     * Signed fee quote claim (`{ signedQuote, refundAddress }`).
+     */
+    claim: QuoteClaim;
+    /**
+     * Fee token from the quote. The zero address denotes a native fee.
+     */
+    feeToken: string;
+    /**
+     * Total fee amount from the quote, in `feeToken` minor units.
+     */
+    feeTotalAmount: string | bigint;
+}
+/**
+ * Result of {@link CCTPV2BridgingProvider.burnWithFees}.
+ *
+ * The prepared requests are returned unexecuted; the caller executes the
+ * approvals first (in order) and then the burn.
+ */
+interface BurnWithFeesResult {
+    /**
+     * ERC-20 approvals to the `TokenMessengerWithFees` wrapper required before the
+     * burn. Always contains at least one entry: the burn-token approval. A
+     * distinct fee-token approval is added only when the fee token differs from
+     * the burn token and is not the native token.
+     */
+    approvals: PreparedChainRequest[];
+    /**
+     * The prepared `depositForBurnWithHookAndFees` burn transaction.
+     */
+    burn: PreparedChainRequest;
+    /**
+     * The resolved fee payment plan (native value, approvals, and flags).
+     */
+    feePayment: FeePaymentPlan;
+}
+/**
+ * Concrete implementation of BridgingProvider for Circle's Cross-Chain Transfer Protocol (CCTP) version 2.
+ *
+ * This provider handles cross-chain bridging using CCTP v2 contracts, which enable native USDC
+ * bridging between supported blockchain networks. The provider supports burn-and-mint operations
+ * with built-in validation, fee estimation, and transaction monitoring.
+ *
+ * The CCTPv2 provider is designed to be:
+ * - **Type-safe**: Full TypeScript support with comprehensive validation
+ * - **Flexible**: Support for both FAST and SLOW bridge configurations
+ * - **Reliable**: Built-in error handling and recovery mechanisms
+ * - **Observable**: Rich event emission for monitoring and debugging
+ *
+ * @example
+ * ```typescript
+ * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+ * import { createEvmAdapter } from '@circle-fin/adapter-viem-v2'
+ *
+ * const provider = new CCTPV2BridgingProvider()
+ *
+ * // Check route support
+ * const isSupported = provider.supportsRoute('Ethereum', 'Base', 'USDC')
+ *
+ * // Create adapters
+ * const sourceAdapter = createEvmAdapter({ privateKey: '0x...' })
+ * const destAdapter = createEvmAdapter({ privateKey: '0x...' })
+ *
+ * // Prepare bridge parameters
+ * const params: BridgeParams = {
+ *   source: { adapter: sourceAdapter, chain: 'Ethereum' },
+ *   destination: { adapter: destAdapter, chain: 'Base' },
+ *   amount: '10.50',
+ *   token: 'USDC',
+ *   config: {
+ *     transferSpeed: 'FAST',
+ *   },
+ * }
+ *
+ * // Estimate bridge costs
+ * const estimate = await provider.estimate(params)
+ * console.log('Estimated cost:', estimate.totalCost)
+ *
+ * // Execute bridge operation (when implemented)
+ * const result = await provider.bridge(params)
+ * console.log('Bridge completed!')
+ * ```
+ */
+declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> implements ICCTPV2BridgingProvider {
+    /** The name of the provider */
+    readonly name = "CCTPV2BridgingProvider";
+    /**
+     * The chains that this provider supports.
+     */
+    supportedChains: ChainDefinition[];
+    /**
+     * The provider's configuration.
+     */
+    private readonly config;
+    /**
+     * Creates a new instance of the CCTP v2 bridging provider.
+     *
+     * @param config - Optional configuration overrides for the provider
+     */
+    constructor(config?: CCTPV2Config);
+    /**
+     * Resolves the effective polling configuration for an attestation request.
+     *
      * Precedence (lowest to highest): provider `config.attestation`, then the
      * per-call `config`. Headers merge independently across
      * `config.attestation.headers`, the provider-level `config.headers`, and any
@@ -6730,6 +7404,57 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * ```
      */
     burn<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(params: BridgeParams<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<PreparedChainRequest>;
+    /**
+     * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
+     *
+     * Builds the source-chain `depositForBurnWithHookAndFees` call for the
+     * GenericExecutor FORWARD path: fees are collected up front on the source chain
+     * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
+     * the GenericExecutor, and the GE `hookData` is passed through unchanged.
+     *
+     * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
+     * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+     * `claim` are produced elsewhere and passed in here:
+     * - `hookData`: `buildForwardingHookDataWithPayload(version,
+     *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
+     * - `claim.signedQuote` / `feeToken` / `feeTotalAmount`: from `fetchFeeQuote`
+     *   (`@circle-fin/provider-fee-v1`), whose FORWARD item must be bound to the
+     *   SAME `hookData` and executor `destinationCaller` used here.
+     *
+     * The returned approvals and burn are NOT executed — the caller executes the
+     * approvals first (in order) and then the burn. The fee payment channel matches
+     * the quote's `feeToken`:
+     * - Native fee: exactly `feeTotalAmount` is attached as the burn's `msg.value`;
+     *   only the burn amount is approved.
+     * - USDC fee (same token as the burn): a single combined `amount + feeTotalAmount`
+     *   approval covers both; the redundant second approval is skipped.
+     *
+     * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+     * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
+     * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
+     * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
+     *   support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
+     *   a bigint or a numeric string coercible to bigint, the hookData lacks a
+     *   `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
+     *   context cannot be resolved.
+     *
+     * @example
+     * ```typescript
+     * const { approvals, burn } = await provider.burnWithFees({
+     *   source,
+     *   destinationChain: Arc,
+     *   amount: 1_000_000n,
+     *   executor: genericExecutorAddress,
+     *   hookData: geForwardHookData,
+     *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
+     *   feeToken: '0x0000000000000000000000000000000000000000', // native
+     *   feeTotalAmount: 3_500_000n,
+     * })
+     * for (const approval of approvals) await approval.execute()
+     * const txHash = await burn.execute()
+     * ```
+     */
+    burnWithFees<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(params: BurnWithFeesParams<TFromAdapterCapabilities>): Promise<BurnWithFeesResult>;
     /**
      * Waits for a transaction to be mined and confirmed on the blockchain.
      *
@@ -6754,164 +7479,5 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
     waitForTransaction(adapter: Adapter, txHash: string, chain: ChainDefinition, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
 }
 
-/**
- * Get the token account address where USDC will be minted for the recipient.
- *
- * For EVM chains, the recipient address directly holds ERC20 tokens, so the raw
- * address is returned as-is. For Solana, USDC is held in Associated Token Accounts
- * (ATAs), so this function derives the ATA address for the given owner and USDC mint.
- *
- * @param chainType - The type of blockchain ('evm' or 'solana').
- * @param rawAddress - The recipient's wallet address on the destination chain.
- * @param mint - The USDC mint address (only used for Solana chains).
- * @returns The address where USDC tokens will be minted (raw address for EVM, ATA for Solana).
- *
- * @example
- * ```typescript
- * import { getMintRecipientAccount } from './getMintRecipientAccount'
- *
- * // EVM: returns the same address
- * const evmAccount = await getMintRecipientAccount(
- *   'evm',
- *   '0x742d35Cc6634C0532925a3b8D89C7DA5C3cfa',
- *   'N/A'
- * )
- *
- * // Solana: derives the Associated Token Account
- * const solanaAccount = await getMintRecipientAccount(
- *   'solana',
- *   '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
- *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
- * )
- * ```
- */
-declare const getMintRecipientAccount: (
-/** The blockchain type - determines how token accounts are handled */
-chainType: ChainType, 
-/** The recipient's wallet address (hex format for EVM, base58 for Solana) */
-rawAddress: string, 
-/** The USDC mint address (ignored for EVM chains, required base58 address for Solana) */
-mintAddress: string) => Promise<string>;
-
-/**
- * Validates and converts a fee value to bigint.
- *
- * This utility performs:
- * 1. Conversion from string or number to bigint
- * 2. Validation that the value is non-negative
- *
- * @param value - The fee value to validate and convert (string or number)
- * @param fieldName - The name of the field for error messages
- * @returns The validated fee as a bigint
- * @throws {KitError} If the value cannot be converted to bigint or is negative
- *
- * @example
- * ```typescript
- * const fee = validateAndConvertFee('1000000', 'minimumFee')
- * console.log(fee) // 1000000n
- *
- * const fee2 = validateAndConvertFee(500, 'forwardingFee')
- * console.log(fee2) // 500n
- * ```
- */
-declare function validateAndConvertFee(value: number | string, fieldName: string): bigint;
-
-/** A block number value that can be provided as bigint, number, or string. */
-type BlockNumberInput = bigint | number | string | undefined;
-/**
- * Determines whether an attestation has expired based on the current block number.
- *
- * An attestation expires when the destination chain's current block number is greater
- * than or equal to the expiration block specified in the attestation message.
- * Slow transfers and re-attested messages have `expirationBlock: '0'` and never expire.
- *
- * @param attestation - The attestation message containing expiration block information
- * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
- * @returns `true` if the attestation has expired, `false` if still valid or never expires
- * @throws KitError If currentBlockNumber or expirationBlock is invalid
- *
- * @example
- * ```typescript
- * import { isAttestationExpired } from '@circle-fin/cctp-v2-provider'
- *
- * // Check if attestation is expired on EVM chain
- * const publicClient = await adapter.getPublicClient(destinationChain)
- * const currentBlock = await publicClient.getBlockNumber()
- * const expired = isAttestationExpired(attestation, currentBlock)
- *
- * if (expired) {
- *   const freshAttestation = await provider.reAttest(source, burnTxHash)
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Check on Solana
- * const slot = await adapter.getConnection(destinationChain).getSlot()
- * const expired = isAttestationExpired(attestation, slot)
- * ```
- */
-declare const isAttestationExpired: (attestation: AttestationMessage, currentBlockNumber: BlockNumberInput) => boolean;
-/**
- * Calculates the number of blocks remaining until an attestation expires.
- *
- * Returns the difference between the expiration block and the current block number.
- * Returns `null` if the attestation has `expirationBlock: '0'` (never expires).
- * Returns `0n` or a negative bigint if the attestation has already expired.
- *
- * @param attestation - The attestation message containing expiration block information
- * @param currentBlockNumber - The current block number on the destination chain (bigint, number, or string)
- * @returns The number of blocks until expiry as a bigint, or `null` if the attestation never expires
- * @throws KitError If currentBlockNumber or expirationBlock is invalid
- *
- * @example
- * ```typescript
- * import { getBlocksUntilExpiry } from '@circle-fin/cctp-v2-provider'
- *
- * const publicClient = await adapter.getPublicClient(destinationChain)
- * const currentBlock = await publicClient.getBlockNumber()
- * const blocksRemaining = getBlocksUntilExpiry(attestation, currentBlock)
- *
- * if (blocksRemaining === null) {
- *   console.log('Attestation never expires')
- * } else if (blocksRemaining <= 0n) {
- *   console.log('Attestation has expired')
- * } else {
- *   console.log(`${blocksRemaining} blocks until expiry`)
- * }
- * ```
- */
-declare const getBlocksUntilExpiry: (attestation: AttestationMessage, currentBlockNumber: BlockNumberInput) => bigint | null;
-/**
- * Determines whether a mint failure was caused by an expired attestation.
- *
- * This function inspects the error thrown during a mint operation to detect
- * if the failure is due to the attestation's expiration block being exceeded.
- * When this returns `true`, the caller should use `reAttest()` to obtain a
- * fresh attestation before retrying the mint.
- *
- * @param error - The error thrown during the mint operation
- * @returns `true` if the error indicates the attestation has expired, `false` otherwise
- *
- * @example
- * ```typescript
- * import { isMintFailureRelatedToAttestation } from '@circle-fin/cctp-v2-provider'
- *
- * try {
- *   await mintRequest.execute()
- * } catch (error) {
- *   if (isMintFailureRelatedToAttestation(error)) {
- *     // Attestation expired - get a fresh one
- *     const freshAttestation = await provider.reAttest(source, burnTxHash)
- *     const newMintRequest = await provider.mint(source, destination, freshAttestation)
- *     await newMintRequest.execute()
- *   } else {
- *     throw error
- *   }
- * }
- * ```
- */
-declare const isMintFailureRelatedToAttestation: (error: unknown) => boolean;
-
-export { CCTPV2BridgingProvider, getBlocksUntilExpiry, getMintRecipientAccount, isAttestationExpired, isMintFailureRelatedToAttestation, validateAndConvertFee };
-export type { CCTPV2Config };
+export { CCTPV2BridgingProvider, PREPAID_FORWARD_REVERT_NAMES, assertForwardHookData, getBlocksUntilExpiry, getMintRecipientAccount, hasForwardHook, isAttestationExpired, isMintFailureRelatedToAttestation, mapPrepaidForwardError, resolveFeePayment, validateAndConvertFee };
+export type { BurnWithFeesParams, BurnWithFeesResult, CCTPV2Config, FeeApproval, FeePaymentPlan, PrepaidForwardRevertName, ResolveFeePaymentParams };