upshift-config 0.5.14

package/lib/core/helpers/vaults.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultSubgraphUrl = exports.SUBGRAPH_POOL_URLS = exports.AVAX_PRICE_FEED_ADDRESS = exports.REWARD_DISTRIBUTOR_ADDRESS = exports.getVaultVersionV2 = exports.getVaultVersion = exports.getAddressChainType = exports.isBadVault = exports.isBadTransaction = void 0;
+exports.getVaultSymbol = getVaultSymbol;
+exports.resolveFeeWaived = resolveFeeWaived;
+const ethers_1 = require("ethers");
+const vaults_1 = require("../constants/vaults");
+const web3_1 = require("./web3");
+const chain_address_1 = require("./chain-address");
+const vault_metadata_1 = require("../vault-metadata");
+const logger_1 = require("../logger");
+/** @internal */
+const VAULT_SYMBOLS_LOWERCASE = Object.fromEntries(Object.entries(vaults_1.VAULT_SYMBOLS).map(([k, v]) => [k.toLowerCase(), v]));
+/**
+ * Bad transactions that should be ignored
+ * these transactions are usually from tests and can skew data
+ */
+const isBadTransaction = (hash, chainId) => {
+    const badTxs = {
+        1: [
+            // farmBOLD deposit test tx due to a decimal error
+            '0xaba75b16e74a7a2457bfdcded853edd2bb4d3b305919baf84fb1f6b54b864889',
+            '0xc4c30185198672cbc91a95520d1bf91634ece37c199b2f1f15d29e8290c7ed4b',
+            '0x8e319576413897d1750f16bb93c7f59759b5bbafcb5bd9ef956f6bc0b0314aef',
+            '0x49057f8ea86b84a21808269558474686c9de02d31dc9e03a201b61104afbcdd3',
+            '0x7146dd528423705e225dd508f06cc6b4dab490c767400652ef82e7c96031359d',
+            '0x826340b2f376e71795177e9d68fee07e0c45263b45d22c36327db81db36d70a6',
+            '0xd79f4cf16dd4a794809448bf021bb64b6bfd22fb42094403baad4da5664b7519',
+        ],
+    };
+    if (chainId in badTxs) {
+        return badTxs[chainId].includes(hash);
+    }
+    return false;
+};
+exports.isBadTransaction = isBadTransaction;
+const isBadVault = (address) => {
+    if (!address)
+        return false;
+    if ((0, vault_version_1.getAddressChainType)(address) !== 'evm')
+        return false;
+    switch ((0, ethers_1.getAddress)(address)) {
+        case (0, ethers_1.getAddress)('0x706162790b601A8514c18718d0c63C9D1268e89C'):
+            return true;
+        case (0, ethers_1.getAddress)('0xd684AF965b1c17D628ee0d77cae94259c41260F4'):
+            return true; // ETH: sUSDe
+        case (0, ethers_1.getAddress)('0xB78dAf3fD674B81ebeaaa88d711506fa069E1C5E'):
+            return true; // ETH: ETH Optimizer
+        case (0, ethers_1.getAddress)('0x4e2D90f0307A93b54ACA31dc606F93FE6b9132d2'):
+            return true; // Base: LBTC
+        case (0, ethers_1.getAddress)('0x18a5a3D575F34e5eBa92ac99B0976dBe26f9F869'):
+            return true; // ETH: LBTC
+        case (0, ethers_1.getAddress)('0xD0b717ef23817b1a127139830Cf0FcD449ef74F0'):
+            return true; // BNB: Sienna USDT Tulipa
+        case (0, ethers_1.getAddress)('0xeb402fc96C7ed2f889d837C9976D6d821c1B5f01'):
+            return true; // ETH: Kelp TAC Vault
+        case (0, ethers_1.getAddress)('0xEBac5e50003d4B17Be422ff9775043cD61002f7f'):
+            return true; // ETH: Upshift BTC
+        case (0, ethers_1.getAddress)('0x419386E3Ef42368e602720CC458e00c0B28c47A7'):
+            return true; // ETH: Kelp TAC Vault
+        default:
+            return false;
+    }
+};
+exports.isBadVault = isBadVault;
+const vault_version_1 = require("./vault-version");
+Object.defineProperty(exports, "getAddressChainType", { enumerable: true, get: function () { return vault_version_1.getAddressChainType; } });
+Object.defineProperty(exports, "getVaultVersion", { enumerable: true, get: function () { return vault_version_1.getVaultVersion; } });
+Object.defineProperty(exports, "getVaultVersionV2", { enumerable: true, get: function () { return vault_version_1.getVaultVersionV2; } });
+// Used for Upshift
+const REWARD_DISTRIBUTOR_ADDRESS = (chainId) => {
+    switch (chainId) {
+        case 43114:
+            return [
+                '0xAeAc5f82B140c0f7309f7E9Ec43019062A5e5BE2',
+                '0xd3e653A9f6F3d96B26Dd4487a53D151140B697C4',
+            ];
+        default:
+            return ['0x0000000000000000000000000000000000000000'];
+    }
+};
+exports.REWARD_DISTRIBUTOR_ADDRESS = REWARD_DISTRIBUTOR_ADDRESS;
+// Used for Upshift
+const AVAX_PRICE_FEED_ADDRESS = (chainId) => {
+    switch (chainId) {
+        case 1:
+            return '0xFF3EEb22B5E3dE6e705b44749C2559d704923FD7';
+        default:
+            return '0x';
+    }
+};
+exports.AVAX_PRICE_FEED_ADDRESS = AVAX_PRICE_FEED_ADDRESS;
+async function getVaultSymbol(vault, provider) {
+    if ((0, chain_address_1.isStellarAddress)(vault)) {
+        logger_1.Logger.log.warn('getVaultSymbol', `Vault symbol lookup is not yet supported for Stellar vaults: ${vault}`);
+        return undefined;
+    }
+    const address = (0, ethers_1.getAddress)(vault);
+    let vaultsMetadata = {};
+    try {
+        vaultsMetadata = await (0, vault_metadata_1.fetchVaultMetadata)();
+    }
+    catch (e) {
+        logger_1.Logger.log.error('getVaultSymbol:fetchMetadata', e, { vault });
+    }
+    const entries = Object.entries(vaultsMetadata);
+    for (const [_, metadata] of entries) {
+        if (metadata.address.toLowerCase() === address.toLowerCase()) {
+            return metadata.symbol;
+        }
+    }
+    const hardcodedSymbol = vaults_1.VAULT_SYMBOLS[address] ??
+        VAULT_SYMBOLS_LOWERCASE[address.toLowerCase()];
+    if (hardcodedSymbol) {
+        return hardcodedSymbol;
+    }
+    const symbol = await (0, web3_1.getSymbol)(provider, vault);
+    return symbol;
+}
+/**
+ * @deprecated
+ * Replaced by SUBGRAPH_VAULT_URLS which are subgraphs deployed on Goldsky.
+ */
+const SUBGRAPH_POOL_URLS = (apiKey, chainId, pool) => {
+    if (chainId === 999) {
+        if (!pool) {
+            throw new Error(`Pool address is required for chainId ${chainId}`);
+        }
+        switch (pool) {
+            // hbHYPE
+            case '0x96C6cBB6251Ee1c257b2162ca0f39AA5Fa44B1FB':
+                return {
+                    999: 'https://api.goldsky.com/api/public/project_cm9g0xy3o4j6v01vd34r3hvv9/subgraphs/august-hyperevm-hyperbeat/1.0.0/gn',
+                };
+            // hbBTC
+            case '0xc061d38903b99aC12713B550C2CB44B221674F94':
+                return {
+                    999: 'https://api.goldsky.com/api/public/project_cm9g0xy3o4j6v01vd34r3hvv9/subgraphs/august-hyperevm-hbBTC/1.0.0/gn',
+                };
+            default:
+                throw new Error(`Unsupported pool for chainId ${chainId}: ${pool}`);
+        }
+    }
+    const urls = {
+        1: `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/BtbHLe7XtX2x9Ude9PKv2uagNHj6JYhjjFcimxvk7NPD`,
+        8453: `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/E96gN4ZAmtCwLfsYccy3TqCTBbizGPWssFFeZfJ5QSQP`,
+        43114: `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/Ho15f2DBGndTMAYx9bPxJzasQRsAd5oLdci4oZvWs2u6`,
+        42161: `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/BrqNoj6FWm678yFRKdVWBncwt3zUnpbA3u4n9A9puUSg`,
+        56: `https://gateway.thegraph.com/api/${apiKey}/subgraphs/id/4BDCXZvSBuNGX3ck6C6nTGos7Dg5SxjfHMjrKnQz4YE2`,
+    };
+    if (chainId && !(chainId in urls)) {
+        throw new Error(`Unsupported chainId: ${chainId}. Supported chains: ${Object.keys(urls).join(', ')}`);
+    }
+    return urls;
+};
+exports.SUBGRAPH_POOL_URLS = SUBGRAPH_POOL_URLS;
+/**
+ * Previously fabricated a Goldsky subgraph URL from the chain name and vault
+ * symbol. That guess is unreliable and produced dead endpoints:
+ * - The path segment `/v1/subgraphs/name/goldsky/` is legacy hosted-service
+ *   syntax, not Goldsky's current scheme (cf. {@link SUBGRAPH_VAULT_URLS}).
+ * - The chain name isn't the subgraph slug — ethers reports Citrea's network as
+ *   `unknown`, and mainnet as `mainnet` where the subgraph uses `eth`.
+ * - A vault's symbol isn't its subgraph name — e.g. on-chain `EctUSD` vs the
+ *   deployed `earn-ctusd`.
+ *
+ * A fabricated URL 404s silently, so a missing subgraph reads as "no data"
+ * rather than an error (this masked the Citrea Earn ctUSD outage). Subgraph URLs
+ * must now come from backend vault metadata (`fetchVaultMetadata → subgraph`).
+ * This returns `undefined` so callers hit their existing "Missing Subgraph"
+ * branch (warn + Slack alert) instead of querying a dead endpoint.
+ *
+ * @param _network - Unused. Kept for call-site compatibility.
+ * @param _symbol - Unused. Kept for call-site compatibility.
+ * @returns `undefined` — the SDK no longer guesses subgraph URLs.
+ * @deprecated Resolve subgraph URLs from `fetchVaultMetadata`; do not rely on a
+ *   generated fallback.
+ */
+const getDefaultSubgraphUrl = (_network, _symbol) => {
+    return undefined;
+};
+exports.getDefaultSubgraphUrl = getDefaultSubgraphUrl;
+/**
+ * Resolve whether a single fee (management or performance) is currently waived.
+ *
+ * Backend-driven, per AUGUST-5584. This centralizes logic that previously lived —
+ * and diverged — across two upshift-app components. The resolution is deliberately
+ * split between the backend and the SDK:
+ *
+ * - The backend `isFeeWaivedToggle` (`platform_fee_override.is_fee_waived`) is both
+ *   the master enable AND the TVL latch. Retool config takes precedence over live
+ *   TVL, and the backend flips this flag `false` once live TVL crosses the
+ *   configured threshold. That flip is one-way: if TVL later falls back below the
+ *   threshold the waiver does NOT re-apply. The SDK therefore does no TVL math and
+ *   never reads `latest_reported_tvl` here — trusting the flag preserves the latch.
+ * - The **date** window is time-dependent, so it cannot be a static DB flag; the SDK
+ *   evaluates it live against the clock.
+ *
+ * Resolution:
+ * - Toggle off  → never waived (also the only "hide" path once TVL trips the latch).
+ * - Toggle on, both date and TVL blank → indefinite manual waiver → waived.
+ * - Toggle on with a date window → waived while `now < waivedUntilDate`.
+ * - Toggle on with a TVL threshold configured → waived (the backend keeps the toggle
+ *   on only while live TVL is under the threshold).
+ *
+ * @param isFeeWaivedToggle - Backend master/TVL-latch flag. `false` ⇒ never waived.
+ * @param waivedUntilDate - ISO datetime string the waiver runs until, or `null` for
+ *   no date window. An unparseable string yields `NaN`, which is never `> now`, so
+ *   it correctly contributes no date-based waiver.
+ * @param waivedUntilTvl - Configured TVL threshold in whole USD, or `null`. Used only
+ *   to detect that a TVL-based waiver was set (values `<= 0` are treated as unset);
+ *   the threshold comparison itself is owned by the backend.
+ * @param now - Clock, injected for deterministic testing. Defaults to `new Date()`.
+ * @returns `true` if the UI should present this fee as "Fee Waived" right now.
+ * @example
+ * ```ts
+ * // Toggle on, 30-day window still open → waived.
+ * resolveFeeWaived(true, '2099-01-01T00:00:00Z', null); // true
+ * // Toggle off overrides everything → not waived.
+ * resolveFeeWaived(false, '2099-01-01T00:00:00Z', 10_000_000); // false
+ * ```
+ */
+function resolveFeeWaived(isFeeWaivedToggle, waivedUntilDate, waivedUntilTvl, now = new Date()) {
+    // Master toggle off ⇒ never waived. Also satisfies the one-way TVL latch: the
+    // backend has already flipped this false when live TVL crossed the threshold.
+    if (!isFeeWaivedToggle)
+        return false;
+    const isDateActive = waivedUntilDate != null && new Date(waivedUntilDate) > now;
+    const isTvlConfigured = waivedUntilTvl != null && waivedUntilTvl > 0;
+    // Toggle on but neither trigger configured ⇒ indefinite manual waiver.
+    if (waivedUntilDate == null && !isTvlConfigured)
+        return true;
+    return isDateActive || isTvlConfigured;
+}
+//# sourceMappingURL=vaults.js.map

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

