augustdigital-sdk 8.20.1

package/lib/core/helpers/chain-error.js

@@ -0,0 +1,682 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LP_TOKEN_ADDRESS_SELECTOR = void 0;
+exports.isUserRejectionError = isUserRejectionError;
+exports.isExpectedRevertError = isExpectedRevertError;
+exports.isInsufficientFundsError = isInsufficientFundsError;
+exports.isRetryableRpcError = isRetryableRpcError;
+exports.isEmptyViewResponse = isEmptyViewResponse;
+exports.retryOnTransientRpc = retryOnTransientRpc;
+exports.logChainError = logChainError;
+const logger_1 = require("../logger");
+/**
+ * Classification of caught chain/RPC/wallet errors so the SDK can decide
+ * whether a failure is worth a standalone Sentry issue or is routine, expected
+ * noise that should ride along as a breadcrumb instead.
+ *
+ * Why this exists: most of the SDK's read/write paths `catch` and re-throw, and
+ * historically logged every caught error at `error` level — which the SDK's
+ * Sentry sink turns into a billed issue (see the severity policy on
+ * `SDKSentrySink` in `core/logger`). Two large, low-signal categories dominate
+ * that volume:
+ *
+ * 1. **User-rejected transactions** — the user clicked "reject" in their wallet.
+ *    This is normal product behaviour, not an SDK fault, yet it fires on every
+ *    cancelled deposit/redeem/approve.
+ * 2. **Expected on-chain read reverts** — reading a function a vault doesn't
+ *    implement, or an address with no/incompatible bytecode, reverts. This is a
+ *    routine outcome of probing heterogeneous vaults, not a defect.
+ * 3. **Underfunded sender accounts** — the node rejects the transaction because
+ *    the sender can't cover gas (or, on rollups such as Citrea, the extra L1
+ *    data-availability fee). This is a "top up your wallet" prompt, not a bug.
+ *
+ * These predicates let call sites demote exactly those cases to `warn` while
+ * leaving genuine failures at `error`. They are intentionally dependency-free
+ * (no `ethers`/Sentry imports) so they stay cheap and safe in both browser and
+ * Node, and classify purely by inspecting the error's `code`/`message` shape.
+ *
+ * @module
+ */
+/**
+ * Best-effort message extraction from an unknown thrown value. Reads
+ * `error.message` for `Error` and error-like objects, passes strings through,
+ * and falls back to `String(error)` for everything else. Never throws.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns The error's message text (never `undefined`).
+ */
+function errorText(error) {
+    if (typeof error === 'string')
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    if (error && typeof error === 'object') {
+        const maybe = error.message;
+        if (typeof maybe === 'string')
+            return maybe;
+    }
+    return String(error);
+}
+/**
+ * Collect the `code` fields an error-like value may carry. Wallet/provider
+ * errors stash their machine-readable code in different places depending on the
+ * stack: ethers sets a top-level string `code` (e.g. `'ACTION_REJECTED'`),
+ * EIP-1193 providers use a numeric `code` (e.g. `4001`), and some wrap the
+ * original under `error`/`info.error`/`cause`. We scan the common locations so
+ * callers needn't know which library produced the error.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns Every string/number `code` found (possibly empty).
+ */
+function errorCodes(error) {
+    const codes = [];
+    if (error && typeof error === 'object') {
+        const e = error;
+        const candidates = [
+            e.code,
+            e.error?.code,
+            e.info?.error?.code,
+            e.cause?.code,
+        ];
+        for (const c of candidates) {
+            if (typeof c === 'string' || typeof c === 'number')
+                codes.push(c);
+        }
+    }
+    return codes;
+}
+/**
+ * Collect every human-readable message string an error-like value carries,
+ * across the nested locations providers stash them in.
+ *
+ * Why this is separate from {@link errorText}: ethers v6 flattens a rejected
+ * `eth_estimateGas`/`eth_call` to a generic *top-level* `message` (e.g.
+ * `"missing revert data"`) while preserving the node's original JSON-RPC error
+ * one level down at `info.error.message`. The real reason (an insufficient-funds
+ * report, say) is therefore invisible to a top-level `.message` read. We scan
+ * the top-level message plus `error.message`, `info.error.message`,
+ * `cause.message`, and `cause.info.error.message` so a caller catches the reason
+ * whether it holds the raw provider error or an SDK error that wrapped it as
+ * `cause`.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns Every non-empty message string found (possibly empty array).
+ */
+function nestedMessages(error) {
+    const out = [];
+    const push = (value) => {
+        if (typeof value === 'string' && value.length > 0)
+            out.push(value);
+    };
+    push(errorText(error));
+    if (error && typeof error === 'object') {
+        const e = error;
+        push(e.error?.message);
+        push(e.info?.error?.message);
+        push(e.cause?.message);
+        push(e.cause?.info?.error?.message);
+    }
+    return out;
+}
+/**
+ * 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;
+ * }
+ * ```
+ */
+function isUserRejectionError(error) {
+    const codes = errorCodes(error);
+    if (codes.includes('ACTION_REJECTED') || codes.includes(4001))
+        return true;
+    const msg = errorText(error).toLowerCase();
+    return (msg.includes('user rejected') ||
+        msg.includes('user denied') ||
+        msg.includes('rejected the request') ||
+        msg.includes('request rejected'));
+}
+/**
+ * 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;
+ * }
+ * ```
+ */
+function isExpectedRevertError(error) {
+    const codes = errorCodes(error);
+    if (codes.includes('CALL_EXCEPTION'))
+        return true;
+    const msg = errorText(error).toLowerCase();
+    return (msg.includes('call_exception') ||
+        msg.includes('missing revert data') ||
+        msg.includes('execution reverted') ||
+        msg.includes('call revert exception') ||
+        msg.includes('reverted'));
+}
+/**
+ * Is this error the chain node reporting that the sender can't afford the
+ * transaction's gas/fee — i.e. the account needs topping up, not a defect?
+ *
+ * This is distinct from a contract revert, and easy to misclassify. When the
+ * node rejects `eth_estimateGas` for an underfunded account, ethers v6 discards
+ * the node's reason and surfaces a generic `CALL_EXCEPTION` / `"missing revert
+ * data"` at the top level — which {@link isExpectedRevertError} matches. The
+ * real reason survives only in the nested JSON-RPC error, so this predicate
+ * scans there (via `nestedMessages`). On a write path, check this **before**
+ * {@link isExpectedRevertError}, or a genuine funds shortfall reads as a benign
+ * revert.
+ *
+ * Matching is anchored to the node's pre-execution funds-check phrasings (see
+ * `INSUFFICIENT_FUNDS_PHRASES`), each of which carries a `for <purpose>`
+ * qualifier — `insufficient funds for gas`, `insufficient funds for transfer`,
+ * `not enough funds for L1 fee` (Citrea's data-availability fee), etc. This is
+ * deliberately narrower than a bare `"insufficient funds"` substring: a
+ * *contract revert reason* that merely contains the word "funds" (e.g.
+ * `execution reverted: insufficient funds in pool`) must stay a genuine failure,
+ * not be demoted to an ACCOUNT_NOT_FUNDED "top up gas" prompt.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the failure is an unfunded/underfunded sender account.
+ *
+ * @example
+ * ```ts
+ * try { await vault.requestRedeem(...); }
+ * catch (e) {
+ *   if (isInsufficientFundsError(e))
+ *     throw new AugustValidationError(
+ *       'ACCOUNT_NOT_FUNDED',
+ *       'Add gas to continue',
+ *       { cause: e },
+ *     );
+ *   throw e;
+ * }
+ * ```
+ */
+/**
+ * The node pre-execution funds-check phrasings {@link isInsufficientFundsError}
+ * recognises, lower-cased. Each keeps the `for <purpose>` qualifier so the match
+ * is anchored to a funding rejection and can't be tripped by a contract revert
+ * reason that merely mentions "funds". `insufficient funds for gas` covers the
+ * geth/reth `"... for gas * price + value"` message; `not enough funds for l1
+ * fee` is the rollup (Citrea) data-availability-fee shortfall.
+ */
+const INSUFFICIENT_FUNDS_PHRASES = [
+    'insufficient funds for gas',
+    'insufficient funds for transfer',
+    'insufficient funds for intrinsic transaction cost',
+    'not enough funds for l1 fee',
+];
+function isInsufficientFundsError(error) {
+    return nestedMessages(error).some((raw) => {
+        const msg = raw.toLowerCase();
+        return INSUFFICIENT_FUNDS_PHRASES.some((phrase) => msg.includes(phrase));
+    });
+}
+/**
+ * Collect the HTTP status codes an error-like value may carry. Transport
+ * failures that reach us through ethers' `FetchRequest` keep the upstream
+ * status on the error (`status`), on the wrapped fetch response
+ * (`info.status` / `response.status`), or on a `statusCode` alias depending on
+ * which layer produced it. We scan all of them so a caller needn't know.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns Every numeric status found (possibly empty).
+ */
+function errorStatuses(error) {
+    const out = [];
+    const push = (value) => {
+        if (typeof value === 'number' && Number.isFinite(value))
+            out.push(value);
+    };
+    if (error && typeof error === 'object') {
+        const e = error;
+        push(e.status);
+        push(e.statusCode);
+        push(e.info?.status);
+        push(e.info?.statusCode);
+        push(e.response?.status);
+        push(e.response?.statusCode);
+    }
+    return out;
+}
+/**
+ * Does this error carry evidence that the EVM actually executed and reverted?
+ *
+ * Used as a **veto** by {@link isRetryableRpcError}: nodes reuse the generic
+ * JSON-RPC codes (`-32603`, `-32000`) for genuine execution reverts as well as
+ * for internal/transport faults, so a positive transport match must never win
+ * over a real revert. Evidence of real execution is:
+ *
+ * - a `CALL_EXCEPTION` that carries non-empty revert `data` (the ABI-encoded
+ *   custom error / `Error(string)` payload),
+ * - an `execution reverted` / `call revert exception` message anywhere in the
+ *   nested error chain,
+ * - an attached receipt with `status === 0` (the tx mined and failed).
+ *
+ * Note that a bare `CALL_EXCEPTION` with **no** revert data (ethers' `missing
+ * revert data`) is deliberately *not* evidence — see {@link isRetryableRpcError}.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the error proves on-chain execution reverted.
+ */
+function hasRevertEvidence(error) {
+    if (error && typeof error === 'object') {
+        const e = error;
+        const codes = errorCodes(error);
+        if (codes.includes('CALL_EXCEPTION') &&
+            typeof e.data === 'string' &&
+            e.data.length > 2) {
+            return true;
+        }
+        if (e.receipt?.status === 0)
+            return true;
+    }
+    return nestedMessages(error).some((raw) => {
+        const msg = raw.toLowerCase();
+        return (msg.includes('execution reverted') ||
+            msg.includes('call revert exception'));
+    });
+}
+/**
+ * JSON-RPC error codes that indicate the *node or its transport* failed, not
+ * that the EVM rejected the call. `-32603` is the spec's "Internal error" and
+ * `-32000` the de-facto "Server error" both Alchemy and Infura emit for
+ * transient upstream faults (including while serving
+ * `eth_getTransactionReceipt` for a freshly broadcast tx).
+ */
+const RETRYABLE_RPC_CODES = [
+    -32603,
+    -32000,
+    'NETWORK_ERROR',
+    'SERVER_ERROR',
+    'TIMEOUT',
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+];
+/**
+ * Message fragments (lower-cased) that identify a transient transport failure.
+ *
+ * `could not coalesce error` is ethers v6's catch-all when it cannot map a
+ * node's JSON-RPC payload onto a typed error — in practice this is what a
+ * flaky provider looks like from inside `tx.wait()`. `eth_gettransactionreceipt`
+ * is included because a failure *naming that method* is by definition a receipt
+ * poll, which is safe to repeat: the transaction is already broadcast and
+ * polling is idempotent.
+ *
+ * `missing revert data` is deliberately **absent**. It is a `CALL_EXCEPTION`,
+ * not a transport frame, and {@link isExpectedRevertError} already treats it as
+ * a revert — having this predicate disagree would make the two classifiers
+ * contradict each other. The narrow subset of `missing revert data` that really
+ * is a transport artefact (an empty response to an argument-free view call) has
+ * its own predicate: {@link isEmptyViewResponse}.
+ */
+const RETRYABLE_RPC_PHRASES = [
+    'could not coalesce error',
+    'eth_gettransactionreceipt',
+    'timeout',
+    'timed out',
+    'etimedout',
+    'econnreset',
+    'econnrefused',
+    'enotfound',
+    'socket hang up',
+    'network error',
+    'network request failed',
+    'failed to fetch',
+    'fetch failed',
+    'load failed',
+    'connection closed',
+    'connection reset',
+    'too many requests',
+    'rate limit',
+    'service unavailable',
+    'bad gateway',
+    'gateway timeout',
+    'internal server error',
+    'internal error',
+    'server error',
+];
+/**
+ * Is this error a transient RPC **transport** failure that is safe to retry,
+ * rather than a decision the chain made?
+ *
+ * Why this exists: the SDK's write paths poll `eth_getTransactionReceipt` to
+ * confirm a broadcast transaction. When the provider hiccups mid-poll, ethers
+ * surfaces `could not coalesce error (error={ "code": -32603, … "method":
+ * "eth_getTransactionReceipt" … })`. Historically that propagated out of
+ * `safeWaitForTx` and the SDK reported the write as **failed** — even though
+ * the transaction was broadcast, its hash was known, and it mined fine. Users
+ * then retried and hit `ERC20InsufficientBalance` because the first attempt had
+ * in fact succeeded. Classifying the failure as transport-level lets callers
+ * re-poll instead of lying to the user.
+ *
+ * Matches, in order of precedence:
+ * 1. **Veto** — anything with revert evidence ({@link hasRevertEvidence}:
+ *    `CALL_EXCEPTION` carrying revert `data`, an `execution reverted` message,
+ *    or an attached `receipt.status === 0`) returns `false`. Nodes reuse
+ *    `-32603`/`-32000` for real reverts, so the veto must come first.
+ * 2. JSON-RPC / ethers transport codes — see `RETRYABLE_RPC_CODES`.
+ * 3. HTTP `429` and any `5xx` carried on the error.
+ * 4. Transport message fragments — see `RETRYABLE_RPC_PHRASES`.
+ *
+ * Retrying is only safe for **idempotent** work: re-reading an immutable value
+ * (`decimals()`) or re-polling a receipt for a hash that is already on the
+ * wire. Never use this to re-send a transaction.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns `true` when the failure is a transient transport fault worth
+ *   retrying with backoff; `false` for chain-level decisions (reverts) and for
+ *   anything unrecognised — the safe default is to surface the error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   return await provider.waitForTransaction(hash, 1, 120_000);
+ * } catch (e) {
+ *   if (!isRetryableRpcError(e)) throw e; // real revert — surface it
+ *   await sleep(250);
+ *   return await provider.waitForTransaction(hash, 1, 120_000);
+ * }
+ * ```
+ */
+function isRetryableRpcError(error) {
+    if (error === null || error === undefined)
+        return false;
+    // A chain-level decision is never a transport fault. Check first: nodes
+    // reuse -32603/-32000 for genuine execution reverts.
+    if (hasRevertEvidence(error))
+        return false;
+    const codes = errorCodes(error);
+    if (codes.some((code) => RETRYABLE_RPC_CODES.includes(code)))
+        return true;
+    // 429 (rate limited) and any 5xx are upstream faults, not our request being
+    // wrong — 4xx other than 429 means retrying would fail identically.
+    if (errorStatuses(error).some((status) => status === 429 || (status >= 500 && status < 600))) {
+        return true;
+    }
+    return nestedMessages(error).some((raw) => {
+        const msg = raw.toLowerCase();
+        return RETRYABLE_RPC_PHRASES.some((phrase) => msg.includes(phrase));
+    });
+}
+/**
+ * `lpTokenAddress()` — `keccak256("lpTokenAddress()")[0..4]`. The August `evm-2`
+ * tokenized vault's receipt-token getter, exported so the readers that invoke it
+ * can scope {@link isEmptyViewResponse} to exactly this call instead of
+ * duplicating the literal.
+ */
+exports.LP_TOKEN_ADDRESS_SELECTOR = '0xf5ae497a';
+/**
+ * Four-byte selectors for the argument-free view functions that a correctly
+ * addressed contract **cannot** legitimately revert on. Each is
+ * `keccak256(signature)[0..4]`.
+ *
+ * These are the only calls for which an empty RPC response is unambiguously a
+ * provider artefact rather than a contract decision — the metadata they return
+ * is fixed at deployment and takes no arguments, so there is no input that
+ * could make them fail.
+ *
+ * **Caveat for `lpTokenAddress()`.** The four ERC-20 entries hold that property
+ * absolutely: any deployed, conforming token implements them. `lpTokenAddress()`
+ * holds it only *given correct routing* — the function exists on `evm-2` vaults
+ * and nowhere else, so a vault wrongly routed into the `evm-2` branch returns
+ * empty returndata **deterministically**, producing a byte-identical error to a
+ * provider blip. That ambiguity is resolved not by this predicate but by the
+ * caller: every reader that retries on this selector is bounded (3 attempts) and
+ * rethrows the original error once they are spent, so a deterministic misroute
+ * still surfaces unchanged — only a transient blip is absorbed. Never pair this
+ * selector with an unbounded retry or a fallback value.
+ */
+const ARGUMENT_FREE_VIEW_SELECTORS = new Set([
+    '0x313ce567', // decimals()
+    '0x95d89b41', // symbol()
+    '0x06fdde03', // name()
+    '0x18160ddd', // totalSupply()
+    exports.LP_TOKEN_ADDRESS_SELECTOR, // lpTokenAddress()
+]);
+/**
+ * Extract the 4-byte selector of the call an ethers `CALL_EXCEPTION` describes.
+ *
+ * ethers v6 attaches the attempted call as `error.transaction.data`, and also
+ * embeds it in the human-readable message as `data="0x…"`. We read the
+ * structured field first and fall back to the message so the predicate still
+ * works on an error that has been serialized and rehydrated (which is how these
+ * arrive from a logging pipeline).
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns The lower-cased `0x`-prefixed 4-byte selector, or `null` when the
+ *   error does not name a call.
+ */
+function callSelector(error) {
+    if (error && typeof error === 'object') {
+        const e = error;
+        const data = e.transaction?.data;
+        if (typeof data === 'string' && /^0x[0-9a-fA-F]{8}/.test(data)) {
+            return data.slice(0, 10).toLowerCase();
+        }
+    }
+    // ethers renders the same field two ways depending on nesting depth:
+    // `data="0x313ce567"` at the top level and `"data": "0x313ce567"` inside the
+    // serialized `transaction={…}` blob. Accept both.
+    for (const raw of nestedMessages(error)) {
+        const match = raw.match(/data"?\s*[:=]\s*"(0x[0-9a-fA-F]{8})/);
+        if (match?.[1])
+            return match[1].toLowerCase();
+    }
+    return null;
+}
+/**
+ * Is this error an **empty RPC response to an argument-free view call** —
+ * i.e. a transport artefact wearing a revert's clothes?
+ *
+ * Why this is separate from {@link isRetryableRpcError}: when a provider
+ * truncates or 500s a response to `eth_call`, ethers reports
+ * `missing revert data (action="call", data="0x313ce567", …)` with a `null`
+ * `data` field. That is byte-for-byte the shape of a genuine revert with no
+ * reason string, so a general "transport" predicate cannot safely claim it —
+ * doing so would retry every data-less `CALL_EXCEPTION` in the SDK. This
+ * predicate narrows the claim to the one case where the ambiguity resolves:
+ * a **deployed ERC-20's `decimals()`/`symbol()`/`name()`/`totalSupply()` cannot
+ * legitimately revert**, because it takes no arguments and returns state fixed
+ * at deployment. An empty response there is the provider's fault, full stop.
+ *
+ * A match requires all of:
+ * 1. no revert evidence ({@link hasRevertEvidence}) — anything carrying real
+ *    revert `data`, an `execution reverted` message, or a failed receipt is out;
+ * 2. a `missing revert data` message;
+ * 3. an `action` of `call` or `staticCall` — a read, never a state change;
+ * 4. **when a selector is derivable** from the error, that it is
+ *    `expectedSelector` (if given) or one of
+ *    {@link ARGUMENT_FREE_VIEW_SELECTORS}. When no selector can be recovered,
+ *    conditions 1–3 stand on their own.
+ *
+ * Note the cost of a false positive is bounded and small: the caller retries an
+ * idempotent read a couple of times before surfacing the same error. The cost
+ * of a false negative is the production flood this predicate exists to stop.
+ *
+ * @param error - The caught value, of unknown type.
+ * @param expectedSelector - Optional `0x`-prefixed 4-byte selector the caller
+ *   knows it invoked (e.g. `'0x313ce567'` for `decimals()`). When supplied, the
+ *   error's own selector must match it — this stops a `decimals()` retry from
+ *   firing on an unrelated view call that happened to fail the same way.
+ * @returns `true` when the failure is an empty provider response to a view call
+ *   that cannot revert, and is therefore safe to retry.
+ *
+ * @example
+ * ```ts
+ * try { return Number(await erc20.decimals()); }
+ * catch (e) {
+ *   if (!isEmptyViewResponse(e, '0x313ce567')) throw e; // real problem
+ *   return Number(await erc20.decimals());              // provider blip
+ * }
+ * ```
+ */
+function isEmptyViewResponse(error, expectedSelector) {
+    if (error === null || error === undefined)
+        return false;
+    if (hasRevertEvidence(error))
+        return false;
+    const messages = nestedMessages(error).map((raw) => raw.toLowerCase());
+    if (!messages.some((msg) => msg.includes('missing revert data')))
+        return false;
+    // The call must be a read. ethers exposes this as a structured `action`
+    // ('call' | 'estimateGas' | 'sendTransaction' | …) and mirrors it in the
+    // message as action="call".
+    const action = error && typeof error === 'object'
+        ? error.action
+        : undefined;
+    const isRead = action === 'call' ||
+        action === 'staticCall' ||
+        messages.some((msg) => msg.includes('action="call"') || msg.includes('action="staticcall"'));
+    if (!isRead)
+        return false;
+    const selector = callSelector(error);
+    // Nothing to check against — conditions 1-3 already establish "empty response
+    // to a read", which is the signal we act on.
+    if (!selector)
+        return true;
+    if (expectedSelector)
+        return selector === expectedSelector.toLowerCase();
+    return ARGUMENT_FREE_VIEW_SELECTORS.has(selector);
+}
+/**
+ * How many times an idempotent RPC read is attempted in total (1 initial call +
+ * 2 retries) before the transport error is surfaced. Deliberately small:
+ * CLAUDE.md §4.2 — retrying harder during a provider outage amplifies load
+ * rather than recovering from it.
+ */
+const RPC_RETRY_ATTEMPTS = 3;
+/**
+ * Base backoff between retry attempts, in milliseconds. Doubles per attempt
+ * (250ms, then 500ms), so a fully-failed read costs ~750ms of added latency.
+ */
+const RPC_RETRY_BASE_DELAY_MS = 250;
+/**
+ * Run an **idempotent** RPC read, retrying with exponential backoff while the
+ * failure classifies as a transient transport fault
+ * ({@link isRetryableRpcError}).
+ *
+ * Lives next to the classifiers it consumes so there is exactly one retry
+ * implementation in the SDK: both the receipt-poll fallback in the vault write
+ * paths and the cached `decimals()` reader in `core/helpers/web3.ts` call this.
+ *
+ * Only safe for operations that can be repeated without side effects: polling
+ * `eth_getTransactionReceipt` for an already-broadcast hash, or re-reading an
+ * immutable value such as `decimals()`. **Never wrap a transaction send in
+ * this.**
+ *
+ * Anything that is not a transport fault (a genuine revert, a user rejection,
+ * an insufficient-funds rejection) is rethrown on the first attempt with no
+ * delay, so real failures still fail fast.
+ *
+ * @param tag - Low-cardinality log label for the retry breadcrumb.
+ * @param operation - The idempotent async read to run.
+ * @param context - Extra structured context for the retry breadcrumb (e.g.
+ *   `{ hash }`). Sanitized by the logger before transport.
+ * @param isRetryable - Predicate deciding whether a caught error warrants
+ *   another attempt. Defaults to the strict transport definition
+ *   ({@link isRetryableRpcError}); pass a wider one only where the call site
+ *   can prove the extra shape is also a provider artefact — the only such case
+ *   today is the selector-scoped {@link isEmptyViewResponse} used by
+ *   `getDecimalsOrThrow`.
+ * @returns Whatever `operation` resolves to on the first successful attempt.
+ * @throws The last error thrown by `operation` once retries are exhausted, or
+ *   immediately when the error is not retryable.
+ *
+ * @example
+ * ```ts
+ * const receipt = await retryOnTransientRpc(
+ *   'safeWaitForTx:transport-retry',
+ *   () => provider.waitForTransaction(hash, 1, 120_000),
+ *   { hash },
+ * );
+ * ```
+ */
+async function retryOnTransientRpc(tag, operation, context = {}, isRetryable = isRetryableRpcError) {
+    let lastError;
+    for (let attempt = 1; attempt <= RPC_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryable(error) || attempt === RPC_RETRY_ATTEMPTS) {
+                throw error;
+            }
+            const delayMs = RPC_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1);
+            logger_1.Logger.log.warn(tag, 'transient RPC error; retrying', {
+                ...context,
+                attempt,
+                attempts: RPC_RETRY_ATTEMPTS,
+                delayMs,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    // Unreachable: the loop either returns or throws on its final attempt.
+    throw lastError;
+}
+/**
+ * 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.
+ */
+function logChainError(tag, error, isBenign, context) {
+    if (isBenign) {
+        // Demote to a breadcrumb: the SDK's Sentry sink forwards `warn` as a
+        // breadcrumb, so this no longer creates its own billed issue while still
+        // preserving the trail if a genuine error follows.
+        logger_1.Logger.log.warn(tag, { message: errorText(error), ...(context ?? {}) });
+        return;
+    }
+    logger_1.Logger.log.error(tag, error, context);
+}
+//# sourceMappingURL=chain-error.js.map