@ckb-ccc/core 1.12.4 → 1.13.0

package/dist.commonjs/index.js

@@ -1,41 +1 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ccc = void 0;
-__exportStar(require("./barrel.js"), exports);
-exports.ccc = __importStar(require("./barrel.js"));
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./address.advanced-COp7SNhZ.js"),t=require("./barrel-CXC2Uy5L.js");exports.Address=t.H,exports.Bytes=e.hr,exports.Cell=e.a,exports.CellAny=e.o,Object.defineProperty(exports,"CellDep",{enumerable:!0,get:function(){return e.s}}),exports.CellDepInfo=e.nt,exports.CellDepVec=e.c,Object.defineProperty(exports,"CellInput",{enumerable:!0,get:function(){return e.l}}),exports.CellInputVec=e.u,Object.defineProperty(exports,"CellOutput",{enumerable:!0,get:function(){return e.d}}),exports.CellOutputVec=e.f,exports.Client=t.J,exports.ClientBlock=e.rt,exports.ClientBlockHeader=e.it,exports.ClientBlockUncle=e.at,exports.ClientCache=t.X,exports.ClientCacheMemory=t.Y,exports.ClientIndexerSearchKey=e.ot,exports.ClientIndexerSearchKeyFilter=e.st,exports.ClientIndexerSearchKeyTransaction=e.ct,exports.ClientJsonRpc=t.K,exports.ClientPublicMainnet=t.G,exports.ClientPublicTestnet=t.W,exports.ClientTransactionResponse=e.lt,exports.Codec=e.mr,exports.CodecBool=e.Sn,exports.CodecByte=e.Cn,exports.CodecByte16=e.wn,exports.CodecByte32=e.Tn,exports.CodecByte4=e.En,exports.CodecByte8=e.Dn,exports.CodecBytes=e.On,exports.CodecRaw=e.kn,exports.CodecUint128=e.An,exports.CodecUint128BE=e.jn,exports.CodecUint128LE=e.Mn,exports.CodecUint16=e.Nn,exports.CodecUint16BE=e.Pn,exports.CodecUint16LE=e.Fn,exports.CodecUint256=e.In,exports.CodecUint256BE=e.Ln,exports.CodecUint256LE=e.Rn,exports.CodecUint32=e.zn,exports.CodecUint32BE=e.Bn,exports.CodecUint32LE=e.Vn,exports.CodecUint512=e.Hn,exports.CodecUint512BE=e.Un,exports.CodecUint512LE=e.Wn,exports.CodecUint64=e.Gn,exports.CodecUint64BE=e.Kn,exports.CodecUint64LE=e.qn,exports.CodecUint8=e.Jn,exports.DepTypeCodec=e.p,exports.Entity=e.cr,Object.defineProperty(exports,"Epoch",{enumerable:!0,get:function(){return e.xt}}),exports.ErrorClientBase=e.ut,exports.ErrorClientDuplicatedTransaction=e.dt,exports.ErrorClientMaxFeeRateExceeded=e.ft,exports.ErrorClientRBFRejected=e.pt,exports.ErrorClientResolveUnknown=e.mt,exports.ErrorClientVerification=e.ht,exports.ErrorClientWaitTransactionTimeout=e.gt,exports.ErrorTransactionInsufficientCapacity=e.E,exports.ErrorTransactionInsufficientCoin=e.D,exports.HashTypeCodec=e.j,exports.HasherCkb=e.ur,exports.HasherKeecak256=t.Q,exports.InputToSign=t.R,exports.KnownScript=e.J,exports.One=e.vn,Object.defineProperty(exports,"OutPoint",{enumerable:!0,get:function(){return e.m}}),exports.RawTransaction=e.h,exports.RequestorJsonRpc=t.q,Object.defineProperty(exports,"Script",{enumerable:!0,get:function(){return e.M}}),exports.ScriptInfo=e._t,exports.ScriptOpt=e.N,exports.ScriptVec=e.P,exports.SignPsbtOptions=t.z,exports.Signature=t.v,exports.Signer=t.y,exports.SignerAlwaysError=t.c,exports.SignerBtc=t._,exports.SignerBtcPublicKeyReadonly=t.g,exports.SignerCkbPrivateKey=t.m,exports.SignerCkbPublicKey=t.h,exports.SignerCkbScriptReadonly=t.p,exports.SignerDoge=t.f,exports.SignerDogeAddressReadonly=t.d,exports.SignerDogePrivateKey=t.u,exports.SignerDummy=t.l,exports.SignerEvm=t.o,exports.SignerEvmAddressReadonly=t.a,exports.SignerInfo=t.b,exports.SignerNostr=t.i,exports.SignerNostrPrivateKey=t.n,exports.SignerNostrPublicKeyReadonly=t.r,exports.SignerOpenLink=t.s,exports.SignerSignType=t.x,exports.SignerType=t.S,Object.defineProperty(exports,"Since",{enumerable:!0,get:function(){return e.g}}),Object.defineProperty(exports,"Transaction",{enumerable:!0,get:function(){return e._}}),Object.defineProperty(exports,"WitnessArgs",{enumerable:!0,get:function(){return e.v}}),exports.Zero=e.yn,exports.apply=e.Tt,exports.btcEcdsaPublicKeyHash=t.M,exports.btcP2pkhAddressFromPublicKey=t.N,exports.btcPublicKeyFromP2pkhAddress=t.P,exports.btcVarLengthBytesFrom=t.F,exports.buildNostrEventFromMessage=t.C,exports.bytesConcat=e.gr,exports.bytesConcatTo=e._r,exports.bytesEq=e.vr,exports.bytesFrom=e.yr,exports.bytesTo=e.br,exports.calcDaoClaimEpoch=e.y,exports.calcDaoProfit=e.b,Object.defineProperty(exports,"ccc",{enumerable:!0,get:function(){return t.t}}),exports.codec=e.lr,exports.codecPadding=e.Yn,exports.codecUint=e.Xn,exports.codecUintNumber=e.Zn,exports.depTypeFrom=e.x,exports.depTypeFromBytes=e.S,exports.depTypeToBytes=e.C,exports.epochFrom=e.St,exports.epochFromHex=e.Ct,exports.epochToHex=e.wt,exports.fixedPointFrom=e.bn,exports.fixedPointToString=e.xn,exports.gcd=e.Et,exports.hashCkb=e.dr,exports.hashTypeFrom=e.F,exports.hashTypeFromBytes=e.I,exports.hashTypeId=t.U,exports.hashTypeToBytes=e.L,exports.hexFrom=e.pr,exports.isDaoOutputLimitExceeded=e.w,exports.isWebview=e.Dt,exports.keystoreDecrypt=t.B,exports.keystoreEncrypt=t.V,exports.messageHashBtcEcdsa=t.I,exports.messageHashCkbSecp256k1=t.A,exports.messageHashDogeEcdsa=t.D,Object.defineProperty(exports,"mol",{enumerable:!0,get:function(){return t.Z}}),exports.nostrEventHash=t.w,exports.numBeFromBytes=e.Qn,exports.numBeToBytes=e.$n,exports.numFrom=e.er,exports.numFromBytes=e.tr,exports.numLeFromBytes=e.nr,exports.numLeToBytes=e.rr,exports.numMax=e.ir,exports.numMin=e.ar,exports.numToBytes=e.or,exports.numToHex=e.sr,exports.reduceAsync=e.Ot,exports.sleep=e.kt,exports.stringify=e.At,exports.udtBalanceFrom=e.T,exports.verifyMessageBtcEcdsa=t.L,exports.verifyMessageCkbSecp256k1=t.j,exports.verifyMessageDogeEcdsa=t.O,exports.verifyMessageEvmPersonal=t.E,exports.verifyMessageJoyId=t.k,exports.verifyMessageNostrEvent=t.T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckb-ccc/core",
-  "version": "1.12.4",
+  "version": "1.13.0",
   "description": "Core of CCC - CKBer's Codebase",
   "author": "Hanssen0 <hanssen0@hanssen0.com>",
   "license": "MIT",
