@circle-fin/app-kit 1.9.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.mts CHANGED
@@ -374,6 +374,14 @@ interface CCTPSplitConfig {
374
374
  type: 'split';
375
375
  tokenMessenger: string;
376
376
  messageTransmitter: string;
377
+ /**
378
+ * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
379
+ *
380
+ * Optional. Present only on chains that support the prepaid FORWARD path
381
+ * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
382
+ * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
383
+ */
384
+ tokenMessengerWithFees?: string;
377
385
  confirmations: number;
378
386
  }
379
387
  /**
@@ -394,6 +402,14 @@ interface CCTPSplitConfig {
394
402
  interface CCTPMergedConfig {
395
403
  type: 'merged';
396
404
  contract: string;
405
+ /**
406
+ * Address of the `TokenMessengerWithFees` wrapper, when deployed on this chain.
407
+ *
408
+ * Optional. Present only on chains that support the prepaid FORWARD path
409
+ * (source-chain fee collection via `depositForBurnWithHookAndFees`). Resolve
410
+ * it with `resolveCCTPV2ContractAddress(chain, 'tokenMessengerWithFees')`.
411
+ */
412
+ tokenMessengerWithFees?: string;
397
413
  confirmations: number;
398
414
  }
399
415
  /**
@@ -528,6 +544,21 @@ interface GatewayV1Contracts {
528
544
  * @example "0xabcdef1234567890abcdef1234567890abcdef12"
529
545
  */
530
546
  minter: string;
547
+ /**
548
+ * The address of the `DepositForHandler` contract.
549
+ *
550
+ * @description Optional. The handler the GenericExecutor calls on this chain
551
+ * to run a fast cross-chain deposit into the {@link GatewayV1Contracts.wallet}.
552
+ * Present only on chains that are fast-deposit destinations; other Gateway
553
+ * chains omit it.
554
+ *
555
+ * Address format varies by blockchain:
556
+ * - EVM chains: 40-character hexadecimal with 0x prefix (e.g., "0x1234...")
557
+ * - Solana: Base58-encoded 32-byte address (e.g., "9WzDX...")
558
+ *
559
+ * @example "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48"
560
+ */
561
+ depositForHandler?: string;
531
562
  }
532
563
  /**
533
564
  * Versioned map of Gateway contract configurations.
@@ -1362,6 +1393,7 @@ declare const ArcTestnet: {
1362
1393
  readonly v1: {
1363
1394
  readonly wallet: "0x0077777d7EBA4688BDeF3E311b846F25870A19B9";
1364
1395
  readonly minter: "0x0022222ABE238Cc2C7Bb1f21003F0a260052475B";
1396
+ readonly depositForHandler: "0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48";
1365
1397
  };
1366
1398
  };
1367
1399
  readonly forwarderSupported: {
@@ -5472,6 +5504,110 @@ interface CCTPv2ActionMap {
5472
5504
  */
5473
5505
  hookData: string;
5474
5506
  };
5507
+ /**
5508
+ * Initiate a prepaid cross-chain USDC transfer through the `TokenMessengerWithFees` wrapper.
5509
+ *
5510
+ * Burn USDC on the source chain while collecting all fees up front against a
5511
+ * signed quote. The wrapper collects the fee via `FeeManager`, then delegates
5512
+ * to the unmodified `TokenMessengerV2`. When `hookData` is provided (the
5513
+ * GenericExecutor FORWARD path) the wrapper's `depositForBurnWithHookAndFees`
5514
+ * contract method is used; otherwise `depositForBurnWithFees` is used.
5515
+ *
5516
+ * @remarks
5517
+ * SDK/contract naming: this SDK action is `depositForBurnWithFees` but, when a
5518
+ * `hookData` is present, it dispatches to the `depositForBurnWithHookAndFees`
5519
+ * contract method on `TokenMessengerWithFees` (NOT on `TokenMessengerV2`).
5520
+ *
5521
+ * Fee payment channel (must match the quote's `feeToken`):
5522
+ * - Native fee (`feeToken` is the zero address): exactly `feeTotalAmount` is
5523
+ * attached as `msg.value`.
5524
+ * - ERC-20 fee (e.g. USDC): no value is attached; the caller must first approve
5525
+ * the wrapper for `feeTotalAmount` (see the provider's fee approval helper).
5526
+ *
5527
+ * @remarks
5528
+ * Unlike `depositForBurn`, the `TokenMessengerWithFees` contract methods do NOT
5529
+ * take `maxFee` or `minFinalityThreshold` — fee and finality behavior are
5530
+ * derived from the signed quote — so those fields are omitted from this action.
5531
+ *
5532
+ * @example
5533
+ * ```typescript
5534
+ * await adapter.action('cctp.v2.depositForBurnWithFees', {
5535
+ * amount: BigInt('1000000'),
5536
+ * mintRecipient: executorAddress, // GenericExecutor (bytes32)
5537
+ * destinationCaller: executorAddress, // GenericExecutor (bytes32)
5538
+ * fromChain: ethereum,
5539
+ * toChain: arc,
5540
+ * hookData: geForwardHookData, // cctp-forward-wrapped GenericExecutor blob
5541
+ * claim: { signedQuote: '0x...', refundAddress: '0x...' },
5542
+ * feeToken: '0x0000000000000000000000000000000000000000', // native
5543
+ * feeTotalAmount: 3500000n,
5544
+ * })
5545
+ * ```
5546
+ */
5547
+ depositForBurnWithFees: Omit<CCTPv2ActionMap['depositForBurn'], 'maxFee' | 'minFinalityThreshold'> & {
5548
+ /**
5549
+ * Optional hex-encoded hook data for the GenericExecutor FORWARD path.
5550
+ *
5551
+ * When present, the `depositForBurnWithHookAndFees` contract method is used
5552
+ * and the blob must be wrapped in the `cctp-forward` envelope (the wrapper
5553
+ * rejects a FORWARD fee quote whose hook lacks it). When omitted, the plain
5554
+ * `depositForBurnWithFees` contract method is used.
5555
+ */
5556
+ hookData?: string;
5557
+ /**
5558
+ * Signed fee quote claim passed to the `TokenMessengerWithFees` wrapper.
5559
+ *
5560
+ * `signedQuote` is the `[uint8 0x01][abi.encode(Quote)]` blob returned by the
5561
+ * Fee Quote service; `refundAddress` receives any fee overpayment refund.
5562
+ */
5563
+ claim: QuoteClaim;
5564
+ /**
5565
+ * Fee token from the signed quote.
5566
+ *
5567
+ * The zero address (`0x000…0`) means the fee is paid in native currency and
5568
+ * is attached as `msg.value`. Any other address (e.g. USDC) means an ERC-20
5569
+ * fee that must be approved to the wrapper beforehand. This is independent of
5570
+ * `burnToken`, which is always USDC.
5571
+ */
5572
+ feeToken: string;
5573
+ /**
5574
+ * Total fee amount from the signed quote, in `feeToken` minor units.
5575
+ *
5576
+ * Firm only until the quote's `expiresAt`. For a native fee this is the exact
5577
+ * `msg.value`; for an ERC-20 fee this is the amount approved to the wrapper.
5578
+ */
5579
+ feeTotalAmount: bigint;
5580
+ };
5581
+ }
5582
+ /**
5583
+ * Signed fee quote claim consumed by the `TokenMessengerWithFees` wrapper.
5584
+ *
5585
+ * Mirrors the on-chain `IFeeManager.QuoteClaim` struct.
5586
+ *
5587
+ * @example
5588
+ * ```typescript
5589
+ * const claim: QuoteClaim = {
5590
+ * signedQuote: '0x01...', // [uint8 0x01][abi.encode(Quote)]
5591
+ * refundAddress: '0xUserWallet...',
5592
+ * }
5593
+ * ```
5594
+ */
5595
+ interface QuoteClaim {
5596
+ /**
5597
+ * Opaque signed quote bytes (`0x` hex) from the fee-quote service
5598
+ * (`SignedFeeQuote.signedQuote` returned by `fetchFeeQuote`). Pass verbatim;
5599
+ * do not decode.
5600
+ *
5601
+ * The quote binds the FORWARD fee item to the on-chain call via `argsHash`;
5602
+ * passing a quote that does not match the burn args reverts `QuoteArgsMismatch`.
5603
+ */
5604
+ signedQuote: string;
5605
+ /**
5606
+ * Address that receives any refund of overpaid fees.
5607
+ *
5608
+ * Typically the user wallet that authorized the burn.
5609
+ */
5610
+ refundAddress: string;
5475
5611
  }
5476
5612
 
5477
5613
  /**
@@ -8469,14 +8605,14 @@ declare const ServiceError: {
8469
8605
  };
8470
8606
 
8471
8607
  /**
8472
- * Standardized error definitions for Earn/Zenith operations.
8608
+ * Standardized error definitions for Earn operations.
8473
8609
  *
8474
8610
  * These error codes provide fine-grained categorization of failures
8475
- * from the Zenith earn service, enabling SDK consumers to distinguish
8611
+ * from the Earn service, enabling SDK consumers to distinguish
8476
8612
  * between input errors (fix your request) and service errors (retry later).
8477
8613
  *
8478
8614
  * Error code ranges:
8479
- * - 1100-1105: INPUT errors — invalid inputs, unsupported configurations
8615
+ * - 1100-1106: INPUT errors — invalid, unsupported, or stale request state
8480
8616
  * - 8100-8105: SERVICE errors — retryable backend/provider failures
8481
8617
  *
8482
8618
  * @example
@@ -8536,6 +8672,15 @@ declare const EarnError: {
8536
8672
  readonly name: "EARN_UNSUPPORTED_BRIDGE_ROUTE";
8537
8673
  readonly type: ErrorType;
8538
8674
  };
8675
+ /**
8676
+ * The bridge quote expired. This is an INPUT error because the prepared
8677
+ * request is stale and must be replaced instead of retried.
8678
+ */
8679
+ readonly BRIDGE_QUOTE_EXPIRED: {
8680
+ readonly code: 1106;
8681
+ readonly name: "EARN_BRIDGE_QUOTE_EXPIRED";
8682
+ readonly type: ErrorType;
8683
+ };
8539
8684
  /** The proxy signing call failed — retryable. */
8540
8685
  readonly SIGNING_FAILED: {
8541
8686
  readonly code: 8100;
@@ -12174,6 +12319,70 @@ interface ICCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> {
12174
12319
  mint<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(source: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['source'], destination: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>['destination'], attestation: AttestationMessage): Promise<PreparedChainRequest>;
12175
12320
  }
12176
12321
 
12322
+ /**
12323
+ * An ERC-20 approval required before a prepaid-FORWARD burn.
12324
+ *
12325
+ * @example
12326
+ * ```typescript
12327
+ * const approval: FeeApproval = {
12328
+ * token: '0xUSDC...',
12329
+ * amount: 1_003_500_000n,
12330
+ * }
12331
+ * ```
12332
+ */
12333
+ interface FeeApproval {
12334
+ /**
12335
+ * Token address to approve (the burn token and/or the ERC-20 fee token).
12336
+ */
12337
+ token: string;
12338
+ /**
12339
+ * Amount to approve to the `TokenMessengerWithFees` wrapper, in token minor units.
12340
+ */
12341
+ amount: bigint;
12342
+ }
12343
+ /**
12344
+ * The resolved fee payment channel for a prepaid-FORWARD burn.
12345
+ *
12346
+ * @example
12347
+ * ```typescript
12348
+ * const plan: FeePaymentPlan = {
12349
+ * isNativeFee: false,
12350
+ * isBurnTokenFee: true,
12351
+ * nativeValue: 0n,
12352
+ * approvals: [{ token: '0xUSDC...', amount: 1_003_500_000n }],
12353
+ * }
12354
+ * ```
12355
+ */
12356
+ interface FeePaymentPlan {
12357
+ /**
12358
+ * True when the fee is paid in native currency (`feeToken` is the zero address).
12359
+ */
12360
+ isNativeFee: boolean;
12361
+ /**
12362
+ * True when the fee token is the same token being burned (both USDC).
12363
+ *
12364
+ * In this case a single, combined approval covers both the burn and the fee,
12365
+ * so the redundant second approval is skipped.
12366
+ */
12367
+ isBurnTokenFee: boolean;
12368
+ /**
12369
+ * Native value to attach as `msg.value`.
12370
+ *
12371
+ * Exactly `feeTotalAmount` for a native fee; `0n` for an ERC-20 fee.
12372
+ */
12373
+ nativeValue: bigint;
12374
+ /**
12375
+ * ERC-20 approvals required before the burn, each to the `TokenMessengerWithFees`
12376
+ * wrapper.
12377
+ *
12378
+ * - Native fee: a single approval of `amount` for the burn token.
12379
+ * - ERC-20 fee equal to the burn token: a single approval of `amount + feeTotalAmount`.
12380
+ * - ERC-20 fee different from the burn token: two approvals — `amount` for the
12381
+ * burn token and `feeTotalAmount` for the fee token.
12382
+ */
12383
+ approvals: FeeApproval[];
12384
+ }
12385
+
12177
12386
  /**
12178
12387
  * Configuration options for the CCTP v2 provider.
12179
12388
  *
@@ -12203,6 +12412,81 @@ interface CCTPV2Config {
12203
12412
  */
12204
12413
  headers?: Record<string, string>;
12205
12414
  }
