voltaire-effect 0.2.23

package/src/primitives/Blob/BlobSchema.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Blob Schema definitions for EIP-4844.
+ *
+ * EIP-4844 introduces "blobs" - large data structures (128KB each) that can be
+ * attached to transactions for data availability. Blobs are used for Layer 2
+ * rollup data and are significantly cheaper than calldata.
+ *
+ * Each blob is exactly 131,072 bytes (128KB) and contains 4,096 field elements
+ * of 32 bytes each.
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-4844
+ * @module BlobSchema
+ * @since 0.0.1
+ */
+import { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/** @internal */
+type BrandedBlob = BlobNamespace.BrandedBlob;
+
+/** @internal */
+const BlobTypeSchema = S.declare<BrandedBlob>(
+	(u): u is BrandedBlob => {
+		if (!(u instanceof Uint8Array)) return false;
+		return BlobNamespace.isValid(u);
+	},
+	{ identifier: "Blob" },
+);
+
+/**
+ * Effect Schema for validating EIP-4844 blobs.
+ *
+ * Validates that input is exactly 131,072 bytes (128KB). This is the fixed
+ * size for all EIP-4844 blobs.
+ *
+ * @description
+ * A blob must be exactly SIZE bytes (131,072). The schema accepts:
+ * - Uint8Array of exactly 131,072 bytes
+ * - Array of numbers (0-255) of exactly 131,072 elements
+ *
+ * Use `Blob.fromData()` if you have smaller data that needs to be padded.
+ *
+ * @example
+ * ```typescript
+ * import { BlobSchema } from 'voltaire-effect/primitives/Blob'
+ * import * as Schema from 'effect/Schema'
+ *
+ * // Validate an existing blob
+ * const blob = Schema.decodeSync(BlobSchema)(blobBytes)
+ * ```
+ *
+ * @throws ParseError - When input is not exactly 131,072 bytes
+ * @see from - For creating blobs from exact-size data
+ * @see fromData - For creating blobs from arbitrary data (with padding)
+ * @since 0.0.1
+ */
+export const BlobSchema: S.Schema<BrandedBlob, Uint8Array | readonly number[]> =
+	S.transformOrFail(
+		S.Union(S.Uint8ArrayFromSelf, S.Array(S.Number)),
+		BlobTypeSchema,
+		{
+			strict: true,
+			decode: (bytes, _options, ast) => {
+				try {
+					const arr =
+						bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+					// Validate size - Blob.from() pads small data instead of throwing
+					if (!BlobNamespace.isValid(arr)) {
+						return ParseResult.fail(
+							new ParseResult.Type(
+								ast,
+								bytes,
+								`Invalid blob size: expected 131072 bytes, got ${arr.length}`,
+							),
+						);
+					}
+					return ParseResult.succeed(BlobNamespace.from(arr));
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, bytes, (e as Error).message),
+					);
+				}
+			},
+			encode: (b) => ParseResult.succeed(b as Uint8Array),
+		},
+	).annotations({ identifier: "BlobSchema" });

