/** * The August Vaults Module. * * @module AugustVaults */ /** * Export getters */ export * from './getters'; import type { IAddress, IChainId, IGetOriginInfoOptions, INormalizedNumber, IOriginInfo, IVaultHistoricalParams, IVaultPosition, IVaultUserHistoryItem } from '../../types'; import type SolanaAdapter from '../../adapters/solana'; import { AugustBase, type IAugustBase } from '../../core'; import SuiAdapter from '../../adapters/sui'; import { type IContractWriteOptions, type INativeDepositOptions } from './write.actions'; import type { Signer, Wallet } from 'ethers'; import type { IGetVaultsOptions, IVaultBaseOptions, IVaultCustomOptions } from './types'; export type { IGetVaultsOptions, 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; /** * 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`). */ private _stellarRpc?; 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; /** * @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; /** * 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 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 */ getVaults(options?: IGetVaultsOptions): Promise; /** * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl. * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD. * Wrapper vaults (non-null `underlying_vault_address`) are skipped: their * deposits sit in the underlying vault as LP and are already counted there. * @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; /** * 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. */ getVault({ vault, chainId, options, loadSubaccounts, loadSnapshots, }: { vault: IAddress; chainId?: IChainId; options?: IVaultCustomOptions; loadSubaccounts?: boolean; loadSnapshots?: boolean; }): Promise; /** * 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. */ getVaultLoans({ vault, chainId, }: { vault: IAddress; chainId?: IChainId; }): Promise; /** * 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. */ getVaultSubaccountLoans({ vault, chainId, }: { vault: IAddress; chainId?: IChainId; }): Promise; /** * 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. */ getVaultAllocations({ vault, chainId, }: { vault: IAddress; chainId?: IChainId; }): Promise; /** * @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; }): Promise<{ 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; /** * A wallet's redemption requests on one vault, split into * `availableRedemptions` and `pendingRedemptions`. EVM, Stellar and Solana * vault addresses are accepted; see `AugustSDK.getVaultAvailableRedemptions` * for what each list holds on Solana. * * @param props - `vault`, the vault address; `chainId`, the EVM chain whose * RPC to use (the active network when omitted); `wallet`, the holder, * required for Solana, where it is base58; `verbose`, to also return the * processed and requested withdrawal lists (always empty for Solana). * @returns `{ availableRedemptions, pendingRedemptions }`, plus the verbose lists. * @throws Error when unauthorized, or when `vault` is missing or not an address. */ getVaultAvailableRedemptions({ vault, chainId, wallet, verbose, }: { vault: IAddress; chainId?: number; wallet?: IAddress; verbose?: boolean; }): Promise<{ processedWithdrawals: import("../../types").ISubgraphWithdrawProccessed[]; requestedWithdrawals: import("../../types").ISubgraphWithdrawRequest[]; 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; /** * 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 * 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. */ getVaultPositions({ vault, wallet, chainId, showAllVaults, solanaWallet, stellarWallet, options, }: { vault?: IAddress; wallet?: IAddress; chainId?: IChainId; showAllVaults?: boolean; solanaWallet?: string; stellarWallet?: string; options?: IVaultBaseOptions; }): Promise; /** * */ getUserHistory({ wallet, chainId, vault, }: { wallet: IAddress; chainId?: IChainId; vault?: IAddress; options?: IVaultBaseOptions; }): Promise; /** * 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 * @throws {@link AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a * live position has no indexed deposits, withdrawals or priceable share * transfers. * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the * vault's underlying asset has no USD price. */ getVaultUserLifetimePnl({ vault, wallet, chainId, }: { vault: IAddress; wallet: IAddress; chainId?: IChainId; }): Promise; /** * 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; /** * */ getUserTransfers({ wallet, chainId, vault, options, }: { wallet: IAddress; chainId?: IChainId; vault?: IAddress; options?: IVaultBaseOptions; }): Promise<{ id: string; value: string; to: string; from: string; pool: string; block: number; timestamp: number; transactionHash: string; }[]>; /** * 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`); * ``` */ getVaultActivity({ vault, chainId, sinceTs, untilTs, types, }: { vault: IAddress; chainId?: IChainId; sinceTs?: number; untilTs?: number; types?: IVaultUserHistoryItem['type'][]; }): Promise; /** * 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); * ``` */ getSwapRouterWhitelistedTokens(chainId: number, options?: { fromBlock?: number; }): Promise; /** * 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); * ``` */ getSwapRouterEligibleVaults(chainId: number, options?: { fromBlock?: number; }): Promise; /** * Read a SwapRouter origin code's on-chain registration through this * instance's provider for `chainId`. See {@link getOriginInfo} for the * registration rule and caching. * * @param options - `chainId` and the `bytes32` `originCode` to look up. * @returns {@link IOriginInfo}. * @throws AugustValidationError (`INVALID_CHAIN`) when no provider is * configured for `chainId`; (`INVALID_INPUT`) for a malformed code. * @throws AugustSDKError when the `origins(bytes32)` read fails. * @worstCaseRpcCalls 1 — one `origins(bytes32)` read, cached for 5 minutes. * @example * ```ts * const info = await augustSdk.getOriginInfo({ chainId: 1, originCode }); * ``` */ getOriginInfo(options: Omit): Promise; /** * @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; /** * @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; historical?: IVaultHistoricalParams; }): Promise<{ 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; /** * 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[]>; /** * @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; /** * 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; /** * @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; /** * 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 in the next major release. * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead. * * @param vault Vault address * @returns Annualized APY data including liquidity APY */ getVaultAnnualizedApy(vault: IAddress): Promise; /** * Get summary data for a vault (name, type, chain, recent returns). * @param vault Vault address * @returns Vault summary data */ getVaultSummary(vault: IAddress): Promise; /** * 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; /** * 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; /** * 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; /** * 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; /** * 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; amount: string | bigint | number; minOut: string | bigint | number; chainId?: IChainId; wait?: boolean; }): Promise; /** * 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; amount: string | bigint | number; chainId?: IChainId; }): Promise; } export default AugustVaults;