@circle-fin/app-kit 1.10.0 → 1.12.0

package/estimateSwap.mjs

@@ -16,6 +16,17 @@
  * limitations under the License.
  */
 
+// Buffer polyfill setup - executes before any other code
+// Ensures globalThis.Buffer is available for Solana libraries
+import { Buffer } from 'buffer';
+if (typeof globalThis !== 'undefined' && typeof globalThis.Buffer === 'undefined') {
+    globalThis.Buffer = Buffer;
+}
+if (typeof window !== 'undefined' && typeof window.Buffer === 'undefined') {
+    window.Buffer = Buffer;
+}
+
+
 import { z } from 'zod';
 import 'pino';
 import { hexlify, hexZeroPad } from '@ethersproject/bytes';
@@ -27,6 +38,7 @@ import '@coral-xyz/anchor';
 import bs58 from 'bs58';
 import '@noble/curves/ed25519';
 import { formatUnits as formatUnits$1 } from '@ethersproject/units';
+import 'viem';
 import { keccak256 } from '@ethersproject/keccak256';
 
 // Import global type declarations
@@ -44,6 +56,51 @@ import { keccak256 } from '@ethersproject/keccak256';
  * }
  * ```
  */ const isNodeEnvironment = ()=>typeof process !== 'undefined' && typeof process.versions === 'object' && typeof process.versions.node === 'string';
+/**
+ * Check whether the current runtime exposes a browser DOM.
+ *
+ * @remarks
+ * This intentionally does not treat every non-Node runtime as a browser.
+ * Server-side edge runtimes such as Cloudflare Workers, Deno, and Supabase
+ * Edge Functions do not expose Node globals but can safely use server
+ * credentials. A Node.js runtime remains server-side even when a test or SSR
+ * environment provides a DOM shim.
+ *
+ * @returns `true` when running in a browser window, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { isBrowserEnvironment } from '@core/utils'
+ *
+ * if (isBrowserEnvironment()) {
+ *   throw new Error('Server-only secrets must not be used in the browser')
+ * }
+ * ```
+ */ const isBrowserEnvironment = ()=>{
+    const browserWindow = globalThis.window;
+    return !isNodeEnvironment() && browserWindow?.document !== undefined;
+};
+/**
+ * Return the SDK User-Agent request header only when running in Node.js.
+ *
+ * Browsers forbid manually setting `User-Agent`, and a custom fallback header
+ * can trigger CORS preflight. Non-Node server runtimes also omit this optional
+ * attribution header because they cannot set it reliably.
+ *
+ * @returns A User-Agent header in Node.js, or an empty object otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { getNodeUserAgentHeader } from '@core/utils'
+ *
+ * const headers = {
+ *   'Content-Type': 'application/json',
+ *   ...getNodeUserAgentHeader(),
+ * }
+ * ```
+ */ const getNodeUserAgentHeader = ()=>isNodeEnvironment() ? {
+        'User-Agent': getUserAgent()
+    } : {};
 /**
  * Detect the runtime environment and return a shortened identifier.
  *
@@ -2946,6 +3003,8 @@ class KitError extends Error {
     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 = {}));
@@ -2999,6 +3058,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";
@@ -3024,6 +3084,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) {
@@ -5572,7 +5633,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',
@@ -6437,6 +6499,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
@@ -6556,6 +6716,8 @@ var Chains = /*#__PURE__*/Object.freeze({
   WorldChainSepolia: WorldChainSepolia,
   XDC: XDC,
   XDCApothem: XDCApothem,
+  XLayer: XLayer,
+  XLayerTestnet: XLayerTestnet,
   ZKSyncEra: ZKSyncEra,
   ZKSyncEraSepolia: ZKSyncEraSepolia
 });
