@circle-fin/app-kit 1.9.0 → 1.11.0

package/unifiedBalance.d.cts

@@ -373,6 +373,14 @@ interface CCTPSplitConfig {
     type: 'split';
     tokenMessenger: string;
     messageTransmitter: string;
+    /**
+     * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
+     *
+     * Optional. Present only on chains that support the prepaid FORWARD path
+     * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
+     * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
+     */
+    tokenMessengerWithFees?: string;
     confirmations: number;
 }
 /**
@@ -393,6 +401,14 @@ interface CCTPSplitConfig {
 interface CCTPMergedConfig {
     type: 'merged';
     contract: string;
+    /**
+     * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
+     *
+     * Optional. Present only on chains that support the prepaid FORWARD path
+     * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
+     * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
+     */
+    tokenMessengerWithFees?: string;
     confirmations: number;
 }
 /**
@@ -527,6 +543,21 @@ interface GatewayV1Contracts {
      * @example "0xabcdef1234567890abcdef1234567890abcdef12"
      */
     minter: string;
+    /**
+     * The address of the `DepositForHandler` contract.
+     *
+     * @description Optional. The handler the GenericExecutor calls on this chain
+     * to run a fast cross-chain deposit into the {@link GatewayV1Contracts.wallet}.
+     * Present only on chains that are fast-deposit destinations; other Gateway
+     * chains omit it.
+     *
+     * Address format varies by blockchain:
+     * - EVM chains: 40-character hexadecimal with 0x prefix (e.g., "0x1234...")
+     * - Solana: Base58-encoded 32-byte address (e.g., "9WzDX...")
+     *
+     * @example "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48"
+     */
+    depositForHandler?: string;
 }
 /**
  * Versioned map of Gateway contract configurations.
@@ -1826,6 +1857,110 @@ interface CCTPv2ActionMap {
          */
         hookData: string;
     };
+    /**
+     * Initiate a prepaid cross-chain USDC transfer through the `TokenMessengerWithFees` wrapper.
+     *
+     * Burn USDC on the source chain while collecting all fees up front against a
+     * signed quote. The wrapper collects the fee via `FeeManager`, then delegates
+     * to the unmodified `TokenMessengerV2`. When `hookData` is provided (the
+     * GenericExecutor FORWARD path) the wrapper's `depositForBurnWithHookAndFees`
+     * contract method is used; otherwise `depositForBurnWithFees` is used.
+     *
+     * @remarks
+     * SDK/contract naming: this SDK action is `depositForBurnWithFees` but, when a
+     * `hookData` is present, it dispatches to the `depositForBurnWithHookAndFees`
+     * contract method on `TokenMessengerWithFees` (NOT on `TokenMessengerV2`).
+     *
+     * Fee payment channel (must match the quote's `feeToken`):
+     * - Native fee (`feeToken` is the zero address): exactly `feeTotalAmount` is
+     *   attached as `msg.value`.
+     * - ERC-20 fee (e.g. USDC): no value is attached; the caller must first approve
+     *   the wrapper for `feeTotalAmount` (see the provider's fee approval helper).
+     *
+     * @remarks
+     * Unlike `depositForBurn`, the `TokenMessengerWithFees` contract methods do NOT
+     * take `maxFee` or `minFinalityThreshold` — fee and finality behavior are
+     * derived from the signed quote — so those fields are omitted from this action.
+     *
+     * @example
+     * ```typescript
+     * await adapter.action('cctp.v2.depositForBurnWithFees', {
+     *   amount: BigInt('1000000'),
+     *   mintRecipient: executorAddress,     // GenericExecutor (bytes32)
+     *   destinationCaller: executorAddress, // GenericExecutor (bytes32)
+     *   fromChain: ethereum,
+     *   toChain: arc,
+     *   hookData: geForwardHookData,        // cctp-forward-wrapped GenericExecutor blob
+     *   claim: { signedQuote: '0x...', refundAddress: '0x...' },
+     *   feeToken: '0x0000000000000000000000000000000000000000', // native
+     *   feeTotalAmount: 3500000n,
+     * })
+     * ```
+     */
+    depositForBurnWithFees: Omit<CCTPv2ActionMap['depositForBurn'], 'maxFee' | 'minFinalityThreshold'> & {
+        /**
+         * Optional hex-encoded hook data for the GenericExecutor FORWARD path.
+         *
+         * When present, the `depositForBurnWithHookAndFees` contract method is used
+         * and the blob must be wrapped in the `cctp-forward` envelope (the wrapper
+         * rejects a FORWARD fee quote whose hook lacks it). When omitted, the plain
+         * `depositForBurnWithFees` contract method is used.
+         */
+        hookData?: string;
+        /**
+         * Signed fee quote claim passed to the `TokenMessengerWithFees` wrapper.
+         *
+         * `signedQuote` is the `[uint8 0x01][abi.encode(Quote)]` blob returned by the
+         * Fee Quote service; `refundAddress` receives any fee overpayment refund.
+         */
+        claim: QuoteClaim;
+        /**
+         * Fee token from the signed quote.
+         *
+         * The zero address (`0x000…0`) means the fee is paid in native currency and
+         * is attached as `msg.value`. Any other address (e.g. USDC) means an ERC-20
+         * fee that must be approved to the wrapper beforehand. This is independent of
+         * `burnToken`, which is always USDC.
+         */
+        feeToken: string;
+        /**
+         * Total fee amount from the signed quote, in `feeToken` minor units.
+         *
+         * Firm only until the quote's `expiresAt`. For a native fee this is the exact
+         * `msg.value`; for an ERC-20 fee this is the amount approved to the wrapper.
+         */
+        feeTotalAmount: bigint;
+    };
+}
+/**
+ * Signed fee quote claim consumed by the `TokenMessengerWithFees` wrapper.
+ *
+ * Mirrors the on-chain `IFeeManager.QuoteClaim` struct.
+ *
+ * @example
+ * ```typescript
+ * const claim: QuoteClaim = {
+ *   signedQuote: '0x01...', // [uint8 0x01][abi.encode(Quote)]
+ *   refundAddress: '0xUserWallet...',
+ * }
+ * ```
+ */
+interface QuoteClaim {
+    /**
+     * Opaque signed quote bytes (`0x` hex) from the fee-quote service
+     * (`SignedFeeQuote.signedQuote` returned by `fetchFeeQuote`). Pass verbatim;
+     * do not decode.
+     *
+     * The quote binds the FORWARD fee item to the on-chain call via `argsHash`;
+     * passing a quote that does not match the burn args reverts `QuoteArgsMismatch`.
+     */
+    signedQuote: string;
+    /**
+     * Address that receives any refund of overpaid fees.
+     *
+     * Typically the user wallet that authorized the burn.
+     */
+    refundAddress: string;
 }
 
 /**
@@ -5942,10 +6077,13 @@ interface ResolvedSpendParams<TFromAdapterCapabilities extends AdapterCapabiliti
  */
 type SpendFeeFunction = (params: ResolvedSpendParams) => Promise<string> | string;
 /**
- * Function that resolves the fee recipient address for a given source chain.
- * Called once per source chain in a multi-chain spend.
+ * Function that resolves the fee recipient address for a spend.
+ * Called once per spend, against the resolved **destination** chain —
+ * every fee burn intent in a spend mints to that single chain
+ * regardless of which source chain(s) funded it, so only one
+ * recipient address (valid on the destination chain) is ever needed.
  */
