@augustdigital/sdk 8.3.2 → 8.6.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 * 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;
         }
@@ -429,8 +463,85 @@ async function getSubgraphAllWithdrawals(pool, provider, slackWebookUrl = slack_
         };
     }
 }
+/**
+ * Fetch a user's deposit/withdraw history for an archived vault from the backend
+ * Mongo snapshot (`/upshift/vault_history`) instead of its retired subgraph.
+ *
+ * Returns the same {@link ISubgraphUserHistoryItem} shape as the subgraph path,
+ * so the caller's downstream transform/normalization is unchanged. `amount` is
+ * the raw deposited-asset amount (base units); `decimals` is attached so the
+ * caller can normalize, mirroring the subgraph path.
+ *
+ * Pre-deposit vaults accept multiple deposit assets with differing decimals
+ * (e.g. USDS at 18, USDC at 6). When the backend supplies `asset_address` per
+ * row, it is propagated as {@link ISubgraphUserHistoryItem.assetIn} (and, when
+ * present, `asset_decimals` is used for that row's `decimals`) so lifetime PnL
+ * resolves each deposit against its own token rather than the vault decimals —
+ * without it, an 18-decimal deposit normalized at the vault's 6 decimals
+ * inflates the cost basis by ~1e12. This mirrors the subgraph path, whose
+ * deposit rows already carry `assetIn`.
+ *
+ * Side effects: one RPC read (`getDecimals`) and one HTTP GET to the public API.
+ *
+ * @param user - The wallet whose history to fetch.
+ * @param provider - Contract runner, used to read the vault's decimals.
+ * @param pool - The (archived) vault contract address.
+ * @returns The user's deposits and settled withdrawals. Empty on a non-200
+ *   response.
+ */
+async function getArchivedVaultUserHistory(user, provider, pool) {
+    const decimals = await (0, core_1.getDecimals)(provider, pool);
+    const response = await (0, core_1.fetchAugustPublic)(core_1.WEBSERVER_ENDPOINTS.public.tokenizedVault.userHistory(pool, user));
+    if (response.status !== 200) {
+        core_1.Logger.log.error('getArchivedVaultUserHistory', `non-200 from vault_history for ${pool}: ${response.status}`);
+        return [];
+    }
+    const rows = (await response.json());
+    // The backend already stores final ISubgraphUserHistoryItem.type values, so
+    // no translation is needed. Two row-level guards before mapping, since both
+    // bad shapes propagate destructively downstream:
+    //   - amount_raw must be a non-negative integer: the caller does
+    //     BigInt(amount) outside a try/catch, and one bad row would throw and
+    //     wipe the user's entire (all-vault) history.
+    //   - timestamp must parse to a real time: a malformed value makes getTime()
+    //     return NaN, which stringifies to "NaN" and then sorts/normalizes
+    //     incorrectly downstream. Drop the row rather than emit a "NaN" stamp.
+    return (rows
+        .filter((row) => /^\d+$/.test(row.amount_raw) &&
+        !Number.isNaN(new Date(row.timestamp).getTime()))
+        .map((row) => ({
+        id: row.transaction_hash,
+        contractId_: pool,
+        timestamp_: String(Math.floor(new Date(row.timestamp).getTime() / 1000)),
+        transactionHash_: row.transaction_hash,
+        block_number: row.block_number != null ? String(row.block_number) : '0',
+        address: row.wallet,
+        amount: row.amount_raw,
+        type: row.type,
+        // Per-asset decimals when known, else the vault's. PnL re-resolves
+        // decimals from `assetIn` anyway; this keeps display/normalization
+        // correct for any consumer that reads the row's `decimals` directly.
+        decimals: row.asset_decimals ?? decimals,
+        // Carry the deposit asset through so mixed-decimal deposits normalize
+        // against their own token, not the vault's. Omitted when unknown.
+        ...(row.asset_address ? { assetIn: row.asset_address } : {}),
+    }))
+        // Match the subgraph path's ordering contract: sortUserHistory sorts
+        // ascending by unix timestamp_, and downstream consumers rely on that
+        // chronology. The backend returns rows in arbitrary order, so re-sort here.
+        .sort((a, b) => Number(a.timestamp_) - Number(b.timestamp_)));
+}
 async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     try {
+        // Archived vaults: serve history from the backend Mongo snapshot instead of
+        // the (retired) subgraph. The archived set is fetched from the backend (the
+        // routing source of truth) so a vault is only rerouted once its history is
+        // backfilled. Same return shape keeps downstream unchanged.
+        const archivedVaults = await (0, fetcher_2.fetchArchivedVaults)();
+        if (archivedVaults.has(pool.toLowerCase())) {
+            return await getArchivedVaultUserHistory(user, provider, pool);
+        }
+        // setup
         const chainId = await (0, core_1.getChainId)(provider);
         const requests = [];
         let vaultSymbol = await (0, core_1.getVaultSymbol)(pool, provider);
@@ -444,6 +555,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 +653,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 +665,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 +676,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 +756,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 +769,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 +785,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 +812,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,105 @@
+/** @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;
+    /**
+     * Optional aggregator contract-method filter. When set, the aggregator is
+     * constrained to this single method (ParaSwap's `/prices`
+     * `includeContractMethods`), so the returned calldata's leading 4-byte
+     * selector is deterministic — required when the on-chain SwapRouter only
+     * authorizes one selector per router. When omitted, the aggregator picks the
+     * optimal method freely and the selector may vary between quotes.
+     */
+    contractMethod?: string;
+    /** 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;
@@ -20,6 +45,7 @@ async function fetchSwapQuote(request) {
         slippageBps,
         partner: request.partner ?? paraswap_1.PARASWAP_DEFAULTS.partner,
         partnerAddress: request.partnerAddress ?? paraswap_1.PARASWAP_DEFAULTS.partnerAddress,
+        contractMethod: request.contractMethod,
         fetchImpl,
         signal: request.signal,
     });
@@ -35,7 +61,7 @@ async function fetchSwapQuote(request) {
 }
 function validateRequest(req) {
     if (req.slippageBps !== undefined &&
-        (req.slippageBps < 0 || req.slippageBps >= 10000)) {
+        (req.slippageBps < 0 || req.slippageBps >= 10_000)) {
         throw new errors_1.AugustValidationError('INVALID_INPUT', `fetchSwapQuote: slippageBps must be in [0, 10000), got ${req.slippageBps}. 10000 bps = 100% slippage and disables protection entirely; use a tighter bound.`);
     }
     if (req.amount === 0n) {