@@ -8021,13 +8183,12 @@ const swapTokenEnumSchema = z.enum([
         headers: {
             ...DEFAULT_CONFIG$1.headers,
             ...config.headers ?? {},
-            // In browser environments, directly setting the 'User-Agent' or similar headers is restricted and may be ignored or cause errors.
-            // This is why we use the 'X-User-Agent' header instead.
-            ...typeof window === 'undefined' ? {
-                'User-Agent': getUserAgent()
-            } : {
-                'X-User-Agent': getUserAgent()
-            }
+            // Browsers forbid setting a user-agent request header, and the custom
+            // fallback header the SDK used instead trips CORS preflight against the
+            // Circle APIs (it isn't in their `Access-Control-Allow-Headers`),
+            // blocking the request. So send the SDK user agent only in Node;
+            // browsers omit it entirely.
+            ...getNodeUserAgentHeader()
         }
     };
     let lastError;
@@ -8585,6 +8746,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain]: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
         [Blockchain.World_Chain]: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
         [Blockchain.XDC]: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
+        [Blockchain.X_Layer]: '0xB6CEceAB302E2E4948951eE7843FC24E92933061',
         [Blockchain.ZKSync_Era]: '0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4',
         // =========================================================================
         // Testnets (alphabetically sorted)
@@ -8619,6 +8781,7 @@ const swapTokenEnumSchema = z.enum([
         [Blockchain.Unichain_Sepolia]: '0x31d0220469e10c4E71834a79b1f276d740d3768F',
         [Blockchain.World_Chain_Sepolia]: '0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88',
         [Blockchain.XDC_Apothem]: '0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4',
+        [Blockchain.X_Layer_Testnet]: '0xDec90b78111Ba2fc6FC6d84d8B9ec159A2d4b9B3',
         [Blockchain.ZKSync_Sepolia]: '0xAe045DE5638162fa134807Cb558E15A3F5A7F853'
     }
 };
