@ickb/sdk 1000.0.82 → 9001.0.0

package/src/order/cells.ts

@@ -0,0 +1,383 @@
+import type { ccc } from "@ckb-ccc/core";
+import type { ValueComponents } from "../utils/utils.ts";
+import { OrderData } from "./order_data.ts";
+
+/**
+ * Represents a parsed order cell on the blockchain.
+ *
+ * Implements `ValueComponents` to expose the cell's raw data and its
+ * value breakdown (CKB and UDT).
+ */
+export class OrderCell implements ValueComponents {
+  /** Raw live cell that carries the order lock and UDT type. */
+  public readonly cell: ccc.Cell;
+  /** Decoded order payload from `cell.outputData`. */
+  public readonly data: OrderData;
+  /** CKB capacity available for matching after occupied capacity is reserved. */
+  public readonly ckbUnoccupied: ccc.FixedPoint;
+  /** Absolute total order value in the order's comparison units. */
+  public readonly absTotal: ccc.Num;
+  /** Absolute matched progress in the order's comparison units. */
+  public readonly absProgress: ccc.Num;
+
+  constructor({
+    cell,
+    data,
+    ckbUnoccupied,
+    absTotal,
+    absProgress,
+  }: {
+    cell: ccc.Cell;
+    data: OrderData;
+    ckbUnoccupied: ccc.FixedPoint;
+    absTotal: ccc.Num;
+    absProgress: ccc.Num;
+  }) {
+    this.cell = cell;
+    this.data = data;
+    this.ckbUnoccupied = ckbUnoccupied;
+    this.absTotal = absTotal;
+    this.absProgress = absProgress;
+  }
+
+  /**
+   * Gets the order CKB amount.
+   *
+   * @returns The CKB amount as a `ccc.FixedPoint`.
+   */
+  public get ckbValue(): ccc.FixedPoint {
+    return this.cell.cellOutput.capacity;
+  }
+
+  /**
+   * Gets the order UDT amount.
+   *
+   * @returns The UDT amount as a `ccc.FixedPoint`.
+   */
+  public get udtValue(): ccc.FixedPoint {
+    return this.data.udtValue;
+  }
+
+  /**
+   * Attempts to parse an OrderCell from a raw cell.
+   *
+   * Returns `undefined` if parsing or validation fails.
+   *
+   * @param cell - The raw chain cell to convert.
+   * @returns An `OrderCell` instance or `undefined`.
+   */
+  public static tryFrom(cell: ccc.Cell): OrderCell | undefined {
+    try {
+      return OrderCell.mustFrom(cell);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Parses and validates a raw cell as OrderCell.
+   *
+   * Throws if the cell is invalid or data validation fails.
+   *
+   * @param cell - The raw chain cell to convert.
+   * @returns A new `OrderCell` instance.
+   * @throws When decoding or validation fails.
+   */
+  public static mustFrom(cell: ccc.Cell): OrderCell {
+    let data: OrderData;
+    try {
+      data = OrderData.decode(cell.outputData);
+      data.validate();
+    } catch (error) {
+      throw new Error(`Invalid order payload at ${cell.outPoint.toHex()}`, {
+        cause: error,
+      });
+    }
+
+    const udtValue = data.udtValue;
+    const ckbUnoccupied = cell.capacityFree;
+    const { ckbToUdt, udtToCkb } = data.info;
+    const isCkb2Udt = data.info.isCkb2Udt();
+    const isUdt2Ckb = data.info.isUdt2Ckb();
+    const isDualRatio = isCkb2Udt && isUdt2Ckb;
+
+    // Compute total values in base units
+    const ckb2UdtValue = isCkb2Udt
+      ? ckbUnoccupied * ckbToUdt.ckbScale + udtValue * ckbToUdt.udtScale
+      : 0n;
+    const udt2CkbValue = isUdt2Ckb
+      ? ckbUnoccupied * udtToCkb.ckbScale + udtValue * udtToCkb.udtScale
+      : 0n;
+
+    const absTotal = absoluteOrderTotal(ckb2UdtValue, udt2CkbValue, data.info);
+    // What the order already holds of its output side; a dual-ratio order is complete.
+    let absProgress = ckbUnoccupied * udtToCkb.ckbScale;
+    if (isDualRatio) {
+      absProgress = absTotal;
+    } else if (isCkb2Udt) {
+      absProgress = udtValue * ckbToUdt.udtScale;
+    }
+
+    return new OrderCell({ cell, data, ckbUnoccupied, absTotal, absProgress });
+  }
+
+  /**
+   * Checks whether the CKB-to-UDT side is enabled and has nonzero inventory.
+   *
+   * @remarks Executable-match checks for fee, minimum output, and ratio bounds happen during matching.
+   */
+  public isCkb2UdtMatchable(): boolean {
+    return this.data.info.isCkb2Udt() && this.ckbUnoccupied > 0n;
+  }
+
+  /**
+   * Checks whether the UDT-to-CKB side is enabled and has nonzero inventory.
+   *
+   * @remarks Executable-match checks for fee, minimum output, and ratio bounds happen during matching.
+   */
+  public isUdt2CkbMatchable(): boolean {
+    return this.data.info.isUdt2Ckb() && this.data.udtValue > 0n;
+  }
+
+  /** Returns true when either side is enabled and has nonzero inventory. */
+  public isMatchable(): boolean {
+    return this.isCkb2UdtMatchable() || this.isUdt2CkbMatchable();
+  }
+
+  /**
+   * Checks if the order is fulfilled.
+   *
+   * @returns True if the order is fulfilled (not matchable), otherwise false.
+   */
+  public isFulfilled(): boolean {
+    return !this.isMatchable();
+  }
+
+  /**
+   * Retrieves the master out point of the order.
+   * @returns The master out point associated with the order.
+   */
+  public getMaster(): ccc.OutPoint {
+    return this.data.getMaster(this.cell.outPoint);
+  }
+
+  /**
+   * Whether `descendant` can be this origin order's live continuation.
+   *
+   * @remarks
+   * This confusion-attack guard requires the same order script, UDT type,
+   * master, and info, while forbidding lower total value or lower progress.
+   * See {@link https://github.com/ickb/whitepaper/issues/19}.
+   */
+  public isValid(descendant: OrderCell): boolean {
+    const udt = this.cell.cellOutput.type;
+    return (
+      this.data.isMint() &&
+      this.cell.cellOutput.lock.eq(descendant.cell.cellOutput.lock) &&
+      udt !== undefined &&
+      descendant.cell.cellOutput.type?.eq(udt) === true &&
+      descendant.getMaster().eq(this.getMaster()) &&
+      this.data.info.eq(descendant.data.info) &&
+      this.absTotal <= descendant.absTotal &&
+      this.absProgress <= descendant.absProgress
+    );
+  }
+
+  /**
+   * Resolves the best valid descendant order.
+   *
+   * @remarks
+   * The genuine mint origin is the immutable validation baseline. Resolution
+   * prefers greater progress and then greater total value; candidate identity is
+   * irrelevant. Equal-score non-mint candidates are ambiguous, while the mint
+   * origin wins an equal-score tie when it is still live.
+   */
+  public resolve(descendants: OrderCell[]): OrderCell | undefined {
+    let resolution: OrderResolution | undefined;
+    for (const descendant of descendants) {
+      if (!this.isValid(descendant)) {
+        continue;
+      }
+
+      resolution = betterOrderResolution(resolution, descendant);
+    }
+
+    if (resolution?.isAmbiguous === true) {
+      return undefined;
+    }
+
+    return resolution?.order;
+  }
+}
+
+interface OrderResolution {
+  isAmbiguous: boolean;
+  order: OrderCell;
+}
+
+function absoluteOrderTotal(
+  ckb2UdtValue: bigint,
+  udt2CkbValue: bigint,
+  info: OrderData["info"],
+): bigint {
+  if (ckb2UdtValue === 0n) {
+    return udt2CkbValue;
+  }
+  if (udt2CkbValue === 0n) {
+    return ckb2UdtValue;
+  }
+
+  const { ckbToUdt, udtToCkb } = info;
+  return (
+    (ckb2UdtValue * udtToCkb.ckbScale * udtToCkb.udtScale +
+      udt2CkbValue * ckbToUdt.ckbScale * ckbToUdt.udtScale) >>
+    1n
+  );
+}
+
+function betterOrderResolution(
+  current: OrderResolution | undefined,
+  candidate: OrderCell,
+): OrderResolution {
+  if (current === undefined || compareOrderScore(current.order, candidate) < 0) {
+    return { isAmbiguous: false, order: candidate };
+  }
+  if (compareOrderScore(current.order, candidate) > 0) {
+    return current;
+  }
+  if (current.order.cell.outPoint.eq(candidate.cell.outPoint)) {
+    return current;
+  }
+  if (candidate.data.isMint() && !current.order.data.isMint()) {
+    return { isAmbiguous: false, order: candidate };
+  }
+  if (!candidate.data.isMint() && current.order.data.isMint()) {
+    return current;
+  }
+  return { ...current, isAmbiguous: true };
+}
+
+function compareOrderScore(left: OrderCell, right: OrderCell): number {
+  if (left.absProgress !== right.absProgress) {
+    return left.absProgress < right.absProgress ? -1 : 1;
+  }
+  if (left.absTotal !== right.absTotal) {
+    return left.absTotal < right.absTotal ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Represents a master cell
+ */
+export class MasterCell {
+  /** Raw live master cell that anchors an order group. */
+  public readonly cell: ccc.Cell;
+
+  /**
+   * Creates an instance of MasterCell.
+   * @param cell - The ccc.Cell instance to be wrapped by the MasterCell.
+   */
+  constructor(cell: ccc.Cell) {
+    this.cell = cell;
+  }
+
+  /** Whether this master anchors `order`: its type is the order script and the order names it. */
+  public anchors(order: OrderCell): boolean {
+    return (
+      this.cell.cellOutput.type?.eq(order.cell.cellOutput.lock) === true &&
+      order.getMaster().eq(this.cell.outPoint)
+    );
+  }
+}
+
+/**
+ * Represents a group of orders associated with a master cell.
+ */
+export class OrderGroup implements ValueComponents {
+  /** Master cell that authorizes and anchors the current order. */
+  public readonly master: MasterCell;
+  /** Current resolved order cell. */
+  public readonly order: OrderCell;
+  /** Origin order used to validate descendant progress and identity. */
+  public readonly origin: OrderCell;
+  /** The block that committed the origin and its master: how long the order has been on the book. */
+  public readonly blockNumber: ccc.Num;
+
+  /**
+   * Creates an instance of OrderGroup.
+   * @param master - The master cell associated with the order group.
+   * @param order - The order within the group.
+   * @param origin - The original order associated with the group.
+   * @param blockNumber - The block that committed the origin and its master.
+   */
+  constructor(
+    master: MasterCell,
+    order: OrderCell,
+    origin: OrderCell,
+    blockNumber: ccc.Num,
+  ) {
+    this.master = master;
+    this.order = order;
+    this.origin = origin;
+    this.blockNumber = blockNumber;
+  }
+
+  /**
+   * Gets the CKB value of the group.
+   *
+   * @returns The total CKB amount as a `ccc.FixedPoint`, which is the sum of the CKB values of the order cell and the master cell.
+   */
+  public get ckbValue(): ccc.FixedPoint {
+    return this.order.cell.cellOutput.capacity + this.master.cell.cellOutput.capacity;
+  }
+
+  /**
+   * Gets the UDT value of the group.
+   *
+   * @returns The UDT amount as a `ccc.FixedPoint`, derived from the order cell.
+   */
+  public get udtValue(): ccc.FixedPoint {
+    return this.order.data.udtValue;
+  }
+
+  /**
+   * Tries to create an OrderGroup from the provided parameters.
+   * @param master - The master cell.
+   * @param order - The order within the group.
+   * @param origin - The original order.
+   * @returns An OrderGroup instance or undefined if creation fails.
+   */
+  public static tryFrom(
+    master: MasterCell,
+    order: OrderCell,
+    origin: OrderCell,
+    blockNumber: ccc.Num,
+  ): OrderGroup | undefined {
+    const og = new OrderGroup(master, order, origin, blockNumber);
+    if (og.isValid()) {
+      return og;
+    }
+    return undefined;
+  }
+
+  /** Whether the master anchors both orders and the order continues its origin. */
+  public isValid(): boolean {
+    return (
+      this.master.anchors(this.origin) &&
+      this.master.anchors(this.order) &&
+      this.origin.isValid(this.order)
+    );
+  }
+
+  /**
+   * Checks if the specified lock is the owner of the master cell.
+   *
+   * @param locks - The locks to check ownership against.
+   * @returns True if the lock is the owner, otherwise false.
+   */
+  public isOwner(...locks: ccc.Script[]): boolean {
+    const lock = this.master.cell.cellOutput.lock;
+    return locks.some((l) => lock.eq(l));
+  }
+}

package/src/order/conversion.ts

@@ -0,0 +1,162 @@
+import { ccc } from "@ckb-ccc/core";
+import { ckbFromUdt } from "../udt.ts";
+import { ceilDiv, type ExchangeRatio, type ValueComponents } from "../utils/utils.ts";
+import { Info } from "./info.ts";
+import { Ratio } from "./ratio.ts";
+
+const maxUint64 = (1n << 64n) - 1n;
+
+/**
+ * Error thrown when an exact quote cannot be represented by the order ratio format.
+ */
+export class OrderConversionRepresentabilityError extends Error {
+  /** Creates a representability error with the default public conversion message. */
+  constructor(
+    message = "Order conversion quote cannot be represented as Uint64 ratio",
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "OrderConversionRepresentabilityError";
+  }
+}
+
+/**
+ * Quotes a new order: the output-side amount, the CKB fee, and the order info.
+ *
+ * @remarks
+ * The returned `Info` preserves the quoted amount after fee adjustment so the
+ * minted order records the executable limit price.
+ */
+export function quoteConversion(
+  isCkb2Udt: boolean,
+  midpoint: ExchangeRatio,
+  amounts: ValueComponents,
+  { fee, feeBase }: { fee: ccc.Num; feeBase: ccc.Num },
+): { convertedAmount: ccc.FixedPoint; ckbFee: ccc.FixedPoint; info: Info } {
+  const base = Ratio.from(midpoint);
+  const amount = isCkb2Udt ? amounts.ckbValue : amounts.udtValue;
+  const { aScale, bScale } = feeAdjustedScales(base, isCkb2Udt, fee, feeBase);
+  const convertedAmount = ceilDiv(amount * aScale, bScale);
+  let ckbFee = 0n;
+
+  if (amount > 0n && fee !== 0n) {
+    ckbFee = isCkb2Udt
+      ? amount - ckbFromUdt(convertedAmount, base)
+      : ckbFromUdt(amount, base) - convertedAmount;
+  }
+
+  // Every order this SDK creates carries the default minimum match, the one the bot's
+  // remainder rule is sized to.
+  const info = Info.create(
+    isCkb2Udt,
+    quotePreservingRatio(amount, convertedAmount, isCkb2Udt),
+  );
+  return { convertedAmount, ckbFee, info };
+}
+
+/** The direction's scales with the fee taken out of the output side, reduced. */
+function feeAdjustedScales(
+  ratio: Ratio,
+  isCkb2Udt: boolean,
+  fee: ccc.Num,
+  feeBase: ccc.Num,
+): { aScale: ccc.Num; bScale: ccc.Num } {
+  if (fee < 0n) {
+    throw new Error("Fee cannot be negative");
+  }
+  if (feeBase <= 0n) {
+    throw new Error("Fee base must be positive");
+  }
+  if (fee >= feeBase) {
+    throw new Error("Fee too big relative to feeBase");
+  }
+  if (!ratio.isPopulated()) {
+    throw new Error("Invalid ExchangeRatio");
+  }
+
+  let { ckbScale: aScale, udtScale: bScale } = ratio;
+  if (!isCkb2Udt) {
+    [aScale, bScale] = [bScale, aScale];
+  }
+  aScale *= feeBase - fee;
+  bScale *= feeBase;
+  const divisor = ccc.gcd(aScale, bScale);
+  return { aScale: aScale / divisor, bScale: bScale / divisor };
+}
+
+/**
+ * The ratio that reproduces the quote exactly: the greatest Uint64 fraction at most
+ * `quotedOutput / inputAmount`, which must still round the input up to the quoted output.
+ */
+function quotePreservingRatio(
+  inputAmount: ccc.FixedPoint,
+  quotedOutput: ccc.FixedPoint,
+  isCkb2Udt: boolean,
+): Ratio {
+  if (inputAmount < 0n || quotedOutput < 0n) {
+    throw new Error("Order conversion amounts cannot be negative");
+  }
+  if (inputAmount === 0n || quotedOutput === 0n) {
+    throw new OrderConversionRepresentabilityError(
+      "Order conversion quote must have positive input and output",
+    );
+  }
+
+  const { numerator, denominator } = greatestBoundedFractionAtMost(
+    quotedOutput,
+    inputAmount,
+    maxUint64,
+  );
+  if (numerator <= 0n || (quotedOutput - 1n) * denominator >= inputAmount * numerator) {
+    throw new OrderConversionRepresentabilityError();
+  }
+
+  return Ratio.from({
+    ckbScale: isCkb2Udt ? numerator : denominator,
+    udtScale: isCkb2Udt ? denominator : numerator,
+  });
+}
+
+/**
+ * The greatest fraction at most `numerator / denominator` whose terms are at most
+ * `maxTerm`, reduced. It walks the continued fraction's convergents while they fit; the
+ * first that does not is replaced by the largest semiconvergent the bound allows, which
+ * is closer to the target than the last fitting convergent on the same side of it. Every
+ * other convergent lands above the target and is skipped.
+ */
+export function greatestBoundedFractionAtMost(
+  numerator: bigint,
+  denominator: bigint,
+  maxTerm: bigint,
+): { numerator: bigint; denominator: bigint } {
+  let best = { numerator: 0n, denominator: 1n };
+  let [previousP, previousQ, p, q] = [0n, 1n, 1n, 0n];
+  let [n, d] = [numerator, denominator];
+  while (d !== 0n) {
+    const quotient = n / d;
+    let term = quotient;
+    if (p !== 0n) {
+      term = ccc.numMin(term, (maxTerm - previousP) / p);
+    }
+    if (q !== 0n) {
+      term = ccc.numMin(term, (maxTerm - previousQ) / q);
+    }
+    const candidate = {
+      numerator: term * p + previousP,
+      denominator: term * q + previousQ,
+    };
+    if (
+      candidate.denominator > 0n &&
+      candidate.numerator * denominator <= candidate.denominator * numerator &&
+      candidate.numerator * best.denominator > best.numerator * candidate.denominator
+    ) {
+      best = candidate;
+    }
+    if (term < quotient) {
+      break;
+    }
+    [previousP, previousQ, p, q] = [p, q, candidate.numerator, candidate.denominator];
+    [n, d] = [d, n % d];
+  }
+  return best;
+}

package/src/order/fee.ts

@@ -0,0 +1,30 @@
+import { ccc } from "@ckb-ccc/core";
+import { ceilDiv } from "../utils/utils.ts";
+import type { OrderGroup } from "./cells.ts";
+
+const CELL_INPUT_SERIALIZED_SIZE = 44;
+// CellOutput table/script wrappers plus DynVec offset; output data Bytes plus offset.
+const CELL_OUTPUT_SERIALIZATION_OVERHEAD = 60;
+const OUTPUT_DATA_SERIALIZATION_OVERHEAD = 8;
+// The supported SDK completion prepares a later signer witness, inserting one
+// empty witness-vector entry for each preceding order input.
+const EMPTY_WITNESS_SERIALIZATION_SIZE = 8;
+const PREPARED_PARTIAL_SERIALIZATION_OVERHEAD =
+  CELL_INPUT_SERIALIZED_SIZE +
+  CELL_OUTPUT_SERIALIZATION_OVERHEAD +
+  OUTPUT_DATA_SERIALIZATION_OVERHEAD +
+  EMPTY_WITNESS_SERIALIZATION_SIZE;
+
+/**
+ * The mining fee one more matched order adds to a prepared transaction at the fee rate
+ * (shannons per thousand bytes): its input, its replacement output with data, and its
+ * empty witness, sized for the largest order of the pool.
+ */
+export function partialOrderFee(orderPool: OrderGroup[], feeRate: ccc.Num): bigint {
+  const orderSize = orderPool.reduce(
+    (largest, group) => Math.max(largest, group.order.cell.occupiedSize),
+    0,
+  );
+  const bytes = ccc.numFrom(orderSize + PREPARED_PARTIAL_SERIALIZATION_OVERHEAD);
+  return ceilDiv(bytes * feeRate, 1000n);
+}

package/src/order/fill.ts

@@ -0,0 +1,83 @@
+import type { ccc } from "@ckb-ccc/core";
+import type { ExchangeRatio } from "../utils/utils.ts";
+import type { OrderGroup } from "./cells.ts";
+import { partialOrderFee } from "./fee.ts";
+import { type Match, OrderMatcher } from "./matcher.ts";
+
+/**
+ * What a fill must return before the bot takes it, in mining fees of its own: the buffer
+ * for the deposits and withdrawals that rebalance the inventory it moves (user decision
+ * 2026-09-10, tuned on testnet). One rule for the bot's fills and the refused-buy
+ * classification used by the generator and interface.
+ */
+const FILL_COST_FEES = 10n;
+
+/** The cost of taking one fill, in the exchange value's unit. */
+export function fillCost(fee: bigint, { ckbScale }: ExchangeRatio): bigint {
+  return FILL_COST_FEES * fee * ckbScale;
+}
+
+/** A fill's exchange value at the DAO ratio, net of the cost of taking it. */
+export function netOf(
+  fill: Match,
+  cost: bigint,
+  { ckbScale, udtScale }: ExchangeRatio,
+): bigint {
+  return fill.ckbDelta * ckbScale + fill.udtDelta * udtScale - cost;
+}
+
+/** Whether the matcher's whole fill returns its cost. */
+export function returnsCost(
+  matcher: OrderMatcher,
+  cost: bigint,
+  exchangeRatio: ExchangeRatio,
+): boolean {
+  return netOf(matcher.match(matcher.bMaxMatch), cost, exchangeRatio) > 0n;
+}
+
+/**
+ * Whether the bot would take the whole order in the given direction. Judged on the order
+ * alone, independently of the bot's current inventory. Price and the sampled fee rate
+ * decide profitability; balances decide whether a particular turn can afford it.
+ */
+export function fillsWhole(
+  group: OrderGroup,
+  isCkb2Udt: boolean,
+  exchangeRatio: ExchangeRatio,
+  feeRate: ccc.Num,
+): boolean {
+  const fee = partialOrderFee([group], feeRate);
+  const matcher = OrderMatcher.from(group, isCkb2Udt, fee);
+  return (
+    matcher !== undefined &&
+    returnsCost(matcher, fillCost(fee, exchangeRatio), exchangeRatio)
+  );
+}
+
+/**
+ * Whether a buy fails today's whole-fill profitability rule and should be collected.
+ * DAO growth makes it less attractive, though a lower fee rate could change this result.
+ * Sells are not refused: growth can make them profitable later, so unfilled sells return
+ * only through the age cutoff ({@link isStale}).
+ */
+export function isRefused(
+  group: OrderGroup,
+  { exchangeRatio, feeRate }: { exchangeRatio: ExchangeRatio; feeRate: ccc.Num },
+): boolean {
+  return (
+    group.order.data.info.isCkb2Udt() && !fillsWhole(group, true, exchangeRatio, feeRate)
+  );
+}
+
+/** Thirty days of eight-second blocks. */
+export const STALE_ORDER_BLOCKS = (30n * 24n * 60n * 60n) / 8n;
+
+/**
+ * Whether the order has sat on the book for thirty days: whatever the reason (dust under
+ * the fill's cost, a remainder another matcher left, an ask above the market), it is
+ * collected and its funds returned. Age from the origin's block. The block count assumes
+ * eight-second blocks, not wall time.
+ */
+export function isStale(group: OrderGroup, tip: ccc.ClientBlockHeader): boolean {
+  return group.blockNumber + STALE_ORDER_BLOCKS <= tip.number;
+}