upshift-sdk 8.20.1

package/lib/modules/vaults/main.js

@@ -0,0 +1,1623 @@
+"use strict";
+/**
+ * The August Vaults Module.
+ *
+ * @module AugustVaults
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AugustVaults = void 0;
+/**
+ * Export getters
+ */
+__exportStar(require("./getters"), exports);
+/**
+ * AugustVaults class
+ */
+const fetcher_1 = require("./fetcher");
+const ethers_1 = require("ethers");
+const getters_1 = require("./getters");
+const vaults_1 = require("../../services/subgraph/vaults");
+const deposits_1 = require("../../services/layerzero/deposits");
+const redeems_1 = require("../../services/layerzero/redeems");
+const core_1 = require("../../core");
+const utils_1 = require("../../adapters/solana/utils");
+const utils_2 = require("../../adapters/stellar/utils");
+const sui_1 = __importDefault(require("../../adapters/sui"));
+const constants_1 = require("../../adapters/sui/constants");
+const vaults_2 = require("../../core/constants/vaults");
+const write_actions_1 = require("./write.actions");
+const read_actions_1 = require("./read.actions");
+const prefetch_1 = require("./prefetch");
+/**
+ * Vault operations class handling multi-chain vault queries and user positions.
+ * Supports both EVM and Solana vaults with unified interface.
+ */
+class AugustVaults extends core_1.AugustBase {
+    solanaService;
+    suiService;
+    headers = null;
+    /**
+     * Consumer-supplied Soroban RPC override for Stellar vault reads, with the
+     * network it was configured for so it's only applied to matching-network
+     * vaults (see `IVaultBaseOptions.stellarRpc`).
+     */
+    _stellarRpc;
+    constructor(baseConfig, solana, sui) {
+        super(baseConfig);
+        this.solanaService = solana;
+        this.suiService = sui || new sui_1.default();
+        // Network defaults to mainnet, matching the StellarAdapter constructor.
+        this._stellarRpc = baseConfig.stellar?.rpcUrl
+            ? {
+                rpcUrl: baseConfig.stellar.rpcUrl,
+                network: baseConfig.stellar.network ?? 'mainnet',
+            }
+            : undefined;
+        this.headers = {
+            'x-environment': this.monitoring?.['x-environment'],
+            'x-user-id': this.monitoring?.['x-user-id'],
+        };
+    }
+    /**
+     * @description deposit underlying token into the specified pool with adapter support. This is for when we cannot pass in a signer in sdk and need to do so as an arg
+     * @param signer signer / wallet object
+     * @param options object including pool contract address, user wallet address, string amount, and optional depositAsset
+     * @returns deposit tx hash
+     */
+    async vaultDeposit(signer, options) {
+        return (0, write_actions_1.vaultDeposit)(signer, options);
+    }
+    /**
+     * @description deposit native token (ETH/AVAX/etc) into a vault using MultiAssetNativeDepositWrapper
+     * @param signer signer / wallet object
+     * @param options object including wrapper contract address, receiver address (optional), and amount
+     * @returns deposit tx hash
+     */
+    async depositNative(signer, options) {
+        return (0, write_actions_1.depositNative)(signer, options);
+    }
+    /**
+     * Fetch all vaults across configured networks with optional enrichment.
+     * Automatically filters by available providers and optionally by chain IDs.
+     * Includes closed vaults that are still visible (`status: 'closed'`,
+     * `is_visible: true`) so consumers can render positions held in closed
+     * vaults; closed vaults with `is_visible: false` are excluded.
+     *
+     * RPC volume (worst case, wallet enrichment path): the per-vault
+     * `balanceOf`/`lagDuration` reads are aggregated into chunked Multicall3
+     * `aggregate3` batches per chain (10 calls per chunk) on chains where the
+     * canonical Multicall3 deployment is verified; other chains (e.g. Citrea
+     * 4114) keep one `eth_call` per read. Measured with
+     * `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
+     * 54 after (~35% fewer; 124 per-vault `eth_call`s collapse into ~13
+     * `aggregate3` calls — the remaining requests are the per-vault cached
+     * decimals/receipt-token reads on a cold cache).
+     * @param options Filtering and enrichment configuration
+     * @returns Array of vault objects with optional loans/allocations/positions
+     */
+    async getVaults(options) {
+        // if (!(this.authorized && this.augustKey)) // @todo: commented out for integrators
+        const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, options?.loadSubaccounts, options?.loadSnapshots);
+        const vaultsPerAvailableProviders = allVaults.filter((v) => 
+        // Stellar vaults are backend-only (no RPC provider required)
+        v?.chain_type === 'stellar' ||
+            // Solana vaults use this.solanaService (not this.providers). Without
+            // an explicit pass-through here they get silently dropped on any
+            // instance whose ACTIVE_RPC_URLS() doesn't register chainId -1.
+            // Gate on solanaService presence so we don't let a vault through that
+            // we have no adapter to fetch — that would crash the inner getter and
+            // turn into a PENDING entry that the final filter drops anyway.
+            (v?.chain_type === 'solana' && !!this.solanaService) ||
+            (this.providers?.[v?.chain] ? true : false));
+        const vaultsPerChainId = options?.chainIds
+            ? vaultsPerAvailableProviders.filter((v) => options.chainIds.includes(v.chain))
+            : vaultsPerAvailableProviders;
+        // Fetch and transform (filter for active status)
+        const emberVaults = await this.suiService.getEmberVaults({
+            status: 'active',
+        });
+        const activeEmberVaults = Array.isArray(emberVaults)
+            ? emberVaults.filter((v) => v?.status === 'active')
+            : [];
+        const whitelistedEmberVaults = activeEmberVaults.filter((v) => {
+            if (!v?.address)
+                return false;
+            const normalizedAddress = v.address.toLowerCase().trim();
+            return constants_1.ALLOWED_SUI_VAULT_ADDRESSES.includes(normalizedAddress);
+        });
+        const transformedVaults = this.suiService.transformEmberVaultsToIVaults(whitelistedEmberVaults);
+        // Use comprehensive vault fetching for maximum coverage
+        const vaultFetchResult = await (0, fetcher_1.fetchVaultsComprehensive)(vaultsPerChainId, async (vault) => {
+            // Handle fallback RPC if provided
+            const rpcUrl = vault.fallbackRpc || this.providers?.[vault.chain];
+            // Closed vaults have no live loans/allocations. In portfolio mode,
+            // skip that enrichment so a closed vault is never dropped just because
+            // getVaultAllocations re-throws (no debank data / no subaccounts).
+            const isClosedVault = vault.status === 'closed';
+            const skipClosedEnrichment = !!options?.includeClosed && isClosedVault;
+            // Handle minimal data fetching
+            const shouldFetchLoans = !skipClosedEnrichment &&
+                !vault.minimal &&
+                (typeof options?.loans !== 'undefined' ? options?.loans : true);
+            const shouldFetchAllocations = !skipClosedEnrichment &&
+                !vault.minimal &&
+                (typeof options?.allocations !== 'undefined'
+                    ? options?.allocations
+                    : true);
+            const v = await (0, getters_1.getVault)({
+                vault: vault.address,
+                loans: shouldFetchLoans,
+                allocations: shouldFetchAllocations,
+                options: {
+                    rpcUrl,
+                    solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
+                    env: this.monitoring?.env,
+                    augustKey: this.keys?.august,
+                    subgraphKey: this.keys?.graph,
+                    // Portfolio mode: let the EVM getter resolve closed + invisible
+                    // vaults instead of null-ing them, so the closed vault survives.
+                    includeClosed: options?.includeClosed,
+                },
+                loadSubaccounts: options?.loadSubaccounts,
+                loadSnapshots: options?.loadSnapshots,
+            });
+            return v;
+        }, {
+            maxRetries: 5,
+            baseDelay: 2000,
+            batchSize: 15,
+            parallelLimit: 8,
+            includeClosed: true,
+            includeInvisible: false,
+            timeout: 60000,
+            fallbackRpcUrls: {
+                // Use configured fallback RPC endpoints for each chain
+                1: (0, core_1.getFallbackRpcUrls)(1),
+                56: (0, core_1.getFallbackRpcUrls)(56),
+                43114: (0, core_1.getFallbackRpcUrls)(43114),
+                8453: (0, core_1.getFallbackRpcUrls)(8453),
+                42161: (0, core_1.getFallbackRpcUrls)(42161),
+                137: (0, core_1.getFallbackRpcUrls)(137),
+                // [SPECIAL_CHAINS.solana.chainId]: getFallbackRpcUrls(SPECIAL_CHAINS.solana.chainId),
+            },
+        });
+        // Log vault fetching results in DEV mode
+        core_1.Logger.log.info('getVaults', `Total: ${vaultFetchResult.coverageReport.totalVaults}, ` +
+            `Success: ${vaultFetchResult.coverageReport.successfulVaults}, ` +
+            `Failed: ${vaultFetchResult.coverageReport.failedVaults}, ` +
+            `Rate: ${vaultFetchResult.successRate.toFixed(2)}%`);
+        if (vaultFetchResult.coverageReport.failedVaults > 0) {
+            core_1.Logger.log.warn('getVaults:failed', vaultFetchResult.failed.map((f) => ({
+                address: f.address,
+                chain: f.chain,
+                error: f.error.message,
+                attempts: f.attempts,
+            })));
+        }
+        // Use intelligent filtering to preserve more vaults
+        const vaultResponses = vaultFetchResult.successful
+            .sort((a, b) => a.index - b.index)
+            .map((item) => item.data);
+        const filteredResults = (0, fetcher_1.filterVaultsIntelligently)(vaultResponses, {
+            includeClosed: true,
+            includeInvisible: true,
+            minStatus: ['active', 'closed'],
+        });
+        // Closed vaults are included in the result ONLY when the caller opts in via
+        // `includeClosed` (portfolio mode). By default they are dropped, so the
+        // marketplace / discovery callers never receive a closed vault and don't
+        // have to filter `status === 'closed'` themselves. The portfolio passes
+        // `includeClosed: true` so a user's position in a closed vault can be
+        // joined against this list. Note: closed + invisible vaults land in the
+        // `closed` bucket (the status check precedes the visibility check in
+        // filterVaultsIntelligently), so this single gate covers them too.
+        const filteredResponses = [
+            ...filteredResults.active,
+            ...(options?.includeClosed ? filteredResults.closed : []),
+            ...filteredResults.invisible,
+        ];
+        if ((options.wallet && (0, ethers_1.isAddress)(options.wallet)) ||
+            (options.solanaWallet &&
+                utils_1.SolanaUtils.isSolanaAddress(options.solanaWallet))) {
+            // Batch the per-vault balanceOf/lagDuration reads (Multicall3, grouped
+            // by chain) before fanning out — vaults the batch couldn't serve fall
+            // back to their own reads inside getVaultPositions.
+            const prefetchedReads = await (0, prefetch_1.prefetchVaultPositionReads)({
+                vaults: vaultsPerAvailableProviders,
+                wallet: options.wallet,
+                providers: this.providers,
+            });
+            // fetch all positions for user wallet
+            const vaultResponses = await (0, core_1.promiseSettle)(vaultsPerAvailableProviders.map((v) => (0, getters_1.getVaultPositions)({
+                vault: v.address,
+                wallet: options.wallet,
+                solanaWallet: options.solanaWallet,
+                stellarWallet: options.stellarWallet,
+                options: {
+                    rpcUrl: this.providers?.[v.chain],
+                    solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
+                    env: this.monitoring?.env,
+                    augustKey: this.keys?.august,
+                    subgraphKey: this.keys?.graph,
+                },
+                prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
+            })), 5, // 5 retries
+            2000);
+            // return vault object with position property
+            const positions = vaultResponses
+                .flat()
+                .filter((v) => v.status !== 'PENDING');
+            return filteredResponses.map((r) => ({
+                ...r,
+                position: positions?.find((pos) => pos.vault?.toLowerCase() === r.address?.toLowerCase()) || null,
+            }));
+        }
+        if (options.wallet && !(0, ethers_1.isAddress)(options.wallet)) {
+            core_1.Logger.log.warn('getVaults:invalid_wallet', options.wallet);
+        }
+        // console.log(`#getVaults:`, filteredResponses);
+        return [...filteredResponses, ...transformedVaults];
+    }
+    /**
+     * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl.
+     * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD.
+     * @param options Optional configuration for loading vaults
+     * @returns Total deposited amount in USD (sum of all latest_reported_tvl values)
+     */
+    async getTotalDeposited(options) {
+        const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, options?.loadSubaccounts, options?.loadSnapshots);
+        let total = 0;
+        allVaults.forEach((vault) => {
+            if (vaults_2.TVL_EXCLUDED_VAULTS.has(vault.address?.toLowerCase()))
+                return;
+            if (vault.latest_reported_tvl !== null &&
+                vault.latest_reported_tvl !== undefined) {
+                total += vault.latest_reported_tvl;
+            }
+        });
+        return total;
+    }
+    /**
+     * Fetch detailed data for a single vault with optional enrichment.
+     * Automatically includes loans and allocations unless explicitly disabled.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @param options Enrichment and wallet options
+     * @returns Single vault object with optional position data
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
+     */
+    async getVault({ vault, chainId, options, loadSubaccounts, loadSnapshots, }) {
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        // if (!isAddress(vault))
+        //   throw new Error(
+        //     `Vault input parameter is not an address: ${String(vault)}`,
+        //   );
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVault');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVault');
+        // get vault data
+        const vaultResponse = await (0, getters_1.getVault)({
+            vault: vault,
+            loans: typeof options?.loans !== 'undefined' ? options?.loans : true,
+            allocations: typeof options?.allocations !== 'undefined'
+                ? options?.allocations
+                : true,
+            options: {
+                rpcUrl: chainId
+                    ? this.providers?.[chainId]
+                    : this.activeNetwork?.rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+            loadSubaccounts,
+            loadSnapshots,
+        });
+        if (((0, ethers_1.isAddress)(vault) || (0, utils_2.isStellarAddress)(vault)) &&
+            ((options?.wallet && (0, ethers_1.isAddress)(options?.wallet)) ||
+                (options?.solanaWallet &&
+                    utils_1.SolanaUtils.isSolanaAddress(options?.solanaWallet)) ||
+                (options?.stellarWallet && (0, utils_2.isStellarAddress)(options?.stellarWallet)))) {
+            // fetch all positions for user wallet
+            const vaultResponses = await (0, getters_1.getVaultPositions)({
+                vault: vault,
+                solanaWallet: options?.solanaWallet,
+                stellarWallet: options?.stellarWallet,
+                wallet: options?.wallet,
+                options: {
+                    rpcUrl: chainId
+                        ? this.providers?.[chainId]
+                        : this.activeNetwork?.rpcUrl,
+                    solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
+                    env: this.monitoring?.env,
+                    augustKey: this.keys?.august,
+                    subgraphKey: this.keys?.graph,
+                    headers: this.headers,
+                },
+            });
+            // return vault object with position property
+            const positions = vaultResponses.filter((v) => v.status !== 'PENDING');
+            return {
+                ...vaultResponse,
+                position: positions?.find((pos) => pos.vault?.toLowerCase() === vault?.toLowerCase()) || null,
+            };
+        }
+        if (options?.wallet && !(0, ethers_1.isAddress)(options?.wallet)) {
+            core_1.Logger.log.warn('getVault:invalid_wallet', options?.wallet);
+        }
+        // console.log(`#getVault::${vaultResponse.symbol}:`, vaultResponse);
+        return vaultResponse;
+    }
+    /**
+     * Fetch the active loans issued by a vault.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Loan data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
+     */
+    async getVaultLoans({ vault, chainId, }) {
+        // Sanitize
+        // if (!this.authorized) throw new Error('Not authorized.');
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault))
+            throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVaultLoans');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVaultLoans');
+        // get vault loans data
+        const vaultResponse = await (0, getters_1.getVaultLoans)(vault, {
+            rpcUrl: chainId
+                ? this.providers?.[chainId]
+                : this.requireActiveNetwork().rpcUrl,
+            env: this.monitoring?.env,
+            augustKey: this.keys?.august,
+            subgraphKey: this.keys?.graph,
+            chainId: chainId,
+            solanaService: this.solanaService,
+            stellarRpc: this._stellarRpc,
+            headers: this.headers,
+        });
+        return vaultResponse;
+    }
+    /**
+     * Fetch a vault's loans broken down by sub-account.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Sub-account loan data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
+     */
+    async getVaultSubaccountLoans({ vault, chainId, }) {
+        // Sanitize
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault))
+            throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVaultSubaccountLoans');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVaultSubaccountLoans');
+        // get vault subaccount loans data
+        const vaultResponse = await (0, getters_1.getVaultSubaccountLoans)(vault, {
+            rpcUrl: chainId
+                ? this.providers?.[chainId]
+                : this.requireActiveNetwork().rpcUrl,
+            env: this.monitoring?.env,
+            augustKey: this.keys?.august,
+            subgraphKey: this.keys?.graph,
+            chainId: chainId,
+            solanaService: this.solanaService,
+            stellarRpc: this._stellarRpc,
+            headers: this.headers,
+        });
+        return vaultResponse;
+    }
+    /**
+     * Fetch a vault's DeFi / CeFi / OTC allocation breakdown.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Allocation data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
+     */
+    async getVaultAllocations({ vault, chainId, }) {
+        // Sanitize
+        // if (!this.authorized) throw new Error('Not authorized.');
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault) &&
+            !utils_1.SolanaUtils.isSolanaAddress(vault) &&
+            !(0, utils_2.isStellarAddress)(vault))
+            throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVaultAllocations');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVaultAllocations');
+        // get vault allocations data
+        try {
+            const vaultResponse = await (0, getters_1.getVaultAllocations)(vault, {
+                rpcUrl: chainId
+                    ? this.providers?.[chainId]
+                    : this.activeNetwork?.rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            });
+            return vaultResponse;
+        }
+        catch (e) {
+            const err = e;
+            if (err.message.includes('debank')) {
+                return {
+                    status: 400,
+                    message: 'There was an error fetching from debank',
+                };
+            }
+            return {
+                status: 400,
+                message: 'There was an error fetching vaults',
+            };
+        }
+    }
+    /**
+     * @deprecated use getVaultHistoricalTimeseries instead
+     * @function getVaultApy gets the vault/pool APR, both current and historical
+     * @param vault pool/vault contract address
+     * @param historical (optional) When passed, returns the historical records of the pool/vault APR
+     * @returns a value or array of objects containing the APR and timestamp
+     */
+    async getVaultApy({ vault, historical, }) {
+        // if (!this.authorized) throw new Error('Not authorized.');
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault) && !(0, utils_2.isStellarAddress)(vault))
+            throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        return await (0, getters_1.getVaultApy)({
+            vault,
+            historical,
+            options: {
+                rpcUrl: this.activeNetwork?.rpcUrl,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * @function getVaultHistoricalTimeseries gets historical timeseries data for a vault
+     * @param vault Vault contract address
+     * @param nDays Number of days of historical data (default 30, min 1)
+     * @returns Historical timeseries data with TVL, APY, PnL, share price, and other metrics
+     */
+    async getVaultHistoricalTimeseries({ vault, nDays, }) {
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        return await (0, getters_1.getVaultHistoricalTimeseries)({
+            vault,
+            nDays,
+            options: {
+                rpcUrl: this.activeNetwork?.rpcUrl,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     *
+     */
+    async getVaultAvailableRedemptions({ vault, chainId, wallet, verbose, }) {
+        if (!this.authorized)
+            throw new Error('Not authorized.');
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault) && !(0, utils_2.isStellarAddress)(vault))
+            throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        return await (0, getters_1.getVaultAvailableRedemptions)({
+            vault,
+            wallet,
+            options: {
+                rpcUrl: chainId
+                    ? this.providers?.[chainId]
+                    : this.activeNetwork?.rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+                verbose: verbose,
+            },
+        });
+    }
+    /**
+     * Historical redemption requests for a vault (settled, cancelled, and
+     * pending-but-out-of-window). Filterable by wallet.
+     *
+     * Stellar vaults return `[]` — on-chain redemption history is not yet
+     * indexed for that adapter.
+     *
+     * @param vault - Vault address (EVM or Stellar). Stellar input is
+     *   accepted but always resolves to an empty array for now.
+     * @param chainId - Chain id to resolve the RPC URL against. Falls
+     *   back to the active network.
+     * @param wallet - Optional EVM wallet filter; when omitted the
+     *   response includes every wallet that has ever redeemed against
+     *   the vault.
+     * @param lookbackBlocks - How far back to scan for redemption logs.
+     *   Defaults to the SDK's internal lookback when omitted.
+     * @returns The same array shape `getVaultRedemptionHistory` returns
+     *   at the module level — historical redemption records, newest
+     *   first.
+     *
+     * @example
+     * ```ts
+     * const history = await sdk.vaultsModule.getVaultRedemptionHistory({
+     *   vault: '0xVault',
+     *   chainId: 8453,
+     *   wallet: '0xWallet',
+     * });
+     * ```
+     */
+    async getVaultRedemptionHistory({ vault, chainId, wallet, lookbackBlocks, }) {
+        if (!this.authorized)
+            throw new Error('Not authorized.');
+        if (!vault)
+            throw new Error('Vault input parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault) && !(0, utils_2.isStellarAddress)(vault)) {
+            throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
+        }
+        return await (0, getters_1.getVaultRedemptionHistory)({
+            vault,
+            wallet,
+            lookbackBlocks,
+            options: {
+                rpcUrl: chainId
+                    ? this.providers?.[chainId]
+                    : this.activeNetwork?.rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Fetch the wallet's positions across vaults — a single vault, one chain,
+     * or every chain with a configured provider.
+     *
+     * RPC volume (worst case, multi-vault paths): the two non-cacheable
+     * per-vault reads (`balanceOf`, `lagDuration`) are aggregated into chunked
+     * Multicall3 `aggregate3` batches per chain (10 calls per chunk) on chains
+     * where the canonical deployment is verified; unverified chains (e.g.
+     * Citrea 4114) and non-EVM vaults keep one `eth_call` per read. Measured
+     * with `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
+     * 54 after (~35% fewer). A vault whose batched read fails (e.g. paused)
+     * falls back to its own per-vault reads — never to a zeroed balance.
+     */
+    async getVaultPositions({ vault, wallet, chainId, showAllVaults, solanaWallet, stellarWallet, options, }) {
+        // if (!this.authorized) throw new Error('Not authorized.');
+        // Validate that at least one wallet type is provided
+        if (solanaWallet && !utils_1.SolanaUtils.isSolanaAddress(solanaWallet)) {
+            throw new Error('Solana wallet parameter must be provided and be a valid Solana address');
+        }
+        // Validate EVM wallet if provided
+        if (wallet && !(0, ethers_1.isAddress)(wallet)) {
+            throw new Error(`Wallet parameter is not a valid address: ${String(wallet)}`);
+        }
+        if (vault) {
+            const positions = await (0, getters_1.getVaultPositions)({
+                vault,
+                wallet,
+                solanaWallet,
+                stellarWallet,
+                options: {
+                    rpcUrl: chainId
+                        ? this.providers?.[chainId]
+                        : this.activeNetwork?.rpcUrl,
+                    solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
+                    env: this.monitoring?.env,
+                    augustKey: this.keys?.august,
+                    subgraphKey: this.keys?.graph,
+                    headers: this.headers,
+                },
+            });
+            if (showAllVaults)
+                return positions;
+            return positions.filter((v) => v?.status !== 'PENDING');
+        }
+        const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, false, false);
+        if (chainId) {
+            const vaultsPerChain = allVaults.filter((v) => v.chain === chainId);
+            // Batch balanceOf/lagDuration via Multicall3 before the per-vault
+            // fan-out; un-batched vaults fall back to their own reads.
+            const prefetchedReads = await (0, prefetch_1.prefetchVaultPositionReads)({
+                vaults: vaultsPerChain,
+                wallet,
+                providers: this.providers,
+            });
+            const vaultResponses = await Promise.all(vaultsPerChain.map((v) => (0, getters_1.getVaultPositions)({
+                vault: v.address,
+                solanaWallet,
+                stellarWallet,
+                wallet,
+                options: {
+                    rpcUrl: this.providers?.[v.chain],
+                    solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
+                    env: this.monitoring?.env,
+                    augustKey: this.keys?.august,
+                    subgraphKey: this.keys?.graph,
+                    headers: this.headers,
+                },
+                prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
+            })));
+            const flattened = vaultResponses.flat();
+            let final;
+            if (showAllVaults)
+                final = flattened;
+            else
+                final = flattened.filter((v) => v?.status !== 'PENDING');
+            core_1.Logger.log.info(`getPositions::${chainId || 'all'}:`, final.map((v) => v.vault));
+            return final;
+        }
+        const vaultsPerAvailableProviders = allVaults.filter((v) => 
+        // Stellar vaults are backend-only (no RPC provider required)
+        v?.chain_type === 'stellar' ||
+            // Solana vaults use this.solanaService (not this.providers). Without
+            // this clause every Solana position is dropped on any instance where
+            // ACTIVE_RPC_URLS() doesn't register chainId -1 — which is exactly
+            // how the jitoSOL "missing position" regression manifested. Gate on
+            // solanaService presence so we don't pass Solana vaults through with
+            // no adapter to read them — the inner getter would crash, hit the
+            // outer catch, and silently return PENDING (then get filtered out).
+            (v?.chain_type === 'solana' && !!this.solanaService) ||
+            (this.providers?.[v?.chain] ? true : false));
+        // Batch balanceOf/lagDuration via Multicall3, grouped by chain, before
+        // the per-vault fan-out; un-batched vaults fall back to their own reads.
+        const prefetchedReads = await (0, prefetch_1.prefetchVaultPositionReads)({
+            vaults: vaultsPerAvailableProviders,
+            wallet,
+            providers: this.providers,
+        });
+        const vaultResponses = await Promise.all(vaultsPerAvailableProviders.map((v) => (0, getters_1.getVaultPositions)({
+            vault: v.address,
+            solanaWallet,
+            stellarWallet,
+            wallet,
+            options: {
+                rpcUrl: this.providers?.[v.chain],
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+            prefetchedReads: prefetchedReads.get(String(v.address).toLowerCase()),
+        })));
+        const flattened = vaultResponses.flat();
+        let final;
+        if (showAllVaults)
+            final = flattened;
+        else
+            final = flattened.filter((v) => v?.status !== 'PENDING');
+        // console.log(`#getPositions::${chainId || 'all'}:`, final);
+        return final;
+    }
+    /**
+     *
+     */
+    async getUserHistory({ wallet, chainId, vault, }) {
+        // Santize
+        // if (!this.authorized) throw new Error('Not authorized.');
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error(`Wallet parameter is not an address: ${String(wallet)}`);
+        // Get Chain ID — required for subgraph queries
+        const _chainId = chainId || this.activeNetwork?.chainId;
+        if (!_chainId) {
+            throw new Error('Chain ID is required for getUserHistory. Pass chainId explicitly or configure an active network.');
+        }
+        // Format history initialization
+        let finalArray = [];
+        function formatHistory(history) {
+            return history.map((h) => ({
+                timestamp: Number(h.timestamp_),
+                address: h.address,
+                amount: (0, core_1.toNormalizedBn)(BigInt(h.amount), h.decimals),
+                pool: h.contractId_,
+                chainId: _chainId,
+                type: h.type,
+                transactionHash: h.transactionHash_,
+                // Deposit rows on multi-asset (pre-deposit) vaults carry the actual
+                // deposited token address; propagate it so consumers render the right
+                // asset symbol instead of guessing the vault's first deposit asset.
+                assetIn: h.assetIn,
+                // withdraw-request rows carry the burned share amount. Normalize with
+                // the vault decimals (the share token's own decimals) so UIs can show
+                // the receipt-token quantity that was actually burned.
+                shares: h.shares
+                    ? (0, core_1.toNormalizedBn)(BigInt(h.shares), h.decimals)
+                    : undefined,
+            }));
+        }
+        // Helper function to fetch history for a vault
+        // For LayerZero-enabled vaults (coreUSDC, upUSDC), queries BOTH the standard
+        // subgraph and the LayerZero subgraph, since deposits can be either same-chain
+        // or cross-chain via LayerZero
+        const fetchVaultHistory = async (vaultAddress, vaultChainId) => {
+            // Always query the standard subgraph
+            const provider = (0, core_1.createProvider)(this.providers?.[vaultChainId]);
+            const standardHistory = await (0, vaults_1.getSubgraphUserHistory)(wallet, provider, vaultAddress);
+            const formattedStandard = formatHistory(standardHistory);
+            // If this vault also supports LayerZero cross-chain deposits,
+            // query the LayerZero subgraph and merge results
+            const layerZeroVaultKey = (0, deposits_1.isLayerZeroVault)(vaultAddress);
+            if (layerZeroVaultKey) {
+                try {
+                    const layerZeroDeposits = await (0, deposits_1.queryLayerZeroDeposits)(layerZeroVaultKey, wallet);
+                    const formattedLayerZero = layerZeroDeposits.map((deposit) => ({
+                        timestamp: Number(deposit.timestamp_) || 0,
+                        address: wallet,
+                        amount: (0, core_1.toNormalizedBn)(BigInt(deposit.assetAmt), deposits_1.LAYERZERO_VAULTS[layerZeroVaultKey].decimals),
+                        pool: deposits_1.LAYERZERO_VAULTS[layerZeroVaultKey].address,
+                        chainId: vaultChainId || _chainId,
+                        type: 'deposit',
+                        transactionHash: deposit.transactionHash_,
+                    }));
+                    // For earnAUSD, also query LayerZero redeems
+                    let formattedLayerZeroRedeems = [];
+                    if (layerZeroVaultKey === 'earnAUSD') {
+                        try {
+                            const layerZeroRedeems = await (0, redeems_1.queryLayerZeroRedeems)(wallet);
+                            formattedLayerZeroRedeems = layerZeroRedeems.map((redeem) => ({
+                                timestamp: Number(redeem.timestamp_) || 0,
+                                address: wallet,
+                                amount: (0, core_1.toNormalizedBn)(BigInt(redeem.shareAmt), deposits_1.LAYERZERO_VAULTS[layerZeroVaultKey].decimals),
+                                pool: deposits_1.LAYERZERO_VAULTS[layerZeroVaultKey].address,
+                                chainId: vaultChainId || _chainId,
+                                type: 'redeem',
+                                transactionHash: redeem.transactionHash_,
+                            }));
+                        }
+                        catch (redeemError) {
+                            core_1.Logger.log.warn('getUserHistory:layerzero:redeems', `Failed to fetch LayerZero redeems for earnAUSD: ${redeemError.message}`);
+                        }
+                    }
+                    // Deduplicate against standard subgraph history only — LZ deposits and
+                    // LZ redeems are not deduped against each other because a single tx can
+                    // legitimately emit both a Deposited and a Redeemed event.
+                    const seenTxHashes = new Set(formattedStandard.map((h) => h.transactionHash?.toLowerCase()));
+                    const uniqueLayerZero = formattedLayerZero.filter((h) => !seenTxHashes.has(h.transactionHash?.toLowerCase()));
+                    const uniqueLayerZeroRedeems = formattedLayerZeroRedeems.filter((h) => !seenTxHashes.has(h.transactionHash?.toLowerCase()));
+                    return [
+                        ...formattedStandard,
+                        ...uniqueLayerZero,
+                        ...uniqueLayerZeroRedeems,
+                    ];
+                }
+                catch (error) {
+                    // If LayerZero query fails, still return standard history
+                    core_1.Logger.log.warn('getUserHistory:layerzero', `Failed to fetch LayerZero deposits for ${layerZeroVaultKey}: ${error.message}`);
+                    return formattedStandard;
+                }
+            }
+            return formattedStandard;
+        };
+        // If vault is provided, return history for that vault. This path is
+        // EVM-only (see fetchVaultHistory → getSubgraphUserHistory); a non-EVM
+        // vault address would drive eth_chainId against a Solana/Stellar RPC.
+        if (vault) {
+            finalArray = (0, ethers_1.isAddress)(vault)
+                ? await fetchVaultHistory(vault, chainId)
+                : [];
+        }
+        else {
+            // Fetch all vaults
+            const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, false, false);
+            // If chainId is provided, return history for all vaults on that chain.
+            // EVM-only: skip non-EVM (Solana/Stellar) vault addresses.
+            if (chainId) {
+                const vaultsPerChain = allVaults.filter((v) => v.chain === chainId && (0, ethers_1.isAddress)(v.address));
+                const vaultResponses = await Promise.all(vaultsPerChain.map((v) => fetchVaultHistory(v.address, v.chain)));
+                const flattened = vaultResponses.flat();
+                finalArray = flattened;
+            }
+            else {
+                // Else, fetch all history for all vaults across all initialized chains.
+                // Gate on isAddress(v.address): the Solana provider is registered under
+                // chainId -1, so without this a Solana vault passes `providers?.[v.chain]`
+                // and gets routed into the EVM subgraph path, throwing
+                // "eth_chainId is not available on SOLANA_MAINNET" on every fetch.
+                // LayerZero vaults query subgraphs directly and don't need a provider.
+                const vaultsPerAvailableProviders = allVaults.filter((v) => (0, ethers_1.isAddress)(v.address) &&
+                    (this.providers?.[v?.chain] || (0, deposits_1.isLayerZeroVault)(v.address)));
+                const vaultResponses = await Promise.all(vaultsPerAvailableProviders.map((v) => fetchVaultHistory(v.address, v.chain)));
+                const flattened = vaultResponses.flat();
+                finalArray = flattened;
+            }
+        }
+        core_1.Logger.log.info('getUserHistory', `${wallet}::${finalArray.length}`);
+        return finalArray;
+    }
+    /**
+     * Get lifetime PnL for a user in a specific vault.
+     * @param props Vault address, wallet address, and optional chain ID
+     * @returns Lifetime PnL data including realized and unrealized PnL
+     */
+    async getVaultUserLifetimePnl({ vault, wallet, chainId, }) {
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error(`Wallet parameter is not an address: ${String(wallet)}`);
+        if (!(0, ethers_1.isAddress)(vault) && !(0, utils_2.isStellarAddress)(vault))
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        const { getVaultUserLifetimePnl } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getVaultUserLifetimePnl({
+            vault,
+            wallet,
+            options: {
+                rpcUrl: chainId
+                    ? this.providers?.[chainId]
+                    : this.requireActiveNetwork().rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+            coingeckoKey: this.keys?.coingecko,
+        });
+    }
+    /**
+     * Get PnL for a vault (vault-level, not user-specific).
+     * Returns the vault's overall profit and loss across all users.
+     * @param props Vault address and optional chain ID
+     * @returns Vault PnL in USD and notional value
+     */
+    async getVaultPnl({ vault, chainId, }) {
+        if (!(0, ethers_1.isAddress)(vault))
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        const { getVaultPnl } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getVaultPnl({
+            vault,
+            options: {
+                rpcUrl: chainId
+                    ? this.providers?.[chainId]
+                    : this.requireActiveNetwork().rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     *
+     */
+    async getUserTransfers({ wallet, chainId, vault, options, }) {
+        // Santize
+        // if (!this.authorized) throw new Error('Not authorized.');
+        if (!(0, ethers_1.isAddress)(wallet))
+            throw new Error(`Wallet parameter is not an address: ${String(wallet)}`);
+        // Format history initialization
+        let finalArray = [];
+        function formatTransfers(transfers) {
+            return transfers.map((t) => ({
+                id: t.id,
+                value: t.value,
+                to: t.to,
+                from: t.from,
+                pool: t.contractId_,
+                block: Number(t.block_number),
+                timestamp: Number(t.timestamp_),
+                transactionHash: t.transactionHash_,
+            }));
+        }
+        // If vault is provided, return history for that vault
+        if (vault) {
+            const provider = (0, core_1.createProvider)(this.providers?.[chainId]);
+            const userHistory = await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, vault);
+            finalArray = formatTransfers(userHistory);
+        }
+        else {
+            // Fetch all vaults
+            const allVaults = await (0, core_1.fetchTokenizedVaults)(undefined, this.headers, false, false);
+            // If chainId is provided, return history for all vaults on that chain
+            if (chainId) {
+                const vaultsPerChain = allVaults.filter((v) => v.chain === chainId);
+                const vaultResponses = await Promise.all(vaultsPerChain.map(async (v) => {
+                    const provider = (0, core_1.createProvider)(this.providers?.[v.chain]);
+                    const userHistory = await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, v.address);
+                    return userHistory;
+                }));
+                const flattened = vaultResponses.flat();
+                finalArray = formatTransfers(flattened);
+            }
+            else {
+                // Else, fetch all history for all vaults across all initialized chains
+                const vaultsPerAvailableProviders = allVaults.filter((v) => this.providers?.[v?.chain] ? true : false);
+                const vaultResponses = await Promise.all(vaultsPerAvailableProviders.map(async (v) => {
+                    const provider = (0, core_1.createProvider)(this.providers?.[v.chain]);
+                    const userHistory = await (0, vaults_1.getSubgraphUserTransfers)(wallet, provider, v.address);
+                    return userHistory;
+                }));
+                const flattened = vaultResponses.flat();
+                finalArray = formatTransfers(flattened);
+            }
+        }
+        core_1.Logger.log.info('getUserTransfers', `${wallet}::${finalArray.length}`);
+        return finalArray;
+    }
+    /**
+     * Fetch a vault's deposit/withdrawal activity across every participant.
+     *
+     * This is the vault-wide counterpart to {@link getUserHistory}: instead of
+     * filtering the subgraph to one wallet, it returns every deposit,
+     * withdrawal-request, and processed-withdrawal event for the pool. Use it to
+     * answer flow questions ("how many deposits in the last 7 days", "net flow
+     * this week") that point-in-time TVL cannot.
+     *
+     * Rows are read from the Goldsky subgraph, paginated internally so busy
+     * vaults are not truncated at the 1000-row page cap. When `sinceTs` is
+     * supplied the reader stops paging once it passes the window boundary, so a
+     * short lookback stays cheap even on high-volume vaults.
+     *
+     * @param params - Query parameters.
+     * @param params.vault - Vault (pool) address to read activity for.
+     * @param params.chainId - Chain id of the vault; falls back to the active
+     * network when omitted. Required for the subgraph lookup.
+     * @param params.sinceTs - Lower bound (inclusive) as a Unix timestamp in
+     * seconds. Events at or after this time are returned.
+     * @param params.untilTs - Upper bound (inclusive) as a Unix timestamp in
+     * seconds. Events at or before this time are returned.
+     * @param params.types - Restrict to a subset of event types (e.g.
+     * `['deposit']`). Returns all types when omitted.
+     * @returns Activity items sorted oldest-first, each with a normalized
+     * `amount`, actor `address`, `type`, and `transactionHash`.
+     * @throws If `vault` is not a valid address, or no chain id can be resolved.
+     * @example
+     * ```ts
+     * const weekAgo = Math.floor(Date.now() / 1000) - 7 * 86_400;
+     * const deposits = await sdk.getVaultActivity({
+     *   vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA',
+     *   chainId: 143,
+     *   sinceTs: weekAgo,
+     *   types: ['deposit'],
+     * });
+     * console.log(`${deposits.length} deposits in the last 7 days`);
+     * ```
+     */
+    async getVaultActivity({ vault, chainId, sinceTs, untilTs, types, }) {
+        if (!(0, ethers_1.isAddress)(vault))
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        const _chainId = chainId || this.activeNetwork?.chainId;
+        if (!_chainId) {
+            throw new Error('Chain ID is required for getVaultActivity. Pass chainId explicitly or configure an active network.');
+        }
+        const provider = (0, core_1.createProvider)(this.providers?.[_chainId]);
+        const raw = await (0, vaults_1.getSubgraphVaultHistory)(provider, vault, undefined, {
+            sinceTs,
+        });
+        const typeFilter = types?.length ? new Set(types) : undefined;
+        return raw
+            .map((h) => ({
+            timestamp: Number(h.timestamp_),
+            address: h.address,
+            amount: (0, core_1.toNormalizedBn)(BigInt(h.amount), h.decimals),
+            pool: h.contractId_,
+            chainId: _chainId,
+            type: h.type,
+            transactionHash: h.transactionHash_,
+        }))
+            .filter((h) => {
+            if (sinceTs !== undefined && h.timestamp < sinceTs)
+                return false;
+            if (untilTs !== undefined && h.timestamp > untilTs)
+                return false;
+            if (typeFilter && !typeFilter.has(h.type))
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Resolve the ERC-20 tokens currently whitelisted for the `SwapRouter` on a
+     * chain — the any-token set a deposit UI can offer as swap-and-deposit inputs,
+     * each verified `true` against the router's on-chain allowlist.
+     *
+     * Reconstructs the set from the router's `TokenEnabled` event history and
+     * re-checks `whitelistedTokens(token)` for each (the mapping is not
+     * enumerable). See {@link getSwapRouterWhitelistedTokens} for the full
+     * two-stage behavior and RPC cost. Uses this instance's configured provider
+     * for `chainId`; returns `[]` (no RPC) when no router is deployed there or no
+     * provider is configured.
+     *
+     * @param chainId - EVM chain ID to resolve the allowlist for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed whitelisted token addresses; `[]` when unavailable.
+     *   Callers still exclude a target vault's natively-accepted assets (those
+     *   deposit without a swap).
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const tokens = await augustSdk.getSwapRouterWhitelistedTokens(1);
+     * ```
+     */
+    async getSwapRouterWhitelistedTokens(chainId, options) {
+        if (!(0, core_1.getSwapRouterAddress)(chainId))
+            return [];
+        const rpcUrl = this.providers?.[chainId];
+        if (!rpcUrl) {
+            core_1.Logger.log.warn('getSwapRouterWhitelistedTokens', `no provider configured for chain ${chainId}`);
+            return [];
+        }
+        return (0, core_1.getSwapRouterWhitelistedTokens)(chainId, {
+            rpcUrl,
+            fromBlock: options?.fromBlock,
+        });
+    }
+    /**
+     * Resolve the vaults currently eligible for the any-token `SwapRouter`
+     * deposit surface on a chain — every vault the router has `enableVault`-ed
+     * whose on-chain registration is still live.
+     *
+     * Reconstructs the set from the router's `VaultEnabled` event history and
+     * re-checks `vaultInfo(vault).referenceAsset != 0` for each (the mapping is
+     * not enumerable). See {@link getSwapRouterEligibleVaults} for the full
+     * two-stage behavior and RPC cost. Uses this instance's configured provider
+     * for `chainId`; returns `[]` (no RPC) when no router is deployed there or no
+     * provider is configured.
+     *
+     * On-chain eligibility only — app-level policy (e.g. excluding vaults with
+     * their own OVault deposit flow) remains the caller's responsibility.
+     *
+     * @param chainId - EVM chain ID to resolve eligible vaults for.
+     * @param options - Optional `fromBlock` to override the deploy-block scan floor.
+     * @returns Checksummed eligible vault addresses; `[]` when unavailable.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const vaults = await augustSdk.getSwapRouterEligibleVaults(1);
+     * ```
+     */
+    async getSwapRouterEligibleVaults(chainId, options) {
+        if (!(0, core_1.getSwapRouterAddress)(chainId))
+            return [];
+        const rpcUrl = this.providers?.[chainId];
+        if (!rpcUrl) {
+            core_1.Logger.log.warn('getSwapRouterEligibleVaults', `no provider configured for chain ${chainId}`);
+            return [];
+        }
+        return (0, core_1.getSwapRouterEligibleVaults)(chainId, {
+            rpcUrl,
+            fromBlock: options?.fromBlock,
+        });
+    }
+    /**
+     * @function getStakingPositions gets all available reward staking positions
+     * @param wallet optionally passed user wallet address
+     * @param chainId optionally passed chainId
+     * @returns all available staking positions for connected or passed network(s)
+     */
+    async getStakingPositions(wallet, chainId) {
+        if (chainId) {
+            const positions = await (0, getters_1.getRewardsStakingPositions)({
+                rpcUrl: this.providers?.[chainId] || this.requireActiveNetwork().rpcUrl,
+                wallet,
+            });
+            return positions;
+        }
+        const positions = await Promise.all(Object.values(this.providers).map((rpcUrl) => {
+            return (0, getters_1.getRewardsStakingPositions)({
+                rpcUrl: chainId
+                    ? this.providers?.[chainId]
+                    : rpcUrl || this.requireActiveNetwork().rpcUrl,
+                wallet,
+            });
+        }));
+        return positions.flat();
+    }
+    /**
+     * @function getVaultTvl gets the vault/pool TVL, both current and historical
+     * @param vault pool/vault contract address
+     * @param historical (optional) When passed, returns the historical records of the pool/vault TVL
+     * @returns an object or array of objects containing the TVL and timestamp
+     */
+    async getVaultTvl({ vault, chainId, historical, }) {
+        if (!this.authorized)
+            throw new Error('Not authorized.');
+        if (!vault)
+            throw new Error('Pool input parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault) && !(0, utils_2.isStellarAddress)(vault))
+            throw new Error(`Pool input parameter is not an address: ${String(vault)}`);
+        const resolvedChainId = chainId ?? this.activeNetwork?.chainId;
+        const rpcUrl = chainId
+            ? this.providers?.[chainId]
+            : this.activeNetwork?.rpcUrl;
+        return await (0, getters_1.getVaultTvl)({
+            vault,
+            options: {
+                rpcUrl: rpcUrl,
+                chainId: resolvedChainId,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+            historical: historical,
+        });
+    }
+    /**
+     * @function getYieldLastRealizedOn gets the timestamp when yield was last realized for a vault
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Timestamp (Unix timestamp in seconds) when yield was last realized
+     */
+    async getYieldLastRealizedOn({ vault, chainId, }) {
+        const rpcUrl = chainId
+            ? this.providers?.[chainId]
+            : this.activeNetwork?.rpcUrl;
+        return await (0, getters_1.getYieldLastRealizedOn)({
+            vault,
+            options: {
+                rpcUrl: rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Gets borrower health-factor data for vaults on a chain, optionally
+     * scoped to a single vault.
+     *
+     * Pass `vault` whenever the caller knows which pool it cares about —
+     * this skips the all-vaults cross-chain fanout and only reads the loans
+     * for that one pool. The response map is keyed by **lowercased** vault
+     * address; look entries up with `address.toLowerCase()`.
+     *
+     * Individual loan failures (bad/test loan contracts, unrecognized
+     * borrowers) are isolated and logged rather than rejecting the batch.
+     *
+     * @param chainId Optional chain to scope the read to. When omitted,
+     *   iterates the SDK's configured providers and returns the flattened
+     *   list (legacy shape — prefer passing a chain).
+     * @param vault Optional vault address. When provided alongside
+     *   `chainId`, only that vault's data is fetched.
+     * @returns When `chainId` is set, an object map of lowercased vault
+     *   address → array of borrower-health-factor rows. When `chainId` is
+     *   omitted, a flat array (legacy behavior, kept for backward compat).
+     */
+    async getVaultBorrowerHealthFactor(chainId, vault) {
+        if (chainId) {
+            const health_factors = await (0, getters_1.getHealthFactorOfBorrowersByVault)({
+                options: {
+                    rpcUrl: this.providers?.[chainId] || this.requireActiveNetwork().rpcUrl,
+                    env: this.monitoring?.env,
+                    augustKey: this.keys?.august,
+                },
+                vault,
+            });
+            return health_factors;
+        }
+        const health_factors = await Promise.all(Object.values(this.providers).map((rpcUrl) => {
+            return (0, getters_1.getHealthFactorOfBorrowersByVault)({
+                options: {
+                    rpcUrl: chainId
+                        ? this.providers?.[chainId]
+                        : rpcUrl || this.requireActiveNetwork().rpcUrl,
+                    solanaService: this.solanaService,
+                    stellarRpc: this._stellarRpc,
+                    env: this.monitoring?.env,
+                    augustKey: this.keys?.august,
+                    subgraphKey: this.keys?.graph,
+                    headers: this.headers,
+                },
+                vault,
+            });
+        }));
+        return health_factors.flat();
+    }
+    /**
+     * @function getUserPoints fetches user points from the backend API
+     * @param userAddress User wallet address
+     * @returns Points data from the backend API
+     */
+    async getUserPoints(userAddress) {
+        const { getUserPoints } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getUserPoints({
+            userAddress,
+            options: {
+                rpcUrl: this.requireActiveNetwork().rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Register a user for the points program, authenticated by a wallet signature.
+     *
+     * The caller produces a personal_sign signature over a canonical message
+     * built from these primitives — see `registerUserForPoints` in
+     * `./getters` for the exact template and a worked example.
+     *
+     * @param userAddress EVM wallet address being registered.
+     * @param referrerAddress Optional referrer EVM address.
+     * @param chainId Chain on which the wallet signed; powers the EIP-1271
+     *   fallback for smart-contract wallets and pins the signature cross-chain.
+     * @param signature 0x-prefixed hex personal_sign signature over the canonical message.
+     * @param nonce Single-use random string (8–128 chars).
+     * @param expiry Unix seconds; must be in the future, within the backend's TTL.
+     * @returns Raw `Response` from the backend.
+     */
+    async registerUserForPoints(userAddress, referrerAddress, chainId, signature, nonce, expiry) {
+        const { registerUserForPoints } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await registerUserForPoints({
+            userAddress,
+            referrerAddress,
+            chainId,
+            signature,
+            nonce,
+            expiry,
+            options: {
+                rpcUrl: this.requireActiveNetwork().rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * @function fetchPointsLeaderboard fetches the points leaderboard data
+     * @param params Optional parameters for pagination and sorting
+     * @returns Leaderboard response data
+     */
+    async fetchPointsLeaderboard(params) {
+        const { fetchPointsLeaderboard } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await fetchPointsLeaderboard({
+            params,
+            options: {
+                rpcUrl: this.requireActiveNetwork().rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Get annualized APY metrics for a vault.
+     *
+     * Supported Vaults: cUSDO, tETH, wstETH, rsETH
+     *
+     * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated.
+     * These fields will be removed on 2026-01-01.
+     * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
+     *
+     * @param vault Vault address
+     * @returns Annualized APY data including liquidity APY
+     */
+    async getVaultAnnualizedApy(vault) {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        const { getVaultAnnualizedApy } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getVaultAnnualizedApy({
+            vault,
+            options: {
+                rpcUrl: this.requireActiveNetwork().rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Get summary data for a vault (name, type, chain, recent returns).
+     * @param vault Vault address
+     * @returns Vault summary data
+     */
+    async getVaultSummary(vault) {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        const { getVaultSummary } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getVaultSummary({
+            vault,
+            options: {
+                rpcUrl: this.requireActiveNetwork().rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Get withdrawal summary and pending queue for a vault.
+     * @param vault Vault address
+     * @param chainId Chain ID (will be converted to chain name)
+     * @returns Withdrawal summary and pending queue
+     */
+    async getVaultWithdrawals(vault, chainId) {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        const chain = chainId?.toString() || this.requireActiveNetwork().chainId.toString();
+        const { getVaultWithdrawals } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getVaultWithdrawals({
+            vault,
+            chain,
+            options: {
+                rpcUrl: this.requireActiveNetwork().rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Fetch pending redemptions for a vault with liquidity analysis.
+     * @param vault - Vault contract address
+     * @param pastDays - Number of past days to include (default 7, min 1, max 30)
+     * @param futureDays - Number of future days to include (default 14, min 1, max 30)
+     * @returns Pending redemptions grouped by date with liquidity summary
+     */
+    async getVaultPendingRedemptions({ vault, pastDays, futureDays, }) {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault))
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        const { getVaultPendingRedemptions } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getVaultPendingRedemptions({
+            vault,
+            pastDays,
+            futureDays,
+            options: {
+                rpcUrl: this.requireActiveNetwork().rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Preview the amount of assets that would be received for redeeming shares (queued redemption).
+     * @param vault Vault contract address
+     * @param sharesAmount Amount of shares to redeem (human-readable, raw bigint, or string)
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns The amount of assets as INormalizedNumber { normalized, raw }
+     */
+    async previewRedemption({ vault, sharesAmount, chainId, }) {
+        const rpcUrl = chainId
+            ? this.providers?.[chainId]
+            : this.requireActiveNetwork().rpcUrl;
+        return await (0, getters_1.getPreviewRedemption)({
+            vault,
+            sharesAmount,
+            options: {
+                rpcUrl,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Get all withdrawal requests for a vault with deterministic status tracking.
+     *
+     * Matches requests to processed events by `(receiver, claimableDate)` tuple.
+     *
+     * **Status values:**
+     * - `'processed'` — Matching `WithdrawalProcessed` event found on-chain.
+     * - `'ready_to_claim'` — Claimable date has passed, no processed event found yet.
+     * - `'pending'` — Claimable date is still in the future.
+     *
+     * **Lookback window:** Processed events are fetched from on-chain logs, which
+     * only cover a finite block range. Requests whose claimable date is older than
+     * this window with no matching processed event are excluded (assumed already
+     * processed). Use `lookbackBlocks` to widen or narrow the scan range.
+     *
+     * @param vault - Vault contract address
+     * @param receiver - Optional receiver address to filter by
+     * @param lookbackBlocks - Optional on-chain log lookback window in blocks.
+     *   Defaults to chain-specific value (e.g. 150,000 for Ethereum, 3,456,000 for Monad).
+     * @param chainId - Optional chain id for the vault address
+     * @returns Array of withdrawal requests with status and claimable dates
+     */
+    async getWithdrawalRequestsWithStatus(vault, receiver, lookbackBlocks, chainId) {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        if (!(0, ethers_1.isAddress)(vault)) {
+            throw new Error(`Vault parameter is not an address: ${String(vault)}`);
+        }
+        const rpcUrl = (chainId && this.providers?.[chainId]) ||
+            this.requireActiveNetwork().rpcUrl;
+        const { getWithdrawalRequestsWithStatus } = await Promise.resolve().then(() => __importStar(require('./getters')));
+        return await getWithdrawalRequestsWithStatus({
+            vault,
+            receiver,
+            lookbackBlocks,
+            options: {
+                rpcUrl,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+        });
+    }
+    /**
+     * Redeem vault shares for an underlying asset via instant redemption (RWA subaccount).
+     * Resolves the vault address to the RwaRedeemSubaccount internally.
+     * Handles vault share approval automatically.
+     * @param signer - Signer / wallet object
+     * @param vault - Vault contract address
+     * @param asset - Redeemable asset address (e.g. USDC, USDT)
+     * @param amount - Amount of vault shares to redeem
+     * @param minOut - Minimum output amount in output asset units (slippage protection)
+     * @param chainId - Optional chain ID (uses active network if not provided)
+     * @param wait - Wait for transaction confirmation
+     * @returns transaction hash
+     */
+    async rwaRedeemAsset(signer, { vault, asset, amount, minOut, chainId, wait, }) {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        // Fetch vault data to resolve subaccount address and decimals
+        const vaultData = await (0, getters_1.getVault)({
+            vault,
+            loans: false,
+            allocations: false,
+            options: {
+                rpcUrl: chainId ? this.providers?.[chainId] : this.activeNetwork.rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+            loadSnapshots: false,
+            loadSubaccounts: false,
+        });
+        if (!vaultData?.instant_redeem_config) {
+            throw new Error(`Vault ${vault} does not support instant redemption.`);
+        }
+        const { subaccountAddress, redeemableAssets } = vaultData.instant_redeem_config;
+        // Resolve output asset decimals from config
+        const redeemableAsset = redeemableAssets.find((a) => a.address.toLowerCase() === asset.toLowerCase());
+        if (!redeemableAsset) {
+            throw new Error(`Asset ${asset} is not redeemable for vault ${vault}.`);
+        }
+        const walletAddress = (await signer.getAddress());
+        return (0, write_actions_1.rwaRedeemAsset)(signer, {
+            target: subaccountAddress,
+            wallet: walletAddress,
+            asset,
+            amount,
+            minOut,
+            decimals: vaultData.decimals,
+            outputDecimals: redeemableAsset.decimals,
+            wait,
+        });
+    }
+    /**
+     * Preview the output amount for an RWA instant redemption.
+     * Resolves the vault address to the RwaRedeemSubaccount internally.
+     * @param vault - Vault contract address
+     * @param asset - Redeemable asset address (e.g. USDC, USDT)
+     * @param amount - Amount of vault shares to preview
+     * @param chainId - Optional chain ID (uses active network if not provided)
+     * @returns normalized number of the expected output amount (in output asset decimals)
+     */
+    async previewRwaRedemption({ vault, asset, amount, chainId, }) {
+        if (!vault)
+            throw new Error('Vault address parameter is undefined.');
+        const rpcUrl = chainId
+            ? this.providers?.[chainId]
+            : this.activeNetwork.rpcUrl;
+        // Fetch vault data to resolve subaccount address and decimals
+        const vaultData = await (0, getters_1.getVault)({
+            vault,
+            loans: false,
+            allocations: false,
+            options: {
+                rpcUrl,
+                solanaService: this.solanaService,
+                stellarRpc: this._stellarRpc,
+                env: this.monitoring?.env,
+                augustKey: this.keys?.august,
+                subgraphKey: this.keys?.graph,
+                headers: this.headers,
+            },
+            loadSnapshots: false,
+            loadSubaccounts: false,
+        });
+        if (!vaultData?.instant_redeem_config) {
+            throw new Error(`Vault ${vault} does not support instant redemption.`);
+        }
+        const { subaccountAddress, redeemableAssets } = vaultData.instant_redeem_config;
+        // Resolve output asset decimals from config
+        const redeemableAsset = redeemableAssets.find((a) => a.address.toLowerCase() === asset.toLowerCase());
+        if (!redeemableAsset) {
+            throw new Error(`Asset ${asset} is not redeemable for vault ${vault}.`);
+        }
+        const provider = (0, core_1.createProvider)(rpcUrl);
+        return (0, read_actions_1.previewRwaRedemption)(provider, {
+            target: subaccountAddress,
+            asset,
+            amount,
+            decimals: vaultData.decimals,
+            outputDecimals: redeemableAsset.decimals,
+        });
+    }
+}
+exports.AugustVaults = AugustVaults;
+exports.default = AugustVaults;
+//# sourceMappingURL=main.js.map