@augustdigital/sdk 8.3.1 → 8.5.0

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

@@ -1,8 +1,20 @@
+/**
+ * Export getters
+ */
 export * from './getters';
 export * from './utils';
+/**
+ * AugustVaults class
+ */
 export * from './main';
+/**
+ * Export points-related functions
+ */
 export { getUserPoints, registerUserForPoints, fetchPointsLeaderboard, getYieldLastRealizedOn, } from './getters';
 export { fetchVaultMetadata } from './fetcher';
 export { getRewardMultiplierByTimestamp } from './utils';
+/**
+ * Export write/read actions
+ */
 export * from './write.actions';
 export * from './read.actions';

package/lib/modules/vaults/index.js

@@ -15,9 +15,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRewardMultiplierByTimestamp = exports.fetchVaultMetadata = exports.getYieldLastRealizedOn = exports.fetchPointsLeaderboard = exports.registerUserForPoints = exports.getUserPoints = void 0;
+/**
+ * Export getters
+ */
 __exportStar(require("./getters"), exports);
 __exportStar(require("./utils"), exports);
+/**
+ * AugustVaults class
+ */
 __exportStar(require("./main"), exports);
+/**
+ * Export points-related functions
+ */
 var getters_1 = require("./getters");
 Object.defineProperty(exports, "getUserPoints", { enumerable: true, get: function () { return getters_1.getUserPoints; } });
 Object.defineProperty(exports, "registerUserForPoints", { enumerable: true, get: function () { return getters_1.registerUserForPoints; } });
