@circle-fin/app-kit 1.13.0 → 1.15.0

package/bridge.d.ts

@@ -167,6 +167,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.
      *
@@ -486,6 +510,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.
  *
@@ -559,6 +611,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.
@@ -679,9 +744,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",
@@ -860,6 +926,7 @@ declare enum SwapChain {
     XDC = "XDC",
     HyperEVM = "HyperEVM",
     Monad = "Monad",
+    Arc = "Arc",
     Arc_Testnet = "Arc_Testnet"
 }
 /**
@@ -873,7 +940,7 @@ declare enum SwapChain {
  * Use `isSwapSupportedChain()` for runtime validation.
  */
 type SwapChainDefinition = ChainDefinition & {
-    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc_Testnet;
+    chain: Blockchain.Ethereum | Blockchain.Base | Blockchain.Polygon | Blockchain.Solana | Blockchain.Arbitrum | Blockchain.Optimism | Blockchain.Avalanche | Blockchain.Linea | Blockchain.Ink | Blockchain.World_Chain | Blockchain.Unichain | Blockchain.Plume | Blockchain.Sei | Blockchain.Sonic | Blockchain.XDC | Blockchain.HyperEVM | Blockchain.Monad | Blockchain.Arc | Blockchain.Arc_Testnet;
 };
 /**
  * Chain identifier accepted by swap operations.
@@ -934,6 +1001,7 @@ type SwapChainIdentifier = SwapChainDefinition | SwapChain | `${SwapChain}`;
  */
 declare enum BridgeChain {
     Arbitrum = "Arbitrum",
+    Arc = "Arc",
     Avalanche = "Avalanche",
     Base = "Base",
     Codex = "Codex",
@@ -1030,6 +1098,7 @@ type BridgeChainIdentifier = ChainDefinition | BridgeChain | `${BridgeChain}`;
  * ```
  */
 declare enum EarnChain {
+    Arc = "Arc",
     Arc_Testnet = "Arc_Testnet"
 }
 /**
@@ -1063,7 +1132,7 @@ type EarnChainIdentifier = EarnChainDefinition | EarnChain | `${EarnChain}`;
  * console.log(EARN_BRIDGE_SOURCE_BLOCKCHAINS.join(', '))
  * ```
  */
-declare const EARN_BRIDGE_SOURCE_BLOCKCHAINS: readonly [Blockchain.Arbitrum_Sepolia, Blockchain.Base_Sepolia, Blockchain.Ethereum_Sepolia];
+declare const EARN_BRIDGE_SOURCE_BLOCKCHAINS: readonly [Blockchain.Arbitrum, Blockchain.Arbitrum_Sepolia, Blockchain.Base, Blockchain.Base_Sepolia, Blockchain.Ethereum, Blockchain.Ethereum_Sepolia];
 /**
  * Blockchains supported as the source chain for cross-chain Earn deposits.
  *
@@ -1103,13 +1172,13 @@ type EarnBridgeSourceChainIdentifier = EarnBridgeSourceChainDefinition | EarnBri
  * console.log(EARN_BRIDGE_DESTINATION_BLOCKCHAINS.join(', '))
  * ```
  */
-declare const EARN_BRIDGE_DESTINATION_BLOCKCHAINS: readonly [Blockchain.Arc_Testnet];
+declare const EARN_BRIDGE_DESTINATION_BLOCKCHAINS: readonly [Blockchain.Arc, Blockchain.Arc_Testnet];
 /**
  * Blockchains supported as the destination (vault) chain for cross-chain Earn
  * deposits.
  *
  * Intentionally narrower than {@link EarnChain}: cross-chain deposits
- * currently land only on Arc Testnet.
+ * land on Arc (mainnet) or Arc Testnet.
  */
 type EarnBridgeDestinationBlockchain = (typeof EARN_BRIDGE_DESTINATION_BLOCKCHAINS)[number];
 /**
@@ -1122,13 +1191,13 @@ type EarnBridgeDestinationChainDefinition = ChainDefinition & {
 };
 /**
  * Chain identifier accepted for the destination (vault) side of a cross-chain
- * Earn deposit. Constrains the destination to Arc Testnet.
+ * Earn deposit. Constrains the destination to Arc or Arc Testnet.
  *
  * @example
  * ```typescript
  * import type { EarnBridgeDestinationChainIdentifier } from '@core/chains'
  *
- * const destination: EarnBridgeDestinationChainIdentifier = 'Arc_Testnet'
+ * const destination: EarnBridgeDestinationChainIdentifier = 'Arc'
  * ```
  */
 type EarnBridgeDestinationChainIdentifier = EarnBridgeDestinationChainDefinition | EarnBridgeDestinationBlockchain | `${EarnBridgeDestinationBlockchain}`;
@@ -2345,6 +2414,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.
  *
@@ -3440,6 +3674,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.). */
@@ -4564,29 +4800,15 @@ interface TokenSymbolRegistry {
  */
 type TokenSymbol = keyof TokenSymbolRegistry extends never ? string : LiteralUnion<Extract<keyof TokenSymbolRegistry, string>>;
 /**
- * Selector for identifying a token.
+ * Token selector accepted by adapters and the static
+ * {@link TokenRegistry.resolve} method.
  *
  * @remarks
- * Can be one of:
- * - A symbol string (e.g., "USDC") - resolves from registry
- * - A raw locator object with explicit decimals - for arbitrary tokens
- *
- * Using a symbol is preferred when the token is in the registry, as it
- * automatically resolves decimals and the correct chain address.
- *
- * @example
- * ```typescript
- * // By symbol (preferred for known tokens)
- * const selector1: TokenSelector = 'USDC'
- *
- * // By raw locator (for arbitrary tokens)
- * const selector2: TokenSelector = {
- *   locator: '0x1234...',
- *   decimals: 18,
- * }
- * ```
+ * Keep this alias at adapter and registry boundaries so their accepted token
+ * forms remain explicit even when other product surfaces define narrower
+ * token inputs.
  */
-type TokenSelector = TokenSymbol | RawTokenSelector;
+type RegistryTokenSelector = TokenSymbol | RawTokenSelector;
 /**
  * The resolved token information after registry lookup.
  *
@@ -4636,12 +4858,12 @@ interface TokenRegistry {
     /**
      * Resolve a token selector to concrete token information for a chain.
      *
-     * @param selector - The token to resolve (symbol or raw locator).
+     * @param selector - The token to resolve. Accepts a symbol or raw locator.
      * @param chainId - The chain identifier to resolve for.
      * @returns The resolved token information.
      * @throws When the token cannot be resolved (unknown symbol, missing decimals, etc.).
      */
-    resolve(selector: TokenSelector, chainId: ChainIdentifier): ResolvedToken;
+    resolve(selector: RegistryTokenSelector, chainId: ChainIdentifier): ResolvedToken;
     /**
      * Resolve a token by chain-specific locator (address/program ID).
      *
@@ -5463,6 +5685,55 @@ TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContex
      * Must be a valid address format for the specified blockchain.
      */
     recipientAddress?: string;
+    /**
+     * Whether Circle's relayer submits the destination transaction.
+     *
+     * How an omitted value resolves, and whether an explicit `false` is accepted,
+     * is provider-specific.
+     */
+    useForwarder?: boolean;
+    /**
+     * Optional destination dApp deposit action for a fast cross-chain transfer.
+     *
+     * When set, the burned USDC is minted to Circle's GenericExecutor on the
+     * destination chain, which calls the registered dApp (for example, a Gateway
+     * `depositFor`) in the same relayed flow. Consumed by the CCTP v2 provider's
+     * executor-deposit path; requires `useForwarder: true`.
+     *
+     * @see {@link BridgeDepositAction}
+     */
+    deposit?: BridgeDepositAction;
+}
+/**
+ * Destination dApp deposit action for a fast cross-chain transfer.
+ *
+ * When present on a bridge destination, the CCTP v2 provider routes the
+ * transfer through Circle's GenericExecutor: the burned USDC is minted to the
+ * executor on the destination chain, which then calls the registered dApp (for
+ * example, a Gateway `depositFor`) in the same relayed flow. Encoded into
+ * executor hookData via `buildDepositForGenericExecutorPayload`.
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeDepositAction } from '@core/provider'
+ *
+ * const deposit: BridgeDepositAction = {
+ *   dappId: 'gateway_deposit',
+ *   params: ['0xTokenMessengerWithFees', '0xDepositAccount', 0n],
+ * }
+ * ```
+ */
+interface BridgeDepositAction {
+    /**
+     * Registered dApp identifier the GenericExecutor invokes on the destination
+     * chain (for example, `'gateway_deposit'`).
+     */
+    dappId: string;
+    /**
+     * Positional arguments for the dApp function, in ABI order. Dynamic amount
+     * slots are filled in by the executor from the minted amount.
+     */
+    params: readonly unknown[];
 }
 /**
  * Parameters for executing a cross-chain bridge operation.
@@ -5473,17 +5744,70 @@ interface BridgeParams$1<TFromCapabilities extends AdapterCapabilities = Adapter
  *
  * @defaultValue ChainDefinition
  */
