voltaire-effect 0.2.23

package/src/contract/EventStream.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Live implementation of EventStreamService.
+ *
+ * @module EventStream
+ * @since 0.3.0
+ *
+ * @description
+ * Provides the live implementation layer for EventStreamService.
+ * Creates an EIP-1193 provider from TransportService and wraps core EventStream.
+ */
+
+import type { BrandedAbi } from "@tevm/voltaire";
+import {
+	type BackfillOptions,
+	EventStream as CoreEventStream,
+	type EventStreamResult,
+	type WatchOptions,
+} from "@tevm/voltaire/contract";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Runtime from "effect/Runtime";
+
+type EventType = BrandedAbi.Event.EventType;
+
+import * as Stream from "effect/Stream";
+import { TransportService } from "../services/Transport/TransportService.js";
+import { EventStreamError } from "./EventStreamError.js";
+import {
+	type BackfillStreamOptions,
+	EventStreamService,
+	type EventStreamShape,
+	type WatchStreamOptions,
+} from "./EventStreamService.js";
+
+/**
+ * Wraps an AsyncGenerator as an Effect Stream.
+ */
+const fromAsyncGenerator = <T>(
+	makeGenerator: () => AsyncGenerator<T>,
+): Stream.Stream<T, EventStreamError> =>
+	Stream.fromAsyncIterable(
+		{ [Symbol.asyncIterator]: makeGenerator },
+		(error) =>
+			new EventStreamError(
+				error instanceof Error ? error.message : "EventStream error",
+				{ cause: error instanceof Error ? error : undefined },
+			),
+	);
+
+/**
+ * Build an EventStream directly from TransportService without a service layer.
+ */
+export const makeEventStream = (): Effect.Effect<
+	EventStreamShape,
+	never,
+	TransportService
+> =>
+	Effect.gen(function* () {
+		const transport = yield* TransportService;
+		const runtime = yield* Effect.runtime();
+		const runPromise = Runtime.runPromise(runtime);
+
+		const provider = {
+			request: async ({
+				method,
+				params,
+			}: {
+				method: string;
+				params?: unknown[];
+			}) => runPromise(transport.request(method, params)),
+			on: () => {},
+			removeListener: () => {},
+		};
+
+		return {
+			backfill: <TEvent extends EventType>(
+				options: BackfillStreamOptions<TEvent>,
+			): Stream.Stream<EventStreamResult<TEvent>, EventStreamError> => {
+				const { address, event, filter, ...backfillOptions } = options;
+				const coreStream = CoreEventStream({
+					provider: provider as any,
+					address,
+					event,
+					filter,
+				});
+				return fromAsyncGenerator(() =>
+					coreStream.backfill(backfillOptions as BackfillOptions),
+				);
+			},
+
+			watch: <TEvent extends EventType>(
+				options: WatchStreamOptions<TEvent>,
+			): Stream.Stream<EventStreamResult<TEvent>, EventStreamError> => {
+				const { address, event, filter, ...watchOptions } = options;
+				const coreStream = CoreEventStream({
+					provider: provider as any,
+					address,
+					event,
+					filter,
+				});
+				return fromAsyncGenerator(() =>
+					coreStream.watch(watchOptions as WatchOptions),
+				);
+			},
+		};
+	});
+
+/**
+ * Live implementation of EventStreamService.
+ *
+ * @since 0.3.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Stream } from 'effect';
+ * import { makeEventStream, HttpTransport } from 'voltaire-effect';
+ *
+ * const program = Effect.gen(function* () {
+ *   const eventStream = yield* makeEventStream();
+ *   yield* Stream.runForEach(
+ *     eventStream.backfill({
+ *       address: '0x...',
+ *       event: transferEvent,
+ *       fromBlock: 18000000n,
+ *       toBlock: 18001000n
+ *     }),
+ *     ({ log }) => Effect.log(`Event: ${log.eventName}`)
+ *   );
+ * }).pipe(
+ *   Effect.provide(HttpTransport('https://...'))
+ * );
+ * ```
+ */
+export const EventStream: Layer.Layer<
+	EventStreamService,
+	never,
+	TransportService
+> = Layer.effect(EventStreamService, makeEventStream());

