Merge pull request #94 from IntersectMBO/feat/time-module

feat: add Time module for slot operations

Author: solidsnakedev

packages/evolution/src/core/Time/Slot.ts

@@ -0,0 +1,9 @@
+/**
+ * Slot number in the Cardano blockchain.
+ * Represents a discrete time unit in the blockchain.
+ * Each slot is typically 1 second (1000ms) on mainnet.
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export type Slot = bigint

packages/evolution/src/core/Time/SlotConfig.ts

@@ -0,0 +1,70 @@
+import type * as Network from "../Network.js"
+
+/**
+ * Slot configuration for a Cardano network.
+ * Defines the relationship between slots and Unix time.
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export interface SlotConfig {
+  /**
+   * Unix timestamp (in milliseconds) of the network start (Shelley era).
+   */
+  readonly zeroTime: bigint
+
+  /**
+   * First slot number of the Shelley era.
+   */
+  readonly zeroSlot: bigint
+
+  /**
+   * Duration of each slot in milliseconds (typically 1000ms = 1 second).
+   */
+  readonly slotLength: number
+}
+
+/**
+ * Network-specific slot configurations for all Cardano networks.
+ *
+ * - **Mainnet**: Production network starting at Shelley era
+ * - **Preview**: Preview testnet for protocol updates
+ * - **Preprod**: Pre-production testnet
+ * - **Custom**: Customizable for emulator/devnet (initialized with zeros)
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export const SLOT_CONFIG_NETWORK: Record<Network.Network, SlotConfig> = {
+  Mainnet: {
+    zeroTime: 1596059091000n, // Shelley era start
+    zeroSlot: 4492800n,
+    slotLength: 1000,
+  },
+  Preview: {
+    zeroTime: 1666656000000n,
+    zeroSlot: 0n,
+    slotLength: 1000,
+  },
+  Preprod: {
+    zeroTime: 1654041600000n + 1728000000n, // 1655769600000n
+    zeroSlot: 86400n,
+    slotLength: 1000,
+  },
+  Custom: {
+    zeroTime: 0n,
+    zeroSlot: 0n,
+    slotLength: 0,
+  },
+}
+
+/**
+ * Get slot configuration for a network.
+ *
+ * @param network - The network to get configuration for
+ * @returns Slot configuration for the network
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export const getSlotConfig = (network: Network.Network): SlotConfig => SLOT_CONFIG_NETWORK[network]

packages/evolution/src/core/Time/UnixTime.ts

@@ -0,0 +1,62 @@
+/**
+ * Unix time in milliseconds since epoch (January 1, 1970 00:00:00 UTC).
+ * Used for JavaScript Date interop and general time operations.
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export type UnixTime = bigint
+
+/**
+ * Convert UnixTime (milliseconds) to seconds.
+ *
+ * @param unixTime - Unix time in milliseconds
+ * @returns Unix time in seconds
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export const toSeconds = (unixTime: UnixTime): bigint => unixTime / 1000n
+
+/**
+ * Convert seconds to UnixTime (milliseconds).
+ *
+ * @param seconds - Time in seconds
+ * @returns Unix time in milliseconds
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export const fromSeconds = (seconds: bigint): UnixTime => seconds * 1000n
+
+/**
+ * Get current UnixTime.
+ *
+ * @returns Current Unix time in milliseconds
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export const now = (): UnixTime => BigInt(Date.now())
+
+/**
+ * Convert JavaScript Date to UnixTime.
+ *
+ * @param date - JavaScript Date object
+ * @returns Unix time in milliseconds
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export const fromDate = (date: Date): UnixTime => BigInt(date.getTime())
+
+/**
+ * Convert UnixTime to JavaScript Date.
+ *
+ * @param unixTime - Unix time in milliseconds
+ * @returns JavaScript Date object
+ *
+ * @category Time
+ * @since 2.0.0
+ */
+export const toDate = (unixTime: UnixTime): Date => new Date(Number(unixTime))

packages/evolution/src/core/Time/index.ts

