@augustdigital/sdk 8.17.0 → 8.19.0

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

@@ -75,11 +75,84 @@ export { explorerLink } from './explorer-link';
 /**
  * Fetch token decimals from contract or Solana mint.
  * Results are cached to minimize RPC calls.
+ *
+ * **Never throws** — a failed read logs at error level and resolves
+ * `undefined`. Callers that must not silently proceed on an unknown scale (any
+ * path that encodes an amount) should use {@link getDecimalsOrThrow} instead:
+ * feeding `undefined` into `toNormalizedBn` silently defaults to 18 decimals.
+ *
  * @param provider Web3 provider
  * @param address Token contract address or Solana mint
- * @returns Number of decimals for the token
+ * @param isVault Resolve `address` as a vault (evm-2 vaults redirect to the
+ *   receipt token) rather than reading it as a plain ERC-20. Defaults to `true`.
+ * @returns Number of decimals for the token, or `undefined` when the read failed.
  */
 export declare const getDecimals: (provider: IContractRunner, address: IAddress, isVault?: boolean) => Promise<number>;
+/**
+ * Read a token's `decimals()` with the **same cache and stampede protection as
+ * {@link getDecimals}**, but surfacing failures instead of swallowing them, and
+ * retrying the transient ones.
+ *
+ * Two reasons this exists rather than a flag on `getDecimals`:
+ *
+ * 1. **`getDecimals` must keep returning `undefined` on failure** — a dozen
+ *    read paths depend on that. Amount-encoding paths need the opposite: an
+ *    `undefined` reaching `toNormalizedBn` silently means 18 decimals, which
+ *    misencodes the transaction. Here the original error propagates, so the
+ *    caller's `AugustSDKError` keeps its cause and its Sentry grouping.
+ * 2. **Retry.** Providers intermittently return an empty response to
+ *    `decimals()`, which ethers reports as
+ *    `missing revert data (action="call", data="0x313ce567", …)` — a shape a
+ *    deployed ERC-20 cannot legitimately produce, since `decimals()` takes no
+ *    arguments. That is retried here via {@link isEmptyViewResponse} scoped to
+ *    this exact selector, alongside ordinary transport faults
+ *    ({@link isRetryableRpcError}). The empty-view widening applies **only**
+ *    here; everywhere else the strict transport definition stands. A genuine
+ *    revert (`CALL_EXCEPTION` carrying revert data) is never retried.
+ *
+ * Cache is shared with `getDecimals`, so a read-then-write flow against the
+ * same token costs one `decimals()` RPC in total, and N concurrent callers for
+ * an uncached token collapse to one.
+ *
+ * **Exception — an unresolvable chain scope bypasses the cache entirely.** When
+ * {@link resolveProviderScope} cannot determine the chain (a runner with no
+ * resolved network and no connection URL, e.g. a browser provider before its
+ * first request), the only available key is the shared `unknown` bucket. Read
+ * paths happily use that bucket, and this function deliberately does not: the
+ * two paths have different blast radii. A wrong cached `decimals` on a read
+ * renders a wrong number on screen; on a write it misencodes an amount the user
+ * then *signs*. The collision needed — the same address being a different token
+ * with different decimals on two chains, within one process, across a
+ * mid-session chain switch — is narrow, but "no worse than the read path" is
+ * not the bar for a value that ends up in a transaction. In that case the read
+ * is neither served from nor written to the cache, and it also skips the
+ * in-flight dedup map, since joining another caller under an untrusted key
+ * would reintroduce exactly the collision being avoided. Retries still apply;
+ * the only thing forgone is the RPC saving.
+ *
+ * RPC cost: 1 on a cache miss, 0 on a hit, up to 3 on a miss that keeps
+ * faulting (~750ms of added latency in the worst case before it gives up).
+ * Always ≥1 when the chain scope is unresolvable.
+ *
+ * @param runner - Provider or signer to read through. A signer is unwrapped to
+ *   its provider for cache scoping, so it shares entries with reads on the
+ *   same chain.
+ * @param address - Token address. Read directly as an ERC-20 — pass the
+ *   receipt-token address yourself for an `evm-2` vault's share scale.
+ * @param tag - Low-cardinality label for retry breadcrumbs (e.g.
+ *   `'vaultDeposit:poolDecimals'`).
+ * @returns The token's decimals.
+ * @throws The underlying read error once retries are exhausted, or immediately
+ *   when the failure is neither a transport fault nor an empty view response.
+ *
+ * @example
+ * ```ts
+ * // Amount encoding must not proceed on a guessed scale.
+ * const decimals = await getDecimalsOrThrow(signer, token, 'deposit:decimals');
+ * const amount = toNormalizedBn(userInput, decimals);
+ * ```
+ */
+export declare const getDecimalsOrThrow: (runner: IContractRunner, address: IAddress, tag: string) => Promise<number>;
 /**
  * Fetch the whitelisted deposit-asset addresses from a vault's whitelist
  * contract. Cached with a 5-minute TTL; a fresh fetch fans out into N
@@ -87,12 +160,89 @@ export declare const getDecimals: (provider: IContractRunner, address: IAddress,
  * @internal
  */
 export declare const getWhitelistedAssets: (provider: IContractRunner, whitelistAddress: IAddress) => Promise<IAddress[]>;
