@circle-fin/app-kit 1.8.1 → 1.9.0

package/index.d.ts

@@ -659,6 +659,8 @@ declare enum Blockchain {
     Celo_Alfajores_Testnet = "Celo_Alfajores_Testnet",
     Codex = "Codex",
     Codex_Testnet = "Codex_Testnet",
+    Cronos = "Cronos",
+    Cronos_Testnet = "Cronos_Testnet",
     Edge = "Edge",
     Edge_Testnet = "Edge_Testnet",
     Ethereum = "Ethereum",
@@ -900,6 +902,7 @@ declare enum BridgeChain {
     Avalanche = "Avalanche",
     Base = "Base",
     Codex = "Codex",
+    Cronos = "Cronos",
     Edge = "Edge",
     Ethereum = "Ethereum",
     HyperEVM = "HyperEVM",
@@ -923,6 +926,7 @@ declare enum BridgeChain {
     Avalanche_Fuji = "Avalanche_Fuji",
     Base_Sepolia = "Base_Sepolia",
     Codex_Testnet = "Codex_Testnet",
+    Cronos_Testnet = "Cronos_Testnet",
     Edge_Testnet = "Edge_Testnet",
     Ethereum_Sepolia = "Ethereum_Sepolia",
     HyperEVM_Testnet = "HyperEVM_Testnet",
@@ -1880,6 +1884,94 @@ declare const CodexTestnet: {
     };
 };
 
+/**
+ * Cronos Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */
+declare const Cronos: {
+    readonly type: "evm";
+    readonly chain: Blockchain.Cronos;
+    readonly name: "Cronos";
+    readonly title: "Cronos Mainnet";
+    readonly nativeCurrency: {
+        readonly name: "Cronos";
+        readonly symbol: "CRO";
+        readonly decimals: 18;
+    };
+    readonly chainId: 25;
+    readonly isTestnet: false;
+    readonly explorerUrl: "https://cronoscan.com/tx/{hash}";
+    readonly rpcEndpoints: readonly ["https://evm.cronos.org"];
+    readonly eurcAddress: "0xA6dE01a2d62C6B5f3525d768f34d276652C554c8";
+    readonly usdcAddress: "0x3D7F2C478aAfdB65542BCB44bCeeC05849999d2D";
+    readonly usdtAddress: null;
+    readonly cctp: {
+        readonly domain: 32;
+        readonly contracts: {
+            readonly v2: {
+                readonly type: "split";
+                readonly tokenMessenger: "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d";
+                readonly messageTransmitter: "0x81D40F21F12A8F0E3252Bccb954D722d4c464B64";
+                readonly confirmations: 1;
+                readonly fastConfirmations: 1;
+            };
+        };
+        readonly forwarderSupported: {
+            readonly source: false;
+            readonly destination: false;
+        };
+    };
+    readonly kitContracts: {
+        readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
+    };
+};
+
+/**
+ * Cronos Testnet chain definition
+ * @remarks
+ * This represents the official test network for the Cronos blockchain.
+ * Cronos is an EVM-compatible blockchain.
+ */
+declare const CronosTestnet: {
+    readonly type: "evm";
+    readonly chain: Blockchain.Cronos_Testnet;
+    readonly name: "Cronos Testnet";
+    readonly title: "Cronos Testnet";
+    readonly nativeCurrency: {
+        readonly name: "CRO";
+        readonly symbol: "tCRO";
+        readonly decimals: 18;
+    };
+    readonly chainId: 338;
+    readonly isTestnet: true;
+    readonly explorerUrl: "https://explorer.cronos.org/testnet/tx/{hash}";
+    readonly rpcEndpoints: readonly ["https://evm-t3.cronos.org"];
+    readonly eurcAddress: "0x31f7538adb53cF16350e6B0c89d03D91b7D12c46";
+    readonly usdcAddress: "0xEb33dc5fac03833e132593659e1dE7256aB59794";
+    readonly usdtAddress: null;
+    readonly cctp: {
+        readonly domain: 32;
+        readonly contracts: {
+            readonly v2: {
+                readonly type: "split";
+                readonly tokenMessenger: "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA";
+                readonly messageTransmitter: "0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275";
+                readonly confirmations: 1;
+                readonly fastConfirmations: 1;
+            };
+        };
+        readonly forwarderSupported: {
+            readonly source: false;
+            readonly destination: false;
+        };
+    };
+    readonly kitContracts: {
+        readonly bridge: "0xC5567a5E3370d4DBfB0540025078e283e36A363d";
+    };
+};
+
 /**
  * Edge Mainnet chain definition
  * @remarks
@@ -4173,6 +4265,8 @@ declare const Chains_Celo: typeof Celo;
 declare const Chains_CeloAlfajoresTestnet: typeof CeloAlfajoresTestnet;
 declare const Chains_Codex: typeof Codex;
 declare const Chains_CodexTestnet: typeof CodexTestnet;
+declare const Chains_Cronos: typeof Cronos;
+declare const Chains_CronosTestnet: typeof CronosTestnet;
 declare const Chains_Edge: typeof Edge;
 declare const Chains_EdgeTestnet: typeof EdgeTestnet;
 declare const Chains_Ethereum: typeof Ethereum;
@@ -4240,6 +4334,8 @@ declare namespace Chains {
     Chains_CeloAlfajoresTestnet as CeloAlfajoresTestnet,
     Chains_Codex as Codex,
     Chains_CodexTestnet as CodexTestnet,
+    Chains_Cronos as Cronos,
+    Chains_CronosTestnet as CronosTestnet,
     Chains_Edge as Edge,
     Chains_EdgeTestnet as EdgeTestnet,
     Chains_Ethereum as Ethereum,
@@ -8381,7 +8477,7 @@ declare const ServiceError: {
  *
  * Error code ranges:
  * - 1100-1105: INPUT errors — invalid inputs, unsupported configurations
- * - 8100-8104: SERVICE errors — retryable backend/provider failures
+ * - 8100-8105: SERVICE errors — retryable backend/provider failures
  *
  * @example
  * ```typescript
@@ -8470,6 +8566,12 @@ declare const EarnError: {
         readonly name: "EARN_PAUSED";
         readonly type: ErrorType;
     };
+    /** Position PnL is still reconciling and can be retried. */
+    readonly POSITION_PNL_PENDING: {
+        readonly code: 8105;
+        readonly name: "EARN_POSITION_PNL_PENDING";
+        readonly type: ErrorType;
+    };
 };
 
 /**
@@ -12015,6 +12117,38 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
      * @returns A promise that resolves to the attestation message.
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Polls attestation data until Circle's relayer mint transaction is confirmed.
+     *
+     * @param source - The source wallet context containing the chain definition and wallet address.
+     * @param txHash - The transaction hash of the deposit for burn transaction.
+     * @param config - Optional polling configuration overrides.
+     * @returns A promise that resolves to the relayer mint attestation message.
+     * @throws KitError If the source wallet context is invalid, the transaction hash is invalid,
+     *   the relayer forward fails, the response is invalid, or polling times out.
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider({
+     *   headers: { 'X-Partner-UUID': '00000000-0000-0000-0000-000000000000' },
+     * })
+     *
+     * const attestation = await provider.fetchRelayerMint(
+     *   {
+     *     adapter,
+     *     chain: Chains.EthereumSepolia,
+     *     address: '0x1234...',
+     *   },
+     *   '0xabc123...',
+     * )
+     *
+     * console.log('Relayer mint tx:', attestation.forwardTxHash)
+     * ```
+     */
+    fetchRelayerMint<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], txHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Requests a fresh attestation for an expired attestation.
      *
