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

package/dist/packages/router/router.d.ts

@@ -3,45 +3,114 @@ import { Caller } from "../../general/utils/caller";
 import { Transaction } from "@mysten/sui/transactions";
 import { TransactionBlock } from "@mysten/sui.js/transactions";
 /**
- * @class Router Provider
+ * The `Router` class provides a collection of methods to interact with Aftermath's
+ * smart order routing system on the Sui Network. It handles routing trades through
+ * various liquidity pools to achieve the best possible execution price, retrieving
+ * trade volume, managing supported coins, and more.
  *
  * @example
- * ```
+ * ```typescript
  * // Create provider
  * const router = (new Aftermath("MAINNET")).Router();
- * // Call sdk
+ * // Retrieve 24h volume
+ * const volume24h = await router.getVolume24hrs();
+ * // Get supported coins
  * const supportedCoins = await router.getSupportedCoins();
  * ```
  */
 export declare class Router extends Caller {
+    /**
+     * Contains static information about the router, such as the maximum
+     * allowable external fee percentage.
+     */
     static readonly constants: {
         /**
-         * Max fee percentage that third parties can charge on router trades
+         * The maximum external fee percentage that a third party can charge on router trades.
+         * @remarks 0.5 = 50%
          */
         maxExternalFeePercentage: number;
     };
     /**
-     * Creates `Router` provider to call api.
+     * Creates a new `Router` instance to perform router-related calls on the
+     * Aftermath platform.
      *
-     * @param network - The Sui network to interact with
-     * @returns New `Router` instance
+     * @param config - Optional configuration settings, including network and access token.
+     * @returns A new `Router` instance.
+     *
+     * @example
+     * ```typescript
+     * const afSdk = new Aftermath("MAINNET");
+     * await afSdk.init(); // initialize provider
+     *
+     * const router = afSdk.Router();
+     * ```
      */
     constructor(config?: CallerConfig);
     /**
-     * Retrieves the total volume in the last 24 hours.
-     * @returns A Promise that resolves to a number representing the total volume.
+     * Retrieves the total trading volume in the last 24 hours.
+     *
+     * @returns A promise that resolves to a `number` representing the total volume in the last 24 hours.
+     *
+     * @example
+     * ```typescript
+     * const volume = await router.getVolume24hrs();
+     * console.log(volume); // e.g. 1234567.89
+     * ```
      */
     getVolume24hrs: () => Promise<number>;
+    /**
+     * Fetches a list of all coin types that are supported for trading through the router.
+     *
+     * @returns A promise that resolves to an array of coin types (`CoinType[]`).
+     *
+     * @example
+     * ```typescript
+     * const supportedCoins = await router.getSupportedCoins();
+     * console.log(supportedCoins); // ["0x2::sui::SUI", "0x<...>::coin::TOKEN", ...]
+     * ```
+     */
     getSupportedCoins(): Promise<string[]>;
+    /**
+     * Searches the supported coins by applying a filter string.
+     *
+     * @param inputs - An object containing a `filter` string to match against supported coins.
+     * @param abortSignal - An optional `AbortSignal` to cancel the request if needed.
+     * @returns A promise that resolves to an array of coin types matching the filter.
+     *
+     * @example
+     * ```typescript
+     * const searchResult = await router.searchSupportedCoins({ filter: "SUI" });
+     * console.log(searchResult); // e.g. ["0x2::sui::SUI"]
+     * ```
+     */
     searchSupportedCoins(inputs: {
         filter: string;
     }, abortSignal?: AbortSignal): Promise<string[]>;
     /**
-     * Creates route across multiple pools and protocols for best trade execution price
+     * Creates an optimal trade route for a given token input (`coinInType`) with a
+     * specified input amount (`coinInAmount`). This route may consist of multiple
+     * swaps across different DEX protocols to achieve the best price.
+     *
+     * @param inputs - Details required to construct the trade route, including `coinInType`, `coinOutType`, and `coinInAmount`.
+     * @param abortSignal - An optional signal to abort the request if needed.
+     * @returns A promise resolving to a `RouterCompleteTradeRoute` object containing the full route details.
      *
-     * @param inputs - Details for router to construct trade route
-     * @param abortSignal - Optional signal to abort passed to fetch call
-     * @returns Routes, paths, and amounts of each smaller trade within complete trade
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({
+     *   coinInType: "0x2::sui::SUI",
+     *   coinOutType: "0x<...>::coin::TOKEN",
+     *   coinInAmount: BigInt(10_000_000_000),
+     *   // optional fields:
+     *   referrer: "0x<referrer_address>",
+     *   externalFee: {
+     *     recipient: "0x<fee_collector>",
+     *     feePercentage: 0.01
+     *   },
+     *   protocolBlacklist: ["Cetus", "BlueMove"]
+     * });
+     * console.log(route);
+     * ```
      */
     getCompleteTradeRouteGivenAmountIn(inputs: ApiRouterPartialCompleteTradeRouteBody & {
         /**
@@ -50,11 +119,25 @@ export declare class Router extends Caller {
         coinInAmount: Balance;
     }, abortSignal?: AbortSignal): Promise<RouterCompleteTradeRoute>;
     /**
-     * Creates route across multiple pools and protocols for best trade execution price
+     * Creates an optimal trade route for a given token output (`coinOutType`) with a
+     * specified output amount (`coinOutAmount`). This route may consist of multiple
+     * swaps to achieve the target output amount, factoring in slippage.
+     *
+     * @param inputs - Details required to construct the trade route, including `coinInType`, `coinOutType`, `coinOutAmount`, and `slippage`.
+     * @param abortSignal - An optional signal to abort the request if needed.
+     * @returns A promise resolving to a `RouterCompleteTradeRoute` object containing the full route details.
      *
-     * @param inputs - Details for router to construct trade route
-     * @param abortSignal - Optional signal to abort passed to fetch call
-     * @returns Routes, paths, and amounts of each smaller trade within complete trade
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountOut({
+     *   coinInType: "0x2::sui::SUI",
+     *   coinOutType: "0x<...>::coin::TOKEN",
+     *   coinOutAmount: BigInt(20_000_000),
+     *   slippage: 0.01, // 1%
+     *   protocolWhitelist: ["Aftermath", "Cetus"]
+     * });
+     * console.log(route);
+     * ```
      */
     getCompleteTradeRouteGivenAmountOut(inputs: ApiRouterPartialCompleteTradeRouteBody & {
         /**
@@ -63,20 +146,133 @@ export declare class Router extends Caller {
         coinOutAmount: Balance;
         slippage: Slippage;
     }, abortSignal?: AbortSignal): Promise<RouterCompleteTradeRoute>;
+    /**
+     * Generates a transaction to execute a previously calculated complete trade route.
+     * This transaction can then be signed and executed by the user.
+     *
+     * @param inputs - An object containing the wallet address, the complete trade route, slippage tolerance, and optional sponsorship settings.
+     * @returns A promise resolving to a `Uint8Array` representing the serialized transaction.
+     *
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     * const transactionBytes = await router.getTransactionForCompleteTradeRoute({
+     *   walletAddress: "0x<your_address>",
+     *   completeRoute: route,
+     *   slippage: 0.01
+     * });
+     * // The returned bytes can now be signed and executed using your chosen wallet.
+     * ```
+     */
     getTransactionForCompleteTradeRoute(inputs: ApiRouterTransactionForCompleteTradeRouteBody): Promise<Transaction>;
+    /**
+     * **Legacy method** for generating a transaction to execute a complete trade route.
+     * Uses an older version of transaction serialization.
+     *
+     * @param inputs - Similar to `getTransactionForCompleteTradeRoute` but serialized using the legacy method.
+     * @returns A promise resolving to a `Uint8Array` representing the serialized transaction.
+     *
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     * const transactionBytesV0 = await router.getTransactionForCompleteTradeRouteV0({
+     *   walletAddress: "0x<your_address>",
+     *   completeRoute: route,
+     *   slippage: 0.01
+     * });
+     * // Use this if your environment requires legacy transaction structure
+     * ```
+     */
     getTransactionForCompleteTradeRouteV0(inputs: ApiRouterTransactionForCompleteTradeRouteBody): Promise<TransactionBlock>;
+    /**
+     * Adds a trade route to an existing transaction, allowing you to build complex
+     * transactions containing multiple actions (swaps, transfers, etc.) in a single
+     * atomic transaction.
+     *
+     * @param inputs - Includes the existing `Transaction`, a complete route, slippage, wallet address, and an optional `coinInId`.
+     * @returns An object containing:
+     *  - `tx`: The updated `Transaction` including the route instructions
+     *  - `coinOutId`: A `TransactionObjectArgument` referencing the output coin after the swap
+     *
+     * @example
+     * ```typescript
+     * // 1) Create a route
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     *
+     * // 2) Initialize your transaction
+     * const tx = new Transaction();
+     *
+     * // 3) Add router instructions
+     * const { tx: updatedTx, coinOutId } =
+     *   await router.addTransactionForCompleteTradeRoute({
+     *     tx,
+     *     completeRoute: route,
+     *     slippage: 0.01,
+     *     walletAddress: "0x<your_address>"
+     * });
+     *
+     * // 4) Continue building your transaction with the resulting coinOutId, if desired
+     * updatedTx.transferObjects([coinOutId!], "0x<your_address>");
+     * ```
+     */
     addTransactionForCompleteTradeRoute(inputs: Omit<ApiRouterAddTransactionForCompleteTradeRouteBody, "serializedTx"> & {
         tx: Transaction;
     }): Promise<{
         tx: Transaction;
         coinOutId: import("@mysten/sui/transactions").TransactionObjectArgument | undefined;
     }>;
+    /**
+     * **Legacy method** for adding a trade route to an existing transaction.
+     * Uses an older version of transaction serialization.
+     *
+     * @param inputs - Similar to `addTransactionForCompleteTradeRoute` but returns a `TransactionBlock`.
+     * @returns An object containing:
+     *  - `tx`: The updated `TransactionBlock`
+     *  - `coinOutId`: A `TransactionObjectArgumentV0` referencing the output coin
+     *
+     * @example
+     * ```typescript
+     * // 1) Create a route
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     *
+     * // 2) Initialize your transaction block
+     * const txBlock = new TransactionBlock();
+     *
+     * // 3) Add router instructions (legacy)
+     * const { tx: updatedTxBlock, coinOutId } =
+     *   await router.addTransactionForCompleteTradeRouteV0({
+     *     tx: txBlock,
+     *     completeRoute: route,
+     *     slippage: 0.01,
+     *     walletAddress: "0x<your_address>"
+     * });
+     *
+     * // 4) Continue building your transaction with the resulting coinOutId
+     * updatedTxBlock.transferObjects([coinOutId!], "0x<your_address>");
+     * ```
+     */
     addTransactionForCompleteTradeRouteV0(inputs: Omit<ApiRouterAddTransactionForCompleteTradeRouteV0Body, "serializedTx"> & {
         tx: TransactionBlock;
     }): Promise<{
         tx: TransactionBlock;
         coinOutId: any;
     }>;
+    /**
+     * Retrieves trade events (interactions) for a given user based on router usage.
+     *
+     * @param inputs - Includes a `walletAddress`, cursor pagination, and limit.
+     * @returns A promise resolving to the user's `RouterTradeEvent`s, potentially paginated.
+     *
+     * @example
+     * ```typescript
+     * const events = await router.getInteractionEvents({
+     *   walletAddress: "0x<your_address>",
+     *   cursor: 0,
+     *   limit: 10
+     * });
+     * console.log(events);
+     * ```
+     */
     getInteractionEvents(inputs: ApiRouterTradeEventsBody): Promise<import("../../types").IndexerEventsWithCursor<RouterTradeEvent>>;
 }
 //# sourceMappingURL=router.d.ts.map

package/dist/packages/router/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/packages/router/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,6CAA6C,EAE7C,wBAAwB,EAExB,wBAAwB,EACxB,gBAAgB,EAChB,OAAO,EACP,sCAAsC,EACtC,gDAAgD,EAEhD,kDAAkD,EAGlD,QAAQ,EAER,YAAY,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,qBAAa,MAAO,SAAQ,MAAM;IAKjC,gBAAuB,SAAS;QAC/B;;WAEG;;MAEF;IAMF;;;;;OAKG;gBACS,MAAM,CAAC,EAAE,YAAY;IAYjC;;;OAGG;IACI,cAAc,QAAa,QAAQ,MAAM,CAAC,CAE/C;IAEW,iBAAiB;IAIjB,oBAAoB,CAChC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,EAC1B,WAAW,CAAC,EAAE,WAAW;IAS1B;;;;;;OAMG;IACU,kCAAkC,CAC9C,MAAM,EAAE,sCAAsC,GAAG;QAChD;;WAEG;QACH,YAAY,EAAE,OAAO,CAAC;KACtB,EACD,WAAW,CAAC,EAAE,WAAW;IAQ1B;;;;;;OAMG;IACU,mCAAmC,CAC/C,MAAM,EAAE,sCAAsC,GAAG;QAChD;;WAEG;QACH,aAAa,EAAE,OAAO,CAAC;QACvB,QAAQ,EAAE,QAAQ,CAAC;KACnB,EACD,WAAW,CAAC,EAAE,WAAW;IAYb,mCAAmC,CAC/C,MAAM,EAAE,6CAA6C;IAQzC,qCAAqC,CACjD,MAAM,EAAE,6CAA6C;IAQzC,mCAAmC,CAC/C,MAAM,EAAE,IAAI,CACX,gDAAgD,EAChD,cAAc,CACd,GAAG;QACH,EAAE,EAAE,WAAW,CAAC;KAChB;;;;IAgBW,qCAAqC,CACjD,MAAM,EAAE,IAAI,CACX,kDAAkD,EAClD,cAAc,CACd,GAAG;QACH,EAAE,EAAE,gBAAgB,CAAC;KACrB;;;;IAoBW,oBAAoB,CAAC,MAAM,EAAE,wBAAwB;CAMlE"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/packages/router/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,6CAA6C,EAE7C,wBAAwB,EAExB,wBAAwB,EACxB,gBAAgB,EAChB,OAAO,EACP,sCAAsC,EACtC,gDAAgD,EAEhD,kDAAkD,EAGlD,QAAQ,EAER,YAAY,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,MAAO,SAAQ,MAAM;IAKjC;;;OAGG;IACH,gBAAuB,SAAS;QAC/B;;;WAGG;;MAEF;IAMF;;;;;;;;;;;;;;OAcG;gBACS,MAAM,CAAC,EAAE,YAAY;IAYjC;;;;;;;;;;OAUG;IACI,cAAc,QAAa,QAAQ,MAAM,CAAC,CAE/C;IAEF;;;;;;;;;;OAUG;IACU,iBAAiB;IAI9B;;;;;;;;;;;;OAYG;IACU,oBAAoB,CAChC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,EAC1B,WAAW,CAAC,EAAE,WAAW;IAS1B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,kCAAkC,CAC9C,MAAM,EAAE,sCAAsC,GAAG;QAChD;;WAEG;QACH,YAAY,EAAE,OAAO,CAAC;KACtB,EACD,WAAW,CAAC,EAAE,WAAW;IAQ1B;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,mCAAmC,CAC/C,MAAM,EAAE,sCAAsC,GAAG;QAChD;;WAEG;QACH,aAAa,EAAE,OAAO,CAAC;QACvB,QAAQ,EAAE,QAAQ,CAAC;KACnB,EACD,WAAW,CAAC,EAAE,WAAW;IAY1B;;;;;;;;;;;;;;;;;OAiBG;IACU,mCAAmC,CAC/C,MAAM,EAAE,6CAA6C;IAQtD;;;;;;;;;;;;;;;;;OAiBG;IACU,qCAAqC,CACjD,MAAM,EAAE,6CAA6C;IAQtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACU,mCAAmC,CAC/C,MAAM,EAAE,IAAI,CACX,gDAAgD,EAChD,cAAc,CACd,GAAG;QACH,EAAE,EAAE,WAAW,CAAC;KAChB;;;;IAgBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACU,qCAAqC,CACjD,MAAM,EAAE,IAAI,CACX,kDAAkD,EAClD,cAAc,CACd,GAAG;QACH,EAAE,EAAE,gBAAgB,CAAC;KACrB;;;;IAoBF;;;;;;;;;;;;;;;OAeG;IACU,oBAAoB,CAAC,MAAM,EAAE,wBAAwB;CAMlE"}

package/dist/packages/router/router.js

@@ -25,13 +25,18 @@ const caller_1 = require("../../general/utils/caller");
 const transactions_1 = require("@mysten/sui/transactions");
 const transactions_2 = require("@mysten/sui.js/transactions");
 /**
- * @class Router Provider
+ * The `Router` class provides a collection of methods to interact with Aftermath's
+ * smart order routing system on the Sui Network. It handles routing trades through
+ * various liquidity pools to achieve the best possible execution price, retrieving
+ * trade volume, managing supported coins, and more.
  *
  * @example
- * ```
+ * ```typescript
  * // Create provider
  * const router = (new Aftermath("MAINNET")).Router();
- * // Call sdk
+ * // Retrieve 24h volume
+ * const volume24h = await router.getVolume24hrs();
+ * // Get supported coins
  * const supportedCoins = await router.getSupportedCoins();
  * ```
  */
@@ -40,10 +45,19 @@ class Router extends caller_1.Caller {
     //  Constructor
     // =========================================================================
     /**
-     * Creates `Router` provider to call api.
+     * Creates a new `Router` instance to perform router-related calls on the
+     * Aftermath platform.
+     *
+     * @param config - Optional configuration settings, including network and access token.
+     * @returns A new `Router` instance.
+     *
+     * @example
+     * ```typescript
+     * const afSdk = new Aftermath("MAINNET");
+     * await afSdk.init(); // initialize provider
      *
-     * @param network - The Sui network to interact with
-     * @returns New `Router` instance
+     * const router = afSdk.Router();
+     * ```
      */
     constructor(config) {
         super(config, "router");
@@ -54,29 +68,79 @@ class Router extends caller_1.Caller {
         //  Inspections
         // =========================================================================
         /**
-         * Retrieves the total volume in the last 24 hours.
-         * @returns A Promise that resolves to a number representing the total volume.
+         * Retrieves the total trading volume in the last 24 hours.
+         *
+         * @returns A promise that resolves to a `number` representing the total volume in the last 24 hours.
+         *
+         * @example
+         * ```typescript
+         * const volume = await router.getVolume24hrs();
+         * console.log(volume); // e.g. 1234567.89
+         * ```
          */
         this.getVolume24hrs = () => __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("volume-24hrs");
         });
     }
+    /**
+     * Fetches a list of all coin types that are supported for trading through the router.
+     *
+     * @returns A promise that resolves to an array of coin types (`CoinType[]`).
+     *
+     * @example
+     * ```typescript
+     * const supportedCoins = await router.getSupportedCoins();
+     * console.log(supportedCoins); // ["0x2::sui::SUI", "0x<...>::coin::TOKEN", ...]
+     * ```
+     */
     getSupportedCoins() {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("supported-coins");
         });
     }
+    /**
+     * Searches the supported coins by applying a filter string.
+     *
+     * @param inputs - An object containing a `filter` string to match against supported coins.
+     * @param abortSignal - An optional `AbortSignal` to cancel the request if needed.
+     * @returns A promise that resolves to an array of coin types matching the filter.
+     *
+     * @example
+     * ```typescript
+     * const searchResult = await router.searchSupportedCoins({ filter: "SUI" });
+     * console.log(searchResult); // e.g. ["0x2::sui::SUI"]
+     * ```
+     */
     searchSupportedCoins(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi(`supported-coins/${inputs.filter}`, undefined, abortSignal);
         });
     }
     /**
-     * Creates route across multiple pools and protocols for best trade execution price
+     * Creates an optimal trade route for a given token input (`coinInType`) with a
+     * specified input amount (`coinInAmount`). This route may consist of multiple
+     * swaps across different DEX protocols to achieve the best price.
      *
-     * @param inputs - Details for router to construct trade route
-     * @param abortSignal - Optional signal to abort passed to fetch call
-     * @returns Routes, paths, and amounts of each smaller trade within complete trade
+     * @param inputs - Details required to construct the trade route, including `coinInType`, `coinOutType`, and `coinInAmount`.
+     * @param abortSignal - An optional signal to abort the request if needed.
+     * @returns A promise resolving to a `RouterCompleteTradeRoute` object containing the full route details.
+     *
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({
+     *   coinInType: "0x2::sui::SUI",
+     *   coinOutType: "0x<...>::coin::TOKEN",
+     *   coinInAmount: BigInt(10_000_000_000),
+     *   // optional fields:
+     *   referrer: "0x<referrer_address>",
+     *   externalFee: {
+     *     recipient: "0x<fee_collector>",
+     *     feePercentage: 0.01
+     *   },
+     *   protocolBlacklist: ["Cetus", "BlueMove"]
+     * });
+     * console.log(route);
+     * ```
      */
     getCompleteTradeRouteGivenAmountIn(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -84,11 +148,25 @@ class Router extends caller_1.Caller {
         });
     }
     /**
-     * Creates route across multiple pools and protocols for best trade execution price
+     * Creates an optimal trade route for a given token output (`coinOutType`) with a
+     * specified output amount (`coinOutAmount`). This route may consist of multiple
+     * swaps to achieve the target output amount, factoring in slippage.
+     *
+     * @param inputs - Details required to construct the trade route, including `coinInType`, `coinOutType`, `coinOutAmount`, and `slippage`.
+     * @param abortSignal - An optional signal to abort the request if needed.
+     * @returns A promise resolving to a `RouterCompleteTradeRoute` object containing the full route details.
      *
-     * @param inputs - Details for router to construct trade route
-     * @param abortSignal - Optional signal to abort passed to fetch call
-     * @returns Routes, paths, and amounts of each smaller trade within complete trade
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountOut({
+     *   coinInType: "0x2::sui::SUI",
+     *   coinOutType: "0x<...>::coin::TOKEN",
+     *   coinOutAmount: BigInt(20_000_000),
+     *   slippage: 0.01, // 1%
+     *   protocolWhitelist: ["Aftermath", "Cetus"]
+     * });
+     * console.log(route);
+     * ```
      */
     getCompleteTradeRouteGivenAmountOut(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -98,16 +176,83 @@ class Router extends caller_1.Caller {
     // =========================================================================
     //  Transactions
     // =========================================================================
+    /**
+     * Generates a transaction to execute a previously calculated complete trade route.
+     * This transaction can then be signed and executed by the user.
+     *
+     * @param inputs - An object containing the wallet address, the complete trade route, slippage tolerance, and optional sponsorship settings.
+     * @returns A promise resolving to a `Uint8Array` representing the serialized transaction.
+     *
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     * const transactionBytes = await router.getTransactionForCompleteTradeRoute({
+     *   walletAddress: "0x<your_address>",
+     *   completeRoute: route,
+     *   slippage: 0.01
+     * });
+     * // The returned bytes can now be signed and executed using your chosen wallet.
+     * ```
+     */
     getTransactionForCompleteTradeRoute(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApiTransaction("transactions/trade", inputs);
         });
     }