-type SpendFeeRecipientFunction = (feePayoutChain: ChainDefinition, params: ResolvedSpendParams) => Promise<string> | string;
+type SpendFeeRecipientFunction = (destinationChain: ChainDefinition, params: ResolvedSpendParams) => Promise<string> | string;
 /**
  * Policy for computing and routing custom developer fees.
  *
@@ -5955,11 +6093,54 @@ type SpendFeeRecipientFunction = (feePayoutChain: ChainDefinition, params: Resol
  * Fields that only exist after resolution (e.g. per-source allocations)
  * may be `undefined`.  Implementations should only rely on top-level
  * fields such as `to`, `token`, and `amount`.
+ *
+ * @remarks
+ * `resolveFeeRecipientAddress` is optional when you configure
+ * {@link UnifiedBalanceKit.setFeeRecipients} instead — the declarative
+ * map takes priority over this callback when both are present. Provide
+ * exactly one of the two; a policy with neither throws at spend time.
  */
 interface CustomFeePolicy {
     computeFee: SpendFeeFunction;
-    resolveFeeRecipientAddress: SpendFeeRecipientFunction;
+    resolveFeeRecipientAddress?: SpendFeeRecipientFunction;
 }
+/**
+ * Chain type group used to key {@link FeeRecipientsConfig}.
+ *
+ * @remarks
+ * Only `'evm'` and `'solana'` are live today (the only chain types the
+ * kit's provider currently supports). This is deliberately a narrow
+ * subset of `@core/chains`' broader `ChainType` union rather than a
+ * hardcoded two-field struct, so that support for additional non-EVM
+ * chain types (e.g. Stellar, Starknet) can be added later by adding
+ * new union members here — no restructuring of `FeeRecipientsConfig`
+ * or its consumers required.
+ */
+type FeeRecipientChainType = 'evm' | 'solana';
+/**
+ * Declarative map of fee recipient addresses, keyed by chain type.
+ *
+ * @remarks
+ * Set via {@link UnifiedBalanceKit.setFeeRecipients}. At spend time the
+ * kit resolves the spend's destination chain to its
+ * {@link FeeRecipientChainType} and looks up the matching entry —
+ * exactly one recipient is used per spend (see
+ * {@link SpendFeeRecipientFunction}). Provide entries for every chain
+ * type you expect to spend to; a spend to a destination chain type
+ * with no matching entry throws before any fee collection is
+ * attempted.
+ *
+ * @example
+ * ```typescript
+ * import type { FeeRecipientsConfig } from '@circle-fin/unified-balance-kit'
+ *
+ * const feeRecipients: FeeRecipientsConfig = {
+ *   evm: '0x1234567890123456789012345678901234567890',
+ *   solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+ * }
+ * ```
+ */
+type FeeRecipientsConfig = Partial<Record<FeeRecipientChainType, string>>;
 /**
  * Fee category describing the origin of a fee line item.
  *
@@ -6796,10 +6977,13 @@ interface GetDelegateStatusParams<TAdapterCapabilities extends AdapterCapabiliti
 }
 
 /**
- * Parameters for initiating a delayed fund removal from a Gateway
+ * Parameters for initiating a delayed recovery fund removal from a Gateway
  * account.
  *
  * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
+ *
  * Fund removals have a mandatory 7-day delay before they can be
  * completed.  Only one removal may be pending per chain at a
  * time.  Initiating a second removal on the same chain adds the
@@ -6882,7 +7066,12 @@ interface InitiateRemoveFundResult {
     explorerUrl?: string;
 }
 /**
- * Parameters for completing a fund removal after the activation period.
+ * Parameters for completing a recovery fund removal after the withdrawal
+ * delay.
+ *
+ * @remarks
+ * Use fund removal only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * @typeParam TAdapterCapabilities - Adapter capability constraints.
  * @typeParam TChainIdentifier - Accepted chain identifier type.
@@ -6979,6 +7168,11 @@ interface GetSupportedChainsOptions {
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -7180,7 +7374,12 @@ declare class AppKitUnifiedBalance {
      */
     removeDelegate(params: UpdateDelegateParams): Promise<UpdateDelegateResult>;
     /**
-     * Kick off a delayed fund removal from an account.
+     * Initiate a trustless recovery removal from an account.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Calling this method starts the 7-day withdrawal delay before the removal can
+     * be completed.
      *
      * @param params - The account owner's adapter context, amount, and token.
      * @returns Promise resolving to the initiation details.
@@ -7198,11 +7397,16 @@ declare class AppKitUnifiedBalance {
      */
     initiateRemoveFund(params: InitiateRemoveFundParams): Promise<InitiateRemoveFundResult>;
     /**
-     * Complete a fund removal once the activation period has passed.
+     * Complete a trustless recovery removal after the withdrawal delay.
+     *
+     * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+     * recovery path for situations where the normal spend flow is unavailable.
+     * Both EVM and Solana removals require a 7-day withdrawal delay after
+     * `initiateRemoveFund` before funds can be removed.
      *
      * @param params - The account owner context matching the original initiation.
      * @returns Promise resolving to the fund removal details.
-     * @throws {KitError} If the activation period has not elapsed or the
+     * @throws {KitError} If the withdrawal delay has not elapsed or the
      *   on-chain transaction fails.
      *
      * @example
@@ -7273,6 +7477,43 @@ declare class AppKitUnifiedBalance {
      * ```
      */
     removeCustomFeePolicy(): void;