@@ -12046,10 +12180,28 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
  * @remarks
  * This interface defines all configurable aspects of the CCTP v2 provider:
  * - attestation: Settings for the attestation fetching process
+ * - headers: Custom HTTP headers sent with every Circle attestation API request
  */
 interface CCTPV2Config {
     /** Configuration for the attestation fetching process */
     attestation?: Partial<ApiPollingConfig>;
+    /**
+     * Custom HTTP headers sent with every Circle attestation (Iris) API request
+     * made by the provider (attestation fetch, re-attestation, and relayer mint
+     * status polling).
+     *
+     * @remarks
+     * Headers are merged on top of the defaults (such as `Content-Type`) without
+     * removing them. The header is forwarded as-is to Circle's API; the SDK does
+     * not interpret it.
+     *
+     * Precedence (lowest to highest): provider defaults, then these
+     * `config.headers`, then any per-call `config.headers` passed to
+     * {@link CCTPV2BridgingProvider.fetchAttestation},
+     * {@link CCTPV2BridgingProvider.fetchRelayerMint}, or
+     * {@link CCTPV2BridgingProvider.reAttest}.
+     */
+    headers?: Record<string, string>;
 }
 /**
  * Concrete implementation of BridgingProvider for Circle's Cross-Chain Transfer Protocol (CCTP) version 2.
@@ -12115,6 +12267,20 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * @param config - Optional configuration overrides for the provider
      */
     constructor(config?: CCTPV2Config);
