@circle-fin/app-kit 1.10.0 → 1.12.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,9 @@ import 'bn.js';
 import '@coral-xyz/anchor';
 import 'bs58';
 import '@noble/curves/ed25519';
-import { keccak256 } from '@ethersproject/keccak256';
+import { decodeFunctionData } from 'viem';
 import { formatUnits as formatUnits$1 } from '@ethersproject/units';
+import { keccak256 } from '@ethersproject/keccak256';
 
 // Import global type declarations
 /**
@@ -44,6 +56,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.
  *
@@ -621,6 +678,11 @@ class KitError extends Error {
         name: 'INPUT_INSUFFICIENT_SWAP_AMOUNT',
         type: 'INPUT'
     },
+    /** Action not supported by this adapter / ecosystem */ UNSUPPORTED_ACTION: {
+        code: 1008,
+        name: 'INPUT_UNSUPPORTED_ACTION',
+        type: 'INPUT'
+    },
     /** No route satisfies the slippage or minimum-output constraint */ SLIPPAGE_CONSTRAINT_NOT_MET: {
         code: 1009,
         name: 'INPUT_SLIPPAGE_CONSTRAINT_NOT_MET',
@@ -685,6 +747,29 @@ class KitError extends Error {
         type: 'LIQUIDITY'
     }
 };
