upshift-sdk 8.20.1

package/lib/core/fetcher.js

@@ -0,0 +1,903 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSafeCache = exports.getSafeCache = exports.CACHE = void 0;
+exports.setSdkRequestTimeout = setSdkRequestTimeout;
+exports.getSdkRequestTimeout = getSdkRequestTimeout;
+exports.setPublicApiBaseUrl = setPublicApiBaseUrl;
+exports.getPublicApiBaseUrl = getPublicApiBaseUrl;
+exports.fetchAugustWithKey = fetchAugustWithKey;
+exports.fetchAugustPublic = fetchAugustPublic;
+exports.fetchAugustWithBearer = fetchAugustWithBearer;
+exports.isRetryableError = isRetryableError;
+exports.withRetry = withRetry;
+exports.fetchTokenizedVault = fetchTokenizedVault;
+exports.fetchTokenizedVaults = fetchTokenizedVaults;
+exports.fetchTokenPrice = fetchTokenPrice;
+exports.fetchTokenPriceByAddress = fetchTokenPriceByAddress;
+exports.fetchTokenizedVaultLoans = fetchTokenizedVaultLoans;
+exports.fetchTokenizedVaultSubaccountLoans = fetchTokenizedVaultSubaccountLoans;
+exports.fetchVaultHistoricalTimeseries = fetchVaultHistoricalTimeseries;
+exports.promiseSettle = promiseSettle;
+const core_1 = require("./helpers/core");
+const ethers_1 = require("ethers");
+const abis_1 = require("../abis");
+const lru_cache_1 = require("lru-cache");
+const chain_address_1 = require("./helpers/chain-address");
+const chain_error_1 = require("./helpers/chain-error");
+const fetcher_1 = require("../services/coingecko/fetcher");
+const logger_1 = require("./logger");
+const ethers_2 = require("ethers");
+const web3_1 = require("./constants/web3");
+const core_2 = require("./constants/core");
+const vault_version_1 = require("./helpers/vault-version");
+const analytics_1 = require("./analytics");
+const sanitize_1 = require("./analytics/sanitize");
+const errors_1 = require("./errors");
+/** Map an HTTP status to the appropriate typed SDK error subclass. */
+function errorFromResponseStatus(status, message, options) {
+    if (status === 401) {
+        return new errors_1.AugustAuthError('AUTH_UNAUTHORIZED', message, options);
+    }
+    if (status === 403) {
+        return new errors_1.AugustAuthError('AUTH_FORBIDDEN', message, options);
+    }
+    if (status === 429) {
+        return new errors_1.AugustRateLimitError(message, options);
+    }
+    return new errors_1.AugustServerError(status, message, options);
+}
+let SDK_REQUEST_TIMEOUT_OVERRIDE = null;
+/**
+ * Override the default request timeout used by every August fetcher helper
+ * when the caller doesn't supply a per-call `timeoutMs`. Pass `null` (or
+ * call with no arguments) to clear the override and fall back to the
+ * compiled-in `REQUEST_TIMEOUT_MS`.
+ *
+ * @param ms - Positive number of milliseconds to wait before aborting, or
+ *   `null` to clear.
+ */
+function setSdkRequestTimeout(ms = null) {
+    if (ms === null) {
+        SDK_REQUEST_TIMEOUT_OVERRIDE = null;
+        return;
+    }
+    if (!Number.isFinite(ms) || ms <= 0) {
+        logger_1.Logger.log.warn('setSdkRequestTimeout', 'Ignoring non-positive timeout', {
+            ms,
+        });
+        return;
+    }
+    SDK_REQUEST_TIMEOUT_OVERRIDE = ms;
+}
+/**
+ * Read the active default request timeout — the SDK-level override if set,
+ * otherwise the compiled-in `REQUEST_TIMEOUT_MS`.
+ */
+function getSdkRequestTimeout() {
+    return SDK_REQUEST_TIMEOUT_OVERRIDE ?? core_2.REQUEST_TIMEOUT_MS;
+}
+let PUBLIC_API_BASE_OVERRIDE = null;
+/**
+ * Override the base URL used for `WEBSERVER_URL.public` requests — the
+ * unauthenticated vault-catalog API that `getVault` / `fetchTokenizedVault`
+ * (and the other `fetchAugustPublic` callers) read from. Defaults to the
+ * compiled-in prod base (`https://api.augustdigital.io/api/v1`); pass `null`
+ * (or call with no arguments) to clear.
+ *
+ * Intended for non-prod deployments that run against an ISOLATED backend
+ * (e.g. a staging API): set it once at construction via
+ * `IAugustBase.publicApiBaseUrl` so a staging-only vault resolves. Production
+ * leaves it unset, so behaviour is unchanged.
+ *
+ * This is a process-global override on the fetcher helpers. The SDK constructor
+ * calls it on EVERY instantiation (with `null` when `publicApiBaseUrl` is
+ * omitted), so the last `AugustSDK` instantiated is authoritative — a prod
+ * instance resets it to the default even after a prior staging instance set it.
+ * An invalid or non-http(s) URL is treated as "no override": it RESETS to the
+ * compiled-in default (warned) rather than retaining a prior value, so a bad env
+ * value can neither break fetches nor silently leave a previous instance's base
+ * in place.
+ *
+ * Whenever the effective base CHANGES, the shared public-response cache is
+ * cleared, so catalog data fetched from the previous backend is never served for
+ * the new one (e.g. a prod-cached vault leaking into a staging instance). Base
+ * changes happen at construction, when the cache is cold, so this is ~free.
+ *
+ * @param url - Absolute http(s) base URL (trailing slash is trimmed). `null`, or
+ *   an invalid / non-http(s) value, resets to the compiled-in public base.
+ */
+function setPublicApiBaseUrl(url = null) {
+    const previous = PUBLIC_API_BASE_OVERRIDE;
+    if (url === null) {
+        PUBLIC_API_BASE_OVERRIDE = null;
+    }
+    else {
+        let parsed = null;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed ||
+            (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')) {
+            // Reset to the default rather than retaining a stale prior override, so
+            // each construction stays authoritative and a bad env value fails safe to
+            // prod instead of inheriting another instance's base.
+            logger_1.Logger.log.warn('setPublicApiBaseUrl', 'Ignoring invalid/non-http(s) URL; resetting to the default public base', { url });
+            PUBLIC_API_BASE_OVERRIDE = null;
+        }
+        else {
+            // Store WITHOUT a trailing slash: buildAugustUrl concatenates
+            // `${base}${relativeUrl}` (relativeUrl starts with '/'), so a trailing
+            // slash on the base would produce a double slash.
+            PUBLIC_API_BASE_OVERRIDE = url.replace(/\/+$/, '');
+        }
+    }
+    if (PUBLIC_API_BASE_OVERRIDE !== previous) {
+        // The public base moved (or reset). Drop cached public-catalog responses
+        // keyed against the previous base (see fetchTokenizedVault(s) etc.) so they
+        // aren't served for the new backend.
+        cache_1.CACHE.clear();
+    }
+}
+/**
+ * Read the active base for the `public` server — the SDK-level override if set,
+ * otherwise the compiled-in `WEBSERVER_URL.public`.
+ */
+function getPublicApiBaseUrl() {
+    return PUBLIC_API_BASE_OVERRIDE ?? core_2.WEBSERVER_URL.public;
+}
+/**
+ * Combine the per-request timeout signal with any caller-supplied signal.
+ * Uses `AbortSignal.any` (Node 22+) with a manual relay fallback.
+ *
+ * Returns `timedOut()` (a closure over an internal flag set when the timeout
+ * fires) so the caller can distinguish "we timed out" from "caller cancelled",
+ * and `cleanup()` to release the fallback-relay listener.
+ */
+function buildRequestAbortSignal(options) {
+    const timeoutMs = options?.timeoutMs ?? SDK_REQUEST_TIMEOUT_OVERRIDE ?? core_2.REQUEST_TIMEOUT_MS;
+    const timeoutController = new AbortController();
+    let didTimeout = false;
+    const timeoutId = setTimeout(() => {
+        didTimeout = true;
+        timeoutController.abort();
+    }, timeoutMs);
+    let signal = timeoutController.signal;
+    // No-op by default; replaced with a real listener-removal closure only when
+    // the manual relay fallback path below registers an 'abort' listener.
+    let relayCleanup = () => undefined;
+    if (options?.signal) {
+        // Capture in a local so the cleanup closure below keeps the non-nullable
+        // narrowing (a closure over `options.signal` would otherwise be re-widened).
+        const callerSignal = options.signal;
+        if (typeof AbortSignal.any === 'function') {
+            signal = AbortSignal.any([timeoutController.signal, callerSignal]);
+        }
+        else if (callerSignal.aborted) {
+            timeoutController.abort();
+        }
+        else {
+            const relay = () => timeoutController.abort();
+            callerSignal.addEventListener('abort', relay, { once: true });
+            relayCleanup = () => callerSignal.removeEventListener('abort', relay);
+        }
+    }
+    return {
+        signal,
+        timeoutId,
+        timeoutMs,
+        timedOut: () => didTimeout,
+        cleanup: () => {
+            clearTimeout(timeoutId);
+            relayCleanup();
+        },
+    };
+}
+let _overrideDeprecationWarned = false;
+function warnOverrideDeprecation(callerTag) {
+    if (_overrideDeprecationWarned)
+        return;
+    _overrideDeprecationWarned = true;
+    // Deliberately a direct console.warn, not Logger.log.warn: a deprecation
+    // notice must surface in the integrator's console in every environment.
+    // Logger.log.warn would downgrade it to a prod-silent Sentry breadcrumb.
+    // biome-ignore lint/suspicious/noConsole: integrator-facing deprecation notice must surface in every environment; Logger.log.warn would downgrade it to a prod-silent Sentry breadcrumb.
+    console.warn(`[@augustdigital/sdk] ${callerTag}: option "override" is deprecated and will be removed in a future major version. Pass a valid apiKey instead.`);
+}
+/**
+ * LRU cache for API responses and frequently accessed data.
+ * 24-hour TTL with 1000 item capacity.
+ */
+/**
+ * Read a response header tolerantly. Real `fetch` returns a `Headers` instance,
+ * but some test mocks supply a plain object; both shapes are supported here.
+ */
+function readResponseHeader(headers, name) {
+    if (!headers)
+        return undefined;
+    const h = headers;
+    if (typeof h.get === 'function') {
+        return h.get(name) ?? undefined;
+    }
+    const v = headers[name];
+    return typeof v === 'string' ? v : undefined;
+}
+const cache_1 = require("./cache");
+Object.defineProperty(exports, "CACHE", { enumerable: true, get: function () { return cache_1.CACHE; } });
+Object.defineProperty(exports, "getSafeCache", { enumerable: true, get: function () { return cache_1.getSafeCache; } });
+Object.defineProperty(exports, "setSafeCache", { enumerable: true, get: function () { return cache_1.setSafeCache; } });
+/**
+ * Dedicated cache for token prices with short TTL to prevent rate limiting.
+ * 30-second TTL with 500 item capacity.
+ */
+const PRICE_CACHE = new lru_cache_1.LRUCache({
+    max: 500,
+    ttl: 1000 * 30, // 30 seconds
+    allowStale: false,
+});
+/**
+ * Cache for failed price requests to prevent retry storms.
+ * 5-second TTL to allow quick retry after temporary failures.
+ */
+const PRICE_ERROR_CACHE = new lru_cache_1.LRUCache({
+    max: 100,
+    ttl: 1000 * 5, // 5 seconds
+    allowStale: false,
+});
+/**
+ * In-flight price requests to prevent duplicate simultaneous API calls.
+ */
+const PRICE_REQUESTS = new Map();
+/**
+ * Build an August backend URL, rejecting unknown server keys and any
+ * `relativeUrl` that would escape the configured origin.
+ * Throws `AugustValidationError` with `code: 'INVALID_URL'`.
+ */
+function buildAugustUrl(server, relativeUrl) {
+    const serverKey = server;
+    // The `public` base is overridable (setPublicApiBaseUrl / IAugustBase
+    // .publicApiBaseUrl) so non-prod deployments can point vault-catalog reads at
+    // an isolated backend. Resolved once here via getPublicApiBaseUrl() (single
+    // source of truth), so the origin check below validates against the OVERRIDDEN
+    // origin.
+    const base = serverKey === 'public' ? getPublicApiBaseUrl() : core_2.WEBSERVER_URL[serverKey];
+    if (!base) {
+        throw new errors_1.AugustValidationError('INVALID_URL', `Unknown August server "${String(server)}". Expected one of: ${Object.keys(core_2.WEBSERVER_URL).join(', ')}`);
+    }
+    if (typeof relativeUrl !== 'string' || relativeUrl.length === 0) {
+        throw new errors_1.AugustValidationError('INVALID_URL', 'relativeUrl must be a non-empty string');
+    }
+    // Reject anything that looks like a scheme or protocol-relative authority.
+    if (/^\s*[a-z][a-z0-9+.-]*:|^\s*\/\//i.test(relativeUrl)) {
+        throw new errors_1.AugustValidationError('INVALID_URL', `relativeUrl must be a path, not an absolute or protocol-relative URL`);
+    }
+    // Concat (rather than `new URL(rel, base)`) preserves base paths like /api/v1
+    // when relativeUrl starts with `/`. Origin check below is a second line.
+    const candidate = `${base}${relativeUrl}`;
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        throw new errors_1.AugustValidationError('INVALID_URL', `Invalid URL path: ${(0, sanitize_1.sanitizeString)(relativeUrl)}`);
+    }
+    const baseOrigin = new URL(base).origin;
+    if (url.origin !== baseOrigin) {
+        throw new errors_1.AugustValidationError('INVALID_URL', `URL origin mismatch: refusing to fetch ${url.origin} from a "${serverKey}" request scoped to ${baseOrigin}`);
+    }
+    return url.toString();
+}
+/**
+ * Make authenticated requests to August backend services using API key.
+ * Automatically logs errors with correlation IDs for debugging.
+ * @param apiKey - August API key for authentication
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
+async function fetchAugustWithKey(apiKey, relativeUrl, options) {
+    if (options?.override) {
+        warnOverrideDeprecation('fetchAugustWithKey');
+    }
+    if (!apiKey && !options?.override) {
+        throw new errors_1.AugustAuthError('AUTH_MISSING_KEY', 'fetchAugustWithKey: apiKey is required (set keys.august on the SDK constructor, or pass an explicit apiKey).');
+    }
+    const defaultHeaders = {
+        'x-api-key': apiKey,
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    const { signal: requestSignal, timeoutMs: effectiveTimeoutMs, timedOut, cleanup, } = buildRequestAbortSignal(options);
+    const startTime = performance.now();
+    const server = options?.server || 'production';
+    try {
+        const safeUrl = buildAugustUrl(server, relativeUrl);
+        const res = await fetch(safeUrl, {
+            headers: {
+                ...defaultHeaders,
+                ...options?.headers,
+            },
+            method: options?.method ?? 'GET',
+            body: JSON.stringify(options?.data),
+            signal: requestSignal,
+        });
+        cleanup();
+        // Track API call
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, res.status, server);
+        const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
+        const logger = logger_1.Logger.getLogger();
+        if (!res.ok || res.status !== 200) {
+            if (correlationId && logger) {
+                logger.setTag('correlation_id', correlationId);
+            }
+            const error = errorFromResponseStatus(res.status, `Request failed: ${res.status}`, { correlationId });
+            logger?.captureException(error, { correlationId, status: res.status });
+            throw error;
+        }
+        return res;
+    }
+    catch (error) {
+        cleanup();
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, 0, server);
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (err.name === 'AbortError') {
+            if (!timedOut()) {
+                throw err;
+            }
+            const timeoutError = new errors_1.AugustTimeoutError((0, sanitize_1.sanitizeString)(`Request timeout after ${effectiveTimeoutMs / 1000}s: ${relativeUrl}`), effectiveTimeoutMs);
+            logger_1.Logger.log.error('fetchAugustWithKey', timeoutError, { relativeUrl });
+            throw timeoutError;
+        }
+        throw err;
+    }
+}
+/**
+ * Make unauthenticated requests to August public API endpoints.
+ * Used for fetching vault metadata and public market data.
+ * @param relativeUrl - Endpoint path relative to public API base URL
+ * @param options - Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
+async function fetchAugustPublic(relativeUrl, options) {
+    const defaultHeaders = {
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    const { signal: requestSignal, timeoutMs: effectiveTimeoutMs, timedOut, cleanup, } = buildRequestAbortSignal(options);
+    const startTime = performance.now();
+    try {
+        const safeUrl = buildAugustUrl('public', relativeUrl);
+        const res = await fetch(safeUrl, {
+            headers: {
+                ...defaultHeaders,
+                ...options?.headers,
+            },
+            method: options?.method ?? 'GET',
+            body: JSON.stringify(options?.data),
+            signal: requestSignal,
+        });
+        cleanup();
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, res.status, 'public');
+        const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
+        const logger = logger_1.Logger.getLogger();
+        if (!res.ok || res.status !== 200) {
+            if (correlationId && logger) {
+                logger.setTag('correlation_id', correlationId);
+            }
+            const error = errorFromResponseStatus(res.status, `Request failed: ${res.status}`, { correlationId });
+            logger?.captureException(error, { correlationId, status: res.status });
+            throw error;
+        }
+        return res;
+    }
+    catch (error) {
+        cleanup();
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, 0, 'public');
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (err.name === 'AbortError') {
+            if (!timedOut()) {
+                throw err;
+            }
+            const timeoutError = new errors_1.AugustTimeoutError((0, sanitize_1.sanitizeString)(`Request timeout after ${effectiveTimeoutMs / 1000}s: ${relativeUrl}`), effectiveTimeoutMs);
+            logger_1.Logger.log.error('fetchAugustPublic', timeoutError, { relativeUrl });
+            throw timeoutError;
+        }
+        throw err;
+    }
+}
+/**
+ * Make authenticated requests using Bearer token authentication.
+ * Typically used for user-specific operations requiring OAuth tokens.
+ * @param bearerToken - OAuth bearer token
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
+async function fetchAugustWithBearer(bearerToken, relativeUrl, options) {
+    const defaultHeaders = {
+        authorization: `Bearer ${bearerToken}`,
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    const { signal: requestSignal, timeoutMs: effectiveTimeoutMs, timedOut, cleanup, } = buildRequestAbortSignal(options);
+    const startTime = performance.now();
+    const server = options?.server ?? 'production';
+    try {
+        const safeUrl = buildAugustUrl(server, relativeUrl);
+        const res = await fetch(safeUrl, {
+            headers: {
+                ...defaultHeaders,
+                ...options?.headers,
+            },
+            method: options?.method ?? 'GET',
+            body: JSON.stringify(options?.data),
+            signal: requestSignal,
+        });
+        cleanup();
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, res.status, server);
+        const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
+        const logger = logger_1.Logger.getLogger();
+        if (!res.ok || res.status !== 200) {
+            if (correlationId && logger) {
+                logger.setTag('correlation_id', correlationId);
+            }
+            const error = errorFromResponseStatus(res.status, `Request failed: ${res.status}`, { correlationId });
+            logger?.captureException(error, { correlationId, status: res.status });
+            throw error;
+        }
+        return res;
+    }
+    catch (error) {
+        cleanup();
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, 0, server);
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (err.name === 'AbortError') {
+            if (!timedOut()) {
+                throw err;
+            }
+            const timeoutError = new errors_1.AugustTimeoutError((0, sanitize_1.sanitizeString)(`Request timeout after ${effectiveTimeoutMs / 1000}s: ${relativeUrl}`), effectiveTimeoutMs);
+            logger_1.Logger.log.error('fetchAugustWithBearer', timeoutError, { relativeUrl });
+            throw timeoutError;
+        }
+        throw err;
+    }
+}
+/**
+ * Check if an error is network-related and suitable for retry.
+ * Identifies timeouts, connection resets, and fetch failures.
+ */
+function isRetryableError(error) {
+    return ((error instanceof TypeError && error.message.includes('fetch failed')) ||
+        error.name === 'AbortError' ||
+        error.message.includes('ETIMEDOUT') ||
+        error.message.includes('timeout') ||
+        error.message.includes('ECONNRESET') ||
+        error.message.includes('ENOTFOUND') ||
+        error.message.includes('ECONNREFUSED'));
+}
+/**
+ * Wrap async operations with exponential backoff retry logic.
+ * Retries on network errors with increasing delays between attempts.
+ * @param fn - Async function to execute with retry logic
+ * @param maxRetries - Maximum number of retry attempts
+ * @param baseDelay - Initial delay in milliseconds (doubles each retry)
+ * @param shouldRetry - Custom function to determine if error is retryable
+ * @returns Result of successful function execution
+ * @throws Last error if all retries exhausted
+ */
+async function withRetry(fn, maxRetries = 3, baseDelay = 1000, shouldRetry = isRetryableError) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < maxRetries && shouldRetry(error)) {
+                const delay = baseDelay * 2 ** attempt;
+                logger_1.Logger.log.warn('withRetry', `Attempt ${attempt + 1} failed, retrying in ${delay}ms: ${error.message}`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            throw error;
+        }
+    }
+    // Unreachable in practice: the final attempt re-throws inside the loop. This
+    // satisfies the compiler's control-flow analysis without a non-null assertion.
+    throw lastError ?? new Error('withRetry exhausted retries without an error');
+}
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
+ * @returns Array of tokenized vault configurations
+ */
+async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots) {
+    if (!pool) {
+        return [];
+    }
+    // Build cache key based on loading options
+    const keyParts = [`tokenized-vault-${pool}`];
+    if (loadSubaccounts === false)
+        keyParts.push('no-subaccounts');
+    if (loadSnapshots === false)
+        keyParts.push('no-snapshots');
+    const key = keyParts.join('-');
+    let tokenizedVault;
+    const cachedResponse = await (0, cache_1.getSafeCache)(key);
+    if (cachedResponse) {
+        tokenizedVault = cachedResponse;
+    }
+    if (!tokenizedVault) {
+        // Build endpoint URL with optional query parameters
+        let endpoint = core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.byVaultAddress(pool);
+        const params = new URLSearchParams();
+        if (loadSubaccounts === false) {
+            params.set('load_subaccounts', 'false');
+        }
+        if (loadSnapshots === false) {
+            params.set('load_snapshots', 'false');
+        }
+        const queryString = params.toString();
+        if (queryString) {
+            endpoint += `?${queryString}`;
+        }
+        const tokenizedVaultsResponse = await fetchAugustPublic(endpoint, {
+            headers: headers,
+        });
+        tokenizedVault = (await tokenizedVaultsResponse.json());
+        cache_1.CACHE.set(key, tokenizedVault, { ttl: 1000 * 60 * 10 }); // Cache for 10 minutes
+    }
+    // Filter by specific vault if address provided
+    if (pool &&
+        ((0, ethers_1.isAddress)(pool) || (0, chain_address_1.isSolanaAddress)(pool) || (0, chain_address_1.isStellarAddress)(pool))) {
+        return tokenizedVault ? [tokenizedVault] : [];
+    }
+    return [tokenizedVault];
+}
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
+ * @param loadSubaccounts - Optional flag to load subaccounts and EOA operators (defaults to true on API)
+ * @returns Array of tokenized vault configurations
+ */
+async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshots) {
+    // Build cache key based on loading options
+    const keyParts = ['tokenized-vaults'];
+    if (pool)
+        keyParts.push(pool);
+    if (loadSubaccounts === false)
+        keyParts.push('no-subaccounts');
+    if (loadSnapshots === false)
+        keyParts.push('no-snapshots');
+    const key = keyParts.join('-');
+    let tokenizedVaults;
+    const cachedResponse = await (0, cache_1.getSafeCache)(key);
+    if (cachedResponse) {
+        tokenizedVaults = cachedResponse;
+    }
+    if (!tokenizedVaults) {
+        // Build endpoint URL with optional query parameters
+        let endpoint = core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.list;
+        const params = new URLSearchParams();
+        if (loadSubaccounts === false) {
+            params.set('load_subaccounts', 'false');
+        }
+        if (loadSnapshots === false) {
+            params.set('load_snapshots', 'false');
+        }
+        const queryString = params.toString();
+        if (queryString) {
+            endpoint += `?${queryString}`;
+        }
+        const tokenizedVaultsResponse = await fetchAugustPublic(endpoint, {
+            headers: headers,
+        });
+        tokenizedVaults =
+            (await tokenizedVaultsResponse.json());
+        const ttl = 1000 * 60 * 15; // 15 minute cache
+        cache_1.CACHE.set(key, tokenizedVaults, { ttl });
+    }
+    // Filter by specific vault if address provided
+    if (pool &&
+        ((0, ethers_1.isAddress)(pool) || (0, chain_address_1.isSolanaAddress)(pool) || (0, chain_address_1.isStellarAddress)(pool))) {
+        const foundObj = tokenizedVaults.find((t) => t.address.toLowerCase() === pool.toLowerCase());
+        return foundObj ? [foundObj] : [];
+    }
+    return tokenizedVaults;
+}
+/**
+ * Fetch current USD price for a token symbol or vault LP token.
+ * For vault LP tokens, calculates share price using totalAssets/totalSupply ratio.
+ * Falls back to CoinGecko if primary source fails.
+ * @param symbol - Token symbol or contract address
+ * @param provider - Optional web3 provider for on-chain price calculations
+ * @param coinGeckoKey - Optional CoinGecko API key for fallback pricing
+ * @param headers - Monitoring headers for request tracking
+ * @returns Token price in USD
+ */
+async function fetchTokenPrice(symbol, provider, coinGeckoKey, headers) {
+    if (!symbol) {
+        logger_1.Logger.log.error('fetchTokenPrice', 'symbol parameter is undefined');
+        return 0;
+    }
+    // Normalize symbol and apply aliases BEFORE generating cache key
+    let normalizedSymbol = symbol.toLowerCase();
+    normalizedSymbol = normalizedSymbol === 'xbtc' ? 'btc' : normalizedSymbol;
+    normalizedSymbol = normalizedSymbol === 'strbtc' ? 'btc' : normalizedSymbol;
+    // Generate cache key based on normalized symbol and provider presence
+    const cacheKey = `price:${normalizedSymbol}:${provider ? 'with-provider' : 'no-provider'}`;
+    // Check error cache to prevent retry storms after failures
+    const cachedError = PRICE_ERROR_CACHE.get(cacheKey);
+    if (cachedError) {
+        logger_1.Logger.log.info('fetchTokenPrice', `Error cache HIT for ${normalizedSymbol} - throwing cached error`);
+        throw cachedError;
+    }
+    // Check price cache first to avoid rate limiting
+    const cachedPrice = PRICE_CACHE.get(cacheKey);
+    if (cachedPrice !== undefined) {
+        logger_1.Logger.log.info('fetchTokenPrice', `Cache HIT for ${normalizedSymbol}: $${cachedPrice}`);
+        return cachedPrice;
+    }
+    // Check for in-flight request to deduplicate simultaneous calls
+    const inflightRequest = PRICE_REQUESTS.get(cacheKey);
+    if (inflightRequest) {
+        logger_1.Logger.log.info('fetchTokenPrice', `In-flight request deduplication for ${normalizedSymbol}`);
+        return inflightRequest;
+    }
+    // Create the price fetching promise
+    const pricePromise = (async () => {
+        try {
+            const price = await _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers);
+            // Cache the successful result
+            PRICE_CACHE.set(cacheKey, price);
+            // Clear any previous error cache on success
+            PRICE_ERROR_CACHE.delete(cacheKey);
+            return price;
+        }
+        catch (error) {
+            // Cache the error temporarily to prevent retry storms
+            const err = error instanceof Error ? error : new Error(String(error));
+            PRICE_ERROR_CACHE.set(cacheKey, err);
+            logger_1.Logger.log.info('fetchTokenPrice', `Cached error for ${normalizedSymbol}: ${err.message}`);
+            throw err;
+        }
+        finally {
+            // Clean up in-flight request tracking
+            PRICE_REQUESTS.delete(cacheKey);
+        }
+    })();
+    // Track this request to prevent duplicates
+    PRICE_REQUESTS.set(cacheKey, pricePromise);
+    return pricePromise;
+}
+// Normalize both raw integers to the same decimal scale BEFORE dividing —
+// dividing the raw bigints first floors the ratio to ~1 and loses all
+// fractional precision. Returns 1 for an empty vault (priced 1:1).
+function normalizedSharePrice(totalAssets, totalSupply, decimals) {
+    const supply = Number((0, core_1.toNormalizedBn)(totalSupply, decimals).normalized);
+    if (!supply)
+        return 1;
+    return Number((0, core_1.toNormalizedBn)(totalAssets, decimals).normalized) / supply;
+}
+/**
+ * Internal price fetching implementation.
+ * This is separated to allow caching and request deduplication in the public function.
+ */
+async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers) {
+    // Fetch vault metadata to check if symbol is a vault LP token
+    const tokenizedVaults = await fetchTokenizedVaults(undefined, headers, false, false);
+    const vaultArray = tokenizedVaults.map((vault) => ({
+        vault: vault.address,
+        symbol: vault.receipt_token_symbol,
+    }));
+    const foundVaultLpAsset = vaultArray.find((v) => v.symbol?.toLowerCase() === symbol?.toLowerCase());
+    // @todo: handle multi-asset vaults
+    const tokenizedVault = tokenizedVaults.find((vault) => vault.address === foundVaultLpAsset?.vault);
+    const version = (0, vault_version_1.getVaultVersionV2)(tokenizedVault);
+    if (foundVaultLpAsset?.vault && provider && version === 'evm-2') {
+        try {
+            const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset?.vault), abis_1.ABI_TOKENIZED_VAULT_V2, provider);
+            // Same bounded, no-fallback retry the write paths use for this selector
+            // (`getReceiptTokenAddressOrThrow` in `core/helpers/web3`). It cannot be
+            // reused here: `helpers/web3` imports `fetchTokenizedVault` from this
+            // module, so importing it back would be a circular dependency (CLAUDE.md
+            // §9). A transient empty `eth_call` response is absorbed; a vault that
+            // genuinely lacks `lpTokenAddress()` still falls into the catch below
+            // after the attempts are spent.
+            const receiptAddress = await (0, chain_error_1.retryOnTransientRpc)('fetchTokenPrice:receiptToken', () => vaultContract.lpTokenAddress(), { vault: foundVaultLpAsset.vault }, (error) => (0, chain_error_1.isRetryableRpcError)(error) ||
+                (0, chain_error_1.isEmptyViewResponse)(error, chain_error_1.LP_TOKEN_ADDRESS_SELECTOR));
+            const receiptContract = new ethers_2.Contract(receiptAddress, [web3_1.MIN_ABIS.decimals], provider);
+            const decimals = Number(await receiptContract.decimals());
+            const sharePrice = await vaultContract.getSharePrice();
+            return Number((0, core_1.toNormalizedBn)(sharePrice, decimals).normalized);
+        }
+        catch {
+            throw new Error('failed to fetch token price for evm-2 vault');
+        }
+    }
+    // Apply symbol normalization and aliases for API calls
+    let _symbol = symbol?.toLowerCase();
+    _symbol = _symbol === 'xbtc' ? 'btc' : _symbol;
+    _symbol = _symbol === 'strbtc' ? 'btc' : _symbol;
+    try {
+        // Fetch base token price from August backend
+        const res = await fetch(`https://prices.augustdigital.io/price/${_symbol}`, { headers: headers });
+        if (res.status !== 200) {
+            throw new Error(`fetching ${_symbol} price: ${res?.statusText}`);
+        }
+        const json = (await res.json());
+        // For vault LP tokens, calculate share price using on-chain ratio
+        if (foundVaultLpAsset && provider) {
+            const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset.vault), abis_1.ABI_LENDING_POOL_V2, provider);
+            const [totalAssets, totalSupply, rawDecimals] = await Promise.all([
+                vaultContract.totalAssets(),
+                vaultContract.totalSupply(),
+                vaultContract.decimals(),
+            ]);
+            const decimals = Number(rawDecimals);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return json.price * sharePrice;
+        }
+        return json.price;
+    }
+    catch {
+        // Fallback to CoinGecko if primary source fails
+        const fallbackPrice = await (0, fetcher_1.fetchTokenPricesFromCoinGecko)(symbol, coinGeckoKey);
+        if (foundVaultLpAsset && provider) {
+            const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset.vault), abis_1.ABI_LENDING_POOL_V2, provider);
+            const [totalAssets, totalSupply, rawDecimals] = await Promise.all([
+                vaultContract.totalAssets(),
+                vaultContract.totalSupply(),
+                vaultContract.decimals(),
+            ]);
+            const decimals = Number(rawDecimals);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return fallbackPrice * sharePrice;
+        }
+        if (fallbackPrice) {
+            return fallbackPrice;
+        }
+        else {
+            throw new Error('failed to fetch token price');
+        }
+    }
+}
+/**
+ * Fetch token price by contract address and chain ID from August price server.
+ * @param address - Token contract address
+ * @param chainId - Network chain ID
+ * @param headers - Optional monitoring headers for request tracking
+ * @returns Token price in USD, or 0 if not found
+ */
+async function fetchTokenPriceByAddress(address, chainId, headers) {
+    if (!address || !chainId) {
+        return 0;
+    }
+    try {
+        const url = new URL(`${core_2.PRICE_SERVER_URL}/price_by_address_chain`);
+        url.searchParams.set('address', address);
+        url.searchParams.set('chain', chainId.toString());
+        url.searchParams.set('method', 'contract');
+        const res = await fetch(url.toString(), {
+            headers: {
+                accept: 'application/json',
+                ...headers,
+            },
+        });
+        if (res.status !== 200) {
+            throw new Error(`Failed to fetch price for ${address} on chain ${chainId}: ${res.statusText}`);
+        }
+        const json = (await res.json());
+        return json.price || 0;
+    }
+    catch (e) {
+        logger_1.Logger.log.warn('fetchTokenPriceByAddress', `Failed to fetch price for ${address} on chain ${chainId}: ${e}`);
+        return 0;
+    }
+}
+/**
+ * Fetch active loans for a specific vault from backend API.
+ * Results are cached per vault and chain to reduce API calls.
+ * @param pool - Vault address
+ * @param chainId - Network chain ID
+ * @param headers - Monitoring headers for request tracking
+ * @returns Array of active loan objects
+ */
+async function fetchTokenizedVaultLoans(pool, chainId, headers) {
+    const key = `loans-${chainId}-${pool}`;
+    let loans;
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
+    }
+    else {
+        const tokenizedVaultsResponse = await fetchAugustPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.loans(pool, chainId, true), { headers: headers });
+        loans = (await tokenizedVaultsResponse.json()).loans;
+        await (0, cache_1.setSafeCache)(key, loans);
+    }
+    return loans?.filter((l) => l.state.toLowerCase() === 'active');
+}
+/**
+ * Fetch subaccount loans for a specific tokenized vault (lending pool).
+ * Retrieves all active subaccount loan data from the backend.
+ * @param pool - Vault address
+ * @param chainId - Network chain ID
+ * @param headers - Monitoring headers for request tracking
+ * @returns Array of active subaccount loan objects
+ */
+async function fetchTokenizedVaultSubaccountLoans(pool, chainId, headers) {
+    const key = `subaccount-loans-${chainId}-${pool}`;
+    let loans;
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
+    }
+    else {
+        const tokenizedVaultsResponse = await fetchAugustPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.subaccountLoans(pool, chainId, true), { headers: headers });
+        loans = (await tokenizedVaultsResponse.json()).loans;
+        await (0, cache_1.setSafeCache)(key, loans);
+    }
+    return loans?.filter((l) => l.state.toLowerCase() === 'active');
+}
+/**
+ * Fetch historical timeseries data for a specific vault.
+ * Returns TVL, APY, PnL, and share price data over time.
+ * @param vaultAddress - Vault contract address
+ * @param nDays - Number of days of historical data to fetch (default 30, min 1)
+ * @param headers - Monitoring headers for request tracking
+ * @returns Historical timeseries data with date keys
+ */
+async function fetchVaultHistoricalTimeseries(vaultAddress, nDays, headers) {
+    const key = `vault-historical-timeseries-${vaultAddress}-${nDays}`;
+    const cachedResponse = await (0, cache_1.getSafeCache)(key);
+    if (cachedResponse) {
+        return cachedResponse;
+    }
+    const response = await fetchAugustPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.historicalTimeseries(vaultAddress, nDays), { headers: headers });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch historical timeseries data: ${response.statusText}`);
+    }
+    const json = (await response.json());
+    cache_1.CACHE.set(key, json, { ttl: 1000 * 60 * 10 }); // Cache for 10 minutes
+    return json;
+}
+/**
+ * Execute multiple promises with retry logic and allow partial failures.
+ * Unlike Promise.all, continues execution if some promises fail.
+ * Failed promises return null to maintain array index alignment.
+ * @param promises - Array of promises to execute
+ * @param maxRetries - Maximum retry attempts per promise
+ * @param baseDelay - Initial delay for exponential backoff
+ * @returns Array of results with null for failed promises
+ */
+async function promiseSettle(promises, maxRetries = 3, baseDelay = 1000) {
+    const promisesWithRetry = promises.map((promise, index) => withRetry(async () => {
+        try {
+            return await promise;
+        }
+        catch (error) {
+            logger_1.Logger.log.warn('promiseSettle', `Promise at index ${index} failed`, error);
+            throw error;
+        }
+    }, maxRetries, baseDelay));
+    const results = await Promise.allSettled(promisesWithRetry);
+    return results.map((result, index) => {
+        if (result.status === 'fulfilled') {
+            return result.value;
+        }
+        else {
+            logger_1.Logger.log.warn('promiseSettle', `Promise at index ${index} failed after retries`, result.reason);
+            return null;
+        }
+    });
+}
+//# sourceMappingURL=fetcher.js.map