@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/modules/vaults/write.actions.js

@@ -24,6 +24,10 @@ const core_1 = require("../../core");
 const swap_quotes_1 = require("../../services/swap-quotes");
 const adapter_helpers_1 = require("./adapter.helpers");
 const utils_1 = require("./utils");
+// Treat unparseable RPC payloads (bare "0x", etc.) as 0n with a warn log —
+// the defensive default is "approve again," and the log surfaces flaky RPCs
+// before they cause silent gas waste from spurious approvals.
+/** @internal */
 function safeBigInt(value, context = 'safeBigInt') {
     if (value === null || value === undefined)
         return 0n;
@@ -44,6 +48,11 @@ function safeBigInt(value, context = 'safeBigInt') {
         return 0n;
     }
 }
+// EVM-0/1 single-asset underlying deposits reuse vaultDecimals (vault and
+// underlying decimals match under ERC-4626 inheritance), saving one RPC.
+// Multi-asset / adapter / non-underlying paths must read from the deposit
+// asset's own ERC-20 — using share decimals there silently misencodes amounts.
+/** @internal */
 async function resolveDepositTokenDecimals(args) {
     const { actualDepositAsset, underlyingAsset, isNativeToken, isMultiAssetVault, vaultDecimals, readErc20Decimals, } = args;
     if (isNativeToken)
@@ -53,6 +62,7 @@ async function resolveDepositTokenDecimals(args) {
         return vaultDecimals;
     return readErc20Decimals(actualDepositAsset);
 }
+/** @internal */
 function resolveSpender(args) {
     if (args.swapRouterAddress)
         return args.swapRouterAddress;
@@ -62,6 +72,9 @@ function resolveSpender(args) {
         return args.adapterWrapperAddress;
     return args.target;
 }
+// Reject JS-number amounts past Number.MAX_SAFE_INTEGER — any larger
+// integer the caller passes is already wrong before we hit toNormalizedBn.
+/** @internal */
 function validateAmountPrecision(amount) {
     if (typeof amount === 'string' || typeof amount === 'bigint')
         return;
@@ -75,13 +88,17 @@ function validateAmountPrecision(amount) {
         throw new core_1.AugustValidationError('INVALID_INPUT', `amount ${amount} exceeds Number.MAX_SAFE_INTEGER; pass a string or bigint to preserve precision`);
     }
 }
+// Tries tx.wait() first (preserves replacement detection & revert checks), then falls back to
+// provider.waitForTransaction() for RPCs (e.g. Monad) that return malformed pending tx fields.
 const SAFE_WAIT_TIMEOUT_MS = 120000;
+/** @internal */
 function isNonceParsing(error) {
     const code = error?.code;
     const msg = String(error).toLowerCase();
     return ((code === 'INVALID_ARGUMENT' || code === 'BAD_DATA') &&
         msg.includes('nonce'));
 }
+/** @internal */
 async function safeWaitForTx(tx) {
     try {
         return await tx.wait();
@@ -102,6 +119,14 @@ async function safeWaitForTx(tx) {
         throw error;
     }
 }
+/**
+ * Wraps an ethers contract call that returns a TransactionResponse.
+ * Some RPCs (e.g. Monad) return malformed pending tx fields like `nonce: "undefined"`,
+ * which causes ethers.js to throw during response parsing before safeWaitForTx runs.
+ * This wrapper catches that error, extracts the tx hash from the error context, and
+ * falls back to provider.waitForTransaction().
+ */
+/** @internal */
 async function safeSendTx(contractCall, provider, shouldWait) {
     try {
         const tx = await contractCall();
@@ -112,6 +137,8 @@ async function safeSendTx(contractCall, provider, shouldWait) {
     catch (error) {
         if (!isNonceParsing(error))
             throw error;
+        // The tx was sent but ethers couldn't parse the response.
+        // Try to extract the hash from the error payload.
         const errStr = String(error);
         const hashMatch = errStr.match(/"hash"\s*:\s*"(0x[0-9a-fA-F]{64})"/);
         if (!hashMatch?.[1])
@@ -131,6 +158,15 @@ async function safeSendTx(contractCall, provider, shouldWait) {
         return { tx: null, hash: txHash };
     }
 }
+/**
+ * Shared nonce-recovery helper for catch blocks. When an RPC returns a
+ * malformed nonce and ethers throws, try to extract the tx hash from the
+ * error payload. Optionally waits for confirmation (with status check).
+ *
+ * Returns the recovered hash, or null if this error is not a nonce-parse error
+ * or if no hash could be extracted (caller should re-throw the original error).
+ */
+/** @internal */
 async function tryRecoverTxHash(error, signer, wait) {
     if (!isNonceParsing(error))
         return null;
@@ -205,6 +241,7 @@ async function approveCore(signer, options) {
         const actualDepositAsset = (depositAsset || underlyingAsset);
         const isNativeToken = actualDepositAsset === ethers_1.ZeroAddress ||
             actualDepositAsset === '0x0000000000000000000000000000000000000000';
+        // Native tokens travel as msg.value — no ERC-20 allowance to grant.
         if (isNativeToken)
             return { kind: 'native' };
         const isAdapterDeposit = actualDepositAsset.toLowerCase() !== underlyingAsset.toLowerCase();
@@ -264,13 +301,112 @@ async function approveCore(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `Approval failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount } });
     }
 }
+/**
+ * Approve a vault (or the appropriate adapter wrapper) to spend a token
+ * ahead of a separate deposit call. Spender routing mirrors
+ * {@link vaultDeposit} (multi-asset → vault, adapter → wrapper, standard →
+ * vault). Returns `undefined` when the existing allowance already covers
+ * `amount` **or** when the deposit asset is native.
+ *
+ * @returns Transaction hash when an approval was sent, `undefined` when
+ *   the existing allowance already covers `amount` or the deposit asset is
+ *   native (no ERC-20 allowance applies). Use {@link approve} for a
+ *   discriminated `ApproveResult` if you need to tell those two cases apart.
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultApprove({
+ *   target: '0x...',         // vault contract address
+ *   wallet: walletAddress,
+ *   amount: '100',           // 100 of the deposit token (UI units)
+ *   wait: true,              // wait for the approval to confirm
+ * });
+ * if (hash) console.log('approve tx', hash);
+ * // hash === undefined means the on-chain allowance already covers the
+ * // amount, or the deposit asset is native (msg.value, no allowance).
+ * ```
+ */
 async function vaultApprove(signer, options) {
     const result = await approveCore(signer, options);
     return result.kind === 'sent' ? result.hash : undefined;
 }
+/**
+ * Same approval logic as {@link vaultApprove} but returns a discriminated
+ * union so callers can tell `sent` apart from `sufficient` and `native`
+ * without re-reading on-chain state. Preferred shape for new integrations.
+ *
+ * @example
+ * ```ts
+ * const r = await augustSdk.evm.approve({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '100',
+ *   wait: true,
+ * });
+ * switch (r.kind) {
+ *   case 'sent':
+ *     showToast('Approval submitted', r.hash);
+ *     break;
+ *   case 'sufficient':
+ *     // r.existing is the existing on-chain allowance (raw bigint)
+ *     break;
+ *   case 'native':
+ *     // No allowance needed; native token will travel as msg.value
+ *     break;
+ * }
+ * ```
+ *
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustSDKError when the approval submission fails.
+ */
 async function approve(signer, options) {
     return approveCore(signer, options);
 }
+/**
+ * Deposit underlying token into the specified vault. Auto-routes to the
+ * correct contract path (single-asset ERC-4626, EVM-2 multi-asset,
+ * Paraswap adapter, native-token wrapper, depositWithPermit) based on the
+ * vault version and `depositAsset`.
+ *
+ * Amounts are encoded against the **deposit token's** decimals, not the
+ * vault's share decimals. The SDK reads the appropriate decimals via the
+ * vault metadata and the asset's ERC-20.
+ *
+ * Approval is handled automatically: if the existing allowance doesn't
+ * cover `amount`, an `approve` is sent and **always waited for** (regardless
+ * of the caller's `wait` flag) so the deposit tx can't be re-ordered ahead
+ * of the approval on Monad-style RPCs.
+ *
+ * @param signer ethers Signer / Wallet (or viem WalletClient via {@link setSigner})
+ * @param options Vault address, wallet, amount, optional `depositAsset` for
+ *   adapter routes, optional `wait` to wait for the deposit receipt.
+ * @returns Deposit transaction hash.
+ * @throws AugustValidationError on invalid wallet/target/amount or missing
+ *   adapter config when `depositAsset` differs from the vault underlying.
+ * @throws AugustSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultDeposit({
+ *   target: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32', // vault
+ *   wallet: walletAddress,
+ *   amount: '100',         // 100 USDC (UI units)
+ *   wait: true,            // wait for the deposit receipt
+ * });
+ * ```
+ *
+ * @example Adapter deposit (different deposit asset than the vault's underlying)
+ * ```ts
+ * await augustSdk.evm.vaultDeposit({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '0.5',
+ *   depositAsset: WETH_ADDRESS,   // swap WETH -> vault underlying via the adapter
+ *   chainId: 1,
+ * });
+ * ```
+ */
 async function vaultDeposit(signer, options) {
     const { wallet, target, wait, amount, depositAsset, chainId, poolName } = options;
     const [goodWallet, goodPool] = [
@@ -334,11 +470,13 @@ async function vaultDeposit(signer, options) {
         const swapRouterAddress = wantsSwapRouter && resolvedChainId !== undefined
             ? (0, core_1.getSwapRouterAddress)(resolvedChainId)
             : undefined;
+        // Legacy adapter uses minAmountOut: 0 (MEV-vulnerable); fall-through is unsafe.
         if (wantsSwapRouter && !swapRouterAddress) {
             throw new core_1.AugustValidationError('INVALID_CHAIN', resolvedChainId === undefined
                 ? `vaultDeposit: vault ${target} requires SwapRouter routing but chainId could not be resolved — pass options.chainId or ensure tokenized-vault metadata is loaded`
                 : `vaultDeposit: vault ${target} is registered on SwapRouter but no SwapRouter is deployed for chainId ${resolvedChainId}`, { context: { vault: target, chainId: resolvedChainId } });
         }
+        // SwapRouter has no permit variant; throw rather than silently drop the signature.
         if (wantsSwapRouter && options?.isDepositWithPermit) {
             throw new core_1.AugustValidationError('INVALID_INPUT', `vaultDeposit: isDepositWithPermit is not supported on SwapRouter-routed vaults (${target}). Call vaultDeposit without isDepositWithPermit, or use the legacy vault.deposit path directly.`, { context: { vault: target } });
         }
@@ -403,22 +541,30 @@ async function vaultDeposit(signer, options) {
             }
         }
         let depositTx;
+        // Route to appropriate deposit method
         if (isMultiAssetVault) {
             if (options?.isDepositWithPermit) {
+                // depositWithPermit flow
+                // build structure hash of permit off chain
                 const deadline = (0, utils_1.createDeadline)();
+                //sign the hash with private key of depositor
                 const { v, r, s } = await (0, utils_1.generatePermitSignature)(actualDepositAsset, wallet, await poolContract.getAddress(), normalizedAmt.raw, deadline, signer, tokenizedVault.chain);
+                //actually call depositWithPermit func
                 const { hash: permitHash } = await safeSendTx(() => poolContract
                     .connect(signer)
                     .depositWithPermit(actualDepositAsset, normalizedAmt.raw, wallet, deadline, r, s, v), signer, wait);
                 core_1.Logger.log.info('deposit:tx_hash', permitHash);
                 return permitHash;
             }
+            // Multi-asset vault deposit (EVM-2)
             depositTx = await poolContract
                 .connect(signer)
                 .deposit(actualDepositAsset, normalizedAmt.raw, wallet);
         }
         else if (isAdapterDeposit && adapterConfig) {
+            // Adapter deposit (swap or native wrapper)
             if (adapterConfig.bridgeId === 2) {
+                // Paraswap bridge - build swap and deposit transaction
                 const adapterContract = await (0, adapter_helpers_1.buildSwapAndDepositTransaction)({
                     signer,
                     srcToken: actualDepositAsset,
@@ -436,13 +582,14 @@ async function vaultDeposit(signer, options) {
                     srcToken: actualDepositAsset,
                     dstToken: underlyingAsset,
                     bridgeId: adapterConfig.bridgeId,
-                    quoteData: '0x',
+                    quoteData: '0x', // This will be populated by buildSwapAndDepositTransaction
                 };
                 depositTx = await adapterContract
                     .connect(signer)
                     .swapAndDeposit(swapAndDepositParams);
             }
             else {
+                // Native/wrapped token deposit via wrapper contract
                 const nativeDepositConfig = await (0, adapter_helpers_1.buildNativeDepositTransaction)({
                     signer,
                     srcToken: actualDepositAsset,
@@ -458,12 +605,15 @@ async function vaultDeposit(signer, options) {
             }
         }
         else {
+            // Standard deposit
             if (isNativeToken) {
+                // Native ETH/AVAX deposit
                 depositTx = await poolContract
                     .connect(signer)
                     .deposit(normalizedAmt.raw, wallet, { value: normalizedAmt.raw });
             }
             else {
+                // Standard ERC20 deposit
                 depositTx = await poolContract
                     .connect(signer)
                     .deposit(normalizedAmt.raw, wallet);
@@ -486,6 +636,42 @@ async function vaultDeposit(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `Deposit failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, depositAsset } });
     }
 }
+/**
+ * Request to redeem vault shares. For EVM-1 vaults this queues a standard
+ * redemption (claimable later via `vaultRedeem`); for EVM-2 vaults this
+ * also handles the receipt-token allowance automatically. Pass
+ * `isInstantRedeem: true` for vaults that support instant settlement.
+ *
+ * Approval of the receipt token (EVM-2) is always waited on before the
+ * redeem call, regardless of the caller's `wait` flag.
+ *
+ * @param signer ethers Signer / Wallet (or viem WalletClient via {@link setSigner})
+ * @param options Vault address, wallet, amount, optional `isInstantRedeem`,
+ *   optional `wait` to wait for the redeem receipt.
+ * @returns Redeem transaction hash.
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',           // 10 shares (UI units)
+ *   wait: true,
+ * });
+ * ```
+ *
+ * @example Instant redemption
+ * ```ts
+ * await augustSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   isInstantRedeem: true,
+ * });
+ * ```
+ */
 async function vaultRequestRedeem(signer, options) {
     const { wallet, target, wait, amount } = options;
     const [goodWallet, goodPool] = [
@@ -500,16 +686,21 @@ async function vaultRequestRedeem(signer, options) {
     }
     validateAmountPrecision(amount);
     try {
+        // Get vault version to determine correct ABI
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target))?.[0];
         const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
         let poolContract;
         let decimals;
+        // Handle different vault versions
         if (vaultVersion === 'evm-2') {
+            // For evm-2, always use ABI_TOKENIZED_VAULT_V2 to get lpTokenAddress
+            // even for instant redeem, we need lpTokenAddress for receipt token decimals
             const vaultContract = (0, core_1.createContract)({
                 address: target,
                 provider: signer,
                 abi: abis_1.ABI_TOKENIZED_VAULT_V2,
             });
+            // Get receipt token for decimals
             const receiptTokenAddr = (await vaultContract.lpTokenAddress());
             const receiptContract = (0, core_1.createContract)({
                 address: receiptTokenAddr,
@@ -517,13 +708,19 @@ async function vaultRequestRedeem(signer, options) {
                 abi: abis_1.ABI_ERC20,
             });
             decimals = Number(await receiptContract.decimals());
+            // Convert amount to bignumber
             const normalizedAmt = (0, core_1.toNormalizedBn)(amount, decimals);
+            // EVM-2 lp/receipt token is a separate ERC-20: vault.transferFrom(lp)
+            // needs explicit allowance even on self-redeem (msg.sender on the lp
+            // token is the vault, not the user — no ERC-4626 owner-shortcut).
             const allowance = await receiptContract.allowance(wallet, target);
             if (safeBigInt(allowance, 'vaultRequestRedeem:allowance') <
                 BigInt(normalizedAmt.raw)) {
                 const { hash: approveHash } = await safeSendTx(() => receiptContract.connect(signer).approve(target, normalizedAmt.raw), signer, true);
                 core_1.Logger.log.info('approve:receipt_token:tx_hash', approveHash);
             }
+            // For evm-2, use vaultContract for both instant and standard redeem
+            // ABI_TOKENIZED_VAULT_V2 has both instantRedeem (2 params) and requestRedeem
             poolContract = vaultContract;
         }
         else {
@@ -540,26 +737,32 @@ async function vaultRequestRedeem(signer, options) {
                 });
             decimals = await poolContract.decimals();
         }
+        // Convert amount to bignumber (for non-evm-2 vaults)
         const normalizedAmt = (0, core_1.toNormalizedBn)(amount, decimals);
+        // Withdraw from vault - EVM-2 uses 2 params, others use 3 params
         let requestRedeemTx;
         if (options.isInstantRedeem) {
             if (vaultVersion === 'evm-2') {
+                // EVM-2: instantRedeem(uint256 shares, address receiverAddr) - 2 params
                 requestRedeemTx = await poolContract
                     .connect(signer)
                     .instantRedeem(BigInt(normalizedAmt.raw), wallet);
             }
             else {
+                // EVM-0/EVM-1: instantRedeem(uint256 shares, address receiverAddr, address holderAddr) - 3 params
                 requestRedeemTx = await poolContract
                     .connect(signer)
                     .instantRedeem(BigInt(normalizedAmt.raw), wallet, wallet);
             }
         }
         else if (vaultVersion === 'evm-2') {
+            // EVM-2: requestRedeem(uint256 shares, address receiverAddr)
             requestRedeemTx = await poolContract
                 .connect(signer)
                 .requestRedeem(BigInt(normalizedAmt.raw), wallet);
         }
         else {
+            // EVM-0/EVM-1: requestRedeem(uint256 shares, address receiver, address owner)
             requestRedeemTx = await poolContract
                 .connect(signer)
                 .requestRedeem(BigInt(normalizedAmt.raw), wallet, wallet);
@@ -581,6 +784,13 @@ async function vaultRequestRedeem(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `Request redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount } });
     }
 }
+/**
+ * @TODO
+ * @description withdraw funds from the specified pool including accrued rewards
+ * @param signer signer / wallet object
+ * @param options object including pool contract address, user wallet address, and more
+ * @returns claim tx hash
+ */
 async function vaultRedeem(signer, options) {
     const { wallet, target, wait, year, day, month, receiverIndex } = options;
     const [goodWallet, goodPool] = [
@@ -617,6 +827,34 @@ async function vaultRedeem(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `Redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, year, month, day, receiverIndex } });
     }
 }
+/**
+ * Deposit a native token (ETH / AVAX / etc.) into a vault via the
+ * `MultiAssetNativeDepositWrapper`. The wrapper forwards `msg.value` to
+ * the vault as the deposit underlying — no allowance is required.
+ *
+ * `amount` is the **raw on-chain value in wei-equivalent** (18 decimals
+ * for ETH-family natives). If you have a UI-shaped amount in ether, scale
+ * it first.
+ *
+ * @param signer ethers Signer / Wallet
+ * @param options `wrapperAddress` is the deployed wrapper contract;
+ *   `receiver` defaults to the signer's address; `amount` is the native
+ *   amount in wei; `wait` waits for the deposit receipt.
+ * @returns Deposit transaction hash.
+ * @throws AugustValidationError on invalid wrapper / receiver / amount.
+ * @throws AugustSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * import { parseEther } from 'ethers';
+ *
+ * await augustSdk.evm.depositNative({
+ *   wrapperAddress: nativeWrapperAddress,
+ *   amount: parseEther('0.5'),   // 0.5 ETH in wei
+ *   wait: true,
+ * });
+ * ```
+ */
 async function depositNative(signer, options) {
     const { wrapperAddress, receiver, amount, wait } = options;
     const goodWrapper = (0, core_1.checkAddress)(wrapperAddress, console, 'contract');
@@ -628,29 +866,36 @@ async function depositNative(signer, options) {
     }
     validateAmountPrecision(amount);
     try {
+        // Create wrapper contract instance
         const wrapperContract = (0, core_1.createContract)({
             address: wrapperAddress,
             provider: signer,
             abi: abis_1.ABI_MULTI_ASSET_NATIVE_DEPOSIT_WRAPPER,
-        });
+        }); // TODO: provide typed interface
+        // Convert amount to bigint (native tokens use 18 decimals typically)
+        // For native deposits, amount should be in wei/smallest unit
         const amountBigInt = typeof amount === 'bigint'
             ? amount
             : typeof amount === 'string'
                 ? BigInt(amount)
                 : BigInt(amount);
         let depositTx;
+        // Connect the contract first, then get the function to disambiguate between overloads
         const connectedContract = wrapperContract.connect(signer);
+        // Call depositNative with or without receiver parameter
         if (receiver) {
             const goodReceiver = (0, core_1.checkAddress)(receiver, console, 'wallet');
             if (!goodReceiver) {
                 throw new core_1.AugustValidationError('INVALID_ADDRESS', 'depositNative: invalid receiver address');
             }
+            // depositNative(address receiver) - with receiver
             const depositNativeWithReceiver = connectedContract.getFunction('depositNative(address)');
             depositTx = await depositNativeWithReceiver(receiver, {
                 value: amountBigInt,
             });
         }
         else {
+            // depositNative() - without receiver (uses msg.sender as receiver)
             const depositNativeNoParams = connectedContract.getFunction('depositNative()');
             depositTx = await depositNativeNoParams({
                 value: amountBigInt,
@@ -673,6 +918,41 @@ async function depositNative(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `Deposit native failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { wrapperAddress, receiver, amount } });
     }
 }
+/**
+ * Redeem vault shares for an underlying asset via the RwaRedeemSubaccount.
+ * Caller must approve the **vault share token** (not the output asset) to
+ * the subaccount beforehand — it pulls shares via `transferFrom`.
+ *
+ * Pass `minOut` to enforce slippage protection (in `outputDecimals` units).
+ * The SDK does not currently compute `minOut` from a slippage percentage —
+ * the caller is responsible for choosing a safe lower bound.
+ *
+ * @throws AugustValidationError on invalid addresses or amount inputs.
+ * @throws AugustSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * // 1. Approve the vault share token to the subaccount first.
+ * await augustSdk.evm.vaultApprove({
+ *   target: subaccountAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   wait: true,
+ * });
+ *
+ * // 2. Redeem 10 shares for USDC, requiring at least 9.5 USDC out.
+ * await augustSdk.evm.rwaRedeemAsset({
+ *   target: subaccountAddress,
+ *   wallet: walletAddress,
+ *   asset: USDC_ADDRESS,
+ *   amount: '10',
+ *   minOut: '9.5',
+ *   decimals: 18,            // vault share decimals
+ *   outputDecimals: 6,       // USDC decimals
+ *   wait: true,
+ * });
+ * ```
+ */
 async function rwaRedeemAsset(signer, options) {
     const { target, wallet, asset, amount, minOut, decimals, outputDecimals, wait, } = options;
     const goodTarget = (0, core_1.checkAddress)(target, console, 'contract');
@@ -712,10 +992,12 @@ async function rwaRedeemAsset(signer, options) {
         throw new core_1.AugustSDKError('UNKNOWN', `RWA redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, asset, amount, minOut } });
     }
 }
+/** @internal */
 async function dispatchViaSwapRouter(args) {
     const amountRaw = BigInt(args.normalizedAmt.raw);
     const sharesReceiver = args.receiver ?? args.wallet;
     if (args.isNativeToken) {
+        // SwapRouter native path requires underlying === wrapped native.
         const wrappedNative = core_1.SWAP_ROUTER_WRAPPED_NATIVE[args.chainId];
         if (!wrappedNative ||
             args.underlyingAsset.toLowerCase() !== wrappedNative.toLowerCase()) {
@@ -748,6 +1030,10 @@ async function dispatchViaSwapRouter(args) {
             wait: args.wait,
         });
     }
+    // Vault share decimals can diverge from the underlying asset decimals
+    // (e.g. an 18-decimal share token over an 8-decimal WBTC underlying on
+    // a multi-asset v2 vault). The swap quote must use the underlying's
+    // on-chain decimals so Paraswap's /prices interprets the route correctly.
     const underlyingErc20 = (0, core_1.createContract)({
         address: args.underlyingAsset,
         provider: args.signer,
@@ -781,6 +1067,7 @@ async function dispatchViaSwapRouter(args) {
         wait: args.wait,
     });
 }
+/** @internal */
 function resolveSwapRouterOrThrow(chainId) {
     const router = (0, core_1.getSwapRouterAddress)(chainId);
     if (!router) {
@@ -788,6 +1075,7 @@ function resolveSwapRouterOrThrow(chainId) {
     }
     return router;
 }
+/** @internal */
 async function ensureAllowance(signer, token, owner, spender, amount) {
     const tokenContract = (0, core_1.createContract)({
         address: token,
@@ -800,6 +1088,7 @@ async function ensureAllowance(signer, token, owner, spender, amount) {
     const { hash } = await safeSendTx(() => tokenContract.connect(signer).approve(spender, amount), signer, true);
     core_1.Logger.log.info('swapRouter:approve:tx_hash', hash);
 }
+/** @internal */
 function ensureSwapsValid(swaps) {
     if (swaps.length === 0) {
         throw new core_1.AugustValidationError('INVALID_INPUT', 'swapAndDeposit: at least one swap leg is required');
@@ -811,6 +1100,7 @@ function ensureSwapsValid(swaps) {
         validateSwapParams(swaps[i], i);
     }
 }
+/** @internal */
 function validateSwapParams(swap, index) {
     const where = `swapAndDeposit: swaps[${index}]`;
     if (!(0, core_1.checkAddress)(swap.tokenIn, console, 'contract')) {
@@ -835,6 +1125,7 @@ function validateSwapParams(swap, index) {
         throw new core_1.AugustValidationError('INVALID_INPUT', `${where}.payload must be ABI-encoded calldata (got "${swap.payload.slice(0, 12)}…")`);
     }
 }
+/** @internal */
 function totalInputPerToken(swaps) {
     const totals = new Map();
     for (const swap of swaps) {
@@ -843,6 +1134,9 @@ function totalInputPerToken(swaps) {
     }
     return totals;
 }
+// Allowance owner must equal msg.sender (contract uses transferFrom(msg.sender, ...));
+// smart-account wallets need explicit handling outside the SDK.
+/** @internal */
 async function resolveSignerEOA(signer, callerContext) {
     const getAddress = signer.getAddress;
     if (typeof getAddress !== 'function') {
@@ -854,6 +1148,47 @@ async function resolveSignerEOA(signer, callerContext) {
     }
     return eoa;
 }
+/**
+ * Swap one or more whitelisted ERC-20s into a vault's reference asset via
+ * the on-chain SwapRouter, then deposit the proceeds into the vault.
+ *
+ * Approval is sent automatically when the caller's allowance on each
+ * `swaps[i].tokenIn` against the SwapRouter is below `amountIn`.
+ *
+ * @param signer - ethers `Signer` or `Wallet` with the EOA that holds the input tokens.
+ * @param options - {@link ISwapAndDepositOptions}.
+ * @returns The transaction hash of the `swapAndDeposit` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, empty/oversized swap arrays.
+ * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
+ *
+ * @example
+ * ```ts
+ * const quote = await fetchSwapQuote({
+ *   chainId: 1,
+ *   srcToken: WBTC,
+ *   srcDecimals: 8,
+ *   destToken: USDC,
+ *   destDecimals: 6,
+ *   amount: 100_000_000n,
+ *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+ * });
+ * const hash = await swapAndDeposit(signer, {
+ *   chainId: 1,
+ *   vault: '0x8AcA0841993ef4C87244d519166e767f49362C21',
+ *   receiver: wallet,
+ *   swaps: [{
+ *     tokenIn: WBTC,
+ *     tokenOut: USDC,
+ *     amountIn: 100_000_000n,
+ *     minAmountOut: quote.minAmountOut,
+ *     router: quote.router,
+ *     payload: quote.payload,
+ *   }],
+ * });
+ * ```
+ */
 async function swapAndDeposit(signer, options) {
     const { chainId, vault, receiver, swaps, originCode, wait } = options;
     const goodVault = (0, core_1.checkAddress)(vault, console, 'contract');
@@ -878,6 +1213,18 @@ async function swapAndDeposit(signer, options) {
     core_1.Logger.log.info('swapAndDeposit:tx_hash', hash);
     return hash;
 }
+/**
+ * Deposit a vault's reference asset directly through the SwapRouter — no
+ * swap. Useful when the caller already holds the reference asset but wants
+ * the origin/referral fee accounting that only the SwapRouter path provides.
+ *
+ * @param signer - ethers `Signer` or `Wallet`.
+ * @param options - {@link ISwapRouterDirectDepositOptions}.
+ * @returns The transaction hash of the `deposit` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, or zero amount.
+ */
 async function depositViaSwapRouter(signer, options) {
     const { chainId, vault, receiver, asset, amount, originCode, wait } = options;
     const goodVault = (0, core_1.checkAddress)(vault, console, 'contract');
@@ -903,6 +1250,21 @@ async function depositViaSwapRouter(signer, options) {
     core_1.Logger.log.info('depositViaSwapRouter:tx_hash', hash);
     return hash;
 }
+/**
+ * Deposit native ETH (or chain-native equivalent) into a vault via the
+ * SwapRouter. The router wraps `amount` to the chain's wrapped-native token
+ * before depositing — only valid when the vault's reference asset equals
+ * the wrapped-native token.
+ *
+ * No ERC-20 approval is needed; `amount` travels as `msg.value`.
+ *
+ * @param signer - ethers `Signer` or `Wallet`.
+ * @param options - {@link ISwapRouterNativeDepositOptions}.
+ * @returns The transaction hash of the `depositNativeToken` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, or zero amount.
+ */
 async function depositNativeViaSwapRouter(signer, options) {
     const { chainId, vault, receiver, amount, originCode, wait } = options;
     const goodVault = (0, core_1.checkAddress)(vault, console, 'contract');