@augustdigital/sdk 8.3.2 → 8.6.0

package/lib/adapters/evm/index.js

@@ -18,60 +18,268 @@ const write_actions_1 = require("../../modules/vaults/write.actions");
 const read_actions_1 = require("../../modules/vaults/read.actions");
 const signer_1 = require("../../core/helpers/signer");
 __exportStar(require("./getters"), exports);
+/**
+ * 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()
+ * ```
+ */
 class EVMAdapter {
+    signer;
+    rawSigner;
     constructor(signer) {
         this.rawSigner = signer;
+        // Don't normalize in constructor - do it lazily when needed
     }
+    /**
+     * Set a new signer (supports both ethers and viem/wagmi)
+     * @param signer - Either an ethers Signer/Wallet or viem WalletClient
+     */
     setSigner(signer) {
         this.rawSigner = signer;
-        this.signer = undefined;
+        this.signer = undefined; // Reset normalized signer
     }
+    /**
+     * Get the normalized ethers-compatible signer
+     * Converts viem WalletClient to ethers Signer if needed
+     */
     async getSigner() {
         if (!this.rawSigner) {
             throw new Error('No signer provided');
         }
+        // If we already have a normalized signer, return it
         if (this.signer) {
             return this.signer;
         }
+        // Normalize and cache the signer
         this.signer = await (0, signer_1.normalizeSigner)(this.rawSigner);
         return this.signer;
     }
+    // Core EVM operations
     async vaultApprove(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.vaultApprove)(signer, options);
     }
+    /**
+     * 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);
+     * ```
+     */
     async approve(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.approve)(signer, options);
     }
+    /**
+     * 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);
+     * ```
+     */
     async vaultAllowance(options) {
         const signer = await this.getSigner();
         return (0, read_actions_1.vaultAllowance)(signer, options);
     }
+    // Vault operations (delegate to modules)
+    /**
+     * 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,
+     * });
+     * ```
+     */
     async vaultDeposit(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.vaultDeposit)(signer, options);
     }
+    /**
+     * 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,
+     * });
+     * ```
+     */
     async vaultRequestRedeem(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.vaultRequestRedeem)(signer, options);
     }
+    /**
+     * 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,
+     * });
+     * ```
+     */
     async depositNative(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.depositNative)(signer, options);
     }
+    /**
+     * 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 }],
+     * });
+     * ```
+     */
     async swapAndDeposit(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.swapAndDeposit)(signer, options);
     }
+    /**
+     * 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.
+     */
     async depositViaSwapRouter(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.depositViaSwapRouter)(signer, options);
     }
+    /**
+     * 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.
+     */
     async depositNativeViaSwapRouter(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.depositNativeViaSwapRouter)(signer, options);
     }
