@augustdigital/sdk 8.5.0 → 8.6.1

package/lib/core/fetcher.d.ts

@@ -14,7 +14,7 @@ export type IFetchAugustMethods = 'get' | 'post' | 'put';
 export type IFetchAugustOptions = {
     method?: IFetchAugustMethods;
     headers?: Record<string, string>;
-    data?: any;
+    data?: unknown;
     server?: keyof typeof WEBSERVER_URL;
     /** Caller-supplied AbortSignal; combined with the default timeout. */
     signal?: AbortSignal;
@@ -32,7 +32,7 @@ export type IFetchAugustOptions = {
  * call with no arguments) to clear the override and fall back to the
  * compiled-in `REQUEST_TIMEOUT_MS`.
  *
- * @param ms Positive number of milliseconds to wait before aborting, or
+ * @param ms - Positive number of milliseconds to wait before aborting, or
  *   `null` to clear.
  */
 export declare function setSdkRequestTimeout(ms?: number | null): void;
@@ -46,9 +46,9 @@ export { CACHE, getSafeCache, setSafeCache };
 /**
  * Make authenticated requests to August backend services using API key.
  * Automatically logs errors with correlation IDs for debugging.
- * @param apiKey August API key for authentication
- * @param relativeUrl Endpoint path relative to base URL
- * @param options Request configuration including method and headers
+ * @param apiKey - August API key for authentication
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
  * @returns Response object if successful
  * @throws Error with correlation ID if request fails
  */
@@ -56,8 +56,8 @@ export declare function fetchAugustWithKey(apiKey: string, relativeUrl: string,
 /**
  * Make unauthenticated requests to August public API endpoints.
  * Used for fetching vault metadata and public market data.
- * @param relativeUrl Endpoint path relative to public API base URL
- * @param options Request configuration including method and headers
+ * @param relativeUrl - Endpoint path relative to public API base URL
+ * @param options - Request configuration including method and headers
  * @returns Response object if successful
  * @throws Error with correlation ID if request fails
  */
@@ -65,9 +65,9 @@ export declare function fetchAugustPublic(relativeUrl: string, options?: IFetchA
 /**
  * Make authenticated requests using Bearer token authentication.
  * Typically used for user-specific operations requiring OAuth tokens.
- * @param bearerToken OAuth bearer token
- * @param relativeUrl Endpoint path relative to base URL
- * @param options Request configuration including method and headers
+ * @param bearerToken - OAuth bearer token
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
  * @returns Response object if successful
  * @throws Error with correlation ID if request fails
  */
@@ -80,10 +80,10 @@ export declare function isRetryableError(error: Error): boolean;
 /**
  * Wrap async operations with exponential backoff retry logic.
  * Retries on network errors with increasing delays between attempts.
- * @param fn Async function to execute with retry logic
- * @param maxRetries Maximum number of retry attempts
- * @param baseDelay Initial delay in milliseconds (doubles each retry)
- * @param shouldRetry Custom function to determine if error is retryable
+ * @param fn - Async function to execute with retry logic
+ * @param maxRetries - Maximum number of retry attempts
+ * @param baseDelay - Initial delay in milliseconds (doubles each retry)
+ * @param shouldRetry - Custom function to determine if error is retryable
  * @returns Result of successful function execution
  * @throws Last error if all retries exhausted
  */
@@ -91,17 +91,17 @@ export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number,
 /**
  * Fetch tokenized vault configurations from backend API.
  * Results are cached to reduce API calls. Optionally filter by specific vault address.
- * @param pool Optional vault address to filter results
- * @param headers Monitoring headers for request tracking
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
  * @returns Array of tokenized vault configurations
  */
 export declare function fetchTokenizedVault(pool: VaultAddress, headers?: IWSMonitorHeaders, loadSubaccounts?: boolean, loadSnapshots?: boolean): Promise<ITokenizedVault[]>;
 /**
  * Fetch tokenized vault configurations from backend API.
  * Results are cached to reduce API calls. Optionally filter by specific vault address.
- * @param pool Optional vault address to filter results
- * @param headers Monitoring headers for request tracking
- * @param loadSubaccounts Optional flag to load subaccounts and EOA operators (defaults to true on API)
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
+ * @param loadSubaccounts - Optional flag to load subaccounts and EOA operators (defaults to true on API)
  * @returns Array of tokenized vault configurations
  */
 export declare function fetchTokenizedVaults(pool?: IAddress, headers?: IWSMonitorHeaders, loadSubaccounts?: boolean, loadSnapshots?: boolean): Promise<ITokenizedVault[]>;
@@ -109,45 +109,45 @@ export declare function fetchTokenizedVaults(pool?: IAddress, headers?: IWSMonit
  * Fetch current USD price for a token symbol or vault LP token.
  * For vault LP tokens, calculates share price using totalAssets/totalSupply ratio.
  * Falls back to CoinGecko if primary source fails.
- * @param symbol Token symbol or contract address
- * @param provider Optional web3 provider for on-chain price calculations
- * @param coinGeckoKey Optional CoinGecko API key for fallback pricing
- * @param headers Monitoring headers for request tracking
+ * @param symbol - Token symbol or contract address
+ * @param provider - Optional web3 provider for on-chain price calculations
+ * @param coinGeckoKey - Optional CoinGecko API key for fallback pricing
+ * @param headers - Monitoring headers for request tracking
  * @returns Token price in USD
  */
-export declare function fetchTokenPrice(symbol: string, provider?: IContractRunner, coinGeckoKey?: string, headers?: IWSMonitorHeaders): Promise<any>;
+export declare function fetchTokenPrice(symbol: string, provider?: IContractRunner, coinGeckoKey?: string, headers?: IWSMonitorHeaders): Promise<number>;
 /**
  * Fetch token price by contract address and chain ID from August price server.
- * @param address Token contract address
- * @param chainId Network chain ID
- * @param headers Optional monitoring headers for request tracking
+ * @param address - Token contract address
+ * @param chainId - Network chain ID
+ * @param headers - Optional monitoring headers for request tracking
  * @returns Token price in USD, or 0 if not found
  */
 export declare function fetchTokenPriceByAddress(address: VaultAddress, chainId: number, headers?: IWSMonitorHeaders): Promise<number>;
 /**
  * Fetch active loans for a specific vault from backend API.
  * Results are cached per vault and chain to reduce API calls.
- * @param pool Vault address
- * @param chainId Network chain ID
- * @param headers Monitoring headers for request tracking
+ * @param pool - Vault address
+ * @param chainId - Network chain ID
+ * @param headers - Monitoring headers for request tracking
  * @returns Array of active loan objects
  */
 export declare function fetchTokenizedVaultLoans(pool: VaultAddress, chainId: number, headers?: IWSMonitorHeaders): Promise<IWSVaultLoan[]>;
 /**
  * Fetch subaccount loans for a specific tokenized vault (lending pool).
  * Retrieves all active subaccount loan data from the backend.
- * @param pool Vault address
- * @param chainId Network chain ID
- * @param headers Monitoring headers for request tracking
+ * @param pool - Vault address
+ * @param chainId - Network chain ID
+ * @param headers - Monitoring headers for request tracking
  * @returns Array of active subaccount loan objects
  */
 export declare function fetchTokenizedVaultSubaccountLoans(pool: VaultAddress, chainId: number, headers?: IWSMonitorHeaders): Promise<IWSVaultLoan[]>;
 /**
  * Fetch historical timeseries data for a specific vault.
  * Returns TVL, APY, PnL, and share price data over time.
- * @param vaultAddress Vault contract address
- * @param nDays Number of days of historical data to fetch (default 30, min 1)
- * @param headers Monitoring headers for request tracking
+ * @param vaultAddress - Vault contract address
+ * @param nDays - Number of days of historical data to fetch (default 30, min 1)
+ * @param headers - Monitoring headers for request tracking
  * @returns Historical timeseries data with date keys
  */
 export declare function fetchVaultHistoricalTimeseries(vaultAddress: IAddress, nDays?: number, headers?: IWSMonitorHeaders): Promise<IHistoricalTimeseriesResponse>;
@@ -155,9 +155,9 @@ export declare function fetchVaultHistoricalTimeseries(vaultAddress: IAddress, n
  * Execute multiple promises with retry logic and allow partial failures.
  * Unlike Promise.all, continues execution if some promises fail.
  * Failed promises return null to maintain array index alignment.
- * @param promises Array of promises to execute
- * @param maxRetries Maximum retry attempts per promise
- * @param baseDelay Initial delay for exponential backoff
+ * @param promises - Array of promises to execute
+ * @param maxRetries - Maximum retry attempts per promise
+ * @param baseDelay - Initial delay for exponential backoff
  * @returns Array of results with null for failed promises
  */
 export declare function promiseSettle<T>(promises: Promise<T>[], maxRetries?: number, baseDelay?: number): Promise<T[]>;

package/lib/core/fetcher.js

@@ -50,7 +50,7 @@ let SDK_REQUEST_TIMEOUT_OVERRIDE = null;
  * call with no arguments) to clear the override and fall back to the
  * compiled-in `REQUEST_TIMEOUT_MS`.
  *
- * @param ms Positive number of milliseconds to wait before aborting, or
+ * @param ms - Positive number of milliseconds to wait before aborting, or
  *   `null` to clear.
  */
 function setSdkRequestTimeout(ms = null) {
@@ -90,18 +90,23 @@ function buildRequestAbortSignal(options) {
         timeoutController.abort();
     }, timeoutMs);
     let signal = timeoutController.signal;
-    let relayCleanup = () => { };
+    // No-op by default; replaced with a real listener-removal closure only when
+    // the manual relay fallback path below registers an 'abort' listener.
+    let relayCleanup = () => undefined;
     if (options?.signal) {
+        // Capture in a local so the cleanup closure below keeps the non-nullable
+        // narrowing (a closure over `options.signal` would otherwise be re-widened).
+        const callerSignal = options.signal;
         if (typeof AbortSignal.any === 'function') {
-            signal = AbortSignal.any([timeoutController.signal, options.signal]);
+            signal = AbortSignal.any([timeoutController.signal, callerSignal]);
         }
-        else if (options.signal.aborted) {
+        else if (callerSignal.aborted) {
             timeoutController.abort();
         }
         else {
             const relay = () => timeoutController.abort();
-            options.signal.addEventListener('abort', relay, { once: true });
-            relayCleanup = () => options.signal.removeEventListener('abort', relay);
+            callerSignal.addEventListener('abort', relay, { once: true });
+            relayCleanup = () => callerSignal.removeEventListener('abort', relay);
         }
     }
     return {
@@ -207,9 +212,9 @@ function buildAugustUrl(server, relativeUrl) {
 /**
  * Make authenticated requests to August backend services using API key.
  * Automatically logs errors with correlation IDs for debugging.
- * @param apiKey August API key for authentication
- * @param relativeUrl Endpoint path relative to base URL
- * @param options Request configuration including method and headers
+ * @param apiKey - August API key for authentication
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
  * @returns Response object if successful
  * @throws Error with correlation ID if request fails
  */
@@ -272,8 +277,8 @@ async function fetchAugustWithKey(apiKey, relativeUrl, options) {
 /**
  * Make unauthenticated requests to August public API endpoints.
  * Used for fetching vault metadata and public market data.
- * @param relativeUrl Endpoint path relative to public API base URL
- * @param options Request configuration including method and headers
+ * @param relativeUrl - Endpoint path relative to public API base URL
+ * @param options - Request configuration including method and headers
  * @returns Response object if successful
  * @throws Error with correlation ID if request fails
  */
@@ -327,9 +332,9 @@ async function fetchAugustPublic(relativeUrl, options) {
 /**
  * Make authenticated requests using Bearer token authentication.
  * Typically used for user-specific operations requiring OAuth tokens.
- * @param bearerToken OAuth bearer token
- * @param relativeUrl Endpoint path relative to base URL
- * @param options Request configuration including method and headers
+ * @param bearerToken - OAuth bearer token
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
  * @returns Response object if successful
  * @throws Error with correlation ID if request fails
  */
@@ -398,10 +403,10 @@ function isRetryableError(error) {
 /**
  * Wrap async operations with exponential backoff retry logic.
  * Retries on network errors with increasing delays between attempts.
- * @param fn Async function to execute with retry logic
- * @param maxRetries Maximum number of retry attempts
- * @param baseDelay Initial delay in milliseconds (doubles each retry)
- * @param shouldRetry Custom function to determine if error is retryable
+ * @param fn - Async function to execute with retry logic
+ * @param maxRetries - Maximum number of retry attempts
+ * @param baseDelay - Initial delay in milliseconds (doubles each retry)
+ * @param shouldRetry - Custom function to determine if error is retryable
  * @returns Result of successful function execution
  * @throws Last error if all retries exhausted
  */
@@ -422,13 +427,15 @@ async function withRetry(fn, maxRetries = 3, baseDelay = 1000, shouldRetry = isR
             throw error;
         }
     }
-    throw lastError;
+    // Unreachable in practice: the final attempt re-throws inside the loop. This
+    // satisfies the compiler's control-flow analysis without a non-null assertion.
+    throw lastError ?? new Error('withRetry exhausted retries without an error');
 }
 /**
  * Fetch tokenized vault configurations from backend API.
  * Results are cached to reduce API calls. Optionally filter by specific vault address.
- * @param pool Optional vault address to filter results
- * @param headers Monitoring headers for request tracking
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
  * @returns Array of tokenized vault configurations
  */
 async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots) {
@@ -459,7 +466,7 @@ async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots
         }
         const queryString = params.toString();
         if (queryString) {
-            endpoint += '?' + queryString;
+            endpoint += `?${queryString}`;
         }
         const tokenizedVaultsResponse = await fetchAugustPublic(endpoint, {
             headers: headers,
@@ -477,9 +484,9 @@ async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots
 /**
  * Fetch tokenized vault configurations from backend API.
  * Results are cached to reduce API calls. Optionally filter by specific vault address.
- * @param pool Optional vault address to filter results
- * @param headers Monitoring headers for request tracking
- * @param loadSubaccounts Optional flag to load subaccounts and EOA operators (defaults to true on API)
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
+ * @param loadSubaccounts - Optional flag to load subaccounts and EOA operators (defaults to true on API)
  * @returns Array of tokenized vault configurations
  */
 async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshots) {
@@ -509,7 +516,7 @@ async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshot
         }
         const queryString = params.toString();
         if (queryString) {
-            endpoint += '?' + queryString;
+            endpoint += `?${queryString}`;
         }
         const tokenizedVaultsResponse = await fetchAugustPublic(endpoint, {
             headers: headers,
@@ -531,10 +538,10 @@ async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshot
  * Fetch current USD price for a token symbol or vault LP token.
  * For vault LP tokens, calculates share price using totalAssets/totalSupply ratio.
  * Falls back to CoinGecko if primary source fails.
- * @param symbol Token symbol or contract address
- * @param provider Optional web3 provider for on-chain price calculations
- * @param coinGeckoKey Optional CoinGecko API key for fallback pricing
- * @param headers Monitoring headers for request tracking
+ * @param symbol - Token symbol or contract address
+ * @param provider - Optional web3 provider for on-chain price calculations
+ * @param coinGeckoKey - Optional CoinGecko API key for fallback pricing
+ * @param headers - Monitoring headers for request tracking
  * @returns Token price in USD
  */
 async function fetchTokenPrice(symbol, provider, coinGeckoKey, headers) {
@@ -592,6 +599,15 @@ async function fetchTokenPrice(symbol, provider, coinGeckoKey, headers) {
     PRICE_REQUESTS.set(cacheKey, pricePromise);
     return pricePromise;
 }
+// Normalize both raw integers to the same decimal scale BEFORE dividing —
+// dividing the raw bigints first floors the ratio to ~1 and loses all
+// fractional precision. Returns 1 for an empty vault (priced 1:1).
+function normalizedSharePrice(totalAssets, totalSupply, decimals) {
+    const supply = Number((0, core_1.toNormalizedBn)(totalSupply, decimals).normalized);
+    if (!supply)
+        return 1;
+    return Number((0, core_1.toNormalizedBn)(totalAssets, decimals).normalized) / supply;
+}
 /**
  * Internal price fetching implementation.
  * This is separated to allow caching and request deduplication in the public function.
@@ -616,7 +632,7 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
             const sharePrice = await vaultContract.getSharePrice();
             return Number((0, core_1.toNormalizedBn)(sharePrice, decimals).normalized);
         }
-        catch (e) {
+        catch {
             throw new Error('failed to fetch token price for evm-2 vault');
         }
     }
@@ -640,12 +656,12 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
                 vaultContract.decimals(),
             ]);
             const decimals = Number(rawDecimals);
-            const ratio = (totalAssets || BigInt(0)) / (totalSupply || BigInt(0)) || 1;
-            return json.price * Number((0, core_1.toNormalizedBn)(ratio, decimals).normalized);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return json.price * sharePrice;
         }
         return json.price;
     }
-    catch (e) {
+    catch {
         // Fallback to CoinGecko if primary source fails
         const fallbackPrice = await (0, fetcher_1.fetchTokenPricesFromCoinGecko)(symbol, coinGeckoKey);
         if (foundVaultLpAsset && provider) {
@@ -656,8 +672,8 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
                 vaultContract.decimals(),
             ]);
             const decimals = Number(rawDecimals);
-            const ratio = (totalAssets || BigInt(0)) / (totalSupply || BigInt(0)) || 1;
-            return fallbackPrice * Number((0, core_1.toNormalizedBn)(ratio, decimals).normalized);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return fallbackPrice * sharePrice;
         }
         if (fallbackPrice) {
             return fallbackPrice;
@@ -669,9 +685,9 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
 }
 /**
  * Fetch token price by contract address and chain ID from August price server.
- * @param address Token contract address
- * @param chainId Network chain ID
- * @param headers Optional monitoring headers for request tracking
+ * @param address - Token contract address
+ * @param chainId - Network chain ID
+ * @param headers - Optional monitoring headers for request tracking
  * @returns Token price in USD, or 0 if not found
  */
 async function fetchTokenPriceByAddress(address, chainId, headers) {
@@ -703,51 +719,53 @@ async function fetchTokenPriceByAddress(address, chainId, headers) {
 /**
  * Fetch active loans for a specific vault from backend API.
  * Results are cached per vault and chain to reduce API calls.
- * @param pool Vault address
- * @param chainId Network chain ID
- * @param headers Monitoring headers for request tracking
+ * @param pool - Vault address
+ * @param chainId - Network chain ID
+ * @param headers - Monitoring headers for request tracking
  * @returns Array of active loan objects
  */
 async function fetchTokenizedVaultLoans(pool, chainId, headers) {
     const key = `loans-${chainId}-${pool}`;
     let loans;
-    if (cache_1.CACHE.get(key)) {
-        loans = cache_1.CACHE.get(key);
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
     }
     else {
         const tokenizedVaultsResponse = await fetchAugustPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.loans(pool, chainId, true), { headers: headers });
         loans = (await tokenizedVaultsResponse.json()).loans;
-        cache_1.CACHE.set(key, loans);
+        await (0, cache_1.setSafeCache)(key, loans);
     }
     return loans?.filter((l) => l.state.toLowerCase() === 'active');
 }
 /**
  * Fetch subaccount loans for a specific tokenized vault (lending pool).
  * Retrieves all active subaccount loan data from the backend.
- * @param pool Vault address
- * @param chainId Network chain ID
- * @param headers Monitoring headers for request tracking
+ * @param pool - Vault address
+ * @param chainId - Network chain ID
+ * @param headers - Monitoring headers for request tracking
  * @returns Array of active subaccount loan objects
  */
 async function fetchTokenizedVaultSubaccountLoans(pool, chainId, headers) {
     const key = `subaccount-loans-${chainId}-${pool}`;
     let loans;
-    if (cache_1.CACHE.get(key)) {
-        loans = cache_1.CACHE.get(key);
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
     }
     else {
         const tokenizedVaultsResponse = await fetchAugustPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.subaccountLoans(pool, chainId, true), { headers: headers });
         loans = (await tokenizedVaultsResponse.json()).loans;
-        cache_1.CACHE.set(key, loans);
+        await (0, cache_1.setSafeCache)(key, loans);
     }
     return loans?.filter((l) => l.state.toLowerCase() === 'active');
 }
 /**
  * Fetch historical timeseries data for a specific vault.
  * Returns TVL, APY, PnL, and share price data over time.
- * @param vaultAddress Vault contract address
- * @param nDays Number of days of historical data to fetch (default 30, min 1)
- * @param headers Monitoring headers for request tracking
+ * @param vaultAddress - Vault contract address
+ * @param nDays - Number of days of historical data to fetch (default 30, min 1)
+ * @param headers - Monitoring headers for request tracking
  * @returns Historical timeseries data with date keys
  */
 async function fetchVaultHistoricalTimeseries(vaultAddress, nDays, headers) {
@@ -768,9 +786,9 @@ async function fetchVaultHistoricalTimeseries(vaultAddress, nDays, headers) {
  * Execute multiple promises with retry logic and allow partial failures.
  * Unlike Promise.all, continues execution if some promises fail.
  * Failed promises return null to maintain array index alignment.
- * @param promises Array of promises to execute
- * @param maxRetries Maximum retry attempts per promise
- * @param baseDelay Initial delay for exponential backoff
+ * @param promises - Array of promises to execute
+ * @param maxRetries - Maximum retry attempts per promise
+ * @param baseDelay - Initial delay for exponential backoff
  * @returns Array of results with null for failed promises
  */
 async function promiseSettle(promises, maxRetries = 3, baseDelay = 1000) {

package/lib/core/helpers/adapters.d.ts

@@ -1,4 +1,4 @@
-import { IAddress, IVaultAdapterConfig } from '../../types';
+import type { IAddress, IVaultAdapterConfig } from '../../types';
 /**
  * Get adapter configuration for a vault
  */

package/lib/core/helpers/chain-error.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Is this error a wallet/user rejection of a transaction or signature request?
+ *
+ * Detects ethers v6's `ACTION_REJECTED` code, the EIP-1193 `4001`
+ * ("User rejected the request") code (top-level or nested), and the common
+ * human-readable phrasings as a fallback for providers that omit a code.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the failure was the user declining in their wallet.
+ *
+ * @example
+ * ```ts
+ * try { await vault.deposit(...); }
+ * catch (e) {
+ *   if (isUserRejectionError(e)) return; // user cancelled — not an error
+ *   throw e;
+ * }
+ * ```
+ */
+export declare function isUserRejectionError(error: unknown): boolean;
+/**
+ * Is this error a routine on-chain read revert rather than a real failure?
+ *
+ * Reading a function a contract doesn't implement, or an address that holds no
+ * (or incompatible) bytecode, reverts — a normal outcome when the SDK probes
+ * heterogeneous vaults. Matches ethers' `CALL_EXCEPTION` code and the
+ * message variants emitted by ethers and viem (`missing revert data`,
+ * `execution reverted`, `call revert exception`, and the bare `reverted`
+ * phrasing such as `the contract function "totalAssets" reverted`).
+ *
+ * Scope note: callers apply this on **read** paths only. A reverted *write*
+ * (a tx that failed on-chain) is a genuine error and is intentionally not
+ * demoted by this predicate's use in `write.actions`.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the failure is an expected/benign contract revert.
+ *
+ * @example
+ * ```ts
+ * try { return await vaultContract.maxDepositAmount(); }
+ * catch (e) {
+ *   logChainError('maxDeposit', e, isExpectedRevertError(e));
+ *   throw e;
+ * }
+ * ```
+ */
+export declare function isExpectedRevertError(error: unknown): boolean;
+/**
+ * Log a caught chain error at the severity its category warrants, without
+ * swallowing it. When `isBenign` is `true` the failure is recorded as a `warn`
+ * (a Sentry breadcrumb that rides along with the next real issue, not a billed
+ * standalone issue); otherwise it is logged at `error` (a Sentry issue). The
+ * caller is still responsible for re-throwing — this only routes telemetry.
+ *
+ * Pass the benign decision explicitly (via {@link isUserRejectionError} or
+ * {@link isExpectedRevertError}) so the call site documents *why* the demotion
+ * is safe and each path opts into only the category that applies to it.
+ *
+ * @param tag - Low-cardinality call-site label (e.g. `'deposit'`), used as the
+ *   Sentry breadcrumb/issue grouping key.
+ * @param error - The caught value, of unknown type.
+ * @param isBenign - `true` to demote to `warn`; `false` to keep at `error`.
+ * @param context - Optional structured context attached to the log entry. It is
+ *   sanitized by the logger before transport.
+ */
+export declare function logChainError(tag: string, error: unknown, isBenign: boolean, context?: Record<string, unknown>): void;