12415
+ /**
12416
+ * Parameters for a prepaid-FORWARD burn via {@link CCTPV2BridgingProvider.burnWithFees}.
12417
+ *
12418
+ * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
12419
+ */
12420
+ interface BurnWithFeesParams<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities> {
12421
+ /**
12422
+ * Source wallet context (adapter + CCTP v2 source chain).
12423
+ */
12424
+ source: WalletContext<TFromAdapterCapabilities, ChainDefinitionWithCCTPv2>;
12425
+ /**
12426
+ * Destination chain definition (provides the destination CCTP domain).
12427
+ */
12428
+ destinationChain: ChainDefinitionWithCCTPv2;
12429
+ /**
12430
+ * Amount of USDC to burn, in minor units.
12431
+ */
12432
+ amount: string | bigint;
12433
+ /**
12434
+ * The GenericExecutor address on the destination chain.
12435
+ *
12436
+ * Used for BOTH `mintRecipient` and `destinationCaller` (padded to bytes32 by
12437
+ * the underlying action): the executor mints to itself and is the only account
12438
+ * allowed to complete the transfer.
12439
+ */
12440
+ executor: string;
12441
+ /**
12442
+ * The `cctp-forward`-wrapped GenericExecutor hookData blob.
12443
+ *
12444
+ * Produced with `@core/utils`: wrap the bare blob from
12445
+ * `buildDepositForGenericExecutorPayload(...).hookData` with
12446
+ * `buildForwardingHookDataWithPayload(version, bareBlob)`. It must begin with
12447
+ * the `cctp-forward` frame, or the wrapper reverts `ForwardFeeWithoutHook`.
12448
+ *
12449
+ * Pass the SAME wrapped bytes here that were bound to the FORWARD fee quote
12450
+ * (`fetchFeeQuote` FORWARD `params.hookData`); mismatched bytes revert
12451
+ * `QuoteArgsMismatch`. Do not pass the bare (`circle-generic-executor`) blob.
12452
+ */
12453
+ hookData: string;
12454
+ /**
12455
+ * Signed fee quote claim (`{ signedQuote, refundAddress }`).
12456
+ */
12457
+ claim: QuoteClaim;
12458
+ /**
12459
+ * Fee token from the quote. The zero address denotes a native fee.
12460
+ */
12461
+ feeToken: string;
12462
+ /**
12463
+ * Total fee amount from the quote, in `feeToken` minor units.
12464
+ */
12465
+ feeTotalAmount: string | bigint;
12466
+ }
12467
+ /**
12468
+ * Result of {@link CCTPV2BridgingProvider.burnWithFees}.
12469
+ *
12470
+ * The prepared requests are returned unexecuted; the caller executes the
12471
+ * approvals first (in order) and then the burn.
12472
+ */
12473
+ interface BurnWithFeesResult {
12474
+ /**
12475
+ * ERC-20 approvals to the `TokenMessengerWithFees` wrapper required before the
12476
+ * burn. Always contains at least one entry: the burn-token approval. A
12477
+ * distinct fee-token approval is added only when the fee token differs from
12478
+ * the burn token and is not the native token.
12479
+ */
12480
+ approvals: PreparedChainRequest[];
12481
+ /**
12482
+ * The prepared `depositForBurnWithHookAndFees` burn transaction.
12483
+ */
12484
+ burn: PreparedChainRequest;
12485
+ /**
12486
+ * The resolved fee payment plan (native value, approvals, and flags).
12487
+ */
12488
+ feePayment: FeePaymentPlan;
12489
+ }
12206
12490
  /**
12207
12491
  * Concrete implementation of BridgingProvider for Circle's Cross-Chain Transfer Protocol (CCTP) version 2.
12208
12492
  *
@@ -12711,6 +12995,57 @@ declare class CCTPV2BridgingProvider extends BridgingProvider<CCTPV2Actions> imp
12711
12995
  * ```
12712
12996
  */
12713
12997
  burn<TFromAdapterCapabilities extends AdapterCapabilities, TToAdapterCapabilities extends AdapterCapabilities>(params: BridgeParams$1<TFromAdapterCapabilities, TToAdapterCapabilities>): Promise<PreparedChainRequest>;
12998
+ /**
12999
+ * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
13000
+ *
13001
+ * Builds the source-chain `depositForBurnWithHookAndFees` call for the
13002
+ * GenericExecutor FORWARD path: fees are collected up front on the source chain
13003
+ * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
13004
+ * the GenericExecutor, and the GE `hookData` is passed through unchanged.
13005
+ *
13006
+ * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
13007
+ * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
13008
+ * `claim` are produced elsewhere and passed in here:
13009
+ * - `hookData`: `buildForwardingHookDataWithPayload(version,
13010
+ * buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
13011
+ * - `claim.signedQuote` / `feeToken` / `feeTotalAmount`: from `fetchFeeQuote`
13012
+ * (`@circle-fin/provider-fee-v1`), whose FORWARD item must be bound to the
13013
+ * SAME `hookData` and executor `destinationCaller` used here.
13014
+ *
13015
+ * The returned approvals and burn are NOT executed — the caller executes the
13016
+ * approvals first (in order) and then the burn. The fee payment channel matches
13017
+ * the quote's `feeToken`:
13018
+ * - Native fee: exactly `feeTotalAmount` is attached as the burn's `msg.value`;
13019
+ * only the burn amount is approved.
13020
+ * - USDC fee (same token as the burn): a single combined `amount + feeTotalAmount`
13021
+ * approval covers both; the redundant second approval is skipped.
13022
+ *
13023
+ * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
13024
+ * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
13025
+ * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
13026
+ * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
13027
+ * support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
13028
+ * a bigint or a numeric string coercible to bigint, the hookData lacks a
13029
+ * `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
13030
+ * context cannot be resolved.
13031
+ *
13032
+ * @example
13033
+ * ```typescript
13034
+ * const { approvals, burn } = await provider.burnWithFees({
13035
+ * source,
13036
+ * destinationChain: Arc,
13037
+ * amount: 1_000_000n,
13038
+ * executor: genericExecutorAddress,
13039
+ * hookData: geForwardHookData,
13040
+ * claim: { signedQuote: '0x01...', refundAddress: userAddress },
13041
+ * feeToken: '0x0000000000000000000000000000000000000000', // native
13042
+ * feeTotalAmount: 3_500_000n,
13043
+ * })
13044
+ * for (const approval of approvals) await approval.execute()
13045
+ * const txHash = await burn.execute()
13046
+ * ```
13047
+ */
13048
+ burnWithFees<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(params: BurnWithFeesParams<TFromAdapterCapabilities>): Promise<BurnWithFeesResult>;
12714
13049
  /**
12715
13050
  * Waits for a transaction to be mined and confirmed on the blockchain.
12716
13051
  *
@@ -13553,6 +13888,29 @@ interface ServiceSwapConfig {
13553
13888
  * @example 'lifi', 'paraswap'
13554
13889
  */
13555
13890
  provider?: string;
13891
+ /**
13892
+ * Whether to fuse the ERC-20 approval and the swap into a single atomic
13893
+ * batch when the adapter supports it (EIP-5792, or a signing strategy that
13894
+ * declares atomic batching).
13895
+ *
13896
+ * @remarks
13897
+ * Defaults to `true`. When batching is available this collapses the two
13898
+ * sequential transactions of the on-chain approval path into one atomic
13899
+ * submission — a single signing challenge for a smart-contract wallet. Set
13900
+ * to `false` to force the sequential approve-then-swap path. Has no effect on
13901
+ * the gasless permit path (already a single transaction) or on native-token
13902
+ * swaps (no approval needed).
13903
+ *
13904
+ * The batch path relies on the wallet's own gas estimation for the swap call:
13905
+ * the service-provided gas floor and pre-flight simulation that the sequential
13906
+ * path applies are not conveyed through the batch. For a complex/multi-hop
13907
+ * swap whose wallet-side estimate under-shoots, this can out-of-gas-revert the
13908
+ * atomic batch where the sequential path would succeed — set `false` to fall
13909
+ * back to the service-floored sequential path if you hit this.
13910
+ *
13911
+ * @defaultValue true
13912
+ */
13913
+ batchTransactions?: boolean;
13556
13914
  }
13557
13915
  /**
13558
13916
  * Parameters for initiating a swap operation through the Stablecoin Service.
@@ -14987,9 +15345,10 @@ interface SwapDestinationLeg {
14987
15345
  * Parameters for {@link SwapKit.getSwapStatus}.
14988
15346
  *
14989
15347
  * @remarks
14990
- * Only `txHash`, `chainIn`, and `kitKey` are required. Supply `chainOut`
14991
- * when the original swap was cross-chain (source chain ≠ destination
14992
- * chain).
15348
+ * Only `txHash` and `chainIn` are required; `chainOut` and `kitKey` are
15349
+ * optional. Supply `chainOut` when the original swap was cross-chain
15350
+ * (source chain ≠ destination chain); omit `kitKey` to call in
15351
+ * permissionless mode.
14993
15352
  *
14994
15353
  * The field names mirror {@link SwapResult.chainIn} / {@link
14995
15354
  * SwapResult.chainOut} so consumers can pipe a `SwapResult` straight into
@@ -15004,11 +15363,11 @@ interface SwapDestinationLeg {
15004
15363
  * ```typescript
15005
15364
  * const result = await kit.swap(params)
15006
15365
  *
15366
+ * // Permissionless — no kit key needed. Pass `kitKey` to authenticate.
15007
15367
  * let status = await kit.getSwapStatus({
15008
15368
  * txHash: result.txHash,
15009
15369
  * chainIn: result.chainIn,
15010
15370
  * chainOut: result.chainOut,
15011
- * kitKey: process.env.KIT_KEY ?? '',
15012
15371
  * })
15013
15372
  * while (status.progress.status === 'PENDING') {
15014
15373
  * await new Promise((r) => setTimeout(r, 3_000))
@@ -15016,7 +15375,6 @@ interface SwapDestinationLeg {
15016
15375
  * txHash: result.txHash,
15017
15376
  * chainIn: result.chainIn,
15018
15377
  * chainOut: result.chainOut,
15019
- * kitKey: process.env.KIT_KEY ?? '',
15020
15378
  * })
15021
15379
  * }
15022
15380
  * ```
@@ -15044,8 +15402,11 @@ interface GetSwapStatusParams {
15044
15402
  /**
15045
15403
  * Stablecoin Service Kit Key used as a bearer credential for the status
15046
15404
  * request. Treat this value as a secret and do not log it.
15405
+ *
15406
+ * Optional — when omitted, the request is made without an `Authorization`
15407
+ * header (permissionless mode).
15047
15408
  */
15048
- kitKey: string;
15409
+ kitKey?: string;
15049
15410
  }
15050
15411
  /**
15051
15412
  * Result of a swap status lookup — a single snapshot of the swap's state at
@@ -15093,8 +15454,11 @@ interface WaitForSwapCommonParams {
15093
15454
  /**
15094
15455
  * Stablecoin Service Kit Key used as a bearer credential. Treat as a
15095
15456
  * secret and do not log it.
15457
+ *
15458
+ * Optional — when omitted, the request is made without an `Authorization`
15459
+ * header (permissionless mode).
15096
15460
  */
15097
- readonly kitKey: string;
15461
+ readonly kitKey?: string;
15098
15462
  /**
15099
15463
  * Overall wait budget, in milliseconds. The promise rejects with a
15100
15464
  * RETRYABLE {@link KitError} when this elapses without a terminal
@@ -15255,8 +15619,11 @@ interface GetTokenRatesParams {
15255
15619
  /**
15256
15620
  * Stablecoin Service Kit Key used as a bearer credential for the rates
15257
15621
  * request. Treat this value as a secret and do not log it.
15622
+ *
15623
+ * Optional — when omitted, the request is made without an `Authorization`
15624
+ * header (permissionless mode).
15258
15625
  */
15259
- kitKey: string;
15626
+ kitKey?: string;
15260
15627
  }
15261
15628
  /**
15262
15629
  * Result of a token rates lookup.
@@ -15431,6 +15798,30 @@ interface SwapKitConfig<TExtraProviders extends FlexibleSwappingProvider[] = []>
15431
15798
  disableErrorReporting?: boolean;
15432
15799
  }
15433
15800
 
15801
+ /** @internal */
15802
+ declare const bridgeQuoteExpirySchema: z.ZodCatch<z.ZodOptional<z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
15803
+ mode: z.ZodLiteral<"TIMESTAMP">;
15804
+ expiresAt: z.ZodString;
15805
+ }, "strip", z.ZodTypeAny, {
15806
+ mode: "TIMESTAMP";
15807
+ expiresAt: string;
15808
+ }, {
15809
+ mode: "TIMESTAMP";
15810
+ expiresAt: string;
15811
+ }>, z.ZodObject<{
15812
+ mode: z.ZodLiteral<"BLOCK_NUMBER">;
15813
+ expiresAtBlock: z.ZodNumber;
15814
+ blockEstimatedAt: z.ZodOptional<z.ZodString>;
15815
+ }, "strip", z.ZodTypeAny, {
15816
+ mode: "BLOCK_NUMBER";
15817
+ expiresAtBlock: number;
15818
+ blockEstimatedAt?: string | undefined;
15819
+ }, {
15820
+ mode: "BLOCK_NUMBER";
15821
+ expiresAtBlock: number;
15822
+ blockEstimatedAt?: string | undefined;
15823
+ }>]>>>;
15824
+
15434
15825
  /**
15435
15826
  * Configuration options for the Earn Service provider.
15436
15827
  *
@@ -15504,6 +15895,7 @@ interface VaultRewardInfo {
15504
15895
  * assetAddress: '0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf',
15505
15896
  * lltv: 0.86,
15506
15897
  * supplyUsd: 50000000.25,
15898
+ * allocationPct: 0.6,
15507
15899
  * }
15508
15900
  * ```
15509
15901
  */
@@ -15516,6 +15908,17 @@ interface CollateralInfo {
15516
15908
  readonly lltv: number;
15517
15909
  /** Approximate supplied value in USD, e.g. 50000000.25 for $50,000,000.25. */
15518
15910
  readonly supplyUsd: number;
15911
+ /**
15912
+ * Share of the vault's supply allocated to this collateral market
15913
+ * (e.g., 0.6 = 60%).
15914
+ *
15915
+ * Populated for Morpho V1 vaults; `null` when the underlying product
15916
+ * exposes no per-market allocation (e.g. Morpho V2). Optional for now — a
15917
+ * backend that predates this field omits it entirely, matching the other
15918
+ * optional facets on {@link EarnOpportunityBase}; a future release makes it
15919
+ * required once every backend emits it.
15920
+ */
15921
+ readonly allocationPct?: number | null | undefined;
15519
15922
  }
