@circle-fin/app-kit 1.9.0 → 1.11.0

package/earn.cjs

@@ -18,15 +18,29 @@
 
 'use strict';
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+const { Buffer } = require('buffer');
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 var zod = require('zod');
 require('pino');
+require('@ethersproject/bytes');
+require('@ethersproject/abi');
+require('@ethersproject/address');
 var web3_js = require('@solana/web3.js');
 require('bn.js');
 require('@coral-xyz/anchor');
 require('bs58');
 require('@noble/curves/ed25519');
-var keccak256 = require('@ethersproject/keccak256');
 var units = require('@ethersproject/units');
+var keccak256 = require('@ethersproject/keccak256');
 
 // Import global type declarations
 /**
@@ -43,6 +57,51 @@ var units = require('@ethersproject/units');
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Check whether the current runtime exposes a browser DOM.
+ *
+ * @remarks
+ * This intentionally does not treat every non-Node runtime as a browser.
+ * Server-side edge runtimes such as Cloudflare Workers, Deno, and Supabase
+ * Edge Functions do not expose Node globals but can safely use server
+ * credentials. A Node.js runtime remains server-side even when a test or SSR
+ * environment provides a DOM shim.
+ *
+ * @returns `true` when running in a browser window, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { isBrowserEnvironment } from '@core/utils'
+ *
+ * if (isBrowserEnvironment()) {
+ *   throw new Error('Server-only secrets must not be used in the browser')
+ * }
+ * ```
+ */ const isBrowserEnvironment = ()=>{
+    const browserWindow = globalThis.window;
+    return !isNodeEnvironment() && browserWindow?.document !== undefined;
+};
+/**
+ * Return the SDK User-Agent request header only when running in Node.js.
+ *
+ * Browsers forbid manually setting `User-Agent`, and a custom fallback header
+ * can trigger CORS preflight. Non-Node server runtimes also omit this optional
+ * attribution header because they cannot set it reliably.
+ *
+ * @returns A User-Agent header in Node.js, or an empty object otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { getNodeUserAgentHeader } from '@core/utils'
+ *
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
+ * }
+ * ```
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -1761,14 +1820,14 @@ class KitError extends Error {
 }
 
 /**
- * Standardized error definitions for Earn/Zenith operations.
+ * Standardized error definitions for Earn operations.
  *
  * These error codes provide fine-grained categorization of failures
- * from the Zenith earn service, enabling SDK consumers to distinguish
+ * from the Earn service, enabling SDK consumers to distinguish
  * between input errors (fix your request) and service errors (retry later).
  *
  * Error code ranges:
- * - 1100-1105: INPUT errors — invalid inputs, unsupported configurations
+ * - 1100-1106: INPUT errors — invalid, unsupported, or stale request state
  * - 8100-8105: SERVICE errors — retryable backend/provider failures
  *
  * @example
@@ -1821,6 +1880,14 @@ class KitError extends Error {
         name: 'EARN_UNSUPPORTED_BRIDGE_ROUTE',
         type: 'INPUT'
     },
+    /**
+   * The bridge quote expired. This is an INPUT error because the prepared
+   * request is stale and must be replaced instead of retried.
+   */ BRIDGE_QUOTE_EXPIRED: {
+        code: 1106,
+        name: 'EARN_BRIDGE_QUOTE_EXPIRED',
+        type: 'INPUT'
+    },
     /** The proxy signing call failed — retryable. */ SIGNING_FAILED: {
         code: 8100,
         name: 'EARN_SIGNING_FAILED',
@@ -1880,6 +1947,9 @@ function getOptionalString(value) {
  *   internal-error, vault-refresh-busy, off-chain-paused, position-PnL-pending,
  *   bridge failures/status lookup failures
  *
+ * Quote expiry is INPUT/FATAL because callers must start a fresh bridge prepare
+ * flow rather than retry the stale prepared bundle.
+ *
  * Unrecognized codes fall through to `parseApiError` for HTTP-status-based
  * handling.
  *
@@ -2113,6 +2183,13 @@ function getOptionalString(value) {
             errorDef: EarnError.PROVIDER_ERROR,
             recoverability: 'FATAL'
         }
+    ],
+    [
+        380506,
+        {
+            errorDef: EarnError.BRIDGE_QUOTE_EXPIRED,
+            recoverability: 'FATAL'
+        }
     ]
 ]);
 /**
@@ -2836,7 +2913,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: {
@@ -5904,7 +5984,10 @@ var Chains = {
     minter: zod.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: zod.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
 ;
 /**
@@ -6367,6 +6450,39 @@ const swapTokenEnumSchema = zod.z.enum([
     throw new Error(`Invalid chain identifier type: ${typeof chainIdentifier}. Expected ChainDefinition object, Blockchain enum, or string literal.`);
 }
 
+/**
+ * Resolve a chain identifier to a plain chain-name string.
+ *
+ * Accept a string literal (`'Ethereum'`), a `ChainDefinition`-like
+ * object (`{ chain: 'Ethereum' }`), or `null`/`undefined` and return
+ * the chain name as a string. Return `undefined` when the value
+ * cannot be resolved.
+ *
+ * @remarks
+ * Unlike `resolveChainIdentifier` (which returns a full `ChainDefinition`
+ * and throws on invalid input), this helper is intentionally lenient and
+ * never throws — it is safe to call in error-handling and telemetry paths.
+ *
+ * @param value - A string, chain-definition object, or nullish value.
+ * @returns The chain name string, or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * import { resolveChainName } from '@core/chains'
+ *
+ * resolveChainName('Ethereum')              // 'Ethereum'
+ * resolveChainName({ chain: 'Ethereum' })   // 'Ethereum'
+ * resolveChainName(undefined)               // undefined
+ * ```
+ */ function resolveChainName(value) {
+    if (value == null) return undefined;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'object' && 'chain' in value && typeof value.chain === 'string') {
+        return value.chain;
+    }
+    return undefined;
+}
+
 /**
  * Extracts chain information including name, display name, and expected address format.
  *
@@ -6751,13 +6867,12 @@ const swapTokenEnumSchema = zod.z.enum([
         headers: {
             ...DEFAULT_CONFIG$1.headers,
             ...config.headers ?? {},
-            // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
-            // This is why we use the 'X-User-Agent' header instead.
-            ...typeof window === 'undefined' ? {
-                'User-Agent': getUserAgent()
-            } : {
-                'X-User-Agent': getUserAgent()
-            }
+            // Browsers forbid setting a user-agent request header, and the custom
+            // fallback header the SDK used instead trips CORS preflight against the
+            // Circle APIs (it isn't in their `Access-Control-Allow-Headers`),
+            // blocking the request. So send the SDK user agent only in Node;
+            // browsers omit it entirely.
+            ...getNodeUserAgentHeader()
         }
     };
     let lastError;
@@ -8016,6 +8131,223 @@ const swapTokenEnumSchema = zod.z.enum([
     return explorerUrl;
 }
 
+/**
+ * CCTP forwarding magic bytes prefix.
+ *
+ * The ASCII string "cctp-forward" (12 bytes) that identifies a forwarding request.
+ * This prefix is right-padded to 24 bytes in the final hookData.
+ */ const CCTP_FORWARD_MAGIC_PREFIX = 'cctp-forward';
+
+/**
+ * Project an arbitrary payload onto the exact set of fields the telemetry
+ * endpoint accepts.
+ *
+ * @remarks
+ * Defense-in-depth before the last network hop: rather than
+ * `JSON.stringify`-ing the caller's object verbatim, only the
+ * allowlisted {@link ClientLogPayload} fields (and the allowlisted
+ * sub-fields of `errorDetails` / `clientContext`) are copied across.
+ * A regressing upstream mapper — or a plain-JS caller that bypasses the
+ * type — therefore cannot exfiltrate stray properties (secrets, PII,
+ * raw error stacks) through the analytics channel. Optional fields are
+ * only included when present so the serialised shape matches the
+ * server's strict schema.
+ *
+ * @internal
+ */ function toSafePayload(payload) {
+    const clientContext = {
+        platform: payload.clientContext.platform,
+        os: payload.clientContext.os,
+        runtimeName: payload.clientContext.runtimeName
+    };
+    const safe = {
+        sdkName: payload.sdkName,
+        sdkVersion: payload.sdkVersion,
+        eventType: payload.eventType,
+        timestamp: payload.timestamp,
+        clientContext
+    };
+    if (payload.sourceChain !== undefined) safe['sourceChain'] = payload.sourceChain;
+    if (payload.destinationChain !== undefined) safe['destinationChain'] = payload.destinationChain;
+    if (payload.tokenIn !== undefined) safe['tokenIn'] = payload.tokenIn;
+    if (payload.tokenOut !== undefined) safe['tokenOut'] = payload.tokenOut;
+    if (payload.txHash !== undefined) safe['txHash'] = payload.txHash;
+    if (payload.correlationId !== undefined) safe['correlationId'] = payload.correlationId;
+    if (payload.errorDetails !== undefined) {
+        const errorDetails = {
+            ...payload.errorDetails.errorCode !== undefined && {
+                errorCode: payload.errorDetails.errorCode
+            },
+            ...payload.errorDetails.errorType !== undefined && {
+                errorType: payload.errorDetails.errorType
+            }
+        };
+        safe['errorDetails'] = errorDetails;
+    }
+    return safe;
+}
+/**
+ * Default telemetry endpoint.
+ *
+ * Override via the `STABLECOIN_KITS_TELEMETRY_URL` environment variable
+ * (e.g. for staging or local development).
+ *
+ * @internal
+ */ const DEFAULT_LOGS_URL = 'https://api.circle.com/v1/stablecoinKits/logs';
+/**
+ * Resolve the telemetry endpoint URL.
+ *
+ * @internal
+ */ function getLogsUrl() {
+    if (isNodeEnvironment() && typeof process.env['STABLECOIN_KITS_TELEMETRY_URL'] === 'string' && process.env['STABLECOIN_KITS_TELEMETRY_URL'].length > 0) {
+        return process.env['STABLECOIN_KITS_TELEMETRY_URL'];
+    }
+    return DEFAULT_LOGS_URL;
+}
+/**
+ * Send a telemetry event to the proxy service.
+ *
+ * @remarks
+ * Fire-and-forget: the returned promise is intentionally not awaited
+ * by the caller. A fetch failure (network error, non-2xx, timeout)
+ * is silently swallowed so telemetry never blocks or fails user
+ * operations.
+ *
+ * @param payload - The structured log payload matching the server schema.
+ *
+ * @example
+ * ```typescript
+ * import { emitAnalyticsLog } from '@core/utils'
+ *
+ * // Fire-and-forget — do not await
+ * void emitAnalyticsLog(payload)
+ * ```
+ */ async function emitAnalyticsLog(payload) {
+    // Hand-rolled timeout via `AbortController` + `setTimeout` rather than
+    // `AbortSignal.timeout(...)` so we can `clearTimeout` the handle in a
+    // `finally`. `AbortSignal.timeout` registers a timer that stays on the
+    // event loop until it fires even if the fetch already settled, which
+    // manifests as spurious `TimeoutError` unhandled rejections during
+    // process teardown (notably between e2e test fork lifecycles). See
+    // nodejs/node#48298 for the underlying issue.
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(()=>{
+        controller.abort(new DOMException('Telemetry request timed out', 'TimeoutError'));
+    }, 5_000);
+    // Don't let the timer keep the Node event loop alive in short-lived
+    // CLIs / test processes; telemetry is best-effort and must never
+    // block clean process exit. `unref` only exists on Node's `Timeout`
+    // object, not on the `number` returned by the browser's `setTimeout`,
+    // so we feature-detect rather than call unconditionally.
+    if (typeof timeoutHandle.unref === 'function') {
+        timeoutHandle.unref();
+    }
+    try {
+        await fetch(getLogsUrl(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                // Browsers forbid setting a user-agent request header, and the custom
+                // fallback header the SDK used instead trips CORS preflight (it isn't
+                // in the telemetry endpoint's `Access-Control-Allow-Headers`), so send
+                // it only in Node; browsers omit it entirely.
+                ...getNodeUserAgentHeader()
+            },
+            body: JSON.stringify(toSafePayload(payload)),
+            signal: controller.signal
+        });
+    } catch  {
+    // Silently swallow — telemetry must never break user operations.
+    } finally{
+        clearTimeout(timeoutHandle);
+    }
+}
+
+/**
+ * Build the `clientContext` object for telemetry payloads.
+ *
+ * @remarks
+ * Use the exported `getRuntime()` and `isNodeEnvironment()` from
+ * `@core/utils` to detect the runtime environment. The returned
+ * string is parsed into the structured `ClientContext` fields
+ * expected by the server schema.
+ *
+ * @returns A {@link ClientContext} with platform, OS, and runtime name
+ *   populated from the current environment.
+ *
+ * @example
+ * ```typescript
+ * import { buildClientContext } from '@core/utils'
+ *
+ * const ctx = buildClientContext()
+ * // Node: { platform: 'node', os: 'darwin', runtimeName: null }
+ * // Browser: { platform: 'browser', os: null, runtimeName: 'chrome' }
+ * ```
+ */ function buildClientContext() {
+    const runtime = getRuntime();
+    if (runtime.startsWith('browser/')) {
+        return {
+            platform: 'browser',
+            os: null,
+            runtimeName: runtime.slice('browser/'.length).toLowerCase()
+        };
+    }
+    if (runtime.startsWith('node/')) {
+        return {
+            platform: 'node',
+            os: isNodeEnvironment() ? process.platform : null,
+            runtimeName: null
+        };
+    }
+    return {
+        platform: 'node',
+        os: null,
+        runtimeName: null
+    };
+}
+
+/**
+ * Extract structured error details from an unknown error value.
+ *
+ * @remarks
+ * Handle three cases:
+ * - `KitError` — extract `code` and `name`.
+ * - `Error` — extract `name`.
+ * - Anything else — return empty details.
+ *
+ * Only structured, bounded fields (`errorCode`, `errorType`) are
+ * included. Free-text fields (`message`, `stack`) are intentionally
+ * omitted to avoid leaking secrets or PII through vendor telemetry.
+ *
+ * @param error - The thrown value to extract details from.
+ * @returns A {@link ErrorDetails} object suitable for telemetry payloads.
+ *
+ * @example
+ * ```typescript
+ * import { extractErrorDetails } from '@core/utils'
+ *
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   const details = extractErrorDetails(error)
+ *   // { errorCode: '1001', errorType: 'INPUT_NETWORK_MISMATCH' }
+ * }
+ * ```
+ */ function extractErrorDetails(error) {
+    if (error instanceof KitError) {
+        return {
+            errorCode: String(error.code),
+            errorType: error.name
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            errorType: error.name
+        };
+    }
+    return {};
+}
+
 /**
  * Strip the `@circle-fin/` scope from a kit package name to produce the
  * short SDK name used in telemetry payloads.
@@ -8034,8 +8366,154 @@ const swapTokenEnumSchema = zod.z.enum([
     return pkgName.replace('@circle-fin/', '');
 }
 
+/**
+ * Soft signal for the case where building or emitting a telemetry payload
+ * threw — for example, a buggy `TelemetryContextResolver`, a regression in
+ * `extractErrorDetails`, or a synchronous failure inside `emitAnalyticsLog`
+ * before it could swallow the error itself. Logged with a stable prefix so
+ * consumers can grep for it. We deliberately do not re-throw: the caller's
+ * original operation error must always win.
+ *
+ * @internal
+ */ function warnTelemetryDrop(eventType, cause) {
+    try {
+        // Pass `cause` as the second console.warn argument rather than
+        // string-coercing it. `String(err)` (and `err.message` alone)
+        // discards the stack trace, nested `cause`, and any custom Error
+        // properties — exactly the context an on-call needs when a
+        // resolver-closure regression triggers this path.
+        console.warn(`[stablecoin-kits telemetry] dropped event '${eventType}':`, cause);
+    } catch  {
+    // console.warn itself throwing is the user's environment; nothing more we
+    // can do without risking the original operation error.
+    }
+}
+/**
+ * Build a telemetry payload from common fields.
+ *
+ * @internal
+ */ function buildPayload(config, eventType, errorDetails, context) {
+    return {
+        sdkName: config.sdkName,
+        sdkVersion: config.sdkVersion,
+        eventType,
+        timestamp: new Date().toISOString(),
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
+        clientContext: buildClientContext(),
+        ...context?.sourceChain != null && {
+            sourceChain: context.sourceChain
+        },
+        ...context?.destinationChain != null && {
+            destinationChain: context.destinationChain
+        },
+        ...context?.tokenIn != null && {
+            tokenIn: context.tokenIn
+        },
+        ...context?.tokenOut != null && {
+            tokenOut: context.tokenOut
+        },
+        ...context?.txHash != null && {
+            txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
+        }
+    };
+}
+/**
+ * Emit telemetry for a completed operation without affecting its caller.
+ *
+ * No-ops when `config.disabled` is `true`. Like {@link withErrorTelemetry},
+ * failures while constructing or submitting the telemetry payload are reported
+ * as a soft warning and never change a completed operation's result.
+ *
+ * @param eventType - The telemetry event type for the completed operation.
+ * @param config - Per-kit SDK identity and disabled flag.
+ * @param context - Optional chain, token, and transaction context.
+ * @returns Nothing.
+ * @throws Never — telemetry failures are reported as warnings.
+ *
+ * @example
+ * ```typescript
+ * import { emitSuccessTelemetry } from '@core/utils'
+ *
+ * emitSuccessTelemetry(
+ *   'bridge_bridge',
+ *   { sdkName: 'bridge-kit', sdkVersion: '1.0.0', disabled: false },
+ *   { sourceChain: 'Ethereum', destinationChain: 'Base', tokenIn: 'USDC' },
+ * )
+ * ```
+ */ function emitSuccessTelemetry(eventType, config, context) {
+    if (config.disabled) {
+        return;
+    }
+    try {
+        void emitAnalyticsLog(buildPayload(config, eventType, undefined, context));
+    } catch (telemetryError) {
+        warnTelemetryDrop(eventType, telemetryError);
+    }
+}
+/**
+ * Wrap an async operation with error telemetry.
+ *
+ * Execute `fn` and, if it throws, emit an error telemetry payload
+ * before re-throwing. No-ops when `config.disabled` is `true`.
+ *
+ * `context` may be a static {@link TelemetryContext} or a
+ * {@link TelemetryContextResolver}. The resolver is invoked in the
+ * catch branch, so it can read state — most importantly `txHash` —
+ * that the wrapped operation set after a successful broadcast. The
+ * resolver must close over per-call locals only; passing instance
+ * state would break isolation between concurrent invocations.
+ *
+ * @param fn - The async operation to execute.
+ * @param eventType - The telemetry event type for this operation.
+ * @param config - Per-kit SDK identity and disabled flag.
+ * @param context - Optional context, static or lazily resolved.
+ * @returns The result of the operation.
+ * @throws Re-throws any error after emitting telemetry.
+ *
+ * @example
+ * ```typescript
+ * import { withErrorTelemetry } from '@core/utils'
+ *
+ * let txHash: string | undefined
+ * const result = await withErrorTelemetry(
+ *   () => provider.swap(params, h => { txHash = h }),
+ *   'swap_swap',
+ *   { sdkName: 'swap-kit', sdkVersion: '1.0.0', disabled: false },
+ *   () => ({
+ *     sourceChain: 'Ethereum',
+ *     tokenIn: 'USDC',
+ *     tokenOut: 'EURC',
+ *     ...(txHash != null && { txHash }),
+ *   }),
+ * )
+ * ```
+ */ async function withErrorTelemetry(fn, eventType, config, context) {
+    try {
+        return await fn();
+    } catch (error) {
+        if (!config.disabled) {
+            try {
+                const resolved = typeof context === 'function' ? context() : context;
+                void emitAnalyticsLog(buildPayload(config, eventType, extractErrorDetails(error), resolved));
+            } catch (telemetryError) {
+                // Never let telemetry emission mask the original operation error.
+                // But surface a soft signal so silent telemetry drops are
+                // discoverable (e.g. a regression in a resolver closure or in
+                // `extractErrorDetails`) instead of vanishing without any trace.
+                warnTelemetryDrop(eventType, telemetryError);
+            }
+        }
+        throw error;
+    }
+}
+
 var name$3 = "@circle-fin/bridge-kit";
