@circle-fin/app-kit 1.10.0 → 1.12.0

package/index.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 from 'pino';
 import { parseUnits as parseUnits$1, formatUnits as formatUnits$1 } from '@ethersproject/units';
@@ -27,61 +38,69 @@ import { PublicKey } from '@solana/web3.js';
 import 'bn.js';
 import '@coral-xyz/anchor';
 import '@noble/curves/ed25519';
+import { decodeFunctionData } from 'viem';
 import { keccak256 } from '@ethersproject/keccak256';
 
+// Import global type declarations
 /**
- * Creates a AppKit context.
+ * Check whether the current runtime is Node.js.
  *
- * This function constructs a context object, initializes the actions registry
- * used for event handlers, and merges in any custom implementations provided
- * via params.
+ * @returns `true` when running in Node.js, `false` otherwise.
  *
- * @param params - Optional custom implementations to override defaults
- * @returns A AppKitContext
+ * @example
+ * ```typescript
+ * import { isNodeEnvironment } from '@core/utils'
+ *
+ * if (isNodeEnvironment()) {
+ *   console.log('Running in Node.js')
+ * }
+ * ```
+ */ 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
- * // Create context with all defaults
- * const defaultContext = createContext()
+ * import { isBrowserEnvironment } from '@core/utils'
  *
- * // Create context with custom fee calculation
- * const customContext = createContext({
- *   getFee: async (type, params) => {
- *     if (type === 'bridge') {
- *       // Custom bridge fee logic
- *       return await calculateBridgeFee(params)
- *     }
- *     // Use default for other types
- *     return defaultFeeCalculation(type, params)
- *   }
- * })
+ * if (isBrowserEnvironment()) {
+ *   throw new Error('Server-only secrets must not be used in the browser')
+ * }
  * ```
- */ const createContext = (params = {})=>{
-    return {
-        ...params,
-        actions: {
-            bridge: {},
-            earn: {},
-            ...params.actions
-        }
-    };
+ */ const isBrowserEnvironment = ()=>{
+    const browserWindow = globalThis.window;
+    return !isNodeEnvironment() && browserWindow?.document !== undefined;
 };
-
-// Import global type declarations
 /**
- * Check whether the current runtime is Node.js.
+ * Return the SDK User-Agent request header only when running in Node.js.
  *
- * @returns `true` when running in Node.js, `false` otherwise.
+ * 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 { isNodeEnvironment } from '@core/utils'
+ * import { getNodeUserAgentHeader } from '@core/utils'
  *
- * if (isNodeEnvironment()) {
- *   console.log('Running in Node.js')
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
  * }
  * ```
- */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -4067,6 +4086,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 = {}));
@@ -4120,6 +4141,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";
@@ -4145,6 +4167,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) {
@@ -6703,7 +6726,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',
@@ -7568,6 +7592,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
@@ -7687,6 +7809,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 });
@@ -9282,13 +9406,12 @@ const swapTokenEnumSchema = z.enum([
         headers: {
             ...DEFAULT_CONFIG$3.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;
@@ -10051,6 +10174,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -10085,6 +10209,7 @@ function parseOrThrow(value, schema, context) {
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -11034,6 +11159,52 @@ function parseOrThrow(value, schema, context) {
     return explorerUrl;
 }
 
+/**
+ * Assert that a value has type `never` (exhaustive switch helper).
+ *
+ * @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 _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
+ * type Foo = { type: 'a'; x: number } | { type: 'b'; y: string }
+ *
+ * function handle(foo: Foo): string {
+ *   switch (foo.type) {
+ *     case 'a': return String(foo.x)
+ *     case 'b': return foo.y
+ *     default: return assertNever(foo)
+ *   }
+ * }
+ * ```
+ */ 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}`);
+}
+
 /**
  * CCTP forwarding magic bytes prefix.
  *
@@ -11219,6 +11390,7 @@ function resolveOptions(options) {
     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 && {
@@ -11289,18 +11461,15 @@ function resolveOptions(options) {
         timeoutHandle.unref();
     }
     try {
-        const isNode = isNodeEnvironment();
-        const userAgent = getUserAgent();
         await fetch(getLogsUrl(), {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                // Browser restricts setting User-Agent; use X-User-Agent instead.
-                ...isNode ? {
-                    'User-Agent': userAgent
-                } : {
-                    'X-User-Agent': userAgent
-                }
+                // 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
@@ -11513,7 +11682,7 @@ function resolveOptions(options) {
         // 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 error event '${eventType}':`, cause);
+        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.
@@ -11529,7 +11698,9 @@ function resolveOptions(options) {
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -11545,9 +11716,45 @@ function resolveOptions(options) {
         },
         ...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$1(config, eventType, undefined, context));
+    } catch (telemetryError) {
+        warnTelemetryDrop(eventType, telemetryError);
+    }
+}
 /**
  * Wrap an async operation with error telemetry.
  *
@@ -11658,7 +11865,7 @@ function resolveOptions(options) {
 }
 
 var name$4 = "@circle-fin/bridge-kit";
-var version$5 = "1.12.1";
+var version$5 = "1.13.0";
 var pkg$5 = {
 	name: name$4,
 	version: version$5};
@@ -11695,13 +11902,21 @@ const assertCustomFeePolicySymbol$2 = Symbol('assertCustomFeePolicy');
     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)=>{
+}).strict().superRefine((data, ctx)=>{
     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.'
+    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.'
+        });
+    }
 });
 /**
  * Assert that the provided value conforms to {@link CustomFeePolicy}.
@@ -14294,7 +14509,13 @@ const FAST_TIER_FINALITY_THRESHOLD = 1000;
 /**
  * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
  * hookData must start with.
- */ const CCTP_FORWARD_MAGIC_HEX = Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+ *
+ * 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`.
+ */ const CCTP_FORWARD_MAGIC_HEX = Array.from(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX)).map((byte)=>byte.toString(16).padStart(2, '0')).join('');
 /**
  * Determine whether a hookData blob begins with the `cctp-forward` envelope.
  *
@@ -14495,14 +14716,32 @@ const CUSTOM_BURN_GAS_ESTIMATE_EVM = 201_525n // p99 and max are same here: 201_
 ;
 const RECEIVE_MESSAGE_GAS_ESTIMATE_EVM = 237_401n // (99p: 163_963n + max: 310_839n) / 2 = 237_401n
 ;
-// Hard execution caps: observed max + ~30% buffer, used as gasLimit overrides on
-// chains whose eth_estimateGas under-reports (e.g. Cronos EIP-7623 calldata floor).
-// Kept separate from the fee-estimate averages above.
-const APPROVE_GAS_LIMIT_EVM = 100_000n // ERC-20 approve observed max ~46k
+// Gas FLOORS, not ceilings — kept separate from the fee-estimate averages
+// above. `executePreparedChainRequest` submits
+// max(estimate * buffer, floor), so a chain whose real cost exceeds the floor
+// is covered by its own estimate, and a chain whose estimator under-reports
+// (Cronos: returns 30_600 where the EIP-7623 calldata floor is 45_000) is
+// covered by the floor.
+//
+// Two distinct chain surcharges drive these numbers, both measured live:
+//   Sei  — ~+51_500 per NEWLY CREATED storage slot (73_595 vs vanilla 22_100);
+//          no flat per-tx surcharge (31_535, identical to Base).
+//   Edge — ~+53_200 flat on EVERY tx (84_751 vs Base 31_535); storage priced
+//          normally. Edge therefore fails warm as well as cold.
+// A floor must clear the worst COLD cost, since a slot that exists at estimate
+// time can be consumed before inclusion and cost a full step more on execution.
+// Each floor is therefore derived from the worst observed estimate *after* the
+// 1.25x buffer, plus headroom — sizing it below the buffered value would leave
+// the estimate governing and defeat the point of the floor.
+//
+// The `*_GAS_LIMIT_EVM` names are kept despite these being floors: they are
+// exported, so renaming to `*_GAS_FLOOR_EVM` would be a breaking change for
+// consumers. Read "LIMIT" here as "the limit we submit", never as a ceiling.
+const APPROVE_GAS_LIMIT_EVM = 150_000n // buffered worst cold 149_355 (Edge Testnet 119_484 x 1.25) + drift headroom
 ;
-const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 300_000n // observed max 226_506 + ~30%
+const DEPOSIT_FOR_BURN_GAS_LIMIT_EVM = 500_000n // buffered worst 474_078 (Sei 379_263 x 1.25) + ~26k headroom
 ;
-const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839 + ~30%
+const RECEIVE_MESSAGE_GAS_LIMIT_EVM = 400_000n // observed max 310_839; clears Cronos' calldata floor ~10x
 ;
 /**
  * The minimum finality threshold for CCTPv2 transfers.
@@ -15967,6 +16206,63 @@ function hasPendingState(analysis, result) {
     return waitForPendingTransaction(pendingStep, adapter, chain);
 }
 
+/**
+ * Multiplier applied to a successful gas estimate before it is submitted.
+ *
+ * Estimates are exact, not padded: Sei returns 109_739 for an approve that
+ * consumes 107_717 (1.9% headroom). Chains that price storage in large steps
+ * can exceed the estimate if state changes between estimation and inclusion,
+ * so the estimate is padded before use.
+ *
+ * @remarks
+ * This buffer alone does NOT cover Sei's ~51_500 per-new-slot step at approve
+ * scale (25% of ~110_000 is only ~27_500). For approve, the FLOOR is what
+ * covers a slot that exists at estimation time and is consumed before
+ * inclusion — so do not lower `APPROVE_GAS_LIMIT_EVM` on the reasoning that
+ * the estimate covers it. For burn the buffer does cover a step (25% of
+ * ~300_000 exceeds 51_500).
+ */ const GAS_ESTIMATE_BUFFER_PERCENT = 125n;
+/**
+ * Resolve the gas limit for an EVM request as `max(estimate * buffer, floor)`.
+ *
+ * Estimates first so chains whose real cost exceeds the floor are covered by
+ * their own measurement, and falls back to the floor whenever estimation is
+ * unavailable or under-reports. Estimation failure is never fatal here: before
+ * floors existed these requests were submitted with a pinned limit and no
+ * estimate at all, so degrading to the floor is never worse than the previous
+ * behaviour.
+ *
+ * @param request - The prepared EVM request to size a gas limit for
+ * @param gasFloor - The minimum gas limit to submit, in gas units
+ * @returns The gas limit to submit, in gas units
+ * @throws Never — estimation failures degrade to `gasFloor`
+ *
+ * @example
+ * ```typescript
+ * const gasLimit = await resolveGasLimit(request, 150_000)
+ * ```
+ */ const resolveGasLimit = async (request, gasFloor)=>{
+    try {
+        // Deliberately called without a `fallback`: both the viem and ethers
+        // adapters *return* the supplied fallback object when estimation reverts
+        // rather than throwing, which would set the estimate to the floor and then
+        // multiply it by the buffer below. Omitting it routes reverts through the
+        // catch, so a failed estimate degrades to exactly the floor.
+        const estimate = await request.estimate();
+        // The arithmetic stays inside the try on purpose. `EstimatedGas.gas` is
+        // typed `bigint`, but adapters are a public extension point and may be
+        // implemented in plain JS, so a non-bigint `gas` would throw here
+        // ("Cannot mix BigInt and other types"). Guarding it keeps the documented
+        // contract — estimation never aborts a step, it degrades to the floor.
+        const buffered = estimate.gas * GAS_ESTIMATE_BUFFER_PERCENT / 100n;
+        // Convert before comparing: Math.max throws on BigInt operands, and gas
+        // units are far below Number.MAX_SAFE_INTEGER so the narrowing is lossless.
+        return Math.max(Number(buffered), gasFloor);
+    } catch  {
+        // Estimation is best-effort; the floor is the known-safe value.
+        return gasFloor;
+    }
+};
 /**
  * Executes a prepared chain request and returns the result as a bridge step.
  *
@@ -15980,8 +16276,8 @@ function hasPendingState(analysis, result) {
  *   - `adapter`: The adapter that will execute the transaction
  *   - `confirmations`: The number of confirmations to wait for (defaults to 1)
  *   - `timeout`: The timeout for the request in milliseconds
- *   - `gasLimit`: Optional explicit gas limit (number) forwarded to EVM execute,
- *     bypassing `eth_estimateGas`; ignored for non-EVM requests
+ *   - `gasFloor`: Optional minimum gas limit (number); the request is submitted
+ *     with `max(estimate * 1.25, gasFloor)`. Ignored for non-EVM requests
  * @returns The bridge step with the transaction details and explorer URL
  * @throws If the transaction execution fails
  *
@@ -15996,7 +16292,7 @@ function hasPendingState(analysis, result) {
  * })
  * console.log('Transaction hash:', step.txHash)
  * ```
