@augustdigital/sdk 8.3.1 → 8.5.0

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

@@ -1,5 +1,30 @@
 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;
@@ -8,8 +33,25 @@ export declare function getVault({ vault, loans, allocations, options, loadSubac
     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, }: {
     vault: IAddress;
@@ -29,6 +71,9 @@ export declare function getVaultRedemptionHistory({ vault, wallet, lookbackBlock
     lookbackBlocks?: number;
     options: IVaultBaseOptions;
 }): Promise<IVaultRedemptionHistoryItem[]>;
+/**
+ * Vault Positions
+ */
 export declare function getVaultPositions({ vault, wallet, solanaWallet, stellarWallet, options, }: {
     vault: IAddress;
     wallet?: IAddress;
@@ -36,6 +81,9 @@ export declare function getVaultPositions({ vault, wallet, solanaWallet, stellar
     stellarWallet?: string;
     options: IVaultBaseOptions;
 }): Promise<IVaultPosition[]>;
+/**
+ * @deprecated use getVaultHistoricalTimeseries instead
+ */
 export declare function getVaultApy({ vault, options, historical, }: {
     vault: IAddress;
     options?: IVaultBaseOptions;
@@ -57,18 +105,117 @@ export declare function getVaultTvl({ vault, options, historical, }: {
     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;
@@ -78,6 +225,12 @@ export declare function registerUserForPoints({ userAddress, referrerAddress, ch
     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;
@@ -86,16 +239,44 @@ export declare function fetchPointsLeaderboard({ params, options, }: {
     };
     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>;
+/**
+ * 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
+ *
+ * @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;
@@ -105,45 +286,159 @@ export declare function getVaultHistoricalTimeseries({ vault, nDays, options, }:
     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 INormalizedNumber { normalized, raw }
+ */
 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
+ * @param params.vault - Vault address to query
+ * @param params.receiver - (Optional) Filter by receiver address
+ * @param params.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.
+ * @param params.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;