@ickb/sdk 1000.0.81 → 9000.0.1

package/src/order/order.ts

@@ -0,0 +1,302 @@
+import { ccc } from "@ckb-ccc/core";
+import { findCells, type ScriptDeps, type ValueComponents } from "../utils/utils.ts";
+import {
+  attestResolvedOrderGroup,
+  MasterCell,
+  OrderCell,
+  OrderGroup,
+  validatedOrderGroup,
+} from "./cells.ts";
+import { Info, type InfoLike } from "./info.ts";
+import type { Match } from "./matcher.ts";
+import { OrderData } from "./order_data.ts";
+import { Relative } from "./relative.ts";
+
+type TransactionResponse = Awaited<ReturnType<ccc.Client["getTransaction"]>>;
+
+/**
+ * Builds and scans iCKB Stack order cells for one order script deployment.
+ */
+export class OrderManager implements ScriptDeps {
+  /** Order lock script this manager scans and builds for. */
+  public readonly script: ccc.Script;
+  /** Cell deps required to execute the order script. */
+  public readonly cellDeps: ccc.CellDep[];
+  /** UDT type script accepted by this order market. */
+  public readonly udtScript: ccc.Script;
+
+  /**
+   * Creates an order manager for one order script, its cell deps, and UDT type.
+   */
+  constructor(script: ccc.Script, cellDeps: ccc.CellDep[], udtScript: ccc.Script) {
+    this.script = script;
+    this.cellDeps = cellDeps;
+    this.udtScript = udtScript;
+  }
+
+  /** Returns true when the cell is an order cell for this manager's scripts. */
+  public isOrder(cell: ccc.Cell): boolean {
+    return (
+      cell.cellOutput.lock.eq(this.script) &&
+      Boolean(cell.cellOutput.type?.eq(this.udtScript))
+    );
+  }
+
+  /**
+   * Adds a new order cell and its master cell to a partial transaction.
+   *
+   * @remarks
+   * The order output is locked by the order script and typed by the configured
+   * UDT. The following master output is typed by the order script and locked by
+   * the caller-provided lock.
+   */
+  public mint(
+    txLike: ccc.TransactionLike,
+    lock: ccc.Script,
+    infoLike: InfoLike,
+    { ckbValue, udtValue }: ValueComponents,
+  ): ccc.Transaction {
+    const tx = ccc.Transaction.from(txLike);
+    const data = OrderData.from({
+      udtValue,
+      master: { type: "relative", value: Relative.create(1n) },
+      info: Info.from(infoLike),
+    });
+    data.validate();
+    if (ckbValue < 0n) {
+      throw new Error("ckbValue invalid, negative");
+    }
+
+    tx.addCellDeps(this.cellDeps);
+    const outputCount = tx.addOutput(
+      { lock: this.script, type: this.udtScript },
+      data.toBytes(),
+    );
+    const orderOutput = tx.outputs[outputCount - 1];
+    if (orderOutput === undefined) {
+      throw new Error("Failed to append order output");
+    }
+    orderOutput.capacity += ckbValue;
+    tx.addOutput({ lock, type: this.script });
+    return tx;
+  }
+
+  /**
+   * Adds inputs and partial outputs for a chosen match.
+   */
+  public addMatch(txLike: ccc.TransactionLike, match: Match): ccc.Transaction {
+    const tx = ccc.Transaction.from(txLike);
+    const partials = match.partials.map((partial) => this.validatedPartial(partial));
+    let ckbDelta = 0n;
+    let udtDelta = 0n;
+    for (const { group, ckbOut, udtOut } of partials) {
+      ckbDelta += group.order.ckbValue - ckbOut;
+      udtDelta += group.order.udtValue - udtOut;
+    }
+    if (match.ckbDelta !== ckbDelta || match.udtDelta !== udtDelta) {
+      throw new Error("Match deltas do not match partial order accounting");
+    }
+    if (partials.length === 0) {
+      return tx;
+    }
+
+    tx.addCellDeps(this.cellDeps);
+    for (const { group, ckbOut, udtOut } of partials) {
+      const { order } = group;
+      tx.addInput(order.cell);
+      tx.addOutput(
+        { lock: this.script, type: this.udtScript, capacity: ckbOut },
+        OrderData.from({
+          udtValue: udtOut,
+          master: { type: "absolute", value: order.getMaster() },
+          info: order.data.info,
+        }).toBytes(),
+      );
+    }
+    return tx;
+  }
+
+  /**
+   * Adds order groups and their master cells as melt inputs.
+   *
+   * @remarks Melts exactly the groups it is given: callers pass fulfilled groups
+   * to collect and a live group to cancel it.
+   */
+  public melt(txLike: ccc.TransactionLike, groups: OrderGroup[]): ccc.Transaction {
+    const tx = ccc.Transaction.from(txLike);
+    const selected = groups.map(validatedOrderGroup);
+    if (selected.length === 0) {
+      return tx;
+    }
+    for (const group of selected) {
+      if (!this.isOrder(group.order.cell)) {
+        throw new Error(
+          `Melt order ${group.order.cell.outPoint.toHex()} does not match this order manager`,
+        );
+      }
+    }
+    tx.addCellDeps(this.cellDeps);
+    for (const group of selected) {
+      tx.addInput(group.order.cell);
+      tx.addInput(group.master.cell);
+    }
+    return tx;
+  }
+
+  /**
+   * Finds valid order groups by scanning order cells and master cells. Unresolved or
+   * invalid groups are skipped.
+   */
+  public async findOrders(client: ccc.Client): Promise<OrderGroup[]> {
+    const [orders, masters] = await Promise.all([
+      this.findSimpleOrders(client),
+      this.findAllMasters(client),
+    ]);
+    const rawGroups = new Map(
+      masters.map((master) => [
+        master.cell.outPoint.toHex(),
+        { master, orders: new Array<OrderCell>() },
+      ]),
+    );
+    for (const order of orders) {
+      rawGroups.get(order.getMaster().toHex())?.orders.push(order);
+    }
+
+    // Each group's origin is one transaction read; resolving them together turns a book of
+    // fifty orders from seconds of round trips into one.
+    const groups = await Promise.all(
+      [...rawGroups.values()]
+        .filter((rawGroup) => rawGroup.orders.length > 0)
+        .map(async ({ master, orders: candidates }) =>
+          this.resolveOrderGroup(client, master, candidates),
+        ),
+    );
+    return groups.filter((group) => group !== undefined);
+  }
+
+  private async findSimpleOrders(client: ccc.Client): Promise<OrderCell[]> {
+    const cells = await findCells(client, {
+      script: this.script,
+      scriptType: "lock",
+      filter: { script: this.udtScript },
+      scriptSearchMode: "exact",
+      withData: true,
+    });
+    return cells.flatMap((cell) => {
+      const order = OrderCell.tryFrom(cell);
+      return order !== undefined && this.isOrder(cell) ? [order] : [];
+    });
+  }
+
+  private async findAllMasters(client: ccc.Client): Promise<MasterCell[]> {
+    // An exact type search returns master cells only, so nothing re-filters here.
+    const cells = await findCells(client, {
+      script: this.script,
+      scriptType: "type",
+      scriptSearchMode: "exact",
+      withData: true,
+    });
+    return cells.map((cell) => new MasterCell(cell));
+  }
+
+  /** Resolves one master and its descendant orders into a validated order group. */
+  private async resolveOrderGroup(
+    client: ccc.Client,
+    master: MasterCell,
+    orders: OrderCell[],
+  ): Promise<OrderGroup | undefined> {
+    const found = await this.findOrigin(client, master.cell.outPoint);
+    const order = found?.origin.resolve(orders);
+    if (found === undefined || order === undefined) {
+      return undefined;
+    }
+    const group = OrderGroup.tryFrom(master, order, found.origin, found.blockNumber);
+    // A dual-ratio order, valid on chain but placed by nothing in the stack, is left to
+    // whoever placed it: neither matched, estimated, shown nor melted here.
+    if (group === undefined || group.order.data.info.isDualRatio()) {
+      return undefined;
+    }
+    return attestResolvedOrderGroup(group);
+  }
+
+  /**
+   * The mint order created beside the master, read from the master's transaction: the
+   * client cache first, then the node, recording the response for the next read. The
+   * response's block number dates the order; an uncommitted origin has none.
+   */
+  private async findOrigin(
+    client: ccc.Client,
+    master: ccc.OutPoint,
+  ): Promise<{ origin: OrderCell; blockNumber: ccc.Num | undefined } | undefined> {
+    const { txHash, index: masterIndex } = master;
+    const response = await cachedTransactionResponse(client, txHash);
+    if (response === undefined) {
+      return undefined;
+    }
+
+    let origin: OrderCell | undefined;
+    for (const [i, output] of [...response.transaction.outputCells].entries()) {
+      const index = BigInt(i);
+      if (index === masterIndex) {
+        continue;
+      }
+      const cell = ccc.Cell.from({
+        cellOutput: output.cellOutput,
+        outputData: output.outputData,
+        outPoint: { txHash, index },
+      });
+      const order = OrderCell.tryFrom(cell);
+      if (
+        order === undefined ||
+        !this.isOrder(cell) ||
+        !order.data.isMint() ||
+        !order.getMaster().eq(master)
+      ) {
+        continue;
+      }
+      if (origin !== undefined) {
+        // Two mint orders pointing at one master: the group is ambiguous, skip it.
+        return undefined;
+      }
+      origin = order;
+    }
+    return origin === undefined
+      ? undefined
+      : { origin, blockNumber: response.blockNumber };
+  }
+
+  private validatedPartial({
+    group,
+    ckbOut,
+    udtOut,
+  }: Match["partials"][number]): Match["partials"][number] {
+    const validated = validatedOrderGroup(group);
+    const outPoint = validated.order.cell.outPoint.toHex();
+    if (!this.isOrder(validated.order.cell)) {
+      throw new Error(`Match order ${outPoint} does not match this order manager`);
+    }
+    if (ckbOut < 0n) {
+      throw new Error(`Match order ${outPoint} has negative CKB output`);
+    }
+    if (udtOut < 0n) {
+      throw new Error(`Match order ${outPoint} has negative UDT output`);
+    }
+    return { group: validated, ckbOut, udtOut };
+  }
+}
+
+async function cachedTransactionResponse(
+  client: ccc.Client,
+  txHash: ccc.Hex,
+): Promise<TransactionResponse | undefined> {
+  // As CCC's own readers do, trust the cache only once the transaction is in a block: the
+  // cache also holds what CCC records at broadcast and what a lagging node answered, and a
+  // long-lived client would otherwise keep that answer for good.
+  const cached = await client.cache.getTransactionResponse(txHash);
+  if (cached?.blockNumber !== undefined) {
+    return cached;
+  }
+
+  // CCC's read records a found response in the cache itself.
+  return client.getTransaction(txHash);
+}

