voltaire-effect 0.2.23

package/src/primitives/Epoch/BigInt.ts

@@ -0,0 +1,46 @@
+import { Epoch } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing a beacon chain epoch number.
+ * @since 0.0.1
+ */
+export type EpochType = ReturnType<typeof Epoch.from>;
+
+const EpochTypeSchema = S.declare<EpochType>(
+	(u): u is EpochType => typeof u === "bigint",
+	{ identifier: "Epoch" },
+);
+
+/**
+ * Effect Schema for validating beacon chain epoch numbers.
+ * Accepts bigint, number, or string and returns branded EpochType.
+ *
+ * @example
+ * ```typescript
+ * import * as Epoch from 'voltaire-effect/Epoch'
+ * import * as Schema from 'effect/Schema'
+ *
+ * const epoch = Schema.decodeSync(Epoch.EpochSchema)(123456n)
+ * ```
+ * @since 0.0.1
+ */
+export const EpochSchema: S.Schema<EpochType, bigint | number | string> =
+	S.transformOrFail(
+		S.Union(S.BigIntFromSelf, S.Number, S.String),
+		EpochTypeSchema,
+		{
+			strict: true,
+			decode: (value, _options, ast) => {
+				try {
+					return ParseResult.succeed(Epoch.from(value));
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, value, (e as Error).message),
+					);
+				}
+			},
+			encode: (epoch) => ParseResult.succeed(epoch as bigint),
+		},
+	).annotations({ identifier: "EpochSchema" });