- */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasLimit }) {
+ */ async function executePreparedChainRequest({ name, request, adapter, chain, confirmations = 1, timeout, gasFloor }) {
     const step = {
         name,
         state: 'pending'
@@ -16009,8 +16305,8 @@ function hasPendingState(analysis, result) {
             step.state = 'noop';
             return step;
         }
-        const txHash = request.type === 'evm' && gasLimit !== undefined ? await request.execute({
-            gasLimit
+        const txHash = request.type === 'evm' && gasFloor !== undefined ? await request.execute({
+            gasLimit: await resolveGasLimit(request, gasFloor)
         }) : await request.execute();
         step.txHash = txHash;
         const retryOptions = {
@@ -16084,7 +16380,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.approve(params.source, approvalAmount),
-        gasLimit: Number(APPROVE_GAS_LIMIT_EVM)
+        gasFloor: Number(APPROVE_GAS_LIMIT_EVM)
     });
 }
 
@@ -16112,7 +16408,7 @@ function hasPendingState(analysis, result) {
         adapter: params.source.adapter,
         chain: params.source.chain,
         request: await provider.burn(params),
-        gasLimit: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
+        gasFloor: Number(DEPOSIT_FOR_BURN_GAS_LIMIT_EVM)
     });
 }
 
@@ -16206,10 +16502,9 @@ function hasPendingState(analysis, result) {
         request: mintRequest,
         // Some chains (e.g. Cronos) enforce an EIP-7623 calldata gas floor that
         // eth_estimateGas does not account for, returning a below-floor value
-        // without reverting. Pinning to a value above the observed execution max
-        // (310_839) bypasses re-estimation and guarantees we clear both the floor
-        // and the actual execution cost.
-        gasLimit: Number(RECEIVE_MESSAGE_GAS_LIMIT_EVM)
+        // without reverting. The floor covers those; chains that cost more than the
+        // floor are covered by their own estimate.
+        gasFloor: Number(RECEIVE_MESSAGE_GAS_LIMIT_EVM)
     });
     // Add forwarded: false for non-relayer mints
     return {
@@ -16732,7 +17027,7 @@ const mockAttestationMessage = {
     return step;
 }
 
-var version$4 = "1.10.0";
+var version$4 = "1.10.2";
 var pkg$4 = {
 	version: version$4};
 
@@ -18611,7 +18906,7 @@ function assertCCTPV2Config(config) {
     ]
 ];
 
-/** SDK name used in telemetry payloads. */ const SDK_NAME$2 = resolveKitSdkName(pkg$5.name);
+/** SDK name used in telemetry payloads. */ const SDK_NAME$3 = resolveKitSdkName(pkg$5.name);
 /**
  * Pick the most-relevant `txHash` to attach to an error telemetry payload.
  *
@@ -18753,7 +19048,7 @@ function assertCCTPV2Config(config) {
         this.actionDispatcher = new Actionable();
         this.disableErrorReporting = config.disableErrorReporting === true;
         this.telemetryConfig = {
-            sdkName: SDK_NAME$2,
+            sdkName: SDK_NAME$3,
             sdkVersion: pkg$5.version,
             disabled: this.disableErrorReporting
         };
@@ -19278,75 +19573,8 @@ function assertCCTPV2Config(config) {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg$5.name}/${pkg$5.version}`);
 
-/**
- * Create a BridgeKit instance with optional developer fee configuration.
- *
- * This utility creates a BridgeKit instance that optionally includes developer
- * fee configuration based on the provided AppKit context. If the context
- * provides both `getFee` and `getFeeRecipient` methods, they will be configured
- * as developer fees in the BridgeKit instance using the `setCustomFeePolicy` method.
- *
- * The fee integration transforms string-based fees from the context into the
- * format expected by BridgeKit, enabling seamless fee calculation across both kits.
- *
- * @param context - The AppKit context containing optional fee methods
- * @returns A configured BridgeKit instance with or without developer fees
- *
- * @example
- * ```typescript
- * import { createBridgeKit } from '@circle-fin/app-kit/utils'
- * import { createContext } from '@circle-fin/app-kit/context'
- *
- * // Create context with fee methods
- * const context = createContext({
- *   getFee: async (type, params) => '1000000', // 1 USDC in micro-units
- *   getFeeRecipient: async (type, info) => '0x742d35Cc4634C0532925a3b8D1d7'
- * })
- *
- * // Create BridgeKit with developer fees
- * const bridgeKit = createBridgeKit(context)
- * ```
- *
- * @example
- * ```typescript
- * import { createBridgeKit } from '@circle-fin/app-kit/utils'
- * import { createContext } from '@circle-fin/app-kit/context'
- *
- * // Create context without fee methods
- * const context = createContext()
- *
- * // Create standard BridgeKit instance
- * const bridgeKit = createBridgeKit(context)
- * ```
- */ const createBridgeKit = (context)=>{
-    const getFee = context.getFee?.bind(context);
-    const getFeeRecipient = context.getFeeRecipient?.bind(context);
-    const hasBoth = typeof getFee === 'function' && typeof getFeeRecipient === 'function';
-    const kit = new BridgeKit({
-        ...context.disableErrorReporting != null && {
-            disableErrorReporting: context.disableErrorReporting
-        },
-        ...context.headers != null && {
-            headers: context.headers
-        }
-    });
-    if (hasBoth) {
-        kit.setCustomFeePolicy({
-            calculateFee: async (params)=>{
-                const feeStr = await getFee('bridge', params);
-                return feeStr;
-            },
-            resolveFeeRecipientAddress: async (chain, params)=>await getFeeRecipient('bridge', {
-                    chain,
-                    params: params || {}
-                })
-        });
-    }
-    return kit;
-};
-
 var name$3 = "@circle-fin/swap-kit";
-var version$3 = "1.4.0";
+var version$3 = "1.5.1";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -20179,6 +20407,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
@@ -20304,6 +20542,45 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     // Validate without trimming - any whitespace will cause validation to fail
     return apiKeyPattern.test(apiKey);
 };