package/src/contract/EventStreamError.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "@effect/vitest";
+import { EventStreamError } from "./EventStreamError.js";
+
+describe("EventStreamError", () => {
+	describe("constructor", () => {
+		it("creates error with message", () => {
+			const error = new EventStreamError("Event stream failed");
+			expect(error.message).toBe("Event stream failed");
+			expect(error.name).toBe("EventStreamError");
+			expect(error._tag).toBe("EventStreamError");
+		});
+
+		it("creates error with cause", () => {
+			const originalError = new Error("Connection lost");
+			const error = new EventStreamError("Event stream disconnected", {
+				cause: originalError,
+			});
+			expect(error.cause).toBe(originalError);
+		});
+
+		it("creates error with context", () => {
+			const context = {
+				contractAddress: "0x1234",
+				eventName: "Transfer",
+				fromBlock: 12345,
+			};
+			const error = new EventStreamError("Failed to subscribe", { context });
+			expect(
+				(error as unknown as { context: Record<string, unknown> }).context,
+			).toEqual(context);
+		});
+
+		it("creates error with both cause and context", () => {
+			const originalError = new Error("RPC error");
+			const context = { blockRange: "100-200" };
+			const error = new EventStreamError("Event fetch failed", {
+				cause: originalError,
+				context,
+			});
+			expect(error.cause).toBe(originalError);
+			expect(
+				(error as unknown as { context: Record<string, unknown> }).context,
+			).toEqual(context);
+		});
+	});
+
+	describe("instanceof checks", () => {
+		it("EventStreamError is instanceof Error", () => {
+			const error = new EventStreamError("Error");
+			expect(error instanceof Error).toBe(true);
+		});
+
+		it("EventStreamError is instanceof EventStreamError", () => {
+			const error = new EventStreamError("Error");
+			expect(error instanceof EventStreamError).toBe(true);
+		});
+	});
+
+	describe("stack trace", () => {
+		it("has stack trace", () => {
+			const error = new EventStreamError("Error");
+			expect(error.stack).toBeDefined();
+			expect(error.stack).toContain("EventStreamError");
+		});
+	});
+
+	describe("edge cases", () => {
+		it("handles empty message", () => {
+			const error = new EventStreamError("");
+			expect(error.message).toBe("");
+		});
+
+		it("handles long error messages", () => {
+			const longMessage = "A".repeat(1000);
+			const error = new EventStreamError(longMessage);
+			expect(error.message).toBe(longMessage);
+			expect(error.message.length).toBe(1000);
+		});
+
+		it("handles special characters in message", () => {
+			const specialMessage = "Error: <script>alert('xss')</script>";
+			const error = new EventStreamError(specialMessage);
+			expect(error.message).toBe(specialMessage);
+		});
+
+		it("handles newlines in message", () => {
+			const multilineMessage = "Line 1\nLine 2\nLine 3";
+			const error = new EventStreamError(multilineMessage);
+			expect(error.message).toBe(multilineMessage);
+		});
+	});
+});

package/src/contract/EventStreamError.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview EventStream error type for voltaire-effect.
+ *
+ * @module EventStreamError
+ * @since 0.3.0
+ */
+
+import * as Data from "effect/Data";
+
+/**
+ * Error thrown when an EventStream operation fails.
+ *
+ * @since 0.3.0
+ */
+export class EventStreamError extends Data.TaggedError("EventStreamError")<{
+	readonly message: string;
+	readonly cause?: unknown;
+	readonly context?: Record<string, unknown>;
+}> {
+	constructor(
+		message: string,
+		options?: {
+			cause?: unknown;
+			context?: Record<string, unknown>;
+		},
+	) {
+		super({
+			message,
+			cause: options?.cause,
+			context: options?.context,
+		});
+	}
+}

