@ickb/sdk 1000.0.82 → 9001.0.0

package/src/order/info.ts

@@ -0,0 +1,181 @@
+import { ccc, mol } from "@ckb-ccc/core";
+import { CheckedUint8 } from "../utils/codec.ts";
+import type { ExchangeRatio } from "../utils/utils.ts";
+import { Ratio } from "./ratio.ts";
+
+/**
+ * Wire shape for an order's directional ratios and minimum CKB match.
+ */
+export interface InfoLike {
+  /** Populated when the order can trade CKB for UDT; empty otherwise. */
+  ckbToUdt: ExchangeRatio;
+  /** Populated when the order can trade UDT for CKB; empty otherwise. */
+  udtToCkb: ExchangeRatio;
+  /** Base-2 exponent for the minimum CKB match amount. */
+  ckbMinMatchLog: ccc.FixedPointLike;
+}
+
+const InfoCodec = mol.struct({
+  ckbToUdt: Ratio,
+  udtToCkb: Ratio,
+  ckbMinMatchLog: CheckedUint8,
+});
+
+const InfoBase = ccc.Entity.Base<InfoLike, Info>();
+
+/**
+ * Order price and minimum-match metadata.
+ *
+ * @remarks
+ * Exactly one populated ratio describes a directional order. Two populated
+ * ratios describe a dual-ratio order. Validation rejects empty/invalid pairs and
+ * ratio pairs that allow value extraction.
+ */
+export interface Info {
+  /** Ratio for CKB-to-UDT matching, or empty when unavailable. */
+  ckbToUdt: Ratio;
+  /** Ratio for UDT-to-CKB matching, or empty when unavailable. */
+  udtToCkb: Ratio;
+  /** Base-2 exponent for the minimum CKB match amount. */
+  ckbMinMatchLog: number;
+  /** Creates a copy of this order info. */
+  clone(): Info;
+  /** Returns whether another value has the same order info. */
+  eq(other: InfoLike): boolean;
+  /** Returns `2 ** ckbMinMatchLog` as the minimum CKB match amount. */
+  getCkbMinMatch(): ccc.FixedPoint;
+  /** Returns the CKB hash of the serialized order info. */
+  hash(): ccc.Hex;
+  /** Returns whether the CKB-to-UDT ratio is populated. */
+  isCkb2Udt(): boolean;
+  /** Returns whether both directional ratios are populated. */
+  isDualRatio(): boolean;
+  /** Returns whether the UDT-to-CKB ratio is populated. */
+  isUdt2Ckb(): boolean;
+  /** Serializes the order info to bytes. */
+  toBytes(): ccc.Bytes;
+  /** Serializes the order info to full-width hexadecimal. */
+  toHex(): ccc.Hex;
+  /** Throws if the ratios or minimum-match exponent are invalid. */
+  validate(): void;
+}
+
+// 2^36 shannons, about 687 CKB, leaves fresh remainders headroom above the fill-cost floor.
+// Orders below twice that minimum are whole-only. Converted to iCKB, this band must stay
+// below `ICKB_REFILL_BELOW` so a buyer too small to split triggers a refill when inventory
+// cannot fill it whole. Fee changes and an aging buy can still make a remainder unprofitable.
+export const CKB_MIN_MATCH_LOG_DEFAULT = 36;
+
+// An interface, this class expression and a typed const rather than one plain class: a
+// class extending `ccc.Entity.Base<...>()` emits an unexported `*_base` declaration, which
+// API Extractor's ae-forgotten-export rejects (tried 2026-10-30).
+// eslint-disable-next-line @typescript-eslint/no-shadow -- Preserve the runtime constructor name.
+const InfoImplementation = class Info extends InfoBase {
+  static {
+    ccc.codec(InfoCodec)(this);
+  }
+
+  /** Ratio for CKB-to-UDT matching, or empty when unavailable. */
+  public readonly ckbToUdt: Ratio;
+  /** Ratio for UDT-to-CKB matching, or empty when unavailable. */
+  public readonly udtToCkb: Ratio;
+  /** Base-2 exponent for the minimum CKB match amount. */
+  public readonly ckbMinMatchLog: number;
+
+  /** Creates order info from normalized ratio objects. */
+  constructor(ckbToUdt: Ratio, udtToCkb: Ratio, ckbMinMatchLog: number) {
+    super();
+    this.ckbToUdt = ckbToUdt;
+    this.udtToCkb = udtToCkb;
+    this.ckbMinMatchLog = ckbMinMatchLog;
+  }
+
+  /** Normalizes an `InfoLike` wire object or existing entity into `Info`. */
+  public static override from(info: InfoLike): Info {
+    if (info instanceof Info) {
+      return info;
+    }
+
+    const { ckbToUdt, udtToCkb, ckbMinMatchLog } = info;
+    return new Info(Ratio.from(ckbToUdt), Ratio.from(udtToCkb), Number(ckbMinMatchLog));
+  }
+
+  /** Creates directional order info from one ratio, at the default minimum match. */
+  public static create(isCkb2Udt: boolean, ratioLike: ExchangeRatio): Info {
+    return Info.from({
+      ckbToUdt: isCkb2Udt ? ratioLike : Ratio.empty(),
+      udtToCkb: isCkb2Udt ? Ratio.empty() : ratioLike,
+      ckbMinMatchLog: CKB_MIN_MATCH_LOG_DEFAULT,
+    });
+  }
+
+  /** Throws when ratio pairing or minimum-match exponent is invalid. */
+  public validate(): void {
+    if (!isValidCkbMinMatchLog(this.ckbMinMatchLog)) {
+      throw new Error("ckbMinMatchLog invalid");
+    }
+    this.ckbToUdt.validate();
+    this.udtToCkb.validate();
+
+    if (this.ckbToUdt.isEmpty()) {
+      if (this.udtToCkb.isPopulated()) {
+        return;
+      }
+      throw new Error("ckbToUdt is Empty, but udtToCkb is not Populated");
+    }
+
+    if (this.udtToCkb.isEmpty()) {
+      if (this.ckbToUdt.isPopulated()) {
+        return;
+      }
+      throw new Error("udtToCkb is Empty, but ckbToUdt is not Populated");
+    }
+
+    if (!this.ckbToUdt.isPopulated() || !this.udtToCkb.isPopulated()) {
+      throw new Error("One ratio is invalid, so not Empty and not Populated");
+    }
+
+    if (
+      this.ckbToUdt.ckbScale * this.udtToCkb.udtScale <
+      this.ckbToUdt.udtScale * this.udtToCkb.ckbScale
+    ) {
+      throw new Error("udtToCkb and ckbToUdt allow order value to be extracted");
+    }
+  }
+
+  /** Returns the minimum CKB match amount. */
+  public getCkbMinMatch(): ccc.FixedPoint {
+    return 1n << BigInt(this.ckbMinMatchLog);
+  }
+
+  /** Returns true when CKB-to-UDT matching is enabled. */
+  public isCkb2Udt(): boolean {
+    return this.ckbToUdt.isPopulated();
+  }
+
+  /** Returns true when UDT-to-CKB matching is enabled. */
+  public isUdt2Ckb(): boolean {
+    return this.udtToCkb.isPopulated();
+  }
+
+  /** Returns true when both directions are enabled. */
+  public isDualRatio(): boolean {
+    return this.isCkb2Udt() && this.isUdt2Ckb();
+  }
+};
+
+/** CCC-backed order-info constructor and codec. */
+// eslint-disable-next-line @typescript-eslint/no-redeclare -- The public type and runtime constructor intentionally share a name.
+export const Info: {
+  byteLength?: number;
+  new (ckbToUdt: Ratio, udtToCkb: Ratio, ckbMinMatchLog: number): Info;
+  create: (isCkb2Udt: boolean, ratioLike: ExchangeRatio) => Info;
+  decode: (encoded: ccc.BytesLike) => Info;
+  encode: (info: InfoLike) => ccc.Bytes;
+  from: (info: InfoLike) => Info;
+  fromBytes: (encoded: ccc.BytesLike) => Info;
+} = InfoImplementation;
+
+function isValidCkbMinMatchLog(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= 64;
+}

