@circle-fin/app-kit 1.15.2 → 1.16.0

package/earn.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).
  *
@@ -5578,1209 +5652,1274 @@ interface InvocationMeta {
 }
 
 /**
- * Transfer speed options for cross-chain operations.
+ * Type definitions for the Amount system.
  *
- * Defines the available speed modes for CCTPv2 transfers, affecting
- * both transfer time and potential fee implications.
+ * @remarks
+ * This module defines the core types for type-safe token amount handling.
+ * Amounts are immutable value objects that carry the raw bigint value
+ * and decimal precision. Token identity (symbol, address) is managed
+ * separately by the token registry.
+ *
+ * @packageDocumentation
  */
-declare enum TransferSpeed {
-    /** Fast burn mode - reduces transfer time but may have different fee implications */
-    FAST = "FAST",
-    /** Standard burn mode - normal transfer time with standard fees */
-    SLOW = "SLOW"
-}
 /**
- * Context object representing a wallet and signing authority on a specific blockchain network.
- *
- * Combines a wallet or contract address, the blockchain it resides on, and the adapter (signer)
- * responsible for authorizing transactions. Used to specify the source or destination in cross-chain
- * transfer operations.
+ * An immutable token amount value.
  *
  * @remarks
- * The `adapter` (signer) and `address` do not always have to belong to the same entity. For example,
- * in minting or withdrawal scenarios, the signing adapter may authorize a transaction that credits
- * funds to a different recipient address. This context is essential for cross-chain operations,
- * ensuring that both the address and the associated adapter are correctly paired with the intended
- * blockchain, but not necessarily with each other.
+ * Amounts are pure numeric value objects containing the raw bigint value
+ * (in smallest units) and decimal precision. They are immutable - all
+ * math operations return new Amount instances.
+ *
+ * Token identity (symbol, contract address) is intentionally NOT included.
+ * This separation ensures developers explicitly source token metadata from
+ * the token registry, preventing incorrect symbol display.
  *
  * @example
  * ```typescript
- * import type { WalletContext } from '@core/provider'
- * import { adapter, blockchain } from './setup'
- *
- * const wallet: WalletContext = {
- *   adapter,
- *   address: '0x1234...abcd',
- *   chain: blockchain,
+ * const amount: Amount = {
+ *   raw: 1_000_000n,  // 1 token in smallest units (e.g., 1 USDC)
+ *   decimals: 6,
  * }
  * ```
  */
