@ickb/sdk 1000.0.82 → 9001.0.0

package/src/index.ts

@@ -1,3 +1,89 @@
-export * from "./sdk.js";
-export * from "./codec.js";
-export * from "./constants.js";
+/**
+ * Public SDK for one iCKB conversion workflow: read the sampled state, quote, build and
+ * complete a conversion, sign, send, and wait.
+ *
+ * @packageDocumentation
+ */
+
+import type { ccc } from "@ckb-ccc/core";
+import type {
+  AccountState,
+  ConversionTransactionOptions,
+  ConversionTransactionResult,
+  SystemState,
+} from "./conversion/types.ts";
+import type { LockUpPolicy } from "./dao.ts";
+import type { OrderGroup } from "./order/cells.ts";
+import { IckbSdk as IckbSdkClass } from "./sdk.ts";
+import type { SupportedChain } from "./utils/chain.ts";
+
+/** The SDK an integrator drives: the state read and the conversion builder. */
+export interface IckbSdk {
+  /** Builds and completes a conversion, or returns a typed planning failure. */
+  buildConversionTransaction: (
+    options: ConversionTransactionOptions,
+  ) => Promise<ConversionTransactionResult>;
+  /** Reads system, user-order, and account state at the sampled tip's parent, under one timing policy. */
+  getL1AccountState: (
+    client: ccc.Client,
+    locks: ccc.Script[],
+    lockUp: LockUpPolicy,
+    maxFeeRate?: ccc.NumLike,
+  ) => Promise<{
+    system: SystemState;
+    userOrders: OrderGroup[];
+    account: AccountState;
+  }>;
+}
+
+/** Creates the SDK for one chain's deployment. */
+// eslint-disable-next-line @typescript-eslint/no-redeclare -- The public type and the constructor namespace intentionally share a name.
+export const IckbSdk: { fromChain: (chain: SupportedChain) => IckbSdk } = IckbSdkClass;
+
+export { DEFAULT_ORDER_FEE, DEFAULT_ORDER_FEE_BASE } from "./conversion/estimate.ts";
+export { projectConversionTransactionContext } from "./conversion/projection.ts";
+export type {
+  AccountAvailabilityProjection,
+  AccountState,
+  ConversionDirection,
+  ConversionKind,
+  ConversionNotice,
+  ConversionTransactionContext,
+  ConversionTransactionContextProjection,
+  ConversionTransactionFailureReason,
+  ConversionTransactionOptions,
+  ConversionTransactionResult,
+  SystemState,
+} from "./conversion/types.ts";
+export { WALLET_LOCK_UP } from "./dao.ts";
+export type { BroadcastDeadline, LockUpPolicy } from "./dao.ts";
+export type { IckbDepositCell, ReceiptCell } from "./logic.ts";
+export type { MasterCell, OrderCell, OrderGroup } from "./order/cells.ts";
+export {
+  OrderConversionRepresentabilityError,
+  quoteConversion,
+} from "./order/conversion.ts";
+export type { Info, InfoLike } from "./order/info.ts";
+export type { Master, MasterLike } from "./order/master.ts";
+export type { OrderData, OrderDataLike } from "./order/order_data.ts";
+export { Ratio } from "./order/ratio.ts";
+export type { Relative, RelativeLike } from "./order/relative.ts";
+export type {
+  DaoWithdrawalRequestCell,
+  OwnerCell,
+  WithdrawalGroup,
+} from "./owned_owner.ts";
+export { IckbError } from "./sdk.ts";
+export type { IckbErrorCode } from "./sdk.ts";
+export {
+  signAndSendTransaction,
+  signerAccountLocks,
+  TransactionBroadcastError,
+  TransactionExpiredError,
+} from "./send/sign_and_send_transaction.ts";
+export { TransactionWaitError, waitTransaction } from "./send/wait_transaction.ts";
+export type { WaitTransactionOptions } from "./send/wait_transaction.ts";
+export { ickbExchangeRatio } from "./udt.ts";
+export type { SupportedChain } from "./utils/chain.ts";
+export { clientCache } from "./utils/utils.ts";
+export type { ExchangeRatio, ValueComponents } from "./utils/utils.ts";

package/src/logic.ts