@@ -0,0 +1,353 @@
+import { ethers, Interface, type InterfaceAbi, JsonRpcProvider } from 'ethers';
+import type { Abi } from 'abitype';
+import type { TypedContract } from '../../types/typed-contract';
+import type { IAddress, IContractRunner, IInfuraOptions } from '../../types';
+/**
+ * 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
+ */
+export declare const determineBlockCutoff: (chain: number) => 120000 | 3456000 | 150000;
+/**
+ * Approximate block time in seconds per chain.
+ * Used to estimate time ranges from block counts.
+ * @param chain - Chain ID
+ * @returns Seconds per block
+ */
+export declare const determineSecondsPerBlock: (chain: number) => number;
+/**
+ * Get block interval for paginated historical queries per chain.
+ * Respects RPC eth_getLogs range limits.
+ * @param chain Chain ID
+ * @returns Block interval for pagination
+ */
+export declare const determineBlockSkipInternal: (chain: number) => 1000 | 8000 | 10000;
+/**
+ * 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`.
+ */
+export declare const determineRpcBatchMaxCount: (rpcUrl: string) => number;
+/**
+ * Retrieve chain ID from web3 provider.
+ * Handles both initialized and uninitialized provider states.
+ * @param provider Web3 provider instance
+ * @returns Numeric chain ID
+ */
+export declare const getChainId: (provider: IContractRunner) => Promise<number>;
+/**
+ * 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
+ */
+export declare function createContract<const TAbi extends Abi>({ provider, address, abi, }: {
+    address: string;
+    provider: IContractRunner;
+    abi: TAbi;
+}): TypedContract<TAbi> | undefined;
+/**
+ * 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.
+ */
+export declare const createProvider: (rpcUrl: string, chainId?: number) => JsonRpcProvider;
+/**
+ * Create or reuse a cached Infura provider for the specified chain.
+ * @param infura Configuration with chain ID and API key
+ */
+export declare const getInfuraProvider: (infura: IInfuraOptions) => JsonRpcProvider;
+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
+ * @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
+ * decimals/symbol reads downstream.
+ * @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, or `undefined` when the read failed.
+ */
+export declare const getReceiptTokenAddress: (provider: IContractRunner, address: IAddress) => Promise<`0x${string}`>;
+/**
+ * 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
+ */
+export declare const getSymbol: (provider: IContractRunner, address: IAddress | undefined, isVault?: boolean) => Promise<string>;
+/**
+ * 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
+ */
+export declare function getTokenMetadata(provider: IContractRunner, asset: IAddress, meta: ('symbol' | 'decimals' | 'name' | 'totalSupply')[]): Promise<any[]>;
+/**
+ * Fetch management fee percentage from vault contract.
+ * Performs static call first to check if method exists.
+ * @todo fix so that when lending pool does not have "managementFeePercent", to not break everything
+ * @param provider Web3 provider
+ * @param address Vault contract address
+ * @returns Management fee as percentage or undefined if not supported
+ */
+export declare const getManagementFeePercent: (provider: IContractRunner, address: IAddress) => Promise<number>;
+/**
+ * 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
+ */
+export declare function simulateTransaction(provider: IContractRunner, abi: string[] | any, functionName: string, options?: {
+    args?: (string | number | bigint)[][];
+    from?: string;
+    to?: string;
+}): Promise<boolean | ethers.Result>;
+/**
+ * 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
+ */
+export declare function checkAddress(address: string, logger?: any, type?: 'wallet' | 'contract'): boolean;
+type ILoanOracleFeeCategories = 'LOAN.REPAY.INTERESTS';
+/**
+ * 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
+ */
+export declare function getLoanOracleFeeRate(provider: IContractRunner, category_id: ILoanOracleFeeCategories, address: IAddress, chainId?: number): Promise<number>;
+/**
+ * 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
+ */
+export declare function getHistoricalContractData(provider: IContractRunner, contractAddress: IAddress, abi: Interface | InterfaceAbi, methodName: string, args: (string | number | bigint | boolean)[], startBlock: number, endBlock: number, blockInterval?: number): Promise<any[]>;
+/**
+ * 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
+ */
+export declare function getHistoricalContractDataByDate(provider: IContractRunner, contractAddress: IAddress, abi: Interface | InterfaceAbi, methodName: string, args: (string | number | bigint | boolean)[], startDate: string | number, endDate: string | number, intervalHours?: number): Promise<any[]>;