CCC Docs
    Preparing search index...

    Class Epoch

    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.
    const e = new Epoch(1n, 1n, 2n); // 1 + 1/2

    This class is primarily a thin value-object; operations return new Epoch instances.

    Hierarchy

    Index

    Constructors

    constructor

    Properties

    integer numerator denominator byteLength?

    Accessors

    0 1 2 Genesis OneNervosDaoCycle

    Methods

    normalizeBase normalizeCanonical toNum toPackedHex fromNum from clone compare lt le eq ge gt add sub toUnix encode decode fromBytes toBytes hash toHex

    Constructors

    • Construct a new Epoch instance.

      Parameters

      • integer: bigint

        Whole epoch units (Num/bigint)

      • numerator: bigint

        Fractional numerator (Num).

      • denominator: bigint

        Fractional denominator (Num).

      Returns Epoch

    Properties

    integer: bigint

    Whole epoch units (Num/bigint)

    numerator: bigint

    Fractional numerator (Num).

    denominator: bigint

    Fractional denominator (Num).

    byteLength?: number

    The bytes length of the entity, if it is fixed, otherwise undefined

    Accessors

    • get "0"(): bigint

      Backwards-compatible array-style index 0 referencing the whole epoch integer.

      Returns bigint

      integer portion (Num)

      Use .integer property instead.

    • get "1"(): bigint

      Backwards-compatible array-style index 1 referencing the epoch fractional numerator.

      Returns bigint

      numerator portion (Num)

      Use .numerator property instead.

    • get "2"(): bigint

      Backwards-compatible array-style index 2 referencing the epoch fractional denominator.

      Returns bigint

      denominator portion (Num)

      Use .denominator property instead.

    • get Genesis(): Epoch

      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

      Epoch with integer = 0, numerator = 0, denominator = 0.

    • get OneNervosDaoCycle(): Epoch

      Return an Epoch representing one Nervos DAO cycle (180 epochs exactly).

      Returns Epoch

      Epoch equal to 180 with denominator set to 1 to represent an exact whole unit.

    Methods

    • 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 Epoch

      New Epoch with denominator corrected (but fraction not reduced).

    • 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 Epoch

      Canonicalized Epoch with a non-negative, reduced fractional part and integer adjusted accordingly.

    • 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.

      Returns bigint

      Packed numeric representation (Num) suitable for RPC packing.

      If integer, numerator or denominator are negative.

      If integer, numerator or denominator overflow the packing limits.

    • 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 numToHex

      Returns `0x${string}`

      Hex string corresponding to the packed epoch.

    • Construct an Epoch by unpacking a RPC-style packed numeric form.

      Parameters

      • v: NumLike

        NumLike packed epoch (like Num and Hex)

      Returns Epoch

      Epoch whose integer, numerator and denominator are extracted from the packed layout.

    • 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.

      Parameters

      Returns Epoch

      Epoch instance

    • Return a deep copy of this Epoch.

      Returns Epoch

      New Epoch instance with identical components.

    • 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.

      Parameters

      • other: EpochLike

        Epoch-like value to compare against.

      Returns -1 | 0 | 1

      1 if this > other, 0 if equal, -1 if this < other.

      epochA.compare(epochB); // -1|0|1

    • Check whether this epoch is less than another EpochLike.

      Parameters

      • other: EpochLike

        EpochLike to compare against.

      Returns boolean

      true if this < other.

    • Check whether this epoch is less than or equal to another EpochLike.

      Parameters

      • other: EpochLike

        EpochLike to compare against.

      Returns boolean

      true if this <= other.

    • Check whether this epoch equals another EpochLike.

      Parameters

      • other: EpochLike

        EpochLike to compare against.

      Returns boolean

      true if equal.

    • Check whether this epoch is greater than or equal to another EpochLike.

      Parameters

      • other: EpochLike

        EpochLike to compare against.

      Returns boolean

      true if this >= other.

    • Check whether this epoch is greater than another EpochLike.

      Parameters

      • other: EpochLike

        EpochLike to compare against.

      Returns boolean

      true if this > other.

    • 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.

      Parameters

      Returns Epoch

      Normalized Epoch representing the sum.

    • 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.

      Parameters

      • other: EpochLike

        Epoch-like value to subtract.

      Returns Epoch

      Normalized Epoch representing this - other.

    • 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.

      Parameters

      • reference: Pick<ClientBlockHeader, "epoch" | "timestamp">

        Object providing epoch (Epoch) and timestamp (Num) fields, such as a ClientBlockHeader.

      • epochInMilliseconds: bigint = ...

        Duration of a single epoch in milliseconds. Defaults to 4 hours.

      Returns bigint

      Estimated Unix timestamp in milliseconds as bigint.

    • Encode the entity into bytes

      Parameters

      Returns Bytes

      The encoded bytes

      Will throw an error if the entity is not serializable

    • Decode the entity from bytes

      Parameters

      Returns Epoch

      The decoded entity

      Will throw an error if the entity is not serializable

    • Create an entity from bytes

      Parameters

      Returns Epoch

      The created entity

      Will throw an error if the entity is not serializable

    • Convert the entity to bytes

      Returns Bytes

      The bytes representation of the entity

    • Calculate the hash of the entity

      Returns `0x${string}`

      The hash of the entity

    • Convert the entity to a full-byte untrimmed Hex representation

      Returns `0x${string}`

      The entity full-byte untrimmed hexadecimal representation

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods