@eternl/network-id 0.46.0 → 0.47.0

package/README.md

@@ -27,6 +27,27 @@ if (isSupportedNetworkId(id)) {
 }
 ```
 
+## Caller-supplied slot timelines
+
+`@eternl/network-id/timeline` provides `createSlotTimeline` for a caller's explicit
+era boundaries. It snapshots and freezes the supplied data, checks continuity,
+and rejects unsafe integers. It does not register networks or select endpoints.
+
+```ts
+import { createSlotTimeline } from '@eternl/network-id/timeline'
+
+const timeline = createSlotTimeline([
+  { firstSlot: 0, startTimeMs: Date.UTC(2026, 0, 1), slotLengthMs: 1000 }
+])
+const time = timeline.timestampAtSlot(42)
+const firstSlot = timeline.slotAtOrAfter(time + 1) // 43
+```
+
+Times are nonnegative Unix milliseconds. `slotAtOrAfter` clamps timestamps before
+genesis to slot zero; it rounds up, so the inclusive last slot in `[start, end)`
+is `slotAtOrAfter(end) - 1`. Results beyond the safe integer range throw.
+Existing registered-network helpers and frontend network lists are unchanged.
+
 ## Exports
 
 - `NETWORK_ID`

package/dist/timeline.cjs

@@ -0,0 +1,58 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/timeline.ts
+const integer = (value, label) => {
+	if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${label} must be a nonnegative safe integer`);
+	return BigInt(value);
+};
+const safeNumber = (value) => {
+	if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("Slot timeline result exceeds the safe integer range");
+	return Number(value);
+};
+/** Build an immutable, continuous timeline from caller-supplied era boundaries. */
+const createSlotTimeline = (input) => {
+	if (!input.length) throw new RangeError("Slot timeline must contain at least one era");
+	const eras = input.map((era, index) => {
+		const firstSlot = integer(era.firstSlot, "First slot");
+		const startTimeMs = integer(era.startTimeMs, "Start time");
+		const slotLengthMs = integer(era.slotLengthMs, "Slot length");
+		const previous = input[index - 1];
+		if (slotLengthMs === 0n || index === 0 && firstSlot !== 0n) throw new RangeError("Slot timeline must start at slot zero with positive slot lengths");
+		if (previous && (era.firstSlot <= previous.firstSlot || startTimeMs !== BigInt(previous.startTimeMs) + (firstSlot - BigInt(previous.firstSlot)) * BigInt(previous.slotLengthMs))) throw new RangeError("Slot timeline eras must be ordered and continuous");
+		return Object.freeze({
+			firstSlot: era.firstSlot,
+			startTimeMs: era.startTimeMs,
+			slotLengthMs: era.slotLengthMs
+		});
+	});
+	const timestampAtSlot = (slot) => {
+		const value = integer(slot, "Slot");
+		let era = eras[0];
+		for (const candidate of eras) {
+			if (candidate.firstSlot > slot) break;
+			era = candidate;
+		}
+		return safeNumber(BigInt(era.startTimeMs) + (value - BigInt(era.firstSlot)) * BigInt(era.slotLengthMs));
+	};
+	/** First slot starting at or after a timestamp; timestamps before genesis clamp to zero. */
+	const slotAtOrAfter = (timestampMs) => {
+		const value = integer(timestampMs, "Timestamp");
+		let era = eras[0];
+		if (timestampMs <= era.startTimeMs) return 0;
+		for (const candidate of eras) {
+			if (candidate.startTimeMs > timestampMs) break;
+			era = candidate;
+		}
+		const length = BigInt(era.slotLengthMs);
+		const elapsed = value - BigInt(era.startTimeMs);
+		return safeNumber(BigInt(era.firstSlot) + (elapsed + length - 1n) / length);
+	};
+	return Object.freeze({
+		eras: Object.freeze(eras),
+		timestampAtSlot,
+		slotAtOrAfter
+	});
+};
+//#endregion
+exports.createSlotTimeline = createSlotTimeline;
+
+//# sourceMappingURL=timeline.cjs.map

