@augustdigital/sdk 8.16.1 → 8.19.0

package/lib/adapters/evm/index.js

@@ -57,8 +57,10 @@ class EVMAdapter {
         if (this.signer) {
             return this.signer;
         }
-        // Normalize and cache the signer
-        this.signer = await (0, signer_1.normalizeSigner)(this.rawSigner);
+        // Normalize and cache the signer. The attribution wrap is unconditional
+        // and reads the process-global config at send time, so a cached signer
+        // honors attribution enabled or reset after caching.
+        this.signer = (0, signer_1.wrapSignerWithAttribution)(await (0, signer_1.normalizeSigner)(this.rawSigner));
         return this.signer;
     }
     // Core EVM operations

package/lib/adapters/stellar/soroban.d.ts

@@ -58,9 +58,14 @@ export declare function getHealthyServer(config: ISorobanNetworkConfig): Promise
  * Exported so an operation with different semantics (e.g. an idempotency-aware
  * submission path) can compose or replace this policy via
  * {@link FailoverOptions.isRetryable} — extension without editing the core.
+ *
+ * Named distinctly from `core/helpers/chain-error`'s `isRetryableRpcError`
+ * (the EVM transport classifier, deliberately public) — the internal-dts
+ * leak check matches `@internal` tags by name across the whole `src.ts` tree,
+ * so a same-named pair would make it flag the public EVM one as a leak.
  * @internal
  */
