@ickb/sdk 1000.0.43 → 1000.0.52

package/src/index.ts

@@ -11,6 +11,7 @@ import {
   asyncBinarySearch,
   RestrictedTransaction,
   type ExchangeRatio,
+  binarySearch,
 } from "@ickb/utils";
 import {
   convert,
@@ -31,61 +32,94 @@ import {
   type OrderGroup,
 } from "@ickb/order";
 
+/**
+ * Controller for managing iCKB operations.
+ */
 export class IckbController {
+  /**
+   * Creates an instance of IckbController.
+   * @param ickbUdtManager - The manager for iCKB UDT operations.
+   * @param logicManager - The logic manager for handling business logic.
+   * @param ownedOwnerManager - The manager for owned owner operations.
+   * @param orderManager - The manager for order operations.
+   * @param daoManager - The manager for DAO operations.
+   */
   constructor(
     public readonly ickbUdtManager: IckbUdtManager,
     public readonly logicManager: LogicManager,
     public readonly ownedOwnerManager: OwnedOwnerManager,
     public readonly orderManager: OrderManager,
     public readonly daoManager: DaoManager,
+    public readonly bots: ccc.Script[],
   ) {}
 
-  static fromDeps({
-    xudt,
-    dao,
-    ickbLogic,
-    ownedOwner,
-    order,
-  }: {
-    xudt: ScriptDeps;
-    dao: ScriptDeps;
-    ickbLogic: ScriptDeps;
-    ownedOwner: ScriptDeps;
-    order: ScriptDeps;
-  }): IckbController {
-    const daoManager = DaoManager.fromDeps(dao);
-
+  /**
+   * Creates an instance of IckbController from script dependencies.
+   * @param deps - The script dependencies.
+   * @param deps.udt - The script dependencies for UDT.
+   * @param deps.dao - The script dependencies for DAO.
+   * @param deps.ickbLogic - The script dependencies for iCKB logic.
+   * @param deps.ownedOwner - The script dependencies for owned owner.
+   * @param deps.order - The script dependencies for order.
+   * @returns An instance of IckbController.
+   */
+  static fromDeps(
+    deps: {
+      udt: ScriptDeps;
+      dao: ScriptDeps;
+      ickbLogic: ScriptDeps;
+      ownedOwner: ScriptDeps;
+      order: ScriptDeps;
+    },
+    bots: ccc.Script[],
+  ): IckbController {
     const {
-      script: { codeHash, hashType },
-      cellDeps,
-    } = xudt;
-    const ickbXudt = {
+      udt: {
+        script: { codeHash, hashType },
+        cellDeps,
+      },
+      ickbLogic: { script: ickbLogicScript },
+    } = deps;
+
+    const daoManager = DaoManager.fromDeps(deps);
+    const udt = {
       script: new ccc.Script(
         codeHash,
         hashType,
-        [ickbLogic.script.hash(), "00000080"].join("") as ccc.Hex,
+        [ickbLogicScript.hash(), "00000080"].join("") as ccc.Hex,
       ),
       cellDeps,
     };
-    const ickbUdtManager = IckbUdtManager.fromDeps(ickbXudt, daoManager);
+    const ickbUdtManager = IckbUdtManager.fromDeps({ udt }, daoManager);
 
     return new IckbController(
       ickbUdtManager,
-      LogicManager.fromDeps(ickbLogic, daoManager, ickbUdtManager),
-      OwnedOwnerManager.fromDeps(ownedOwner, daoManager, ickbUdtManager),
-      OrderManager.fromDeps(order, ickbUdtManager),
+      LogicManager.fromDeps(deps, daoManager, ickbUdtManager),
+      OwnedOwnerManager.fromDeps(deps, daoManager, ickbUdtManager),
+      OrderManager.fromDeps(deps, ickbUdtManager),
       daoManager,
+      bots,
     );
   }
 
-  // fee examples:
-  // 100000n => 0.001%
-  // 10000n => 0.01%
-  // 1000n => 0.1%
-  // 100n => 1%
-  // 10n => 10%
-  // 1n => 100%
-  // less than 1n => 0%
+  /**
+   * Previews the conversion between CKB and UDT.
+   * @param conversion - The conversion parameters.
+   * @param conversion.isCkb2Udt - Indicates if the conversion is from CKB to UDT.
+   * @param conversion.amount - The amount to convert.
+   * @param conversion.rate - The exchange rate for conversion.
+   * @param conversion.fee - The fee for the conversion.
+   * @returns The rate and converted amount.
+   *
+   * Fee meaning examples:
+   * - 100000n => 0.001%
+   * - 10000n => 0.01%
+   * - 1000n => 0.1%
+   * - 100n => 1%
+   * - 10n => 10%
+   * - 1n => 100%
+   * - less than 1n => 0%
+   */
   static previewConversion(conversion: {
     isCkb2Udt: boolean;
     amount: ccc.FixedPoint;
@@ -111,6 +145,23 @@ export class IckbController {
     return { rate, convertedAmount };
   }
 
+  /**
+   * Converts between CKB and UDT based on the provided options.
+   * @param options - The conversion options.
+   * @param options.conversion - The conversion parameters.
+   * @param options.conversion.isCkb2Udt - Indicates if the conversion is from CKB to UDT.
+   * @param options.conversion.amount - The amount to convert.
+   * @param options.conversion.rate - The exchange rate for conversion.
+   * @param options.conversion.ckbMinMatchLog - Minimum CKB match log (optional).
+   * @param options.conversion.ckbMinFee - Minimum CKB fee (optional).
+   * @param options.signer - The signer for the transaction.
+   * @param options.userCells - The user's cells.
+   * @param options.system - The current system state.
+   * @param options.filters - The filters for the conversion.
+   * @param options.filters.isReadyOnly - Indicates if only ready conversions should be considered.
+   * @param options.filters.isFulfilledOnly - Indicates if only fulfilled conversions should be considered.
+   * @returns A promise that resolves to the conversion result or undefined.
+   */
   async convert(options: {
     conversion: Parameters<typeof IckbController.previewConversion>[0] & {
       ckbMinMatchLog?: number;
@@ -166,6 +217,19 @@ export class IckbController {
     );
   }
 
+  /**
+   * Attempts to perform a conversion based on the provided parameters.
+   * @param n - The size of deposit to make or withdraw from.
+   * @param conversion - The conversion parameters.
+   * @param conversion.isCkb2Udt - Indicates if the conversion is from CKB to UDT.
+   * @param conversion.amount - The amount to convert.
+   * @param conversion.rate - The exchange rate for conversion.
+   * @param conversion.info - Additional information for the conversion.
+   * @param conversion.ckbMinFee - Minimum CKB fee.
+   * @param conversion.lock - The script lock for the transaction.
+   * @param options - Additional options for the conversion.
+   * @returns A promise that resolves to the conversion result or undefined.
+   */
   private async attempt(
     n: number,
     conversion: {
@@ -180,13 +244,14 @@ export class IckbController {
   ): ReturnType<IckbController["convert"]> {
     try {
       const { isCkb2Udt, rate, info, ckbMinFee, lock } = conversion;
-      const { signer, userCells, system, filters } = options;
-      const { feeRate, depositPool, ckbDepositCap, exchangeRatio } = system;
+      const { signer, userCells, filters, system } = options;
+      const { feeRate, ckbDepositCap, exchangeRatio, depositPool } = system;
 
       const tx = SmartTransaction.default();
-      const maturities: ccc.Epoch[] = [];
+      const maturities: ccc.Epoch[] = [[0n, 1n, 80n]]; // 3 minutes minimum
       let ckbFee = ccc.Zero;
       let amount = conversion.amount;
+      let udtWithdrawed = ccc.Zero;
 
       // Core protocol
       if (n > 0) {
@@ -200,7 +265,8 @@ export class IckbController {
         } else {
           const myDeposits = depositPool.slice(0, n);
           // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-          amount -= myDeposits.slice(-1)[0]!.udtCumulative;
+          udtWithdrawed = myDeposits.slice(-1)[0]!.udtCumulative;
+          amount -= udtWithdrawed;
           if (amount < ccc.Zero) {
             // Too many Withdrawal Requests respectfully to the amount
             return undefined;
@@ -223,14 +289,13 @@ export class IckbController {
           : convert(true, amount, exchangeRatio) - convertedAmount;
 
         maturities.push(
-          // TODO: use real world data from deposits, open orders and bot balances
-          orderMaturityEstimate(isCkb2Udt, amount, system.tip),
+          orderMaturityEstimate(isCkb2Udt, amount, udtWithdrawed, system),
         );
-      }
 
-      // Check that order provides enough fee to the bot for being matched
-      if (ckbFee < ckbMinFee) {
-        return undefined;
+        // Check that order provides enough fee to the bot for being matched
+        if (ckbFee < ckbMinFee) {
+          return undefined;
+        }
       }
 
       const { receipts, withdrawalGroups, orders, udts, capacities } =
@@ -262,9 +327,19 @@ export class IckbController {
     }
   }
 
+  /**
+   * Retrieves the L1 state based on the provided parameters.
+   * @param client - The client to interact with the blockchain.
+   * @param filter - The set of filters to apply.
+   * @param locks - The script locks to filter the user cells.
+   * @param options - Optional parameters for the state retrieval.
+   * @param options.minLockUp - The minimum lock-up period (optional).
+   * @param options.maxLockUp - The maximum lock-up period (optional).
+   * @returns A promise that resolves to an object containing the system state and user cells.
+   */
   async getL1State(
     client: ccc.Client,
-    filter: Set<keyof UserCells | "depositPool">,
+    filter: Set<keyof UserCells | "depositPool" | "ckbBots">,
     locks: ccc.Script[],
     options?: {
       minLockUp?: ccc.Epoch;
@@ -287,6 +362,7 @@ export class IckbController {
       orders,
       deposits,
       withdrawalRequests,
+      botCapacities,
     ] = await Promise.all([
       client.getFeeRate(),
       filter.has("depositPool")
@@ -313,7 +389,9 @@ export class IckbController {
       filter.has("withdrawalRequests")
         ? collect(this.daoManager.findWithdrawalRequests(client, locks, opts))
         : [],
-      // TODO: fetch bot cells for estimating timings
+      filter.has("ckbBots")
+        ? collect(CapacityManager.findCapacities(client, locks, opts))
+        : [],
     ]);
 
     // Sort depositPool by maturity
@@ -339,6 +417,12 @@ export class IckbController {
     const exchangeRatio = ickbExchangeRatio(tip);
     const ckbDepositCap = convert(false, ICKB_DEPOSIT_CAP, exchangeRatio);
 
+    // Calculate the ckb ready to match incoming transactions
+    let ckbBots = botCapacities.reduce((acc, c) => acc + c.ckbValue, ccc.Zero);
+    // Each bot keeps a reserve of CKB for operations
+    ckbBots -= ccc.numFrom(this.bots.length) * ccc.fixedPointFrom("2000");
+    ckbBots = ckbBots > ccc.Zero ? ckbBots : ccc.Zero;
+
     return {
       system: {
         feeRate,
@@ -348,6 +432,7 @@ export class IckbController {
         udtDepositCap: ICKB_DEPOSIT_CAP,
         depositPool: cumulativeDepositPool,
         orderPool: nonUserOrders,
+        ckbBots,
       },
       user: {
         capacities,
@@ -362,46 +447,127 @@ export class IckbController {
   }
 }
 
+/**
+ * Represents the state of the system.
+ */
 export interface SystemState {
+  /** The fee rate for transactions. */
   feeRate: ccc.Num;
+
+  /** The tip for the current block header. */
   tip: ccc.ClientBlockHeader;
-  exchangeRatio: {
-    ckbScale: ccc.Num;
-    udtScale: ccc.Num;
-  };
+
+  /** The exchange ratio between CKB and UDT. */
+  exchangeRatio: ExchangeRatio;
+
+  /** The deposit cap expressed in CKB. */
   ckbDepositCap: ccc.FixedPoint;
+
+  /** The deposit cap expressed in iCKB. */
   udtDepositCap: ccc.FixedPoint;
+
+  /**
+   * The deposit pool containing iCKB deposit cells with cumulative iCKB amounts.
+   */
   depositPool: (IckbDepositCell & { udtCumulative: bigint })[];
+
+  /**
+   * The order pool containing non-user order cells.
+   */
   orderPool: OrderCell[];
+
+  /**
+   * The ckb held by bots ready to match incoming iCKB to CKB conversions.
+   */
+  ckbBots: ccc.FixedPoint;
 }
 
+/**
+ * Represents the user cells in the system.
+ */
 export interface UserCells {
+  /** The capacities owned by the user. */
   capacities: CapacityCell[];
+
+  /** The UDTs owned by the user. */
   udts: UdtCell[];
+
+  /** The receipts associated with the user's transactions. */
   receipts: ReceiptCell[];
+
+  /** The withdrawal groups for the user. */
   withdrawalGroups: WithdrawalGroup[];
+
+  /** The orders placed by the user. */
   orders: OrderGroup[];
+
+  /** The classical/non-iCKB deposits made by the user. */
   deposits: DaoCell[];
+
+  /** The classical/non-iCKB withdrawal requests made by the user. */
   withdrawalRequests: DaoCell[];
 }
 
+/**
+ * Represents a conversion transaction.
+ */
 export interface Conversion {
+  /** The smart transaction associated with the conversion. */
   tx: SmartTransaction;
+
+  /** The fee in CKB for the order created by the conversion. */
   ckbFee: ccc.FixedPoint;
+
+  /** The estimated maturity epoch for conversion. */
   maturity: ccc.Epoch;
 }
 
-// Estimate bot ability to fulfill orders:
-// - CKB to iCKB orders at 100k CKB every minute
-// - iCKB to CKB orders at 200 CKB every minute
+/**
+ * Estimates the maturity of an order based on the type of conversion and amount.
+ *
+ * @param isCkb2Udt - A boolean indicating if the order is from CKB to UDT.
+ * @param amount - The amount of CKB or UDT involved in the order.
+ * @param udtWithdrawed - The amount of UDT that has been withdrawn by the current conversion via core.
+ * @param system - The current system state, which includes the block header tip, order pool, deposit pool, CKB bots, and exchange ratio.
+ *
+ * @returns The estimated maturity epoch for the order.
+ */
 function orderMaturityEstimate(
   isCkb2Udt: boolean,
   amount: bigint,
-  tip: ccc.ClientBlockHeader,
+  udtWithdrawed: ccc.FixedPoint,
+  system: SystemState,
 ): ccc.Epoch {
-  return epochAdd(tip.epoch, [
+  const { tip, orderPool, depositPool, ckbBots, exchangeRatio } = system;
+
+  // Maturity estimate a priori, the estimation is based on:
+  // - CKB to iCKB orders at 100k CKB every minute
+  // - iCKB to CKB orders at 200 CKB every minute
+  let maturity = epochAdd(tip.epoch, [
     0n,
     1n + amount / ccc.fixedPointFrom(isCkb2Udt ? 100000 : 200),
     4n * 60n,
   ]);
+
+  if (isCkb2Udt) {
+    return maturity;
+  }
+
+  if (depositPool.length > 0) {
+    const udtWaiting = orderPool
+      .filter((o) => o.isUdt2CkbMatchable())
+      .reduce((acc, o) => acc + o.udtValue, ccc.Zero);
+    const udtAvailable = convert(isCkb2Udt, ckbBots, exchangeRatio);
+
+    const udtToConvert = amount + udtWithdrawed + udtWaiting - udtAvailable;
+    const i = binarySearch(
+      depositPool.length,
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      (n) => depositPool[n]!.udtCumulative >= udtToConvert,
+    );
+
+    maturity = depositPool[i]?.maturity ?? maturity;
+  }
+
+  return maturity;
 }