voltaire-effect 0.2.23

package/src/block/block.test.ts

@@ -0,0 +1,579 @@
+/**
+ * @fileoverview Tests for block module Effect wrappers.
+ */
+
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+	TransportError,
+	TransportService,
+	type TransportShape,
+} from "../services/Transport/index.js";
+import { BlockError, BlockNotFoundError } from "./BlockError.js";
+import { fetchBlock } from "./fetchBlock.js";
+import { fetchBlockByHash } from "./fetchBlockByHash.js";
+import { fetchBlockReceipts } from "./fetchBlockReceipts.js";
+import { toLightBlock } from "./toLightBlock.js";
+
+const mockBlock = {
+	number: "0x112a880",
+	hash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+	parentHash:
+		"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+	timestamp: "0x6500e400",
+	transactions: ["0xabc", "0xdef"],
+};
+
+const mockReceipt = {
+	transactionHash: "0xabc",
+	status: "0x1",
+	gasUsed: "0x5208",
+};
+
+describe("block module", () => {
+	describe("BlockError", () => {
+		it("creates error with message", () => {
+			const error = new BlockError("test error");
+			expect(error.message).toBe("test error");
+			expect(error._tag).toBe("BlockError");
+		});
+
+		it("creates error with cause", () => {
+			const cause = new Error("underlying");
+			const error = new BlockError("test error", { cause });
+			expect(error.message).toContain("test error");
+			expect(error.cause).toBe(cause);
+		});
+	});
+
+	describe("BlockNotFoundError", () => {
+		it("creates error with block number", () => {
+			const error = new BlockNotFoundError(18000000n);
+			expect(error.message).toBe("Block 18000000 not found");
+			expect(error._tag).toBe("BlockNotFoundError");
+			expect(error.identifier).toBe(18000000n);
+		});
+
+		it("creates error with block hash", () => {
+			const error = new BlockNotFoundError("0x1234");
+			expect(error.message).toBe("Block 0x1234 not found");
+			expect(error.identifier).toBe("0x1234");
+		});
+	});
+
+	describe("fetchBlock", () => {
+		it("fetches block by number", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(
+					method: string,
+					params?: unknown[],
+				): Effect.Effect<T, never> => {
+					expect(method).toBe("eth_getBlockByNumber");
+					expect(params).toEqual(["0x112a880", false]);
+					return Effect.succeed(mockBlock as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlock(18000000n, "header").pipe(Effect.provide(TestLayer)),
+			);
+
+			expect(result).toEqual(mockBlock);
+		});
+
+		it("fetches block with transactions", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(
+					_method: string,
+					params?: unknown[],
+				): Effect.Effect<T, never> => {
+					expect(params).toEqual(["0x112a880", true]);
+					return Effect.succeed(mockBlock as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlock(18000000n, "transactions").pipe(Effect.provide(TestLayer)),
+			);
+
+			expect(result).toEqual(mockBlock);
+		});
+
+		it("fails when block not found", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(): Effect.Effect<T, never> => Effect.succeed(null as T),
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlock(99999999n, "header").pipe(
+					Effect.provide(TestLayer),
+					Effect.either,
+				),
+			);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				expect(result.left).toBeInstanceOf(BlockNotFoundError);
+			}
+		});
+
+		it("formats block number as hex correctly", async () => {
+			let capturedParams: unknown[] | undefined;
+			const mockTransport: TransportShape = {
+				request: <T>(
+					_method: string,
+					params?: unknown[],
+				): Effect.Effect<T, never> => {
+					capturedParams = params;
+					return Effect.succeed(mockBlock as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			await Effect.runPromise(
+				fetchBlock(0n, "header").pipe(Effect.provide(TestLayer)),
+			);
+			expect(capturedParams?.[0]).toBe("0x0");
+
+			await Effect.runPromise(
+				fetchBlock(255n, "header").pipe(Effect.provide(TestLayer)),
+			);
+			expect(capturedParams?.[0]).toBe("0xff");
+
+			await Effect.runPromise(
+				fetchBlock(1000000n, "header").pipe(Effect.provide(TestLayer)),
+			);
+			expect(capturedParams?.[0]).toBe("0xf4240");
+		});
+
+		it("wraps transport errors in BlockError", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(): Effect.Effect<T, TransportError> =>
+					Effect.fail(
+						new TransportError({
+							code: -32000,
+							message: "connection failed",
+						}),
+					),
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlock(18000000n, "header", { maxRetries: 0 }).pipe(
+					Effect.provide(TestLayer),
+					Effect.either,
+				),
+			);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				expect(result.left).toBeInstanceOf(BlockError);
+				expect((result.left as BlockError).cause).toBeInstanceOf(
+					TransportError,
+				);
+			}
+		});
+
+		it("fetches block with receipts", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, never> => {
+					if (method === "eth_getBlockByNumber") {
+						return Effect.succeed(mockBlock as T);
+					}
+					if (method === "eth_getBlockReceipts") {
+						return Effect.succeed([mockReceipt] as T);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlock(18000000n, "receipts").pipe(Effect.provide(TestLayer)),
+			);
+
+			expect(result).toEqual({ ...mockBlock, receipts: [mockReceipt] });
+		});
+	});
+
+	describe("fetchBlockByHash", () => {
+		it("fetches block by hash", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(
+					method: string,
+					params?: unknown[],
+				): Effect.Effect<T, never> => {
+					expect(method).toBe("eth_getBlockByHash");
+					expect(params).toEqual([mockBlock.hash, false]);
+					return Effect.succeed(mockBlock as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockByHash(mockBlock.hash, "header").pipe(
+					Effect.provide(TestLayer),
+				),
+			);
+
+			expect(result).toEqual(mockBlock);
+		});
+
+		it("fails when block not found", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(): Effect.Effect<T, never> => Effect.succeed(null as T),
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockByHash("0xnotfound", "header").pipe(
+					Effect.provide(TestLayer),
+					Effect.either,
+				),
+			);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				expect(result.left).toBeInstanceOf(BlockNotFoundError);
+			}
+		});
+	});
+
+	describe("fetchBlockReceipts", () => {
+		it("fetches receipts via eth_getBlockReceipts", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, never> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.succeed([mockReceipt] as T);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({ hash: mockBlock.hash }).pipe(
+					Effect.provide(TestLayer),
+				),
+			);
+
+			expect(result).toEqual([mockReceipt]);
+		});
+
+		it("falls back to individual receipt fetching", async () => {
+			let getBlockReceiptsCalled = false;
+
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, TransportError> => {
+					if (method === "eth_getBlockReceipts") {
+						getBlockReceiptsCalled = true;
+						return Effect.fail(
+							new TransportError({
+								code: -32601,
+								message: "method not found",
+							}),
+						);
+					}
+					if (method === "eth_getTransactionReceipt") {
+						return Effect.succeed(mockReceipt as T);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({
+					hash: mockBlock.hash,
+					transactions: ["0xabc"],
+				}).pipe(Effect.provide(TestLayer)),
+			);
+
+			expect(getBlockReceiptsCalled).toBe(true);
+			expect(result).toEqual([mockReceipt]);
+		});
+
+		it("returns empty array when eth_getBlockReceipts returns null", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, never> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.succeed(null as T);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({ hash: mockBlock.hash }).pipe(
+					Effect.provide(TestLayer),
+				),
+			);
+
+			expect(result).toEqual([]);
+		});
+
+		it("handles malformed data from eth_getBlockReceipts", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, never> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.succeed("not an array" as T);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({ hash: mockBlock.hash }).pipe(
+					Effect.provide(TestLayer),
+				),
+			);
+
+			expect(result).toBe("not an array");
+		});
+
+		it("returns empty array when transactions is missing", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, TransportError> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.fail(
+							new TransportError({
+								code: -32601,
+								message: "method not found",
+							}),
+						);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({ hash: mockBlock.hash }).pipe(
+					Effect.provide(TestLayer),
+				),
+			);
+
+			expect(result).toEqual([]);
+		});
+
+		it("returns empty array when transactions is empty", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, TransportError> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.fail(
+							new TransportError({
+								code: -32601,
+								message: "method not found",
+							}),
+						);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({ hash: mockBlock.hash, transactions: [] }).pipe(
+					Effect.provide(TestLayer),
+				),
+			);
+
+			expect(result).toEqual([]);
+		});
+
+		it("fails when eth_getTransactionReceipt errors during fallback", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, TransportError> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.fail(
+							new TransportError({
+								code: -32601,
+								message: "method not found",
+							}),
+						);
+					}
+					if (method === "eth_getTransactionReceipt") {
+						return Effect.fail(
+							new TransportError({
+								code: -32000,
+								message: "server error",
+							}),
+						);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts(
+					{ hash: mockBlock.hash, transactions: ["0xabc"] },
+					{ maxRetries: 0 },
+				).pipe(Effect.provide(TestLayer), Effect.either),
+			);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				expect(result.left).toBeInstanceOf(BlockError);
+			}
+		});
+
+		it("filters out null receipts from fallback path", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(
+					method: string,
+					params?: unknown[],
+				): Effect.Effect<T, TransportError> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.fail(
+							new TransportError({
+								code: -32601,
+								message: "method not found",
+							}),
+						);
+					}
+					if (method === "eth_getTransactionReceipt") {
+						const txHash = (params as string[])?.[0];
+						if (txHash === "0xabc") {
+							return Effect.succeed(mockReceipt as T);
+						}
+						return Effect.succeed(null as T);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({
+					hash: mockBlock.hash,
+					transactions: ["0xabc", "0xmissing"],
+				}).pipe(Effect.provide(TestLayer)),
+			);
+
+			expect(result).toEqual([mockReceipt]);
+		});
+
+		it("handles transactions as objects with hash property", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, TransportError> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.fail(
+							new TransportError({
+								code: -32601,
+								message: "method not found",
+							}),
+						);
+					}
+					if (method === "eth_getTransactionReceipt") {
+						return Effect.succeed(mockReceipt as T);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({
+					hash: mockBlock.hash,
+					transactions: [{ hash: "0xabc" }],
+				}).pipe(Effect.provide(TestLayer)),
+			);
+
+			expect(result).toEqual([mockReceipt]);
+		});
+
+		it("fails with BlockError on non-method-not-found errors", async () => {
+			const mockTransport: TransportShape = {
+				request: <T>(method: string): Effect.Effect<T, TransportError> => {
+					if (method === "eth_getBlockReceipts") {
+						return Effect.fail(
+							new TransportError({
+								code: -32000,
+								message: "internal error",
+							}),
+						);
+					}
+					return Effect.succeed([] as T);
+				},
+			};
+
+			const TestLayer = Layer.succeed(TransportService, mockTransport);
+
+			const result = await Effect.runPromise(
+				fetchBlockReceipts({ hash: mockBlock.hash }).pipe(
+					Effect.provide(TestLayer),
+					Effect.either,
+				),
+			);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				expect(result.left).toBeInstanceOf(BlockError);
+			}
+		});
+	});
+
+	describe("toLightBlock", () => {
+		it("extracts light block from full block", () => {
+			const result = toLightBlock(mockBlock);
+
+			expect(result.number).toBe(18000000n);
+			expect(result.hash).toBe(mockBlock.hash);
+			expect(result.parentHash).toBe(mockBlock.parentHash);
+			expect(result.timestamp).toBe(0x6500e400n);
+		});
+
+		it("handles header-wrapped block", () => {
+			const headerBlock = {
+				hash: mockBlock.hash,
+				header: {
+					number: "0x112a880",
+					parentHash: mockBlock.parentHash,
+					timestamp: "0x6500e400",
+				},
+			};
+
+			const result = toLightBlock(headerBlock);
+
+			expect(result.number).toBe(18000000n);
+			expect(result.parentHash).toBe(mockBlock.parentHash);
+		});
+	});
+
+	describe("exports", () => {
+		it("exports all expected items from index", async () => {
+			const exports = await import("./index.js");
+
+			expect(exports.BlockError).toBeDefined();
+			expect(exports.BlockNotFoundError).toBeDefined();
+			expect(exports.fetchBlock).toBeDefined();
+			expect(exports.fetchBlockByHash).toBeDefined();
+			expect(exports.fetchBlockReceipts).toBeDefined();
+			expect(exports.toLightBlock).toBeDefined();
+		});
+	});
+});