package/dist/timeline.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.cjs","names":[],"sources":["../src/timeline.ts"],"sourcesContent":["export type SlotEra          = Readonly<{\n  firstSlot:                  number,\n  startTimeMs:                number,\n  slotLengthMs:               number,\n}>\n\nconst integer                 = (value: number, label: string): bigint => {\n\n  if (!Number.isSafeInteger(value) || value < 0) {\n\n    throw new RangeError(`${label} must be a nonnegative safe integer`)\n  }\n\n  return BigInt(value)\n}\n\nconst safeNumber              = (value: bigint): number => {\n\n  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {\n\n    throw new RangeError('Slot timeline result exceeds the safe integer range')\n  }\n\n  return Number(value)\n}\n\n/** Build an immutable, continuous timeline from caller-supplied era boundaries. */\nexport const createSlotTimeline = (input: readonly SlotEra[]) => {\n\n  if (!input.length) {\n\n    throw new RangeError('Slot timeline must contain at least one era')\n  }\n\n  const eras                  = input.map((era, index) => {\n\n    const firstSlot           = integer(era.firstSlot, 'First slot')\n    const startTimeMs         = integer(era.startTimeMs, 'Start time')\n    const slotLengthMs        = integer(era.slotLengthMs, 'Slot length')\n    const previous            = input[index - 1]\n\n    if (slotLengthMs === 0n || (index === 0 && firstSlot !== 0n)) {\n\n      throw new RangeError('Slot timeline must start at slot zero with positive slot lengths')\n    }\n\n    if (previous && (era.firstSlot <= previous.firstSlot || startTimeMs !== BigInt(previous.startTimeMs) +\n        (firstSlot - BigInt(previous.firstSlot)) * BigInt(previous.slotLengthMs))) {\n\n      throw new RangeError('Slot timeline eras must be ordered and continuous')\n    }\n\n    return Object.freeze({ firstSlot: era.firstSlot, startTimeMs: era.startTimeMs, slotLengthMs: era.slotLengthMs })\n  })\n\n  const timestampAtSlot       = (slot: number): number => {\n\n    const value               = integer(slot, 'Slot')\n    let era                   = eras[0]!\n\n    for (const candidate of eras) {\n\n      if (candidate.firstSlot > slot) break\n      era                     = candidate\n    }\n\n    return safeNumber(BigInt(era.startTimeMs) + (value - BigInt(era.firstSlot)) * BigInt(era.slotLengthMs))\n  }\n\n  /** First slot starting at or after a timestamp; timestamps before genesis clamp to zero. */\n  const slotAtOrAfter         = (timestampMs: number): number => {\n\n    const value               = integer(timestampMs, 'Timestamp')\n    let era                   = eras[0]!\n\n    if (timestampMs <= era.startTimeMs) return 0\n\n    for (const candidate of eras) {\n\n      if (candidate.startTimeMs > timestampMs) break\n      era                     = candidate\n    }\n\n    const length              = BigInt(era.slotLengthMs)\n    const elapsed             = value - BigInt(era.startTimeMs)\n\n    return safeNumber(BigInt(era.firstSlot) + (elapsed + length - 1n) / length)\n  }\n\n  return Object.freeze({ eras: Object.freeze(eras), timestampAtSlot, slotAtOrAfter })\n}\n\nexport type SlotTimeline      = ReturnType<typeof createSlotTimeline>\n"],"mappings":";;AAMA,MAAM,WAA2B,OAAe,UAA0B;CAExE,IAAI,CAAC,OAAO,cAAc,KAAK,KAAK,QAAQ,GAE1C,MAAM,IAAI,WAAW,GAAG,MAAM,oCAAoC;CAGpE,OAAO,OAAO,KAAK;AACrB;AAEA,MAAM,cAA2B,UAA0B;CAEzD,IAAI,QAAQ,OAAO,OAAO,gBAAgB,GAExC,MAAM,IAAI,WAAW,qDAAqD;CAG5E,OAAO,OAAO,KAAK;AACrB;;AAGA,MAAa,sBAAsB,UAA8B;CAE/D,IAAI,CAAC,MAAM,QAET,MAAM,IAAI,WAAW,6CAA6C;CAGpE,MAAM,OAAwB,MAAM,KAAK,KAAK,UAAU;EAEtD,MAAM,YAAsB,QAAQ,IAAI,WAAW,YAAY;EAC/D,MAAM,cAAsB,QAAQ,IAAI,aAAa,YAAY;EACjE,MAAM,eAAsB,QAAQ,IAAI,cAAc,aAAa;EACnE,MAAM,WAAsB,MAAM,QAAQ;EAE1C,IAAI,iBAAiB,MAAO,UAAU,KAAK,cAAc,IAEvD,MAAM,IAAI,WAAW,kEAAkE;EAGzF,IAAI,aAAa,IAAI,aAAa,SAAS,aAAa,gBAAgB,OAAO,SAAS,WAAW,KAC9F,YAAY,OAAO,SAAS,SAAS,KAAK,OAAO,SAAS,YAAY,IAEzE,MAAM,IAAI,WAAW,mDAAmD;EAG1E,OAAO,OAAO,OAAO;GAAE,WAAW,IAAI;GAAW,aAAa,IAAI;GAAa,cAAc,IAAI;EAAa,CAAC;CACjH,CAAC;CAED,MAAM,mBAAyB,SAAyB;EAEtD,MAAM,QAAsB,QAAQ,MAAM,MAAM;EAChD,IAAI,MAAwB,KAAK;EAEjC,KAAK,MAAM,aAAa,MAAM;GAE5B,IAAI,UAAU,YAAY,MAAM;GAChC,MAA0B;EAC5B;EAEA,OAAO,WAAW,OAAO,IAAI,WAAW,KAAK,QAAQ,OAAO,IAAI,SAAS,KAAK,OAAO,IAAI,YAAY,CAAC;CACxG;;CAGA,MAAM,iBAAyB,gBAAgC;EAE7D,MAAM,QAAsB,QAAQ,aAAa,WAAW;EAC5D,IAAI,MAAwB,KAAK;EAEjC,IAAI,eAAe,IAAI,aAAa,OAAO;EAE3C,KAAK,MAAM,aAAa,MAAM;GAE5B,IAAI,UAAU,cAAc,aAAa;GACzC,MAA0B;EAC5B;EAEA,MAAM,SAAsB,OAAO,IAAI,YAAY;EACnD,MAAM,UAAsB,QAAQ,OAAO,IAAI,WAAW;EAE1D,OAAO,WAAW,OAAO,IAAI,SAAS,KAAK,UAAU,SAAS,MAAM,MAAM;CAC5E;CAEA,OAAO,OAAO,OAAO;EAAE,MAAM,OAAO,OAAO,IAAI;EAAG;EAAiB;CAAc,CAAC;AACpF"}