package/src/order/master.ts

@@ -0,0 +1,42 @@
+import { ccc, mol } from "@ckb-ccc/core";
+import { Relative, type RelativeLike } from "./relative.ts";
+
+// Both variants are 36 bytes, and OrderData is a struct, so the union must be fixed-size:
+// CCC 1.23+ sizes a plain union dynamically and rejects it as a struct field.
+const MasterCodec = mol.fixedUnion({
+  relative: Relative,
+  absolute: ccc.OutPoint,
+});
+
+/**
+ * Master pointer before normalization.
+ */
+export type MasterLike =
+  | { type: "relative"; value: RelativeLike }
+  | { type: "absolute"; value: ccc.OutPointLike };
+
+/**
+ * Master pointer stored in order data.
+ */
+export type Master =
+  { type: "relative"; value: Relative } | { type: "absolute"; value: ccc.OutPoint };
+
+/** Normalizes a master pointer into entity values. */
+export function masterFrom(master: MasterLike): Master {
+  if (master.type === "relative") {
+    return { type: "relative", value: Relative.from(master.value) };
+  }
+  return { type: "absolute", value: ccc.OutPoint.from(master.value) };
+}
+
+/** Validates a normalized master pointer. */
+export function masterValidate(master: Master): void {
+  const { type, value } = master;
+  if (type === "relative") {
+    value.validate();
+  } else if (!/^0x[0-9a-f]{64}$/i.test(value.txHash) || value.index < 0) {
+    throw new Error("OutPoint invalid");
+  }
+}
+
+export { MasterCodec };