@@ -0,0 +1,283 @@
+import { ccc } from "@ckb-ccc/core";
+import {
+  assertDaoOutputLimit,
+  DAO_DEPOSIT_DATA,
+  DaoOutputLimitError,
+  depositMaturity,
+  isDaoDeposit,
+  pushHeaderDep,
+  type LockUpPolicy,
+} from "./dao.ts";
+import {
+  decodeReceiptData,
+  encodeReceiptData,
+  IckbUdt,
+  ickbValue,
+  receiptDataBytes,
+  type ReceiptData,
+} from "./udt.ts";
+import {
+  findCells,
+  headersByNumber,
+  type ScannedCell,
+  type ScriptDeps,
+  type ValueComponents,
+} from "./utils/utils.ts";
+
+const maxDepositQuantity = 63;
+// Receipts must carry enough capacity for phase 2 when the wallet has no other
+// CKB: one iCKB xUDT cell, one plain capacity cell, and the fee reserve.
+const phase2TxFeeReserve = ccc.One;
+
+/**
+ * A live iCKB deposit: a DAO deposit cell locked by the iCKB Logic script, valued at its
+ * deposit header.
+ */
+export interface IckbDepositCell extends ValueComponents {
+  /** The DAO deposit cell. */
+  cell: ccc.Cell;
+  /** The header of the block that committed the deposit, which values it. */
+  header: ccc.ClientBlockHeader;
+  /**
+   * The DAO claim epoch as sampled at the tip, not rolled: each reader judges it against
+   * its own {@link LockUpPolicy} with `depositMaturity`.
+   */
+  claimEpoch: ccc.Epoch;
+}
+
+/**
+ * Represents a receipt cell containing the receipt for iCKB Deposits.
+ */
+export interface ReceiptCell extends ValueComponents {
+  /** The cell associated with the receipt. */
+  cell: ccc.Cell;
+  /** The header of the block that committed the deposits, which values them. */
+  header: ccc.ClientBlockHeader;
+}
+
+/**
+ * Manages logic related to deposits and receipts in the blockchain.
+ */
+export class LogicManager implements ScriptDeps {
+  /** The iCKB Logic script used as receipt type and DAO deposit lock. */
+  public readonly script: ccc.Script;
+
+  /** Cell dependencies required to execute the iCKB Logic script. */
+  public readonly cellDeps: ccc.CellDep[];
+
+  /** The Nervos DAO script the deposits carry, with its cell deps. */
+  public readonly dao: ScriptDeps;
+
+  /** Creates the manager for one iCKB Logic deployment over one DAO deployment. */
+  constructor(script: ccc.Script, cellDeps: ccc.CellDep[], dao: ScriptDeps) {
+    this.script = script;
+    this.cellDeps = cellDeps;
+    this.dao = dao;
+  }
+
+  /** Whether the cell is an iCKB receipt: typed by the logic script with a decodable prefix. */
+  public isReceipt(cell: ccc.Cell): boolean {
+    return (
+      cell.cellOutput.type?.eq(this.script) === true &&
+      ccc.bytesFrom(cell.outputData).length >= receiptDataBytes
+    );
+  }
+
+  /** Whether the cell is a DAO deposit locked by the logic script. */
+  public isDeposit(cell: ccc.Cell): boolean {
+    return isDaoDeposit(cell, this.dao.script) && cell.cellOutput.lock.eq(this.script);
+  }
+
+  /**
+   * Adds `depositQuantity` DAO deposits of `depositCapacity` locked by the logic script,
+   * then the receipt that mints their iCKB in phase 2, locked by `lock`.
+   *
+   * @remarks Completion (`IckbSdk.completeTransaction`) adds the dep group that also
+   * resolves the xUDT script.
+   */
+  public deposit(
+    txLike: ccc.TransactionLike,
+    depositQuantity: number,
+    depositCapacity: ccc.FixedPoint,
+    lock: ccc.Script,
+  ): ccc.Transaction {
+    // A zero quantity would mint a receipt for no deposits, which iCKB Logic refuses on chain.
+    if (!Number.isSafeInteger(depositQuantity) || depositQuantity <= 0) {
+      throw new TypeError("iCKB deposit quantity must be a positive safe integer");
+    }
+    const tx = ccc.Transaction.from(txLike);
+    if (depositQuantity > maxDepositQuantity) {
+      // The completion walk steps a plan down on this error.
+      throw new DaoOutputLimitError(tx.outputs.length + depositQuantity + 1);
+    }
+
+    const depositCell = ccc.Cell.from({
+      previousOutput: { txHash: `0x${"00".repeat(32)}`, index: 0 },
+      cellOutput: { capacity: depositCapacity, lock: this.script, type: this.dao.script },
+      outputData: DAO_DEPOSIT_DATA,
+    });
+    const depositAmount = depositCell.capacityFree;
+    if (depositAmount < ccc.fixedPointFrom(1000)) {
+      throw new Error(
+        "iCKB deposit minimum is 1000 CKB free capacity (1082 CKB total capacity)",
+      );
+    }
+    if (depositAmount > ccc.fixedPointFrom(1000000)) {
+      throw new Error(
+        "iCKB deposit maximum is 1000000 CKB free capacity (1000082 CKB total capacity)",
+      );
+    }
+
+    tx.addCellDeps(this.cellDeps);
+    tx.addCellDeps(this.dao.cellDeps);
+    for (let i = 0; i < depositQuantity; i += 1) {
+      tx.addOutput(depositCell.cellOutput, depositCell.outputData);
+    }
+    // Receipts track the deposit's free capacity, not the full DAO cell capacity.
+    tx.addOutput(
+      { capacity: receiptPhase2Capacity(lock), lock, type: this.script },
+      encodeReceiptData({ depositQuantity: BigInt(depositQuantity), depositAmount }),
+    );
+    assertDaoOutputLimit(tx, this.dao.script);
+    return tx;
+  }
+
+  /**
+   * Adds receipt inputs and their deposit header deps for iCKB deposit completion.
+   *
+   * @remarks This prepares the phase-2 inputs; the iCKB they mint is completed by
+   * `IckbSdk.completeTransaction`.
+   */
+  public completeDeposit(
+    txLike: ccc.TransactionLike,
+    receipts: ReceiptCell[],
+  ): ccc.Transaction {
+    const tx = ccc.Transaction.from(txLike);
+    if (receipts.length === 0) {
+      return tx;
+    }
+    for (const receipt of receipts) {
+      const outPoint = receipt.cell.outPoint.toHex();
+      if (!this.isReceipt(receipt.cell)) {
+        throw new Error(
+          `Receipt ${outPoint} is not an iCKB receipt for this logic script`,
+        );
+      }
+    }
+    tx.addCellDeps(this.cellDeps);
+    for (const receipt of receipts) {
+      pushHeaderDep(tx, receipt.header.hash);
+      tx.addInput(receipt.cell);
+    }
+    return tx;
+  }
+
+  /**
+   * The receipts among `cells`, valued at their deposit headers, each header read once.
+   */
+  public async receiptsFrom(
+    client: ccc.Client,
+    cells: readonly ScannedCell[],
+  ): Promise<ReceiptCell[]> {
+    const receipts = cells.filter(({ cell }) => this.isReceipt(cell));
+    const headers = await headersByNumber(
+      client,
+      receipts.map(({ blockNumber }) => blockNumber),
+    );
+    return receipts.map(({ cell, blockNumber }) =>
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every receipt's block was read above.
+      receiptCell(cell, headers.get(blockNumber)!),
+    );
+  }
+
+  /**
+   * Every live iCKB deposit, valued at its deposit header, with its claim epoch at the tip;
+   * each deposit block's header is read once.
+   */
+  public async findDeposits(
+    client: ccc.Client,
+    tip: ccc.ClientBlockHeader,
+  ): Promise<IckbDepositCell[]> {
+    const cells = (
+      await findCells(client, {
+        script: this.script,
+        scriptType: "lock",
+        filter: {
+          script: this.dao.script,
+          outputData: DAO_DEPOSIT_DATA,
+          outputDataSearchMode: "exact",
+        },
+        scriptSearchMode: "exact",
+        withData: true,
+      })
+    ).filter(({ cell }) => this.isDeposit(cell));
+    const headers = await headersByNumber(
+      client,
+      cells.map(({ blockNumber }) => blockNumber),
+    );
+    return cells.map(({ cell, blockNumber }) =>
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- every deposit's block was read above.
+      ickbDepositCell(cell, headers.get(blockNumber)!, tip),
+    );
+  }
+}
+
+/** Values a DAO deposit cell at its deposit header and samples its claim epoch at the tip. */
+function ickbDepositCell(
+  cell: ccc.Cell,
+  header: ccc.ClientBlockHeader,
+  tip: ccc.ClientBlockHeader,
+): IckbDepositCell {
+  const interests = ccc.calcDaoProfit(cell.capacityFree, header, tip);
+  return {
+    cell,
+    header,
+    claimEpoch: ccc.calcDaoClaimEpoch(header, tip),
+    ckbValue: cell.cellOutput.capacity + interests,
+    udtValue: ickbValue(cell.capacityFree, header),
+  };
+}
+
+/** The deposits a withdrawal request made now may claim at their sampled dates under the policy. */
+export function readyDeposits(
+  deposits: readonly IckbDepositCell[],
+  tip: ccc.ClientBlockHeader,
+  policy: LockUpPolicy,
+): IckbDepositCell[] {
+  return deposits.filter(
+    (deposit) => depositMaturity(deposit.claimEpoch, tip, policy).isReady,
+  );
+}
+
+/** Decodes a receipt cell and values it at its deposit header. */
+export function receiptCell(cell: ccc.Cell, header: ccc.ClientBlockHeader): ReceiptCell {
+  let receipt: ReceiptData;
+  try {
+    receipt = decodeReceiptData(cell.outputData);
+  } catch (error) {
+    throw new Error(
+      `Invalid iCKB receipt payload at ${cell.outPoint.toHex()}: ${cell.outputData}`,
+      { cause: error },
+    );
+  }
+  return {
+    cell,
+    header,
+    ckbValue: cell.cellOutput.capacity,
+    udtValue: ickbValue(receipt.depositAmount, header) * receipt.depositQuantity,
+  };
+}
+
+/**
+ * Returns the CKB needed for the two phase-2 outputs created by one receipt.
+ *
+ * @remarks The value is sized with the actual user lock because lock args affect
+ * occupied capacity. It includes one plain output, one xUDT output, and the
+ * phase-2 fee reserve.
+ */
+export function receiptPhase2Capacity(lock: ccc.Script): ccc.FixedPoint {
+  // Capacity is measured with the actual user lock. Lock args are wallet-specific
+  // and can make both phase-2 outputs larger than protocol-only examples.
+  const plainCellCapacity = BigInt(8 + lock.occupiedSize) * ccc.One;
+  return plainCellCapacity + IckbUdt.minimumXudtCellCapacity(lock) + phase2TxFeeReserve;
+}