+/**
+ * Read an `evm-2` vault's receipt (LP) token address via `lpTokenAddress()`,
+ * retrying only the transient transport faults and surfacing everything else
+ * unchanged.
+ *
+ * Why this exists: `lpTokenAddress()` sits immediately before the receipt-token
+ * `decimals()` read on every `evm-2` write path (approve / deposit / request
+ * redeem / swap-router deposit). Those `decimals()` reads were hardened against
+ * provider blips ({@link getDecimalsOrThrow}); the `lpTokenAddress()` read one
+ * line above them was not, so a single truncated `eth_call` response still
+ * failed the whole write with
+ * `missing revert data (action="call", data="0xf5ae497a", …)` — observed in
+ * production against a mainnet vault whose `lpTokenAddress()` demonstrably
+ * returns a real address when the provider is healthy.
+ *
+ * **This must never hide a misrouted vault, and does not.** `lpTokenAddress()`
+ * exists *only* on `evm-2` vaults. A vault wrongly classified as `evm-2` returns
+ * empty returndata for it, deterministically and forever, and that empty
+ * response is byte-identical to the transient one — it is the *only* signal the
+ * SDK gets that its version routing was wrong. So the retry here is deliberately
+ * shaped to preserve that signal:
+ *
+ * - it is **bounded** (3 attempts, ~750ms of backoff in total — see
+ *   `retryOnTransientRpc`), never open-ended;
+ * - on exhaustion it **rethrows the original error object**, with its identity,
+ *   message, `code` and `transaction.data` intact, so the caller's
+ *   `AugustSDKError` cause and Sentry grouping are exactly what they are today;
+ * - it has **no fallback**: it never substitutes another address, never resolves
+ *   the vault address itself, and never resolves `null`/`undefined`. It either
+ *   returns a real receipt-token address or throws.
+ *
+ * Net effect: a blip costs a retry, a misroute costs three `eth_call`s and then
+ * fails exactly as loudly as before.
+ *
+ * **Deliberately not cached.** Unlike `decimals()`, the vault→receipt-token
+ * mapping is not memoized here. Caching it would make a misroute's first
+ * (failed) probe and every subsequent one diverge, and would put a
+ * vault-identity mapping in the cache on the money path. The lenient, cached
+ * reader is {@link getReceiptTokenAddress} — use that on read paths that can
+ * tolerate `undefined`.
+ *
+ * RPC cost: exactly 1 `eth_call` on success; at most 3 when the provider keeps
+ * faulting.
+ *
+ * @param runner - Provider or signer to read through.
+ * @param vault - Address of the `evm-2` tokenized vault.
+ * @param tag - Low-cardinality label for retry breadcrumbs (e.g.
+ *   `'vaultRequestRedeem:receiptToken'`).
+ * @returns The vault's receipt (LP) token address. Never `null`/`undefined`.
+ * @throws The underlying read error, unmodified, once the bounded retries are
+ *   exhausted — or immediately when the failure is neither a transport fault nor
+ *   an empty response to this exact selector (e.g. a genuine revert carrying
+ *   revert data).
+ *
+ * @example
+ * ```ts
+ * const receiptToken = await getReceiptTokenAddressOrThrow(
+ *   signer,
+ *   vault,
+ *   'vaultRequestRedeem:receiptToken',
+ * );
+ * const decimals = await getDecimalsOrThrow(signer, receiptToken, 'tag');
+ * ```
+ */
+export declare const getReceiptTokenAddressOrThrow: (runner: IContractRunner, vault: IAddress, tag: string) => Promise<IAddress>;
 /**
  * Fetch receipt token address from tokenized vault contract.
  * Results are cached to minimize RPC calls.
+ *
+ * **Never throws** — a failed read logs at error level and resolves
+ * `undefined`, which several read paths depend on. The underlying
+ * `lpTokenAddress()` call is made through
+ * {@link getReceiptTokenAddressOrThrow}, so a transient provider blip is
+ * absorbed by a bounded retry before that happens; a deterministic failure (a
+ * vault that has no `lpTokenAddress()` because it is not `evm-2`) still resolves
+ * `undefined` after the attempts are spent, exactly as before. Callers on a
+ * money path must use {@link getReceiptTokenAddressOrThrow} directly instead —
+ * an `undefined` receipt-token address there would silently mis-address a
+ * `decimals()` read.
+ *
  * @param provider Web3 provider
  * @param address Tokenized vault contract address
- * @returns Receipt token address
+ * @returns Receipt token address, or `undefined` when the read failed.
  */
 export declare const getReceiptTokenAddress: (provider: IContractRunner, address: IAddress) => Promise<`0x${string}`>;
 /**

package/lib/core/helpers/web3.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getManagementFeePercent = exports.getSymbol = exports.getReceiptTokenAddress = exports.getWhitelistedAssets = exports.getDecimals = exports.explorerLink = exports.getInfuraProvider = exports.createProvider = exports.getChainId = exports.determineBlockSkipInternal = exports.determineSecondsPerBlock = exports.determineBlockCutoff = void 0;
+exports.getManagementFeePercent = exports.getSymbol = exports.getReceiptTokenAddress = exports.getReceiptTokenAddressOrThrow = exports.getWhitelistedAssets = exports.getDecimalsOrThrow = exports.getDecimals = exports.explorerLink = exports.getInfuraProvider = exports.createProvider = exports.getChainId = exports.determineBlockSkipInternal = exports.determineSecondsPerBlock = exports.determineBlockCutoff = void 0;
 exports.createContract = createContract;
 exports.getTokenMetadata = getTokenMetadata;
 exports.simulateTransaction = simulateTransaction;
@@ -15,6 +15,7 @@ const logger_1 = require("../logger");
 const web3_1 = require("../constants/web3");
 const fetcher_1 = require("../fetcher");
 const chain_address_1 = require("./chain-address");
+const chain_error_1 = require("./chain-error");
 const constants_1 = require("../../adapters/solana/constants");
 const abis_1 = require("../../abis");
 const TokenizedVaultV2_1 = require("../../abis/TokenizedVaultV2");
@@ -199,8 +200,9 @@ exports.getInfuraProvider = getInfuraProvider;
 var explorer_link_1 = require("./explorer-link");
 Object.defineProperty(exports, "explorerLink", { enumerable: true, get: function () { return explorer_link_1.explorerLink; } });
 /**
- * Stable per-provider identity for cache keys — prevents cross-chain collisions
- * when the same address represents different tokens on different networks.
+ * Stable per-provider identity for cache keys, or `null` when the chain cannot
+ * be determined at all — the distinction callers need to decide whether a cache
+ * key is trustworthy.
  *
  * `provider._network` is a *getter* in ethers v6 that throws
  * `network is not available yet (NETWORK_ERROR)` until the provider has
@@ -210,8 +212,19 @@ Object.defineProperty(exports, "explorerLink", { enumerable: true, get: function
  * `getReceiptTokenAddress`, …) and surface as a confusing TVL failure on
  * fresh provider instances. We swallow the throw and fall back to the
  * connection URL — slightly less precise as a cache key but always safe.
+ *
+ * The runner is unwrapped to its provider first. An `IContractRunner` is either
+ * a `Provider` or a `Signer`, and a `Signer` carries the network on
+ * `signer.provider`, not on itself — without the unwrap every signer-backed
+ * read scoped to `'unknown'` and could never share a cache entry with the
+ * provider-backed read of the same token. The unwrap is a **no-op for
+ * providers**: ethers' `AbstractProvider` defines `get provider() { return
+ * this; }`, so read callers resolve to exactly the scope they did before.
+ *
+ * @returns `chain:<id>`, `url:<endpoint>`, or `null` when neither is available.
  */
