voltaire-effect 0.2.23 → 0.2.25

package/src/primitives/Hardfork/index.ts

@@ -1,39 +1,149 @@
 /**
  * @module Hardfork
- * @description Ethereum hardfork constants and identifiers.
+ * @description Ethereum hardfork constants and utilities.
+ *
+ * Hardforks represent protocol upgrades that change EVM behavior, gas costs,
+ * or add new features.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Hardfork from 'voltaire-effect/primitives/Hardfork'
+ *
+ * function checkFeatures(fork: Hardfork.HardforkType) {
+ *   // ...
+ * }
+ * ```
  *
  * ## Constants
  *
- * - `FRONTIER`, `HOMESTEAD`, `TANGERINE_WHISTLE`, `SPURIOUS_DRAGON`
- * - `BYZANTIUM`, `CONSTANTINOPLE`, `PETERSBURG`, `ISTANBUL`
- * - `MUIR_GLACIER`, `BERLIN`, `LONDON`, `ARROW_GLACIER`, `GRAY_GLACIER`
- * - `SHANGHAI`, `CANCUN`, `PRAGUE`
+ * ```typescript
+ * Hardfork.FRONTIER          // Original launch (July 2015)
+ * Hardfork.HOMESTEAD         // First planned hardfork
+ * Hardfork.BYZANTIUM         // Added REVERT, RETURNDATASIZE, etc.
+ * Hardfork.CONSTANTINOPLE    // Added CREATE2, shift opcodes
+ * Hardfork.ISTANBUL          // EIP-2200: Rebalanced SSTORE
+ * Hardfork.BERLIN            // EIP-2929: Cold/warm access
+ * Hardfork.LONDON            // EIP-1559: Base fee
+ * Hardfork.MERGE             // Proof of Stake transition
+ * Hardfork.SHANGHAI          // EIP-3855: PUSH0
+ * Hardfork.CANCUN            // EIP-4844: Blobs, EIP-1153: TLOAD/TSTORE
+ * Hardfork.PRAGUE            // EIP-2537: BLS12-381
+ * ```
+ *
+ * ## Pure Functions
  *
- * ## Usage
+ * ```typescript
+ * // Parsing
+ * Hardfork.fromString(name)           // HardforkType | undefined
+ * Hardfork.toString(fork)             // string
+ * Hardfork.isValidName(name)          // boolean
+ *
+ * // Listing
+ * Hardfork.allIds()                   // HardforkType[]
+ * Hardfork.allNames()                 // string[]
+ * Hardfork.range(start, end)          // HardforkType[]
+ *
+ * // Comparison
+ * Hardfork.compare(a, b)              // -1 | 0 | 1
+ * Hardfork.equals(a, b)               // boolean
+ * Hardfork.gt(a, b)                   // boolean
+ * Hardfork.gte(a, b)                  // boolean
+ * Hardfork.lt(a, b)                   // boolean
+ * Hardfork.lte(a, b)                  // boolean
+ * Hardfork.isAfter(fork, min)         // boolean
+ * Hardfork.isAtLeast(fork, min)       // boolean
+ * Hardfork.isBefore(fork, max)        // boolean
+ * Hardfork.min(forks)                 // HardforkType
+ * Hardfork.max(forks)                 // HardforkType
+ *
+ * // Feature checks
+ * Hardfork.hasEIP1153(fork)           // boolean (transient storage)
+ * Hardfork.hasEIP1559(fork)           // boolean (fee market)
+ * Hardfork.hasEIP3855(fork)           // boolean (PUSH0)
+ * Hardfork.hasEIP4844(fork)           // boolean (blobs)
+ * Hardfork.supportsBlobs(fork)        // boolean
+ * Hardfork.supportsEIP1559(fork)      // boolean
+ * Hardfork.supportsPUSH0(fork)        // boolean
+ * Hardfork.supportsTransientStorage(fork) // boolean
+ * Hardfork.isPoS(fork)                // boolean
+ * Hardfork.isPostMerge(fork)          // boolean
+ * ```
  *
+ * @example
  * ```typescript
  * import * as Hardfork from 'voltaire-effect/primitives/Hardfork'
  *
- * const hardfork = Hardfork.CANCUN
+ * const fork = Hardfork.CANCUN
+ *
+ * if (Hardfork.supportsBlobs(fork)) {
+ *   console.log('Blob transactions supported!')
+ * }
+ *
+ * if (Hardfork.isAtLeast(fork, Hardfork.SHANGHAI)) {
+ *   console.log('PUSH0 available')
+ * }
  * ```
  *
  * @since 0.1.0
  */
