aftermath-ts-sdk 1.2.63 → 1.2.64-docs.0

package/dist/packages/pools/pool.js

@@ -15,23 +15,51 @@ const caller_1 = require("../../general/utils/caller");
 const _1 = require(".");
 const utils_1 = require("../../general/utils");
 /**
- * Represents a pool object and provides methods for interacting with the pool.
- * @class
+ * The `Pool` class encapsulates all the functionality needed to interact
+ * with a specific AMM pool on the Aftermath platform. It allows you to
+ * calculate trade amounts, deposit/withdraw amounts, fetch transactions,
+ * and retrieve on-chain statistics and event data.
+ *
+ * @example
+ * ```typescript
+ * const afSdk = new Aftermath("MAINNET");
+ * await afSdk.init(); // initialize provider
+ *
+ * const pools = afSdk.Pools();
+ * const pool = await pools.getPool({ objectId: "0x..." });
+ *
+ * const stats = await pool.getStats();
+ * const tradeTx = await pool.getTradeTransaction({
+ *   walletAddress: "0x...",
+ *   coinInType: "0x2::sui::SUI",
+ *   coinInAmount: BigInt(1e9),
+ *   coinOutType: "0x<yourCoin>",
+ *   slippage: 0.01,
+ * });
+ * ```
  */
 class Pool extends caller_1.Caller {
     /**
-     * Creates a new instance of the Pool class.
-     * @constructor
-     * @param {PoolObject} pool - The pool object.
-     * @param {SuiNetwork} [network] - The network to use.
+     * Creates a new instance of the `Pool` class for on-chain interaction.
+     *
+     * @param pool - The fetched `PoolObject` from Aftermath API or on-chain query.
+     * @param config - Optional caller configuration (e.g., network, access token).
+     * @param Provider - An optional `AftermathApi` instance for advanced transaction usage.
      */
     constructor(pool, config, Provider) {
         super(config, `pools/${pool.objectId}`);
         this.pool = pool;
         this.Provider = Provider;
         /**
-         * Retrieves the volume in the last 24 hours for the pool.
-         * @returns A promise that resolves to the volume in the last 24 hours.
+         * Retrieves the 24-hour volume for this specific pool.
+         *
+         * @returns A promise resolving to a number (volume in 24h).
+         *
+         * @example
+         * ```typescript
+         * const vol24h = await pool.getVolume24hrs();
+         * console.log("Pool 24h Volume:", vol24h);
+         * ```
          */
         this.getVolume24hrs = () => __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("volume-24hrs");
@@ -40,28 +68,47 @@ class Pool extends caller_1.Caller {
         //  Calculations
         // =========================================================================
         /**
-         * Calculates the spot price for the pool.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {CoinType} inputs.coinInType - The input coin type.
-         * @param {CoinType} inputs.coinOutType - The output coin type.
-         * @param {boolean} [inputs.withFees] - Whether to include fees in the calculation.
-         * @returns {number} The spot price for the pool.
+         * Calculates the instantaneous spot price for swapping from `coinInType`
+         * to `coinOutType` within this pool. Optionally includes fees in the price.
+         *
+         * @param inputs - Object specifying input coin, output coin, and a boolean for `withFees`.
+         * @returns The numerical spot price (float).
+         *
+         * @example
+         * ```typescript
+         * const price = pool.getSpotPrice({
+         *   coinInType: "0x<coinA>",
+         *   coinOutType: "0x<coinB>",
+         *   withFees: true,
+         * });
+         * console.log("Spot Price:", price);
+         * ```
          */
         this.getSpotPrice = (inputs) => {
             const spotPriceWithDecimals = cmmmCalculations_1.CmmmCalculations.calcSpotPriceWithFees(utils_1.Helpers.deepCopy(this.pool), inputs.coinInType, inputs.coinOutType, !inputs.withFees);
+            // Adjust for decimals difference
             return ((spotPriceWithDecimals *
                 Number(this.pool.coins[inputs.coinOutType].decimalsScalar)) /
                 Number(this.pool.coins[inputs.coinInType].decimalsScalar));
         };
         // TODO: account for referral discount for all calculations
         /**
-         * Calculates the output amount for a trade.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {CoinType} inputs.coinInType - The input coin type.
-         * @param {Balance} inputs.coinInAmount - The input coin amount.
-         * @param {CoinType} inputs.coinOutType - The output coin type.
-         * @param {boolean} [inputs.referral] - Whether the trade includes a referral.
-         * @returns {Balance} The output amount for the trade.
+         * Calculates how much output coin you would receive when trading
+         * a given input coin and amount in this pool, factoring in protocol
+         * and optional DAO fees.
+         *
+         * @param inputs - Includes `coinInType`, `coinInAmount`, and `coinOutType`.
+         * @returns A bigint representing how many output coins you'd get.
+         * @throws Error if the trade amount is too large relative to the pool balance.
+         *
+         * @example
+         * ```typescript
+         * const amountOut = pool.getTradeAmountOut({
+         *   coinInType: "0x<coinA>",
+         *   coinInAmount: BigInt(1000000),
+         *   coinOutType: "0x<coinB>",
+         * });
+         * ```
          */
         this.getTradeAmountOut = (inputs) => {
             const pool = utils_1.Helpers.deepCopy(this.pool);
@@ -86,13 +133,21 @@ class Pool extends caller_1.Caller {
             return coinOutAmount;
         };
         /**
-         * Calculates the input amount for a trade.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {CoinType} inputs.coinInType - The input coin type.
-         * @param {Balance} inputs.coinOutAmount - The output coin amount.
-         * @param {CoinType} inputs.coinOutType - The output coin type.
-         * @param {boolean} [inputs.referral] - Whether the trade includes a referral.
-         * @returns {Balance} The input amount for the trade.
+         * Calculates how much input coin is required to obtain a certain output coin amount
+         * from this pool, factoring in fees.
+         *
+         * @param inputs - Includes `coinInType`, desired `coinOutAmount`, and `coinOutType`.
+         * @returns A bigint representing the needed input amount.
+         * @throws Error if the desired output is too large relative to pool balances.
+         *
+         * @example
+         * ```typescript
+         * const amountIn = pool.getTradeAmountIn({
+         *   coinInType: "0x<coinA>",
+         *   coinOutAmount: BigInt(1000000),
+         *   coinOutType: "0x<coinB>"
+         * });
+         * ```
          */
         this.getTradeAmountIn = (inputs) => {
             const pool = utils_1.Helpers.deepCopy(this.pool);
@@ -117,11 +172,19 @@ class Pool extends caller_1.Caller {
             return coinInAmountWithoutFees;
         };
         /**
-         * Calculates the LP amount and ratio for a deposit.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {CoinsToBalance} inputs.amountsIn - The input amounts.
-         * @param {boolean} [inputs.referral] - Whether the deposit includes a referral.
-         * @returns {Object} The LP amount and ratio for the deposit.
+         * Calculates how many LP tokens you receive for providing liquidity
+         * in specific coin amounts. Also returns a ratio for reference.
+         *
+         * @param inputs - Contains the amounts in for each coin in the pool.
+         * @returns An object with `lpAmountOut` and `lpRatio`.
+         *
+         * @example
+         * ```typescript
+         * const depositCalc = pool.getDepositLpAmountOut({
+         *   amountsIn: { "0x<coinA>": BigInt(1000000), "0x<coinB>": BigInt(500000) },
+         * });
+         * console.log(depositCalc.lpAmountOut, depositCalc.lpRatio);
+         * ```
          */
         this.getDepositLpAmountOut = (inputs) => {
             const calcedLpRatio = cmmmCalculations_1.CmmmCalculations.calcDepositFixedAmounts(this.pool, Object.entries(inputs.amountsIn).reduce((acc, [coin, amount]) => (Object.assign(Object.assign({}, acc), { [coin]: this.getAmountWithDAOFee({ amount }) })), {}));
@@ -135,12 +198,20 @@ class Pool extends caller_1.Caller {
             };
         };
         /**
-         * Calculates the output amounts for a withdraw.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {number} inputs.lpRatio - The LP ratio.
-         * @param {CoinsToBalance} inputs.amountsOutDirection - The output amounts.
-         * @param {boolean} [inputs.referral] - Whether the withdraw includes a referral.
-         * @returns {CoinsToBalance} The output amounts for the withdraw.
+         * Calculates how many coins a user will receive when withdrawing a specific ratio or LP amount.
+         * This method is used in multi-coin withdrawals where you specify how much of each coin you want.
+         *
+         * @param inputs - The LP ratio and an object specifying direction amounts for each coin.
+         * @returns A `CoinsToBalance` object with final amounts out, factoring in DAO fees.
+         *
+         * @example
+         * ```typescript
+         * const outAmounts = pool.getWithdrawAmountsOut({
+         *   lpRatio: 0.1,
+         *   amountsOutDirection: { "0x<coinA>": BigInt(500000) },
+         * });
+         * console.log(outAmounts);
+         * ```
          */
         this.getWithdrawAmountsOut = (inputs) => {
             const amountsOut = cmmmCalculations_1.CmmmCalculations.calcWithdrawFlpAmountsOut(this.pool, inputs.amountsOutDirection, inputs.lpRatio);
@@ -149,17 +220,24 @@ class Pool extends caller_1.Caller {
                     inputs.amountsOutDirection[coin] <= BigInt(0))
                     continue;
                 const amountOut = amountsOut[coin];
-                if (amountOut <= BigInt(0))
-                    throw new Error(`amountsOut[${coin}] <= 0 `);
-                if (amountOut / this.pool.coins[coin].balance >=
-                    _1.Pools.constants.bounds.maxWithdrawPercentageOfPoolBalance)
+                if (amountOut <= 0) {
+                    throw new Error(`amountsOut[${coin}] <= 0`);
+                }
+                if (Number(amountOut) / Number(this.pool.coins[coin].balance) >=
+                    _1.Pools.constants.bounds.maxWithdrawPercentageOfPoolBalance) {
                     throw new Error("coinOutAmount / coinOutPoolBalance >= maxWithdrawPercentageOfPoolBalance");
-                amountsOut[coin] = this.getAmountWithDAOFee({
-                    amount: amountOut,
-                });
+                }
+                amountsOut[coin] = this.getAmountWithDAOFee({ amount: amountOut });
             }
             return amountsOut;
         };
+        /**
+         * A simplified multi-coin withdraw approach: calculates all outputs by proportion of the
+         * user's LP share among selected coin types. Useful for approximate or "blind" all-coin out logic.
+         *
+         * @param inputs - Contains the `lpCoinAmountIn` to burn, and which coin types to receive.
+         * @returns A record mapping coin type => final amounts out.
+         */
         this.getWithdrawAmountsOutSimple = (inputs) => {
             const { lpCoinAmountIn, coinTypesOut, referral } = inputs;
             const lpCoinSupply = this.pool.lpCoinSupply;
@@ -198,11 +276,17 @@ class Pool extends caller_1.Caller {
             return amountsOut;
         };
         /**
-         * Calculates the output amounts for an all coin withdraw.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {number} inputs.lpRatio - The LP ratio.
-         * @param {boolean} [inputs.referral] - Whether the withdraw includes a referral.
-         * @returns {CoinsToBalance} The output amounts for the all coin withdraw.
+         * Calculates how many coins you get when withdrawing **all** coin types from the pool,
+         * given a ratio. This is typically used for proportionate withdrawal.
+         *
+         * @param inputs - Includes `lpRatio`, the portion of your LP to burn (0 < ratio < 1).
+         * @returns A record of coin type => amounts out, after factoring in any fees.
+         *
+         * @example
+         * ```typescript
+         * const allOut = pool.getAllCoinWithdrawAmountsOut({ lpRatio: 0.1 });
+         * console.log(allOut); // amounts for each coin
+         * ```
          */
         this.getAllCoinWithdrawAmountsOut = (inputs) => {
             if (inputs.lpRatio >= 1)
@@ -215,39 +299,69 @@ class Pool extends caller_1.Caller {
             return amountsOut;
         };
         /**
-         * Calculates the LP ratio for a multi-coin withdraw.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {bigint} inputs.lpCoinAmountIn - The LP coin amount out.
-         * @returns {number} The LP ratio for the multi-coin withdraw.
+         * For multi-coin withdraw, calculates the ratio of how much LP you are burning
+         * relative to the total supply. e.g. if user burns 100 of 1000 supply => ratio 0.1.
+         *
+         * @param inputs - Contains the `lpCoinAmountIn` to burn.
+         * @returns A float ratio (0 < ratio < 1).
          */
         this.getMultiCoinWithdrawLpRatio = (inputs) => Number(this.pool.lpCoinSupply - inputs.lpCoinAmountIn) /
             Number(this.pool.lpCoinSupply);
         /**
-         * Calculates the LP ratio for an all coin withdraw.
-         * @param {Object} inputs - The inputs for the method.
-         * @param {bigint} inputs.lpCoinAmountIn - The LP coin amount out.
-         * @returns {number} The LP ratio for the all coin withdraw.
+         * For an all-coin withdraw, calculates the ratio of how much LP is burned
+         * relative to total supply. e.g. if user burns 50 of 200 supply => ratio 0.25.
+         *
+         * @param inputs - Contains the `lpCoinAmountIn`.
+         * @returns A float ratio, typically 0 < ratio < 1.
          */
         this.getAllCoinWithdrawLpRatio = (inputs) => Number(inputs.lpCoinAmountIn) / Number(this.pool.lpCoinSupply);
         // =========================================================================
         //  Getters
         // =========================================================================
+        /**
+         * Returns an array of coin types in ascending lexicographic order
+         * for the coins contained in this pool.
+         *
+         * @returns An array of coin type strings.
+         */
         this.coins = () => {
             return Object.keys(this.pool.coins).sort((a, b) => a.localeCompare(b));
         };
+        /**
+         * Returns an array of `PoolCoin` objects, one for each coin in this pool,
+         * sorted lexicographically by coin type.
+         *
+         * @returns An array of `PoolCoin`.
+         */
         this.poolCoins = () => {
             return Object.entries(this.pool.coins)
                 .sort((a, b) => a[0].localeCompare(b[0]))
                 .map((data) => data[1]);
         };
+        /**
+         * Returns an array of `[CoinType, PoolCoin]` pairs, sorted by coin type.
+         *
+         * @returns An array of coin-type => `PoolCoin` pairs.
+         */
         this.poolCoinEntries = () => {
             return Object.entries(this.pool.coins).sort((a, b) => a[0].localeCompare(b[0]));
         };
+        /**
+         * Returns the current DAO fee percentage, if configured (0 < fee <= 100%).
+         *
+         * @returns A decimal fraction representing the fee (e.g., 0.01 = 1%) or `undefined`.
+         */
         this.daoFeePercentage = () => {
             return this.pool.daoFeePoolObject
                 ? utils_1.Casting.bpsToPercentage(this.pool.daoFeePoolObject.feeBps)
                 : undefined;
         };
+        /**
+         * Returns the Sui address that currently receives the DAO fee portion of
+         * pool trades, or `undefined` if no DAO fee is configured.
+         *
+         * @returns The DAO fee recipient address.
+         */
         this.daoFeeRecipient = () => {
             var _a;
             return (_a = this.pool.daoFeePoolObject) === null || _a === void 0 ? void 0 : _a.feeRecipient;
@@ -255,18 +369,36 @@ class Pool extends caller_1.Caller {
         // =========================================================================
         //  Private Helpers
         // =========================================================================
+        /**
+         * Applies the DAO fee (if present) to a given `amount`, effectively reducing
+         * that amount by the fee fraction. e.g. if fee is 2%, it returns 98% of the input.
+         *
+         * @param inputs - Contains `amount` as a bigint.
+         * @returns The post-fee amount as a bigint.
+         */
         this.getAmountWithDAOFee = (inputs) => {
             const daoFeePercentage = this.daoFeePercentage();
             if (!daoFeePercentage)
                 return inputs.amount;
             return BigInt(Math.floor(Number(inputs.amount) * (1 - daoFeePercentage)));
         };
+        /**
+         * The inverse operation of `getAmountWithDAOFee`, used in internal calculations
+         * when we need to back out how much input was needed prior to the fee cut.
+         *
+         * @param inputs - Contains `amount` as a bigint.
+         * @returns The pre-fee amount as a bigint.
+         */
         this.getAmountWithoutDAOFee = (inputs) => {
             const daoFeePercentage = this.daoFeePercentage();
             if (!daoFeePercentage)
                 return inputs.amount;
             return BigInt(Math.floor(Number(inputs.amount) * (1 / (1 - daoFeePercentage))));
         };
+        /**
+         * Provides an instance of the Pools provider from `AftermathApi`.
+         * Throws an error if not defined.
+         */
         this.useProvider = () => {
             var _a;
             const provider = (_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Pools();
@@ -280,10 +412,20 @@ class Pool extends caller_1.Caller {
     //  Transactions
     // =========================================================================
     /**
-     * Fetches the deposit transaction for the pool.
-     * @async
-     * @param {ApiPoolDepositBody} inputs - The inputs for the method.
-     * @returns {Promise<Transaction>} The deposit transaction for the pool.
+     * Builds or fetches a deposit transaction to add liquidity to this pool.
+     * The resulting `Transaction` can be signed and submitted by the user.
+     *
+     * @param inputs - The deposit parameters including coin amounts, slippage, etc.
+     * @returns A `Transaction` to deposit funds into the pool.
+     *
+     * @example
+     * ```typescript
+     * const depositTx = await pool.getDepositTransaction({
+     *   walletAddress: "0x...",
+     *   amountsIn: { "0x<coin>": BigInt(1000000) },
+     *   slippage: 0.01,
+     * });
+     * ```
      */
     getDepositTransaction(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -291,10 +433,22 @@ class Pool extends caller_1.Caller {
         });
     }
     /**
-     * Fetches the withdraw transaction for the pool.
-     * @async
-     * @param {ApiPoolWithdrawBody} inputs - The inputs for the method.
-     * @returns {Promise<Transaction>} The withdraw transaction for the pool.
+     * Builds or fetches a withdrawal transaction to remove liquidity from this pool.
+     *
+     * @param inputs - The parameters specifying how much LP is burned, desired coins out, slippage, etc.
+     * @returns A `Transaction` to withdraw funds from the pool.
+     *
+     * @example
+     * ```typescript
+     * const withdrawTx = await pool.getWithdrawTransaction({
+     *   walletAddress: "0x...",
+     *   amountsOutDirection: {
+     *     "0x<coin>": BigInt(500000),
+     *   },
+     *   lpCoinAmount: BigInt(1000000),
+     *   slippage: 0.01,
+     * });
+     * ```
      */
     getWithdrawTransaction(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -302,10 +456,19 @@ class Pool extends caller_1.Caller {
         });
     }
     /**
-     * Fetches the all coin withdraw transaction for the pool.
-     * @async
-     * @param {ApiPoolAllCoinWithdrawBody} inputs - The inputs for the method.
-     * @returns {Promise<Transaction>} The all coin withdraw transaction for the pool.
+     * Builds or fetches a transaction to withdraw all coin types from this pool,
+     * effectively "burning" an LP position in exchange for multiple coin outputs.
+     *
+     * @param inputs - The parameters specifying how much LP to burn.
+     * @returns A `Transaction` to withdraw all coins from the pool in proportion.
+     *
+     * @example
+     * ```typescript
+     * const allCoinWithdrawTx = await pool.getAllCoinWithdrawTransaction({
+     *   walletAddress: "0x...",
+     *   lpCoinAmount: BigInt(500000),
+     * });
+     * ```
      */
     getAllCoinWithdrawTransaction(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -313,16 +476,45 @@ class Pool extends caller_1.Caller {
         });
     }
     /**
-     * Fetches the trade transaction for the pool.
-     * @async
-     * @param {ApiPoolTradeBody} inputs - The inputs for the method.
-     * @returns {Promise<Transaction>} The trade transaction for the pool.
+     * Builds or fetches a trade transaction to swap between two coin types in this pool.
+     *
+     * @param inputs - The trade parameters including coin in/out, amounts, slippage, etc.
+     * @returns A `Transaction` that can be signed and executed for the swap.
+     *
+     * @example
+     * ```typescript
+     * const tradeTx = await pool.getTradeTransaction({
+     *   walletAddress: "0x...",
+     *   coinInType: "0x<coinA>",
+     *   coinInAmount: BigInt(1000000),
+     *   coinOutType: "0x<coinB>",
+     *   slippage: 0.005,
+     * });
+     * ```
      */
     getTradeTransaction(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.useProvider().fetchBuildTradeTx(Object.assign(Object.assign({}, inputs), { pool: this }));
         });
     }
+    /**
+     * Builds a transaction to update the DAO fee percentage for this pool,
+     * if it has a DAO fee configured. The user must own the appropriate
+     * `daoFeePoolOwnerCap`.
+     *
+     * @param inputs - Includes user wallet, `daoFeePoolOwnerCapId`, and the new fee percentage.
+     * @returns A `Transaction` that can be signed to update the DAO fee on chain.
+     * @throws If this pool has no DAO fee configuration.
+     *
+     * @example
+     * ```typescript
+     * const tx = await pool.getUpdateDaoFeeTransaction({
+     *   walletAddress: "0x...",
+     *   daoFeePoolOwnerCapId: "0x<capId>",
+     *   newFeePercentage: 0.01, // 1%
+     * });
+     * ```
+     */
     getUpdateDaoFeeTransaction(inputs) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
@@ -332,6 +524,24 @@ class Pool extends caller_1.Caller {
             return this.useProvider().buildDaoFeePoolUpdateFeeBpsTx(Object.assign(Object.assign({}, inputs), { daoFeePoolId, lpCoinType: this.pool.lpCoinType, newFeeBps: utils_1.Casting.percentageToBps(inputs.newFeePercentage) }));
         });
     }
+    /**
+     * Builds a transaction to update the DAO fee recipient for this pool,
+     * if it has a DAO fee configured. The user must own the appropriate
+     * `daoFeePoolOwnerCap`.
+     *
+     * @param inputs - Includes user wallet, `daoFeePoolOwnerCapId`, and the new fee recipient.
+     * @returns A `Transaction` that can be signed to update the DAO fee recipient on chain.
+     * @throws If this pool has no DAO fee configuration.
+     *
+     * @example
+     * ```typescript
+     * const tx = await pool.getUpdateDaoFeeRecipientTransaction({
+     *   walletAddress: "0x...",
+     *   daoFeePoolOwnerCapId: "0x<capId>",
+     *   newFeeRecipient: "0x<recipient>",
+     * });
+     * ```
+     */
     getUpdateDaoFeeRecipientTransaction(inputs) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
@@ -345,9 +555,16 @@ class Pool extends caller_1.Caller {
     //  Inspections
     // =========================================================================
     /**
-     * Fetches the pool statistics.
-     * @async
-     * @returns {Promise<PoolStats>} The pool statistics.
+     * Fetches comprehensive pool statistics (volume, TVL, fees, APR, etc.) from the Aftermath API.
+     * Also caches the result in `this.stats`.
+     *
+     * @returns A promise resolving to `PoolStats` object.
+     *
+     * @example
+     * ```typescript
+     * const stats = await pool.getStats();
+     * console.log(stats.volume, stats.fees, stats.apr);
+     * ```
      */
     getStats() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -357,18 +574,25 @@ class Pool extends caller_1.Caller {
         });
     }
     /**
-     * Sets the pool statistics.
-     * @param {PoolStats} stats - The pool statistics.
+     * Caches the provided stats object into `this.stats`.
+     *
+     * @param stats - The `PoolStats` object to store.
      */
     setStats(stats) {
         this.stats = stats;
     }
     /**
-     * Fetches the volume data for the pool.
-     * @async
-     * @param {Object} inputs - The inputs for the method.
-     * @param {PoolGraphDataTimeframeKey} inputs.timeframe - The timeframe for the data.
-     * @returns {Promise<PoolDataPoint[]>} The volume data for the pool.
+     * Fetches an array of volume data points for a specified timeframe.
+     * This is often used for charting or historical references.
+     *
+     * @param inputs - Contains a `timeframe` key, such as `"1D"` or `"1W"`.
+     * @returns A promise resolving to an array of `PoolDataPoint`.
+     *
+     * @example
+     * ```typescript
+     * const volumeData = await pool.getVolumeData({ timeframe: "1D" });
+     * console.log(volumeData); // e.g. [{ time: 1686000000, value: 123.45 }, ...]
+     * ```
      */
     getVolumeData(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -376,11 +600,16 @@ class Pool extends caller_1.Caller {
         });
     }
     /**
-     * Fetches the fee data for the pool.
-     * @async
-     * @param {Object} inputs - The inputs for the method.
-     * @param {PoolGraphDataTimeframeKey} inputs.timeframe - The timeframe for the data.
-     * @returns {Promise<PoolDataPoint[]>} The fee data for the pool.
+     * Fetches an array of fee data points for a specified timeframe.
+     *
+     * @param inputs - Contains a `timeframe` key, e.g., `"1D"` or `"1W"`.
+     * @returns A promise resolving to an array of `PoolDataPoint`.
+     *
+     * @example
+     * ```typescript
+     * const feeData = await pool.getFeeData({ timeframe: "1D" });
+     * console.log(feeData);
+     * ```
      */
     getFeeData(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -390,6 +619,18 @@ class Pool extends caller_1.Caller {
     // =========================================================================
     //  Events
     // =========================================================================
+    /**
+     * Fetches user interaction events (deposit/withdraw) with this pool, optionally paginated.
+     *
+     * @param inputs - Includes user `walletAddress` and optional pagination fields.
+     * @returns A promise that resolves to `PoolDepositEvent | PoolWithdrawEvent` objects with a cursor if more exist.
+     *
+     * @example
+     * ```typescript
+     * const events = await pool.getInteractionEvents({ walletAddress: "0x...", limit: 10 });
+     * console.log(events.events, events.nextCursor);
+     * ```
+     */
     getInteractionEvents(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApiIndexerEvents("interaction-events-by-user", inputs);
@@ -398,7 +639,8 @@ class Pool extends caller_1.Caller {
 }
 exports.Pool = Pool;
 /**
- * Private constants used in the class.
+ * Internal margin of error used in trade calculations to prevent
+ * exceeding maximum allowed percentages of pool balances.
  */
 Pool.constants = {
     percentageBoundsMarginOfError: 0.001, // 0.1%