+    /**
+     * 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,
+     * });
+     * ```
+     */
     async vaultRedeem(options) {
         const signer = await this.getSigner();
         return (0, write_actions_1.vaultRedeem)(signer, options);
@@ -92,22 +300,83 @@ class EVMAdapter {
         const signer = await this.getSigner();
         return (0, read_actions_1.getRemainingAllocations)(signer, options);
     }
+    /**
+     * 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,
+     * });
+     * ```
+     */
     async previewDeposit(options) {
         const signer = await this.getSigner();
         return (0, read_actions_1.previewDeposit)(signer, options);
     }
+    /**
+     * 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,
+     * });
+     * ```
+     */
     async previewRedeem(options) {
         const signer = await this.getSigner();
         return (0, read_actions_1.previewRedeem)(signer, options);
     }
+    /**
+     * 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 });
+     * ```
+     */
     async allowance(options) {
         const signer = await this.getSigner();
         return (0, read_actions_1.allowance)(signer, options);
     }
+    /**
+     * Read an ERC-20 token balance.
+     *
+     * @returns Balance as a raw `bigint`.
+     *
+     * @example
+     * ```ts
+     * const raw = await augustSdk.evm.balanceOf({ asset: usdcAddress, owner });
+     * ```
+     */
     async balanceOf(options) {
         const signer = await this.getSigner();
         return (0, read_actions_1.balanceOf)(signer, options);
     }
+    /**
+     * 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 });
+     * ```
+     */
     async maxDeposit(options) {
         const signer = await this.getSigner();
         return (0, read_actions_1.maxDeposit)(signer, options);

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

@@ -1,2 +1,8 @@
+/**
+ * @todo
+ */
 export declare const functionsToCallMapping: (provider: any, contract: any, functionCalls: any[]) => any[];
+/**
+ * @todo
+ */
 export declare const functionsToCallReduction: (acc: any, curr: any, i: number, functionCalls: any[], contractCalls: any[]) => any;

package/lib/adapters/evm/utils.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.functionsToCallReduction = exports.functionsToCallMapping = void 0;
 const core_1 = require("../../core");
+/**
+ * @todo
+ */
 const functionsToCallMapping = (provider, contract, functionCalls) => {
     return functionCalls.map((f) => {
         if (f === 'symbol') {
@@ -14,6 +17,9 @@ const functionsToCallMapping = (provider, contract, functionCalls) => {
     });
 };
 exports.functionsToCallMapping = functionsToCallMapping;
+/**
+ * @todo
+ */
 const functionsToCallReduction = (acc, curr, i, functionCalls, contractCalls) => {
     let val;
     if (functionCalls[i] === 'totalSupply' ||
@@ -33,6 +39,7 @@ const functionsToCallReduction = (acc, curr, i, functionCalls, contractCalls) =>
         val = Number(curr.toString());
     }
     else if (functionCalls[i] === 'loansOperator') {
+        // TODO: hardcoded as we cannot pull the real strategist
         val = '0x4DCb388488622e47683EAd1a147947140a31e485';
     }
     else {

package/lib/adapters/solana/constants.d.ts

@@ -1,4 +1,4 @@
-import { ISolanaNetwork } from '../../types';
+import type { ISolanaNetwork } from '../../types';
 import { vaultIdl } from './idl/vault-idl';
 declare const fallbackDecimals = 8;
 declare const fallbackNetwork: ISolanaNetwork;

package/lib/adapters/solana/constants.js

@@ -7,6 +7,9 @@ const fallbackDecimals = 8;
 exports.fallbackDecimals = fallbackDecimals;
 const fallbackNetwork = 'mainnet-beta';
 exports.fallbackNetwork = fallbackNetwork;
+// ============================================================================
+// SOLANA CONFIGURATION
+// ============================================================================
 const fallbackRpcEndpoints = {
     devnet: 'https://api.devnet.solana.com',
     mainnet: 'https://api.mainnet-beta.solana.com',
@@ -19,7 +22,7 @@ const programIds = {
         vault: '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq',
     },
     ['mainnet-beta']: {
-        vault: '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq',
+        vault: '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq', // BTCsyrup vault
     },
     testnet: {
         vault: '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq',

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

@@ -1,3 +1,11 @@
-import { ITokenizedVault } from '../../types';
+import type { ITokenizedVault } from '../../types';
 import type { IVaultBaseOptions } from '../../modules/vaults/types';
+/**
+ * Fetch Solana vault data from on-chain program state.
+ * Falls back to backend-only data when Solana RPC is unavailable,
+ * ensuring vaults always appear in the list even without on-chain access.
+ * @param tokenizedVault Vault metadata from backend
+ * @param options RPC configuration with Solana service
+ * @returns Formatted vault object with Solana-specific fields
+ */
 export declare const getSolanaVault: (tokenizedVault: ITokenizedVault, options: IVaultBaseOptions) => Promise<import("../../types").IVault>;

package/lib/adapters/solana/getters.js

@@ -39,14 +39,24 @@ const utils_1 = require("./utils");
 const SolanaConstants = __importStar(require("./constants"));
 const core_1 = require("../../core");
 const utils_2 = require("../../modules/vaults/utils");
+/**
+ * Fetch Solana vault data from on-chain program state.
+ * Falls back to backend-only data when Solana RPC is unavailable,
+ * ensuring vaults always appear in the list even without on-chain access.
+ * @param tokenizedVault Vault metadata from backend
+ * @param options RPC configuration with Solana service
+ * @returns Formatted vault object with Solana-specific fields
+ */
 const getSolanaVault = async (tokenizedVault, options) => {
     const solanaRpcUrl = options.rpcUrl;
     const solanaMetadata = tokenizedVault.solana_vault_metadata;
     const programId = utils_1.SolanaUtils.resolveProgramId(tokenizedVault.address, solanaMetadata);
+    // Fallback decimals: prefer backend metadata, then the application default
     const fallbackDecimals = solanaMetadata?.deposit_token_decimals ?? SolanaConstants.fallbackDecimals;
     let vaultState = null;
     let depositMint = null;
     let onChainAvailable = false;
+    // Attempt to fetch on-chain data; gracefully degrade if RPC is unavailable
     try {
         vaultState = await utils_1.SolanaUtils.getVaultStateReadOnly({
             idl: SolanaConstants.vaultIdl,
@@ -70,6 +80,7 @@ const getSolanaVault = async (tokenizedVault, options) => {
         }
     }
     catch (error) {
+        // Only degrade gracefully for network/RPC issues; re-throw everything else
         const isNetworkError = error instanceof Error &&
             (/fetch failed|ETIMEDOUT|timeout|ECONNREFUSED|403|503|network/i.test(error.message) ||
                 error.name === 'AbortError');
@@ -79,6 +90,9 @@ const getSolanaVault = async (tokenizedVault, options) => {
         core_1.Logger.log.warn('getSolanaVault', 'RPC unavailable, using backend-only data', { vault: tokenizedVault.address, error });
     }
     const decimals = vaultState?.depositMintDecimals ?? fallbackDecimals;
+    // Fetch share mint supply to get totalSupply.
+    // Prefer vaultState.shareMint (correct for multi-vault programs like jitoSOL);
+    // fall back to deriveShareMintPda(programId) for legacy single-vault programs.
     let totalSupply = (0, core_1.toNormalizedBn)(0, decimals);
     if (onChainAvailable) {
         try {
@@ -100,6 +114,11 @@ const getSolanaVault = async (tokenizedVault, options) => {
             });
         }
     }
+    // Total assets must mirror the on-chain `VaultState::total_assets()` which
+    // is `local_aum + deployed_aum` (see solana-vaults/programs/august-vault/
+    // src/state/vault.rs). Reading deployed_aum alone makes the displayed share
+    // price drop below 1.0 the instant the operator deploys part of the vault,
+    // even though the vault has had no PnL.
     let totalAssets;
     if (onChainAvailable) {
         const localAumRaw = vaultState?.vaultState?.localAum;
@@ -115,6 +134,7 @@ const getSolanaVault = async (tokenizedVault, options) => {
     else {
         totalAssets = (0, utils_2.backendTvlToNormalizedBn)(tokenizedVault.latest_reported_tvl, decimals);
     }
+    // Deposit asset: use on-chain data if available, otherwise backend metadata
     const depositAsset = {
         address: depositMint?.address ?? solanaMetadata?.deposit_mint,
         symbol: depositMint?.symbol ?? solanaMetadata?.deposit_token_symbol,
@@ -125,6 +145,7 @@ const getSolanaVault = async (tokenizedVault, options) => {
             vault: tokenizedVault.address,
         });
     }
+    // Build unified vault object combining on-chain and backend data
     return (0, utils_2.buildBackendVault)(tokenizedVault, {
         chainId: core_1.SPECIAL_CHAINS.solana.chainId,
         version: 'sol-0',

package/lib/adapters/solana/idl/vault-idl.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.vaultIdl = void 0;
+// /**
+//  * Program IDL in camelCase format in order to be used in JS/TS.
+//  *
+//  * Note that this is only a type helper and is not the actual IDL. The original
+//  * IDL can be found at `target/idl/august_vault.json`.
+//  */
 exports.vaultIdl = {
     address: '7B8n9vL51b6ibqRAd1adZsi3x3kxtq5NZaondh22Vkyq',
     metadata: {
@@ -990,6 +996,9 @@ exports.vaultIdl = {
             name: 'VaultState',
             type: {
                 kind: 'struct',
+                // Field order MUST match programs/august-vault/src/state/vault.rs:36
+                // exactly. Borsh deserialization is positional; any reorder, addition,
+                // or omission silently corrupts every field after the drift point.
                 fields: [
                     {
                         name: 'operator',

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

@@ -1,10 +1,15 @@
+/**
+ * Solana Adapter for August SDK
+ *
+ * @module SolanaAdapter
+ */
 import * as SolanaConstants from './constants';
 import * as SolanaGetters from './getters';
 import * as SolanaActions from './vault.actions';
-import { AnchorProvider, web3 } from '@coral-xyz/anchor';
-import { Connection, PublicKey, Transaction } from '@solana/web3.js';
-import { ISolanaNetwork, ISolanaRpcEndpoint } from './types';
-import { SendTransactionOptions } from '@solana/wallet-adapter-base';
+import type { AnchorProvider, web3 } from '@coral-xyz/anchor';
+import { Connection, PublicKey, type Transaction } from '@solana/web3.js';
+import type { ISolanaNetwork, ISolanaRpcEndpoint } from './types';
+import type { SendTransactionOptions } from '@solana/wallet-adapter-base';
 export declare const Solana: {
     utils: {
         getExplorerLink: ({ signature, type, network, }: {
@@ -102,6 +107,16 @@ export declare const Solana: {
     actions: typeof SolanaActions;
     getters: typeof SolanaGetters;
 };
+/**
+ * Solana Adapter for August SDK
+ *
+ * @example
+ * To access the Solana adapter instance
+ * ```
+ * const sdk = new AugustSDK()
+ * sdk.solana.getVaultState()
+ * ```
+ */
 declare class SolanaAdapter {
     private _endpoint;
     private _network;
@@ -132,11 +147,51 @@ declare class SolanaAdapter {
     getTokenSymbol(mintAddress: string | PublicKey): Promise<string>;
     fetchUserTokenBalance(publicKey: PublicKey | string, depositMint: PublicKey | string): Promise<any>;
     fetchUserShareBalance(publicKey: PublicKey | string, shareMint: PublicKey | string): Promise<any>;
+    /**
+     * BigInt-safe variant of {@link fetchUserShareBalance}. Returns the raw u64
+     * `amount` (as a base-units string) plus the mint's `decimals` (or `null`
+     * when the scale can't be determined — see Returns), so the caller can
+     * produce a correct `INormalizedNumber` without losing precision.
+     *
+     * Prefer this anywhere the result feeds BigInt math — positions, max-
+     * actions, redemption sizing, allowance checks. `fetchUserShareBalance`
+     * returns a JS-number `uiAmount` which silently encodes against 18 decimals
+     * when passed through `toNormalizedBn(value)` without an explicit decimals
+     * argument; that's exactly how the jitoSOL "missing position" regression
+     * manifested.
+     *
+     * RPC cost: 1 `getParsedTokenAccountsByOwner` call. Worst case ~150ms on a
+     * healthy mainnet endpoint.
+     *
+     * @param publicKey   Wallet owner (PublicKey or base58 string).
+     * @param shareMint   The vault's share-token mint (PublicKey or base58).
+     * @returns
+     *   `{ amount, decimals }`. Three observable shapes:
+     *   - `{ amount: '<u64>', decimals: <number> }` — token account exists.
+     *   - `{ amount: '0', decimals: null }` — no token account for this mint
+     *     under this wallet, OR `tokenAmount` was missing from the response,
+     *     OR `publicKey`/`shareMint` was not supplied. Distinguishable from a
+     *     genuine zero-balance account (`decimals` would be set there).
+     *   - `{ amount: '0', decimals: null }` — RPC threw (error is logged).
+     *
+     *   `decimals === null` means "we could not determine the scale" — callers
+     *   that need an `INormalizedNumber` must fall back to a known decimals
+     *   value (typically the deposit mint's decimals from backend metadata)
+     *   before normalizing. Never throws.
+     */
     fetchUserShareBalanceRaw(publicKey: PublicKey | string, shareMint: PublicKey | string): Promise<{
         amount: string;
         decimals: number | null;
     }>;
+    /**
+     * Deposit funds into a Solana August vault.
+     * @param depositAmount  `bigint` (raw on-chain units) or `number` (UI amount).
+     */
     vaultDeposit(vaultProgramId: PublicKey | string, idl: any, publicKey: PublicKey | string, depositAmount: number | bigint, sendTransaction: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>, vaultAddress?: PublicKey | string): Promise<any>;
+    /**
+     * Redeem vault shares from a Solana August vault.
+     * @param redeemShares  `bigint` (raw share units) or `number` (UI amount).
+     */
     vaultRedeem(vaultProgramId: PublicKey | string, idl: any, publicKey: PublicKey | string, redeemShares: number | bigint, sendTransaction: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>, vaultAddress?: PublicKey | string): Promise<any>;
     getProgramId(type: 'vault'): string;
 }