+
+// Re-export type
+export type { HardforkType } from "@tevm/voltaire/Hardfork";
+
+// Schema
+export { HardforkSchema } from "./HardforkSchema.js";
+
+// Parsing
+export { fromString } from "./fromString.js";
+export { toString } from "./toString.js";
+export { isValidName } from "./isValidName.js";
+
+// Listing
+export { allIds } from "./allIds.js";
+export { allNames } from "./allNames.js";
+export { range } from "./range.js";
+
+// Comparison
+export { compare } from "./compare.js";
+export { equals } from "./equals.js";
+export { gt, gte, lt, lte, isAfter, isAtLeast, isBefore } from "./comparisons.js";
+export { min, max } from "./minMax.js";
+
+// Feature checks
+export {
+	hasEIP1153,
+	hasEIP1559,
+	hasEIP3855,
+	hasEIP4844,
+	supportsBlobs,
+	supportsEIP1559,
+	supportsPUSH0,
+	supportsTransientStorage,
+	isPoS,
+	isPostMerge,
+} from "./features.js";
+
+// Constants
 export {
-	ARROW_GLACIER,
-	BERLIN,
-	BYZANTIUM,
-	CANCUN,
-	CONSTANTINOPLE,
 	FRONTIER,
-	GRAY_GLACIER,
 	HOMESTEAD,
+	DAO,
+	TANGERINE_WHISTLE,
+	SPURIOUS_DRAGON,
+	BYZANTIUM,
+	CONSTANTINOPLE,
+	PETERSBURG,
 	ISTANBUL,
-	LONDON,
 	MUIR_GLACIER,
-	PETERSBURG,
-	PRAGUE,
+	BERLIN,
+	LONDON,
+	ARROW_GLACIER,
+	GRAY_GLACIER,
+	MERGE,
 	SHANGHAI,
-	SPURIOUS_DRAGON,
-	TANGERINE_WHISTLE,
+	CANCUN,
+	PRAGUE,
+	OSAKA,
+	DEFAULT,
 } from "@tevm/voltaire/Hardfork";

package/src/primitives/Hardfork/isValidName.ts

@@ -0,0 +1,14 @@
+/**
+ * @module isValidName
+ * @description Validate hardfork name (pure)
+ * @since 0.1.0
+ */
+import * as Hardfork from "@tevm/voltaire/Hardfork";
+
+/**
+ * Check if a string is a valid hardfork name
+ *
+ * @param name - Name to validate
+ * @returns true if name is a valid hardfork
+ */
+export const isValidName: (name: string) => boolean = Hardfork.isValidName;

package/src/primitives/Hardfork/minMax.ts

@@ -0,0 +1,23 @@
+/**
+ * @module minMax
+ * @description Min/max hardfork functions (pure)
+ * @since 0.1.0
+ */
+import * as Hardfork from "@tevm/voltaire/Hardfork";
+import type { HardforkType } from "@tevm/voltaire/Hardfork";
+
+/**
+ * Get the minimum (earliest) hardfork from an array
+ *
+ * @param forks - Array of hardforks
+ * @returns Earliest hardfork
+ */
+export const min: (forks: HardforkType[]) => HardforkType = Hardfork.min;
+
+/**
+ * Get the maximum (latest) hardfork from an array
+ *
+ * @param forks - Array of hardforks
+ * @returns Latest hardfork
+ */
+export const max: (forks: HardforkType[]) => HardforkType = Hardfork.max;

package/src/primitives/Hardfork/range.ts

@@ -0,0 +1,19 @@
+/**
+ * @module range
+ * @description Get range of hardforks (pure)
+ * @since 0.1.0
+ */
+import * as Hardfork from "@tevm/voltaire/Hardfork";
+import type { HardforkType } from "@tevm/voltaire/Hardfork";
+
+/**
+ * Get a range of hardforks between start and end (inclusive)
+ *
+ * @param start - Start hardfork
+ * @param end - End hardfork
+ * @returns Array of hardforks in range
+ */
+export const range: (
+	start: HardforkType,
+	end: HardforkType,
+) => HardforkType[] = Hardfork.range;

package/src/primitives/Hardfork/toString.ts

