voltaire-effect 0.2.23

package/src/primitives/Nonce/Number.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Effect Schema for Nonce from number encoding.
+ * Provides bidirectional transformation between numbers and NonceType.
+ *
+ * @module Number
+ * @since 0.1.0
+ */
+
+import { Uint } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Branded type representing an Ethereum account nonce.
+ *
+ * @description
+ * A nonce is a counter that tracks the number of transactions sent from an account.
+ * Nonces are used to prevent replay attacks and order transactions.
+ */
+export type NonceType = bigint & { readonly __tag: "Nonce" };
+
+/**
+ * Internal schema declaration for NonceType.
+ * Validates that a value is a non-negative bigint.
+ *
+ * @internal
+ */
+const NonceTypeSchema = S.declare<NonceType>(
+	(u): u is NonceType => typeof u === "bigint" && u >= 0n,
+	{ identifier: "Nonce" },
+);
+
+/**
+ * Schema for Nonce encoded as a number.
+ *
+ * @description
+ * Transforms numbers to NonceType and vice versa.
+ * Validates that the input is a non-negative integer.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as Nonce from 'voltaire-effect/primitives/Nonce'
+ * import * as S from 'effect/Schema'
+ *
+ * const nonce = S.decodeSync(Nonce.Number)(42)
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const num = S.encodeSync(Nonce.Number)(nonce)
+ * // 42
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Number: S.Schema<NonceType, number> = S.transformOrFail(
+	S.Number,
+	NonceTypeSchema,
+	{
+		strict: true,
+		decode: (n, _options, ast) => {
+			try {
+				return ParseResult.succeed(Uint.from(n) as unknown as NonceType);
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, n, (e as Error).message),
+				);
+			}
+		},
+		encode: (nonce, _options, _ast) => {
+			return ParseResult.succeed(globalThis.Number(nonce));
+		},
+	},
+).annotations({ identifier: "Nonce.Number" });

package/src/primitives/Nonce/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @module Nonce
+ * @description Effect Schemas for Ethereum account nonces.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Nonce from 'voltaire-effect/primitives/Nonce'
+ *
+ * function getNextNonce(current: Nonce.NonceType): Nonce.NonceType {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Schemas
+ *
+ * | Schema | Input | Output | Description |
+ * |--------|-------|--------|-------------|
+ * | `Nonce.Number` | number | NonceType | Non-negative integer nonce |
+ * | `Nonce.BigInt` | bigint | NonceType | Non-negative bigint nonce |
+ * | `Nonce.Hex` | string | NonceType | Hex-encoded nonce |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import * as Nonce from 'voltaire-effect/primitives/Nonce'
+ * import * as S from 'effect/Schema'
+ *
+ * // Decode from number
+ * const nonce = S.decodeSync(Nonce.Number)(42)
+ *
+ * // Decode from hex
+ * const fromHex = S.decodeSync(Nonce.Hex)('0x2a')
+ *
+ * // Encode back
+ * const num = S.encodeSync(Nonce.Number)(nonce)
+ * ```
+ *
+ * ## About Nonces
+ *
+ * A nonce is a counter that tracks the number of transactions sent from an account.
+ * Each new transaction from an account must have a nonce one greater than the previous,
+ * starting from 0.
+ *
+ * Nonces serve several purposes:
+ * - **Ordering**: Ensure transactions execute in the correct sequence
+ * - **Replay protection**: Prevent duplicate transaction execution
+ * - **Replacement**: Allow replacing pending transactions with same nonce
+ *
+ * @since 0.1.0
+ */
+
+export { BigInt } from "./BigInt.js";
+export { Hex } from "./Hex.js";
+// Schemas
+export { type NonceType, Number } from "./Number.js";

package/src/primitives/OpStep/OpStepSchema.ts

