@circle-fin/app-kit 1.15.1 → 1.15.3

package/earn.mjs

@@ -698,6 +698,29 @@ class KitError extends Error {
         name: 'INPUT_VALIDATION_FAILED',
         type: 'INPUT'
     }};
+/**
+ * Standardized error definitions for BALANCE type errors.
+ *
+ * BALANCE errors indicate insufficient funds or allowance issues
+ * that prevent transaction execution.
+ *
+ * @example
+ * ```typescript
+ * import { BalanceError } from '@core/errors'
+ *
+ * const error = new KitError({
+ *   ...BalanceError.INSUFFICIENT_TOKEN,
+ *   recoverability: 'FATAL',
+ *   message: 'Insufficient USDC balance on Ethereum',
+ *   cause: { trace: { required: '100', available: '50' } }
+ * })
+ * ```
+ */ const BalanceError = {
+    /** Insufficient token balance for transaction */ INSUFFICIENT_TOKEN: {
+        code: 9001,
+        name: 'BALANCE_INSUFFICIENT_TOKEN',
+        type: 'BALANCE'
+    }};
 /**
  * Standardized error definitions for ONCHAIN type errors.
  *
@@ -9129,7 +9152,7 @@ const swapTokenEnumSchema = z.enum([
 }
 
 var name$3 = "@circle-fin/bridge-kit";
-var version$3 = "1.15.0";
+var version$3 = "1.15.1";
 var pkg$3 = {
 	name: name$3,
 	version: version$3};
@@ -9217,7 +9240,7 @@ const READ_ACTION_KEY_SET = new Set(READ_ACTION_KEYS);
  *
  * @internal
  */ function isReadActionKey(action) {
-    return READ_ACTION_KEY_SET.has(action);
+    return typeof action === 'string' && READ_ACTION_KEY_SET.has(action);
 }
 
 /**
@@ -12541,6 +12564,86 @@ const abiParameterSchema = z.object({
     };
 }
 
+/**
+ * EIP-7702 delegation indicator. A 7702-delegated EOA's bytecode is
+ * `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 a contract signer.
+ *
+ * Spec: https://eips.ethereum.org/EIPS/eip-7702
+ */ const EIP_7702_DELEGATION_PREFIX = '0xef0100';
+/**
+ * Determine whether `address` on `chain` signs as a contract (ERC-1271)
+ * rather than as an EOA.
+ *
+ * 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.
+ *
+ * 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 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 classify.
+ * @param chain - EVM chain where the signer lives.
+ * @returns `true` when the signer is a contract account and the transfer
+ *   request must set `contractSigner: true`; `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { isContractSigner } from '@core/adapter-evm'
+ * import { Ethereum } from '@core/chains'
+ *
+ * const useErc1271 = await isContractSigner(adapter, '0xabc...', Ethereum)
+ * ```
+ */ async function isContractSigner(adapter, address, chain) {
+    let code;
+    try {
+        code = await adapter.readBytecode(address, chain);
+    } catch (err) {
+        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 false;
+    }
+    return true;
+}
+
+/**
+ * Duck-type test for an EVM adapter that exposes `readBytecode`.
+ *
+ * Used as a structural guard at package boundaries (e.g. the Circle Wallets
+ * hybrid adapter calling into a chain adapter, or the Gateway sign path
+ * receiving an arbitrary adapter implementation) where `instanceof EvmAdapter`
+ * is unreliable because each consumer bundles its own copy of the base class.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is an object exposing a callable
+ *   `readBytecode` method, narrowed to {@link EvmAdapterLike}.
+ *
+ * @example
+ * ```typescript
+ * import { isEvmAdapterLike } from '@core/adapter-evm'
+ *
+ * if (isEvmAdapterLike(adapter)) {
+ *   const code = await adapter.readBytecode('0xabc...', chain)
+ * }
+ * ```
+ */ function isEvmAdapterLike(value) {
+    return typeof value === 'object' && value !== null && 'readBytecode' in value && typeof value.readBytecode === 'function';
+}
+
 const hexBytesSchema$1 = z.string().regex(/^0x([0-9a-fA-F]{2})*$/, {
     message: 'value must be a 0x-prefixed even-length hex string'
 }).transform((value)=>value);
@@ -14435,7 +14538,7 @@ new Set(Object.values(Blockchain));
 registerKit(`${pkg$2.name}/${pkg$2.version}`);
 
 var name$1 = "@circle-fin/earn-kit";
-var version$1 = "1.7.0";
+var version$1 = "1.8.0";
 var pkg$1 = {
 	name: name$1,
 	version: version$1};
@@ -14974,6 +15077,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();
 }
@@ -16325,12 +16564,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
         }
@@ -16446,10 +16692,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.
@@ -16556,19 +16800,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.
@@ -17356,7 +17601,7 @@ const bridgeDepositPrepareReviewSchema = z.object({
 }
 
 var name = "@circle-fin/provider-earn-service";
-var version = "1.6.0";
+var version = "1.7.0";
 var pkg = {
 	name: name,
 	version: version};
@@ -17504,23 +17749,16 @@ var pkg = {
     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)
         }
     };
 }
@@ -19026,6 +19264,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 {
@@ -19432,7 +19688,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,
@@ -19440,6 +19696,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);
@@ -19739,21 +20023,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(totalDeposits),
         liquidity: formatAmount(liquidity),
-        ...liquidityProfile !== undefined && {
-            liquidityProfile: {
-                ...liquidityProfile,
-                totalDeposits: formatAmount(liquidityProfile.totalDeposits),
-                available: formatAmount(liquidityProfile.available),
-                totalSupply: formatAmount(liquidityProfile.totalSupply)
-            }
+        liquidityProfile: {
+            ...liquidityProfile,
+            totalDeposits: formatAmount(liquidityProfile.totalDeposits),
+            available: formatAmount(liquidityProfile.available),
+            totalSupply: formatAmount(liquidityProfile.totalSupply)
         }
     };
 }
@@ -20239,6 +20517,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.
  *
@@ -20251,6 +20572,7 @@ const sourceAdapterContextSchema = z.object({
     to: z.undefined().optional(),
     vaultAddress: vaultAddressSchema,
     amount: amountSchema,
+    gasFees: z.array(earnGasFeeEstimateSchema).optional(),
     config: earnConfigSchema.optional()
 }).strict();
 const crossChainDepositDestinationSchema = z.object({
@@ -20871,6 +21193,9 @@ async function deposit$1(context, params) {
         },
         vaultAddress: params.vaultAddress,
         amount: params.amount,
+        ...!hasExplicitDestination && params.gasFees !== undefined && {
+            gasFees: toProviderGasFees(params.gasFees)
+        },
         ...params.config !== undefined && {
             config: params.config
         }
@@ -20893,6 +21218,21 @@ async function deposit$1(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.