+/**
+ * Assert that a Stablecoin Service kit key is not being supplied from a browser.
+ *
+ * The kit key (`KIT_KEY:<id>:<secret>`) is a server-only secret. Every
+ * Stablecoin Service request that attaches an `Authorization: Bearer` header
+ * funnels through this package, so calling this guard before that header is
+ * built prevents the secret from being sent from — and thus bundled into — a
+ * client application. In Node.js the check is a no-op, preserving the
+ * legitimate "hold the kit key on the server, forward the prepared transaction
+ * to the client" flow. When no kit key is supplied the permissionless (keyless)
+ * client path remains fully allowed.
+ *
+ * @param apiKey - The inline kit key for the request, or `undefined` when none
+ *   was supplied (permissionless mode).
+ * @returns Nothing.
+ * @throws KitError with VALIDATION_FAILED when a kit key is supplied while
+ *   running in a browser environment. The secret value is never echoed.
+ *
+ * @example
+ * ```typescript
+ * import { assertBrowserSafeApiKey } from '@core/service-client'
+ *
+ * // Server (Node.js): no-op, request proceeds with the Authorization header.
+ * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ *
+ * // Browser: throws to stop the secret from leaking into the client bundle.
+ * assertBrowserSafeApiKey('KIT_KEY:my-id:my-secret')
+ *
+ * // Browser, permissionless: allowed.
+ * assertBrowserSafeApiKey(undefined)
+ * ```
+ */ const assertBrowserSafeApiKey = (apiKey)=>{
+    if (apiKey === undefined) {
+        return;
+    }
+    if (isBrowserEnvironment()) {
+        throw createValidationFailedError$1('kitKey', '[redacted]', 'kitKey must not be provided in a browser environment — it is a server-only secret. Run kit operations that use a kit key on your server, or omit kitKey to use the permissionless (keyless) client path');
+    }
+};
 
 /**
  * Create a cross-chain bridge and swap transaction through the Stablecoin Service.
@@ -20361,6 +20638,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     const url = new URL('/v1/stablecoinKits/swap', STABLECOIN_SERVICE_BASE_URL).toString();
     // Remove the API key from the request body
     const { apiKey, ...requestBody } = validatedParams;
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(apiKey);
     const effectiveConfig = {
         ...DEFAULT_CONFIG$1,
         headers: {
@@ -20515,6 +20794,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     }
     // Use validated data
     const validatedParams = result.data;
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     // Build the API URL
     const url = buildQuoteUrl(validatedParams);
     // Merge default config with Authorization header
@@ -20587,6 +20868,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
             toChain: result.data.toChain
         }
     };
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildSwapStatusUrl(validatedParams);
     const effectiveConfig = {
         ...DEFAULT_CONFIG$1,
@@ -20691,6 +20974,8 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
             addresses: result.data.addresses
         }
     };
+    // Never let a server-only kit key leave a browser (no-op in Node.js).
+    assertBrowserSafeApiKey(validatedParams.apiKey);
     const url = buildTokenRatesUrl(validatedParams);
     const effectiveConfig = {
         ...DEFAULT_CONFIG$1,
@@ -20705,6 +20990,138 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     return pollApiGet(url, isGetTokenRatesResponse, effectiveConfig);
 };
 
+/**
+ * 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'
+    }
+];
+
 /**
  * USDC ABI
  *
@@ -21940,6 +22357,179 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
     }
 ];
 
+/**
+ * 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: []
+    }
+];
+
 /**
  * Zod schema for validating EVM adapter capabilities.
  *
@@ -23448,72 +24038,55 @@ function evmSigningData(burnIntent) {
  * `0xef0100` followed by the 20-byte delegate address (23 bytes total).
  * The underlying secp256k1 key still produces `ecrecover`-verifiable
  * signatures, so for Gateway's purposes a 7702-delegated address is
- * an EOA, not an SCA.
+ * an EOA, not a contract signer.
  *
  * Spec: https://eips.ethereum.org/EIPS/eip-7702
  */ const EIP_7702_DELEGATION_PREFIX = '0xef0100';
 /**
- * Assert that `address` on `chain` can sign Gateway burn intents.
- *
- * Gateway verifies burn-intent signatures with plain `ecrecover` (see
- * `evm-gateway-contracts/src/lib/EIP712Domain.sol`). Smart-contract
- * accounts (SCAs) produce signatures over wrapped hashes (ERC-1271 /
- * ERC-6492 / ERC-6900 replay-safe hashes) that Gateway cannot verify.
- * Additionally, the Circle Wallets backend rejects SCA typed-data signing
- * against Gateway's chainId-less domain with an opaque
- * `invalid integer value <nil>/<nil> for type uint256` error.
+ * Determine whether `address` on `chain` signs as a contract (ERC-1271)
+ * rather than as an EOA.
  *
- * EIP-7702-delegated EOAs are exempt: they expose non-empty bytecode
- * (`0xef0100<delegate>`) but the underlying secp256k1 key still produces
- * `ecrecover`-verifiable signatures, so Gateway accepts them.
+ * Gateway validates burn-intent signatures two ways: a static `ecrecover`
+ * check for EOAs, and — for requests that carry `contractSigner: true` —
+ * an offchain `isValidSignature` simulation against the signing contract
+ * (ERC-1271). Gateway does not infer which one to use, so the caller must
+ * declare it. This detects the contract case from on-chain bytecode.
  *
- * When the signer is a true SCA, raises an `INPUT_UNSUPPORTED_ACTION`
- * error directing the caller to register an EOA delegate against the
- * SCA and then submit the spend with the delegate EOA as the signer
- * and the SCA as the source account. See the unified-balance / Gateway
- * docs for the exact API.
+ * EIP-7702-delegated EOAs are treated as EOAs: they expose non-empty
+ * bytecode (`0xef0100<delegate>`) but the underlying secp256k1 key still
+ * produces `ecrecover`-verifiable signatures, so the cheaper EOA path
+ * stays correct for them.
  *
- * If bytecode cannot be read (RPC failure, etc.) the pre-check is
- * skipped and downstream signing surfaces its own error — a warning is
- * logged so the skip is diagnosable.
+ * If bytecode cannot be read (RPC failure, etc.) the address is reported
+ * as an EOA and a warning is logged so the fallback is diagnosable. A
+ * genuine contract signer misreported this way is rejected by Gateway with
+ * an invalid-signature error rather than silently mis-attested.
  *
  * @param adapter - Anything exposing {@link EvmAdapterLike.readBytecode}.
- * @param address - Signer address to validate.
+ * @param address - Signer address to classify.
  * @param chain - EVM chain where the signer lives.
- * @throws {KitError} INPUT_UNSUPPORTED_ACTION when `address` is an SCA.
+ * @returns `true` when the signer is a contract account and the transfer
+ *   request must set `contractSigner: true`; `false` otherwise.
  *
  * @example
  * ```typescript
- * import { assertSignerIsEoa } from '@core/adapter-evm'
+ * import { isContractSigner } from '@core/adapter-evm'
  * import { Ethereum } from '@core/chains'
  *
- * await assertSignerIsEoa(adapter, '0xabc...', Ethereum)
+ * const useErc1271 = await isContractSigner(adapter, '0xabc...', Ethereum)
  * ```
- */ async function assertSignerIsEoa(adapter, address, chain) {
+ */ async function isContractSigner(adapter, address, chain) {
     let code;
     try {
         code = await adapter.readBytecode(address, chain);
     } catch (err) {
-        console.warn(`[gateway] assertSignerIsEoa skipped (readBytecode failed for ` + `${address} on ${chain.name}): ` + (err instanceof Error ? err.message : String(err)));
-        return;
+        console.warn(`[gateway] isContractSigner defaulting to EOA (readBytecode failed ` + `for ${address} on ${chain.name}): ` + (err instanceof Error ? err.message : String(err)));
+        return false;
     }
     if (code === undefined || code === '0x' || code.toLowerCase().startsWith(EIP_7702_DELEGATION_PREFIX)) {
-        return;
+        return false;
     }
-    throw new KitError({
-        ...InputError.UNSUPPORTED_ACTION,
-        recoverability: 'FATAL',
-        message: `Gateway burn-intent signing requires an EOA signer (Gateway ` + `verifies signatures with ecrecover and does not support ERC-1271). ` + `The signer ${address} on ${chain.name} has on-chain bytecode, ` + `indicating it is a smart-contract account (SCA). Register an EOA ` + `delegate against the SCA, then submit the spend with the delegate ` + `EOA as the signer and the SCA as the source account. See DEVX-2774.`,
-        cause: {
-            trace: {
-                operation: 'signEvmIntentGroup.assertSignerIsEoa',
-                address,
-                chain: chain.name,
-                bytecodeBytes: (code.length - 2) / 2,
-                bytecodePrefix: code.slice(0, 12)
-            }
-        }
-    });
+    return true;
 }
 
 /**
@@ -23540,78 +24113,177 @@ function evmSigningData(burnIntent) {
     return typeof value === 'object' && value !== null && 'readBytecode' in value && typeof value.readBytecode === 'function';
 }
 
+function resolveIntentChain(group, intent) {
+    const sourceDomain = intent.spec.sourceDomain;
+    const chain = group.chainsByDomain.get(sourceDomain);
+    if (chain !== undefined) return chain;
+    throw createValidationFailedError$1('intent.spec.sourceDomain', sourceDomain, `No source chain found for Gateway domain ${String(sourceDomain)}`);
+}
+function normalizeSignatureResult(result) {
+    if (typeof result === 'string') {
+        return {
+            signature: result,
+            contractSigner: false
+        };
+    }
+    if (typeof result === 'object' && result !== null && 'signature' in result && typeof result.signature === 'string') {
+        return {
+            signature: result.signature,
+            contractSigner: 'contractSigner' in result && result.contractSigner === true
+        };
+    }
+    throw createValidationFailedError$1('signature', result, 'must be a signature string or an object containing a signature string');
+}
+function validateGroupIntents(intents) {
+    evmSigningData(intents);
+}
+function collectChainsByDomain(group) {
+    const chainsByDomain = new Map();
+    for (const intent of group.intents){
+        chainsByDomain.set(intent.spec.sourceDomain, resolveIntentChain(group, intent));
+    }
+    return chainsByDomain;
+}
+async function classifySignerTypes(group, chainsByDomain) {
+    const { adapter, address } = group;
+    // Duck-typed on readBytecode rather than `instanceof EvmAdapter` because
+    // each consumer package bundles its own copy of the base class and the
+    // `instanceof` identity check fails across package boundaries.
+    // Empty strings are rejected to avoid calling eth_getCode('') on the RPC.
+    const hasResolvedSigner = typeof address === 'string' && address.length > 0;
+    const signerTypes = await Promise.all([
+        ...chainsByDomain
+    ].map(async ([sourceDomain, sourceChain])=>{
+        const contractSigner = hasResolvedSigner && sourceChain.type === 'evm' && isEvmAdapterLike(adapter) ? await isContractSigner(adapter, address, sourceChain) : false;
+        return [
+            sourceDomain,
+            contractSigner
+        ];
+    }));
+    return new Map(signerTypes);
+}
+function createSigningUnits(group, signerTypeByDomain) {
+    const contractUnitsByDomain = new Map();
+    let eoaUnit;
+    for (const [index, intent] of group.intents.entries()){
+        const sourceDomain = intent.spec.sourceDomain;
+        const contractSigner = signerTypeByDomain.get(sourceDomain) ?? false;
+        if (contractSigner) {
+            const existingUnit = contractUnitsByDomain.get(sourceDomain);
+            if (existingUnit === undefined) {
+                contractUnitsByDomain.set(sourceDomain, {
+                    intents: [
+                        intent
+                    ],
+                    chain: resolveIntentChain(group, intent),
+                    contractSigner: true,
+                    firstIntentIndex: index
+                });
+            } else {
+                existingUnit.intents.push(intent);
+            }
+        } else {
+            eoaUnit ??= {
+                intents: [],
+                chain: resolveIntentChain(group, intent),
+                contractSigner: false,
+                firstIntentIndex: index
+            };
+            eoaUnit.intents.push(intent);
+        }
+    }
+    const signingUnits = [
+        ...contractUnitsByDomain.values()
+    ];
+    if (eoaUnit !== undefined) signingUnits.push(eoaUnit);
+    signingUnits.sort((a, b)=>a.firstIntentIndex - b.firstIntentIndex);
+    return signingUnits;
+}
+async function signUnit(group, unit) {
+    const { adapter, address } = group;
+    const firstIntent = unit.intents[0];
+    const typedData = unit.intents.length === 1 && firstIntent !== undefined ? evmSigningData(firstIntent) : evmSigningData(unit.intents);
+    const operationContext = address === undefined ? {
+        chain: unit.chain
+    } : {
+        chain: unit.chain,
+        address
+    };
+    const signRequest = await adapter.prepareAction('gateway.v1.signBurnIntents', {
+        typedData,
+        chain: unit.chain
+    }, operationContext);
+    const result = normalizeSignatureResult(await signRequest.execute());
+    return {
+        intents: unit.intents,
+        signature: result.signature,
+        contractSigner: result.contractSigner || unit.contractSigner
+    };
+}
+async function signUnits(group, signingUnits) {
+    const signedSets = [];
+    // Keep wallet prompts deterministic. Multiple adapter groups can still sign
+    // in parallel, but one signer is asked for its chain-bound signatures in
+    // source-intent order.
+    for (const unit of signingUnits){
+        signedSets.push(await signUnit(group, unit));
+    }
+    return signedSets;
+}
 /**
- * Sign an EVM adapter group: batches all intents and produces a single
- * EIP-712 ECDSA signature.
+ * Sign an EVM adapter group.
  *
- * For a single-intent group, `primaryType` is `'BurnIntent'`.
- * For multi-intent groups, `primaryType` is `'BurnIntentSet'`.
+ * EOA intents remain batched into one EIP-712 `BurnIntentSet`. ERC-1271
+ * intents are grouped and signed per source chain because smart accounts
+ * commonly include `chainId` in their replay-safe signature hash.
+ * All returned entries can still be submitted together in one atomic Gateway
+ * transfer request.
  *
- * Before signing, asserts that the signer address is an EOA. Gateway
- * verifies burn-intent signatures with plain `ecrecover` (no ERC-1271
- * fallback), so signatures produced by smart-contract accounts (SCAs)
- * cannot be verified. When an SCA is detected, a clear error is raised
- * directing the caller to the delegate workflow (DEVX-2774).
+ * Before signing, classifies the signer as an EOA or a contract account.
+ * Gateway validates EOA signatures with `ecrecover` and contract-account
+ * signatures with ERC-1271, but it does not infer which one applies — the
+ * transfer request has to declare it. The returned `contractSigner` flag
+ * carries that decision through to `buildTransferRequestBody`.
  *
  * @param group - The adapter group containing the adapter, chain, and
  *   burn intents to sign.
- * @returns A signed set with the intents and the ECDSA signature.
+ * @returns Signed entries with their intents, signatures, and Gateway signer
+ *   validation mode.
+ * @throws KitError when an intent has no source-chain mapping or a signing
+ *   action returns an invalid signature shape.
  *
  * @example
  * ```typescript
  * import { signEvmIntentGroup } from '@core/adapter-evm'
  *
- * const signedSet = await signEvmIntentGroup({
+ * const signedSets = await signEvmIntentGroup({
  *   adapter: evmAdapter,
  *   chain: ethereumChain,
  *   intents: [burnIntent1, burnIntent2],
+ *   chainsByDomain: new Map([
+ *     [0, ethereumChain],
+ *     [6, baseChain],
+ *   ]),
  *   address: '0x...',
  * })
- * console.log(signedSet.signature)
+ * console.log(signedSets)
  * ```
  */ async function signEvmIntentGroup(group) {
-    const { adapter, intents: groupIntents, chain, address } = group;
-    const operationContext = address === undefined ? {
-        chain
-    } : {
-        chain,
-        address
-    };
-    // Gateway verifies burn-intent signatures with plain ecrecover. An SCA
-    // signer silently produces a signature over a wrapped hash that Gateway
-    // cannot verify, and Circle Wallets' KMS rejects the typed data up front
-    // with an opaque `<nil>/<nil>` error. Short-circuit with a clear message
-    // when we can detect bytecode at the signer address. See DEVX-2774.
-    //
-    // Duck-typed on readBytecode rather than `instanceof EvmAdapter` because
-    // each consumer package bundles its own copy of the base class and the
-    // `instanceof` identity check fails across package boundaries.
-    //
-    // Empty string is defended against because assertSignerIsEoa would
-    // otherwise call eth_getCode('') on the RPC.
-    const hasResolvedSigner = typeof address === 'string' && address.length > 0;
-    if (hasResolvedSigner && chain.type === 'evm' && isEvmAdapterLike(adapter)) {
-        await assertSignerIsEoa(adapter, address, chain);
-    }
-    const firstIntent = groupIntents[0];
-    const typedData = groupIntents.length === 1 && firstIntent ? evmSigningData(firstIntent) : evmSigningData(groupIntents);
-    const signRequest = await adapter.prepareAction('gateway.v1.signBurnIntents', {
-        typedData,
-        chain
-    }, operationContext);
-    const sig = await signRequest.execute();
-    return {
-        intents: groupIntents,
-        signature: sig
-    };
+    // Validate the collection before doing bytecode reads or asking a wallet
+    // to sign. evmSigningData owns the canonical BurnIntent validation.
+    validateGroupIntents(group.intents);
+    const chainsByDomain = collectChainsByDomain(group);
+    const signerTypeByDomain = await classifySignerTypes(group, chainsByDomain);
+    const signingUnits = createSigningUnits(group, signerTypeByDomain);
+    return await signUnits(group, signingUnits);
 }
 
 /**
  * Add an EVM intent into the batched EVM group map.
  *
  * On EVM, all intents for the same adapter are batched into a single
- * group so that they can be signed in one EIP-712 `BurnIntentSet`
- * operation.
+ * group. The signing step uses `chainsByDomain` to preserve EOA batching
+ * while signing ERC-1271 intents separately on their source chains.
  *
  * @param intent - The burn intent to group.
  * @param alloc - The allocation that resolved to this intent.
@@ -23628,6 +24300,7 @@ function evmSigningData(burnIntent) {
     const existing = evmGroups.get(alloc.adapter);
     if (existing) {
         existing.intents.push(intent);
+        existing.chainsByDomain.set(alloc.chain.gateway.domain, alloc.chain);
     } else {
         evmGroups.set(alloc.adapter, {
             adapter: alloc.adapter,
@@ -23635,6 +24308,12 @@ function evmSigningData(burnIntent) {
             intents: [
                 intent
             ],
+            chainsByDomain: new Map([
+                [
+                    alloc.chain.gateway.domain,
+                    alloc.chain
+                ]
+            ]),
             address: alloc.sourceSigner
         });
     }
@@ -27462,6 +28141,11 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
                 apiKey: serviceParams.apiKey
             }
         });
+        // Per-swap correlation id returned by the service as a top-level response
+        // field for every chain (EVM + Solana). Attached to success telemetry so a
+        // swap can be correlated across records; never used for control flow.
+        // Undefined only against a not-yet-upgraded service that omits it.
+        const correlationId = serviceResponse.correlationId;
         // Build and return SwapResult
         return {
             tokenIn,
@@ -27471,6 +28155,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             fromAddress: serviceParams.fromAddress,
             toAddress: serviceParams.toAddress,
             txHash,
+            ...correlationId !== undefined && {
+                correlationId
+            },
             executedTransactions,
             ...config !== undefined && {
                 config
@@ -30370,7 +31057,13 @@ async function resolveTokenDecimals(context, resolvedParams) {
  *   amountIn: '50.00'
  * })
  * ```
- */ async function swap$1(context, params, /** @internal */ onBroadcast) {
+ */ async function swap$1(context, params, /**
+   * @internal
+   * Invoked after a successful broadcast with the on-chain `txHash` and the
+   * service-issued `correlationId` (join key for success telemetry). The
+   * service returns `correlationId` for every chain (EVM + Solana); it is
+   * undefined only against a not-yet-upgraded service that omits the field.
+   */ onBroadcast) {
     // Step 1: Validate parameters using schema
     assertSwapParams(params, swapParamsSchema);
     // Step 2: Resolve parameters (chain definitions, wallet addresses, token aliases preserved)
@@ -30390,13 +31083,16 @@ async function resolveTokenDecimals(context, resolvedParams) {
     // Step 5: Execute swap via provider
     const swapParams = buildServiceSwapParams(resolvedParams, paramsWithFees);
     const providerResult = await provider.swap(swapParams);
+    // `correlationId` is an internal telemetry join key, not part of the public
+    // SwapResult — strip it here so it never leaks into the formatted result.
+    const { correlationId, ...providerResultPublic } = providerResult;
     // A throwing `onBroadcast` must never strand the caller after a
     // successful swap broadcast — the chain has moved. `safeInvokeCallback`
     // swallows the error and surfaces a `console.warn` prefixed with
     // `[stablecoin-kits swap-kit] callback threw and was swallowed:` so a
     // kit-side closure bug stays debuggable rather than vanishing.
     safeInvokeCallback('swap-kit', ()=>{
-        onBroadcast?.(providerResult.txHash);
+        onBroadcast?.(providerResultPublic.txHash, correlationId);
     });
     const { tokenInDecimals, tokenOutDecimals } = await resolveTokenDecimals(context, resolvedParams);
     // Step 6: Compose chain identity (owned by the kit, derived from the
@@ -30405,10 +31101,10 @@ async function resolveTokenDecimals(context, resolvedParams) {
     // resolves `progress` — the provider's snapshot, or a terminal `'DONE'` for
     // a provider that omits it (a synchronous same-chain completion).
     const composedResult = {
-        ...providerResult,
+        ...providerResultPublic,
         chainIn: resolvedParams.from.chain,
         chainOut: resolvedParams.toChain ?? resolvedParams.from.chain,
-        progress: providerResult.progress ?? {
+        progress: providerResultPublic.progress ?? {
             status: 'DONE'
         }
     };
@@ -31189,7 +31885,7 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
     ESTIMATE: 'swap_estimate'
 };
 
-/** SDK name used in telemetry payloads. */ const SDK_NAME$1 = resolveKitSdkName(pkg$3.name);
+/** SDK name used in telemetry payloads. */ const SDK_NAME$2 = resolveKitSdkName(pkg$3.name);
 /**
  * A high-level class-based interface for same-chain and cross-chain token swap operations.
  *
@@ -31261,7 +31957,13 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
  */ class SwapKit {
     context;
     /** Whether error telemetry is disabled. */ disableErrorReporting;
-    /** Per-kit telemetry identity for shared helpers. */ telemetryConfig;
+    /** Per-kit telemetry identity for error reporting. */ telemetryConfig;
+    /**
+   * Per-kit telemetry identity for success/analytics events. Gated by
+   * `disableAnalytics` (independent of `disableErrorReporting`) so a developer
+   * can opt out of volume analytics without also silencing error reports —
+   * mirrors EarnKit.
+   */ analyticsTelemetryConfig;
     /**
    * Create a new SwapKit instance.
    *
@@ -31311,10 +32013,15 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
         this.context = createSwapKitContext(config);
         this.disableErrorReporting = config.disableErrorReporting === true;
         this.telemetryConfig = {
-            sdkName: SDK_NAME$1,
+            sdkName: SDK_NAME$2,
             sdkVersion: pkg$3.version,
             disabled: this.disableErrorReporting
         };
+        this.analyticsTelemetryConfig = {
+            sdkName: SDK_NAME$2,
+            sdkVersion: pkg$3.version,
+            disabled: config.disableAnalytics === true
+        };
     }
     /**
    * Estimate the output amount and fees for a swap operation.
@@ -31355,8 +32062,12 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * console.log(`Fees:`, quote.fees)
    * ```
    */ async estimate(params) {
+        const destinationChain = params.to?.chain ? resolveChainName(params.to.chain) : undefined;
         return withErrorTelemetry(async ()=>estimate(this.context, params), SWAP_EVENT_TYPES.ESTIMATE, this.telemetryConfig, {
             sourceChain: resolveChainName(params.from.chain),
+            ...destinationChain != null && {
+                destinationChain
+            },
             tokenIn: params.tokenIn,
             tokenOut: params.tokenOut
         });
@@ -31415,16 +32126,54 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * ```
    */ async swap(params) {
         let txHash;
-        return withErrorTelemetry(async ()=>swap$1(this.context, params, (h)=>{
-                txHash = h;
-            }), SWAP_EVENT_TYPES.SWAP, this.telemetryConfig, ()=>({
+        let correlationId;
+        // Shared context builder so the error resolver and the success emit stay in
+        // lockstep — a field added here reaches both call sites. Reads the per-call
+        // locals lazily, so txHash/correlationId (set during the swap) are captured
+        // whenever it is invoked.
+        // Destination chain is the primary attribution dimension for cross-chain
+        // swaps; resolved once from the (static) params. Omitted for same-chain
+        // swaps that leave `to.chain` unset (destination == source).
+        const destinationChain = params.to?.chain ? resolveChainName(params.to.chain) : undefined;
+        const buildTelemetryContext = ()=>({
                 sourceChain: resolveChainName(params.from.chain),
+                ...destinationChain != null && {
+                    destinationChain
+                },
                 tokenIn: params.tokenIn,
                 tokenOut: params.tokenOut,
                 ...txHash != null && {
                     txHash
+                },
+                ...correlationId != null && {
+                    correlationId
                 }
-            }));
+            });
+        const result = await withErrorTelemetry(async ()=>swap$1(this.context, params, (h, cId)=>{
+                txHash = h;
+                correlationId = cId;
+            }), SWAP_EVENT_TYPES.SWAP, this.telemetryConfig, buildTelemetryContext);
+        // withErrorTelemetry only emits on failure. Record the successful swap here
+        // so the backend can attribute swap volume to a developer: the client event
+        // carries the (burn) txHash + correlationId, which joins to the
+        // server-emitted event carrying entity_id. Best-effort; never throws.
+        //
+        // Emit whenever a broadcast happened, i.e. we have the source/burn txHash.
+        // For a cross-chain swap that is the source-chain burn (progress is still
+        // PENDING while the destination mint settles) — we intentionally attribute
+        // at broadcast using the burn txHash rather than tracking the destination
+        // leg, which keeps the capture simple and self-contained in swap().
+        //
+        // Guard against a terminal-failure result: the EVM provider throws on
+        // revert today, but the kit is provider-agnostic, so a provider that
+        // returns a FAILED/NOT_FOUND result without throwing must not be recorded
+        // as a successful swap. Routed through analyticsTelemetryConfig so it is
+        // gated by disableAnalytics, independent of error reporting.
+        const status = result.progress?.status;
+        if (txHash != null && status !== 'FAILED' && status !== 'NOT_FOUND') {
+            emitSuccessTelemetry(SWAP_EVENT_TYPES.SWAP, this.analyticsTelemetryConfig, buildTelemetryContext());
+        }
+        return result;
     }
     /**
    * Fetch the current status of a swap from the Stablecoin Service.
@@ -31770,6 +32519,113 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg$3.name}/${pkg$3.version}`);
 
+/**
+ * Creates a AppKit context.
+ *
+ * This function constructs a context object, initializes the actions registry
+ * used for event handlers, and merges in any custom implementations provided
+ * via params.
+ *
+ * @param params - Optional custom implementations to override defaults
+ * @returns A AppKitContext
+ *
+ * @example
+ * ```typescript
+ * // Create context with all defaults
+ * const defaultContext = createContext()
+ *
+ * // Create context with custom fee calculation
+ * const customContext = createContext({
+ *   getFee: async (type, params) => {
+ *     if (type === 'bridge') {
+ *       // Custom bridge fee logic
+ *       return await calculateBridgeFee(params)
+ *     }
+ *     // Use default for other types
+ *     return defaultFeeCalculation(type, params)
+ *   }
+ * })
+ * ```
+ */ const createContext = (params = {})=>{
+    return {
+        ...params,
+        actions: {
+            bridge: {},
+            earn: {},
+            ...params.actions
+        }
+    };
+};
+
+/**
+ * Create a BridgeKit instance with optional developer fee configuration.
+ *
+ * This utility creates a BridgeKit instance that optionally includes developer
+ * fee configuration based on the provided AppKit context. If the context
+ * provides both `getFee` and `getFeeRecipient` methods, they will be configured
+ * as developer fees in the BridgeKit instance using the `setCustomFeePolicy` method.
+ *
+ * The fee integration transforms string-based fees from the context into the
+ * format expected by BridgeKit, enabling seamless fee calculation across both kits.
+ *
+ * @param context - The AppKit context containing optional fee methods
+ * @returns A configured BridgeKit instance with or without developer fees
+ *
+ * @example
+ * ```typescript
+ * import { createBridgeKit } from '@circle-fin/app-kit/utils'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ *
+ * // Create context with fee methods
+ * const context = createContext({
+ *   getFee: async (type, params) => '1000000', // 1 USDC in micro-units
+ *   getFeeRecipient: async (type, info) => '0x742d35Cc4634C0532925a3b8D1d7'
+ * })
+ *
+ * // Create BridgeKit with developer fees
+ * const bridgeKit = createBridgeKit(context)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { createBridgeKit } from '@circle-fin/app-kit/utils'
+ * import { createContext } from '@circle-fin/app-kit/context'
+ *
+ * // Create context without fee methods
+ * const context = createContext()
+ *
+ * // Create standard BridgeKit instance
+ * const bridgeKit = createBridgeKit(context)
+ * ```
+ */ const createBridgeKit = (context)=>{
+    const getFee = context.getFee?.bind(context);
+    const getFeeRecipient = context.getFeeRecipient?.bind(context);
+    const hasBoth = typeof getFee === 'function' && typeof getFeeRecipient === 'function';
+    const kit = new BridgeKit({
+        ...context.disableErrorReporting != null && {
+            disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.headers != null && {
+            headers: context.headers
+        }
+    });
+    if (context.customFeePolicy?.bridge != null) {
+        kit.setCustomFeePolicy(context.customFeePolicy.bridge);
+    } else if (hasBoth) {
+        kit.setCustomFeePolicy({
+            calculateFee: async (params)=>{
+                const feeStr = await getFee('bridge', params);
+                return feeStr;
+            },
+            resolveFeeRecipientAddress: async (chain, params)=>await getFeeRecipient('bridge', {
+                    chain,
+                    params: params || {}
+                })
+        });
+    }
+    return kit;
+};
+
 /**
  * Create a SwapKit instance with optional developer fee configuration.
  *
@@ -31803,9 +32659,14 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
     const kit = new SwapKit({
         ...context.disableErrorReporting != null && {
             disableErrorReporting: context.disableErrorReporting
+        },
+        ...context.disableAnalytics != null && {
+            disableAnalytics: context.disableAnalytics
         }
     });
-    if (hasBoth) {
+    if (context.customFeePolicy?.swap != null) {
+        kit.setCustomFeePolicy(context.customFeePolicy.swap);
+    } else if (hasBoth) {
         kit.setCustomFeePolicy({
             computeFee: async (params)=>{
                 // Adapt provider-level params (with tokenIn/tokenOut)
@@ -31864,7 +32725,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$2 = "@circle-fin/earn-kit";
-var version$2 = "1.3.0";
+var version$2 = "1.5.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -32507,6 +33368,683 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     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]`.
+ *
+ * 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 buildBatchedEarnExecuteDescriptor(input) {
+    return createEarnExecuteDescriptor(input, assertBatchedEarnExecuteCall);
+}
+/**
+ * Type guard: narrow an adapter authorization review to an EarnKit
+ * `earn.execute` review.
+ *
+ * Use this inside an adapter `onBeforeAuthorize` hook to detect whether the
+ * request carries EarnKit semantic data before reading it, instead of
+ * comparing `review.kind` by hand. Robust against plain-JavaScript callers:
+ * accepts `unknown` and checks the shape at runtime.
+ *
+ * @param review - The `review` field from an `AuthorizationRequest`, or any
+ *   value.
+ * @returns `true` when `review` is an `earn.execute` review with the expected
+ *   `{ encoded, decoded }` data shape.
+ *
+ * @example
+ * ```typescript
+ * onBeforeAuthorize: async ({ review }) => {
+ *   if (isEarnExecuteReview(review)) {
+ *     await showEarnConfirmation(review.data.decoded.summary)
+ *   }
+ *   return 'approve'
+ * }
+ * ```
+ */ function isEarnExecuteReview(review) {
+    if (typeof review !== 'object' || review === null) {
+        return false;
+    }
+    const candidate = review;
+    if (candidate.kind !== EARN_EXECUTE_REVIEW_KIND) {
+        return false;
+    }
+    const data = candidate.data;
+    if (typeof data !== 'object' || data === null) {
+        return false;
+    }
+    const { encoded, decoded } = data;
+    return typeof encoded === 'object' && encoded !== null && typeof decoded === 'object' && decoded !== null;
+}
+
 /**
  * Prepare an earn adapter action, execute it, wait for confirmation, and
  * throw a structured revert error if the receipt status is `'reverted'`.
@@ -32533,16 +34071,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({
@@ -32567,6 +34126,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.
@@ -33863,7 +35694,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name$1 = "@circle-fin/provider-earn-service";
-var version$1 = "1.3.0";
+var version$1 = "1.4.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -33925,15 +35756,25 @@ var pkg$1 = {
  *
  * @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$1('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
@@ -33951,7 +35792,7 @@ var pkg$1 = {
             ...DEFAULT_CONFIG,
             headers: {
                 ...DEFAULT_CONFIG.headers,
-                [SDK_VERSION_HEADER]: sdkVersion,
+                ...sdkVersionHeader,
                 Authorization: `Bearer ${serviceConfig.kitKey}`
             }
         },
@@ -35491,6 +37332,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 {
@@ -35523,6 +37404,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'deposit',
+                        executionParams,
                         revertMessage: 'Earn deposit reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Deposit', result);
@@ -35654,6 +37537,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 {
@@ -35686,6 +37607,8 @@ function finishElapsedWait(lastStatus, lastError) {
                             tokenInputs,
                             signature
                         },
+                        action: 'withdraw',
+                        executionParams,
                         revertMessage: 'Earn withdraw reverted on-chain'
                     });
                     reportTransactionSuccess(transactionReportContext, 'Withdraw', result);
@@ -35765,6 +37688,8 @@ function finishElapsedWait(lastStatus, lastError) {
                         tokenInputs: [],
                         signature
                     },
+                    action: 'claimRewards',
+                    executionParams,
                     revertMessage: 'Earn claim rewards reverted on-chain'
                 }), ({ txHash })=>txHash);
             return {
@@ -36065,6 +37990,12 @@ function createUnsupportedCrossChainDepositError(chain, reason) {
     if (config.providers !== undefined && !Array.isArray(config.providers)) {
         throw createValidationFailedError$1('config.providers', config.providers, 'providers must be an array of earn providers when provided');
     }
+    if (config.disableAnalytics !== undefined && typeof config.disableAnalytics !== 'boolean') {
+        throw createValidationFailedError$1('config.disableAnalytics', config.disableAnalytics, 'disableAnalytics must be a boolean when provided');
+    }
+    if (config.disableErrorReporting !== undefined && typeof config.disableErrorReporting !== 'boolean') {
+        throw createValidationFailedError$1('config.disableErrorReporting', config.disableErrorReporting, 'disableErrorReporting must be a boolean when provided');
+    }
     const defaultProviders = getDefaultProviders$1();
     const providers = [
         ...config.providers ?? [],
@@ -36076,6 +38007,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.
  *
@@ -36417,11 +38373,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
@@ -37591,6 +39552,14 @@ function hasCrossChainDestination(params) {
     return formatClaimRewardsQuoteInfo(result);
 }
 
+/** SDK name used in telemetry payloads. */ const SDK_NAME$1 = resolveKitSdkName(pkg$2.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':
@@ -37605,6 +39574,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$1('error.cause.trace', exhaustive, 'EarnKit.retry() does not support this earn operation');
+            }
+    }
+}
 /**
  * A high-level class-based interface for DeFi lending vault operations.
  *
@@ -37663,6 +39696,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
@@ -37687,6 +39722,16 @@ function formatRetryResult(operation, result) {
    */ constructor(config = {}){
         this.context = createEarnKitContext(config);
         this.actionDispatcher = new Actionable();
+        this.telemetryConfig = {
+            sdkName: SDK_NAME$1,
+            sdkVersion: pkg$2.version,
+            disabled: config.disableErrorReporting === true
+        };
+        this.analyticsTelemetryConfig = {
+            sdkName: SDK_NAME$1,
+            sdkVersion: pkg$2.version,
+            disabled: config.disableAnalytics === true
+        };
         for (const provider of this.context.providers){
             provider.registerDispatcher(this.actionDispatcher);
         }
@@ -37747,29 +39792,36 @@ function formatRetryResult(operation, result) {
    * }
    * ```
    */ async retry(error) {
-        if (!isKitError(error)) {
-            throw createValidationFailedError$1('error', error, 'EarnKit.retry() requires a KitError thrown by a previous earn operation');
-        }
-        if (!isRetryableError$1(error)) {
-            throw createValidationFailedError$1('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$1('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$1('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$1('error', error, 'EarnKit.retry() requires a KitError thrown by a previous earn operation');
+            }
+            if (!isRetryableError$1(error)) {
+                throw createValidationFailedError$1('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$1('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$1('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.
@@ -37803,7 +39855,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.
@@ -37828,7 +39882,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.
@@ -37875,7 +39934,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.
@@ -37900,7 +39961,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.
@@ -37927,10 +39988,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$3(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$3(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.
@@ -37956,7 +40037,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.
@@ -37983,7 +40072,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.
@@ -38005,7 +40104,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.
@@ -38027,7 +40128,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.
@@ -38049,7 +40152,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)
+        });
     }
 }
 
@@ -38138,7 +40243,14 @@ registerKit(`${pkg$2.name}/${pkg$2.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;
 };
@@ -39447,7 +41559,7 @@ async function deposit$2(context, params) {
 }
 
 var name = "@circle-fin/unified-balance-kit";
-var version = "1.3.0";
+var version = "1.4.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -40788,7 +42900,8 @@ function throwNetworkMismatch(expected, actual) {
     };
 }
 /**
- * Group intents by adapter and chain for signing (Solana one-per-intent, EVM batched by adapter).
+ * Group intents for signing (Solana one-per-intent, EVM batched by adapter
+ * with every source chain retained by Gateway domain).
  *
  * @param intents - Burn intents from estimate response.
  * @param allocations - Normalized allocations used to map domain → adapter/chain.
@@ -42165,22 +44278,32 @@ const DEFAULT_GAS_FEE = parseUnits('0.1', USDC_DECIMALS);
  *
  * Single-intent sets become one burnIntent + signature; multi-intent sets become burnIntentSet + signature.
  *
+ * Sets flagged `contractSigner` carry `contractSigner: true`, which tells
+ * Gateway to validate the signature with ERC-1271 (an offchain
+ * `isValidSignature` simulation) instead of `ecrecover`. The flag is
+ * omitted for EOA signers so their payloads stay byte-identical.
+ *
  * @param signedSets - Signed intent sets (intents + signature per signer).
  * @returns Array of transfer payloads for POST /v1/transfer.
  */ function buildTransferRequestBody(signedSets) {
     return signedSets.map((set)=>{
         const firstIntent = set.intents[0];
+        const contractSigner = set.contractSigner === true ? {
+            contractSigner: true
+        } : {};
         if (set.intents.length === 1 && firstIntent) {
             return {
                 burnIntent: serializeBurnIntent(firstIntent),
-                signature: set.signature
+                signature: set.signature,
+                ...contractSigner
             };
         }
         return {
             burnIntentSet: {
                 intents: set.intents.map(serializeBurnIntent)
             },
-            signature: set.signature
+            signature: set.signature,
+            ...contractSigner
         };
     });
 }
@@ -42543,11 +44666,16 @@ const BPS_DIVISOR = 100_000n;
     return required;
 }
 
+function requireEvmChainsByDomain(group) {
+    if (group.chainsByDomain !== undefined) return group.chainsByDomain;
+    throw createValidationFailedError$1('adapterGroup.chainsByDomain', group.chainsByDomain, 'must be provided for an EVM adapter group');
+}
 /**
- * Sign each adapter group: Solana one intent per signature, EVM batch per adapter.
+ * Sign each adapter group: Solana one intent per signature, and EVM either
+ * batched for EOAs or split by source chain for ERC-1271 signers.
  *
  * @param adapterGroups - Groups from groupIntentsByAdapter.
- * @returns Promise of signed sets (intents + signature) for buildTransferRequestBody.
+ * @returns Promise of signed sets for buildTransferRequestBody.
  *
  * @example
  * ```typescript
@@ -42560,9 +44688,10 @@ const BPS_DIVISOR = 100_000n;
         if (group.chain.type === 'solana') {
             return signSolanaIntentGroup(group);
         }
-        return [
-            await signEvmIntentGroup(group)
-        ];
+        return await signEvmIntentGroup({
+            ...group,
+            chainsByDomain: requireEvmChainsByDomain(group)
+        });
     }));
     return nested.flat();
 }
@@ -43212,7 +45341,8 @@ async function runSpendNormalPath(params, destChain, useForwarder, dispatcher, s
             signedSetCount: signedSets.length,
             signatures: signedSets.map((s)=>({
                     intentCount: s.intents.length,
-                    signature: s.signature
+                    signature: s.signature,
+                    contractSigner: s.contractSigner === true
                 }))
         }
     });
@@ -45957,7 +48087,11 @@ const removeFundParamsSchema = z.object({
 // Remove Fund Operations
 // ---------------------------------------------------------------------------
 /**
- * Kick off a delayed fund removal from an account.
+ * Kick off a delayed recovery fund removal from an account.
+ *
+ * Use `initiateRemoveFund` only as a trustless fallback when the normal spend
+ * flow is unavailable. For day-to-day movement out of a Unified Balance, use
+ * `spend`.
  *
  * Validates `from` and `amount`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -45994,7 +48128,10 @@ const removeFundParamsSchema = z.object({
     return provider.initiateRemoveFund(resolved);
 }
 /**
- * Complete a fund removal once the 7-day activation period has passed.
+ * Complete a recovery fund removal once the 7-day withdrawal delay has passed.
+ *
+ * Use `removeFund` only as a trustless fallback when the normal spend flow is
+ * unavailable. For day-to-day movement out of a Unified Balance, use `spend`.
  *
  * Validates `from`, resolves the chain and token via
  * {@link resolveRemoveFundParams}, selects the matching provider, then calls
@@ -46083,13 +48220,18 @@ const removeFundParamsSchema = z.object({
 /** SDK name used in telemetry payloads. */ const SDK_NAME = resolveKitSdkName(pkg.name);
 /**
  * A high-level class-based interface for cross-chain USDC deposits,
- * spending, balance queries, delegation management, and withdrawals.
+ * spending, balance queries, delegation management, and recovery fund removals.
  *
  * UnifiedBalanceKit provides a familiar class-based API for developers who
  * prefer traditional object-oriented patterns. The class maintains an
  * internal context and provides methods that delegate to the standalone
  * operation functions exported by this package.
  *
+ * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+ * trustless recovery path for situations where the normal spend flow is
+ * unavailable, and it requires a 7-day withdrawal delay before funds can be
+ * removed.
+ *
  * @remarks
  * For functional usage, import and use the operations directly:
  * ```typescript
@@ -46310,7 +48452,11 @@ const removeFundParamsSchema = z.object({
         });
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Kick off a delayed recovery fund removal from an account.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner's adapter context, amount, and
    *   optional token type.
@@ -46324,7 +48470,12 @@ const removeFundParamsSchema = z.object({
         });
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a recovery fund removal once the 7-day withdrawal delay has
+   * passed.
+   *
+   * Use this only as a trustless fallback when the normal spend flow is
+   * unavailable. For day-to-day movement out of a Unified Balance, use
+   * `spend`.
    *
    * @param params - The account owner context matching the original
    *   fund removal initiation.
@@ -46451,6 +48602,11 @@ registerKit(`${pkg.name}/${pkg.version}`);
  * Internally holds a persistent {@link UnifiedBalanceKit} instance so that
  * event dispatchers and custom fee policies are preserved across calls.
  *
+ * Use {@link AppKitUnifiedBalance.spend} for normal movement out of a Unified
+ * Balance. {@link AppKitUnifiedBalance.removeFund} is a trustless recovery path
+ * for situations where the normal spend flow is unavailable, and it requires a
+ * 7-day withdrawal delay after {@link AppKitUnifiedBalance.initiateRemoveFund}.
+ *
  * @example
  * ```typescript
  * import { AppKit } from '@circle-fin/app-kit'
@@ -46662,7 +48818,12 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.removeDelegate(params);
     }
     /**
-   * Kick off a delayed fund removal from an account.
+   * Initiate a trustless recovery removal from an account.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Calling this method starts the 7-day withdrawal delay before the removal can
+   * be completed.
    *
    * @param params - The account owner's adapter context, amount, and token.
    * @returns Promise resolving to the initiation details.
@@ -46681,11 +48842,16 @@ registerKit(`${pkg.name}/${pkg.version}`);
         return this.kit.initiateRemoveFund(params);
     }
     /**
-   * Complete a fund removal once the activation period has passed.
+   * Complete a trustless recovery removal after the withdrawal delay.
+   *
+   * Use `spend` for normal movement out of a Unified Balance. `removeFund` is a
+   * recovery path for situations where the normal spend flow is unavailable.
+   * Both EVM and Solana removals require a 7-day withdrawal delay after
+   * `initiateRemoveFund` before funds can be removed.
    *
    * @param params - The account owner context matching the original initiation.
    * @returns Promise resolving to the fund removal details.
-   * @throws {KitError} If the activation period has not elapsed or the
+   * @throws {KitError} If the withdrawal delay has not elapsed or the
    *   on-chain transaction fails.
    *
    * @example
@@ -46802,6 +48968,33 @@ registerKit(`${pkg.name}/${pkg.version}`);
     }
 }
 
+const APP_KIT_CUSTOM_FEE_POLICY_KEYS = new Set([
+    'bridge',
+    'swap',
+    'unifiedBalance'
+]);
+function assertAppKitCustomFeePolicy(policy) {
+    if (policy === null || typeof policy !== 'object' || Array.isArray(policy)) {
+        throw createValidationFailedError$1('policy', policy, 'AppKit custom fee policy must be an object');
+    }
+    for (const key of Object.keys(policy)){
+        if (!APP_KIT_CUSTOM_FEE_POLICY_KEYS.has(key)) {
+            throw createValidationFailedError$1(`policy.${key}`, key, 'AppKit custom fee policy only supports bridge, swap, and unifiedBalance');
+        }
+    }
+    const candidate = policy;
+    if (candidate.bridge !== undefined) {
+        assertCustomFeePolicy$2(candidate.bridge);
+    }
+    if (candidate.swap !== undefined) {
+        assertCustomFeePolicy$1(candidate.swap);
+    }
+}
+function assertAppKitCustomFeePolicyScope(operation) {
+    if (typeof operation !== 'string' || !APP_KIT_CUSTOM_FEE_POLICY_KEYS.has(operation)) {
+        throw createValidationFailedError$1('operation', operation, 'AppKit custom fee policy operation must be bridge, swap, or unifiedBalance');
+    }
+}
 /**
  * A high-level SDK for stablecoin operations, including bridging, swapping, and earn.
  *
@@ -46924,18 +49117,28 @@ registerKit(`${pkg.name}/${pkg.version}`);
    * })
    * ```
    */ constructor(config = {}){
-        this.context = createContext({
-            ...config,
+        if (config.customFeePolicy !== undefined) {
+            assertAppKitCustomFeePolicy(config.customFeePolicy);
+        }
+        const unifiedBalance = new AppKitUnifiedBalance({
+            ...config.unifiedBalance,
             ...config.disableErrorReporting != null && {
                 disableErrorReporting: config.disableErrorReporting
+            },
+            ...config.disableAnalytics != null && {
+                disableAnalytics: config.disableAnalytics
             }
         });
-        this.unifiedBalance = new AppKitUnifiedBalance({
-            ...config.unifiedBalance,
+        if (config.customFeePolicy?.unifiedBalance != null) {
+            unifiedBalance.setCustomFeePolicy(config.customFeePolicy.unifiedBalance);
+        }
+        this.context = createContext({
+            ...config,
             ...config.disableErrorReporting != null && {
                 disableErrorReporting: config.disableErrorReporting
             }
         });
+        this.unifiedBalance = unifiedBalance;
         this.earn = {
             // A single implementation cannot satisfy the per-branch deposit
             // overloads, so assert the overloaded interface shape; the
@@ -47379,6 +49582,77 @@ registerKit(`${pkg.name}/${pkg.version}`);
    */ getSupportedChains(operationType) {
         return getSupportedChains$2(this.context, operationType, this.unifiedBalance);
     }
+    /**
+   * Set operation-scoped custom fee policies.
+   *
+   * Configure custom fees for only the operations that need them. Bridge and
+   * swap policies are forwarded to the underlying kits when those operations
+   * run. Unified balance policies are applied immediately to the namespaced
+   * Unified Balance Kit.
+   *
+   * @param policy - Partial custom fee policy grouped by operation.
+   * @returns Nothing.
+   * @throws \{KitError\} If `policy` or a provided operation policy is invalid.
+   *
+   * @example
+   * ```typescript
+   * kit.setCustomFeePolicy({
+   *   bridge: {
+   *     computeFee: () => '1.00',
+   *     resolveFeeRecipientAddress: () => '0x1234567890123456789012345678901234567890',
+   *   },
+   * })
+   * ```
+   */ setCustomFeePolicy(policy) {
+        assertAppKitCustomFeePolicy(policy);
+        if (policy.unifiedBalance != null) {
+            this.unifiedBalance.setCustomFeePolicy(policy.unifiedBalance);
+        }
+        this.context.customFeePolicy = {
+            ...this.context.customFeePolicy,
+            ...policy
+        };
+    }
+    /**
+   * Remove an AppKit-level custom fee policy for one operation.
+   *
+   * Bridge and swap policies are removed from AppKit's persistent context so
+   * future operations fall back to legacy fee hooks. Unified balance policies
+   * are also removed from the namespaced Unified Balance Kit.
+   *
+   * @param operation - Operation whose custom fee policy should be removed.
+   * @returns Nothing.
+   * @throws \{KitError\} If `operation` is invalid.
+   *
+   * @example
+   * ```typescript
+   * kit.removeCustomFeePolicy('bridge')
+   * ```
+   */ removeCustomFeePolicy(operation) {
+        assertAppKitCustomFeePolicyScope(operation);
+        if (operation === 'unifiedBalance') {
+            this.unifiedBalance.removeCustomFeePolicy();
+        }
+        if (this.context.customFeePolicy == null) {
+            return;
+        }
+        const currentPolicy = this.context.customFeePolicy;
+        const nextPolicy = {};
+        if (operation !== 'bridge' && currentPolicy.bridge !== undefined) {
+            nextPolicy.bridge = currentPolicy.bridge;
+        }
+        if (operation !== 'swap' && currentPolicy.swap !== undefined) {
+            nextPolicy.swap = currentPolicy.swap;
+        }
+        if (operation !== 'unifiedBalance' && currentPolicy.unifiedBalance !== undefined) {
+            nextPolicy.unifiedBalance = currentPolicy.unifiedBalance;
+        }
+        if (Object.keys(nextPolicy).length === 0) {
+            delete this.context.customFeePolicy;
+            return;
+        }
+        this.context.customFeePolicy = nextPolicy;
+    }
     on(actionOrWildCard, handler) {
         const action = actionOrWildCard;
         const typedHandler = handler;
@@ -47433,5 +49707,5 @@ registerKit(`${pkg.name}/${pkg.version}`);
     }
 }
 
-export { AppKit, BalanceError, Blockchain, BridgeChain, EarnChain, EarnError, EarnKit, InputError, KitError, NetworkError, OnchainError, RateLimitError, RpcError, ServiceError, SwapChain, TOKEN_ALIASES, TransferSpeed, UnifiedBalanceChain, anyDepositParamsSchema, claimRewardsParamsSchema, createEarnKitContext, depositParamsSchema$1 as depositParamsSchema, claimRewards$1 as earnClaimRewards, deposit$3 as earnDeposit, exploreVaults$1 as earnExploreVaults, exploreVaultsIterator$1 as earnExploreVaultsIterator, getClaimRewardsQuote$1 as earnGetClaimRewardsQuote, getCrossChainDepositStatus$1 as earnGetCrossChainDepositStatus, getCrossChainDepositStatusOutcome as earnGetCrossChainDepositStatusOutcome, getDepositQuote$1 as earnGetDepositQuote, getPosition$1 as earnGetPosition, getSupportedChains$3 as earnGetSupportedChains, getVaults$1 as earnGetVaults, getWithdrawalQuote$1 as earnGetWithdrawalQuote, waitForCrossChainDeposit$1 as earnWaitForCrossChainDeposit, withdraw$1 as earnWithdraw, exploreVaultsIteratorParamsSchema, exploreVaultsParamsSchema, getClaimRewardsQuoteParamsSchema, getCrossChainDepositStatusParamsSchema, getDepositQuoteParamsSchema, getErrorCode, getErrorMessage, getPositionParamsSchema, getTokenDecimals, getVaultsParamsSchema, getWithdrawalQuoteParamsSchema, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRateLimitError, isRetryableError$1 as isRetryableError, isRpcError, isServiceError, isTerminalCrossChainDepositStatus as isTerminalEarnCrossChainDepositStatus, isTokenAddress, isTokenAlias, isUserCancellationError, setExternalPrefix, validateToken, waitForCrossChainDepositParamsSchema, withdrawParamsSchema };
+export { AppKit, BalanceError, Blockchain, BridgeChain, EARN_EXECUTE_REVIEW_KIND, EarnChain, EarnError, EarnKit, InputError, KitError, NetworkError, OnchainError, RateLimitError, RpcError, ServiceError, SwapChain, TOKEN_ALIASES, TransferSpeed, UnifiedBalanceChain, anyDepositParamsSchema, claimRewardsParamsSchema, createEarnKitContext, depositParamsSchema$1 as depositParamsSchema, claimRewards$1 as earnClaimRewards, deposit$3 as earnDeposit, exploreVaults$1 as earnExploreVaults, exploreVaultsIterator$1 as earnExploreVaultsIterator, getClaimRewardsQuote$1 as earnGetClaimRewardsQuote, getCrossChainDepositStatus$1 as earnGetCrossChainDepositStatus, getCrossChainDepositStatusOutcome as earnGetCrossChainDepositStatusOutcome, getDepositQuote$1 as earnGetDepositQuote, getPosition$1 as earnGetPosition, getSupportedChains$3 as earnGetSupportedChains, getVaults$1 as earnGetVaults, getWithdrawalQuote$1 as earnGetWithdrawalQuote, waitForCrossChainDeposit$1 as earnWaitForCrossChainDeposit, withdraw$1 as earnWithdraw, exploreVaultsIteratorParamsSchema, exploreVaultsParamsSchema, getClaimRewardsQuoteParamsSchema, getCrossChainDepositStatusParamsSchema, getDepositQuoteParamsSchema, getErrorCode, getErrorMessage, getPositionParamsSchema, getTokenDecimals, getVaultsParamsSchema, getWithdrawalQuoteParamsSchema, isBalanceError, isEarnExecuteReview, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRateLimitError, isRetryableError$1 as isRetryableError, isRpcError, isServiceError, isTerminalCrossChainDepositStatus as isTerminalEarnCrossChainDepositStatus, isTokenAddress, isTokenAlias, isUserCancellationError, setExternalPrefix, validateToken, waitForCrossChainDepositParamsSchema, withdrawParamsSchema };
 //# sourceMappingURL=index.mjs.map