add comment

examples/example.ts

@@ -866,6 +866,9 @@ async function _swapStableExample(
 
   const swapAmount = 1_000n;
 
+  // This pool have 2 assets in config. They are [tDJED, tiUSD].
+  // Index-0 Asset is tDJED. Index-1 Asset is tiUSD.
+  // This order swap 1_000n tDJED to ... tiUSD.
   const amountOut = StableswapCalculation.calculateSwapAmount({
     inIndex: 0,
     outIndex: 1,
@@ -910,6 +913,8 @@ async function _depositStableExample(
 
   const pool = await blockfrostAdapter.getStablePoolByLpAsset(lpAsset);
 
+  // This pool have 2 assets in config. They are [tDJED, tiUSD].
+  // This order deposit 100_000n tDJED and 1_000n tiUSD to pool.
   const amountIns = [100_000n, 1_000n];
 
   const lpAmount = StableswapCalculation.calculateDeposit({
@@ -998,6 +1003,8 @@ async function _withdrawImbalanceStableExample(
 
   const withdrawAmounts = [1234n, 5678n];
 
+  // This pool have 2 assets in config. They are [tDJED, tiUSD].
+  // This order withdraw exactly 1234n tDJED and 5678n tiUSD from pool.
   const lpAmount = StableswapCalculation.calculateWithdrawImbalance({
     withdrawAmounts: withdrawAmounts,
     totalLiquidity: pool.totalLiquidity,
@@ -1039,6 +1046,8 @@ async function _zapOutStableExample(
 
   const pool = await blockfrostAdapter.getStablePoolByLpAsset(lpAsset);
 
+  // This pool have 2 assets in config. They are [tDJED, tiUSD].
+  // This order withdraw xxx tiUSD by 12345 Lp Asset from pool.
   const lpAmount = 12345n;
   const outIndex = 0;
   const amountOut = StableswapCalculation.calculateZapOut({

src/calculate.ts

@@ -627,13 +627,22 @@ export namespace StableswapCalculation {
     feeDenominator: bigint;
   };
 
+  /**
+   * @property {number} inIndex - index of asset in config assets that you want to swap
+   * @property {bigint} amountIn - amount of asset that you want to swap
+   * @property {number} outIndex - index of asset in config assets that you want to receive
+   */
   export type StableswapCalculateSwapOptions =
     CommonStableswapCalculationOptions & {
       inIndex: number;
       outIndex: number;
       amountIn: bigint;
     };
 
+  /**
+   * @property {bigint[]} amountIns - amount of assets that you want to deposit ordering by assets in config
+   * @property {bigint} totalLiquidity - amount of asset that you want to swap
+   */
   export type StableswapCalculateDepositOptions =
     CommonStableswapCalculationOptions & {
       amountIns: bigint[];
@@ -648,19 +657,29 @@ export namespace StableswapCalculation {
     totalLiquidity: bigint;
   };
 
+  /**
+   * @property {bigint[]} withdrawAmounts - exactly amount of assets that you want to withdraw ordering by assets in config
+   */
   export type StableswapCalculateWithdrawImbalanceOptions =
     CommonStableswapCalculationOptions & {
       withdrawAmounts: bigint[];
       totalLiquidity: bigint;
     };
 
+  /**
+   * @property {bigint} amountLpIn - exactly LP amount that you want to withdraw
+   * @property {number} outIndex - index of asset that you want to zap out in config assets
+   */
   export type StableswapCalculateZapOutOptions =
     CommonStableswapCalculationOptions & {
       amountLpIn: bigint;
       outIndex: number;
       totalLiquidity: bigint;
     };
 
+  /**
+   * @returns amount of asset that you want to receive.
+   */
   export function calculateSwapAmount({
     inIndex,
     outIndex,
@@ -715,6 +734,9 @@ export namespace StableswapCalculation {
     return amountOut;
   }
 
+  /**
+   * @returns amount of liquidity asset you receive.
+   */
   export function calculateDeposit({
     amountIns,
     amp,
@@ -816,6 +838,9 @@ export namespace StableswapCalculation {
     return lpAmount;
   }
 
+  /**
+   * @returns amounts of asset you can receive ordering by config assets
+   */
   export function calculateWithdraw({
     withdrawalLPAmount,
     multiples,
@@ -848,6 +873,9 @@ export namespace StableswapCalculation {
     return amountOuts;
   }
 
+  /**
+   * @returns lp asset amount you need to provide to receive exactly amount of assets in the pool
+   */
   export function calculateWithdrawImbalance({
     withdrawAmounts,
     amp,
@@ -929,6 +957,9 @@ export namespace StableswapCalculation {
     return lpAmount;
   }
 
+  /**
+   * @returns amount asset amount you want receive
+   */
   export function calculateZapOut({
     amountLpIn,
     outIndex,

src/stableswap.ts

@@ -23,6 +23,10 @@ import { NetworkEnvironment, NetworkId } from "./types/network";
 import { lucidToNetworkEnv } from "./utils/network.internal";
 import { buildUtxoToStoreDatum } from "./utils/tx.internal";
 
+/**
+ * @property {bigint} assetInIndex - Index of asset you want to swap in config assets
+ * @property {bigint} assetOutIndex - Index of asset you want to receive in config assets
+ */
 export type SwapOptions = {
   type: StableOrder.StepType.SWAP;
   assetInAmount: bigint;
@@ -50,6 +54,9 @@ export type WithdrawImbalanceOptions = {
   withdrawAmounts: bigint[];
 };
 
+/**
+ * @property {bigint} assetOutIndex - Index of asset you want to receive in config assets
+ */
 export type ZapOutOptions = {
   type: StableOrder.StepType.ZAP_OUT;
   lpAmount: bigint;