@augustdigital/sdk 8.3.1 → 8.5.0

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 { 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,3 +1,8 @@
+/**
+ * Solana Adapter for August SDK
+ *
+ * @module SolanaAdapter
+ */
 import * as SolanaConstants from './constants';
 import * as SolanaGetters from './getters';
 import * as SolanaActions from './vault.actions';
@@ -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;
 }

package/lib/adapters/solana/index.js

@@ -34,6 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Solana = void 0;
+/**
+ * Solana Adapter for August SDK
+ *
+ * @module SolanaAdapter
+ */
 const SolanaConstants = __importStar(require("./constants"));
 const SolanaGetters = __importStar(require("./getters"));
 const SolanaActions = __importStar(require("./vault.actions"));
@@ -47,6 +52,16 @@ exports.Solana = {
     actions: SolanaActions,
     getters: SolanaGetters,
 };
+/**
+ * Solana Adapter for August SDK
+ *
+ * @example
+ * To access the Solana adapter instance
+ * ```
+ * const sdk = new AugustSDK()
+ * sdk.solana.getVaultState()
+ * ```
+ */
 class SolanaAdapter {
     constructor(endpoint, network = utils_1.SolanaUtils.fallbackNetwork) {
         this._endpoint = endpoint;
@@ -58,6 +73,7 @@ class SolanaAdapter {
             connection,
         });
     }
+    // Getters and setters for private properties
     get endpoint() {
         return this._endpoint;
     }