-export declare function isRetryableRpcError(err: unknown): boolean;
+export declare function isRetryableSorobanRpcError(err: unknown): boolean;
 /**
  * Whether a simulation *error* string is a node/infrastructure failure (which
  * clears on another endpoint) rather than a genuine contract revert (which
@@ -76,7 +81,7 @@ export declare function isRetryableSimulationError(errorText: string): boolean;
  * failover core (Open/Closed at the call site).
  */
 export interface FailoverOptions {
-    /** Which thrown errors get the next endpoint. Defaults to {@link isRetryableRpcError}. */
+    /** Which thrown errors get the next endpoint. Defaults to {@link isRetryableSorobanRpcError}. */
     isRetryable?: (err: unknown) => boolean;
     /** Per-attempt timeout in ms. Defaults to {@link RPC_OPERATION_TIMEOUT_MS}. */
     timeoutMs?: number;
@@ -92,7 +97,7 @@ export interface FailoverOptions {
  * the health-gated server first (the fast, cached path) and, on a retryable
  * failure, drop that cached choice and retry the op against every endpoint in
  * priority order. Deterministic contract/domain errors short-circuit (see
- * {@link isRetryableRpcError}); each attempt is time-boxed so a hung node can't
+ * {@link isRetryableSorobanRpcError}); each attempt is time-boxed so a hung node can't
  * stall the loop.
  *
  * The `operation` is a strategy (dependency-injected), so new read/build calls

package/lib/adapters/stellar/soroban.js

@@ -11,7 +11,7 @@ exports.resolveNetworkConfig = resolveNetworkConfig;
 exports.resetHealthyServerCache = resetHealthyServerCache;
 exports.redactRpcUrl = redactRpcUrl;
 exports.getHealthyServer = getHealthyServer;
-exports.isRetryableRpcError = isRetryableRpcError;
+exports.isRetryableSorobanRpcError = isRetryableSorobanRpcError;
 exports.isRetryableSimulationError = isRetryableSimulationError;
 exports.withEndpointFailover = withEndpointFailover;
 exports.toBigIntAmount = toBigIntAmount;
@@ -291,9 +291,14 @@ async function probeHealthyServer(rpcUrls, cacheKey) {
  * Exported so an operation with different semantics (e.g. an idempotency-aware
  * submission path) can compose or replace this policy via
  * {@link FailoverOptions.isRetryable} — extension without editing the core.
+ *
+ * Named distinctly from `core/helpers/chain-error`'s `isRetryableRpcError`
+ * (the EVM transport classifier, deliberately public) — the internal-dts
+ * leak check matches `@internal` tags by name across the whole `src.ts` tree,
+ * so a same-named pair would make it flag the public EVM one as a leak.
  * @internal
  */
-function isRetryableRpcError(err) {
+function isRetryableSorobanRpcError(err) {
     return !(err instanceof core_1.AugustValidationError || err instanceof core_1.AugustSDKError);
 }
 /**
@@ -334,7 +339,7 @@ function dropCachedServer(rpcUrls) {
  * the health-gated server first (the fast, cached path) and, on a retryable
  * failure, drop that cached choice and retry the op against every endpoint in
  * priority order. Deterministic contract/domain errors short-circuit (see
- * {@link isRetryableRpcError}); each attempt is time-boxed so a hung node can't
+ * {@link isRetryableSorobanRpcError}); each attempt is time-boxed so a hung node can't
  * stall the loop.
  *
  * The `operation` is a strategy (dependency-injected), so new read/build calls
@@ -345,7 +350,7 @@ function dropCachedServer(rpcUrls) {
  * @internal
  */
 async function withEndpointFailover(config, method, operation, options = {}) {
-    const isRetryable = options.isRetryable ?? isRetryableRpcError;
+    const isRetryable = options.isRetryable ?? isRetryableSorobanRpcError;
     const timeoutMs = options.timeoutMs ?? RPC_OPERATION_TIMEOUT_MS;
     const rpcUrls = config.rpcUrls && config.rpcUrls.length > 0
         ? config.rpcUrls

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

@@ -2,4 +2,4 @@
  * Sentry DSN for SDK analytics.
  * This is an internal constant - not exposed to SDK users.
  */
-export declare const SENTRY_DSN = "https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776";
+export declare const SENTRY_DSN = "https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776";

package/lib/core/analytics/constants.js

@@ -5,5 +5,5 @@ exports.SENTRY_DSN = void 0;
  * Sentry DSN for SDK analytics.
  * This is an internal constant - not exposed to SDK users.
  */
-exports.SENTRY_DSN = 'https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776';
+exports.SENTRY_DSN = 'https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776';
 //# sourceMappingURL=constants.js.map

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.16.1";
+export declare const SDK_VERSION = "8.19.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.16.1';
+exports.SDK_VERSION = '8.19.0';
 //# sourceMappingURL=version.js.map

package/lib/core/attribution.d.ts

@@ -0,0 +1,111 @@
+/**
+ * ERC-8021 transaction attribution (Base Builder Codes).
+ *
+ * ERC-8021 appends an attribution suffix to transaction calldata. Contracts
+ * decode their ABI-encoded arguments normally and ignore the trailing bytes,
+ * while offchain indexers (e.g. base.dev analytics for Base Builder Codes)
+ * read the suffix to attribute the transaction to the originating app.
+ *
+ * This is a leaf module: process-global state configured once via
+ * {@link IAugustBase.attribution} in the SDK constructor and read by the
+ * EVM write paths (the normalized-signer wrap in the EVM adapter and the
+ * cross-chain vault `writeContract` calls).
+ *
+ * @module attribution
+ */
+/**
+ * The 16-byte ERC-8021 suffix terminator. The last 16 bytes of an attributed
+ * transaction's calldata are always this marker; parsers read backwards from
+ * it to recover the schema ID and builder codes.
+ */
+export declare const ERC8021_MARKER = "80218021802180218021802180218021";
+/**
+ * Configuration for ERC-8021 calldata-suffix attribution (Base Builder Codes).
+ *
+ * @example
+ * ```typescript
+ * const sdk = new AugustSDK({
+ *   appName: 'my-app',
+ *   providers: { 8453: 'https://...' },
+ *   keys: { august: '...' },
+ *   attribution: { builderCodes: ['bc_abc123'] },
+ * });
+ * ```
+ */
+export interface IAttributionConfig {
+    /**
+     * Builder codes to embed in the suffix, e.g. from base.dev registration
+     * (`bc_…`). ASCII strings of 1–64 characters each; the comma-joined list
+     * must fit in 255 bytes (schema 0 length prefix is a single byte).
+     */
+    builderCodes: string[];
+    /**
+     * EVM chain IDs to attribute. Omit to attribute writes on every EVM chain
+     * (the suffix is inert on chains without an ERC-8021 indexer and costs
+     * ~16 gas per non-zero byte). When set, writes on other chains are sent
+     * without the suffix; call sites that cannot determine their chain ID
+     * append the suffix regardless, since over-attribution is harmless and
+     * under-attribution loses data.
+     */
+    chains?: number[];
+}
+/**
+ * Build an ERC-8021 schema-0 attribution suffix from builder codes.
+ *
+ * Layout (appended to calldata, read back-to-front by parsers):
+ * `ascii(codes.join(','))` ∥ codesLength (1 byte) ∥ schemaId `0x00` ∥
+ * 16-byte marker `0x80218021802180218021802180218021`.
+ *
+ * @param codes Builder codes as printable-ASCII strings (e.g. `bc_abc123`),
+ *   each 1–64 chars, no commas; the comma-joined list must be ≤ 255 bytes.
+ * @returns `0x`-prefixed hex suffix ready to concatenate onto calldata.
+ * @throws Error when `codes` is empty, a code contains a comma or
+ *   non-printable/non-ASCII characters, or the joined list exceeds 255 bytes.
+ * @example
+ * ```typescript
+ * buildAttributionSuffix(['baseapp', 'morpho']);
+ * // '0x626173656170702c6d6f7270686f0e0080218021802180218021802180218021'
+ * ```
+ */
+export declare function buildAttributionSuffix(codes: string[]): string;
+/**
+ * Set (or clear) the process-global attribution config.
+ *
+ * Called unconditionally on every `AugustSDK` construction — an instance
+ * that omits `attribution` passes `null` and RESETS the state, so a prior
+ * instance's builder codes never leak into a later instance in the same
+ * process (same semantics as `setPublicApiBaseUrl`).
+ *
+ * @param config Attribution config from the SDK constructor, or `null` to
+ *   disable attribution.
+ * @throws Error when the config's builder codes fail validation — thrown
+ *   synchronously from the constructor so misconfiguration is caught at
+ *   init, not on the first write.
+ */
+export declare function setAttribution(config: IAttributionConfig | null): void;
+/**
+ * Return the active ERC-8021 suffix for a write on the given chain, or
+ * `undefined` when attribution is off or the chain is excluded.
+ *
+ * @param chainId EVM chain ID of the transaction, when the call site knows
+ *   it. When omitted and a `chains` restriction is configured, the suffix is
+ *   returned anyway (over-attribution is harmless; see
+ *   {@link IAttributionConfig.chains}).
+ * @returns `0x`-prefixed hex suffix, or `undefined` when nothing should be
+ *   appended.
+ */
+export declare function getAttributionSuffix(chainId?: number): string | undefined;
+/**
+ * Append the active attribution suffix to calldata.
+ *
+ * No-ops (returns `data` unchanged) when attribution is off, the chain is
+ * excluded, `data` is empty/absent (plain value transfers are never
+ * attributed), or `data` already ends with the ERC-8021 marker (guards
+ * against double-appending when an upstream layer — e.g. a wagmi config
+ * `dataSuffix` — already attributed the transaction).
+ *
+ * @param data `0x`-prefixed calldata of the outgoing transaction.
+ * @param chainId EVM chain ID of the transaction, when known.
+ * @returns Calldata with the suffix appended, or the input unchanged.
+ */
+export declare function appendAttributionSuffix(data: string | undefined | null, chainId?: number): string | undefined | null;

package/lib/core/attribution.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * ERC-8021 transaction attribution (Base Builder Codes).
+ *
+ * ERC-8021 appends an attribution suffix to transaction calldata. Contracts
+ * decode their ABI-encoded arguments normally and ignore the trailing bytes,
+ * while offchain indexers (e.g. base.dev analytics for Base Builder Codes)
+ * read the suffix to attribute the transaction to the originating app.
+ *
+ * This is a leaf module: process-global state configured once via
+ * {@link IAugustBase.attribution} in the SDK constructor and read by the
+ * EVM write paths (the normalized-signer wrap in the EVM adapter and the
+ * cross-chain vault `writeContract` calls).
+ *
+ * @module attribution
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC8021_MARKER = void 0;
+exports.buildAttributionSuffix = buildAttributionSuffix;
+exports.setAttribution = setAttribution;
+exports.getAttributionSuffix = getAttributionSuffix;
+exports.appendAttributionSuffix = appendAttributionSuffix;
+/**
+ * The 16-byte ERC-8021 suffix terminator. The last 16 bytes of an attributed
+ * transaction's calldata are always this marker; parsers read backwards from
+ * it to recover the schema ID and builder codes.
+ */
+exports.ERC8021_MARKER = '80218021802180218021802180218021';
+/**
+ * Build an ERC-8021 schema-0 attribution suffix from builder codes.
+ *
+ * Layout (appended to calldata, read back-to-front by parsers):
+ * `ascii(codes.join(','))` ∥ codesLength (1 byte) ∥ schemaId `0x00` ∥
+ * 16-byte marker `0x80218021802180218021802180218021`.
+ *
+ * @param codes Builder codes as printable-ASCII strings (e.g. `bc_abc123`),
+ *   each 1–64 chars, no commas; the comma-joined list must be ≤ 255 bytes.
+ * @returns `0x`-prefixed hex suffix ready to concatenate onto calldata.
+ * @throws Error when `codes` is empty, a code contains a comma or
+ *   non-printable/non-ASCII characters, or the joined list exceeds 255 bytes.
+ * @example
+ * ```typescript
+ * buildAttributionSuffix(['baseapp', 'morpho']);
+ * // '0x626173656170702c6d6f7270686f0e0080218021802180218021802180218021'
+ * ```
+ */
+function buildAttributionSuffix(codes) {
+    if (!Array.isArray(codes) || codes.length === 0) {
+        throw new Error('August SDK: attribution.builderCodes must be a non-empty array of builder-code strings (e.g. ["bc_abc123"]). Register at https://base.dev to obtain one.');
+    }
+    for (const code of codes) {
+        if (typeof code !== 'string' ||
+            code.length === 0 ||
+            code.length > 64 ||
+            !/^[\x21-\x7e]+$/.test(code) ||
+            code.includes(',')) {
+            throw new Error(`August SDK: invalid builder code "${code}". Codes must be 1-64 printable ASCII characters with no commas or whitespace.`);
+        }
+    }
+    const joined = codes.join(',');
+    if (joined.length > 255) {
+        throw new Error(`August SDK: attribution builder codes exceed 255 bytes when comma-joined (got ${joined.length}). Use fewer or shorter codes.`);
+    }
+    let hex = '';
+    for (let i = 0; i < joined.length; i++) {
+        hex += joined.charCodeAt(i).toString(16).padStart(2, '0');
+    }
+    const length = joined.length.toString(16).padStart(2, '0');
+    return `0x${hex}${length}00${exports.ERC8021_MARKER}`;
+}
+let activeSuffix = null;
+let activeChains = null;
+/**
+ * Set (or clear) the process-global attribution config.
+ *
+ * Called unconditionally on every `AugustSDK` construction — an instance
+ * that omits `attribution` passes `null` and RESETS the state, so a prior
+ * instance's builder codes never leak into a later instance in the same
+ * process (same semantics as `setPublicApiBaseUrl`).
+ *
+ * @param config Attribution config from the SDK constructor, or `null` to
+ *   disable attribution.
+ * @throws Error when the config's builder codes fail validation — thrown
+ *   synchronously from the constructor so misconfiguration is caught at
+ *   init, not on the first write.
+ */
+function setAttribution(config) {
+    if (!config) {
+        activeSuffix = null;
+        activeChains = null;
+        return;
+    }
+    activeSuffix = buildAttributionSuffix(config.builderCodes);
+    activeChains =
+        Array.isArray(config.chains) && config.chains.length > 0
+            ? config.chains
+            : null;
+}
+/**
+ * Return the active ERC-8021 suffix for a write on the given chain, or
+ * `undefined` when attribution is off or the chain is excluded.
+ *
+ * @param chainId EVM chain ID of the transaction, when the call site knows
+ *   it. When omitted and a `chains` restriction is configured, the suffix is
+ *   returned anyway (over-attribution is harmless; see
+ *   {@link IAttributionConfig.chains}).
+ * @returns `0x`-prefixed hex suffix, or `undefined` when nothing should be
+ *   appended.
+ */
+function getAttributionSuffix(chainId) {
+    if (!activeSuffix)
+        return undefined;
+    if (activeChains && typeof chainId === 'number') {
+        if (!activeChains.includes(chainId))
+            return undefined;
+    }
+    return activeSuffix;
+}
+/**
+ * Append the active attribution suffix to calldata.
+ *
+ * No-ops (returns `data` unchanged) when attribution is off, the chain is
+ * excluded, `data` is empty/absent (plain value transfers are never
+ * attributed), or `data` already ends with the ERC-8021 marker (guards
+ * against double-appending when an upstream layer — e.g. a wagmi config
+ * `dataSuffix` — already attributed the transaction).
+ *
+ * @param data `0x`-prefixed calldata of the outgoing transaction.
+ * @param chainId EVM chain ID of the transaction, when known.
+ * @returns Calldata with the suffix appended, or the input unchanged.
+ */
+function appendAttributionSuffix(data, chainId) {
+    const suffix = getAttributionSuffix(chainId);
+    if (!suffix)
+        return data;
+    if (typeof data !== 'string' || data === '' || data === '0x')
+        return data;
+    if (data.toLowerCase().endsWith(exports.ERC8021_MARKER))
+        return data;
+    return data + suffix.slice(2);
+}
+//# sourceMappingURL=attribution.js.map

package/lib/core/base.class.d.ts

@@ -1,6 +1,7 @@
 import type { ISolanaConfig, IStellarConfig, IAddress, IChainId, IEnv, IProvidersConfig, IWSMonitorHeaders } from '../types';
 import { type IAnalyticsConfig } from './analytics';
 import { type IVersionCheckConfig } from './version-check';
+import { type IAttributionConfig } from './attribution';
 interface IKeys {
     august?: string;
     graph?: string;
@@ -83,6 +84,21 @@ export interface IAugustBase {
      * a stale cross-environment base is higher blast-radius than a stale timeout.)
      */
     publicApiBaseUrl?: string;
+    /**
+     * ERC-8021 calldata-suffix attribution (Base Builder Codes). When set,
+     * every EVM write sent through the SDK — ethers vault writes and the
+     * cross-chain (OVault) viem writes — carries the attribution suffix so
+     * offchain indexers (base.dev) can credit the transaction to your app.
+     * Omit to send unattributed transactions (the default).
+     *
+     * Note: this is a process-global override applied on EVERY construction —
+     * the last `AugustSDK` instantiated is authoritative, and one that omits
+     * `attribution` RESETS it (same semantics as `publicApiBaseUrl`).
+     *
+     * @throws Throws synchronously from the constructor when the builder codes
+     *   are malformed — see {@link IAttributionConfig}.
+     */
+    attribution?: IAttributionConfig;
 }
 interface IActiveNetwork {
     chainId: IChainId;
@@ -107,7 +123,7 @@ export declare class AugustBase {
      * @throws If `appName` is missing, malformed, or out of the allowed
      *   length range — see {@link IAugustBase.appName}.
      */
-    constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, }: IAugustBase);
+    constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IAugustBase);
     /**
      * Verify API keys and authorize SDK usage.
      * TODO: initialize class with appropriate keys and verify august key

package/lib/core/base.class.js

@@ -6,6 +6,7 @@ const logger_1 = require("./logger");
 const analytics_1 = require("./analytics");
 const version_check_1 = require("./version-check");
 const fetcher_1 = require("./fetcher");
+const attribution_1 = require("./attribution");
 /**
  * Validate an appName at SDK construction time.
  *
@@ -55,7 +56,7 @@ class AugustBase {
      * @throws If `appName` is missing, malformed, or out of the allowed
      *   length range — see {@link IAugustBase.appName}.
      */
-    constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, }) {
+    constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }) {
         // Validate first so the failure mode is a clear, actionable error before
         // any provider / analytics side effects run.
         this.appName = validateAppName(appName);
@@ -95,6 +96,10 @@ class AugustBase {
         // prior staging instance would leak into a later prod instance in the same
         // process — the inverse of the isolation this option exists to provide.
         (0, fetcher_1.setPublicApiBaseUrl)(publicApiBaseUrl ?? null);
+        // ERC-8021 attribution follows the same reset-on-omit contract as
+        // `publicApiBaseUrl`: called unconditionally so a prior instance's
+        // builder codes never leak into a later instance in the same process.
+        (0, attribution_1.setAttribution)(attribution ?? null);
     }
     /**
      * Verify API keys and authorize SDK usage.

package/lib/core/fetcher.js

@@ -23,6 +23,7 @@ const ethers_1 = require("ethers");
 const abis_1 = require("../abis");
 const lru_cache_1 = require("lru-cache");
 const chain_address_1 = require("./helpers/chain-address");
+const chain_error_1 = require("./helpers/chain-error");
 const fetcher_1 = require("../services/coingecko/fetcher");
 const logger_1 = require("./logger");
 const ethers_2 = require("ethers");
@@ -705,7 +706,15 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
     if (foundVaultLpAsset?.vault && provider && version === 'evm-2') {
         try {
             const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset?.vault), abis_1.ABI_TOKENIZED_VAULT_V2, provider);
-            const receiptAddress = (await vaultContract.lpTokenAddress());
+            // Same bounded, no-fallback retry the write paths use for this selector
+            // (`getReceiptTokenAddressOrThrow` in `core/helpers/web3`). It cannot be
+            // reused here: `helpers/web3` imports `fetchTokenizedVault` from this
+            // module, so importing it back would be a circular dependency (CLAUDE.md
+            // §9). A transient empty `eth_call` response is absorbed; a vault that
+            // genuinely lacks `lpTokenAddress()` still falls into the catch below
+            // after the attempts are spent.
+            const receiptAddress = await (0, chain_error_1.retryOnTransientRpc)('fetchTokenPrice:receiptToken', () => vaultContract.lpTokenAddress(), { vault: foundVaultLpAsset.vault }, (error) => (0, chain_error_1.isRetryableRpcError)(error) ||
+                (0, chain_error_1.isEmptyViewResponse)(error, chain_error_1.LP_TOKEN_ADDRESS_SELECTOR));
             const receiptContract = new ethers_2.Contract(receiptAddress, [web3_1.MIN_ABIS.decimals], provider);
             const decimals = Number(await receiptContract.decimals());
             const sharePrice = await vaultContract.getSharePrice();

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

@@ -46,6 +46,146 @@ export declare function isUserRejectionError(error: unknown): boolean;
  */
 export declare function isExpectedRevertError(error: unknown): boolean;
 export declare function isInsufficientFundsError(error: unknown): boolean;
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare function isRetryableRpcError(error: unknown): boolean;
+/**
+ * `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.
+ */
+export declare const LP_TOKEN_ADDRESS_SELECTOR = "0xf5ae497a";
+/**
+ * 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
+ * }
+ * ```
+ */
+export declare function isEmptyViewResponse(error: unknown, expectedSelector?: string): boolean;
+/**
+ * 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 },
+ * );
+ * ```
+ */
+export declare function retryOnTransientRpc<T>(tag: string, operation: () => Promise<T>, context?: Record<string, unknown>, isRetryable?: (error: unknown) => boolean): Promise<T>;
 /**
  * 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`