+    /**
+     * Resolves the effective polling configuration for an attestation request.
+     *
+     * Precedence (lowest to highest): provider `config.attestation`, then the
+     * per-call `config`. Headers merge independently across
+     * `config.attestation.headers`, the provider-level `config.headers`, and any
+     * per-call `config.headers`, so a more specific header augments rather than
+     * replaces the broader ones. The `headers` key is omitted entirely when no
+     * headers are configured, leaving the attestation fetchers' defaults intact.
+     *
+     * @param config - Optional per-call polling configuration overrides
+     * @returns The merged polling configuration passed to the attestation fetchers
+     */
+    private resolveAttestationConfig;
     /**
      * Execute a cross-chain USDC bridge operation using the CCTP v2 protocol.
      *
@@ -12357,6 +12523,43 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
      * ```
      */
     fetchAttestation<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
+    /**
+     * Polls attestation data until Circle's relayer mint transaction is confirmed.
+     *
+     * This method is used by forwarded transfers. It polls the same Iris
+     * attestation endpoint as {@link CCTPV2BridgingProvider.fetchAttestation},
+     * but waits for a completed relayer forward state and returns the attestation
+     * message containing `forwardTxHash`.
+     *
+     * @typeParam TFromAdapterCapabilities - The type representing the capabilities of the source adapter
+     * @param source - The source wallet context containing the chain definition and wallet address
+     * @param transactionHash - The transaction hash of the burn operation
+     * @param config - Optional polling configuration overrides for timeout, retries, delay, and headers
+     * @returns A promise that resolves to the attestation message with `forwardTxHash`
+     * @throws KitError If the relayer forward fails, the response is invalid, or polling times out
+     *
+     * @example
+     * ```typescript
+     * import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+     * import { Chains } from '@core/chains'
+     *
+     * const provider = new CCTPV2BridgingProvider({
+     *   headers: { 'X-Partner-UUID': '00000000-0000-0000-0000-000000000000' },
+     * })
+     *
+     * const attestation = await provider.fetchRelayerMint(
+     *   {
+     *     adapter,
+     *     chain: Chains.EthereumSepolia,
+     *     address: '0x1234...',
+     *   },
+     *   '0xabc123...',
+     * )
+     *
+     * console.log('Relayer mint tx:', attestation.forwardTxHash)
+     * ```
+     */
+    fetchRelayerMint<TFromAdapterCapabilities extends AdapterCapabilities>(source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>, transactionHash: string, config?: Partial<ApiPollingConfig>): Promise<AttestationMessage>;
     /**
      * Requests a fresh attestation for an expired attestation.
      *
@@ -12532,11 +12735,24 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
     waitForTransaction(adapter: Adapter, txHash: string, chain: ChainDefinition, config?: WaitForTransactionConfig): Promise<WaitForTransactionResponse>;
 }
 
+/**
+ * Configuration forwarded to the default bridging providers.
+ */
+interface DefaultProvidersConfig {
+    /**
+     * Custom HTTP headers forwarded with the CCTP provider's attestation (Iris)
+     * API requests. See {@link BridgeKitConfig.headers}.
+     */
+    headers?: Record<string, string>;
+}
 /**
  * The default providers that will be used in addition to the providers provided
  * to the BridgeKit constructor.
+ *
+ * @param config - Optional configuration forwarded to the default providers
+ * @returns The default bridging providers
  */