package/src/block/fetchBlock.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Effect-wrapped fetchBlock for one-off block fetching.
+ *
+ * @module fetchBlock
+ * @since 0.3.0
+ */
+
+import type {
+	BlockInclude,
+	RetryOptions,
+	StreamBlock,
+} from "@tevm/voltaire/block";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { TransportService } from "../services/Transport/TransportService.js";
+import { BlockError, BlockNotFoundError } from "./BlockError.js";
+import { createFetchBlockReceipts } from "./fetchBlockReceipts.js";
+
+/**
+ * Fetch a block by number with optional transaction inclusion.
+ *
+ * @since 0.3.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import * as Block from 'voltaire-effect/block'
+ * import { HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const block = yield* Block.fetchBlock(18000000n, 'header')
+ *   console.log('Block:', block.hash)
+ * }).pipe(Effect.provide(HttpTransport('https://eth.llamarpc.com')))
+ * ```
+ */
+export const fetchBlock = <TInclude extends BlockInclude = "header">(
+	blockNumber: bigint,
+	include: TInclude = "header" as TInclude,
+	retryOptions?: RetryOptions,
+): Effect.Effect<
+	StreamBlock<TInclude>,
+	BlockError | BlockNotFoundError,
+	TransportService
+> => {
+	const maxRetries = retryOptions?.maxRetries ?? 3;
+	const initialDelay = retryOptions?.initialDelay ?? 1000;
+	const maxDelay = retryOptions?.maxDelay ?? 30000;
+
+	const retrySchedule = Schedule.exponential(
+		Duration.millis(initialDelay),
+	).pipe(
+		Schedule.jittered,
+		Schedule.compose(Schedule.recurs(maxRetries)),
+		Schedule.whileOutput((duration) =>
+			Duration.lessThanOrEqualTo(duration, Duration.millis(maxDelay)),
+		),
+	);
+
+	const includeTransactions = include !== "header";
+
+	const fetchEffect = Effect.gen(function* () {
+		const transport = yield* TransportService;
+
+		const block = yield* transport
+			.request("eth_getBlockByNumber", [
+				`0x${blockNumber.toString(16)}`,
+				includeTransactions,
+			])
+			.pipe(
+				Effect.mapError(
+					(e) =>
+						new BlockError(`Failed to fetch block ${blockNumber}`, {
+							cause: e,
+						}),
+				),
+			);
+
+		if (!block) {
+			return yield* Effect.fail(new BlockNotFoundError(blockNumber));
+		}
+
+		if (include === "receipts") {
+			const receipts = yield* createFetchBlockReceipts(
+				block as Record<string, unknown>,
+				retryOptions,
+			);
+			return { ...block, receipts } as unknown as StreamBlock<TInclude>;
+		}
+
+		return block as unknown as StreamBlock<TInclude>;
+	});
+
+	return fetchEffect.pipe(
+		Effect.retry({
+			schedule: retrySchedule,
+			while: (error) => error instanceof BlockError,
+		}),
+	);
+};