voltaire-effect 0.2.23 → 0.2.24

package/src/primitives/Blob/splitData.ts

@@ -0,0 +1,36 @@
+/**
+ * @module splitData
+ * @description Split large data into multiple blobs
+ * @since 0.1.0
+ */
+import { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+import { Effect } from "effect";
+import type { InvalidBlobDataSizeError } from "@tevm/voltaire/Blob";
+
+type BrandedBlob = BlobNamespace.BrandedBlob;
+
+/**
+ * Split large data into multiple blobs.
+ *
+ * Each blob holds up to 126972 bytes of data (max 6 blobs per transaction).
+ *
+ * @param data - Data to split
+ * @returns Effect yielding array of blobs or failing with InvalidBlobDataSizeError
+ * @throws {InvalidBlobDataSizeError} If data requires more than 6 blobs
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const largeData = new Uint8Array(300000)
+ * const blobs = await Effect.runPromise(Blob.splitData(largeData)) // [blob1, blob2, blob3]
+ * ```
+ * @since 0.1.0
+ */
+export const splitData = (
+	data: Uint8Array,
+): Effect.Effect<BrandedBlob[], InvalidBlobDataSizeError> =>
+	Effect.try({
+		try: () => BlobNamespace.splitData(data),
+		catch: (e) => e as InvalidBlobDataSizeError,
+	});

package/src/primitives/Blob/toCommitment.ts

@@ -0,0 +1,43 @@
+/**
+ * @module toCommitment
+ * @description Compute KZG commitment for blob using KZGService
+ * @since 0.1.0
+ */
+import type { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+import { Effect } from "effect";
+import {
+	type KZGError,
+	KZGService,
+} from "../../crypto/KZG/KZGService.js";
+
+type BrandedBlob = BlobNamespace.BrandedBlob;
+type Commitment = BlobNamespace.Commitment;
+
+/**
+ * Compute KZG commitment for blob.
+ *
+ * Requires KZGService to be provided in the Effect context.
+ *
+ * @param blob - 128KB blob data
+ * @returns Effect yielding 48-byte commitment, requiring KZGService
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ * import { KZGLive } from 'voltaire-effect/crypto/KZG'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Blob.toCommitment(blob).pipe(Effect.provide(KZGLive))
+ * const commitment = await Effect.runPromise(program)
+ * ```
+ * @since 0.1.0
+ */
+export const toCommitment = (
+	blob: BrandedBlob,
+): Effect.Effect<Commitment, KZGError, KZGService> =>
+	Effect.gen(function* () {
+		const kzg = yield* KZGService;
+		const commitment = yield* kzg.blobToKzgCommitment(
+			blob as unknown as import("@tevm/voltaire").KzgBlobType,
+		);
+		return commitment as unknown as Commitment;
+	});

package/src/primitives/Blob/toProof.ts

@@ -0,0 +1,50 @@
+/**
+ * @module toProof
+ * @description Generate KZG proof for blob using KZGService
+ * @since 0.1.0
+ */
+import type { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+import { Effect } from "effect";
+import {
+	type KZGError,
+	KZGService,
+} from "../../crypto/KZG/KZGService.js";
+
+type BrandedBlob = BlobNamespace.BrandedBlob;
+type Commitment = BlobNamespace.Commitment;
+type Proof = BlobNamespace.Proof;
+
+/**
+ * Generate KZG proof for blob and commitment.
+ *
+ * Requires KZGService to be provided in the Effect context.
+ *
+ * @param blob - 128KB blob data
+ * @param commitment - 48-byte KZG commitment
+ * @returns Effect yielding 48-byte proof, requiring KZGService
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ * import { KZGLive } from 'voltaire-effect/crypto/KZG'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const commitment = yield* Blob.toCommitment(blob)
+ *   const proof = yield* Blob.toProof(blob, commitment)
+ *   return proof
+ * }).pipe(Effect.provide(KZGLive))
+ * ```
+ * @since 0.1.0
+ */
+export const toProof = (
+	blob: BrandedBlob,
+	commitment: Commitment,
+): Effect.Effect<Proof, KZGError, KZGService> =>
+	Effect.gen(function* () {
+		const kzg = yield* KZGService;
+		const proof = yield* kzg.computeBlobKzgProof(
+			blob as unknown as import("@tevm/voltaire").KzgBlobType,
+			commitment as unknown as import("@tevm/voltaire").KzgCommitmentType,
+		);
+		return proof as unknown as Proof;
+	});

package/src/primitives/Blob/toVersionedHash.ts

@@ -0,0 +1,35 @@
+/**
+ * @module toVersionedHash
+ * @description Create versioned hash from commitment
+ * @since 0.1.0
+ */
+import { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+import type { InvalidCommitmentSizeError } from "@tevm/voltaire/Blob";
+import { Effect } from "effect";
+
+type Commitment = BlobNamespace.Commitment;
+type VersionedHash = BlobNamespace.VersionedHash;
+
+/**
+ * Create versioned hash from commitment.
+ *
+ * Formula: BLOB_COMMITMENT_VERSION_KZG (0x01) || sha256(commitment)[1:]
+ *
+ * @param commitment - 48-byte KZG commitment
+ * @returns Effect yielding 32-byte versioned hash or failing with InvalidCommitmentSizeError
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const hash = await Effect.runPromise(Blob.toVersionedHash(commitment))
+ * ```
+ * @since 0.1.0
+ */
+export const toVersionedHash = (
+	commitment: Commitment,
+): Effect.Effect<VersionedHash, InvalidCommitmentSizeError> =>
+	Effect.try({
+		try: () => BlobNamespace.toVersionedHash(commitment),
+		catch: (e) => e as InvalidCommitmentSizeError,
+	});

package/src/primitives/Blob/verify.ts

@@ -0,0 +1,49 @@
+/**
+ * @module verify
+ * @description Verify KZG proof for blob using KZGService
+ * @since 0.1.0
+ */
+import type { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+import { Effect } from "effect";
+import {
+	type KZGError,
+	KZGService,
+} from "../../crypto/KZG/KZGService.js";
+
+type BrandedBlob = BlobNamespace.BrandedBlob;
+type Commitment = BlobNamespace.Commitment;
+type Proof = BlobNamespace.Proof;
+
+/**
+ * Verify KZG proof for blob and commitment.
+ *
+ * Requires KZGService to be provided in the Effect context.
+ *
+ * @param blob - 128KB blob data
+ * @param commitment - 48-byte KZG commitment
+ * @param proof - 48-byte KZG proof
+ * @returns Effect yielding boolean (true if valid), requiring KZGService
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ * import { KZGLive } from 'voltaire-effect/crypto/KZG'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Blob.verify(blob, commitment, proof).pipe(Effect.provide(KZGLive))
+ * const isValid = await Effect.runPromise(program)
+ * ```
+ * @since 0.1.0
+ */
+export const verify = (
+	blob: BrandedBlob,
+	commitment: Commitment,
+	proof: Proof,
+): Effect.Effect<boolean, KZGError, KZGService> =>
+	Effect.gen(function* () {
+		const kzg = yield* KZGService;
+		return yield* kzg.verifyBlobKzgProof(
+			blob as unknown as import("@tevm/voltaire").KzgBlobType,
+			commitment as unknown as import("@tevm/voltaire").KzgCommitmentType,
+			proof as unknown as import("@tevm/voltaire").KzgProofType,
+		);
+	});

package/src/primitives/Blob/verifyBatch.ts

@@ -0,0 +1,119 @@
+/**
+ * @module verifyBatch
+ * @description Verify batch of KZG proofs for blobs
+ * @since 0.1.0
+ */
+import type { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+import {
+	BlobArrayLengthMismatchError,
+	BlobNotImplementedError,
+	InvalidBlobCountError,
+	InvalidBlobSizeError,
+	InvalidCommitmentSizeError,
+	InvalidProofSizeError,
+	MAX_PER_TRANSACTION,
+	SIZE,
+} from "@tevm/voltaire/Blob";
+import { Effect } from "effect";
+
+type BrandedBlob = BlobNamespace.BrandedBlob;
+type Commitment = BlobNamespace.Commitment;
+type Proof = BlobNamespace.Proof;
+
+type VerifyBatchError =
+	| BlobArrayLengthMismatchError
+	| InvalidBlobCountError
+	| InvalidBlobSizeError
+	| InvalidCommitmentSizeError
+	| InvalidProofSizeError
+	| BlobNotImplementedError;
+
+/**
+ * Verify batch of KZG proofs for blobs.
+ *
+ * Note: Batch verification is not yet implemented. This function validates
+ * inputs and throws BlobNotImplementedError.
+ *
+ * @param blobs - Array of 128KB blobs
+ * @param commitments - Array of 48-byte commitments
+ * @param proofs - Array of 48-byte proofs
+ * @returns Effect failing with BlobNotImplementedError (not yet implemented)
+ * @throws {BlobArrayLengthMismatchError} If array lengths don't match
+ * @throws {InvalidBlobCountError} If too many blobs
+ * @throws {InvalidBlobSizeError} If blob size is invalid
+ * @throws {InvalidCommitmentSizeError} If commitment size is invalid
+ * @throws {InvalidProofSizeError} If proof size is invalid
+ * @throws {BlobNotImplementedError} Always (not yet implemented)
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Blob.verifyBatch(blobs, commitments, proofs)
+ * // Will fail with BlobNotImplementedError
+ * ```
+ * @since 0.1.0
+ */
+export const verifyBatch = (
+	blobs: readonly BrandedBlob[],
+	commitments: readonly Commitment[],
+	proofs: readonly Proof[],
+): Effect.Effect<boolean, VerifyBatchError> =>
+	Effect.try({
+		try: (): boolean => {
+			if (
+				blobs.length !== commitments.length ||
+				blobs.length !== proofs.length
+			) {
+				throw new BlobArrayLengthMismatchError("Arrays must have same length", {
+					value: {
+						blobs: blobs.length,
+						commitments: commitments.length,
+						proofs: proofs.length,
+					},
+					expected: "equal array lengths",
+				});
+			}
+			if (blobs.length > MAX_PER_TRANSACTION) {
+				throw new InvalidBlobCountError("Too many blobs", {
+					value: blobs.length,
+					expected: `max ${MAX_PER_TRANSACTION} blobs`,
+				});
+			}
+			for (let i = 0; i < blobs.length; i++) {
+				const blob = blobs[i] as Uint8Array;
+				if (blob.length !== SIZE) {
+					throw new InvalidBlobSizeError("Invalid blob size", {
+						value: blob.length,
+						expected: `${SIZE} bytes`,
+						context: { index: i },
+					});
+				}
+			}
+			for (let i = 0; i < commitments.length; i++) {
+				const commitment = commitments[i] as unknown as Uint8Array;
+				if (commitment.length !== 48) {
+					throw new InvalidCommitmentSizeError("Invalid commitment size", {
+						value: commitment.length,
+						expected: "48 bytes",
+						context: { index: i },
+					});
+				}
+			}
+			for (let i = 0; i < proofs.length; i++) {
+				const proof = proofs[i] as unknown as Uint8Array;
+				if (proof.length !== 48) {
+					throw new InvalidProofSizeError("Invalid proof size", {
+						value: proof.length,
+						expected: "48 bytes",
+						context: { index: i },
+					});
+				}
+			}
+			throw new BlobNotImplementedError("Not implemented", {
+				value: "verifyBatch",
+				expected: "implementation",
+			});
+		},
+		catch: (e) => e as VerifyBatchError,
+	});

package/src/primitives/BloomFilter/BloomFilter.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as BloomFilter from "./index.js";
+
+describe("BloomFilter.create", () => {
+	it("creates a filter with valid parameters", async () => {
+		const program = BloomFilter.create(2048, 3);
+		const filter = await Effect.runPromise(program);
+		expect(filter).toBeInstanceOf(Uint8Array);
+		expect(filter.length).toBe(256); // 2048 bits / 8
+		expect(filter.m).toBe(2048);
+		expect(filter.k).toBe(3);
+	});
+
+	it("fails on invalid parameters (m <= 0)", async () => {
+		const program = BloomFilter.create(0, 3);
+		const result = await Effect.runPromiseExit(program);
+		expect(result._tag).toBe("Failure");
+	});
+
+	it("fails on invalid parameters (k <= 0)", async () => {
+		const program = BloomFilter.create(2048, 0);
+		const result = await Effect.runPromiseExit(program);
+		expect(result._tag).toBe("Failure");
+	});
+});
+
+describe("BloomFilter.fromHex", () => {
+	it("creates filter from valid hex", async () => {
+		const hex = "0x" + "00".repeat(256);
+		const program = BloomFilter.fromHex(hex, 2048, 3);
+		const filter = await Effect.runPromise(program);
+		expect(filter.length).toBe(256);
+		expect(filter.m).toBe(2048);
+		expect(filter.k).toBe(3);
+	});
+
+	it("fails on wrong hex length", async () => {
+		const hex = "0x" + "00".repeat(128);
+		const program = BloomFilter.fromHex(hex, 2048, 3);
+		const result = await Effect.runPromiseExit(program);
+		expect(result._tag).toBe("Failure");
+	});
+});
+
+describe("BloomFilter pure functions", () => {
+	it("add and contains", async () => {
+		const filter = await Effect.runPromise(BloomFilter.create(2048, 3));
+		const item = new Uint8Array([1, 2, 3, 4, 5]);
+
+		expect(BloomFilter.contains(filter, item)).toBe(false);
+		BloomFilter.add(filter, item);
+		expect(BloomFilter.contains(filter, item)).toBe(true);
+	});
+
+	it("isEmpty", async () => {
+		const filter = await Effect.runPromise(BloomFilter.create(2048, 3));
+		expect(BloomFilter.isEmpty(filter)).toBe(true);
+
+		BloomFilter.add(filter, new Uint8Array([1, 2, 3]));
+		expect(BloomFilter.isEmpty(filter)).toBe(false);
+	});
+
+	it("density", async () => {
+		const filter = await Effect.runPromise(BloomFilter.create(2048, 3));
+		expect(BloomFilter.density(filter)).toBe(0);
+
+		BloomFilter.add(filter, new Uint8Array([1, 2, 3]));
+		expect(BloomFilter.density(filter)).toBeGreaterThan(0);
+	});
+
+	it("toHex", async () => {
+		const filter = await Effect.runPromise(BloomFilter.create(2048, 3));
+		const hex = BloomFilter.toHex(filter);
+		expect(hex).toMatch(/^0x[0-9a-f]+$/i);
+		expect(hex.length).toBe(514); // 0x + 512 hex chars
+	});
+
+	it("merge", async () => {
+		const filter1 = await Effect.runPromise(BloomFilter.create(2048, 3));
+		const filter2 = await Effect.runPromise(BloomFilter.create(2048, 3));
+
+		BloomFilter.add(filter1, new Uint8Array([1, 2, 3]));
+		BloomFilter.add(filter2, new Uint8Array([4, 5, 6]));
+
+		const merged = BloomFilter.merge(filter1, filter2);
+		expect(BloomFilter.contains(merged, new Uint8Array([1, 2, 3]))).toBe(true);
+		expect(BloomFilter.contains(merged, new Uint8Array([4, 5, 6]))).toBe(true);
+	});
+
+	it("combine", async () => {
+		const filter1 = await Effect.runPromise(BloomFilter.create(2048, 3));
+		const filter2 = await Effect.runPromise(BloomFilter.create(2048, 3));
+		const filter3 = await Effect.runPromise(BloomFilter.create(2048, 3));
+
+		BloomFilter.add(filter1, new Uint8Array([1]));
+		BloomFilter.add(filter2, new Uint8Array([2]));
+		BloomFilter.add(filter3, new Uint8Array([3]));
+
+		const combined = BloomFilter.combine(filter1, filter2, filter3);
+		expect(BloomFilter.contains(combined, new Uint8Array([1]))).toBe(true);
+		expect(BloomFilter.contains(combined, new Uint8Array([2]))).toBe(true);
+		expect(BloomFilter.contains(combined, new Uint8Array([3]))).toBe(true);
+	});
+
+	it("hash", () => {
+		const item = new Uint8Array([1, 2, 3, 4, 5]);
+		const h = BloomFilter.hash(item, 0, 2048);
+		expect(h).toBeGreaterThanOrEqual(0);
+		expect(h).toBeLessThan(2048);
+	});
+
+	it("hashFromKeccak", () => {
+		const keccakHash = new Uint8Array(32).fill(0xff);
+		const h = BloomFilter.hashFromKeccak(keccakHash, 0, 2048);
+		expect(h).toBeGreaterThanOrEqual(0);
+		expect(h).toBeLessThan(2048);
+	});
+
+	it("expectedFalsePositiveRate", async () => {
+		const filter = await Effect.runPromise(BloomFilter.create(2048, 3));
+		const rate = BloomFilter.expectedFalsePositiveRate(filter, 100);
+		expect(rate).toBeGreaterThanOrEqual(0);
+		expect(rate).toBeLessThanOrEqual(1);
+	});
+});
+
+describe("BloomFilter round-trip", () => {
+	it("fromHex(toHex(filter)) preserves data", async () => {
+		const filter = await Effect.runPromise(BloomFilter.create(2048, 3));
+		BloomFilter.add(filter, new Uint8Array([1, 2, 3]));
+
+		const hex = BloomFilter.toHex(filter);
+		const restored = await Effect.runPromise(BloomFilter.fromHex(hex, 2048, 3));
+
+		expect(BloomFilter.contains(restored, new Uint8Array([1, 2, 3]))).toBe(true);
+	});
+});

package/src/primitives/BloomFilter/add.ts

@@ -0,0 +1,23 @@
+/**
+ * @module add
+ * @description Add item to BloomFilter (pure, in-place mutation)
+ * @since 0.1.0
+ */
+import { BloomFilter, type BloomFilterType } from "@tevm/voltaire/BloomFilter";
+
+/**
+ * Add an item to a BloomFilter (mutates in place)
+ *
+ * @param filter - The bloom filter
+ * @param item - Item to add (Uint8Array)
+ * @example
+ * ```typescript
+ * import * as BloomFilter from 'voltaire-effect/primitives/BloomFilter'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const filter = await Effect.runPromise(BloomFilter.create(2048, 3))
+ * BloomFilter.add(filter, new Uint8Array([1, 2, 3]))
+ * ```
+ */
+export const add = (filter: BloomFilterType, item: Uint8Array): void =>
+	BloomFilter.add(filter, item);

package/src/primitives/BloomFilter/combine.ts

@@ -0,0 +1,21 @@
+/**
+ * @module combine
+ * @description Combine multiple BloomFilters into one (pure)
+ * @since 0.1.0
+ */
+import { BloomFilter, type BloomFilterType } from "@tevm/voltaire/BloomFilter";
+
+/**
+ * Combine multiple BloomFilters into a single filter
+ *
+ * @param filters - Filters to combine
+ * @returns Combined bloom filter
+ * @example
+ * ```typescript
+ * import * as BloomFilter from 'voltaire-effect/primitives/BloomFilter'
+ *
+ * const combined = BloomFilter.combine(filter1, filter2, filter3)
+ * ```
+ */
+export const combine = (...filters: BloomFilterType[]): BloomFilterType =>
+	BloomFilter.combine(...filters);

package/src/primitives/BloomFilter/contains.ts

@@ -0,0 +1,26 @@
+/**
+ * @module contains
+ * @description Check if BloomFilter may contain an item (pure predicate)
+ * @since 0.1.0
+ */
+import { BloomFilter, type BloomFilterType } from "@tevm/voltaire/BloomFilter";
+
+/**
+ * Check if a BloomFilter might contain an item
+ *
+ * False positives are possible, false negatives are not.
+ *
+ * @param filter - The bloom filter
+ * @param item - Item to check
+ * @returns true if item might be in filter, false if definitely not
+ * @example
+ * ```typescript
+ * import * as BloomFilter from 'voltaire-effect/primitives/BloomFilter'
+ *
+ * if (BloomFilter.contains(filter, item)) {
+ *   console.log('Item might be in filter')
+ * }
+ * ```
+ */
+export const contains = (filter: BloomFilterType, item: Uint8Array): boolean =>
+	BloomFilter.contains(filter, item);

package/src/primitives/BloomFilter/create.ts

@@ -0,0 +1,35 @@
+/**
+ * @module create
+ * @description Create BloomFilter with Effect error handling
+ * @since 0.1.0
+ */
+import { Effect } from "effect";
+import {
+	BloomFilter,
+	type BloomFilterType,
+	InvalidBloomFilterParameterError,
+} from "@tevm/voltaire/BloomFilter";
+
+/**
+ * Create a new BloomFilter with specified parameters
+ *
+ * @param m - Number of bits in the filter
+ * @param k - Number of hash functions
+ * @returns Effect yielding BloomFilterType or failing with InvalidBloomFilterParameterError
+ * @example
+ * ```typescript
+ * import * as BloomFilter from 'voltaire-effect/primitives/BloomFilter'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = BloomFilter.create(2048, 3)
+ * const filter = await Effect.runPromise(program)
+ * ```
+ */
+export const create = (
+	m: number,
+	k: number,
+): Effect.Effect<BloomFilterType, InvalidBloomFilterParameterError> =>
+	Effect.try({
+		try: () => BloomFilter.create(m, k),
+		catch: (e) => e as InvalidBloomFilterParameterError,
+	});

package/src/primitives/BloomFilter/density.ts

@@ -0,0 +1,22 @@
+/**
+ * @module density
+ * @description Calculate BloomFilter bit density (pure)
+ * @since 0.1.0
+ */
+import { BloomFilter, type BloomFilterType } from "@tevm/voltaire/BloomFilter";
+
+/**
+ * Calculate the density (fill ratio) of a BloomFilter
+ *
+ * @param filter - The bloom filter
+ * @returns Density as a number between 0 and 1
+ * @example
+ * ```typescript
+ * import * as BloomFilter from 'voltaire-effect/primitives/BloomFilter'
+ *
+ * const d = BloomFilter.density(filter)
+ * console.log(d) // e.g. 0.15
+ * ```
+ */
+export const density = (filter: BloomFilterType): number =>
+	BloomFilter.density(filter);

package/src/primitives/BloomFilter/expectedFalsePositiveRate.ts

@@ -0,0 +1,25 @@
+/**
+ * @module expectedFalsePositiveRate
+ * @description Calculate expected false positive rate (pure)
+ * @since 0.1.0
+ */
+import { BloomFilter, type BloomFilterType } from "@tevm/voltaire/BloomFilter";
+
+/**
+ * Calculate the expected false positive rate for a given item count
+ *
+ * @param filter - The bloom filter
+ * @param itemCount - Number of items in the filter
+ * @returns Expected false positive rate (0 to 1)
+ * @example
+ * ```typescript
+ * import * as BloomFilter from 'voltaire-effect/primitives/BloomFilter'
+ *
+ * const rate = BloomFilter.expectedFalsePositiveRate(filter, 100)
+ * console.log(rate) // e.g. 0.001
+ * ```
+ */
+export const expectedFalsePositiveRate = (
+	filter: BloomFilterType,
+	itemCount: number,
+): number => BloomFilter.expectedFalsePositiveRate(filter, itemCount);

package/src/primitives/BloomFilter/fromHex.ts

@@ -0,0 +1,37 @@
+/**
+ * @module fromHex
+ * @description Create BloomFilter from hex string with Effect error handling
+ * @since 0.1.0
+ */
+import { Effect } from "effect";
+import {
+	BloomFilter,
+	type BloomFilterType,
+	InvalidBloomFilterLengthError,
+} from "@tevm/voltaire/BloomFilter";
+
+/**
+ * Create BloomFilter from hex string
+ *
+ * @param hex - Hex string (with or without 0x prefix)
+ * @param m - Number of bits
+ * @param k - Number of hash functions
+ * @returns Effect yielding BloomFilterType or failing with InvalidBloomFilterLengthError
+ * @example
+ * ```typescript
+ * import * as BloomFilter from 'voltaire-effect/primitives/BloomFilter'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = BloomFilter.fromHex('0x00...', 2048, 3)
+ * const filter = await Effect.runPromise(program)
+ * ```
+ */
+export const fromHex = (
+	hex: string,
+	m: number,
+	k: number,
+): Effect.Effect<BloomFilterType, InvalidBloomFilterLengthError> =>
+	Effect.try({
+		try: () => BloomFilter.fromHex(hex, m, k),
+		catch: (e) => e as InvalidBloomFilterLengthError,
+	});