-declare const getDefaultProviders$1: () => readonly [CCTPV2BridgingProvider];
+declare const getDefaultProviders$1: (config?: DefaultProvidersConfig) => readonly [CCTPV2BridgingProvider];
 
 /**
  * Configuration options for initializing a BridgeKit instance.
@@ -12593,6 +12809,23 @@ interface BridgeKitConfig<TExtraProviders extends FlexibleBridgingProvider[] = [
      * @defaultValue false
      */
     disableErrorReporting?: boolean;
+    /**
+     * Custom HTTP headers forwarded with the default CCTP provider's attestation
+     * (Iris) API requests.
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. The header is forwarded as-is to Circle's API;
+     * the SDK does not interpret it.
+     *
+     * @example
+     * ```typescript
+     * const kit = new BridgeKit({
+     *   headers: { 'X-Access-Key': '00000000-0000-0000-0000-000000000000' },
+     * })
+     * ```
+     */
+    headers?: Record<string, string>;
 }
 /**
  * Merges action types from multiple bridging providers into a unified action map.
@@ -15526,10 +15759,11 @@ interface AssetAmount {
     /**
      * Optional category tag for the amount.
      *
-     * Present on fee entries to identify the kind of fee — for cross-chain
-     * deposit quotes this is the source-fee item type (e.g. `'FORWARD'`,
-     * `'PRE_FINALITY'`). Omitted when the amount has no meaningful category
-     * (plain deposit/withdrawal/share/reward amounts).
+     * Present on fee entries to identify the kind of fee. For cross-chain deposit
+     * quotes this is the source-fee item type (e.g. `'FORWARD'`,
+     * `'PRE_FINALITY'`), and for withdrawal quotes this can identify Circle fees
+     * (e.g. `'circle'`). Omitted when the amount has no meaningful
+     * category (plain deposit/withdrawal/share/reward amounts).
      */
     readonly type?: string | undefined;
     /**
@@ -16168,7 +16402,12 @@ interface WithdrawalQuoteInfo {
      * available balance and quoted withdrawal in a single round-trip.
      */
     readonly maxWithdrawable: AssetAmount;
-    /** Fees applied to the withdrawal. */
+    /**
+     * Fees applied to the withdrawal.
+     *
+     * Circle fees are returned with `type: 'circle'` so callers can distinguish
+     * them from untyped plain fees and native gas estimates.
+     */
     readonly fees: readonly AssetAmount[];
     /**
      * Estimated native gas fees for the transactions needed to withdraw.
@@ -23609,14 +23848,17 @@ type TokenAddress = string & {
 /**
  * Known token aliases supported by AppKit.
  *
- * These aliases map to chain-specific token addresses and have dedicated
- * transfer actions in the adapter layer.
+ * These aliases map to chain-specific token addresses. `USDC`, `USDT`, and
+ * `NATIVE` have dedicated transfer actions in the adapter layer. `EURC` has no
+ * dedicated action — it resolves to the chain's `eurcAddress` and is sent via
+ * the generic token transfer action, so it is only supported on chains where
+ * `eurcAddress` is set.
  *
  * @remarks
  * For swap operations, see {@link SupportedToken} in SwapKit which supports
- * additional tokens (EURC, DAI, USDE, PYUSD).
+ * additional tokens (DAI, USDE, PYUSD).
  */