-interface WalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
-/**
- * The chain definition type to use for the wallet context.
- *
- * @defaultValue ChainDefinition
- */
-TChainDefinition extends ChainDefinition = ChainDefinition> {
-    /**
-     * The adapter (signer) for the wallet on the specified chain.
-     *
-     * Responsible for authorizing transactions and signing messages on behalf of the wallet or
-     * for a different recipient, depending on the use case.
-     */
-    adapter: Adapter<TAdapterCapabilities>;
+interface Amount$1 {
     /**
-     * The wallet or contract address.
-     *
-     * Must be a valid address format for the specified blockchain. May differ from the adapter's
-     * own address in scenarios such as relayed transactions or third-party minting.
+     * The raw value in smallest units (e.g., wei for ETH, micro-units for USDC).
      */
-    address: string;
+    readonly raw: bigint;
     /**
-     * The blockchain network where the wallet or contract address resides.
+     * Number of decimal places for this token.
      *
-     * Determines the context and format for the address and adapter.
+     * @remarks
+     * Common values:
+     * - USDC/USDT: 6
+     * - ETH/ERC-20: 18
      */
-    chain: TChainDefinition;
+    readonly decimals: number;
 }
 /**
- * Wallet context for bridge destinations with optional custom recipient.
- *
- * Extends WalletContext to support scenarios where the recipient address
- * differs from the signer address (e.g., bridging to a third-party wallet).
- * The signer address is used for transaction authorization, while the
- * recipient address specifies where the minted funds should be sent.
- *
- * @typeParam TAdapterCapabilities - The adapter capabilities type to use for the wallet context.
- * @typeParam TChainDefinition - The chain definition type to use for the wallet context.
- *
- * @example
- * ```typescript
- * import type { DestinationWalletContext } from '@core/provider'
- * import { adapter, blockchain } from './setup'
+ * Configuration for creating amounts.
  *
- * // Bridge to a custom recipient address
- * const destination: DestinationWalletContext = {
- *   adapter,
- *   address: '0x1234...abcd', // Signer address
- *   chain: blockchain,
- *   recipientAddress: '0x9876...fedc' // Custom recipient
- * }
- * ```
+ * @remarks
+ * Specifies the decimal precision for the amount. Typically obtained
+ * from the token registry.
  */
-interface DestinationWalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+interface AmountConfig {
+    /**
+     * Number of decimal places.
+     */
+    decimals: number;
+}
 /**
- * The chain definition type to use for the wallet context.
- *
- * @defaultValue ChainDefinition
+ * Options for formatting amounts as human-readable strings.
  */
-TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContext<TAdapterCapabilities, TChainDefinition> {
+interface FormatOptions {
     /**
-     * Optional custom recipient address for minted funds.
-     *
-     * When provided, minted tokens will be sent to this address instead of
-     * the address specified in the wallet context. The wallet context address
-     * is still used for transaction signing and authorization.
+     * Locale for number formatting.
      *
-     * Must be a valid address format for the specified blockchain.
+     * @defaultValue 'en-US'
      */
-    recipientAddress?: string;
+    locale?: string;
     /**
-     * Whether Circle's relayer submits the destination transaction.
+     * Minimum fraction digits to display.
      *
-     * How an omitted value resolves, and whether an explicit `false` is accepted,
-     * is provider-specific.
+     * @defaultValue 0
      */
-    useForwarder?: boolean;
+    minimumFractionDigits?: number;
     /**
-     * Optional destination dApp deposit action for a fast cross-chain transfer.
+     * Maximum fraction digits to display.
      *
-     * 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`.
+     * @defaultValue decimals
+     */
+    maximumFractionDigits?: number;
+    /**
+     * Use grouping separators (e.g., 1,000,000).
      *
-     * @see {@link BridgeDepositAction}
+     * @defaultValue true
      */
-    deposit?: BridgeDepositAction;
+    useGrouping?: boolean;
 }
 /**
- * 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'
+ * Options for parsing human-readable strings to amounts.
  *
- * const deposit: BridgeDepositAction = {
- *   dappId: 'gateway_deposit',
- *   params: ['0xTokenMessengerWithFees', '0xDepositAccount', 0n],
- * }
- * ```
+ * @remarks
+ * Currently only supports '.' as the decimal separator (en-US style).
  */
-interface BridgeDepositAction {
+interface ParseOptions {
     /**
-     * Registered dApp identifier the GenericExecutor invokes on the destination
-     * chain (for example, `'gateway_deposit'`).
+     * Number of decimal places.
      */
-    dappId: string;
+    decimals: number;
     /**
-     * Positional arguments for the dApp function, in ABI order. Dynamic amount
-     * slots are filled in by the executor from the minted amount.
+     * Whether to allow negative values.
+     *
+     * @defaultValue false
      */
-    params: readonly unknown[];
+    allowNegative?: boolean;
 }
 /**
- * Parameters for executing a cross-chain bridge operation.
+ * Result of comparing two amounts.
  */
-interface BridgeParams$1<TFromCapabilities extends AdapterCapabilities = AdapterCapabilities, TToCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+type ComparisonResult = -1 | 0 | 1;
 /**
- * The chain definition type to use for the wallet context.
+ * Types that can be converted to an Amount.
  *
- * @defaultValue ChainDefinition
+ * @remarks
+ * - `bigint`: Raw value (requires config with decimals)
+ * - `string`: Human-readable (e.g., "100.50")
+ * - `number`: Human-readable (e.g., 100.5) - beware of precision!
+ * - `Amount`: Existing amount or plain object with Amount shape
  */
-TChainDefinition extends ChainDefinition = ChainDefinition, 
+type AmountLike = bigint | string | number | Amount$1;
 /**
- * The token type the provider accepts.
- *
- * @defaultValue 'USDC'
+ * JSON representation of an Amount.
  *
  * @remarks
- * The default preserves the original USDC-only contract for consumers that
- * omit the token type. Providers that accept a different token type pass
- * `TToken` explicitly.
+ * Used for serialization. The `raw` value is stringified since JSON
+ * does not support bigint natively.
  *
  * @example
  * ```typescript
- * // Default — TToken resolves to 'USDC'
- * type DefaultParams = BridgeParams // params.token is typed as 'USDC'
- *
- * // Provider that identifies tokens by a hex string template literal
- * type HexTokenParams = BridgeParams<
- *   AdapterCapabilities,
- *   AdapterCapabilities,
- *   ChainDefinition,
- *   `0x${string}`
- * > // params.token is typed as `0x${string}`
+ * const json: AmountJSON = {
+ *   raw: "1500000",
+ *   decimals: 6,
+ *   formatted: "1.5"
+ * }
  * ```
  */
-TToken extends string = 'USDC'> {
-    /** The source adapter containing wallet and chain information */
-    source: WalletContext<TFromCapabilities, TChainDefinition>;
-    /** The destination adapter containing wallet and chain information */
-    destination: DestinationWalletContext<TToCapabilities, TChainDefinition>;
-    /** The amount to transfer (as a string to avoid precision issues) */
-    amount: string;
-    /** The token to transfer (provider-defined; defaults to `'USDC'`) */
-    token: TToken;
-    /** Bridge configuration (e.g., fast burn settings) */
-    config: BridgeConfig;
-    /**
-     * Optional server-signed quote to reuse, typically the
-     * {@link EstimateResult.quote} returned by an earlier `estimate` call.
-     *
-     * When present and still valid, a provider with a server-signed quote
-     * model may reuse it instead of fetching a fresh quote, so the fee the
-     * caller was quoted is the fee they pay. Providers decide when a reused
-     * quote is still valid (e.g. freshness, fee token, speed); an unusable or
-     * mismatched quote is ignored and a fresh one is fetched. Transfer
-     * parameters are validated by the provider's on-chain contract, so a quote
-     * reused for a different transfer is rejected there rather than silently.
-     * Providers without a quote model ignore this field entirely, and do so
-     * silently — nothing verifies that a quote reached the provider that issued
-     * it, because the route is matched to a provider only after these
-     * parameters are validated. A quote is meaningful only on the route that
-     * produced it.
-     *
-     * Typed `unknown`: a caller reaches `bridge` through a provider-agnostic
-     * surface, so this shared type names no provider's shape. It is public
-     * input in any case, and is validated before any field is read — by the
-     * provider that serves the route, or by the kit for routes it prices
-     * itself. Treat it as opaque and pass it back unmodified.
-     *
-     * This is a `bridge` input. A quote is an output of `estimate`, not an
-     * input to it — `estimate` always returns a freshly-priced quote, and a
-     * provider may reject a quote passed to `estimate` rather than ignore it.
-     */
-    quote?: unknown;
-    /**
-     * Optional invocation metadata for tracing and correlation.
-     *
-     * When provided, the `traceId` is used to correlate all events emitted during
-     * the bridge operation. If not provided, an OpenTelemetry-compatible traceId
-     * will be auto-generated.
-     */
-    invocationMeta?: InvocationMeta;
+interface AmountJSON {
+    /** The raw value as a string (bigint serialized). */
+    raw: string;
+    /** Number of decimal places. */
+    decimals: number;
+    /** Human-readable formatted value. */
+    formatted: string;
 }
+
 /**
- * Configuration options for customizing bridge behavior.
+ * Minimal fields required for internal Amount operations.
  *
  * @remarks
- * This interface is currently incomplete and will be expanded in future versions
- * to include additional configuration options such as slippage tolerance,
- * deadline settings, and other bridge parameters.
+ * This internal type mirrors the public {@link Amount} interface shape but exists
+ * separately to avoid circular dependencies. Internal modules (math, comparison,
+ * formatting) import this lightweight type instead of the full Amount class.
+ *
+ * The Amount class implements this interface, so internal helpers can operate
+ * on either Amount instances or plain objects with the same shape.
  *
+ * @see {@link ../types.ts#Amount} for the public interface
+ * @internal
  */
-interface BridgeConfig {
+interface AmountFields {
+    readonly raw: bigint;
+    readonly decimals: number;
+}
+
+/**
+ * Fluent Amount class for type-safe token amount handling.
+ *
+ * @remarks
+ * The `Amount` class provides an immutable, fluent API for working with token
+ * amounts. It wraps a raw bigint value with decimal precision and provides
+ * chainable methods for math, comparison, and formatting.
+ *
+ * Token identity (symbol, contract address) is intentionally NOT included.
+ * This ensures developers explicitly source token metadata from the token
+ * registry, preventing incorrect symbol display.
+ *
+ * @example
+ * ```typescript
+ * import { Amount } from '@core/amounts'
+ *
+ * // Create from raw value or parse from string
+ * const a = Amount.of(1_000_000n, { decimals: 6 })
+ * const b = Amount.parse('0.5', { decimals: 6 })
+ *
+ * // Fluent operations
+ * const result = a.add(b).mul(2n).sub(Amount.parse('0.25', { decimals: 6 }))
+ *
+ * // Comparisons and formatting
+ * a.gt(b)           // true
+ * a.toString()      // "1"
+ *
+ * // For display with symbol, combine with token registry:
+ * // `${amount.toString()} ${token.symbol}`
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * An immutable token amount with fluent API methods.
+ *
+ * @remarks
+ * The `Amount` class provides a type-safe, ergonomic way to work with token
+ * amounts. It combines the raw bigint value with decimal precision and
+ * provides chainable methods for:
+ *
+ * - **Math operations**: add, sub, mul, div, abs, neg
+ * - **Comparisons**: eq, lt, lte, gt, gte, cmp, min, max
+ * - **Predicates**: isZero, isPositive, isNegative
+ * - **Formatting**: formatted, toString, toJSON
+ * - **Conversion**: toDecimals
+ *
+ * All operations return new Amount instances - the class is immutable.
+ *
+ * Token identity (symbol) is intentionally excluded. Source token metadata
+ * from the token registry for display purposes.
+ */
+declare class Amount implements AmountFields {
+    /** The raw value in smallest units (e.g., wei for ETH, micro-units for USDC). */
+    readonly raw: bigint;
+    /** Number of decimal places for this token. */
+    readonly decimals: number;
+    private constructor();
     /**
-     * The transfer speed mode for CCTPv2 transfers.
+     * Create an Amount from a raw bigint value.
      *
-     * Controls whether to use fast burn mode (FAST) or standard mode (SLOW).
-     * Fast burn may reduce transfer time but could have different fee implications.
+     * @param raw - The raw value in smallest units.
+     * @param config - Configuration with decimals.
+     * @returns A new immutable Amount instance.
+     * @throws KitError If raw is not a bigint or decimals is invalid.
      *
-     * @defaultValue TransferSpeed.FAST
+     * @example
+     * ```typescript
+     * // Get decimals from token registry
+     * const amount = Amount.of(1_000_000n, { decimals: 6 })
+     * ```
      */
-    transferSpeed?: TransferSpeed | `${TransferSpeed}` | undefined;
+    static of(raw: bigint, config: AmountConfig): Amount;
     /**
-     * Enable or disable EIP-5792 batched transaction execution.
-     *
-     * When `true` (or `undefined` / omitted), the bridge will attempt to batch
-     * the approve and burn calls into a single `wallet_sendCalls` request if
-     * the connected wallet supports it. Set to `false` to explicitly opt out
-     * and always use the sequential approve -> burn flow.
+     * Parse a human-readable string or number into an Amount.
      *
-     * @defaultValue `undefined` (batching attempted when the wallet supports it)
+     * @param input - The input to parse (e.g., "100.50" or 100.5).
+     * @param options - Parse options including decimals.
+     * @returns A new immutable Amount instance.
+     * @throws KitError If input is invalid or parsing fails.
      *
      * @example
      * ```typescript
-     * const config: BridgeConfig = {
-     *   batchTransactions: false, // force sequential flow
-     * }
+     * const amount = Amount.parse('100.50', { decimals: 6 })
      * ```
      */
-    batchTransactions?: boolean | undefined;
+    static parse(input: string | number, options: ParseOptions): Amount;
     /**
-     * The maximum fee to pay for the burn operation.
+     * Convert any AmountLike value to an Amount.
      *
-     * Provide the amount as a base-10 numeric string representing the
-     * token amount in human-readable format. For example: to set a maximum
-     * fee of 1 USDC, pass `"1"`. Decimal values are supported (e.g., `"0.5"`
-     * for half a USDC).
+     * @param input - The input (bigint, string, number, or existing Amount).
+     * @param config - Configuration (required for non-Amount inputs).
+     * @returns A new immutable Amount instance.
+     * @throws KitError If conversion fails or config is missing.
      *
-     * @defaultValue `"0"`
+     * @remarks
+     * When providing a `number` input, very large or small values may be
+     * converted to exponential notation (e.g., `1e21`), which is not supported.
+     * For such values, provide a `string` representation instead.
      *
      * @example
      * ```typescript
-     * import type { BridgeConfig, TransferSpeed } from '@core/provider'
-     *
-     * const config: BridgeConfig = {
-     *   transferSpeed: TransferSpeed.FAST,
-     *   maxFee: "1", // 1 USDC maximum fee
-     *   customFee: {
-     *     value: "0.5", // 0.5 USDC developer fee
-     *     recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
-     *   }
-     * }
+     * Amount.from(1_000_000n, { decimals: 6 })  // from bigint
+     * Amount.from('1.00', { decimals: 6 })      // from string
+     * Amount.from(existingAmount)               // pass-through
      * ```
      */
-    maxFee?: string;
+    static from(input: AmountLike, config?: AmountConfig): Amount;
     /**
-     * The custom fee to charge for the transfer.
+     * Create a zero Amount with the given configuration.
      *
-     * Whatever value you provide here is **added on top of the transfer amount**. The user must have
-     * enough balance for `amount + customFee`, and the wallet signs for that total on the source
-     * chain. The custom fee is split automatically:
+     * @param config - Configuration with decimals.
+     * @returns A zero Amount instance.
      *
-     * - 10% routes to Circle.
-     * - 90% routes to your `recipientAddress`.
+     * @example
+     * ```typescript
+     * const zero = Amount.zero({ decimals: 6 })
+     * ```
+     */
+    static zero(config: AmountConfig): Amount;
+    /**
+     * Check if a value is an Amount-like object.
      *
-     * The original transfer amount proceeds through CCTPv2 unchanged, and the protocol fee (1–14 bps
-     * in FAST mode, 0% in STANDARD) is taken from that transfer amount.
+     * @param value - The value to check.
+     * @returns True if the value has Amount shape (raw: bigint, decimals: number).
      *
      * @example
      * ```typescript
-     * import type { BridgeConfig } from '@core/provider'
+     * Amount.isAmount({ raw: 1000000n, decimals: 6 }) // true
+     * Amount.isAmount({ value: 100 })                 // false
+     * ```
+     */
+    static isAmount(value: unknown): value is {
+        raw: bigint;
+        decimals: number;
+    };
+    /**
+     * Sum an array of Amounts.
      *
-     * const config: BridgeConfig = {
-     *   customFee: {
-     *     value: '5', // 5 USDC developer fee
-     *     recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
-     *   },
-     * }
+     * @param amounts - The amounts to sum (must have same decimals).
+     * @returns A new Amount with the total sum.
+     * @throws KitError If amounts array is empty or decimals don't match.
      *
-     * // Fee flow for a 100 USDC transfer with 5 USDC custom fee:
-     * // Source chain (Ethereum):
-     * // - Wallet debits: 105 USDC total (100 transfer + 5 custom fee)
-     * // - Custom fee split: 0.5 USDC (10%) → Circle, 4.5 USDC (90%) → your recipientAddress
-     * // - Amount sent to CCTPv2: 100 USDC (unchanged)
-     * //
-     * // Destination chain (Base):
-     * // - CCTPv2 FAST fee (example: 1 bps): ~0.01 USDC deducted
-     * // - User receives: ~99.99 USDC
-     * //
-     * // Note: Actual CCTP fees vary by route (1-14 bps for FAST, 0 bps for STANDARD)
+     * @example
+     * ```typescript
+     * const fee1 = Amount.parse('0.10', { decimals: 6 })
+     * const fee2 = Amount.parse('0.25', { decimals: 6 })
+     * const fee3 = Amount.parse('0.15', { decimals: 6 })
+     *
+     * const total = Amount.sum([fee1, fee2, fee3])
+     * total.toString() // "0.5"
      * ```
      */
-    customFee?: CustomFee | undefined;
+    static sum(amounts: readonly Amount[]): Amount;
     /**
-     * Which leg pays the protocol fee.
+     * Deserialize an Amount from a JSON object.
      *
-     * `'source'` leaves the delivered amount unreduced; `'destination'` takes the
-     * fee from it. Omit it to let the routed provider decide — a provider rejects
-     * a value it cannot honour.
+     * @param json - The JSON object (e.g., from `JSON.parse()`).
+     * @returns A new Amount instance.
+     * @throws KitError If the JSON structure is invalid.
+     *
+     * @example
+     * ```typescript
+     * const json = JSON.parse('{"raw":"1500000","decimals":6}')
+     * const amount = Amount.fromJSON(json)
+     * ```
      */
-    feePayment?: 'source' | 'destination' | undefined;
-}
-/**
- * Custom fee configuration charged by the integrator.
- *
- * Use to charge an absolute fee on the source chain in human-readable
- * token amounts.
- *
- * @remarks
- * This is an absolute amount, not a percentage. The `recipientAddress` must be
- * a valid address for the source chain of the transfer.
- *
- * @example
- * ```typescript
- * import type { CustomFee } from '@core/provider'
- *
- * const config: CustomFee = {
- *   value: '1', // 1 USDC
- *   recipientAddress: '0x1234567890123456789012345678901234567890',
- * }
- * ```
- */
-interface CustomFee {
+    static fromJSON(json: unknown): Amount;
     /**
-     * The absolute fee to charge for the transfer.
+     * Compare this Amount with another.
      *
-     * Provide the amount as a base-10 numeric string representing the token
-     * amount in human-readable format. For example: to charge 1 USDC, pass
-     * `"1"`. Decimal values are supported (e.g., `"0.5"` for half a USDC).
-     * This is not a percentage.
+     * @param other - The Amount to compare with.
+     * @returns -1 if this is less than other, 0 if equal, 1 if this is greater.
+     * @throws KitError If amounts have different decimals.
      *
-     * Note: passing `"0"` results in no fee being charged.
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.5', { decimals: 6 })
+     * const b = Amount.parse('2.0', { decimals: 6 })
+     * a.compare(b) // -1
+     * ```
      */
-    value?: string | undefined;
+    compare(other: Amount): ComparisonResult;
     /**
-     * The fee recipient for the bridge transfer.
-     *
-     * This is the address that will receive the fee on the source chain of the
-     * bridge transfer. The fee recipient address **must be a valid address for
-     * the source chain** of the bridge transfer.
+     * Check if this Amount equals another.
      *
-     * @remarks
-     * Circle automatically receives 10% of every custom fee; the remaining 90% is
-     * sent to this `recipientAddress`.
+     * @param other - The Amount to compare with.
+     * @returns True if the raw values are equal.
+     * @throws KitError If amounts have different decimals.
      *
-     * For example: if bridging from Ethereum to Solana, pass an EVM address like
-     * `"0x1234567890123456789012345678901234567890"` because the source chain
-     * is Ethereum.
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.5', { decimals: 6 })
+     * const b = Amount.parse('1.5', { decimals: 6 })
+     * a.eq(b) // true
+     * ```
      */
-    recipientAddress?: string | undefined;
-}
-/**
- * Represents the context of an adapter used for cross-chain operations.
- *
- * An AdapterContext must always specify both the adapter and the chain explicitly.
- * The address field behavior is determined by the adapter's address control model:
- *
- * - **Developer-controlled adapters**: The `address` field is required because
- *   each operation must explicitly specify which address to use.
- * - **User-controlled adapters**: The `address` field is forbidden because
- *   the address is automatically resolved from the connected wallet or signer.
- * - **Legacy adapters**: The `address` field remains optional for backward compatibility.
- *
- * This ensures clear, debuggable code where the intended chain is always visible at the call site,
- * and address requirements are enforced at compile time based on adapter capabilities.
- *
- * @typeParam TAdapterCapabilities - The adapter capabilities type to derive address requirements from
- * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
- *
- * @example
- * ```typescript
- * // Developer-controlled adapter (address required)
- * const devContext: AdapterContext<{ addressContext: 'developer-controlled', supportedChains: [] }> = {
- *   adapter: myDevAdapter,
- *   chain: 'Ethereum',
- *   address: '0x123...' // Required
- * }
- *
- * // User-controlled adapter (address forbidden)
- * const userContext: AdapterContext<{ addressContext: 'user-controlled', supportedChains: [] }> = {
- *   adapter: myUserAdapter,
- *   chain: 'Ethereum'
- *   // address: '0x123...' // TypeScript error: not allowed
- * }
- * ```
- */
-type AdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> = {
-    /** The adapter instance for blockchain operations */
-    adapter: Adapter<TAdapterCapabilities>;
-    /** The chain reference, which can be a ChainDefinition, Blockchain enum, or string literal */
-    chain: TChainIdentifier;
-} & AddressField<ExtractAddressContext<TAdapterCapabilities>>;
-/**
- * Represents a bridge destination with an explicit custom recipient address.
- *
- * Extends {@link AdapterContext} with an additional `recipientAddress` field to specify
- * a custom recipient that differs from the adapter's address. Use this when bridging to
- * third-party wallets or smart contracts rather than the default address associated with
- * the destination adapter.
- *
- * @typeParam TCapabilities - The adapter capabilities type for the destination adapter
- * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
- *
- * @remarks
- * The `recipientAddress` must be a valid address format for the destination chain
- * specified in the adapter context. The bridge provider validates address compatibility
- * during the transfer preparation phase and will throw an error if the address format
- * is invalid for the target chain.
- *
- * @example
- * ```typescript
- * import { BridgeDestinationWithAddress } from '@core/provider'
- * import { ethereumAdapter } from './adapters'
- *
- * // Bridge to a custom recipient address on Ethereum
- * const destination: BridgeDestinationWithAddress = {
- *   adapter: ethereumAdapter,
- *   chain: 'Ethereum',
- *   recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0'
- * }
- * ```
- */
-type BridgeDestinationWithAddress<TCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> = AdapterContext<TCapabilities, TChainIdentifier> & {
+    eq(other: Amount): boolean;
     /**
-     * The custom recipient address on the destination chain.
+     * Check if this Amount is less than another.
      *
-     * Must be a valid address format for the chain specified in this adapter context.
-     * This address will receive the bridged funds instead of the adapter's default address.
+     * @param other - The Amount to compare with.
+     * @returns True if this.raw is less than other.raw.
+     * @throws KitError If amounts have different decimals.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.0', { decimals: 6 })
+     * const b = Amount.parse('2.0', { decimals: 6 })
+     * a.lt(b) // true
+     * ```
      */
-    recipientAddress: string;
-};
-/**
- * Forwarder-only destination without an adapter.
- *
- * Used when Circle's Forwarder handles the mint transaction and no destination
- * adapter is available. Requires both `useForwarder: true` and a `recipientAddress`.
- *
- * When using this destination type:
- * - The mint step completes when the IRIS API confirms `forwardState === 'CONFIRMED'`
- * - No on-chain transaction confirmation is performed (no adapter available)
- * - The mint step's `data` field will be undefined (no transaction receipt)
- *
- * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
- *
- * @example
- * ```typescript
- * // Forwarder-only destination (no adapter needed)
- * const dest: ForwarderDestination = {
- *   chain: 'Base',
- *   recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
- *   useForwarder: true
- * }
- * ```
- */
-interface ForwarderDestination<TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> {
-    /** The destination chain where USDC will be minted */
-    chain: TChainIdentifier;
-    /** The recipient address that will receive the minted USDC */
-    recipientAddress: string;
-    /** Must be true for forwarder-only destinations */
-    useForwarder: true;
-}
-/**
- * Union type representing a bridge destination.
- *
- * Supports multiple destination configurations:
- * - {@link AdapterContext}: Standard destination with adapter (for default recipient)
- * - {@link BridgeDestinationWithAddress}: Destination with adapter and custom recipient
- * - {@link ForwarderDestination}: Forwarder-only destination without adapter (requires recipientAddress)
- *
- * When `useForwarder` is enabled with an adapter, Circle's Orbit relayer handles the mint
- * transaction and the adapter is used to wait for transaction confirmation.
- *
- * When `useForwarder` is enabled without an adapter (ForwarderDestination), the mint step
- * completes when the IRIS API confirms `forwardState === 'CONFIRMED'` without on-chain
- * confirmation.
- *
- * @typeParam TAdapterCapabilities - The adapter capabilities type for the destination adapter
- * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
- *
- * @example
- * ```typescript
- * // Standard destination with adapter
- * const dest1: BridgeDestination = { adapter, chain: 'Base' }
- *
- * // Destination with adapter and custom recipient
- * const dest2: BridgeDestination = { adapter, chain: 'Base', recipientAddress: '0x...' }
- *
- * // Destination with forwarder enabled (adapter for tx confirmation)
- * const dest3: BridgeDestination = { adapter, chain: 'Base', useForwarder: true }
- *
- * // Forwarder-only destination (no adapter, requires recipientAddress)
- * const dest4: BridgeDestination = { chain: 'Base', useForwarder: true, recipientAddress: '0x...' }
- * ```
- */
-type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> = ((AdapterContext<TAdapterCapabilities, TChainIdentifier> | BridgeDestinationWithAddress<TAdapterCapabilities, TChainIdentifier>) & {
+    lt(other: Amount): boolean;
     /**
-     * Enable Circle's relayer to submit the destination transaction.
+     * Check if this Amount is less than or equal to another.
      *
-     * Where the relay fee is charged depends on the route and on
-     * {@link BridgeConfig.feePayment}: it may be taken from the amount that
-     * arrives, or priced into a quote the source transaction pays.
+     * @param other - The Amount to compare with.
+     * @returns True if this.raw is less than or equal to other.raw.
+     * @throws KitError If amounts have different decimals.
      *
-     * Whether the option is required, optional, or refused depends on the
-     * routed provider and the rest of the config.
-     */
-    useForwarder?: boolean;
-}) | ForwarderDestination<TChainIdentifier>;
-
-/**
- * Type definitions for the Amount system.
- *
- * @remarks
- * This module defines the core types for type-safe token amount handling.
- * Amounts are immutable value objects that carry the raw bigint value
- * and decimal precision. Token identity (symbol, address) is managed
- * separately by the token registry.
- *
- * @packageDocumentation
- */
-/**
- * An immutable token amount value.
- *
- * @remarks
- * Amounts are pure numeric value objects containing the raw bigint value
- * (in smallest units) and decimal precision. They are immutable - all
- * math operations return new Amount instances.
- *
- * Token identity (symbol, contract address) is intentionally NOT included.
- * This separation ensures developers explicitly source token metadata from
- * the token registry, preventing incorrect symbol display.
- *
- * @example
- * ```typescript
- * const amount: Amount = {
- *   raw: 1_000_000n,  // 1 token in smallest units (e.g., 1 USDC)
- *   decimals: 6,
- * }
- * ```
- */
-interface Amount$1 {
-    /**
-     * The raw value in smallest units (e.g., wei for ETH, micro-units for USDC).
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.5', { decimals: 6 })
+     * const b = Amount.parse('1.5', { decimals: 6 })
+     * a.lte(b) // true
+     * ```
      */
-    readonly raw: bigint;
+    lte(other: Amount): boolean;
     /**
-     * Number of decimal places for this token.
+     * Check if this Amount is greater than another.
      *
-     * @remarks
-     * Common values:
-     * - USDC/USDT: 6
-     * - ETH/ERC-20: 18
+     * @param other - The Amount to compare with.
+     * @returns True if this.raw is greater than other.raw.
+     * @throws KitError If amounts have different decimals.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('2.0', { decimals: 6 })
+     * const b = Amount.parse('1.0', { decimals: 6 })
+     * a.gt(b) // true
+     * ```
      */
-    readonly decimals: number;
-}
-/**
- * Configuration for creating amounts.
- *
- * @remarks
- * Specifies the decimal precision for the amount. Typically obtained
- * from the token registry.
- */
-interface AmountConfig {
+    gt(other: Amount): boolean;
     /**
-     * Number of decimal places.
+     * Check if this Amount is greater than or equal to another.
+     *
+     * @param other - The Amount to compare with.
+     * @returns True if this.raw is greater than or equal to other.raw.
+     * @throws KitError If amounts have different decimals.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('2.0', { decimals: 6 })
+     * const b = Amount.parse('2.0', { decimals: 6 })
+     * a.gte(b) // true
+     * ```
      */
-    decimals: number;
-}
-/**
- * Options for formatting amounts as human-readable strings.
- */
-interface FormatOptions {
+    gte(other: Amount): boolean;
     /**
-     * Locale for number formatting.
+     * Return the minimum of this Amount and another.
      *
-     * @defaultValue 'en-US'
+     * @param other - The Amount to compare with.
+     * @returns The smaller of the two amounts.
+     * @throws KitError If amounts have different decimals.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.0', { decimals: 6 })
+     * const b = Amount.parse('2.0', { decimals: 6 })
+     * a.min(b).toString() // "1"
+     * ```
      */
-    locale?: string;
+    min(other: Amount): Amount;
     /**
-     * Minimum fraction digits to display.
+     * Return the maximum of this Amount and another.
      *
-     * @defaultValue 0
+     * @param other - The Amount to compare with.
+     * @returns The larger of the two amounts.
+     * @throws KitError If amounts have different decimals.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.0', { decimals: 6 })
+     * const b = Amount.parse('2.0', { decimals: 6 })
+     * a.max(b).toString() // "2"
+     * ```
      */
-    minimumFractionDigits?: number;
+    max(other: Amount): Amount;
     /**
-     * Maximum fraction digits to display.
+     * Add another Amount to this one.
      *
-     * @defaultValue decimals
+     * @param other - The Amount to add.
+     * @returns A new Amount with the sum.
+     * @throws KitError If amounts have different decimals.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.5', { decimals: 6 })
+     * const b = Amount.parse('0.5', { decimals: 6 })
+     * a.add(b).toString() // "2"
+     * ```
      */
-    maximumFractionDigits?: number;
+    add(other: Amount): Amount;
     /**
-     * Use grouping separators (e.g., 1,000,000).
+     * Subtract another Amount from this one.
      *
-     * @defaultValue true
+     * @param other - The Amount to subtract.
+     * @returns A new Amount with the difference.
+     * @throws KitError If amounts have different decimals.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('2.0', { decimals: 6 })
+     * const b = Amount.parse('0.5', { decimals: 6 })
+     * a.sub(b).toString() // "1.5"
+     * ```
      */
-    useGrouping?: boolean;
-}
-/**
- * Options for parsing human-readable strings to amounts.
- *
- * @remarks
- * Currently only supports '.' as the decimal separator (en-US style).
- */
-interface ParseOptions {
+    sub(other: Amount): Amount;
     /**
-     * Number of decimal places.
+     * Multiply this Amount by a scalar.
+     *
+     * @param multiplier - The scalar to multiply by (bigint or integer number).
+     * @returns A new Amount with the product.
+     *
+     * @remarks
+     * When using a `number` as a multiplier, precision is limited by standard
+     * JavaScript floating-point capabilities (~15-17 significant digits). For
+     * high-precision calculations, provide the multiplier as a `bigint`.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('1.5', { decimals: 6 })
+     * a.mul(2n).toString() // "3"
+     * a.mul(3).toString()  // "4.5"
+     * ```
      */
-    decimals: number;
+    mul(multiplier: bigint | number): Amount;
     /**
-     * Whether to allow negative values.
+     * Divide this Amount by a scalar.
      *
-     * @defaultValue false
+     * @param divisor - The scalar to divide by (bigint or integer number).
+     * @returns A new Amount with the quotient (integer division).
+     * @throws KitError If divisor is zero.
+     *
+     * @remarks
+     * When using a `number` as a divisor, precision is limited by standard
+     * JavaScript floating-point capabilities (~15-17 significant digits). For
+     * high-precision calculations, provide the divisor as a `bigint`.
+     *
+     * @example
+     * ```typescript
+     * const a = Amount.parse('6.0', { decimals: 6 })
+     * a.div(2n).toString() // "3"
+     * a.div(4).toString()  // "1.5"
+     * ```
      */
-    allowNegative?: boolean;
-}
-/**
- * Result of comparing two amounts.
- */
-type ComparisonResult = -1 | 0 | 1;
-/**
- * Types that can be converted to an Amount.
- *
- * @remarks
- * - `bigint`: Raw value (requires config with decimals)
- * - `string`: Human-readable (e.g., "100.50")
- * - `number`: Human-readable (e.g., 100.5) - beware of precision!
- * - `Amount`: Existing amount or plain object with Amount shape
- */
-type AmountLike = bigint | string | number | Amount$1;
-/**
- * JSON representation of an Amount.
- *
- * @remarks
- * Used for serialization. The `raw` value is stringified since JSON
- * does not support bigint natively.
- *
- * @example
- * ```typescript
- * const json: AmountJSON = {
- *   raw: "1500000",
- *   decimals: 6,
- *   formatted: "1.5"
- * }
- * ```
- */
-interface AmountJSON {
-    /** The raw value as a string (bigint serialized). */
-    raw: string;
-    /** Number of decimal places. */
-    decimals: number;
-    /** Human-readable formatted value. */
-    formatted: string;
-}
-
-/**
- * Minimal fields required for internal Amount operations.
- *
- * @remarks
- * This internal type mirrors the public {@link Amount} interface shape but exists
- * separately to avoid circular dependencies. Internal modules (math, comparison,
- * formatting) import this lightweight type instead of the full Amount class.
- *
- * The Amount class implements this interface, so internal helpers can operate
- * on either Amount instances or plain objects with the same shape.
- *
- * @see {@link ../types.ts#Amount} for the public interface
- * @internal
- */
-interface AmountFields {
-    readonly raw: bigint;
-    readonly decimals: number;
-}
-
-/**
- * Fluent Amount class for type-safe token amount handling.
- *
- * @remarks
- * The `Amount` class provides an immutable, fluent API for working with token
- * amounts. It wraps a raw bigint value with decimal precision and provides
- * chainable methods for math, comparison, and formatting.
- *
- * Token identity (symbol, contract address) is intentionally NOT included.
- * This ensures developers explicitly source token metadata from the token
- * registry, preventing incorrect symbol display.
- *
- * @example
- * ```typescript
- * import { Amount } from '@core/amounts'
- *
- * // Create from raw value or parse from string
- * const a = Amount.of(1_000_000n, { decimals: 6 })
- * const b = Amount.parse('0.5', { decimals: 6 })
- *
- * // Fluent operations
- * const result = a.add(b).mul(2n).sub(Amount.parse('0.25', { decimals: 6 }))
- *
- * // Comparisons and formatting
- * a.gt(b)           // true
- * a.toString()      // "1"
- *
- * // For display with symbol, combine with token registry:
- * // `${amount.toString()} ${token.symbol}`
- * ```
- *
- * @packageDocumentation
- */
-
-/**
- * An immutable token amount with fluent API methods.
- *
- * @remarks
- * The `Amount` class provides a type-safe, ergonomic way to work with token
- * amounts. It combines the raw bigint value with decimal precision and
- * provides chainable methods for:
- *
- * - **Math operations**: add, sub, mul, div, abs, neg
- * - **Comparisons**: eq, lt, lte, gt, gte, cmp, min, max
- * - **Predicates**: isZero, isPositive, isNegative
- * - **Formatting**: formatted, toString, toJSON
- * - **Conversion**: toDecimals
- *
- * All operations return new Amount instances - the class is immutable.
- *
- * Token identity (symbol) is intentionally excluded. Source token metadata
- * from the token registry for display purposes.
- */
-declare class Amount implements AmountFields {
-    /** The raw value in smallest units (e.g., wei for ETH, micro-units for USDC). */
-    readonly raw: bigint;
-    /** Number of decimal places for this token. */
-    readonly decimals: number;
-    private constructor();
+    div(divisor: bigint | number): Amount;
     /**
-     * Create an Amount from a raw bigint value.
+     * Get the absolute value of this Amount.
      *
-     * @param raw - The raw value in smallest units.
-     * @param config - Configuration with decimals.
-     * @returns A new immutable Amount instance.
-     * @throws KitError If raw is not a bigint or decimals is invalid.
+     * @returns A new Amount with the absolute value.
      *
      * @example
      * ```typescript
-     * // Get decimals from token registry
-     * const amount = Amount.of(1_000_000n, { decimals: 6 })
+     * const a = Amount.of(-1_500_000n, { decimals: 6 })
+     * a.abs().toString() // "1.5"
      * ```
      */
-    static of(raw: bigint, config: AmountConfig): Amount;
+    abs(): Amount;
     /**
-     * Parse a human-readable string or number into an Amount.
+     * Negate this Amount.
      *
-     * @param input - The input to parse (e.g., "100.50" or 100.5).
-     * @param options - Parse options including decimals.
-     * @returns A new immutable Amount instance.
-     * @throws KitError If input is invalid or parsing fails.
+     * @returns A new Amount with the negated value.
      *
      * @example
      * ```typescript
-     * const amount = Amount.parse('100.50', { decimals: 6 })
+     * const a = Amount.parse('1.5', { decimals: 6 })
+     * a.neg().raw // -1_500_000n
      * ```
      */
-    static parse(input: string | number, options: ParseOptions): Amount;
+    neg(): Amount;
     /**
-     * Convert any AmountLike value to an Amount.
-     *
-     * @param input - The input (bigint, string, number, or existing Amount).
-     * @param config - Configuration (required for non-Amount inputs).
-     * @returns A new immutable Amount instance.
-     * @throws KitError If conversion fails or config is missing.
+     * Check if this Amount is zero.
      *
-     * @remarks
-     * When providing a `number` input, very large or small values may be
-     * converted to exponential notation (e.g., `1e21`), which is not supported.
-     * For such values, provide a `string` representation instead.
+     * @returns True if the raw value is 0n.
      *
      * @example
      * ```typescript
-     * Amount.from(1_000_000n, { decimals: 6 })  // from bigint
-     * Amount.from('1.00', { decimals: 6 })      // from string
-     * Amount.from(existingAmount)               // pass-through
+     * Amount.zero({ decimals: 6 }).isZero() // true
+     * Amount.parse('0.001', { decimals: 6 }).isZero() // false
      * ```
      */
-    static from(input: AmountLike, config?: AmountConfig): Amount;
+    isZero(): boolean;
     /**
-     * Create a zero Amount with the given configuration.
+     * Check if this Amount is positive.
      *
-     * @param config - Configuration with decimals.
-     * @returns A zero Amount instance.
+     * @returns True if the raw value is greater than 0n.
      *
      * @example
      * ```typescript
-     * const zero = Amount.zero({ decimals: 6 })
+     * Amount.parse('1.0', { decimals: 6 }).isPositive() // true
+     * Amount.zero({ decimals: 6 }).isPositive() // false
      * ```
      */
-    static zero(config: AmountConfig): Amount;
+    isPositive(): boolean;
     /**
-     * Check if a value is an Amount-like object.
+     * Check if this Amount is negative.
      *
-     * @param value - The value to check.
-     * @returns True if the value has Amount shape (raw: bigint, decimals: number).
+     * @returns True if the raw value is less than 0n.
      *
      * @example
      * ```typescript
-     * Amount.isAmount({ raw: 1000000n, decimals: 6 }) // true
-     * Amount.isAmount({ value: 100 })                 // false
+     * Amount.of(-1_000_000n, { decimals: 6 }).isNegative() // true
+     * Amount.parse('1.0', { decimals: 6 }).isNegative() // false
      * ```
      */
-    static isAmount(value: unknown): value is {
-        raw: bigint;
-        decimals: number;
-    };
+    isNegative(): boolean;
     /**
-     * Sum an array of Amounts.
+     * Convert this Amount to a different decimal precision.
      *
-     * @param amounts - The amounts to sum (must have same decimals).
-     * @returns A new Amount with the total sum.
-     * @throws KitError If amounts array is empty or decimals don't match.
+     * @param newDecimals - The target number of decimal places.
+     * @returns A new Amount with adjusted precision (or this if same precision).
+     * @throws KitError If newDecimals is invalid.
      *
      * @example
      * ```typescript
-     * const fee1 = Amount.parse('0.10', { decimals: 6 })
-     * const fee2 = Amount.parse('0.25', { decimals: 6 })
-     * const fee3 = Amount.parse('0.15', { decimals: 6 })
+     * // Scale up: 6 decimals → 18 decimals
+     * const usdc = Amount.parse('1.5', { decimals: 6 })
+     * const scaled = usdc.toDecimals(18)
+     * scaled.raw // 1_500_000_000_000_000_000n
      *
-     * const total = Amount.sum([fee1, fee2, fee3])
-     * total.toString() // "0.5"
+     * // Scale down: 18 decimals → 6 decimals (truncates)
+     * const eth = Amount.of(1_500_000_000_000_000_000n, { decimals: 18 })
+     * eth.toDecimals(6).raw // 1_500_000n
      * ```
      */
-    static sum(amounts: readonly Amount[]): Amount;
+    toDecimals(newDecimals: number): Amount;
     /**
-     * Deserialize an Amount from a JSON object.
+     * Format this Amount as a human-readable string.
      *
-     * @param json - The JSON object (e.g., from `JSON.parse()`).
-     * @returns A new Amount instance.
-     * @throws KitError If the JSON structure is invalid.
+     * @param options - Formatting options (locale, fraction digits, grouping).
+     * @returns A formatted string (e.g., "1,000.50").
      *
      * @example
      * ```typescript
-     * const json = JSON.parse('{"raw":"1500000","decimals":6}')
-     * const amount = Amount.fromJSON(json)
+     * const a = Amount.parse('1000.5', { decimals: 6 })
+     * a.formatted()                              // "1,000.5"
+     * a.formatted({ minimumFractionDigits: 2 }) // "1,000.50"
+     * a.formatted({ useGrouping: false })       // "1000.5"
      * ```
      */
-    static fromJSON(json: unknown): Amount;
+    formatted(options?: FormatOptions): string;
     /**
-     * Compare this Amount with another.
+     * Convert to a human-readable string.
      *
-     * @param other - The Amount to compare with.
-     * @returns -1 if this is less than other, 0 if equal, 1 if this is greater.
-     * @throws KitError If amounts have different decimals.
+     * @returns A formatted string like "1.5".
+     *
+     * @remarks
+     * For display with a token symbol, combine with the token registry:
+     * ```typescript
+     * `${amount.toString()} ${token.symbol}`
+     * ```
      *
      * @example
      * ```typescript
      * const a = Amount.parse('1.5', { decimals: 6 })
-     * const b = Amount.parse('2.0', { decimals: 6 })
-     * a.compare(b) // -1
+     * a.toString() // "1.5"
      * ```
      */
-    compare(other: Amount): ComparisonResult;
+    toString(): string;
     /**
-     * Check if this Amount equals another.
+     * Convert to a JSON-serializable object.
      *
-     * @param other - The Amount to compare with.
-     * @returns True if the raw values are equal.
-     * @throws KitError If amounts have different decimals.
+     * @returns An object with raw (as string), decimals, and formatted value.
      *
      * @example
      * ```typescript
      * const a = Amount.parse('1.5', { decimals: 6 })
-     * const b = Amount.parse('1.5', { decimals: 6 })
-     * a.eq(b) // true
+     * a.toJSON()
+     * // { raw: "1500000", decimals: 6, formatted: "1.5" }
      * ```
      */
-    eq(other: Amount): boolean;
+    toJSON(): AmountJSON;
+}
+
+/**
+ * Transfer speed options for cross-chain operations.
+ *
+ * Defines the available speed modes for CCTPv2 transfers, affecting
+ * both transfer time and potential fee implications.
+ */
+declare enum TransferSpeed {
+    /** Fast burn mode - reduces transfer time but may have different fee implications */
+    FAST = "FAST",
+    /** Standard burn mode - normal transfer time with standard fees */
+    SLOW = "SLOW"
+}
+/**
+ * Context object representing a wallet and signing authority on a specific blockchain network.
+ *
+ * Combines a wallet or contract address, the blockchain it resides on, and the adapter (signer)
+ * responsible for authorizing transactions. Used to specify the source or destination in cross-chain
+ * transfer operations.
+ *
+ * @remarks
+ * The `adapter` (signer) and `address` do not always have to belong to the same entity. For example,
+ * in minting or withdrawal scenarios, the signing adapter may authorize a transaction that credits
+ * funds to a different recipient address. This context is essential for cross-chain operations,
+ * ensuring that both the address and the associated adapter are correctly paired with the intended
+ * blockchain, but not necessarily with each other.
+ *
+ * @example
+ * ```typescript
+ * import type { WalletContext } from '@core/provider'
+ * import { adapter, blockchain } from './setup'
+ *
+ * const wallet: WalletContext = {
+ *   adapter,
+ *   address: '0x1234...abcd',
+ *   chain: blockchain,
+ * }
+ * ```
+ */
+interface WalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> {
     /**
-     * Check if this Amount is less than another.
-     *
-     * @param other - The Amount to compare with.
-     * @returns True if this.raw is less than other.raw.
-     * @throws KitError If amounts have different decimals.
+     * The adapter (signer) for the wallet on the specified chain.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.0', { decimals: 6 })
-     * const b = Amount.parse('2.0', { decimals: 6 })
-     * a.lt(b) // true
-     * ```
+     * Responsible for authorizing transactions and signing messages on behalf of the wallet or
+     * for a different recipient, depending on the use case.
      */
-    lt(other: Amount): boolean;
+    adapter: Adapter<TAdapterCapabilities>;
     /**
-     * Check if this Amount is less than or equal to another.
+     * The wallet or contract address.
      *
-     * @param other - The Amount to compare with.
-     * @returns True if this.raw is less than or equal to other.raw.
-     * @throws KitError If amounts have different decimals.
+     * Must be a valid address format for the specified blockchain. May differ from the adapter's
+     * own address in scenarios such as relayed transactions or third-party minting.
+     */
+    address: string;
+    /**
+     * The blockchain network where the wallet or contract address resides.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.5', { decimals: 6 })
-     * const b = Amount.parse('1.5', { decimals: 6 })
-     * a.lte(b) // true
-     * ```
+     * Determines the context and format for the address and adapter.
      */
-    lte(other: Amount): boolean;
+    chain: TChainDefinition;
+}
+/**
+ * Wallet context for bridge destinations with optional custom recipient.
+ *
+ * Extends WalletContext to support scenarios where the recipient address
+ * differs from the signer address (e.g., bridging to a third-party wallet).
+ * The signer address is used for transaction authorization, while the
+ * recipient address specifies where the minted funds should be sent.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type to use for the wallet context.
+ * @typeParam TChainDefinition - The chain definition type to use for the wallet context.
+ *
+ * @example
+ * ```typescript
+ * import type { DestinationWalletContext } from '@core/provider'
+ * import { adapter, blockchain } from './setup'
+ *
+ * // Bridge to a custom recipient address
+ * const destination: DestinationWalletContext = {
+ *   adapter,
+ *   address: '0x1234...abcd', // Signer address
+ *   chain: blockchain,
+ *   recipientAddress: '0x9876...fedc' // Custom recipient
+ * }
+ * ```
+ */
+interface DestinationWalletContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition> extends WalletContext<TAdapterCapabilities, TChainDefinition> {
     /**
-     * Check if this Amount is greater than another.
+     * Optional custom recipient address for minted funds.
      *
-     * @param other - The Amount to compare with.
-     * @returns True if this.raw is greater than other.raw.
-     * @throws KitError If amounts have different decimals.
+     * When provided, minted tokens will be sent to this address instead of
+     * the address specified in the wallet context. The wallet context address
+     * is still used for transaction signing and authorization.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('2.0', { decimals: 6 })
-     * const b = Amount.parse('1.0', { decimals: 6 })
-     * a.gt(b) // true
-     * ```
+     * Must be a valid address format for the specified blockchain.
      */
-    gt(other: Amount): boolean;
+    recipientAddress?: string;
     /**
-     * Check if this Amount is greater than or equal to another.
-     *
-     * @param other - The Amount to compare with.
-     * @returns True if this.raw is greater than or equal to other.raw.
-     * @throws KitError If amounts have different decimals.
+     * Whether Circle's relayer submits the destination transaction.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('2.0', { decimals: 6 })
-     * const b = Amount.parse('2.0', { decimals: 6 })
-     * a.gte(b) // true
-     * ```
+     * How an omitted value resolves, and whether an explicit `false` is accepted,
+     * is provider-specific.
      */
-    gte(other: Amount): boolean;
+    useForwarder?: boolean;
     /**
-     * Return the minimum of this Amount and another.
+     * Optional destination dApp deposit action for a fast cross-chain transfer.
      *
-     * @param other - The Amount to compare with.
-     * @returns The smaller of the two amounts.
-     * @throws KitError If amounts have different decimals.
+     * 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`.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.0', { decimals: 6 })
-     * const b = Amount.parse('2.0', { decimals: 6 })
-     * a.min(b).toString() // "1"
-     * ```
+     * @see {@link BridgeDepositAction}
      */
-    min(other: Amount): Amount;
+    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.
+ */
+interface BridgeParams$1<TFromCapabilities extends AdapterCapabilities = AdapterCapabilities, TToCapabilities extends AdapterCapabilities = AdapterCapabilities, 
+/**
+ * The chain definition type to use for the wallet context.
+ *
+ * @defaultValue ChainDefinition
+ */
+TChainDefinition extends ChainDefinition = ChainDefinition, 
+/**
+ * The token type the provider accepts.
+ *
+ * @defaultValue 'USDC'
+ *
+ * @remarks
+ * The default preserves the original USDC-only contract for consumers that
+ * omit the token type. Providers that accept a different token type pass
+ * `TToken` explicitly.
+ *
+ * @example
+ * ```typescript
+ * // Default — TToken resolves to 'USDC'
+ * type DefaultParams = BridgeParams // params.token is typed as 'USDC'
+ *
+ * // Provider that identifies tokens by a hex string template literal
+ * type HexTokenParams = BridgeParams<
+ *   AdapterCapabilities,
+ *   AdapterCapabilities,
+ *   ChainDefinition,
+ *   `0x${string}`
+ * > // params.token is typed as `0x${string}`
+ * ```
+ */
+TToken extends string = 'USDC'> {
+    /** The source adapter containing wallet and chain information */
+    source: WalletContext<TFromCapabilities, TChainDefinition>;
+    /** The destination adapter containing wallet and chain information */
+    destination: DestinationWalletContext<TToCapabilities, TChainDefinition>;
+    /** The amount to transfer (as a string to avoid precision issues) */
+    amount: string;
+    /** The token to transfer (provider-defined; defaults to `'USDC'`) */
+    token: TToken;
+    /** Bridge configuration (e.g., fast burn settings) */
+    config: BridgeConfig;
     /**
-     * Return the maximum of this Amount and another.
-     *
-     * @param other - The Amount to compare with.
-     * @returns The larger of the two amounts.
-     * @throws KitError If amounts have different decimals.
+     * Optional server-signed quote to reuse, typically the
+     * {@link EstimateResult.quote} returned by an earlier `estimate` call.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.0', { decimals: 6 })
-     * const b = Amount.parse('2.0', { decimals: 6 })
-     * a.max(b).toString() // "2"
-     * ```
-     */
-    max(other: Amount): Amount;
-    /**
-     * Add another Amount to this one.
+     * When present and still valid, a provider with a server-signed quote
+     * model may reuse it instead of fetching a fresh quote, so the fee the
+     * caller was quoted is the fee they pay. Providers decide when a reused
+     * quote is still valid (e.g. freshness, fee token, speed); an unusable or
+     * mismatched quote is ignored and a fresh one is fetched. Transfer
+     * parameters are validated by the provider's on-chain contract, so a quote
+     * reused for a different transfer is rejected there rather than silently.
+     * Providers without a quote model ignore this field entirely, and do so
+     * silently — nothing verifies that a quote reached the provider that issued
+     * it, because the route is matched to a provider only after these
+     * parameters are validated. A quote is meaningful only on the route that
+     * produced it.
      *
-     * @param other - The Amount to add.
-     * @returns A new Amount with the sum.
-     * @throws KitError If amounts have different decimals.
+     * Typed `unknown`: a caller reaches `bridge` through a provider-agnostic
+     * surface, so this shared type names no provider's shape. It is public
+     * input in any case, and is validated before any field is read — by the
+     * provider that serves the route, or by the kit for routes it prices
+     * itself. Treat it as opaque and pass it back unmodified.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.5', { decimals: 6 })
-     * const b = Amount.parse('0.5', { decimals: 6 })
-     * a.add(b).toString() // "2"
-     * ```
+     * This is a `bridge` input. A quote is an output of `estimate`, not an
+     * input to it — `estimate` always returns a freshly-priced quote, and a
+     * provider may reject a quote passed to `estimate` rather than ignore it.
      */
-    add(other: Amount): Amount;
+    quote?: unknown;
     /**
-     * Subtract another Amount from this one.
-     *
-     * @param other - The Amount to subtract.
-     * @returns A new Amount with the difference.
-     * @throws KitError If amounts have different decimals.
+     * Optional invocation metadata for tracing and correlation.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('2.0', { decimals: 6 })
-     * const b = Amount.parse('0.5', { decimals: 6 })
-     * a.sub(b).toString() // "1.5"
-     * ```
+     * When provided, the `traceId` is used to correlate all events emitted during
+     * the bridge operation. If not provided, an OpenTelemetry-compatible traceId
+     * will be auto-generated.
      */
-    sub(other: Amount): Amount;
+    invocationMeta?: InvocationMeta;
+}
+/**
+ * Configuration options for customizing bridge behavior.
+ *
+ * @remarks
+ * This interface is currently incomplete and will be expanded in future versions
+ * to include additional configuration options such as slippage tolerance,
+ * deadline settings, and other bridge parameters.
+ *
+ */
+interface BridgeConfig {
     /**
-     * Multiply this Amount by a scalar.
-     *
-     * @param multiplier - The scalar to multiply by (bigint or integer number).
-     * @returns A new Amount with the product.
+     * The transfer speed mode for CCTPv2 transfers.
      *
-     * @remarks
-     * When using a `number` as a multiplier, precision is limited by standard
-     * JavaScript floating-point capabilities (~15-17 significant digits). For
-     * high-precision calculations, provide the multiplier as a `bigint`.
+     * Controls whether to use fast burn mode (FAST) or standard mode (SLOW).
+     * Fast burn may reduce transfer time but could have different fee implications.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.5', { decimals: 6 })
-     * a.mul(2n).toString() // "3"
-     * a.mul(3).toString()  // "4.5"
-     * ```
+     * @defaultValue TransferSpeed.FAST
      */
-    mul(multiplier: bigint | number): Amount;
+    transferSpeed?: TransferSpeed | `${TransferSpeed}` | undefined;
     /**
-     * Divide this Amount by a scalar.
+     * Enable or disable EIP-5792 batched transaction execution.
      *
-     * @param divisor - The scalar to divide by (bigint or integer number).
-     * @returns A new Amount with the quotient (integer division).
-     * @throws KitError If divisor is zero.
+     * When `true` (or `undefined` / omitted), the bridge will attempt to batch
+     * the approve and burn calls into a single `wallet_sendCalls` request if
+     * the connected wallet supports it. Set to `false` to explicitly opt out
+     * and always use the sequential approve -> burn flow.
      *
-     * @remarks
-     * When using a `number` as a divisor, precision is limited by standard
-     * JavaScript floating-point capabilities (~15-17 significant digits). For
-     * high-precision calculations, provide the divisor as a `bigint`.
+     * @defaultValue `undefined` (batching attempted when the wallet supports it)
      *
      * @example
      * ```typescript
-     * const a = Amount.parse('6.0', { decimals: 6 })
-     * a.div(2n).toString() // "3"
-     * a.div(4).toString()  // "1.5"
+     * const config: BridgeConfig = {
+     *   batchTransactions: false, // force sequential flow
+     * }
      * ```
      */
-    div(divisor: bigint | number): Amount;
+    batchTransactions?: boolean | undefined;
     /**
-     * Get the absolute value of this Amount.
-     *
-     * @returns A new Amount with the absolute value.
+     * The maximum fee to pay for the burn operation.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.of(-1_500_000n, { decimals: 6 })
-     * a.abs().toString() // "1.5"
-     * ```
-     */
-    abs(): Amount;
-    /**
-     * Negate this Amount.
+     * Provide the amount as a base-10 numeric string representing the
+     * token amount in human-readable format. For example: to set a maximum
+     * fee of 1 USDC, pass `"1"`. Decimal values are supported (e.g., `"0.5"`
+     * for half a USDC).
      *
-     * @returns A new Amount with the negated value.
+     * @defaultValue `"0"`
      *
      * @example
      * ```typescript
-     * const a = Amount.parse('1.5', { decimals: 6 })
-     * a.neg().raw // -1_500_000n
+     * import type { BridgeConfig, TransferSpeed } from '@core/provider'
+     *
+     * const config: BridgeConfig = {
+     *   transferSpeed: TransferSpeed.FAST,
+     *   maxFee: "1", // 1 USDC maximum fee
+     *   customFee: {
+     *     value: "0.5", // 0.5 USDC developer fee
+     *     recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
+     *   }
+     * }
      * ```
      */
-    neg(): Amount;
+    maxFee?: string;
     /**
-     * Check if this Amount is zero.
+     * The custom fee to charge for the transfer.
      *
-     * @returns True if the raw value is 0n.
+     * Whatever value you provide here is **added on top of the transfer amount**. The user must have
+     * enough balance for `amount + customFee`, and the wallet signs for that total on the source
+     * chain. The custom fee is split automatically:
      *
-     * @example
-     * ```typescript
-     * Amount.zero({ decimals: 6 }).isZero() // true
-     * Amount.parse('0.001', { decimals: 6 }).isZero() // false
-     * ```
-     */
-    isZero(): boolean;
-    /**
-     * Check if this Amount is positive.
+     * - 10% routes to Circle.
+     * - 90% routes to your `recipientAddress`.
      *
-     * @returns True if the raw value is greater than 0n.
+     * The original transfer amount proceeds through CCTPv2 unchanged, and the protocol fee (1–14 bps
+     * in FAST mode, 0% in STANDARD) is taken from that transfer amount.
      *
      * @example
      * ```typescript
-     * Amount.parse('1.0', { decimals: 6 }).isPositive() // true
-     * Amount.zero({ decimals: 6 }).isPositive() // false
-     * ```
-     */
-    isPositive(): boolean;
-    /**
-     * Check if this Amount is negative.
+     * import type { BridgeConfig } from '@core/provider'
      *
-     * @returns True if the raw value is less than 0n.
+     * const config: BridgeConfig = {
+     *   customFee: {
+     *     value: '5', // 5 USDC developer fee
+     *     recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+     *   },
+     * }
      *
-     * @example
-     * ```typescript
-     * Amount.of(-1_000_000n, { decimals: 6 }).isNegative() // true
-     * Amount.parse('1.0', { decimals: 6 }).isNegative() // false
+     * // Fee flow for a 100 USDC transfer with 5 USDC custom fee:
+     * // Source chain (Ethereum):
+     * // - Wallet debits: 105 USDC total (100 transfer + 5 custom fee)
+     * // - Custom fee split: 0.5 USDC (10%) → Circle, 4.5 USDC (90%) → your recipientAddress
+     * // - Amount sent to CCTPv2: 100 USDC (unchanged)
+     * //
+     * // Destination chain (Base):
+     * // - CCTPv2 FAST fee (example: 1 bps): ~0.01 USDC deducted
+     * // - User receives: ~99.99 USDC
+     * //
+     * // Note: Actual CCTP fees vary by route (1-14 bps for FAST, 0 bps for STANDARD)
      * ```
      */
-    isNegative(): boolean;
+    customFee?: CustomFee | undefined;
     /**
-     * Convert this Amount to a different decimal precision.
-     *
-     * @param newDecimals - The target number of decimal places.
-     * @returns A new Amount with adjusted precision (or this if same precision).
-     * @throws KitError If newDecimals is invalid.
-     *
-     * @example
-     * ```typescript
-     * // Scale up: 6 decimals → 18 decimals
-     * const usdc = Amount.parse('1.5', { decimals: 6 })
-     * const scaled = usdc.toDecimals(18)
-     * scaled.raw // 1_500_000_000_000_000_000n
+     * Which leg pays the protocol fee.
      *
-     * // Scale down: 18 decimals → 6 decimals (truncates)
-     * const eth = Amount.of(1_500_000_000_000_000_000n, { decimals: 18 })
-     * eth.toDecimals(6).raw // 1_500_000n
-     * ```
+     * `'source'` leaves the delivered amount unreduced; `'destination'` takes the
+     * fee from it. Omit it to let the routed provider decide — a provider rejects
+     * a value it cannot honour.
      */
-    toDecimals(newDecimals: number): Amount;
+    feePayment?: 'source' | 'destination' | undefined;
+}
+/**
+ * Custom fee configuration charged by the integrator.
+ *
+ * Use to charge an absolute fee on the source chain in human-readable
+ * token amounts.
+ *
+ * @remarks
+ * This is an absolute amount, not a percentage. The `recipientAddress` must be
+ * a valid address for the source chain of the transfer.
+ *
+ * @example
+ * ```typescript
+ * import type { CustomFee } from '@core/provider'
+ *
+ * const config: CustomFee = {
+ *   value: '1', // 1 USDC
+ *   recipientAddress: '0x1234567890123456789012345678901234567890',
+ * }
+ * ```
+ */
+interface CustomFee {
     /**
-     * Format this Amount as a human-readable string.
+     * The absolute fee to charge for the transfer.
      *
-     * @param options - Formatting options (locale, fraction digits, grouping).
-     * @returns A formatted string (e.g., "1,000.50").
+     * Provide the amount as a base-10 numeric string representing the token
+     * amount in human-readable format. For example: to charge 1 USDC, pass
+     * `"1"`. Decimal values are supported (e.g., `"0.5"` for half a USDC).
+     * This is not a percentage.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1000.5', { decimals: 6 })
-     * a.formatted()                              // "1,000.5"
-     * a.formatted({ minimumFractionDigits: 2 }) // "1,000.50"
-     * a.formatted({ useGrouping: false })       // "1000.5"
-     * ```
+     * Note: passing `"0"` results in no fee being charged.
      */
-    formatted(options?: FormatOptions): string;
+    value?: string | undefined;
     /**
-     * Convert to a human-readable string.
+     * The fee recipient for the bridge transfer.
      *
-     * @returns A formatted string like "1.5".
+     * This is the address that will receive the fee on the source chain of the
+     * bridge transfer. The fee recipient address **must be a valid address for
+     * the source chain** of the bridge transfer.
      *
      * @remarks
-     * For display with a token symbol, combine with the token registry:
-     * ```typescript
-     * `${amount.toString()} ${token.symbol}`
-     * ```
+     * Circle automatically receives 10% of every custom fee; the remaining 90% is
+     * sent to this `recipientAddress`.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.5', { decimals: 6 })
-     * a.toString() // "1.5"
-     * ```
+     * For example: if bridging from Ethereum to Solana, pass an EVM address like
+     * `"0x1234567890123456789012345678901234567890"` because the source chain
+     * is Ethereum.
      */
-    toString(): string;
+    recipientAddress?: string | undefined;
+}
+/**
+ * Represents the context of an adapter used for cross-chain operations.
+ *
+ * An AdapterContext must always specify both the adapter and the chain explicitly.
+ * The address field behavior is determined by the adapter's address control model:
+ *
+ * - **Developer-controlled adapters**: The `address` field is required because
+ *   each operation must explicitly specify which address to use.
+ * - **User-controlled adapters**: The `address` field is forbidden because
+ *   the address is automatically resolved from the connected wallet or signer.
+ * - **Legacy adapters**: The `address` field remains optional for backward compatibility.
+ *
+ * This ensures clear, debuggable code where the intended chain is always visible at the call site,
+ * and address requirements are enforced at compile time based on adapter capabilities.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type to derive address requirements from
+ * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
+ *
+ * @example
+ * ```typescript
+ * // Developer-controlled adapter (address required)
+ * const devContext: AdapterContext<{ addressContext: 'developer-controlled', supportedChains: [] }> = {
+ *   adapter: myDevAdapter,
+ *   chain: 'Ethereum',
+ *   address: '0x123...' // Required
+ * }
+ *
+ * // User-controlled adapter (address forbidden)
+ * const userContext: AdapterContext<{ addressContext: 'user-controlled', supportedChains: [] }> = {
+ *   adapter: myUserAdapter,
+ *   chain: 'Ethereum'
+ *   // address: '0x123...' // TypeScript error: not allowed
+ * }
+ * ```
+ */
+type AdapterContext<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> = {
+    /** The adapter instance for blockchain operations */
+    adapter: Adapter<TAdapterCapabilities>;
+    /** The chain reference, which can be a ChainDefinition, Blockchain enum, or string literal */
+    chain: TChainIdentifier;
+} & AddressField<ExtractAddressContext<TAdapterCapabilities>>;
+/**
+ * Represents a bridge destination with an explicit custom recipient address.
+ *
+ * Extends {@link AdapterContext} with an additional `recipientAddress` field to specify
+ * a custom recipient that differs from the adapter's address. Use this when bridging to
+ * third-party wallets or smart contracts rather than the default address associated with
+ * the destination adapter.
+ *
+ * @typeParam TCapabilities - The adapter capabilities type for the destination adapter
+ * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
+ *
+ * @remarks
+ * The `recipientAddress` must be a valid address format for the destination chain
+ * specified in the adapter context. The bridge provider validates address compatibility
+ * during the transfer preparation phase and will throw an error if the address format
+ * is invalid for the target chain.
+ *
+ * @example
+ * ```typescript
+ * import { BridgeDestinationWithAddress } from '@core/provider'
+ * import { ethereumAdapter } from './adapters'
+ *
+ * // Bridge to a custom recipient address on Ethereum
+ * const destination: BridgeDestinationWithAddress = {
+ *   adapter: ethereumAdapter,
+ *   chain: 'Ethereum',
+ *   recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0'
+ * }
+ * ```
+ */
+type BridgeDestinationWithAddress<TCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> = AdapterContext<TCapabilities, TChainIdentifier> & {
     /**
-     * Convert to a JSON-serializable object.
+     * The custom recipient address on the destination chain.
      *
-     * @returns An object with raw (as string), decimals, and formatted value.
+     * Must be a valid address format for the chain specified in this adapter context.
+     * This address will receive the bridged funds instead of the adapter's default address.
+     */
+    recipientAddress: string;
+};
+/**
+ * Forwarder-only destination without an adapter.
+ *
+ * Used when Circle's Forwarder handles the mint transaction and no destination
+ * adapter is available. Requires both `useForwarder: true` and a `recipientAddress`.
+ *
+ * When using this destination type:
+ * - The mint step completes when the IRIS API confirms `forwardState === 'CONFIRMED'`
+ * - No on-chain transaction confirmation is performed (no adapter available)
+ * - The mint step's `data` field will be undefined (no transaction receipt)
+ *
+ * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
+ *
+ * @example
+ * ```typescript
+ * // Forwarder-only destination (no adapter needed)
+ * const dest: ForwarderDestination = {
+ *   chain: 'Base',
+ *   recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+ *   useForwarder: true
+ * }
+ * ```
+ */
+interface ForwarderDestination<TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> {
+    /** The destination chain where USDC will be minted */
+    chain: TChainIdentifier;
+    /** The recipient address that will receive the minted USDC */
+    recipientAddress: string;
+    /** Must be true for forwarder-only destinations */
+    useForwarder: true;
+}
+/**
+ * Union type representing a bridge destination.
+ *
+ * Supports multiple destination configurations:
+ * - {@link AdapterContext}: Standard destination with adapter (for default recipient)
+ * - {@link BridgeDestinationWithAddress}: Destination with adapter and custom recipient
+ * - {@link ForwarderDestination}: Forwarder-only destination without adapter (requires recipientAddress)
+ *
+ * When `useForwarder` is enabled with an adapter, Circle's Orbit relayer handles the mint
+ * transaction and the adapter is used to wait for transaction confirmation.
+ *
+ * When `useForwarder` is enabled without an adapter (ForwarderDestination), the mint step
+ * completes when the IRIS API confirms `forwardState === 'CONFIRMED'` without on-chain
+ * confirmation.
+ *
+ * @typeParam TAdapterCapabilities - The adapter capabilities type for the destination adapter
+ * @typeParam TChainIdentifier - The chain identifier type constraint (defaults to ChainIdentifier)
+ *
+ * @example
+ * ```typescript
+ * // Standard destination with adapter
+ * const dest1: BridgeDestination = { adapter, chain: 'Base' }
+ *
+ * // Destination with adapter and custom recipient
+ * const dest2: BridgeDestination = { adapter, chain: 'Base', recipientAddress: '0x...' }
+ *
+ * // Destination with forwarder enabled (adapter for tx confirmation)
+ * const dest3: BridgeDestination = { adapter, chain: 'Base', useForwarder: true }
+ *
+ * // Forwarder-only destination (no adapter, requires recipientAddress)
+ * const dest4: BridgeDestination = { chain: 'Base', useForwarder: true, recipientAddress: '0x...' }
+ * ```
+ */
+type BridgeDestination<TAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities, TChainIdentifier extends ChainIdentifier$1 = ChainIdentifier$1> = ((AdapterContext<TAdapterCapabilities, TChainIdentifier> | BridgeDestinationWithAddress<TAdapterCapabilities, TChainIdentifier>) & {
+    /**
+     * Enable Circle's relayer to submit the destination transaction.
      *
-     * @example
-     * ```typescript
-     * const a = Amount.parse('1.5', { decimals: 6 })
-     * a.toJSON()
-     * // { raw: "1500000", decimals: 6, formatted: "1.5" }
-     * ```
+     * Where the relay fee is charged depends on the route and on
+     * {@link BridgeConfig.feePayment}: it may be taken from the amount that
+     * arrives, or priced into a quote the source transaction pays.
+     *
+     * Whether the option is required, optional, or refused depends on the
+     * routed provider and the rest of the config.
      */
-    toJSON(): AmountJSON;
+    useForwarder?: boolean;
+}) | ForwarderDestination<TChainIdentifier>;
+
+/**
+ * MOVED, not new. Lifted from providers/earn-service/src/validations/, where the
+ * same mapper existed; borrow-service uses it instead of adding a second copy.
+ */
+
+/**
+ * A single claimed (or claimable) reward token amount.
+ *
+ * @example
+ * ```typescript
+ * import type { ClaimedAmount } from '@core/service-client'
+ *
+ * const reward: ClaimedAmount = {
+ *   address: '0x9994E35Db50125E0DF82e4c2dde62496CE330999',
+ *   symbol: 'MORPHO',
+ *   amount: Amount.fromJSON({ raw: '12500000000000000000', decimals: 18 }),
+ * }
+ * ```
+ */
+interface ClaimedAmount$1 {
+    /** Reward token contract address. */
+    readonly address: string;
+    /** Reward token symbol. */
+    readonly symbol: string;
+    /** Claimed (or claimable) amount. */
+    readonly amount: Amount;
+}
+
+/**
+ * MOVED, not new. The claim-rewards result types previously declared
+ * identically in providers/earn-service/src/types.ts and
+ * providers/borrow-service/src/types.ts. Both now re-export from here.
+ */
+/**
+ * Provider-level result types for the claim-rewards contract.
+ *
+ * The claim-rewards contract returns the same shapes to every kit that
+ * consumes it, so these are declared once here rather than per service.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Result returned when no rewards were claimable.
+ *
+ * No transaction is submitted in this case, so there is no hash to report.
+ */
+interface NoClaimableRewardsResult {
+    /** Discriminant: nothing was claimable. */
+    readonly status: 'no_rewards';
+    /** Always empty. */
+    readonly rewards: readonly [];
+}
+/**
+ * Read-only claimable-rewards quote.
+ *
+ * Services may extend this with their own optional fields (e.g. EarnKit
+ * carries an always-empty `gasFees` for symmetry with its other quotes); the
+ * `rewards` list itself is contract-defined and identical everywhere.
+ */
+interface ClaimRewardsQuoteInfo$1 {
+    /** Reward tokens currently available for claiming. */
+    readonly rewards: readonly ClaimedAmount$1[];
 }
 
 /** @internal */
@@ -6872,12 +7011,9 @@ interface CollateralInfo {
      * (e.g., 0.6 = 60%).
      *
      * Populated for Morpho V1 vaults; `null` when the underlying product
-     * exposes no per-market allocation (e.g. Morpho V2). Optional for now — a
-     * backend that predates this field omits it entirely, matching the other
-     * optional facets on {@link EarnOpportunityBase}; a future release makes it
-     * required once every backend emits it.
+     * exposes no per-market allocation (e.g. Morpho V2).
      */
-    readonly allocationPct?: number | null | undefined;
+    readonly allocationPct: number | null;
 }
 /**
  * Vault warning from the underlying earn protocol.
@@ -7047,19 +7183,19 @@ interface EarnOpportunityBase {
     /** Reward tokens distributed by this opportunity. */
     readonly rewards: readonly VaultRewardInfo[];
     /** Primary on-chain address (protocol-neutral; replaces vaultAddress). */
-    readonly address?: string | undefined;
+    readonly address: string;
     /** RFC3339 freshness timestamp: provider state ts, else cache sync time. */
-    readonly asOf?: string | undefined;
+    readonly asOf: string;
     /** Manager/curator identity; `null` when the product has no manager. */
-    readonly manager?: ManagerInfo | null | undefined;
+    readonly manager: ManagerInfo | null;
     /** Yield profile including trailing averages. */
-    readonly apyProfile?: ApyProfile | undefined;
+    readonly apyProfile: ApyProfile;
     /** Fee split. */
-    readonly fee?: FeeInfo | undefined;
+    readonly fee: FeeInfo;
     /** Liquidity profile. */
-    readonly liquidityProfile?: LiquidityProfile | undefined;
+    readonly liquidityProfile: LiquidityProfile;
     /** Risk signals. */
-    readonly riskSignals?: RiskSignals | undefined;
+    readonly riskSignals: RiskSignals;
     /** @deprecated use {@link EarnOpportunityBase.address} */
     readonly vaultAddress: string;
     /** @deprecated use {@link ApyProfile.current} via apyProfile */
@@ -7126,13 +7262,9 @@ interface VaultOpportunity extends EarnOpportunityBase {
     /**
      * Universal discriminator identifying the opportunity shape.
      *
-     * Optional for now — a backend that predates the field omits it, matching
-     * the other optional facets — so this release stays source-compatible for
-     * code that constructs the type. A future release makes it required once
-     * every backend emits it. Always present on responses from an emitting
-     * backend; narrow on it before reading product-specific fields.
+     * Narrow on `productType` before reading product-specific fields.
      */
-    readonly productType?: 'vault';
+    readonly productType: 'vault';
     /** Collateral markets backing this vault. */
     readonly collateral: readonly CollateralInfo[];
 }
@@ -7604,20 +7736,19 @@ interface EarnWithdrawResult {
  * Extend {@link AssetAmount} with a required contract address.
  * The former `tokenAddress` field is now `address`, and
  * `amountBaseUnits` / `decimals` are collapsed into `amount`.
+ *
+ * @remarks
+ * This is a distinct type from `@core/service-client`'s `ClaimedAmount`, which
+ * carries only `address`/`symbol`/`amount`. This local, richer type is the one
+ * used throughout this package (`provider/claimRewards/claimRewards.ts`,
+ * `validations/schemas.ts`), by `@circle-fin/earn-kit`, and as the `rewards`
+ * element type of this file's {@link ClaimRewardsResult}; take care to import
+ * the one you actually mean.
  */
 interface ClaimedAmount extends AssetAmount {
     /** Reward token contract address (always present for claimed rewards). */
     readonly address: string;
 }
-/**
- * Result returned when no rewards are claimable.
- */
-interface NoClaimableRewardsResult {
-    /** Discriminates the no-op result where no transaction was submitted. */
-    readonly status: 'no_rewards';
-    /** Empty because there were no rewards to claim. */
-    readonly rewards: readonly [];
-}
 /**
  * Fields shared by both {@link EarnGasFeeEstimate} variants.
  *
@@ -7796,9 +7927,7 @@ interface WithdrawalQuoteInfo {
  * - `amount` — claimable amount as an {@link Amount}
  * - `address` — reward token contract address
  */
-interface ClaimRewardsQuoteInfo {
-    /** Reward tokens available for claiming. */
-    readonly rewards: readonly AssetAmount[];
+interface ClaimRewardsQuoteInfo extends ClaimRewardsQuoteInfo$1 {
     /**
      * Estimated native gas fees for claiming rewards.
      *
@@ -8158,6 +8287,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;
 }
@@ -8488,14 +8623,8 @@ type EarnVaultInfo = DistributiveOmit<EarnOpportunity, 'totalDeposits' | 'liquid
     readonly totalDeposits: string;
     /** Available liquidity in the vault in human-readable decimal format. */
     readonly liquidity: string;
-    /**
-     * Liquidity profile with amounts as human-readable decimal strings.
-     *
-     * Optional during the expand/contract migration window: a backend that
-     * predates the nested facets omits it, so it is absent until the response
-     * carries it.
-     */
-    readonly liquidityProfile?: EarnLiquidityProfile;
+    /** Liquidity profile with amounts as human-readable decimal strings. */
+    readonly liquidityProfile: EarnLiquidityProfile;
 };
 /** Result of a batch vault lookup. */
 type EarnGetVaultsResult = Omit<GetVaultsResult, 'vaults'> & {
@@ -9967,8 +10096,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.
@@ -9987,13 +10116,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
@@ -10003,7 +10132,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