@@ -70,6 +86,7 @@ class SolanaAdapter {
     get provider() {
         return this._provider;
     }
+    // Method to set connection with wallet for authenticated operations
     setWalletProvider(_publicKey, signTransaction) {
         if (_publicKey && signTransaction) {
             const publicKey = typeof _publicKey === 'string' ? new web3_js_1.PublicKey(_publicKey) : _publicKey;
@@ -143,6 +160,38 @@ class SolanaAdapter {
             shareMint,
         });
     }
+    /**
+     * 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.
+     */
     async fetchUserShareBalanceRaw(publicKey, shareMint) {
         return await utils_1.SolanaUtils.fetchUserShareBalanceRaw({
             network: this._network,
@@ -151,6 +200,10 @@ class SolanaAdapter {
             shareMint,
         });
     }
+    /**
+     * Deposit funds into a Solana August vault.
+     * @param depositAmount  `bigint` (raw on-chain units) or `number` (UI amount).
+     */
     async vaultDeposit(vaultProgramId, idl, publicKey, depositAmount, sendTransaction, vaultAddress) {
         return await (0, vault_actions_1.handleSolanaDeposit)({
             network: this._network,
@@ -164,6 +217,10 @@ class SolanaAdapter {
             sendTransaction,
         });
     }
+    /**
+     * Redeem vault shares from a Solana August vault.
+     * @param redeemShares  `bigint` (raw share units) or `number` (UI amount).
+     */
     async vaultRedeem(vaultProgramId, idl, publicKey, redeemShares, sendTransaction, vaultAddress) {
         return await (0, vault_actions_1.handleSolanaRedeem)({
             network: this._network,

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

@@ -66,6 +66,28 @@ declare function fetchUserShareBalance({ connection, publicKey, shareMint, }: {
     publicKey: PublicKey | string;
     shareMint?: PublicKey | string;
 } & ISolanaConnectionOptions): Promise<any>;
+/**
+ * Same on-chain lookup as `fetchUserShareBalance`, but returns the raw u64
+ * `amount` string and the mint's `decimals` — or `null` when the scale can't
+ * be determined (see Return shape) — instead of the floating-point `uiAmount`.
+ * Callers that feed the result into BigInt math (positions, redemptions,
+ * allowances) must use this — `uiAmount` is lossy and silently encodes with
+ * the wrong scale when passed back through `toNormalizedBn` without an
+ * explicit decimals argument.
+ *
+ * Return shape:
+ *   `{ amount: '<u64>', decimals: number }` — token account exists.
+ *   `{ amount: '0',     decimals: null   }` — no token account, missing
+ *      tokenAmount in the parsed response, missing args, or the RPC threw.
+ *
+ * `decimals === null` is the "scale unknown" signal — callers that need a
+ * normalized `INormalizedNumber` must substitute a known decimals value
+ * (typically the deposit mint's decimals from backend metadata) before
+ * normalizing. Never throws.
+ *
+ * RPC cost: 1 × `getParsedTokenAccountsByOwner`. Independent of how many
+ * other accounts the wallet owns (filter is mint-scoped).
+ */
 declare function fetchUserShareBalanceRaw({ connection, publicKey, shareMint, }: {
     publicKey: PublicKey | string;
     shareMint?: PublicKey | string;
@@ -73,9 +95,15 @@ declare function fetchUserShareBalanceRaw({ connection, publicKey, shareMint, }:
     amount: string;
     decimals: number | null;
 }>;
+/**
+ * Resolve the on-chain program ID for a Solana vault.
+ * Prefers the explicit `program_id` from metadata; falls back to the vault address
+ * (for legacy vaults where address == program ID).
+ */
 declare function resolveProgramId(vaultAddress: string, solanaMetadata?: {
     program_id?: string;
 } | null): string;
+/** @internal */
 export declare function uiAmountToRawBn(uiAmount: number, decimals: number): BN;
 export declare const SolanaUtils: {
     getExplorerLink: typeof getExplorerLink;

package/lib/adapters/solana/utils.js

@@ -7,31 +7,42 @@ const web3_js_1 = require("@solana/web3.js");
 const ethers_1 = require("ethers");
 const constants_1 = require("./constants");
 const core_1 = require("../../core");
+// ============================================================================
+// SOLANA UTILITIES
+// ============================================================================
 function getExplorerLink({ signature, type = 'tx', network = constants_1.fallbackNetwork, }) {
     const baseUrl = 'https://solscan.io';
     return `${baseUrl}/${type}/${signature}?cluster=${network}`;
 }
+// Re-exported from the core leaf so consumers in the core layer can import it
+// without taking a dependency on the Solana adapter.
 const chain_address_1 = require("../../core/helpers/chain-address");
 Object.defineProperty(exports, "isSolanaAddress", { enumerable: true, get: function () { return chain_address_1.isSolanaAddress; } });
 function isSolana(signature) {
     if (!signature || typeof signature !== 'string')
         return false;
+    // Check if it's an Ethereum address first
     if ((0, ethers_1.isAddress)(signature))
         return false;
+    // Check if it's a valid Solana address (including PDAs) — addresses are not signatures
     if ((0, chain_address_1.isSolanaAddress)(signature))
         return false;
+    // Check if it's a valid base58 string with correct length for Solana signatures
+    // Solana signatures are base58 encoded and typically 88 characters long
     const base58Chars = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
     const isValidBase58 = signature
         .split('')
         .every((char) => base58Chars.includes(char));
     if (!isValidBase58)
         return false;
+    // Check length - Solana signatures are typically 88 characters
     return (signature.length >= 80 && signature.length <= 100);
 }
 function getProgram({ provider, idl, programId, network, }) {
     if (!idl) {
         return new anchor_1.Program(constants_1.vaultIdl, provider);
     }
+    // If programId is provided, create a modified IDL with the correct address
     if (programId) {
         const modifiedIdl = {
             ...idl,
@@ -41,6 +52,9 @@ function getProgram({ provider, idl, programId, network, }) {
     }
     return new anchor_1.Program(idl, provider);
 }
+// ============================================================================
+// SOLANA PROVIDERS
+// ============================================================================
 async function testRpcEndpoint({ connection }) {
     try {
         const blockHeight = await connection.getBlockHeight();
@@ -50,13 +64,16 @@ async function testRpcEndpoint({ connection }) {
         return { success: false, error };
     }
 }
+// Function to get the best available RPC endpoint
 async function getBestRpcEndpoint({ endpoint, network = constants_1.fallbackNetwork, connection, }) {
     const primaryEndpoint = endpoint;
     const fallbackEndpoint = constants_1.fallbackRpcEndpoints[network];
+    // Test primary endpoint first
     const primaryTest = await testRpcEndpoint({ connection });
     if (primaryTest.success) {
         return primaryEndpoint;
     }
+    // Fall back to public endpoint
     core_1.Logger.log.warn('getBestRpcEndpoint', '⚠️ Primary RPC endpoint failed, using fallback:', fallbackEndpoint);
     return fallbackEndpoint;
 }
@@ -68,14 +85,17 @@ function getProvider({ connection, publicKey, signTransaction, }) {
         publicKey,
         signTransaction,
         signAllTransactions: async (txs) => {
+            // Use Promise.all instead of await in loop
             const signedTransactions = await Promise.all(txs.map(async (tx) => signTransaction(tx)));
             return signedTransactions;
         },
     }, { commitment: 'confirmed' });
 }
+// Read-only provider for data fetching without wallet connection
 function getReadOnlyProvider({ connection }) {
+    // Create a dummy wallet object for read-only operations
     const dummyWallet = {
-        publicKey: web3_js_1.PublicKey.default,
+        publicKey: web3_js_1.PublicKey.default, // Use default public key
         signTransaction: async (_tx) => {
             throw new core_1.AugustValidationError('INVALID_INPUT', 'Cannot sign transactions with read-only provider');
         },
@@ -87,6 +107,9 @@ function getReadOnlyProvider({ connection }) {
         commitment: 'confirmed',
     });
 }
+// ============================================================================
+// SOLANA DERIVATIONS
+// ============================================================================
 function deriveVaultStatePda(vaultProgramId) {
     if (!vaultProgramId)
         throw new core_1.AugustValidationError('INVALID_INPUT', 'Vault program ID missing');
@@ -120,6 +143,9 @@ function deriveVaultTokenAtaPda(vaultProgramId, depositMint, vaultVersion) {
     const [pda] = web3_js_1.PublicKey.findProgramAddressSync(seeds, _vaultProgramId);
     return pda;
 }
+// ============================================================================
+// SOLANA VAULTS
+// ============================================================================
 async function getVaultState({ provider, connection, vaultProgramId, vaultAddress, idl, }) {
     const returnObj = {
         vaultState: null,
@@ -169,6 +195,7 @@ async function getVaultState({ provider, connection, vaultProgramId, vaultAddres
         return returnObj;
     }
 }
+// Read-only version of getVaultState that works without wallet connection
 async function getVaultStateReadOnly({ vaultProgramId, vaultAddress, connection, idl, }) {
     const returnObj = {
         vaultState: null,
@@ -186,11 +213,13 @@ async function getVaultStateReadOnly({ vaultProgramId, vaultAddress, connection,
         const vaultStatePda = vaultAddress
             ? new web3_js_1.PublicKey(vaultAddress)
             : deriveVaultStatePda(_vaultProgramId);
+        // Use connection directly to fetch account data
         const accountInfo = await connection.getAccountInfo(vaultStatePda);
         if (!accountInfo) {
             core_1.Logger.log.warn('getVaultStateReadOnly', 'Vault state account not found');
             return returnObj;
         }
+        // Try to create a program with read-only provider for parsing
         try {
             const readOnlyProvider = getReadOnlyProvider({ connection });
             const program = getProgram({
@@ -219,6 +248,7 @@ async function getVaultStateReadOnly({ vaultProgramId, vaultAddress, connection,
             core_1.Logger.log.error('getVaultStateReadOnly', programError, {
                 message: 'Error creating program with read-only provider',
             });
+            // Fallback: program parsing failed, vault state is unavailable
             returnObj.vaultState = null;
         }
         await (0, core_1.setSafeCache)(cacheKey, returnObj);
@@ -232,6 +262,7 @@ async function getVaultStateReadOnly({ vaultProgramId, vaultAddress, connection,
         return returnObj;
     }
 }
+// Fetch deposit and share mint addresses from on-chain vault state (read-only, no wallet required)
 async function getVaultMints({ vaultProgramId, vaultAddress, connection, idl, }) {
     try {
         const cacheKey = `vaultMints-${vaultAddress || vaultProgramId}`;
@@ -255,6 +286,7 @@ async function getVaultMints({ vaultProgramId, vaultAddress, connection, idl, })
         const returnObj = {
             depositMint: state.depositMint.toString(),
             shareMint: state.shareMint.toString(),
+            // Empty arrays yield undefined, falling back to legacy PDA seeds (no version byte)
             vaultVersion: Array.isArray(state.vaultVersion)
                 ? state.vaultVersion[0]
                 : undefined,
@@ -285,6 +317,7 @@ async function getToken({ mintAddress, endpoint, connection, }) {
         const cachedData = await (0, core_1.getSafeCache)(cacheKey);
         if (cachedData)
             return cachedData;
+        // First, try to get token metadata via Metaplex DAS API
         const response = await fetch(endpoint, {
             method: 'POST',
             headers: {
@@ -297,7 +330,8 @@ async function getToken({ mintAddress, endpoint, connection, }) {
                 params: { id: mintAddress.toString() },
             }),
         });
-        const data = (await response.json());
+        const data = (await response.json()); // @todo: add interface
+        // If we got valid token metadata, return it
         if (data.result?.token_info?.decimals !== undefined) {
             return {
                 address: data?.result?.id,
@@ -311,19 +345,25 @@ async function getToken({ mintAddress, endpoint, connection, }) {
                 supply: data.result?.token_info?.supply,
             };
         }
+        // If Metaplex metadata didn't work, check if this is a vault program address
+        // In that case, we should query the share mint PDA instead
         if (connection) {
             try {
                 const vaultProgramId = new web3_js_1.PublicKey(mintAddress);
+                // Try to get vault state to see if this is a vault
                 const vaultState = await getVaultStateReadOnly({
                     vaultProgramId,
                     connection,
                     idl: constants_1.vaultIdl,
                 });
+                // If we successfully got vault state, derive the share mint and query that
                 if (vaultState.vaultState) {
                     const shareMintPda = deriveShareMintPda(vaultProgramId);
+                    // Get share mint metadata from blockchain
                     const shareMintInfo = await connection.getParsedAccountInfo(shareMintPda);
                     if (shareMintInfo.value) {
                         const parsedData = shareMintInfo.value.data;
+                        // Try to get Metaplex metadata for the share mint
                         const shareMintMetadata = await fetch(endpoint, {
                             method: 'POST',
                             headers: {
@@ -338,7 +378,7 @@ async function getToken({ mintAddress, endpoint, connection, }) {
                         });
                         const shareMintData = (await shareMintMetadata.json());
                         const returnObj = {
-                            address: mintAddress.toString(),
+                            address: mintAddress.toString(), // Return original vault address
                             symbol: shareMintData.result?.content?.metadata?.symbol || 'N/A',
                             decimals: parsedData.parsed.info.decimals,
                             name: shareMintData.result?.content?.metadata?.name ||
@@ -348,7 +388,7 @@ async function getToken({ mintAddress, endpoint, connection, }) {
                             mintAuthority: shareMintData.result?.token_info?.mint_authority,
                             freezeAuthority: shareMintData.result?.token_info?.freeze_authority,
                             supply: parsedData.parsed.info.supply,
-                            shareMintAddress: shareMintPda.toString(),
+                            shareMintAddress: shareMintPda.toString(), // Include share mint address
                         };
                         await (0, core_1.setSafeCache)(cacheKey, returnObj);
                         return returnObj;
@@ -356,9 +396,11 @@ async function getToken({ mintAddress, endpoint, connection, }) {
                 }
             }
             catch (vaultError) {
+                // Not a vault or error checking vault state, continue to return null
                 core_1.Logger.log.info('getToken', 'Not a vault program or error querying vault:', vaultError);
             }
         }
+        // If all attempts failed, return null
         return null;
     }
     catch (error) {
@@ -368,6 +410,7 @@ async function getToken({ mintAddress, endpoint, connection, }) {
         return null;
     }
 }
+// Helper function to get just the token symbol
 async function getTokenSymbol({ endpoint, mintAddress, }) {
     try {
         const tokenMetadata = await getToken({ endpoint, mintAddress });
@@ -431,6 +474,28 @@ async function fetchUserShareBalance({ connection, publicKey, shareMint, }) {
         return 0;
     }
 }
+/**
+ * Same on-chain lookup as `fetchUserShareBalance`, but returns the raw u64
+ * `amount` string and the mint's `decimals` — or `null` when the scale can't
+ * be determined (see Return shape) — instead of the floating-point `uiAmount`.
+ * Callers that feed the result into BigInt math (positions, redemptions,
+ * allowances) must use this — `uiAmount` is lossy and silently encodes with
+ * the wrong scale when passed back through `toNormalizedBn` without an
+ * explicit decimals argument.
+ *
+ * Return shape:
+ *   `{ amount: '<u64>', decimals: number }` — token account exists.
+ *   `{ amount: '0',     decimals: null   }` — no token account, missing
+ *      tokenAmount in the parsed response, missing args, or the RPC threw.
+ *
+ * `decimals === null` is the "scale unknown" signal — callers that need a
+ * normalized `INormalizedNumber` must substitute a known decimals value
+ * (typically the deposit mint's decimals from backend metadata) before
+ * normalizing. Never throws.
+ *
+ * RPC cost: 1 × `getParsedTokenAccountsByOwner`. Independent of how many
+ * other accounts the wallet owns (filter is mint-scoped).
+ */
 async function fetchUserShareBalanceRaw({ connection, publicKey, shareMint, }) {
     if (!publicKey || !shareMint)
         return { amount: '0', decimals: null };
@@ -456,9 +521,17 @@ async function fetchUserShareBalanceRaw({ connection, publicKey, shareMint, }) {
         return { amount: '0', decimals: null };
     }
 }
+/**
+ * Resolve the on-chain program ID for a Solana vault.
+ * Prefers the explicit `program_id` from metadata; falls back to the vault address
+ * (for legacy vaults where address == program ID).
+ */
 function resolveProgramId(vaultAddress, solanaMetadata) {
     return solanaMetadata?.program_id || vaultAddress;
 }
+// String-arithmetic UI→raw conversion. Truncates past `decimals` like
+// ethers.parseUnits; safe past Number.MAX_SAFE_INTEGER.
+/** @internal */
 function uiAmountToRawBn(uiAmount, decimals) {
     if (!Number.isFinite(uiAmount)) {
         throw new core_1.AugustValidationError('INVALID_INPUT', `uiAmountToRawBn: amount must be finite, got ${uiAmount}`);
@@ -469,6 +542,8 @@ function uiAmountToRawBn(uiAmount, decimals) {
     if (!Number.isInteger(decimals) || decimals < 0) {
         throw new core_1.AugustValidationError('INVALID_INPUT', `uiAmountToRawBn: decimals must be a non-negative integer, got ${decimals}`);
     }
+    // Build the fixed-decimal string manually — `.toFixed(decimals)` rounds
+    // the last digit, but parseUnits semantics require truncation.
     const uiStr = uiAmount.toString();
     const expansion = uiStr.includes('e') || uiStr.includes('E')
         ? uiAmount.toFixed(Math.max(decimals, 20)).replace(/\.?0+$/, '')

package/lib/adapters/solana/vault.actions.d.ts

@@ -2,6 +2,17 @@ import { web3 } from '@coral-xyz/anchor';
 import { Connection, PublicKey, Transaction } from '@solana/web3.js';
 import { ISolanaConnectionOptions } from './types';
 import { SendTransactionOptions } from '@solana/wallet-adapter-base';
+/**
+ * Deposit funds into a Solana August vault and mint share tokens.
+ *
+ * @param depositAmount  `bigint` is treated as raw on-chain units (preferred
+ *   — no JS-float round-trip). `number` is treated as a UI amount and
+ *   scaled by the deposit mint's decimals via {@link uiAmountToRawBn}.
+ * @throws AugustValidationError on missing wallet/programId or invalid amount.
+ * @remarks The on-chain `deposit` instruction has no `min_shares_out`
+ *   parameter; slippage cannot be enforced on-chain until the program ships
+ *   that argument.
+ */
 export declare function handleSolanaDeposit({ provider, connection, network, vaultProgramId, vaultAddress, depositAmount, publicKey, sendTransaction, idl, }: {
     vaultProgramId: PublicKey | string;
     vaultAddress?: PublicKey | string;
@@ -10,6 +21,14 @@ export declare function handleSolanaDeposit({ provider, connection, network, vau
     depositAmount: number | bigint;
     sendTransaction: (transaction: Transaction | web3.VersionedTransaction, connection: Connection, options?: SendTransactionOptions) => Promise<web3.TransactionSignature>;
 } & ISolanaConnectionOptions): Promise<any>;
+/**
+ * Redeem vault shares back into the underlying mint on a Solana August vault.
+ *
+ * @param redeemShares  `bigint` is treated as raw share-token units;
+ *   `number` is treated as a UI amount. See {@link handleSolanaDeposit} for
+ *   the same caveat about the missing on-chain slippage guard.
+ * @throws AugustValidationError on missing wallet/programId or invalid amount.
+ */
 export declare function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultAddress, publicKey, redeemShares, sendTransaction, idl, }: {
     idl: any;
     vaultProgramId: PublicKey | string;