@ickb/sdk 1000.0.82 → 9001.0.0

package/src/order/order_data.ts

@@ -0,0 +1,131 @@
+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;
+}
+
+// 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 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,127 @@
+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;
+  /** 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;
+}
+
+// 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 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);
+  }
+};
+
+/** 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,109 @@
+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;
+}
+
+// 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 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;