package/src/order/order_data.ts

@@ -0,0 +1,128 @@
+import { ccc, mol } from "@ckb-ccc/core";
+import { CheckedUint128LE } from "../utils/codec.ts";
+import { Info, type InfoLike } from "./info.ts";
+import {
+  MasterCodec,
+  masterFrom,
+  masterValidate,
+  type Master,
+  type MasterLike,
+} from "./master.ts";
+
+const maxUint128 = (1n << 128n) - 1n;
+
+/**
+ * Wire shape for order cell data.
+ */
+export interface OrderDataLike {
+  /** UDT amount held by the order cell. */
+  udtValue: ccc.FixedPointLike;
+  /** Relative or absolute pointer to the master cell. */
+  master: MasterLike;
+  /** Price and minimum-match metadata. */
+  info: InfoLike;
+}
+
+const OrderDataCodec = mol.struct({
+  udtValue: CheckedUint128LE,
+  master: MasterCodec,
+  info: Info,
+});
+
+const OrderBase = ccc.Entity.Base<OrderDataLike, OrderData>();
+
+/**
+ * Serialized order cell payload.
+ */
+export interface OrderData {
+  /** UDT amount held by the order cell. */
+  udtValue: ccc.FixedPoint;
+  /** Master-cell pointer. */
+  master: Master;
+  /** Price and minimum-match metadata. */
+  info: Info;
+  /** Creates a copy of this order payload. */
+  clone(): OrderData;
+  /** Returns whether another value has the same order payload. */
+  eq(other: OrderDataLike): boolean;
+  /** Resolves a relative master against `current`, or returns the absolute master. */
+  getMaster(current: ccc.OutPoint): ccc.OutPoint;
+  /** Returns the CKB hash of the serialized order payload. */
+  hash(): ccc.Hex;
+  /** Returns whether the master pointer is relative to the current output. */
+  isMint(): boolean;
+  /** Serializes the order payload to bytes. */
+  toBytes(): ccc.Bytes;
+  /** Serializes the order payload to full-width hexadecimal. */
+  toHex(): ccc.Hex;
+  /** Throws if the UDT value, master pointer, or info is invalid. */
+  validate(): void;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-shadow -- Preserve the runtime constructor name.
+const OrderDataImplementation = class OrderData extends OrderBase {
+  static {
+    ccc.codec(OrderDataCodec)(this);
+  }
+
+  /** UDT amount held by the order cell. */
+  public readonly udtValue: ccc.FixedPoint;
+  /** Master-cell pointer. */
+  public readonly master: Master;
+  /** Price and minimum-match metadata. */
+  public readonly info: Info;
+
+  /** Creates normalized order data. */
+  constructor(udtValue: ccc.FixedPoint, master: Master, info: Info) {
+    super();
+    this.udtValue = udtValue;
+    this.master = master;
+    this.info = info;
+  }
+
+  /** Normalizes an `OrderDataLike` wire object or existing entity into `OrderData`. */
+  public static override from(data: OrderDataLike): OrderData {
+    if (data instanceof OrderData) {
+      return data;
+    }
+
+    const { udtValue, master, info } = data;
+    return new OrderData(ccc.numFrom(udtValue), masterFrom(master), Info.from(info));
+  }
+
+  /** Throws when the order payload is not internally valid. */
+  public validate(): void {
+    if (this.udtValue < 0n) {
+      throw new Error("udtValue invalid, negative");
+    }
+    if (this.udtValue > maxUint128) {
+      throw new Error("udtValue exceeds Uint128");
+    }
+    masterValidate(this.master);
+    this.info.validate();
+  }
+
+  /** Returns true when the master pointer is relative to the current output. */
+  public isMint(): boolean {
+    return this.master.type === "relative";
+  }
+
+  /** Resolves the master out point relative to the current order out point. */
+  public getMaster(current: ccc.OutPoint): ccc.OutPoint {
+    const { type, value } = this.master;
+    return type === "relative"
+      ? new ccc.OutPoint(current.txHash, current.index + value.distance)
+      : value;
+  }
+};
+
+/** CCC-backed order-data constructor and codec. */
+// eslint-disable-next-line @typescript-eslint/no-redeclare -- The public type and runtime constructor intentionally share a name.
+export const OrderData: {
+  byteLength?: number;
+  new (udtValue: ccc.FixedPoint, master: Master, info: Info): OrderData;
+  decode: (encoded: ccc.BytesLike) => OrderData;
+  encode: (data: OrderDataLike) => ccc.Bytes;
+  from: (data: OrderDataLike) => OrderData;
+  fromBytes: (encoded: ccc.BytesLike) => OrderData;
+} = OrderDataImplementation;

package/src/order/ratio.ts

@@ -0,0 +1,144 @@
+import { ccc, mol } from "@ckb-ccc/core";
+import { CheckedUint64LE } from "../utils/codec.ts";
+import { compareBigInt, type ExchangeRatio } from "../utils/utils.ts";
+
+const maxUint64 = (1n << 64n) - 1n;
+
+const RatioCodec = mol.struct({
+  ckbScale: CheckedUint64LE,
+  udtScale: CheckedUint64LE,
+});
+
+const RatioBase = ccc.Entity.Base<ExchangeRatio, Ratio>();
+
+/**
+ * Serialized exchange ratio used by order info.
+ *
+ * @remarks
+ * A ratio is either empty (`0, 0`) or populated with both scales greater than
+ * zero. Mixed empty/populated values are invalid.
+ */
+export interface Ratio extends ExchangeRatio {
+  /** Creates a copy of this ratio. */
+  clone(): Ratio;
+  /** Compares effective CKB-to-UDT prices, returning their numeric ordering. */
+  compare(other: Ratio): number;
+  /** Converts an amount in the selected direction, rounding up only when requested. */
+  convert(isCkb2Udt: boolean, amount: ccc.FixedPoint, mustCeil: boolean): ccc.FixedPoint;
+  /** Returns whether another value has the same scales. */
+  eq(other: ExchangeRatio): boolean;
+  /** Returns the CKB hash of the serialized ratio. */
+  hash(): ccc.Hex;
+  /** Returns whether both scales are zero. */
+  isEmpty(): boolean;
+  /** Returns whether both scales are positive. */
+  isPopulated(): boolean;
+  /** Serializes the ratio to bytes. */
+  toBytes(): ccc.Bytes;
+  /** Serializes the ratio to full-width hexadecimal. */
+  toHex(): ccc.Hex;
+  /** Throws unless both scales fit Uint64 and are both zero or both positive. */
+  validate(): void;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-shadow -- Preserve the runtime constructor name.
+const RatioImplementation = class Ratio extends RatioBase {
+  static {
+    ccc.codec(RatioCodec)(this);
+  }
+
+  /** CKB-side scale. */
+  public readonly ckbScale: ccc.Num;
+  /** UDT-side scale. */
+  public readonly udtScale: ccc.Num;
+
+  /** Creates a ratio from raw scales. */
+  constructor(ckbScale: ccc.Num, udtScale: ccc.Num) {
+    super();
+    this.ckbScale = ckbScale;
+    this.udtScale = udtScale;
+  }
+
+  /** Normalizes an exchange ratio wire object or existing entity into `Ratio`. */
+  public static override from(ratio: ExchangeRatio): Ratio {
+    if (ratio instanceof Ratio) {
+      return ratio;
+    }
+
+    const { ckbScale, udtScale } = ratio;
+    return new Ratio(ckbScale, udtScale);
+  }
+
+  /** Throws when the ratio is neither empty nor fully populated. */
+  public validate(): void {
+    if (
+      this.ckbScale < 0n ||
+      this.ckbScale > maxUint64 ||
+      this.udtScale < 0n ||
+      this.udtScale > maxUint64
+    ) {
+      throw new Error("Ratio scale exceeds Uint64");
+    }
+    if (!this.isEmpty() && !this.isPopulated()) {
+      throw new Error("Ratio invalid: not empty, not populated");
+    }
+  }
+
+  /** Returns true for the sentinel empty ratio. */
+  public isEmpty(): boolean {
+    return this.ckbScale === 0n && this.udtScale === 0n;
+  }
+
+  /** Returns true when both scales are positive. */
+  public isPopulated(): boolean {
+    return this.ckbScale > 0n && this.udtScale > 0n;
+  }
+
+  /** Creates the sentinel empty ratio. */
+  public static empty(): Ratio {
+    return new Ratio(0n, 0n);
+  }
+
+  /** Compares two populated ratios by effective CKB-to-UDT price. */
+  public compare(other: Ratio): number {
+    if (this.udtScale === other.udtScale) {
+      return compareBigInt(this.ckbScale, other.ckbScale);
+    }
+
+    if (this.ckbScale === other.ckbScale) {
+      return compareBigInt(other.udtScale, this.udtScale);
+    }
+
+    return compareBigInt(this.ckbScale * other.udtScale, other.ckbScale * this.udtScale);
+  }
+
+  /** Converts an amount in the requested direction with optional ceiling. */
+  public convert(
+    isCkb2Udt: boolean,
+    amount: ccc.FixedPoint,
+    mustCeil: boolean,
+  ): ccc.FixedPoint {
+    if (!this.isPopulated()) {
+      throw new Error("Invalid midpoint ExchangeRatio");
+    }
+
+    let { ckbScale: aScale, udtScale: bScale } = this;
+    if (!isCkb2Udt) {
+      [aScale, bScale] = [bScale, aScale];
+    }
+
+    return (amount * aScale + (mustCeil ? bScale - 1n : 0n)) / bScale;
+  }
+};
+
+/** CCC-backed ratio constructor and codec. */
+// eslint-disable-next-line @typescript-eslint/no-redeclare -- The public type and runtime constructor intentionally share a name.
+export const Ratio: {
+  byteLength?: number;
+  new (ckbScale: ccc.Num, udtScale: ccc.Num): Ratio;
+  decode: (encoded: ccc.BytesLike) => Ratio;
+  empty: () => Ratio;
+  encode: (ratio: ExchangeRatio) => ccc.Bytes;
+  from: (ratio: ExchangeRatio) => Ratio;
+  fromBytes: (encoded: ccc.BytesLike) => Ratio;
+} = RatioImplementation;

package/src/order/relative.ts

@@ -0,0 +1,106 @@
+import { ccc, mol } from "@ckb-ccc/core";
+import { CheckedInt32LE } from "../utils/codec.ts";
+
+const minInt32 = -(1n << 31n);
+const maxInt32 = (1n << 31n) - 1n;
+
+/**
+ * Wire shape for a relative master pointer.
+ */
+export interface RelativeLike {
+  /** Must be the 32-byte zero padding used by the standard encoding. */
+  padding: ccc.BytesLike;
+  /** Signed output-index distance from the current order to its master. */
+  distance: ccc.NumLike;
+}
+
+const RelativeCodec = mol.struct({
+  padding: mol.Byte32,
+  distance: CheckedInt32LE,
+});
+
+const RelativeBase = ccc.Entity.Base<RelativeLike, Relative>();
+
+/**
+ * Relative pointer from an order output to its master output.
+ */
+export interface Relative {
+  /** Standard zero padding. */
+  padding: ccc.Bytes;
+  /** Signed output-index distance to the master output. */
+  distance: ccc.Num;
+  /** Creates a copy of this relative pointer. */
+  clone(): Relative;
+  /** Returns whether another value has the same padding and distance. */
+  eq(other: RelativeLike): boolean;
+  /** Returns the CKB hash of the serialized relative pointer. */
+  hash(): ccc.Hex;
+  /** Serializes the relative pointer to bytes. */
+  toBytes(): ccc.Bytes;
+  /** Serializes the relative pointer to full-width hexadecimal. */
+  toHex(): ccc.Hex;
+  /** Throws unless padding is canonical and distance fits Int32. */
+  validate(): void;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-shadow -- Preserve the runtime constructor name.
+const RelativeImplementation = class Relative extends RelativeBase {
+  static {
+    ccc.codec(RelativeCodec)(this);
+  }
+
+  /** Standard zero padding. */
+  public readonly padding: ccc.Bytes;
+  /** Signed output-index distance to the master output. */
+  public readonly distance: ccc.Num;
+
+  /** Creates a normalized relative pointer. */
+  constructor(padding: ccc.Bytes, distance: ccc.Num) {
+    super();
+    this.padding = padding;
+    this.distance = distance;
+  }
+
+  /** Normalizes a relative pointer wire object or existing entity into `Relative`. */
+  public static override from(relative: RelativeLike): Relative {
+    if (relative instanceof Relative) {
+      return relative;
+    }
+
+    const { padding, distance } = relative;
+    return new Relative(ccc.bytesFrom(padding), ccc.numFrom(distance));
+  }
+
+  /** Creates a relative pointer with standard zero padding. */
+  public static create(distance: ccc.Num): Relative {
+    return new Relative(Relative.padding(), distance);
+  }
+
+  /** Returns the standard 32-byte zero padding. */
+  public static padding(): ccc.Bytes {
+    return new Uint8Array(32);
+  }
+
+  /** Throws when padding is not the standard 32-byte zero value. */
+  public validate(): void {
+    if (this.padding.length !== 32 || this.padding.some((x) => x !== 0)) {
+      throw new Error("Relative master invalid, non standard padding");
+    }
+    if (this.distance < minInt32 || this.distance > maxInt32) {
+      throw new Error("Relative master distance exceeds Int32");
+    }
+  }
+};
+
+/** CCC-backed relative-pointer constructor and codec. */
+// eslint-disable-next-line @typescript-eslint/no-redeclare -- The public type and runtime constructor intentionally share a name.
+export const Relative: {
+  byteLength?: number;
+  new (padding: ccc.Bytes, distance: ccc.Num): Relative;
+  create: (distance: ccc.Num) => Relative;
+  decode: (encoded: ccc.BytesLike) => Relative;
+  encode: (relative: RelativeLike) => ccc.Bytes;
+  from: (relative: RelativeLike) => Relative;
+  fromBytes: (encoded: ccc.BytesLike) => Relative;
+  padding: () => ccc.Bytes;
+} = RelativeImplementation;