@@ -27,6 +36,9 @@ var fetcher_1 = require("./fetcher");
 Object.defineProperty(exports, "fetchVaultMetadata", { enumerable: true, get: function () { return fetcher_1.fetchVaultMetadata; } });
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "getRewardMultiplierByTimestamp", { enumerable: true, get: function () { return utils_1.getRewardMultiplierByTimestamp; } });
+/**
+ * Export write/read actions
+ */
 __exportStar(require("./write.actions"), exports);
 __exportStar(require("./read.actions"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1,28 +1,96 @@
+/**
+ * The August Vaults Module.
+ *
+ * @module AugustVaults
+ */
+/**
+ * Export getters
+ */
 export * from './getters';
 import type { IAddress, IChainId, INormalizedNumber, IVaultHistoricalParams, IVaultPosition, IVaultUserHistoryItem } from '../../types';
-import SolanaAdapter from '../../adapters/solana';
-import { AugustBase, IAugustBase } from '../../core';
+import type SolanaAdapter from '../../adapters/solana';
+import { AugustBase, type IAugustBase } from '../../core';
 import SuiAdapter from '../../adapters/sui';
-import { IContractWriteOptions, INativeDepositOptions } from './write.actions';
-import { Signer, Wallet } from 'ethers';
+import { type IContractWriteOptions, type INativeDepositOptions } from './write.actions';
+import type { Signer, Wallet } from 'ethers';
 import type { IVaultBaseOptions, IVaultCustomOptions } from './types';
 export type { IVaultBaseOptions, IVaultCustomOptions } from './types';
+/**
+ * Vault operations class handling multi-chain vault queries and user positions.
+ * Supports both EVM and Solana vaults with unified interface.
+ */
 export declare class AugustVaults extends AugustBase {
     private solanaService;
     private suiService;
     private headers;
     constructor(baseConfig: IAugustBase, solana: SolanaAdapter, sui: SuiAdapter);
+    /**
+     * @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
+     */
     vaultDeposit(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string>;
+    /**
+     * @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
+     */
     depositNative(signer: Signer | Wallet, options: INativeDepositOptions): Promise<string>;
+    /**
+     * 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.
+     * @param options Filtering and enrichment configuration
+     * @returns Array of vault objects with optional loans/allocations/positions
+     */
     getVaults(options?: {
         chainIds?: number[];
         loadSubaccounts?: boolean;
         loadSnapshots?: boolean;
+        /**
+         * Portfolio mode: include closed vaults in the result.
+         *
+         * By default (`false`) closed vaults are excluded, so marketplace /
+         * discovery callers never receive a `status: 'closed'` vault. When set,
+         * closed vaults are returned regardless of `is_visible` (closed +
+         * invisible vaults bucket as closed), so a consumer joining user
+         * positions can render a position held in a closed vault on the
+         * portfolio page.
+         *
+         * In this mode, loans/allocations enrichment is also skipped for closed
+         * vaults: they have none, and the per-vault enrichment
+         * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
+         * vault has no live strategy/debank data or no subaccounts, which would
+         * land the vault in the `failed` bucket and silently drop it before it
+         * reaches the filter. Skipping enrichment lets the vault survive on its
+         * backend metadata + base on-chain read.
+         *
+         * @default false
+         */
+        includeClosed?: boolean;
     } & IVaultCustomOptions): Promise<import("../../types").IVault[]>;
+    /**
+     * 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)
+     */
     getTotalDeposited(options?: {
         loadSubaccounts?: boolean;
         loadSnapshots?: boolean;
     }): Promise<number>;
+    /**
+     * 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
+     */
     getVault({ vault, chainId, options, loadSubaccounts, loadSnapshots, }: {
         vault: IAddress;
         chainId?: IChainId;
@@ -30,14 +98,23 @@ export declare class AugustVaults extends AugustBase {
         loadSubaccounts?: boolean;
         loadSnapshots?: boolean;
     }): Promise<import("../../types").IVault>;
+    /**
+     *
+     */
     getVaultLoans({ vault, chainId, }: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("../../types").IVaultLoan[]>;
+    /**
+     *
+     */
     getVaultSubaccountLoans({ vault, chainId, }: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("../../types").IVaultLoan[]>;
+    /**
+     *
+     */
     getVaultAllocations({ vault, chainId, }: {
         vault: IAddress;
         chainId?: IChainId;
@@ -45,6 +122,13 @@ export declare class AugustVaults extends AugustBase {
         status: number;
         message: string;
     }>;
+    /**
+     * @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
+     */
     getVaultApy({ vault, historical, }: {
         vault: IAddress;
         historical?: Partial<IVaultHistoricalParams>;
@@ -52,10 +136,19 @@ export declare class AugustVaults extends AugustBase {
         value: number;
         timestamp: string;
     }[]>;
+    /**
+     * @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
+     */
     getVaultHistoricalTimeseries({ vault, nDays, }: {
         vault: IAddress;
         nDays?: number;
     }): Promise<import("../../types").IHistoricalTimeseriesResponse>;
+    /**
+     *
+     */
     getVaultAvailableRedemptions({ vault, chainId, wallet, verbose, }: {
         vault: IAddress;
         chainId?: number;
@@ -67,12 +160,44 @@ export declare class AugustVaults extends AugustBase {
         availableRedemptions: import("../../types").IVaultAvailableRedemption[];
         pendingRedemptions: import("../../types").IVaultAvailableRedemption[];
     }>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
     getVaultRedemptionHistory({ vault, chainId, wallet, lookbackBlocks, }: {
         vault: IAddress;
         chainId?: IChainId;
         wallet?: IAddress;
         lookbackBlocks?: number;
     }): Promise<import("../../types").IVaultRedemptionHistoryItem[]>;
+    /**
+     *
+     */
     getVaultPositions({ vault, wallet, chainId, showAllVaults, solanaWallet, stellarWallet, options, }: {
         vault?: IAddress;
         wallet?: IAddress;
@@ -82,21 +207,38 @@ export declare class AugustVaults extends AugustBase {
         stellarWallet?: string;
         options?: IVaultBaseOptions;
     }): Promise<IVaultPosition[]>;
+    /**
+     *
+     */
     getUserHistory({ wallet, chainId, vault, }: {
         wallet: IAddress;
         chainId?: IChainId;
         vault?: IAddress;
         options?: IVaultBaseOptions;
     }): Promise<IVaultUserHistoryItem[]>;
+    /**
+     * 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
+     */
     getVaultUserLifetimePnl({ vault, wallet, chainId, }: {
         vault: IAddress;
         wallet: IAddress;
         chainId?: IChainId;
     }): Promise<import("../../types").IVaultUserLifetimePnl>;
+    /**
+     * 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
+     */
     getVaultPnl({ vault, chainId, }: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("../../types").IVaultPnl>;
+    /**
+     *
+     */
     getUserTransfers({ wallet, chainId, vault, options, }: {
         wallet: IAddress;
         chainId?: IChainId;
@@ -112,7 +254,19 @@ export declare class AugustVaults extends AugustBase {
         timestamp: number;
         transactionHash: string;
     }[]>;
+    /**
+     * @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)
+     */
     getStakingPositions(wallet?: IAddress, chainId?: IChainId): Promise<import("../../types").IActiveStakingPosition[]>;
+    /**
+     * @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
+     */
     getVaultTvl({ vault, chainId, historical, }: {
         vault: IAddress;
         chainId?: IChainId;
@@ -121,32 +275,157 @@ export declare class AugustVaults extends AugustBase {
         value: INormalizedNumber;
         timestamp: string;
     }[]>;
+    /**
+     * @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
+     */
     getYieldLastRealizedOn({ vault, chainId, }: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<number>;
+    /**
+     * 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).
+     */
     getVaultBorrowerHealthFactor(chainId?: IChainId, vault?: IAddress): Promise<Record<string, import("../../types").IVaultBorrowerHealthFactor[]> | Record<string, import("../../types").IVaultBorrowerHealthFactor[]>[]>;
+    /**
+     * @function getUserPoints fetches user points from the backend API
+     * @param userAddress User wallet address
+     * @returns Points data from the backend API
+     */
     getUserPoints(userAddress: IAddress): Promise<any>;
+    /**
+     * 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.
+     */
     registerUserForPoints(userAddress: IAddress, referrerAddress: IAddress | undefined, chainId: number, signature: string, nonce: string, expiry: number): Promise<Response>;
+    /**
+     * @function fetchPointsLeaderboard fetches the points leaderboard data
+     * @param params Optional parameters for pagination and sorting
+     * @returns Leaderboard response data
+     */
     fetchPointsLeaderboard(params?: {
         page?: number;
         perPage?: number;
         sortBy?: 'streakDays' | 'totalPoints';
     }): Promise<any>;
+    /**
+     * 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
+     */
     getVaultAnnualizedApy(vault: IAddress): Promise<import("../../types").IVaultAnnualizedApy>;
+    /**
+     * Get summary data for a vault (name, type, chain, recent returns).
+     * @param vault Vault address
+     * @returns Vault summary data
+     */
     getVaultSummary(vault: IAddress): Promise<import("../../types").IVaultSummary>;
+    /**
+     * 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
+     */
     getVaultWithdrawals(vault: IAddress, chainId?: number): Promise<import("../../types").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)
+     * @returns Pending redemptions grouped by date with liquidity summary
+     */
     getVaultPendingRedemptions({ vault, pastDays, futureDays, }: {
         vault: IAddress;
         pastDays?: number;
         futureDays?: number;
     }): Promise<import("../../types").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 chainId Optional chain ID (uses active network if not provided)
+     * @returns The amount of assets as INormalizedNumber { normalized, raw }
+     */
     previewRedemption({ vault, sharesAmount, chainId, }: {
         vault: IAddress;
         sharesAmount: string | bigint | number;
         chainId?: IChainId;
     }): Promise<INormalizedNumber>;
+    /**
+     * 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
+     */
     getWithdrawalRequestsWithStatus(vault: IAddress, receiver?: IAddress, lookbackBlocks?: number, chainId?: number): Promise<import("./getters").WithdrawalRequestStatus[]>;
+    /**
+     * 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
+     */
     rwaRedeemAsset(signer: Signer | Wallet, { vault, asset, amount, minOut, chainId, wait, }: {
         vault: IAddress;
         asset: IAddress;
@@ -155,6 +434,15 @@ export declare class AugustVaults extends AugustBase {
         chainId?: IChainId;
         wait?: boolean;
     }): Promise<string>;
+    /**
+     * 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)
+     */
     previewRwaRedemption({ vault, asset, amount, chainId, }: {
         vault: IAddress;
         asset: IAddress;