package/src/primitives/Blob/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Blob module for EIP-4844 blob data.
+ *
+ * EIP-4844 introduces "blobs" - large data structures (128KB each) that can be
+ * attached to transactions for data availability. Blobs are used for Layer 2
+ * rollup data and are significantly cheaper than calldata.
+ *
+ * This module provides Effect-based schemas and functions for creating,
+ * validating, and working with blob data.
+ *
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ * import * as Effect from 'effect/Effect'
+ *
+ * // Create a blob from arbitrary data (will be padded)
+ * const blob = await Effect.runPromise(Blob.fromData(data))
+ *
+ * // Extract the original data
+ * const retrieved = Blob.toData(blob)
+ *
+ * // Check if data is valid blob size
+ * if (Blob.isValid(data)) {
+ *   const exactBlob = await Effect.runPromise(Blob.from(data))
+ * }
+ * ```
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-4844
+ * @module Blob
+ * @since 0.0.1
+ */
+
+/**
+ * Blob constants from EIP-4844
+ * - SIZE: 131,072 bytes (128KB)
+ * - FIELD_ELEMENTS_PER_BLOB: 4,096
+ * - BYTES_PER_FIELD_ELEMENT: 32
+ * - MAX_PER_TRANSACTION: 6
+ */
+export {
+	BYTES_PER_FIELD_ELEMENT,
+	FIELD_ELEMENTS_PER_BLOB,
+	MAX_PER_TRANSACTION,
+	SIZE,
+} from "@tevm/voltaire/Blob";
+/** Schema for blob validation */
+export { BlobSchema, BlobSchema as Schema } from "./BlobSchema.js";
+/** Create blob from exact 131,072 bytes */
+/** Create blob from arbitrary data with padding */
+
+/** Check if data is valid blob size */
+export { isValid } from "./isValid.js";
+/** Extract original data from blob */
+export { toData } from "./toData.js";

package/src/primitives/Blob/isValid.ts

@@ -0,0 +1,22 @@
+import { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+
+/**
+ * Checks if a Uint8Array is a valid blob (exactly 131072 bytes).
+ * Pure function - never throws.
+ *
+ * @param blob - The bytes to validate
+ * @returns true if valid blob size, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ *
+ * if (Blob.isValid(data)) {
+ *   // data is 128KB
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const isValid = (blob: Uint8Array): boolean =>
+	BlobNamespace.isValid(blob);

package/src/primitives/Blob/toData.ts

@@ -0,0 +1,23 @@
+import { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
+
+type BrandedBlob = BlobNamespace.BrandedBlob;
+
+/**
+ * Extracts the original data from a blob.
+ * Decodes blob format back to raw data bytes.
+ * Pure function - never throws.
+ *
+ * @param blob - The blob to extract data from
+ * @returns The original data as Uint8Array
+ *
+ * @example
+ * ```typescript
+ * import * as Blob from 'voltaire-effect/primitives/Blob'
+ *
+ * const originalData = Blob.toData(blob)
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const toData = (blob: BrandedBlob): Uint8Array =>
+	BlobNamespace.toData(blob);

package/src/primitives/Block/Block.test.ts

