@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/helpers/web3.js

@@ -0,0 +1,1034 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getManagementFeePercent = exports.getSymbol = exports.getReceiptTokenAddress = exports.getReceiptTokenAddressOrThrow = exports.getWhitelistedAssets = exports.getDecimalsOrThrow = exports.getDecimals = exports.explorerLink = exports.getInfuraProvider = exports.createProvider = exports.getChainId = exports.determineRpcBatchMaxCount = exports.determineBlockSkipInternal = exports.determineSecondsPerBlock = exports.determineBlockCutoff = void 0;
+exports.createContract = createContract;
+exports.getTokenMetadata = getTokenMetadata;
+exports.simulateTransaction = simulateTransaction;
+exports.checkAddress = checkAddress;
+exports.getLoanOracleFeeRate = getLoanOracleFeeRate;
+exports.getHistoricalContractData = getHistoricalContractData;
+exports.getHistoricalContractDataByDate = getHistoricalContractDataByDate;
+const ethers_1 = require("ethers");
+const errors_1 = require("../errors");
+const cache_1 = require("../cache");
+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");
+const TokenizedVaultV2WhitelistedAssets_1 = require("../../abis/TokenizedVaultV2WhitelistedAssets");
+//import { getVaultVersion } from './helpers.vaults';
+const vault_version_1 = require("./vault-version");
+/**
+ * Web3 Helper Utilities
+ *
+ * Core utilities for blockchain interaction:
+ * - Provider Management: createProvider, getInfuraProvider, getChainId
+ * - Contract Helpers: createContract, getDecimals, getSymbol, getTokenMetadata
+ * - Transaction Utilities: simulateTransaction, checkAddress
+ * - Historical Queries: getHistoricalContractData, getHistoricalContractDataByDate
+ * - Oracle Integration: getLoanOracleFeeRate
+ * - Block Utilities: determineBlockCutoff, determineBlockSkipInternal
+ */
+/**
+ * Get maximum block range for historical queries per chain.
+ * Prevents RPC timeouts by limiting lookback window.
+ * @param chain Chain ID
+ * @returns Maximum number of blocks to query
+ */
+const determineBlockCutoff = (chain) => {
+    switch (chain) {
+        case 56:
+            return 120_000;
+        case 43114:
+            return 120_000;
+        case 143:
+            return 3_456_000;
+        default:
+            return 150_000;
+    }
+};
+exports.determineBlockCutoff = determineBlockCutoff;
+/**
+ * Approximate block time in seconds per chain.
+ * Used to estimate time ranges from block counts.
+ * @param chain - Chain ID
+ * @returns Seconds per block
+ */
+const determineSecondsPerBlock = (chain) => {
+    switch (chain) {
+        case 143: // Monad ~500ms
+            return 0.5;
+        case 56: // BSC ~2s
+        case 43114: // Avalanche ~2s
+            return 2;
+        default: // Ethereum ~12s
+            return 12;
+    }
+};
+exports.determineSecondsPerBlock = determineSecondsPerBlock;
+/**
+ * Get block interval for paginated historical queries per chain.
+ * Respects RPC eth_getLogs range limits.
+ * @param chain Chain ID
+ * @returns Block interval for pagination
+ */
+const determineBlockSkipInternal = (chain) => {
+    switch (chain) {
+        case 43114:
+            return 8_000;
+        case 56:
+            return 8_000;
+        case 143: // Monad — Alchemy limits eth_getLogs to 1000 blocks
+            return 1_000;
+        case 999: // HyperEVM — rpc.hypurrscan.io limits eth_getLogs to 1000 blocks
+            return 1_000;
+        case 4114: // Citrea — rpc.mainnet.citrea.xyz rejects `to - from >= 1000`
+            // ("query exceeds max block range 1000"). The redemption-history chunker
+            // queries `[end - blockSkip, end]`, so `to - from === blockSkip`; 999 is
+            // the largest value the RPC accepts.
+            return 999;
+        default:
+            // 10k blocks is the eth_getLogs range cap enforced by every mainstream
+            // provider (Alchemy, Infura, dRPC, QuickNode). The previous 50k default
+            // was rejected outright with JSON-RPC -32600 ("You can make eth_getLogs
+            // requests with up to a 10000 block range") on Ethereum mainnet, which
+            // failed `getVaultRedemptionHistory` for every vault on an unlisted
+            // chain. RPC-count impact: a 150k-block cutoff now costs 15 getLogs
+            // calls instead of 3, batched 20-concurrent, so still one round trip.
+            return 10_000;
+    }
+};
+exports.determineBlockSkipInternal = determineBlockSkipInternal;
+/**
+ * Default batch cap. Chosen to stay under the smallest limit among the
+ * providers we route to by default (e.g. rpc.hypurrscan.io rejects > 20).
+ */
+const DEFAULT_RPC_BATCH_MAX_COUNT = 10;
+/**
+ * Maximum JSON-RPC calls ethers may coalesce into a single batched HTTP
+ * request for a given endpoint.
+ *
+ * Providers advertise wildly different batch limits and reject the whole batch
+ * — not the excess — when exceeded, so one oversized batch fails every call
+ * inside it. dRPC's free tier caps batches at 3, which made every Mezo read
+ * fail with `server response 500 … "Batch of more than 3 requests are not
+ * allowed"` (the single highest-volume SDK error in production).
+ *
+ * Detection is host-based rather than chain-based because the limit is a
+ * property of the endpoint, not the chain: the same chain served by a
+ * self-hosted node has no such cap.
+ *
+ * @param rpcUrl - The RPC endpoint URL. Unparseable values fall back to the
+ *   conservative default rather than throwing.
+ * @returns Batch size cap to pass to ethers as `batchMaxCount`.
+ */
+const determineRpcBatchMaxCount = (rpcUrl) => {
+    let host = '';
+    try {
+        host = new URL(rpcUrl).hostname.toLowerCase();
+    }
+    catch {
+        return DEFAULT_RPC_BATCH_MAX_COUNT;
+    }
+    // dRPC free tier: "Batch of more than 3 requests are not allowed".
+    if (host === 'drpc.org' || host.endsWith('.drpc.org'))
+        return 3;
+    return DEFAULT_RPC_BATCH_MAX_COUNT;
+};
+exports.determineRpcBatchMaxCount = determineRpcBatchMaxCount;
+/**
+ * Retrieve chain ID from web3 provider.
+ * Handles both initialized and uninitialized provider states.
+ * @param provider Web3 provider instance
+ * @returns Numeric chain ID
+ */
+const getChainId = async (provider) => {
+    try {
+        if (!provider?._network) {
+            return Number((await provider.getNetwork()).chainId);
+        }
+        else {
+            return Number(provider?._network.chainId);
+        }
+    }
+    catch (e) {
+        return Number((await provider.getNetwork()).chainId);
+    }
+};
+exports.getChainId = getChainId;
+/**
+ * Create ethers contract instance with address validation.
+ * @param provider Web3 provider for contract calls
+ * @param address Contract address (must be checksummed)
+ * @param abi Contract ABI (must be declared with `as const`)
+ * @returns Strongly-typed contract instance or undefined if address invalid
+ */
+function createContract({ provider, address, abi, }) {
+    const goodAddress = checkAddress(address);
+    if (!goodAddress)
+        return;
+    const contract = new ethers_1.Contract(address, abi, provider);
+    if (!contract) {
+        logger_1.Logger.log.error('createContract', 'contract does not exist on connected chain');
+        return;
+    }
+    return contract;
+}
+/**
+ * Create or reuse a cached JSON-RPC provider.
+ * Passing `chainId` enables ethers' `staticNetwork` to skip the `eth_chainId`
+ * round-trip on first use.
+ *
+ * @param rpcUrl RPC endpoint URL — must be a non-empty string.
+ * @param chainId Optional chain ID — enables staticNetwork
+ * @throws Error with a clear, remediable message when `rpcUrl` is missing or
+ *   empty. Without this guard, ethers v6 silently defaults to
+ *   `http://localhost:8545` and surfaces a cryptic
+ *   `network is not available yet (NETWORK_ERROR)` on the first RPC call.
+ */
+const createProvider = (rpcUrl, chainId) => {
+    if (typeof rpcUrl !== 'string' || rpcUrl.trim().length === 0) {
+        const forChain = chainId ? ` for chain ${chainId}` : '';
+        throw new Error(`createProvider: no RPC URL provided${forChain}. ` +
+            'Pass an RPC URL when constructing UpshiftSDK ' +
+            '(`new UpshiftSDK({ providers: { [chainId]: url } })`), ' +
+            `or set the UPSHIFT_RPC_${chainId ?? '<chainId>'} environment variable.`);
+    }
+    const cacheKey = chainId ? `${rpcUrl}|${chainId}` : rpcUrl;
+    if (cache_1.CACHE.has(cacheKey))
+        return cache_1.CACHE.get(cacheKey);
+    // batchMaxCount respects server-side batch limits — providers reject the
+    // entire batch when it is exceeded (see determineRpcBatchMaxCount).
+    const batchMaxCount = (0, exports.determineRpcBatchMaxCount)(rpcUrl);
+    const provider = chainId
+        ? new ethers_1.JsonRpcProvider(rpcUrl, ethers_1.Network.from(chainId), {
+            staticNetwork: ethers_1.Network.from(chainId),
+            batchMaxCount,
+        })
+        : new ethers_1.JsonRpcProvider(rpcUrl, undefined, {
+            batchMaxCount,
+        });
+    cache_1.CACHE.set(cacheKey, provider);
+    return provider;
+};
+exports.createProvider = createProvider;
+/**
+ * Create or reuse a cached Infura provider for the specified chain.
+ * @param infura Configuration with chain ID and API key
+ */
+const getInfuraProvider = (infura) => {
+    let baseUrl = 'https://';
+    switch (infura.chainId) {
+        case 8453: {
+            baseUrl = baseUrl + 'base-mainnet';
+            break;
+        }
+        case 43114: {
+            baseUrl = baseUrl + 'avalanche-mainnet';
+            break;
+        }
+        case 137: {
+            baseUrl = baseUrl + 'polygon-mainnet';
+            break;
+        }
+        case 42161: {
+            baseUrl = baseUrl + 'arbitrum-mainnet';
+            break;
+        }
+        default: {
+            baseUrl = baseUrl + 'mainnet';
+            break;
+        }
+    }
+    const url = `${baseUrl}.infura.io/v3/${infura.apiKey}`;
+    return (0, exports.createProvider)(url, infura.chainId);
+};
+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, 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
+ * resolved its network (i.e. before its first successful request, when
+ * `staticNetwork` was not supplied at construction). Accessing it directly
+ * here used to leak that error out of every cached read (`getDecimals`,
+ * `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 resolveProviderScope(runner) {
+    const provider = runner?.provider ?? runner;
+    let chainId;
+    try {
+        const net = provider
+            ._network;
+        chainId = net?.chainId;
+    }
+    catch {
+        // ethers v6 throws when the lazy network hasn't been detected yet.
+        chainId = undefined;
+    }
+    if (chainId !== undefined && chainId !== null) {
+        return `chain:${String(chainId)}`;
+    }
+    const conn = provider._getConnection?.();
+    if (conn?.url)
+        return `url:${conn.url}`;
+    return null;
+}
+/**
+ * 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, undefined, false, false))?.[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 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.
+ *
+ * Transient transport faults (provider rate limits, socket resets, an empty
+ * response to `decimals()`) are logged at `warn` — a breadcrumb, not a
+ * standalone Sentry issue — since the caller sees the same `undefined` either
+ * way. Everything else is logged at `error`. The read itself is **not**
+ * retried here; that is opt-in via {@link getDecimalsOrThrow}.
+ *
+ * @param provider Web3 provider
+ * @param address Token contract address or Solana mint
+ * @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) {
+        logger_1.Logger.log.info('getDecimals', 'address is zero address');
+        return 0;
+    }
+    if ((0, chain_address_1.isSolanaAddress)(address))
+        return constants_1.fallbackDecimals;
+    if (!(address && provider))
+        return;
+    const key = decimalsCacheKey(providerScope(provider), address);
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    try {
+        return await sharedDecimalsRequest(key, () => fetchDecimals(provider, address, isVault));
+    }
+    catch (e) {
+        // Severity split. A provider rate-limit or socket fault is not a defect in
+        // the SDK or the caller's input — the read resolves `undefined` either way,
+        // exactly as documented, and logging it at error level made a QuickNode
+        // `50/second request limit reached` burst the fourth highest-volume issue
+        // in Sentry with nothing actionable in it. Genuine failures (a non-ERC-20
+        // at this address, a real revert) stay at error.
+        //
+        // Note this only changes the log level. The no-retry contract of this
+        // lenient reader is deliberate and unchanged — callers that must not
+        // proceed on an unknown scale use `getDecimalsOrThrow`, which retries.
+        const isTransient = (0, chain_error_1.isRetryableRpcError)(e) || (0, chain_error_1.isEmptyViewResponse)(e, DECIMALS_SELECTOR);
+        if (isTransient) {
+            logger_1.Logger.log.warn('getDecimals', {
+                address,
+                reason: 'transient RPC failure',
+                message: e instanceof Error ? e.message : String(e),
+            });
+        }
+        else {
+            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 `UpshiftSDKError` 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();
+/**
+ * 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
+ * decimals/symbol reads downstream.
+ * @internal
+ */
+const getWhitelistedAssets = async (provider, whitelistAddress) => {
+    if (!(whitelistAddress && provider)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'getWhitelistedAssets: provider and whitelistAddress are required');
+    }
+    const key = `whitelisted-assets-${providerScope(provider)}-${whitelistAddress}`;
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    const inflight = WHITELISTED_ASSETS_REQUESTS.get(key);
+    if (inflight)
+        return inflight;
+    const fetchPromise = (async () => {
+        try {
+            const contract = new ethers_1.Contract(whitelistAddress, TokenizedVaultV2WhitelistedAssets_1.ABI_TOKENIZED_VAULT_V2_WHITELISTED_ASSETS, provider);
+            const list = (await contract.getWhitelistedAssets());
+            cache_1.CACHE.set(key, list, { ttl: 5 * 60 * 1000 });
+            return list;
+        }
+        finally {
+            WHITELISTED_ASSETS_REQUESTS.delete(key);
+        }
+    })();
+    WHITELISTED_ASSETS_REQUESTS.set(key, fetchPromise);
+    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
+ *   `UpshiftSDKError` 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, or `undefined` when the read failed.
+ */
+const getReceiptTokenAddress = async (provider, address) => {
+    if (!(address && provider))
+        return;
+    const key = `receipt-token-${providerScope(provider)}-${address}`;
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    const inflight = RECEIPT_TOKEN_REQUESTS.get(key);
+    if (inflight)
+        return inflight;
+    const fetchPromise = (async () => {
+        try {
+            const receiptToken = await (0, exports.getReceiptTokenAddressOrThrow)(provider, address, 'getReceiptTokenAddress');
+            cache_1.CACHE.set(key, receiptToken);
+            return receiptToken;
+        }
+        catch (e) {
+            logger_1.Logger.log.error('getReceiptTokenAddress', e);
+            return undefined;
+        }
+        finally {
+            RECEIPT_TOKEN_REQUESTS.delete(key);
+        }
+    })();
+    RECEIPT_TOKEN_REQUESTS.set(key, fetchPromise);
+    return fetchPromise;
+};
+exports.getReceiptTokenAddress = getReceiptTokenAddress;
+/** @internal */
+const SYMBOL_REQUESTS = new Map();
+/**
+ * Fetch token symbol from contract.
+ * Results are cached to minimize RPC calls.
+ * @param provider Web3 provider
+ * @param address Token contract address
+ * @returns Token symbol string
+ */
+const getSymbol = async (provider, address, isVault = true) => {
+    if (address === ethers_1.ZeroAddress) {
+        logger_1.Logger.log.info('getSymbol', 'address is zero address');
+        return 'N/A';
+    }
+    if (!(address && provider))
+        return;
+    const key = `symbol-${providerScope(provider)}-${address}`;
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    const inflight = SYMBOL_REQUESTS.get(key);
+    if (inflight)
+        return inflight;
+    const fetchPromise = (async () => {
+        try {
+            if (isVault) {
+                const tokenizedVault = (await (0, fetcher_1.fetchTokenizedVault)(address, undefined, false, false))?.[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.symbol], provider);
+                const symbol = (await contract.symbol());
+                cache_1.CACHE.set(key, symbol);
+                return symbol;
+            }
+            else {
+                const contract = new ethers_1.Contract(address, [web3_1.MIN_ABIS.symbol], provider);
+                const symbol = (await contract.symbol());
+                cache_1.CACHE.set(key, symbol);
+                return symbol;
+            }
+        }
+        catch (e) {
+            // Recovered failure, not an incident: the caller gets `undefined` and
+            // renders without a symbol. Logging it at `error` made every transient
+            // RPC hiccup ("socket hang up", connection reset) a standalone Sentry
+            // issue — ~24k events across one grouping, none actionable — and the
+            // interpolated `${address}::${e}` message put the token address in the
+            // issue title, so each address produced its own group.
+            //
+            // As a warning it becomes a breadcrumb on whatever the caller ultimately
+            // reports, with the address and reason as structured fields.
+            logger_1.Logger.log.warn('getSymbol', {
+                address,
+                isVault,
+                reason: e instanceof Error ? e.message : String(e),
+            });
+            return undefined;
+        }
+        finally {
+            SYMBOL_REQUESTS.delete(key);
+        }
+    })();
+    SYMBOL_REQUESTS.set(key, fetchPromise);
+    return fetchPromise;
+};
+exports.getSymbol = getSymbol;
+/**
+ * Batch fetch multiple token metadata fields in a single call.
+ * Efficiently retrieves name, symbol, decimals, and totalSupply.
+ * @param provider Web3 provider
+ * @param asset Token contract address
+ * @param meta Array of metadata fields to fetch
+ * @returns Array of metadata values in same order as requested
+ */
+async function getTokenMetadata(provider, asset, meta) {
+    if (!asset)
+        return [];
+    function buildAbi() {
+        const abiArr = [];
+        if (meta?.includes('name'))
+            abiArr.push(web3_1.MIN_ABIS.name);
+        if (meta?.includes('symbol'))
+            abiArr.push(web3_1.MIN_ABIS.symbol);
+        if (meta?.includes('decimals'))
+            abiArr.push(web3_1.MIN_ABIS.decimals);
+        if (meta?.includes('totalSupply'))
+            abiArr.push(web3_1.MIN_ABIS.totalSupply);
+        return abiArr;
+    }
+    try {
+        const contract = new ethers_1.Contract(asset, buildAbi(), provider);
+        const getterArr = [];
+        if (meta?.includes('name'))
+            getterArr.push(contract.name());
+        if (meta?.includes('symbol'))
+            getterArr.push(contract.symbol());
+        if (meta?.includes('decimals'))
+            getterArr.push(contract.decimals());
+        if (meta?.includes('totalSupply'))
+            getterArr.push(contract.totalSupply());
+        return await Promise.all(getterArr);
+    }
+    catch (e) {
+        logger_1.Logger.log.error('getTokenMetadata', e);
+        return [];
+    }
+}
+/**
+ * Fetch management fee percentage from vault contract.
+ *
+ * A single `eth_call` to `managementFeePercent()`. Vaults that do not expose
+ * the method (older lending pools) revert, which is absorbed and reported as
+ * `undefined` — the previous implementation issued an identical `staticCall`
+ * probe first, doubling the RPC cost for no extra information since a view
+ * call that reverts fails the same way either time.
+ *
+ * @param provider Web3 provider
+ * @param address Vault contract address
+ * @returns Management fee as a percentage (basis points ÷ 100), or `undefined`
+ *   when the vault does not support the method or the call fails.
+ * @worstCaseRpcCalls 1 — one `eth_call`.
+ */
+const getManagementFeePercent = async (provider, address) => {
+    if (!(address && provider))
+        return;
+    try {
+        const contract = new ethers_1.Contract(address, [web3_1.MIN_ABIS.managementFeePercent], provider);
+        const fee = (await contract.managementFeePercent());
+        return Number(fee) / 100;
+    }
+    catch (e) {
+        logger_1.Logger.log.error('getManagementFeePercent', e);
+        return undefined;
+    }
+};
+exports.getManagementFeePercent = getManagementFeePercent;
+/**
+ * Simulate contract transaction without executing on-chain.
+ * Useful for testing transaction viability before sending.
+ * @param provider Web3 provider
+ * @param abi Contract ABI
+ * @param functionName Function to simulate
+ * @param options Transaction parameters including args, from, to
+ * @returns Decoded function result or false if simulation fails
+ */
+async function simulateTransaction(provider, abi, functionName, options) {
+    try {
+        const customInterface = new ethers_1.Interface(abi);
+        const callData = customInterface.encodeFunctionData(functionName, options?.args);
+        const response = await provider.call({
+            from: options?.from,
+            to: options?.to,
+            data: callData,
+        });
+        if (!response)
+            return false;
+        return customInterface.decodeFunctionResult(functionName, response);
+    }
+    catch (e) {
+        logger_1.Logger.log.error('simulateTransaction', e);
+        if (String(e).includes('reverted with reason string "denied"'))
+            return true;
+        return false;
+    }
+}
+/**
+ * Validate Ethereum address format and checksum.
+ * @param address Address string to validate
+ * @param logger Optional logger for error messages
+ * @param type Context type for logging
+ * @returns True if address is valid and checksummed
+ */
+function checkAddress(address, logger, type = 'contract') {
+    const _logger = logger ?? console;
+    if (!address) {
+        _logger.error(type, 'address is undefined');
+        return false;
+    }
+    if (typeof address !== 'string') {
+        _logger.error(type, 'address not of string type:', String(typeof address), String(address));
+        return false;
+    }
+    if (!(0, ethers_1.isAddress)(address)) {
+        _logger.error(type, 'address not checksummed:', String(address));
+        return false;
+    }
+    return true;
+}
+/**
+ * Fetch dynamic fee rate from on-chain oracle contract.
+ * Used for calculating loan interest repayment fees.
+ * @param provider Web3 provider
+ * @param category_id Fee category identifier
+ * @param address Context address for fee calculation
+ * @param chainId Optional chain ID (auto-detected if not provided)
+ * @returns Fee rate as decimal number
+ */
+async function getLoanOracleFeeRate(provider, category_id, address, chainId) {
+    if (!(0, ethers_1.isAddress)(address)) {
+        logger_1.Logger.log.error('getLoanOracleFee', 'address is undefined or not a valid address');
+        return;
+    }
+    let _chainId = chainId;
+    if (!chainId) {
+        const chainIdRes = await (0, exports.getChainId)(provider);
+        _chainId = Number(chainIdRes);
+    }
+    if (!web3_1.ORACLE_CONTRACTS?.[_chainId]) {
+        logger_1.Logger.log.warn('getLoanOracleFeeRate', 'no oracle address for', _chainId);
+        return Number(0);
+    }
+    const oracleContract = createContract({
+        provider,
+        address: web3_1.ORACLE_CONTRACTS[_chainId],
+        abi: abis_1.ABI_FEE_ORACLE,
+    });
+    const hashedCategory = (0, ethers_1.keccak256)((0, ethers_1.toUtf8Bytes)(category_id));
+    const rawFee = await oracleContract.getContextFeeRate(hashedCategory, (0, ethers_1.getAddress)(address));
+    return Number((0, ethers_1.formatUnits)(rawFee, 6));
+}
+/**
+ * Query historical contract state across a block range.
+ * Useful for reconstructing historical data like TVL over time.
+ * @param provider Web3 provider
+ * @param contractAddress Target contract address
+ * @param abi Contract ABI
+ * @param methodName View function to call
+ * @param args Function arguments
+ * @param startBlock Starting block number
+ * @param endBlock Ending block number (current block if not specified)
+ * @param blockInterval Blocks between each query
+ * @returns Array of results with block numbers and timestamps
+ */
+async function getHistoricalContractData(provider, contractAddress, abi, methodName, args = [], startBlock, endBlock, blockInterval = 1000) {
+    const contract = new ethers_1.ethers.Contract(contractAddress, abi, provider);
+    const results = [];
+    if (!endBlock) {
+        endBlock = await provider.getBlockNumber();
+    }
+    for (let blockNumber = startBlock; blockNumber <= endBlock; blockNumber += blockInterval) {
+        try {
+            const contractAtBlock = contract.connect(provider);
+            const result = await contractAtBlock[methodName](...args, {
+                blockTag: blockNumber,
+            });
+            const block = await provider.getBlock(blockNumber);
+            results.push({
+                blockNumber,
+                timestamp: block.timestamp,
+                result: result.toString(),
+            });
+        }
+        catch (error) {
+            logger_1.Logger.log.error('getHistoricalContractData', `Error at block ${blockNumber}`, error);
+        }
+    }
+    return results;
+}
+/**
+ * Query historical contract state at regular time intervals.
+ * Uses binary search to find blocks closest to target timestamps.
+ * @param provider Web3 provider
+ * @param contractAddress Target contract address
+ * @param abi Contract ABI
+ * @param methodName View function to call
+ * @param args Function arguments
+ * @param startDate Start date (string or timestamp)
+ * @param endDate End date (string or timestamp)
+ * @param intervalHours Hours between each query
+ * @returns Array of results with dates, blocks, and values
+ */
+async function getHistoricalContractDataByDate(provider, contractAddress, abi, methodName, args = [], startDate, endDate, intervalHours = 24) {
+    const contract = new ethers_1.ethers.Contract(contractAddress, abi, provider);
+    const startTimestamp = Math.floor(new Date(startDate).getTime() / 1000);
+    const endTimestamp = Math.floor(new Date(endDate).getTime() / 1000);
+    const intervalSeconds = intervalHours * 3600;
+    const results = [];
+    // Binary search to find block closest to timestamp
+    async function findBlockByTimestamp(targetTimestamp) {
+        let left = 1;
+        let right = await provider.getBlockNumber();
+        let closestBlock = null;
+        while (left <= right) {
+            const mid = Math.floor((left + right) / 2);
+            const block = await provider.getBlock(mid);
+            if (!block) {
+                right = mid - 1;
+                continue;
+            }
+            if (block.timestamp === targetTimestamp) {
+                return block;
+            }
+            if (!closestBlock ||
+                Math.abs(block.timestamp - targetTimestamp) <
+                    Math.abs(closestBlock.timestamp - targetTimestamp)) {
+                closestBlock = block;
+            }
+            if (block.timestamp < targetTimestamp) {
+                left = mid + 1;
+            }
+            else {
+                right = mid - 1;
+            }
+        }
+        return closestBlock;
+    }
+    try {
+        // Loop through time intervals
+        for (let timestamp = startTimestamp; timestamp <= endTimestamp; timestamp += intervalSeconds) {
+            // Find closest block to timestamp
+            const block = await findBlockByTimestamp(timestamp);
+            if (!block) {
+                logger_1.Logger.log.warn('getHistoricalContractDataByDate', `No block found for timestamp ${timestamp}`);
+                continue;
+            }
+            // Make the contract call
+            const result = await contract[methodName](...args, {
+                blockTag: block.number,
+            });
+            results.push({
+                date: new Date(timestamp * 1000).toISOString(),
+                blockNumber: block.number,
+                timestamp,
+                result: result.toString(),
+            });
+        }
+        return results;
+    }
+    catch (error) {
+        logger_1.Logger.log.error('getHistoricalContractDataByDate', error);
+        throw error;
+    }
+}
+//# sourceMappingURL=web3.js.map