@@ -12,39 +12,35 @@
   },
   "sideEffects": false,
   "main": "./dist.commonjs/index.js",
-  "module": "./dist/index.js",
+  "module": "./dist/index.mjs",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "require": "./dist.commonjs/index.js",
-      "default": "./dist.commonjs/index.js"
+      "import": "./dist/index.mjs",
+      "require": "./dist.commonjs/index.js"
     },
-    "./barrel": {
-      "import": "./dist/barrel.js",
-      "require": "./dist.commonjs/barrel.js",
-      "default": "./dist.commonjs/barrel.js"
+    "./advanced": {
+      "import": "./dist/advanced.mjs",
+      "require": "./dist.commonjs/advanced.js"
     },
     "./advancedBarrel": {
-      "import": "./dist/advancedBarrel.js",
-      "require": "./dist.commonjs/advancedBarrel.js",
-      "default": "./dist.commonjs/advancedBarrel.js"
+      "import": "./dist/advancedBarrel.mjs",
+      "require": "./dist.commonjs/advancedBarrel.js"
     },
-    "./advanced": {
-      "import": "./dist/advanced.js",
-      "require": "./dist.commonjs/advanced.js",
-      "default": "./dist.commonjs/advanced.js"
-    }
+    "./barrel": {
+      "import": "./dist/barrel.mjs",
+      "require": "./dist.commonjs/barrel.js"
+    },
+    "./package.json": "./package.json"
   },
   "devDependencies": {
     "@eslint/js": "^9.34.0",
     "@types/ws": "^8.18.1",
-    "copyfiles": "^2.4.1",
     "eslint": "^9.34.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "prettier": "^3.6.2",
     "prettier-plugin-organize-imports": "^4.2.0",
-    "rimraf": "^6.0.1",
+    "tsdown": "0.22.3",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.41.0",
     "vitest": "^3.2.4"
@@ -54,9 +50,9 @@
   },
   "dependencies": {
     "@joyid/ckb": "^1.1.2",
-    "@noble/ciphers": "^0.5.3",
-    "@noble/curves": "^1.9.7",
-    "@noble/hashes": "^1.8.0",
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
     "bech32": "^2.0.0",
     "bs58check": "^4.0.0",
     "buffer": "^6.0.3",
@@ -64,10 +60,11 @@
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.18.3"
   },