+/**
+ * Standardized error definitions for RPC type errors.
+ *
+ * RPC errors occur when communicating with blockchain RPC providers,
+ * including endpoint failures, invalid responses, and provider-specific issues.
+ *
+ * @example
+ * ```typescript
+ * import { RpcError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...RpcError.ENDPOINT_ERROR,
+ *   recoverability: 'RETRYABLE',
+ *   message: 'RPC endpoint unavailable on Ethereum',
+ *   cause: { trace: { endpoint: 'https://mainnet.infura.io' } }
+ * })
+ * ```
+ */ const RpcError = {
+    /** RPC endpoint returned error or is unavailable */ ENDPOINT_ERROR: {
+        code: 4001,
+        name: 'RPC_ENDPOINT_ERROR',
+        type: 'RPC'
+    }};
 /**
  * Standardized error definitions for NETWORK type errors.
  *
@@ -2284,6 +2369,8 @@ function getOptionalString(value) {
     Blockchain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     Blockchain["XDC"] = "XDC";
     Blockchain["XDC_Apothem"] = "XDC_Apothem";
+    Blockchain["X_Layer"] = "X_Layer";
+    Blockchain["X_Layer_Testnet"] = "X_Layer_Testnet";
     Blockchain["ZKSync_Era"] = "ZKSync_Era";
     Blockchain["ZKSync_Sepolia"] = "ZKSync_Sepolia";
 })(Blockchain || (Blockchain = {}));
@@ -2337,6 +2424,7 @@ var BridgeChain;
     BridgeChain["Unichain"] = "Unichain";
     BridgeChain["World_Chain"] = "World_Chain";
     BridgeChain["XDC"] = "XDC";
+    BridgeChain["X_Layer"] = "X_Layer";
     // Testnet chains with CCTPv2 support
     BridgeChain["Arc_Testnet"] = "Arc_Testnet";
     BridgeChain["Arbitrum_Sepolia"] = "Arbitrum_Sepolia";
@@ -2362,6 +2450,7 @@ var BridgeChain;
     BridgeChain["Unichain_Sepolia"] = "Unichain_Sepolia";
     BridgeChain["World_Chain_Sepolia"] = "World_Chain_Sepolia";
     BridgeChain["XDC_Apothem"] = "XDC_Apothem";
+    BridgeChain["X_Layer_Testnet"] = "X_Layer_Testnet";
 })(BridgeChain || (BridgeChain = {}));
 var UnifiedBalanceChain;
 (function(UnifiedBalanceChain) {
@@ -4899,7 +4988,8 @@ var EarnChain;
     isTestnet: true,
     explorerUrl: 'https://amoy.polygonscan.com/tx/{hash}',
     rpcEndpoints: [
-        'https://rpc-amoy.polygon.technology'
+        'https://polygon-amoy-bor-rpc.publicnode.com',
+        'https://polygon-amoy.drpc.org'
     ],
     eurcAddress: null,
     usdcAddress: '0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582',
@@ -5764,6 +5854,104 @@ var EarnChain;
     }
 });
 
+/**
+ * X Layer Mainnet chain definition
+ * @remarks
+ * This represents the official production network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayer = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer,
+    name: 'X Layer',
+    title: 'X Layer Mainnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 196,
+    isTestnet: false,
+    explorerUrl: 'https://www.oklink.com/xlayer/tx/{hash}',
+    rpcEndpoints: [
+        'https://xlayerrpc.okx.com'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d',
+                messageTransmitter: '0x81D40F21F12A8F0E3252Bccb954D722d4c464B64',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+    }
+});
+
+/**
+ * X Layer Testnet chain definition
+ * @remarks
+ * This represents the official test network for the X Layer blockchain.
+ * X Layer is an EVM-compatible OP Stack Layer-2 blockchain built by OKX,
+ * using OKB as its native gas token. (Migrated from Polygon zkEVM/CDK to the
+ * OP Stack on 2025-10-27; older docs describing it as zkEVM are obsolete.)
+ */ const XLayerTestnet = defineChain({
+    type: 'evm',
+    chain: Blockchain.X_Layer_Testnet,
+    name: 'X Layer Testnet',
+    title: 'X Layer Testnet',
+    nativeCurrency: {
+        name: 'OKB',
+        symbol: 'OKB',
+        decimals: 18
+    },
+    chainId: 1952,
+    isTestnet: true,
+    // Deliberately not oklink.com (used for mainnet): viem's bundled OKLink
+    // testnet URL targets the deprecated pre-rebrand chain ID 195, not this
+    // chain's ID (1952). Verified against the internal chain-expansion-scripts
+    // config (`v2config.sandbox.yml`) — do not "normalize" this to match mainnet.
+    explorerUrl: 'https://web3.okx.com/explorer/x-layer-testnet/tx/{hash}',
+    rpcEndpoints: [
+        'https://testrpc.xlayer.tech'
+    ],
+    eurcAddress: null,
+    usdcAddress: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
+    usdtAddress: null,
+    cctp: {
+        domain: 37,
+        contracts: {
+            v2: {
+                type: 'split',
+                tokenMessenger: '0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA',
+                messageTransmitter: '0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275',
+                confirmations: 65,
+                fastConfirmations: 1
+            }
+        },
+        forwarderSupported: {
+            source: false,
+            destination: false
+        }
+    },
+    kitContracts: {
+        bridge: BRIDGE_CONTRACT_EVM_TESTNET
+    }
+});
+
 /**
  * ZKSync Era Mainnet chain definition
  * @remarks
@@ -5883,6 +6071,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 });
@@ -6392,6 +6582,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 +6999,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;
@@ -7294,6 +7516,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -7328,6 +7551,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -8042,134 +8266,544 @@ const swapTokenEnumSchema = z.enum([
 }
 
 /**
- * CCTP forwarding magic bytes prefix.
+ * Assert that a value has type `never` (exhaustive switch helper).
  *
- * 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';
-
-/**
- * Strip the `@circle-fin/` scope from a kit package name to produce the
- * short SDK name used in telemetry payloads.
+ * @remarks
+ * Use in the `default` branch of a switch over a discriminated union.
+ * If all union members are handled, the default is unreachable and TypeScript
+ * narrows the parameter to `never`. If a member is missed, the compiler errors.
  *
- * @param pkgName - The full npm package name (e.g. `@circle-fin/bridge-kit`).
- * @returns The unscoped kit name (e.g. `bridge-kit`).
+ * @param _x - The value (typed as `never` when switch is exhaustive).
+ * @returns Never returns; always throws.
+ * @throws Error when the switch is not exhaustive.
  *
  * @example
  * ```typescript
- * import pkg from '../../package.json'
- * import { resolveKitSdkName } from '@core/utils'
+ * type Foo = { type: 'a'; x: number } | { type: 'b'; y: string }
  *
- * const SDK_NAME = resolveKitSdkName(pkg.name) // 'bridge-kit'
+ * function handle(foo: Foo): string {
+ *   switch (foo.type) {
+ *     case 'a': return String(foo.x)
+ *     case 'b': return foo.y
+ *     default: return assertNever(foo)
+ *   }
+ * }
  * ```
- */ function resolveKitSdkName(pkgName) {
-    return pkgName.replace('@circle-fin/', '');
+ */ function assertNever$2(x) {
+    // Plain `String(x)` collapses non-primitive union members (objects, arrays)
+    // to `'[object Object]'`, which is useless when triaging which discriminant
+    // was missed. Attempt `JSON.stringify` first so the thrown message preserves
+    // the offending shape. Fall back to a minimal `typeof`-based label if
+    // serialization fails (`BigInt` member, circular references, host objects).
+    //
+    // `x` is statically typed as `never` (the whole point of this helper), but
+    // at runtime callers may still pass an unexpected value when the switch is
+    // not actually exhaustive — that's exactly the bug we want to surface. Cast
+    // through `unknown` so the runtime defence is not stripped by the compiler.
+    const value = x;
+    let stringified;
+    try {
+        const json = JSON.stringify(value);
+        stringified = typeof json === 'string' ? json : `<${typeof value}>`;
+    } catch  {
+        stringified = `<unstringifiable ${typeof value}>`;
+    }
+    throw new Error(`Unhandled switch case: ${stringified}`);
 }
 
-var name$3 = "@circle-fin/bridge-kit";
-var version$3 = "1.12.1";
-var pkg$3 = {
-	name: name$3,
-	version: version$3};
-
 /**
- * Schema for validating BridgeKit custom fee policy.
+ * CCTP forwarding magic bytes prefix.
  *
- * Validates the shape of {@link CustomFeePolicy}, which lets SDK consumers
- * provide custom fee calculation and fee-recipient resolution logic.
+ * 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.
  *
- * - computeFee: optional function (recommended) that receives human-readable amounts
- *   and returns a fee as a string (or Promise<string>).
- * - calculateFee: optional function (deprecated) that receives smallest-unit amounts
- *   and returns a fee as a string (or Promise<string>).
- * - resolveFeeRecipientAddress: required function that returns a recipient address as a
- *   string (or Promise<string>).
+ * @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.
  *
- * Exactly one of `computeFee` or `calculateFee` must be provided (not both).
+ * @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.
  *
- * This schema only ensures the presence and return types of the functions; it
- * does not validate their argument types.
+ * Override via the `STABLECOIN_KITS_TELEMETRY_URL` environment variable
+ * (e.g. for staging or local development).
  *
- * @example
- * ```ts
- * const config = {
- *   computeFee: async () => '1', // 1 USDC (human-readable)
- *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
- * }
- * const result = customFeePolicySchema.safeParse(config)
- * // result.success === true
- * ```
- */ z.object({
-    computeFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
-    calculateFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
-    resolveFeeRecipientAddress: z.function().returns(z.string().or(z.promise(z.string())))
-}).strict().refine((data)=>{
-    const hasComputeFee = data.computeFee !== undefined;
-    const hasCalculateFee = data.calculateFee !== undefined;
-    // XOR: exactly one must be provided
-    return hasComputeFee !== hasCalculateFee;
-}, {
-    message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
-});
-
+ * @internal
+ */ const DEFAULT_LOGS_URL = 'https://api.circle.com/v1/stablecoinKits/logs';
 /**
- * Schema for validating hexadecimal strings with '0x' prefix.
+ * Resolve the telemetry endpoint URL.
  *
- * This schema validates that a string:
- * - Is a string type
- * - Is not empty after trimming
- * - Starts with '0x'
- * - Contains only valid hexadecimal characters (0-9, a-f, A-F) after '0x'
+ * @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
- * This schema does not validate length, making it suitable for various hex string types
- * like addresses, transaction hashes, and other hex-encoded data.
+ * 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.
  *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * @param payload - The structured log payload matching the server schema.
  *
  * @example
  * ```typescript
- * import { hexStringSchema } from '@core/adapter'
+ * import { emitAnalyticsLog } from '@core/utils'
  *
- * const validAddress = '0x1234567890123456789012345678901234567890'
- * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
- *
- * const addressResult = hexStringSchema.safeParse(validAddress)
- * const txHashResult = hexStringSchema.safeParse(validTxHash)
- * console.log(addressResult.success) // true
- * console.log(txHashResult.success) // true
+ * // Fire-and-forget — do not await
+ * void emitAnalyticsLog(payload)
  * ```
- */ const hexStringSchema = z.string().min(1, 'Hex string is required').refine((value)=>value.trim().length > 0, 'Hex string cannot be empty').refine((value)=>value.startsWith('0x'), 'Hex string must start with 0x prefix').refine((value)=>{
-    const hexPattern = /^0x[0-9a-fA-F]+$/;
-    return hexPattern.test(value);
-}, 'Hex string contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after 0x');
+ */ 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);
+    }
+}
+
 /**
- * Schema for validating EVM addresses.
+ * Build the `clientContext` object for telemetry payloads.
  *
- * This schema validates that a string is a properly formatted EVM address:
- * - Must be a valid hex string with '0x' prefix
- * - Must be exactly 42 characters long (0x + 40 hex characters)
+ * @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.
  *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * @returns A {@link ClientContext} with platform, OS, and runtime name
+ *   populated from the current environment.
  *
  * @example
  * ```typescript
- * import { evmAddressSchema } from '@core/adapter'
- *
- * const validAddress = '0x1234567890123456789012345678901234567890'
+ * import { buildClientContext } from '@core/utils'
  *
- * const result = evmAddressSchema.safeParse(validAddress)
- * console.log(result.success) // true
+ * const ctx = buildClientContext()
+ * // Node: { platform: 'node', os: 'darwin', runtimeName: null }
+ * // Browser: { platform: 'browser', os: null, runtimeName: 'chrome' }
  * ```
- */ const evmAddressSchema = hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
+ */ 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
+    };
+}
+
 /**
- * Schema for validating transaction hashes.
+ * Extract structured error details from an unknown error value.
  *
- * This schema validates that a string is a properly formatted transaction hash:
- * - Must be a valid hex string with '0x' prefix
- * - Must be exactly 66 characters long (0x + 64 hex characters)
+ * @remarks
+ * Handle three cases:
+ * - `KitError` — extract `code` and `name`.
+ * - `Error` — extract `name`.
+ * - Anything else — return empty details.
  *
- * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ * 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.
+ *
+ * @param pkgName - The full npm package name (e.g. `@circle-fin/bridge-kit`).
+ * @returns The unscoped kit name (e.g. `bridge-kit`).
+ *
+ * @example
+ * ```typescript
+ * import pkg from '../../package.json'
+ * import { resolveKitSdkName } from '@core/utils'
+ *
+ * const SDK_NAME = resolveKitSdkName(pkg.name) // 'bridge-kit'
+ * ```
+ */ function resolveKitSdkName(pkgName) {
+    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.13.0";
+var pkg$3 = {
+	name: name$3,
+	version: version$3};
+
+/**
+ * Schema for validating BridgeKit custom fee policy.
+ *
+ * Validates the shape of {@link CustomFeePolicy}, which lets SDK consumers
+ * provide custom fee calculation and fee-recipient resolution logic.
+ *
+ * - computeFee: optional function (recommended) that receives human-readable amounts
+ *   and returns a fee as a string (or Promise<string>).
+ * - calculateFee: optional function (deprecated) that receives smallest-unit amounts
+ *   and returns a fee as a string (or Promise<string>).
+ * - resolveFeeRecipientAddress: required function that returns a recipient address as a
+ *   string (or Promise<string>).
+ *
+ * Exactly one of `computeFee` or `calculateFee` must be provided (not both).
+ *
+ * This schema only ensures the presence and return types of the functions; it
+ * does not validate their argument types.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   computeFee: async () => '1', // 1 USDC (human-readable)
+ *   resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+ * }
+ * const result = customFeePolicySchema.safeParse(config)
+ * // result.success === true
+ * ```
+ */ z.object({
+    computeFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
+    calculateFee: z.function().returns(z.string().or(z.promise(z.string()))).optional(),
+    resolveFeeRecipientAddress: z.function().returns(z.string().or(z.promise(z.string())))
+}).strict().superRefine((data, ctx)=>{
+    const hasComputeFee = data.computeFee !== undefined;
+    const hasCalculateFee = data.calculateFee !== undefined;
+    if (hasComputeFee && hasCalculateFee) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee, not both. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
+    if (!hasComputeFee && !hasCalculateFee) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Provide either computeFee or calculateFee. Use computeFee (recommended) for human-readable amounts.'
+        });
+    }
+});
+
+/**
+ * Schema for validating hexadecimal strings with '0x' prefix.
+ *
+ * This schema validates that a string:
+ * - Is a string type
+ * - Is not empty after trimming
+ * - Starts with '0x'
+ * - Contains only valid hexadecimal characters (0-9, a-f, A-F) after '0x'
+ *
+ * @remarks
+ * This schema does not validate length, making it suitable for various hex string types
+ * like addresses, transaction hashes, and other hex-encoded data.
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { hexStringSchema } from '@core/adapter'
+ *
+ * const validAddress = '0x1234567890123456789012345678901234567890'
+ * const validTxHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ *
+ * const addressResult = hexStringSchema.safeParse(validAddress)
+ * const txHashResult = hexStringSchema.safeParse(validTxHash)
+ * console.log(addressResult.success) // true
+ * console.log(txHashResult.success) // true
+ * ```
+ */ const hexStringSchema = z.string().min(1, 'Hex string is required').refine((value)=>value.trim().length > 0, 'Hex string cannot be empty').refine((value)=>value.startsWith('0x'), 'Hex string must start with 0x prefix').refine((value)=>{
+    const hexPattern = /^0x[0-9a-fA-F]+$/;
+    return hexPattern.test(value);
+}, 'Hex string contains invalid characters. Only hexadecimal characters (0-9, a-f, A-F) are allowed after 0x');
+/**
+ * Schema for validating EVM addresses.
+ *
+ * This schema validates that a string is a properly formatted EVM address:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 42 characters long (0x + 40 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
+ *
+ * @example
+ * ```typescript
+ * import { evmAddressSchema } from '@core/adapter'
+ *
+ * const validAddress = '0x1234567890123456789012345678901234567890'
+ *
+ * const result = evmAddressSchema.safeParse(validAddress)
+ * console.log(result.success) // true
+ * ```
+ */ const evmAddressSchema = hexStringSchema.refine((value)=>value.length === 42, 'EVM address must be exactly 42 characters long (0x + 40 hex characters)').transform((value)=>value);
+/**
+ * Schema for validating transaction hashes.
+ *
+ * This schema validates that a string is a properly formatted transaction hash:
+ * - Must be a valid hex string with '0x' prefix
+ * - Must be exactly 66 characters long (0x + 64 hex characters)
+ *
+ * @throws {KitError} If validation fails with INPUT_VALIDATION_FAILED code (1098), with details about which properties failed
  *
  * @example
  * ```typescript
@@ -8895,7 +9529,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 +9569,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.1";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -9670,6 +10310,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
@@ -9704,16 +10354,321 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * const isValid = isValidApiKey('KIT_KEY:e84d2546d4e321b2ff427dc988c89503:f84d2548d4e322b2ff427fc989c87503')
  * console.log(isValid) // true
  *
- * ```
- */ const isValidApiKey = (apiKey)=>{
-    // Handle invalid input types
-    if (typeof apiKey !== 'string') {
-        return false;
+ * ```
+ */ const isValidApiKey = (apiKey)=>{
+    // Handle invalid input types
+    if (typeof apiKey !== 'string') {
+        return false;
+    }
+    const apiKeyPattern = /^KIT_KEY:[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$/;
+    // Validate without trimming - any whitespace will cause validation to fail
+    return apiKeyPattern.test(apiKey);
+};
+
+/**
+ * IAdapter contract ABI.
+ *
+ * Shared ABI for the on-chain Adapter contract used by multiple kits
+ * (swap, earn) for executing signed instruction sets. The `execute()`
+ * function accepts EIP-712 signed execution parameters, token inputs,
+ * and a signature, then executes the corresponding on-chain
+ * instructions.
+ */ const adapterContractAbi = [
+    {
+        type: 'function',
+        name: 'execute',
+        inputs: [
+            {
+                name: 'params',
+                type: 'tuple',
+                internalType: 'struct IAdapter.ExecutionParams',
+                components: [
+                    {
+                        name: 'instructions',
+                        type: 'tuple[]',
+                        internalType: 'struct IAdapter.Instruction[]',
+                        components: [
+                            {
+                                name: 'target',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'data',
+                                type: 'bytes',
+                                internalType: 'bytes'
+                            },
+                            {
+                                name: 'value',
+                                type: 'uint256',
+                                internalType: 'uint256'
+                            },
+                            {
+                                name: 'tokenIn',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'amountToApprove',
+                                type: 'uint256',
+                                internalType: 'uint256'
+                            },
+                            {
+                                name: 'tokenOut',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'minTokenOut',
+                                type: 'uint256',
+                                internalType: 'uint256'
+                            }
+                        ]
+                    },
+                    {
+                        name: 'tokens',
+                        type: 'tuple[]',
+                        internalType: 'struct IAdapter.TokenRecipient[]',
+                        components: [
+                            {
+                                name: 'token',
+                                type: 'address',
+                                internalType: 'address'
+                            },
+                            {
+                                name: 'beneficiary',
+                                type: 'address',
+                                internalType: 'address'
+                            }
+                        ]
+                    },
+                    {
+                        name: 'execId',
+                        type: 'uint256',
+                        internalType: 'uint256'
+                    },
+                    {
+                        name: 'deadline',
+                        type: 'uint256',
+                        internalType: 'uint256'
+                    },
+                    {
+                        name: 'metadata',
+                        type: 'bytes',
+                        internalType: 'bytes'
+                    }
+                ]
+            },
+            {
+                name: 'tokenInputs',
+                type: 'tuple[]',
+                internalType: 'struct IAdapter.TokenInput[]',
+                components: [
+                    {
+                        name: 'permitType',
+                        type: 'uint8',
+                        internalType: 'enum IAdapter.PermitType'
+                    },
+                    {
+                        name: 'token',
+                        type: 'address',
+                        internalType: 'address'
+                    },
+                    {
+                        name: 'amount',
+                        type: 'uint256',
+                        internalType: 'uint256'
+                    },
+                    {
+                        name: 'permitCalldata',
+                        type: 'bytes',
+                        internalType: 'bytes'
+                    }
+                ]
+            },
+            {
+                name: 'signature',
+                type: 'bytes',
+                internalType: 'bytes'
+            }
+        ],
+        outputs: [],
+        stateMutability: 'payable'
+    }
+];
+
+/**
+ * Minimal ERC-4626 tokenized-vault ABI.
+ *
+ * Covers only the mutating methods EarnKit bundles as inner instructions inside
+ * an Adapter `execute()` call: `deposit`, `withdraw`, and `redeem`. It exists so
+ * clients can decode the inner instruction calldata into a human-readable
+ * summary of what a signer is authorizing (asset amount, receiver, owner)
+ * rather than showing opaque bytes. The 4-byte selectors match the calldata the
+ * earn service signs (`deposit(uint256,address)` = `0x6e553f65`,
+ * `withdraw(uint256,address,address)` = `0xb460af94`,
+ * `redeem(uint256,address,address)` = `0xba087652`).
+ */ const erc4626VaultAbi = [
+    {
+        type: 'function',
+        name: 'deposit',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'assets',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'receiver',
+                type: 'address',
+                internalType: 'address'
+            }
+        ],
+        outputs: [
+            {
+                name: 'shares',
+                type: 'uint256',
+                internalType: 'uint256'
+            }
+        ]
+    },
+    {
+        type: 'function',
+        name: 'withdraw',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'assets',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'receiver',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'owner',
+                type: 'address',
+                internalType: 'address'
+            }
+        ],
+        outputs: [
+            {
+                name: 'shares',
+                type: 'uint256',
+                internalType: 'uint256'
+            }
+        ]
+    },
+    {
+        type: 'function',
+        name: 'redeem',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'shares',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'receiver',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'owner',
+                type: 'address',
+                internalType: 'address'
+            }
+        ],
+        outputs: [
+            {
+                name: 'assets',
+                type: 'uint256',
+                internalType: 'uint256'
+            }
+        ]
+    }
+];
+
+/**
+ * Minimal FeeTaker ABI.
+ *
+ * The earn service appends a `takeFeeERC20` instruction to withdraw bundles
+ * when Circle charges a withdrawal fee. This ABI decodes that inner instruction
+ * so the fee (token, beneficiary, amount) is visible in the signing summary
+ * instead of appearing as opaque calldata alongside the redeem/withdraw call.
+ */ const feeTakerAbi = [
+    {
+        type: 'function',
+        name: 'takeFeeERC20',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'token',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'beneficiary',
+                type: 'address',
+                internalType: 'address'
+            },
+            {
+                name: 'fee',
+                type: 'uint256',
+                internalType: 'uint256'
+            },
+            {
+                name: 'kitType',
+                type: 'bytes8',
+                internalType: 'bytes8'
+            }
+        ],
+        outputs: []
+    }
+];
+
+/**
+ * Minimal Merkl Distributor ABI.
+ *
+ * EarnKit claim-rewards bundles a single `claim` instruction targeting the
+ * Merkl Distributor, batching one entry per reward token. This ABI decodes that
+ * inner instruction so the claimed tokens and amounts are visible in the signing
+ * summary. `claim` uses dynamic array arguments, which is why a real ABI decoder
+ * (rather than fixed-word slicing) is required for the reward instruction.
+ */ const merklDistributorAbi = [
+    {
+        type: 'function',
+        name: 'claim',
+        stateMutability: 'nonpayable',
+        inputs: [
+            {
+                name: 'users',
+                type: 'address[]',
+                internalType: 'address[]'
+            },
+            {
+                name: 'tokens',
+                type: 'address[]',
+                internalType: 'address[]'
+            },
+            {
+                name: 'amounts',
+                type: 'uint256[]',
+                internalType: 'uint256[]'
+            },
+            {
+                name: 'proofs',
+                type: 'bytes32[][]',
+                internalType: 'bytes32[][]'
+            }
+        ],
+        outputs: []
     }
-    const apiKeyPattern = /^KIT_KEY:[a-zA-Z0-9._-]+:[a-zA-Z0-9._-]+$/;
-    // Validate without trimming - any whitespace will cause validation to fail
-    return apiKeyPattern.test(apiKey);
-};
+];
 
 /**
  * Zod schema for validating EVM adapter capabilities.
@@ -12228,7 +13183,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.5.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -12844,31 +13799,670 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     return tokenInputs;
 }
 /**
- * Resolve the single token that needs adapter allowance from signed Earn
- * instructions.
+ * Resolve the single token that needs adapter allowance from signed Earn
+ * instructions.
+ *
+ * @param executionParams - Service-signed `ExecutionParams` forwarded to the adapter.
+ * @returns The token requested by positive approval instructions, or `undefined`.
+ * @throws {@link KitError} If positive approval instructions reference multiple tokens.
+ *
+ * @internal
+ */ function resolveEarnApprovalToken(executionParams) {
+    let approvedToken;
+    executionParams.instructions.forEach((instruction, index)=>{
+        const amount = BigInt(instruction.amountToApprove);
+        if (amount <= 0n) {
+            return;
+        }
+        const { tokenIn } = instruction;
+        if (approvedToken === undefined) {
+            approvedToken = tokenIn;
+            return;
+        }
+        if (!isSameAddress(tokenIn, approvedToken)) {
+            throw createValidationFailedError(`executionParams.instructions[${index.toString()}].tokenIn`, tokenIn, 'tokenIn must match the token approved for adapter spending');
+        }
+    });
+    return approvedToken;
+}
+
+/**
+ * Combined ABI of every inner instruction EarnKit can bundle inside an Adapter
+ * `execute()` call. `decodeFunctionData` matches an instruction's calldata to
+ * one of these functions by its 4-byte selector.
+ */ const earnInstructionAbi = [
+    ...erc4626VaultAbi,
+    ...feeTakerAbi,
+    ...merklDistributorAbi
+];
+/**
+ * Extract and shallow-validate the `instructions` array from loosely-typed
+ * signed execution params.
+ *
+ * The earn service schema validates `tokenIn`/`amountToApprove` and passes the
+ * remaining instruction fields through untyped, so the params arrive as a plain
+ * record; each accessed field is narrowed at runtime.
+ */ function requireInstructions(executionParams) {
+    const instructions = executionParams['instructions'];
+    if (!Array.isArray(instructions)) {
+        throw decodeMismatchError('execution params are missing an instructions array', {
+            instructions
+        });
+    }
+    return instructions.map((instruction, index)=>{
+        if (typeof instruction !== 'object' || instruction === null) {
+            throw decodeMismatchError(`instructions[${index.toString()}] is not an object`, {
+                index
+            });
+        }
+        return instruction;
+    });
+}
+/**
+ * Build a fail-closed {@link KitError} for an earn decode or review failure.
+ *
+ * Marked non-recoverable: a mismatch between what would be shown and what would
+ * be signed is never safe to retry, so the operation fails fast rather than
+ * presenting misleading decoded data. `messagePrefix` names the failing stage
+ * (calldata decode vs. review construction); callers bind it once and pass the
+ * specific failure as `message`.
+ */ function failClosedEarnError(messagePrefix, message, trace) {
+    return new KitError({
+        ...EarnError.INTERNAL_ERROR,
+        recoverability: 'FATAL',
+        message: `${messagePrefix}: ${message}`,
+        cause: {
+            trace
+        }
+    });
+}
+/**
+ * Build a {@link KitError} for a decode or consistency failure.
+ *
+ * Thin wrapper over {@link failClosedEarnError} bound to the decode-stage
+ * message prefix.
+ */ function decodeMismatchError(message, trace) {
+    return failClosedEarnError('Unable to decode earn transaction', message, trace);
+}
+/**
+ * Narrow an untyped value to a 0x-prefixed hex string, or fail fast.
+ */ function requireHex(value, path) {
+    if (typeof value === 'string' && /^0x[0-9a-fA-F]*$/.test(value)) {
+        return value;
+    }
+    throw decodeMismatchError(`${path} is not a hex string`, {
+        path,
+        value
+    });
+}
+/**
+ * Narrow an untyped value to a 20-byte EVM address, or fail fast.
+ */ function requireAddress(value, path) {
+    if (typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value)) {
+        return value;
+    }
+    throw decodeMismatchError(`${path} is not an address`, {
+        path,
+        value
+    });
+}
+/**
+ * Narrow an untyped `uint256`-like value (decimal string, bigint, or integer)
+ * to a bigint, or fail fast.
+ */ function requireUint(value, path) {
+    if (typeof value === 'bigint') {
+        return value;
+    }
+    if (typeof value === 'string' && /^\d+$/.test(value)) {
+        return BigInt(value);
+    }
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+        return BigInt(value);
+    }
+    throw decodeMismatchError(`${path} is not a uint256 value`, {
+        path,
+        value
+    });
+}
+/**
+ * Decode inner instruction calldata against the earn instruction ABI, mapping a
+ * viem decode failure (unknown selector, malformed args) to a fail-fast error.
+ */ function decodeEarnInstructionData(data, index) {
+    try {
+        return decodeFunctionData({
+            abi: earnInstructionAbi,
+            data
+        });
+    } catch (error) {
+        throw decodeMismatchError(`instructions[${index.toString()}] calldata is not a recognized earn instruction`, {
+            index,
+            selector: data.slice(0, 10),
+            error: String(error)
+        });
+    }
+}
+/**
+ * Decode Adapter `execute()` calldata, mapping a viem decode failure to a
+ * fail-fast error.
+ */ function decodeExecuteCalldata(calldata) {
+    try {
+        return decodeFunctionData({
+            abi: adapterContractAbi,
+            data: calldata
+        });
+    } catch (error) {
+        throw decodeMismatchError('encoded calldata is not a valid Adapter execute() call', {
+            error: String(error)
+        });
+    }
+}
+/**
+ * Decode one inner instruction's calldata into a typed {@link
+ * DecodedEarnInstruction}.
+ */ function decodeInstruction(instruction, index) {
+    const target = requireAddress(instruction['target'], `instructions[${index.toString()}].target`);
+    const data = requireHex(instruction['data'], `instructions[${index.toString()}].data`);
+    const decoded = decodeEarnInstructionData(data, index);
+    switch(decoded.functionName){
+        case 'deposit':
+            {
+                const [assets, receiver] = decoded.args;
+                return {
+                    method: 'deposit',
+                    vault: target,
+                    assets: assets.toString(),
+                    receiver
+                };
+            }
+        case 'withdraw':
+            {
+                const [assets, receiver, owner] = decoded.args;
+                return {
+                    method: 'withdraw',
+                    vault: target,
+                    assets: assets.toString(),
+                    receiver,
+                    owner
+                };
+            }
+        case 'redeem':
+            {
+                const [shares, receiver, owner] = decoded.args;
+                return {
+                    method: 'redeem',
+                    vault: target,
+                    shares: shares.toString(),
+                    receiver,
+                    owner
+                };
+            }
+        case 'takeFeeERC20':
+            {
+                const [token, beneficiary, fee, kitType] = decoded.args;
+                return {
+                    method: 'takeFeeERC20',
+                    feeTaker: target,
+                    token,
+                    beneficiary,
+                    fee: fee.toString(),
+                    kitType
+                };
+            }
+        case 'claim':
+            {
+                const users = decoded.args[0];
+                const tokens = decoded.args[1];
+                const amounts = decoded.args[2];
+                // Merkl claim(users, tokens, amounts, proofs) carries parallel arrays,
+                // one entry per reward. Reject any length skew rather than padding with
+                // zero amounts or dropping trailing entries, so the preview can never
+                // misstate what is claimed or for whom.
+                //
+                // Note: Merkl `amounts` are the *cumulative lifetime* total claimable per
+                // (user, token); the Distributor transfers only `amount - alreadyClaimed`.
+                // This decode faithfully surfaces the signed cumulative value, which is
+                // what `DecodedRewardClaim.amount` documents. See that type's doc.
+                if (new Set([
+                    users.length,
+                    tokens.length,
+                    amounts.length
+                ]).size !== 1) {
+                    throw decodeMismatchError(`instructions[${index.toString()}] claim has mismatched recipient/token/amount lengths`, {
+                        index,
+                        users: users.length,
+                        tokens: tokens.length,
+                        amounts: amounts.length
+                    });
+                }
+                const rewards = tokens.map((token, rewardIndex)=>({
+                        recipient: requireAddress(users[rewardIndex], `instructions[${index.toString()}].claim.users[${rewardIndex.toString()}]`),
+                        address: token,
+                        amount: requireUint(amounts[rewardIndex], `instructions[${index.toString()}].claim.amounts[${rewardIndex.toString()}]`).toString()
+                    }));
+                return {
+                    method: 'claim',
+                    distributor: target,
+                    rewards
+                };
+            }
+        /* v8 ignore next 2 -- exhaustive switch; default is unreachable */ default:
+            return assertNever$2(decoded);
+    }
+}
+/**
+ * Lift the primary values a wallet prompt cares about out of the decoded
+ * instructions into a flat summary.
+ */ function buildSummary(instructions, envelope) {
+    const summary = {};
+    instructions.forEach((instruction, index)=>{
+        switch(instruction.method){
+            case 'deposit':
+            case 'withdraw':
+            case 'redeem':
+                {
+                    // The summary lifts a single primary token movement to the top level.
+                    // An earn bundle carries exactly one deposit/withdraw/redeem today;
+                    // fail fast rather than silently overwriting an earlier one, which
+                    // would drop it from the wallet-facing preview.
+                    if (summary.token !== undefined) {
+                        throw decodeMismatchError('multiple deposit/withdraw/redeem instructions cannot be summarized into a single preview', {
+                            index
+                        });
+                    }
+                    // Pair the amount with the token it is actually denominated in so the
+                    // preview never folds two units into one entry:
+                    //  - deposit:  `assets` of the underlying asset pulled in (`tokenIn`)
+                    //  - redeem:   `shares` of the vault-share token burned (`tokenIn`)
+                    //  - withdraw: `assets` of the underlying asset paid out (`tokenOut`).
+                    //    `withdraw(assets)` counts the underlying received, not the shares
+                    //    burned to produce it, so `tokenIn` (the share token) would misstate
+                    //    the unit; the underlying is the instruction's `tokenOut`.
+                    const amount = instruction.method === 'redeem' ? instruction.shares : instruction.assets;
+                    const tokenField = instruction.method === 'withdraw' ? 'tokenOut' : 'tokenIn';
+                    summary.vault = instruction.vault;
+                    summary.receiver = instruction.receiver;
+                    summary.token = {
+                        address: requireAddress(envelope[index]?.[tokenField], `instructions[${index.toString()}].${tokenField}`),
+                        amount
+                    };
+                    break;
+                }
+            case 'takeFeeERC20':
+                {
+                    // As with the vault case, a second fee would silently overwrite the
+                    // first and understate what is charged; fail fast instead.
+                    if (summary.fee !== undefined) {
+                        throw decodeMismatchError('multiple fee instructions cannot be summarized into a single preview', {
+                            index
+                        });
+                    }
+                    summary.fee = {
+                        address: instruction.token,
+                        amount: instruction.fee
+                    };
+                    break;
+                }
+            case 'claim':
+                {
+                    // A second claim would silently drop the first from the preview
+                    // (rewards are already batched inside one Merkl claim); fail fast.
+                    if (summary.rewards !== undefined) {
+                        throw decodeMismatchError('multiple claim instructions cannot be summarized into a single preview', {
+                            index
+                        });
+                    }
+                    summary.rewards = instruction.rewards;
+                    break;
+                }
+            /* v8 ignore next 2 -- exhaustive switch; default is unreachable */ default:
+                assertNever$2(instruction);
+        }
+    });
+    return summary;
+}
+/**
+ * Vault/claim instruction methods each declared action may decode to. The
+ * mapping is many-to-one: a full withdrawal decodes to `redeem`, and any action
+ * may carry an auxiliary `takeFeeERC20` alongside its primary instruction.
+ */ const ACTION_ALLOWED_METHODS = {
+    deposit: new Set([
+        'deposit'
+    ]),
+    withdraw: new Set([
+        'withdraw',
+        'redeem'
+    ]),
+    claimRewards: new Set([
+        'claim'
+    ])
+};
+/**
+ * Fail fast when the caller-declared `action` disagrees with the decoded
+ * instructions, so the preview's headline can never mislabel what is signed
+ * (e.g. a `deposit`-labeled call handed withdraw params). `takeFeeERC20` is an
+ * auxiliary Circle-fee instruction and is allowed alongside any action.
+ */ function assertActionMatchesInstructions(action, instructions) {
+    const allowed = ACTION_ALLOWED_METHODS[action];
+    instructions.forEach((instruction, index)=>{
+        if (instruction.method === 'takeFeeERC20') {
+            return;
+        }
+        if (!allowed.has(instruction.method)) {
+            throw decodeMismatchError(`decoded instruction method '${instruction.method}' does not match the '${action}' action`, {
+                action,
+                method: instruction.method,
+                index
+            });
+        }
+    });
+}
+/**
+ * Decode a same-chain earn `execute()` bundle into a human-readable summary.
+ *
+ * Decodes every inner instruction in the service-signed `executionParams` — the
+ * same object the SDK ABI-encodes into the transaction — so the returned decode
+ * is a faithful, drift-free view of what the signer is authorizing: input token
+ * and amount, target vault, receiver, any Circle fee, and claimed rewards. Fails
+ * fast with a non-recoverable {@link KitError} if any instruction cannot be
+ * decoded, rather than returning misleading data.
+ *
+ * @param input - Action, chain, adapter, and the signed execution params.
+ * @returns The decoded transaction summary.
+ * @throws {@link KitError} If an instruction's calldata cannot be decoded.
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeEarnExecute({
+ *   action: 'deposit',
+ *   chain: 'Arc_Testnet',
+ *   adapter: '0x7fb8c7260b63934d8da38af902f87ae6e284a845',
+ *   executionParams,
+ * })
+ * // decoded.summary -> { token: { address, amount }, vault, receiver }
+ * ```
+ *
+ * @internal
+ */ function decodeEarnExecute(input) {
+    const { action, chain, adapter, executionParams } = input;
+    const envelope = requireInstructions(executionParams);
+    const instructions = envelope.map((instruction, index)=>decodeInstruction(instruction, index));
+    assertActionMatchesInstructions(action, instructions);
+    return {
+        action,
+        chain,
+        adapter,
+        instructions,
+        summary: buildSummary(instructions, envelope)
+    };
+}
+/**
+ * Assert that ABI-encoded Adapter `execute()` calldata encodes the same
+ * instruction set as the service-signed execution params.
+ *
+ * Fail-fast preview check: the SDK encodes `execute(executeParams, ...)` locally,
+ * so decoding those final bytes and comparing every field of each instruction
+ * against the signed params proves the previewed instruction set matches what
+ * will be signed. It compares `instructions[]` only — the outer `tokens`,
+ * `execId`, `deadline`, and `metadata` are not re-compared here. The
+ * authoritative integrity guarantee for the full signed struct is the on-chain
+ * EIP-712 signature verification, which reverts if any signed field is altered.
+ *
+ * @param calldata - Encoded `execute()` calldata about to be signed.
+ * @param executionParams - Service-signed execution params.
+ * @throws {@link KitError} If the calldata is not an `execute()` call or any
+ *   instruction field differs from the signed params.
+ *
+ * @example
+ * ```typescript
+ * assertEarnCalldataMatchesExecuteParams(
+ *   prepared.getCallData().data,
+ *   executionParams,
+ * )
+ * ```
+ *
+ * @internal
+ */ function assertEarnCalldataMatchesExecuteParams(calldata, executionParams) {
+    // adapterContractAbi declares only `execute`, so a successful decode is always
+    // the execute() call; a non-execute selector throws inside
+    // decodeExecuteCalldata above.
+    const decoded = decodeExecuteCalldata(calldata);
+    const encoded = decoded.args[0].instructions;
+    const signed = requireInstructions(executionParams);
+    // Compare each encoded instruction against its signed counterpart. Iterating
+    // the encoded instructions and indexing the signed set keeps both mismatch
+    // branches reachable: a signed set that is too short trips the guard below,
+    // and one that is too long trips the post-loop check.
+    encoded.forEach((instruction, index)=>{
+        const signedInstruction = signed[index];
+        if (signedInstruction === undefined) {
+            throw decodeMismatchError(`signed params are missing instruction ${index.toString()}`, {
+                index,
+                encoded: encoded.length,
+                signed: signed.length
+            });
+        }
+        const path = `instructions[${index.toString()}]`;
+        assertHexEqual(instruction.target, signedInstruction['target'], `${path}.target`);
+        assertHexEqual(instruction.data, signedInstruction['data'], `${path}.data`);
+        assertUintEqual(instruction.value, signedInstruction['value'], `${path}.value`);
+        assertHexEqual(instruction.tokenIn, signedInstruction['tokenIn'], `${path}.tokenIn`);
+        assertUintEqual(instruction.amountToApprove, signedInstruction['amountToApprove'], `${path}.amountToApprove`);
+        assertHexEqual(instruction.tokenOut, signedInstruction['tokenOut'], `${path}.tokenOut`);
+        assertUintEqual(instruction.minTokenOut, signedInstruction['minTokenOut'], `${path}.minTokenOut`);
+    });
+    if (signed.length > encoded.length) {
+        throw decodeMismatchError('signed params contain more instructions than the encoded calldata', {
+            encoded: encoded.length,
+            signed: signed.length
+        });
+    }
+}
+/**
+ * Assert two hex values are equal, case-insensitively (addresses and calldata).
+ */ function assertHexEqual(encoded, signed, path) {
+    const signedHex = requireHex(signed, path);
+    if (encoded.toLowerCase() !== signedHex.toLowerCase()) {
+        throw decodeMismatchError(`${path} differs from signed params`, {
+            path,
+            encoded,
+            signed: signedHex
+        });
+    }
+}
+/**
+ * Assert an encoded bigint equals a signed `uint256`-like value.
+ */ function assertUintEqual(encoded, signed, path) {
+    const signedUint = requireUint(signed, path);
+    if (encoded !== signedUint) {
+        throw decodeMismatchError(`${path} differs from signed params`, {
+            path,
+            encoded: encoded.toString(),
+            signed: signedUint.toString()
+        });
+    }
+}
+
+/**
+ * Namespaced discriminator for the EarnKit authorization review.
+ *
+ * Applications match on this in an adapter `onBeforeAuthorize` hook to decide
+ * whether the request carries EarnKit semantic data. Prefer the
+ * {@link isEarnExecuteReview} type guard over comparing this string directly.
+ *
+ * @example
+ * ```typescript
+ * if (review?.kind === EARN_EXECUTE_REVIEW_KIND) { … }
+ * ```
+ */ const EARN_EXECUTE_REVIEW_KIND = 'earn.execute';
+
+/**
+ * Build a fail-closed {@link KitError} for a review-construction failure.
+ *
+ * Marked non-recoverable: a review that cannot prove the calldata matches the
+ * signed operation must abort authorization, never retry with misleading data.
+ */ function reviewError(message, trace) {
+    return failClosedEarnError('Unable to build earn authorization review', message, trace);
+}
+/**
+ * Narrow the canonical authorization payload to the single Adapter `execute()`
+ * call a same-chain earn operation authorizes.
+ *
+ * Same-chain deposit, withdraw, and claim-rewards each authorize exactly one
+ * `evm-calls` payload carrying one call. Anything else (typed data, a batch,
+ * an empty call list) means this descriptor was attached to the wrong
+ * authorization unit, so fail closed rather than decode misleading data.
+ */ function assertSingleEvmCallPayload(payload) {
+    if (payload.type !== 'evm-calls') {
+        throw reviewError(`expected an 'evm-calls' payload but received '${payload.type}'`, {
+            type: payload.type
+        });
+    }
+    const [call, ...rest] = payload.calls;
+    if (call === undefined) {
+        throw reviewError('the evm-calls payload contains no calls to review', {
+            callCount: payload.calls.length
+        });
+    }
+    if (rest.length > 0) {
+        throw reviewError('a same-chain earn operation authorizes exactly one Adapter execute() call', {
+            callCount: payload.calls.length
+        });
+    }
+    return call;
+}
+/**
+ * Select the final earn `execute()` call from an atomic Earn batch.
+ *
+ * Same-chain batched deposit/withdraw authorizes either `[execute]` when the
+ * current allowance is sufficient, or `[approve, execute]` when a top-up is
+ * required. Any other shape means the descriptor was attached to an
+ * unexpected authorization unit, so fail closed.
+ */ function assertBatchedEarnExecuteCall(payload) {
+    if (payload.type !== 'evm-calls') {
+        throw reviewError(`expected an 'evm-calls' payload but received '${payload.type}'`, {
+            type: payload.type
+        });
+    }
+    if (payload.calls.length !== 1 && payload.calls.length !== 2) {
+        throw reviewError('a batched earn operation authorizes [execute] or [approve, execute]', {
+            callCount: payload.calls.length
+        });
+    }
+    const executeCall = payload.calls.at(-1);
+    if (executeCall === undefined) {
+        throw reviewError('the earn batch contains no execute call to review', {
+            callCount: payload.calls.length
+        });
+    }
+    return executeCall;
+}
+/**
+ * Map a canonical {@link EvmCall} to the {@link EarnEncodedTransaction} preview
+ * shape, failing closed when the earn `execute()` call carries no calldata.
+ */ function toEarnEncodedTransaction(call) {
+    if (call.data === undefined) {
+        throw reviewError('the earn execute() call is missing calldata', {
+            to: call.to
+        });
+    }
+    return {
+        to: call.to,
+        data: call.data,
+        ...call.value !== undefined && {
+            value: call.value
+        }
+    };
+}
+/**
+ * Create an Earn authorization descriptor using the supplied canonical-payload
+ * call selector.
+ *
+ * @param input - The action, chain, and service-signed execution params.
+ * @param selectCall - Fail-closed selector for the execute call under review.
+ * @returns A lazy descriptor that decodes and verifies the selected call.
+ *
+ * @internal
+ */ function createEarnExecuteDescriptor(input, selectCall) {
+    const { action, chain, executionParams } = input;
+    const createReview = (payload)=>{
+        const call = selectCall(payload);
+        const encoded = toEarnEncodedTransaction(call);
+        const decoded = decodeEarnExecute({
+            action,
+            chain,
+            adapter: encoded.to,
+            executionParams
+        });
+        // Prove the calldata about to be signed encodes the same instruction set as
+        // the service-signed params. Throwing here aborts before the wallet prompt.
+        assertEarnCalldataMatchesExecuteParams(encoded.data, executionParams);
+        const review = {
+            kind: EARN_EXECUTE_REVIEW_KIND,
+            data: {
+                encoded,
+                decoded
+            }
+        };
+        return review;
+    };
+    return {
+        createReview
+    };
+}
+/**
+ * Build the lazy `earn.execute` authorization descriptor for a same-chain earn
+ * action.
+ *
+ * The returned descriptor carries only a `createReview` factory — no intent
+ * override, because the adapter's action system supplies the intent from the
+ * action key. The factory is evaluated at most once, and only when the
+ * application configured an adapter `onBeforeAuthorize` hook. When it runs it:
+ *
+ * 1. narrows the canonical payload to its single Adapter `execute()` call;
+ * 2. lifts that call into an {@link EarnEncodedTransaction};
+ * 3. decodes it into a `DecodedEarnTx`; and
+ * 4. asserts the decoded calldata matches the service-signed params, throwing
+ *    (aborting authorization before the wallet or signer) on any mismatch.
+ *
+ * @param input - The action, chain, and service-signed execution params.
+ * @returns An authorization descriptor to pass as the fourth `prepareAction`
+ *   argument for the final earn action only (never the allowance approval).
+ * @throws {@link KitError} From the review factory when the payload is not a
+ *   single earn `execute()` call or the calldata diverges from the signed
+ *   params. The throw surfaces through the adapter gate before authorization.
+ *
+ * @example
+ * ```typescript
+ * const descriptor = buildEarnExecuteDescriptor({
+ *   action: 'deposit',
+ *   chain: 'Arc_Testnet',
+ *   executionParams,
+ * })
+ * await adapter.prepareAction('earn.deposit', actionParams, ctx, {
+ *   authorization: descriptor,
+ * })
+ * ```
+ *
+ * @internal
+ */ function buildEarnExecuteDescriptor(input) {
+    return createEarnExecuteDescriptor(input, assertSingleEvmCallPayload);
+}
+/**
+ * Build a lazy `earn.execute` authorization descriptor for an atomic Earn
+ * batch containing either `[execute]` or `[approve, execute]`.
  *
- * @param executionParams - Service-signed `ExecutionParams` forwarded to the adapter.
- * @returns The token requested by positive approval instructions, or `undefined`.
- * @throws {@link KitError} If positive approval instructions reference multiple tokens.
+ * The review always decodes and verifies the final call against the
+ * service-signed execution params. Unexpected payload types and call counts
+ * fail closed before wallet authorization.
+ *
+ * @param input - The action, chain, and service-signed execution params.
+ * @returns A descriptor suitable for `batchExecute` authorization options.
+ * @throws {@link KitError} From the lazy review factory when the batch shape or
+ *   final execute calldata cannot be verified.
  *
  * @internal
- */ function resolveEarnApprovalToken(executionParams) {
-    let approvedToken;
-    executionParams.instructions.forEach((instruction, index)=>{
-        const amount = BigInt(instruction.amountToApprove);
-        if (amount <= 0n) {
-            return;
-        }
-        const { tokenIn } = instruction;
-        if (approvedToken === undefined) {
-            approvedToken = tokenIn;
-            return;
-        }
-        if (!isSameAddress(tokenIn, approvedToken)) {
-            throw createValidationFailedError(`executionParams.instructions[${index.toString()}].tokenIn`, tokenIn, 'tokenIn must match the token approved for adapter spending');
-        }
-    });
-    return approvedToken;
+ */ function buildBatchedEarnExecuteDescriptor(input) {
+    return createEarnExecuteDescriptor(input, assertBatchedEarnExecuteCall);
 }
 
 /**
@@ -12897,16 +14491,37 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
  *   address,
  *   actionKey: 'earn.deposit',
  *   actionParams: { executeParams, tokenInputs, signature },
+ *   action: 'deposit',
+ *   executionParams,
  *   revertMessage: 'Earn deposit reverted on-chain',
  * })
  * ```
  *
  * @internal
  */ async function executeEarnAction(params) {
-    const { adapter, chain, address, actionKey, actionParams, revertMessage } = params;
+    const { adapter, chain, address, actionKey, actionParams, action, executionParams, revertMessage } = params;
+    // Attach the lazy `earn.execute` review to the final earn action only (never
+    // the allowance approval, which runs on a separate path). The adapter's
+    // action system supplies the intent from `actionKey`, so the descriptor
+    // carries only the review factory. The factory is evaluated at most once,
+    // and only when the application configured an `onBeforeAuthorize` hook.
+    const authorization = buildEarnExecuteDescriptor({
+        action,
+        // The provider validates the chain is Earn-supported in
+        // `resolveAdapterContext` before reaching execute, so the concrete chain
+        // identifier is a valid `EarnChainIdentifier`. It is carried through to the
+        // decoded preview's display `chain` field only.
+        chain: chain.chain,
+        executionParams
+    });
+    // The abstract `Adapter.prepareAction` is 3-arg; the fourth authorization
+    // argument lives on the `withLegacyCompat` wrapper that produced the concrete
+    // adapter passed here. Narrow the single seam that threads the descriptor.
     const prepared = await adapter.prepareAction(actionKey, actionParams, {
         chain,
         address
+    }, {
+        authorization
     });
     const gasLimitOverride = await estimateBufferedGasLimit(prepared);
     const txHash = prepared.type === 'evm' && gasLimitOverride !== undefined ? await prepared.execute({
@@ -12931,6 +14546,278 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     };
 }
 
+/**
+ * Decide whether a same-chain earn action should be submitted as a single
+ * atomic batch.
+ *
+ * Returns `true` only when the consumer has not opted out
+ * (`batchTransactions !== false`), the source chain is EVM, the adapter
+ * structurally exposes the shared batch methods, and the wallet reports atomic
+ * batch support. `address` is forwarded as `fromAddress` so developer-controlled
+ * adapters can probe the specific wallet. Any thrown capability probe is
+ * treated as "no support".
+ *
+ * @param params - Adapter, chain, address, and the resolved `batchTransactions` flag.
+ * @returns `true` when batched execution should be attempted.
+ *
+ * @example
+ * ```typescript
+ * if (await shouldUseBatchedEarnAction({ adapter, chain, address, batchTransactions })) {
+ *   // take the batched approve + execute path
+ * }
+ * ```
+ *
+ * @internal
+ */ async function shouldUseBatchedEarnAction(params) {
+    const { adapter, chain, address, batchTransactions } = params;
+    if (batchTransactions === false) {
+        return false;
+    }
+    if (chain.type !== 'evm') {
+        return false;
+    }
+    const candidate = adapter;
+    if (typeof candidate.supportsAtomicBatch !== 'function' || typeof candidate.batchExecute !== 'function') {
+        return false;
+    }
+    try {
+        return await candidate.supportsAtomicBatch(chain, {
+            fromAddress: address
+        });
+    } catch  {
+        return false;
+    }
+}
+async function buildSuccessfulBatchResult(adapter, chain, receipt, batchId, revertMessage) {
+    const transaction = {
+        txHash: receipt.txHash,
+        explorerUrl: buildExplorerUrl(chain, receipt.txHash)
+    };
+    let confirmed;
+    try {
+        confirmed = await adapter.waitForTransaction(receipt.txHash, {
+            confirmations: 1
+        }, chain);
+    } catch  {
+        // The batch adapter already confirmed success. Receipt enrichment is
+        // telemetry-only, so an additional RPC failure must not turn an accepted
+        // money-moving operation into a retryable business failure.
+        return transaction;
+    }
+    if (confirmed.status === 'reverted') {
+        throw createTransactionRevertedError(chain.name, revertMessage, {
+            batchId
+        }, receipt.txHash, transaction.explorerUrl);
+    }
+    return {
+        ...transaction,
+        ...confirmed.gasUsed !== undefined && {
+            gasUsed: confirmed.gasUsed
+        },
+        ...confirmed.effectiveGasPrice !== undefined && {
+            effectiveGasPrice: confirmed.effectiveGasPrice
+        }
+    };
+}
+function throwBatchFailure(result, executeReceipt, chain, actionKey, revertMessage) {
+    const cause = result.error;
+    if (result.statusCode === 400) {
+        throw new KitError({
+            ...RpcError.ENDPOINT_ERROR,
+            recoverability: 'RETRYABLE',
+            message: `Batched earn ${actionKey} failed off-chain before inclusion (batch ${result.batchId}).`,
+            cause: {
+                trace: {
+                    batchId: result.batchId,
+                    statusCode: result.statusCode,
+                    cause
+                }
+            }
+        });
+    }
+    const causeTrace = cause instanceof KitError && typeof cause.cause?.trace === 'object' && cause.cause.trace !== null ? cause.cause.trace : undefined;
+    if (cause instanceof KitError && causeTrace?.['kind'] === 'failed_offchain') {
+        throw cause;
+    }
+    const isConfirmedRevert = cause instanceof KitError && cause.name === OnchainError.TRANSACTION_REVERTED.name || result.statusCode === 500 || result.statusCode === 600 || result.statusCode === undefined && cause === undefined && executeReceipt?.status === 'error' && executeReceipt.txHash !== '';
+    if (isConfirmedRevert) {
+        throw createTransactionRevertedError(chain.name, revertMessage, {
+            batchId: result.batchId,
+            error: cause
+        });
+    }
+    throw new KitError({
+        ...NetworkError.TIMEOUT,
+        recoverability: 'FATAL',
+        message: `Batched earn ${actionKey} was submitted (batch ${result.batchId}) but its outcome could not be confirmed; check the transaction status before retrying.`,
+        cause: {
+            trace: {
+                batchId: result.batchId,
+                cause
+            }
+        }
+    });
+}
+/**
+ * Execute the `approve` and `execute` steps of a same-chain earn action as a
+ * single atomic batch.
+ *
+ * Prepare both `PreparedChainRequest` objects upfront, extract their raw call
+ * data via `getCallData()`, then submit both through the adapter's shared
+ * `batchExecute`. `address` is forwarded as `opts.fromAddress` so
+ * developer-controlled adapters batch on behalf of the right wallet;
+ * `idempotencyKey` is forwarded for adapters that deduplicate ambiguous
+ * submissions (the Circle developer-controlled adapter reuses the Earn
+ * execution id); other adapters may ignore either option. Reused by both the
+ * deposit and withdraw flows via the `actionKey` parameter.
+ *
+ * @param params - Adapter, chain, action key, signed payload, and approval inputs.
+ * @returns The confirmed execute transaction hash, explorer URL, and receipt
+ *   gas data when the adapter can retrieve it.
+ * @throws {@link KitError} when the source chain is not EVM.
+ * @throws {@link KitError} when calldata extraction (`getCallData`) is not
+ *   supported by the prepared requests.
+ * @throws {@link KitError} when the batch reverts on-chain (a confirmed
+ *   terminal revert), carrying `batchId`.
+ * @throws {@link KitError} RETRYABLE when EIP-5792 reports an off-chain
+ *   failure carrying `batchId` and status code `400`; no call was included.
+ * @throws {@link KitError} FATAL `NetworkError.TIMEOUT` when the batch was
+ *   submitted but its outcome could not be confirmed (poll timeout or any
+ *   other non-revert post-submission failure); carries `batchId` so the caller
+ *   can check transaction status before retrying.
+ * @remarks
+ * Once the batch has been submitted this function does not fall back to the
+ * sequential path — the batch is already on its way, so a fallback would risk
+ * double-spend. Post-submission failures surface through the adapter's batch
+ * result: a confirmed on-chain revert (Circle: a `TRANSACTION_REVERTED` cause;
+ * Viem: status code `500`/`600`) is thrown as a revert error, status code `400`
+ * is reported as a retryable off-chain failure, and any other unconfirmed
+ * outcome is thrown as a FATAL timeout error carrying `batchId`.
+ *
+ * @example
+ * ```typescript
+ * const { txHash, explorerUrl } = await executeBatchedEarnAction({
+ *   adapter,
+ *   chain,
+ *   address,
+ *   actionKey: 'earn.deposit',
+ *   executeParams,
+ *   tokenInputs,
+ *   signature,
+ *   approvalToken: usdcAddress,
+ *   delegate: adapterContractAddress,
+ *   requiredAllowance: 1_000_000n,
+ *   idempotencyKey: '550e8400-e29b-41d4-a716-446655440000',
+ *   revertMessage: 'Earn deposit reverted on-chain',
+ * })
+ * ```
+ *
+ * @internal
+ */ async function executeBatchedEarnAction(params) {
+    const { adapter, chain, address, actionKey, executeParams, tokenInputs, signature, approvalToken, delegate, requiredAllowance, idempotencyKey, revertMessage } = params;
+    if (chain.type !== 'evm') {
+        throw new KitError({
+            ...InputError.INVALID_CHAIN,
+            recoverability: 'FATAL',
+            message: 'Batched earn execution is only supported on EVM chains.'
+        });
+    }
+    const evmChain = chain;
+    const batchAdapter = adapter;
+    // Read the current allowance so the approval tops up only the missing amount.
+    // When the existing allowance already covers the payload, skip the approve
+    // call and batch only the execute — this mirrors the sequential
+    // approveAllowanceIfNeeded guard and avoids an increaseAllowance underflow
+    // (requiredAllowance - currentAllowance would be negative, which reverts as
+    // an out-of-range uint256).
+    const allowancePrepared = await adapter.prepareAction('token.allowance', {
+        tokenAddress: approvalToken,
+        delegate
+    }, {
+        chain,
+        address
+    });
+    const currentAllowance = parseAllowanceResponse(await allowancePrepared.execute());
+    const approvalNeeded = currentAllowance < requiredAllowance;
+    const executePrepared = await adapter.prepareAction(actionKey, {
+        executeParams,
+        tokenInputs,
+        signature
+    }, {
+        chain,
+        address
+    });
+    const approvePrepared = approvalNeeded ? await prepareApprovalAction({
+        adapter,
+        chain,
+        address,
+        tokenAddress: approvalToken,
+        delegate,
+        currentAllowance,
+        requiredAllowance
+    }) : undefined;
+    if (executePrepared.type !== 'evm' || !executePrepared.getCallData) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ACTION,
+            recoverability: 'FATAL',
+            message: 'Batched earn execution requires EVM prepared requests with getCallData() support.'
+        });
+    }
+    if (approvePrepared !== undefined && (approvePrepared.type !== 'evm' || !approvePrepared.getCallData)) {
+        throw new KitError({
+            ...InputError.UNSUPPORTED_ACTION,
+            recoverability: 'FATAL',
+            message: 'Batched earn execution requires EVM prepared requests with getCallData() support.'
+        });
+    }
+    const executeCallData = executePrepared.getCallData();
+    // Prepend the approve call only when an allowance top-up is required.
+    const calls = approvePrepared?.type === 'evm' && approvePrepared.getCallData ? [
+        approvePrepared.getCallData(),
+        executeCallData
+    ] : [
+        executeCallData
+    ];
+    const authorization = buildBatchedEarnExecuteDescriptor({
+        action: actionKey === 'earn.deposit' ? 'deposit' : 'withdraw',
+        chain: evmChain.chain,
+        executionParams: executeParams
+    });
+    const result = await batchAdapter.batchExecute(calls, evmChain, {
+        fromAddress: address,
+        idempotencyKey,
+        atomicRequired: true,
+        authorization
+    });
+    // Success fans one confirmed hash across every receipt; the execute call is
+    // the last one (approve, if present, precedes it). On failure a confirming
+    // adapter returns no receipts, so a missing/non-success last receipt — or a
+    // populated `result.error` — means the batch failed after submission (point
+    // of no return). We never fall back, which would double-spend.
+    const receiptCountMatches = result.receipts.length === calls.length;
+    const executeReceipt = receiptCountMatches ? result.receipts[calls.length - 1] : undefined;
+    const succeeded = receiptCountMatches && (result.statusCode === undefined || result.statusCode === 200) && result.error === undefined && executeReceipt?.status === 'success' && executeReceipt.txHash !== '';
+    if (succeeded) {
+        return buildSuccessfulBatchResult(adapter, evmChain, executeReceipt, result.batchId, revertMessage);
+    }
+    // Distinguish an off-chain rejection, a confirmed on-chain revert, and an
+    // unknown outcome across both adapter conventions that share this contract:
+    //   - Circle SCA: no receipts + `error`; its trace kind identifies an
+    //     off-chain rejection, confirmed revert, or unconfirmed outcome.
+    //   - Viem EIP-5792: statusCode 500/600 explicitly confirms an on-chain
+    //     full/partial revert.
+    //   - Legacy/string-status wallets: a real-hash error receipt with no cause
+    //     is the best available confirmed-revert signal.
+    // statusCode 400 is terminal but off-chain: the wallet confirms no call was
+    // included, so it must not be labeled as a revert or unknown outcome.
+    // Anything else — a poll timeout or any other post-submission failure with no
+    // confirmed-revert signal — means the batch was submitted but its fate is
+    // unconfirmed. Surface that as a FATAL (non-auto-retry) error carrying
+    // `batchId` so the caller checks status before retrying, rather than
+    // mislabeling it a revert.
+    return throwBatchFailure(result, executeReceipt, evmChain, actionKey, revertMessage);
+}
+
 /**
  * Validate that a service-signed execution payload has not expired before
  * the SDK asks the wallet to broadcast a transaction.
@@ -14227,7 +16114,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name = "@circle-fin/provider-earn-service";
-var version = "1.3.0";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -14289,15 +16176,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 +16212,7 @@ var pkg = {
             ...DEFAULT_CONFIG,
             headers: {
                 ...DEFAULT_CONFIG.headers,
-                [SDK_VERSION_HEADER]: sdkVersion,
+                ...sdkVersionHeader,
                 Authorization: `Bearer ${serviceConfig.kitKey}`
             }
         },
@@ -15845,6 +17742,46 @@ function finishElapsedWait(lastStatus, lastError) {
             const approvalToken = resolveEarnApprovalToken(executionParams);
             const tokenInputs = approvalToken === undefined ? [] : buildEarnTokenInputs(executionParams, approvalToken);
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
+            const approvalNeeded = !options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n;
+            // Batch-capable wallets bundle approve + deposit into one atomic
+            // submission. Only attempt this when an approval is actually needed.
+            if (approvalNeeded && approvalToken !== undefined && await shouldUseBatchedEarnAction({
+                adapter,
+                chain,
+                address,
+                batchTransactions: config?.batchTransactions
+            })) {
+                const { txHash, explorerUrl } = await this.runPhase(ctx, 'deposit', 'execute', async ()=>{
+                    try {
+                        const result = await executeBatchedEarnAction({
+                            adapter,
+                            chain,
+                            address,
+                            actionKey: 'earn.deposit',
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature,
+                            approvalToken,
+                            delegate: adapterContractAddress,
+                            requiredAllowance,
+                            idempotencyKey: execId,
+                            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,
+                    explorerUrl,
+                    vaultAddress,
+                    amount: params.amount
+                };
+            }
             if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n) {
                 await this.runPhase(ctx, 'approve', 'approve', async ()=>{
                     try {
@@ -15877,6 +17814,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'deposit',
+                        executionParams,
                         revertMessage: 'Earn deposit reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Deposit', result);
@@ -16008,6 +17947,44 @@ function finishElapsedWait(lastStatus, lastError) {
             const tokenInputs = buildEarnTokenInputs(executionParams, vaultAddress);
             const approvalToken = tokenInputs[0]?.token;
             const requiredAllowance = sumTokenInputAmounts(tokenInputs);
+            // Batch-capable wallets bundle approve + withdraw into one atomic
+            // submission. Only attempt this when an approval is actually needed.
+            if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n && await shouldUseBatchedEarnAction({
+                adapter,
+                chain,
+                address,
+                batchTransactions: config?.batchTransactions
+            })) {
+                const { txHash, explorerUrl } = await this.runPhase(ctx, 'withdraw', 'execute', async ()=>{
+                    try {
+                        const result = await executeBatchedEarnAction({
+                            adapter,
+                            chain,
+                            address,
+                            actionKey: 'earn.withdraw',
+                            executeParams: executionParams,
+                            tokenInputs,
+                            signature,
+                            approvalToken,
+                            delegate: adapterContractAddress,
+                            requiredAllowance,
+                            idempotencyKey: execId,
+                            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,
+                    vaultAddress,
+                    amount: params.amount
+                };
+            }
             if (!options.skipApprove && approvalToken !== undefined) {
                 await this.runPhase(ctx, 'approve', 'approve', async ()=>{
                     try {
@@ -16040,6 +18017,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'withdraw',
+                        executionParams,
                         revertMessage: 'Earn withdraw reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
@@ -16119,6 +18098,8 @@ function finishElapsedWait(lastStatus, lastError) {
                         tokenInputs: [],
                         signature
                     },
+                    action: 'claimRewards',
+                    executionParams,
                     revertMessage: 'Earn claim rewards reverted on-chain'
                 }), ({ txHash })=>txHash);
             return {
@@ -16419,6 +18400,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 +18417,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.
  *
@@ -16771,11 +18783,16 @@ const sourceAdapterContextSchema = z.object({
  *
  * Validate the optional Kit Key field using the standard `apiKeySchema`
  * format (`KIT_KEY:<keyId>:<keySecret>`). When omitted, the SDK
- * operates in permissionless mode.
+ * operates in permissionless mode. `baseUrl` overrides the Earn Service
+ * endpoint (e.g. staging); `batchTransactions: false` opts out of atomic
+ * batched execution. Both are forwarded to the provider, so this `.strict()`
+ * schema must accept them or a valid config object is rejected.
  *
  * @internal
  */ const earnConfigSchema = z.object({
-    kitKey: apiKeySchema.optional()
+    kitKey: apiKeySchema.optional(),
+    baseUrl: z.string().optional(),
+    batchTransactions: z.boolean().optional()
 }).strict();
 /**
  * Canonical decimal form: a leading digit with no leading zeros (a single
@@ -17945,6 +19962,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 +19984,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 +20106,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 +20132,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 +20202,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 +20265,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 +20292,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 +20344,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 +20371,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 +20398,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 +20447,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 +20482,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 +20514,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 +20538,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 +20562,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 +20653,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;
 };