@circle-fin/app-kit 1.13.0 → 1.15.0

package/unifiedBalance.d.ts

@@ -166,6 +166,30 @@ interface BaseChainDefinition {
      * ```
      */
     kitContracts?: KitContracts;
+    /**
+     * Optional CCTPx configuration.
+     *
+     * @description When provided, the chain supports CCTPx (Cross-Chain Token Service).
+     * CCTPx is a service-level protocol layered on top of CCTP v2's message-passing layer
+     * that enables cross-chain transfers of registered tokens (Circle-issued or otherwise).
+     *
+     * The CCTS contract is deployed via CREATE3 so its address is deterministic and may
+     * be committed to chain config ahead of the on-chain deployment.
+     *
+     * Use the {@link isCCTPXSupported} type guard to check if a chain has CCTPx support
+     * before accessing this property.
+     *
+     * @example
+     * ```typescript
+     * if (isCCTPXSupported(chain)) {
+     *   console.log('CCTS address:', chain.cctpx.serviceAddress)
+     * }
+     * ```
+     *
+     * @see {@link CCTPXChainConfig} for the structure of CCTPx configuration.
+     * @see {@link isCCTPXSupported} for checking CCTPx support.
+     */
+    cctpx?: CCTPXChainConfig;
     /**
      * Optional Gateway contract configuration for Gateway protocol support.
      *
@@ -485,6 +509,34 @@ interface CCTPConfig {
         destination: boolean;
     };
 }
+/**
+ * Configuration for Circle's Cross-Chain Token Service (CCTS) — the CCTPx protocol.
+ *
+ * @category Types
+ *
+ * @description Contains the CCTS proxy contract address on a given chain. The CCTS
+ * contract is the service-level entry point for CCTPx cross-chain transfers of
+ * registered tokens (Circle-issued or otherwise). Addresses are deterministic via CREATE3
+ * and may be committed to chain config ahead of the on-chain deploy.
+ *
+ * @example
+ * ```typescript
+ * const cctpxConfig: CCTPXChainConfig = {
+ *   serviceAddress: '0x1234567890abcdef1234567890abcdef12345678'
+ * }
+ * ```
+ */
+interface CCTPXChainConfig {
+    /**
+     * The CrossChainTokenService (CCTS) proxy contract address on this chain.
+     *
+     * @description Deterministic CREATE3 address. Used by the SDK as the `to` field
+     * when calling `crossChainTransfer` and `resolveTokenManager`.
+     *
+     * @example "0x1234567890abcdef1234567890abcdef12345678"
+     */
+    serviceAddress: string;
+}
 /**
  * Available kit contract types for enhanced chain functionality.
  *
@@ -558,6 +610,19 @@ interface GatewayV1Contracts {
      * @example "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48"
      */
     depositForHandler?: string;
+    /**
+     * The address of the `GenericExecutor` contract.
+     *
+     * @description Optional. The contract that acts as `mintRecipient` and
+     * `destinationCaller` for the CCTP v2 prepaid FORWARD path. It receives the
+     * CCTP mint and calls {@link GatewayV1Contracts.depositForHandler} to
+     * complete the fast deposit into the {@link GatewayV1Contracts.wallet}.
+     * Present only on chains that are fast-deposit destinations; other Gateway
+     * chains omit it.
+     *
+     * @example "0xFa7be2f04F3Ad4ca969260729c6d45B5625984A7"
+     */
+    genericExecutor?: string;
 }
 /**
  * Versioned map of Gateway contract configurations.
@@ -678,9 +743,10 @@ declare enum Blockchain {
     Algorand_Testnet = "Algorand_Testnet",
     Aptos = "Aptos",
     Aptos_Testnet = "Aptos_Testnet",
-    Arc_Testnet = "Arc_Testnet",
     Arbitrum = "Arbitrum",
     Arbitrum_Sepolia = "Arbitrum_Sepolia",
+    Arc = "Arc",
+    Arc_Testnet = "Arc_Testnet",
     Avalanche = "Avalanche",
     Avalanche_Fuji = "Avalanche_Fuji",
     Base = "Base",
@@ -746,6 +812,135 @@ declare enum Blockchain {
     ZKSync_Era = "ZKSync_Era",
     ZKSync_Sepolia = "ZKSync_Sepolia"
 }
+/**
+ * Enumeration of blockchains that support cross-chain bridging via CCTPv2.
+ *
+ * The enum is derived from the full {@link Blockchain} enum but filtered to only
+ * include chains with active CCTPv2 support. When new chains gain CCTPv2 support,
+ * they are added to this enum.
+ *
+ * @enum
+ * @category Enums
+ *
+ * @remarks
+ * - This enum is the **canonical source** of bridging-supported chains.
+ * - Use this enum (or its string literals) in `kit.bridge()` calls for type safety.
+ * - Attempting to use a chain not in this enum will produce a TypeScript compile error.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, BridgeChain } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ *
+ * // ✅ Valid - autocomplete suggests only supported chains
+ * await kit.bridge({
+ *   from: { adapter, chain: BridgeChain.Ethereum },
+ *   to: { adapter, chain: BridgeChain.Base },
+ *   amount: '100'
+ * })
+ *
+ * // ✅ Also valid - string literals work with autocomplete
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Ethereum_Sepolia' },
+ *   to: { adapter, chain: 'Base_Sepolia' },
+ *   amount: '100'
+ * })
+ *
+ * // ❌ Compile error - Algorand is not in BridgeChain
+ * await kit.bridge({
+ *   from: { adapter, chain: 'Algorand' }, // TypeScript error!
+ *   to: { adapter, chain: 'Base' },
+ *   amount: '100'
+ * })
+ * ```
+ *
+ * @see {@link Blockchain} for the complete list of all known blockchains.
+ * @see {@link BridgeChainIdentifier} for the type that accepts these values.
+ */
+declare enum BridgeChain {
+    Arbitrum = "Arbitrum",
+    Arc = "Arc",
+    Avalanche = "Avalanche",
+    Base = "Base",
+    Codex = "Codex",
+    Cronos = "Cronos",
+    Edge = "Edge",
+    Ethereum = "Ethereum",
+    HyperEVM = "HyperEVM",
+    Injective = "Injective",
+    Ink = "Ink",
+    Linea = "Linea",
+    Monad = "Monad",
+    Morph = "Morph",
+    Optimism = "Optimism",
+    Pharos = "Pharos",
+    Plasma = "Plasma",
+    Plume = "Plume",
+    Polygon = "Polygon",
+    Sei = "Sei",
+    Solana = "Solana",
+    Sonic = "Sonic",
+    Unichain = "Unichain",
+    World_Chain = "World_Chain",
+    XDC = "XDC",
+    X_Layer = "X_Layer",
+    Arc_Testnet = "Arc_Testnet",
+    Arbitrum_Sepolia = "Arbitrum_Sepolia",
+    Avalanche_Fuji = "Avalanche_Fuji",
+    Base_Sepolia = "Base_Sepolia",
+    Codex_Testnet = "Codex_Testnet",
+    Cronos_Testnet = "Cronos_Testnet",
+    Edge_Testnet = "Edge_Testnet",
+    Ethereum_Sepolia = "Ethereum_Sepolia",
+    HyperEVM_Testnet = "HyperEVM_Testnet",
+    Injective_Testnet = "Injective_Testnet",
+    Ink_Testnet = "Ink_Testnet",
+    Linea_Sepolia = "Linea_Sepolia",
+    Monad_Testnet = "Monad_Testnet",
+    Morph_Testnet = "Morph_Testnet",
+    Optimism_Sepolia = "Optimism_Sepolia",
+    Pharos_Testnet = "Pharos_Testnet",
+    Plasma_Testnet = "Plasma_Testnet",
+    Plume_Testnet = "Plume_Testnet",
+    Polygon_Amoy_Testnet = "Polygon_Amoy_Testnet",
+    Sei_Testnet = "Sei_Testnet",
+    Solana_Devnet = "Solana_Devnet",
+    Sonic_Testnet = "Sonic_Testnet",
+    Unichain_Sepolia = "Unichain_Sepolia",
+    World_Chain_Sepolia = "World_Chain_Sepolia",
+    XDC_Apothem = "XDC_Apothem",
+    X_Layer_Testnet = "X_Layer_Testnet"
+}
+/**
+ * Type representing valid bridge chain identifiers.
+ *
+ * This type constrains chain parameters to only accept chains that support CCTPv2 bridging
+ *
+ * Accepts:
+ * - A {@link BridgeChain} enum value (e.g., `BridgeChain.Ethereum`)
+ * - A string literal matching a BridgeChain value (e.g., `'Ethereum'`)
+ * - A {@link ChainDefinition} object for a supported chain
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeChainIdentifier } from '@circle-fin/bridge-kit'
+ * import { BridgeChain } from '@circle-fin/bridge-kit'
+ * import { Solana } from '@circle-fin/bridge-kit/chains'
+ *
+ * // All of these are valid BridgeChainIdentifier values:
+ * const chain1: BridgeChainIdentifier = BridgeChain.Ethereum
+ * const chain2: BridgeChainIdentifier = 'Base_Sepolia'
+ * const chain3: BridgeChainIdentifier = Solana // ChainDefinition
+ *
+ * // This will cause a TypeScript error:
+ * const chain4: BridgeChainIdentifier = 'Algorand' // Error!
+ * ```
+ *
+ * @see {@link BridgeChain} for the enum of supported chains.
+ * @see {@link ChainIdentifier} for the less restrictive type accepting all chains.
+ */
+type BridgeChainIdentifier = ChainDefinition | BridgeChain | `${BridgeChain}`;
 /**
  * Enumeration of blockchains that support Gateway V1 operations
  * (deposit, spend, balance, delegate, removeFund).
@@ -766,6 +961,7 @@ declare enum Blockchain {
  * @see {@link UnifiedBalanceChainIdentifier} for the type that accepts these values.
  */
 declare enum UnifiedBalanceChain {
+    Arc = "Arc",
     Arbitrum = "Arbitrum",
     Avalanche = "Avalanche",
     Base = "Base",
@@ -1990,6 +2186,171 @@ interface CCTPActionMap {
     readonly v2: CCTPv2ActionMap;
 }
 
+/**
+ * Action map for Circle's CCTPx protocol operations.
+ *
+ * Define the parameter schemas for CCTPx actions that enable cross-chain transfers
+ * of registered tokens (Circle-issued or otherwise) through Circle's `CrossChainTokenService`
+ * (CCTS) contract.
+ *
+ * @remarks
+ * CCTPx is a service-level protocol layered on top of CCTP v2's message-passing layer.
+ * The CCTS contract coordinates token locking/burning, fee collection, and cross-chain
+ * message dispatch. The SDK obtains a signed fee quote from IRIS, then calls
+ * `crossChainTransfer` on CCTS with the quote bytes verbatim and the native fee as
+ * `msg.value`. The auto-relay flow handled by Circle's Orbit relayer (paid for via the
+ * `FORWARD` fee component included in the signed quote) means no separate
+ * `receiveMessage` step is required on the destination.
+ *
+ * USDC and EURC bridging continues to use CCTP v2 (`cctp.v2.*`) actions, not CCTPx.
+ *
+ * @example
+ * ```typescript
+ * import type { ActionPayload } from '@core/adapter'
+ *
+ * const transferParams: ActionPayload<'cctpx.crossChainTransfer'> = {
+ *   tokenId: '0xabc123...',
+ *   amount: 1_000_000n,
+ *   destinationDomain: 1,
+ *   destinationAddress: '0xRecipient',
+ *   destinationCaller: '0x0000000000000000000000000000000000000000000000000000000000000000',
+ *   minFinalityThreshold: 1000,
+ *   claim: { signedQuote: '0xdeadbeef...', refundAddress: '0xSenderEOA...' },
+ *   autoExecuteHookData: false,
+ *   hookData: '0x',
+ *   serviceAddress: '0xCCTSProxy...',
+ *   nativeFeeAmount: 100_000n,
+ *   fromChain,
+ * }
+ * ```
+ */
+interface CCTPXActionMap {
+    /**
+     * Initiate a CCTPx cross-chain transfer through the `CrossChainTokenService` contract.
+     *
+     * Encode and submit a `crossChainTransfer(...)` call to the CCTS proxy on the source
+     * chain, passing the IRIS-signed fee quote bytes verbatim and the native fee as
+     * `msg.value`. The contract emits CCTP v2's `MessageSent` event, which IRIS attests
+     * to before Circle's Orbit relayer auto-executes the destination mint.
+     *
+     * @remarks
+     * The caller (typically `CCTPXBridgingProvider`) is responsible for:
+     * - Resolving `tokenId` and the per-chain `tokenAddress` from the IRIS token registry
+     * - Approving the per-token `TokenManager` for `amount` before this call
+     * - Fetching `claim.signedQuote` and computing `nativeFeeAmount` from IRIS
+     *
+     * This action only encodes and submits the on-chain call; it does not perform any
+     * off-chain orchestration.
+     */
+    crossChainTransfer: ActionParameters & {
+        /**
+         * The CCTPx tokenId for the asset being transferred.
+         *
+         * Provided as a 32-byte hex string assigned by CCTPx at registration time.
+         * The same `tokenId` is used across all chains for a given token; per-chain
+         * `tokenAddress` is resolved from the IRIS token registry separately.
+         */
+        tokenId: string;
+        /**
+         * Amount of the token to transfer, in the token's smallest units.
+         */
+        amount: bigint;
+        /**
+         * CCTP domain identifier of the destination chain.
+         *
+         * CCTPx reuses CCTP v2 domain numbering; pass `dstChain.cctp.domain`.
+         */
+        destinationDomain: number;
+        /**
+         * Recipient address on the destination chain, encoded as bytes.
+         *
+         * For EVM destinations this is a 20-byte address encoded as a hex string.
+         */
+        destinationAddress: string;
+        /**
+         * `bytes32` value restricting which address may execute on the destination.
+         *
+         * Omit (or pass the 32-byte zero hash) to allow permissionless relay — the
+         * default for auto-relayed CCTPx transfers. When omitted, the handler
+         * substitutes the zero hash.
+         *
+         * @defaultValue `ZERO_HASH` — permissionless relay
+         */
+        destinationCaller?: string;
+        /**
+         * Minimum finality threshold for attestation eligibility.
+         *
+         * Use `1000` for FAST transfers (pre-finality) or `2000` for SLOW transfers
+         * (full finality). For FAST, the `claim.signedQuote` must include a
+         * `PRE_FINALITY` item; otherwise the on-chain call reverts.
+         */
+        minFinalityThreshold: number;
+        /**
+         * The CCTS fee-quote claim — maps 1:1 to the on-chain
+         * `IFeeManager.QuoteClaim` tuple.
+         *
+         * The contract requires a tuple here, not a flat bytes blob. Encoding the
+         * signed quote without the tuple wrapper produces a different function
+         * selector and the call will revert.
+         */
+        claim: {
+            /**
+             * IRIS-signed fee quote bytes, passed verbatim to the contract.
+             *
+             * Obtained from `POST /v1/quote/cctpx/{tokenId}/{src}/{dst}`. Contains the
+             * version-prefixed ABI-encoded `Quote` struct and Circle's signature; the
+             * `FeeManager` contract validates the signature against the quote items.
+             */
+            signedQuote: string;
+            /**
+             * Address that receives any native-fee refund from `FeeManager`.
+             *
+             * Forwarded verbatim to `FeeManager` for refund attribution. The contract
+             * accepts `address(0)` (the zero address) to disable refunds, so omitting
+             * this field is safe; the handler will substitute the zero address.
+             *
+             * @defaultValue `ZERO_ADDRESS` — refunds disabled
+             */
+            refundAddress?: string;
+        };
+        /**
+         * Whether the destination chain should auto-execute the hook data.
+         *
+         * For basic transfers this is `false`. Reserved for advanced integrations
+         * that bundle a post-mint hook on the destination.
+         */
+        autoExecuteHookData: boolean;
+        /**
+         * Optional hook data bytes passed through to the destination handler.
+         *
+         * Pass `'0x'` (empty bytes) for basic transfers.
+         */
+        hookData: string;
+        /**
+         * The `CrossChainTokenService` proxy address on the source chain.
+         *
+         * Used as the transaction `to` field. Typically sourced from
+         * `srcChain.cctpx.serviceAddress` — but is passed as an explicit parameter
+         * so the action does not depend on chain-config narrowing at the call site.
+         */
+        serviceAddress: string;
+        /**
+         * Native gas amount to send as `msg.value`.
+         *
+         * Must exactly equal `sum(quote.items[].amount)` when `feeToken` is the
+         * native currency (the P0 default). The contract verifies the value against
+         * the signed quote; do not over-send.
+         */
+        nativeFeeAmount: bigint;
+        /**
+         * Source chain definition.
+         *
+         * Provides the adapter with chain context (chainId, RPC, etc.) for the call.
+         */
+        fromChain: ChainDefinition;
+    };
+}
+
 /**
  * Permit signature standards for gasless token approvals.
  *
@@ -3085,6 +3446,8 @@ interface NativeActionMap {
 interface ActionMap {
     /** CCTP-specific operations with automatic address resolution. */
     readonly cctp: CCTPActionMap;
+    /** CCTPx operations (CrossChainTokenService) for cross-chain transfers of registered tokens (Circle-issued or otherwise). */
+    readonly cctpx: CCTPXActionMap;
     /** Gateway Wallet operations, versioned (e.g. gateway.v1.deposit). */
     readonly gateway: GatewayActionMap;
     /** Native token operations (ETH, SOL, MATIC, etc.). */
@@ -4408,63 +4771,140 @@ interface DepositResult$1 {
 }
 
 /**
- * Data payload for a single step in a spend operation.
+ * Fee category describing the origin of a fee line item.
  *
- * @remarks
- * Each spend step carries its current state, optional transaction details,
- * and error information when the step fails.
+ * - `'provider'`  — Fee charged by the cross-chain provider (e.g. protocol fee).
+ * - `'gasFee'`    — On-chain gas cost denominated in the transfer token (e.g. USDC).
+ * - `'kit'`       — Fee charged by the kit / developer integration.
+ * - `'forwarder'` — Fee charged by Circle's Forwarding Service for automatic mint.
+ */
+type FeeType = 'provider' | 'gasFee' | 'kit' | 'forwarder';
+/**
+ * Per-chain breakdown of a fee amount.
  *
  * @example
  * ```typescript
- * import type { SpendStep } from '@circle-fin/provider-gateway-v1'
+ * import type { FeeAllocation } from '@core/types'
+ * import { Blockchain } from '@core/chains'
  *
- * const step: SpendStep = {
- *   name: 'mint',
- *   state: 'success',
- *   txHash: '0xabc…',
- *   explorerUrl: 'https://basescan.org/tx/0xabc…',
+ * const allocation: FeeAllocation = {
+ *   chain: Blockchain.Ethereum,
+ *   amount: '0.00005',
  * }
  * ```
  */
-interface SpendStep {
-    /** Human-readable name of the step (e.g., "buildBurnIntents", "mint"). */
-    name: string;
-    /** The state of the step. */
-    state: 'pending' | 'success' | 'error';
-    /** Optional transaction hash for this step (if applicable). */
-    txHash?: string;
-    /** Optional explorer URL for viewing this transaction on a block explorer. */
-    explorerUrl?: string;
-    /** Optional data for the step. */
-    data?: unknown;
-    /** Optional human-readable error message. */
-    errorMessage?: string;
-    /** Optional raw error object. */
-    error?: unknown;
+interface FeeAllocation {
+    /** The chain to which this portion of the fee applies. */
+    chain: Blockchain;
+    /** The fee amount on this chain (human-readable decimal string). */
+    amount: string;
 }
 /**
- * Destination for a Gateway spend (mint) operation.
+ * A single fee line item within an estimate.
  *
  * @remarks
- * Omitting `recipientAddress` causes funds to be minted to the
- * address resolved from the adapter.  Providing it overrides the
- * default destination.
- *
- * @typeParam TAdapterCapabilities - Adapter capability constraints.
- * @typeParam TChainIdentifier - Accepted chain identifier type.
+ * Each entry describes a fee category (`type`), the token it is
+ * denominated in, the aggregate `amount`, and an optional per-chain
+ * `allocations` breakdown.
  *
  * @example
  * ```typescript
- * import type { SpendDestination } from '@circle-fin/provider-gateway-v1'
+ * import type { FeeEntry } from '@core/types'
+ * import { Blockchain } from '@core/chains'
  *
- * const destination: SpendDestination = {
- *   adapter: avalancheAdapter,
- *   chain: 'Avalanche',
- *   recipientAddress: '0xDEST…abcd',
+ * // Fee with per-chain allocation breakdown
+ * const providerFee: FeeEntry = {
+ *   type: 'provider',
+ *   token: 'USDC',
+ *   amount: '0.00011',
+ *   allocations: [
+ *     { chain: Blockchain.Ethereum, amount: '0.00005' },
+ *     { chain: Blockchain.Polygon, amount: '0.00006' },
+ *   ],
  * }
- * ```
- */
-type SpendDestination$1<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier> = {
+ *
+ * // Flat fee without allocations (e.g. forwarder)
+ * const forwarderFee: FeeEntry = {
+ *   type: 'forwarder',
+ *   token: 'USDC',
+ *   amount: '0.005',
+ * }
+ * ```
+ */
+interface FeeEntry {
+    /** The category of this fee. */
+    type: FeeType;
+    /** The token in which this fee is denominated (e.g. `'USDC'`, `'ETH'`). */
+    token: string;
+    /** Aggregate fee amount (human-readable decimal string). */
+    amount: string;
+    /** Per-chain breakdown of the fee. Omitted for flat fees (e.g. forwarder). */
+    allocations?: FeeAllocation[];
+    /**
+     * When `type === 'kit'`, the address that receives the kit fee.
+     * Omitted for other fee types.
+     */
+    recipientAddress?: string;
+}
+
+/**
+ * Data payload for a single step in a spend operation.
+ *
+ * @remarks
+ * Each spend step carries its current state, optional transaction details,
+ * and error information when the step fails.
+ *
+ * @example
+ * ```typescript
+ * import type { SpendStep } from '@circle-fin/provider-gateway-v1'
+ *
+ * const step: SpendStep = {
+ *   name: 'mint',
+ *   state: 'success',
+ *   txHash: '0xabc…',
+ *   explorerUrl: 'https://basescan.org/tx/0xabc…',
+ * }
+ * ```
+ */
+interface SpendStep {
+    /** Human-readable name of the step (e.g., "buildBurnIntents", "mint"). */
+    name: string;
+    /** The state of the step. */
+    state: 'pending' | 'success' | 'error';
+    /** Optional transaction hash for this step (if applicable). */
+    txHash?: string;
+    /** Optional explorer URL for viewing this transaction on a block explorer. */
+    explorerUrl?: string;
+    /** Optional data for the step. */
+    data?: unknown;
+    /** Optional human-readable error message. */
+    errorMessage?: string;
+    /** Optional raw error object. */
+    error?: unknown;
+}
+/**
+ * Destination for a Gateway spend (mint) operation.
+ *
+ * @remarks
+ * Omitting `recipientAddress` causes funds to be minted to the
+ * address resolved from the adapter.  Providing it overrides the
+ * default destination.
+ *
+ * @typeParam TAdapterCapabilities - Adapter capability constraints.
+ * @typeParam TChainIdentifier - Accepted chain identifier type.
+ *
+ * @example
+ * ```typescript
+ * import type { SpendDestination } from '@circle-fin/provider-gateway-v1'
+ *
+ * const destination: SpendDestination = {
+ *   adapter: avalancheAdapter,
+ *   chain: 'Avalanche',
+ *   recipientAddress: '0xDEST…abcd',
+ * }
+ * ```
+ */
+type SpendDestination$1<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier> = {
     /** The adapter for executing on-chain calls. */
     adapter: Adapter<TAdapterCapabilities>;
     /** The destination chain. */
@@ -4766,7 +5206,7 @@ interface SpendResult$1 {
      * executed spend. Same shape as {@link EstimateSpendResult.fees}.
      * Omitted when using `config.retry` (no estimate was run).
      */
-    fees?: FeeEntry$1[];
+    fees?: FeeEntry[];
     /**
      * Gateway transfer identifier. Present when `useForwarder` is enabled
      * and can be used to query transfer status via `GET /v1/transfer/{id}`.
@@ -4788,80 +5228,6 @@ interface SpendResult$1 {
      */
     steps?: SpendStep[];
 }
-/**
- * Fee category describing the origin of a fee line item.
- *
- * - `'provider'`  — Fee charged by the cross-chain provider (e.g. protocol fee).
- * - `'gasFee'`    — On-chain gas cost denominated in the transfer token (e.g. USDC).
- * - `'kit'`       — Fee charged by the kit / developer integration.
- * - `'forwarder'` — Fee charged by Circle's Forwarding Service for automatic mint.
- */
-type FeeType$1 = 'provider' | 'gasFee' | 'kit' | 'forwarder';
-/**
- * Per-chain breakdown of a fee amount.
- *
- * @example
- * ```typescript
- * import type { FeeAllocation } from '@circle-fin/provider-gateway-v1'
- *
- * const allocation: FeeAllocation = {
- *   chain: 'Ethereum',
- *   amount: '0.00005',
- * }
- * ```
- */
-interface FeeAllocation$1 {
-    /** The chain to which this portion of the fee applies. */
-    chain: Blockchain;
-    /** The fee amount on this chain (human-readable decimal string). */
-    amount: string;
-}
-/**
- * A single fee line item within an estimate.
- *
- * @remarks
- * Each entry describes a fee category (`type`), the token it is
- * denominated in, the aggregate `amount`, and an optional per-chain
- * `allocations` breakdown.
- *
- * @example
- * ```typescript
- * import type { FeeEntry } from '@circle-fin/provider-gateway-v1'
- *
- * // Fee with per-chain allocation breakdown
- * const providerFee: FeeEntry = {
- *   type: 'provider',
- *   token: 'USDC',
- *   amount: '0.00011',
- *   allocations: [
- *     { chain: 'Ethereum', amount: '0.00005' },
- *     { chain: 'Polygon', amount: '0.00006' },
- *   ],
- * }
- *
- * // Flat fee without allocations (e.g. forwarder)
- * const forwarderFee: FeeEntry = {
- *   type: 'forwarder',
- *   token: 'USDC',
- *   amount: '0.005',
- * }
- * ```
- */
-interface FeeEntry$1 {
-    /** The category of this fee. */
-    type: FeeType$1;
-    /** The token in which this fee is denominated (e.g. `'USDC'`, `'ETH'`). */
-    token: string;
-    /** Aggregate fee amount (human-readable decimal string). */
-    amount: string;
-    /** Per-chain breakdown of the fee. Omitted for flat fees (e.g. forwarder). */
-    allocations?: FeeAllocation$1[];
-    /**
-     * When `type === 'kit'`, the address that receives the kit fee.
-     * Omitted for other fee types.
-     */
-    recipientAddress?: string;
-}
 /**
  * Cost estimation for a spend (mint) operation.
  *
@@ -4909,7 +5275,7 @@ interface FeeEntry$1 {
  */
 interface EstimateSpendResult$1 {
     /** Itemised fee breakdown for the spend operation. */
-    fees: FeeEntry$1[];
+    fees: FeeEntry[];
 }
 
 /**
@@ -6296,80 +6662,7 @@ type FeeRecipientChainType = 'evm' | 'solana';
  * ```
  */
 type FeeRecipientsConfig = Partial<Record<FeeRecipientChainType, string>>;
-/**
- * Fee category describing the origin of a fee line item.
- *
- * - `'provider'`  — Fee charged by the cross-chain provider (e.g. protocol fee).
- * - `'gasFee'`    — On-chain gas cost denominated in the transfer token (e.g. USDC).
- * - `'kit'`       — Fee charged by the kit / developer integration.
- * - `'forwarder'` — Fee charged by Circle's Forwarding Service for automatic mint.
- */
-type FeeType = 'provider' | 'gasFee' | 'kit' | 'forwarder';
-/**
- * Per-chain breakdown of a fee amount.
- *
- * @example
- * ```typescript
- * import type { FeeAllocation } from '@circle-fin/unified-balance-kit'
- *
- * const allocation: FeeAllocation = {
- *   chain: 'Ethereum',
- *   amount: '0.00005',
- * }
- * ```
- */
-interface FeeAllocation {
-    /** The chain to which this portion of the fee applies. */
-    chain: Blockchain;
-    /** The fee amount on this chain (human-readable decimal string). */
-    amount: string;
-}
-/**
- * A single fee line item within an estimate.
- *
- * @remarks
- * Each entry describes a fee category (`type`), the token it is
- * denominated in, the aggregate `amount`, and an optional per-chain
- * `allocations` breakdown.
- *
- * @example
- * ```typescript
- * import type { FeeEntry } from '@circle-fin/unified-balance-kit'
- *
- * // Fee with per-chain allocation breakdown
- * const providerFee: FeeEntry = {
- *   type: 'provider',
- *   token: 'USDC',
- *   amount: '0.00011',
- *   allocations: [
- *     { chain: 'Ethereum', amount: '0.00005' },
- *     { chain: 'Polygon', amount: '0.00006' },
- *   ],
- * }
- *
- * // Flat fee without allocations (e.g. forwarder)
- * const forwarderFee: FeeEntry = {
- *   type: 'forwarder',
- *   token: 'USDC',
- *   amount: '0.005',
- * }
- * ```
- */
-interface FeeEntry {
-    /** The category of this fee. */
-    type: FeeType;
-    /** The token in which this fee is denominated (e.g. `'USDC'`, `'ETH'`). */
-    token: string;
-    /** Aggregate fee amount (human-readable decimal string). */
-    amount: string;
-    /** Per-chain breakdown of the fee. Omitted for flat fees (e.g. forwarder). */
-    allocations?: FeeAllocation[];
-    /**
-     * When `type === 'kit'`, the address that receives the kit fee.
-     * Omitted for other fee types.
-     */
-    recipientAddress?: string;
-}
+
 /**
  * Cost estimation for a spend (mint) operation.
  *
@@ -6570,6 +6863,21 @@ interface UnifiedBalanceKitConfig<TExtraProviders extends FlexibleGatewayProvide
     headers?: Record<string, string>;
 }
 
+/**
+ * USD exchange-rate metadata.
+ *
+ * Non-binding, useful for USD-denominated fee estimates. `feeTokenUsd` prices
+ * the source-chain fee token (the token `feeTotalAmount` is denominated in).
+ *
+ * @internal
+ */
+interface FeeQuoteExchangeRates {
+    /** USD price of the fee token, as a decimal string. */
+    readonly feeTokenUsd: string;
+    /** USD price of the destination token, as a decimal string. */
+    readonly destinationTokenUsd: string;
+}
+
 /**
  * Token allowance strategy used to authorize a Gateway deposit.
  *
@@ -6609,7 +6917,7 @@ type AllowanceStrategy = 'approve' | 'permit' | 'authorize';
  * }
  * ```
  */
-interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier> {
+interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends BridgeChainIdentifier = BridgeChainIdentifier> {
     /**
      * The adapter context identifying the depositor and chain.
      */
@@ -6622,7 +6930,7 @@ interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = Adapt
     amount: string;
     /**
      * The token to deposit.
-     * Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalised to uppercase internally.
+     * Accepts any case (e.g. `'usdc'`, `'Usdc'`); normalized to uppercase internally.
      *
      * @defaultValue 'USDC'
      */
@@ -6630,9 +6938,40 @@ interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = Adapt
     /**
      * The token allowance strategy to authorize the deposit.
      *
+     * Only valid for same-chain (STANDARD) deposits. Must not be set when
+     * `to` is provided (FAST cross-chain deposits do not use an allowance
+     * strategy).
+     *
      * @defaultValue 'authorize'
      */
     allowanceStrategy?: AllowanceStrategy;
+    /**
+     * Destination chain for a FAST cross-chain deposit.
+     *
+     * When set, the deposit follows the prepaid-FORWARD CCTP v2 path:
+     * the burned USDC is minted to the GenericExecutor on the destination
+     * chain, which then calls Gateway `deposit` in a single relayed flow.
+     *
+     * Must not be set when `config.transferSpeed` is `'STANDARD'`.
+     */
+    to?: {
+        chain: UnifiedBalanceChainIdentifier;
+    };
+    /**
+     * Transfer configuration for the deposit.
+     *
+     * @defaultValue `{ transferSpeed: 'STANDARD' }`. Set `transferSpeed: 'FAST'`
+     *   explicitly for cross-chain deposits (when `to` is provided).
+     */
+    config?: DepositConfig;
+    /**
+     * Opaque signed fee-quote bytes from the Quote API.
+     *
+     * Pass this to commit to the fee price returned by a previous
+     * {@link estimateDeposit} call (see {@link EstimateDepositResult.quote}).
+     * When omitted a fresh quote is fetched automatically (FAST path only).
+     */
+    quote?: string;
 }
 /**
  * Parameters for depositing tokens into *another* Gateway account.
@@ -6659,7 +6998,7 @@ interface DepositParams<TAdapterCapabilities extends AdapterCapabilities = Adapt
  * }
  * ```
  */
-interface DepositForParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends UnifiedBalanceChainIdentifier = UnifiedBalanceChainIdentifier> extends Omit<DepositParams<TAdapterCapabilities, TChainIdentifier>, 'allowanceStrategy'> {
+interface DepositForParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends BridgeChainIdentifier = BridgeChainIdentifier> extends Omit<DepositParams<TAdapterCapabilities, TChainIdentifier>, 'allowanceStrategy'> {
     /**
      * The Gateway account address to credit with the deposit.
      *
@@ -6668,6 +7007,34 @@ interface DepositForParams<TAdapterCapabilities extends AdapterCapabilities = Ad
      */
     depositAccount: string;
 }
+/**
+ * Relay progress for a cross-chain (FAST) deposit.
+ *
+ * Set after `depositFastCrossChain` completes the ~60-second relay wait.
+ * Always present on the FAST path; absent on same-chain STANDARD deposits.
+ *
+ * @example
+ * ```typescript
+ * if (result.progress?.status === 'DONE') {
+ *   console.log('Minted on destination:', result.txHash)
+ * } else if (result.progress?.status === 'PENDING') {
+ *   console.log('Relay still in progress — poll getDepositStatus later')
+ * } else if (result.progress?.status === 'FAILED') {
+ *   console.log('Relay failed — manual mint may be required')
+ * }
+ * ```
+ */
+interface DepositProgress {
+    /**
+     * Relay outcome after the burn is confirmed on the source chain.
+     *
+     * - `'DONE'`    — Circle's relayer minted USDC on the destination chain.
+     * - `'PENDING'` — Relay timed out (~60 s); the mint may still complete.
+     * - `'FAILED'`  — Relayer reported a permanent failure; manual mint may
+     *                 be required.
+     */
+    status: 'DONE' | 'PENDING' | 'FAILED';
+}
 /**
  * Result returned after a successful deposit operation.
  *
@@ -6697,22 +7064,232 @@ interface DepositResult {
     depositedTo: string;
     /** The address that signed and funded the deposit. */
     depositedBy: string;
-    /** The chain on which the deposit occurred. */
+    /**
+     * The chain where the deposit balance lands.
+     *
+     * @remarks For cross-chain (FAST) deposits this is the destination chain
+     * where the minted USDC is credited. For same-chain (STANDARD) deposits it
+     * is the chain the deposit occurred on. Prefer `sourceChain` /
+     * `destinationChain` for cross-chain flows.
+     */
     chain: Blockchain;
     /**
-     * Unique identifier returned by the blockchain once the
-     * transaction is mined.
+     * Transaction hash of the completed deposit.
+     *
+     * @remarks
+     * For same-chain (STANDARD) deposits this is the on-chain deposit
+     * transaction. For cross-chain (FAST) deposits with
+     * `progress.status === 'DONE'` this is the Circle-relayed mint on the
+     * destination chain; when the relay is still pending or has failed it
+     * falls back to the source-chain burn hash.
      */
     txHash: string;
     /**
-     * Link to view the transaction details on the appropriate
-     * blockchain explorer.
+     * Link to view the transaction on a block explorer.
      *
      * @remarks
-     * May be `undefined` when the explorer URL cannot be resolved
-     * for the chain.
+     * Follows the same chain as {@link txHash}: points to the destination-chain
+     * mint for a completed FAST deposit, or the source-chain burn otherwise.
+     * May be `undefined` when the chain has no configured explorer URL.
      */
     explorerUrl?: string;
+    /**
+     * Source chain of the cross-chain deposit (FAST path only).
+     *
+     * Present when `to` was specified in the deposit params.
+     */
+    sourceChain?: Blockchain;
+    /**
+     * Destination chain of the cross-chain deposit (FAST path only).
+     *
+     * Present when `to` was specified in the deposit params.
+     */
+    destinationChain?: Blockchain;
+    /**
+     * Itemised fee breakdown for the cross-chain deposit (FAST path only).
+     *
+     * Contains at least a `gasFee` entry and a `forwarder` entry (Circle
+     * FORWARD fee). The `gasFee` covers the source-chain burn gas; when a
+     * `usdc.approve` was required it also includes the actual on-chain approve
+     * gas derived from the transaction receipt.
+     */
+    fees?: FeeEntry[];
+    /**
+     * Relay progress after the source-chain burn (FAST path only).
+     *
+     * Present on every FAST deposit result. Use this to determine whether
+     * the destination-chain mint completed within the ~60-second relay window.
+     */
+    progress?: DepositProgress;
+}
+/**
+ * Transfer-speed configuration for a deposit operation.
+ *
+ * @example
+ * ```typescript
+ * import type { DepositConfig } from '@circle-fin/unified-balance-kit'
+ *
+ * const config: DepositConfig = { transferSpeed: 'FAST' }
+ * ```
+ */
+interface DepositConfig {
+    /**
+     * Requested transfer speed for a cross-chain fast deposit.
+     *
+     * @defaultValue `'STANDARD'`
+     */
+    transferSpeed?: 'FAST' | 'STANDARD';
+}
+/**
+ * Parameters for estimating the fees of a fast cross-chain deposit.
+ *
+ * The result is plain, serializable data — no live adapter reference is
+ * included. Pass the result (plus `from`) directly to
+ * {@link DepositParams} or {@link DepositForParams} for execution:
+ *
+ * ```typescript
+ * const estimate = await kit.estimateDeposit({ from, amount, token, to })
+ * const result   = await kit.deposit({ ...estimate, from })
+ * ```
+ *
+ * @typeParam TAdapterCapabilities - Adapter capability constraints.
+ * @typeParam TChainIdentifier - Accepted chain identifier type.
+ *
+ * @example
+ * ```typescript
+ * import type { EstimateDepositParams } from '@circle-fin/unified-balance-kit'
+ *
+ * const params: EstimateDepositParams = {
+ *   from: { adapter: evmAdapter, chain: 'Ethereum' },
+ *   amount: '100',
+ *   to: { chain: 'Arc_Testnet' },
+ *   config: { transferSpeed: 'FAST' },
+ * }
+ * ```
+ */
+interface EstimateDepositParams<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends BridgeChainIdentifier = BridgeChainIdentifier> {
+    /**
+     * The adapter context identifying the depositor and source chain.
+     * The adapter is used for source-chain gas estimation.
+     */
+    from: AdapterContext<TAdapterCapabilities, TChainIdentifier>;
+    /**
+     * The amount of tokens to deposit (human-readable decimal string).
+     *
+     * @example "100", "0.5"
+     */
+    amount: string;
+    /**
+     * The token to deposit.
+     *
+     * @defaultValue 'USDC'
+     */
+    token?: SupportedTokenInput;
+    /**
+     * Destination chain for a FAST cross-chain deposit.
+     *
+     * Required when `config.transferSpeed` is `'FAST'`.
+     * Must not be set when `config.transferSpeed` is `'STANDARD'` (the default).
+     */
+    to?: {
+        chain: UnifiedBalanceChainIdentifier;
+    };
+    /**
+     * Transfer configuration.
+     *
+     * @defaultValue `{ transferSpeed: 'STANDARD' }`
+     */
+    config?: DepositConfig;
+    /**
+     * Gateway account address to credit (for a `depositFor` round-trip).
+     *
+     * When provided, this value is echoed on the result so
+     * `kit.depositFor({ ...estimate, from })` works without re-specifying it.
+     */
+    depositAccount?: string;
+    /**
+     * Allowance strategy echoed to the result for round-trip convenience.
+     */
+    allowanceStrategy?: AllowanceStrategy;
+}
+/**
+ * Fee-preview result returned by `estimateDeposit`.
+ *
+ * Plain, serializable data — no live adapter reference. Pass the result
+ * directly to `deposit` or `depositFor` (re-attaching only `from`):
+ *
+ * ```typescript
+ * const estimate = await kit.estimateDeposit({ from, amount, token, to })
+ * const result   = await kit.deposit({ ...estimate, from })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import type { EstimateDepositResult } from '@circle-fin/unified-balance-kit'
+ *
+ * const result: EstimateDepositResult = {
+ *   amount: '100',
+ *   token: 'USDC',
+ *   to: { chain: 'Arc_Testnet' },
+ *   config: { transferSpeed: 'FAST' },
+ *   fees: [
+ *     { type: 'gasFee',    token: 'ETH',  amount: '0.0002' },
+ *     { type: 'forwarder', token: 'USDC', amount: '0.12'   },
+ *   ],
+ *   quote: '0x…',
+ * }
+ * ```
+ */
+interface EstimateDepositResult {
+    /** Deposit amount (human-readable decimal string). */
+    amount: string;
+    /** Normalized token to deposit. */
+    token: SupportedToken;
+    /**
+     * Destination chain (echoed from input).
+     *
+     * Present for FAST transfers; absent for STANDARD.
+     */
+    to?: {
+        chain: UnifiedBalanceChainIdentifier;
+    };
+    /** Transfer configuration (echoed with defaults applied). */
+    config: Required<DepositConfig>;
+    /**
+     * Itemized fee breakdown.
+     *
+     * Always contains at least a `gasFee` entry. For FAST transfers the gas
+     * cost includes the source-chain burn; when the current USDC allowance is
+     * insufficient it also includes the `usdc.approve` transaction. For
+     * STANDARD deposits on EVM with `allowanceStrategy: 'approve'`, or any
+     * `depositFor` on EVM, the gas cost includes both the
+     * `usdc.increaseAllowance` and the deposit transaction. A `forwarder`
+     * entry is always present for FAST cross-chain transfers.
+     */
+    fees: FeeEntry[];
+    /**
+     * Opaque signed fee-quote bytes from the Quote API.
+     *
+     * Present for FAST cross-chain deposits; absent for STANDARD or
+     * same-chain. Pass this to {@link deposit} or {@link depositFor} to
+     * commit to the quoted price.
+     */
+    quote?: string;
+    /**
+     * Gateway account to credit (echoed from input for `depositFor` round-trip).
+     */
+    depositAccount?: string;
+    /**
+     * Allowance strategy (echoed from input for `deposit` round-trip).
+     */
+    allowanceStrategy?: AllowanceStrategy;
+    /**
+     * Optional USD exchange-rate metadata from the Quote API.
+     *
+     * Present when the Quote API returns exchange rates for the fee token
+     * and destination token. Non-binding; useful for USD-denominated display.
+     */
+    exchangeRates?: FeeQuoteExchangeRates;
 }
 
 /**
@@ -7460,6 +8037,35 @@ declare class AppKitUnifiedBalance {
      * ```
      */
     depositFor(params: DepositForParams): Promise<DepositResult>;
+    /**
+     * Estimate the fees for a deposit without executing it.
+     *
+     * Return plain, serializable data that can be spread directly into
+     * {@link AppKitUnifiedBalance.deposit} or
+     * {@link AppKitUnifiedBalance.depositFor}.
+     *
+     * @param params - Estimate details including the depositor context, amount,
+     *   destination chain, and optional transfer speed.
+     * @returns Promise resolving to the itemised fee estimate.
+     * @throws {KitError} If the estimate parameters are invalid or the route is
+     *   unsupported.
+     *
+     * @example
+     * ```typescript
+     * const estimate = await kit.unifiedBalance.estimateDeposit({
+     *   from: { adapter, chain: 'Ethereum' },
+     *   amount: '100',
+     *   to: { chain: 'Polygon' },
+     *   config: { transferSpeed: 'FAST' },
+     * })
+     *
+     * const result = await kit.unifiedBalance.deposit({
+     *   ...estimate,
+     *   from: { adapter, chain: 'Ethereum' },
+     * })
+     * ```
+     */
+    estimateDeposit(params: EstimateDepositParams): Promise<EstimateDepositResult>;
     /**
      * Spend (mint) USDC on a destination chain by pulling funds from one or
      * more account sources.