package/dist/timeline.d.cts

@@ -0,0 +1,19 @@
+//#region src/timeline.d.ts
+export type SlotEra = Readonly<{
+  firstSlot: number;
+  startTimeMs: number;
+  slotLengthMs: number;
+}>;
+/** Build an immutable, continuous timeline from caller-supplied era boundaries. */
+export declare const createSlotTimeline: (input: readonly SlotEra[]) => Readonly<{
+  eras: readonly Readonly<{
+    firstSlot: number;
+    startTimeMs: number;
+    slotLengthMs: number;
+  }>[];
+  timestampAtSlot: (slot: number) => number;
+  slotAtOrAfter: (timestampMs: number) => number;
+}>;
+export type SlotTimeline = ReturnType<typeof createSlotTimeline>;
+//#endregion
+//# sourceMappingURL=timeline.d.cts.map

package/dist/timeline.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.cts","names":[],"sources":["../src/timeline.ts"],"mappings":";YAAY,UAAmB;EAC7B;EACA;EACA;;;qBAwBW,qBAAkB,gBAAoB,cAAS;;;;;;EA4BrB,kBAAA;EAeO,gBAAA;;YAsBlC,eAAoB,kBAAkB"}

package/dist/timeline.d.mts

@@ -0,0 +1,19 @@
+//#region src/timeline.d.ts
+export type SlotEra = Readonly<{
+  firstSlot: number;
+  startTimeMs: number;
+  slotLengthMs: number;
+}>;
+/** Build an immutable, continuous timeline from caller-supplied era boundaries. */
+export declare const createSlotTimeline: (input: readonly SlotEra[]) => Readonly<{
+  eras: readonly Readonly<{
+    firstSlot: number;
+    startTimeMs: number;
+    slotLengthMs: number;
+  }>[];
+  timestampAtSlot: (slot: number) => number;
+  slotAtOrAfter: (timestampMs: number) => number;
+}>;
+export type SlotTimeline = ReturnType<typeof createSlotTimeline>;
+//#endregion
+//# sourceMappingURL=timeline.d.mts.map