package/src/primitives/Epoch/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Epoch module for working with beacon chain epochs.
+ * Provides Effect-based operations for creating and converting epochs.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Epoch from 'voltaire-effect/primitives/Epoch'
+ *
+ * function getEpochRewards(epoch: Epoch.EpochType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @module
+ * @since 0.0.1
+ */
+export { EpochSchema, type EpochType } from "./BigInt.js";

package/src/primitives/ErrorSignature/ErrorSignature.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Schema from "effect/Schema";
+import * as ErrorSignature from "./index.js";
+
+describe("ErrorSignature.String", () => {
+	describe("decode", () => {
+		it("parses from error definition", () => {
+			const sig = Schema.decodeSync(ErrorSignature.String)(
+				"InsufficientBalance(uint256,uint256)",
+			);
+			expect(sig).toBeInstanceOf(Uint8Array);
+			expect(sig.length).toBe(4);
+		});
+
+		it("parses from hex", () => {
+			const sig = Schema.decodeSync(ErrorSignature.String)("0x08c379a0");
+			expect(sig).toBeInstanceOf(Uint8Array);
+			expect(sig.length).toBe(4);
+		});
+	});
+
+	describe("encode", () => {
+		it("encodes to hex string", () => {
+			const sig = Schema.decodeSync(ErrorSignature.String)("0x08c379a0");
+			const hex = Schema.encodeSync(ErrorSignature.String)(sig);
+			expect(hex).toBe("0x08c379a0");
+		});
+	});
+});
+
+describe("pure functions", () => {
+	it("toHex converts to hex", () => {
+		const sig = Schema.decodeSync(ErrorSignature.String)("0x08c379a0");
+		const hex = ErrorSignature.toHex(sig);
+		expect(hex).toBe("0x08c379a0");
+	});
+
+	it("equals compares signatures", () => {
+		const a = Schema.decodeSync(ErrorSignature.String)("0x08c379a0");
+		const b = Schema.decodeSync(ErrorSignature.String)("0x08c379a0");
+		expect(ErrorSignature.equals(a, b)).toBe(true);
+	});
+});

package/src/primitives/ErrorSignature/String.ts

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Effect Schema for Solidity error selectors.
+ * @module ErrorSignature/String
+ * @since 0.1.0
+ *
+ * @description
+ * Error signatures are 4-byte selectors that identify Solidity custom errors.
+ * They are computed the same way as function selectors.
+ */
+
+import { ErrorSignature } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing a 4-byte Solidity error selector.
+ * @since 0.1.0
+ */
+export type ErrorSignatureType = ReturnType<typeof ErrorSignature.from>;
+
+/**
+ * Input types accepted for creating an ErrorSignature.
+ * @since 0.1.0
+ */
+export type ErrorSignatureLike = Parameters<typeof ErrorSignature.from>[0];
+
+const ErrorSignatureTypeSchema = S.declare<ErrorSignatureType>(
+	(u): u is ErrorSignatureType => u instanceof Uint8Array && u.length === 4,
+	{ identifier: "ErrorSignature" },
+);
+
+/**
+ * Schema for ErrorSignature from string.
+ *
+ * @description
+ * Transforms error signature strings to ErrorSignatureType.
+ * Accepts error definition strings or hex-encoded 4-byte selectors.
+ * Encodes to hex string.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as ErrorSignature from 'voltaire-effect/primitives/ErrorSignature'
+ * import * as S from 'effect/Schema'
+ *
+ * // From error definition
+ * const sig = S.decodeSync(ErrorSignature.String)('InsufficientBalance(uint256,uint256)')
+ *
+ * // From hex
+ * const fromHex = S.decodeSync(ErrorSignature.String)('0x08c379a0')
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const hex = S.encodeSync(ErrorSignature.String)(sig)
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const String: S.Schema<ErrorSignatureType, string> = S.transformOrFail(
+	S.String,
+	ErrorSignatureTypeSchema,
+	{
+		strict: true,
+		decode: (value, _options, ast) => {
+			try {
+				if (value.includes("(")) {
+					return ParseResult.succeed(ErrorSignature.fromSignature(value));
+				}
+				return ParseResult.succeed(ErrorSignature.from(value));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, value, (e as Error).message),
+				);
+			}
+		},
+		encode: (sig) => ParseResult.succeed(ErrorSignature.toHex(sig)),
+	},
+).annotations({ identifier: "ErrorSignature.String" });
+
+export { String as ErrorSignatureSchema };
+
+/**
+ * Converts an ErrorSignature to hex string.
+ *
+ * @param sig - The error signature
+ * @returns hex string
+ * @since 0.1.0
+ */
+export const toHex = (
+	sig: ErrorSignatureType,
+): ReturnType<typeof ErrorSignature.toHex> => ErrorSignature.toHex(sig);
+
+/**
+ * Compares two error signatures for equality.
+ *
+ * @param a - First signature
+ * @param b - Second signature
+ * @returns true if equal
+ * @since 0.1.0
+ */
+export const equals = (a: ErrorSignatureType, b: ErrorSignatureType): boolean =>
+	ErrorSignature.equals(a, b);

package/src/primitives/ErrorSignature/index.ts

@@ -0,0 +1,55 @@
+/**
+ * @module ErrorSignature
+ * @description Effect Schemas for Solidity error selectors.
+ *
+ * Error signatures are 4-byte selectors that identify Solidity custom errors.
+ * Standard error selectors:
+ * - Error(string): 0x08c379a0
+ * - Panic(uint256): 0x4e487b71
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as ErrorSignature from 'voltaire-effect/primitives/ErrorSignature'
+ *
+ * function decodeRevert(errSig: ErrorSignature.ErrorSignatureType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Schemas
+ *
+ * | Schema | Input | Output |
+ * |--------|-------|--------|
+ * | `ErrorSignature.String` | signature string | ErrorSignatureType |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import * as ErrorSignature from 'voltaire-effect/primitives/ErrorSignature'
+ * import * as S from 'effect/Schema'
+ *
+ * // From error definition
+ * const sig = S.decodeSync(ErrorSignature.String)('InsufficientBalance(uint256,uint256)')
+ *
+ * // To hex
+ * const hex = S.encodeSync(ErrorSignature.String)(sig)
+ * ```
+ *
+ * ## Pure Functions
+ *
+ * ```typescript
+ * ErrorSignature.toHex(sig)  // string
+ * ErrorSignature.equals(a, b)  // boolean
+ * ```
+ *
+ * @since 0.1.0
+ */
+export {
+	type ErrorSignatureLike,
+	ErrorSignatureSchema,
+	type ErrorSignatureType,
+	equals,
+	String,
+	toHex,
+} from "./String.js";

package/src/primitives/EventLog/EventLog.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Schema from "effect/Schema";
+import * as EventLog from "./index.js";
+
+describe("EventLog.Rpc", () => {
+	it("validates event log structure", () => {
+		const input = {
+			address: "0x1234567890123456789012345678901234567890",
+			topics: [`0x${"ab".repeat(32)}`, `0x${"cd".repeat(32)}`],
+			data: new Uint8Array(32).fill(0xff),
+			blockNumber: 12345678n,
+			logIndex: 0,
+		};
+		const result = Schema.decodeSync(EventLog.Rpc)(input);
+		expect(result.address).toBeInstanceOf(Uint8Array);
+		expect(result.topics.length).toBe(2);
+		expect(result.data).toBeInstanceOf(Uint8Array);
+	});
+
+	it("accepts 0 topics (LOG0)", () => {
+		const input = {
+			address: "0x1234567890123456789012345678901234567890",
+			topics: [],
+			data: new Uint8Array(0),
+		};
+		const result = Schema.decodeSync(EventLog.Rpc)(input);
+		expect(result.topics.length).toBe(0);
+	});
+
+	it("accepts 1 topic (LOG1)", () => {
+		const input = {
+			address: "0x1234567890123456789012345678901234567890",
+			topics: [`0x${"ab".repeat(32)}`],
+			data: new Uint8Array(0),
+		};
+		const result = Schema.decodeSync(EventLog.Rpc)(input);
+		expect(result.topics.length).toBe(1);
+	});
+
+	it("accepts 3 topics (LOG3)", () => {
+		const input = {
+			address: "0x1234567890123456789012345678901234567890",
+			topics: [
+				`0x${"ab".repeat(32)}`,
+				`0x${"cd".repeat(32)}`,
+				`0x${"ef".repeat(32)}`,
+			],
+			data: new Uint8Array(0),
+		};
+		const result = Schema.decodeSync(EventLog.Rpc)(input);
+		expect(result.topics.length).toBe(3);
+	});
+
+	it("accepts 4 topics (LOG4)", () => {
+		const input = {
+			address: "0x1234567890123456789012345678901234567890",
+			topics: [
+				`0x${"ab".repeat(32)}`,
+				`0x${"cd".repeat(32)}`,
+				`0x${"ef".repeat(32)}`,
+				`0x${"12".repeat(32)}`,
+			],
+			data: new Uint8Array(0),
+		};
+		const result = Schema.decodeSync(EventLog.Rpc)(input);
+		expect(result.topics.length).toBe(4);
+	});
+
+	it("rejects logs with more than 4 topics", () => {
+		const input = {
+			address: "0x1234567890123456789012345678901234567890",
+			topics: Array.from({ length: 5 }, () => `0x${"ab".repeat(32)}`),
+			data: new Uint8Array(0),
+		};
+		expect(() => Schema.decodeSync(EventLog.Rpc)(input)).toThrow();
+	});
+});

package/src/primitives/EventLog/Rpc.ts

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Effect Schema for EVM event logs.
+ * @module EventLog/EventLogSchema
+ * @since 0.0.1
+ *
+ * @description
+ * Event logs are the primary mechanism for smart contracts to emit events.
+ * Each log contains the emitting contract's address, indexed topics for filtering,
+ * and arbitrary data bytes.
+ */
+
+import type { EventLogType } from "@tevm/voltaire/EventLog";
+import * as EventLog from "@tevm/voltaire/EventLog";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+import { Hex as AddressSchema } from "../Address/Hex.js";
+import { Hex as HashSchema } from "../Hash/index.js";
+
+/**
+ * Internal schema for validating EventLog structure.
+ * @internal
+ */
+const EventLogTypeSchema = S.declare<EventLogType>(
+	(u): u is EventLogType => {
+		if (typeof u !== "object" || u === null) return false;
+		const log = u as Record<string, unknown>;
+		return (
+			"address" in log &&
+			log.address instanceof Uint8Array &&
+			(log.address as Uint8Array).length === 20 &&
+			"topics" in log &&
+			Array.isArray(log.topics) &&
+			"data" in log &&
+			log.data instanceof Uint8Array
+		);
+	},
+	{ identifier: "EventLog" },
+);
+
+/**
+ * Internal structured schema for EventLog input.
+ * @internal
+ */
+const EventLogSchemaInternal = S.Struct({
+	address: AddressSchema,
+	topics: S.Array(HashSchema).pipe(S.maxItems(4)),
+	data: S.Uint8ArrayFromSelf,
+	blockNumber: S.optional(S.BigIntFromSelf),
+	transactionHash: S.optional(HashSchema),
+	transactionIndex: S.optional(S.Number),
+	blockHash: S.optional(HashSchema),
+	logIndex: S.optional(S.Number),
+	removed: S.optional(S.Boolean),
+});
+
+/**
+ * Effect Schema for validating EVM event logs.
+ *
+ * @description
+ * Validates and transforms event log data into a typed EventLogType.
+ * Event logs contain:
+ * - address: The contract that emitted the event (20 bytes)
+ * - topics: Array of indexed parameters (up to 4, each 32 bytes)
+ * - data: Non-indexed parameters encoded as bytes
+ * - blockNumber: Block containing this log (optional)
+ * - transactionHash: Transaction that emitted this log (optional)
+ * - transactionIndex: Index of transaction in block (optional)
+ * - blockHash: Hash of block containing this log (optional)
+ * - logIndex: Index of log within transaction (optional)
+ * - removed: True if log was removed due to chain reorg (optional)
+ *
+ * @example
+ * ```typescript
+ * import * as EventLog from 'voltaire-effect/primitives/EventLog'
+ * import * as Schema from 'effect/Schema'
+ *
+ * const parse = Schema.decodeSync(EventLog.Schema)
+ *
+ * // Parse a Transfer event log
+ * const log = parse({
+ *   address: contractAddress,  // 20-byte address
+ *   topics: [
+ *     transferEventSignature,  // Topic 0: event signature
+ *     fromAddressTopic,        // Topic 1: from address (padded)
+ *     toAddressTopic           // Topic 2: to address (padded)
+ *   ],
+ *   data: encodedAmount,       // Non-indexed amount parameter
+ *   blockNumber: 12345678n,
+ *   logIndex: 0
+ * })
+ *
+ * // Access log properties
+ * console.log(log.address)  // Contract address
+ * console.log(log.topics)   // Indexed parameters
+ * console.log(log.data)     // Encoded data
+ * ```
+ *
+ * @throws {ParseError} When log structure is invalid
+ * @see {@link EventLogType} for the output type
+ * @since 0.0.1
+ */
+export const Rpc: S.Schema<
+	EventLogType,
+	S.Schema.Encoded<typeof EventLogSchemaInternal>
+> = S.transformOrFail(EventLogSchemaInternal, EventLogTypeSchema, {
+	strict: true,
+	decode: (d, _options, ast) => {
+		try {
+			return ParseResult.succeed(
+				EventLog.from({
+					address: d.address,
+					topics: d.topics,
+					data: d.data,
+					blockNumber: d.blockNumber,
+					transactionHash: d.transactionHash,
+					transactionIndex: d.transactionIndex,
+					blockHash: d.blockHash,
+					logIndex: d.logIndex,
+					removed: d.removed,
+				}),
+			);
+		} catch (e) {
+			return ParseResult.fail(
+				new ParseResult.Type(ast, d, (e as Error).message),
+			);
+		}
+	},
+	encode: (e) =>
+		ParseResult.succeed({
+			address: e.address,
+			topics: [...e.topics],
+			data: e.data,
+			blockNumber: e.blockNumber,
+			transactionHash: e.transactionHash,
+			transactionIndex: e.transactionIndex,
+			blockHash: e.blockHash,
+			logIndex: e.logIndex,
+			removed: e.removed,
+		}),
+}).annotations({ identifier: "EventLog.Rpc" });
+
+export { Rpc as EventLogSchema };
+export { Rpc as Schema };
+export { EventLogTypeSchema };
+
+/**
+ * Type representing an EVM event log entry.
+ *
+ * @description
+ * Contains all data for an emitted event:
+ * - address: Emitting contract address
+ * - topics: Indexed event parameters (for filtering)
+ * - data: Non-indexed parameters (ABI encoded)
+ * - Metadata: block, transaction, and log indices
+ *
+ * @see {@link EventLogSchema} for creating instances
+ * @since 0.0.1
+ */
+export type { EventLogType };

package/src/primitives/EventLog/extensions/index.ts

@@ -0,0 +1,17 @@
+export {
+	clone,
+	copy,
+	filterLogs,
+	getIndexed,
+	getIndexedTopics,
+	getSignature,
+	getTopic0,
+	isRemoved,
+	matchesAddress,
+	matchesFilter,
+	matchesTopics,
+	sortLogs,
+	wasRemoved,
+} from "@tevm/voltaire/EventLog";
+
+export { addressEquals, hashEquals } from "./utils.js";

package/src/primitives/EventLog/extensions/utils.ts

@@ -0,0 +1,18 @@
+import type { AddressType } from "@tevm/voltaire/Address";
+import type { HashType } from "@tevm/voltaire/Hash";
+
+export function hashEquals(a: HashType, b: HashType): boolean {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] !== b[i]) return false;
+	}
+	return true;
+}
+
+export function addressEquals(a: AddressType, b: AddressType): boolean {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] !== b[i]) return false;
+	}
+	return true;
+}