-TChainDefinition extends ChainDefinition = ChainDefinition> {
+TChainDefinition extends ChainDefinition = ChainDefinition, 
+/**
+ * The token type the provider accepts.
+ *
+ * @defaultValue 'USDC'
+ *
+ * @remarks
+ * The default preserves the original USDC-only contract for consumers that
+ * omit the token type. Providers that accept a different token type pass
+ * `TToken` explicitly.
+ *
+ * @example
+ * ```typescript
+ * // Default — TToken resolves to 'USDC'
+ * type DefaultParams = BridgeParams // params.token is typed as 'USDC'
+ *
+ * // Provider that identifies tokens by a hex string template literal
+ * type HexTokenParams = BridgeParams<
+ *   AdapterCapabilities,
+ *   AdapterCapabilities,
+ *   ChainDefinition,
+ *   `0x${string}`
+ * > // params.token is typed as `0x${string}`
+ * ```
+ */
+TToken extends string = 'USDC'> {
     /** The source adapter containing wallet and chain information */
     source: WalletContext<TFromCapabilities, TChainDefinition>;
     /** The destination adapter containing wallet and chain information */
     destination: DestinationWalletContext<TToCapabilities, TChainDefinition>;
     /** The amount to transfer (as a string to avoid precision issues) */
     amount: string;
-    /** The token to transfer (currently only USDC is supported) */
-    token: 'USDC';
+    /** The token to transfer (provider-defined; defaults to `'USDC'`) */
+    token: TToken;
     /** Bridge configuration (e.g., fast burn settings) */
     config: BridgeConfig;
+    /**
+     * Optional server-signed quote to reuse, typically the
+     * {@link EstimateResult.quote} returned by an earlier `estimate` call.
+     *
+     * When present and still valid, a provider with a server-signed quote
+     * model may reuse it instead of fetching a fresh quote, so the fee the
+     * caller was quoted is the fee they pay. Providers decide when a reused
+     * quote is still valid (e.g. freshness, fee token, speed); an unusable or
+     * mismatched quote is ignored and a fresh one is fetched. Transfer
+     * parameters are validated by the provider's on-chain contract, so a quote
+     * reused for a different transfer is rejected there rather than silently.
+     * Providers without a quote model ignore this field entirely, and do so
+     * silently — nothing verifies that a quote reached the provider that issued
+     * it, because the route is matched to a provider only after these
+     * parameters are validated. A quote is meaningful only on the route that
+     * produced it.
+     *
+     * Typed `unknown`: a caller reaches `bridge` through a provider-agnostic
+     * surface, so this shared type names no provider's shape. It is public
+     * input in any case, and is validated before any field is read — by the
+     * provider that serves the route, or by the kit for routes it prices
+     * itself. Treat it as opaque and pass it back unmodified.
+     *
+     * This is a `bridge` input. A quote is an output of `estimate`, not an
+     * input to it — `estimate` always returns a freshly-priced quote, and a
+     * provider may reject a quote passed to `estimate` rather than ignore it.
+     */
+    quote?: unknown;
     /**
      * Optional invocation metadata for tracing and correlation.
      *
@@ -5622,6 +5946,43 @@ interface BridgeStep {
      */
     errorCategory?: BridgeStepErrorCategory;
 }
+/**
+ * A non-fatal advisory surfaced on a {@link BridgeResult} or an
+ * {@link EstimateResult}.
+ *
+ * Warnings report things the caller should know about that did not fail the
+ * operation — for example a requested FAST transfer that was degraded to SLOW.
+ * They are additive and optional: providers populate them when relevant and
+ * leave `warnings` undefined otherwise, so consumers that ignore the field are
+ * unaffected.
+ *
+ * The codes are shared across both results, so a check written against one
+ * works against the other. A code is raised only where its condition can
+ * arise, so an estimate reaches a subset of what a bridge does.
+ *
+ * @example
+ * ```typescript
+ * const downgrade = result.warnings?.find(w => w.code === 'SPEED_DOWNGRADED')
+ * if (downgrade) {
+ *   // Inform the user that the requested FAST speed was not available.
+ *   showToast(`Transfer speed changed to ${String(downgrade.data?.['actual'])}`)
+ * }
+ * ```
+ */
+interface BridgeWarning {
+    /**
+     * Stable machine-readable warning code (e.g. `'SPEED_DOWNGRADED'`). Prefer
+     * branching on this over `message`.
+     */
+    code: string;
+    /** Optional human-readable explanation for logging or display. */
+    message?: string;
+    /**
+     * Optional structured context for the warning (e.g.
+     * `{ requested: 'FAST', actual: 'SLOW' }`).
+     */
+    data?: Record<string, unknown>;
+}
 /**
  * Result object returned after a successful cross-chain bridge operation.
  *
@@ -5636,11 +5997,24 @@ interface BridgeStep {
  * console.log(`Steps executed: ${result.steps.length}`)
  * ```
  */
-interface BridgeResult {
+interface BridgeResult<TToken extends string = 'USDC'> {
     /** The amount that was transferred (as a string to avoid precision issues) */
     amount: string;
-    /** The token that was transferred (currently only USDC is supported) */
-    token: 'USDC';
+    /**
+     * The token that was transferred.
+     *
+     * @remarks
+     * `TToken` defaults to `'USDC'` to preserve source compatibility for
+     * consumers that use the result type without an explicit generic. Kits that
+     * route across providers use `BridgeResult<string>` internally.
+     *
+     * Provider implementations narrow this in their own subclass code
+     * by passing a literal as the `TToken` generic — for example a
+     * USDC-only provider declares `BridgeResult<'USDC'>`, and a
+     * provider whose tokens are bytes32 identifiers declares the result
+     * with a `0x`-prefixed template-literal string type.
+     */
+    token: TToken;
     /** The state of the transfer */
     state: 'pending' | 'success' | 'error';
     /** The bridge configuration that was used for this operation */
@@ -5678,6 +6052,12 @@ interface BridgeResult {
     };
     /** Array of steps that were executed during the bridge process */
     steps: BridgeStep[];
+    /**
+     * Non-fatal advisories surfaced during the bridge (e.g. a FAST→SLOW speed
+     * downgrade). Optional and additive — providers populate it when relevant
+     * and leave it undefined otherwise. See {@link BridgeWarning}.
+     */
+    warnings?: BridgeWarning[];
 }
 /**
  * Configuration options for customizing bridge behavior.
@@ -5779,6 +6159,14 @@ interface BridgeConfig {
      * ```
      */
     customFee?: CustomFee | undefined;
+    /**
+     * Which leg pays the protocol fee.
+     *
+     * `'source'` leaves the delivered amount unreduced; `'destination'` takes the
+     * fee from it. Omit it to let the routed provider decide — a provider rejects
+     * a value it cannot honour.
+     */
+    feePayment?: 'source' | 'destination' | undefined;
 }
 /**
  * Custom fee configuration charged by the integrator.
@@ -5975,25 +6363,95 @@ interface ForwarderDestination<TChainIdentifier extends ChainIdentifier$1 = Chai
  */
 type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> = ((AdapterContext<TAdapterCapabilities, TChainIdentifier> | BridgeDestinationWithAddress<TAdapterCapabilities, TChainIdentifier>) & {
     /**
-     * Enable Circle's Forwarder to handle the mint transaction.
+     * Enable Circle's relayer to submit the destination transaction.
      *
-     * When true, Circle's Orbit relayer will fetch the attestation and submit
-     * the mint transaction on the user's behalf. The relay fee is deducted from
-     * the minted USDC at mint time.
+     * Where the relay fee is charged depends on the route and on
+     * {@link BridgeConfig.feePayment}: it may be taken from the amount that
+     * arrives, or priced into a quote the source transaction pays.
      *
-     * @defaultValue false
+     * Whether the option is required, optional, or refused depends on the
+     * routed provider and the rest of the config.
      */
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
 /**
- * Configure how CCTP and forwarding fees are collected for a bridge.
+ * Display symbols the provider recognizes as a convenience for callers.
+ *
+ * A consumer may pass one of these symbols instead of a raw bytes32 token
+ * id; the provider resolves it to the symbol's canonical bytes32 id via
+ * {@link KNOWN_TOKEN_IDS_BY_NETWORK} (a symbol can map to more than one
+ * bridge, so the map pins the canonical one). This list does NOT gate
+ * routability: any token the IRIS registry lists with deployments on both
+ * endpoints routes when passed by its bytes32 id, whether listed here or
+ * not.
+ *
+ * @example
+ * ```typescript
+ * for (const symbol of KNOWN_TOKEN_SYMBOLS) console.log(symbol)
+ * ```
+ */
+declare const KNOWN_TOKEN_SYMBOLS: readonly ["cirBTC", "wETH", "EURC"];
+/**
+ * A known token symbol. Derived from {@link KNOWN_TOKEN_SYMBOLS} so the
+ * type and the runtime set never drift.
+ *
+ * @example
+ * ```typescript
+ * const sym: KnownTokenSymbol = 'cirBTC'
+ * ```
+ */
+type KnownTokenSymbol = (typeof KNOWN_TOKEN_SYMBOLS)[number];
+
+/**
+ * CCTPx token identifier: a bytes32 hex string. Within one CrossChainTokenService
+ * deployment it names the same registered token on every chain that deployment
+ * spans, which is what makes a cross-chain transfer addressable by id alone. Passed verbatim to the
+ * `CrossChainTokenService.crossChainTransfer` contract call and used as the
+ * `tokenId` path segment on the IRIS fee-quote endpoint.
+ */
+type CCTPXTokenId = `0x${string}`;
+/**
+ * A token value accepted by {@link CCTPXTokenId}-keyed route checks.
+ *
+ * The provider's `supportsRoute` accepts either a {@link KnownTokenSymbol},
+ * which it resolves to a bytes32 id via the per-network map, or a
+ * {@link CCTPXTokenId} passed directly. This union is the honest type of what
+ * the route check accepts, so callers and JSDoc examples never need an `as`
+ * cast to pass a symbol.
+ *
+ * @example
+ * ```typescript
+ * const bySymbol: CCTPXRouteToken = 'cirBTC'
+ * const byId: CCTPXRouteToken =
+ *   '0x0000000000000000000000000000000000000000000000000000000063697254'
+ * ```
+ */
+type CCTPXRouteToken = CCTPXTokenId | KnownTokenSymbol;
+
+/**
+ * Token string accepted by `bridge` / `estimate`.
+ *
+ * Use `'USDC'` for CCTP v2, a known CCTPx symbol (`'cirBTC'`, `'wETH'`,
+ * `'EURC'`), or a 32-byte hex CCTPx token id.
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeToken } from '@circle-fin/bridge-kit'
+ *
+ * const usdc: BridgeToken = 'USDC'
+ * const eurc: BridgeToken = 'EURC'
+ * const tokenId: BridgeToken =
+ *   '0x0000000000000000000000000000000000000000000000000000000063697254'
+ * ```
+ */
+type BridgeToken = 'USDC' | CCTPXRouteToken;
+/**
+ * Configuration accepted by `bridge` and `estimate`.
  *
  * @remarks
- * Use `'source'` with `to.useForwarder: true` to treat `amount` as the exact
- * destination amount. Bridge Kit obtains a signed fee quote, collects the fee
- * in source-chain USDC, and leaves the destination mint unreduced. Omit the
- * option (or use `'destination'`) to preserve the existing max-fee behavior.
+ * The kit's name for {@link BridgeConfig}, kept as the parameter type so a
+ * kit-only option can be added here without touching the provider-facing config.
  *
  * @example
  * ```typescript
@@ -6006,10 +6464,7 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
  * ```
  * @since 1.14.0
  */
-interface BridgeExecutionConfig extends BridgeConfig {
-    /** Select source-side signed fees or the legacy destination-side fee path. */
-    feePayment?: 'source' | 'destination';
-}
+type BridgeExecutionConfig = BridgeConfig;
 type FeeFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
 type FeeRecipientFunction<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities> = (feePayoutChain: ChainDefinition, params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>) => Promise<string> | string;
 /**
@@ -6027,6 +6482,13 @@ type FeeRecipientFunction<TFromAdapterCapabilities extends AdapterCapabilities,
  * Use `computeFee` (recommended) for human-readable amounts, or `calculateFee` (deprecated)
  * for smallest-unit amounts. Only one should be provided.
  *
+ * **USDC only.** Because the fee is collected on top of the transfer amount and
+ * split through CCTPv2's USDC flow, this policy cannot apply to any other token.
+ * Bridging a non-USDC token (for example CCTPx `cirBTC` or `wETH`)
+ * is rejected with `INPUT_VALIDATION_FAILED` before anything is submitted —
+ * on `bridge` and `estimate` alike — rather than proceeding without the fee.
+ * A per-call `config.customFee` is rejected the same way.
+ *
  * @example
  * ```typescript
  * import type { CustomFeePolicy, BridgeParams } from '@circle-fin/bridge-kit'
@@ -6104,7 +6566,8 @@ type CustomFeePolicy$2 = {
  * - The `from` field specifies the source adapter context (wallet and chain).
  * - The `to` field specifies the destination, supporting both explicit and derived recipient addresses.
  * - The `config` field allows customization of bridge behavior (e.g., transfer speed).
- * - The `token` field is optional and defaults to 'USDC'; other tokens are not currently supported.
+ * - The `token` field is optional and defaults to `'USDC'`. It accepts
+ *   `'USDC'`, a known CCTPx symbol, or a bytes32 CCTPx token id.
  *
  * @typeParam TFromAdapterCapabilities - The source adapter capabilities type.
  * @typeParam TToAdapterCapabilities - The destination adapter capabilities type.
@@ -6172,10 +6635,29 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      */
     config?: BridgeExecutionConfig;
     /**
-     * The token to transfer. Defaults to 'USDC'.
-     * If omitted, the provider will use 'USDC' by default.
+     * The token to transfer. Defaults to `'USDC'`.
+     *
+     * A known symbol is a convenience for a canonical CCTPx registration. A
+     * symbol that maps to more than one bridge resolves to the registration
+     * pinned by the provider. Pass the bridge's bytes32 token id directly when
+     * an exact registration is required.
+     *
+     * If omitted, defaults to `'USDC'`.
+     *
+     * @example
+     * ```typescript
+     * // USDC via CCTPv2 (default)
+     * const usdc: BridgeParams['token'] = 'USDC'
+     *
+     * // CCTPx by bare symbol — resolves via the known-symbol map
+     * const bare: BridgeParams['token'] = 'wETH'
+     *
+     * // CCTPx by bytes32 token id
+     * const explicit: BridgeParams['token'] =
+     *   '0x0000000000000000000000000000000000000000000000000000000063697254'
+     * ```
      */
-    token?: 'USDC';
+    token?: BridgeToken;
     /**
      * Optional invocation metadata for tracing and correlation.
      *
@@ -6198,15 +6680,68 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      */
     invocationMeta?: InvocationMeta;
     /**
-     * Reuse the opaque signed quote returned by a receive-exact estimate.
+     * Optional server-signed quote to reuse — pass the `quote` returned by an
+     * earlier {@link BridgeKit.estimate | estimate} call straight back so the
+     * fee you were quoted is the fee you pay.
+     *
+     * Treat the value as opaque, and never log or decode it. It belongs to
+     * whichever provider issued it and carries that provider's own shape,
+     * which is why it is typed `unknown` here: a route is matched to a
+     * provider after these parameters are validated, so the kit cannot know
+     * whose quote this is. The provider that serves the route validates it
+     * before reading any field.
+     *
+     * An unusable quote is not handled the same way everywhere, so take the
+     * value from an estimate result rather than constructing one:
+     * - A provider with a reusable quote model (e.g. CCTPx) reuses it while it
+     *   is fresh and matches the requested fee token and speed; otherwise it
+     *   transparently fetches a fresh quote and flags a `QUOTE_NOT_REUSED`
+     *   result warning, so a stale quote is never worse than passing none.
+     * - Receive-exact bridging (`config.feePayment: 'source'`) instead
+     *   **rejects** a quote that is invalid, mismatched, expired, or too close
+     *   to expiry, rather than repricing behind your back.
+     * - Providers with no quote model (e.g. USDC via CCTP v2) ignore it —
+     *   **silently**. Route selection happens after these parameters are
+     *   validated, so the kit cannot tell whose quote this is, and nothing
+     *   checks that it reached the provider that issued it. In practice this
+     *   bites when the token changes between `estimate` and `bridge`: a quote
+     *   from a CCTPx token (`cirBTC`, `wETH`) passed to a plain USDC bridge is
+     *   dropped without an error or a warning, and the fee comes from CCTP v2
+     *   instead. Keeping the same token routes back to the same provider, so
+     *   the quote arrives. Re-estimate whenever the transfer changes.
+     *
+     * The transfer parameters (amount, recipient, chains) are validated
+     * on-chain, so a quote reused for a different transfer is rejected by the
+     * contract rather than silently — reuse a quote only for the transfer it
+     * was estimated for.
+     *
+     * This field is for {@link BridgeKit.bridge | bridge} only. A quote is
+     * produced by `estimate` and consumed by `bridge`, and `estimate` always
+     * returns a freshly-priced one. Passing a quote back into `estimate` is a
+     * usage error: CCTPx rejects it outright, while receive-exact ignores it and
+     * prices afresh, so the quote you get back is never the one you sent. Take
+     * the quote from the estimate result, not from your input.
      *
-     * @remarks
-     * Bridge Kit validates a supplied quote against the exact transfer and fails
-     * when it is invalid, mismatched, expired, or too close to expiry. Omit this
-     * value to let Bridge Kit fetch a fresh quote automatically. Never log or
-     * decode it.
+     * @example
+     * ```typescript
+     * const estimate = await kit.estimate({
+     *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+     *   to: { adapter: destAdapter, chain: 'Base' },
+     *   amount: '100',
+     *   token: 'wETH',
+     * })
+     *
+     * // Reuse the quoted fee for the bridge.
+     * const result = await kit.bridge({
+     *   from: { adapter: sourceAdapter, chain: 'Ethereum' },
+     *   to: { adapter: destAdapter, chain: 'Base' },
+     *   amount: '100',
+     *   token: 'wETH',
+     *   quote: estimate.quote,
+     * })
+     * ```
      */
-    quote?: string;
+    quote?: unknown;
 }
 
 /**
@@ -7698,6 +8233,18 @@ interface AppKitContext {
         chain: ChainDefinition;
         params: OperationParamsMap[T];
     }): Promise<string>;
+    /**
+     * Optional client-side configuration forwarded to the underlying
+     * {@link createOnrampKit} factory when `kit.onramp` is accessed.
+     *
+     * @remarks
+     * The onramp namespace on the client carries NO secret — the
+     * long-lived `apiKey` lives exclusively on the server entry
+     * (`@circle-fin/app-kit/server`). These options exist purely so
+     * staging / SSR consumers can override the widget origin or
+     * inject a host `Window`.
+     */
+    onramp?: AppKitOnrampClientConfig | undefined;
     /**
      * Operation-scoped custom fee policies.
      *
@@ -7769,6 +8316,35 @@ interface AppKitContext {
      */
     headers?: Record<string, string>;
 }
+/**
+ * Client-side onramp configuration carried on {@link AppKitContext.onramp}.
+ *
+ * @remarks
+ * No secret material lives here — the server-only `apiKey` is
+ * configured on the matching `@circle-fin/app-kit/server` entry. Both
+ * fields are optional with safe production defaults; the typical
+ * application leaves them unset and instantiates `new AppKit()`.
+ */
+interface AppKitOnrampClientConfig {
+    /**
+     * Override the hosted widget origin. Defaults to the onramp-kit
+     * production origin.
+     *
+     * @remarks
+     * Override for staging environments only — production traffic
+     * should always use the default.
+     */
+    readonly widgetBaseUrl?: string | undefined;
+    /**
+     * Inject a host `Window` for testing or SSR-friendly bundles.
+     *
+     * @remarks
+     * Production code leaves this unset and relies on the global
+     * `window`. Exposed (not `@internal`) so SSR frameworks can
+     * hand-feed the host window after hydration.
+     */
+    readonly window?: Window | undefined;
+}
 
 /**
  * Execute a cross-chain bridge operation using the AppKit context.
@@ -7806,6 +8382,9 @@ interface AppKitContext {
  * console.log(`Bridged ${result.amount} ${result.token} (${result.state})`)
  * ```
  */
-declare const bridge: (context: AppKitContext, params: BridgeParams) => Promise<BridgeResult>;
+declare function bridge(context: AppKitContext, params: Omit<BridgeParams, 'token'> & {
+    token?: 'USDC';
+}): Promise<BridgeResult>;
+declare function bridge(context: AppKitContext, params: BridgeParams): Promise<BridgeResult<string>>;
 
 export { bridge };