-type TokenAlias = 'USDC' | 'USDT' | 'NATIVE';
+type TokenAlias = 'USDC' | 'USDT' | 'NATIVE' | 'EURC';
 /**
  * Operation types that support the `getFee`/`getFeeRecipient` hooks.
  */
@@ -23775,6 +24017,16 @@ interface AppKitContext {
      * @defaultValue false
      */
     disableErrorReporting?: boolean;
+    /**
+     * Custom HTTP headers forwarded with the underlying CCTP provider's
+     * attestation (Iris) API requests made by bridge operations.
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. The header is forwarded as-is to Circle's API;
+     * the SDK does not interpret it.
+     */
+    headers?: Record<string, string>;
 }
 /**
  * Earn operation namespace exposed as `kit.earn`.
@@ -24073,7 +24325,7 @@ type ActionHandler<T extends {
  * When `to` is a `string`, the address must be a valid address. When `to` is an
  * {@link Adapter}, the recipient is derived from the adapter's active account.
  *
- * The `token` field accepts both supported token aliases ('USDC', 'USDT', 'NATIVE') and custom token
+ * The `token` field accepts both supported token aliases ('USDC', 'USDT', 'NATIVE', 'EURC') and custom token
  * contract addresses.
  *
  * @example
@@ -24113,7 +24365,8 @@ interface SendParams {
      * If omitted, the provider will use 'USDC' by default.
      *
      * Supports both known aliases and custom token contract addresses:
-     * - Known aliases: 'USDC', 'USDT', 'NATIVE'
+     * - Known aliases: 'USDC', 'USDT', 'NATIVE', 'EURC' ('EURC' requires the
+     *   chain to have an `eurcAddress` configured)
      * - Custom token addresses: EVM addresses or Solana SPL token mint addresses
      *
      * @example
@@ -26551,7 +26804,11 @@ declare class AppKit {
  * The type annotation `readonly TokenAlias[]` ensures this array stays in sync
  * with the TokenAlias type definition - TypeScript will enforce any changes.
  *
- * For swap operations, additional tokens (EURC, DAI, USDE, PYUSD) are supported
+ * `USDC`, `USDT`, and `NATIVE` map to dedicated adapter transfer actions.
+ * `EURC` has no dedicated action — it resolves to the chain's `eurcAddress`
+ * and uses the generic token transfer action (see {@link prepareSend}).
+ *
+ * For swap operations, additional tokens (DAI, USDE, PYUSD) are supported
  * via SwapKit's SupportedToken type.
  */
 declare const TOKEN_ALIASES: readonly TokenAlias[];
@@ -26562,7 +26819,7 @@ declare const TOKEN_ALIASES: readonly TokenAlias[];
  * or neither.
  */
 interface TokenValidationResult {
-    /** True if the token is a known alias (USDC, USDT, NATIVE) */
+    /** True if the token is a known alias (USDC, USDT, NATIVE, EURC) */
     isAlias: boolean;
     /** True if the token is a valid address for the chain */
     isAddress: boolean;
@@ -26593,7 +26850,7 @@ declare function isTokenAlias(token: string): token is TokenAlias;
  * Type guard to check if a string is a valid token address for a chain.
  *
  * This function verifies that a token string is:
- * 1. Not a known alias ('USDC', 'USDT', 'NATIVE')
+ * 1. Not a known alias ('USDC', 'USDT', 'NATIVE', 'EURC')
  * 2. A valid address format for the specified chain
  *
  * Use this to narrow the type to `TokenAddress` in TypeScript.
@@ -26622,7 +26879,7 @@ declare function isTokenAddress(token: string, chain: ChainDefinition): token is
  * Validate and classify a token identifier.
  *
  * This function determines whether a token string is:
- * 1. A known alias ('USDC', 'USDT', or 'NATIVE')
+ * 1. A known alias ('USDC', 'USDT', 'NATIVE', or 'EURC')
  * 2. A valid token address for the given chain
  * 3. An invalid/unrecognized token identifier
  *