@@ -0,0 +1,377 @@
+/**
+ * @fileoverview Tests for Block Effect Schemas.
+ * @module Block/Block.test
+ */
+
+import { Block, BlockBody, BlockHeader, Hex, Withdrawal } from "@tevm/voltaire";
+import * as S from "effect/Schema";
+import { describe, expect, it } from "vitest";
+import { BlockSchema } from "./BlockSchema.js";
+import { Rpc } from "./Rpc.js";
+
+type BlockType = Block.BlockType;
+
+/**
+ * Creates a valid block header for testing.
+ */
+function createValidHeader(): ReturnType<typeof BlockHeader.from> {
+	return BlockHeader.from({
+		parentHash: `0x${"ab".repeat(32)}`,
+		ommersHash: `0x${"cd".repeat(32)}`,
+		beneficiary: `0x${"ef".repeat(20)}`,
+		stateRoot: `0x${"11".repeat(32)}`,
+		transactionsRoot: `0x${"22".repeat(32)}`,
+		receiptsRoot: `0x${"33".repeat(32)}`,
+		logsBloom: new Uint8Array(256).fill(0),
+		difficulty: 0n,
+		number: 12345n,
+		gasLimit: 30000000n,
+		gasUsed: 21000n,
+		timestamp: 1700000000n,
+		extraData: new Uint8Array(0),
+		mixHash: `0x${"44".repeat(32)}`,
+		nonce: new Uint8Array(8).fill(0),
+		baseFeePerGas: 1000000000n,
+	});
+}
+
+/**
+ * Creates a valid block body for testing.
+ */
+function createValidBody(): ReturnType<typeof BlockBody.from> {
+	return BlockBody.from({
+		transactions: [],
+		ommers: [],
+	});
+}
+
+/**
+ * Creates a valid block for testing.
+ */
+function createValidBlock(): ReturnType<typeof Block.from> {
+	return Block.from({
+		header: createValidHeader(),
+		body: createValidBody(),
+		hash: `0x${"55".repeat(32)}`,
+		size: 1000n,
+	});
+}
+
+describe("BlockSchema", () => {
+	it("validates complete block", () => {
+		const block = createValidBlock();
+		const result = S.decodeSync(BlockSchema)(block);
+		expect(result.hash.length).toBe(32);
+		expect(result.header.number).toBe(12345n);
+	});
+
+	it("rejects block with invalid header (string)", () => {
+		const block = createValidBlock();
+		const invalid = { ...block, header: "garbage" } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with invalid header (null)", () => {
+		const block = createValidBlock();
+		const invalid = { ...block, header: null } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with invalid body (null)", () => {
+		const block = createValidBlock();
+		const invalid = { ...block, body: null } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with wrong hash length", () => {
+		const block = createValidBlock();
+		const invalid = {
+			...block,
+			hash: new Uint8Array(16),
+		} as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block missing required header field (parentHash)", () => {
+		const block = createValidBlock();
+		const { parentHash: _, ...headerWithoutParentHash } = block.header as {
+			parentHash: Uint8Array;
+			[key: string]: unknown;
+		};
+		const invalid = {
+			...block,
+			header: headerWithoutParentHash,
+		} as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with wrong parentHash length", () => {
+		const block = createValidBlock();
+		const invalidHeader = { ...block.header, parentHash: new Uint8Array(16) };
+		const invalid = { ...block, header: invalidHeader } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with wrong beneficiary length", () => {
+		const block = createValidBlock();
+		const invalidHeader = { ...block.header, beneficiary: new Uint8Array(32) };
+		const invalid = { ...block, header: invalidHeader } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with wrong logsBloom length", () => {
+		const block = createValidBlock();
+		const invalidHeader = { ...block.header, logsBloom: new Uint8Array(128) };
+		const invalid = { ...block, header: invalidHeader } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with wrong nonce length", () => {
+		const block = createValidBlock();
+		const invalidHeader = { ...block.header, nonce: new Uint8Array(4) };
+		const invalid = { ...block, header: invalidHeader } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with non-bigint number", () => {
+		const block = createValidBlock();
+		const invalidHeader = { ...block.header, number: 12345 };
+		const invalid = { ...block, header: invalidHeader } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with non-array transactions", () => {
+		const block = createValidBlock();
+		const invalidBody = { ...block.body, transactions: "not-an-array" };
+		const invalid = { ...block, body: invalidBody } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects block with non-array ommers", () => {
+		const block = createValidBlock();
+		const invalidBody = { ...block.body, ommers: {} };
+		const invalid = { ...block, body: invalidBody } as unknown as BlockType;
+		expect(() => S.decodeSync(BlockSchema)(invalid)).toThrow();
+	});
+
+	it("rejects non-object input", () => {
+		expect(() =>
+			S.decodeSync(BlockSchema)("not-an-object" as unknown as BlockType),
+		).toThrow();
+		expect(() =>
+			S.decodeSync(BlockSchema)(null as unknown as BlockType),
+		).toThrow();
+		expect(() =>
+			S.decodeSync(BlockSchema)(undefined as unknown as BlockType),
+		).toThrow();
+	});
+});
+
+describe("Block.Rpc", () => {
+	const createRpcBlock = () => ({
+		hash: `0x${"ab".repeat(32)}`,
+		size: "0x3e8",
+		parentHash: `0x${"cd".repeat(32)}`,
+		sha3Uncles: `0x${"de".repeat(32)}`,
+		miner: `0x${"ef".repeat(20)}`,
+		stateRoot: `0x${"11".repeat(32)}`,
+		transactionsRoot: `0x${"22".repeat(32)}`,
+		receiptsRoot: `0x${"33".repeat(32)}`,
+		logsBloom: `0x${"00".repeat(256)}`,
+		difficulty: "0x0",
+		number: "0x3039",
+		gasLimit: "0x1c9c380",
+		gasUsed: "0x5208",
+		timestamp: "0x65510d80",
+		extraData: "0x",
+		mixHash: `0x${"44".repeat(32)}`,
+		nonce: "0x0000000000000000",
+		baseFeePerGas: "0x3b9aca00",
+		transactions: [],
+	});
+
+	it("decodes RPC block", () => {
+		const rpcBlock = createRpcBlock();
+		const block = S.decodeSync(Rpc)(rpcBlock);
+		expect(block.header.number).toBe(12345n);
+		expect(block.hash.length).toBe(32);
+	});
+
+	it("decodes post-Shanghai block with withdrawals", () => {
+		const rpcBlock = {
+			...createRpcBlock(),
+			withdrawalsRoot: `0x${"55".repeat(32)}`,
+			withdrawals: [
+				{
+					index: "0x0",
+					validatorIndex: "0x1",
+					address: `0x${"aa".repeat(20)}`,
+					amount: "0x1000",
+				},
+			],
+		};
+		const block = S.decodeSync(Rpc)(rpcBlock);
+		expect(block.body.withdrawals?.length).toBe(1);
+	});
+
+	it("decodes post-Cancun block with blob fields", () => {
+		const rpcBlock = {
+			...createRpcBlock(),
+			withdrawalsRoot: `0x${"55".repeat(32)}`,
+			withdrawals: [],
+			blobGasUsed: "0x20000",
+			excessBlobGas: "0x0",
+			parentBeaconBlockRoot: `0x${"66".repeat(32)}`,
+		};
+		const block = S.decodeSync(Rpc)(rpcBlock);
+		expect(block.header.blobGasUsed).toBe(131072n);
+		expect(block.header.excessBlobGas).toBe(0n);
+	});
+
+	it("encodes block to RPC format", () => {
+		const block = createValidBlock();
+		const rpc = S.encodeSync(Rpc)(block);
+
+		expect(rpc.hash).toBe(Hex.fromBytes(block.hash));
+		expect(rpc.number).toBe(Hex.fromBigInt(block.header.number));
+		expect(rpc.parentHash).toBe(Hex.fromBytes(block.header.parentHash));
+		expect(rpc.miner).toBe(Hex.fromBytes(block.header.beneficiary));
+	});
+
+	it("round-trips block through RPC format", () => {
+		const rpcBlock = createRpcBlock();
+		const block = S.decodeSync(Rpc)(rpcBlock);
+		const encoded = S.encodeSync(Rpc)(block);
+
+		// Decode again and compare
+		const decoded = S.decodeSync(Rpc)(encoded);
+		expect(decoded.header.number).toBe(block.header.number);
+		expect(decoded.header.gasLimit).toBe(block.header.gasLimit);
+	});
+
+	it("encodes block with withdrawals", () => {
+		const header = BlockHeader.from({
+			parentHash: `0x${"ab".repeat(32)}`,
+			ommersHash: `0x${"cd".repeat(32)}`,
+			beneficiary: `0x${"ef".repeat(20)}`,
+			stateRoot: `0x${"11".repeat(32)}`,
+			transactionsRoot: `0x${"22".repeat(32)}`,
+			receiptsRoot: `0x${"33".repeat(32)}`,
+			logsBloom: new Uint8Array(256).fill(0),
+			difficulty: 0n,
+			number: 17000000n,
+			gasLimit: 30000000n,
+			gasUsed: 21000n,
+			timestamp: 1700000000n,
+			extraData: new Uint8Array(0),
+			mixHash: `0x${"44".repeat(32)}`,
+			nonce: new Uint8Array(8).fill(0),
+			baseFeePerGas: 1000000000n,
+			withdrawalsRoot: `0x${"55".repeat(32)}`,
+		});
+
+		const body = BlockBody.from({
+			transactions: [],
+			ommers: [],
+			withdrawals: [
+				Withdrawal.from({
+					index: 0n,
+					validatorIndex: 1n,
+					address: `0x${"aa".repeat(20)}`,
+					amount: 1000000000n,
+				}),
+			],
+		});
+
+		const block = Block.from({
+			header,
+			body,
+			hash: `0x${"66".repeat(32)}`,
+			size: 2000n,
+		});
+
+		const rpc = S.encodeSync(Rpc)(block);
+		expect(rpc.withdrawals).toBeDefined();
+		expect(rpc.withdrawals?.length).toBe(1);
+		expect(rpc.withdrawals?.[0].index).toBe("0x0");
+		expect(rpc.withdrawals?.[0].validatorIndex).toBe("0x1");
+	});
+
+	it("rejects invalid RPC block", () => {
+		const invalid = {
+			hash: "not-valid-hex",
+			size: "0x100",
+			parentHash: `0x${"cd".repeat(32)}`,
+		};
+		expect(() => S.decodeSync(Rpc)(invalid as never)).toThrow();
+	});
+
+	it("decodes pre-London block (no baseFeePerGas)", () => {
+		const preLondonRpc = {
+			hash: `0x${"ab".repeat(32)}`,
+			size: "0x3e8",
+			parentHash: `0x${"cd".repeat(32)}`,
+			sha3Uncles: `0x${"de".repeat(32)}`,
+			miner: `0x${"ef".repeat(20)}`,
+			stateRoot: `0x${"11".repeat(32)}`,
+			transactionsRoot: `0x${"22".repeat(32)}`,
+			receiptsRoot: `0x${"33".repeat(32)}`,
+			logsBloom: `0x${"00".repeat(256)}`,
+			difficulty: "0x2d79883d2000",
+			number: "0xc5d488",
+			gasLimit: "0x1c9c380",
+			gasUsed: "0xbebc20",
+			timestamp: "0x60c7a2bb",
+			extraData: "0x6e616e6f706f6f6c2e6f7267",
+			mixHash: `0x${"44".repeat(32)}`,
+			nonce: "0x0db95e41b7970000",
+			transactions: [],
+		};
+		const block = S.decodeSync(Rpc)(preLondonRpc);
+		expect(block.header.baseFeePerGas).toBeUndefined();
+		expect(block.header.difficulty).toBe(50000000000000n);
+	});
+
+	it("encodes block with optional EIP-4844 fields", () => {
+		const header = BlockHeader.from({
+			parentHash: `0x${"ab".repeat(32)}`,
+			ommersHash: `0x${"cd".repeat(32)}`,
+			beneficiary: `0x${"ef".repeat(20)}`,
+			stateRoot: `0x${"11".repeat(32)}`,
+			transactionsRoot: `0x${"22".repeat(32)}`,
+			receiptsRoot: `0x${"33".repeat(32)}`,
+			logsBloom: new Uint8Array(256).fill(0),
+			difficulty: 0n,
+			number: 19000000n,
+			gasLimit: 30000000n,
+			gasUsed: 21000n,
+			timestamp: 1710000000n,
+			extraData: new Uint8Array(0),
+			mixHash: `0x${"44".repeat(32)}`,
+			nonce: new Uint8Array(8).fill(0),
+			baseFeePerGas: 1000000000n,
+			withdrawalsRoot: `0x${"55".repeat(32)}`,
+			blobGasUsed: 131072n,
+			excessBlobGas: 0n,
+			parentBeaconBlockRoot: `0x${"77".repeat(32)}`,
+		});
+
+		const body = BlockBody.from({
+			transactions: [],
+			ommers: [],
+			withdrawals: [],
+		});
+
+		const block = Block.from({
+			header,
+			body,
+			hash: `0x${"88".repeat(32)}`,
+			size: 500n,
+		});
+
+		const rpc = S.encodeSync(Rpc)(block);
+		expect(rpc.blobGasUsed).toBe("0x20000");
+		expect(rpc.excessBlobGas).toBe("0x0");
+		expect(rpc.parentBeaconBlockRoot).toBe(`0x${"77".repeat(32)}`);
+	});
+});