package/src/order/matcher.ts

@@ -0,0 +1,191 @@
+import { ccc } from "@ckb-ccc/core";
+import { ceilDiv } from "../utils/utils.ts";
+import type { OrderCell, OrderGroup } from "./cells.ts";
+
+/**
+ * The fills of one or more orders from the matcher caller's perspective.
+ */
+export interface Match {
+  /** Net CKB change from the match. */
+  ckbDelta: bigint;
+
+  /** Net UDT change from the match. */
+  udtDelta: bigint;
+
+  /** Partial order outputs that must replace matched order inputs. */
+  partials: Array<{
+    /** Resolved group that proves the matched order's mint origin. */
+    group: OrderGroup;
+
+    /** CKB capacity for the replacement partial order output. */
+    ckbOut: ccc.FixedPoint;
+
+    /** UDT amount for the replacement partial order output. */
+    udtOut: ccc.FixedPoint;
+  }>;
+}
+
+/**
+ * One order's fills in one direction, in the contract's terms: `a` is the asset the order
+ * gives, `b` the asset the caller pays. A partial pays `b` between `bMinMatch` and
+ * `bMaxMatch`; paying `bMaxMatch` completes the order.
+ */
+export class OrderMatcher {
+  public readonly group: OrderGroup;
+  public readonly isCkb2Udt: boolean;
+  public readonly aScale: ccc.Num;
+  public readonly bScale: ccc.Num;
+  public readonly aIn: ccc.FixedPoint;
+  public readonly bIn: ccc.FixedPoint;
+  public readonly aMin: ccc.FixedPoint;
+  public readonly bMinMatch: ccc.FixedPoint;
+  public readonly bMaxMatch: ccc.FixedPoint;
+  public readonly bMaxOut: ccc.FixedPoint;
+
+  private constructor(
+    group: OrderGroup,
+    isCkb2Udt: boolean,
+    { aScale, bScale, aIn, bIn, aMin, bMinMatch, bMaxMatch, bMaxOut }: OrderMatcherTerms,
+  ) {
+    this.group = group;
+    this.isCkb2Udt = isCkb2Udt;
+    this.aScale = aScale;
+    this.bScale = bScale;
+    this.aIn = aIn;
+    this.bIn = bIn;
+    this.aMin = aMin;
+    this.bMinMatch = bMinMatch;
+    this.bMaxMatch = bMaxMatch;
+    this.bMaxOut = bMaxOut;
+  }
+
+  /** The order's matcher in one direction, or `undefined` when nothing gains in it. */
+  public static from(
+    group: OrderGroup,
+    isCkb2Udt: boolean,
+    ckbMiningFee: ccc.FixedPoint,
+  ): OrderMatcher | undefined {
+    const terms = orderMatcherTerms(group.order, isCkb2Udt, ckbMiningFee);
+    return terms === undefined ? undefined : new OrderMatcher(group, isCkb2Udt, terms);
+  }
+
+  public match(bAllowance: ccc.FixedPoint): Match {
+    if (bAllowance < this.bMinMatch) {
+      return { ckbDelta: 0n, udtDelta: 0n, partials: [] };
+    }
+
+    if (bAllowance >= this.bMaxMatch) {
+      return this.create(this.aMin, this.bMaxOut);
+    }
+
+    const bOut = this.bIn + bAllowance;
+    const aOut = nonDecreasing({
+      aScale: this.bScale,
+      bScale: this.aScale,
+      aIn: this.bIn,
+      bIn: this.aIn,
+      aOut: bOut,
+    });
+    return this.create(aOut, bOut);
+  }
+
+  public create(aOut: ccc.FixedPoint, bOut: ccc.FixedPoint): Match {
+    return this.isCkb2Udt
+      ? {
+          ckbDelta: this.aIn - aOut,
+          udtDelta: this.bIn - bOut,
+          partials: [{ group: this.group, ckbOut: aOut, udtOut: bOut }],
+        }
+      : {
+          ckbDelta: this.bIn - bOut,
+          udtDelta: this.aIn - aOut,
+          partials: [{ group: this.group, ckbOut: bOut, udtOut: aOut }],
+        };
+  }
+}
+
+interface OrderMatcherTerms {
+  aScale: ccc.Num;
+  bScale: ccc.Num;
+  aIn: ccc.FixedPoint;
+  bIn: ccc.FixedPoint;
+  aMin: ccc.FixedPoint;
+  bMinMatch: ccc.FixedPoint;
+  bMaxMatch: ccc.FixedPoint;
+  bMaxOut: ccc.FixedPoint;
+}
+
+function orderMatcherTerms(
+  order: OrderCell,
+  isCkb2Udt: boolean,
+  ckbMiningFee: ccc.FixedPoint,
+): OrderMatcherTerms | undefined {
+  if (isCkb2Udt ? !order.isCkb2UdtMatchable() : !order.isUdt2CkbMatchable()) {
+    return undefined;
+  }
+  const { info } = order.data;
+  const ckbMinMatch = info.getCkbMinMatch();
+  let terms: Omit<OrderMatcherTerms, "bMaxMatch" | "bMaxOut">;
+  if (isCkb2Udt) {
+    const { ckbScale: aScale, udtScale: bScale } = info.ckbToUdt;
+    terms = {
+      aScale,
+      bScale,
+      aIn: order.ckbValue,
+      bIn: order.udtValue,
+      aMin: order.cell.cellOutput.capacity - order.ckbUnoccupied,
+      // The contract's ckb2udt minimum is a plain CKB delta (limit_order entry.rs:116);
+      // a value-conserving partial moving u UDT moves u*udtScale/ckbScale CKB, so the
+      // UDT-denominated floor is ceil(minMatch * ckbScale / udtScale).
+      bMinMatch: ceilDiv(ckbMinMatch * aScale, bScale),
+    };
+  } else {
+    const { ckbScale: bScale, udtScale: aScale } = info.udtToCkb;
+    // The contract's udt2ckb minimum values the UDT moved at the ratio, and a payment of
+    // p CKB moves floor(p*bScale/aScale) UDT, so the smallest payment the contract accepts
+    // is the one whose floor reaches ceil(min*bScale/aScale) UDT: the plain minimum,
+    // rounded up to the ratio's grid.
+    const udtMinMatch = ceilDiv(ckbMinMatch * bScale, aScale);
+    terms = {
+      aScale,
+      bScale,
+      aIn: order.udtValue,
+      bIn: order.ckbValue,
+      aMin: 0n,
+      bMinMatch: ceilDiv(udtMinMatch * aScale, bScale),
+    };
+  }
+
+  const { aScale, bScale, aIn, bIn, aMin, bMinMatch } = terms;
+  // A buyer pays the fill's mining fee out of the CKB it gives, so nothing gains once the
+  // fee eats that; a seller's fill brings CKB in, and its caller nets the fee (`netOf`).
+  if (aIn <= aMin + (isCkb2Udt ? ckbMiningFee : 0n)) {
+    return undefined;
+  }
+  const bMaxOut = nonDecreasing({ aScale, bScale, aIn, bIn, aOut: aMin });
+  const bMaxMatch = bMaxOut - bIn;
+  return {
+    ...terms,
+    // An order under its own minimum can only be completed.
+    bMinMatch: ccc.numMin(bMinMatch, bMaxMatch),
+    bMaxMatch,
+    bMaxOut,
+  };
+}
+
+/** The smallest `b` output that keeps the order's value non-decreasing at its ratio. */
+function nonDecreasing({
+  aScale,
+  bScale,
+  aIn,
+  bIn,
+  aOut,
+}: {
+  aScale: ccc.Num;
+  bScale: ccc.Num;
+  aIn: ccc.FixedPoint;
+  bIn: ccc.FixedPoint;
+  aOut: ccc.FixedPoint;
+}): ccc.FixedPoint {
+  return ceilDiv(aScale * (aIn - aOut) + bScale * bIn, bScale);
+}