-function providerScope(provider) {
+function resolveProviderScope(runner) {
+    const provider = runner?.provider ?? runner;
     let chainId;
     try {
         const net = provider
@@ -228,16 +241,124 @@ function providerScope(provider) {
     const conn = provider._getConnection?.();
     if (conn?.url)
         return `url:${conn.url}`;
-    return 'unknown';
+    return null;
 }
-/** @internal */
+/**
+ * Scope string for cache keys, collapsing an unresolvable runner to the
+ * literal `'unknown'` bucket.
+ *
+ * This is the long-standing behaviour of every cached read in this module and
+ * is deliberately preserved: read callers keep keying exactly as they always
+ * have, `decimals-unknown-…` entries included. Only {@link getDecimalsOrThrow}
+ * treats an unresolvable scope specially — see the note there on why the write
+ * path holds itself to a higher bar than the read path.
+ */
+function providerScope(runner) {
+    return resolveProviderScope(runner) ?? 'unknown';
+}
+/**
+ * Cache key for a token's `decimals()`, shared by **every** decimals reader in
+ * the SDK — the lenient {@link getDecimals} used by read paths and the strict
+ * {@link getDecimalsOrThrow} used by write paths. One namespace is the point:
+ * a page that reads a vault and then deposits into it must not pay the RPC
+ * twice (CLAUDE.md §4.1, "reuse results across functions").
+ *
+ * **What the entry holds is the *effective share-scale* decimals for `address`,
+ * not necessarily `address`'s own `decimals()`.** {@link fetchDecimals} with
+ * `isVault` redirects an `evm-2` vault to its receipt token, and the result is
+ * still stored under the vault's key — that redirect is the whole point of the
+ * flag, and every reader of a vault address wants the receipt token's scale.
+ * Consequence for future callers: `getDecimalsOrThrow(runner, evm2VaultAddr)`
+ * reads directly (`isVault: false`) but can be served the receipt token's value
+ * from this shared entry. Write paths therefore pass the receipt-token address
+ * explicitly for `evm-2` vaults; do not add a caller that expects an `evm-2`
+ * vault's own `decimals()` back out of this cache.
+ *
+ * @param scope - Result of {@link providerScope} / {@link resolveProviderScope}.
+ * @param address - Token address, or a vault address whose entry holds the
+ *   share-scale token's decimals (see above).
+ */
+function decimalsCacheKey(scope, address) {
+    return `decimals-${scope}-${address}`;
+}
+/**
+ * In-flight `decimals()` reads, keyed exactly as the cache. Collapses a
+ * stampede of concurrent callers for the same uncached token into one RPC.
+ *
+ * The stored promise **may reject** — strict callers need the original error.
+ * Lenient callers therefore must not return it raw; {@link getDecimals} awaits
+ * it inside a `try`.
+ * @internal
+ */
 const DECIMALS_REQUESTS = new Map();
+/**
+ * Run (or join) the single in-flight `decimals()` read for `key`, caching the
+ * result on success. Failures are never cached, so a transient outage does not
+ * poison the entry.
+ *
+ * @param key - Cache key from {@link decimalsCacheKey}.
+ * @param fetch - Performs the actual read. Only invoked on a miss with nothing
+ *   already in flight. Whichever caller registers the in-flight promise first
+ *   supplies this closure — a concurrent {@link getDecimalsOrThrow} joining a
+ *   {@link getDecimals}-initiated request inherits the lenient, no-retry read
+ *   instead of its own `retryOnTransientRpc` wrap. Not a correctness bug (the
+ *   strict caller still throws the original error), just a narrow window
+ *   where the strict path's transient-retry guarantee is momentarily lost.
+ * @returns The decimals value.
+ * @throws Whatever `fetch` throws — callers that must not throw wrap this.
+ */
+function sharedDecimalsRequest(key, fetch) {
+    const inflight = DECIMALS_REQUESTS.get(key);
+    if (inflight)
+        return inflight;
+    const request = (async () => {
+        const decimals = await fetch();
+        cache_1.CACHE.set(key, decimals);
+        return decimals;
+    })().finally(() => {
+        DECIMALS_REQUESTS.delete(key);
+    });
+    DECIMALS_REQUESTS.set(key, request);
+    return request;
+}
+/**
+ * Read `decimals()` off an ERC-20 at `address`, or — when `isVault` and the
+ * vault is `evm-2` — off its receipt token, which is where the share scale
+ * actually lives.
+ *
+ * @param runner - Provider or signer to read through.
+ * @param address - Token or vault address.
+ * @param isVault - Resolve `address` as a vault (may cost a backend metadata
+ *   fetch plus a `lpTokenAddress()` read) rather than reading it directly.
+ * @returns The decimals value.
+ * @throws Whatever the underlying read throws.
+ */
+async function fetchDecimals(runner, address, isVault) {
+    let realAddress = address;
+    if (isVault) {
+        const tokenizedVault = (await (0, fetcher_1.fetchTokenizedVault)(address))?.[0];
+        const version = (0, vault_version_1.getVaultVersionV2)(tokenizedVault);
+        if (version === 'evm-2') {
+            realAddress = await (0, exports.getReceiptTokenAddress)(runner, address);
+        }
+    }
+    const contract = new ethers_1.Contract(realAddress, [web3_1.MIN_ABIS.decimals], runner);
+    return Number(await contract.decimals());
+}
 /**
  * Fetch token decimals from contract or Solana mint.
  * Results are cached to minimize RPC calls.
+ *
+ * **Never throws** — a failed read logs at error level and resolves
+ * `undefined`. Callers that must not silently proceed on an unknown scale (any
+ * path that encodes an amount) should use {@link getDecimalsOrThrow} instead:
+ * feeding `undefined` into `toNormalizedBn` silently defaults to 18 decimals.
+ *
  * @param provider Web3 provider
  * @param address Token contract address or Solana mint
- * @returns Number of decimals for the token
+ * @param isVault Resolve `address` as a vault (evm-2 vaults redirect to the
+ *   receipt token) rather than reading it as a plain ERC-20. Defaults to `true`.
+ * @returns Number of decimals for the token, or `undefined` when the read failed.
  */
 const getDecimals = async (provider, address, isVault = true) => {
     if (address === ethers_1.ZeroAddress) {
@@ -248,45 +369,105 @@ const getDecimals = async (provider, address, isVault = true) => {
         return constants_1.fallbackDecimals;
     if (!(address && provider))
         return;
-    const key = `decimals-${providerScope(provider)}-${address}`;
+    const key = decimalsCacheKey(providerScope(provider), address);
     if (cache_1.CACHE.has(key))
         return cache_1.CACHE.get(key);
-    const inflight = DECIMALS_REQUESTS.get(key);
-    if (inflight)
-        return inflight;
-    const fetchPromise = (async () => {
-        try {
-            if (isVault) {
-                const tokenizedVault = (await (0, fetcher_1.fetchTokenizedVault)(address))?.[0];
-                const version = (0, vault_version_1.getVaultVersionV2)(tokenizedVault);
-                let realAddress = address;
-                if (version === 'evm-2') {
-                    realAddress = await (0, exports.getReceiptTokenAddress)(provider, address);
-                }
-                const contract = new ethers_1.Contract(realAddress, [web3_1.MIN_ABIS.decimals], provider);
-                const decimals = Number(await contract.decimals());
-                cache_1.CACHE.set(key, decimals);
-                return decimals;
-            }
-            else {
-                const contract = new ethers_1.Contract(address, [web3_1.MIN_ABIS.decimals], provider);
-                const decimals = Number(await contract.decimals());
-                cache_1.CACHE.set(key, decimals);
-                return decimals;
-            }
-        }
-        catch (e) {
-            logger_1.Logger.log.error('getDecimals', `${address}::${e}`);
-            return undefined;
-        }
-        finally {
-            DECIMALS_REQUESTS.delete(key);
-        }
-    })();
-    DECIMALS_REQUESTS.set(key, fetchPromise);
-    return fetchPromise;
+    try {
+        return await sharedDecimalsRequest(key, () => fetchDecimals(provider, address, isVault));
+    }
+    catch (e) {
+        logger_1.Logger.log.error('getDecimals', `${address}::${e}`);
+        return undefined;
+    }
 };
 exports.getDecimals = getDecimals;
+/**
+ * `decimals()` — `keccak256("decimals()")[0..4]`. Scopes the empty-view-response
+ * retry to exactly the call this reader makes.
+ */
+const DECIMALS_SELECTOR = '0x313ce567';
+/**
+ * Read a token's `decimals()` with the **same cache and stampede protection as
+ * {@link getDecimals}**, but surfacing failures instead of swallowing them, and
+ * retrying the transient ones.
+ *
+ * Two reasons this exists rather than a flag on `getDecimals`:
+ *
+ * 1. **`getDecimals` must keep returning `undefined` on failure** — a dozen
+ *    read paths depend on that. Amount-encoding paths need the opposite: an
+ *    `undefined` reaching `toNormalizedBn` silently means 18 decimals, which
+ *    misencodes the transaction. Here the original error propagates, so the
+ *    caller's `AugustSDKError` keeps its cause and its Sentry grouping.
+ * 2. **Retry.** Providers intermittently return an empty response to
+ *    `decimals()`, which ethers reports as
+ *    `missing revert data (action="call", data="0x313ce567", …)` — a shape a
+ *    deployed ERC-20 cannot legitimately produce, since `decimals()` takes no
+ *    arguments. That is retried here via {@link isEmptyViewResponse} scoped to
+ *    this exact selector, alongside ordinary transport faults
+ *    ({@link isRetryableRpcError}). The empty-view widening applies **only**
+ *    here; everywhere else the strict transport definition stands. A genuine
+ *    revert (`CALL_EXCEPTION` carrying revert data) is never retried.
+ *
+ * Cache is shared with `getDecimals`, so a read-then-write flow against the
+ * same token costs one `decimals()` RPC in total, and N concurrent callers for
+ * an uncached token collapse to one.
+ *
+ * **Exception — an unresolvable chain scope bypasses the cache entirely.** When
+ * {@link resolveProviderScope} cannot determine the chain (a runner with no
+ * resolved network and no connection URL, e.g. a browser provider before its
+ * first request), the only available key is the shared `unknown` bucket. Read
+ * paths happily use that bucket, and this function deliberately does not: the
+ * two paths have different blast radii. A wrong cached `decimals` on a read
+ * renders a wrong number on screen; on a write it misencodes an amount the user
+ * then *signs*. The collision needed — the same address being a different token
+ * with different decimals on two chains, within one process, across a
+ * mid-session chain switch — is narrow, but "no worse than the read path" is
+ * not the bar for a value that ends up in a transaction. In that case the read
+ * is neither served from nor written to the cache, and it also skips the
+ * in-flight dedup map, since joining another caller under an untrusted key
+ * would reintroduce exactly the collision being avoided. Retries still apply;
+ * the only thing forgone is the RPC saving.
+ *
+ * RPC cost: 1 on a cache miss, 0 on a hit, up to 3 on a miss that keeps
+ * faulting (~750ms of added latency in the worst case before it gives up).
+ * Always ≥1 when the chain scope is unresolvable.
+ *
+ * @param runner - Provider or signer to read through. A signer is unwrapped to
+ *   its provider for cache scoping, so it shares entries with reads on the
+ *   same chain.
+ * @param address - Token address. Read directly as an ERC-20 — pass the
+ *   receipt-token address yourself for an `evm-2` vault's share scale.
+ * @param tag - Low-cardinality label for retry breadcrumbs (e.g.
+ *   `'vaultDeposit:poolDecimals'`).
+ * @returns The token's decimals.
+ * @throws The underlying read error once retries are exhausted, or immediately
+ *   when the failure is neither a transport fault nor an empty view response.
+ *
+ * @example
+ * ```ts
+ * // Amount encoding must not proceed on a guessed scale.
+ * const decimals = await getDecimalsOrThrow(signer, token, 'deposit:decimals');
+ * const amount = toNormalizedBn(userInput, decimals);
+ * ```
+ */
+const getDecimalsOrThrow = async (runner, address, tag) => {
+    const read = () => (0, chain_error_1.retryOnTransientRpc)(tag, () => fetchDecimals(runner, address, false), { address }, (error) => (0, chain_error_1.isRetryableRpcError)(error) ||
+        (0, chain_error_1.isEmptyViewResponse)(error, DECIMALS_SELECTOR));
+    const scope = resolveProviderScope(runner);
+    if (scope === null) {
+        // Untrusted key: no cache read, no cache write, no dedup. See the note
+        // above — a mis-scoped decimals value here gets signed into a transaction.
+        logger_1.Logger.log.warn(tag, 'decimals cache bypassed: chain scope unresolved', {
+            address,
+        });
+        return read();
+    }
+    const key = decimalsCacheKey(scope, address);
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    return sharedDecimalsRequest(key, read);
+};
+exports.getDecimalsOrThrow = getDecimalsOrThrow;
 /** @internal */
 const WHITELISTED_ASSETS_REQUESTS = new Map();
 /**
@@ -320,14 +501,96 @@ const getWhitelistedAssets = async (provider, whitelistAddress) => {
     return fetchPromise;
 };
 exports.getWhitelistedAssets = getWhitelistedAssets;
+/**
+ * Read an `evm-2` vault's receipt (LP) token address via `lpTokenAddress()`,
+ * retrying only the transient transport faults and surfacing everything else
+ * unchanged.
+ *
+ * Why this exists: `lpTokenAddress()` sits immediately before the receipt-token
+ * `decimals()` read on every `evm-2` write path (approve / deposit / request
+ * redeem / swap-router deposit). Those `decimals()` reads were hardened against
+ * provider blips ({@link getDecimalsOrThrow}); the `lpTokenAddress()` read one
+ * line above them was not, so a single truncated `eth_call` response still
+ * failed the whole write with
+ * `missing revert data (action="call", data="0xf5ae497a", …)` — observed in
+ * production against a mainnet vault whose `lpTokenAddress()` demonstrably
+ * returns a real address when the provider is healthy.
+ *
+ * **This must never hide a misrouted vault, and does not.** `lpTokenAddress()`
+ * exists *only* on `evm-2` vaults. A vault wrongly classified as `evm-2` returns
+ * empty returndata for it, deterministically and forever, and that empty
+ * response is byte-identical to the transient one — it is the *only* signal the
+ * SDK gets that its version routing was wrong. So the retry here is deliberately
+ * shaped to preserve that signal:
+ *
+ * - it is **bounded** (3 attempts, ~750ms of backoff in total — see
+ *   `retryOnTransientRpc`), never open-ended;
+ * - on exhaustion it **rethrows the original error object**, with its identity,
+ *   message, `code` and `transaction.data` intact, so the caller's
+ *   `AugustSDKError` cause and Sentry grouping are exactly what they are today;
+ * - it has **no fallback**: it never substitutes another address, never resolves
+ *   the vault address itself, and never resolves `null`/`undefined`. It either
+ *   returns a real receipt-token address or throws.
+ *
+ * Net effect: a blip costs a retry, a misroute costs three `eth_call`s and then
+ * fails exactly as loudly as before.
+ *
+ * **Deliberately not cached.** Unlike `decimals()`, the vault→receipt-token
+ * mapping is not memoized here. Caching it would make a misroute's first
+ * (failed) probe and every subsequent one diverge, and would put a
+ * vault-identity mapping in the cache on the money path. The lenient, cached
+ * reader is {@link getReceiptTokenAddress} — use that on read paths that can
+ * tolerate `undefined`.
+ *
+ * RPC cost: exactly 1 `eth_call` on success; at most 3 when the provider keeps
+ * faulting.
+ *
+ * @param runner - Provider or signer to read through.
+ * @param vault - Address of the `evm-2` tokenized vault.
+ * @param tag - Low-cardinality label for retry breadcrumbs (e.g.
+ *   `'vaultRequestRedeem:receiptToken'`).
+ * @returns The vault's receipt (LP) token address. Never `null`/`undefined`.
+ * @throws The underlying read error, unmodified, once the bounded retries are
+ *   exhausted — or immediately when the failure is neither a transport fault nor
+ *   an empty response to this exact selector (e.g. a genuine revert carrying
+ *   revert data).
+ *
+ * @example
+ * ```ts
+ * const receiptToken = await getReceiptTokenAddressOrThrow(
+ *   signer,
+ *   vault,
+ *   'vaultRequestRedeem:receiptToken',
+ * );
+ * const decimals = await getDecimalsOrThrow(signer, receiptToken, 'tag');
+ * ```
+ */
+const getReceiptTokenAddressOrThrow = async (runner, vault, tag) => {
+    const contract = new ethers_1.Contract(vault, TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2, runner);
+    return (0, chain_error_1.retryOnTransientRpc)(tag, () => contract.lpTokenAddress(), { vault }, (error) => (0, chain_error_1.isRetryableRpcError)(error) ||
+        (0, chain_error_1.isEmptyViewResponse)(error, chain_error_1.LP_TOKEN_ADDRESS_SELECTOR));
+};
+exports.getReceiptTokenAddressOrThrow = getReceiptTokenAddressOrThrow;
 /** @internal */
 const RECEIPT_TOKEN_REQUESTS = new Map();
 /**
  * Fetch receipt token address from tokenized vault contract.
  * Results are cached to minimize RPC calls.
+ *
+ * **Never throws** — a failed read logs at error level and resolves
+ * `undefined`, which several read paths depend on. The underlying
+ * `lpTokenAddress()` call is made through
+ * {@link getReceiptTokenAddressOrThrow}, so a transient provider blip is
+ * absorbed by a bounded retry before that happens; a deterministic failure (a
+ * vault that has no `lpTokenAddress()` because it is not `evm-2`) still resolves
+ * `undefined` after the attempts are spent, exactly as before. Callers on a
+ * money path must use {@link getReceiptTokenAddressOrThrow} directly instead —
+ * an `undefined` receipt-token address there would silently mis-address a
+ * `decimals()` read.
+ *
  * @param provider Web3 provider
  * @param address Tokenized vault contract address
- * @returns Receipt token address
+ * @returns Receipt token address, or `undefined` when the read failed.
  */
 const getReceiptTokenAddress = async (provider, address) => {
     if (!(address && provider))
@@ -340,8 +603,7 @@ const getReceiptTokenAddress = async (provider, address) => {
         return inflight;
     const fetchPromise = (async () => {
         try {
-            const vaultContract = new ethers_1.Contract(address, TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2, provider);
-            const receiptToken = (await vaultContract.lpTokenAddress());
+            const receiptToken = await (0, exports.getReceiptTokenAddressOrThrow)(provider, address, 'getReceiptTokenAddress');
             cache_1.CACHE.set(key, receiptToken);
             return receiptToken;
         }

package/lib/core/index.d.ts

@@ -1,5 +1,6 @@
 export * from './fetcher';
 export * from './base.class';
+export * from './attribution';
 export * from './auth';
 export * from './logger';
 export * from './analytics';

package/lib/core/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./fetcher"), exports);
 __exportStar(require("./base.class"), exports);
+__exportStar(require("./attribution"), exports);
 __exportStar(require("./auth"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./analytics"), exports);

package/lib/evm/methods/crossChainVault.js

@@ -58,6 +58,7 @@ exports.isCrossChainOperation = isCrossChainOperation;
 exports.getAvailableChains = getAvailableChains;
 exports.formatCrossChainError = formatCrossChainError;
 exports.getLayerZeroScanUrl = getLayerZeroScanUrl;
+const attribution_1 = require("../../core/attribution");
 const core_1 = require("../../core");
 const crossChain_1 = require("../types/crossChain");
 const OFT_1 = require("../../abis/OFT");
@@ -537,6 +538,7 @@ async function approveCrossChain(tokenAddress, spenderAddress, amount, walletCli
         abi: OFT_1.ABI_CROSS_CHAIN_ERC20,
         functionName: 'approve',
         args: [spenderAddress, amount],
+        dataSuffix: (0, attribution_1.getAttributionSuffix)(),
     });
     const receipt = await publicClient.waitForTransactionReceipt({
         hash: hash,
@@ -625,6 +627,7 @@ async function crossChainVaultDeposit(props) {
         args: txInputs.txArgs,
         value: txInputs.messageValue,
         gas: gasLimit,
+        dataSuffix: (0, attribution_1.getAttributionSuffix)(props.userChainId),
     });
     // 5. Wait for confirmation
     const receipt = await publicClient.waitForTransactionReceipt({
@@ -709,6 +712,7 @@ async function crossChainVaultRedeem(props) {
         args: txInputs.txArgs,
         value: txInputs.messageValue,
         gas: gasLimit,
+        dataSuffix: (0, attribution_1.getAttributionSuffix)(props.config.hubChainId),
     });
     // 6. Wait for confirmation
     const receipt = await publicClient.waitForTransactionReceipt({