+    /**
+     * **Legacy method** for generating a transaction to execute a complete trade route.
+     * Uses an older version of transaction serialization.
+     *
+     * @param inputs - Similar to `getTransactionForCompleteTradeRoute` but serialized using the legacy method.
+     * @returns A promise resolving to a `Uint8Array` representing the serialized transaction.
+     *
+     * @example
+     * ```typescript
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     * const transactionBytesV0 = await router.getTransactionForCompleteTradeRouteV0({
+     *   walletAddress: "0x<your_address>",
+     *   completeRoute: route,
+     *   slippage: 0.01
+     * });
+     * // Use this if your environment requires legacy transaction structure
+     * ```
+     */
     getTransactionForCompleteTradeRouteV0(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApiTransactionV0("transactions/trade-v0", inputs);
         });
     }
+    /**
+     * Adds a trade route to an existing transaction, allowing you to build complex
+     * transactions containing multiple actions (swaps, transfers, etc.) in a single
+     * atomic transaction.
+     *
+     * @param inputs - Includes the existing `Transaction`, a complete route, slippage, wallet address, and an optional `coinInId`.
+     * @returns An object containing:
+     *  - `tx`: The updated `Transaction` including the route instructions
+     *  - `coinOutId`: A `TransactionObjectArgument` referencing the output coin after the swap
+     *
+     * @example
+     * ```typescript
+     * // 1) Create a route
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     *
+     * // 2) Initialize your transaction
+     * const tx = new Transaction();
+     *
+     * // 3) Add router instructions
+     * const { tx: updatedTx, coinOutId } =
+     *   await router.addTransactionForCompleteTradeRoute({
+     *     tx,
+     *     completeRoute: route,
+     *     slippage: 0.01,
+     *     walletAddress: "0x<your_address>"
+     * });
+     *
+     * // 4) Continue building your transaction with the resulting coinOutId, if desired
+     * updatedTx.transferObjects([coinOutId!], "0x<your_address>");
+     * ```
+     */
     addTransactionForCompleteTradeRoute(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
@@ -118,6 +263,36 @@ class Router extends caller_1.Caller {
             };
         });
     }
