@augustdigital/sdk 8.3.2 → 8.6.0

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

@@ -1,3 +1,28 @@
-import { IStellarDepositParams, IStellarRedeemParams } from './types';
+/**
+ * Stellar Vault Actions
+ *
+ * Builds unsigned Soroban transactions for vault deposit/redeem operations.
+ * Returns assembled XDR (base64) for wallet signing (e.g. Freighter).
+ */
+import type { 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,78 @@ 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 the network confirms it.
+     *
+     * Submits on the network this adapter was constructed with, so `signedXdr`
+     * must be signed for that same network.
+     *
+     * @param signedXdr - Base64-encoded XDR of the signed transaction.
+     * @returns The transaction hash once the network confirms it as successful.
+     * @throws {@link AugustTimeoutError} when the transaction is not confirmed
+     *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+     * @throws {@link AugustSDKError} when the RPC rejects the submission or the
+     *   transaction confirms as failed. Its `context` carries `{ network, status }`
+     *   plus, when the result XDR decodes, a `resultCode` string holding the
+     *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+     *   is `undefined` when the code cannot be decoded.
+     * @example
+     * ```ts
+     * try {
+     *   const hash = await adapter.submitTransaction(signedXdr);
+     * } catch (err) {
+     *   if (err instanceof AugustSDKError && err.context?.resultCode === 'txBadSeq') {
+     *     // stale sequence number — rebuild the transaction and resubmit
+     *   }
+     * }
+     * ```
+     */
     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;

package/lib/adapters/stellar/index.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * Stellar Adapter for August SDK
+ *
+ * Provides Stellar vault operations: deposit, redeem, position queries,
+ * and on-chain data fetching via Soroban RPC.
+ *
+ * @module StellarAdapter
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -46,7 +54,22 @@ exports.Stellar = {
     submit: StellarSubmit,
     getters: 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()
+ * ```
+ */
 class StellarAdapter {
+    _network;
     constructor(network = 'mainnet') {
         this._network = network;
     }
@@ -59,24 +82,72 @@ class StellarAdapter {
     getExplorerLink(id, type) {
         return utils_1.StellarUtils.getExplorerLink({ id, type, network: this._network });
     }
+    /**
+     * Build an unsigned deposit transaction for a Stellar vault.
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
     async vaultDeposit(params) {
         return StellarActions.handleStellarDeposit({
             ...params,
             network: this._network,
         });
     }
+    /**
+     * Build an unsigned redeem transaction for a Stellar vault.
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
     async vaultRedeem(params) {
         return StellarActions.handleStellarRedeem({
             ...params,
             network: this._network,
         });
     }
+    /**
+     * Submit a signed Soroban transaction and poll until the network confirms it.
+     *
+     * Submits on the network this adapter was constructed with, so `signedXdr`
+     * must be signed for that same network.
+     *
+     * @param signedXdr - Base64-encoded XDR of the signed transaction.
+     * @returns The transaction hash once the network confirms it as successful.
+     * @throws {@link AugustTimeoutError} when the transaction is not confirmed
+     *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+     * @throws {@link AugustSDKError} when the RPC rejects the submission or the
+     *   transaction confirms as failed. Its `context` carries `{ network, status }`
+     *   plus, when the result XDR decodes, a `resultCode` string holding the
+     *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+     *   is `undefined` when the code cannot be decoded.
+     * @example
+     * ```ts
+     * try {
+     *   const hash = await adapter.submitTransaction(signedXdr);
+     * } catch (err) {
+     *   if (err instanceof AugustSDKError && err.context?.resultCode === 'txBadSeq') {
+     *     // stale sequence number — rebuild the transaction and resubmit
+     *   }
+     * }
+     * ```
+     */
     async submitTransaction(signedXdr) {
         return StellarSubmit.submitStellarTransaction(signedXdr, this._network);
     }
+    /**
+     * 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).
+     */
     async getUserPosition(vaultAddress, walletAddress) {
         return StellarGetters.getStellarUserPosition(vaultAddress, walletAddress, this._network);
     }
+    /**
+     * 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.
+     */
     async convertToShares(vaultAddress, rawAmount) {
         return StellarGetters.convertToShares(vaultAddress, rawAmount, this._network);
     }

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

@@ -1,11 +1,31 @@
-import { xdr, rpc } from '@stellar/stellar-sdk';
+/**
+ * Shared Soroban RPC utilities
+ *
+ * Common transaction building and read-only query helpers used by
+ * actions, submit, and getters modules.
+ */
+import { type xdr, rpc } from '@stellar/stellar-sdk';
 import type { IStellarNetwork } from './types';
+/** Resolved network configuration for Soroban RPC calls. */
 export interface ISorobanNetworkConfig {
     rpcUrl: string;
     passphrase: string;
 }
 export declare function createServer(rpcUrl: string): rpc.Server;
+/**
+ * Resolve RPC URL and network passphrase for a Stellar network.
+ */
 export declare function resolveNetworkConfig(network: IStellarNetwork): ISorobanNetworkConfig;
+/**
+ * Validate and convert a string amount to a non-negative BigInt.
+ * Throws a descriptive error if the value is not a valid non-negative integer string.
+ */
 export declare function toBigIntAmount(value: string, label: string): bigint;
 export declare function queryContract(config: ISorobanNetworkConfig, contractId: string, method: string, args?: xdr.ScVal[]): Promise<xdr.ScVal | null>;
+/**
+ * Build an unsigned Soroban contract invocation transaction.
+ * Fetches the real source account from the network (the account must exist and be funded).
+ * Simulates via Soroban RPC to attach resource footprint and auth entries,
+ * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ */
 export declare function buildSorobanTx(config: ISorobanNetworkConfig, sourceAddress: string, contractId: string, method: string, args: xdr.ScVal[]): Promise<string>;