@circle-fin/app-kit 1.12.0 → 1.13.0

package/estimateBridge.d.mts

@@ -718,6 +718,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 +948,7 @@ declare enum BridgeChain {
     Morph = "Morph",
     Optimism = "Optimism",
     Pharos = "Pharos",
+    Plasma = "Plasma",
     Plume = "Plume",
     Polygon = "Polygon",
     Sei = "Sei",
@@ -971,6 +974,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 +2656,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2796,7 +2800,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -2957,6 +2961,18 @@ interface TokenActionMap {
          */
         walletAddress?: string | undefined;
     };
+    /**
+     * Get the on-chain name of the token contract.
+     *
+     * This is a read-only operation. For USDC the value is also the EIP-712
+     * domain name, which permit and authorize signing flows need.
+     */
+    name: ActionParameters & {
+        /**
+         * The contract address of the token.
+         */
+        tokenAddress: string;
+    };
 }
 
 /**
@@ -3786,6 +3802,30 @@ declare class ActionRegistry {
     executeAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, context: ResolvedOperationContext): Promise<PreparedChainRequest>;
 }
 
+/**
+ * Canonical list of actions that do not prepare or submit transactions.
+ *
+ * @internal
+ */
+declare const READ_ACTION_KEYS: readonly ["token.allowance", "token.balanceOf", "token.name", "native.balanceOf", "usdc.allowance", "usdc.balanceOf", "usdc.name", "gateway.v1.isDelegate", "gateway.v1.withdrawingBalance", "gateway.v1.withdrawalBlock", "gateway.v1.signBurnIntents"];
+/**
+ * Action keys that execute without preparing or submitting a transaction.
+ *
+ * @remarks
+ * Derive this type from the canonical runtime list so compile-time and runtime
+ * classification cannot drift. `gateway.v1.signBurnIntents` is included
+ * because the action system models off-chain signing as a read action: it does
+ * not prepare a chain request.
+ *
+ * @example
+ * ```typescript
+ * import type { ReadActionKey } from '@core/adapter'
+ *
+ * const action: ReadActionKey = 'token.allowance'
+ * ```
+ */
+type ReadActionKey = (typeof READ_ACTION_KEYS)[number];
+
 /**
  * Defines the capabilities of an adapter, including address handling patterns and supported chains.
  *
@@ -3954,6 +3994,69 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
      * ```
      */
     prepareAction<TActionKey extends ActionKeys>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<PreparedChainRequest>;
+    /**
+     * Execute a non-transaction action without routing through transaction preparation.
+     *
+     * @remarks
+     * Use this seam for balance, allowance, contract-state, and other actions
+     * classified as reads. It never calls {@link Adapter.prepareAction}, so
+     * transaction authorization wrappers only observe actions that can produce a
+     * signable chain request.
+     *
+     * @typeParam TActionKey - The read action key.
+     * @param action - The read action to execute.
+     * @param params - The parameters for the read action.
+     * @param ctx - The operation context.
+     * @returns The raw action response.
+     * @throws {KitError} When the key is not a read action or no handler is registered.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import { Ethereum } from '@core/chains'
+     *
+     * const balance = await adapter.readAction(
+     *   'token.balanceOf',
+     *   { tokenAddress, walletAddress },
+     *   { chain: Ethereum },
+     * )
+     * ```
+     *
+     * @internal
+     */
+    readAction<TActionKey extends ReadActionKey>(action: TActionKey, params: ActionPayload<TActionKey>, ctx: OperationContext<TAdapterCapabilities>): Promise<unknown>;
+    /**
+     * Read the current token allowance a delegate holds over an owner's tokens.
+     *
+     * @remarks
+     * Perform a network read through {@link Adapter.readAction}. This method
+     * never routes through {@link Adapter.prepareAction}. On chains without an
+     * allowance model, such as Solana, return the maximum uint256 value.
+     *
+     * @param params - The token to query and the delegate whose allowance is being read.
+     * @param ctx - Operation context with compile-time validated address requirements.
+     * @returns A promise resolving to the current allowance in the token's base units.
+     * @throws {KitError} When the adapter does not register a `token.allowance` handler.
+     * @throws Error When the operation context or action handler fails.
+     *
+     * @example
+     * ```typescript
+     * import type { Adapter } from '@core/adapter'
+     * import { Ethereum } from '@core/chains'
+     *
+     * declare const adapter: Adapter
+     *
+     * const allowance = await adapter.getTokenAllowance(
+     *   {
+     *     tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+     *     delegate: '0x1111111111111111111111111111111111111111',
+     *   },
+     *   { chain: Ethereum },
+     * )
+     * console.log(allowance) // 1000000n
+     * ```
+     */
+    getTokenAllowance(params: ActionPayload<'token.allowance'>, ctx: OperationContext<TAdapterCapabilities>): Promise<bigint>;
     /**
      * Prepares a transaction for future gas estimation and execution.
      *
@@ -5760,6 +5863,139 @@ 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.
+ */
+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;
 /**
@@ -5920,7 +6156,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.
@@ -5947,6 +6183,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;
 }
 
 /**
@@ -6062,12 +6308,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.
@@ -6545,12 +6800,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;
 }
 /**
@@ -6679,29 +6943,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;
     /**
@@ -7468,13 +7740,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>;
 }
@@ -7518,6 +7795,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 };