@circle-fin/app-kit 1.9.0 → 1.10.0

package/bridge.mjs

@@ -20,9 +20,9 @@ import { z } from 'zod';
 import pino from 'pino';
 import { formatUnits as formatUnits$1, parseUnits as parseUnits$1 } from '@ethersproject/units';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
+import '@ethersproject/abi';
 import { getAddress } from '@ethersproject/address';
 import bs58 from 'bs58';
-import '@ethersproject/abi';
 import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
@@ -3094,7 +3094,10 @@ var EarnChain;
         contracts: {
             v1: {
                 wallet: GATEWAY_WALLET_EVM_TESTNET,
-                minter: GATEWAY_MINTER_EVM_TESTNET
+                minter: GATEWAY_MINTER_EVM_TESTNET,
+                // DepositForHandler the GenericExecutor calls to run a fast cross-chain
+                // deposit into the GatewayWallet above.
+                depositForHandler: '0xD05E7D2E7d30b92c5F17d7d0fC575fce231F1A48'
             }
         },
         forwarderSupported: {
@@ -6212,7 +6215,10 @@ var Chains = /*#__PURE__*/Object.freeze({
     minter: z.string({
         required_error: 'Gateway minter address is required. Please provide a valid contract address.',
         invalid_type_error: 'Gateway minter address must be a string.'
-    }).min(1, 'Gateway minter address cannot be empty.')
+    }).min(1, 'Gateway minter address cannot be empty.'),
+    depositForHandler: z.string({
+        invalid_type_error: 'Gateway depositForHandler address must be a string.'
+    }).min(1, 'Gateway depositForHandler address cannot be empty.').optional()
 }).strict() // Reject any additional properties not defined in the schema
 ;
 /**
@@ -6734,21 +6740,31 @@ const swapTokenEnumSchema = z.enum([
  * returning the appropriate address based on the requested contract type.
  *
  * @param chain - The chain definition to resolve the contract address for
- * @param contractType - The type of contract address to resolve ('tokenMessenger' or 'messageTransmitter')
+ * @param contractType - The type of contract address to resolve ('tokenMessenger', 'messageTransmitter', or 'tokenMessengerWithFees')
  * @returns The contract address for the specified contract type
  * @throws Error when chain does not support CCTP v2 or has unsupported contract configuration
+ * @throws Error when 'tokenMessengerWithFees' is requested but not configured on the chain
  */ const resolveCCTPV2ContractAddress = (chain, contractType)=>{
     // Handle custom bridge contract for tokenMessenger (burn transaction)
-    if (hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
+    if (contractType === 'tokenMessenger' && hasCustomContractSupport(chain, 'bridge') && chain.kitContracts?.bridge !== undefined) {
         return chain.kitContracts.bridge;
     }
     // At this point we know CCTP v2 is supported, so contracts exist
     const cctpConfig = chain.cctp;
     const contracts = cctpConfig.contracts.v2;
+    // The `TokenMessengerWithFees` wrapper (prepaid FORWARD path) is an optional
+    // deployment carried alongside both split and merged configurations.
+    if (contractType === 'tokenMessengerWithFees') {
+        const wrapper = contracts.tokenMessengerWithFees;
+        if (wrapper === undefined || wrapper === '') {
+            throw new Error(`TokenMessengerWithFees is not configured on chain ${chain.name}. The prepaid FORWARD path is unavailable on this chain.`);
+        }
+        return wrapper;
+    }
     // Handle different contract types with explicit type checking
     switch(contracts.type){
         case 'split':
-            return contracts.tokenMessenger ;
+            return contractType === 'tokenMessenger' ? contracts.tokenMessenger : contracts.messageTransmitter;
         case 'merged':
             return contracts.contract;
         default:
@@ -9603,7 +9619,7 @@ function resolveOptions(options) {
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$3 = "1.12.0";
+var version$3 = "1.12.1";
 var pkg$3 = {
 	name: name$2,
 	version: version$3};
@@ -12107,6 +12123,144 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
     return false;
 };
 
+/**
+ * The zero address, denoting a native-currency fee in a signed quote.
+ */ const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+/**
+ * Resolve the fee payment channel for a prepaid-FORWARD burn via `TokenMessengerWithFees`.
+ *
+ * Determines the native `msg.value` and the ERC-20 approvals required, honouring
+ * the quote's `feeToken`:
+ * - Native fee (`feeToken` is the zero address): attach exactly `feeTotalAmount`
+ *   as `msg.value`; approve only the burn amount.
+ * - ERC-20 fee equal to the burn token (both USDC — the `isBurnTokenFee` case):
+ *   approve a single combined `amount + feeTotalAmount` and skip the redundant
+ *   second approval.
+ * - ERC-20 fee different from the burn token: approve the burn amount and the fee
+ *   amount separately.
+ *
+ * This encodes only balance/allowance intent; it does not fetch balances. The
+ * caller is responsible for a balance preflight against the fresh quote.
+ *
+ * @param params - The fee token, burn token, burn amount, and total fee amount.
+ * @returns The resolved fee payment plan.
+ * @throws KitError if `amount` or `feeTotalAmount` is negative.
+ *
+ * @example
+ * ```typescript
+ * // Native fee
+ * resolveFeePayment({
+ *   feeToken: '0x0000000000000000000000000000000000000000',
+ *   burnToken: '0xUSDC...',
+ *   amount: 1_000_000n,
+ *   feeTotalAmount: 3_500_000n,
+ * })
+ * // → { isNativeFee: true, isBurnTokenFee: false, nativeValue: 3_500_000n,
+ * //     approvals: [{ token: '0xUSDC...', amount: 1_000_000n }] }
+ * ```
+ */ const resolveFeePayment = (params)=>{
+    const { feeToken, burnToken, amount, feeTotalAmount } = params;
+    if (typeof amount !== 'bigint' || amount < 0n) {
+        throw createValidationFailedError$1('amount', amount, 'Must be a non-negative bigint');
+    }
+    if (typeof feeTotalAmount !== 'bigint' || feeTotalAmount < 0n) {
+        throw createValidationFailedError$1('feeTotalAmount', feeTotalAmount, 'Must be a non-negative bigint');
+    }
+    const isNativeFee = feeToken.toLowerCase() === ZERO_ADDRESS;
+    const isBurnTokenFee = !isNativeFee && feeToken.toLowerCase() === burnToken.toLowerCase();
+    if (isNativeFee) {
+        return {
+            isNativeFee: true,
+            isBurnTokenFee: false,
+            nativeValue: feeTotalAmount,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount
+                }
+            ]
+        };
+    }
+    if (isBurnTokenFee) {
+        // Fee and burn draw on the same token — a single combined approval covers
+        // both; the redundant second approval is skipped.
+        return {
+            isNativeFee: false,
+            isBurnTokenFee: true,
+            nativeValue: 0n,
+            approvals: [
+                {
+                    token: burnToken,
+                    amount: amount + feeTotalAmount
+                }
+            ]
+        };
+    }
+    return {
+        isNativeFee: false,
+        isBurnTokenFee: false,
+        nativeValue: 0n,
+        approvals: [
+            {
+                token: burnToken,
+                amount
+            },
+            {
+                token: feeToken,
+                amount: feeTotalAmount
+            }
+        ]
+    };
+};
+
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ */ const CCTP_FORWARD_MAGIC_HEX = Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+/**
+ * Determine whether a hookData blob begins with the `cctp-forward` envelope.
+ *
+ * The prepaid FORWARD path requires the GenericExecutor blob to be wrapped in a
+ * `cctp-forward` frame; without it the wrapper reverts `ForwardFeeWithoutHook`.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @returns True when the hookData starts with the `cctp-forward` magic.
+ *
+ * @example
+ * ```typescript
+ * hasForwardHook('0x636374702d666f7277617264...') // true
+ * hasForwardHook('0xdeadbeef') // false
+ * ```
+ */ const hasForwardHook = (hookData)=>{
+    if (typeof hookData !== 'string') {
+        return false;
+    }
+    const normalized = (hookData.startsWith('0x') ? hookData.slice(2) : hookData).toLowerCase();
+    return normalized.startsWith(CCTP_FORWARD_MAGIC_HEX);
+};
+/**
+ * Assert that a hookData blob is forward-friendly for the prepaid FORWARD path.
+ *
+ * The prepaid FORWARD path always requests a FORWARD fee item, so the wrapper
+ * requires the hookData to start with a `cctp-forward` frame. Validating this
+ * before the burn surfaces the guaranteed `ForwardFeeWithoutHook` revert as a
+ * typed input error instead of an on-chain failure.
+ *
+ * @param hookData - The 0x-prefixed hookData hex string.
+ * @throws KitError (`INPUT_VALIDATION_FAILED`) if the hookData is missing or lacks
+ *   the `cctp-forward` frame.
+ *
+ * @example
+ * ```typescript
+ * assertForwardHookData(geForwardHookData) // ok
+ * assertForwardHookData('0xdeadbeef') // throws — would revert ForwardFeeWithoutHook
+ * ```
+ */ const assertForwardHookData = (hookData)=>{
+    if (!hasForwardHook(hookData)) {
+        throw createValidationFailedError$1('hookData', hookData, 'Prepaid FORWARD burns require a cctp-forward-wrapped hookData; without it the TokenMessengerWithFees wrapper reverts ForwardFeeWithoutHook');
+    }
+};
+
 /**
  * Type guard to validate the forwardFee object structure.
  *
@@ -13038,6 +13192,109 @@ const assertCCTPv2BridgeParamsSymbol = Symbol('assertCCTPv2BridgeParams');
     }
 }
 
+/**
+ * Assert that `params` is a well-formed {@link BurnWithFeesParams} object.
+ *
+ * Validates the full public-boundary input before any field destructuring,
+ * `BigInt()` coercion, or adapter preparation runs, so malformed JS-caller
+ * inputs always produce typed `KitError` validation failures.
+ *
+ * Checks performed (in order):
+ * - `params` must be a non-null plain object
+ * - `source` — valid CCTP v2 wallet context (via `assertCCTPv2WalletContext`)
+ * - `destinationChain` — present and supports CCTP v2
+ * - source and destination chains must both be testnet or both mainnet
+ * - source and destination chains must differ
+ * - `executor` — non-empty string
+ * - `amount` — bigint or non-empty string coercible to bigint
+ * - `feeTotalAmount` — bigint or non-empty string coercible to bigint
+ * - `feeToken` — valid EVM address (`0x` + 40 hex chars)
+ * - `claim.signedQuote` — valid `0x`-prefixed hex string
+ * - `claim.refundAddress` — valid EVM address
+ * - `hookData` — valid `0x`-prefixed hex string when present
+ *
+ * @param params - The value to validate.
+ * @throws {KitError} If any field is missing or invalid.
+ *
+ * @example
+ * ```typescript
+ * assertBurnWithFeesParams(params)
+ * // params is now typed as BurnWithFeesParams and safe to use
+ * const { source, destinationChain, amount } = params
+ * ```
+ */ function assertBurnWithFeesParams(params) {
+    if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+        throw createValidationFailedError$1('params', params, 'Must be a non-null plain object');
+    }
+    const p = params;
+    // Source wallet context
+    assertCCTPv2WalletContext(p['source']);
+    const source = p['source'];
+    // destinationChain
+    const destinationChain = p['destinationChain'];
+    if (destinationChain === null || destinationChain === undefined || typeof destinationChain !== 'object') {
+        throw createValidationFailedError$1('destinationChain', destinationChain, 'Must be a chain definition object');
+    }
+    if (!isCCTPV2Supported(destinationChain)) {
+        throw createValidationFailedError$1('destinationChain', destinationChain, 'destinationChain must support CCTP v2');
+    }
+    const dest = destinationChain;
+    // Testnet / mainnet mismatch
+    if (source.chain.isTestnet !== dest.isTestnet) {
+        throw createNetworkMismatchError(source.chain, dest);
+    }
+    // Same-chain guard
+    if (source.chain.name === dest.name) {
+        throw createUnsupportedRouteError(source.chain.name, dest.name);
+    }
+    // executor
+    const executor = p['executor'];
+    if (typeof executor !== 'string' || executor === '') {
+        throw createValidationFailedError$1('executor', executor, 'A GenericExecutor address is required (used for both mintRecipient and destinationCaller)');
+    }
+    // amount
+    const rawAmount = p['amount'];
+    if (typeof rawAmount !== 'bigint' && typeof rawAmount !== 'string' || rawAmount === '') {
+        throw createValidationFailedError$1('amount', rawAmount, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawAmount);
+    } catch  {
+        throw createValidationFailedError$1('amount', rawAmount, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeTotalAmount
+    const rawFee = p['feeTotalAmount'];
+    if (typeof rawFee !== 'bigint' && typeof rawFee !== 'string' || rawFee === '') {
+        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a bigint or a numeric string');
+    }
+    try {
+        BigInt(rawFee);
+    } catch  {
+        throw createValidationFailedError$1('feeTotalAmount', rawFee, 'Must be a valid integer value coercible to bigint');
+    }
+    // feeToken
+    if (!evmAddressSchema.safeParse(p['feeToken']).success) {
+        throw createValidationFailedError$1('feeToken', p['feeToken'], 'Must be a valid EVM address (use the zero address for a native fee)');
+    }
+    // claim
+    const rawClaim = p['claim'];
+    if (rawClaim === null || typeof rawClaim !== 'object' || Array.isArray(rawClaim)) {
+        throw createValidationFailedError$1('claim', rawClaim, 'Must be an object with signedQuote and refundAddress');
+    }
+    const claim = rawClaim;
+    if (!hexStringSchema.safeParse(claim['signedQuote']).success) {
+        throw createValidationFailedError$1('claim.signedQuote', claim['signedQuote'], 'Must be a valid hex string starting with 0x');
+    }
+    if (!evmAddressSchema.safeParse(claim['refundAddress']).success) {
+        throw createValidationFailedError$1('claim.refundAddress', claim['refundAddress'], 'Must be a valid EVM address');
+    }
+    // hookData (optional)
+    const hookData = p['hookData'];
+    if (hookData !== undefined && hookData !== '' && !hexStringSchema.safeParse(hookData).success) {
+        throw createValidationFailedError$1('hookData', hookData, 'Must be a valid hex string starting with 0x');
+    }
+}
+
 /**
  * CCTP bridge step names that can occur in the bridging flow.
  *
@@ -14246,10 +14503,15 @@ const mockAttestationMessage = {
     const burnCallData = burnRequest.getCallData();
     // batchExecute may throw before submission (wallet declined) but never
     // after — post-submission errors are returned as empty receipts.
+    // The sender is threaded for adapters whose execution is routed through a
+    // signing strategy (which has no wallet account to read it from); the
+    // wallet-client path ignores it.
     const batchResult = await adapter.batchExecute([
         approveCallData,
         burnCallData
-    ], chain);
+    ], chain, {
+        fromAddress: params.source.address
+    });
     const approveReceipt = batchResult.receipts[0];
     const burnReceipt = batchResult.receipts[1];
     const approveStep = await buildBatchedStep('approve', approveReceipt, batchResult.batchId, adapter, chain, batchResult.statusCode, batchResult.error);
@@ -14392,7 +14654,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$2 = "1.9.0";
+var version$2 = "1.10.0";
 var pkg$2 = {
 	version: version$2};
 
@@ -15547,7 +15809,7 @@ function assertCCTPV2Config(config) {
             throw new Error(`Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
         }
         // Resolve spender address with proper error handling
-        const spenderAddress = resolveCCTPV2ContractAddress(chain);
+        const spenderAddress = resolveCCTPV2ContractAddress(chain, 'tokenMessenger');
         // Prepare action parameters
         const actionParams = {
             amount: BigInt(amount),
@@ -16027,6 +16289,106 @@ function assertCCTPV2Config(config) {
         return await source.adapter.prepareAction('cctp.v2.depositForBurn', actionParams, resolvedContext);
     }
     /**
+   * Prepare a prepaid-FORWARD burn through the `TokenMessengerWithFees` wrapper.
+   *
+   * Builds the source-chain `depositForBurnWithHookAndFees` call for the
+   * GenericExecutor FORWARD path: fees are collected up front on the source chain
+   * against a signed quote, `mintRecipient` and `destinationCaller` are both set to
+   * the GenericExecutor, and the GE `hookData` is passed through unchanged.
+   *
+   * This is the low-level on-chain primitive behind the UBK `fastCrossChainDeposit`
+   * and Bridge Kit `bridge({ deposit })` flows. The `hookData` and signed-quote
+   * `claim` are produced elsewhere and passed in here:
+   * - `hookData`: `buildForwardingHookDataWithPayload(version,
+   *   buildDepositForGenericExecutorPayload(...).hookData)` from `@core/utils`.
+   * - `claim.signedQuote` / `feeToken` / `feeTotalAmount`: from `fetchFeeQuote`
+   *   (`@circle-fin/provider-fee-v1`), whose FORWARD item must be bound to the
+   *   SAME `hookData` and executor `destinationCaller` used here.
+   *
+   * The returned approvals and burn are NOT executed — the caller executes the
+   * approvals first (in order) and then the burn. The fee payment channel matches
+   * the quote's `feeToken`:
+   * - Native fee: exactly `feeTotalAmount` is attached as the burn's `msg.value`;
+   *   only the burn amount is approved.
+   * - USDC fee (same token as the burn): a single combined `amount + feeTotalAmount`
+   *   approval covers both; the redundant second approval is skipped.
+   *
+   * @typeParam TFromAdapterCapabilities - The source adapter's capabilities.
+   * @param params - The burn amount, executor, hookData, signed-quote claim, and fee.
+   * @returns The prepared approvals, the prepared burn, and the resolved fee plan.
+   * @throws {KitError} If the wallet context is invalid, `destinationChain` does not
+   *   support CCTP v2, the executor is missing, `amount` or `feeTotalAmount` is not
+   *   a bigint or a numeric string coercible to bigint, the hookData lacks a
+   *   `cctp-forward` frame (guaranteed `ForwardFeeWithoutHook`), or the operation
+   *   context cannot be resolved.
+   *
+   * @example
+   * ```typescript
+   * const { approvals, burn } = await provider.burnWithFees({
+   *   source,
+   *   destinationChain: Arc,
+   *   amount: 1_000_000n,
+   *   executor: genericExecutorAddress,
+   *   hookData: geForwardHookData,
+   *   claim: { signedQuote: '0x01...', refundAddress: userAddress },
+   *   feeToken: '0x0000000000000000000000000000000000000000', // native
+   *   feeTotalAmount: 3_500_000n,
+   * })
+   * for (const approval of approvals) await approval.execute()
+   * const txHash = await burn.execute()
+   * ```
+   */ async burnWithFees(params) {
+        assertBurnWithFeesParams(params);
+        const { source, destinationChain, executor, hookData, claim, feeToken } = params;
+        const amount = BigInt(params.amount);
+        const feeTotalAmount = BigInt(params.feeTotalAmount);
+        // Coupling guard: the prepaid FORWARD path always requests a FORWARD fee item,
+        // so the hookData must carry a cctp-forward frame; otherwise the wrapper
+        // reverts ForwardFeeWithoutHook. Surface it as a typed input error up front.
+        assertForwardHookData(hookData);
+        const burnToken = source.chain.usdcAddress;
+        const feePayment = resolveFeePayment({
+            feeToken,
+            burnToken,
+            amount,
+            feeTotalAmount
+        });
+        // Resolve operation context from the source wallet context.
+        const operationContext = this.extractOperationContext(source);
+        let resolvedContext;
+        try {
+            resolvedContext = await resolveOperationContext(source.adapter, operationContext);
+        } catch (error) {
+            throw createValidationFailedError$1('source.adapter', undefined, `Failed to resolve operation context: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const context = resolvedContext;
+        const wrapperAddress = resolveCCTPV2ContractAddress(source.chain, 'tokenMessengerWithFees');
+        // Build the ERC-20 approvals to the wrapper (burn token, plus a distinct fee
+        // token only when the fee is not paid in the burn token).
+        const approvals = await Promise.all(feePayment.approvals.map(async (approval)=>source.adapter.prepareAction('token.approve', {
+                tokenAddress: approval.token,
+                delegate: wrapperAddress,
+                amount: approval.amount
+            }, context)));
+        // Build the burn: mintRecipient AND destinationCaller are both the executor.
+        const burn = await source.adapter.prepareAction('cctp.v2.depositForBurnWithFees', {
+            fromChain: source.chain,
+            toChain: destinationChain,
+            amount,
+            mintRecipient: executor,
+            destinationCaller: executor,
+            hookData,
+            claim,
+            feeToken,
+            feeTotalAmount
+        }, context);
+        return {
+            approvals,
+            burn,
+            feePayment
+        };
+    }
+    /**
    * Waits for a transaction to be mined and confirmed on the blockchain.
    *
    * This method should block until the transaction is confirmed on the blockchain.
@@ -16906,7 +17268,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.3.2";
+var version$1 = "1.4.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -16971,7 +17333,10 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
     }).min(1, 'kitKey must be a non-empty string').optional(),
     provider: z.string({
         invalid_type_error: 'provider must be a string'
-    }).min(1, 'provider must be a non-empty string').optional()
+    }).min(1, 'provider must be a non-empty string').optional(),
+    batchTransactions: z.boolean({
+        invalid_type_error: 'batchTransactions must be a boolean'
+    }).optional()
 });
 /**
  * Zod schema for adapter context.
@@ -17410,7 +17775,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
      * Circle Stablecoin Service API Key.
      * Must be a valid API key format.
-     */ apiKey: apiKeySchema
+     */ apiKey: apiKeySchema.optional()
 }).superRefine(requireCrossChainQuoteToAddress);
 /**
  * Zod schema for validating CreateSwapRequest parameters.
@@ -17468,7 +17833,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     /**
    * Circle Stablecoin Service API Key.
    * Must be a valid API key format.
-   */ apiKey: apiKeySchema
+   */ apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetSwapStatusResponse data.
@@ -17504,7 +17869,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     toChain: z.string({
         invalid_type_error: 'toChain must be a string'
     }).min(1, 'toChain must be a non-empty string if provided').optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating CreateSwapResponse payloads.
@@ -17513,13 +17878,15 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'fee token is required',
         invalid_type_error: 'fee token must be a string'
     }).min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema
+    amount: feeAmountSchema,
+    decimals: z.number().int('fee token decimals must be an integer').nonnegative('fee token decimals must be a non-negative integer').optional(),
+    symbol: z.string({
+        invalid_type_error: 'fee token symbol must be a string'
+    }).min(1, 'fee token symbol must be a non-empty string').optional()
 });
 /**
  * Developer fee item schema with basis field.
- */ const createSwapDeveloperFeeItemSchema = z.object({
-    token: z.string().min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema,
+ */ const createSwapDeveloperFeeItemSchema = createSwapFeeItemSchema.extend({
     basis: z.enum([
         'inputAmount',
         'estimatedAmount'
@@ -17611,7 +17978,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     addresses: z.array(z.string({
         invalid_type_error: 'addresses entries must be strings'
     }).min(1, 'addresses entries must be non-empty strings')).min(1, 'addresses must contain at least one entry when provided').max(MAX_RATE_ADDRESSES_PER_REQUEST, `addresses supports at most ${String(MAX_RATE_ADDRESSES_PER_REQUEST)} values per request`).optional(),
-    apiKey: apiKeySchema
+    apiKey: apiKeySchema.optional()
 });
 /**
  * Zod schema for validating GetTokenRatesResponse payloads.
@@ -18834,7 +19201,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
 var name = "@circle-fin/earn-kit";
-var version = "1.2.2";
+var version = "1.3.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -18964,7 +19331,11 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     asset: z.string(),
     assetAddress: z.string(),
     lltv: z.number(),
-    supplyUsd: z.number()
+    supplyUsd: z.number(),
+    // Optional during the expand/contract window (a backend that predates the
+    // field omits the key), mirroring the `.optional()` facets on the base
+    // schema; `null` when the product exposes no per-market allocation (V2).
+    allocationPct: z.number().nullable().optional()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -18978,7 +19349,74 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     ])
 });
 /**
- * Zod schema for a single vault info object in the API response.
+ * Zod schema for the manager (curator) facet in the API response.
+ *
+ * @internal
+ */ const managerSchema = z.object({
+    name: z.string(),
+    address: z.string().optional(),
+    // Only 'curator' is emitted today (Morpho V1/V2). Additional manager roles
+    // are added here as the providers that emit them land, rather than shipped
+    // speculatively.
+    type: z.enum([
+        'curator'
+    ])
+});
+/**
+ * Zod schema for the APY profile facet in the API response.
+ *
+ * @internal
+ */ const apyProfileSchema = z.object({
+    current: z.number(),
+    native: z.number().nullable(),
+    d7: z.number().nullable(),
+    d30: z.number().nullable(),
+    d90: z.number().nullable(),
+    rewardShare: z.number().nullable(),
+    source: z.string().optional(),
+    asOf: z.string().optional()
+});
+/**
+ * Zod schema for the fee split facet in the API response.
+ *
+ * @internal
+ */ const feeInfoSchema = z.object({
+    performance: z.number().nullable(),
+    management: z.number().nullable()
+});
+/**
+ * Zod schema for the liquidity profile facet in the API response.
+ *
+ * `totalSupply` is the outstanding vault share tokens (ERC4626 totalSupply);
+ * it is validated as a raw JSON amount, like `totalDeposits`/`available`.
+ *
+ * @internal
+ */ const liquidityProfileSchema = z.object({
+    totalDeposits: amountJsonSchema,
+    available: amountJsonSchema,
+    totalSupply: amountJsonSchema,
+    status: z.enum([
+        'active',
+        'low_liquidity'
+    ])
+});
+/**
+ * Zod schema for the risk signals facet in the API response.
+ *
+ * @internal
+ */ const riskSignalsSchema = z.object({
+    circleSentinel: z.boolean(),
+    warnings: z.array(vaultWarningSchema).optional(),
+    earnKitWarnings: z.array(z.string()).optional()
+});
+/**
+ * Zod schema for the universal earn-opportunity base in the API response.
+ *
+ * Retains every existing deprecated flat field (kept validated through the
+ * expand/contract window so default-strip does not drop them) and adds the
+ * new nested facets. The nested facets are `.optional()` during the
+ * transition so the SDK still validates against a not-yet-fully-deployed
+ * backend; they become required after Expand ships.
  *
  * @internal
  */ const vaultInfoResponseSchema = z.object({
@@ -19003,6 +19441,96 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     warnings: z.array(vaultWarningSchema).optional(),
     earnKitWarnings: z.array(z.string()).optional()
 });
+/**
+ * Shared base schema: existing flat fields (kept) plus the new nested
+ * facets and neutral identity. Facets are `.optional()` during the
+ * transition; flip to required once the backend is confirmed emitting.
+ *
+ * @internal
+ */ const earnBaseSchema = vaultInfoResponseSchema.extend({
+    address: z.string().optional(),
+    asOf: z.string().optional(),
+    manager: managerSchema.nullable().optional(),
+    apyProfile: apyProfileSchema.optional(),
+    fee: feeInfoSchema.optional(),
+    liquidityProfile: liquidityProfileSchema.optional(),
+    riskSignals: riskSignalsSchema.optional()
+});
+/**
+ * Zod schema for the `vault` opportunity variant.
+ *
+ * @internal
+ */ const vaultOpportunitySchema = earnBaseSchema.extend({
+    productType: z.literal('vault'),
+    collateral: z.array(collateralSchema)
+});
+/**
+ * Discriminated union over `productType`. Add union members here as new
+ * product types (e.g. `lending_market`, `rwa_token`) land.
+ *
+ * @internal
+ */ const earnOpportunityVariants = [
+    vaultOpportunitySchema
+];
+/** @internal */ const earnOpportunitySchema = z.discriminatedUnion('productType', earnOpportunityVariants);
+/** Product types this SDK version knows how to parse. */ const knownProductTypes = new Set(earnOpportunityVariants.map((variant)=>variant.shape.productType.value));
+/**
+ * Tolerant list parser for earn opportunities.
+ *
+ * `z.discriminatedUnion` throws on an unrecognized discriminant and
+ * `z.array` fails the whole array if any element fails. Two migration-window
+ * cases are smoothed over here so neither breaks an already-shipped SDK:
+ *
+ * - A backend that predates `productType` omits it entirely. `'vault'` was the
+ *   only opportunity type then, so default a missing discriminant to `'vault'`
+ *   rather than dropping every vault the backend returns.
+ * - A future backend adds a *second* `productType` this SDK version does not
+ *   know. Drop those elements (a present-but-unrecognized discriminant) instead
+ *   of rejecting the whole list.
+ *
+ * Only the drop above is a *tolerant* case. Anything that is not a plain object
+ * with a present-but-unknown string `productType` — `null`, `undefined`,
+ * primitives, or an object whose `productType` is malformed — is passed through
+ * untouched so `z.array(earnOpportunitySchema)` reports it as a normal
+ * validation failure. It is deliberately not silently dropped (which would hide
+ * malformed backend data) and never throws here (an unguarded property read on
+ * a non-object would escape `safeParse` as a raw `TypeError` instead of a
+ * `ZodError`).
+ *
+ * @internal
+ */ const earnOpportunityListSchema = z.preprocess((raw)=>{
+    if (!Array.isArray(raw)) {
+        return raw;
+    }
+    // Array.isArray narrows `raw` to `any[]`; view it as `unknown[]` so the
+    // map/filter chain stays type-safe and no `any` leaks into the return.
+    const entries = raw;
+    return entries.map((entry)=>{
+        // Only touch plain objects; non-objects fall through to fail validation.
+        if (typeof entry !== 'object' || entry === null) {
+            return entry;
+        }
+        const record = entry;
+        // Older backend predating productType: default to the only type then.
+        return record.productType === undefined ? {
+            ...record,
+            productType: 'vault'
+        } : record;
+    }).filter((entry)=>{
+        // Drop ONLY a present-but-unknown string discriminant (a future
+        // productType this SDK version doesn't know). Everything else —
+        // non-objects, a non-string productType — flows through to
+        // z.array(earnOpportunitySchema) and fails/passes validation normally.
+        if (typeof entry !== 'object' || entry === null) {
+            return true;
+        }
+        const productType = entry.productType;
+        if (typeof productType !== 'string') {
+            return true;
+        }
+        return knownProductTypes.has(productType);
+    });
+}, z.array(earnOpportunitySchema));
 // ---------------------------------------------------------------------------
 // Position response schema
 // ---------------------------------------------------------------------------
@@ -19132,6 +19660,7 @@ const positionPnlSchema = z.discriminatedUnion('status', [
  *
  * @internal
  */ const depositPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: depositExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -19223,6 +19752,21 @@ const bridgeDepositPrepareReviewSchema = z.object({
     amount: amountJsonSchema,
     vaultAddress: hexAddressSchema
 }).passthrough();
+/** @internal */ const bridgeQuoteExpirySchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('TIMESTAMP'),
+        expiresAt: z.string().datetime({
+            offset: true
+        })
+    }),
+    z.object({
+        mode: z.literal('BLOCK_NUMBER'),
+        expiresAtBlock: z.number().int(),
+        blockEstimatedAt: z.string().datetime({
+            offset: true
+        }).optional()
+    })
+]).optional().catch(undefined);
 /**
  * Zod schema for the bridge deposit prepare payload.
  *
@@ -19234,6 +19778,10 @@ const bridgeDepositPrepareReviewSchema = z.object({
     execId: bridgeDepositExecIdSchema,
     erc3009TypedData: bridgeDepositPreparedBundleSchema,
     expiresAt: z.string().datetime(),
+    quoteIssuedAt: z.string().datetime({
+        offset: true
+    }).optional().catch(undefined),
+    quoteExpiry: bridgeQuoteExpirySchema,
     review: bridgeDepositPrepareReviewSchema
 });
 /**
@@ -19299,6 +19847,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const withdrawPayloadSchema = z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: withdrawExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -19312,6 +19861,27 @@ const bridgeDepositPrepareReviewSchema = z.object({
     data: withdrawPayloadSchema
 });
 // ---------------------------------------------------------------------------
+// Transaction report response schema
+// ---------------------------------------------------------------------------
+/**
+ * Zod schema for the transaction report payload inside the API `data` envelope.
+ *
+ * The Earn Service returns an empty payload (`{"data":{}}`) on success, so the
+ * schema accepts any object shape and does not require specific fields.
+ *
+ * @internal
+ */ const transactionReportPayloadSchema = z.object({}).passthrough();
+/**
+ * Zod schema for the `POST /v1/earnKit/transactions/report` API response.
+ *
+ * The Earn Service API wraps the transaction report payload in a `data`
+ * envelope.
+ *
+ * @internal
+ */ z.object({
+    data: transactionReportPayloadSchema
+});
+// ---------------------------------------------------------------------------
 // Claim rewards response schema
 // ---------------------------------------------------------------------------
 /**
@@ -19372,6 +19942,30 @@ const bridgeDepositPrepareReviewSchema = z.object({
     token: z.string(),
     amount: amountJsonSchema
 });
+/**
+ * Zod schema for a native gas-fee entry in an EarnKit quote response.
+ *
+ * The Earn Service backend estimates gas server-side and returns one entry per
+ * action (`Approve`, `Deposit`, `Withdraw`). A successful estimate carries
+ * `fees` in the SDK `EstimatedGas` shape (`{ gas, gasPrice, fee }`), each a raw
+ * integer string in the chain's native base units. When the backend cannot
+ * estimate an action it returns `fees: null` with an `error` message instead.
+ *
+ * The schema deliberately validates almost nothing beyond the envelope: `name`
+ * is optional and `fees` is entirely unvalidated (`unknown`). ALL validation
+ * of `fees` — that it is an object at all, and that `gas`, `gasPrice`, and
+ * `fee` are parseable integer strings — is deferred to {@link toQuoteGasFees},
+ * which degrades a malformed entry to a `fees: null` soft failure. This is
+ * intentional: gas is best-effort, so a single unparseable gas entry (a wrong
+ * type such as `fees: 123` or `fees: 'bad'`, a missing field, or a non-numeric
+ * `fee`) must never fail Zod validation and reject the entire quote.
+ *
+ * @internal
+ */ const quoteGasFeeSchema = z.object({
+    name: z.string().optional(),
+    fees: z.unknown(),
+    error: z.string().optional()
+}).passthrough();
 /**
  * Zod schema for the inner deposit quote payload.
  *
@@ -19387,7 +19981,8 @@ const bridgeDepositPrepareReviewSchema = z.object({
     expectedShares: amountJsonSchema,
     sharePrice: z.string(),
     currentApy: z.number(),
-    fees: z.array(feeSchema).optional()
+    fees: z.array(feeSchema).optional(),
+    gasFees: z.array(quoteGasFeeSchema).optional()
 });
 /**
  * Zod schema for the `POST /v1/earnKit/deposit/quote` API response.
@@ -19414,6 +20009,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
     sharePrice: z.string(),
     maxWithdrawable: amountJsonSchema,
     fees: z.array(feeSchema),
+    gasFees: z.array(quoteGasFeeSchema).optional(),
     warnings: z.array(z.string()).optional()
 });
 /**
@@ -19471,7 +20067,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const getVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     errors: z.array(vaultErrorSchema)
 });
 /**
@@ -19501,7 +20097,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
  *
  * @internal
  */ const exploreVaultsPayloadSchema = z.object({
-    vaults: z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     pagination: explorePaginationSchema
 });
 /**