@augustdigital/sdk 8.3.1 → 8.5.0

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,

package/lib/adapters/stellar/actions.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Stellar Vault Actions
+ *
+ * Builds unsigned Soroban transactions for vault deposit/redeem operations.
+ * Returns assembled XDR (base64) for wallet signing (e.g. Freighter).
+ */
 import { IStellarDepositParams, IStellarRedeemParams } from './types';
+/**
+ * Deposit assets into a Stellar vault (self-deposit).
+ *
+ * Builds an unsigned Soroban transaction invoking the vault's `deposit` function.
+ * All three address roles (receiver, from, operator) are set to senderAddress.
+ *
+ * Contract signature: deposit(assets: i128, receiver: Address, from: Address, operator: Address) -> i128
+ *
+ * @returns Base64-encoded XDR of the unsigned transaction, ready for wallet signing.
+ */
 export declare function handleStellarDeposit(params: IStellarDepositParams): Promise<string>;
+/**
+ * Build an unsigned self-redeem Soroban transaction (receiver, owner, and
+ * operator all = `receiverAddress`). Assumes the deployed vault exposes
+ * `redeem(shares: i128, receiver, owner, operator) -> i128`; divergence
+ * surfaces as a generic Soroban simulation error.
+ *
+ * @returns Base64-encoded XDR ready for wallet signing; pass the signed
+ *   XDR to {@link submitStellarTransaction}.
+ */
 export declare function handleStellarRedeem(params: IStellarRedeemParams): Promise<string>;

package/lib/adapters/stellar/actions.js

@@ -1,4 +1,10 @@
 "use strict";