-var version$3 = "1.12.0";
+var version$3 = "1.12.2";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -8860,6 +9338,17 @@ var TransferSpeed;
     clock: zod.z.any().optional()
 }).passthrough();
 
+/**
+ * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
+ * hookData must start with.
+ *
+ * Encoded with `TextEncoder` (a browser-safe Web API) rather than `Buffer.from`
+ * so this module-level constant does not reference the Node `Buffer` global at
+ * import time. App Kit inlines this provider into its bundle without a Buffer polyfill, and a
+ * bare `Buffer` here crashes browser bundles (e.g. Vite) on load — even for apps
+ * that never touch the prepaid FORWARD path. Mirrors `buildForwardingHookData`.
+ */ Array.from(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX)).map((byte)=>byte.toString(16).padStart(2, '0')).join('');
+
 /**
  * The minimum finality threshold for CCTPv2 transfers.
  *
@@ -8892,7 +9381,7 @@ var TransferSpeed;
 registerKit(`${pkg$3.name}/${pkg$3.version}`);
 
 var name$2 = "@circle-fin/swap-kit";
-var version$2 = "1.3.2";
+var version$2 = "1.5.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -8957,7 +9446,10 @@ const optionalChainIdentifierField = chainIdentifierField.optional();
     }).min(1, 'kitKey must be a non-empty string').optional(),
     provider: zod.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: zod.z.boolean({
+        invalid_type_error: 'batchTransactions must be a boolean'
+    }).optional()
 });
 /**
  * Zod schema for adapter context.
@@ -9396,7 +9888,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.
@@ -9454,7 +9946,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.
@@ -9490,7 +9982,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     toChain: zod.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.
@@ -9499,13 +9991,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: zod.z.number().int('fee token decimals must be an integer').nonnegative('fee token decimals must be a non-negative integer').optional(),
+    symbol: zod.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 = zod.z.object({
-    token: zod.z.string().min(1, 'fee token must be a non-empty string'),
-    amount: feeAmountSchema,
+ */ const createSwapDeveloperFeeItemSchema = createSwapFeeItemSchema.extend({
     basis: zod.z.enum([
         'inputAmount',
         'estimatedAmount'
@@ -9597,7 +10091,7 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     addresses: zod.z.array(zod.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.
@@ -9628,6 +10122,16 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
         required_error: 'estimatedAmount is required',
         invalid_type_error: 'estimatedAmount must be a string'
     }).min(1, 'estimatedAmount must be a non-empty string'),
+    // Per-swap join key echoed back verbatim on success telemetry. Optional so a
+    // not-yet-upgraded service (no field) still validates during rollout. A
+    // malformed/non-UUID value is coerced to `undefined` (no telemetry id) rather
+    // than throwing: this is a telemetry-only field (stripped from the developer
+    // result, never used for control flow), so it must not be able to abort the
+    // swap via `parseCreateSwapResponse().parse()`. Mirrors the best-effort,
+    // never-throw contract of the rest of the telemetry stack. Implemented with
+    // `preprocess` rather than Zod's `.catch()` because static analysis misreads
+    // `.catch` on the schema chain as an unhandled Promise (S7785).
+    correlationId: zod.z.preprocess((value)=>zod.z.string().uuid().safeParse(value).success ? value : undefined, zod.z.string().optional()),
     config: createSwapRequestBaseSchema.shape.config.optional(),
     fees: createSwapFeesSchema.optional(),
     transaction: createSwapTransactionSchema
@@ -12186,7 +12690,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/earn-kit";
-var version$1 = "1.2.2";
+var version$1 = "1.4.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -12653,7 +13157,7 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *
  * @param params - Adapter, chain, token/delegate/wallet addresses, the required
  *   allowance for the signed payload, and a revert message for on-chain failure.
- * @returns The approval transaction hash when an approval was submitted, or
+ * @returns The approval transaction result when an approval was submitted, or
  *   `undefined` when the existing allowance already covers `requiredAllowance`
  *   (or `requiredAllowance` is zero).
  * @throws {@link KitError} If the `token.allowance` response is malformed.
@@ -12661,7 +13165,7 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *
  * @example
  * ```typescript
- * const txHash = await approveAllowanceIfNeeded({
+ * const approval = await approveAllowanceIfNeeded({
  *   adapter,
  *   chain,
  *   tokenAddress: usdcAddress,
@@ -12723,7 +13227,15 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
         maxAttempts: params.allowancePropagation?.maxAttempts ?? DEFAULT_PROPAGATION_ATTEMPTS,
         delayMs: params.allowancePropagation?.delayMs ?? DEFAULT_PROPAGATION_DELAY_MS
     });
-    return approvalTxHash;
+    return {
+        txHash: approvalTxHash,
+        ...approvalReceipt.gasUsed !== undefined && {
+            gasUsed: approvalReceipt.gasUsed
+        },
+        ...approvalReceipt.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: approvalReceipt.effectiveGasPrice
+        }
+    };
 }
 
 /** @internal */ function isSameAddress(actual, expected) {
@@ -12871,7 +13383,13 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     }
     return {
         txHash,
-        explorerUrl
+        explorerUrl,
+        ...receipt.gasUsed !== undefined && {
+            gasUsed: receipt.gasUsed
+        },
+        ...receipt.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: receipt.effectiveGasPrice
+        }
     };
 }
 
@@ -13183,112 +13701,6 @@ const EARN_OPERATIONS = new Set([
     return hasEarnServiceParamsShape(operation, candidate['params']);
 }
 
-function buildGasFeeBase(name, chain) {
-    return {
-        name,
-        token: chain.nativeCurrency.symbol,
-        blockchain: chain.chain
-    };
-}
-function buildGasFeeSuccess(name, chain, fees) {
-    return {
-        ...buildGasFeeBase(name, chain),
-        fees
-    };
-}
-function buildGasFeeFailure(name, chain, error) {
-    return {
-        ...buildGasFeeBase(name, chain),
-        fees: null,
-        error: getErrorMessage(error)
-    };
-}
-async function estimatePreparedGasFee(name, chain, prepared) {
-    try {
-        const estimate = bufferEstimatedGas(await prepared.estimate());
-        if (estimate.gas <= 0n) {
-            throw createValidationFailedError('estimate.gas', estimate.gas.toString(), 'gas estimate must be greater than zero');
-        }
-        return buildGasFeeSuccess(name, chain, estimate);
-    } catch (error) {
-        return buildGasFeeFailure(name, chain, error);
-    }
-}
-async function estimateApprovalGasFeeIfNeeded(params) {
-    const { adapter, chain, address, tokenAddress, delegate, requiredAllowance } = params;
-    if (requiredAllowance <= 0n) {
-        return undefined;
-    }
-    try {
-        const allowancePrepared = await adapter.prepareAction('token.allowance', {
-            tokenAddress,
-            delegate
-        }, {
-            chain,
-            address
-        });
-        const allowanceRaw = await allowancePrepared.execute();
-        const currentAllowance = parseAllowanceResponse(allowanceRaw);
-        if (currentAllowance >= requiredAllowance) {
-            return undefined;
-        }
-        // Reuse the execute path's approval builder so the estimate simulates the
-        // exact approval (action, amount, and WARM_SLOT_RESIDUAL) that
-        // approveAllowanceIfNeeded later submits.
-        const approvalPrepared = await prepareApprovalAction({
-            adapter,
-            chain,
-            address,
-            tokenAddress,
-            delegate,
-            currentAllowance,
-            requiredAllowance
-        });
-        return await estimatePreparedGasFee('Approve', chain, approvalPrepared);
-    } catch (error) {
-        return buildGasFeeFailure('Approve', chain, error);
-    }
-}
-/**
- * Estimate gas fee entries for an earn quote without submitting transactions.
- *
- * Each entry is produced by simulating the prepared transaction against
- * current chain state. When an approval is required (allowance below the
- * signed payload's required amount), the subsequent action simulation runs
- * without that approval in place and is expected to revert — the action entry
- * then carries `fees: null` with the revert message while the approval entry
- * still estimates normally. Quote consumers must treat that as "estimate
- * pending approval", not a hard failure.
- *
- * @internal
- */ async function estimateEarnQuoteGasFees(params) {
-    const { adapter, chain, address, actionName, actionKey, actionParams, approval } = params;
-    const gasFees = [];
-    if (approval !== undefined) {
-        const approvalEstimate = await estimateApprovalGasFeeIfNeeded({
-            adapter,
-            chain,
-            address,
-            tokenAddress: approval.token,
-            delegate: approval.delegate,
-            requiredAllowance: approval.requiredAllowance
-        });
-        if (approvalEstimate !== undefined) {
-            gasFees.push(approvalEstimate);
-        }
-    }
-    try {
-        const actionPrepared = await adapter.prepareAction(actionKey, actionParams, {
-            chain,
-            address
-        });
-        gasFees.push(await estimatePreparedGasFee(actionName, chain, actionPrepared));
-    } catch (error) {
-        gasFees.push(buildGasFeeFailure(actionName, chain, error));
-    }
-    return gasFees;
-}
-
 // ---------------------------------------------------------------------------
 // Shared primitives
 // ---------------------------------------------------------------------------
@@ -13366,7 +13778,11 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     asset: zod.z.string(),
     assetAddress: zod.z.string(),
     lltv: zod.z.number(),
-    supplyUsd: zod.z.number()
+    supplyUsd: zod.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: zod.z.number().nullable().optional()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -13380,15 +13796,82 @@ 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 vaultInfoResponseSchema = zod.z.object({
-    vaultAddress: zod.z.string(),
-    chain: zod.z.string(),
+ */ const managerSchema = zod.z.object({
     name: zod.z.string(),
-    protocol: zod.z.string(),
-    asset: zod.z.string(),
+    address: zod.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: zod.z.enum([
+        'curator'
+    ])
+});
+/**
+ * Zod schema for the APY profile facet in the API response.
+ *
+ * @internal
+ */ const apyProfileSchema = zod.z.object({
+    current: zod.z.number(),
+    native: zod.z.number().nullable(),
+    d7: zod.z.number().nullable(),
+    d30: zod.z.number().nullable(),
+    d90: zod.z.number().nullable(),
+    rewardShare: zod.z.number().nullable(),
+    source: zod.z.string().optional(),
+    asOf: zod.z.string().optional()
+});
+/**
+ * Zod schema for the fee split facet in the API response.
+ *
+ * @internal
+ */ const feeInfoSchema = zod.z.object({
+    performance: zod.z.number().nullable(),
+    management: zod.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 = zod.z.object({
+    totalDeposits: amountJsonSchema,
+    available: amountJsonSchema,
+    totalSupply: amountJsonSchema,
+    status: zod.z.enum([
+        'active',
+        'low_liquidity'
+    ])
+});
+/**
+ * Zod schema for the risk signals facet in the API response.
+ *
+ * @internal
+ */ const riskSignalsSchema = zod.z.object({
+    circleSentinel: zod.z.boolean(),
+    warnings: zod.z.array(vaultWarningSchema).optional(),
+    earnKitWarnings: zod.z.array(zod.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 = zod.z.object({
+    vaultAddress: zod.z.string(),
+    chain: zod.z.string(),
+    name: zod.z.string(),
+    protocol: zod.z.string(),
+    asset: zod.z.string(),
     assetAddress: zod.z.string(),
     currentApy: zod.z.number(),
     nativeApy: zod.z.number(),
@@ -13405,6 +13888,96 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     warnings: zod.z.array(vaultWarningSchema).optional(),
     earnKitWarnings: zod.z.array(zod.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: zod.z.string().optional(),
+    asOf: zod.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: zod.z.literal('vault'),
+    collateral: zod.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 = zod.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 = zod.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);
+    });
+}, zod.z.array(earnOpportunitySchema));
 // ---------------------------------------------------------------------------
 // Position response schema
 // ---------------------------------------------------------------------------
@@ -13534,6 +14107,7 @@ const positionPnlSchema = zod.z.discriminatedUnion('status', [
  *
  * @internal
  */ const depositPayloadSchema = zod.z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: depositExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -13625,6 +14199,21 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     amount: amountJsonSchema,
     vaultAddress: hexAddressSchema
 }).passthrough();
+/** @internal */ const bridgeQuoteExpirySchema = zod.z.discriminatedUnion('mode', [
+    zod.z.object({
+        mode: zod.z.literal('TIMESTAMP'),
+        expiresAt: zod.z.string().datetime({
+            offset: true
+        })
+    }),
+    zod.z.object({
+        mode: zod.z.literal('BLOCK_NUMBER'),
+        expiresAtBlock: zod.z.number().int(),
+        blockEstimatedAt: zod.z.string().datetime({
+            offset: true
+        }).optional()
+    })
+]).optional().catch(undefined);
 /**
  * Zod schema for the bridge deposit prepare payload.
  *
@@ -13636,6 +14225,10 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     execId: bridgeDepositExecIdSchema,
     erc3009TypedData: bridgeDepositPreparedBundleSchema,
     expiresAt: zod.z.string().datetime(),
+    quoteIssuedAt: zod.z.string().datetime({
+        offset: true
+    }).optional().catch(undefined),
+    quoteExpiry: bridgeQuoteExpirySchema,
     review: bridgeDepositPrepareReviewSchema
 });
 /**
@@ -13701,6 +14294,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
  *
  * @internal
  */ const withdrawPayloadSchema = zod.z.object({
+    execId: bridgeDepositExecIdSchema,
     executionParams: withdrawExecutionParamsSchema,
     signature: hexSignatureSchema
 });
@@ -13714,6 +14308,27 @@ const bridgeDepositPrepareReviewSchema = zod.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 = zod.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
+ */ const transactionReportResponseSchema = zod.z.object({
+    data: transactionReportPayloadSchema
+});
+// ---------------------------------------------------------------------------
 // Claim rewards response schema
 // ---------------------------------------------------------------------------
 /**
@@ -13774,6 +14389,30 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     token: zod.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 = zod.z.object({
+    name: zod.z.string().optional(),
+    fees: zod.z.unknown(),
+    error: zod.z.string().optional()
+}).passthrough();
 /**
  * Zod schema for the inner deposit quote payload.
  *
@@ -13789,7 +14428,8 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     expectedShares: amountJsonSchema,
     sharePrice: zod.z.string(),
     currentApy: zod.z.number(),
-    fees: zod.z.array(feeSchema).optional()
+    fees: zod.z.array(feeSchema).optional(),
+    gasFees: zod.z.array(quoteGasFeeSchema).optional()
 });
 /**
  * Zod schema for the `POST /v1/earnKit/deposit/quote` API response.
@@ -13816,6 +14456,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
     sharePrice: zod.z.string(),
     maxWithdrawable: amountJsonSchema,
     fees: zod.z.array(feeSchema),
+    gasFees: zod.z.array(quoteGasFeeSchema).optional(),
     warnings: zod.z.array(zod.z.string()).optional()
 });
 /**
@@ -13873,7 +14514,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
  *
  * @internal
  */ const getVaultsPayloadSchema = zod.z.object({
-    vaults: zod.z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     errors: zod.z.array(vaultErrorSchema)
 });
 /**
@@ -13903,7 +14544,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
  *
  * @internal
  */ const exploreVaultsPayloadSchema = zod.z.object({
-    vaults: zod.z.array(vaultInfoResponseSchema),
+    vaults: earnOpportunityListSchema,
     pagination: explorePaginationSchema
 });
 /**
@@ -13996,6 +14637,16 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
  */ function isWithdrawResponse(value) {
     return withdrawResponseSchema.safeParse(value).success;
 }
+/**
+ * Type guard for the transaction report API response.
+ *
+ * @param value - Unknown response value to validate
+ * @returns True when the value matches the transaction report response shape
+ *
+ * @internal
+ */ function isTransactionReportResponse(value) {
+    return transactionReportResponseSchema.safeParse(value).success;
+}
 /**
  * Type guard for the claim rewards API response.
  *
@@ -14038,7 +14689,7 @@ const bridgeDepositPrepareReviewSchema = zod.z.object({
 }
 
 var name = "@circle-fin/provider-earn-service";
-var version = "1.2.2";
+var version = "1.3.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -14100,15 +14751,25 @@ var pkg = {
  *
  * @internal
  */ function buildConfig(serviceConfig) {
+    // The kit key is a server-only secret. Reject it in the browser so it cannot
+    // leak into a client bundle (no-op in Node.js). Keyless usage stays allowed.
+    if (serviceConfig?.kitKey !== undefined && isBrowserEnvironment()) {
+        throw createValidationFailedError('kitKey', '[redacted]', 'kitKey must not be provided in a browser environment — it is a server-only secret. Run EarnKit operations that use a kit key on your server, or omit kitKey to use the permissionless (keyless) client path');
+    }
     const baseUrl = serviceConfig?.baseUrl ?? EARN_SERVICE_BASE_URL;
-    const sdkVersion = resolveSdkVersionHeader();
+    // The API CORS policy does not allow this custom header. Keep the existing
+    // per-request version attribution for Node callers, but omit it in browsers
+    // so public EarnKit endpoints do not fail at CORS preflight.
+    const sdkVersionHeader = isNodeEnvironment() ? {
+        [SDK_VERSION_HEADER]: resolveSdkVersionHeader()
+    } : {};
     if (serviceConfig?.kitKey === undefined) {
         return {
             pollingConfig: {
                 ...DEFAULT_CONFIG,
                 headers: {
                     ...DEFAULT_CONFIG.headers,
-                    [SDK_VERSION_HEADER]: sdkVersion
+                    ...sdkVersionHeader
                 }
             },
             baseUrl
@@ -14126,7 +14787,7 @@ var pkg = {
             ...DEFAULT_CONFIG,
             headers: {
                 ...DEFAULT_CONFIG.headers,
-                [SDK_VERSION_HEADER]: sdkVersion,
+                ...sdkVersionHeader,
                 Authorization: `Bearer ${serviceConfig.kitKey}`
             }
         },
@@ -14158,7 +14819,7 @@ var pkg = {
 }
 
 /**
- * Convert an API vault info object into the SDK {@link VaultInfo} shape.
+ * Convert an API vault info object into the SDK {@link EarnOpportunity} shape.
  *
  * Map the API chain code back to the SDK chain identifier and hydrate the
  * amount payloads into {@link Amount} instances.
@@ -14169,16 +14830,29 @@ var pkg = {
  *
  * @internal
  */ function toVaultInfo(data) {
-    const { totalDeposits, liquidity, ...vault } = data;
+    const { totalDeposits, liquidity, liquidityProfile, ...vault } = data;
     const chain = toSdkChain(vault.chain);
     if (chain === undefined) {
         throw createInvalidChainError(vault.chain, 'Chain returned by the Earn Service is not supported by the SDK');
     }
+    // The nested facets are `.optional()` in the schema (a backend that predates
+    // them omits them) and are typed optional on `EarnOpportunity` to match.
+    // Convert the nested liquidity amounts when present and pass the remaining
+    // facets straight through; each absent facet stays absent rather than being
+    // asserted present by a cast.
     return {
         ...vault,
         chain,
         totalDeposits: Amount.fromJSON(totalDeposits),
-        liquidity: Amount.fromJSON(liquidity)
+        liquidity: Amount.fromJSON(liquidity),
+        ...liquidityProfile !== undefined && {
+            liquidityProfile: {
+                ...liquidityProfile,
+                totalDeposits: Amount.fromJSON(liquidityProfile.totalDeposits),
+                available: Amount.fromJSON(liquidityProfile.available),
+                totalSupply: Amount.fromJSON(liquidityProfile.totalSupply)
+            }
+        }
     };
 }
 
@@ -14213,8 +14887,11 @@ function toVaultError(error) {
     }
     try {
         const response = await pollApiGet(url.toString(), isGetVaultsResponse, pollingConfig);
+        // `pollApiGet` validates via a boolean guard and returns the raw JSON — it
+        // does not run the schema's preprocess. Parse explicitly so unknown
+        // `productType` values are dropped before `toVaultInfo`.
         return {
-            vaults: response.data.vaults.map(toVaultInfo),
+            vaults: earnOpportunityListSchema.parse(response.data.vaults).map(toVaultInfo),
             errors: response.data.errors.map(toVaultError)
         };
     } catch (error) {
@@ -14263,8 +14940,11 @@ function toVaultError(error) {
     }
     try {
         const response = await pollApiGet(url.toString(), isExploreVaultsResponse, pollingConfig);
+        // `pollApiGet` validates via a boolean guard and returns the raw JSON — it
+        // does not run the schema's preprocess. Parse explicitly so unknown
+        // `productType` values are dropped before `toVaultInfo`.
         return {
-            vaults: response.data.vaults.map(toVaultInfo),
+            vaults: earnOpportunityListSchema.parse(response.data.vaults).map(toVaultInfo),
             pagination: response.data.pagination
         };
     } catch (error) {
@@ -14428,6 +15108,12 @@ function toPositionInfo(data) {
             execId: response.data.execId,
             preparedBundle,
             expiresAt: response.data.expiresAt,
+            ...response.data.quoteIssuedAt !== undefined && {
+                quoteIssuedAt: response.data.quoteIssuedAt
+            },
+            ...response.data.quoteExpiry !== undefined && {
+                quoteExpiry: response.data.quoteExpiry
+            },
             review: response.data.review
         };
     } catch (error) {
@@ -14769,7 +15455,110 @@ function toClaimedAmount(reward) {
     }
 }
 
-function toDepositQuoteInfo(data) {
+/**
+ * Map the Earn Service's server-side quote gas estimates into the SDK
+ * {@link EarnGasFeeEstimate} shape.
+ *
+ * The Earn Service estimates gas for each action (`Approve`, `Deposit`,
+ * `Withdraw`) and returns `{ name, fees: { gas, gasPrice, fee } }` with raw
+ * integer strings.
+ * The SDK type additionally carries `token` (the chain's native currency
+ * symbol) and `blockchain`, which are filled in here from the chain
+ * definition.
+ *
+ * Gas reporting is best-effort: a malformed entry (e.g. a non-integer string
+ * that fails `BigInt` parsing) degrades to a `{ fees: null, error }` estimate
+ * rather than throwing, so one bad entry never fails the whole quote.
+ *
+ * @param gasFees - Backend gas-fee entries from the quote response, if any.
+ * @param chain - Chain definition, used for the native token symbol and
+ *   blockchain identifier.
+ * @returns One {@link EarnGasFeeEstimate} per backend entry (empty when the
+ *   backend returned none).
+ *
+ * @example
+ * ```typescript
+ * toQuoteGasFees(
+ *   [{ name: 'Deposit', fees: { gas: '364142', gasPrice: '21000000000', fee: '7646982000000000' } }],
+ *   arcTestnet,
+ * )
+ * // [{ name: 'Deposit', token: 'USDC', blockchain: 'Arc_Testnet',
+ * //    fees: { gas: 364142n, gasPrice: 21000000000n, fee: '7646982000000000' } }]
+ * ```
+ *
+ * @internal
+ */ function toQuoteGasFees(gasFees, chain) {
+    if (gasFees === undefined) {
+        return [];
+    }
+    return gasFees.map((entry)=>{
+        const base = {
+            // `name` is optional on the wire; label an unnamed entry rather than
+            // emitting `name: undefined`.
+            name: entry.name ?? 'Unknown',
+            token: chain.nativeCurrency.symbol,
+            blockchain: chain.chain
+        };
+        // The Earn Service itself reports a failed estimate as `fees: null` with
+        // an error; propagate that soft failure verbatim.
+        if (entry.fees === null || entry.fees === undefined) {
+            return {
+                ...base,
+                fees: null,
+                error: entry.error ?? 'gas estimate unavailable'
+            };
+        }
+        // `fees` is `unknown` at the schema layer, so ALL validation happens here:
+        // that it is an object at all, and that `gas`, `gasPrice`, and `fee` are
+        // each parseable integer strings (including `fee`, which the SDK contract
+        // requires be a numeric base-unit string). Any failure — a wrong type
+        // (`fees: 123`), a missing field, or a non-numeric value — degrades the
+        // whole entry to a `fees: null` soft failure rather than surfacing a
+        // malformed "successful" estimate or rejecting the quote.
+        try {
+            if (typeof entry.fees !== 'object') {
+                throw new TypeError(`gas fees must be an object (got ${typeof entry.fees})`);
+            }
+            const { gas, gasPrice, fee } = entry.fees;
+            return {
+                ...base,
+                fees: {
+                    gas: toBigInt('gas', gas),
+                    gasPrice: toBigInt('gasPrice', gasPrice),
+                    fee: toBigInt('fee', fee).toString()
+                }
+            };
+        } catch (error) {
+            return {
+                ...base,
+                fees: null,
+                error: getErrorMessage(error)
+            };
+        }
+    });
+}
+/**
+ * Parse an unknown value into a `bigint`, rejecting anything that is not a
+ * non-empty integer string. `BigInt` alone is too permissive for this path —
+ * it accepts numbers, booleans, and empty strings — so guard the type first.
+ *
+ * @param field - Field name, used in the thrown error message.
+ * @param value - Raw value from the backend gas entry.
+ * @returns The parsed `bigint`.
+ * @throws {TypeError} When `value` is not a non-empty integer string.
+ */ function toBigInt(field, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`gas fee field "${field}" must be an integer string`);
+    }
+    try {
+        // BigInt throws on non-integer strings (e.g. "1.5", "not-a-number").
+        return BigInt(value);
+    } catch  {
+        throw new Error(`gas fee field "${field}" is not a valid integer string: ${value}`);
+    }
+}
+
+function toDepositQuoteInfo(data, chain) {
     const fees = (data.fees ?? []).map(({ token: feeTokenSymbol, ...fee })=>{
         // Earn Service returns fee.token as a display symbol, for example "USDC".
         return {
@@ -14798,7 +15587,10 @@ function toDepositQuoteInfo(data) {
         sharePrice: data.sharePrice,
         currentApy: data.currentApy,
         fees,
-        gasFees: []
+        // The Earn Service estimates gas server-side; the chain fills token/blockchain.
+        // Cross-chain quotes resolve no local chain definition, so gasFees stays
+        // empty there (unchanged behavior).
+        gasFees: chain === undefined ? [] : toQuoteGasFees(data.gasFees, chain)
     };
 }
 /**
@@ -14833,7 +15625,7 @@ function toDepositQuoteInfo(data) {
     };
     try {
         const response = await pollApiPost(url.toString(), requestBody, isDepositQuoteResponse, pollingConfig);
-        return toDepositQuoteInfo(response.data);
+        return toDepositQuoteInfo(response.data, params.chainDefinition);
     } catch (error) {
         throw parseEarnApiError(error, {
             operation: 'getDepositQuote'
@@ -14841,7 +15633,7 @@ function toDepositQuoteInfo(data) {
     }
 }
 
-function toWithdrawalQuoteInfo(data) {
+function toWithdrawalQuoteInfo(data, chain) {
     return {
         vaultAddress: data.vaultAddress,
         vaultName: data.vaultName,
@@ -14869,7 +15661,7 @@ function toWithdrawalQuoteInfo(data) {
                     status
                 }
             })),
-        gasFees: [],
+        gasFees: chain === undefined ? [] : toQuoteGasFees(data.gasFees, chain),
         // Wire format uses `warnings`, but the SDK surface uses
         // `earnKitWarnings` to match the precedent set by `VaultInfo` —
         // `warnings` is reserved for the structured `VaultWarning` shape.
@@ -14901,7 +15693,7 @@ function toWithdrawalQuoteInfo(data) {
     };
     try {
         const response = await pollApiPost(url.toString(), requestBody, isWithdrawalQuoteResponse, pollingConfig);
-        return toWithdrawalQuoteInfo(response.data);
+        return toWithdrawalQuoteInfo(response.data, params.chainDefinition);
     } catch (error) {
         throw parseEarnApiError(error, {
             operation: 'getWithdrawalQuote'
@@ -14937,6 +15729,8 @@ function toWithdrawalQuoteInfo(data) {
                     amount: Amount.fromJSON(r.amount),
                     address: r.token
                 })),
+            // The claimRewards/quote response does not carry a gas estimate (unlike
+            // deposit/withdrawal quotes), so there is nothing to surface here.
             gasFees: []
         };
     } catch (error) {
@@ -14946,6 +15740,83 @@ function toWithdrawalQuoteInfo(data) {
     }
 }
 
+/**
+ * Build the native gas triple the backend expects for `gasUsed`.
+ *
+ * Returns `undefined` unless both receipt components are present, so the
+ * caller can omit the field entirely — the Earn Service treats a missing
+ * triple as "skip the gas cache write, still return 200".
+ *
+ * @param gasUsed - Receipt gas units used.
+ * @param effectiveGasPrice - Receipt effective gas price.
+ * @returns The `{ gas, gasPrice, fee }` triple, or `undefined` when either
+ *   component is missing.
+ *
+ * @example
+ * ```typescript
+ * buildReportedGasUsed(362454n, 29466364605n)
+ * // { gas: '362454', gasPrice: '29466364605', fee: '10680201716540670' }
+ * ```
+ *
+ * @internal
+ */ function buildReportedGasUsed(gasUsed, effectiveGasPrice) {
+    if (gasUsed === undefined || effectiveGasPrice === undefined) {
+        return undefined;
+    }
+    return {
+        gas: gasUsed.toString(),
+        gasPrice: effectiveGasPrice.toString(),
+        fee: (gasUsed * effectiveGasPrice).toString()
+    };
+}
+/**
+ * Report the outcome of an SDK-submitted same-chain Earn transaction.
+ *
+ * @param params - Transaction report parameters.
+ * @throws {@link KitError} When the API call fails.
+ *
+ * @internal
+ */ async function reportEarnTransaction(params) {
+    const { pollingConfig, baseUrl } = buildConfig(params.config);
+    const url = new URL(`${EARN_KIT_API_PREFIX}/transactions/report`, baseUrl);
+    // The report endpoint is not idempotent: success reports refresh the gas
+    // cache and failure reports increment counts. If the first request succeeds
+    // server-side but the client times out or sees a transient 5xx, retrying
+    // would duplicate the report (double-writing an outcome or inflating failure
+    // counts). Reporting is best-effort (see the fire-and-forget caller), so
+    // make exactly one attempt and never retry — a single dropped report is
+    // preferable to a duplicated one. `maxRetries` here is the total attempt
+    // count in pollApiWithValidation (loop runs `attempt <= maxRetries`), so 1
+    // means one request with no retry; 0 would skip the request entirely.
+    const reportConfig = {
+        ...pollingConfig,
+        maxRetries: 1
+    };
+    const gasUsed = buildReportedGasUsed(params.gasUsed, params.effectiveGasPrice);
+    const requestBody = {
+        execId: params.execId,
+        chain: params.chain,
+        status: params.status,
+        action: params.action,
+        ...params.txHash !== undefined && {
+            txHash: params.txHash
+        },
+        ...gasUsed !== undefined && {
+            gasUsed
+        },
+        ...params.errorCode !== undefined && {
+            errorCode: params.errorCode
+        }
+    };
+    try {
+        await pollApiPost(url.toString(), requestBody, isTransactionReportResponse, reportConfig);
+    } catch (error) {
+        throw parseEarnApiError(error, {
+            operation: 'transactionReport'
+        });
+    }
+}
+
 /**
  * Sum the amounts across every token input to size the allowance approval.
  *
@@ -15056,6 +15927,59 @@ function toWithdrawalQuoteInfo(data) {
 // Intentionally built-ins-only: Earn bridge support is limited to SDK-known
 // token contracts plus the explicit ERC-3009 domain allowlist below.
 const TOKEN_REGISTRY = createTokenRegistry();
+function submitTransactionReport(reportContext, action, status, details) {
+    void reportEarnTransaction({
+        execId: reportContext.execId,
+        chain: reportContext.chain,
+        config: reportContext.config,
+        action,
+        status,
+        ...details
+    }).catch(()=>undefined);
+}
+function reportTransactionSuccess(reportContext, action, result) {
+    if (result === undefined) {
+        return;
+    }
+    submitTransactionReport(reportContext, action, 'success', {
+        txHash: result.txHash,
+        gasUsed: result.gasUsed,
+        effectiveGasPrice: result.effectiveGasPrice
+    });
+}
+function reportTransactionFailure(reportContext, action, error) {
+    submitTransactionReport(reportContext, action, 'failure', {
+        txHash: transactionReportTxHash(error),
+        errorCode: transactionReportErrorCode(error)
+    });
+}
+function transactionReportErrorCode(error) {
+    if (isKitError(error)) {
+        return error.name;
+    }
+    const message = getErrorMessage(error);
+    if (/user (rejected|denied)|rejected by user/i.test(message)) {
+        return 'USER_REJECTED';
+    }
+    if (/insufficient funds/i.test(message)) {
+        return 'INSUFFICIENT_FUNDS';
+    }
+    if (/timeout|timed out/i.test(message)) {
+        return 'TIMEOUT';
+    }
+    return 'UNKNOWN_ERROR';
+}
+function transactionReportTxHash(error) {
+    if (!isKitError(error)) {
+        return undefined;
+    }
+    const trace = error.cause?.trace;
+    if (typeof trace !== 'object' || trace === null) {
+        return undefined;
+    }
+    const txHash = trace['txHash'];
+    return typeof txHash === 'string' && txHash !== '' ? txHash : undefined;
+}
 /**
  * Build the typed error raised when a cross-chain wait is cancelled via its
  * `AbortSignal`. Mirrors `@core/adapter-base`'s `createAbortError` (same
@@ -15377,7 +16301,7 @@ function finishElapsedWait(lastStatus, lastError) {
             const adapterContractAddress = requireAdapterContract(chain);
             const { adapter } = params.from;
             const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await this.runPhase(ctx, 'deposit', 'fetchParams', async ()=>fetchDeposit({
+            const { execId, executionParams, signature } = await this.runPhase(ctx, 'deposit', 'fetchParams', async ()=>fetchDeposit({
                     vaultAddress,
                     amount: params.amount,
                     address,
@@ -15385,32 +16309,55 @@ function finishElapsedWait(lastStatus, lastError) {
                     config
                 }), ()=>undefined);
             validateExecutionDeadline(executionParams);
+            const transactionReportContext = {
+                execId,
+                chain: apiChain,
+                config
+            };
             const approvalToken = resolveEarnApprovalToken(executionParams);
             const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
             if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n) {
-                await this.runPhase(ctx, 'approve', 'approve', async ()=>approveAllowanceIfNeeded({
+                await this.runPhase(ctx, 'approve', 'approve', async ()=>{
+                    try {
+                        const approval = await approveAllowanceIfNeeded({
+                            adapter,
+                            chain,
+                            tokenAddress: approvalToken,
+                            delegate: adapterContractAddress,
+                            address,
+                            requiredAllowance,
+                            revertMessage: 'Earn deposit token approval reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Approve', approval);
+                        return approval;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Approve', error);
+                        throw error;
+                    }
+                }, (approval)=>approval?.txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>{
+                try {
+                    const result = await executeEarnAction({
                         adapter,
                         chain,
-                        tokenAddress: approvalToken,
-                        delegate: adapterContractAddress,
                         address,
-                        requiredAllowance,
-                        revertMessage: 'Earn deposit token approval reverted on-chain'
-                    }), (txHash)=>txHash);
-            }
-            const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>executeEarnAction({
-                    adapter,
-                    chain,
-                    address,
-                    actionKey: 'earn.deposit',
-                    actionParams: {
-                        executeParams: executionParams,
-                        tokenInputs,
-                        signature
-                    },
-                    revertMessage: 'Earn deposit reverted on-chain'
-                }), ({ txHash })=>txHash);
+                        actionKey: 'earn.deposit',
+                        actionParams: {
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature
+                        },
+                        revertMessage: 'Earn deposit reverted on-chain'
+                    });
+                    reportTransactionSuccess(transactionReportContext, 'Deposit', result);
+                    return result;
+                } catch (error) {
+                    reportTransactionFailure(transactionReportContext, 'Deposit', error);
+                    throw error;
+                }
+            }, ({ txHash })=>txHash);
             return {
                 kind: 'same-chain',
                 txHash,
@@ -15490,7 +16437,13 @@ function finishElapsedWait(lastStatus, lastError) {
             amount: params.amount,
             sourceChain: sourceChain.chain,
             destinationChain: destinationChain.chain,
-            expiresAt: prepared.expiresAt
+            expiresAt: prepared.expiresAt,
+            ...prepared.quoteIssuedAt !== undefined && {
+                quoteIssuedAt: prepared.quoteIssuedAt
+            },
+            ...prepared.quoteExpiry !== undefined && {
+                quoteExpiry: prepared.quoteExpiry
+            }
         };
     }
     /** {@inheritdoc} */ async withdraw(params) {
@@ -15511,7 +16464,7 @@ function finishElapsedWait(lastStatus, lastError) {
             const adapterContractAddress = requireAdapterContract(chain);
             const vaultAddress = assertHexAddress('vaultAddress', params.vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
             const { adapter } = params.from;
-            const { executionParams, signature } = await this.runPhase(ctx, 'withdraw', 'fetchParams', async ()=>fetchWithdraw({
+            const { execId, executionParams, signature } = await this.runPhase(ctx, 'withdraw', 'fetchParams', async ()=>fetchWithdraw({
                     vaultAddress,
                     amount: params.amount,
                     address,
@@ -15519,32 +16472,55 @@ function finishElapsedWait(lastStatus, lastError) {
                     config
                 }), ()=>undefined);
             validateExecutionDeadline(executionParams);
+            const transactionReportContext = {
+                execId,
+                chain: apiChain,
+                config
+            };
             const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
             const approvalToken = tokenInputs[0]?.token;
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
             if (!options.skipApprove && approvalToken !== undefined) {
-                await this.runPhase(ctx, 'approve', 'approve', async ()=>approveAllowanceIfNeeded({
+                await this.runPhase(ctx, 'approve', 'approve', async ()=>{
+                    try {
+                        const approval = await approveAllowanceIfNeeded({
+                            adapter,
+                            chain,
+                            tokenAddress: approvalToken,
+                            delegate: adapterContractAddress,
+                            address,
+                            requiredAllowance,
+                            revertMessage: 'Vault share token approval reverted on-chain'
+                        });
+                        reportTransactionSuccess(transactionReportContext, 'Approve', approval);
+                        return approval;
+                    } catch (error) {
+                        reportTransactionFailure(transactionReportContext, 'Approve', error);
+                        throw error;
+                    }
+                }, (approval)=>approval?.txHash);
+            }
+            const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>{
+                try {
+                    const result = await executeEarnAction({
                         adapter,
                         chain,
-                        tokenAddress: approvalToken,
-                        delegate: adapterContractAddress,
                         address,
-                        requiredAllowance,
-                        revertMessage: 'Vault share token approval reverted on-chain'
-                    }), (txHash)=>txHash);
-            }
-            const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>executeEarnAction({
-                    adapter,
-                    chain,
-                    address,
-                    actionKey: 'earn.withdraw',
-                    actionParams: {
-                        executeParams: executionParams,
-                        tokenInputs,
-                        signature
-                    },
-                    revertMessage: 'Earn withdraw reverted on-chain'
-                }), ({ txHash })=>txHash);
+                        actionKey: 'earn.withdraw',
+                        actionParams: {
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature
+                        },
+                        revertMessage: 'Earn withdraw reverted on-chain'
+                    });
+                    reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
+                    return result;
+                } catch (error) {
+                    reportTransactionFailure(transactionReportContext, 'Withdraw', error);
+                    throw error;
+                }
+            }, ({ txHash })=>txHash);
             return {
                 txHash,
                 explorerUrl,
@@ -15678,141 +16654,6 @@ function finishElapsedWait(lastStatus, lastError) {
                 }
         }
     }
-    gasEstimateFailure(name, chain, error) {
-        return {
-            name,
-            token: chain.nativeCurrency.symbol,
-            blockchain: chain.chain,
-            fees: null,
-            error: getErrorMessage(error)
-        };
-    }
-    async estimateDepositQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, amount, config } = params;
-        try {
-            const adapterContractAddress = requireAdapterContract(chain);
-            const normalizedVaultAddress = assertHexAddress('vaultAddress', vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await fetchDeposit({
-                vaultAddress: normalizedVaultAddress,
-                amount,
-                address,
-                chain: apiChain,
-                config
-            });
-            validateExecutionDeadline(executionParams);
-            const approvalToken = resolveEarnApprovalToken(executionParams);
-            const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
-            const requiredAllowance = sumTokenInputAmounts(tokenInputs);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Deposit',
-                actionKey: 'earn.deposit',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs,
-                    signature
-                },
-                approval: approvalToken !== undefined && requiredAllowance > 0n ? {
-                    token: approvalToken,
-                    delegate: adapterContractAddress,
-                    requiredAllowance
-                } : undefined
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Deposit', chain, error)
-            ];
-        }
-    }
-    async estimateWithdrawalQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, amount, config } = params;
-        try {
-            const adapterContractAddress = requireAdapterContract(chain);
-            const normalizedVaultAddress = assertHexAddress('vaultAddress', vaultAddress, 'Vault address must be a 0x-prefixed 20-byte hex address.');
-            const { executionParams, signature } = await fetchWithdraw({
-                vaultAddress: normalizedVaultAddress,
-                amount,
-                address,
-                chain: apiChain,
-                config
-            });
-            validateExecutionDeadline(executionParams);
-            const tokenInputs = buildEarnTokenInputs(executionParams, normalizedVaultAddress);
-            const approvalToken = tokenInputs[0]?.token;
-            const requiredAllowance = sumTokenInputAmounts(tokenInputs);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Withdraw',
-                actionKey: 'earn.withdraw',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs,
-                    signature
-                },
-                approval: approvalToken !== undefined ? {
-                    token: approvalToken,
-                    delegate: adapterContractAddress,
-                    requiredAllowance
-                } : undefined
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Withdraw', chain, error)
-            ];
-        }
-    }
-    async estimateClaimRewardsQuoteGasFees(params) {
-        const { adapter, chain, apiChain, address, vaultAddress, config } = params;
-        try {
-            requireAdapterContract(chain);
-            const { rewards, executionParams, signature } = await fetchClaimRewards({
-                address,
-                chain: apiChain,
-                vaultAddress,
-                config
-            });
-            if (rewards.length === 0) {
-                return [];
-            }
-            const missingExecutionParams = executionParams === undefined;
-            const missingSignature = signature === undefined;
-            if (missingExecutionParams || missingSignature) {
-                throw new KitError({
-                    ...EarnError.INTERNAL_ERROR,
-                    recoverability: 'RETRYABLE',
-                    message: 'Claim rewards response must include executionParams and signature when rewards are claimable',
-                    cause: {
-                        trace: {
-                            rewardsCount: rewards.length,
-                            missingExecutionParams,
-                            missingSignature
-                        }
-                    }
-                });
-            }
-            validateExecutionDeadline(executionParams);
-            return await estimateEarnQuoteGasFees({
-                adapter,
-                chain,
-                address,
-                actionName: 'Claim Rewards',
-                actionKey: 'earn.claimRewards',
-                actionParams: {
-                    executeParams: executionParams,
-                    tokenInputs: [],
-                    signature
-                }
-            });
-        } catch (error) {
-            return [
-                this.gasEstimateFailure('Claim Rewards', chain, error)
-            ];
-        }
-    }
     /** {@inheritdoc} */ async getDepositQuote(params) {
         const config = this.resolveConfig(params.config);
         if (hasQuoteDestinationChain(params)) {
@@ -15835,96 +16676,43 @@ function finishElapsedWait(lastStatus, lastError) {
             throw createValidationFailedError('chain', destinationChain.chain, 'chain is only supported for cross-chain Earn deposit quotes; omit chain/address when quoting on the source chain');
         }
         const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        // The quote fetch and the gas estimation share no data, so run them
-        // concurrently. The estimator never rejects (failures fold into
-        // `{ fees: null }` entries), so only a quote failure can throw here.
-        const [quote, gasFees] = await Promise.all([
-            fetchDepositQuote({
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                address,
-                chain,
-                config
-            }),
-            this.estimateDepositQuoteGasFees({
-                adapter: params.from.adapter,
-                chain: chainDefinition,
-                apiChain: chain,
-                address,
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                config
-            })
-        ]);
-        return {
-            ...quote,
-            gasFees
-        };
+        // Gas is estimated server-side by the Earn Service and returned on the quote, so the
+        // SDK no longer simulates it locally. `chainDefinition` lets the fetch fill
+        // the native token symbol / blockchain on each gas entry.
+        return fetchDepositQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+            chainDefinition
+        });
     }
     /** {@inheritdoc} */ async getWithdrawalQuote(params) {
         const config = this.resolveConfig(params.config);
         const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        // The quote fetch and the gas estimation share no data, so run them
-        // concurrently. The estimator never rejects (failures fold into
-        // `{ fees: null }` entries), so only a quote failure can throw here.
-        const [quote, gasFees] = await Promise.all([
-            fetchWithdrawalQuote({
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                address,
-                chain,
-                config
-            }),
-            this.estimateWithdrawalQuoteGasFees({
-                adapter: params.from.adapter,
-                chain: chainDefinition,
-                apiChain: chain,
-                address,
-                vaultAddress: params.vaultAddress,
-                amount: params.amount,
-                config
-            })
-        ]);
-        return {
-            ...quote,
-            gasFees
-        };
+        // Gas is estimated server-side by the Earn Service and returned on the quote.
+        return fetchWithdrawalQuote({
+            vaultAddress: params.vaultAddress,
+            amount: params.amount,
+            address,
+            chain,
+            config,
+            chainDefinition
+        });
     }
     /** {@inheritdoc} */ async getClaimRewardsQuote(params) {
         const config = this.resolveConfig(params.config);
-        const { address, chain, chainDefinition } = await resolveAdapterContext(params.from);
-        const quote = await fetchClaimRewardsQuote({
+        const { address, chain } = await resolveAdapterContext(params.from);
+        // The claimRewards/quote response carries no gas estimate (unlike
+        // deposit/withdrawal quotes), and the SDK no longer estimates gas locally,
+        // so gasFees is always empty for claim rewards.
+        return fetchClaimRewardsQuote({
             vaultAddress: params.vaultAddress,
             address,
             chain,
             config
         });
-        // No claimable rewards means there is nothing to execute, so there is no
-        // gas to estimate. Short-circuit on the already-fetched quote rather than
-        // calling the (heavier) claim execution endpoint again — this also keeps
-        // `gasFees` empty as documented, instead of risking a `{ fees: null }`
-        // estimation-error entry when the adapter/RPC is unavailable. This
-        // short-circuit is why the claim path stays sequential instead of using
-        // the Promise.all pattern of the deposit/withdrawal quotes: estimating in
-        // parallel would hit the signing endpoint even when nothing is claimable.
-        if (quote.rewards.length === 0) {
-            return {
-                ...quote,
-                gasFees: []
-            };
-        }
-        const gasFees = await this.estimateClaimRewardsQuoteGasFees({
-            adapter: params.from.adapter,
-            chain: chainDefinition,
-            apiChain: chain,
-            address,
-            vaultAddress: params.vaultAddress,
-            config
-        });
-        return {
-            ...quote,
-            gasFees
-        };
     }
 }
 function hasDepositDestination(params) {
@@ -16103,6 +16891,12 @@ function createUnsupportedCrossChainDepositError(chain, reason) {
     if (config.providers !== undefined && !Array.isArray(config.providers)) {
         throw createValidationFailedError('config.providers', config.providers, 'providers must be an array of earn providers when provided');
     }
+    if (config.disableAnalytics !== undefined && typeof config.disableAnalytics !== 'boolean') {
+        throw createValidationFailedError('config.disableAnalytics', config.disableAnalytics, 'disableAnalytics must be a boolean when provided');
+    }
+    if (config.disableErrorReporting !== undefined && typeof config.disableErrorReporting !== 'boolean') {
+        throw createValidationFailedError('config.disableErrorReporting', config.disableErrorReporting, 'disableErrorReporting must be a boolean when provided');
+    }
     const defaultProviders = getDefaultProviders();
     const providers = [
         ...config.providers ?? [],
@@ -16114,6 +16908,31 @@ function createUnsupportedCrossChainDepositError(chain, reason) {
     return context;
 }
 
+/**
+ * Register Earn Kit telemetry event type strings with the shared registry so
+ * error telemetry helpers remain compile-time checked.
+ *
+ * @internal
+ */ /**
+ * Telemetry event type identifiers for Earn Kit operations.
+ *
+ * @internal
+ */ const EARN_EVENT_TYPES = {
+    GET_VAULTS: 'earn_get_vaults',
+    EXPLORE_VAULTS: 'earn_explore_vaults',
+    GET_POSITION: 'earn_get_position',
+    GET_CROSS_CHAIN_DEPOSIT_STATUS: 'earn_get_cross_chain_deposit_status',
+    WAIT_FOR_CROSS_CHAIN_DEPOSIT: 'earn_wait_for_cross_chain_deposit',
+    DEPOSIT: 'earn_deposit',
+    CROSS_CHAIN_DEPOSIT: 'earn_cross_chain_deposit',
+    WITHDRAW: 'earn_withdraw',
+    CLAIM_REWARDS: 'earn_claim_rewards',
+    GET_DEPOSIT_QUOTE: 'earn_get_deposit_quote',
+    GET_WITHDRAWAL_QUOTE: 'earn_get_withdrawal_quote',
+    GET_CLAIM_REWARDS_QUOTE: 'earn_get_claim_rewards_quote',
+    RETRY: 'earn_retry'
+};
+
 /**
  * Format a provider amount object as a human-readable decimal string.
  *
@@ -16162,11 +16981,27 @@ function formatPositionPnL(pnl) {
  * @param vault - Provider vault info with raw amount objects
  * @returns Vault info with total deposits and liquidity formatted as strings
  */ function formatVaultInfo(vault) {
-    const { totalDeposits, liquidity, ...rest } = vault;
+    // The flat `totalDeposits`/`liquidity` are deprecated aliases that are
+    // intentionally dual-read through the migration window so existing
+    // consumers keep receiving them until Contract.
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    const { totalDeposits, liquidity, liquidityProfile, ...rest } = vault;
+    // `liquidityProfile` is `.optional()` in the response schema during the
+    // expand/contract window (an old backend that predates the nested facets
+    // omits it), so only format and re-attach it when present — matching the
+    // provider-side `toVaultInfo` mapper.
     return {
         ...rest,
         totalDeposits: formatAmount(totalDeposits),
-        liquidity: formatAmount(liquidity)
+        liquidity: formatAmount(liquidity),
+        ...liquidityProfile !== undefined && {
+            liquidityProfile: {
+                ...liquidityProfile,
+                totalDeposits: formatAmount(liquidityProfile.totalDeposits),
+                available: formatAmount(liquidityProfile.available),
+                totalSupply: formatAmount(liquidityProfile.totalSupply)
+            }
+        }
     };
 }
 /**
@@ -17613,6 +18448,14 @@ function hasCrossChainDestination(params) {
     return formatClaimRewardsQuoteInfo(result);
 }
 
+/** SDK name used in telemetry payloads. */ const SDK_NAME = resolveKitSdkName(pkg$1.name);
+/**
+ * Determine whether deposit parameters target a destination chain.
+ *
+ * @internal
+ */ function isCrossChainDeposit(params) {
+    return 'to' in params && params.to !== undefined;
+}
 function formatRetryResult(operation, result) {
     switch(operation){
         case 'deposit':
@@ -17627,6 +18470,70 @@ function formatRetryResult(operation, result) {
             }
     }
 }
+/**
+ * Emit the success event corresponding to a completed retry.
+ *
+ * @internal
+ */ function emitRetrySuccessTelemetry(trace, result, config) {
+    switch(trace.operation){
+        case 'deposit':
+            {
+                const sourceChain = resolveChainName(trace.params.from.chain);
+                if ('to' in trace.params && trace.params.to !== undefined) {
+                    const destinationChain = resolveChainName(trace.params.to.chain);
+                    emitSuccessTelemetry(EARN_EVENT_TYPES.CROSS_CHAIN_DEPOSIT, config, {
+                        ...sourceChain != null && {
+                            sourceChain
+                        },
+                        ...destinationChain != null && {
+                            destinationChain
+                        }
+                    });
+                    return;
+                }
+                emitSuccessTelemetry(EARN_EVENT_TYPES.DEPOSIT, config, {
+                    ...sourceChain != null && {
+                        sourceChain
+                    },
+                    ...'txHash' in result && {
+                        txHash: result.txHash
+                    }
+                });
+                return;
+            }
+        case 'withdraw':
+            {
+                const sourceChain = resolveChainName(trace.params.from.chain);
+                emitSuccessTelemetry(EARN_EVENT_TYPES.WITHDRAW, config, {
+                    ...sourceChain != null && {
+                        sourceChain
+                    },
+                    ...'txHash' in result && {
+                        txHash: result.txHash
+                    }
+                });
+                return;
+            }
+        case 'claimRewards':
+            {
+                if ('rewards' in result && result.status === 'claimed') {
+                    const sourceChain = resolveChainName(trace.params.from.chain);
+                    emitSuccessTelemetry(EARN_EVENT_TYPES.CLAIM_REWARDS, config, {
+                        ...sourceChain != null && {
+                            sourceChain
+                        },
+                        txHash: result.txHash
+                    });
+                }
+                return;
+            }
+        default:
+            {
+                const exhaustive = trace;
+                throw createValidationFailedError('error.cause.trace', exhaustive, 'EarnKit.retry() does not support this earn operation');
+            }
+    }
+}
 /**
  * A high-level class-based interface for DeFi lending vault operations.
  *
@@ -17685,6 +18592,8 @@ function formatRetryResult(operation, result) {
  * ```
  */ class EarnKit {
     context;
+    /** Per-kit identity and opt-out state for error telemetry. */ telemetryConfig;
+    /** Per-kit identity and opt-out state for success telemetry. */ analyticsTelemetryConfig;
     /**
    * Event dispatcher for step-level events emitted during multi-phase earn
    * operations. Prefer {@link EarnKit.on} / {@link EarnKit.off} over using
@@ -17709,6 +18618,16 @@ function formatRetryResult(operation, result) {
    */ constructor(config = {}){
         this.context = createEarnKitContext(config);
         this.actionDispatcher = new Actionable();
+        this.telemetryConfig = {
+            sdkName: SDK_NAME,
+            sdkVersion: pkg$1.version,
+            disabled: config.disableErrorReporting === true
+        };
+        this.analyticsTelemetryConfig = {
+            sdkName: SDK_NAME,
+            sdkVersion: pkg$1.version,
+            disabled: config.disableAnalytics === true
+        };
         for (const provider of this.context.providers){
             provider.registerDispatcher(this.actionDispatcher);
         }
@@ -17769,29 +18688,36 @@ function formatRetryResult(operation, result) {
    * }
    * ```
    */ async retry(error) {
-        if (!isKitError(error)) {
-            throw createValidationFailedError('error', error, 'EarnKit.retry() requires a KitError thrown by a previous earn operation');
-        }
-        if (!isRetryableError$1(error)) {
-            throw createValidationFailedError('error.recoverability', error.recoverability, 'EarnKit.retry() requires a retryable or resumable error — check isRetryableError(error) first');
-        }
-        const trace = error.cause?.trace;
-        if (!isEarnErrorTrace(trace)) {
-            throw createValidationFailedError('error.cause.trace', trace, 'EarnKit.retry() requires a KitError carrying earn retry context (operation, steps, provider, params)');
-        }
-        const provider = this.context.providers.find((candidate)=>candidate.name === trace.provider);
-        if (provider === undefined) {
-            throw createValidationFailedError('error.cause.trace.provider', trace.provider, `No earn provider named "${trace.provider}" is registered with this kit`);
-        }
-        const result = await provider.retry(error);
-        // `provider.retry` returns a flat result union with no compile-time link to
-        // `trace.operation`, so narrow the operation here to select the matching
-        // overload. The result cast in each branch is sound: the provider always
-        // returns the result type corresponding to the resumed operation.
-        if (trace.operation === 'claimRewards') {
+        const result = await withErrorTelemetry(async ()=>{
+            if (!isKitError(error)) {
+                throw createValidationFailedError('error', error, 'EarnKit.retry() requires a KitError thrown by a previous earn operation');
+            }
+            if (!isRetryableError$1(error)) {
+                throw createValidationFailedError('error.recoverability', error.recoverability, 'EarnKit.retry() requires a retryable or resumable error — check isRetryableError(error) first');
+            }
+            const trace = error.cause?.trace;
+            if (!isEarnErrorTrace(trace)) {
+                throw createValidationFailedError('error.cause.trace', trace, 'EarnKit.retry() requires a KitError carrying earn retry context (operation, steps, provider, params)');
+            }
+            const provider = this.context.providers.find((candidate)=>candidate.name === trace.provider);
+            if (provider === undefined) {
+                throw createValidationFailedError('error.cause.trace.provider', trace.provider, `No earn provider named "${trace.provider}" is registered with this kit`);
+            }
+            const result = await provider.retry(error);
+            // `provider.retry` returns a flat result union with no compile-time link to
+            // `trace.operation`, so narrow the operation here to select the matching
+            // overload. The result cast in each branch is sound: the provider always
+            // returns the result type corresponding to the resumed operation.
+            if (trace.operation === 'claimRewards') {
+                return formatRetryResult(trace.operation, result);
+            }
             return formatRetryResult(trace.operation, result);
+        }, EARN_EVENT_TYPES.RETRY, this.telemetryConfig);
+        const trace = isKitError(error) ? error.cause?.trace : undefined;
+        if (isEarnErrorTrace(trace)) {
+            emitRetrySuccessTelemetry(trace, result, this.analyticsTelemetryConfig);
         }
-        return formatRetryResult(trace.operation, result);
+        return result;
     }
     /**
    * Return the chains supported by configured earn providers.
@@ -17825,7 +18751,9 @@ function formatRetryResult(operation, result) {
    * result.vaults.forEach(v => console.log(`${v.name}: ${(v.currentApy * 100).toFixed(2)}% APY`))
    * ```
    */ async getVaults(params) {
-        return getVaults$1(this.context, params);
+        const result = await withErrorTelemetry(async ()=>getVaults$1(this.context, params), EARN_EVENT_TYPES.GET_VAULTS, this.telemetryConfig);
+        emitSuccessTelemetry(EARN_EVENT_TYPES.GET_VAULTS, this.analyticsTelemetryConfig, {});
+        return result;
     }
     /**
    * Discover vaults available on a chain.
@@ -17850,7 +18778,12 @@ function formatRetryResult(operation, result) {
    * const guarded = result.vaults.filter(v => v.circleGuarded) // Circle-guarded vaults only
    * ```
    */ async exploreVaults(params) {
-        return exploreVaults$1(this.context, params);
+        const context = {
+            sourceChain: resolveChainName(params.chain)
+        };
+        const result = await withErrorTelemetry(async ()=>exploreVaults$1(this.context, params), EARN_EVENT_TYPES.EXPLORE_VAULTS, this.telemetryConfig, context);
+        emitSuccessTelemetry(EARN_EVENT_TYPES.EXPLORE_VAULTS, this.analyticsTelemetryConfig, context);
+        return result;
     }
     /**
    * Lazily iterate every vault available on a chain.
@@ -17897,7 +18830,9 @@ function formatRetryResult(operation, result) {
    * }
    * ```
    */ async getPosition(params) {
-        return getPosition$1(this.context, params);
+        return withErrorTelemetry(async ()=>getPosition$1(this.context, params), EARN_EVENT_TYPES.GET_POSITION, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain)
+        });
     }
     /**
    * Fetch the current status of a cross-chain deposit by execution ID.
@@ -17922,7 +18857,7 @@ function formatRetryResult(operation, result) {
    * console.log(`Bridge ${status.execId} is ${status.status}`)
    * ```
    */ async getCrossChainDepositStatus(params) {
-        return getCrossChainDepositStatus$1(this.context, params);
+        return withErrorTelemetry(async ()=>getCrossChainDepositStatus$1(this.context, params), EARN_EVENT_TYPES.GET_CROSS_CHAIN_DEPOSIT_STATUS, this.telemetryConfig);
     }
     /**
    * Poll a cross-chain deposit until it reaches a terminal bridge state.
@@ -17949,10 +18884,30 @@ function formatRetryResult(operation, result) {
    * console.log(`Bridge ended as ${result.outcome}`)
    * ```
    */ async waitForCrossChainDeposit(params) {
-        return waitForCrossChainDeposit$1(this.context, params);
+        return withErrorTelemetry(async ()=>waitForCrossChainDeposit$1(this.context, params), EARN_EVENT_TYPES.WAIT_FOR_CROSS_CHAIN_DEPOSIT, this.telemetryConfig);
     }
     async deposit(params) {
-        return deposit$1(this.context, params);
+        const isCrossChain = isCrossChainDeposit(params);
+        const context = {
+            sourceChain: resolveChainName(params.from.chain),
+            ...isCrossChain && {
+                destinationChain: resolveChainName(params.to.chain)
+            }
+        };
+        const eventType = isCrossChain ? EARN_EVENT_TYPES.CROSS_CHAIN_DEPOSIT : EARN_EVENT_TYPES.DEPOSIT;
+        const result = await withErrorTelemetry(async ()=>deposit$1(this.context, params), eventType, this.telemetryConfig, context);
+        if (result.kind === 'cross-chain') {
+            emitSuccessTelemetry(EARN_EVENT_TYPES.CROSS_CHAIN_DEPOSIT, this.analyticsTelemetryConfig, {
+                sourceChain: resolveChainName(result.sourceChain),
+                destinationChain: resolveChainName(result.destinationChain)
+            });
+        } else {
+            emitSuccessTelemetry(EARN_EVENT_TYPES.DEPOSIT, this.analyticsTelemetryConfig, {
+                ...context,
+                txHash: result.txHash
+            });
+        }
+        return result;
     }
     /**
    * Execute a withdrawal from a DeFi lending vault.
@@ -17978,7 +18933,15 @@ function formatRetryResult(operation, result) {
    * console.log(`Withdrew ${result.amount} from ${result.vaultAddress}, tx: ${result.txHash}`)
    * ```
    */ async withdraw(params) {
-        return withdraw$1(this.context, params);
+        const context = {
+            sourceChain: resolveChainName(params.from.chain)
+        };
+        const result = await withErrorTelemetry(async ()=>withdraw$1(this.context, params), EARN_EVENT_TYPES.WITHDRAW, this.telemetryConfig, context);
+        emitSuccessTelemetry(EARN_EVENT_TYPES.WITHDRAW, this.analyticsTelemetryConfig, {
+            ...context,
+            txHash: result.txHash
+        });
+        return result;
     }
     /**
    * Claim rewards from earn vaults.
@@ -18005,7 +18968,17 @@ function formatRetryResult(operation, result) {
    *
    * @internal
    */ async claimRewards(params) {
-        return claimRewards$1(this.context, params);
+        const context = {
+            sourceChain: resolveChainName(params.from.chain)
+        };
+        const result = await withErrorTelemetry(async ()=>claimRewards$1(this.context, params), EARN_EVENT_TYPES.CLAIM_REWARDS, this.telemetryConfig, context);
+        if (result.status === 'claimed') {
+            emitSuccessTelemetry(EARN_EVENT_TYPES.CLAIM_REWARDS, this.analyticsTelemetryConfig, {
+                ...context,
+                txHash: result.txHash
+            });
+        }
+        return result;
     }
     /**
    * Get an informational quote for a deposit into a vault.
@@ -18027,7 +19000,9 @@ function formatRetryResult(operation, result) {
    * console.log(`Expected shares: ${quote.expectedShares.amount}`)
    * ```
    */ async getDepositQuote(params) {
-        return getDepositQuote$1(this.context, params);
+        return withErrorTelemetry(async ()=>getDepositQuote$1(this.context, params), EARN_EVENT_TYPES.GET_DEPOSIT_QUOTE, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain)
+        });
     }
     /**
    * Get an informational quote for a withdrawal from a vault.
@@ -18049,7 +19024,9 @@ function formatRetryResult(operation, result) {
    * console.log(`Shares to redeem: ${quote.sharesToRedeem.amount}`)
    * ```
    */ async getWithdrawalQuote(params) {
-        return getWithdrawalQuote$1(this.context, params);
+        return withErrorTelemetry(async ()=>getWithdrawalQuote$1(this.context, params), EARN_EVENT_TYPES.GET_WITHDRAWAL_QUOTE, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain)
+        });
     }
     /**
    * Get an informational quote for claiming rewards.
@@ -18071,34 +19048,111 @@ function formatRetryResult(operation, result) {
    *
    * @internal
    */ async getClaimRewardsQuote(params) {
-        return getClaimRewardsQuote$1(this.context, params);
+        return withErrorTelemetry(async ()=>getClaimRewardsQuote$1(this.context, params), EARN_EVENT_TYPES.GET_CLAIM_REWARDS_QUOTE, this.telemetryConfig, {
+            sourceChain: resolveChainName(params.from.chain)
+        });
     }
 }
 
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg$1.name}/${pkg$1.version}`);
 
+/**
+ * Register event handlers from a context actions map to a kit instance.
+ *
+ * This utility function registers event handlers stored in a context actions map
+ * with a kit instance that supports event handling via an `on` method. It handles
+ * wildcard handlers ('*') and prefixed action handlers, stripping the prefix
+ * before registration.
+ *
+ * The function is designed to be reusable across different operation types
+ * (bridge, swap, stake, etc.) by accepting a configurable prefix parameter.
+ *
+ * @param kit - The kit instance to register handlers with (must have an `on` method)
+ * @param handlers - Map of action names to arrays of handler functions
+ * @param prefix - Optional prefix to strip from action names (e.g., 'bridge.')
+ *
+ * @example
+ * ```typescript
+ * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
+ * import { BridgeKit } from '@circle-fin/bridge-kit'
+ *
+ * const kit = new BridgeKit()
+ * const handlers = {
+ *   '*': [(payload) => console.log('All actions:', payload)],
+ *   'bridge.approve': [(payload) => console.log('Approved:', payload)],
+ *   'bridge.burn': [(payload) => console.log('Burned:', payload)],
+ * }
+ *
+ * registerActionHandlers(kit, handlers, 'bridge.')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { registerActionHandlers } from '@circle-fin/app-kit/utils'
+ * import { SwapKit } from '@circle-fin/swap-kit'
+ *
+ * const kit = new SwapKit()
+ * const handlers = {
+ *   'swap.initiate': [(payload) => console.log('Swap initiated:', payload)],
+ * }
+ *
+ * registerActionHandlers(kit, handlers, 'swap.')
+ * ```
+ */ const registerActionHandlers = (kit, handlers, prefix = '')=>{
+    for (const [action, handlerArray] of Object.entries(handlers)){
+        // Register all handlers for this action
+        for (const handler of handlerArray){
+            if (action === '*') {
+                // Wildcard handlers are registered as-is
+                kit.on('*', handler);
+            } else if (prefix && action.startsWith(prefix)) {
+                // Remove prefix to get the actual kit action name
+                const kitAction = action.split('.').at(1);
+                if (kitAction) {
+                    kit.on(kitAction, handler);
+                }
+            } else if (!prefix) {
+                // No prefix configured, register action as-is
+                kit.on(action, handler);
+            }
+        // Actions that don't match the prefix are silently ignored
+        }
+    }
+};
+
 /**
  * Create an EarnKit instance for AppKit earn operations.
  *
- * @remarks The context parameter is reserved for future EarnKit wiring.
- * EarnKit does not currently support AppKit developer fee hooks, so the
- * factory does not read fee callbacks from the context. Earn custom fees remain
- * reserved until EarnKit fee support ships.
+ * Attaches any earn event handlers previously registered on the AppKit
+ * context (via `kit.on('earn.*', …)` or `kit.on('*', …)`) so step events
+ * fire during the returned kit's earn operations.
  *
- * When EarnKit supports developer fee hooks, this factory can wire AppKit context through.
+ * @remarks Developer fee hooks from the AppKit context are not applied.
+ * EarnKit does not yet support custom fee policies.
  *
- * @param context - AppKit context reserved for future EarnKit wiring
- * @returns A new EarnKit instance
+ * @param context - AppKit context with earn event handlers and kit options
+ * @returns An EarnKit instance ready for AppKit earn operations
  *
  * @example
  * ```typescript
  * const earnKit = createEarnKit(context)
  * ```
- */ const createEarnKit = ()=>new EarnKit();
+ */ const createEarnKit = (context)=>{
+    const kit = new EarnKit({
+        ...context.disableErrorReporting != null && {
+            disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.disableAnalytics != null && {
+            disableAnalytics: context.disableAnalytics
+        }
+    });
+    registerActionHandlers(kit, context.actions.earn, 'earn');
+    return kit;
+};
 
 async function deposit(context, params) {
-    return createEarnKit().deposit(params);
+    return createEarnKit(context).deposit(params);
 }
 /**
  * Execute an earn withdrawal operation.
@@ -18122,7 +19176,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function withdraw(context, params) {
-    return createEarnKit().withdraw(params);
+    return createEarnKit(context).withdraw(params);
 }
 /**
  * Claim earn rewards.
@@ -18145,7 +19199,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function claimRewards(context, params) {
-    return createEarnKit().claimRewards(params);
+    return createEarnKit(context).claimRewards(params);
 }
 /**
  * Fetch vault information.
@@ -18167,7 +19221,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getVaults(context, params) {
-    return createEarnKit().getVaults(params);
+    return createEarnKit(context).getVaults(params);
 }
 /**
  * Discover vaults available on a chain.
@@ -18191,7 +19245,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function exploreVaults(context, params) {
-    return createEarnKit().exploreVaults(params);
+    return createEarnKit(context).exploreVaults(params);
 }
 /**
  * Lazily iterate every vault available on a chain.
@@ -18215,7 +19269,7 @@ async function deposit(context, params) {
  * }
  * ```
  */ function exploreVaultsIterator(context, params) {
-    return createEarnKit().exploreVaultsIterator(params);
+    return createEarnKit(context).exploreVaultsIterator(params);
 }
 /**
  * Fetch a wallet position in a vault.
@@ -18238,7 +19292,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getPosition(context, params) {
-    return createEarnKit().getPosition(params);
+    return createEarnKit(context).getPosition(params);
 }
 /**
  * Fetch the current status of a cross-chain Earn deposit.
@@ -18260,7 +19314,7 @@ async function deposit(context, params) {
  * console.log(status.status)
  * ```
  */ async function getCrossChainDepositStatus(context, params) {
-    return createEarnKit().getCrossChainDepositStatus(params);
+    return createEarnKit(context).getCrossChainDepositStatus(params);
 }
 /**
  * Poll a cross-chain Earn deposit until it reaches a terminal bridge state.
@@ -18283,7 +19337,7 @@ async function deposit(context, params) {
  * console.log(result.outcome)
  * ```
  */ async function waitForCrossChainDeposit(context, params) {
-    return createEarnKit().waitForCrossChainDeposit(params);
+    return createEarnKit(context).waitForCrossChainDeposit(params);
 }
 /**
  * Fetch a deposit quote.
@@ -18307,7 +19361,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getDepositQuote(context, params) {
-    return createEarnKit().getDepositQuote(params);
+    return createEarnKit(context).getDepositQuote(params);
 }
 /**
  * Fetch a withdrawal quote.
@@ -18331,7 +19385,7 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getWithdrawalQuote(context, params) {
-    return createEarnKit().getWithdrawalQuote(params);
+    return createEarnKit(context).getWithdrawalQuote(params);
 }
 /**
  * Fetch a claim rewards quote.
@@ -18354,7 +19408,43 @@ async function deposit(context, params) {
  * })
  * ```
  */ async function getClaimRewardsQuote(context, params) {
-    return createEarnKit().getClaimRewardsQuote(params);
+    return createEarnKit(context).getClaimRewardsQuote(params);
+}
+/**
+ * Resume a multi-phase earn operation that previously failed.
+ *
+ * Pass the {@link KitError} caught from `deposit`, `withdraw`, or
+ * `claimRewards`. Completed phases can be skipped when the error carries
+ * earn retry context. Call `isRetryableError(error)` first.
+ *
+ * @remarks
+ * Retry re-fetches execution params and may re-submit the execute
+ * transaction. Treat this as best-effort recovery if a prior execute
+ * broadcast may still be in flight.
+ *
+ * @param context - AppKit context
+ * @param error - The error caught from a previous multi-phase earn operation
+ * @returns Promise resolving to the result of the resumed operation
+ * @throws If the error is not retryable or lacks earn retry context
+ *
+ * @example
+ * ```typescript
+ * import { isRetryableError } from '@circle-fin/app-kit'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ * import { retry } from '@circle-fin/app-kit/earn'
+ *
+ * const context = createContext()
+ *
+ * try {
+ *   await deposit(context, params)
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     const result = await retry(context, error)
+ *   }
+ * }
+ * ```
+ */ async function retry(context, error) {
+    return createEarnKit(context).retry(error);
 }
 
 exports.claimRewards = claimRewards;
@@ -18367,6 +19457,7 @@ exports.getDepositQuote = getDepositQuote;
 exports.getPosition = getPosition;
 exports.getVaults = getVaults;
 exports.getWithdrawalQuote = getWithdrawalQuote;
+exports.retry = retry;
 exports.waitForCrossChainDeposit = waitForCrossChainDeposit;
 exports.withdraw = withdraw;
 //# sourceMappingURL=earn.cjs.map