@@ -0,0 +1,118 @@
+import { OpStep } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing a single EVM execution step with full debug information.
+ * @since 0.0.1
+ */
+type OpStepType = ReturnType<typeof OpStep.from>;
+
+const OpStepTypeSchema = S.declare<OpStepType>(
+	(u): u is OpStepType => {
+		if (typeof u !== "object" || u === null) return false;
+		const obj = u as Record<string, unknown>;
+		return (
+			typeof obj.pc === "number" &&
+			typeof obj.op === "number" &&
+			typeof obj.gas === "bigint" &&
+			typeof obj.gasCost === "bigint" &&
+			typeof obj.depth === "number"
+		);
+	},
+	{ identifier: "OpStep" },
+);
+
+/**
+ * Input parameters for creating an OpStep.
+ * @since 0.0.1
+ */
+type OpStepInput = {
+	/** Program counter position */
+	pc: number;
+	/** Opcode being executed */
+	op: number;
+	/** Remaining gas */
+	gas: bigint;
+	/** Cost of this operation */
+	gasCost: bigint;
+	/** Call stack depth */
+	depth: number;
+	/** Optional EVM stack state */
+	stack?: readonly bigint[];
+	/** Optional memory state */
+	memory?: Uint8Array;
+	/** Optional storage state */
+	storage?: Record<string, bigint>;
+	/** Optional error message if step failed */
+	error?: string;
+};
+
+/**
+ * Effect Schema for validating and transforming EVM operation steps.
+ *
+ * Transforms OpStep input data into a validated OpStepType.
+ * Used for tracing and debugging EVM execution.
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { OpStepSchema } from 'voltaire-effect/primitives/OpStep'
+ *
+ * const step = S.decodeSync(OpStepSchema)({
+ *   pc: 0,
+ *   op: 0x60, // PUSH1
+ *   gas: 100000n,
+ *   gasCost: 3n,
+ *   depth: 1,
+ *   stack: [1n, 2n, 3n]
+ * })
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const OpStepSchema: S.Schema<OpStepType, OpStepInput> =
+	S.transformOrFail(
+		S.Struct({
+			pc: S.Number,
+			op: S.Number,
+			gas: S.BigIntFromSelf,
+			gasCost: S.BigIntFromSelf,
+			depth: S.Number,
+			stack: S.optional(S.Array(S.BigIntFromSelf)),
+			memory: S.optional(S.Uint8ArrayFromSelf),
+			storage: S.optional(S.Record({ key: S.String, value: S.BigIntFromSelf })),
+			error: S.optional(S.String),
+		}),
+		OpStepTypeSchema,
+		{
+			strict: true,
+			decode: (value, _options, ast) => {
+				try {
+					return ParseResult.succeed(
+						OpStep.from(value as Parameters<typeof OpStep.from>[0]),
+					);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, value, (e as Error).message),
+					);
+				}
+			},
+			encode: (opStep) =>
+				ParseResult.succeed({
+					pc: opStep.pc,
+					op: opStep.op as number,
+					gas: opStep.gas as bigint,
+					gasCost: opStep.gasCost as bigint,
+					depth: opStep.depth,
+					...(opStep.stack !== undefined && {
+						stack: opStep.stack as readonly bigint[],
+					}),
+					...(opStep.memory !== undefined && { memory: opStep.memory }),
+					...(opStep.storage !== undefined && {
+						storage: opStep.storage as Record<string, bigint>,
+					}),
+					...(opStep.error !== undefined && { error: opStep.error }),
+				}),
+		},
+	).annotations({ identifier: "OpStepSchema" });

package/src/primitives/OpStep/index.ts

@@ -0,0 +1,29 @@
+/**
+ * OpStep module for Effect-based EVM execution step handling.
+ *
+ * Provides Effect-wrapped operations for working with EVM execution steps,
+ * including program counter, opcode, gas, stack, memory, and storage state.
+ *
+ * @example
+ * ```typescript
+ * import * as OpStep from 'voltaire-effect/primitives/OpStep'
+ * import * as Effect from 'effect/Effect'
+ *
+ * // Create an execution step
+ * const step = OpStep.from({
+ *   pc: 10,
+ *   op: 0x01, // ADD
+ *   gas: 50000n,
+ *   gasCost: 3n,
+ *   depth: 1,
+ *   stack: [1n, 2n]
+ * })
+ *
+ * Effect.runSync(step)
+ * ```
+ *
+ * @module
+ * @since 0.0.1
+ */
+
+export { OpStepSchema } from "./OpStepSchema.js";

package/src/primitives/Opcode/OpcodeSchema.ts