+/**
+ * Stellar Vault Actions
+ *
+ * Builds unsigned Soroban transactions for vault deposit/redeem operations.
+ * Returns assembled XDR (base64) for wallet signing (e.g. Freighter).
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleStellarDeposit = handleStellarDeposit;
 exports.handleStellarRedeem = handleStellarRedeem;
@@ -16,6 +22,14 @@ function validateAccountAddress(address, label) {
         throw new core_1.AugustValidationError('INVALID_ADDRESS', `Invalid ${label} address: expected a Stellar account (G-prefix), got "${address}"`);
     }
 }
+/**
+ * Build a self-operation Soroban transaction where all address roles
+ * (receiver, from/owner, operator) are set to the same user address.
+ *
+ * Note: This only supports self-operations. If delegated operations
+ * (distinct receiver/owner/operator) are needed in the future,
+ * a separate argument builder will be required.
+ */
 function buildSelfOperationArgs(amount, userAddress) {
     const userScVal = new stellar_sdk_1.Address(userAddress).toScVal();
     return [
@@ -25,6 +39,16 @@ function buildSelfOperationArgs(amount, userAddress) {
         userScVal,
     ];
 }
+/**
+ * Deposit assets into a Stellar vault (self-deposit).
+ *
+ * Builds an unsigned Soroban transaction invoking the vault's `deposit` function.
+ * All three address roles (receiver, from, operator) are set to senderAddress.
+ *
+ * Contract signature: deposit(assets: i128, receiver: Address, from: Address, operator: Address) -> i128
+ *
+ * @returns Base64-encoded XDR of the unsigned transaction, ready for wallet signing.
+ */
 async function handleStellarDeposit(params) {
     const { contractId, amount, senderAddress, network } = params;
     validateContractAddress(contractId);
@@ -33,6 +57,15 @@ async function handleStellarDeposit(params) {
     const args = buildSelfOperationArgs((0, soroban_1.toBigIntAmount)(amount, 'deposit amount'), senderAddress);
     return (0, soroban_1.buildSorobanTx)(config, senderAddress, contractId, 'deposit', args);
 }
+/**
+ * Build an unsigned self-redeem Soroban transaction (receiver, owner, and
+ * operator all = `receiverAddress`). Assumes the deployed vault exposes
+ * `redeem(shares: i128, receiver, owner, operator) -> i128`; divergence
+ * surfaces as a generic Soroban simulation error.
+ *
+ * @returns Base64-encoded XDR ready for wallet signing; pass the signed
+ *   XDR to {@link submitStellarTransaction}.
+ */
 async function handleStellarRedeem(params) {
     const { contractId, shares, receiverAddress, network } = params;
     validateContractAddress(contractId);

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

@@ -1,3 +1,6 @@
+/**
+ * Stellar Constants
+ */
 import type { IStellarNetwork } from './types';
 export declare const STELLAR_CHAIN_ID: number;
 export declare const STELLAR_CHAIN: {
@@ -8,10 +11,33 @@ export declare const STELLAR_CHAIN: {
 export declare const SOROBAN_RPC_URLS: Record<IStellarNetwork, string>;
 export declare const NETWORK_PASSPHRASES: Record<IStellarNetwork, string>;
 export declare const STELLAR_FALLBACK_DECIMALS = 7;
+/**
+ * Validity window for a submitted Soroban invocation (seconds).
+ *
+ * This becomes the transaction's `maxTime`. Validators reject a tx whose
+ * `maxTime` has passed (`txTOO_LATE`), so the window must outlast the slowest
+ * realistic sign-then-submit path: hardware wallets, careful manual review,
+ * and institutional approval flows (e.g. Fordefi) that don't sign instantly.
+ * 10 minutes comfortably covers those while staying well inside the Soroban
+ * footprint/ledger-entry TTL, so the simulated footprint can't go stale first.
+ *
+ * The window is anchored to the *network* clock (see `getNetworkCloseTime` in
+ * soroban.ts), not the signer's `Date.now()`, so a skewed device clock can't
+ * make the deadline expire early.
+ */
 export declare const TX_TIMEOUT_SECONDS = 600;
+/** Timeout for read-only Soroban simulation queries (seconds). */
 export declare const QUERY_TIMEOUT_SECONDS = 10;
+/**
+ * Max fee ceiling in stroops (1_000_000 stroops = 0.1 XLM).
+ * assembleTransaction adjusts to the actual fee from simulation.
+ */
 export declare const MAX_FEE_STROOPS = "1000000";
+/** Initial confirmation-poll interval (ms). Grows up to {@link POLL_INTERVAL_MAX_MS}. */
 export declare const POLL_INTERVAL_MS = 2000;
+/** Cap for the backed-off confirmation-poll interval (ms). */
 export declare const POLL_INTERVAL_MAX_MS = 8000;
+/** Multiplier applied to the poll interval after each NOT_FOUND poll. */
 export declare const POLL_INTERVAL_BACKOFF = 1.5;
+/** Maximum number of polling attempts before timeout. */
 export declare const MAX_POLL_ATTEMPTS = 30;

package/lib/adapters/stellar/constants.js

@@ -1,8 +1,12 @@
 "use strict";
+/**
+ * Stellar Constants
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_POLL_ATTEMPTS = exports.POLL_INTERVAL_BACKOFF = exports.POLL_INTERVAL_MAX_MS = exports.POLL_INTERVAL_MS = exports.MAX_FEE_STROOPS = exports.QUERY_TIMEOUT_SECONDS = exports.TX_TIMEOUT_SECONDS = exports.STELLAR_FALLBACK_DECIMALS = exports.NETWORK_PASSPHRASES = exports.SOROBAN_RPC_URLS = exports.STELLAR_CHAIN = exports.STELLAR_CHAIN_ID = void 0;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const web3_1 = require("../../core/constants/web3");
+// Synthetic chain ID for Stellar, sourced from SPECIAL_CHAINS. See core/constants/web3.ts for all non-EVM chain IDs.
 exports.STELLAR_CHAIN_ID = web3_1.SPECIAL_CHAINS.stellar.chainId;
 exports.STELLAR_CHAIN = web3_1.SPECIAL_CHAINS.stellar;
 exports.SOROBAN_RPC_URLS = {
@@ -13,12 +17,37 @@ exports.NETWORK_PASSPHRASES = {
     mainnet: stellar_sdk_1.Networks.PUBLIC,
     testnet: stellar_sdk_1.Networks.TESTNET,
 };
+// Most Stellar/Soroban tokens use 7 decimal places (matching XLM's 10^7 stroops convention).
+// Used as fallback when deposit_token_decimals is not available from backend metadata.
 exports.STELLAR_FALLBACK_DECIMALS = 7;
+/**
+ * Validity window for a submitted Soroban invocation (seconds).
+ *
+ * This becomes the transaction's `maxTime`. Validators reject a tx whose
+ * `maxTime` has passed (`txTOO_LATE`), so the window must outlast the slowest
+ * realistic sign-then-submit path: hardware wallets, careful manual review,
+ * and institutional approval flows (e.g. Fordefi) that don't sign instantly.
+ * 10 minutes comfortably covers those while staying well inside the Soroban
+ * footprint/ledger-entry TTL, so the simulated footprint can't go stale first.
+ *
+ * The window is anchored to the *network* clock (see `getNetworkCloseTime` in
+ * soroban.ts), not the signer's `Date.now()`, so a skewed device clock can't
+ * make the deadline expire early.
+ */
 exports.TX_TIMEOUT_SECONDS = 600;
+/** Timeout for read-only Soroban simulation queries (seconds). */
 exports.QUERY_TIMEOUT_SECONDS = 10;
+/**
+ * Max fee ceiling in stroops (1_000_000 stroops = 0.1 XLM).
+ * assembleTransaction adjusts to the actual fee from simulation.
+ */
 exports.MAX_FEE_STROOPS = '1000000';
+/** Initial confirmation-poll interval (ms). Grows up to {@link POLL_INTERVAL_MAX_MS}. */
 exports.POLL_INTERVAL_MS = 2000;
+/** Cap for the backed-off confirmation-poll interval (ms). */
 exports.POLL_INTERVAL_MAX_MS = 8000;
+/** Multiplier applied to the poll interval after each NOT_FOUND poll. */
 exports.POLL_INTERVAL_BACKOFF = 1.5;
+/** Maximum number of polling attempts before timeout. */
 exports.MAX_POLL_ATTEMPTS = 30;
 //# sourceMappingURL=constants.js.map

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

@@ -1,6 +1,62 @@
+/**
+ * Stellar Vault Getters
+ *
+ * Data fetching for Stellar vaults. Enriches backend metadata with on-chain
+ * total assets, total supply, and share decimals from Soroban RPC. Also
+ * provides user position queries and deposit preview (convertToShares).
+ * Falls back to backend TVL for total assets, zero for total supply, and
+ * STELLAR_FALLBACK_DECIMALS for share decimals when on-chain queries fail.
+ */
 import type { ITokenizedVault, IVault } from '../../types';
 import type { IVaultBaseOptions } from '../../modules/vaults/types';
 import type { IStellarNetwork, IStellarUserPosition } from './types';
+/**
+ * Build a unified IVault from backend + on-chain data for Stellar vaults.
+ * Reads total assets and total supply from the Soroban contract via RPC.
+ * Falls back to backend `latest_reported_tvl` for total assets, or zero
+ * for total supply, when on-chain queries fail.
+ */
 export declare const getStellarVault: (tokenizedVault: ITokenizedVault, _options: IVaultBaseOptions) => Promise<IVault>;
+/**
+ * Get user position for a Stellar vault.
+ * Queries the vault contract's balance(address) and decimals() functions via Soroban RPC.
+ *
+ * Returns `{ shares, decimals, decimalsFromFallback }` on success (shares may be
+ * '0' for zero balance), or null when the balance query fails. The two reads are
+ * independent: a `decimals()` failure does NOT null the result — instead
+ * `decimals` falls back to STELLAR_FALLBACK_DECIMALS (7) and
+ * `decimalsFromFallback` is set to `true` so callers can tell a fabricated 7
+ * apart from a genuine 7-decimal vault.
+ *
+ * Why this matters: an ERC4626 offset vault has share decimals = asset + offset
+ * (e.g. 13). A consumer that sizes a redeem trusting a silent fallback 7 would
+ * under-redeem by `10^offset`. Callers that settle a redeem from this position
+ * MUST refuse (surface an error) when `decimalsFromFallback` is `true` rather
+ * than trusting `decimals`. See AUGUST-6381 (follow-up to AUGUST-6380).
+ *
+ * @param vaultAddress - Stellar vault contract ID (C… address)
+ * @param walletAddress - User's Stellar account (G… address); validated upfront
+ * @param network - 'mainnet' | 'testnet' (defaults to 'mainnet')
+ * @returns The position, or `null` if the balance read failed or was unparseable.
+ * @throws AugustValidationError on an invalid `walletAddress`.
+ * @example
+ * ```ts
+ * const pos = await getStellarUserPosition(vault, wallet, 'mainnet');
+ * if (!pos || pos.decimalsFromFallback) {
+ *   // Refuse to size a redeem — share scale is not authoritatively known.
+ *   throw new Error('Stellar share decimals unresolved');
+ * }
+ * const human = Number(pos.shares) / 10 ** pos.decimals;
+ * ```
+ */
 export declare const getStellarUserPosition: (vaultAddress: string, walletAddress: string, network?: IStellarNetwork) => Promise<IStellarUserPosition | null>;
+/**
+ * Query the vault's `convert_to_shares` to preview how many shares a deposit
+ * amount would yield.  Returns the raw share amount as a string, or null on
+ * failure.
+ *
+ * @param vaultAddress  Stellar contract ID (C… address)
+ * @param rawAmount     Deposit amount in the deposit token's smallest unit
+ * @param network       'mainnet' | 'testnet'
+ */
 export declare const convertToShares: (vaultAddress: string, rawAmount: string, network?: IStellarNetwork) => Promise<string | null>;

package/lib/adapters/stellar/getters.js

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * Stellar Vault Getters
+ *
+ * Data fetching for Stellar vaults. Enriches backend metadata with on-chain
+ * total assets, total supply, and share decimals from Soroban RPC. Also
+ * provides user position queries and deposit preview (convertToShares).
+ * Falls back to backend TVL for total assets, zero for total supply, and
+ * STELLAR_FALLBACK_DECIMALS for share decimals when on-chain queries fail.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertToShares = exports.getStellarUserPosition = exports.getStellarVault = void 0;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
@@ -6,6 +15,16 @@ const core_1 = require("../../core");
 const utils_1 = require("../../modules/vaults/utils");
 const constants_1 = require("./constants");
 const soroban_1 = require("./soroban");
+/**
+ * Parse an ScVal into a share-decimals value, reporting whether the
+ * authoritative on-chain value was available.
+ *
+ * Returns `{ decimals, fromFallback }`. When the `decimals()` retval is missing
+ * or unparseable, `decimals` is STELLAR_FALLBACK_DECIMALS (7) and `fromFallback`
+ * is `true` — the signal callers need to avoid trusting a fabricated scale (a
+ * silent 7 under-redeems ERC4626 offset vaults; see AUGUST-6381). A successful
+ * parse returns the on-chain value with `fromFallback: false`.
+ */
 function parseDecimals(scVal, context, vaultAddress) {
     if (!scVal) {
         core_1.Logger.log.error(context, 'Decimals not available — using fallback (financial values may be incorrect)', {
@@ -26,9 +45,19 @@ function parseDecimals(scVal, context, vaultAddress) {
         return { decimals: constants_1.STELLAR_FALLBACK_DECIMALS, fromFallback: true };
     }
 }
+/**
+ * Parse an ScVal into a decimals number, returning the fallback on failure.
+ * Thin wrapper over {@link parseDecimals} for callers that only need the value
+ * (the fallback is already surfaced via logs). Prefer `parseDecimals` when the
+ * caller must distinguish a fallback from an authoritative read.
+ */
 function parseDecimalsOrFallback(scVal, context, vaultAddress) {
     return parseDecimals(scVal, context, vaultAddress).decimals;
 }
+/**
+ * Resolve the Stellar network for a vault from its backend metadata.
+ * Logs a warning when falling back to mainnet.
+ */
 function resolveNetwork(tokenizedVault) {
     const meta = tokenizedVault.stellar_vault_metadata;
     const networkName = meta?.network_name;
@@ -43,6 +72,12 @@ function resolveNetwork(tokenizedVault) {
     }
     return 'mainnet';
 }
+/**
+ * Build a unified IVault from backend + on-chain data for Stellar vaults.
+ * Reads total assets and total supply from the Soroban contract via RPC.
+ * Falls back to backend `latest_reported_tvl` for total assets, or zero
+ * for total supply, when on-chain queries fail.
+ */
 const getStellarVault = async (tokenizedVault, _options) => {
     const stellarMetadata = tokenizedVault.stellar_vault_metadata;
     const depositDecimals = stellarMetadata?.deposit_token_decimals ?? constants_1.STELLAR_FALLBACK_DECIMALS;
@@ -53,6 +88,7 @@ const getStellarVault = async (tokenizedVault, _options) => {
             STELLAR_FALLBACK_DECIMALS: constants_1.STELLAR_FALLBACK_DECIMALS,
         });
     }
+    // Attempt on-chain queries for total assets, total supply, and share decimals
     const network = resolveNetwork(tokenizedVault);
     const config = (0, soroban_1.resolveNetworkConfig)(network);
     const [assetsResult, supplyResult, decimalsResult] = await Promise.all([
@@ -60,6 +96,7 @@ const getStellarVault = async (tokenizedVault, _options) => {
         (0, soroban_1.queryContract)(config, tokenizedVault.address, 'total_supply'),
         (0, soroban_1.queryContract)(config, tokenizedVault.address, 'decimals'),
     ]);
+    // Share token decimals may differ from deposit token decimals
     const shareDecimals = parseDecimalsOrFallback(decimalsResult, 'getStellarVault', tokenizedVault.address);
     let totalAssets;
     if (assetsResult) {
@@ -114,8 +151,41 @@ const getStellarVault = async (tokenizedVault, _options) => {
     });
 };
 exports.getStellarVault = getStellarVault;
+/**
+ * Get user position for a Stellar vault.
+ * Queries the vault contract's balance(address) and decimals() functions via Soroban RPC.
+ *
+ * Returns `{ shares, decimals, decimalsFromFallback }` on success (shares may be
+ * '0' for zero balance), or null when the balance query fails. The two reads are
+ * independent: a `decimals()` failure does NOT null the result — instead
+ * `decimals` falls back to STELLAR_FALLBACK_DECIMALS (7) and
+ * `decimalsFromFallback` is set to `true` so callers can tell a fabricated 7
+ * apart from a genuine 7-decimal vault.
+ *
+ * Why this matters: an ERC4626 offset vault has share decimals = asset + offset
+ * (e.g. 13). A consumer that sizes a redeem trusting a silent fallback 7 would
+ * under-redeem by `10^offset`. Callers that settle a redeem from this position
+ * MUST refuse (surface an error) when `decimalsFromFallback` is `true` rather
+ * than trusting `decimals`. See AUGUST-6381 (follow-up to AUGUST-6380).
+ *
+ * @param vaultAddress - Stellar vault contract ID (C… address)
+ * @param walletAddress - User's Stellar account (G… address); validated upfront
+ * @param network - 'mainnet' | 'testnet' (defaults to 'mainnet')
+ * @returns The position, or `null` if the balance read failed or was unparseable.
+ * @throws AugustValidationError on an invalid `walletAddress`.
+ * @example
+ * ```ts
+ * const pos = await getStellarUserPosition(vault, wallet, 'mainnet');
+ * if (!pos || pos.decimalsFromFallback) {
+ *   // Refuse to size a redeem — share scale is not authoritatively known.
+ *   throw new Error('Stellar share decimals unresolved');
+ * }
+ * const human = Number(pos.shares) / 10 ** pos.decimals;
+ * ```
+ */
 const getStellarUserPosition = async (vaultAddress, walletAddress, network = 'mainnet') => {
     const config = (0, soroban_1.resolveNetworkConfig)(network);
+    // Validate address upfront — invalid input is a caller bug, not an RPC issue
     let userAddress;
     try {
         userAddress = new stellar_sdk_1.Address(walletAddress);
@@ -124,6 +194,7 @@ const getStellarUserPosition = async (vaultAddress, walletAddress, network = 'ma
         throw new core_1.AugustValidationError('INVALID_ADDRESS', `getStellarUserPosition: invalid walletAddress "${walletAddress}": ${String(addrErr)}`, { cause: addrErr });
     }
     try {
+        // Fetch balance and decimals in parallel — they're independent queries
         const [balanceResult, decimalsResult] = await Promise.all([
             (0, soroban_1.queryContract)(config, vaultAddress, 'balance', [userAddress.toScVal()]),
             (0, soroban_1.queryContract)(config, vaultAddress, 'decimals'),
@@ -164,7 +235,17 @@ const getStellarUserPosition = async (vaultAddress, walletAddress, network = 'ma
     }
 };
 exports.getStellarUserPosition = getStellarUserPosition;
+/**
+ * Query the vault's `convert_to_shares` to preview how many shares a deposit
+ * amount would yield.  Returns the raw share amount as a string, or null on
+ * failure.
+ *
+ * @param vaultAddress  Stellar contract ID (C… address)
+ * @param rawAmount     Deposit amount in the deposit token's smallest unit
+ * @param network       'mainnet' | 'testnet'
+ */
 const convertToShares = async (vaultAddress, rawAmount, network = 'mainnet') => {
+    // Validate address upfront — invalid input is a caller bug, not an RPC issue
     try {
         new stellar_sdk_1.Address(vaultAddress);
     }

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

@@ -1,3 +1,11 @@
+/**
+ * Stellar Adapter for August SDK
+ *
+ * Provides Stellar vault operations: deposit, redeem, position queries,
+ * and on-chain data fetching via Soroban RPC.
+ *
+ * @module StellarAdapter
+ */
 import * as StellarConstants from './constants';
 import * as StellarGetters from './getters';
 import * as StellarActions from './actions';
@@ -14,16 +22,56 @@ export declare const Stellar: {
     submit: typeof StellarSubmit;
     getters: typeof StellarGetters;
 };
+/**
+ * Stellar Adapter for August SDK
+ *
+ * @example
+ * ```
+ * const adapter = new StellarAdapter('testnet');
+ * const xdr = await adapter.vaultDeposit({
+ *   contractId: 'CBGWW5...',
+ *   amount: '1000000',
+ *   senderAddress: 'GDLZ...',
+ * });
+ * // Sign xdr with wallet (e.g. Freighter), then submit via adapter.submitTransaction()
+ * ```
+ */
 declare class StellarAdapter {
     private _network;
     constructor(network?: IStellarNetwork);
     get network(): IStellarNetwork;
     isStellarAddress(address: string): boolean;
     getExplorerLink(id: string, type?: 'contract' | 'account' | 'tx'): string;
+    /**
+     * Build an unsigned deposit transaction for a Stellar vault.
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
     vaultDeposit(params: Omit<IStellarDepositParams, 'network'>): Promise<string>;
+    /**
+     * Build an unsigned redeem transaction for a Stellar vault.
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
     vaultRedeem(params: Omit<IStellarRedeemParams, 'network'>): Promise<string>;
+    /**
+     * Submit a signed Soroban transaction and poll until confirmed.
+     * @returns Transaction hash on success
+     */
     submitTransaction(signedXdr: string): Promise<string>;
+    /**
+     * Get user's vault share balance.
+     *
+     * @returns The position `{ shares, decimals, decimalsFromFallback }`, or null
+     * if the balance read fails. When `decimalsFromFallback` is `true` the
+     * `decimals()` read failed and `decimals` is the fallback (7) — callers sizing
+     * a redeem MUST refuse rather than trust it (see AUGUST-6381).
+     */
     getUserPosition(vaultAddress: string, walletAddress: string): Promise<IStellarUserPosition | null>;
+    /**
+     * Preview how many vault shares a deposit amount would yield.
+     * @param vaultAddress  Stellar contract ID (C… address)
+     * @param rawAmount     Deposit amount in the deposit token's smallest unit
+     * @returns Raw share amount as a string, or null if query fails.
+     */
     convertToShares(vaultAddress: string, rawAmount: string): Promise<string | null>;
 }
 export default StellarAdapter;