15520
15923
  /**
15521
15924
  * Vault warning from the underlying earn protocol.
@@ -15535,65 +15938,253 @@ interface VaultWarning {
15535
15938
  readonly level: 'YELLOW' | 'RED';
15536
15939
  }
15537
15940
  /**
15538
- * Describe a yield-bearing vault available through the earn service.
15941
+ * Manager (e.g., curator) responsible for a yield opportunity.
15942
+ *
15943
+ * Generalizes Morpho's "curator". `null` on the opportunity when the
15944
+ * underlying product has no per-opportunity manager (e.g., a pooled
15945
+ * lending market).
15539
15946
  *
15540
15947
  * @example
15541
15948
  * ```typescript
15542
- * const vault: VaultInfo = {
15543
- * vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
15544
- * chain: 'Arc_Testnet',
15545
- * name: 'Steakhouse USDC',
15546
- * protocol: 'MORPHO',
15547
- * asset: 'USDC',
15548
- * assetAddress: '0x3600000000000000000000000000000000000000',
15549
- * currentApy: 0.0425,
15550
- * nativeApy: 0.035,
15551
- * vaultFee: 0.05,
15552
- * rewards: [{ token: 'MORPHO', tokenAddress: '0x...', apy: 0.0075 }],
15553
- * collateral: [{ asset: 'cbBTC', assetAddress: '0x...', lltv: 0.86, supplyUsd: 50000000.25 }],
15554
- * totalDeposits: Amount.fromJSON({ raw: '15000000000000', decimals: 6 }),
15555
- * liquidity: Amount.fromJSON({ raw: '5000000000000', decimals: 6 }),
15949
+ * const manager: ManagerInfo = {
15950
+ * name: 'Steakhouse',
15951
+ * address: '0x...',
15952
+ * type: 'curator',
15953
+ * }
15954
+ * ```
15955
+ */
15956
+ interface ManagerInfo {
15957
+ /** Human-readable manager name. */
15958
+ readonly name: string;
15959
+ /** On-chain manager address, when the product exposes one. */
15960
+ readonly address?: string | undefined;
15961
+ /**
15962
+ * Manager role within the product. Only `'curator'` is emitted today
15963
+ * (Morpho V1/V2); additional roles are added as the providers that emit
15964
+ * them land.
15965
+ */
15966
+ readonly type: 'curator';
15967
+ }
15968
+ /**
15969
+ * Yield profile for an opportunity, including trailing averages.
15970
+ *
15971
+ * `current` is always present; trailing and native values are `null` when
15972
+ * unavailable for this instance (e.g., a vault younger than the lookback
15973
+ * window). `source`/`asOf` carry provenance for derived/staleness-prone
15974
+ * values.
15975
+ *
15976
+ * @example
15977
+ * ```typescript
15978
+ * const apyProfile: ApyProfile = {
15979
+ * current: 0.085,
15980
+ * native: 0.071,
15981
+ * d7: 0.082,
15982
+ * d30: 0.079,
15983
+ * d90: 0.081,
15984
+ * rewardShare: 0.16,
15985
+ * source: 'morpho:avgNetApy',
15986
+ * asOf: '2026-06-23T18:00:00Z',
15987
+ * }
15988
+ * ```
15989
+ */
15990
+ interface ApyProfile {
15991
+ /** Current total APY including rewards. */
15992
+ readonly current: number;
15993
+ /** Native APY excluding reward incentives; `null` when unavailable. */
15994
+ readonly native: number | null;
15995
+ /** Trailing 7-day average net APY; `null` when unavailable. */
15996
+ readonly d7: number | null;
15997
+ /** Trailing 30-day average net APY; `null` when unavailable. */
15998
+ readonly d30: number | null;
15999
+ /** Trailing 90-day average net APY; `null` when unavailable. */
16000
+ readonly d90: number | null;
16001
+ /** Share of current APY attributable to rewards; `null` when unavailable. */
16002
+ readonly rewardShare: number | null;
16003
+ /** Provenance of the trailing values (`native` or `circle:<source>`). */
16004
+ readonly source?: string | undefined;
16005
+ /** RFC3339 timestamp of the newest input used for the trailing values. */
16006
+ readonly asOf?: string | undefined;
16007
+ }
16008
+ /**
16009
+ * Fee split for an opportunity.
16010
+ *
16011
+ * Each component is `null` when the product does not levy it (e.g., Morpho
16012
+ * V1 vaults have no management fee).
16013
+ *
16014
+ * @example
16015
+ * ```typescript
16016
+ * const fee: FeeInfo = { performance: 0.1, management: null }
16017
+ * ```
16018
+ */
16019
+ interface FeeInfo {
16020
+ /** Performance fee as a decimal (e.g., 0.1 = 10%); `null` when unavailable. */
16021
+ readonly performance: number | null;
16022
+ /** Management fee as a decimal; `null` when unavailable. */
16023
+ readonly management: number | null;
16024
+ }
16025
+ /**
16026
+ * Liquidity profile for an opportunity.
16027
+ *
16028
+ * @example
16029
+ * ```typescript
16030
+ * const liquidityProfile: LiquidityProfile = {
16031
+ * totalDeposits: Amount.fromJSON({ raw: '45000000000000', decimals: 6 }),
16032
+ * available: Amount.fromJSON({ raw: '5200000000000', decimals: 6 }),
16033
+ * totalSupply: Amount.fromJSON({ raw: '44900000000000000000', decimals: 18 }),
15556
16034
  * status: 'active',
15557
- * circleGuarded: false,
15558
16035
  * }
15559
16036
  * ```
15560
16037
  */
15561
- interface VaultInfo {
15562
- /** On-chain vault contract address. */
15563
- readonly vaultAddress: string;
15564
- /** Blockchain where the vault is deployed. */
16038
+ interface LiquidityProfile {
16039
+ /** Total value deposited in base-unit amount form. */
16040
+ readonly totalDeposits: Amount;
16041
+ /** Available liquidity in base-unit amount form. */
16042
+ readonly available: Amount;
16043
+ /** Outstanding vault share tokens (ERC4626 totalSupply) in base-unit form. */
16044
+ readonly totalSupply: Amount;
16045
+ /** Current liquidity status. */
16046
+ readonly status: 'active' | 'low_liquidity';
16047
+ }
16048
+ /**
16049
+ * Risk signals for an opportunity.
16050
+ *
16051
+ * @example
16052
+ * ```typescript
16053
+ * const riskSignals: RiskSignals = {
16054
+ * circleSentinel: true,
16055
+ * warnings: [],
16056
+ * earnKitWarnings: [],
16057
+ * }
16058
+ * ```
16059
+ */
16060
+ interface RiskSignals {
16061
+ /** Whether the opportunity is covered by Circle Sentinel. */
16062
+ readonly circleSentinel: boolean;
16063
+ /** Protocol warnings for this opportunity. */
16064
+ readonly warnings?: readonly VaultWarning[] | undefined;
16065
+ /** Circle-specific warnings (e.g., unsupported reward protocol). */
16066
+ readonly earnKitWarnings?: readonly string[] | undefined;
16067
+ }
16068
+ /**
16069
+ * Facets common to every earn opportunity, plus the deprecated flat
16070
+ * fields retained for backward compatibility.
16071
+ *
16072
+ * The flat aliases are emitted by the backend alongside the nested facets
16073
+ * and mapped straight through, so existing consumers keep reading them until
16074
+ * they are removed in a future major release. Narrow on
16075
+ * {@link EarnOpportunity.productType} to access product-specific fields.
16076
+ */
16077
+ interface EarnOpportunityBase {
16078
+ /** Blockchain where the opportunity is deployed. */
15565
16079
  readonly chain: `${EarnChain}`;
15566
- /** Human-readable vault name. */
16080
+ /** Human-readable opportunity name. */
15567
16081
  readonly name: string;
15568
- /** Vault protocol identifier. */
16082
+ /** Protocol identifier. */
15569
16083
  readonly protocol: string;
15570
16084
  /** Underlying deposit asset symbol (e.g., 'USDC'). */
15571
16085
  readonly asset: string;
15572
16086
  /** Underlying deposit asset contract address. */
15573
16087
  readonly assetAddress: string;
15574
- /** Total annualized percentage yield including rewards. */
16088
+ /** Reward tokens distributed by this opportunity. */
16089
+ readonly rewards: readonly VaultRewardInfo[];
16090
+ /** Primary on-chain address (protocol-neutral; replaces vaultAddress). */
16091
+ readonly address?: string | undefined;
16092
+ /** RFC3339 freshness timestamp: provider state ts, else cache sync time. */
16093
+ readonly asOf?: string | undefined;
16094
+ /** Manager/curator identity; `null` when the product has no manager. */
16095
+ readonly manager?: ManagerInfo | null | undefined;
16096
+ /** Yield profile including trailing averages. */
16097
+ readonly apyProfile?: ApyProfile | undefined;
16098
+ /** Fee split. */
16099
+ readonly fee?: FeeInfo | undefined;
16100
+ /** Liquidity profile. */
16101
+ readonly liquidityProfile?: LiquidityProfile | undefined;
16102
+ /** Risk signals. */
16103
+ readonly riskSignals?: RiskSignals | undefined;
16104
+ /** @deprecated use {@link EarnOpportunityBase.address} */
16105
+ readonly vaultAddress: string;
16106
+ /** @deprecated use {@link ApyProfile.current} via apyProfile */
15575
16107
  readonly currentApy: number;
15576
- /** Native APY excluding reward incentives. */
16108
+ /** @deprecated use {@link ApyProfile.native} via apyProfile */
15577
16109
  readonly nativeApy: number;
15578
- /** Vault fee as a decimal (e.g., 0.05 = 5%). */
16110
+ /** @deprecated use {@link FeeInfo.performance} via fee */
15579
16111
  readonly vaultFee: number;
15580
- /** Reward tokens distributed by this vault. */
15581
- readonly rewards: readonly VaultRewardInfo[];
15582
- /** Collateral markets backing this vault. */
15583
- readonly collateral: readonly CollateralInfo[];
15584
- /** Total value deposited in base-unit amount form. */
16112
+ /** @deprecated use {@link LiquidityProfile.totalDeposits} via liquidityProfile */
15585
16113
  readonly totalDeposits: Amount;
15586
- /** Available liquidity in the vault. */
16114
+ /** @deprecated use {@link LiquidityProfile.available} via liquidityProfile */
15587
16115
  readonly liquidity: Amount;
15588
- /** Current vault status. */
16116
+ /** @deprecated use {@link LiquidityProfile.status} via liquidityProfile */
15589
16117
  readonly status: 'active' | 'low_liquidity';
15590
- /** Whether the vault is on Circle's curated Circle-guarded list. */
16118
+ /** @deprecated use {@link RiskSignals.circleSentinel} via riskSignals */
15591
16119
  readonly circleGuarded: boolean;
15592
- /** Morpho protocol warnings for this vault. */
16120
+ /** @deprecated use {@link RiskSignals.warnings} via riskSignals */
15593
16121
  readonly warnings?: readonly VaultWarning[] | undefined;
15594
- /** Circle-specific warnings (e.g., unsupported reward protocol). */
16122
+ /** @deprecated use {@link RiskSignals.earnKitWarnings} via riskSignals */
15595
16123
  readonly earnKitWarnings?: readonly string[] | undefined;
15596
16124
  }
16125
+ /**
16126
+ * A yield-bearing vault opportunity (`productType: 'vault'`).
16127
+ *
16128
+ * Carries the universal {@link EarnOpportunityBase} facets plus the
16129
+ * vault-specific `collateral` markets.
16130
+ *
16131
+ * @example
16132
+ * ```typescript
16133
+ * const vault: VaultOpportunity = {
16134
+ * productType: 'vault',
16135
+ * address: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
16136
+ * chain: 'Arc_Testnet',
16137
+ * name: 'Steakhouse USDC',
16138
+ * protocol: 'MORPHO',
16139
+ * asset: 'USDC',
16140
+ * assetAddress: '0x3600000000000000000000000000000000000000',
16141
+ * asOf: '2026-06-23T18:00:00Z',
16142
+ * manager: { name: 'Steakhouse', address: '0x...', type: 'curator' },
16143
+ * apyProfile: { current: 0.085, native: 0.071, d7: 0.082, d30: 0.079, d90: 0.081, rewardShare: 0.16 },
16144
+ * fee: { performance: 0.1, management: null },
16145
+ * liquidityProfile: {
16146
+ * totalDeposits: Amount.fromJSON({ raw: '15000000000000', decimals: 6 }),
16147
+ * available: Amount.fromJSON({ raw: '5000000000000', decimals: 6 }),
16148
+ * totalSupply: Amount.fromJSON({ raw: '14950000000000000000', decimals: 18 }),
16149
+ * status: 'active',
16150
+ * },
16151
+ * riskSignals: { circleSentinel: true, warnings: [], earnKitWarnings: [] },
16152
+ * rewards: [{ token: 'MORPHO', tokenAddress: '0x...', apy: 0.0075 }],
16153
+ * collateral: [{ asset: 'cbBTC', assetAddress: '0x...', lltv: 0.86, supplyUsd: 50000000.25, allocationPct: 0.6 }],
16154
+ * // deprecated flat aliases (dual-emitted during migration)
16155
+ * vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
16156
+ * currentApy: 0.085,
16157
+ * nativeApy: 0.071,
16158
+ * vaultFee: 0.1,
16159
+ * totalDeposits: Amount.fromJSON({ raw: '15000000000000', decimals: 6 }),
16160
+ * liquidity: Amount.fromJSON({ raw: '5000000000000', decimals: 6 }),
16161
+ * status: 'active',
16162
+ * circleGuarded: true,
16163
+ * }
16164
+ * ```
16165
+ */
16166
+ interface VaultOpportunity extends EarnOpportunityBase {
16167
+ /**
16168
+ * Universal discriminator identifying the opportunity shape.
16169
+ *
16170
+ * Optional for now — a backend that predates the field omits it, matching
16171
+ * the other optional facets — so this release stays source-compatible for
16172
+ * code that constructs the type. A future release makes it required once
16173
+ * every backend emits it. Always present on responses from an emitting
16174
+ * backend; narrow on it before reading product-specific fields.
16175
+ */
16176
+ readonly productType?: 'vault';
16177
+ /** Collateral markets backing this vault. */
16178
+ readonly collateral: readonly CollateralInfo[];
16179
+ }
16180
+ /**
16181
+ * A yield opportunity available through the earn service.
16182
+ *
16183
+ * Modeled as a discriminated union on `productType` over a shared base.
16184
+ * Only the `vault` variant ships today; additional product types (e.g.
16185
+ * `lending_market`, `rwa_token`) are added as additive union members.
16186
+ */
16187
+ type EarnOpportunity = VaultOpportunity;
15597
16188
  /**
15598
16189
  * Per-vault error from a batch vault lookup.
15599
16190
  *
@@ -15773,6 +16364,14 @@ interface AssetAmount {
15773
16364
  */
15774
16365
  readonly status?: string | undefined;
15775
16366
  }
