augustdigital-sdk 8.20.1

package/lib/main.d.ts

@@ -0,0 +1,527 @@
+/**
+ * The main August SDK class.
+ *
+ * @module AugustSDK
+ */
+import SolanaAdapter from './adapters/solana';
+import SuiAdapter from './adapters/sui';
+import StellarAdapter from './adapters/stellar';
+import EVMAdapter from './adapters/evm';
+import type { IAddress, IChainId, IVaultHistoricalParams, IWSMonitorHeaders } from './types';
+import { AugustBase, type IAugustBase } from './core';
+import { AugustVaults, type IVaultBaseOptions, type IVaultCustomOptions } from './modules/vaults';
+import type { Signer, Wallet } from 'ethers';
+import type { IContractWriteOptions } from './modules/vaults/write.actions';
+import { AugustSubAccounts } from './modules/sub-accounts';
+import { AugustApi } from './modules/api';
+/**
+ * Main SDK class for interacting with August Digital vaults and services.
+ * Provides unified access to EVM, Solana, Sui, and Stellar blockchain adapters.
+ */
+export declare class AugustSDK extends AugustBase {
+    private vaults;
+    private subaccounts;
+    private api;
+    solana: SolanaAdapter;
+    sui: SuiAdapter;
+    stellar: StellarAdapter;
+    evm: EVMAdapter;
+    /**
+     * Initialize the August SDK with provider configuration.
+     * Automatically sets up EVM adapter and optionally initializes Solana if RPC URL is provided.
+     */
+    constructor(baseConfig: IAugustBase);
+    /**
+     * Get the Sub-Accounts module instance.
+     */
+    get subAccountsModule(): AugustSubAccounts;
+    /**
+     * Get the Vaults module instance.
+     */
+    get vaultsModule(): AugustVaults;
+    /**
+     * Get the backend API module instance ({@link AugustApi}) — read-only
+     * access to backend-computed data with no on-chain equivalent
+     * (unrealized-PnL series).
+     */
+    get apiModule(): AugustApi;
+    /**
+     * Switch the active network for vault operations.
+     * Updates the SDK's active chain and RPC provider.
+     */
+    switchNetwork(chainId: IChainId): void;
+    /**
+     * Set the active wallet address for tracking user-specific vault data.
+     * Updates monitoring headers with the wallet address.
+     */
+    updateWallet(address: IAddress): void;
+    /**
+     * Clear the active wallet address from the SDK state and monitoring headers.
+     */
+    clearWallet(): void;
+    /**
+     * Pricing and Market Data
+     */
+    /**
+     * Get the current USD price of a token by symbol or contract address.
+     * Falls back to CoinGecko if primary price source fails.
+     *
+     * @param symbol - Token symbol or contract address
+     * @returns Current price in USD
+     */
+    getPrice(symbol: string): Promise<number>;
+    /**
+     * Vault Data and Operations
+     */
+    /**
+     * Fetch all available vaults across configured networks.
+     * Optionally filter by chain IDs and include loan/allocation data.
+     * @param options - Configuration for filtering and enriching vault data
+     * @returns Array of vault objects with metadata and optional position data
+     */
+    getVaults(options?: {
+        chainIds?: number[];
+        headers?: IWSMonitorHeaders;
+        loadSubaccounts?: boolean;
+        loadSnapshots?: boolean;
+    } & IVaultCustomOptions): Promise<import("./types").IVault[]>;
+    getTotalDeposited(options?: {
+        loadSubaccounts?: boolean;
+        loadSnapshots?: boolean;
+    }): Promise<number>;
+    /**
+     * Fetch all available vaults across configured networks.
+     * Optionally filter by chain IDs and include loan/allocation data.
+     * @param options - Configuration for filtering and enriching vault data
+     * @returns Array of vault objects with metadata and optional position data
+     */
+    vaultDeposit(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string>;
+    /**
+     * Fetch detailed information for a specific vault.
+     * @param props - Vault address, chain ID, and optional enrichment options
+     * @returns Single vault object with full metadata
+     */
+    getVault(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+        options?: IVaultCustomOptions;
+        loadSubaccounts?: boolean;
+        loadSnapshots?: boolean;
+    }): Promise<import("./types").IVault>;
+    /**
+     * Get active loans deployed from a vault.
+     * @param props - Vault address and chain ID
+     * @returns Array of loan details including borrower, principal, APR
+     */
+    getVaultLoans(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+    }): Promise<import("./types").IVaultLoan[]>;
+    /**
+     * Get vault asset allocations across DeFi protocols, CeFi, and OTC positions.
+     * @param props - Vault address and chain ID
+     * @returns Detailed breakdown of vault allocations by category
+     */
+    getVaultAllocations(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+    }): Promise<import("./types").IVaultAllocations | {
+        status: number;
+        message: string;
+    }>;
+    /**
+     * Get current or historical APY for a vault.
+     *
+     * @deprecated use getVaultHistoricalTimeseries instead
+     *
+     * @param props - Vault address and optional historical lookback period
+     * @returns APY data including rewards breakdown
+     */
+    getVaultApy(props: {
+        vault: IAddress;
+        historical?: {
+            daysAgo?: number;
+        };
+    }): Promise<{
+        value: number;
+        timestamp: string;
+    }[]>;
+    /**
+     * Get current or historical TVL for a vault.
+     * @param props - Vault address and optional historical parameters
+     * @returns TVL in vault's base asset units
+     */
+    getVaultTvl(props: {
+        vault: IAddress;
+        historical?: IVaultHistoricalParams;
+        chainId?: IChainId;
+    }): Promise<{
+        value: import("./types").INormalizedNumber;
+        timestamp: string;
+    }[]>;
+    /**
+     * Get historical timeseries data for a vault.
+     * @param props - Vault address and optional number of days
+     * @returns Historical timeseries data with TVL, APY, PnL, share price, and other metrics
+     */
+    getVaultHistoricalTimeseries(props: {
+        vault: IAddress;
+        nDays?: number;
+    }): Promise<import("./types").IHistoricalTimeseriesResponse>;
+    /**
+     * Get the timestamp when yield was last realized for a vault.
+     * @param props - Vault address and optional chain ID
+     * @returns Timestamp (Unix timestamp in seconds) when yield was last realized
+     */
+    getYieldLastRealizedOn(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+    }): Promise<number>;
+    /**
+     * Get redemption requests that are ready to be claimed.
+     * @param props - Vault address, chain ID, and optional wallet filter
+     * @returns Array of available redemption requests with amounts and timestamps
+     */
+    getVaultAvailableRedemptions(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+        wallet?: IAddress;
+        verbose?: boolean;
+    }): Promise<{
+        processedWithdrawals: import("./types").ISubgraphWithdrawProccessed[];
+        requestedWithdrawals: import("./types").ISubgraphWithdrawRequest[];
+        availableRedemptions: import("./types").IVaultAvailableRedemption[];
+        pendingRedemptions: import("./types").IVaultAvailableRedemption[];
+    }>;
+    /**
+     * Get historical redemption requests for a vault (settled, cancelled,
+     * pending-but-out-of-window), optionally filtered to one wallet.
+     *
+     * @param props - Vault address, chain ID, optional wallet, and an
+     *   optional `lookbackBlocks` for how far back to scan.
+     * @returns Historical redemption records, newest first.
+     */
+    getVaultRedemptionHistory(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+        wallet?: IAddress;
+        lookbackBlocks?: number;
+    }): Promise<import("./types").IVaultRedemptionHistoryItem[]>;
+    /**
+     * Get user positions across vaults including shares and claimable redemptions.
+     * Supports both EVM and Solana vaults.
+     * @param props - Wallet address, chain ID, and optional vault filter
+     * @returns Array of positions with balances and pending redemptions
+     */
+    getVaultPositions(props: {
+        vault?: IAddress;
+        wallet?: IAddress;
+        chainId?: IChainId;
+        showAllVaults?: boolean;
+        solanaWallet?: string;
+        stellarWallet?: string;
+        options?: IVaultBaseOptions;
+    }): Promise<import("./types").IVaultPosition[]>;
+    /**
+     * Get user's historical vault interactions including deposits and withdrawals.
+     * @param props - Wallet address and optional vault/chain filters
+     * @returns Array of historical transactions with amounts and timestamps
+     */
+    getVaultUserHistory(props: {
+        wallet: IAddress;
+        chainId?: IChainId;
+        vault?: IAddress;
+        options?: IVaultBaseOptions;
+    }): Promise<import("./types").IVaultUserHistoryItem[]>;
+    /**
+     * Get user's vault share transfer history from subgraph.
+     * @param props - Wallet address and optional vault/chain filters
+     * @returns Array of transfer events
+     */
+    getVaultUserTransfers(props: {
+        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;
+    }[]>;
+    /**
+     * Get a vault's deposit/withdrawal activity across every participant.
+     *
+     * The vault-wide counterpart to {@link AugustSDK.getVaultUserHistory} — use
+     * it to answer flow questions ("how many deposits in the last 7 days", "net
+     * flow this week") that point-in-time TVL cannot. Reads from the Goldsky
+     * subgraph, paginated so busy vaults are not truncated; a `sinceTs` window
+     * keeps short lookbacks cheap.
+     * @param props - Vault address, optional chain id, optional `sinceTs`/`untilTs`
+     * Unix-second bounds, and an optional `types` filter.
+     * @returns Array of activity items (oldest-first) with normalized amounts,
+     * actor addresses, event type, and transaction hashes.
+     * @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 items = await sdk.getVaultActivity({ vault, chainId: 143, sinceTs: weekAgo });
+     * ```
+     */
+    getVaultActivity(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+        sinceTs?: number;
+        untilTs?: number;
+        types?: ('withdraw-request' | 'deposit' | 'withdraw-processed' | 'redeem')[];
+    }): Promise<import("./types").IVaultUserHistoryItem[]>;
+    /**
+     * 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.
+     *
+     * Delegates to {@link AugustVaults.getSwapRouterWhitelistedTokens}, which
+     * reconstructs the set from the router's `TokenEnabled` events and verifies
+     * each against the on-chain `whitelistedTokens` mapping (not enumerable).
+     * Returns `[]` when no router is deployed on `chainId` or no provider is
+     * configured for it.
+     *
+     * @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.
+     * @throws AugustSDKError when an `eth_getLogs` scan chunk fails.
+     * @example
+     * ```ts
+     * const tokens = await augustSdk.getSwapRouterWhitelistedTokens(1);
+     * ```
+     */
+    getSwapRouterWhitelistedTokens(chainId: number, options?: {
+        fromBlock?: number;
+    }): Promise<IAddress[]>;
+    /**
+     * 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.
+     *
+     * Delegates to {@link AugustVaults.getSwapRouterEligibleVaults}, which
+     * reconstructs the set from the router's `VaultEnabled` events and verifies
+     * each vault's current `vaultInfo` registration (not enumerable). Returns
+     * `[]` when no router is deployed on `chainId` or no provider is configured
+     * for it. On-chain eligibility only — app-level policy (e.g. OVault
+     * exclusions) 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<IAddress[]>;
+    /**
+     * Get lifetime PnL for a user in a specific vault.
+     * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.
+     * @param props - Vault address, wallet address, and optional chain ID
+     * @returns Lifetime PnL data including realized and unrealized PnL in both native token and USD
+     */
+    getVaultUserLifetimePnl(props: {
+        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(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+    }): Promise<import("./types").IVaultPnl>;
+    /**
+     * Get user's staking positions for vault receipt tokens.
+     * @param props - Wallet address and optional chain ID
+     * @returns Array of staking positions with rewards
+     */
+    getVaultStakingPositions(props: {
+        wallet?: IAddress;
+        chainId?: IChainId;
+    }): Promise<import("./types").IActiveStakingPosition[]>;
+    /**
+     * Get the borrower's health factor by vault.
+     *
+     * Pass `vault` whenever the caller knows which pool it cares about — it
+     * 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()`.
+     *
+     * @param props.chainId Optional chain to scope the read to.
+     * @param props.vault Optional vault address. When provided alongside
+     *   `chainId`, only that vault's borrower-health-factor data is fetched.
+     * @returns Object containing the borrower's health factor by vault.
+     */
+    getVaultBorrowerHealthFactor(props?: {
+        chainId?: IChainId;
+        vault?: IAddress;
+    }): Promise<Record<string, import("./types").IVaultBorrowerHealthFactor[]> | Record<string, import("./types").IVaultBorrowerHealthFactor[]>[]>;
+    /**
+     * Get user points from the backend API.
+     * This fetches processed points data directly from the backend,
+     * removing the need for client-side points calculation.
+     * @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
+     * containing the user address, referrer (or `"none"`), chain, nonce, and
+     * expiry — see `AugustVaults.registerUserForPoints` for the exact template.
+     *
+     * @param userAddress - EVM wallet address being registered.
+     * @param referrerAddress - Optional EVM referrer 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 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>;
+    /**
+     * Fetch 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>;
+    /**
+     * Fetch the historical unrealized-PnL series for a vault, newest first.
+     * Delegates to {@link AugustApi.getVaultUnrealizedPnlHistory} — see it for
+     * parameter semantics and thrown errors.
+     */
+    getVaultUnrealizedPnlHistory(params: {
+        vault: string;
+        limit?: number;
+    }): Promise<import("./types").IUnrealizedPnlSnapshot[]>;
+    /**
+     * Fetch the latest unrealized-PnL snapshot for every tracked vault.
+     * Delegates to {@link AugustApi.getLatestUnrealizedPnl} — see it for
+     * return shape and thrown errors.
+     */
+    getLatestUnrealizedPnl(): Promise<import("./types").IUnrealizedPnlSnapshot[]>;
+    /**
+     * 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 props - Vault address
+     * @returns Annualized APY data including liquidity APY
+     */
+    getVaultAnnualizedApy(props: {
+        vault: IAddress;
+    }): Promise<import("./types").IVaultAnnualizedApy>;
+    /**
+     * Get summary data for a vault (name, type, chain, recent returns).
+     * @param props - Vault address
+     * @returns Vault summary data
+     */
+    getVaultSummary(props: {
+        vault: IAddress;
+    }): Promise<import("./types").IVaultSummary>;
+    /**
+     * Get withdrawal summary and pending queue for a vault.
+     * @param props - Vault address and optional chain ID
+     * @returns Withdrawal summary and pending queue
+     */
+    getVaultWithdrawals(props: {
+        vault: IAddress;
+        chainId?: IChainId;
+    }): Promise<import("./types").IVaultWithdrawals>;
+    /**
+     * Preview the amount of assets that would be received for redeeming shares (queued redemption).
+     * @param props - Vault contract address, shares amount, and optional chain ID
+     * @returns The amount of assets as {@link INormalizedNumber}
+     */
+    previewRedemption(props: {
+        vault: IAddress;
+        sharesAmount: string | bigint | number;
+        chainId?: IChainId;
+    }): Promise<import("./types").INormalizedNumber>;
+    /**
+     * Query LayerZero USDC deposits from the august-layerzero subgraphs.
+     * Returns all deposits or filters by sender wallet address if provided.
+     *
+     * **Important Notes:**
+     * - Only deposit transactions are tracked (not withdrawals or other operations)
+     * - Sender and recipient addresses are stored in bytes32 format in the subgraph
+     * - Timestamps are available from the subgraph
+     *
+     * **Supported Vaults:**
+     * - `upusdc`: 0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42
+     * - `coreusdc`: 0xE9B725010A9E419412ed67d0fA5f3A5f40159D32
+     * - `earnausd`: 0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA
+     *
+     * @param props - Receipt token type ('upusdc', 'coreusdc', or 'earnausd') and optional wallet address to filter by sender
+     * @returns Array of deposit events with the following structure:
+     * - `assetAmt`: Amount of assets deposited (as string)
+     * - `shareAmt`: Amount of shares received (as string)
+     * - `sender`: Sender address in bytes32 format
+     * - `recipient`: Recipient address in bytes32 format
+     * - `dstEid`: Destination endpoint ID (LayerZero chain identifier)
+     * - `transactionHash_`: Transaction hash
+     *
+     * @throws Error if receipt token is invalid or GraphQL request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all coreUSDC deposits
+     * const allDeposits = await sdk.getLayerZeroDeposits({
+     *   receiptToken: 'coreusdc'
+     * });
+     *
+     * // Get deposits for a specific wallet
+     * const userDeposits = await sdk.getLayerZeroDeposits({
+     *   receiptToken: 'upusdc',
+     *   wallet: '0xb0280B58F541131b29D1B33319CD440a99eA0305'
+     * });
+     * ```
+     */
+    getLayerZeroDeposits(props: {
+        receiptToken: 'upusdc' | 'coreusdc' | 'earnausd';
+        wallet?: IAddress;
+    }): Promise<import("./services/layerzero/deposits").ILayerZeroDeposit[]>;
+    /**
+     * Get LayerZero redeems for earnAUSD vault
+     *
+     * @example
+     * ```typescript
+     * // Get all earnAUSD redeems
+     * const allRedeems = await sdk.getLayerZeroRedeems();
+     *
+     * // Get redeems for a specific wallet
+     * const userRedeems = await sdk.getLayerZeroRedeems({
+     *   wallet: '0x2de1DCB8EaAd40fAd327fa3eE3F48774b8e20649'
+     * });
+     * ```
+     */
+    getLayerZeroRedeems(props?: {
+        wallet?: IAddress;
+    }): Promise<import("./services/layerzero/redeems").ILayerZeroRedeem[]>;
+}