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

package/dist/packages/pools/pools.js

@@ -17,14 +17,23 @@ const caller_1 = require("../../general/utils/caller");
 const helpers_1 = require("../../general/utils/helpers");
 const fixedUtils_1 = require("../../general/utils/fixedUtils");
 /**
- * @class Pools Provider
+ * The `Pools` class provides a high-level interface for interacting with
+ * Aftermath Finance liquidity pools. It allows fetching individual or multiple
+ * pools, managing liquidity pool tokens (LP tokens), and creating new pools
+ * if you have the required privileges.
  *
  * @example
- * ```
- * // Create provider
- * const pools = (new Aftermath("MAINNET")).Pools();
- * // Call sdk
- * const pool = await pools.getPool({ objectId: "0xBEEF" });
+ * ```typescript
+ * const afSdk = new Aftermath("MAINNET");
+ * await afSdk.init(); // initialize provider
+ *
+ * const pools = afSdk.Pools();
+ *
+ * // Fetch a single pool
+ * const pool = await pools.getPool({ objectId: "0x<poolId>" });
+ *
+ * // Fetch multiple pools
+ * const poolArray = await pools.getPools({ objectIds: ["0x<id1>", "0x<id2>"] });
  * ```
  */
 class Pools extends caller_1.Caller {
@@ -32,10 +41,10 @@ class Pools extends caller_1.Caller {
     //  Constructor
     // =========================================================================
     /**
-     * Creates `Pools` provider to call api.
+     * Creates a new `Pools` instance for querying and managing AMM pools on Aftermath.
      *
-     * @param network - The Sui network to interact with
-     * @returns New `Pools` instance
+     * @param config - Optional configuration object specifying network or access token.
+     * @param Provider - An optional `AftermathApi` instance providing advanced transaction building.
      */
     constructor(config, Provider) {
         super(config, "pools");
@@ -44,30 +53,30 @@ class Pools extends caller_1.Caller {
         //  Inspections
         // =========================================================================
         /**
-         * Returns the pool object ID for the given LP coin type.
-         * @param inputs - The request body containing the LP coin type.
-         * @returns The pool object ID.
-         * @throws An error if the LP coin type is invalid.
+         * Retrieves the on-chain pool object ID corresponding to a specific LP coin type.
+         *
+         * @param inputs - Contains the `lpCoinType` string.
+         * @returns The pool object ID if it exists.
+         *
+         * @example
+         * ```typescript
+         * const poolId = await pools.getPoolObjectIdForLpCoinType({
+         *   lpCoinType: "0x<lpCoinType>"
+         * });
+         * console.log(poolId);
+         * ```
          */
         this.getPoolObjectIdForLpCoinType = (inputs) => {
             return this.getPoolObjectIdsForLpCoinTypes({
                 lpCoinTypes: [inputs.lpCoinType],
             });
         };
-        this.getPoolObjectIdsForLpCoinTypes = (inputs) => __awaiter(this, void 0, void 0, function* () {
-            // TODO: handle this case
-            // if (
-            // 	inputs.lpCoinTypes.some(
-            // 		(lpCoinType) => !Pools.isPossibleLpCoinType({ lpCoinType })
-            // 	)
-            // )
-            // 	throw new Error("invalid lp coin type");
-            return this.fetchApi("pool-object-ids", inputs);
-        });
         /**
-         * Checks if the given coin type is an LP coin type.
-         * @param inputs - An object containing the LP coin type to check.
-         * @returns A boolean indicating whether the given coin type is an LP coin type.
+         * Checks if a given coin type is recognized as an LP coin.
+         * Internally calls `getPoolObjectIdForLpCoinType`.
+         *
+         * @param inputs - Contains the `lpCoinType` to check.
+         * @returns `true` if the coin is an LP token, `false` otherwise.
          */
         this.isLpCoinType = (inputs) => __awaiter(this, void 0, void 0, function* () {
             try {
@@ -79,8 +88,15 @@ class Pools extends caller_1.Caller {
             }
         });
         /**
-         * Retrieves the total volume in the last 24 hours.
-         * @returns A Promise that resolves to a number representing the total volume.
+         * Retrieves the total volume across all pools in the last 24 hours.
+         *
+         * @returns A promise resolving to a numeric volume (e.g., in USD).
+         *
+         * @example
+         * ```typescript
+         * const totalVol24 = await pools.getTotalVolume24hrs();
+         * console.log("Protocol-wide 24h volume:", totalVol24);
+         * ```
          */
         this.getTotalVolume24hrs = () => __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("volume-24hrs");
@@ -88,6 +104,10 @@ class Pools extends caller_1.Caller {
         // =========================================================================
         //  Private Helpers
         // =========================================================================
+        /**
+         * Provides a typed reference to the `Pools` part of the `AftermathApi`,
+         * throwing an error if not defined.
+         */
         this.useProvider = () => {
             var _b;
             const provider = (_b = this.Provider) === null || _b === void 0 ? void 0 : _b.Pools();
@@ -103,10 +123,16 @@ class Pools extends caller_1.Caller {
     //  Pool Class
     // =========================================================================
     /**
-     * Creates new `Pool` class from queried pool object
+     * Fetches a single pool by its on-chain `objectId` and returns a new `Pool` instance.
+     *
+     * @param inputs - An object containing `objectId`.
+     * @returns A promise that resolves to a `Pool` instance.
      *
-     * @param objectId - Object id of pool to fetch
-     * @returns New `Pool` instance
+     * @example
+     * ```typescript
+     * const pool = await pools.getPool({ objectId: "0x<poolId>" });
+     * console.log(pool.pool.lpCoinType, pool.pool.name);
+     * ```
      */
     getPool(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -115,10 +141,16 @@ class Pools extends caller_1.Caller {
         });
     }
     /**
-     * Creates `Pool[]` of classes from queried pool objects
+     * Fetches multiple pools by their on-chain `objectIds` and returns an array of `Pool` instances.
      *
-     * @param objectIds - Object ids of pools to fetch
-     * @returns New `Pool[]` instances
+     * @param inputs - An object containing an array of `objectIds`.
+     * @returns A promise that resolves to an array of `Pool` instances.
+     *
+     * @example
+     * ```typescript
+     * const poolArray = await pools.getPools({ objectIds: ["0x<id1>", "0x<id2>"] });
+     * console.log(poolArray.length);
+     * ```
      */
     getPools(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -129,8 +161,15 @@ class Pools extends caller_1.Caller {
         });
     }
     /**
-     * Retrieves all pools from the API and returns an array of Pool objects.
-     * @returns {Promise<Pool[]>} A promise that resolves to an array of Pool objects.
+     * Retrieves all pools recognized by the Aftermath API, returning an array of `Pool` objects.
+     *
+     * @returns An array of `Pool` instances.
+     *
+     * @example
+     * ```typescript
+     * const allPools = await pools.getAllPools();
+     * console.log(allPools.map(p => p.pool.name));
+     * ```
      */
     getAllPools() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -138,6 +177,19 @@ class Pools extends caller_1.Caller {
             return pools.map((pool) => new pool_1.Pool(pool, this.config, this.Provider));
         });
     }
+    /**
+     * Fetches information about all owned LP coins for a given wallet address.
+     * This indicates the user's liquidity positions across multiple pools.
+     *
+     * @param inputs - An object containing the `walletAddress`.
+     * @returns A `PoolLpInfo` object summarizing the user's LP balances.
+     *
+     * @example
+     * ```typescript
+     * const lpCoins = await pools.getOwnedLpCoins({ walletAddress: "0x<address>" });
+     * console.log(lpCoins);
+     * ```
+     */
     getOwnedLpCoins(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("owned-lp-coins", inputs);
@@ -147,9 +199,19 @@ class Pools extends caller_1.Caller {
     //  Transactions
     // =========================================================================
     /**
-     * Fetches the API transaction for publishing an LP coin.
-     * @param inputs - The inputs for the transaction.
-     * @returns A promise that resolves with the API transaction.
+     * Constructs or fetches a transaction to publish a new LP coin package,
+     * typically used by advanced users or devs establishing new liquidity pools.
+     *
+     * @param inputs - Includes the user `walletAddress` and the `lpCoinDecimals`.
+     * @returns A transaction object (or data) that can be signed and published to Sui.
+     *
+     * @example
+     * ```typescript
+     * const publishTx = await pools.getPublishLpCoinTransaction({
+     *   walletAddress: "0x<address>",
+     *   lpCoinDecimals: 9
+     * });
+     * ```
      */
     getPublishLpCoinTransaction(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -157,30 +219,112 @@ class Pools extends caller_1.Caller {
         });
     }
     /**
-     * Fetches the transaction for creating a new pool.
-     * @param inputs The inputs required for creating a new pool.
-     * @returns A Promise that resolves to the transaction data.
+     * Constructs a transaction to create a brand new pool on-chain, given coin types,
+     * initial weights, fees, and possible DAO fee info.
+     *
+     * @param inputs - The body describing how to form the new pool.
+     * @returns A transaction object that can be signed and executed.
+     *
+     * @example
+     * ```typescript
+     * const createPoolTx = await pools.getCreatePoolTransaction({
+     *   walletAddress: "0x<address>",
+     *   lpCoinType: "0x<lpCoin>",
+     *   lpCoinMetadata: {
+     *     name: "MyPool LP",
+     *     symbol: "MYPLP"
+     *   },
+     *   coinsInfo: [
+     *     {
+     *       coinType: "0x<coinA>",
+     *       weight: 0.5,
+     *       decimals: 9,
+     *       tradeFeeIn: 0.003,
+     *       initialDeposit: 1_000_000_000n
+     *     },
+     *     // ...
+     *   ],
+     *   poolName: "My Weighted Pool",
+     *   createPoolCapId: "0x<capId>",
+     *   respectDecimals: true,
+     * });
+     * ```
      */
     getCreatePoolTransaction(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApiTransaction("transactions/create-pool", inputs);
         });
     }
+    /**
+     * Retrieves multiple pool object IDs given an array of LP coin types.
+     * If a given LP coin type has no associated pool, it might return `undefined`.
+     *
+     * @param inputs - Contains an array of `lpCoinTypes`.
+     * @returns An array of `ObjectId | undefined` of matching length.
+     *
+     * @example
+     * ```typescript
+     * const poolIds = await pools.getPoolObjectIdsForLpCoinTypes({
+     *   lpCoinTypes: ["0x<lpCoinA>", "0x<lpCoinB>"]
+     * });
+     * console.log(poolIds);
+     * ```
+     */
+    getPoolObjectIdsForLpCoinTypes(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("pool-object-ids", inputs);
+        });
+    }
+    /**
+     * Retrieves the total value locked (TVL) across all or specific pool IDs.
+     *
+     * @param inputs - Optionally provide an array of specific `poolIds`. If omitted, returns global TVL.
+     * @returns A promise resolving to a numeric TVL (e.g., in USD).
+     *
+     * @example
+     * ```typescript
+     * const allTvl = await pools.getTVL();
+     * const subsetTvl = await pools.getTVL({ poolIds: ["0x<id1>", "0x<id2>"] });
+     * ```
+     */
     getTVL(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("tvl", inputs !== null && inputs !== void 0 ? inputs : {});
         });
     }
     /**
-     * Fetches statistics for pools.
-     * @async
-     * @returns {Promise<PoolStats[]>} The statistics for pools.
+     * Fetches an array of `PoolStats` objects for a given set of pools,
+     * including volume, fees, TVL, and other metrics.
+     *
+     * @param inputs - Must include an array of `poolIds`.
+     * @returns An array of `PoolStats` in matching order.
+     *
+     * @example
+     * ```typescript
+     * const stats = await pools.getPoolsStats({ poolIds: ["0x<id1>", "0x<id2>"] });
+     * console.log(stats[0].volume, stats[1].tvl);
+     * ```
      */
     getPoolsStats(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("stats", inputs);
         });
     }
