@augustdigital/sdk 8.3.2 → 8.6.0

package/lib/abis/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Contract ABI definitions for interacting with August/Upshift smart contracts.
+ *
+ * @module ABIs
+ */
 export * from './LendingPool';
 export * from './ERC20';
 export * from './Loan';

package/lib/abis/index.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Contract ABI definitions for interacting with August/Upshift smart contracts.
+ *
+ * @module ABIs
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);

package/lib/adapters/evm/getters.d.ts

@@ -1,4 +1,19 @@
-import { ITokenizedVault } from '../../types';
-import { IVaultBaseOptions } from '../../modules/vaults/types';
+import type { ITokenizedVault } from '../../types';
+import type { IVaultBaseOptions } from '../../modules/vaults/types';
+/**
+ * Fetch EVM vault data for v1 vault contracts (legacy format).
+ * Queries on-chain state and combines with backend metadata.
+ * @param tokenizedVault Vault metadata from backend
+ * @param options RPC configuration and chain details
+ * @returns Formatted vault object or null if closed/invisible
+ */
 export declare const getEvmVaultV1: (tokenizedVault: ITokenizedVault, options: IVaultBaseOptions) => Promise<import("../../types").IVault>;
+/**
+ * Fetch EVM vault data for v2 vault contracts (current format).
+ * V2 vaults use separate contracts for vault, receipt token, and whitelist.
+ * Queries all three contracts and combines results.
+ * @param tokenizedVault Vault metadata from backend
+ * @param options RPC configuration and chain details
+ * @returns Formatted vault object or null if closed/invisible
+ */
 export declare const getEvmVaultV2: (tokenizedVault: ITokenizedVault, options: IVaultBaseOptions) => Promise<import("../../types").IVault>;

package/lib/adapters/evm/getters.js

@@ -6,17 +6,29 @@ const core_1 = require("../../core");
 const utils_1 = require("../../modules/vaults/utils");
 const TokenizedVaultV2_1 = require("../../abis/TokenizedVaultV2");
 const TokenizedVaultV2Receipt_1 = require("../../abis/TokenizedVaultV2Receipt");
+/**
+ * Fetch EVM vault data for v1 vault contracts (legacy format).
+ * Queries on-chain state and combines with backend metadata.
+ * @param tokenizedVault Vault metadata from backend
+ * @param options RPC configuration and chain details
+ * @returns Formatted vault object or null if closed/invisible
+ */
 const getEvmVaultV1 = async (tokenizedVault, options) => {
     const vault = tokenizedVault.address;
     if (!vault) {
         throw new Error('Vault address is undefined');
     }
+    // Skip closed staging vaults that shouldn't be displayed — unless the caller
+    // explicitly opts in (portfolio mode), where a user's position in a closed,
+    // invisible vault must still resolve its metadata.
     if (tokenizedVault.status === 'closed' &&
-        tokenizedVault.is_visible === false) {
+        tokenizedVault.is_visible === false &&
+        !options?.includeClosed) {
         core_1.Logger.log.warn('getEvmVaultV1', `closed: ${tokenizedVault.vault_name}`);
         return null;
     }
     const provider = (0, core_1.createProvider)(options.rpcUrl);
+    // Batch fetch all vault contract data
     const vaultContract = (0, core_1.createContract)({
         address: vault,
         abi: abis_1.ABI_LENDING_POOL_V2,
@@ -45,6 +57,7 @@ const getEvmVaultV1 = async (tokenizedVault, options) => {
         }
         return vaultContract[f]();
     }));