@@ -0,0 +1,55 @@
+import { Opcode } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing an EVM opcode value (0x00-0xFF).
+ * @since 0.0.1
+ */
+type OpcodeType = ReturnType<typeof Opcode>;
+
+const OpcodeTypeSchema = S.declare<OpcodeType>(
+	(u): u is OpcodeType => typeof u === "number" && u >= 0x00 && u <= 0xff,
+	{ identifier: "Opcode" },
+);
+
+/**
+ * Effect Schema for validating and transforming EVM opcodes.
+ *
+ * Transforms a number (0x00-0xFF) into a validated Opcode type.
+ * Used for schema-based validation of EVM instruction opcodes.
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { OpcodeSchema } from 'voltaire-effect/primitives/Opcode'
+ *
+ * // Decode a number to Opcode
+ * const opcode = S.decodeSync(OpcodeSchema)(0x01) // ADD opcode
+ *
+ * // Validate opcode range
+ * const invalid = S.decodeSync(OpcodeSchema)(0x100) // throws - out of range
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const OpcodeSchema: S.Schema<OpcodeType, number> = S.transformOrFail(
+	S.Number,
+	OpcodeTypeSchema,
+	{
+		strict: true,
+		decode: (n, _options, ast) => {
+			try {
+				if (n < 0x00 || n > 0xff) {
+					throw new Error(`Opcode must be between 0x00 and 0xFF, got ${n}`);
+				}
+				return ParseResult.succeed(Opcode(n));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, n, (e as Error).message),
+				);
+			}
+		},
+		encode: (opcode) => ParseResult.succeed(opcode as number),
+	},
+).annotations({ identifier: "OpcodeSchema" });

package/src/primitives/Opcode/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Opcode module for Effect-based EVM opcode handling.
+ *
+ * Provides Effect-wrapped operations for working with EVM opcodes (0x00-0xFF).
+ *
+ * @example
+ * ```typescript
+ * import * as Opcode from 'voltaire-effect/primitives/Opcode'
+ * import * as Effect from 'effect/Effect'
+ *
+ * // Create opcode from number
+ * const add = Opcode.from(0x01) // ADD
+ * const stop = Opcode.from(0x00) // STOP
+ *
+ * // Use with schema validation
+ * import * as S from 'effect/Schema'
+ * const validated = S.decodeSync(Opcode.OpcodeSchema)(0x60) // PUSH1
+ * ```
+ *
+ * @module
+ * @since 0.0.1
+ */
+
+export { OpcodeSchema } from "./OpcodeSchema.js";

