@circle-fin/app-kit 1.12.1 → 1.14.0

package/estimateBridge.d.cts

@@ -559,6 +559,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.
@@ -718,6 +731,8 @@ declare enum Blockchain {
     Optimism_Sepolia = "Optimism_Sepolia",
     Pharos = "Pharos",
     Pharos_Testnet = "Pharos_Testnet",
+    Plasma = "Plasma",
+    Plasma_Testnet = "Plasma_Testnet",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
     Plume = "Plume",
@@ -946,6 +961,7 @@ declare enum BridgeChain {
     Morph = "Morph",
     Optimism = "Optimism",
     Pharos = "Pharos",
+    Plasma = "Plasma",
     Plume = "Plume",
     Polygon = "Polygon",
     Sei = "Sei",
@@ -971,6 +987,7 @@ declare enum BridgeChain {
     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",
@@ -2652,7 +2669,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2796,7 +2813,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -5459,6 +5476,48 @@ TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContex
      * Must be a valid address format for the specified blockchain.
      */
     recipientAddress?: string;
+    /**
+     * 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.
@@ -5859,6 +5918,145 @@ type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = Adapte
     useForwarder?: boolean;
 }) | ForwarderDestination<TChainIdentifier>;
 
+/**
+ * The expiry window of a signed quote.
+ *
+ * A signed quote is short-lived; refresh it immediately before submitting
+ * on-chain rather than caching it.
+ *
+ * The API uses different field names depending on `mode`:
+ * - `TIMESTAMP` → `expiresAt` (unix seconds)
+ * - `BLOCK_NUMBER` → `expiresAtBlock` (source-chain block number)
+ *
+ * @internal
+ */
+type FeeQuoteExpiry = {
+    /** Identify an exact Unix timestamp expiry. */
+    readonly mode: 'TIMESTAMP';
+    /** Unix timestamp in seconds at which the quote expires. */
+    readonly expiresAt: number;
+} | {
+    /** Identify a source-chain block-number expiry. */
+    readonly mode: 'BLOCK_NUMBER';
+    /** Authoritative source-chain block at which the quote expires. */
+    readonly expiresAtBlock: number;
+    /** Optional advisory Unix timestamp estimate for the expiry block. */
+    readonly blockEstimatedAt?: number;
+};
+
+/**
+ * Configure how CCTP and forwarding fees are collected for a bridge.
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * import type { BridgeExecutionConfig } from '@circle-fin/bridge-kit'
+ *
+ * const config: BridgeExecutionConfig = {
+ *   transferSpeed: 'FAST',
+ *   feePayment: 'source',
+ * }
+ * ```
+ * @since 1.14.0
+ */
+interface BridgeExecutionConfig extends BridgeConfig {
+    /** Select source-side signed fees or the legacy destination-side fee path. */
+    feePayment?: 'source' | 'destination';
+}
+/**
+ * Describe one signed Fee Service line item in human-readable USDC.
+ *
+ * @example
+ * ```typescript
+ * import type { ReceiveExactFeeItem } from '@circle-fin/bridge-kit'
+ *
+ * const item: ReceiveExactFeeItem = {
+ *   type: 'FORWARD',
+ *   amount: '0.25',
+ *   args: [],
+ *   argsHash: `0x${'00'.repeat(32)}`,
+ * }
+ * ```
+ * @since 1.14.0
+ */
+interface ReceiveExactFeeItem {
+    /** The Fee Service item type, such as `FORWARD` or `PRE_FINALITY`. */
+    readonly type: string;
+    /** The fee amount in human-readable USDC. */
+    readonly amount: string;
+    /** The ABI arguments covered by the signed quote. */
+    readonly args: readonly string[];
+    /** The hash of the ABI arguments covered by the signed quote. */
+    readonly argsHash: string;
+}
+/**
+ * Return a receive-exact bridge estimate backed by a short-lived signed quote.
+ *
+ * @remarks
+ * Treat `quote` as opaque and sensitive. Pass it back to
+ * {@link BridgeKit.bridge}; do not log or decode it. Bridge Kit validates a
+ * supplied quote against the exact transfer parameters and rejects it when it
+ * is invalid, mismatched, expired, or too close to expiry.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeKit, type BridgeParams } from '@circle-fin/bridge-kit'
+ *
+ * declare const adapter: BridgeParams['from']['adapter']
+ * const kit = new BridgeKit()
+ *
+ * const estimate = await kit.estimate({
+ *   from: { adapter, chain: 'Ethereum' },
+ *   to: {
+ *     chain: 'Base',
+ *     recipientAddress: '0x1234567890123456789012345678901234567890',
+ *     useForwarder: true,
+ *   },
+ *   amount: '100',
+ *   config: { feePayment: 'source' },
+ * })
+ * console.log(estimate.amountReceived, estimate.totalDebit)
+ * ```
+ * @since 1.14.0
+ */
+interface ReceiveExactEstimateResult extends EstimateResult {
+    /** The exact amount the destination recipient receives, in USDC. */
+    readonly amountReceived: string;
+    /** The total signed fee collected on the source chain, in USDC. */
+    readonly feeTotal: string;
+    /** The itemized signed fee quote, with amounts in human-readable USDC. */
+    readonly feeItems: readonly ReceiveExactFeeItem[];
+    /** The total source-wallet debit (`amountReceived + feeTotal`), in USDC. */
+    readonly totalDebit: string;
+    /** The authoritative expiry returned by the Fee Service. */
+    readonly quoteExpiry: FeeQuoteExpiry;
+    /** Opaque signed quote bytes to pass to {@link BridgeKit.bridge}. */
+    readonly quote: string;
+}
+/**
+ * Result returned by {@link BridgeKit.estimate} for legacy and source-fee modes.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   BridgeKit,
+ *   type BridgeEstimateResult,
+ *   type BridgeParams,
+ * } from '@circle-fin/bridge-kit'
+ *
+ * declare const params: BridgeParams
+ * const kit = new BridgeKit()
+ * const result: BridgeEstimateResult = await kit.estimate(params)
+ * if ('amountReceived' in result) console.log(result.totalDebit)
+ * ```
+ * @since 1.14.0
+ */
+type BridgeEstimateResult = EstimateResult | ReceiveExactEstimateResult;
 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;
 /**
@@ -6019,7 +6217,7 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      * Optional bridge configuration (e.g., transfer speed).
      * If omitted, defaults will be used
      */
-    config?: BridgeConfig;
+    config?: BridgeExecutionConfig;
     /**
      * The token to transfer. Defaults to 'USDC'.
      * If omitted, the provider will use 'USDC' by default.
@@ -6046,6 +6244,16 @@ interface BridgeParams<TFromAdapterCapabilities extends AdapterCapabilities = Ad
      * ```
      */
     invocationMeta?: InvocationMeta;
+    /**
+     * Reuse the opaque signed quote returned by a receive-exact estimate.
+     *
+     * @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.
+     */
+    quote?: string;
 }
 
 /**
@@ -6161,12 +6369,21 @@ interface ServiceSwapConfig {
         recipientAddress?: string;
     };
     /**
-     * Stablecoin Service Kit Key used to authenticate service-backed swap
-     * requests.
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
      *
      * Treat this value as a credential. Do not log it, embed it in client-side
      * source, or expose it in telemetry.
      */
+    apiKey?: string | undefined;
+    /**
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * @deprecated Use {@link ServiceSwapConfig.apiKey} instead. Still honored
+     * when `apiKey` is omitted, and `apiKey` takes precedence when both are set.
+     */
     kitKey?: string;
     /**
      * DEX aggregator identifier used to source the swap route.
@@ -6644,12 +6861,21 @@ interface SwapConfig {
         recipientAddress: string;
     };
     /**
-     * Stablecoin Service Kit Key used to authenticate service-backed swap
-     * requests.
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
      *
      * Treat this value as a credential. Do not log it, embed it in client-side
      * source, or expose it in telemetry.
      */
+    apiKey?: string | undefined;
+    /**
+     * Circle API key used to authenticate service-backed swap requests.
+     *
+     * @deprecated Use {@link SwapConfig.apiKey} instead. Still honored when
+     * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
+     */
     kitKey?: string;
 }
 /**
@@ -6778,29 +7004,37 @@ type EarnAdapterContext<TAdapterCapabilities extends AdapterCapabilities = Adapt
  * Configuration options for earn operations.
  *
  * EarnKit supports dual-mode authentication: operations work both with
- * and without a Kit Key. When present, the Kit Key enables permissioned
+ * and without an API key. When present, the API key enables permissioned
  * features like integrator attribution tracking.
  *
  * @example
  * ```typescript
- * // Permissionless (no Kit Key)
+ * // Permissionless (no API key)
  * const config: EarnConfig = {}
  *
- * // Permissioned (with Kit Key)
+ * // Permissioned (with API key)
  * const config: EarnConfig = {
- *   kitKey: 'KIT_KEY:keyId:keySecret',
+ *   apiKey: 'TEST_API_KEY:keyId:keySecret',
  * }
  * ```
  */
 interface EarnConfig {
     /**
-     * Optional Kit Key for permissioned access.
+     * Optional Circle API key for permissioned access.
      *
      * When provided, enables integrator attribution tracking and
      * higher rate limits. When omitted, the SDK operates in
      * permissionless mode.
      *
-     * Format: `KIT_KEY:<keyId>:<keySecret>`
+     * Format: `<ENV>_API_KEY:<keyId>:<keySecret>`. A legacy
+     * `KIT_KEY:<keyId>:<keySecret>` value is also accepted.
+     */
+    readonly apiKey?: string | undefined;
+    /**
+     * Optional Circle API key for permissioned access.
+     *
+     * @deprecated Use {@link EarnConfig.apiKey} instead. Still honored when
+     * `apiKey` is omitted, and `apiKey` takes precedence when both are set.
      */
     readonly kitKey?: string | undefined;
     /**
@@ -7567,13 +7801,18 @@ interface AppKitContext {
      */
     disableErrorReporting?: boolean;
     /**
-     * Custom HTTP headers forwarded with the underlying CCTP provider's
-     * attestation (Iris) API requests made by bridge operations.
+     * Custom HTTP headers forwarded with Circle API requests made by the
+     * underlying kits: the CCTP provider's attestation (Iris) requests for
+     * bridge operations, and the Gateway API requests for unified-balance
+     * operations.
      *
      * @remarks
      * Headers are merged on top of the SDK defaults (such as `Content-Type`)
-     * rather than replacing them. The header is forwarded as-is to Circle's API;
-     * the SDK does not interpret it.
+     * rather than replacing them. Each header is forwarded as-is to Circle's API;
+     * the SDK does not interpret it. The same map is forwarded to every relevant
+     * kit, so a header a given API ignores is simply a no-op there. A
+     * `unifiedBalance.headers` value, if provided, takes precedence for the
+     * unified-balance kit.
      */
     headers?: Record<string, string>;
 }
@@ -7617,6 +7856,6 @@ interface AppKitContext {
  * console.log('Estimated gas fees:', estimate.gasFees)
  * ```
  */
-declare const estimateBridge: (context: AppKitContext, params: BridgeParams) => Promise<EstimateResult>;
+declare const estimateBridge: (context: AppKitContext, params: BridgeParams) => Promise<BridgeEstimateResult>;
 
 export { estimateBridge };