@circle-fin/app-kit 1.15.1 → 1.15.3

package/index.mjs

@@ -13600,7 +13600,7 @@ function resolveOptions(options) {
 }
 
 var name$4 = "@circle-fin/bridge-kit";
-var version$5 = "1.15.0";
+var version$5 = "1.15.1";
 var pkg$5 = {
 	name: name$4,
 	version: version$5};
@@ -14792,7 +14792,7 @@ function createBridgeParamsSchema(tokenSchema, config) {
 /**
  * `POST` — returns a server-signed fee quote for a CCTPx transfer of the
  * given `tokenId` between the named source and destination domains.
- */ const CCTPX_FEE_QUOTE_PATH = '/v1/quote/cctpx/{tokenId}/{sourceDomain}/{destinationDomain}';
+ */ const CCTPX_FEE_QUOTE_PATH = '/v2/quote/cctpx/{tokenId}/{sourceDomain}/{destinationDomain}';
 /**
  * `GET` — returns the remaining fast-burn allowance for the given
  * `tokenIds` (a comma-separated query param of bytes32 token ids). Backs
@@ -16323,7 +16323,7 @@ function createNoopLogger() {
     })
 ]);
 /**
- * Schema for `POST /v1/quote/cctpx/{tokenId}/{src}/{dst}`.
+ * Schema for `POST /v2/quote/cctpx/{tokenId}/{src}/{dst}`.
  *
  * Use {@link parseOrThrow} from `@core/utils` to validate payloads
  * against this schema.
@@ -44514,7 +44514,7 @@ registerKit(`${pkg$3.name}/${pkg$3.version}`);
 };
 
 var name$2 = "@circle-fin/earn-kit";
-var version$2 = "1.7.0";
+var version$2 = "1.8.0";
 var pkg$2 = {
 	name: name$2,
 	version: version$2};
@@ -45053,6 +45053,142 @@ const GAS_SAFETY_MULTIPLIER_DENOMINATOR = 10n;
     };
 }
 
+/**
+ * Fallback gas reserve expressed in ERC-20 deposit token base units when no
+ * quote gas fees are available. 50_000 = 0.05 USDC at the 6-decimal ERC-20
+ * USDC scale used on Arc (and the scale of `balance` / `depositAmountRaw`).
+ *
+ * @internal
+ */ const DEFAULT_GAS_RESERVE = 50_000n;
+/**
+ * Standard ERC-20 decimal precision for USDC and EURC. Both tokens use 6
+ * decimals on all EVM chains, regardless of how many decimals the native
+ * gas-token representation uses.
+ *
+ * @internal
+ */ const STABLECOIN_ERC20_DECIMALS = 6;
+/**
+ * Compute the gas reserve in ERC-20 deposit token base units.
+ *
+ * `EstimatedGas.fee` is denominated in the chain's native currency base units
+ * (e.g. 18-decimal USDC on Arc). The deposit token balance and
+ * `depositAmountRaw` are in ERC-20 token base units (e.g. 6-decimal USDC).
+ * This function converts the native fee total to the same scale so both sides
+ * of the `balance < required` comparison are commensurable.
+ *
+ * Conversion: `fee_token_units = fee_native_units / 10^(nativeDecimals - tokenDecimals)`
+ *
+ * Falls back to {@link DEFAULT_GAS_RESERVE} when:
+ * - `gasFees` is absent or empty
+ * - all fee entries have `fees: null` (estimation failed)
+ * - the converted total rounds to zero (native fee smaller than 1 token unit)
+ *
+ * @internal
+ */ function computeGasReserve(gasFees, nativeDecimals, tokenDecimals) {
+    if (gasFees === undefined || gasFees.length === 0) {
+        return DEFAULT_GAS_RESERVE;
+    }
+    let totalNative = 0n;
+    let hasNullEntry = false;
+    for (const entry of gasFees){
+        if (entry.fees === null) {
+            hasNullEntry = true;
+        } else {
+            totalNative += BigInt(entry.fees.fee);
+        }
+    }
+    const decimalDiff = nativeDecimals - tokenDecimals;
+    // Use ceiling division when reducing precision so we never under-estimate.
+    const scale = decimalDiff > 0 ? 10n ** BigInt(decimalDiff) : 1n;
+    let knownToken;
+    if (totalNative === 0n) {
+        knownToken = 0n;
+    } else if (decimalDiff > 0) {
+        knownToken = (totalNative + scale - 1n) / scale;
+    } else {
+        knownToken = totalNative * 10n ** BigInt(-decimalDiff);
+    }
+    // When any estimate is missing the true total is unknown, so reserve at
+    // least DEFAULT_GAS_RESERVE on top of whatever was already known.
+    // BigInt is not supported by Math.max, so we use an explicit comparison.
+    if (hasNullEntry) {
+        return knownToken > DEFAULT_GAS_RESERVE ? knownToken : DEFAULT_GAS_RESERVE // NOSONAR
+        ;
+    }
+    return knownToken > 0n ? knownToken : DEFAULT_GAS_RESERVE;
+}
+/**
+ * Build a symbol → ERC-20 address map from the chain's known token addresses.
+ * Used to resolve whether the native gas token corresponds to the deposit
+ * token's address.
+ *
+ * @internal
+ */ function buildSymbolAddressMap(chain) {
+    const map = new Map();
+    if (chain.usdcAddress != null) {
+        map.set('USDC', chain.usdcAddress.toLowerCase());
+    }
+    if (chain.eurcAddress != null) {
+        map.set('EURC', chain.eurcAddress.toLowerCase());
+    }
+    return map;
+}
+/**
+ * Pre-broadcast balance check for EOA wallets on chains where the native gas
+ * token and the deposit token are the same asset (e.g. Arc: USDC gas + USDC
+ * deposit).
+ *
+ * When the deposit would consume the entire balance, the adapter locks gas
+ * before `transferFrom`, causing an `ERC20: transfer amount exceeds balance`
+ * revert on-chain. This function reads the wallet balance before broadcast and
+ * throws {@link BalanceError.INSUFFICIENT_TOKEN} (code 9001) when
+ * `balance < depositAmount + gasReserve`, giving callers a clean pre-broadcast
+ * error instead of an opaque chain revert.
+ *
+ * The check is skipped when the chain's native gas currency symbol does not
+ * match the deposit token symbol (derived by address lookup). Examples of
+ * chains where the check is skipped: EURC deposit on Arc, any ETH-gas chain.
+ *
+ * Gas fees from the quote (`gasFees`) are in native-currency base units
+ * (18-decimal on Arc) and are scaled down to ERC-20 token units (6-decimal)
+ * before being added to `depositAmountRaw`.
+ *
+ * @param params - Adapter context, chain, deposit token, amount, and optional
+ *   quote gas fees.
+ * @throws {@link KitError} (code 9001) when the balance is insufficient to
+ *   cover both the deposit and the gas reserve.
+ *
+ * @internal
+ */ async function checkGasReserveForDeposit(params) {
+    const { adapter, chain, address, depositTokenAddress, depositAmountRaw, gasFees } = params;
+    const nativeSymbol = chain.nativeCurrency.symbol.toUpperCase();
+    const symbolAddressMap = buildSymbolAddressMap(chain);
+    const nativeTokenAddress = symbolAddressMap.get(nativeSymbol);
+    // Only applies when native gas currency and deposit token are the same asset.
+    if (nativeTokenAddress === undefined || depositTokenAddress.toLowerCase() !== nativeTokenAddress) {
+        return;
+    }
+    const rawBalance = await executeAdapterReadAction(adapter, 'token.balanceOf', {
+        tokenAddress: depositTokenAddress,
+        walletAddress: address
+    }, {
+        chain,
+        address
+    });
+    const balance = BigInt(String(rawBalance));
+    // Both USDC and EURC use 6 ERC-20 decimals; the check only reaches here when
+    // the deposit token is the chain's native gas asset (USDC or EURC).
+    const gasReserve = computeGasReserve(gasFees, chain.nativeCurrency.decimals, STABLECOIN_ERC20_DECIMALS);
+    const required = depositAmountRaw + gasReserve;
+    if (balance < required) {
+        throw new KitError({
+            ...BalanceError.INSUFFICIENT_TOKEN,
+            recoverability: 'FATAL',
+            message: `Insufficient ${chain.nativeCurrency.symbol} balance to cover deposit and gas. Balance: ${balance.toString()}, required: ${required.toString()} (deposit: ${depositAmountRaw.toString()} + gas reserve: ${gasReserve.toString()})`
+        });
+    }
+}
+
 /** @internal */ function isSameAddress(actual, expected) {
     return actual.toLowerCase() === expected.toLowerCase();
 }
@@ -46442,12 +46578,19 @@ const EARN_OPERATIONS = new Set([
         writable: true,
         configurable: true
     });
+    // Surface the tx hash in the message so callers can look it up without
+    // digging into cause.trace. Only applies to on-chain reverts — other errors
+    // either have no tx hash or already embed it in their message.
+    let message = base.message;
+    if (base.name === 'ONCHAIN_TRANSACTION_REVERTED' && typeof existingTrace['txHash'] === 'string' && existingTrace['txHash'] !== '') {
+        message = `${message} (txHash: ${existingTrace['txHash']})`;
+    }
     return new KitError({
         code: base.code,
         name: base.name,
         type: base.type,
         recoverability,
-        message: base.message,
+        message,
         cause: {
             trace
         }
@@ -46563,10 +46706,8 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     assetAddress: z.string(),
     lltv: z.number(),
     supplyUsd: z.number(),
-    // Optional during the expand/contract window (a backend that predates the
-    // field omits the key), mirroring the `.optional()` facets on the base
-    // schema; `null` when the product exposes no per-market allocation (V2).
-    allocationPct: z.number().nullable().optional()
+    // `null` when the product exposes no per-market allocation (V2).
+    allocationPct: z.number().nullable()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -46673,19 +46814,20 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     earnKitWarnings: z.array(z.string()).optional()
 });
 /**
- * Shared base schema: existing flat fields (kept) plus the new nested
- * facets and neutral identity. Facets are `.optional()` during the
- * transition; flip to required once the backend is confirmed emitting.
+ * Shared base schema: existing flat fields (kept as deprecated aliases) plus
+ * the nested facets. Zenith emits all facets on every response; required here
+ * so a partial emission is caught at parse time rather than surfacing as a
+ * runtime `undefined` access.
  *
  * @internal
  */ const earnBaseSchema = vaultInfoResponseSchema.extend({
-    address: z.string().optional(),
-    asOf: z.string().optional(),
-    manager: managerSchema.nullable().optional(),
-    apyProfile: apyProfileSchema.optional(),
-    fee: feeInfoSchema.optional(),
-    liquidityProfile: liquidityProfileSchema.optional(),
-    riskSignals: riskSignalsSchema.optional()
+    address: z.string(),
+    asOf: z.string(),
+    manager: managerSchema.nullable(),
+    apyProfile: apyProfileSchema,
+    fee: feeInfoSchema,
+    liquidityProfile: liquidityProfileSchema,
+    riskSignals: riskSignalsSchema
 });
 /**
  * Zod schema for the `vault` opportunity variant.
@@ -47473,7 +47615,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name$1 = "@circle-fin/provider-earn-service";
-var version$1 = "1.6.0";
+var version$1 = "1.7.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -47621,23 +47763,16 @@ var pkg$1 = {
     if (chain === undefined) {
         throw createInvalidChainError(vault.chain, 'Chain returned by the Earn Service is not supported by the SDK');
     }
-    // The nested facets are `.optional()` in the schema (a backend that predates
-    // them omits them) and are typed optional on `EarnOpportunity` to match.
-    // Convert the nested liquidity amounts when present and pass the remaining
-    // facets straight through; each absent facet stays absent rather than being
-    // asserted present by a cast.
     return {
         ...vault,
         chain,
         totalDeposits: Amount.fromJSON(totalDeposits),
         liquidity: Amount.fromJSON(liquidity),
-        ...liquidityProfile !== undefined && {
-            liquidityProfile: {
-                ...liquidityProfile,
-                totalDeposits: Amount.fromJSON(liquidityProfile.totalDeposits),
-                available: Amount.fromJSON(liquidityProfile.available),
-                totalSupply: Amount.fromJSON(liquidityProfile.totalSupply)
-            }
+        liquidityProfile: {
+            ...liquidityProfile,
+            totalDeposits: Amount.fromJSON(liquidityProfile.totalDeposits),
+            available: Amount.fromJSON(liquidityProfile.available),
+            totalSupply: Amount.fromJSON(liquidityProfile.totalSupply)
         }
     };
 }
@@ -49153,6 +49288,24 @@ function finishElapsedWait(lastStatus, lastError) {
                     amount: params.amount
                 };
             }
+            // Only EOA wallets pay native gas from their own balance — SCAs have
+            // their gas sponsored externally. Detect EOA by checking that the
+            // adapter supports readBytecode and the wallet address has no on-chain
+            // bytecode (empty code ⟹ EOA; non-empty ⟹ smart-contract account).
+            // EIP-7702-delegated addresses are treated as EOA by isContractSigner.
+            // If the adapter does not expose readBytecode (non-EVM adapter) the
+            // check is skipped conservatively.
+            if (approvalToken !== undefined && requiredAllowance > 0n && chain.type === 'evm' && isEvmAdapterLike(adapter) && !await isContractSigner(adapter, address, chain)) {
+                const sameChainParams = params;
+                await checkGasReserveForDeposit({
+                    adapter,
+                    chain,
+                    address,
+                    depositTokenAddress: approvalToken,
+                    depositAmountRaw: requiredAllowance,
+                    gasFees: sameChainParams.gasFees
+                });
+            }
             if (!options.skipApprove && approvalToken !== undefined && requiredAllowance > 0n) {
                 await this.runPhase(ctx, 'approve', 'approve', async ()=>{
                     try {
@@ -49559,7 +49712,7 @@ function finishElapsedWait(lastStatus, lastError) {
         // Gas is estimated server-side by the Earn Service and returned on the quote, so the
         // SDK no longer simulates it locally. `chainDefinition` lets the fetch fill
         // the native token symbol / blockchain on each gas entry.
-        return fetchDepositQuote({
+        const quote = await fetchDepositQuote({
             vaultAddress: params.vaultAddress,
             amount: params.amount,
             address,
@@ -49567,6 +49720,34 @@ function finishElapsedWait(lastStatus, lastError) {
             config,
             chainDefinition
         });
+        // Run the same pre-broadcast gas reserve check here so callers get an early
+        // warning at quote time — before they call deposit() and hit the real check.
+        // Only applies on stablecoin-gas chains (e.g. Arc) where the deposit token
+        // is also the native gas token, and only for EOA wallets that pay native gas
+        // from their own balance. Skips silently on all other chains and wallet types.
+        if (chainDefinition?.type === 'evm' && isEvmAdapterLike(params.from.adapter) && !await isContractSigner(params.from.adapter, address, chainDefinition)) {
+            const symbol = quote.deposit.symbol.toUpperCase();
+            let depositTokenAddress = null;
+            if (symbol === 'USDC') {
+                depositTokenAddress = chainDefinition.usdcAddress;
+            } else if (symbol === 'EURC') {
+                depositTokenAddress = chainDefinition.eurcAddress;
+            }
+            if (depositTokenAddress != null) {
+                const amountObj = Amount.parse(params.amount, {
+                    decimals: 6
+                });
+                await checkGasReserveForDeposit({
+                    adapter: params.from.adapter,
+                    chain: chainDefinition,
+                    address,
+                    depositTokenAddress,
+                    depositAmountRaw: amountObj.raw,
+                    gasFees: quote.gasFees
+                });
+            }
+        }
+        return quote;
     }
     /** {@inheritdoc} */ async getWithdrawalQuote(params) {
         const config = this.resolveConfig(params.config);
@@ -49866,21 +50047,15 @@ function formatPositionPnL(pnl) {
     // consumers keep receiving them until Contract.
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     const { totalDeposits, liquidity, liquidityProfile, ...rest } = vault;
-    // `liquidityProfile` is `.optional()` in the response schema during the
-    // expand/contract window (an old backend that predates the nested facets
-    // omits it), so only format and re-attach it when present — matching the
-    // provider-side `toVaultInfo` mapper.
     return {
         ...rest,
         totalDeposits: formatAmount$1(totalDeposits),
         liquidity: formatAmount$1(liquidity),
-        ...liquidityProfile !== undefined && {
-            liquidityProfile: {
-                ...liquidityProfile,
-                totalDeposits: formatAmount$1(liquidityProfile.totalDeposits),
-                available: formatAmount$1(liquidityProfile.available),
-                totalSupply: formatAmount$1(liquidityProfile.totalSupply)
-            }
+        liquidityProfile: {
+            ...liquidityProfile,
+            totalDeposits: formatAmount$1(liquidityProfile.totalDeposits),
+            available: formatAmount$1(liquidityProfile.available),
+            totalSupply: formatAmount$1(liquidityProfile.totalSupply)
         }
     };
 }
@@ -50366,6 +50541,49 @@ const sourceAdapterContextSchema = z.object({
     vaultAddress: vaultAddressSchema,
     config: earnConfigSchema.optional()
 });
+/**
+ * Schema for a successful gas fee entry (fees is non-null).
+ *
+ * Validates the kit shape — {@link EarnEstimatedGas} uses decimal strings for
+ * `gas`, `gasPrice`, and `fee`. Only digits are accepted so that the deposit
+ * operation can safely convert them to `bigint` before passing them to the
+ * provider's `computeGasReserve`.
+ *
+ * @internal
+ */ const earnGasFeeEstimateSuccessSchema = z.object({
+    name: z.string(),
+    token: z.string(),
+    blockchain: z.string(),
+    fees: z.object({
+        gas: z.string().regex(/^\d+$/, 'gas must be a non-negative integer string'),
+        gasPrice: z.string().regex(/^\d+$/, 'gasPrice must be a non-negative integer string'),
+        fee: z.string().regex(/^\d+$/, 'fee must be a non-negative integer string')
+    }),
+    error: z.undefined().optional()
+}).strict();
+/**
+ * Schema for a failed gas fee entry (fees is null, error is a string).
+ *
+ * @internal
+ */ const earnGasFeeEstimateFailureSchema = z.object({
+    name: z.string(),
+    token: z.string(),
+    blockchain: z.string(),
+    fees: z.null(),
+    error: z.string()
+}).strict();
+/**
+ * Schema for a single kit-level gas fee estimate entry.
+ *
+ * Rejects arbitrary inputs (null, numbers, empty objects, non-numeric fee
+ * strings) so callers receive a descriptive validation error instead of a
+ * raw `BigInt` conversion error inside `computeGasReserve`.
+ *
+ * @internal
+ */ const earnGasFeeEstimateSchema = z.union([
+    earnGasFeeEstimateSuccessSchema,
+    earnGasFeeEstimateFailureSchema
+]);
 /**
  * Validation schema for the same-chain variant of DepositParams.
  *
@@ -50378,6 +50596,7 @@ const sourceAdapterContextSchema = z.object({
     to: z.undefined().optional(),
     vaultAddress: vaultAddressSchema,
     amount: amountSchema$1,
+    gasFees: z.array(earnGasFeeEstimateSchema).optional(),
     config: earnConfigSchema.optional()
 }).strict();
 const crossChainDepositDestinationSchema = z.object({
@@ -50998,6 +51217,9 @@ async function deposit$3(context, params) {
         },
         vaultAddress: params.vaultAddress,
         amount: params.amount,
+        ...!hasExplicitDestination && params.gasFees !== undefined && {
+            gasFees: toProviderGasFees(params.gasFees)
+        },
         ...params.config !== undefined && {
             config: params.config
         }
@@ -51020,6 +51242,21 @@ async function deposit$3(context, params) {
     }
     return provider.deposit(baseParams);
 }
+function toProviderGasFees(gasFees) {
+    return gasFees.map((entry)=>{
+        if (entry.fees === null) {
+            return entry; // NOSONAR
+        }
+        return {
+            ...entry,
+            fees: {
+                ...entry.fees,
+                gas: BigInt(entry.fees.gas),
+                gasPrice: BigInt(entry.fees.gasPrice)
+            }
+        };
+    });
+}
 function hasCrossChainDestination(params) {
     // Runs before schema validation, so guard against non-object params from
     // untyped callers; assertEarnParams reports those with a structured error.
@@ -52495,10 +52732,10 @@ function readUserAgent(hostWindow) {
  * @param widgetPath - Path appended to `widgetBaseUrl`. Leading `/`
  *   is required by the URL semantics below — see remarks.
  * @param params - Additional query parameters to set on the launch URL
- *   (e.g. `destinationWallet`, `hostApp`). Entries whose value is
- *   `undefined` or empty are skipped. The widget reads these from the
- *   query string — `destinationWallet` in particular is **required** by
- *   the widget, so callers that have it must pass it here.
+ *   (e.g. the asset-scoping `chains` / `tokens` / `pairs`). Entries whose
+ *   value is `undefined` or empty are skipped. Launch URLs end up in
+ *   browser history and access logs, so never pass user identifiers
+ *   such as wallet addresses here.
  * @returns A fully-qualified launch URL.
  *
  * @remarks
@@ -52522,9 +52759,9 @@ function readUserAgent(hostWindow) {
  * @example
  * ```ts
  * composeWidgetUrl('https://onramp.arc.io', 'tok-1', '', {
- *   destinationWallet: '0xabc',
+ *   tokens: 'USDC',
  * })
- * // → 'https://onramp.arc.io/?sessionToken=tok-1&destinationWallet=0xabc'
+ * // → 'https://onramp.arc.io/?sessionToken=tok-1&tokens=USDC'
  * ```
  *
  * @internal Implementation detail shared by the server kit
@@ -52533,13 +52770,6 @@ function readUserAgent(hostWindow) {
  */ function composeWidgetUrl(widgetBaseUrl, sessionToken, widgetPath, params) {
     const url = new URL(widgetPath, widgetBaseUrl);
     url.searchParams.set('sessionToken', sessionToken);
-    if (params !== undefined) {
-        for (const [key, value] of Object.entries(params)){
-            if (typeof value === 'string' && value.length > 0) {
-                url.searchParams.set(key, value);
-            }
-        }
-    }
     return url.toString();
 }
 
@@ -52749,12 +52979,10 @@ function readUserAgent(hostWindow) {
         assertSafeWidgetUrl(session.widgetUrl, expectedOrigin);
         return session.widgetUrl;
     }
-    // Fallback path: compose from a bare session token. The widget reads
-    // the destination wallet from the URL, so forward it when the session
-    // carries one (server-minted sessions always do).
-    return composeWidgetUrl(widgetBaseUrl, session.sessionToken, ONRAMP_WIDGET_PATH, {
-        destinationWallet: typeof session.destinationWallet === 'string' ? session.destinationWallet : undefined
-    });
+    // Fallback path: compose from a bare session token. The widget reads the
+    // destination wallet from the token's `walletAddress` claim, so
+    // `session.destinationWallet` must not be added to the URL.
+    return composeWidgetUrl(widgetBaseUrl, session.sessionToken, ONRAMP_WIDGET_PATH);
 }
 
 const ALLOWED_TRANSITIONS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/app-kit",
-  "version": "1.15.1",
+  "version": "1.15.3",
   "description": "A one-stop Circle SDK solution for building stablecoin (e.g. USDC) applications, with bridging, swapping, and more on-chain operations",
   "keywords": [
     "circle",
@@ -36,11 +36,11 @@
   "module": "./index.mjs",
   "types": "./index.d.cts",
   "dependencies": {
-    "@circle-fin/onramp-kit": "1.0.1",
+    "@circle-fin/onramp-kit": "1.0.2",
     "@circle-fin/unified-balance-kit": "1.7.0",
     "@circle-fin/provider-gateway-v1": "1.5.0",
-    "@circle-fin/earn-kit": "1.7.0",
-    "@circle-fin/bridge-kit": "1.15.0",
+    "@circle-fin/earn-kit": "1.8.0",
+    "@circle-fin/bridge-kit": "1.15.1",
     "@circle-fin/swap-kit": "1.7.0",
     "@coral-xyz/anchor": "^0.31.1",
     "@noble/curves": "1.4.2",

package/server.cjs

@@ -8650,7 +8650,7 @@ const swapTokenEnumSchema = zod.z.enum([
     return kit;
 }
 
-var version = "1.0.1";
+var version = "1.0.2";
 var pkg = {
 	version: version};
 
@@ -9166,10 +9166,10 @@ function isAbortLikeError(err) {
  * @param widgetPath - Path appended to `widgetBaseUrl`. Leading `/`
  *   is required by the URL semantics below — see remarks.
  * @param params - Additional query parameters to set on the launch URL
- *   (e.g. `destinationWallet`, `hostApp`). Entries whose value is
- *   `undefined` or empty are skipped. The widget reads these from the
- *   query string — `destinationWallet` in particular is **required** by
- *   the widget, so callers that have it must pass it here.
+ *   (e.g. the asset-scoping `chains` / `tokens` / `pairs`). Entries whose
+ *   value is `undefined` or empty are skipped. Launch URLs end up in
+ *   browser history and access logs, so never pass user identifiers
+ *   such as wallet addresses here.
  * @returns A fully-qualified launch URL.
  *
  * @remarks
@@ -9193,9 +9193,9 @@ function isAbortLikeError(err) {
  * @example
  * ```ts
  * composeWidgetUrl('https://onramp.arc.io', 'tok-1', '', {
- *   destinationWallet: '0xabc',
+ *   tokens: 'USDC',
  * })
- * // → 'https://onramp.arc.io/?sessionToken=tok-1&destinationWallet=0xabc'
+ * // → 'https://onramp.arc.io/?sessionToken=tok-1&tokens=USDC'
  * ```
  *
  * @internal Implementation detail shared by the server kit
@@ -9434,17 +9434,13 @@ function isAbortLikeError(err) {
             const session = unwrapped !== null && typeof unwrapped === 'object' ? unwrapped : {};
             const sessionToken = typeof session['sessionToken'] === 'string' ? session['sessionToken'] : undefined;
             const existingWidgetUrl = typeof session['widgetUrl'] === 'string' && session['widgetUrl'].length > 0 ? session['widgetUrl'] : undefined;
-            // The widget reads the destination wallet from the launch URL
-            // (`destinationWallet` query param), NOT from the session token —
-            // the `/v1/stablecoinKits/sessions` body is anonymous. We must
-            // therefore bake it into the composed URL or the widget reports
-            // "Destination wallet is required." mid-flow. Host-app asset scoping
-            // (`assets`) rides the same launch URL as `chains`/`tokens`/`pairs`.
+            // The launch URL carries only the session token and host-app asset
+            // scoping (`chains`/`tokens`/`pairs`). The destination wallet must
+            // stay out of it: the widget reads the wallet from the signed session
+            // token's `walletAddress` claim, and a query param would only leak
+            // the address into browser history and access logs.
             const assetParams = serializeAssetSelection(params.assets);
-            const composedWidgetUrl = sessionToken === undefined ? undefined : composeWidgetUrl(widgetBaseUrl, sessionToken, ONRAMP_WIDGET_PATH, {
-                destinationWallet: params.destinationAddress,
-                ...assetParams
-            });
+            const composedWidgetUrl = sessionToken === undefined ? undefined : composeWidgetUrl(widgetBaseUrl, sessionToken, ONRAMP_WIDGET_PATH, assetParams);
             // When wallets-api returns a `widgetUrl`, asset scoping must still be
             // applied — `assets` is a display-only widget concern and is never
             // forwarded upstream, so we merge the params directly into the returned

package/server.d.cts

@@ -1785,17 +1785,17 @@ interface KitEventSubscription<M extends EventMap = KitEventMap> {
  *   embeds. Never sent back by the client; it is redeemed inside the
  *   widget origin only.
  * - `widgetUrl` — fully composed launch URL (origin + path + token +
- *   `destinationWallet`). The server kit prefers to compose this itself
+ *   asset-scoping params). The server kit prefers to compose this itself
  *   so the client kit has no exposure to the widget origin. The client
  *   still accepts a bare `sessionToken` and composes a URL locally as a
  *   fallback. `getOnrampUrl` is the single place that enforces the
  *   https-scheme / origin-pin safety checks before the URL reaches the
  *   DOM — that is a security boundary, not response validation.
  * - `destinationWallet` — the wallet that receives funds. The widget
- *   requires it as a launch query param, so the server kit echoes the
- *   `destinationAddress` it was minted with here (and bakes it into
- *   `widgetUrl`). Used by the client fallback path when it has to
- *   compose the URL from a bare `sessionToken`.
+ *   reads it from the signed session token, not the launch URL, so the
+ *   kit never adds it there. The server kit still echoes the
+ *   `destinationAddress` it was minted with here for the host's
+ *   convenience.
  * - `expiresAt` — RFC 3339 timestamp. The client refuses to launch an
  *   expired session and throws an `INPUT` `KitError` so the host can
  *   re-mint.
@@ -1819,8 +1819,8 @@ interface OnrampSession {
      */
     readonly sessionToken: string;
     /**
-     * Fully composed launch URL (origin + path + token +
-     * `destinationWallet`).
+     * Fully composed launch URL (origin + path + token + optional
+     * asset-scoping params).
      *
      * @remarks
      * The server kit prefers to compose this itself; the client falls
@@ -1833,8 +1833,9 @@ interface OnrampSession {
      *
      * @remarks
      * Echoed verbatim from the `destinationAddress` the server kit
-     * minted with. Used by the client kit's URL-composition fallback
-     * when `widgetUrl` is absent.
+     * minted with, for the host's convenience (e.g. to display it). Never
+     * added to the launch URL: the widget reads the destination wallet
+     * from the signed session token.
      */
     readonly destinationWallet?: string;
     /**