+    /**
+     * **Legacy method** for adding a trade route to an existing transaction.
+     * Uses an older version of transaction serialization.
+     *
+     * @param inputs - Similar to `addTransactionForCompleteTradeRoute` but returns a `TransactionBlock`.
+     * @returns An object containing:
+     *  - `tx`: The updated `TransactionBlock`
+     *  - `coinOutId`: A `TransactionObjectArgumentV0` referencing the output coin
+     *
+     * @example
+     * ```typescript
+     * // 1) Create a route
+     * const route = await router.getCompleteTradeRouteGivenAmountIn({ ... });
+     *
+     * // 2) Initialize your transaction block
+     * const txBlock = new TransactionBlock();
+     *
+     * // 3) Add router instructions (legacy)
+     * const { tx: updatedTxBlock, coinOutId } =
+     *   await router.addTransactionForCompleteTradeRouteV0({
+     *     tx: txBlock,
+     *     completeRoute: route,
+     *     slippage: 0.01,
+     *     walletAddress: "0x<your_address>"
+     * });
+     *
+     * // 4) Continue building your transaction with the resulting coinOutId
+     * updatedTxBlock.transferObjects([coinOutId!], "0x<your_address>");
+     * ```
+     */
     addTransactionForCompleteTradeRouteV0(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
@@ -131,6 +306,22 @@ class Router extends caller_1.Caller {
     // =========================================================================
     //  Events
     // =========================================================================
+    /**
+     * Retrieves trade events (interactions) for a given user based on router usage.
+     *
+     * @param inputs - Includes a `walletAddress`, cursor pagination, and limit.
+     * @returns A promise resolving to the user's `RouterTradeEvent`s, potentially paginated.
+     *
+     * @example
+     * ```typescript
+     * const events = await router.getInteractionEvents({
+     *   walletAddress: "0x<your_address>",
+     *   cursor: 0,
+     *   limit: 10
+     * });
+     * console.log(events);
+     * ```
+     */
     getInteractionEvents(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApiIndexerEvents("events-by-user", inputs);
@@ -141,9 +332,14 @@ exports.Router = Router;
 // =========================================================================
 //  Constants
 // =========================================================================
+/**
+ * Contains static information about the router, such as the maximum
+ * allowable external fee percentage.
+ */
 Router.constants = {
     /**
-     * Max fee percentage that third parties can charge on router trades
+     * The maximum external fee percentage that a third party can charge on router trades.
+     * @remarks 0.5 = 50%
      */
-    maxExternalFeePercentage: 0.5, // 50%
+    maxExternalFeePercentage: 0.5,
 };