16367
+ /**
16368
+ * Source-fee quote expiry metadata returned by bridge prepare.
16369
+ *
16370
+ * `TIMESTAMP` expiries use an ISO-8601 UTC `expiresAt`; `BLOCK_NUMBER`
16371
+ * expiries use a source-chain `expiresAtBlock`, with an optional ISO-8601 UTC
16372
+ * `blockEstimatedAt` for when that block estimate was produced.
16373
+ */
16374
+ type EarnBridgeQuoteExpiry = Readonly<Exclude<z.infer<typeof bridgeQuoteExpirySchema>, undefined>>;
15776
16375
  /**
15777
16376
  * Result of a deposit operation returned by
15778
16377
  * {@link EarningProvider.deposit}.
@@ -15873,6 +16472,13 @@ interface EarnCrossChainDepositResult {
15873
16472
  * @example '2026-05-19T00:00:00Z'
15874
16473
  */
15875
16474
  readonly expiresAt: string;
16475
+ /** ISO-8601 UTC timestamp at which the source-fee quote was issued. */
16476
+ readonly quoteIssuedAt?: string | undefined;
16477
+ /**
16478
+ * Optional source-fee quote expiry metadata for display and refresh UX.
16479
+ * This deadline is independent of the prepared-bundle `expiresAt` above.
16480
+ */
16481
+ readonly quoteExpiry?: EarnBridgeQuoteExpiry | undefined;
15876
16482
  }
15877
16483
  /**
15878
16484
  * Status of one hop (source relay or destination mint) of a cross-chain
@@ -16349,27 +16955,21 @@ interface DepositQuoteInfo {
16349
16955
  */
16350
16956
  readonly fees: readonly AssetAmount[];
16351
16957
  /**
16352
- * Estimated native gas fees for the transactions needed to deposit
16353
- * (e.g. token approval and the deposit itself).
16958
+ * Estimated native gas fees for the transactions needed to deposit (e.g.
16959
+ * token approval and the deposit itself).
16354
16960
  *
16355
16961
  * Optional so that custom {@link EarningProvider} implementations are not
16356
16962
  * required to produce gas estimates. The bundled Earn Service provider
16357
- * always populates this with one entry per transaction in the flow. When an
16358
- * individual estimate cannot be produced, that entry is still present with
16359
- * `fees` set to `null` and `error` describing why — so a non-empty array
16360
- * does not imply every estimate succeeded; inspect each entry's `fees`.
16361
- *
16362
- * The number of entries depends on where estimation stopped: when the flow
16363
- * fails before the approval step is examined, a single entry named after
16364
- * the main action is returned. Look entries up by `name`, not by index.
16365
- *
16366
- * Each estimate simulates the transaction against current chain state.
16367
- * When a token approval is still pending (typically a first-time deposit),
16368
- * the deposit simulation reverts because the allowance is not yet in
16369
- * place, so the deposit entry resolves with `fees: null` while the
16370
- * approval entry still carries a real estimate. Render a fallback (e.g.
16371
- * "available after approval") for that case rather than treating it as an
16372
- * error.
16963
+ * populates this from the server-side estimate returned on the quote, with
16964
+ * one entry per action. Empty for cross-chain quotes, which resolve no
16965
+ * single source chain.
16966
+ *
16967
+ * Each entry is the Earn Service's estimate for that action, so a pending
16968
+ * token approval no longer causes the deposit entry to fail. An entry may
16969
+ * still carry `fees: null` with an `error` when the service could not
16970
+ * estimate it, so a non-empty array does not imply every estimate
16971
+ * succeeded — inspect each entry's `fees` and look entries up by `name`,
16972
+ * not by index.
16373
16973
  */
16374
16974
  readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
16375
16975
  }
@@ -16410,26 +17010,21 @@ interface WithdrawalQuoteInfo {
16410
17010
  */
16411
17011
  readonly fees: readonly AssetAmount[];
16412
17012
  /**
16413
- * Estimated native gas fees for the transactions needed to withdraw.
17013
+ * Estimated native gas fees for the transactions needed to withdraw (e.g.
17014
+ * vault-share approval and the withdrawal itself).
16414
17015
  *
16415
17016
  * Optional so that custom {@link EarningProvider} implementations are not
16416
17017
  * required to produce gas estimates. The bundled Earn Service provider
16417
- * always populates this with one entry per transaction in the flow. When an
16418
- * individual estimate cannot be produced, that entry is still present with
16419
- * `fees` set to `null` and `error` describing why — so a non-empty array
16420
- * does not imply every estimate succeeded; inspect each entry's `fees`.
16421
- *
16422
- * The number of entries depends on where estimation stopped: when the flow
16423
- * fails before the approval step is examined, a single entry named after
16424
- * the main action is returned. Look entries up by `name`, not by index.
16425
- *
16426
- * Each estimate simulates the transaction against current chain state.
16427
- * When a vault-share approval is still pending (typically the first
16428
- * withdrawal from a vault), the withdrawal simulation reverts because the
16429
- * allowance is not yet in place, so the withdrawal entry resolves with
16430
- * `fees: null` while the approval entry still carries a real estimate.
16431
- * Render a fallback (e.g. "available after approval") for that case
16432
- * rather than treating it as an error.
17018
+ * populates this from the server-side estimate returned on the quote, with
17019
+ * one entry per action. Empty for cross-chain quotes, which resolve no
17020
+ * single source chain.
17021
+ *
17022
+ * Each entry is the Earn Service's estimate for that action, so a pending
17023
+ * vault-share approval no longer causes the withdrawal entry to fail. An
17024
+ * entry may still carry `fees: null` with an `error` when the service could
17025
+ * not estimate it, so a non-empty array does not imply every estimate
17026
+ * succeeded — inspect each entry's `fees` and look entries up by `name`,
17027
+ * not by index.
16433
17028
  */
16434
17029
  readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
16435
17030
  /**
@@ -16462,16 +17057,13 @@ interface ClaimRewardsQuoteInfo {
16462
17057
  /** Reward tokens available for claiming. */
16463
17058
  readonly rewards: readonly AssetAmount[];
16464
17059
  /**
16465
- * Estimated native gas fees for claiming rewards. Empty when there are no
16466
- * rewards to claim.
17060
+ * Estimated native gas fees for claiming rewards.
16467
17061
  *
16468
17062
  * Optional so that custom {@link EarningProvider} implementations are not
16469
- * required to produce gas estimates. Otherwise the bundled Earn Service
16470
- * provider populates this with one entry per claim transaction; when an
16471
- * estimate cannot be produced, that entry is still present with `fees` set
16472
- * to `null` and `error` describing why — so a non-empty array does not imply
16473
- * every estimate succeeded; inspect each entry's `fees`. Look entries up by
16474
- * `name`, not by index.
17063
+ * required to produce gas estimates. The bundled Earn Service provider does
17064
+ * not return a gas estimate for claim-rewards quotes, so this is always
17065
+ * empty (`[]`); it is retained for API symmetry with the deposit and
17066
+ * withdrawal quotes.
16475
17067
  */
16476
17068
  readonly gasFees?: readonly EarnGasFeeEstimate$1[] | undefined;
16477
17069
  }