package/src/primitives/EventLog/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @module EventLog
+ * @description Event logs emitted by smart contracts.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as EventLog from 'voltaire-effect/primitives/EventLog'
+ *
+ * function parseLog(log: EventLog.EventLogType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export {
+	EventLogSchema,
+	type EventLogType,
+	EventLogTypeSchema,
+	Rpc,
+	Schema,
+} from "./Rpc.js";

package/src/primitives/EventSignature/EventSignature.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Schema from "effect/Schema";
+import * as EventSignature from "./index.js";
+
+describe("EventSignature.String", () => {
+	describe("decode", () => {
+		it("parses from event definition string", () => {
+			const sig = Schema.decodeSync(EventSignature.String)(
+				"Transfer(address,address,uint256)",
+			);
+			expect(sig).toBeInstanceOf(Uint8Array);
+			expect(sig.length).toBe(32);
+		});
+
+		it("parses from hex string", () => {
+			const sig = Schema.decodeSync(EventSignature.String)(
+				`0x${"ab".repeat(32)}`,
+			);
+			expect(sig).toBeInstanceOf(Uint8Array);
+			expect(sig.length).toBe(32);
+		});
+	});
+
+	describe("encode", () => {
+		it("encodes to hex string", () => {
+			const sig = Schema.decodeSync(EventSignature.String)(
+				"Transfer(address,address,uint256)",
+			);
+			const hex = Schema.encodeSync(EventSignature.String)(sig);
+			expect(hex.startsWith("0x")).toBe(true);
+			expect(hex.length).toBe(66);
+		});
+	});
+});
+
+describe("pure functions", () => {
+	it("toHex converts to hex", () => {
+		const sig = Schema.decodeSync(EventSignature.String)(
+			"Transfer(address,address,uint256)",
+		);
+		const hex = EventSignature.toHex(sig);
+		expect(hex.startsWith("0x")).toBe(true);
+	});
+
+	it("equals compares signatures", () => {
+		const a = Schema.decodeSync(EventSignature.String)(
+			"Transfer(address,address,uint256)",
+		);
+		const b = Schema.decodeSync(EventSignature.String)(
+			"Transfer(address,address,uint256)",
+		);
+		expect(EventSignature.equals(a, b)).toBe(true);
+	});
+});