+    /**
+     * Returns all DAO fee pool owner capabilities owned by a particular user.
+     * This is used to see which pools' DAO fees the user can update.
+     *
+     * @param inputs - An object with user `walletAddress`.
+     * @returns Data about each `DaoFeePoolOwnerCapObject` the user owns.
+     *
+     * @example
+     * ```typescript
+     * const daoCaps = await pools.getOwnedDaoFeePoolOwnerCaps({
+     *   walletAddress: "0x<address>"
+     * });
+     * console.log(daoCaps);
+     * ```
+     */
     getOwnedDaoFeePoolOwnerCaps(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.useProvider().fetchOwnedDaoFeePoolOwnerCaps(inputs);
@@ -189,6 +333,22 @@ class Pools extends caller_1.Caller {
     // =========================================================================
     //  Events
     // =========================================================================
+    /**
+     * Fetches user-specific interaction events (deposits, withdrawals) across pools,
+     * optionally with pagination.
+     *
+     * @param inputs - An object containing `walletAddress`, plus optional pagination (`cursor`, `limit`).
+     * @returns An event set with a cursor for further queries if available.
+     *
+     * @example
+     * ```typescript
+     * const userEvents = await pools.getInteractionEvents({
+     *   walletAddress: "0x...",
+     *   limit: 10,
+     * });
+     * console.log(userEvents.events, userEvents.nextCursor);
+     * ```
+     */
     getInteractionEvents(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApiIndexerEvents("interaction-events-by-user", inputs);
@@ -201,40 +361,105 @@ _a = Pools;
 //  Constants
 // =========================================================================
 /**
- * An object containing various constants used in the pools module.
+ * Static constants relevant to the pool logic, such as protocol fees,
+ * referral percentages, and bounds for trading/withdrawal percentages.
  */
 Pools.constants = {
-    // TODO: remove this and use fixed class
+    /**
+     * Protocol fee structure: `totalProtocol` is the fraction of trades
+     * that is taken as a fee, which is split among `treasury`, `insuranceFund`,
+     * and `devWallet` in the given proportions.
+     */
     feePercentages: {
+        /**
+         * The total fraction (as a decimal) of trades charged by the protocol.
+         * e.g., 0.00005 => 0.005%.
+         */
         totalProtocol: 0.00005,
-        // following fees are taked as portions of total protocol fees above
+        /**
+         * The fraction of `totalProtocol` allocated to the treasury.
+         */
         treasury: 0.5,
+        /**
+         * The fraction of `totalProtocol` allocated to the insurance fund.
+         */
         insuranceFund: 0.3,
-        devWallet: 0.2, // 20%
+        /**
+         * The fraction of `totalProtocol` allocated to the dev wallet.
+         */
+        devWallet: 0.2,
     },
+    /**
+     * Referral fee structures, applying a discount/rebate to the user and
+     * referrer, taken from the treasury portion of protocol fees.
+     */
     referralPercentages: {
-        // these percantages are relative to treasury allocation
+        /**
+         * The fraction of the treasury portion that discounts the user's fee.
+         */
         discount: 0.05,
-        rebate: 0.05, // 5%
+        /**
+         * The fraction of the treasury portion that acts as a rebate to the referrer.
+         */
+        rebate: 0.05,
     },
+    /**
+     * Various bounds used to prevent extreme trades or invalid pool configurations.
+     */
     bounds: {
+        /**
+         * Maximum number of distinct coins allowed in a single pool.
+         */
         maxCoinsInPool: 8,
+        /**
+         * Maximum fraction (decimal) of a pool's balance that can be traded at once.
+         */
         maxTradePercentageOfPoolBalance: 0.3,
+        /**
+         * Maximum fraction (decimal) of a pool's balance that can be withdrawn at once.
+         */
         maxWithdrawPercentageOfPoolBalance: 0.3,
+        /**
+         * Minimum and maximum swap fees (0.01% to 10%).
+         */
         minSwapFee: 0.0001,
         maxSwapFee: 0.1,
+        /**
+         * Minimum and maximum coin weight for weighted pools (1% to 99%).
+         */
         minWeight: 0.01,
         maxWeight: 0.99,
+        /**
+         * Minimum and maximum DAO fee (0% to 100%).
+         */
         minDaoFee: 0,
-        maxDaoFee: 1, // 100%
+        maxDaoFee: 1,
     },
+    /**
+     * Default parameter(s) used in the absence of explicit user or code settings.
+     */
     defaults: {
+        /**
+         * Default decimals for LP coins if none are specified.
+         */
         lpCoinDecimals: 9,
     },
 };
 // =========================================================================
 //  Fees
 // =========================================================================
+/**
+ * Returns how much coin remains **after** applying the protocol fees
+ * (and referral discount if `withReferral` is `true`).
+ *
+ * @param inputs - The original `amount` and an optional referral flag.
+ * @returns The post-fee (net) amount as a bigint.
+ *
+ * @example
+ * ```typescript
+ * const netAmount = Pools.getAmountWithProtocolFees({ amount: 1_000_000n });
+ * ```
+ */
 Pools.getAmountWithProtocolFees = (inputs) => {
     const referralDiscount = inputs.withReferral
         ? _a.constants.feePercentages.totalProtocol *
@@ -246,6 +471,14 @@ Pools.getAmountWithProtocolFees = (inputs) => {
             (_a.constants.feePercentages.totalProtocol -
                 referralDiscount))));
 };
+/**
+ * The inverse calculation: given a net amount (post-fees), figure out
+ * the original gross amount. Used when we already have fees subtracted
+ * but need to restore an original quantity.
+ *
+ * @param inputs - The net `amount` after fees, plus an optional referral flag.
+ * @returns The original gross amount as a bigint.
+ */
 Pools.getAmountWithoutProtocolFees = (inputs) => {
     const referralDiscount = inputs.withReferral
         ? _a.constants.feePercentages.totalProtocol *
@@ -258,10 +491,24 @@ Pools.getAmountWithoutProtocolFees = (inputs) => {
                 (_a.constants.feePercentages.totalProtocol -
                     referralDiscount)))));
 };