@@ -9528,6 +9691,7 @@ const swapTokenEnumSchema = z.enum([
     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 && {
@@ -9598,18 +9762,15 @@ const swapTokenEnumSchema = z.enum([
         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
@@ -9777,7 +9938,7 @@ const swapTokenEnumSchema = z.enum([
         // 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.
@@ -9793,7 +9954,9 @@ const swapTokenEnumSchema = z.enum([
         sdkVersion: config.sdkVersion,
         eventType,
         timestamp: new Date().toISOString(),
-        errorDetails,
+        ...errorDetails !== undefined && {
+            errorDetails
+        },
         clientContext: buildClientContext(),
         ...context?.sourceChain != null && {
             sourceChain: context.sourceChain
@@ -9809,9 +9972,45 @@ const swapTokenEnumSchema = z.enum([
         },
         ...context?.txHash != null && {
             txHash: context.txHash
+        },
+        ...context?.correlationId != null && {
+            correlationId: context.correlationId
         }
     };
 }
+/**
+ * Emit telemetry for a completed operation without affecting its caller.
+ *
+ * No-ops when `config.disabled` is `true`. Like {@link withErrorTelemetry},
+ * failures while constructing or submitting the telemetry payload are reported
+ * as a soft warning and never change a completed operation's result.
+ *
+ * @param eventType - The telemetry event type for the completed operation.
+ * @param config - Per-kit SDK identity and disabled flag.
+ * @param context - Optional chain, token, and transaction context.
+ * @returns Nothing.
+ * @throws Never — telemetry failures are reported as warnings.
+ *
+ * @example
+ * ```typescript
+ * import { emitSuccessTelemetry } from '@core/utils'
+ *
+ * emitSuccessTelemetry(
+ *   'bridge_bridge',
+ *   { sdkName: 'bridge-kit', sdkVersion: '1.0.0', disabled: false },
+ *   { sourceChain: 'Ethereum', destinationChain: 'Base', tokenIn: 'USDC' },
+ * )
+ * ```
+ */ function emitSuccessTelemetry(eventType, config, context) {
+    if (config.disabled) {
+        return;
+    }
+    try {
+        void emitAnalyticsLog(buildPayload(config, eventType, undefined, context));
+    } catch (telemetryError) {
+        warnTelemetryDrop(eventType, telemetryError);
+    }
+}
 /**
  * Wrap an async operation with error telemetry.
  *
@@ -9870,7 +10069,7 @@ const swapTokenEnumSchema = z.enum([
 }
 
 var name$2 = "@circle-fin/bridge-kit";
-var version$2 = "1.12.1";
+var version$2 = "1.13.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -9906,13 +10105,21 @@ var pkg$2 = {
     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.'
+        });
+    }
 });
 
 /**
@@ -10731,7 +10938,13 @@ var TransferSpeed;
 /**
  * The ASCII "cctp-forward" magic, hex-encoded (no `0x`), that a forward-friendly
  * hookData must start with.
- */ Buffer.from(CCTP_FORWARD_MAGIC_PREFIX, 'ascii').toString('hex');
+ *
+ * Encoded with `TextEncoder` (a browser-safe Web API) rather than `Buffer.from`
+ * so this module-level constant does not reference the Node `Buffer` global at
+ * import time. App Kit inlines this provider into its bundle without a Buffer polyfill, and a
+ * bare `Buffer` here crashes browser bundles (e.g. Vite) on load — even for apps
+ * that never touch the prepaid FORWARD path. Mirrors `buildForwardingHookData`.
+ */ Array.from(new TextEncoder().encode(CCTP_FORWARD_MAGIC_PREFIX)).map((byte)=>byte.toString(16).padStart(2, '0')).join('');
 
 /**
  * The minimum finality threshold for CCTPv2 transfers.
@@ -10765,7 +10978,7 @@ var TransferSpeed;
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/swap-kit";
-var version$1 = "1.4.0";
+var version$1 = "1.5.1";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -11598,6 +11811,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
@@ -11684,6 +11907,45 @@ getQuoteRequestBaseSchema.superRefine(requireCrossChainQuoteToAddress);
  * }
  * ```
  */ const isGetTokenRatesResponse = (obj)=>getTokenRatesResponseSchema.safeParse(obj).success;
+/**
+ * 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.
@@ -11741,6 +12003,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,
         headers: {
@@ -11895,6 +12159,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
@@ -11967,6 +12233,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,
@@ -12071,6 +12339,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,
@@ -16497,6 +16767,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,
@@ -16506,6 +16781,9 @@ async function fetchSameChainStatusSnapshot({ isCrossChainSwap, txHash, chain, a
             fromAddress: serviceParams.fromAddress,
             toAddress: serviceParams.toAddress,
             txHash,
+            ...correlationId !== undefined && {
+                correlationId
+            },
             executedTransactions,
             ...config !== undefined && {
                 config
@@ -19405,7 +19683,13 @@ async function resolveTokenDecimals(context, resolvedParams) {
  *   amountIn: '50.00'
  * })
  * ```
- */ async function swap(context, params, /** @internal */ onBroadcast) {
+ */ async function swap(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)
@@ -19425,13 +19709,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
@@ -19440,10 +19727,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'
         }
     };
@@ -20296,7 +20583,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.
    *
@@ -20350,6 +20643,11 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
             sdkVersion: pkg$1.version,
             disabled: this.disableErrorReporting
         };
+        this.analyticsTelemetryConfig = {
+            sdkName: SDK_NAME,
+            sdkVersion: pkg$1.version,
+            disabled: config.disableAnalytics === true
+        };
     }
     /**
    * Estimate the output amount and fees for a swap operation.
@@ -20390,8 +20688,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
         });
@@ -20450,16 +20752,54 @@ function resolveTokenEntry(entry, index, chain, chainDef, context) {
    * ```
    */ async swap(params) {
         let txHash;
-        return withErrorTelemetry(async ()=>swap(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(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.
@@ -20838,9 +21178,14 @@ registerKit(`${pkg$1.name}/${pkg$1.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)
@@ -20899,7 +21244,7 @@ registerKit(`${pkg$1.name}/${pkg$1.version}`);
 };
 
 var name = "@circle-fin/earn-kit";
-var version = "1.3.0";
+var version = "1.5.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -21910,11 +22255,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
@@ -22363,6 +22713,8 @@ function hasCrossChainDepositQuoteShape(params) {
     config: earnConfigSchema.optional()
 });
 
+/** SDK name used in telemetry payloads. */ resolveKitSdkName(pkg.name);
+
 // Auto-register this kit for user agent tracking
 registerKit(`${pkg.name}/${pkg.version}`);