@circle-fin/app-kit 1.10.0 → 1.11.0

package/earn.mjs

@@ -16,6 +16,17 @@
  * limitations under the License.
  */
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 import { z } from 'zod';
 import 'pino';
 import '@ethersproject/bytes';
@@ -26,8 +37,8 @@ import 'bn.js';
 import '@coral-xyz/anchor';
 import 'bs58';
 import '@noble/curves/ed25519';
-import { keccak256 } from '@ethersproject/keccak256';
 import { formatUnits as formatUnits$1 } from '@ethersproject/units';
+import { keccak256 } from '@ethersproject/keccak256';
 
 // Import global type declarations
 /**
@@ -44,6 +55,51 @@ import { formatUnits as formatUnits$1 } from '@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.
  *
@@ -6392,6 +6448,39 @@ const swapTokenEnumSchema = 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.
  *
@@ -6776,13 +6865,12 @@ const swapTokenEnumSchema = 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;
@@ -8048,6 +8136,216 @@ const swapTokenEnumSchema = z.enum([
  * 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.
@@ -8066,8 +8364,154 @@ const swapTokenEnumSchema = 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.1";
+var version$3 = "1.12.2";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -8895,7 +9339,13 @@ var TransferSpeed;
 /**
  * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
  * hookData must start with.
- */ Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+ *
+ * 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.
@@ -8929,7 +9379,7 @@ var TransferSpeed;
 registerKit(`${pkg$3.name}/${pkg$3.version}`);
 
 var name$2 = "@circle-fin/swap-kit";
-var version$2 = "1.4.0";
+var version$2 = "1.5.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -9670,6 +10120,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: z.preprocess((value)=>z.string().uuid().safeParse(value).success ? value : undefined, z.string().optional()),
     config: createSwapRequestBaseSchema.shape.config.optional(),
     fees: createSwapFeesSchema.optional(),
     transaction: createSwapTransactionSchema
@@ -12228,7 +12688,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/earn-kit";
-var version$1 = "1.3.0";
+var version$1 = "1.4.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -14227,7 +14687,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name = "@circle-fin/provider-earn-service";
-var version = "1.3.0";
+var version = "1.3.1";
 var pkg = {
 	name: name,
 	version: version};
@@ -14289,15 +14749,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
@@ -14315,7 +14785,7 @@ var pkg = {
             ...DEFAULT_CONFIG,
             headers: {
                 ...DEFAULT_CONFIG.headers,
-                [SDK_VERSION_HEADER]: sdkVersion,
+                ...sdkVersionHeader,
                 Authorization: `Bearer ${serviceConfig.kitKey}`
             }
         },
@@ -16419,6 +16889,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 ?? [],
@@ -16430,6 +16906,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.
  *
@@ -17945,6 +18446,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':
@@ -17959,6 +18468,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.
  *
@@ -18017,6 +18590,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
@@ -18041,6 +18616,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);
         }
@@ -18101,29 +18686,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.
@@ -18157,7 +18749,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.
@@ -18182,7 +18776,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.
@@ -18229,7 +18828,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.
@@ -18254,7 +18855,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.
@@ -18281,10 +18882,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.
@@ -18310,7 +18931,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.
@@ -18337,7 +18966,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.
@@ -18359,7 +18998,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.
@@ -18381,7 +19022,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.
@@ -18403,7 +19046,9 @@ 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)
+        });
     }
 }
 
@@ -18492,7 +19137,14 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
  * const earnKit = createEarnKit(context)
  * ```
  */ const createEarnKit = (context)=>{
-    const kit = new EarnKit();
+    const kit = new EarnKit({
+        ...context.disableErrorReporting != null && {
+            disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.disableAnalytics != null && {
+            disableAnalytics: context.disableAnalytics
+        }
+    });
     registerActionHandlers(kit, context.actions.earn, 'earn');
     return kit;
 };