package/src/primitives/PackedUserOperation/PackedUserOperationSchema.ts

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview PackedUserOperation Schema definitions for ERC-4337 v0.7.
+ *
+ * ERC-4337 v0.7 introduced a packed format for UserOperations that reduces
+ * calldata size by combining multiple gas fields into fixed-size byte arrays.
+ * This format is more gas-efficient for on-chain processing.
+ *
+ * The packed format combines:
+ * - `accountGasLimits`: verificationGasLimit (16 bytes) + callGasLimit (16 bytes)
+ * - `gasFees`: maxPriorityFeePerGas (16 bytes) + maxFeePerGas (16 bytes)
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-4337
+ * @module PackedUserOperationSchema
+ * @since 0.0.1
+ */
+
+import type { AddressType } from "@tevm/voltaire/Address";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+import { Hex as AddressSchema } from "../Address/Hex.js";
+
+/**
+ * Type representing a packed ERC-4337 user operation (v0.7 format).
+ *
+ * PackedUserOperation is a gas-optimized encoding of UserOperation
+ * where multiple gas fields are packed into fixed-size byte arrays.
+ * This reduces calldata size and on-chain storage costs.
+ *
+ * @example
+ * ```typescript
+ * const packed: PackedUserOperationType = {
+ *   sender: addressBytes,
+ *   nonce: 0n,
+ *   initCode: new Uint8Array(0),
+ *   callData: callDataBytes,
+ *   accountGasLimits: new Uint8Array(32), // [verificationGasLimit, callGasLimit]
+ *   preVerificationGas: 21000n,
+ *   gasFees: new Uint8Array(32),          // [maxPriorityFee, maxFee]
+ *   paymasterAndData: new Uint8Array(0),
+ *   signature: signatureBytes
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export interface PackedUserOperationType {
+	/** Smart contract account address (20 bytes) */
+	readonly sender: AddressType;
+	/** Account nonce to prevent replay attacks */
+	readonly nonce: bigint;
+	/** Factory address + init data for account deployment */
+	readonly initCode: Uint8Array;
+	/** Encoded call data to execute on the account */
+	readonly callData: Uint8Array;
+	/** Packed verificationGasLimit (16 bytes) + callGasLimit (16 bytes) */
+	readonly accountGasLimits: Uint8Array;
+	/** Gas to compensate bundler for pre-verification overhead */
+	readonly preVerificationGas: bigint;
+	/** Packed maxPriorityFeePerGas (16 bytes) + maxFeePerGas (16 bytes) */
+	readonly gasFees: Uint8Array;
+	/** Paymaster address + verification/post-op data */
+	readonly paymasterAndData: Uint8Array;
+	/** Signature over the UserOperation hash */
+	readonly signature: Uint8Array;
+}
+
+const HexStringToBytes: S.Schema<Uint8Array, string> = S.transformOrFail(
+	S.String,
+	S.Uint8ArrayFromSelf,
+	{
+		strict: true,
+		decode: (s, _options, ast) => {
+			try {
+				const hex = s.startsWith("0x") ? s.slice(2) : s;
+				if (hex.length === 0) return ParseResult.succeed(new Uint8Array(0));
+				if (hex.length % 2 !== 0) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, s, "Invalid hex string length"),
+					);
+				}
+				const bytes = new Uint8Array(hex.length / 2);
+				for (let i = 0; i < bytes.length; i++) {
+					bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+				}
+				return ParseResult.succeed(bytes);
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, s, (e as Error).message),
+				);
+			}
+		},
+		encode: (bytes) => {
+			const hex = Array.from(bytes)
+				.map((b) => b.toString(16).padStart(2, "0"))
+				.join("");
+			return ParseResult.succeed(`0x${hex}`);
+		},
+	},
+);
+
+const BigIntFromString: S.Schema<bigint, string> = S.transformOrFail(
+	S.String,
+	S.BigIntFromSelf,
+	{
+		strict: true,
+		decode: (s, _options, ast) => {
+			try {
+				return ParseResult.succeed(BigInt(s));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, s, (e as Error).message),
+				);
+			}
+		},
+		encode: (n) => ParseResult.succeed(n.toString()),
+	},
+);
+
+const PackedUserOperationSchemaInternal = S.Struct({
+	sender: AddressSchema,
+	nonce: BigIntFromString,
+	initCode: HexStringToBytes,
+	callData: HexStringToBytes,
+	accountGasLimits: HexStringToBytes,
+	preVerificationGas: BigIntFromString,
+	gasFees: HexStringToBytes,
+	paymasterAndData: HexStringToBytes,
+	signature: HexStringToBytes,
+});
+
+const PackedUserOperationTypeSchema = S.declare<PackedUserOperationType>(
+	(u): u is PackedUserOperationType =>
+		typeof u === "object" &&
+		u !== null &&
+		"sender" in u &&
+		"nonce" in u &&
+		"accountGasLimits" in u,
+	{ identifier: "PackedUserOperation" },
+);
+
+/**
+ * Input type for PackedUserOperation schema with hex string encoding.
+ * @since 0.0.1
+ */
+export type PackedUserOperationInput = {
+	/** Account address as hex string */
+	sender: string;
+	/** Account nonce as decimal string */
+	nonce: string;
+	/** Init code for account deployment as hex string */
+	initCode: string;
+	/** Encoded call data as hex string */
+	callData: string;
+	/** Packed verificationGasLimit and callGasLimit as hex string */
+	accountGasLimits: string;
+	/** Pre-verification gas as decimal string */
+	preVerificationGas: string;
+	/** Packed maxPriorityFeePerGas and maxFeePerGas as hex string */
+	gasFees: string;
+	/** Paymaster address and data as hex string */
+	paymasterAndData: string;
+	/** User operation signature as hex string */
+	signature: string;
+};
+
+/**
+ * Effect Schema for validating and transforming PackedUserOperation.
+ *
+ * Transforms hex-encoded JSON input into PackedUserOperationType with
+ * proper Address, bigint, and Uint8Array conversions.
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { PackedUserOperationSchema } from 'voltaire-effect/primitives/PackedUserOperation'
+ *
+ * const packed = S.decodeSync(PackedUserOperationSchema)({
+ *   sender: '0x1234567890123456789012345678901234567890',
+ *   nonce: '0',
+ *   initCode: '0x',
+ *   callData: '0x',
+ *   accountGasLimits: '0x' + '00'.repeat(32),
+ *   preVerificationGas: '21000',
+ *   gasFees: '0x' + '00'.repeat(32),
+ *   paymasterAndData: '0x',
+ *   signature: '0x'
+ * })
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const PackedUserOperationSchema: S.Schema<
+	PackedUserOperationType,
+	PackedUserOperationInput
+> = S.transform(
+	PackedUserOperationSchemaInternal,
+	PackedUserOperationTypeSchema,
+	{
+		strict: true,
+		decode: (d) => d as PackedUserOperationType,
+		encode: (e) => e,
+	},
+);

package/src/primitives/PackedUserOperation/hash.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Address } from "@tevm/voltaire/Address";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { hash } from "./hash.js";
+import type { PackedUserOperationType } from "./PackedUserOperationSchema.js";
+
+const mockPackedUserOp: PackedUserOperationType = {
+	sender: new Uint8Array(20) as PackedUserOperationType["sender"],
+	nonce: 0n,
+	initCode: new Uint8Array(0),
+	callData: new Uint8Array(0),
+	accountGasLimits: new Uint8Array(32),
+	preVerificationGas: 21000n,
+	gasFees: new Uint8Array(32),
+	paymasterAndData: new Uint8Array(0),
+	signature: new Uint8Array(0),
+};
+
+const entryPointAddress = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+
+describe("PackedUserOperation.hash", () => {
+	it("produces deterministic 32-byte hash", async () => {
+		const result = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 1n),
+		);
+		expect(result).toBeInstanceOf(Uint8Array);
+		expect(result.length).toBe(32);
+
+		const result2 = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 1n),
+		);
+		expect(result).toEqual(result2);
+	});
+
+	it("chainId as number vs bigint yields same result", async () => {
+		const resultBigInt = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 1n),
+		);
+		const resultNumber = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 1),
+		);
+		expect(resultBigInt).toEqual(resultNumber);
+	});
+
+	it("entryPoint as string address works", async () => {
+		const result = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 1n),
+		);
+		expect(result.length).toBe(32);
+	});
+
+	it("entryPoint as Uint8Array works", async () => {
+		const entryPointBytes = Address(entryPointAddress);
+		const resultString = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 1n),
+		);
+		const resultBytes = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointBytes, 1n),
+		);
+		expect(resultString).toEqual(resultBytes);
+	});
+
+	it("invalid entryPoint triggers ValidationError", async () => {
+		const exit = await Effect.runPromiseExit(
+			hash(mockPackedUserOp, "invalid-address", 1n),
+		);
+		expect(Exit.isFailure(exit)).toBe(true);
+	});
+
+	it("empty initCode/callData produces valid hash", async () => {
+		const opWithEmptyData: PackedUserOperationType = {
+			...mockPackedUserOp,
+			initCode: new Uint8Array(0),
+			callData: new Uint8Array(0),
+		};
+		const result = await Effect.runPromise(
+			hash(opWithEmptyData, entryPointAddress, 1n),
+		);
+		expect(result.length).toBe(32);
+	});
+
+	it("very large nonce values work correctly", async () => {
+		const opWithLargeNonce: PackedUserOperationType = {
+			...mockPackedUserOp,
+			nonce: 2n ** 192n - 1n,
+		};
+		const result = await Effect.runPromise(
+			hash(opWithLargeNonce, entryPointAddress, 1n),
+		);
+		expect(result.length).toBe(32);
+	});
+
+	it("different chainIds produce different hashes", async () => {
+		const hash1 = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 1n),
+		);
+		const hash137 = await Effect.runPromise(
+			hash(mockPackedUserOp, entryPointAddress, 137n),
+		);
+		expect(hash1).not.toEqual(hash137);
+	});
+});