package/src/order/order.ts

@@ -0,0 +1,288 @@
+import { ccc } from "@ckb-ccc/core";
+import { findCells, type ScriptDeps, type ValueComponents } from "../utils/utils.ts";
+import { MasterCell, OrderCell, OrderGroup } 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";
+
+/**
+ * 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);
+    if (groups.length === 0) {
+      return tx;
+    }
+    for (const group of groups) {
+      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 groups) {
+      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, blockNumber }) => [
+        master.cell.outPoint.toHex(),
+        { master, blockNumber, 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, blockNumber, orders: candidates }) =>
+          this.resolveOrderGroup(client, master, blockNumber, 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] : [];
+    });
+  }
+
+  /**
+   * Every master with the block that committed it, which is its mint order's block too:
+   * a master is created beside its mint order and never changes until melted, so this
+   * dates how long the order has been on the book.
+   */
+  private async findAllMasters(
+    client: ccc.Client,
+  ): Promise<Array<{ master: MasterCell; blockNumber: ccc.Num }>> {
+    // 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, blockNumber }) => ({
+      master: new MasterCell(cell),
+      blockNumber,
+    }));
+  }
+
+  /** Resolves one master and its descendant orders into a validated order group. */
+  private async resolveOrderGroup(
+    client: ccc.Client,
+    master: MasterCell,
+    blockNumber: ccc.Num,
+    orders: OrderCell[],
+  ): Promise<OrderGroup | undefined> {
+    const origin = await this.findOrigin(client, master.cell.outPoint);
+    const order = origin?.resolve(orders);
+    if (origin === undefined || order === undefined) {
+      return undefined;
+    }
+    const group = OrderGroup.tryFrom(master, order, origin, 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 group;
+  }
+
+  /**
+   * The mint order created beside the master, read from the master's transaction: the
+   * client cache first, then the node, which records the response for the next read.
+   */
+  private async findOrigin(
+    client: ccc.Client,
+    master: ccc.OutPoint,
+  ): Promise<OrderCell | undefined> {
+    const { txHash, index: masterIndex } = master;
+    // A cached body is trusted like the scan that found the master: an order is a node's
+    // claim until the send checks every cell it spends against its creating transaction.
+    const response =
+      (await client.cache.getTransactionResponse(txHash)) ??
+      (await client.getTransaction(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;
+  }
+
+  private validatedPartial({
+    group,
+    ckbOut,
+    udtOut,
+  }: Match["partials"][number]): Match["partials"][number] {
+    const outPoint = group.order.cell.outPoint.toHex();
+    if (!this.isOrder(group.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, ckbOut, udtOut };
+  }
+}