+/**
+ * A helper to transform a user-provided slippage fraction, e.g. 0.01,
+ * into a 1 - slippage format, if needed for certain math operations.
+ *
+ * @param slippage - The decimal fraction of slippage tolerance, e.g. 0.01 => 1%.
+ * @returns A big integer representing `1 - slippage` in a fixed context.
+ */
 Pools.normalizeInvertSlippage = (slippage) => fixedUtils_1.FixedUtils.directUncast(1 - slippage);
 // =========================================================================
 //  Display
 // =========================================================================
+/**
+ * Produces a user-friendly string for an LP coin type, e.g. "Sui Coin LP"
+ * by analyzing the coin type symbol. Typically used in UIs or logs.
+ *
+ * @param lpCoinType - The coin type for the LP token.
+ * @returns A string representation for display, e.g. "Af_lp_abc" => "Abc LP".
+ */
 Pools.displayLpCoinType = (lpCoinType) => coin_1.Coin.getCoinTypeSymbol(lpCoinType)
     .toLowerCase()
     .replace("af_lp_", "")
@@ -271,6 +518,13 @@ Pools.displayLpCoinType = (lpCoinType) => coin_1.Coin.getCoinTypeSymbol(lpCoinTy
 // =========================================================================
 //  Helpers
 // =========================================================================
+/**
+ * A quick heuristic check to see if the given `lpCoinType` string
+ * might represent an Aftermath LP token. This is not a full on-chain validation.
+ *
+ * @param inputs - An object containing `lpCoinType`.
+ * @returns `true` if it matches a known pattern; otherwise `false`.
+ */
 Pools.isPossibleLpCoinType = (inputs) => {
     const { lpCoinType } = inputs;
     return (lpCoinType.split("::").length === 3 &&