+    /**
+     * Set a declarative fee recipient map, keyed by chain type.
+     *
+     * Once set, `spend()`/`estimateSpend()` resolve the fee recipient by
+     * looking up the spend's destination chain type in this map — taking
+     * priority over `customFeePolicy`'s `resolveFeeRecipientAddress`
+     * callback.
+     *
+     * @remarks
+     * This only controls which address a fee is sent to — it does not by
+     * itself cause any fee to be charged. You still need
+     * `setCustomFeePolicy`'s `computeFee` to determine the fee amount;
+     * calling `setFeeRecipients` without ever calling `setCustomFeePolicy`
+     * throws at spend time (there is no `computeFee` to determine an
+     * amount).
+     *
+     * @param config - Fee recipient addresses keyed by chain type (e.g.
+     *   `{ evm: '0x...', solana: 'Sol...' }`).
+     *
+     * @example
+     * ```typescript
+     * kit.unifiedBalance.setFeeRecipients({
+     *   evm: '0x1234567890123456789012345678901234567890',
+     *   solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
+     * })
+     * ```
+     */
+    setFeeRecipients(config: FeeRecipientsConfig): void;
+    /**
+     * Remove the declarative fee recipient map.
+     *
+     * @example
+     * ```typescript
+     * kit.unifiedBalance.removeFeeRecipients()
+     * ```
+     */
+    removeFeeRecipients(): void;
 }
 
 export { AppKitUnifiedBalance };