package/src/contract/EventStreamService.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview EventStream service definition for Effect-native event streaming.
+ *
+ * @module EventStreamService
+ * @since 0.3.0
+ *
+ * @description
+ * Provides Effect Stream integration for watching contract events.
+ * Wraps voltaire core's EventStream for fiber-safe, composable event streaming.
+ *
+ * @see {@link EventStream} - The live implementation layer
+ * @see {@link TransportService} - Required dependency
+ */
+
+import type { BrandedAbi } from "@tevm/voltaire";
+import type {
+	BackfillOptions,
+	EventStreamConstructorOptions,
+	EventStreamResult,
+	WatchOptions,
+} from "@tevm/voltaire/contract";
+import * as Context from "effect/Context";
+import type * as Stream from "effect/Stream";
+
+type EventType = BrandedAbi.Event.EventType;
+
+import type { EventStreamError } from "./EventStreamError.js";
+
+/**
+ * Options for backfill with address and event included
+ */
+export interface BackfillStreamOptions<TEvent extends EventType>
+	extends Omit<EventStreamConstructorOptions<TEvent>, "provider">,
+		BackfillOptions {}
+
+/**
+ * Options for watch with address and event included
+ */
+export interface WatchStreamOptions<TEvent extends EventType>
+	extends Omit<EventStreamConstructorOptions<TEvent>, "provider">,
+		WatchOptions {}
+
+/**
+ * Shape of the EventStream service.
+ *
+ * @since 0.3.0
+ */
+export type EventStreamShape = {
+	/**
+	 * Backfill historical events within a block range.
+	 *
+	 * @example
+	 * ```typescript
+	 * const program = Effect.gen(function* () {
+	 *   const stream = yield* makeEventStream();
+	 *   yield* Stream.runForEach(
+	 *     stream.backfill({
+	 *       address: '0x...',
+	 *       event: transferEvent,
+	 *       fromBlock: 18000000n,
+	 *       toBlock: 18001000n
+	 *     }),
+	 *     ({ log }) => Effect.log(`Got event: ${log.eventName}`)
+	 *   );
+	 * });
+	 * ```
+	 */
+	readonly backfill: <TEvent extends EventType>(
+		options: BackfillStreamOptions<TEvent>,
+	) => Stream.Stream<EventStreamResult<TEvent>, EventStreamError>;
+
+	/**
+	 * Watch for new events by polling.
+	 *
+	 * @example
+	 * ```typescript
+	 * const program = Effect.gen(function* () {
+	 *   const stream = yield* makeEventStream();
+	 *   yield* Stream.runForEach(
+	 *     stream.watch({
+	 *       address: '0x...',
+	 *       event: approvalEvent
+	 *     }),
+	 *     ({ log }) => Effect.log(`New event: ${log.eventName}`)
+	 *   );
+	 * });
+	 * ```
+	 */
+	readonly watch: <TEvent extends EventType>(
+		options: WatchStreamOptions<TEvent>,
+	) => Stream.Stream<EventStreamResult<TEvent>, EventStreamError>;
+};
+
+/**
+ * EventStream service for Effect-native contract event streaming.
+ *
+ * @since 0.3.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Stream } from 'effect';
+ * import { makeEventStream, HttpTransport } from 'voltaire-effect';
+ *
+ * const program = Effect.gen(function* () {
+ *   const eventStream = yield* makeEventStream();
+ *
+ *   yield* Stream.runForEach(
+ *     eventStream.backfill({
+ *       address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *       event: transferEvent,
+ *       fromBlock: 18000000n,
+ *       toBlock: 18001000n
+ *     }),
+ *     ({ log }) => Effect.log(`Transfer: ${log.args.value}`)
+ *   );
+ * }).pipe(
+ *    *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * );
+ * ```
+ */
+export class EventStreamService extends Context.Tag("EventStreamService")<
+	EventStreamService,
+	EventStreamShape
+>() {}

