@circle-fin/app-kit 1.15.2 → 1.15.3

package/index.cjs

@@ -44521,7 +44521,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};
@@ -45060,6 +45060,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();
 }
@@ -46449,12 +46585,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
         }
@@ -46570,10 +46713,8 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     assetAddress: zod.z.string(),
     lltv: zod.z.number(),
     supplyUsd: zod.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: zod.z.number().nullable().optional()
+    // `null` when the product exposes no per-market allocation (V2).
+    allocationPct: zod.z.number().nullable()
 });
 /**
  * Zod schema for a Morpho vault warning in the API response.
@@ -46680,19 +46821,20 @@ const bridgeFeeTokenSchema = hexAddressSchema;
     earnKitWarnings: zod.z.array(zod.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: zod.z.string().optional(),
-    asOf: zod.z.string().optional(),
-    manager: managerSchema.nullable().optional(),
-    apyProfile: apyProfileSchema.optional(),
-    fee: feeInfoSchema.optional(),
-    liquidityProfile: liquidityProfileSchema.optional(),
-    riskSignals: riskSignalsSchema.optional()
+    address: zod.z.string(),
+    asOf: zod.z.string(),
+    manager: managerSchema.nullable(),
+    apyProfile: apyProfileSchema,
+    fee: feeInfoSchema,
+    liquidityProfile: liquidityProfileSchema,
+    riskSignals: riskSignalsSchema
 });
 /**
  * Zod schema for the `vault` opportunity variant.
@@ -47480,7 +47622,7 @@ const bridgeDepositPrepareReviewSchema = zod.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};
@@ -47628,23 +47770,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)
         }
     };
 }
@@ -49160,6 +49295,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 {
@@ -49566,7 +49719,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,
@@ -49574,6 +49727,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);
@@ -49873,21 +50054,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)
         }
     };
 }
@@ -50373,6 +50548,49 @@ const sourceAdapterContextSchema = zod.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 = zod.z.object({
+    name: zod.z.string(),
+    token: zod.z.string(),
+    blockchain: zod.z.string(),
+    fees: zod.z.object({
+        gas: zod.z.string().regex(/^\d+$/, 'gas must be a non-negative integer string'),
+        gasPrice: zod.z.string().regex(/^\d+$/, 'gasPrice must be a non-negative integer string'),
+        fee: zod.z.string().regex(/^\d+$/, 'fee must be a non-negative integer string')
+    }),
+    error: zod.z.undefined().optional()
+}).strict();
+/**
+ * Schema for a failed gas fee entry (fees is null, error is a string).
+ *
+ * @internal
+ */ const earnGasFeeEstimateFailureSchema = zod.z.object({
+    name: zod.z.string(),
+    token: zod.z.string(),
+    blockchain: zod.z.string(),
+    fees: zod.z.null(),
+    error: zod.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 = zod.z.union([
+    earnGasFeeEstimateSuccessSchema,
+    earnGasFeeEstimateFailureSchema
+]);
 /**
  * Validation schema for the same-chain variant of DepositParams.
  *
@@ -50385,6 +50603,7 @@ const sourceAdapterContextSchema = zod.z.object({
     to: zod.z.undefined().optional(),
     vaultAddress: vaultAddressSchema,
     amount: amountSchema$1,
+    gasFees: zod.z.array(earnGasFeeEstimateSchema).optional(),
     config: earnConfigSchema.optional()
 }).strict();
 const crossChainDepositDestinationSchema = zod.z.object({
@@ -51005,6 +51224,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
         }
@@ -51027,6 +51249,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.
@@ -52502,10 +52739,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
@@ -52529,9 +52766,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
@@ -52540,13 +52777,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();
 }
 
@@ -52756,12 +52986,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 = {