+  "types": "./dist.commonjs/index.d.ts",
   "scripts": {
     "test": "vitest",
     "test:ci": "vitest run",
-    "build": "rimraf ./dist && rimraf ./dist.commonjs && tsc && tsc --project tsconfig.commonjs.json && copyfiles -u 2 misc/basedirs/**/* .",
+    "build": "tsdown",
     "lint": "eslint ./src",
     "format": "prettier --write . && eslint --fix ./src"
   }

package/src/barrel.ts

@@ -2,6 +2,7 @@ export * from "./address/index.js";
 export * from "./bytes/index.js";
 export * from "./ckb/index.js";
 export * from "./client/index.js";
+export * from "./codec/index.js";
 export * from "./fixedPoint/index.js";
 export * from "./hasher/index.js";
 export * from "./hex/index.js";

package/src/ckb/epoch.ts

@@ -0,0 +1,489 @@
+import type { ClientBlockHeader } from "../client/clientTypes.js";
+import { codec, codecPadding, codecUint, Entity } from "../codec/index.js";
+import { Zero } from "../fixedPoint/index.js";
+import { type Hex, type HexLike } from "../hex/index.js";
+import { mol } from "../molecule/index.js";
+import { numFrom, NumLike, numToHex, type Num } from "../num/index.js";
+import { gcd } from "../utils/index.js";
+
+/**
+ * EpochLike
+ *
+ * Union type that represents any allowed input shapes that can be converted
+ * into an Epoch instance.
+ *
+ * Accepted shapes:
+ * - Tuple: [integer, numerator, denominator] where each element is NumLike
+ * - Object: { integer, numerator, denominator } where each field is NumLike
+ * - Packed numeric form: Num (bigint) or Hex (RPC-style packed hex)
+ *
+ * Notes:
+ * - When constructing an Epoch from a Num or Hex the packed numeric representation
+ *   encodes integer (24 bits), numerator (16 bits) and denominator (16 bits).
+ * - Use Epoch.from() to convert any EpochLike into an Epoch instance.
+ *
+ * @example
+ * // From tuple
+ * Epoch.from([1n, 0n, 1n]);
+ */
+export type EpochLike =
+  | [NumLike, NumLike, NumLike]
+  | {
+      integer: NumLike;
+      numerator: NumLike;
+      denominator: NumLike;
+    }
+  | Num
+  | Hex;
+
+/**
+ * Epoch
+ *
+ * Represents a blockchain epoch consisting of a whole integer part and an
+ * optional fractional part represented as numerator/denominator.
+ *
+ * Behavior highlights:
+ * - Internally stores values as Num (bigint).
+ * - Provides normalization routines to canonicalize the fractional part:
+ *   - normalizeBase(): fixes zero/negative denominators
+ *   - normalizeCanonical(): reduces fraction, borrows/carries whole units
+ * - Supports arithmetic (add/sub), comparison and conversion utilities.
+ *
+ * @example
+ * const e = new Epoch(1n, 1n, 2n); // 1 + 1/2
+ *
+ * @remarks
+ * This class is primarily a thin value-object; operations return new Epoch instances.
+ */
+@codec(
+  mol.struct({
+    padding: codecPadding(1),
+    denominator: codecUint(2),
+    numerator: codecUint(2),
+    integer: codecUint(3),
+  }),
+)
+export class Epoch extends Entity.Base<EpochLike, Epoch>() {
+  /**
+   * Construct a new Epoch instance.
+   *
+   * @param integer - Whole epoch units (Num/bigint)
+   * @param numerator - Fractional numerator (Num).
+   * @param denominator - Fractional denominator (Num).
+   */
+  public constructor(
+    public readonly integer: Num,
+    public readonly numerator: Num,
+    public readonly denominator: Num,
+  ) {
+    super();
+  }
+
+  /**
+   * Normalize simpler base invariants:
+   * - If denominator === 0, set denominator to 1 and numerator to 0 for arithmetic convenience.
+   * - If denominator is negative flip signs of numerator and denominator to keep denominator positive.
+   *
+   * This is a minimal correction used before arithmetic or canonical normalization.
+   *
+   * @returns New Epoch with denominator corrected (but fraction not reduced).
+   */
+  normalizeBase(): Epoch {
+    if (this.denominator === Zero) {
+      return new Epoch(this.integer, Zero, numFrom(1));
+    }
+
+    if (this.denominator < Zero) {
+      return new Epoch(this.integer, -this.numerator, -this.denominator);
+    }
+
+    return this;
+  }
+
+  /**
+   * Perform full canonical normalization of the epoch value.
+   *
+   * Steps:
+   * 1. Apply base normalization (normalizeBase).
+   * 2. If numerator is negative, borrow whole denominator(s) from the integer part
+   *    so numerator becomes non-negative. This ensures 0 <= numerator < denominator whenever possible.
+   * 3. Reduce numerator/denominator by their greatest common divisor (gcd).
+   * 4. Carry any whole units from the reduced numerator into the integer part.
+   * 5. Ensure numerator is the strict remainder (numerator < denominator).
+   *
+   * @returns Canonicalized Epoch with a non-negative, reduced fractional part and integer adjusted accordingly.
+   */
+  normalizeCanonical(): Epoch {
+    let { integer, numerator, denominator } = this.normalizeBase();
+
+    // If numerator is negative, borrow enough whole denominators from integer so numerator >= 0.
+    if (numerator < Zero) {
+      // n is the minimal non-negative integer such that numerator + n * denominator >= 0
+      const n = (-numerator + denominator - 1n) / denominator;
+      integer -= n;
+      numerator += denominator * n;
+    }
+
+    // Reduce the fractional part to lowest terms to keep canonical form and avoid unnecessarily large multiples.
+    const g = gcd(numerator, denominator);
+    numerator /= g;
+    denominator /= g;
+
+    // Move any full units contained in the fraction into integer (e.g., 5/2 => +2 integer, remainder 1/2).
+    integer += numerator / denominator;
+
+    // Remainder numerator after removing whole units; ensures numerator < denominator.
+    numerator %= denominator;
+
+    return new Epoch(integer, numerator, denominator);
+  }
+
+  /**
+   * Backwards-compatible array-style index 0 referencing the whole epoch integer.
+   *
+   * @returns integer portion (Num)
+   * @deprecated Use `.integer` property instead.
+   */
+  get 0(): Num {
+    return this.integer;
+  }
+
+  /**
+   * Backwards-compatible array-style index 1 referencing the epoch fractional numerator.
+   *
+   * @returns numerator portion (Num)
+   * @deprecated Use `.numerator` property instead.
+   */
+  get 1(): Num {
+    return this.numerator;
+  }
+
+  /**
+   * Backwards-compatible array-style index 2 referencing the epoch fractional denominator.
+   *
+   * @returns denominator portion (Num)
+   * @deprecated Use `.denominator` property instead.
+   */
+  get 2(): Num {
+    return this.denominator;
+  }
+
+  /**
+   * Convert this Epoch into its RPC-style packed numeric representation (Num).
+   *
+   * Packing layout (little-endian style fields):
+   * - integer: lower 24 bits
+   * - numerator: next 16 bits
+   * - denominator: next 16 bits
+   *
+   * Throws if any component is negative since packed representation assumes non-negative components.
+   *
+   * @throws {Error} If integer, numerator or denominator are negative.
+   * @throws {Error} If integer, numerator or denominator overflow the packing limits.
+   * @returns Packed numeric representation (Num) suitable for RPC packing.
+   */
+  toNum(): Num {
+    if (
+      this.integer < Zero ||
+      this.numerator < Zero ||
+      this.denominator < Zero
+    ) {
+      throw Error("Negative values in Epoch to Num conversion");
+    }
+
+    if (
+      this.integer >= numFrom("0x1000000") || // 24-bit limit
+      this.numerator >= numFrom("0x10000") || // 16-bit limit
+      this.denominator >= numFrom("0x10000") // 16-bit limit
+    ) {
+      throw Error(
+        "Integer must be < 2^24, numerator and denominator must be < 2^16",
+      );
+    }
+
+    return (
+      this.integer +
+      (this.numerator << numFrom(24)) +
+      (this.denominator << numFrom(40))
+    );
+  }
+
+  /**
+   * Convert epoch to hex string representation of the RPC-style packed numeric form.
+   *
+   * Returns the same representation used by CKB RPC responses where the
+   * packed numeric bytes may be trimmed of leading zeros, see {@link numToHex}
+   *
+   * @returns Hex string corresponding to the packed epoch.
+   */
+  toPackedHex(): Hex {
+    return numToHex(this.toNum());
+  }
+
+  /**
+   * Construct an Epoch by unpacking a RPC-style packed numeric form.
+   *
+   * @param v - NumLike packed epoch (like Num and Hex)
+   * @returns Epoch whose integer, numerator and denominator are extracted from the packed layout.
+   */
+  static fromNum(v: NumLike): Epoch {
+    const num = numFrom(v);
+
+    return new Epoch(
+      num & numFrom("0xffffff"),
+      (num >> numFrom(24)) & numFrom("0xffff"),
+      (num >> numFrom(40)) & numFrom("0xffff"),
+    );
+  }
+
+  /**
+   * Create an Epoch from an EpochLike value.
+   *
+   * Accepts:
+   * - an Epoch instance (returned as-is)
+   * - an array [integer, numerator, denominator] where each element is NumLike
+   * - an object { integer, numerator, denominator } where each field is NumLike
+   * - a packed numeric-like value handled by fromNum
+   *
+   * All numeric-like inputs are converted with numFrom() to produce internal Num values.
+   *
+   * @param e - Value convertible to Epoch
+   * @returns Epoch instance
+   */
+  static override from(e: EpochLike): Epoch {
+    if (e instanceof Epoch) {
+      return e;
+    }
+
+    if (Array.isArray(e)) {
+      return new Epoch(numFrom(e[0]), numFrom(e[1]), numFrom(e[2]));
+    }
+
+    if (typeof e === "object") {
+      return new Epoch(
+        numFrom(e.integer),
+        numFrom(e.numerator),
+        numFrom(e.denominator),
+      );
+    }
+
+    return Epoch.fromNum(e);
+  }
+
+  /**
+   * Return a deep copy of this Epoch.
+   *
+   * @returns New Epoch instance with identical components.
+   */
+  override clone(): Epoch {
+    return new Epoch(this.integer, this.numerator, this.denominator);
+  }
+
+  /**
+   * Return the genesis epoch.
+   *
+   * Note: for historical reasons the genesis epoch is represented with all-zero
+   * fields, no other epoch instance should use a zero denominator.
+   *
+   * @returns Epoch with integer = 0, numerator = 0, denominator = 0.
+   */
+  static get Genesis(): Epoch {
+    return new Epoch(Zero, Zero, Zero);
+  }
+
+  /**
+   * Return an Epoch representing one Nervos DAO cycle (180 epochs exactly).
+   *
+   * @returns Epoch equal to 180 with denominator set to 1 to represent an exact whole unit.
+   */
+  static get OneNervosDaoCycle(): Epoch {
+    return new Epoch(numFrom(180), Zero, numFrom(1));
+  }
+
+  /**
+   * Compare this epoch to another EpochLike.
+   *
+   * The comparison computes scaled integer values so fractions are compared without precision loss:
+   *   scaled = (integer * denominator + numerator) * other.denominator
+   *
+   * Special-case: identical object references return equality immediately.
+   *
+   * @param other - Epoch-like value to compare against.
+   * @returns 1 if this > other, 0 if equal, -1 if this < other.
+   *
+   * @example
+   * epochA.compare(epochB); // -1|0|1
+   */
+  compare(other: EpochLike): 1 | 0 | -1 {
+    if (this === other) {
+      return 0;
+    }
+
+    const t = this.normalizeBase();
+    const o = Epoch.from(other).normalizeBase();
+
+    // Compute scaled representations to compare fractions without floating-point arithmetic.
+    const a = (t.integer * t.denominator + t.numerator) * o.denominator;
+    const b = (o.integer * o.denominator + o.numerator) * t.denominator;
+
+    return a > b ? 1 : a < b ? -1 : 0;
+  }
+
+  /**
+   * Check whether this epoch is less than another EpochLike.
+   *
+   * @param other - EpochLike to compare against.
+   * @returns true if this < other.
+   */
+  lt(other: EpochLike): boolean {
+    return this.compare(other) < 0;
+  }
+
+  /**
+   * Check whether this epoch is less than or equal to another EpochLike.
+   *
+   * @param other - EpochLike to compare against.
+   * @returns true if this <= other.
+   */
+  le(other: EpochLike): boolean {
+    return this.compare(other) <= 0;
+  }
+
+  /**
+   * Check whether this epoch equals another EpochLike.
+   *
+   * @param other - EpochLike to compare against.
+   * @returns true if equal.
+   */
+  eq(other: EpochLike): boolean {
+    return this.compare(other) === 0;
+  }
+
+  /**
+   * Check whether this epoch is greater than or equal to another EpochLike.
+   *
+   * @param other - EpochLike to compare against.
+   * @returns true if this >= other.
+   */
+  ge(other: EpochLike): boolean {
+    return this.compare(other) >= 0;
+  }
+
+  /**
+   * Check whether this epoch is greater than another EpochLike.
+   *
+   * @param other - EpochLike to compare against.
+   * @returns true if this > other.
+   */
+  gt(other: EpochLike): boolean {
+    return this.compare(other) > 0;
+  }
+
+  /**
+   * Add another EpochLike to this epoch and return the normalized result.
+   *
+   * Rules and edge-cases:
+   * - Whole parts are added directly; fractional parts are aligned to a common denominator and added.
+   * - Final result is canonicalized to reduce the fraction and carry any overflow to the integer part.
+   *
+   * @param other - Epoch-like value to add.
+   * @returns Normalized Epoch representing the sum.
+   */
+  add(other: EpochLike): Epoch {
+    const t = this.normalizeBase();
+    const o = Epoch.from(other).normalizeBase();
+
+    // Sum whole integer parts.
+    const integer = t.integer + o.integer;
+    let numerator: Num;
+    let denominator: Num;
+
+    // Align denominators if they differ; use multiplication to obtain a common denominator.
+    if (t.denominator !== o.denominator) {
+      // Numerators & Denominators are generally small (<= 2000n); multiplication produces a safe common denominator.
+      numerator = t.numerator * o.denominator + o.numerator * t.denominator;
+      denominator = t.denominator * o.denominator;
+    } else {
+      numerator = t.numerator + o.numerator;
+      denominator = t.denominator;
+    }
+
+    // Normalize to reduce fraction and carry whole units into integer.
+    return new Epoch(integer, numerator, denominator).normalizeCanonical();
+  }
+
+  /**
+   * Subtract an EpochLike from this epoch and return the normalized result.
+   *
+   * Implementation notes:
+   * - Delegates to add by negating the other epoch's integer and numerator while preserving denominator.
+   * - normalizeCanonical will handle negative numerators by borrowing from integer as necessary.
+   *
+   * @param other - Epoch-like value to subtract.
+   * @returns Normalized Epoch representing this - other.
+   */
+  sub(other: EpochLike): Epoch {
+    const { integer, numerator, denominator } = Epoch.from(other);
+    return this.add(new Epoch(-integer, -numerator, denominator));
+  }
+
+  /**
+   * Convert this epoch to an estimated Unix timestamp in milliseconds using a reference header.
+   *
+   * Note: This is an estimation that assumes a constant epoch duration.
+   *
+   * @param reference - Object providing `epoch` (Epoch) and `timestamp` (Num) fields, such as a ClientBlockHeader.
+   * @param epochInMilliseconds - Duration of a single epoch in milliseconds. Defaults to 4 hours.
+   * @returns Estimated Unix timestamp in milliseconds as bigint.
+   */
+  toUnix(
+    reference: Pick<ClientBlockHeader, "epoch" | "timestamp">,
+    epochInMilliseconds: Num = numFrom(4 * 60 * 60 * 1000),
+  ): bigint {
+    // Compute relative epoch difference against the reference header.
+    const { integer, numerator, denominator } = this.sub(reference.epoch);
+
+    // Add whole epoch duration and fractional epoch duration to the reference timestamp.
+    return (
+      reference.timestamp +
+      epochInMilliseconds * integer +
+      (epochInMilliseconds * numerator) / denominator
+    );
+  }
+}
+
+/**
+ * epochFrom
+ *
+ * @deprecated prefer using Epoch.from() directly.
+ *
+ * @param epochLike - Epoch-like value to convert.
+ * @returns Epoch instance corresponding to the input.
+ */
+export function epochFrom(epochLike: EpochLike): Epoch {
+  return Epoch.from(epochLike);
+}
+
+/**
+ * epochFromHex
+ *
+ * @deprecated use Epoch.fromNum() with numeric input instead.
+ *
+ * @param hex - Hex-like or numeric-like value encoding a packed epoch.
+ * @returns Decoded Epoch instance.
+ */
+export function epochFromHex(hex: HexLike): Epoch {
+  return Epoch.fromNum(hex);
+}
+
+/**
+ * epochToHex
+ *
+ * @deprecated use Epoch.from(epochLike).toPackedHex() instead.
+ *
+ * @param epochLike - Value convertible to an Epoch (object, tuple or Epoch).
+ * @returns Hex string representing the packed epoch encoding.
+ */
+export function epochToHex(epochLike: EpochLike): Hex {
+  return Epoch.from(epochLike).toPackedHex();
+}

