@augustdigital/sdk 8.3.2 → 8.6.0

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,7 +52,21 @@ 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 {
+    _endpoint;
+    _network;
+    _connection;
+    _provider;
     constructor(endpoint, network = utils_1.SolanaUtils.fallbackNetwork) {
         this._endpoint = endpoint;
         this._network = network;
@@ -58,6 +77,7 @@ class SolanaAdapter {
             connection,
         });
     }
+    // Getters and setters for private properties
     get endpoint() {
         return this._endpoint;
     }
@@ -70,6 +90,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 +164,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 +204,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 +221,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/types.d.ts

@@ -1,4 +1,4 @@
-import { AnchorProvider } from '@coral-xyz/anchor';
+import type { AnchorProvider } from '@coral-xyz/anchor';
 import type { Connection, PublicKey } from '@solana/web3.js';
 export type ISolanaRpcEndpoint = `https://${string}`;
 export type ISolanaNetwork = 'devnet' | 'mainnet-beta' | 'testnet' | 'localnet';

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

@@ -1,6 +1,6 @@
-import { AnchorProvider, BN, Program, web3 } from '@coral-xyz/anchor';
-import { PublicKey, Transaction } from '@solana/web3.js';
-import { ISolanaConnectionOptions, ISolanaVaultState } from './types';
+import { AnchorProvider, BN, Program, type web3 } from '@coral-xyz/anchor';
+import { PublicKey, type Transaction } from '@solana/web3.js';
+import type { ISolanaConnectionOptions, ISolanaVaultState } from './types';
 declare function getExplorerLink({ signature, type, network, }: {
     signature: string;
     type: 'tx' | 'address' | 'token';
@@ -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

@@ -1,7 +1,18 @@
-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';
+import { type web3 } from '@coral-xyz/anchor';
+import { type Connection, PublicKey, Transaction } from '@solana/web3.js';
+import type { ISolanaConnectionOptions } from './types';
+import type { 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;

package/lib/adapters/solana/vault.actions.js

@@ -8,6 +8,17 @@ const spl_token_1 = require("@solana/spl-token");
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
 const core_1 = require("../../core");
+/**
+ * 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.
+ */
 async function handleSolanaDeposit({ provider, connection, network = constants_1.fallbackNetwork, vaultProgramId, vaultAddress, depositAmount, publicKey, sendTransaction, idl, }) {
     try {
         if (!publicKey)
@@ -44,8 +55,11 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
         core_1.Logger.log.info('handleSolanaDeposit', 'Vault state PDA', vaultStatePda.toBase58());
         const vaultTokenAtaPda = utils_1.SolanaUtils.deriveVaultTokenAtaPda(_vaultProgramId, _depositMint, vaultVersion);
         core_1.Logger.log.info('handleSolanaDeposit', 'Vault token ATA PDA', vaultTokenAtaPda.toBase58());
+        // Use on-chain share mint from vault state instead of deriving a PDA,
+        // since PDA derivation assumes one share mint per program (single-vault only).
         const shareMintAddr = new web3_js_1.PublicKey(shareMint);
         core_1.Logger.log.info('handleSolanaDeposit', 'Share mint', shareMintAddr.toBase58());
+        // Get mint info to handle decimals
         const mintInfo = await connection.getParsedAccountInfo(_depositMint);
         if (!mintInfo.value) {
             throw new Error('Could not fetch mint info');
@@ -64,6 +78,7 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
             }
             depositAmountRaw = (0, utils_1.uiAmountToRawBn)(depositAmount, decimals);
         }
+        // Find user's token accounts
         const userTokenAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
             mint: _depositMint,
         });
@@ -78,9 +93,14 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
         let senderShareAccount;
         if (userShareAccounts.value.length === 0) {
             core_1.Logger.log.info('handleSolanaDeposit', 'Creating share account');
+            // Create share account if it doesn't exist
             senderShareAccount = await (0, spl_token_1.getAssociatedTokenAddress)(shareMintAddr, _publicKey);
             core_1.Logger.log.info('handleSolanaDeposit', 'Sender share account', senderShareAccount.toBase58());
-            const createAtaIx = (0, spl_token_1.createAssociatedTokenAccountInstruction)(_publicKey, senderShareAccount, _publicKey, shareMintAddr);
+            // Create the associated token account
+            const createAtaIx = (0, spl_token_1.createAssociatedTokenAccountInstruction)(_publicKey, // payer
+            senderShareAccount, // associated token account
+            _publicKey, // owner
+            shareMintAddr);
             core_1.Logger.log.info('handleSolanaDeposit', 'Create ATA Ix', createAtaIx.programId.toBase58());
             const transaction = new web3_js_1.Transaction().add(createAtaIx);
             const signature = await sendTransaction(transaction, connection);
@@ -100,7 +120,9 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
         core_1.Logger.log.info('handleSolanaDeposit', 'Share mint', shareMintAddr.toBase58());
         core_1.Logger.log.info('handleSolanaDeposit', 'Deposit mint', _depositMint?.toBase58());
         core_1.Logger.log.info('handleSolanaDeposit', 'Signer', _publicKey.toBase58());
+        // Get a fresh blockhash to avoid "Blockhash not found" errors
         const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
+        // TODO(slippage): pass `min_shares_out` here when the program ships it.
         const tx = await program.methods
             .deposit(depositAmountRaw)
             .accounts({
@@ -118,6 +140,7 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
             preflightCommitment: 'confirmed',
         });
         core_1.Logger.log.info('handleSolanaDeposit', 'Deposit successful:', tx);
+        // Wait for confirmation with the blockhash we used
         await connection.confirmTransaction({
             signature: tx,
             blockhash,
@@ -146,6 +169,14 @@ async function handleSolanaDeposit({ provider, connection, network = constants_1
         });
     }
 }
+/**
+ * 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.
+ */
 async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultAddress, publicKey, redeemShares, sendTransaction, idl, }) {
     try {
         if (!publicKey)
@@ -181,7 +212,10 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
             ? new web3_js_1.PublicKey(vaultAddress)
             : utils_1.SolanaUtils.deriveVaultStatePda(_vaultProgramId);
         const vaultTokenAtaPda = utils_1.SolanaUtils.deriveVaultTokenAtaPda(_vaultProgramId, _depositMint, vaultVersion);
+        // Use on-chain share mint from vault state instead of deriving a PDA,
+        // since PDA derivation assumes one share mint per program (single-vault only).
         const shareMintAddr = new web3_js_1.PublicKey(shareMint);
+        // Get share mint info to handle decimals
         const shareMintInfo = await connection.getParsedAccountInfo(shareMintAddr);
         if (!shareMintInfo.value) {
             throw new Error('Could not fetch share mint info');
@@ -201,6 +235,7 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
             }
             redeemSharesRaw = (0, utils_1.uiAmountToRawBn)(redeemShares, shareDecimals);
         }
+        // Find user's token accounts
         const userTokenAccounts = await connection.getParsedTokenAccountsByOwner(_publicKey, {
             mint: _depositMint,
         });
@@ -215,6 +250,7 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
         }
         const senderTokenAccount = userTokenAccounts?.value[0]?.pubkey;
         const senderShareAccount = userShareAccounts?.value[0]?.pubkey;
+        // Get the fee recipient from vault state
         const readOnlyProvider = utils_1.SolanaUtils.getReadOnlyProvider({ connection });
         const readOnlyProgram = utils_1.SolanaUtils.getProgram({
             provider: readOnlyProvider,
@@ -222,13 +258,19 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
             programId: _vaultProgramId.toBase58(),
         });
         const vaultStateData = await readOnlyProgram.account.vaultState.fetch(vaultStatePda);
+        // Get the fee recipient's token account
         const feeRecipientTokenAccount = await (0, spl_token_1.getAssociatedTokenAddress)(_depositMint, vaultStateData.feeRecipient);
+        // Check if the fee recipient token account exists, if not create it
         const feeRecipientAccountInfo = await connection.getAccountInfo(feeRecipientTokenAccount);
         if (!feeRecipientAccountInfo) {
-            const createFeeRecipientAtaIx = (0, spl_token_1.createAssociatedTokenAccountInstruction)(_publicKey, feeRecipientTokenAccount, vaultStateData.feeRecipient, _depositMint);
+            const createFeeRecipientAtaIx = (0, spl_token_1.createAssociatedTokenAccountInstruction)(_publicKey, // payer (user pays for the account creation)
+            feeRecipientTokenAccount, // associated token account
+            vaultStateData.feeRecipient, // owner (the actual fee recipient)
+            _depositMint);
             const createAccountTx = new web3_js_1.Transaction().add(createFeeRecipientAtaIx);
             const createAccountSignature = await sendTransaction(createAccountTx, connection);
             core_1.Logger.log.info('handleSolanaRedeem', 'Fee recipient token account created:', createAccountSignature);
+            // Wait a moment for the account to be created
             await new Promise((resolve) => setTimeout(resolve, 1000));
         }
         else {
@@ -246,6 +288,7 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
         core_1.Logger.log.info('handleSolanaRedeem', 'Share mint:', shareMintAddr.toBase58());
         core_1.Logger.log.info('handleSolanaRedeem', 'Deposit mint:', _depositMint?.toBase58());
         core_1.Logger.log.info('handleSolanaRedeem', 'Signer:', _publicKey.toBase58());
+        // Get a fresh blockhash to avoid "Blockhash not found" errors
         const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('confirmed');
         const tx = await program.methods
             .redeem(redeemSharesRaw)
@@ -254,7 +297,7 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
             vaultDepositAta: vaultTokenAtaPda,
             senderTokenAccount,
             senderShareAccount,
-            feeRecipientAccount: feeRecipientTokenAccount,
+            feeRecipientAccount: feeRecipientTokenAccount, // The actual fee recipient's token account
             shareMint: shareMintAddr,
             depositMint: _depositMint,
             signer: _publicKey,
@@ -265,6 +308,7 @@ async function handleSolanaRedeem({ provider, connection, vaultProgramId, vaultA
             preflightCommitment: 'confirmed',
         });
         core_1.Logger.log.info('handleSolanaRedeem', 'Redeem successful:', tx);
+        // Wait for confirmation with the blockhash we used
         await connection.confirmTransaction({
             signature: tx,
             blockhash,