@circle-fin/app-kit 1.14.0 → 1.15.1

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.
  *
@@ -691,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",
@@ -807,6 +860,7 @@ declare enum Blockchain {
  */
 declare enum BridgeChain {
     Arbitrum = "Arbitrum",
+    Arc = "Arc",
     Avalanche = "Avalanche",
     Base = "Base",
     Codex = "Codex",
@@ -907,6 +961,7 @@ type BridgeChainIdentifier = ChainDefinition | BridgeChain | `${BridgeChain}`;
  * @see {@link UnifiedBalanceChainIdentifier} for the type that accepts these values.
  */
 declare enum UnifiedBalanceChain {
+    Arc = "Arc",
     Arbitrum = "Arbitrum",
     Avalanche = "Avalanche",
     Base = "Base",
@@ -2131,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.
  *
@@ -3226,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.). */