@@ -16482,8 +17074,8 @@ interface ClaimRewardsQuoteInfo {
16482
17074
  * `vaults` while per-vault failures are in `errors`.
16483
17075
  */
16484
17076
  interface GetVaultsResult {
16485
- /** Successfully resolved vault information. */
16486
- readonly vaults: readonly VaultInfo[];
17077
+ /** Successfully resolved opportunities. */
17078
+ readonly vaults: readonly EarnOpportunity[];
16487
17079
  /** Per-vault errors for failed lookups. */
16488
17080
  readonly errors: readonly VaultError[];
16489
17081
  }
@@ -16536,7 +17128,7 @@ interface ExploreVaultsPagination {
16536
17128
  */
16537
17129
  interface ExploreVaultsResult {
16538
17130
  /** Vaults matching the query, in the requested sort order. */
16539
- readonly vaults: readonly VaultInfo[];
17131
+ readonly vaults: readonly EarnOpportunity[];
16540
17132
  /** Pagination metadata for the query. */
16541
17133
  readonly pagination: ExploreVaultsPagination;
16542
17134
  }
@@ -17192,10 +17784,6 @@ declare class EarnServiceProvider implements EarningProvider {
17192
17784
  supportsRetry(error: unknown): boolean;
17193
17785
  /** {@inheritdoc} */
17194
17786
  retry(error: unknown): Promise<EarnDepositOutcome | EarnWithdrawResult | ClaimRewardsResult>;
17195
- private gasEstimateFailure;
17196
- private estimateDepositQuoteGasFees;
17197
- private estimateWithdrawalQuoteGasFees;
17198
- private estimateClaimRewardsQuoteGasFees;
17199
17787
  /** {@inheritdoc} */
17200
17788
  getDepositQuote<T extends AdapterCapabilities>(params: GetDepositQuoteServiceParams<T>): Promise<DepositQuoteInfo>;
17201
17789
  /** {@inheritdoc} */
@@ -17786,12 +18374,42 @@ type EarnAssetAmount = Omit<AssetAmount, 'amount'> & {
17786
18374
  /** Token amount in human-readable decimal format. */
17787
18375
  readonly amount: string;
17788
18376
  };
17789
- /** Vault information returned by the SDK. */
17790
- type EarnVaultInfo = Omit<VaultInfo, 'totalDeposits' | 'liquidity'> & {
18377
+ /**
18378
+ * Distributive `Omit` over a union.
18379
+ *
18380
+ * A plain `Omit<Union, K>` is not distributive: `keyof (A | B)` collapses to
18381
+ * the shared keys, dropping every variant-specific field and the discriminant
18382
+ * narrowing. Distributing over each member preserves the union.
18383
+ */
18384
+ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
18385
+ /** Liquidity profile returned by the SDK with amounts as decimal strings. */
18386
+ type EarnLiquidityProfile = Omit<LiquidityProfile, 'totalDeposits' | 'available' | 'totalSupply'> & {
18387
+ /** Total value deposited in human-readable decimal format. */
18388
+ readonly totalDeposits: string;
18389
+ /** Available liquidity in human-readable decimal format. */
18390
+ readonly available: string;
18391
+ /** Outstanding vault share tokens (ERC4626 totalSupply) in decimal format. */
18392
+ readonly totalSupply: string;
18393
+ };
18394
+ /**
18395
+ * Vault information returned by the SDK.
18396
+ *
18397
+ * Derived with a distributive `Omit` so each opportunity variant keeps its
18398
+ * product-specific fields and the `productType` discriminant.
18399
+ */
18400
+ type EarnVaultInfo = DistributiveOmit<EarnOpportunity, 'totalDeposits' | 'liquidity' | 'liquidityProfile'> & {
17791
18401
  /** Total value deposited in human-readable decimal format. */
17792
18402
  readonly totalDeposits: string;
17793
18403
  /** Available liquidity in the vault in human-readable decimal format. */
17794
18404
  readonly liquidity: string;
18405
+ /**
18406
+ * Liquidity profile with amounts as human-readable decimal strings.
18407
+ *
18408
+ * Optional during the expand/contract migration window: a backend that
18409
+ * predates the nested facets omits it, so it is absent until the response
18410
+ * carries it.
18411
+ */
18412
+ readonly liquidityProfile?: EarnLiquidityProfile;
17795
18413
  };
17796
18414
  /** Result of a batch vault lookup. */
17797
18415
  type EarnGetVaultsResult = Omit<GetVaultsResult, 'vaults'> & {
@@ -18994,22 +19612,27 @@ declare const getVaultsParamsSchema: z.ZodObject<{
18994
19612
  v1: z.ZodOptional<z.ZodObject<{
18995
19613
  wallet: z.ZodString;
18996
19614
  minter: z.ZodString;
19615
+ depositForHandler: z.ZodOptional<z.ZodString>;
18997
19616
  }, "strict", z.ZodTypeAny, {
18998
19617
  wallet: string;
18999
19618
  minter: string;
19619
+ depositForHandler?: string | undefined;
19000
19620
  }, {
19001
19621
  wallet: string;
19002
19622
  minter: string;
19623
+ depositForHandler?: string | undefined;
19003
19624
  }>>;
19004
19625
  }, "strict", z.ZodTypeAny, {
19005
19626
  v1?: {
19006
19627
  wallet: string;
19007
19628
  minter: string;
19629
+ depositForHandler?: string | undefined;
19008
19630
  } | undefined;
19009
19631
  }, {
19010
19632
  v1?: {
19011
19633
  wallet: string;
19012
19634
  minter: string;
19635
+ depositForHandler?: string | undefined;
19013
19636
  } | undefined;
19014
19637
  }>;
19015
19638
  forwarderSupported: z.ZodObject<{
@@ -19028,6 +19651,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19028
19651
  v1?: {
19029
19652
  wallet: string;
19030
19653
  minter: string;
19654
+ depositForHandler?: string | undefined;
19031
19655
  } | undefined;
19032
19656
  };
19033
19657
  forwarderSupported: {
@@ -19040,6 +19664,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19040
19664
  v1?: {
19041
19665
  wallet: string;
19042
19666
  minter: string;
19667
+ depositForHandler?: string | undefined;
19043
19668
  } | undefined;
19044
19669
  };
19045
19670
  forwarderSupported: {
@@ -19078,6 +19703,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19078
19703
  v1?: {
19079
19704
  wallet: string;
19080
19705
  minter: string;
19706
+ depositForHandler?: string | undefined;
19081
19707
  } | undefined;
19082
19708
  };
19083
19709
  forwarderSupported: {
@@ -19113,6 +19739,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19113
19739
  v1?: {
19114
19740
  wallet: string;
19115
19741
  minter: string;
19742
+ depositForHandler?: string | undefined;
19116
19743
  } | undefined;
19117
19744
  };
19118
19745
  forwarderSupported: {
@@ -19160,22 +19787,27 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19160
19787
  v1: z.ZodOptional<z.ZodObject<{
19161
19788
  wallet: z.ZodString;
19162
19789
  minter: z.ZodString;
19790
+ depositForHandler: z.ZodOptional<z.ZodString>;
19163
19791
  }, "strict", z.ZodTypeAny, {
19164
19792
  wallet: string;
19165
19793
  minter: string;
19794
+ depositForHandler?: string | undefined;
19166
19795
  }, {
19167
19796
  wallet: string;
19168
19797
  minter: string;
19798
+ depositForHandler?: string | undefined;
19169
19799
  }>>;
19170
19800
  }, "strict", z.ZodTypeAny, {
19171
19801
  v1?: {
19172
19802
  wallet: string;
19173
19803
  minter: string;
19804
+ depositForHandler?: string | undefined;
19174
19805
  } | undefined;
19175
19806
  }, {
19176
19807
  v1?: {
19177
19808
  wallet: string;
19178
19809
  minter: string;
19810
+ depositForHandler?: string | undefined;
19179
19811
  } | undefined;
19180
19812
  }>;
19181
19813
  forwarderSupported: z.ZodObject<{
@@ -19194,6 +19826,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19194
19826
  v1?: {
19195
19827
  wallet: string;
19196
19828
  minter: string;
19829
+ depositForHandler?: string | undefined;
19197
19830
  } | undefined;
19198
19831
  };
19199
19832
  forwarderSupported: {
@@ -19206,6 +19839,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19206
19839
  v1?: {
19207
19840
  wallet: string;
19208
19841
  minter: string;
19842
+ depositForHandler?: string | undefined;
19209
19843
  } | undefined;
19210
19844
  };
19211
19845
  forwarderSupported: {
@@ -19242,6 +19876,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19242
19876
  v1?: {
19243
19877
  wallet: string;
19244
19878
  minter: string;
19879
+ depositForHandler?: string | undefined;
19245
19880
  } | undefined;
19246
19881
  };
19247
19882
  forwarderSupported: {
@@ -19276,6 +19911,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19276
19911
  v1?: {
19277
19912
  wallet: string;
19278
19913
  minter: string;
19914
+ depositForHandler?: string | undefined;
19279
19915
  } | undefined;
19280
19916
  };
19281
19917
  forwarderSupported: {
@@ -19311,6 +19947,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19311
19947
  v1?: {
19312
19948
  wallet: string;
19313
19949
  minter: string;
19950
+ depositForHandler?: string | undefined;
19314
19951
  } | undefined;
19315
19952
  };
19316
19953
  forwarderSupported: {
@@ -19345,6 +19982,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19345
19982
  v1?: {
19346
19983
  wallet: string;
19347
19984
  minter: string;
19985
+ depositForHandler?: string | undefined;
19348
19986
  } | undefined;
19349
19987
  };
19350
19988
  forwarderSupported: {
@@ -19380,6 +20018,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19380
20018
  v1?: {
19381
20019
  wallet: string;
19382
20020
  minter: string;
20021
+ depositForHandler?: string | undefined;
19383
20022
  } | undefined;
19384
20023
  };
19385
20024
  forwarderSupported: {
@@ -19414,6 +20053,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19414
20053
  v1?: {
19415
20054
  wallet: string;
19416
20055
  minter: string;
20056
+ depositForHandler?: string | undefined;
19417
20057
  } | undefined;
19418
20058
  };
19419
20059
  forwarderSupported: {
@@ -19452,6 +20092,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19452
20092
  v1?: {
19453
20093
  wallet: string;
19454
20094
  minter: string;
20095
+ depositForHandler?: string | undefined;
19455
20096
  } | undefined;
19456
20097
  };
19457
20098
  forwarderSupported: {
@@ -19486,6 +20127,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19486
20127
  v1?: {
19487
20128
  wallet: string;
19488
20129
  minter: string;
20130
+ depositForHandler?: string | undefined;
19489
20131
  } | undefined;
19490
20132
  };
19491
20133
  forwarderSupported: {
@@ -19524,6 +20166,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19524
20166
  v1?: {
19525
20167
  wallet: string;
19526
20168
  minter: string;
20169
+ depositForHandler?: string | undefined;
19527
20170
  } | undefined;
19528
20171
  };
19529
20172
  forwarderSupported: {
@@ -19558,6 +20201,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19558
20201
  v1?: {
19559
20202
  wallet: string;
19560
20203
  minter: string;
20204
+ depositForHandler?: string | undefined;
19561
20205
  } | undefined;
19562
20206
  };
19563
20207
  forwarderSupported: {
@@ -19605,6 +20249,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19605
20249
  v1?: {
19606
20250
  wallet: string;
19607
20251
  minter: string;
20252
+ depositForHandler?: string | undefined;
19608
20253
  } | undefined;
19609
20254
  };
19610
20255
  forwarderSupported: {
@@ -19639,6 +20284,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19639
20284
  v1?: {
19640
20285
  wallet: string;
19641
20286
  minter: string;
20287
+ depositForHandler?: string | undefined;
19642
20288
  } | undefined;
19643
20289
  };
19644
20290
  forwarderSupported: {
@@ -19682,6 +20328,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19682
20328
  v1?: {
19683
20329
  wallet: string;
19684
20330
  minter: string;
20331
+ depositForHandler?: string | undefined;
19685
20332
  } | undefined;
19686
20333
  };
19687
20334
  forwarderSupported: {
@@ -19716,6 +20363,7 @@ declare const getVaultsParamsSchema: z.ZodObject<{
19716
20363
  v1?: {
19717
20364
  wallet: string;
19718
20365
  minter: string;
20366
+ depositForHandler?: string | undefined;
19719
20367
  } | undefined;
19720
20368
  };
19721
20369
  forwarderSupported: {
@@ -19785,22 +20433,27 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19785
20433
  v1: z.ZodOptional<z.ZodObject<{
19786
20434
  wallet: z.ZodString;
19787
20435
  minter: z.ZodString;
20436
+ depositForHandler: z.ZodOptional<z.ZodString>;
19788
20437
  }, "strict", z.ZodTypeAny, {
19789
20438
  wallet: string;
19790
20439
  minter: string;
20440
+ depositForHandler?: string | undefined;
19791
20441
  }, {
19792
20442
  wallet: string;
19793
20443
  minter: string;
20444
+ depositForHandler?: string | undefined;
19794
20445
  }>>;
19795
20446
  }, "strict", z.ZodTypeAny, {
19796
20447
  v1?: {
19797
20448
  wallet: string;
19798
20449
  minter: string;
20450
+ depositForHandler?: string | undefined;
19799
20451
  } | undefined;
19800
20452
  }, {
19801
20453
  v1?: {
19802
20454
  wallet: string;
19803
20455
  minter: string;
20456
+ depositForHandler?: string | undefined;
19804
20457
  } | undefined;
19805
20458
  }>;
19806
20459
  forwarderSupported: z.ZodObject<{
@@ -19819,6 +20472,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19819
20472
  v1?: {
19820
20473
  wallet: string;
19821
20474
  minter: string;
20475
+ depositForHandler?: string | undefined;
19822
20476
  } | undefined;
19823
20477
  };
19824
20478
  forwarderSupported: {
@@ -19831,6 +20485,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19831
20485
  v1?: {
19832
20486
  wallet: string;
19833
20487
  minter: string;
20488
+ depositForHandler?: string | undefined;
19834
20489
  } | undefined;
19835
20490
  };
19836
20491
  forwarderSupported: {
@@ -19869,6 +20524,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19869
20524
  v1?: {
19870
20525
  wallet: string;
19871
20526
  minter: string;
20527
+ depositForHandler?: string | undefined;
19872
20528
  } | undefined;
19873
20529
  };
19874
20530
  forwarderSupported: {
@@ -19904,6 +20560,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19904
20560
  v1?: {
19905
20561
  wallet: string;
19906
20562
  minter: string;
20563
+ depositForHandler?: string | undefined;
19907
20564
  } | undefined;
19908
20565
  };
19909
20566
  forwarderSupported: {
@@ -19951,22 +20608,27 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19951
20608
  v1: z.ZodOptional<z.ZodObject<{
19952
20609
  wallet: z.ZodString;
19953
20610
  minter: z.ZodString;
20611
+ depositForHandler: z.ZodOptional<z.ZodString>;
19954
20612
  }, "strict", z.ZodTypeAny, {
19955
20613
  wallet: string;
19956
20614
  minter: string;
20615
+ depositForHandler?: string | undefined;
19957
20616
  }, {
19958
20617
  wallet: string;
19959
20618
  minter: string;
20619
+ depositForHandler?: string | undefined;
19960
20620
  }>>;
19961
20621
  }, "strict", z.ZodTypeAny, {
19962
20622
  v1?: {
19963
20623
  wallet: string;
19964
20624
  minter: string;
20625
+ depositForHandler?: string | undefined;
19965
20626
  } | undefined;
19966
20627
  }, {
19967
20628
  v1?: {
19968
20629
  wallet: string;
19969
20630
  minter: string;
20631
+ depositForHandler?: string | undefined;
19970
20632
  } | undefined;
19971
20633
  }>;
19972
20634
  forwarderSupported: z.ZodObject<{
@@ -19985,6 +20647,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19985
20647
  v1?: {
19986
20648
  wallet: string;
19987
20649
  minter: string;
20650
+ depositForHandler?: string | undefined;
19988
20651
  } | undefined;
19989
20652
  };
19990
20653
  forwarderSupported: {
@@ -19997,6 +20660,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
19997
20660
  v1?: {
19998
20661
  wallet: string;
19999
20662
  minter: string;
20663
+ depositForHandler?: string | undefined;
20000
20664
  } | undefined;
20001
20665
  };
20002
20666
  forwarderSupported: {
@@ -20033,6 +20697,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20033
20697
  v1?: {
20034
20698
  wallet: string;
20035
20699
  minter: string;
20700
+ depositForHandler?: string | undefined;
20036
20701
  } | undefined;
20037
20702
  };
20038
20703
  forwarderSupported: {
@@ -20067,6 +20732,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20067
20732
  v1?: {
20068
20733
  wallet: string;
20069
20734
  minter: string;
20735
+ depositForHandler?: string | undefined;
20070
20736
  } | undefined;
20071
20737
  };
20072
20738
  forwarderSupported: {
@@ -20102,6 +20768,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20102
20768
  v1?: {
20103
20769
  wallet: string;
20104
20770
  minter: string;
20771
+ depositForHandler?: string | undefined;
20105
20772
  } | undefined;
20106
20773
  };
20107
20774
  forwarderSupported: {
@@ -20136,6 +20803,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20136
20803
  v1?: {
20137
20804
  wallet: string;
20138
20805
  minter: string;
20806
+ depositForHandler?: string | undefined;
20139
20807
  } | undefined;
20140
20808
  };
20141
20809
  forwarderSupported: {
@@ -20171,6 +20839,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20171
20839
  v1?: {
20172
20840
  wallet: string;
20173
20841
  minter: string;
20842
+ depositForHandler?: string | undefined;
20174
20843
  } | undefined;
20175
20844
  };
20176
20845
  forwarderSupported: {
@@ -20205,6 +20874,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20205
20874
  v1?: {
20206
20875
  wallet: string;
20207
20876
  minter: string;
20877
+ depositForHandler?: string | undefined;
20208
20878
  } | undefined;
20209
20879
  };
20210
20880
  forwarderSupported: {
@@ -20256,6 +20926,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20256
20926
  v1?: {
20257
20927
  wallet: string;
20258
20928
  minter: string;
20929
+ depositForHandler?: string | undefined;
20259
20930
  } | undefined;
20260
20931
  };
20261
20932
  forwarderSupported: {
@@ -20290,6 +20961,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20290
20961
  v1?: {
20291
20962
  wallet: string;
20292
20963
  minter: string;
20964
+ depositForHandler?: string | undefined;
20293
20965
  } | undefined;
20294
20966
  };
20295
20967
  forwarderSupported: {
@@ -20337,6 +21009,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20337
21009
  v1?: {
20338
21010
  wallet: string;
20339
21011
  minter: string;
21012
+ depositForHandler?: string | undefined;
20340
21013
  } | undefined;
20341
21014
  };
20342
21015
  forwarderSupported: {
@@ -20371,6 +21044,7 @@ declare const exploreVaultsParamsSchema: z.ZodObject<{
20371
21044
  v1?: {
20372
21045
  wallet: string;
20373
21046
  minter: string;
21047
+ depositForHandler?: string | undefined;
20374
21048
  } | undefined;
20375
21049
  };
20376
21050
  forwarderSupported: {
@@ -20447,22 +21121,27 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20447
21121
  v1: z.ZodOptional<z.ZodObject<{
20448
21122
  wallet: z.ZodString;
20449
21123
  minter: z.ZodString;
21124
+ depositForHandler: z.ZodOptional<z.ZodString>;
20450
21125
  }, "strict", z.ZodTypeAny, {
20451
21126
  wallet: string;
20452
21127
  minter: string;
21128
+ depositForHandler?: string | undefined;
20453
21129
  }, {
20454
21130
  wallet: string;
20455
21131
  minter: string;
21132
+ depositForHandler?: string | undefined;
20456
21133
  }>>;
20457
21134
  }, "strict", z.ZodTypeAny, {
20458
21135
  v1?: {
20459
21136
  wallet: string;
20460
21137
  minter: string;
21138
+ depositForHandler?: string | undefined;
20461
21139
  } | undefined;
20462
21140
  }, {
20463
21141
  v1?: {
20464
21142
  wallet: string;
20465
21143
  minter: string;
21144
+ depositForHandler?: string | undefined;
20466
21145
  } | undefined;
20467
21146
  }>;
20468
21147
  forwarderSupported: z.ZodObject<{
@@ -20481,6 +21160,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20481
21160
  v1?: {
20482
21161
  wallet: string;
20483
21162
  minter: string;
21163
+ depositForHandler?: string | undefined;
20484
21164
  } | undefined;
20485
21165
  };
20486
21166
  forwarderSupported: {
@@ -20493,6 +21173,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20493
21173
  v1?: {
20494
21174
  wallet: string;
20495
21175
  minter: string;
21176
+ depositForHandler?: string | undefined;
20496
21177
  } | undefined;
20497
21178
  };
20498
21179
  forwarderSupported: {
@@ -20531,6 +21212,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20531
21212
  v1?: {
20532
21213
  wallet: string;
20533
21214
  minter: string;
21215
+ depositForHandler?: string | undefined;
20534
21216
  } | undefined;
20535
21217
  };
20536
21218
  forwarderSupported: {
@@ -20566,6 +21248,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20566
21248
  v1?: {
20567
21249
  wallet: string;
20568
21250
  minter: string;
21251
+ depositForHandler?: string | undefined;
20569
21252
  } | undefined;
20570
21253
  };
20571
21254
  forwarderSupported: {
@@ -20613,22 +21296,27 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20613
21296
  v1: z.ZodOptional<z.ZodObject<{
20614
21297
  wallet: z.ZodString;
20615
21298
  minter: z.ZodString;
21299
+ depositForHandler: z.ZodOptional<z.ZodString>;
20616
21300
  }, "strict", z.ZodTypeAny, {
20617
21301
  wallet: string;
20618
21302
  minter: string;
21303
+ depositForHandler?: string | undefined;
20619
21304
  }, {
20620
21305
  wallet: string;
20621
21306
  minter: string;
21307
+ depositForHandler?: string | undefined;
20622
21308
  }>>;
20623
21309
  }, "strict", z.ZodTypeAny, {
20624
21310
  v1?: {
20625
21311
  wallet: string;
20626
21312
  minter: string;
21313
+ depositForHandler?: string | undefined;
20627
21314
  } | undefined;
20628
21315
  }, {
20629
21316
  v1?: {
20630
21317
  wallet: string;
20631
21318
  minter: string;
21319
+ depositForHandler?: string | undefined;
20632
21320
  } | undefined;
20633
21321
  }>;
20634
21322
  forwarderSupported: z.ZodObject<{
@@ -20647,6 +21335,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20647
21335
  v1?: {
20648
21336
  wallet: string;
20649
21337
  minter: string;
21338
+ depositForHandler?: string | undefined;
20650
21339
  } | undefined;
20651
21340
  };
20652
21341
  forwarderSupported: {
@@ -20659,6 +21348,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20659
21348
  v1?: {
20660
21349
  wallet: string;
20661
21350
  minter: string;
21351
+ depositForHandler?: string | undefined;
20662
21352
  } | undefined;
20663
21353
  };
20664
21354
  forwarderSupported: {
@@ -20695,6 +21385,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20695
21385
  v1?: {
20696
21386
  wallet: string;
20697
21387
  minter: string;
21388
+ depositForHandler?: string | undefined;
20698
21389
  } | undefined;
20699
21390
  };
20700
21391
  forwarderSupported: {
@@ -20729,6 +21420,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20729
21420
  v1?: {
20730
21421
  wallet: string;
20731
21422
  minter: string;
21423
+ depositForHandler?: string | undefined;
20732
21424
  } | undefined;
20733
21425
  };
20734
21426
  forwarderSupported: {
@@ -20764,6 +21456,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20764
21456
  v1?: {
20765
21457
  wallet: string;
20766
21458
  minter: string;
21459
+ depositForHandler?: string | undefined;
20767
21460
  } | undefined;
20768
21461
  };
20769
21462
  forwarderSupported: {
@@ -20798,6 +21491,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20798
21491
  v1?: {
20799
21492
  wallet: string;
20800
21493
  minter: string;
21494
+ depositForHandler?: string | undefined;
20801
21495
  } | undefined;
20802
21496
  };
20803
21497
  forwarderSupported: {
@@ -20833,6 +21527,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20833
21527
  v1?: {
20834
21528
  wallet: string;
20835
21529
  minter: string;
21530
+ depositForHandler?: string | undefined;
20836
21531
  } | undefined;
20837
21532
  };
20838
21533
  forwarderSupported: {
@@ -20867,6 +21562,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20867
21562
  v1?: {
20868
21563
  wallet: string;
20869
21564
  minter: string;
21565
+ depositForHandler?: string | undefined;
20870
21566
  } | undefined;
20871
21567
  };
20872
21568
  forwarderSupported: {
@@ -20918,6 +21614,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20918
21614
  v1?: {
20919
21615
  wallet: string;
20920
21616
  minter: string;
21617
+ depositForHandler?: string | undefined;
20921
21618
  } | undefined;
20922
21619
  };
20923
21620
  forwarderSupported: {
@@ -20952,6 +21649,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20952
21649
  v1?: {
20953
21650
  wallet: string;
20954
21651
  minter: string;
21652
+ depositForHandler?: string | undefined;
20955
21653
  } | undefined;
20956
21654
  };
20957
21655
  forwarderSupported: {
@@ -20998,6 +21696,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
20998
21696
  v1?: {
20999
21697
  wallet: string;
21000
21698
  minter: string;
21699
+ depositForHandler?: string | undefined;
21001
21700
  } | undefined;
21002
21701
  };
21003
21702
  forwarderSupported: {
@@ -21032,6 +21731,7 @@ declare const exploreVaultsIteratorParamsSchema: z.ZodObject<Omit<{
21032
21731
  v1?: {
21033
21732
  wallet: string;
21034
21733
  minter: string;
21734
+ depositForHandler?: string | undefined;
21035
21735
  } | undefined;
21036
21736
  };
21037
21737
  forwarderSupported: {
@@ -21153,22 +21853,27 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21153
21853
  v1: z.ZodOptional<z.ZodObject<{
21154
21854
  wallet: z.ZodString;
21155
21855
  minter: z.ZodString;
21856
+ depositForHandler: z.ZodOptional<z.ZodString>;
21156
21857
  }, "strict", z.ZodTypeAny, {
21157
21858
  wallet: string;
21158
21859
  minter: string;
21860
+ depositForHandler?: string | undefined;
21159
21861
  }, {
21160
21862
  wallet: string;
21161
21863
  minter: string;
21864
+ depositForHandler?: string | undefined;
21162
21865
  }>>;
21163
21866
  }, "strict", z.ZodTypeAny, {
21164
21867
  v1?: {
21165
21868
  wallet: string;
21166
21869
  minter: string;
21870
+ depositForHandler?: string | undefined;
21167
21871
  } | undefined;
21168
21872
  }, {
21169
21873
  v1?: {
21170
21874
  wallet: string;
21171
21875
  minter: string;
21876
+ depositForHandler?: string | undefined;
21172
21877
  } | undefined;
21173
21878
  }>;
21174
21879
  forwarderSupported: z.ZodObject<{
@@ -21187,6 +21892,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21187
21892
  v1?: {
21188
21893
  wallet: string;
21189
21894
  minter: string;
21895
+ depositForHandler?: string | undefined;
21190
21896
  } | undefined;
21191
21897
  };
21192
21898
  forwarderSupported: {
@@ -21199,6 +21905,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21199
21905
  v1?: {
21200
21906
  wallet: string;
21201
21907
  minter: string;
21908
+ depositForHandler?: string | undefined;
21202
21909
  } | undefined;
21203
21910
  };
21204
21911
  forwarderSupported: {
@@ -21237,6 +21944,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21237
21944
  v1?: {
21238
21945
  wallet: string;
21239
21946
  minter: string;
21947
+ depositForHandler?: string | undefined;
21240
21948
  } | undefined;
21241
21949
  };
21242
21950
  forwarderSupported: {
@@ -21272,6 +21980,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21272
21980
  v1?: {
21273
21981
  wallet: string;
21274
21982
  minter: string;
21983
+ depositForHandler?: string | undefined;
21275
21984
  } | undefined;
21276
21985
  };
21277
21986
  forwarderSupported: {
@@ -21319,22 +22028,27 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21319
22028
  v1: z.ZodOptional<z.ZodObject<{
21320
22029
  wallet: z.ZodString;
21321
22030
  minter: z.ZodString;
22031
+ depositForHandler: z.ZodOptional<z.ZodString>;
21322
22032
  }, "strict", z.ZodTypeAny, {
21323
22033
  wallet: string;
21324
22034
  minter: string;
22035
+ depositForHandler?: string | undefined;
21325
22036
  }, {
21326
22037
  wallet: string;
21327
22038
  minter: string;
22039
+ depositForHandler?: string | undefined;
21328
22040
  }>>;
21329
22041
  }, "strict", z.ZodTypeAny, {
21330
22042
  v1?: {
21331
22043
  wallet: string;
21332
22044
  minter: string;
22045
+ depositForHandler?: string | undefined;
21333
22046
  } | undefined;
21334
22047
  }, {
21335
22048
  v1?: {
21336
22049
  wallet: string;
21337
22050
  minter: string;
22051
+ depositForHandler?: string | undefined;
21338
22052
  } | undefined;
21339
22053
  }>;
21340
22054
  forwarderSupported: z.ZodObject<{
@@ -21353,6 +22067,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21353
22067
  v1?: {
21354
22068
  wallet: string;
21355
22069
  minter: string;
22070
+ depositForHandler?: string | undefined;
21356
22071
  } | undefined;
21357
22072
  };
21358
22073
  forwarderSupported: {
@@ -21365,6 +22080,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21365
22080
  v1?: {
21366
22081
  wallet: string;
21367
22082
  minter: string;
22083
+ depositForHandler?: string | undefined;
21368
22084
  } | undefined;
21369
22085
  };
21370
22086
  forwarderSupported: {
@@ -21401,6 +22117,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21401
22117
  v1?: {
21402
22118
  wallet: string;
21403
22119
  minter: string;
22120
+ depositForHandler?: string | undefined;
21404
22121
  } | undefined;
21405
22122
  };
21406
22123
  forwarderSupported: {
@@ -21435,6 +22152,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21435
22152
  v1?: {
21436
22153
  wallet: string;
21437
22154
  minter: string;
22155
+ depositForHandler?: string | undefined;
21438
22156
  } | undefined;
21439
22157
  };
21440
22158
  forwarderSupported: {
@@ -21470,6 +22188,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21470
22188
  v1?: {
21471
22189
  wallet: string;
21472
22190
  minter: string;
22191
+ depositForHandler?: string | undefined;
21473
22192
  } | undefined;
21474
22193
  };
21475
22194
  forwarderSupported: {
@@ -21504,6 +22223,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21504
22223
  v1?: {
21505
22224
  wallet: string;
21506
22225
  minter: string;
22226
+ depositForHandler?: string | undefined;
21507
22227
  } | undefined;
21508
22228
  };
21509
22229
  forwarderSupported: {
@@ -21539,6 +22259,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21539
22259
  v1?: {
21540
22260
  wallet: string;
21541
22261
  minter: string;
22262
+ depositForHandler?: string | undefined;
21542
22263
  } | undefined;
21543
22264
  };
21544
22265
  forwarderSupported: {
@@ -21573,6 +22294,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21573
22294
  v1?: {
21574
22295
  wallet: string;
21575
22296
  minter: string;
22297
+ depositForHandler?: string | undefined;
21576
22298
  } | undefined;
21577
22299
  };
21578
22300
  forwarderSupported: {
@@ -21611,6 +22333,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21611
22333
  v1?: {
21612
22334
  wallet: string;
21613
22335
  minter: string;
22336
+ depositForHandler?: string | undefined;
21614
22337
  } | undefined;
21615
22338
  };
21616
22339
  forwarderSupported: {
@@ -21645,6 +22368,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21645
22368
  v1?: {
21646
22369
  wallet: string;
21647
22370
  minter: string;
22371
+ depositForHandler?: string | undefined;
21648
22372
  } | undefined;
21649
22373
  };
21650
22374
  forwarderSupported: {
@@ -21683,6 +22407,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21683
22407
  v1?: {
21684
22408
  wallet: string;
21685
22409
  minter: string;
22410
+ depositForHandler?: string | undefined;
21686
22411
  } | undefined;
21687
22412
  };
21688
22413
  forwarderSupported: {
@@ -21717,6 +22442,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21717
22442
  v1?: {
21718
22443
  wallet: string;
21719
22444
  minter: string;
22445
+ depositForHandler?: string | undefined;
21720
22446
  } | undefined;
21721
22447
  };
21722
22448
  forwarderSupported: {
@@ -21769,6 +22495,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21769
22495
  v1?: {
21770
22496
  wallet: string;
21771
22497
  minter: string;
22498
+ depositForHandler?: string | undefined;
21772
22499
  } | undefined;
21773
22500
  };
21774
22501
  forwarderSupported: {
@@ -21803,6 +22530,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21803
22530
  v1?: {
21804
22531
  wallet: string;
21805
22532
  minter: string;
22533
+ depositForHandler?: string | undefined;
21806
22534
  } | undefined;
21807
22535
  };
21808
22536
  forwarderSupported: {
@@ -21851,6 +22579,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21851
22579
  v1?: {
21852
22580
  wallet: string;
21853
22581
  minter: string;
22582
+ depositForHandler?: string | undefined;
21854
22583
  } | undefined;
21855
22584
  };
21856
22585
  forwarderSupported: {
@@ -21885,6 +22614,7 @@ declare const anyDepositParamsSchema: z.ZodUnion<[z.ZodObject<{
21885
22614
  v1?: {
21886
22615
  wallet: string;
21887
22616
  minter: string;
22617
+ depositForHandler?: string | undefined;
21888
22618
  } | undefined;
21889
22619
  };
21890
22620
  forwarderSupported: {
@@ -23987,26 +24717,28 @@ interface AppKitContext {
23987
24717
  * Event handlers registered for AppKit operations.
23988
24718
  *
23989
24719
  * This property stores event handlers that are registered via the AppKit's
23990
- * `on()` method. Handlers are grouped by operation type. The current runtime
23991
- * bucket is `bridge`, and the context can add more operation buckets as AppKit
23992
- * wires action handlers for additional kits.
24720
+ * `on()` method. Handlers are grouped by operation type. The runtime buckets
24721
+ * are `bridge` and `earn`; the context can add more operation buckets as
24722
+ * AppKit wires action handlers for additional kits.
23993
24723
  *
23994
- * Within each operation bucket, handlers are keyed by action name (for example,
23995
- * `bridge.approve`) or `*` for wildcard handlers. Each action can have multiple
23996
- * handlers registered, allowing multiple subscribers to listen to the same event.
24724
+ * Within each operation bucket, handlers are keyed by action name (for
24725
+ * example, `bridge.approve` or `earn.deposit`) or `*` for wildcard handlers.
24726
+ * Each action can have multiple handlers registered, allowing multiple
24727
+ * subscribers to listen to the same event.
23997
24728
  *
23998
24729
  * The handlers are stored in the context to allow deferred registration with
23999
- * underlying operation kits, enabling a clean separation between event registration
24000
- * and operation execution.
24730
+ * underlying operation kits, enabling a clean separation between event
24731
+ * registration and operation execution.
24001
24732
  *
24002
24733
  * @example
24003
24734
  * ```typescript
24004
24735
  * const context = createContext()
24005
24736
  * // Handlers registered via kit.on() are stored by operation type
24006
- * // Bridge handlers are registered with BridgeKit when bridge() is executed
24737
+ * // Bridge handlers are registered with BridgeKit when bridge() runs
24738
+ * // Earn handlers are registered with EarnKit when earn operations run
24007
24739
  * ```
24008
24740
  */
24009
- actions: Record<'bridge', Record<string, ((payload: unknown) => void)[]>>;
24741
+ actions: Record<'bridge' | 'earn', Record<string, ((payload: unknown) => void)[]>>;
24010
24742
  /**
24011
24743
  * Disable error telemetry for all sub-kits.
24012
24744
  *
@@ -24032,6 +24764,7 @@ interface AppKitContext {
24032
24764
  * Earn operation namespace exposed as `kit.earn`.
24033
24765
  *
24034
24766
  * Mirrors the operations currently available from `@circle-fin/earn-kit`.
24767
+ * Step events use the AppKit event API (`kit.on('earn.*')` / `kit.on('*')`).
24035
24768
  *
24036
24769
  * @example
24037
24770
  * ```typescript
@@ -24279,6 +25012,40 @@ interface AppKitEarnOperations {
24279
25012
  * @internal
24280
25013
  */
24281
25014
  getClaimRewardsQuote<TFromAdapterCapabilities extends AdapterCapabilities = AdapterCapabilities>(params: GetClaimRewardsQuoteParams<TFromAdapterCapabilities>): Promise<EarnClaimRewardsQuoteInfo>;
25015
+ /**
25016
+ * Resume a multi-phase earn operation that previously failed.
25017
+ *
25018
+ * Pass the {@link KitError} caught from `deposit`, `withdraw`, or
25019
+ * `claimRewards`. The error carries the original inputs and step
25020
+ * progress, so completed phases (for example a successful token
25021
+ * approval) can be skipped. Call `isRetryableError(error)` first.
25022
+ *
25023
+ * @remarks
25024
+ * Retry re-fetches execution params and may re-submit the execute
25025
+ * transaction. Treat this as best-effort recovery: if a prior attempt
25026
+ * broadcast execute but failed before observing the receipt, that
25027
+ * transaction may still be in flight.
25028
+ *
25029
+ * @param error - The error caught from a previous multi-phase earn operation
25030
+ * @returns Promise resolving to the result of the resumed operation
25031
+ * @throws If the error is not retryable or lacks earn retry context
25032
+ *
25033
+ * @example
25034
+ * ```typescript
25035
+ * import { AppKit, isRetryableError } from '@circle-fin/app-kit'
25036
+ *
25037
+ * const kit = new AppKit()
25038
+ *
25039
+ * try {
25040
+ * await kit.earn.deposit(params)
25041
+ * } catch (error) {
25042
+ * if (isRetryableError(error)) {
25043
+ * const result = await kit.earn.retry(error)
25044
+ * }
25045
+ * }
25046
+ * ```
25047
+ */
25048
+ retry(error: unknown): Promise<EarnDepositOutcome | EarnWithdrawResult | EarnClaimRewardsResult>;
24282
25049
  }
24283
25050
  /**
24284
25051
  * Type for event handler functions that can be registered with the AppKit.
@@ -24426,21 +25193,31 @@ type AppKitBridgeActions = PrefixActions<'bridge', DefaultBridgeKitActions>;
24426
25193
  * to namespace them within the AppKit event system.
24427
25194
  */
24428
25195
  type AppKitUnifiedBalanceActions = PrefixActions<'unifiedBalance', GatewayV1Actions>;
25196
+ /**
25197
+ * Prefixed earn actions for AppKit.
25198
+ *
25199
+ * Earn step events are exposed under the `earn.` namespace (for example
25200
+ * `earn.deposit`, `earn.approve`, `earn.withdraw`) so they can be
25201
+ * subscribed to via `kit.on()` alongside bridge and unified balance
25202
+ * events.
25203
+ */
25204
+ type AppKitEarnActions = PrefixActions<'earn', EarnActions>;
24429
25205
  /**
24430
25206
  * Union of all AppKit action names.
24431
25207
  */
24432
- type AppKitActionName = keyof AppKitBridgeActions | keyof AppKitUnifiedBalanceActions;
25208
+ type AppKitActionName = keyof AppKitBridgeActions | keyof AppKitUnifiedBalanceActions | keyof AppKitEarnActions;
24433
25209
  /**
24434
25210
  * All actions available in AppKit.
24435
25211
  */
24436
- type AppKitActions = AppKitBridgeActions & AppKitUnifiedBalanceActions;
25212
+ type AppKitActions = AppKitBridgeActions & AppKitUnifiedBalanceActions & AppKitEarnActions;
24437
25213
 
24438
25214
  /**
24439
25215
  * Parameters for creating a AppKit context.
24440
25216
  *
24441
25217
  * This type allows partial customization of the context while ensuring
24442
25218
  * that all required properties have sensible defaults. Users can override
24443
- * specific methods while keeping the rest intact.
25219
+ * specific methods while keeping the rest intact. Action handler buckets
25220
+ * may also be supplied partially; missing buckets default to empty maps.
24444
25221
  *
24445
25222
  * @example
24446
25223
  * ```typescript
@@ -24452,7 +25229,9 @@ type AppKitActions = AppKitBridgeActions & AppKitUnifiedBalanceActions;
24452
25229
  * })
24453
25230
  * ```
24454
25231
  */
24455
- type CreateContextParams = Partial<AppKitContext>;
25232
+ type CreateContextParams = Omit<Partial<AppKitContext>, 'actions'> & {
25233
+ actions?: Partial<AppKitContext['actions']>;
25234
+ };
24456
25235
 
24457
25236
  /**
24458
25237
  * Destination for a Gateway spend (mint) operation.
@@ -24830,10 +25609,13 @@ interface ResolvedSpendParams<TFromAdapterCapabilities extends AdapterCapabiliti
24830
25609
  */
24831
25610
  type SpendFeeFunction = (params: ResolvedSpendParams) => Promise<string> | string;
24832
25611
  /**
24833
- * Function that resolves the fee recipient address for a given source chain.
24834
- * Called once per source chain in a multi-chain spend.
25612
+ * Function that resolves the fee recipient address for a spend.
25613
+ * Called once per spend, against the resolved **destination** chain
25614
+ * every fee burn intent in a spend mints to that single chain
25615
+ * regardless of which source chain(s) funded it, so only one
25616
+ * recipient address (valid on the destination chain) is ever needed.
24835
25617
  */
24836
- type SpendFeeRecipientFunction = (feePayoutChain: ChainDefinition, params: ResolvedSpendParams) => Promise<string> | string;
25618
+ type SpendFeeRecipientFunction = (destinationChain: ChainDefinition, params: ResolvedSpendParams) => Promise<string> | string;
24837
25619
  /**
24838
25620
  * Policy for computing and routing custom developer fees.
24839
25621
  *
@@ -24843,11 +25625,54 @@ type SpendFeeRecipientFunction = (feePayoutChain: ChainDefinition, params: Resol
24843
25625
  * Fields that only exist after resolution (e.g. per-source allocations)
24844
25626
  * may be `undefined`. Implementations should only rely on top-level
24845
25627
  * fields such as `to`, `token`, and `amount`.
25628
+ *
25629
+ * @remarks
25630
+ * `resolveFeeRecipientAddress` is optional when you configure
25631
+ * {@link UnifiedBalanceKit.setFeeRecipients} instead — the declarative
25632
+ * map takes priority over this callback when both are present. Provide
25633
+ * exactly one of the two; a policy with neither throws at spend time.
24846
25634
  */
24847
25635
  interface CustomFeePolicy {
24848
25636
  computeFee: SpendFeeFunction;
24849
- resolveFeeRecipientAddress: SpendFeeRecipientFunction;
25637
+ resolveFeeRecipientAddress?: SpendFeeRecipientFunction;
24850
25638
  }
25639
+ /**
25640
+ * Chain type group used to key {@link FeeRecipientsConfig}.
25641
+ *
25642
+ * @remarks
25643
+ * Only `'evm'` and `'solana'` are live today (the only chain types the
25644
+ * kit's provider currently supports). This is deliberately a narrow
25645
+ * subset of `@core/chains`' broader `ChainType` union rather than a
25646
+ * hardcoded two-field struct, so that support for additional non-EVM
25647
+ * chain types (e.g. Stellar, Starknet) can be added later by adding
25648
+ * new union members here — no restructuring of `FeeRecipientsConfig`
25649
+ * or its consumers required.
25650
+ */
25651
+ type FeeRecipientChainType = 'evm' | 'solana';
25652
+ /**
25653
+ * Declarative map of fee recipient addresses, keyed by chain type.
25654
+ *
25655
+ * @remarks
25656
+ * Set via {@link UnifiedBalanceKit.setFeeRecipients}. At spend time the
25657
+ * kit resolves the spend's destination chain to its
25658
+ * {@link FeeRecipientChainType} and looks up the matching entry —
25659
+ * exactly one recipient is used per spend (see
25660
+ * {@link SpendFeeRecipientFunction}). Provide entries for every chain
25661
+ * type you expect to spend to; a spend to a destination chain type
25662
+ * with no matching entry throws before any fee collection is
25663
+ * attempted.
25664
+ *
25665
+ * @example
25666
+ * ```typescript
25667
+ * import type { FeeRecipientsConfig } from '@circle-fin/unified-balance-kit'
25668
+ *
25669
+ * const feeRecipients: FeeRecipientsConfig = {
25670
+ * evm: '0x1234567890123456789012345678901234567890',
25671
+ * solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
25672
+ * }
25673
+ * ```
25674
+ */
25675
+ type FeeRecipientsConfig = Partial<Record<FeeRecipientChainType, string>>;
24851
25676
  /**
24852
25677
  * Fee category describing the origin of a fee line item.
24853
25678
  *
@@ -26161,6 +26986,43 @@ declare class AppKitUnifiedBalance {
26161
26986
  * ```
26162
26987
  */
26163
26988
  removeCustomFeePolicy(): void;
26989
+ /**
26990
+ * Set a declarative fee recipient map, keyed by chain type.
26991
+ *
26992
+ * Once set, `spend()`/`estimateSpend()` resolve the fee recipient by
26993
+ * looking up the spend's destination chain type in this map — taking
26994
+ * priority over `customFeePolicy`'s `resolveFeeRecipientAddress`
26995
+ * callback.
26996
+ *
26997
+ * @remarks
26998
+ * This only controls which address a fee is sent to — it does not by
26999
+ * itself cause any fee to be charged. You still need
27000
+ * `setCustomFeePolicy`'s `computeFee` to determine the fee amount;
27001
+ * calling `setFeeRecipients` without ever calling `setCustomFeePolicy`
27002
+ * throws at spend time (there is no `computeFee` to determine an
27003
+ * amount).
27004
+ *
27005
+ * @param config - Fee recipient addresses keyed by chain type (e.g.
27006
+ * `{ evm: '0x...', solana: 'Sol...' }`).
27007
+ *
27008
+ * @example
27009
+ * ```typescript
27010
+ * kit.unifiedBalance.setFeeRecipients({
27011
+ * evm: '0x1234567890123456789012345678901234567890',
27012
+ * solana: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
27013
+ * })
27014
+ * ```
27015
+ */
27016
+ setFeeRecipients(config: FeeRecipientsConfig): void;
27017
+ /**
27018
+ * Remove the declarative fee recipient map.
27019
+ *
27020
+ * @example
27021
+ * ```typescript
27022
+ * kit.unifiedBalance.removeFeeRecipients()
27023
+ * ```
27024
+ */
27025
+ removeFeeRecipients(): void;
26164
27026
  }
26165
27027
 
26166
27028
  interface DeveloperFeeHooks {
@@ -26559,7 +27421,8 @@ declare class AppKit {
26559
27421
  * or `'NOT_FOUND'`). Use {@link AppKit.waitForSwap} if you'd rather
26560
27422
  * not write the polling loop yourself.
26561
27423
  *
26562
- * @param params - `txHash`, `chainIn`, optional `chainOut`, and `kitKey`.
27424
+ * @param params - `txHash` and `chainIn`, plus optional `chainOut` and
27425
+ * `kitKey`.
26563
27426
  * @returns A snapshot of the swap's status at the time of the call.
26564
27427
  * @throws \{KitError\} If `chainIn` or `chainOut` is malformed.
26565
27428
  *
@@ -26671,7 +27534,7 @@ declare class AppKit {
26671
27534
  * translates to the chain's native sentinel address — `0xEee…` for EVM,
26672
27535
  * `1111…` for Solana — before querying the service.
26673
27536
  *
26674
- * @param params - `chain`, optional `tokens`, and `kitKey`.
27537
+ * @param params - `chain`, plus optional `tokens` and `kitKey`.
26675
27538
  * @returns A nested map of `[chain][address] → { priceUSD, fetchedAt }`.
26676
27539
  * @throws \{KitError\} If `chain` is malformed, `tokens` exceeds 100
26677
27540
  * entries, or any entry is neither a registered symbol nor a
@@ -26725,17 +27588,16 @@ declare class AppKit {
26725
27588
  /**
26726
27589
  * Register an event handler for a specific AppKit action.
26727
27590
  *
26728
- * Subscribe to events emitted during bridge or unified balance operations.
26729
- * Bridge events are prefixed with 'bridge.' and unified balance events
26730
- * with 'unifiedBalance.' to namespace them within the AppKit event system.
27591
+ * Subscribe to step events from bridge, earn, or unified balance
27592
+ * operations. Action names are namespaced: `bridge.*`, `earn.*`, and
27593
+ * `unifiedBalance.*`. Use `'*'` to receive every action.
26731
27594
  *
26732
- * Handlers receive strongly-typed payloads based on the action name. Multiple
26733
- * handlers can be registered for the same action, and all will be invoked when
26734
- * the action occurs. Use the wildcard '*' to listen to all actions.
27595
+ * Handlers receive strongly-typed payloads for the chosen action.
27596
+ * Multiple handlers may be registered for the same action.
26735
27597
  *
26736
27598
  * @typeParam K - The action name to listen for
26737
27599
  * @param action - The namespaced action name or '*' for all actions
26738
- * @param handler - Callback function to invoke when the action occurs
27600
+ * @param handler - Callback invoked when the action occurs
26739
27601
  *
26740
27602
  * @example
26741
27603
  * ```typescript
@@ -26748,6 +27610,11 @@ declare class AppKit {
26748
27610
  * console.log('Approval transaction:', payload.values.txHash)
26749
27611
  * })
26750
27612
  *
27613
+ * // Listen to earn deposit steps
27614
+ * kit.on('earn.deposit', (payload) => {
27615
+ * console.log('Earn deposit step:', payload.values.state)
27616
+ * })
27617
+ *
26751
27618
  * // Listen to unified balance action
26752
27619
  * kit.on('unifiedBalance.gateway.spend.succeeded', (payload) => {
26753
27620
  * console.log('Spend succeeded:', payload.data)
@@ -26792,6 +27659,16 @@ declare class AppKit {
26792
27659
  */
26793
27660
  off<K extends AppKitActionName>(action: K, handler: (payload: AppKitActions[K]) => void): void;
26794
27661
  off(action: '*', handler: (payload: AppKitActions[keyof AppKitActions]) => void): void;
27662
+ /**
27663
+ * Remove one handler from a deferred AppKit action bucket.
27664
+ *
27665
+ * Deletes the action key when its handler list becomes empty.
27666
+ *
27667
+ * @param handlers - Action bucket to update (`bridge` or `earn`)
27668
+ * @param action - Stored action key, including namespace or `*`
27669
+ * @param handler - Handler reference previously passed to {@link on}
27670
+ */
27671
+ private removeStoredActionHandler;
26795
27672
  }
26796
27673
 
26797
27674
  /**
@@ -26911,4 +27788,4 @@ declare function isTokenAddress(token: string, chain: ChainDefinition): token is
26911
27788
  declare function validateToken(token: string, chain: ChainDefinition): TokenValidationResult;
26912
27789
 
26913
27790
  export { AppKit, AppKitUnifiedBalance, BalanceError, Blockchain, BridgeChain, EarnChain, EarnError, EarnKit, InputError, KitError, NetworkError, OnchainError, RateLimitError, RpcError, ServiceError, SwapChain, TOKEN_ALIASES, TransferSpeed, UnifiedBalanceChain, anyDepositParamsSchema, claimRewardsParamsSchema, createEarnKitContext, depositParamsSchema, claimRewards as earnClaimRewards, deposit as earnDeposit, exploreVaults as earnExploreVaults, exploreVaultsIterator as earnExploreVaultsIterator, getClaimRewardsQuote as earnGetClaimRewardsQuote, getCrossChainDepositStatus as earnGetCrossChainDepositStatus, getCrossChainDepositStatusOutcome as earnGetCrossChainDepositStatusOutcome, getDepositQuote as earnGetDepositQuote, getPosition as earnGetPosition, getSupportedChains as earnGetSupportedChains, getVaults as earnGetVaults, getWithdrawalQuote as earnGetWithdrawalQuote, waitForCrossChainDeposit as earnWaitForCrossChainDeposit, withdraw as earnWithdraw, exploreVaultsIteratorParamsSchema, exploreVaultsParamsSchema, getClaimRewardsQuoteParamsSchema, getCrossChainDepositStatusParamsSchema, getDepositQuoteParamsSchema, getErrorCode, getErrorMessage, getPositionParamsSchema, getTokenDecimals, getVaultsParamsSchema, getWithdrawalQuoteParamsSchema, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRateLimitError, isRetryableError, isRpcError, isServiceError, isTerminalCrossChainDepositStatus as isTerminalEarnCrossChainDepositStatus, isTokenAddress, isTokenAlias, isUserCancellationError, setExternalPrefix, validateToken, waitForCrossChainDepositParamsSchema, withdrawParamsSchema };
26914
- export type { ActionHandler, AdapterContext, AllowanceStrategy$2 as AllowanceStrategy, AppKitActionName, AppKitActions, AppKitBridgeActions, AppKitConfig, AppKitContext, AppKitEarnOperations, AppKitUnifiedBalanceActions, BaseChainDefinition, BridgeConfig, CustomFeePolicy$2 as BridgeCustomFeePolicy, BridgeParams, BridgeResult, BridgeStep, CCTPConfig, CCTPMergedConfig, CCTPSplitConfig, ChainDefinition, Currency, DelegateStatus, DepositForParams, DepositParams, DepositResult, DeveloperFeeHooks, EVMChainDefinition, EarnAccruedRewardInfo, EarnAdapterContext, AnyDepositParams as EarnAnyDepositParams, EarnAssetAmount, EarnBridgeCctpStatus, EarnBridgeHopStatus, ClaimRewardsParams as EarnClaimRewardsParams, EarnClaimRewardsQuoteInfo, EarnClaimRewardsResult, EarnClaimedAmount, EarnClaimedRewardsResult, EarnConfig, EarnCrossChainDepositDestination, CrossChainDepositParams as EarnCrossChainDepositParams, EarnCrossChainDepositResult, EarnCrossChainDepositStatus, EarnCrossChainDepositWaitOutcome, EarnCrossChainDepositWaitResult, CrossChainGetDepositQuoteParams as EarnCrossChainGetDepositQuoteParams, EarnDepositOutcome, DepositParams$2 as EarnDepositParams, EarnDepositQuoteInfo, EarnDepositResult, ExploreVaultsIteratorParams as EarnExploreVaultsIteratorParams, ExploreVaultsPagination as EarnExploreVaultsPagination, ExploreVaultsParams as EarnExploreVaultsParams, EarnExploreVaultsResult, ExploreVaultsSortBy as EarnExploreVaultsSortBy, EarnGasFeeEstimate, EarnGasFeeEstimateBase, GetClaimRewardsQuoteParams as EarnGetClaimRewardsQuoteParams, GetCrossChainDepositStatusParams as EarnGetCrossChainDepositStatusParams, GetDepositQuoteParams as EarnGetDepositQuoteParams, GetPositionParams as EarnGetPositionParams, GetVaultsParams as EarnGetVaultsParams, EarnGetVaultsResult, GetWithdrawalQuoteParams as EarnGetWithdrawalQuoteParams, EarnKitConfig, EarnKitContext, EarnOperationParams, EarnPositionInfo, EarnPositionPnLInfo, EarningProvider as EarnProvider, SameChainDepositParams as EarnSameChainDepositParams, EarnSameChainDepositResult, SameChainGetDepositQuoteParams as EarnSameChainGetDepositQuoteParams, EarnServiceConfig, EarnVaultInfo, VaultQuery as EarnVaultQuery, WaitForCrossChainDepositParams as EarnWaitForCrossChainDepositParams, WithdrawParams as EarnWithdrawParams, EarnWithdrawResult, EarnWithdrawalQuoteInfo, ErrorDetails, EstimateResult$1 as EstimateResult, EstimateSpendResult, EstimatedGas, FeeOperationType, GetBalancesParams, GetBalancesResult, GetDelegateStatusParams, GetSupportedChainsOptions, GetSwapStatusParams, GetTokenRatesParams, GetTokenRatesResult, InitiateRemoveFundParams, InitiateRemoveFundResult, KitContractType, NonEVMChainDefinition, OperationParamsMap, OperationType, Recoverability, RemoveFundParams, RemoveFundResult, RetryContext, SendParams, SpendDestination, SpendParams, SpendResult, SwapConfig, CustomFeePolicy$1 as SwapCustomFeePolicy, SwapDestinationLeg, SwapEstimate, SwapFeeContext, SwapKitConfig, SwapKitContext, SwapParams, SwapProgress, SwapResult, SwapSourceLeg, SwapStatus, SwapStatusResult, SwapTerminalStatus, TokenInfo, TokenRate, UnifiedBalanceChainIdentifier, CustomFeePolicy as UnifiedBalanceCustomFeePolicy, UnifiedBalanceKitConfig, SupportedToken as UnifiedBalanceSupportedToken, UpdateDelegateParams, UpdateDelegateResult, VersionConfig, WaitForSwapDiscreteParams, WaitForSwapParams, WaitForSwapResultParams };
27791
+ export type { ActionHandler, AdapterContext, AllowanceStrategy$2 as AllowanceStrategy, AppKitActionName, AppKitActions, AppKitBridgeActions, AppKitConfig, AppKitContext, AppKitEarnActions, AppKitEarnOperations, AppKitUnifiedBalanceActions, BaseChainDefinition, BridgeConfig, CustomFeePolicy$2 as BridgeCustomFeePolicy, BridgeParams, BridgeResult, BridgeStep, CCTPConfig, CCTPMergedConfig, CCTPSplitConfig, ChainDefinition, Currency, DelegateStatus, DepositForParams, DepositParams, DepositResult, DeveloperFeeHooks, EVMChainDefinition, EarnAccruedRewardInfo, EarnAdapterContext, AnyDepositParams as EarnAnyDepositParams, EarnAssetAmount, EarnBridgeCctpStatus, EarnBridgeHopStatus, EarnBridgeQuoteExpiry, ClaimRewardsParams as EarnClaimRewardsParams, EarnClaimRewardsQuoteInfo, EarnClaimRewardsResult, EarnClaimedAmount, EarnClaimedRewardsResult, EarnConfig, EarnCrossChainDepositDestination, CrossChainDepositParams as EarnCrossChainDepositParams, EarnCrossChainDepositResult, EarnCrossChainDepositStatus, EarnCrossChainDepositWaitOutcome, EarnCrossChainDepositWaitResult, CrossChainGetDepositQuoteParams as EarnCrossChainGetDepositQuoteParams, EarnDepositOutcome, DepositParams$2 as EarnDepositParams, EarnDepositQuoteInfo, EarnDepositResult, ExploreVaultsIteratorParams as EarnExploreVaultsIteratorParams, ExploreVaultsPagination as EarnExploreVaultsPagination, ExploreVaultsParams as EarnExploreVaultsParams, EarnExploreVaultsResult, ExploreVaultsSortBy as EarnExploreVaultsSortBy, EarnGasFeeEstimate, EarnGasFeeEstimateBase, GetClaimRewardsQuoteParams as EarnGetClaimRewardsQuoteParams, GetCrossChainDepositStatusParams as EarnGetCrossChainDepositStatusParams, GetDepositQuoteParams as EarnGetDepositQuoteParams, GetPositionParams as EarnGetPositionParams, GetVaultsParams as EarnGetVaultsParams, EarnGetVaultsResult, GetWithdrawalQuoteParams as EarnGetWithdrawalQuoteParams, EarnKitConfig, EarnKitContext, EarnOperationParams, EarnPositionInfo, EarnPositionPnLInfo, EarningProvider as EarnProvider, SameChainDepositParams as EarnSameChainDepositParams, EarnSameChainDepositResult, SameChainGetDepositQuoteParams as EarnSameChainGetDepositQuoteParams, EarnServiceConfig, EarnVaultInfo, VaultQuery as EarnVaultQuery, WaitForCrossChainDepositParams as EarnWaitForCrossChainDepositParams, WithdrawParams as EarnWithdrawParams, EarnWithdrawResult, EarnWithdrawalQuoteInfo, ErrorDetails, EstimateResult$1 as EstimateResult, EstimateSpendResult, EstimatedGas, FeeOperationType, GetBalancesParams, GetBalancesResult, GetDelegateStatusParams, GetSupportedChainsOptions, GetSwapStatusParams, GetTokenRatesParams, GetTokenRatesResult, InitiateRemoveFundParams, InitiateRemoveFundResult, KitContractType, NonEVMChainDefinition, OperationParamsMap, OperationType, Recoverability, RemoveFundParams, RemoveFundResult, RetryContext, SendParams, SpendDestination, SpendParams, SpendResult, SwapConfig, CustomFeePolicy$1 as SwapCustomFeePolicy, SwapDestinationLeg, SwapEstimate, SwapFeeContext, SwapKitConfig, SwapKitContext, SwapParams, SwapProgress, SwapResult, SwapSourceLeg, SwapStatus, SwapStatusResult, SwapTerminalStatus, TokenInfo, TokenRate, UnifiedBalanceChainIdentifier, CustomFeePolicy as UnifiedBalanceCustomFeePolicy, FeeRecipientsConfig as UnifiedBalanceFeeRecipientsConfig, UnifiedBalanceKitConfig, SupportedToken as UnifiedBalanceSupportedToken, UpdateDelegateParams, UpdateDelegateResult, VersionConfig, WaitForSwapDiscreteParams, WaitForSwapParams, WaitForSwapResultParams };