@@ -0,0 +1,16 @@
+/**
+ * @module toString
+ * @description Convert hardfork to string (pure)
+ * @since 0.1.0
+ */
+import * as Hardfork from "@tevm/voltaire/Hardfork";
+import type { HardforkType } from "@tevm/voltaire/Hardfork";
+
+/**
+ * Convert hardfork to string name
+ *
+ * @param fork - Hardfork to convert
+ * @returns Hardfork name string
+ */
+// biome-ignore lint/suspicious/noShadowRestrictedNames: toString is the function name in our API
+export const toString: (fork: HardforkType) => string = Hardfork.toString;

package/src/primitives/Hash/Hash.test.ts

@@ -564,6 +564,110 @@ describe("error cases", () => {
 	});
 });
 
+describe("from functions", () => {
+	describe("from", () => {
+		it("parses valid hex string", () => {
+			const hash = Effect.runSync(Hash.from(`0x${"ab".repeat(32)}`));
+			expect(hash.length).toBe(32);
+		});
+
+		it("parses valid Uint8Array", () => {
+			const hash = Effect.runSync(Hash.from(new Uint8Array(32).fill(0xab)));
+			expect(hash.length).toBe(32);
+		});
+
+		it("fails on invalid hex", () => {
+			expect(() => Effect.runSync(Hash.from("invalid"))).toThrow();
+		});
+
+		it("fails on wrong length bytes", () => {
+			expect(() => Effect.runSync(Hash.from(new Uint8Array(16)))).toThrow();
+		});
+	});
+
+	describe("fromHex", () => {
+		it("parses valid hex", () => {
+			const hash = Effect.runSync(Hash.fromHex(`0x${"ab".repeat(32)}`));
+			expect(hash.length).toBe(32);
+		});
+
+		it("parses hex without 0x prefix", () => {
+			const hash = Effect.runSync(Hash.fromHex("ab".repeat(32)));
+			expect(hash.length).toBe(32);
+		});
+
+		it("fails on invalid characters", () => {
+			expect(() =>
+				Effect.runSync(Hash.fromHex(`0x${"gg".repeat(32)}`)),
+			).toThrow();
+		});
+
+		it("fails on wrong length", () => {
+			expect(() => Effect.runSync(Hash.fromHex(`0x${"ab".repeat(16)}`))).toThrow();
+		});
+	});
+
+	describe("fromBytes", () => {
+		it("parses valid 32-byte array", () => {
+			const hash = Effect.runSync(Hash.fromBytes(new Uint8Array(32)));
+			expect(hash.length).toBe(32);
+		});
+
+		it("fails on wrong length (too short)", () => {
+			expect(() => Effect.runSync(Hash.fromBytes(new Uint8Array(31)))).toThrow();
+		});
+
+		it("fails on wrong length (too long)", () => {
+			expect(() => Effect.runSync(Hash.fromBytes(new Uint8Array(33)))).toThrow();
+		});
+	});
+});
+
+describe("isHash", () => {
+	it("returns true for valid hash", () => {
+		const hash = S.decodeSync(Hash.Hex)(`0x${"ab".repeat(32)}`);
+		expect(Hash.isHash(hash)).toBe(true);
+	});
+
+	it("returns false for wrong length", () => {
+		expect(Hash.isHash(new Uint8Array(16))).toBe(false);
+	});
+
+	it("returns false for non-Uint8Array", () => {
+		expect(Hash.isHash("0x" + "ab".repeat(32))).toBe(false);
+	});
+
+	it("returns false for null", () => {
+		expect(Hash.isHash(null)).toBe(false);
+	});
+
+	it("returns false for undefined", () => {
+		expect(Hash.isHash(undefined)).toBe(false);
+	});
+});
+
+describe("toHex", () => {
+	it("converts hash to hex string", () => {
+		const hash = S.decodeSync(Hash.Hex)(`0x${"ab".repeat(32)}`);
+		expect(Hash.toHex(hash)).toBe(`0x${"ab".repeat(32)}`);
+	});
+
+	it("returns lowercase hex", () => {
+		const hash = S.decodeSync(Hash.Hex)(`0x${"AB".repeat(32)}`);
+		expect(Hash.toHex(hash)).toBe(`0x${"ab".repeat(32)}`);
+	});
+
+	it("produces 66-character string", () => {
+		const hash = S.decodeSync(Hash.Hex)(`0x${"00".repeat(32)}`);
+		expect(Hash.toHex(hash).length).toBe(66);
+	});
+
+	it("starts with 0x", () => {
+		const hash = S.decodeSync(Hash.Hex)(`0x${"ab".repeat(32)}`);
+		expect(Hash.toHex(hash).startsWith("0x")).toBe(true);
+	});
+});
+
 describe("additional edge cases", () => {
 	it("isValidHex with missing 0x prefix accepts raw hex", () => {
 		const result = Effect.runSync(Hash.isValidHex("ab".repeat(32)));

package/src/primitives/Hash/from.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Create Hash from string or bytes.
+ *
+ * @module Hash/from
+ * @since 0.0.1
+ */
+
+import type { HashType } from "@tevm/voltaire/Hash";
+import * as Hash from "@tevm/voltaire/Hash";
+import * as Effect from "effect/Effect";
+import { ValidationError } from "@tevm/voltaire/errors";
+
+/**
+ * Create Hash from string or bytes.
+ *
+ * @description Parses hex string or Uint8Array into a 32-byte hash.
+ * Can fail if input is invalid format or wrong length.
+ *
+ * @param {string | Uint8Array} value - Hex string or Uint8Array
+ * @returns {Effect.Effect<HashType, ValidationError>} Effect containing the hash
+ *
+ * @example
+ * ```typescript
+ * import * as Hash from 'voltaire-effect/primitives/Hash'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const hash = Effect.runSync(Hash.from('0x' + 'ab'.repeat(32)))
+ * const hash2 = Effect.runSync(Hash.from(new Uint8Array(32)))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const from = (
+	value: string | Uint8Array,
+): Effect.Effect<HashType, ValidationError> =>
+	Effect.try({
+		try: () => Hash.from(value),
+		catch: (error) =>
+			new ValidationError(
+				error instanceof Error ? error.message : "Invalid hash input",
+				{
+					value,
+					expected: "32-byte hash",
+					cause: error instanceof Error ? error : undefined,
+				},
+			),
+	});

package/src/primitives/Hash/fromBytes.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Create Hash from raw bytes.
+ *
+ * @module Hash/fromBytes
+ * @since 0.0.1
+ */
+
+import type { HashType } from "@tevm/voltaire/Hash";
+import * as Hash from "@tevm/voltaire/Hash";
+import * as Effect from "effect/Effect";
+import { ValidationError } from "@tevm/voltaire/errors";
+
+/**
+ * Create Hash from raw bytes.
+ *
+ * @description Creates a hash from a 32-byte Uint8Array.
+ * Can fail if input is wrong length.
+ *
+ * @param {Uint8Array} bytes - Raw bytes (must be 32 bytes)
+ * @returns {Effect.Effect<HashType, ValidationError>} Effect containing the hash
+ *
+ * @example
+ * ```typescript
+ * import * as Hash from 'voltaire-effect/primitives/Hash'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const hash = Effect.runSync(Hash.fromBytes(new Uint8Array(32)))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromBytes = (
+	bytes: Uint8Array,
+): Effect.Effect<HashType, ValidationError> =>
+	Effect.try({
+		try: () => Hash.fromBytes(bytes),
+		catch: (error) =>
+			new ValidationError(
+				error instanceof Error ? error.message : "Invalid bytes input",
+				{
+					value: bytes,
+					expected: "32-byte Uint8Array",
+					cause: error instanceof Error ? error : undefined,
+				},
+			),
+	});

package/src/primitives/Hash/fromHex.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Create Hash from hex string.
+ *
+ * @module Hash/fromHex
+ * @since 0.0.1
+ */
+
+import type { HashType } from "@tevm/voltaire/Hash";
+import * as Hash from "@tevm/voltaire/Hash";
+import * as Effect from "effect/Effect";
+import { ValidationError } from "@tevm/voltaire/errors";
+
+/**
+ * Create Hash from hex string.
+ *
+ * @description Parses a 66-character hex string (with 0x prefix) into a 32-byte hash.
+ * Can fail if input is invalid format or wrong length.
+ *
+ * @param {string} hex - Hex string with optional 0x prefix
+ * @returns {Effect.Effect<HashType, ValidationError>} Effect containing the hash
+ *
+ * @example
+ * ```typescript
+ * import * as Hash from 'voltaire-effect/primitives/Hash'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const hash = Effect.runSync(Hash.fromHex('0x' + 'ab'.repeat(32)))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromHex = (hex: string): Effect.Effect<HashType, ValidationError> =>
+	Effect.try({
+		try: () => Hash.fromHex(hex),
+		catch: (error) =>
+			new ValidationError(
+				error instanceof Error ? error.message : "Invalid hex string",
+				{
+					value: hex,
+					expected: "66-character hex string (0x + 64 hex chars)",
+					cause: error instanceof Error ? error : undefined,
+				},
+			),
+	});

package/src/primitives/Hash/index.ts

@@ -46,20 +46,57 @@
  */
 
 export type { HashType } from "@tevm/voltaire/Hash";
-// Pure functions
-export { assert } from "./assert.js";
+
+// Re-export constants
+export { SIZE, ZERO } from "@tevm/voltaire/Hash";
+
+// Re-export DI factory functions for advanced use cases
+// Access via: Hash.Keccak256, Hash.MerkleRoot, etc.
+// Note: These are runtime exports that TypeScript types don't fully capture
+import { Hash as HashNamespace } from "@tevm/voltaire/functional";
+const _HashNs = HashNamespace as Record<string, unknown>;
+export const Concat = _HashNs["Concat"] as typeof HashNamespace.concat;
+export const Keccak256 = _HashNs["Keccak256"] as (
+	keccak: { keccak256: (data: Uint8Array) => Uint8Array },
+) => (data: Uint8Array | string) => import("@tevm/voltaire/Hash").HashType;
+export const Keccak256Hex = _HashNs["Keccak256Hex"] as (
+	keccak: { keccak256: (data: Uint8Array) => Uint8Array },
+) => (hex: string) => import("@tevm/voltaire/Hash").HashType;
+export const Keccak256String = _HashNs["Keccak256String"] as (
+	keccak: { keccak256: (data: Uint8Array) => Uint8Array },
+) => (str: string) => import("@tevm/voltaire/Hash").HashType;
+export const MerkleRoot = _HashNs["MerkleRoot"] as (
+	keccak: { keccak256: (data: Uint8Array) => Uint8Array },
+) => (leaves: readonly Uint8Array[]) => import("@tevm/voltaire/Hash").HashType;
+
 // Schemas
 export { Bytes } from "./Bytes.js";
+export { Hex } from "./Hex.js";
+
+// Constructors (fallible)
+export { from } from "./from.js";
+export { fromBytes } from "./fromBytes.js";
+export { fromHex } from "./fromHex.js";
+
+// Validation
+export { assert } from "./assert.js";
+export { isHash } from "./isHash.js";
+export { isValidHex } from "./isValidHex.js";
+export { isZero } from "./isZero.js";
+
+// Operations
 export { clone } from "./clone.js";
 export { concat } from "./concat.js";
 export { equals } from "./equals.js";
+export { slice } from "./slice.js";
+
+// Conversions
 export { format } from "./format.js";
-export { Hex } from "./Hex.js";
-export { isValidHex } from "./isValidHex.js";
-export { isZero } from "./isZero.js";
+export { toBytes } from "./toBytes.js";
+export { toHex } from "./toHex.js";
+export { toString } from "./toString.js";
+
+// Crypto
 export { keccak256, keccak256Hex, keccak256String } from "./keccak256.js";
 export { merkleRoot } from "./merkleRoot.js";
 export { random } from "./random.js";
-export { slice } from "./slice.js";
-export { toBytes } from "./toBytes.js";
-export { toString } from "./toString.js";

package/src/primitives/Hash/isHash.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Check if value is a valid Hash.
+ *
+ * @module Hash/isHash
+ * @since 0.0.1
+ */
+
+import type { HashType } from "@tevm/voltaire/Hash";
+import * as Hash from "@tevm/voltaire/Hash";
+
+/**
+ * Check if value is a valid Hash.
+ *
+ * @description Type guard that checks if a value is a valid 32-byte hash.
+ * This is a pure synchronous function that never fails.
+ *
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if value is a valid HashType
+ *
+ * @example
+ * ```typescript
+ * import * as Hash from 'voltaire-effect/primitives/Hash'
+ *
+ * if (Hash.isHash(value)) {
+ *   // value is HashType
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const isHash = (value: unknown): value is HashType => Hash.isHash(value);

package/src/primitives/Hash/toHex.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Convert Hash to hex string.
+ *
+ * @module Hash/toHex
+ * @since 0.0.1
+ */
+
+import type { HashType } from "@tevm/voltaire/Hash";
+import * as Hash from "@tevm/voltaire/Hash";
+
+/**
+ * Convert Hash to hex string.
+ *
+ * @description Converts a 32-byte hash to a 66-character hex string with 0x prefix.
+ * This is a pure synchronous function that never fails.
+ *
+ * @param {HashType} hash - Hash to convert
+ * @returns {string} Hex string with 0x prefix
+ *
+ * @example
+ * ```typescript
+ * import * as Hash from 'voltaire-effect/primitives/Hash'
+ *
+ * const hex = Hash.toHex(hash) // "0x..."
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const toHex = (hash: HashType): string => Hash.toHex(hash);