@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/services/octavfi/utils.js

@@ -2,6 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformOctavfiToDebank = transformOctavfiToDebank;
 exports.transformOctavfiPortfoliosToDebank = transformOctavfiPortfoliosToDebank;
+/**
+ * Transforms Octavfi portfolio response to DeBank-compatible format.
+ * This allows Solana addresses to use Octavfi data while maintaining
+ * compatibility with existing DeBank parsing functions.
+ *
+ * @param octavfiPortfolio - Octavfi portfolio response
+ * @returns DeBank-compatible response structure
+ */
 function transformOctavfiToDebank(octavfiPortfolio) {
     if (!octavfiPortfolio) {
         return {
@@ -13,20 +21,25 @@ function transformOctavfiToDebank(octavfiPortfolio) {
     }
     const positions = [];
     const tokens = [];
+    // Transform protocols (assetByProtocols) into DeBank positions format
     const assetByProtocols = octavfiPortfolio.assetByProtocols || {};
     Object.entries(assetByProtocols).forEach(([protocolKey, protocol]) => {
+        // Skip wallet protocol - we'll handle it separately in tokens
         if (protocolKey === 'wallet') {
             return;
         }
+        // Extract all assets from nested structure: chains -> protocolPositions -> assets
         const allAssets = [];
         if (protocol.chains) {
             Object.values(protocol.chains).forEach((chain) => {
                 if (chain.protocolPositions) {
                     Object.values(chain.protocolPositions).forEach((protocolPosition) => {
+                        // Direct assets
                         if (protocolPosition.assets &&
                             Array.isArray(protocolPosition.assets)) {
                             allAssets.push(...protocolPosition.assets);
                         }
+                        // Nested protocolPositions (like in Kamino)
                         if (protocolPosition.protocolPositions &&
                             Array.isArray(protocolPosition.protocolPositions)) {
                             protocolPosition.protocolPositions.forEach((nestedPos) => {
@@ -39,33 +52,36 @@ function transformOctavfiToDebank(octavfiPortfolio) {
                 }
             });
         }
+        // Create position structure matching DeBank format
         const position = {
             id: protocolKey,
             chain: getChainFromProtocol(protocol, octavfiPortfolio),
             name: protocol.name || protocolKey,
-            logo_url: '',
-            site_url: '',
+            logo_url: '', // Octavfi doesn't provide protocol logos
+            site_url: '', // Octavfi doesn't provide protocol URLs
             portfolio_item_list: [
                 {
                     name: protocol.name || protocolKey,
                     stats: {
                         asset_usd_value: parseFloat(protocol.value || '0') || 0,
-                        debt_usd_value: 0,
+                        debt_usd_value: 0, // Octavfi doesn't distinguish debt, default to 0
                         net_usd_value: parseFloat(protocol.value || '0') || 0,
                     },
                     detail: {
                         supply_token_list: allAssets
                             .map((asset) => transformAssetToDebankToken(asset, 'supply'))
                             .filter((token) => token !== null),
-                        borrow_token_list: [],
+                        borrow_token_list: [], // Octavfi doesn't provide borrow data
                     },
                 },
             ],
         };
         positions.push(position);
     });
+    // Transform wallet assets to tokens array
     const walletProtocol = assetByProtocols['wallet'];
     if (walletProtocol && walletProtocol.chains) {
+        // Extract assets from nested structure: chains -> protocolPositions -> assets
         Object.values(walletProtocol.chains).forEach((chain) => {
             if (chain.protocolPositions) {
                 Object.values(chain.protocolPositions).forEach((protocolPosition) => {
@@ -75,7 +91,7 @@ function transformOctavfiToDebank(octavfiPortfolio) {
                             tokens.push({
                                 ...transformAssetToDebankToken(asset, 'wallet'),
                                 is_wallet: true,
-                                is_core: true,
+                                is_core: true, // Assume wallet tokens are core tokens
                             });
                         });
                     }
@@ -83,28 +99,33 @@ function transformOctavfiToDebank(octavfiPortfolio) {
             }
         });
     }
+    // Also add protocol assets as tokens (non-wallet)
     Object.entries(assetByProtocols).forEach(([protocolKey, protocol]) => {
         if (protocolKey === 'wallet')
             return;
         if (!protocol || !protocol.chains)
             return;
+        // Extract assets from nested structure
         Object.values(protocol.chains).forEach((chain) => {
             if (chain.protocolPositions) {
                 Object.values(chain.protocolPositions).forEach((protocolPosition) => {
+                    // Direct assets
                     if (protocolPosition.assets &&
                         Array.isArray(protocolPosition.assets)) {
                         protocolPosition.assets.forEach((asset) => {
+                            // Check if token already exists (from wallet)
                             const existingToken = tokens.find((t) => t.symbol === asset.symbol &&
                                 t.chain === (asset.chainKey || asset.chain));
                             if (!existingToken) {
                                 tokens.push({
                                     ...transformAssetToDebankToken(asset, 'supply'),
                                     is_wallet: false,
-                                    is_core: true,
+                                    is_core: true, // Assume protocol tokens are core
                                 });
                             }
                         });
                     }
+                    // Nested protocolPositions (like in Kamino)
                     if (protocolPosition.protocolPositions &&
                         Array.isArray(protocolPosition.protocolPositions)) {
                         protocolPosition.protocolPositions.forEach((nestedPos) => {
@@ -134,7 +155,11 @@ function transformOctavfiToDebank(octavfiPortfolio) {
         },
     };
 }
-function transformAssetToDebankToken(asset, exposureType) {
+/**
+ * Transforms Octavfi asset to DeBank token format
+ */
+function transformAssetToDebankToken(asset, // Using any since the actual structure differs from IOctavfiAsset
+exposureType) {
     if (!asset) {
         return null;
     }
@@ -145,26 +170,31 @@ function transformAssetToDebankToken(asset, exposureType) {
     const contract = asset.contract || asset.chainContract || asset.contractAddress;
     const decimals = parseInt(asset.decimal || asset.decimals || '18', 10);
     return {
-        id: contract || asset.symbol || 'unknown',
+        id: contract || asset.symbol || 'unknown', // Use contract address if available, fallback to symbol
         chain: chain,
         name: asset.name || asset.symbol || 'Unknown',
         symbol: asset.symbol || 'UNKNOWN',
         optimized_symbol: asset.symbol || 'UNKNOWN',
         decimals: decimals,
-        logo_url: '',
+        logo_url: '', // Octavfi doesn't provide token logos
         amount,
         price,
-        protocol_id: '',
+        protocol_id: '', // Will be set by the calling context
         supplying_exposure: exposureType === 'supply' ? 'true' : undefined,
     };
 }
+/**
+ * Determines the chain from protocol data or portfolio chains
+ */
 function getChainFromProtocol(protocol, portfolio) {
+    // Try to get chain from protocol.chains structure
     if (protocol.chains) {
         const chainKeys = Object.keys(protocol.chains);
         if (chainKeys.length > 0) {
             return chainKeys[0];
         }
     }
+    // Fallback to first chain in portfolio
     const chains = portfolio.chains || {};
     const chainKeys = Object.keys(chains);
     if (chainKeys.length > 0) {
@@ -172,6 +202,10 @@ function getChainFromProtocol(protocol, portfolio) {
     }
     return 'unknown';
 }
+/**
+ * Transforms multiple Octavfi portfolios to DeBank format.
+ * Used when fetching multiple addresses.
+ */
 function transformOctavfiPortfoliosToDebank(portfolios) {
     return portfolios.map(transformOctavfiToDebank);
 }

package/lib/services/subgraph/fetcher.js

@@ -14,7 +14,7 @@ async function fetchSubgraphWithRetry(graphUrl, query, apiKey, maxRetries = 3, b
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), core_1.REQUEST_TIMEOUT_MS / 3);
+            const timeoutId = setTimeout(() => controller.abort(), core_1.REQUEST_TIMEOUT_MS / 3); // 30 second timeout
             try {
                 const headers = {
                     'Content-Type': 'application/json',
@@ -40,17 +40,19 @@ async function fetchSubgraphWithRetry(graphUrl, query, apiKey, maxRetries = 3, b
         }
         catch (error) {
             lastError = error;
+            // If it's a timeout error, abort error, or network error and we have retries left
             if (attempt < maxRetries &&
                 ((error instanceof TypeError &&
                     error.message.includes('fetch failed')) ||
                     error.name === 'AbortError' ||
                     error.message.includes('ETIMEDOUT') ||
                     error.message.includes('timeout'))) {
-                const delay = baseDelay * Math.pow(2, attempt);
+                const delay = baseDelay * Math.pow(2, attempt); // Exponential backoff
                 core_1.Logger.log.warn(`fetchSubgraph`, `${graphUrl?.includes('/subgraphs') ? graphUrl?.split('/subgraphs/')?.[1]?.split('/')?.[0] : graphUrl}: Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
                 await new Promise((resolve) => setTimeout(resolve, delay));
                 continue;
             }
+            // If it's not a retryable error or we're out of retries, throw
             throw error;
         }
     }

package/lib/services/subgraph/vaults.d.ts

@@ -1,7 +1,19 @@
 import type { IAddress, IContractRunner, ISubgraphTransfer, ISubgraphUserHistoryItem, ISubgraphWithdrawProccessed, ISubgraphWithdrawRequest } from '../../types';
 export declare function isOldSubgraphSchema(vaultSymbol: string): boolean;
+/**
+ *
+ * @param pool
+ * @param provider
+ * @returns
+ */
 export declare function getSubgraphWithdrawRequests(pool: IAddress, provider: IContractRunner, slackWebookUrl?: string): Promise<ISubgraphWithdrawRequest[]>;
 export declare function getSubgraphWithdrawProccessed(pool: IAddress, provider: IContractRunner, slackWebookUrl?: string): Promise<ISubgraphWithdrawProccessed[]>;
+/**
+ *
+ * @param pool
+ * @param provider
+ * @returns
+ */
 export declare function getSubgraphAllWithdrawals(pool: IAddress, provider: IContractRunner, slackWebookUrl?: string): Promise<{
     withdrawalRequesteds: ISubgraphWithdrawRequest[];
     withdrawalProcesseds: ISubgraphWithdrawProccessed[];

package/lib/services/subgraph/vaults.js

@@ -11,11 +11,20 @@ const slack_1 = require("../../core/logger/slack");
 const fetcher_1 = require("./fetcher");
 const core_1 = require("../../core");
 const fetcher_2 = require("../../modules/vaults/fetcher");
+/**
+ * Utils
+ */
 const GOLDSKY_API_KEY = 'cmd0lz6qf35lg01ty7u20aijy';
+/**
+ * earnAUSD exists on both Ethereum and Monad, so it needs a _monad suffix
+ * to distinguish its Monad subgraph from the Ethereum one.
+ * Other Monad-native vaults (sausd, supermon, etc.) don't need this.
+ */
 function needsMonadSuffix(chainId, symbol) {
     return chainId === 143 && symbol.toLowerCase() === 'earnausd';
 }
 function transformUserHistory(data, chainId, decimals, poolAddress) {
+    //ok to return dupes even though withdraws will return dupe because we parse out duplicate txn hash on the FE
     return [
         ...(data.withdraws?.map((item) => ({
             ...item,
@@ -69,6 +78,7 @@ function sortUserHistory(data, chainId, decimals, poolAddress) {
         return [];
     return transformUserHistory(data, chainId, decimals, poolAddress).sort((a, b) => Number(a.timestamp_) - Number(b.timestamp_));
 }
+// queries
 const WITHDRAWALS_REQUESTED_QUERY_PROPS = `
     id
     day
@@ -155,10 +165,15 @@ const EVM_V2_DEPOSIT_QUERY_PROPS = `
     senderAddr
     receiverAddr
   `;
+// New deployment process uses a different subgraph schema (no trailing underscores).
+// Vaults in SUBGRAPH_VAULT_URLS use the old schema; everything else uses the new schema.
+// GraphQL aliases map new-schema fields to what the SDK expects internally.
 function isOldSubgraphSchema(vaultSymbol) {
     return (vaultSymbol?.toLowerCase() in
         core_1.SUBGRAPH_VAULT_URLS);
 }
+// New schema query props (shared across evm-1 and evm-2 — the new subgraph schema
+// normalized field names, so no per-version variants are needed)
 const NEW_DEPOSIT_QUERY_PROPS = `
     id
     assetIn
@@ -196,6 +211,7 @@ const NEW_WITHDRAWALS_QUERY_PROPS = `
     shares
     owner
     `;
+// New schema: transfer query props
 const NEW_TRANSFER_QUERY_PROPS = `
     id
     from
@@ -215,7 +231,14 @@ const TRANSFER_QUERY_PROPS = `
     block_number
     contractId_
   `;
+/**
+ *
+ * @param pool
+ * @param provider
+ * @returns
+ */
 async function getSubgraphWithdrawRequests(pool, provider, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
+    // setup
     let vaultSymbol = await (0, core_1.getVaultSymbol)(pool, provider);
     if (vaultSymbol === undefined) {
         core_1.Logger.log.warn('getSubgraphWithdrawRequests', `cannot find vault symbol for pool: ${pool}`);
@@ -226,6 +249,7 @@ async function getSubgraphWithdrawRequests(pool, provider, slackWebookUrl = slac
     if (needsMonadSuffix(network, vaultSymbol)) {
         vaultSymbol = vaultSymbol.concat('_monad');
     }
+    // sanitize
     if (vaultSymbol === 'testWETHTSA') {
         return [];
     }
@@ -275,6 +299,7 @@ async function getSubgraphWithdrawRequests(pool, provider, slackWebookUrl = slac
 }
 async function getSubgraphWithdrawProccessed(pool, provider, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     try {
+        // setup
         let vaultSymbol = await (0, core_1.getVaultSymbol)(pool, provider);
         if (vaultSymbol === undefined) {
             core_1.Logger.log.warn('getSubgraphWithdrawProccessed', `cannot find vault symbol for pool: ${pool}`);
@@ -286,6 +311,7 @@ async function getSubgraphWithdrawProccessed(pool, provider, slackWebookUrl = sl
             vaultSymbol = vaultSymbol.concat('_monad');
         }
         const noWithdrawalProcessed = vaultSymbol === 'agETH';
+        // sanitize
         if (vaultSymbol === 'testWETHTSA' || noWithdrawalProcessed) {
             return [];
         }
@@ -338,9 +364,16 @@ async function getSubgraphWithdrawProccessed(pool, provider, slackWebookUrl = sl
         return [];
     }
 }
+/**
+ *
+ * @param pool
+ * @param provider
+ * @returns
+ */
 async function getSubgraphAllWithdrawals(pool, provider, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     let query = '';
     try {
+        // setup
         const errorReturnObj = {
             withdrawalRequesteds: [],
             withdrawalProcesseds: [],
@@ -356,6 +389,7 @@ async function getSubgraphAllWithdrawals(pool, provider, slackWebookUrl = slack_
             vaultSymbol = vaultSymbol.concat('_monad');
         }
         const noWithdrawalProcessed = vaultSymbol === 'agETH';
+        // sanitize
         if (vaultSymbol === 'testWETHTSA') {
             return errorReturnObj;
         }
@@ -431,6 +465,7 @@ async function getSubgraphAllWithdrawals(pool, provider, slackWebookUrl = slack_
 }
 async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     try {
+        // setup
         const chainId = await (0, core_1.getChainId)(provider);
         const requests = [];
         let vaultSymbol = await (0, core_1.getVaultSymbol)(pool, provider);
@@ -444,6 +479,7 @@ async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = sla
             vaultSymbol = vaultSymbol.concat('_monad');
         }
         const noWithdrawalProcessed = vaultSymbol === 'agETH';
+        // sanitize
         if (vaultSymbol === 'testWETHTSA') {
             return requests;
         }
@@ -541,6 +577,7 @@ async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = sla
             return requests;
         }
         const json = (await result.json());
+        // Format data
         const decimals = await (0, core_1.getDecimals)(provider, pool);
         const formattedRequests = sortUserHistory(json.data, chainId, decimals, pool);
         return formattedRequests;
@@ -552,6 +589,7 @@ async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = sla
 }
 async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     try {
+        // setup
         const requests = [];
         let vaultSymbol = await (0, core_1.getVaultSymbol)(pool, provider);
         if (vaultSymbol === undefined) {
@@ -562,7 +600,7 @@ async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.
         const network = Number(networkValue.chainId);
         if (needsMonadSuffix(network, vaultSymbol)) {
             vaultSymbol = vaultSymbol.concat('_monad');
-        }
+        } // sanitize
         if (vaultSymbol === 'testWETHTSA') {
             return requests;
         }
@@ -642,6 +680,7 @@ async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.
             return requests;
         }
         const json = (await result.json());
+        // Format data
         const chainId = await (0, core_1.getChainId)(provider);
         const decimals = await (0, core_1.getDecimals)(provider, pool);
         const formattedRequests = sortUserHistory(json.data, chainId, decimals, pool);
@@ -654,6 +693,7 @@ async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.
 }
 async function getSubgraphUserTransfers(user, provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     try {
+        // setup
         let amountOfTransfers = 0;
         let userTransfers = [];
         let hasNoData = false;
@@ -669,7 +709,7 @@ async function getSubgraphUserTransfers(user, provider, pool, slackWebookUrl = s
         const network = Number(networkValue.chainId);
         if (needsMonadSuffix(network, vaultSymbol)) {
             vaultSymbol = vaultSymbol.concat('_monad');
-        }
+        } // sanitize
         if (vaultSymbol === 'testWETHTSA') {
             return userTransfers;
         }
@@ -696,6 +736,7 @@ async function getSubgraphUserTransfers(user, provider, pool, slackWebookUrl = s
             ? TRANSFER_QUERY_PROPS
             : NEW_TRANSFER_QUERY_PROPS;
         do {
+            // get all the transfers, includes redeem requests and deposits, excludes stake and withdraw events
             const where = `
         where: {
           and: [

package/lib/services/swap-quotes/index.d.ts

@@ -1,25 +1,96 @@
+/** @module core/services/swap-quotes */
 import type { IAddress } from '../../types';
+/** Quote-provider discriminant. Will widen as new providers are added. */
 export type ISwapQuoteProvider = 'paraswap';
+/**
+ * Input to {@link fetchSwapQuote}.
+ */
 export interface ISwapQuoteRequest {
+    /** EVM chain ID where the swap will execute. */
     chainId: number;
+    /** ERC-20 the user holds. */
     srcToken: IAddress;
+    /** `srcToken.decimals()`. */
     srcDecimals: number;
+    /** ERC-20 the SwapRouter should produce — typically the vault's `referenceAsset`. */
     destToken: IAddress;
+    /** `destToken.decimals()`. */
     destDecimals: number;
+    /** Input amount in `srcToken`'s smallest unit. */
     amount: bigint;
+    /**
+     * Address that will execute the resulting calldata. For SwapRouter use,
+     * pass the SwapRouter's address — the aggregator's calldata is bound to
+     * this address, so it must hold the tokens at swap time.
+     */
     receiver: IAddress;
+    /**
+     * Slippage tolerance in bps (1 bp = 0.01%). Defaults to 100 (1%). Must be
+     * in `[0, 10_000)` — 10_000 disables protection entirely and is rejected.
+     */
     slippageBps?: number;
+    /** Aggregator partner key. Defaults to `'august'`. */
     partner?: string;
+    /** Aggregator partner-fee receiver. Defaults to the August partner address. */
     partnerAddress?: IAddress;
+    /**
+     * `fetch`-compatible function override. Defaults to `globalThis.fetch`.
+     * Exposed so callers in Node environments lacking a global `fetch` can
+     * inject one, and so tests can mock without touching the global.
+     */
     fetchImpl?: typeof fetch;
+    /** Optional AbortSignal to cancel the in-flight Paraswap requests. */
     signal?: AbortSignal;
 }
+/**
+ * Output of {@link fetchSwapQuote}. The `router` + `payload` pair maps
+ * directly into one entry of an `ISwapParams[]` passed to
+ * `SwapRouter.swapAndDeposit`.
+ *
+ * Modeled as a discriminated union on `provider` so adding 1inch/0x is an
+ * additive change rather than a breaking widening.
+ */
 export type ISwapQuoteResult = {
+    /** Quote provider that produced this calldata. */
     provider: 'paraswap';
+    /** DEX router that will execute the swap (the contract `payload` is calldata for). */
     router: IAddress;
+    /** ABI-encoded calldata for `router`. */
     payload: `0x${string}`;
+    /** Expected output in `destToken` units before slippage. */
     expectedAmountOut: bigint;
+    /** Slippage-adjusted minimum output. Below this the on-chain call reverts. */
     minAmountOut: bigint;
+    /**
+     * Epoch ms when the quote was fetched. Callers that prefetch a quote
+     * before submitting should re-fetch when this is older than ~60s — DEX
+     * pool state moves and a stale `minAmountOut` may have been computed
+     * against a price that no longer holds.
+     */
     fetchedAt: number;
 };
+/**
+ * Fetch a swap quote and the calldata required for the on-chain SwapRouter
+ * to execute it.
+ *
+ * @throws {@link AugustValidationError} on invalid input (slippage out of
+ * range, zero amount, src===dst).
+ * @throws {@link AugustNetworkError} on transport failure.
+ * @throws {@link AugustServerError} on aggregator-side errors.
+ *
+ * @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]!,
+ * });
+ * // quote.router  -> Paraswap augustor
+ * // quote.payload -> calldata
+ * ```
+ */
 export declare function fetchSwapQuote(request: ISwapQuoteRequest): Promise<ISwapQuoteResult>;

package/lib/services/swap-quotes/index.js

@@ -1,10 +1,35 @@
 "use strict";
+/** @module core/services/swap-quotes */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchSwapQuote = fetchSwapQuote;
 const errors_1 = require("../../core/errors");
 const paraswap_1 = require("./paraswap");
 const DEFAULT_SLIPPAGE_BPS = 100;
 const BPS_DENOMINATOR = 10000n;
+/**
+ * Fetch a swap quote and the calldata required for the on-chain SwapRouter
+ * to execute it.
+ *
+ * @throws {@link AugustValidationError} on invalid input (slippage out of
+ * range, zero amount, src===dst).
+ * @throws {@link AugustNetworkError} on transport failure.
+ * @throws {@link AugustServerError} on aggregator-side errors.
+ *
+ * @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]!,
+ * });
+ * // quote.router  -> Paraswap augustor
+ * // quote.payload -> calldata
+ * ```
+ */
 async function fetchSwapQuote(request) {
     validateRequest(request);
     const slippageBps = request.slippageBps ?? DEFAULT_SLIPPAGE_BPS;

package/lib/services/swap-quotes/paraswap.d.ts

@@ -7,6 +7,13 @@ export interface IParaswapQuoteInput {
     destDecimals: number;
     amount: bigint;
     receiver: IAddress;
+    /**
+     * Slippage tolerance in bps (1 bp = 0.01%). Used to derive the
+     * `destAmount` minimum baked into the resulting Paraswap calldata, so the
+     * on-chain DEX leg enforces the same tolerance the SwapRouter does
+     * (otherwise the leg reverts at the aggregator's exact-out check before
+     * the SwapRouter's `minAmountOut` is ever evaluated).
+     */
     slippageBps: number;
     partner: string;
     partnerAddress: IAddress;
@@ -19,6 +26,16 @@ export interface IParaswapQuoteOutput {
     expectedAmountOut: bigint;
     fetchedAt: number;
 }
+/**
+ * Fetch a Paraswap quote and the calldata to execute it on behalf of the
+ * SwapRouter. Throws `AugustNetworkError` on fetch-layer failure and
+ * `AugustServerError` on Paraswap-side error responses or malformed bodies.
+ *
+ * `fetchedAt` is the wall-clock timestamp captured *after* the calldata
+ * response — callers downstream can use it to decide whether the leg is
+ * fresh enough to broadcast (DEX pool state moves; stale calldata may
+ * silently revert at the on-chain slippage check).
+ */
 export declare function fetchParaswapQuote(input: IParaswapQuoteInput): Promise<IParaswapQuoteOutput>;
 export declare const PARASWAP_DEFAULTS: {
     readonly partner: "august";

package/lib/services/swap-quotes/paraswap.js

@@ -10,6 +10,16 @@ const DEFAULT_PARTNER = 'august';
 const DEFAULT_PARTNER_ADDRESS = '0xb60ee0FA5B6bA917255A03e744967E0Bda531dD0';
 const PARASWAP_VERSION = '6.2';
 const BPS_DENOMINATOR = 10000n;
+/**
+ * Fetch a Paraswap quote and the calldata to execute it on behalf of the
+ * SwapRouter. Throws `AugustNetworkError` on fetch-layer failure and
+ * `AugustServerError` on Paraswap-side error responses or malformed bodies.
+ *
+ * `fetchedAt` is the wall-clock timestamp captured *after* the calldata
+ * response — callers downstream can use it to decide whether the leg is
+ * fresh enough to broadcast (DEX pool state moves; stale calldata may
+ * silently revert at the on-chain slippage check).
+ */
 async function fetchParaswapQuote(input) {
     const priceRoute = await getPriceRoute(input);
     const destAmountRaw = priceRoute.destAmount;
@@ -58,6 +68,10 @@ async function getPriceRoute(input) {
 }
 async function getTransactionData(input, priceRoute) {
     const url = `${PARASWAP_TRANSACTIONS_BASE_URL}/${input.chainId}/?ignoreChecks=true&ignoreGasEstimate=true&onlyParams=false`;
+    // Bake slippage into the destAmount Paraswap embeds as the aggregator's
+    // own min-out, so the DEX leg enforces the same lower bound the
+    // SwapRouter will check. Without this the aggregator uses the exact
+    // priceRoute quote (0% tolerance) and reverts on any adverse movement.
     const expectedDestAmount = BigInt(priceRoute.destAmount);
     const minDestAmount = (expectedDestAmount * (BPS_DENOMINATOR - BigInt(input.slippageBps))) /
         BPS_DENOMINATOR;

package/lib/types/pools.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @deprecated
+ */
 import { IAddress, INormalizedNumber } from './web3';
 import { IDebankProtocolExposure, IDebankTokenExposure, ITokenizedVaultStrategist, IWSSubaccountCefi } from './webserver';
 type ILabelValue = {