upshift-config 0.5.14

package/lib/modules/vaults/getters.d.ts

@@ -0,0 +1,570 @@
+import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
+import type { IVaultBaseOptions } from './types';
+/**
+ * Vault Data Getters
+ *
+ * Main query functions for vault data across chains:
+ * - getVault: Comprehensive vault details with loans/allocations
+ * - getVaultLoans: Active loan data with on-chain enrichment
+ * - getVaultAllocations: DeFi/CeFi/OTC allocation breakdowns
+ * - getVaultAvailableRedemptions: Claimable redemption requests
+ * - getVaultRedemptionHistory: Historical redemption data
+ * - getVaultPositions: User positions across vaults
+ * - getVaultApy: @deprecated Current and historical APY data
+ * - getRewardsStakingPositions: Staking positions and rewards
+ * - getVaultTvl: Current and historical TVL
+ * - getVaultHistoricalTimeseries: Time series data for vault metrics
+ */
+/**
+ * Fetch comprehensive vault data including on-chain state and backend metadata.
+ * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
+ * Optionally enriches with loan and allocation data.
+ * @param vault - Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
+ * @param loans - Include active loan data
+ * @param allocations - Include DeFi/CeFi allocation breakdowns
+ * @param options - RPC and service configuration
+ * @returns Complete vault object with optional enrichments
+ */
+export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, }: {
+    vault: IAddress;
+    loans?: boolean;
+    allocations?: boolean;
+    options: IVaultBaseOptions;
+    loadSubaccounts?: boolean;
+    loadSnapshots?: boolean;
+}): Promise<IVault>;
+/**
+ * Vault Loans
+ */
+export declare function getVaultLoans(vault: VaultAddress | IVault, options: IVaultBaseOptions): Promise<IVaultLoan[]>;
+/**
+ * Vault Subaccount Loans
+ */
+export declare function getVaultSubaccountLoans(vault: VaultAddress | IVault, options: IVaultBaseOptions): Promise<IVaultLoan[]>;
+/**
+ * Vault Allocations
+ */
+/**
+ * Fetch comprehensive vault asset allocation breakdown.
+ * Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans.
+ * Categorizes exposures by borrowing, supplying, lending, and wallet holdings.
+ * @param vault - Vault address
+ * @param options - RPC configuration
+ * @returns Detailed allocation data with exposure categorization
+ */
+export declare function getVaultAllocations(vault: IAddress, options: IVaultBaseOptions): Promise<IVaultAllocations>;
+export declare function getVaultAvailableRedemptions({ vault, wallet, options, prefetchedReads, }: {
+    vault: IAddress;
+    wallet?: IAddress;
+    options: IVaultBaseOptions & {
+        verbose?: boolean;
+    };
+    /**
+     * Values already read via a Multicall3 batch (see
+     * `modules/vaults/prefetch.ts`). When `lagDuration` is present the
+     * per-vault `lagDuration()` RPC is skipped; when omitted, behavior is
+     * exactly the pre-batching per-call path.
+     * @internal
+     */
+    prefetchedReads?: {
+        lagDuration?: number;
+    };
+}): Promise<{
+    processedWithdrawals: ISubgraphWithdrawProccessed[];
+    requestedWithdrawals: import("../../types").ISubgraphWithdrawRequest[];
+    availableRedemptions: IVaultAvailableRedemption[];
+    pendingRedemptions: IVaultAvailableRedemption[];
+}>;
+export declare function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, options, }: {
+    vault: IAddress;
+    wallet?: IAddress;
+    lookbackBlocks?: number;
+    options: IVaultBaseOptions;
+}): Promise<IVaultRedemptionHistoryItem[]>;
+export { getSwapRouterDepositResult } from '../../core/helpers/swap-router';
+/**
+ * Vault Positions
+ */
+export declare function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, prefetchedReads, }: {
+    vault: IAddress;
+    wallet?: IAddress;
+    solanaWallet?: string;
+    stellarWallet?: string;
+    options: IVaultBaseOptions;
+    /**
+     * Per-vault values already read via a Multicall3 batch at the fan-out call
+     * sites (see `modules/vaults/prefetch.ts`). Supplied fields skip the
+     * corresponding `balanceOf` / `lagDuration` RPC for the vault matching the
+     * `vault` parameter; when omitted, behavior is exactly the pre-batching
+     * per-call path.
+     * @internal
+     */
+    prefetchedReads?: {
+        balance?: bigint;
+        lagDuration?: number;
+    };
+}): Promise<IVaultPosition[]>;
+/**
+ * @deprecated use getVaultHistoricalTimeseries instead
+ */
+export declare function getVaultApy({ vault, options, historical, }: {
+    vault: IAddress;
+    options?: IVaultBaseOptions;
+    historical?: IVaultHistoricalParams;
+}): Promise<{
+    value: number;
+    timestamp: string;
+}[]>;
+export declare function getRewardsStakingPositions({ rpcUrl, wallet, coinGeckoKey, }: {
+    wallet?: IAddress;
+    rpcUrl: string;
+    coinGeckoKey?: string;
+}): Promise<IActiveStakingPosition[]>;
+export declare function getVaultTvl({ vault, options, historical, }: {
+    vault: IAddress;
+    options: IVaultBaseOptions;
+    historical?: IVaultHistoricalParams;
+}): Promise<{
+    value: INormalizedNumber;
+    timestamp: string;
+}[]>;
+/**
+ * Build the per-loan borrower / health-factor list for a single vault.
+ *
+ * Resilience: individual loan reads (`loanState()`, `borrower()`) and the
+ * per-borrower August backend call are isolated with `Promise.allSettled` and
+ * try/catch so one bad loan — a test loan whose address isn't a real contract,
+ * a borrower the backend doesn't recognize, an intermittent RPC error — drops
+ * that single row from the result instead of rejecting the whole batch. Failed
+ * rows are logged via `Logger.log.warn`; the loan is still returned with
+ * `health_factor: undefined` so callers can render an explicit empty state
+ * rather than a perpetual loading skeleton.
+ *
+ * @param vault - Vault address to scope the fetch to.
+ * @param options - Standard vault options — `rpcUrl` must point at `vault`'s chain.
+ * @returns Array of `IVaultBorrowerHealthFactor`, one entry per active loan.
+ */
+export declare function getVaultBorrowerHealthFactor({ vault, options, }: {
+    vault: IAddress;
+    options: IVaultBaseOptions;
+}): Promise<IVaultBorrowerHealthFactor[]>;
+/**
+ * Aggregate borrower-health-factor data, optionally scoped to a single vault.
+ *
+ * - When `vault` is provided, only that vault's tokenized record is fetched
+ *   and only its loans are read. This is the path callers should use when
+ *   they already know which vault they care about — it skips the cross-chain
+ *   fanout entirely.
+ * - When `vault` is omitted, the function fetches every tokenized vault and
+ *   builds health factors for each, preserving the legacy behavior. Per-vault
+ *   failures are isolated with `Promise.allSettled` so one bad vault returns
+ *   an empty array instead of rejecting the whole map.
+ *
+ * The returned map is keyed by **lowercased** vault address so callers can
+ * look up entries without worrying about EIP-55 checksum casing in either the
+ * backend response or the caller's input.
+ *
+ * @param options - Standard vault options — `rpcUrl` should match `vault`'s chain.
+ * @param vault - Optional vault address to scope the fetch to.
+ * @returns Map of lowercased vault address → array of borrower-health-factor rows.
+ */
+export declare function getHealthFactorOfBorrowersByVault({ options, vault, }: {
+    options: IVaultBaseOptions;
+    vault?: IAddress;
+}): Promise<Record<string, IVaultBorrowerHealthFactor[]>>;
+/**
+ * Fetch user points from the backend API endpoint.
+ * This replaces client-side points calculation with server-side processing.
+ * @param userAddress - User wallet address (EVM or Solana)
+ * @param options - Request options including headers
+ * @returns Points data from the backend API
+ */
+export declare function getUserPoints({ userAddress, options, }: {
+    userAddress: IAddress;
+    options?: IVaultBaseOptions;
+}): Promise<any>;
+/**
+ * Register a user for the points program, authenticated by a wallet signature.
+ *
+ * The caller must obtain a personal_sign (EIP-191) signature over the
+ * canonical message template below — the backend reconstructs the same
+ * string from these fields and verifies the signature recovers to
+ * `userAddress`. Building the message client-side and server-side from the
+ * same primitives means a hostile client cannot show one message in the
+ * wallet prompt while submitting a different one for validation.
+ *
+ * Canonical message (`\n`-separated, no trailing newline):
+ *
+ * ```
+ * Upshift: register {userAddress.toLowerCase()}
+ * referrer: {referrerAddress.toLowerCase() || "none"}
+ * chain: {chainId}
+ * nonce: {nonce}
+ * expires: {expiry}
+ * ```
+ *
+ * @param userAddress - EVM wallet address being registered. Must match the
+ *   signer that produced `signature`. Lowercased before being embedded in
+ *   the canonical message.
+ * @param referrerAddress - Optional EVM address that referred this user.
+ *   Lowercased when embedded; the literal string `"none"` is used when
+ *   absent. Tampering with this field after signing produces 401.
+ * @param chainId - Chain on which the wallet signed. For smart-contract wallets
+ *   (Safe etc.) this is the chain whose RPC the backend will use to run the
+ *   EIP-1271 `isValidSignature` check; for EOAs it still pins the signature
+ *   to a chain so it can't be replayed cross-chain. Must be one of the chains
+ *   Upshift supports (see backend `SUPPORTED_REGISTRATION_CHAINS`).
+ * @param signature - `0x`-prefixed hex of the personal_sign signature over
+ *   the canonical message. Single-use: replays within ~10 min are rejected.
+ * @param nonce - Caller-generated random string (8–128 chars). Pair with
+ *   `userAddress` to form the single-use key in the backend's nonce store.
+ * @param expiry - Unix timestamp (seconds). Must be in the future and within
+ *   the backend's TTL window (currently 10 min).
+ * @param options - Request options (headers).
+ * @returns Raw `Response` from the backend. 200 on success, 401 for
+ *   expired / replayed / mismatched-signer / tampered-referrer, 422 for an
+ *   unsupported `chainId`.
+ *
+ * @example
+ * ```ts
+ * const nonce = crypto.randomUUID().replace(/-/g, '');
+ * const expiry = Math.floor(Date.now() / 1000) + 300;
+ * const message =
+ *   `Upshift: register ${address.toLowerCase()}\n` +
+ *   `referrer: ${referrer?.toLowerCase() ?? 'none'}\n` +
+ *   `chain: ${chainId}\n` +
+ *   `nonce: ${nonce}\n` +
+ *   `expires: ${expiry}`;
+ * const signature = await walletClient.signMessage({ account: address, message });
+ * await registerUserForPoints({ userAddress: address, referrerAddress: referrer, chainId, signature, nonce, expiry });
+ * ```
+ */
+export declare function registerUserForPoints({ userAddress, referrerAddress, chainId, signature, nonce, expiry, options, }: {
+    userAddress: IAddress;
+    referrerAddress?: IAddress;
+    chainId: number;
+    signature: string;
+    nonce: string;
+    expiry: number;
+    options?: IVaultBaseOptions;
+}): Promise<Response>;
+/**
+ * Fetch the points leaderboard data.
+ * @param params - Optional parameters for pagination and sorting
+ * @param options - Request options including headers
+ * @returns Leaderboard response data
+ */
+export declare function fetchPointsLeaderboard({ params, options, }: {
+    params?: {
+        page?: number;
+        perPage?: number;
+        sortBy?: 'streakDays' | 'totalPoints';
+    };
+    options?: IVaultBaseOptions;
+}): Promise<any>;
+/**
+ * Fetch the timestamp when yield was last realized for a vault.
+ * Returns the assetsUpdatedOn timestamp from the vault contract.
+ * @param vault - Vault contract address
+ * @param options - RPC configuration
+ * @returns Timestamp (Unix timestamp in seconds) when yield was last realized
+ */
+export declare function getYieldLastRealizedOn({ vault, options, }: {
+    vault: IAddress;
+    options: IVaultBaseOptions;
+}): Promise<number>;
+/** Inputs the lifetime-PnL history guard inspects. */
+export interface PnlHistoryConsistencyParams {
+    /** Vault contract address, used for the error message and context. */
+    vault: IAddress;
+    /** User wallet address, used for the error message and context. */
+    wallet: IAddress;
+    /**
+     * Whether the resolved deposit history contains at least one deposit record
+     * (subgraph deposits or LayerZero cross-chain deposits).
+     */
+    hasDeposits: boolean;
+    /** Total withdrawn, in raw base units (asset decimals). */
+    totalWithdrawnRaw: bigint;
+    /** Current on-chain position value, in raw base units (asset decimals). */
+    currentPositionRaw: bigint;
+}
+/**
+ * Guard against the 2026-07-09 lifetime-PnL over-inflation failure mode.
+ *
+ * Lifetime PnL is `currentPosition + totalWithdrawn - totalDeposited`. When the
+ * deposit/withdrawal history fails to load it collapses to empty, so both
+ * `totalDeposited` and `totalWithdrawn` read as zero. If the wallet still holds
+ * a live on-chain position, the formula degenerates to reporting the entire
+ * position as pure profit — a plausible-looking but wrong number.
+ *
+ * This guard rejects exactly that state: a non-zero position with no recorded
+ * deposits *and* no recorded withdrawals. Any of the following is treated as
+ * consistent and passes:
+ * - deposits are present (the normal, computable case);
+ * - withdrawals are present (a fully-exited-then-re-entered position is still
+ *   computable — the withdrawal records prove history loaded);
+ * - the current position is zero (the wallet never interacted or fully exited,
+ *   so a zero PnL is correct, not inflated).
+ *
+ * Pure and synchronous — no RPC, no I/O — so it is safe to call inside the hot
+ * path with no added latency.
+ *
+ * Known imprecision — vault shares are transferable ERC-20 receipt tokens, so a
+ * wallet that *received* shares via a direct token transfer (never deposited,
+ * never withdrew) legitimately has `position > 0` with no history records and
+ * will throw `HISTORY_UNAVAILABLE` even though its history loaded fine. This is
+ * not a regression — the pre-guard formula reported that same position as 100%
+ * profit, which was also wrong — but the error message is misleading for that
+ * (rare) path. If receipt-token transfer becomes a real user flow, distinguish
+ * it here (e.g. by checking for a share-transfer event) rather than widening
+ * the guard.
+ *
+ * @param params - See {@link PnlHistoryConsistencyParams}.
+ * @returns `void` when the history is consistent.
+ * @throws {@link AugustHistoryUnavailableError} with code `HISTORY_UNAVAILABLE`
+ *   and `context: { vault, wallet }` when a non-zero position has neither
+ *   deposits nor withdrawals recorded. The message carries the
+ *   `#getVaultUserLifetimePnl::<vault>::<wallet>` prefix so it groups with the
+ *   other errors leaving the getter.
+ * @example
+ * ```ts
+ * assertPnlHistoryConsistent({
+ *   vault,
+ *   wallet,
+ *   hasDeposits: depositsByAsset.size > 0,
+ *   totalWithdrawnRaw,
+ *   currentPositionRaw: currentPositionValue.raw,
+ * });
+ * ```
+ */
+export declare function assertPnlHistoryConsistent({ vault, wallet, hasDeposits, totalWithdrawnRaw, currentPositionRaw, }: PnlHistoryConsistencyParams): void;
+/**
+ * Sum a wallet's per-asset deposits into the vault's own decimals, at face
+ * value — 1 unit of any deposited asset is treated as 1 unit of the vault's
+ * reporting currency, with no live price conversion.
+ *
+ * Used by {@link getVaultUserLifetimePnl} for `totalDeposited`. Pre-deposit
+ * multi-asset vaults only accept dollar-pegged stablecoins (USDC, USDT, DAI,
+ * USDS, RLUSD, etc.) into a dollar-denominated vault, so face value is a
+ * reasonable stand-in for USD value. This intentionally does NOT re-quote
+ * through a live price oracle: doing so priced a historical deposit at
+ * today's market rate, so `totalDeposited` (and lifetimePnl) drifted between
+ * calls purely from stablecoin peg noise, and approximately re-inflated
+ * deposits back toward face value — which silently excluded the vault's
+ * entry fee from PnL. The fee is money the user actually paid, so PnL must
+ * be computed net of it.
+ *
+ * @param depositsByAsset - Raw deposited amount per asset, keyed by
+ *   lowercased asset address (or `'default'` / `'lz-default'` for
+ *   single-asset / cross-chain rows).
+ * @param assetDecimals - Decimals for each key in `depositsByAsset`.
+ * @param vaultDecimals - The vault's own decimals — the target scale every
+ *   asset is rescaled to.
+ * @returns Total deposited, in raw base units at `vaultDecimals`.
+ */
+export declare function sumDepositsAtFaceValue(depositsByAsset: Map<string, bigint>, assetDecimals: Map<string, number>, vaultDecimals: number): bigint;
+/**
+ * Calculate lifetime PnL for a user in a specific vault.
+ *
+ * Basic logic:
+ * 1. Get user's list of deposits and withdrawals from subgraph
+ * 2. Fetch user's current assets (balanceOf * sharePrice via convertToAssets)
+ * 3. Calculate PnL = assets withdrawn + current assets - assets deposited
+ *
+ * `totalDeposited` is the face value of what the user actually paid in
+ * (each deposited asset's raw amount, rescaled to the vault's decimals — no
+ * live price conversion), so any entry/exit fee the vault charges is
+ * automatically counted as a cost against PnL rather than excluded from it.
+ * Pre-deposit multi-asset vaults are assumed to only accept dollar-pegged
+ * stablecoins into a dollar-denominated vault; a vault accepting a
+ * non-pegged deposit asset would need deposit-time price conversion, which
+ * this function does not perform.
+ *
+ * @param vault - Vault contract address
+ * @param wallet - User wallet address
+ * @param options - RPC configuration and service options
+ * @returns Lifetime PnL data in both native token and USD
+ */
+export declare function getVaultUserLifetimePnl({ vault, wallet, options, }: {
+    vault: IAddress;
+    wallet: IAddress;
+    options: IVaultBaseOptions;
+    coingeckoKey?: string;
+}): Promise<IVaultUserLifetimePnl>;
+/**
+ * Calculate PnL for a vault (vault-level, not user-specific).
+ * Returns the vault's overall profit and loss across all users.
+ *
+ * @param vault - Vault contract address
+ * @param options - RPC configuration and service options
+ * @returns Vault PnL in USD and notional value
+ */
+export declare function getVaultPnl({ vault, options, }: {
+    vault: IAddress;
+    options: IVaultBaseOptions;
+}): Promise<IVaultPnl>;
+export declare function getVaultHistoricalTimeseries({ vault, nDays, options, }: {
+    vault: IAddress;
+    nDays?: number;
+    options?: IVaultBaseOptions;
+}): Promise<IHistoricalTimeseriesResponse>;
+/**
+ * Fetch 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 contract address
+ * @param options - Request options including headers
+ * @returns Annualized APY data including liquidity APY
+ */
+export declare function getVaultAnnualizedApy({ vault, options, }: {
+    vault: IAddress;
+    options?: IVaultBaseOptions;
+}): Promise<IVaultAnnualizedApy>;
+/**
+ * Fetch summary data for a vault (name, type, chain, recent returns).
+ * @param vault - Vault contract address
+ * @param options - Request options including headers
+ * @returns Vault summary data
+ */
+export declare function getVaultSummary({ vault, options, }: {
+    vault: IAddress;
+    options?: IVaultBaseOptions;
+}): Promise<IVaultSummary>;
+/**
+ * Fetch withdrawal summary and pending queue for a vault.
+ * @param vault - Vault contract address
+ * @param chain - Chain identifier (e.g., chain ID as string)
+ * @param options - Request options including headers
+ * @returns Withdrawal summary and pending queue
+ */
+export declare function getVaultWithdrawals({ vault, chain, options, }: {
+    vault: IAddress;
+    chain: string;
+    options?: IVaultBaseOptions;
+}): Promise<IVaultWithdrawals>;
+/**
+ * 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)
+ * @param options - Request options including headers
+ * @returns Pending redemptions grouped by date with liquidity summary
+ */
+export declare function getVaultPendingRedemptions({ vault, pastDays, futureDays, options, }: {
+    vault: IAddress;
+    pastDays?: number;
+    futureDays?: number;
+    options?: IVaultBaseOptions;
+}): Promise<IVaultPendingRedemptions>;
+/**
+ * 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 options - RPC configuration
+ * @returns The amount of assets as an INormalizedNumber with `normalized` and `raw` fields
+ */
+export declare function getPreviewRedemption({ vault, sharesAmount, options, }: {
+    vault: IAddress;
+    sharesAmount: string | bigint | number;
+    options: IVaultBaseOptions;
+}): Promise<INormalizedNumber>;
+/**
+ * Withdrawal request with computed claimable date and current processing status.
+ * The unique identifier is (receiver, claimableDate).
+ *
+ * @interface WithdrawalRequestStatus
+ */
+export interface WithdrawalRequestStatus {
+    /** Transaction hash of the withdrawal request */
+    transactionHash: string;
+    /** Block timestamp when the withdrawal was requested (seconds, UTC) */
+    requestTimestamp: number;
+    /** Shares amount being redeemed */
+    shares: bigint;
+    /** Receiver address for the withdrawal */
+    receiver: string;
+    /** Computed claimable date in UTC (year, month, day) */
+    claimableDate: {
+        year: number;
+        month: number;
+        day: number;
+    };
+    /** Epoch timestamp when this withdrawal becomes claimable */
+    claimableEpoch: number;
+    /** Current status of the withdrawal */
+    status: 'pending' | 'ready_to_claim' | 'processed';
+    /** Transaction hash of the processing transaction (if processed) */
+    processedTransactionHash?: string;
+    /** Assets received (if processed) */
+    assetsReceived?: bigint;
+}
+/**
+ * Returns all withdrawal requests for a vault, enriched with computed claimable dates
+ * and current processing status.
+ *
+ * The unique identifier for matching requests to processed events is:
+ * (receiver, claimableDate.year, claimableDate.month, claimableDate.day)
+ *
+ * This is the primary method for integrators to reliably track withdrawal status
+ * when multiple requests are submitted by the same receiver.
+ *
+ * ## Data sources
+ * - **Withdrawal requests** come from the subgraph (all historical requests).
+ * - **Processed events** come from on-chain `WithdrawalProcessed` logs, which are
+ *   limited to a finite lookback window determined by the chain's block parameters.
+ *
+ * ## Lookback window & filtering
+ * On-chain logs only cover a limited number of recent blocks (e.g. ~20 days on Monad,
+ * ~21 days on Ethereum). The `lookbackBlocks` parameter controls how far back to scan
+ * and is applied uniformly to both data sources: it bounds the `WithdrawalProcessed`
+ * log query *and* drops any withdrawal request whose submission timestamp falls outside
+ * the window — regardless of whether a matching processed event was found. Callers who
+ * need deeper history should widen `lookbackBlocks`.
+ *
+ * ## Status determination
+ * - `'processed'` — A matching `WithdrawalProcessed` event was found (by receiver + claimable date).
+ * - `'ready_to_claim'` — Claimable date has passed (within the lookback window) but no processed event found.
+ * - `'pending'` — Claimable date is still in the future.
+ *
+ * @param params - Query parameters:
+ *   - `vault` — Vault address to query.
+ *   - `receiver` — (Optional) Filter by receiver address.
+ *   - `lookbackBlocks` — (Optional) On-chain log lookback window in blocks.
+ *     Defaults to a chain-specific value (e.g. 150,000 for Ethereum, 3,456,000 for Monad).
+ *     Increasing this scans more history but requires more RPC calls.
+ *   - `options` — Standard vault query options (provider, RPC URL, etc.).
+ * @returns Array of withdrawal requests with status and claimable dates
+ *
+ * @example
+ * ```typescript
+ * const requests = await getWithdrawalRequestsWithStatus({
+ *   vault: '0xVault...',
+ *   receiver: '0xReceiver...'
+ * });
+ *
+ * // Results show exact status + claimable date
+ * requests.forEach(req => {
+ *   console.log(
+ *     `${req.claimableDate.year}-${req.claimableDate.month}-${req.claimableDate.day}: ${req.status}`
+ *   );
+ * });
+ *
+ * // With custom lookback window (e.g. 30 days on Ethereum ≈ 216,000 blocks)
+ * const moreResults = await getWithdrawalRequestsWithStatus({
+ *   vault: '0xVault...',
+ *   lookbackBlocks: 216_000,
+ * });
+ * ```
+ */
+export declare function getWithdrawalRequestsWithStatus(params: {
+    vault: IAddress;
+    receiver?: IAddress;
+    lookbackBlocks?: number;
+    options: IVaultBaseOptions;
+}): Promise<WithdrawalRequestStatus[]>;