package/src/ckb/index.ts

@@ -1,3 +1,4 @@
+export * from "./epoch.js";
 export * from "./hash.js";
 export * from "./script.js";
 export * from "./transaction.js";

package/src/ckb/script.ts

@@ -1,6 +1,7 @@
 import { Bytes, BytesLike, bytesFrom } from "../bytes/index.js";
 import type { Client } from "../client/index.js";
 import { KnownScript } from "../client/knownScript.js";
+import { Codec, Entity, codec } from "../codec/index.js";
 import { Hex, HexLike, hexFrom } from "../hex/index.js";
 import { mol } from "../molecule/index.js";
 import {
@@ -9,7 +10,7 @@ import {
   NUM_TO_HASH_TYPE,
 } from "./script.advanced.js";
 
-export const HashTypeCodec: mol.Codec<HashTypeLike, HashType> = mol.Codec.from({
+export const HashTypeCodec: Codec<HashTypeLike, HashType> = Codec.from({
   byteLength: 1,
   encode: hashTypeToBytes,
   decode: hashTypeFromBytes,
@@ -108,14 +109,14 @@ export type ScriptLike = {
 /**
  * @public
  */
-@mol.codec(
+@codec(
   mol.table({
     codeHash: mol.Byte32,
     hashType: HashTypeCodec,
     args: mol.Bytes,
   }),
 )
-export class Script extends mol.Entity.Base<ScriptLike, Script>() {
+export class Script extends Entity.Base<ScriptLike, Script>() {
   /**
    * Creates an instance of Script.
    *