@ickb/sdk 1000.0.82 → 9000.0.1

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, so an uncommitted origin
+ * is as fresh as an order gets. The block count assumes eight-second blocks, not wall time.
+ */
+export function isStale(group: OrderGroup, tip: ccc.ClientBlockHeader): boolean {
+  return (group.blockNumber ?? tip.number) + STALE_ORDER_BLOCKS <= tip.number;
+}

package/src/order/info.ts

@@ -0,0 +1,178 @@
+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;
+
+// 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 type { ccc } from "@ckb-ccc/core";
+import { ceilDiv, minBigInt } 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: minBigInt(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);
+}