@@ -0,0 +1,150 @@
+/**
+ * Time utilities for Cardano blockchain time operations.
+ * Provides type-safe conversions between slots and Unix time.
+ *
+ * @module Time
+ * @since 2.0.0
+ */
+
+import type * as Network from "../Network.js"
+import type * as Slot from "./Slot.js"
+import * as SlotConfig from "./SlotConfig.js"
+import * as UnixTime from "./UnixTime.js"
+
+export * as Slot from "./Slot.js"
+export * as SlotConfig from "./SlotConfig.js"
+export * as UnixTime from "./UnixTime.js"
+
+/**
+ * Convert a slot number to Unix time (in milliseconds).
+ *
+ * @param slot - The slot number to convert
+ * @param slotConfig - The network's slot configuration
+ * @returns Unix timestamp in milliseconds
+ *
+ * @category Conversion
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * import * as Time from "@evolution-sdk/core/Time"
+ *
+ * const slot = 12345678n
+ * const config = Time.SlotConfig.SLOT_CONFIG_NETWORK.Mainnet
+ * const unixTime = Time.slotToUnixTime(slot, config)
+ * console.log(unixTime) // Unix time in milliseconds
+ * ```
+ */
+export const slotToUnixTime = (slot: Slot.Slot, slotConfig: SlotConfig.SlotConfig): UnixTime.UnixTime => {
+  const msAfterBegin = (slot - slotConfig.zeroSlot) * BigInt(slotConfig.slotLength)
+  return slotConfig.zeroTime + msAfterBegin
+}
+
+/**
+ * Convert Unix time (in milliseconds) to the enclosing slot number.
+ * Uses floor division to find the slot that contains the given time.
+ *
+ * @param unixTime - Unix timestamp in milliseconds
+ * @param slotConfig - The network's slot configuration
+ * @returns The slot number that contains this Unix time
+ *
+ * @category Conversion
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * import * as Time from "@evolution-sdk/core/Time"
+ *
+ * const unixTime = 1596059091000n // Mainnet Shelley start
+ * const config = Time.SlotConfig.SLOT_CONFIG_NETWORK.Mainnet
+ * const slot = Time.unixTimeToSlot(unixTime, config)
+ * console.log(slot) // 4492800n
+ * ```
+ */
+export const unixTimeToSlot = (unixTime: UnixTime.UnixTime, slotConfig: SlotConfig.SlotConfig): Slot.Slot => {
+  const timePassed = unixTime - slotConfig.zeroTime
+  const slotsPassed = timePassed / BigInt(slotConfig.slotLength)
+  return slotsPassed + slotConfig.zeroSlot
+}
+
+/**
+ * Get the current slot number for a network.
+ *
+ * @param network - The network to get current slot for
+ * @returns Current slot number
+ *
+ * @category Utility
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * import * as Time from "@evolution-sdk/core/Time"
+ *
+ * const currentSlot = Time.getCurrentSlot("Mainnet")
+ * console.log(currentSlot) // Current mainnet slot
+ * ```
+ */
+export const getCurrentSlot = (network: Network.Network): Slot.Slot => {
+  const config = SlotConfig.SLOT_CONFIG_NETWORK[network]
+  const now = UnixTime.now()
+  return unixTimeToSlot(now, config)
+}
+
+/**
+ * Check if a slot is in the future relative to current time.
+ *
+ * @param slot - The slot to check
+ * @param slotConfig - The network's slot configuration
+ * @returns True if the slot is in the future
+ *
+ * @category Utility
+ * @since 2.0.0
+ */
+export const isSlotInFuture = (slot: Slot.Slot, slotConfig: SlotConfig.SlotConfig): boolean => {
+  const now = UnixTime.now()
+  const slotTime = slotToUnixTime(slot, slotConfig)
+  return slotTime > now
+}
+
+/**
+ * Check if a slot is in the past relative to current time.
+ *
+ * @param slot - The slot to check
+ * @param slotConfig - The network's slot configuration
+ * @returns True if the slot is in the past
+ *
+ * @category Utility
+ * @since 2.0.0
+ */
+export const isSlotInPast = (slot: Slot.Slot, slotConfig: SlotConfig.SlotConfig): boolean => {
+  const now = UnixTime.now()
+  const slotTime = slotToUnixTime(slot, slotConfig)
+  return slotTime < now
+}
+
+/**
+ * Get the slot at a specific offset from now (in milliseconds).
+ *
+ * @param offsetMs - Offset in milliseconds (positive for future, negative for past)
+ * @param network - The network
+ * @returns Slot number at the offset time
+ *
+ * @category Utility
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * import * as Time from "@evolution-sdk/core/Time"
+ *
+ * // Get slot 5 minutes from now
+ * const futureSlot = Time.getSlotAt(5 * 60 * 1000, "Mainnet")
+ *
+ * // Get slot 10 minutes ago
+ * const pastSlot = Time.getSlotAt(-10 * 60 * 1000, "Mainnet")
+ * ```
+ */
+export const getSlotAt = (offsetMs: number, network: Network.Network): Slot.Slot => {
+  const config = SlotConfig.SLOT_CONFIG_NETWORK[network]
+  const targetTime = UnixTime.now() + BigInt(offsetMs)
+  return unixTimeToSlot(targetTime, config)
+}

packages/evolution/src/core/index.ts

@@ -95,6 +95,7 @@ export * as SingleHostName from "./SingleHostName.js"
 export * as StakeReference from "./StakeReference.js"
 export * as Text from "./Text.js"
 export * as Text128 from "./Text128.js"
+export * as Time from "./Time/index.js"
 export * as Transaction from "./Transaction.js"
 export * as TransactionBody from "./TransactionBody.js"
 export * as TransactionHash from "./TransactionHash.js"