+    // Normalize contract call results into typed object
     const formattedContractCalls = vaultContractCalls.reduce((acc, curr, i) => {
         let val;
         if (core_1.VAULT_FUNCTIONS_V1[i] === 'maxDepositAmount') {
@@ -69,6 +82,7 @@ const getEvmVaultV1 = async (tokenizedVault, options) => {
             val = Number(curr.toString());
         }
         else if (core_1.VAULT_FUNCTIONS_V1[i] === 'loansOperator') {
+            // TODO: hardcoded as we cannot pull the real strategist
             val = '0x4DCb388488622e47683EAd1a147947140a31e485';
         }
         else {
@@ -76,21 +90,35 @@ const getEvmVaultV1 = async (tokenizedVault, options) => {
         }
         return { ...acc, [core_1.VAULT_FUNCTIONS_V1[i]]: val };
     }, {});
+    // Combine on-chain and backend data into unified vault object
     const returnObj = await (0, utils_1.buildFormattedVault)(provider, tokenizedVault, formattedContractCalls);
     return returnObj;
 };
 exports.getEvmVaultV1 = getEvmVaultV1;
+/**
+ * Fetch EVM vault data for v2 vault contracts (current format).
+ * V2 vaults use separate contracts for vault, receipt token, and whitelist.
+ * Queries all three contracts and combines results.
+ * @param tokenizedVault Vault metadata from backend
+ * @param options RPC configuration and chain details
+ * @returns Formatted vault object or null if closed/invisible
+ */
 const getEvmVaultV2 = async (tokenizedVault, options) => {
     const provider = (0, core_1.createProvider)(options.rpcUrl);
     const vault = tokenizedVault.address;
     if (!vault) {
         throw new Error('Vault address is undefined');
     }
+    // Skip closed staging vaults that shouldn't be displayed — unless the caller
+    // explicitly opts in (portfolio mode), where a user's position in a closed,
+    // invisible vault must still resolve its metadata.
     if (tokenizedVault.status === 'closed' &&
-        tokenizedVault.is_visible === false) {
+        tokenizedVault.is_visible === false &&
+        !options?.includeClosed) {
         core_1.Logger.log.warn('getEvmVaultV2', `closed: ${tokenizedVault.vault_name}`);
         return null;
     }
+    // Fetch vault contract state
     const vaultContract = (0, core_1.createContract)({
         address: vault,
         abi: TokenizedVaultV2_1.ABI_TOKENIZED_VAULT_V2,
@@ -110,7 +138,7 @@ const getEvmVaultV2 = async (tokenizedVault, options) => {
     const receiptAddress = vaultContractCalls[core_1.VAULT_FUNCTIONS_V2.length - 1];
     const whitelistedAssetsAddress = vaultContractCalls[0];
     const reciptContract = (0, core_1.createContract)({
-        address: receiptAddress,
+        address: receiptAddress, // lpTokenAddress
         abi: TokenizedVaultV2Receipt_1.ABI_TOKENIZED_VAULT_V2_RECEIPT,
         provider,
     });
@@ -127,6 +155,7 @@ const getEvmVaultV2 = async (tokenizedVault, options) => {
         (0, core_1.getWhitelistedAssets)(provider, whitelistedAssetsAddress),
     ]);
     const whitelistedAssetsContractCalls = [whitelistedList];
+    // Merge all contract call results
     const combinedCalls = [
         ...vaultContractCalls,
         ...receiptContractCalls,
@@ -137,6 +166,7 @@ const getEvmVaultV2 = async (tokenizedVault, options) => {
         ...core_1.VAULT_FUNCTIONS_V2_RECEIPT,
         ...core_1.VAULT_FUNCTIONS_V2_WHITELISTED_ASSETS,
     ];
+    // Normalize all contract results with proper decimal handling
     const formattedContractCalls = combinedCalls.reduce((acc, curr, i) => {
         let val;
         if (combinedFunctions[i] === 'depositCap') {
@@ -163,6 +193,7 @@ const getEvmVaultV2 = async (tokenizedVault, options) => {
             val = Number(curr.toString());
         }
         else if (combinedFunctions[i] === 'loansOperator') {
+            // @hardcoded: we cannot pull the real strategist
             val = '0x4DCb388488622e47683EAd1a147947140a31e485';
         }
         else {
@@ -170,6 +201,7 @@ const getEvmVaultV2 = async (tokenizedVault, options) => {
         }
         return { ...acc, [combinedFunctions[i]]: val };
     }, {});
+    // Combine on-chain and backend data into unified vault object
     const returnObj = await (0, utils_1.buildFormattedVault)(provider, tokenizedVault, formattedContractCalls);
     return returnObj;
 };

package/lib/adapters/evm/index.d.ts

@@ -1,24 +1,225 @@
-import { IContractWriteOptions, INativeDepositOptions, ApproveResult } from '../../modules/vaults/write.actions';
+import { type IContractWriteOptions, type INativeDepositOptions, type ApproveResult } from '../../modules/vaults/write.actions';
 import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions } from '../../types';
-import { IPreviewDepositOptions, IPreviewRedeemOptions, IAllowanceOptions, IBalanceOfOptions, IMaxDepositOptions } from '../../modules/vaults/read.actions';
-import { CompatibleSigner } from '../../core/helpers/signer';
-import { IAddress } from '../../types';
+import { type IPreviewDepositOptions, type IPreviewRedeemOptions, type IAllowanceOptions, type IBalanceOfOptions, type IMaxDepositOptions } from '../../modules/vaults/read.actions';
+import { type CompatibleSigner } from '../../core/helpers/signer';
+import type { IAddress } from '../../types';
 export * from './getters';
+/**
+ * EVM Adapter for August SDK
+ * Supports both ethers Signer/Wallet and wagmi/viem WalletClient
+ *
+ * @example
+ * To access the EVM adapter instance
+ * ```
+ * const sdk = new AugustSDK()
+ * sdk.evm.vaultRedeem()
+ * ```
+ */
 declare class EVMAdapter {
     private signer?;
     private rawSigner?;
     constructor(signer?: CompatibleSigner);
+    /**
+     * Set a new signer (supports both ethers and viem/wagmi)
+     * @param signer - Either an ethers Signer/Wallet or viem WalletClient
+     */
     setSigner(signer: CompatibleSigner): void;
+    /**
+     * Get the normalized ethers-compatible signer
+     * Converts viem WalletClient to ethers Signer if needed
+     */
     private getSigner;
     vaultApprove(options: IContractWriteOptions): Promise<string>;
+    /**
+     * Approve a vault to spend a deposit token, returning a discriminated
+     * {@link ApproveResult} so callers can tell `sent` from `sufficient`
+     * (existing allowance covers) and `native` (no allowance applies).
+     * Prefer this over {@link vaultApprove} for new integrations.
+     *
+     * @example
+     * ```ts
+     * const r = await augustSdk.evm.approve({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: '100',
+     *   wait: true,
+     * });
+     * if (r.kind === 'sent') console.log('approve tx', r.hash);
+     * ```
+     */
     approve(options: IContractWriteOptions): Promise<ApproveResult>;
+    /**
+     * Read the ERC-20 allowance the wallet has granted the vault to spend its
+     * underlying asset, returned as a normalized number. For the newer typed
+     * read that returns a raw `bigint` and accepts an explicit `asset` override,
+     * use {@link EVMAdapter.allowance}.
+     *
+     * Only `target` (vault address) and `wallet` are read from `options`; the
+     * remaining {@link IContractWriteOptions} fields are ignored.
+     *
+     * @param options - `{ target, wallet }` (other fields ignored).
+     * @returns Normalized allowance (`{ raw, normalized }`), or `undefined` when
+     *   `target` / `wallet` fail address validation.
+     *
+     * @example
+     * ```ts
+     * const a = await augustSdk.evm.vaultAllowance({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     * });
+     * console.log(a?.normalized);
+     * ```
+     */
     vaultAllowance(options: IContractWriteOptions): Promise<import("../../types").INormalizedNumber>;
+    /**
+     * Deposit into an August vault. Routes automatically: V1 single-asset vaults
+     * deposit the underlying directly; V2 multi-asset vaults route through the
+     * adapter for non-underlying `depositAsset`. If allowance is insufficient
+     * the method submits an approve transaction first (the approve step always
+     * waits for confirmation to close a race window, regardless of `wait`).
+     *
+     * @param options - {@link IContractWriteOptions}. `target` and `wallet` are
+     *   required; pass `amount`, `depositAsset` (defaults to the vault's
+     *   underlying), `chainId`, `poolName`, `wait`, and `isDepositWithPermit`
+     *   as needed.
+     * @returns The deposit `TransactionResponse`, or `undefined` if an
+     *   approval-only path was taken and no deposit transaction was sent.
+     * @throws AugustValidationError on invalid inputs (bad address, bad amount).
+     * @throws AugustSDKError on RPC / contract revert during the deposit.
+     *
+     * @example
+     * ```ts
+     * const tx = await augustSdk.evm.vaultDeposit({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: '100',
+     *   wait: true,
+     * });
+     * ```
+     */
     vaultDeposit(options: IContractWriteOptions): Promise<string>;
+    /**
+     * Submit a redemption request against a vault. Shares are escrowed and the
+     * underlying assets are released asynchronously by the protocol; callers
+     * collect the matured assets via {@link EVMAdapter.vaultRedeem}, or use the
+     * instant-redeem variant by setting `isInstantRedeem: true`.
+     *
+     * @param options - {@link IContractWriteOptions}. `target`, `wallet`, and
+     *   `amount` (in shares) are required. Set `isInstantRedeem: true` to take
+     *   the instant-redeem path when the vault supports it.
+     * @returns The request `TransactionResponse`, or `undefined` if the request
+     *   could not be built (validation failure).
+     * @throws AugustValidationError on invalid inputs.
+     * @throws AugustSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const tx = await augustSdk.evm.vaultRequestRedeem({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: shareAmount,
+     *   wait: true,
+     * });
+     * ```
+     */
     vaultRequestRedeem(options: IContractWriteOptions): Promise<string>;
+    /**
+     * Deposit the chain's native asset (ETH / AVAX / etc.) into a vault by
+     * routing through the `MultiAssetNativeDepositWrapper`. The wrapper handles
+     * native-to-wrapped conversion and the subsequent vault deposit in a single
+     * transaction.
+     *
+     * @param options - {@link INativeDepositOptions}: `wrapperAddress`, `amount`
+     *   (native, scaled by the chain's native decimals), optional `receiver`
+     *   (defaults to the signer), and optional `wait`.
+     * @returns The deposit `TransactionResponse`.
+     * @throws AugustValidationError on invalid inputs.
+     * @throws AugustSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const tx = await augustSdk.evm.depositNative({
+     *   wrapperAddress: nativeWrapperAddress,
+     *   amount: parseEther('1'),
+     *   wait: true,
+     * });
+     * ```
+     */
     depositNative(options: INativeDepositOptions): Promise<string>;
+    /**
+     * Swap one or more whitelisted ERC-20s into a vault's reference asset via
+     * the on-chain `SwapRouter` and deposit the proceeds. The router handles
+     * fee accrual, slippage protection, and the v1/v3 vs v2 deposit-interface
+     * branching. Approval is sent automatically for each `swaps[i].tokenIn`
+     * when the caller's allowance against the SwapRouter is below `amountIn`.
+     *
+     * @param options - {@link ISwapAndDepositOptions}.
+     * @returns The transaction hash of the `swapAndDeposit` call.
+     * @throws AugustValidationError on invalid inputs (bad chain, empty swaps).
+     * @throws AugustSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const quote = await fetchSwapQuote({
+     *   chainId: 1, srcToken: WBTC, srcDecimals: 8,
+     *   destToken: USDC, destDecimals: 6, amount: 100_000_000n,
+     *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+     * });
+     * const hash = await augustSdk.evm.swapAndDeposit({
+     *   chainId: 1, vault, receiver: wallet,
+     *   swaps: [{ tokenIn: WBTC, tokenOut: USDC, amountIn: 100_000_000n,
+     *     minAmountOut: quote.minAmountOut, router: quote.router, payload: quote.payload }],
+     * });
+     * ```
+     */
     swapAndDeposit(options: ISwapAndDepositOptions): Promise<string>;
+    /**
+     * Deposit a vault's reference asset through the SwapRouter — no swap.
+     * Use this when the caller already holds the reference asset but wants
+     * the origin/referral fee accounting that the SwapRouter path provides.
+     *
+     * @param options - {@link ISwapRouterDirectDepositOptions}.
+     * @returns The transaction hash of the `deposit` call.
+     */
     depositViaSwapRouter(options: ISwapRouterDirectDepositOptions): Promise<string>;
+    /**
+     * Deposit native ETH (or chain-native equivalent) into a vault via the
+     * SwapRouter. Only valid when the vault's reference asset is the chain's
+     * wrapped-native token — the SwapRouter wraps `amount` and deposits.
+     *
+     * @param options - {@link ISwapRouterNativeDepositOptions}.
+     * @returns The transaction hash of the `depositNativeToken` call.
+     */
     depositNativeViaSwapRouter(options: ISwapRouterNativeDepositOptions): Promise<string>;
+    /**
+     * Claim assets from a matured redemption request on a dated-redemption
+     * (RWA-style) vault. The `year`, `month`, `day`, and `receiverIndex` tuple
+     * identifies which batch of the user's matured requests to redeem from —
+     * these are emitted at request-time and indexed by the subgraph.
+     *
+     * For non-dated vaults that complete their redemption via `instantRedeem`,
+     * see {@link EVMAdapter.vaultRequestRedeem} with `isInstantRedeem: true`.
+     *
+     * @param options - {@link IContractWriteOptions} plus `year` / `month` /
+     *   `day` / `receiverIndex` identifying the matured batch to claim.
+     * @returns The redeem `TransactionResponse`.
+     * @throws AugustValidationError on invalid inputs.
+     * @throws AugustSDKError on RPC / contract revert.
+     *
+     * @example
+     * ```ts
+     * const tx = await augustSdk.evm.vaultRedeem({
+     *   target: vaultAddress,
+     *   wallet: walletAddress,
+     *   amount: shareAmount,
+     *   year: '2026',
+     *   month: '06',
+     *   day: '02',
+     *   receiverIndex: '0',
+     *   wait: true,
+     * });
+     * ```
+     */
     vaultRedeem(options: IContractWriteOptions & {
         year: string;
         month: string;
@@ -43,10 +244,71 @@ declare class EVMAdapter {
         vault: IAddress;
         depositCapAmount?: bigint;
     }): Promise<import("../../types").INormalizedNumber>;
+    /**
+     * Preview the share output of a deposit without broadcasting a transaction.
+     * See {@link readPreviewDeposit} for the routing details (EVM-1 vs EVM-2
+     * multi-asset vaults).
+     *
+     * @returns Shares minted in raw on-chain units (share-token decimals).
+     *
+     * @example
+     * ```ts
+     * const shares = await augustSdk.evm.previewDeposit({
+     *   vault: '0x...',
+     *   amount: 1_000_000n,
+     * });
+     * ```
+     */
     previewDeposit(options: IPreviewDepositOptions): Promise<bigint>;
+    /**
+     * Preview the assets returned by redeeming a number of shares, without
+     * broadcasting a transaction.
+     *
+     * @returns Assets returned in raw on-chain units (asset decimals).
+     *
+     * @example
+     * ```ts
+     * const assets = await augustSdk.evm.previewRedeem({
+     *   vault: '0x...',
+     *   shares: 1_000_000_000_000_000_000n,
+     * });
+     * ```
+     */
     previewRedeem(options: IPreviewRedeemOptions): Promise<bigint>;
+    /**
+     * Read the ERC-20 allowance an owner has granted the vault. Defaults to the
+     * vault's underlying asset; pass `asset` to override.
+     *
+     * @returns Allowance as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const raw = await augustSdk.evm.allowance({ vault, owner });
+     * ```
+     */
     allowance(options: IAllowanceOptions): Promise<bigint>;
+    /**
+     * Read an ERC-20 token balance.
+     *
+     * @returns Balance as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const raw = await augustSdk.evm.balanceOf({ asset: usdcAddress, owner });
+     * ```
+     */
     balanceOf(options: IBalanceOfOptions): Promise<bigint>;
+    /**
+     * Read the maximum deposit accepted by the vault for the supplied
+     * receiver. Useful for "vault is full" gates.
+     *
+     * @returns Max deposit as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const cap = await augustSdk.evm.maxDeposit({ vault });
+     * ```
+     */
     maxDeposit(options: IMaxDepositOptions): Promise<bigint>;
 }
 export default EVMAdapter;