@circle-fin/app-kit 1.15.2 → 1.16.0

package/estimateSwap.d.cts

@@ -551,8 +551,23 @@ interface CCTPXChainConfig {
  * const contractType: KitContractType = 'bridge' // Valid
  * const invalidType: KitContractType = 'invalid' // TypeScript error
  * ```
- */
-type KitContractType = 'bridge' | 'adapter';
+ *
+ * @remarks
+ * `'senderPreservingBatcher'` carries a stricter requirement than the others,
+ * because setting it wrong fails silently rather than loudly. It must name a
+ * batching contract that preserves the calling EOA as `msg.sender` in every
+ * subcall — on Arc, the `Multicall3From` predeploy, which achieves that
+ * through the `CallFrom` precompile. The name is deliberately more specific
+ * than "batcher": the ubiquitous Multicall3 at
+ * `0xcA11bde05977b3631167028862bE2a173976CA11` has the same ABI and the same
+ * selectors but does **not** qualify, since each subcall would arrive as the
+ * Multicall3 contract, so a batched `approve` would grant an allowance from
+ * the batcher's own balance rather than from the user's — a field named just
+ * `batcher` would make that misconfiguration look valid. Leave
+ * `senderPreservingBatcher` unset on any chain lacking one; an unset field
+ * simply means callers fall back to submitting calls one at a time.
+ */
+type KitContractType = 'bridge' | 'adapter' | 'senderPreservingBatcher';
 /**
  * Configuration for Gateway v1 contracts.
  *
@@ -1436,8 +1451,13 @@ type PreparedChainRequest = EvmPreparedChainRequest | SolanaPreparedChainRequest
  * Parameters for preparing an EVM contract execution.
  */
 type EvmPreparedChainRequestParams = {
-    /** The type of the prepared execution. */
-    type: 'evm';
+    /**
+     * The type of the prepared execution. Optional here because EVM is the
+     * only chain type `Adapter.prepare()` implementations narrow their param
+     * type to in practice — callers that only ever prepare EVM requests can
+     * omit it rather than repeat a discriminator that never varies for them.
+     */
+    type?: 'evm';
     /** The ABI of the contract. */
     abi: Abi | string[];
     /** The address of the contract. */
@@ -2716,6 +2736,57 @@ interface EarnActionMap {
     readonly claimRewards: ExecuteEarnParams;
 }
 
+/** Permit standards accepted by Borrow Adapter executions. */
+declare enum BorrowPermitType {
+    /** Tokens must be approved separately. */
+    NONE = 0,
+    /** EIP-2612 permit calldata accompanies the token input. */
+    EIP2612 = 1
+}
+/** Token input forwarded by Borrow Kit to the Adapter Contract. */
+interface BorrowTokenInput {
+    readonly permitType: BorrowPermitType;
+    readonly token: `0x${string}`;
+    readonly amount: bigint;
+    readonly permitCalldata: `0x${string}`;
+}
+/** A single instruction in a Circle-signed Borrow execution. */
+interface BorrowInstruction {
+    readonly target: `0x${string}`;
+    readonly data: `0x${string}`;
+    readonly value: string | bigint;
+    readonly tokenIn: `0x${string}`;
+    readonly amountToApprove: string | bigint;
+    readonly tokenOut: `0x${string}`;
+    readonly minTokenOut: string | bigint;
+}
+/** A token recipient in a Circle-signed Borrow execution. */
+interface BorrowTokenRecipient {
+    readonly token: `0x${string}`;
+    readonly beneficiary: `0x${string}`;
+}
+/** Circle-signed Borrow parameters forwarded to the Adapter Contract. */
+interface BorrowExecutionParams {
+    readonly instructions: readonly BorrowInstruction[];
+    readonly tokens: readonly BorrowTokenRecipient[];
+    readonly execId: string | bigint;
+    readonly deadline: string | bigint;
+    readonly metadata: `0x${string}`;
+}
+/** Parameters for a service-signed Borrow Adapter execution. */
+interface ExecuteBorrowParams extends ActionParameters {
+    readonly executeParams: BorrowExecutionParams;
+    readonly tokenInputs: BorrowTokenInput[];
+    readonly signature: `0x${string}`;
+}
+/** Borrow actions supported by EVM adapters. */
+interface BorrowActionMap {
+    /** Execute a Circle-signed partial loan repayment. */
+    readonly repay: ExecuteBorrowParams;
+    /** Execute a Circle-signed borrow. */
+    readonly execute: ExecuteBorrowParams;
+}
+
 /**
  * Single instruction to execute within the Adapter Contract.
  *
@@ -3672,6 +3743,8 @@ interface NativeActionMap {
  * @see {@link ActionPayload} for extracting payload types
  */
 interface ActionMap {
+    /** Borrow operations that execute service-signed payloads. */
+    readonly borrow: BorrowActionMap;
     /** CCTP-specific operations with automatic address resolution. */
     readonly cctp: CCTPActionMap;
     /** CCTPx operations (CrossChainTokenService) for cross-chain transfers of registered tokens (Circle-issued or otherwise). */
@@ -3691,6 +3764,7 @@ interface ActionMap {
     /** Earn operations that execute service-signed payloads via the adapter contract. */
     readonly earn: EarnActionMap;
 }
+
 /**
  * Determine if a type represents an action parameter object (leaf node).
  *
@@ -7431,6 +7505,26 @@ interface VaultQuery {
     /** On-chain vault contract address. */
     readonly vaultAddress: string;
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
 /**
  * Sort order for a vault discovery query.
  *
@@ -7445,6 +7539,51 @@ interface VaultQuery {
  */
 type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
@@ -7628,6 +7767,12 @@ interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabil
      * @example '100.50' for 100.50 USDC
      */
     readonly amount: string;
+    /**
+     * Gas fee estimates from a prior {@link getDepositQuote} call. When provided,
+     * the pre-broadcast gas reserve check uses the actual estimated cost instead
+     * of the conservative fallback reserve.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }
@@ -8222,8 +8367,8 @@ interface AppKitContext {
      *
      * This property stores event handlers that are registered via the AppKit's
      * `on()` method. Handlers are grouped by operation type. The runtime buckets
-     * are `bridge` and `earn`; the context can add more operation buckets as
-     * AppKit wires action handlers for additional kits.
+     * are `bridge`, `earn`, and `borrow`; the context can add more operation
+     * buckets as AppKit wires action handlers for additional kits.
      *
      * Within each operation bucket, handlers are keyed by action name (for
      * example, `bridge.approve` or `earn.deposit`) or `*` for wildcard handlers.
@@ -8242,13 +8387,13 @@ interface AppKitContext {
      * // Earn handlers are registered with EarnKit when earn operations run
      * ```
      */
-    actions: Record<'bridge' | 'earn', Record<string, ((payload: unknown) => void)[]>>;
+    actions: Record<'bridge' | 'earn' | 'borrow', Record<string, ((payload: unknown) => void)[]>>;
     /**
-     * Disable success analytics for the underlying EarnKit, SwapKit, and
-     * UnifiedBalanceKit.
+     * Disable success analytics for the underlying EarnKit, SwapKit,
+     * BorrowKit, and UnifiedBalanceKit.
      *
-     * When `true`, completed earn, swap, and unified balance operations will not
-     * POST analytics events. This does not disable error reporting; use
+     * When `true`, completed earn, swap, borrow, and unified balance operations
+     * will not POST analytics events. This does not disable error reporting; use
      * {@link AppKitContext.disableErrorReporting} for that. Defaults to `false`.
      *
      * @defaultValue false
@@ -8258,7 +8403,7 @@ interface AppKitContext {
      * Disable error telemetry for all sub-kits.
      *
      * When `true`, none of the underlying kits (BridgeKit, SwapKit, EarnKit,
-     * UnifiedBalanceKit) will POST error details to the telemetry
+     * BorrowKit, UnifiedBalanceKit) will POST error details to the telemetry
      * endpoint when operations throw. Defaults to `false` (enabled).
      *
      * @defaultValue false

package/estimateSwap.d.mts

@@ -551,8 +551,23 @@ interface CCTPXChainConfig {
  * const contractType: KitContractType = 'bridge' // Valid
  * const invalidType: KitContractType = 'invalid' // TypeScript error
  * ```
- */
-type KitContractType = 'bridge' | 'adapter';
+ *
+ * @remarks
+ * `'senderPreservingBatcher'` carries a stricter requirement than the others,
+ * because setting it wrong fails silently rather than loudly. It must name a
+ * batching contract that preserves the calling EOA as `msg.sender` in every
+ * subcall — on Arc, the `Multicall3From` predeploy, which achieves that
+ * through the `CallFrom` precompile. The name is deliberately more specific
+ * than "batcher": the ubiquitous Multicall3 at
+ * `0xcA11bde05977b3631167028862bE2a173976CA11` has the same ABI and the same
+ * selectors but does **not** qualify, since each subcall would arrive as the
+ * Multicall3 contract, so a batched `approve` would grant an allowance from
+ * the batcher's own balance rather than from the user's — a field named just
+ * `batcher` would make that misconfiguration look valid. Leave
+ * `senderPreservingBatcher` unset on any chain lacking one; an unset field
+ * simply means callers fall back to submitting calls one at a time.
+ */
+type KitContractType = 'bridge' | 'adapter' | 'senderPreservingBatcher';
 /**
  * Configuration for Gateway v1 contracts.
  *
@@ -1436,8 +1451,13 @@ type PreparedChainRequest = EvmPreparedChainRequest | SolanaPreparedChainRequest
  * Parameters for preparing an EVM contract execution.
  */
 type EvmPreparedChainRequestParams = {
-    /** The type of the prepared execution. */
-    type: 'evm';
+    /**
+     * The type of the prepared execution. Optional here because EVM is the
+     * only chain type `Adapter.prepare()` implementations narrow their param
+     * type to in practice — callers that only ever prepare EVM requests can
+     * omit it rather than repeat a discriminator that never varies for them.
+     */
+    type?: 'evm';
     /** The ABI of the contract. */
     abi: Abi | string[];
     /** The address of the contract. */
@@ -2716,6 +2736,57 @@ interface EarnActionMap {
     readonly claimRewards: ExecuteEarnParams;
 }
 
+/** Permit standards accepted by Borrow Adapter executions. */
+declare enum BorrowPermitType {
+    /** Tokens must be approved separately. */
+    NONE = 0,
+    /** EIP-2612 permit calldata accompanies the token input. */
+    EIP2612 = 1
+}
+/** Token input forwarded by Borrow Kit to the Adapter Contract. */
+interface BorrowTokenInput {
+    readonly permitType: BorrowPermitType;
+    readonly token: `0x${string}`;
+    readonly amount: bigint;
+    readonly permitCalldata: `0x${string}`;
+}
+/** A single instruction in a Circle-signed Borrow execution. */
+interface BorrowInstruction {
+    readonly target: `0x${string}`;
+    readonly data: `0x${string}`;
+    readonly value: string | bigint;
+    readonly tokenIn: `0x${string}`;
+    readonly amountToApprove: string | bigint;
+    readonly tokenOut: `0x${string}`;
+    readonly minTokenOut: string | bigint;
+}
+/** A token recipient in a Circle-signed Borrow execution. */
+interface BorrowTokenRecipient {
+    readonly token: `0x${string}`;
+    readonly beneficiary: `0x${string}`;
+}
+/** Circle-signed Borrow parameters forwarded to the Adapter Contract. */
+interface BorrowExecutionParams {
+    readonly instructions: readonly BorrowInstruction[];
+    readonly tokens: readonly BorrowTokenRecipient[];
+    readonly execId: string | bigint;
+    readonly deadline: string | bigint;
+    readonly metadata: `0x${string}`;
+}
+/** Parameters for a service-signed Borrow Adapter execution. */
+interface ExecuteBorrowParams extends ActionParameters {
+    readonly executeParams: BorrowExecutionParams;
+    readonly tokenInputs: BorrowTokenInput[];
+    readonly signature: `0x${string}`;
+}
+/** Borrow actions supported by EVM adapters. */
+interface BorrowActionMap {
+    /** Execute a Circle-signed partial loan repayment. */
+    readonly repay: ExecuteBorrowParams;
+    /** Execute a Circle-signed borrow. */
+    readonly execute: ExecuteBorrowParams;
+}
+
 /**
  * Single instruction to execute within the Adapter Contract.
  *
@@ -3672,6 +3743,8 @@ interface NativeActionMap {
  * @see {@link ActionPayload} for extracting payload types
  */
 interface ActionMap {
+    /** Borrow operations that execute service-signed payloads. */
+    readonly borrow: BorrowActionMap;
     /** CCTP-specific operations with automatic address resolution. */
     readonly cctp: CCTPActionMap;
     /** CCTPx operations (CrossChainTokenService) for cross-chain transfers of registered tokens (Circle-issued or otherwise). */
@@ -3691,6 +3764,7 @@ interface ActionMap {
     /** Earn operations that execute service-signed payloads via the adapter contract. */
     readonly earn: EarnActionMap;
 }
+
 /**
  * Determine if a type represents an action parameter object (leaf node).
  *
@@ -7431,6 +7505,26 @@ interface VaultQuery {
     /** On-chain vault contract address. */
     readonly vaultAddress: string;
 }
+/**
+ * Fields shared by both {@link EarnGasFeeEstimate} variants.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnGasFeeEstimateBase = {
+ *   name: 'Deposit',
+ *   token: 'ETH',
+ *   blockchain: 'Arc_Testnet',
+ * }
+ * ```
+ */
+interface EarnGasFeeEstimateBase {
+    /** The earn step being estimated, e.g. "Approve", "Deposit", "Withdraw". */
+    readonly name: string;
+    /** Native token used to pay gas fees, e.g. "ETH". */
+    readonly token: string;
+    /** Blockchain where this gas fee applies. */
+    readonly blockchain: ChainDefinition['chain'];
+}
 /**
  * Sort order for a vault discovery query.
  *
@@ -7445,6 +7539,51 @@ interface VaultQuery {
  */
 type ExploreVaultsSortBy = 'apy' | 'tvl' | 'name';
 
+/**
+ * Estimated gas details for one transaction in a kit-level Earn quote, with
+ * every amount as a decimal string so quote results stay JSON-serializable.
+ *
+ * @example
+ * ```typescript
+ * const gas: EarnEstimatedGas = { gas: '73567', gasPrice: '20003763738', fee: '1471616886913446' }
+ * ```
+ */
+interface EarnEstimatedGas {
+    /** Estimated gas units as a decimal string, e.g. '73567'. */
+    readonly gas: string;
+    /** Estimated price per gas unit as a decimal string in wei. */
+    readonly gasPrice: string;
+    /** Total estimated fee as a decimal string in wei. */
+    readonly fee: string;
+}
+/**
+ * Estimated native gas fee for one transaction in an Earn quote.
+ *
+ * A discriminated union on `fees`: a successful estimate carries
+ * {@link EarnEstimatedGas} details and no `error`; a failed estimate carries
+ * `fees: null` and a sanitized `error` message.
+ *
+ * @example
+ * ```typescript
+ * function describe(entry: EarnGasFeeEstimate): string {
+ *   if (entry.fees === null) {
+ *     return `${entry.name}: estimation failed (${entry.error})`
+ *   }
+ *   return `${entry.name}: ${entry.fees.fee} wei`
+ * }
+ * ```
+ */
+type EarnGasFeeEstimate = (EarnGasFeeEstimateBase & {
+    /** Estimated gas details with amounts formatted as decimal strings. */
+    readonly fees: EarnEstimatedGas;
+    /** Never present on a successful estimate. */
+    readonly error?: never;
+}) | (EarnGasFeeEstimateBase & {
+    /** Null because estimation failed. */
+    readonly fees: null;
+    /** Sanitized estimation error message. */
+    readonly error: string;
+});
 /**
  * Adapter context for earn operations, constrained to earn-supported chains.
  *
@@ -7628,6 +7767,12 @@ interface SameChainDepositParams<TFromAdapterCapabilities extends AdapterCapabil
      * @example '100.50' for 100.50 USDC
      */
     readonly amount: string;
+    /**
+     * Gas fee estimates from a prior {@link getDepositQuote} call. When provided,
+     * the pre-broadcast gas reserve check uses the actual estimated cost instead
+     * of the conservative fallback reserve.
+     */
+    readonly gasFees?: readonly EarnGasFeeEstimate[] | undefined;
     /** Optional earn configuration. */
     readonly config?: EarnConfig | undefined;
 }
@@ -8222,8 +8367,8 @@ interface AppKitContext {
      *
      * This property stores event handlers that are registered via the AppKit's
      * `on()` method. Handlers are grouped by operation type. The runtime buckets
-     * are `bridge` and `earn`; the context can add more operation buckets as
-     * AppKit wires action handlers for additional kits.
+     * are `bridge`, `earn`, and `borrow`; the context can add more operation
+     * buckets as AppKit wires action handlers for additional kits.
      *
      * Within each operation bucket, handlers are keyed by action name (for
      * example, `bridge.approve` or `earn.deposit`) or `*` for wildcard handlers.
@@ -8242,13 +8387,13 @@ interface AppKitContext {
      * // Earn handlers are registered with EarnKit when earn operations run
      * ```
      */
-    actions: Record<'bridge' | 'earn', Record<string, ((payload: unknown) => void)[]>>;
+    actions: Record<'bridge' | 'earn' | 'borrow', Record<string, ((payload: unknown) => void)[]>>;
     /**
-     * Disable success analytics for the underlying EarnKit, SwapKit, and
-     * UnifiedBalanceKit.
+     * Disable success analytics for the underlying EarnKit, SwapKit,
+     * BorrowKit, and UnifiedBalanceKit.
      *
-     * When `true`, completed earn, swap, and unified balance operations will not
-     * POST analytics events. This does not disable error reporting; use
+     * When `true`, completed earn, swap, borrow, and unified balance operations
+     * will not POST analytics events. This does not disable error reporting; use
      * {@link AppKitContext.disableErrorReporting} for that. Defaults to `false`.
      *
      * @defaultValue false
@@ -8258,7 +8403,7 @@ interface AppKitContext {
      * Disable error telemetry for all sub-kits.
      *
      * When `true`, none of the underlying kits (BridgeKit, SwapKit, EarnKit,
-     * UnifiedBalanceKit) will POST error details to the telemetry
+     * BorrowKit, UnifiedBalanceKit) will POST error details to the telemetry
      * endpoint when operations throw. Defaults to `false` (enabled).
      *
      * @defaultValue false