package/src/contract/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Contract event streaming module exports for voltaire-effect.
+ *
+ * @module contract
+ * @since 0.3.0
+ *
+ * @description
+ * Effect wrapper for voltaire core's EventStream for contract event streaming.
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Stream } from 'effect';
+ * import { makeEventStream, HttpTransport } from 'voltaire-effect';
+ *
+ * const program = Effect.gen(function* () {
+ *   const stream = yield* makeEventStream();
+ *   yield* Stream.runForEach(
+ *     stream.backfill({
+ *       address: '0x...',
+ *       event: transferEvent,
+ *       fromBlock: 18000000n,
+ *       toBlock: 18001000n
+ *     }),
+ *     ({ log }) => Effect.log(`Event: ${log.eventName}`)
+ *   );
+ * }).pipe(
+ *   Effect.provide(HttpTransport('https://...'))
+ * );
+ * ```
+ */
+
+export { EventStream, makeEventStream } from "./EventStream.js";
+export { EventStreamError } from "./EventStreamError.js";
+export {
+	type BackfillStreamOptions,
+	EventStreamService,
+	type EventStreamShape,
+	type WatchStreamOptions,
+} from "./EventStreamService.js";

package/src/crypto/AesGcm/AesGcm.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as AesGcm from "./index.js";
+
+describe("AesGcm", () => {
+	describe("generateKey", () => {
+		it.effect("generates 256-bit key by default", () =>
+			Effect.gen(function* () {
+				const result = yield* AesGcm.generateKey();
+				expect(result.length).toBe(32);
+			}),
+		);
+
+		it.effect("generates 128-bit key", () =>
+			Effect.gen(function* () {
+				const result = yield* AesGcm.generateKey(128);
+				expect(result.length).toBe(16);
+			}),
+		);
+	});
+
+	describe("generateNonce", () => {
+		it.effect("generates 12-byte nonce", () =>
+			Effect.gen(function* () {
+				const result = yield* AesGcm.generateNonce();
+				expect(result.length).toBe(12);
+			}),
+		);
+	});
+
+	describe("encrypt/decrypt roundtrip", () => {
+		it.effect("encrypts and decrypts correctly", () =>
+			Effect.gen(function* () {
+				const key = yield* AesGcm.generateKey();
+				const nonce = yield* AesGcm.generateNonce();
+				const plaintext = new Uint8Array([1, 2, 3, 4, 5]);
+				const ciphertext = yield* AesGcm.encrypt(key, plaintext, nonce);
+				const decrypted = yield* AesGcm.decrypt(key, ciphertext, nonce);
+				expect(Array.from(decrypted)).toEqual(Array.from(plaintext));
+			}),
+		);
+
+		it.effect("encrypts with AAD", () =>
+			Effect.gen(function* () {
+				const key = yield* AesGcm.generateKey();
+				const nonce = yield* AesGcm.generateNonce();
+				const plaintext = new Uint8Array([1, 2, 3]);
+				const aad = new Uint8Array([10, 20, 30]);
+				const ciphertext = yield* AesGcm.encrypt(key, plaintext, nonce, aad);
+				const decrypted = yield* AesGcm.decrypt(key, ciphertext, nonce, aad);
+				expect(Array.from(decrypted)).toEqual(Array.from(plaintext));
+			}),
+		);
+	});
+
+	describe("Service layer", () => {
+		it.effect("works with live layer", () =>
+			Effect.gen(function* () {
+				const service = yield* AesGcm.AesGcmService;
+				const key = yield* service.generateKey();
+				expect(key.length).toBe(32);
+			}).pipe(Effect.provide(AesGcm.AesGcmLive)),
+		);
+	});
+
+	describe("input validation", () => {
+		it.effect("rejects invalid key size on encrypt", () =>
+			Effect.gen(function* () {
+				const nonce = yield* AesGcm.generateNonce();
+				const plaintext = new Uint8Array([1, 2, 3]);
+				const invalidKey = new Uint8Array(10);
+				const exit = yield* Effect.exit(
+					AesGcm.encrypt(invalidKey, plaintext, nonce),
+				);
+				expect(Exit.isFailure(exit)).toBe(true);
+				if (Exit.isFailure(exit)) {
+					const error = exit.cause;
+					expect(error._tag).toBe("Fail");
+					if (error._tag === "Fail") {
+						expect(error.error).toBeInstanceOf(AesGcm.InvalidKeyError);
+						expect((error.error as AesGcm.InvalidKeyError).keyLength).toBe(10);
+					}
+				}
+			}),
+		);
+
+		it.effect("rejects invalid nonce size on encrypt", () =>
+			Effect.gen(function* () {
+				const key = yield* AesGcm.generateKey();
+				const plaintext = new Uint8Array([1, 2, 3]);
+				const invalidNonce = new Uint8Array(8);
+				const exit = yield* Effect.exit(
+					AesGcm.encrypt(key, plaintext, invalidNonce),
+				);
+				expect(Exit.isFailure(exit)).toBe(true);
+				if (Exit.isFailure(exit)) {
+					const error = exit.cause;
+					expect(error._tag).toBe("Fail");
+					if (error._tag === "Fail") {
+						expect(error.error).toBeInstanceOf(AesGcm.InvalidNonceError);
+						expect((error.error as AesGcm.InvalidNonceError).nonceLength).toBe(
+							8,
+						);
+					}
+				}
+			}),
+		);
+
+		it.effect("rejects invalid key size on decrypt", () =>
+			Effect.gen(function* () {
+				const nonce = yield* AesGcm.generateNonce();
+				const ciphertext = new Uint8Array(32);
+				const invalidKey = new Uint8Array(15);
+				const exit = yield* Effect.exit(
+					AesGcm.decrypt(invalidKey, ciphertext, nonce),
+				);
+				expect(Exit.isFailure(exit)).toBe(true);
+				if (Exit.isFailure(exit)) {
+					const error = exit.cause;
+					expect(error._tag).toBe("Fail");
+					if (error._tag === "Fail") {
+						expect(error.error).toBeInstanceOf(AesGcm.InvalidKeyError);
+					}
+				}
+			}),
+		);
+
+		it.effect("rejects invalid nonce size on decrypt", () =>
+			Effect.gen(function* () {
+				const key = yield* AesGcm.generateKey();
+				const ciphertext = new Uint8Array(32);
+				const invalidNonce = new Uint8Array(16);
+				const exit = yield* Effect.exit(
+					AesGcm.decrypt(key, ciphertext, invalidNonce),
+				);
+				expect(Exit.isFailure(exit)).toBe(true);
+				if (Exit.isFailure(exit)) {
+					const error = exit.cause;
+					expect(error._tag).toBe("Fail");
+					if (error._tag === "Fail") {
+						expect(error.error).toBeInstanceOf(AesGcm.InvalidNonceError);
+					}
+				}
+			}),
+		);
+
+		it.effect("accepts valid key sizes (16, 32 bytes)", () =>
+			Effect.gen(function* () {
+				const nonce = yield* AesGcm.generateNonce();
+				const plaintext = new Uint8Array([1, 2, 3]);
+
+				// AES-128 (16 bytes)
+				const key16 = new Uint8Array(16).fill(1);
+				const result16 = yield* AesGcm.encrypt(key16, plaintext, nonce);
+				expect(result16.length).toBeGreaterThan(plaintext.length);
+
+				// AES-256 (32 bytes)
+				const nonce2 = yield* AesGcm.generateNonce();
+				const key32 = new Uint8Array(32).fill(1);
+				const result32 = yield* AesGcm.encrypt(key32, plaintext, nonce2);
+				expect(result32.length).toBeGreaterThan(plaintext.length);
+			}),
+		);
+
+		it.effect("rejects AES-192 (24-byte key)", () =>
+			Effect.gen(function* () {
+				const nonce = yield* AesGcm.generateNonce();
+				const plaintext = new Uint8Array([1, 2, 3]);
+				const key24 = new Uint8Array(24).fill(1);
+				const exit = yield* Effect.exit(
+					AesGcm.encrypt(key24, plaintext, nonce),
+				);
+				expect(Exit.isFailure(exit)).toBe(true);
+				if (Exit.isFailure(exit)) {
+					const error = exit.cause;
+					expect(error._tag).toBe("Fail");
+					if (error._tag === "Fail") {
+						expect(error.error).toBeInstanceOf(AesGcm.InvalidKeyError);
+					}
+				}
+			}),
+		);
+	});
+});

package/src/crypto/AesGcm/AesGcmService.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview AesGcmService Effect service definition for AES-GCM encryption.
+ * @module AesGcm/AesGcmService
+ * @since 0.0.1
+ */
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+
+/**
+ * Shape interface for AES-GCM encryption service operations.
+ *
+ * @description
+ * Defines the contract for AES-GCM implementations. All methods return Effect
+ * types for composable, type-safe async/error handling.
+ *
+ * @since 0.0.1
+ */
+export interface AesGcmServiceShape {
+	/**
+	 * Encrypts plaintext using AES-GCM.
+	 * @param key - 16-byte (128-bit) or 32-byte (256-bit) key
+	 * @param plaintext - Data to encrypt
+	 * @param nonce - 12-byte (96-bit) nonce/IV (must be unique per key)
+	 * @param aad - Optional additional authenticated data
+	 * @returns Effect containing ciphertext with appended 16-byte auth tag
+	 */
+	readonly encrypt: (
+		key: Uint8Array,
+		plaintext: Uint8Array,
+		nonce: Uint8Array,
+		aad?: Uint8Array,
+	) => Effect.Effect<Uint8Array, Error>;
+	/**
+	 * Decrypts ciphertext using AES-GCM.
+	 * @param key - Same key used for encryption
+	 * @param ciphertext - Encrypted data with appended auth tag
+	 * @param nonce - Same nonce used for encryption
+	 * @param aad - Same AAD used for encryption (if any)
+	 * @returns Effect containing decrypted plaintext
+	 * @throws Error if authentication fails
+	 */
+	readonly decrypt: (
+		key: Uint8Array,
+		ciphertext: Uint8Array,
+		nonce: Uint8Array,
+		aad?: Uint8Array,
+	) => Effect.Effect<Uint8Array, Error>;
+	/**
+	 * Generates a cryptographically random AES key.
+	 * @param bits - Key size: 128 or 256 (default: 256)
+	 * @returns Effect containing the random key bytes
+	 */
+	readonly generateKey: (bits?: 128 | 256) => Effect.Effect<Uint8Array, Error>;
+	/**
+	 * Generates a cryptographically random 96-bit nonce.
+	 * @returns Effect containing 12-byte nonce
+	 */
+	readonly generateNonce: () => Effect.Effect<Uint8Array, Error>;
+}
+
+/**
+ * AES-GCM authenticated encryption service for Effect-based applications.
+ *
+ * @description
+ * Provides AES-GCM encryption with 128 or 256-bit keys. Includes authentication
+ * via Galois/Counter Mode to ensure data integrity.
+ *
+ * @example
+ * ```typescript
+ * import { AesGcmService, AesGcmLive } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const aes = yield* AesGcmService
+ *   const key = yield* aes.generateKey(256)
+ *   const nonce = yield* aes.generateNonce()
+ *   return yield* aes.encrypt(key, plaintext, nonce)
+ * }).pipe(Effect.provide(AesGcmLive))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export class AesGcmService extends Context.Tag("AesGcmService")<
+	AesGcmService,
+	AesGcmServiceShape
+>() {}