@augustdigital/sdk 8.6.0 → 8.7.0

package/lib/adapters/evm/index.d.ts

@@ -1,5 +1,5 @@
 import { type IContractWriteOptions, type INativeDepositOptions, type ApproveResult } from '../../modules/vaults/write.actions';
-import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions } from '../../types';
+import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions, ISwapRouterDepositOptions } from '../../types';
 import { type IPreviewDepositOptions, type IPreviewRedeemOptions, type IAllowanceOptions, type IBalanceOfOptions, type IMaxDepositOptions } from '../../modules/vaults/read.actions';
 import { type CompatibleSigner } from '../../core/helpers/signer';
 import type { IAddress } from '../../types';
@@ -191,6 +191,29 @@ declare class EVMAdapter {
      * @returns The transaction hash of the `depositNativeToken` call.
      */
     depositNativeViaSwapRouter(options: ISwapRouterNativeDepositOptions): Promise<string>;
+    /**
+     * Deposit into a vault through the on-chain `SwapRouter`, choosing the router
+     * path from `depositAsset` (direct deposit, native wrap, or a swap to the
+     * reference asset). The high-level, explicit counterpart to the SwapRouter
+     * branch inside {@link vaultDeposit} — the caller opts into the router
+     * deliberately, so a native-deposit vault is never accidentally swapped.
+     *
+     * Reads the vault's reference asset + decimals on-chain, resolves the swap
+     * quote and fail-closes on aggregator/whitelist drift, and sends the ERC-20
+     * approval to the SwapRouter when allowance is short.
+     *
+     * @param options - {@link ISwapRouterDepositOptions}.
+     * @returns The transaction hash of the router deposit call.
+     * @throws AugustValidationError on unsupported chain, invalid address, zero
+     *   amount, a native deposit into a non-wrapped-native vault, or quote drift.
+     * @example
+     * ```ts
+     * const hash = await augustSdk.evm.swapRouterDeposit({
+     *   chainId: 1, vault, depositAsset: USDT, amount: '100', slippageBps: 50,
+     * });
+     * ```
+     */
+    swapRouterDeposit(options: ISwapRouterDepositOptions): Promise<string>;
     /**
      * Claim assets from a matured redemption request on a dated-redemption
      * (RWA-style) vault. The `year`, `month`, `day`, and `receiverIndex` tuple

package/lib/adapters/evm/index.js

@@ -251,6 +251,32 @@ class EVMAdapter {
         const signer = await this.getSigner();
         return (0, write_actions_1.depositNativeViaSwapRouter)(signer, options);
     }
+    /**
+     * Deposit into a vault through the on-chain `SwapRouter`, choosing the router
+     * path from `depositAsset` (direct deposit, native wrap, or a swap to the
+     * reference asset). The high-level, explicit counterpart to the SwapRouter
+     * branch inside {@link vaultDeposit} — the caller opts into the router
+     * deliberately, so a native-deposit vault is never accidentally swapped.
+     *
+     * Reads the vault's reference asset + decimals on-chain, resolves the swap
+     * quote and fail-closes on aggregator/whitelist drift, and sends the ERC-20
+     * approval to the SwapRouter when allowance is short.
+     *
+     * @param options - {@link ISwapRouterDepositOptions}.
+     * @returns The transaction hash of the router deposit call.
+     * @throws AugustValidationError on unsupported chain, invalid address, zero
+     *   amount, a native deposit into a non-wrapped-native vault, or quote drift.
+     * @example
+     * ```ts
+     * const hash = await augustSdk.evm.swapRouterDeposit({
+     *   chainId: 1, vault, depositAsset: USDT, amount: '100', slippageBps: 50,
+     * });
+     * ```
+     */
+    async swapRouterDeposit(options) {
+        const signer = await this.getSigner();
+        return (0, write_actions_1.swapRouterDeposit)(signer, options);
+    }
     /**
      * Claim assets from a matured redemption request on a dated-redemption
      * (RWA-style) vault. The `year`, `month`, `day`, and `receiverIndex` tuple

package/lib/adapters/solana/vault.actions.d.ts

@@ -2,6 +2,24 @@ import { type web3 } from '@coral-xyz/anchor';
 import { type Connection, PublicKey, Transaction } from '@solana/web3.js';
 import type { ISolanaConnectionOptions } from './types';
 import type { SendTransactionOptions } from '@solana/wallet-adapter-base';
+/**
+ * Extract a human- and machine-readable reason from a thrown Solana/Anchor
+ * error.
+ *
+ * Anchor's {@link https://github.com/coral-xyz/anchor `ProgramError`} calls
+ * `super()` with no argument, so its `.message` is the empty string by
+ * construction — the real reason lives on `.msg`/`.code` (and `.toString()`).
+ * `AnchorError` puts it on `.error.errorMessage` / `.error.errorCode.number`.
+ * Reading `.message` directly (as this file used to) therefore rendered
+ * `"Solana deposit failed: "` for every recognized on-chain revert — dropping
+ * the numeric code the team needs to tell "Vault is paused" from
+ * "Insufficient amount" from an account-constraint violation.
+ *
+ * When no reason can be extracted, returns an actionable, user-facing fallback
+ * rather than an "unknown error" admission — the raw throwable is still
+ * preserved on the wrapped error's `cause` and in telemetry for diagnosis.
+ */
+export declare function describeSolanaError(e: unknown): string;
 /**
  * Deposit funds into a Solana August vault and mint share tokens.
  *

package/lib/adapters/solana/vault.actions.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeSolanaError = describeSolanaError;
 exports.handleSolanaDeposit = handleSolanaDeposit;
 exports.handleSolanaRedeem = handleSolanaRedeem;
 const anchor_1 = require("@coral-xyz/anchor");
@@ -8,6 +9,46 @@ const spl_token_1 = require("@solana/spl-token");
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
 const core_1 = require("../../core");
+/**
+ * User-facing fallback for a throwable that carries no extractable reason.
+ * Surfaces as e.g. `"Solana deposit failed: please try again"` — actionable,
+ * and without telling the user we couldn't classify the failure.
+ */
+const REASONLESS_SOLANA_ERROR = 'please try again';
+/**
+ * Extract a human- and machine-readable reason from a thrown Solana/Anchor
+ * error.
+ *
+ * Anchor's {@link https://github.com/coral-xyz/anchor `ProgramError`} calls
+ * `super()` with no argument, so its `.message` is the empty string by
+ * construction — the real reason lives on `.msg`/`.code` (and `.toString()`).
+ * `AnchorError` puts it on `.error.errorMessage` / `.error.errorCode.number`.
+ * Reading `.message` directly (as this file used to) therefore rendered
+ * `"Solana deposit failed: "` for every recognized on-chain revert — dropping
+ * the numeric code the team needs to tell "Vault is paused" from
+ * "Insufficient amount" from an account-constraint violation.
+ *
+ * When no reason can be extracted, returns an actionable, user-facing fallback
+ * rather than an "unknown error" admission — the raw throwable is still
+ * preserved on the wrapped error's `cause` and in telemetry for diagnosis.
+ */
+function describeSolanaError(e) {
+    if (!(e instanceof Error))
+        return REASONLESS_SOLANA_ERROR;
+    const anchor = e;
+    const reason = anchor.error?.errorMessage ?? anchor.msg ?? '';
+    const code = anchor.error?.errorCode?.number ?? anchor.code;
+    if (reason)
+        return code === undefined ? reason : `${reason} (code ${code})`;
+    // SendTransactionError / generic Error carry a non-empty `.message`.
+    if (e.message)
+        return e.message;
+    // Last resort: a subclass may override `toString()` (never the empty string).
+    const str = e.toString();
+    return str && str !== e.name && str !== `${e.name}: `
+        ? str
+        : REASONLESS_SOLANA_ERROR;
+}
 /**
  * Deposit funds into a Solana August vault and mint share tokens.
  *
@@ -159,7 +200,7 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
             vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
             depositAmount: depositAmountForLog,
         });
-        throw new core_1.AugustSDKError('UNKNOWN', `Solana deposit failed: ${e instanceof Error ? e.message : 'Unknown error'}`, {
+        throw new core_1.AugustSDKError('UNKNOWN', `Solana deposit failed: ${describeSolanaError(e)}`, {
             cause: e,
             context: {
                 vaultProgramId: String(vaultProgramId),
@@ -325,7 +366,7 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
             vaultAddress: vaultAddress ? String(vaultAddress) : undefined,
             redeemShares: redeemSharesForLog,
         });
-        throw new core_1.AugustSDKError('UNKNOWN', `Solana redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, {
+        throw new core_1.AugustSDKError('UNKNOWN', `Solana redeem failed: ${describeSolanaError(e)}`, {
             cause: e,
             context: {
                 vaultProgramId: String(vaultProgramId),

package/lib/core/analytics/instrumentation.js

@@ -123,15 +123,11 @@ function trackMethodCall(methodName, metrics, args) {
         // Counters: SUM(invocation) → total calls; SUM(error)/SUM(invocation) → error rate.
         sdk.setMeasurement('sdk.method.invocation', 1, 'none');
         sdk.setMeasurement('sdk.method.error', metrics.success ? 0 : 1, 'none');
-        // Update tags for filtering
+        // Only sticky-tag the last method name — useful for attributing errors that fire
+        // outside an active SDK span. sdk.category and sdk.chain are already recorded as
+        // span attributes on each call, so mutating the global scope with them here would
+        // just contaminate subsequent unrelated events with stale values.
         sdk.setTag('sdk.last_method', methodName);
-        if (metrics.category) {
-            sdk.setTag('sdk.category', metrics.category);
-        }
-        if (metrics.chainId !== undefined) {
-            sdk.setTag('sdk.chain', (0, chain_name_1.chainIdToTagValue)(metrics.chainId));
-            sdk.setTag('sdk.last_chainId', metrics.chainId.toString());
-        }
     }
     catch {
         // Silently fail - analytics should never break SDK
@@ -223,9 +219,9 @@ function trackSyncMethodCall(methodName, metrics, args) {
                 ...args,
             },
         });
-        // Counters — sync calls attach to whatever span is active on the scope.
-        sdk.setMeasurement('sdk.method.invocation', 1, 'none');
-        sdk.setMeasurement('sdk.method.error', metrics.success ? 0 : 1, 'none');
+        // Measurements omitted: sync methods have no span of their own, so setMeasurement
+        // would attach to whatever parent transaction happens to be active on the scope,
+        // overwriting its counters. The breadcrumb above already captures success/failure.
         sdk.setTag('sdk.last_sync_method', methodName);
         if (metrics.category) {
             sdk.setTag('sdk.category', metrics.category);

package/lib/core/analytics/method-taxonomy.js

@@ -26,6 +26,7 @@ exports.METHOD_CATEGORIES = {
     getLatestUnrealizedPnl: 'read.vault',
     getVaultBorrowerHealthFactor: 'read.vault',
     getYieldLastRealizedOn: 'read.vault',
+    getVaultActivity: 'read.vault',
     getVaultPositions: 'read.position',
     getVaultUserHistory: 'read.position',
     getUserHistory: 'read.position',
@@ -82,6 +83,7 @@ exports.METHOD_CATEGORIES = {
     swapAndDeposit: 'write.deposit',
     depositViaSwapRouter: 'write.deposit',
     depositNativeViaSwapRouter: 'write.deposit',
+    swapRouterDeposit: 'write.deposit',
     vaultRedeem: 'write.redeem',
     vaultRequestRedeem: 'write.redeem',
     rwaRedeemAsset: 'write.redeem',

package/lib/core/analytics/sentry.d.ts

@@ -6,7 +6,7 @@ import type { IAnalyticsConfig } from './types';
  * only refresh user identity and the cached API-key hash.
  *
  * @param config - Analytics configuration. Pass `tracesSampleRate` to
- *   override the Phase 1/2 default of `1.0`.
+ *   override the default of `0.1`.
  * @param environment - Current environment (DEV or PROD).
  * @param walletAddress - Optional wallet address for user identification.
  * @param apiKey - Optional API key (hashed for identification).

package/lib/core/analytics/sentry.js

@@ -138,7 +138,7 @@ function createSentrySink() {
  * only refresh user identity and the cached API-key hash.
  *
  * @param config - Analytics configuration. Pass `tracesSampleRate` to
- *   override the Phase 1/2 default of `1.0`.
+ *   override the default of `0.1`.
  * @param environment - Current environment (DEV or PROD).
  * @param walletAddress - Optional wallet address for user identification.
  * @param apiKey - Optional API key (hashed for identification).
@@ -214,17 +214,36 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
         const rawSampleRate = typeof config.tracesSampleRate === 'number' &&
             Number.isFinite(config.tracesSampleRate)
             ? config.tracesSampleRate
-            : 1.0;
+            : 0.1; // Phase 2 default — verified partners can opt into 1.0 explicitly
         const tracesSampleRate = Math.max(0, Math.min(1, rawSampleRate));
         sdk.init({
             dsn: constants_1.SENTRY_DSN,
-            // TODO(post-verified-partner): ramp default down to ~0.1.
             tracesSampleRate,
             enableTracing: true,
             environment: environment.toLowerCase(),
             release: `august-sdk@${getSDKVersion()}`,
             sendDefaultPii: true,
-            integrations: [sdk.captureConsoleIntegration({ levels: ['error'] })],
+            // SDK errors route through Logger.setSentrySink → captureException directly,
+            // so captureConsoleIntegration is redundant here. Omitting it also prevents
+            // consumer app console.error calls from being billed as SDK error events (the
+            // global sdk:'august-digital' tag would otherwise cause them to pass beforeSend).
+            integrations: [],
+            // Drop classes of event that are never SDK signal, as a backstop to the
+            // call-site demotions (see `logChainError` / `isUserRejectionError`).
+            // Scope is deliberately narrow: only categories that are noise in EVERY
+            // code path. Generic contract reverts (`CALL_EXCEPTION` / "missing revert
+            // data") are intentionally NOT listed — a reverted *write* tx is a real
+            // error we keep at `error` level, and only read-path reverts are demoted
+            // (surgically, at the call site).
+            ignoreErrors: [
+                // Wallet user-rejections are normal product behaviour, not an SDK fault.
+                /user rejected/i,
+                /user denied/i,
+                'ACTION_REJECTED',
+                // Local dev/test node leaking into a prod DSN: :8545 is the canonical
+                // Anvil/Hardhat port and is never a production RPC endpoint.
+                /ECONNREFUSED .*:8545/,
+            ],
             beforeSend(event) {
                 // Only send events tagged as SDK-related
                 if (event.tags?.sdk !== 'august-digital') {
@@ -233,7 +252,14 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
                 return event;
             },
             beforeSendTransaction(transaction) {
-                // Always include transactions for performance tracking
+                // Sub-sample the high-frequency network bookkeeping category (switchNetwork,
+                // updateWallet, clearWallet, setSigner) to 10% of whatever tracesSampleRate
+                // already passed — these fire on every wallet/chain update and are low signal
+                // for the partner-usage dashboard relative to read/write calls.
+                if (transaction.tags?.['sdk.category'] === 'network' &&
+                    Math.random() > 0.1) {
+                    return null;
+                }
                 return transaction;
             },
         });

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "8.6.0";
+export declare const SDK_VERSION = "8.7.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '8.6.0';
+exports.SDK_VERSION = '8.7.0';
 //# sourceMappingURL=version.js.map

package/lib/core/constants/swap-router.d.ts

@@ -9,17 +9,35 @@ import type { IAddress } from '../../types';
  */
 export declare const SWAP_ROUTER_ADDRESSES: Readonly<Record<number, IAddress>>;
 /**
- * Vault addresses registered on a `SwapRouter` via `enableVault`. The
- * presence of a vault here is the signal to route its deposits through the
- * SwapRouter rather than the legacy adapter path.
+ * Vaults whose UI **may offer the any-token SwapRouter deposit surface** —
+ * i.e. the SwapRouter is `enableVault`-ed for them on-chain.
  *
- * Entries mirror the on-chain `vaultInfo[addr].referenceAsset != 0` state of
- * the `SwapRouter` deployment. Verify against the deployed contract before
- * adding a new entry — a vault that is not registered on-chain will revert
- * with `InvalidVault` at deposit time.
+ * This is *eligibility metadata only*. It is consumed by:
+ *  - the app UI, to decide whether to render the (flag-gated) swap-router
+ *    deposit surface for a vault; and
+ *  - {@link swapRouterDeposit}, optionally, as a fail-fast eligibility check.
+ *
+ * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` is the
+ * native/multiasset/adapter path and never routes through the SwapRouter. That
+ * separation is what stops a natively-accepted asset from being silently
+ * swapped — the regression that implicit auto-routing caused. Any-token swap
+ * deposits are the explicit, opt-in job of {@link swapRouterDeposit}.
+ *
+ * Membership requires the vault to be registered on-chain
+ * (`vaultInfo[addr].referenceAsset != 0`) — an unregistered vault reverts with
+ * `InvalidVault` at deposit time. A listed vault's natively-accepted assets
+ * (for a multi-asset vault, its whole deposit-asset set) still deposit via
+ * `vaultDeposit`; only tokens OUTSIDE that set go through `swapRouterDeposit`.
  *
  * Lowercase comparison is required when checking — use
- * {@link vaultUsesSwapRouter} rather than reading this set directly.
+ * {@link isSwapRouterEligible} rather than reading this set directly.
+ */
+export declare const SWAP_ROUTER_ELIGIBLE_VAULTS: ReadonlySet<string>;
+/**
+ * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS}, and the semantics
+ * changed: this set no longer drives `vaultDeposit` auto-routing (that branch
+ * was removed) — it now only marks vaults whose UI may offer the swap-router
+ * deposit surface. Kept as an alias for one release; migrate to the new name.
  */
 export declare const VAULTS_USING_SWAP_ROUTER: ReadonlySet<string>;
 /**

package/lib/core/constants/swap-router.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ADDRESSES = void 0;
+exports.SWAP_ROUTER_DEX_AGGREGATOR = exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS = exports.SWAP_ROUTER_ADDRESSES = void 0;
 /**
  * Address of the `SwapRouter` periphery contract on each supported chain.
  *
@@ -13,26 +13,42 @@ exports.SWAP_ROUTER_ADDRESSES = {
     1: '0xAC771209FF2b71EECfF6E85a9AD01db8Ff2618B0',
 };
 /**
- * Vault addresses registered on a `SwapRouter` via `enableVault`. The
- * presence of a vault here is the signal to route its deposits through the
- * SwapRouter rather than the legacy adapter path.
+ * Vaults whose UI **may offer the any-token SwapRouter deposit surface** —
+ * i.e. the SwapRouter is `enableVault`-ed for them on-chain.
  *
- * Entries mirror the on-chain `vaultInfo[addr].referenceAsset != 0` state of
- * the `SwapRouter` deployment. Verify against the deployed contract before
- * adding a new entry — a vault that is not registered on-chain will revert
- * with `InvalidVault` at deposit time.
+ * This is *eligibility metadata only*. It is consumed by:
+ *  - the app UI, to decide whether to render the (flag-gated) swap-router
+ *    deposit surface for a vault; and
+ *  - {@link swapRouterDeposit}, optionally, as a fail-fast eligibility check.
+ *
+ * It is deliberately **NOT** read by {@link vaultDeposit}: `vaultDeposit` is the
+ * native/multiasset/adapter path and never routes through the SwapRouter. That
+ * separation is what stops a natively-accepted asset from being silently
+ * swapped — the regression that implicit auto-routing caused. Any-token swap
+ * deposits are the explicit, opt-in job of {@link swapRouterDeposit}.
+ *
+ * Membership requires the vault to be registered on-chain
+ * (`vaultInfo[addr].referenceAsset != 0`) — an unregistered vault reverts with
+ * `InvalidVault` at deposit time. A listed vault's natively-accepted assets
+ * (for a multi-asset vault, its whole deposit-asset set) still deposit via
+ * `vaultDeposit`; only tokens OUTSIDE that set go through `swapRouterDeposit`.
  *
  * Lowercase comparison is required when checking — use
- * {@link vaultUsesSwapRouter} rather than reading this set directly.
+ * {@link isSwapRouterEligible} rather than reading this set directly.
  */
-exports.VAULTS_USING_SWAP_ROUTER = new Set([
-    // Upshift Core USDC — ERC-4626 vault, reference asset USDC. Enabled on
-    // the mainnet SwapRouter at vaultType=1 (VAULT_TYPE_ERC4626).
-    '0xe9b725010a9e419412ed67d0fa5f3a5f40159d32',
-    // Sentora USD — Tokenized Vault V2, reference asset USDC. Enabled on the
-    // mainnet SwapRouter at vaultType=2 (VAULT_TYPE_TOKENIZED_VAULT_V2).
+exports.SWAP_ROUTER_ELIGIBLE_VAULTS = new Set([
+    // Sentora USD — native multi-asset Tokenized Vault V2 (reference asset
+    // USDC). Its native assets (USDC/RLUSD/PYUSD/USDT) deposit via vaultDeposit;
+    // the swap-router surface adds deposits of tokens outside that set.
     '0x74ad2f789ed583dbd141bbdafc673fe1f033718b',
 ]);
+/**
+ * @deprecated Renamed to {@link SWAP_ROUTER_ELIGIBLE_VAULTS}, and the semantics
+ * changed: this set no longer drives `vaultDeposit` auto-routing (that branch
+ * was removed) — it now only marks vaults whose UI may offer the swap-router
+ * deposit surface. Kept as an alias for one release; migrate to the new name.
+ */
+exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ELIGIBLE_VAULTS;
 /**
  * 32-byte origin codes registered on the `SwapRouter` via `addOrigin`.
  * Drives origin/referral-fee accrual. The on-chain admin must register a

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;