package/dist/timeline.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.mts","names":[],"sources":["../src/timeline.ts"],"mappings":";YAAY,UAAmB;EAC7B;EACA;EACA;;;qBAwBW,qBAAkB,gBAAoB,cAAS;;;;;;EA4BrB,kBAAA;EAeO,gBAAA;;YAsBlC,eAAoB,kBAAkB"}

package/dist/timeline.mjs

@@ -0,0 +1,57 @@
+//#region src/timeline.ts
+const integer = (value, label) => {
+	if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${label} must be a nonnegative safe integer`);
+	return BigInt(value);
+};
+const safeNumber = (value) => {
+	if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError("Slot timeline result exceeds the safe integer range");
+	return Number(value);
+};
+/** Build an immutable, continuous timeline from caller-supplied era boundaries. */
+const createSlotTimeline = (input) => {
+	if (!input.length) throw new RangeError("Slot timeline must contain at least one era");
+	const eras = input.map((era, index) => {
+		const firstSlot = integer(era.firstSlot, "First slot");
+		const startTimeMs = integer(era.startTimeMs, "Start time");
+		const slotLengthMs = integer(era.slotLengthMs, "Slot length");
+		const previous = input[index - 1];
+		if (slotLengthMs === 0n || index === 0 && firstSlot !== 0n) throw new RangeError("Slot timeline must start at slot zero with positive slot lengths");
+		if (previous && (era.firstSlot <= previous.firstSlot || startTimeMs !== BigInt(previous.startTimeMs) + (firstSlot - BigInt(previous.firstSlot)) * BigInt(previous.slotLengthMs))) throw new RangeError("Slot timeline eras must be ordered and continuous");
+		return Object.freeze({
+			firstSlot: era.firstSlot,
+			startTimeMs: era.startTimeMs,
+			slotLengthMs: era.slotLengthMs
+		});
+	});
+	const timestampAtSlot = (slot) => {
+		const value = integer(slot, "Slot");
+		let era = eras[0];
+		for (const candidate of eras) {
+			if (candidate.firstSlot > slot) break;
+			era = candidate;
+		}
+		return safeNumber(BigInt(era.startTimeMs) + (value - BigInt(era.firstSlot)) * BigInt(era.slotLengthMs));
+	};
+	/** First slot starting at or after a timestamp; timestamps before genesis clamp to zero. */
+	const slotAtOrAfter = (timestampMs) => {
+		const value = integer(timestampMs, "Timestamp");
+		let era = eras[0];
+		if (timestampMs <= era.startTimeMs) return 0;
+		for (const candidate of eras) {
+			if (candidate.startTimeMs > timestampMs) break;
+			era = candidate;
+		}
+		const length = BigInt(era.slotLengthMs);
+		const elapsed = value - BigInt(era.startTimeMs);
+		return safeNumber(BigInt(era.firstSlot) + (elapsed + length - 1n) / length);
+	};
+	return Object.freeze({
+		eras: Object.freeze(eras),
+		timestampAtSlot,
+		slotAtOrAfter
+	});
+};
+//#endregion
+export { createSlotTimeline };
+
+//# sourceMappingURL=timeline.mjs.map

package/dist/timeline.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.mjs","names":[],"sources":["../src/timeline.ts"],"sourcesContent":["export type SlotEra          = Readonly<{\n  firstSlot:                  number,\n  startTimeMs:                number,\n  slotLengthMs:               number,\n}>\n\nconst integer                 = (value: number, label: string): bigint => {\n\n  if (!Number.isSafeInteger(value) || value < 0) {\n\n    throw new RangeError(`${label} must be a nonnegative safe integer`)\n  }\n\n  return BigInt(value)\n}\n\nconst safeNumber              = (value: bigint): number => {\n\n  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {\n\n    throw new RangeError('Slot timeline result exceeds the safe integer range')\n  }\n\n  return Number(value)\n}\n\n/** Build an immutable, continuous timeline from caller-supplied era boundaries. */\nexport const createSlotTimeline = (input: readonly SlotEra[]) => {\n\n  if (!input.length) {\n\n    throw new RangeError('Slot timeline must contain at least one era')\n  }\n\n  const eras                  = input.map((era, index) => {\n\n    const firstSlot           = integer(era.firstSlot, 'First slot')\n    const startTimeMs         = integer(era.startTimeMs, 'Start time')\n    const slotLengthMs        = integer(era.slotLengthMs, 'Slot length')\n    const previous            = input[index - 1]\n\n    if (slotLengthMs === 0n || (index === 0 && firstSlot !== 0n)) {\n\n      throw new RangeError('Slot timeline must start at slot zero with positive slot lengths')\n    }\n\n    if (previous && (era.firstSlot <= previous.firstSlot || startTimeMs !== BigInt(previous.startTimeMs) +\n        (firstSlot - BigInt(previous.firstSlot)) * BigInt(previous.slotLengthMs))) {\n\n      throw new RangeError('Slot timeline eras must be ordered and continuous')\n    }\n\n    return Object.freeze({ firstSlot: era.firstSlot, startTimeMs: era.startTimeMs, slotLengthMs: era.slotLengthMs })\n  })\n\n  const timestampAtSlot       = (slot: number): number => {\n\n    const value               = integer(slot, 'Slot')\n    let era                   = eras[0]!\n\n    for (const candidate of eras) {\n\n      if (candidate.firstSlot > slot) break\n      era                     = candidate\n    }\n\n    return safeNumber(BigInt(era.startTimeMs) + (value - BigInt(era.firstSlot)) * BigInt(era.slotLengthMs))\n  }\n\n  /** First slot starting at or after a timestamp; timestamps before genesis clamp to zero. */\n  const slotAtOrAfter         = (timestampMs: number): number => {\n\n    const value               = integer(timestampMs, 'Timestamp')\n    let era                   = eras[0]!\n\n    if (timestampMs <= era.startTimeMs) return 0\n\n    for (const candidate of eras) {\n\n      if (candidate.startTimeMs > timestampMs) break\n      era                     = candidate\n    }\n\n    const length              = BigInt(era.slotLengthMs)\n    const elapsed             = value - BigInt(era.startTimeMs)\n\n    return safeNumber(BigInt(era.firstSlot) + (elapsed + length - 1n) / length)\n  }\n\n  return Object.freeze({ eras: Object.freeze(eras), timestampAtSlot, slotAtOrAfter })\n}\n\nexport type SlotTimeline      = ReturnType<typeof createSlotTimeline>\n"],"mappings":";AAMA,MAAM,WAA2B,OAAe,UAA0B;CAExE,IAAI,CAAC,OAAO,cAAc,KAAK,KAAK,QAAQ,GAE1C,MAAM,IAAI,WAAW,GAAG,MAAM,oCAAoC;CAGpE,OAAO,OAAO,KAAK;AACrB;AAEA,MAAM,cAA2B,UAA0B;CAEzD,IAAI,QAAQ,OAAO,OAAO,gBAAgB,GAExC,MAAM,IAAI,WAAW,qDAAqD;CAG5E,OAAO,OAAO,KAAK;AACrB;;AAGA,MAAa,sBAAsB,UAA8B;CAE/D,IAAI,CAAC,MAAM,QAET,MAAM,IAAI,WAAW,6CAA6C;CAGpE,MAAM,OAAwB,MAAM,KAAK,KAAK,UAAU;EAEtD,MAAM,YAAsB,QAAQ,IAAI,WAAW,YAAY;EAC/D,MAAM,cAAsB,QAAQ,IAAI,aAAa,YAAY;EACjE,MAAM,eAAsB,QAAQ,IAAI,cAAc,aAAa;EACnE,MAAM,WAAsB,MAAM,QAAQ;EAE1C,IAAI,iBAAiB,MAAO,UAAU,KAAK,cAAc,IAEvD,MAAM,IAAI,WAAW,kEAAkE;EAGzF,IAAI,aAAa,IAAI,aAAa,SAAS,aAAa,gBAAgB,OAAO,SAAS,WAAW,KAC9F,YAAY,OAAO,SAAS,SAAS,KAAK,OAAO,SAAS,YAAY,IAEzE,MAAM,IAAI,WAAW,mDAAmD;EAG1E,OAAO,OAAO,OAAO;GAAE,WAAW,IAAI;GAAW,aAAa,IAAI;GAAa,cAAc,IAAI;EAAa,CAAC;CACjH,CAAC;CAED,MAAM,mBAAyB,SAAyB;EAEtD,MAAM,QAAsB,QAAQ,MAAM,MAAM;EAChD,IAAI,MAAwB,KAAK;EAEjC,KAAK,MAAM,aAAa,MAAM;GAE5B,IAAI,UAAU,YAAY,MAAM;GAChC,MAA0B;EAC5B;EAEA,OAAO,WAAW,OAAO,IAAI,WAAW,KAAK,QAAQ,OAAO,IAAI,SAAS,KAAK,OAAO,IAAI,YAAY,CAAC;CACxG;;CAGA,MAAM,iBAAyB,gBAAgC;EAE7D,MAAM,QAAsB,QAAQ,aAAa,WAAW;EAC5D,IAAI,MAAwB,KAAK;EAEjC,IAAI,eAAe,IAAI,aAAa,OAAO;EAE3C,KAAK,MAAM,aAAa,MAAM;GAE5B,IAAI,UAAU,cAAc,aAAa;GACzC,MAA0B;EAC5B;EAEA,MAAM,SAAsB,OAAO,IAAI,YAAY;EACnD,MAAM,UAAsB,QAAQ,OAAO,IAAI,WAAW;EAE1D,OAAO,WAAW,OAAO,IAAI,SAAS,KAAK,UAAU,SAAS,MAAM,MAAM;CAC5E;CAEA,OAAO,OAAO,OAAO;EAAE,MAAM,OAAO,OAAO,IAAI;EAAG;EAAiB;CAAc,CAAC;AACpF"}

package/llms.txt

@@ -13,6 +13,7 @@
 - [`@eternl/network-id`](./dist/index.d.mts)
 - [`@eternl/network-id/chain`](./dist/chain.d.mts)
 - [`@eternl/network-id/network/*`](./dist/network/)
+- [`@eternl/network-id/timeline`](./dist/timeline.d.mts)
 - [`@eternl/network-id/types/*`](./dist/types/)
 
 ## Optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eternl/network-id",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Network identifiers and network-level metadata for Eternl packages",
   "license": "BUSL-1.1",
   "type": "module",
@@ -28,6 +28,11 @@
       "types": "./dist/types/*.d.mts",
       "import": "./dist/types/*.mjs",
       "require": "./dist/types/*.cjs"
+    },
+    "./timeline": {
+      "types": "./dist/timeline.d.mts",
+      "import": "./dist/timeline.mjs",
+      "require": "./dist/timeline.cjs"
     }
   },
   "files": [