voltaire-effect 0.2.23

package/src/primitives/PackedUserOperation/hash.ts

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview PackedUserOperation hash computation for ERC-4337 v0.7.
+ *
+ * This module computes the hash of a PackedUserOperation as defined in ERC-4337.
+ * The hash is used for signature verification and uniquely identifies the
+ * PackedUserOperation on a specific chain and EntryPoint.
+ *
+ * The hash is computed as:
+ * `keccak256(keccak256(packedUserOpFields), entryPoint, chainId)`
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-4337
+ * @module PackedUserOperation/hash
+ * @since 0.0.1
+ */
+
+import { Keccak256 } from "@tevm/voltaire";
+import type { AddressType } from "@tevm/voltaire/Address";
+import { Address } from "@tevm/voltaire/Address";
+import { ValidationError } from "@tevm/voltaire/errors";
+import * as Effect from "effect/Effect";
+import type { PackedUserOperationType } from "./PackedUserOperationSchema.js";
+
+const pad32 = (bytes: Uint8Array): Uint8Array => {
+	const result = new Uint8Array(32);
+	result.set(bytes, 32 - bytes.length);
+	return result;
+};
+
+const uint256ToBytes = (n: bigint): Uint8Array => {
+	const hex = n.toString(16).padStart(64, "0");
+	const bytes = new Uint8Array(32);
+	for (let i = 0; i < 32; i++) {
+		bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+	}
+	return bytes;
+};
+
+/**
+ * Computes the ERC-4337 user operation hash for signing.
+ *
+ * The hash is computed as `keccak256(userOpHash, entryPoint, chainId)` where
+ * userOpHash is the keccak256 of the packed user operation fields. This is
+ * the value that should be signed by the account owner.
+ *
+ * @description
+ * The hash computation for packed operations uses the pre-packed gas fields
+ * (accountGasLimits and gasFees) directly, rather than the individual gas
+ * values used in the unpacked format.
+ *
+ * This provides replay protection across chains and EntryPoint versions.
+ *
+ * @param packedUserOp - The packed user operation to hash
+ * @param entryPoint - EntryPoint contract address (accepts string, Uint8Array, or AddressType)
+ * @param chainId - Chain ID for replay protection (accepts bigint or number)
+ * @returns Effect that succeeds with 32-byte hash or fails with ValidationError
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import * as PackedUserOperation from 'voltaire-effect/primitives/PackedUserOperation'
+ *
+ * const program = Effect.gen(function* () {
+ *   const packed = yield* PackedUserOperation.from({ ... })
+ *   const userOpHash = yield* PackedUserOperation.hash(
+ *     packed,
+ *     '0x0000000071727De22E5E9d8BAf0edAc6f37da032', // v0.7 EntryPoint
+ *     1n // mainnet
+ *   )
+ *   return userOpHash // 32-byte Uint8Array to sign
+ * })
+ * ```
+ *
+ * @throws ValidationError - When entryPoint address is invalid
+ * @see from - For creating PackedUserOperations
+ * @see unpack - For converting to standard UserOperation format
+ * @since 0.0.1
+ */
+export const hash = (
+	packedUserOp: PackedUserOperationType,
+	entryPoint: number | bigint | string | Uint8Array | AddressType,
+	chainId: bigint | number,
+): Effect.Effect<Uint8Array, ValidationError> =>
+	Effect.try({
+		try: () => {
+			const entryPointAddr = Address(
+				entryPoint as string | number | bigint | Uint8Array,
+			);
+			const chainIdBigInt =
+				typeof chainId === "bigint" ? chainId : BigInt(chainId);
+			const chainIdBytes = uint256ToBytes(chainIdBigInt);
+
+			const parts = [
+				pad32(packedUserOp.sender),
+				uint256ToBytes(packedUserOp.nonce),
+				Keccak256.hash(packedUserOp.initCode),
+				Keccak256.hash(packedUserOp.callData),
+				packedUserOp.accountGasLimits,
+				uint256ToBytes(packedUserOp.preVerificationGas),
+				packedUserOp.gasFees,
+				Keccak256.hash(packedUserOp.paymasterAndData),
+			];
+
+			const totalLength = parts.reduce((acc, part) => acc + part.length, 0);
+			const packed = new Uint8Array(totalLength);
+			let offset = 0;
+			for (const part of parts) {
+				packed.set(part, offset);
+				offset += part.length;
+			}
+
+			const userOpHash = Keccak256.hash(packed);
+
+			const finalPacked = new Uint8Array(32 + 20 + 32);
+			finalPacked.set(userOpHash, 0);
+			finalPacked.set(entryPointAddr, 32);
+			finalPacked.set(pad32(chainIdBytes), 52);
+
+			return Keccak256.hash(finalPacked);
+		},
+		catch: (e) => {
+			if (e instanceof ValidationError) return e;
+			return new ValidationError(e instanceof Error ? e.message : String(e), {
+				value: { packedUserOp, entryPoint, chainId },
+				expected: "valid hash inputs",
+				cause: e instanceof Error ? e : undefined,
+			});
+		},
+	});

package/src/primitives/PackedUserOperation/index.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview PackedUserOperation module for ERC-4337 v0.7 account abstraction.
+ *
+ * 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.
+ *
+ * This module provides Effect-based schemas and functions for creating,
+ * validating, hashing, and unpacking PackedUserOperations.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as PackedUserOperation from 'voltaire-effect/primitives/PackedUserOperation'
+ *
+ * function bundlePackedOps(ops: PackedUserOperation.PackedUserOperationType[]) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as PackedUserOperation from 'voltaire-effect/primitives/PackedUserOperation'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Create packed user operation
+ *   const packed = yield* PackedUserOperation.from({
+ *     sender: '0x1234567890123456789012345678901234567890',
+ *     nonce: 0n,
+ *     initCode: '0x',
+ *     callData: '0xabcd',
+ *     accountGasLimits: new Uint8Array(32),
+ *     preVerificationGas: 21000n,
+ *     gasFees: new Uint8Array(32),
+ *     paymasterAndData: '0x',
+ *     signature: '0x'
+ *   })
+ *
+ *   // Compute hash for signing
+ *   const userOpHash = yield* PackedUserOperation.hash(
+ *     packed,
+ *     '0x0000000071727De22E5E9d8BAf0edAc6f37da032', // v0.7 EntryPoint
+ *     1n
+ *   )
+ *
+ *   // Unpack to full UserOperation
+ *   const userOp = yield* PackedUserOperation.unpack(packed)
+ *
+ *   return { packed, userOpHash, userOp }
+ * })
+ * ```
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-4337
+ * @see UserOperation - For the standard unpacked format
+ * @module PackedUserOperation
+ * @since 0.0.1
+ */
+
+/**
+ * Create a PackedUserOperation from flexible input types.
+ * @see PackedUserOperationFromParams - The input parameter type
+ */
+/**
+ * Compute the ERC-4337 PackedUserOperation hash for signing.
+ */
+/**
+ * The validated PackedUserOperation type with native field types.
+ * @see PackedUserOperationSchema - For parsing from JSON-RPC format
+ */
+export {
+	type PackedUserOperationInput,
+	PackedUserOperationSchema,
+	type PackedUserOperationType,
+} from "./PackedUserOperationSchema.js";
+
+/**
+ * Unpack a PackedUserOperation to standard UserOperation format.
+ * @see UserOperation - For the unpacked format
+ */

package/src/primitives/PackedUserOperation/unpack.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview PackedUserOperation unpacking for ERC-4337 v0.7.
+ *
+ * This module converts PackedUserOperations back to the standard UserOperation
+ * format by extracting the individual gas values from the packed fields.
+ *
+ * The unpacking extracts:
+ * - From `accountGasLimits`: verificationGasLimit (first 16 bytes) + callGasLimit (last 16 bytes)
+ * - From `gasFees`: maxPriorityFeePerGas (first 16 bytes) + maxFeePerGas (last 16 bytes)
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-4337
+ * @module PackedUserOperation/unpack
+ * @since 0.0.1
+ */
+import { ValidationError } from "@tevm/voltaire/errors";
+import * as Effect from "effect/Effect";
+import type { UserOperationType } from "../UserOperation/UserOperationSchema.js";
+import type { PackedUserOperationType } from "./PackedUserOperationSchema.js";
+
+const bytesToUint128 = (bytes: Uint8Array, offset: number): bigint => {
+	let result = 0n;
+	for (let i = 0; i < 16; i++) {
+		result = (result << 8n) | BigInt(bytes[offset + i] ?? 0);
+	}
+	return result;
+};
+
+/**
+ * Unpacks a PackedUserOperation into a full UserOperation.
+ *
+ * Extracts the packed gas fields (accountGasLimits, gasFees) into
+ * their individual components (verificationGasLimit, callGasLimit,
+ * maxPriorityFeePerGas, maxFeePerGas).
+ *
+ * @description
+ * This is the inverse of `UserOperation.pack()`. It extracts:
+ * - `verificationGasLimit`: First 16 bytes of accountGasLimits
+ * - `callGasLimit`: Last 16 bytes of accountGasLimits
+ * - `maxPriorityFeePerGas`: First 16 bytes of gasFees
+ * - `maxFeePerGas`: Last 16 bytes of gasFees
+ *
+ * All other fields are copied directly.
+ *
+ * @param packedUserOp - The packed user operation to unpack
+ * @returns Effect that succeeds with UserOperationType or fails with ValidationError
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import * as PackedUserOperation from 'voltaire-effect/primitives/PackedUserOperation'
+ *
+ * const program = Effect.gen(function* () {
+ *   const packed = yield* PackedUserOperation.from({ ... })
+ *   const userOp = yield* PackedUserOperation.unpack(packed)
+ *   console.log(userOp.callGasLimit)        // extracted from accountGasLimits
+ *   console.log(userOp.verificationGasLimit) // extracted from accountGasLimits
+ *   console.log(userOp.maxFeePerGas)         // extracted from gasFees
+ *   console.log(userOp.maxPriorityFeePerGas) // extracted from gasFees
+ * })
+ * ```
+ *
+ * @throws ValidationError - When the packed fields have invalid format
+ * @see UserOperation.pack - For the inverse operation
+ * @since 0.0.1
+ */
+export const unpack = (
+	packedUserOp: PackedUserOperationType,
+): Effect.Effect<UserOperationType, ValidationError> =>
+	Effect.try({
+		try: () => {
+			const verificationGasLimit = bytesToUint128(
+				packedUserOp.accountGasLimits,
+				0,
+			);
+			const callGasLimit = bytesToUint128(packedUserOp.accountGasLimits, 16);
+			const maxPriorityFeePerGas = bytesToUint128(packedUserOp.gasFees, 0);
+			const maxFeePerGas = bytesToUint128(packedUserOp.gasFees, 16);
+
+			return {
+				sender: packedUserOp.sender,
+				nonce: packedUserOp.nonce,
+				initCode: packedUserOp.initCode,
+				callData: packedUserOp.callData,
+				callGasLimit,
+				verificationGasLimit,
+				preVerificationGas: packedUserOp.preVerificationGas,
+				maxFeePerGas,
+				maxPriorityFeePerGas,
+				paymasterAndData: packedUserOp.paymasterAndData,
+				signature: packedUserOp.signature,
+			} as UserOperationType;
+		},
+		catch: (e) => {
+			if (e instanceof ValidationError) return e;
+			return new ValidationError(e instanceof Error ? e.message : String(e), {
+				value: packedUserOp,
+				expected: "valid PackedUserOperation",
+				cause: e instanceof Error ? e : undefined,
+			});
+		},
+	});

package/src/primitives/Paymaster/PaymasterSchema.ts

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Paymaster Schema definitions for ERC-4337 account abstraction.
+ *
+ * Paymasters are special contracts in ERC-4337 that can sponsor gas fees for
+ * UserOperations. They validate and pay for operations on behalf of users,
+ * enabling gasless transactions and alternative payment methods.
+ *
+ * This module provides Effect Schema definitions for validating and transforming
+ * Paymaster data between JSON-RPC format and native types.
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-4337#extension-paymasters
+ * @module PaymasterSchema
+ * @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 an ERC-4337 Paymaster configuration.
+ *
+ * A Paymaster can sponsor UserOperations by paying for gas fees.
+ * It includes optional time-based validity constraints.
+ *
+ * @example
+ * ```typescript
+ * const paymaster: PaymasterType = {
+ *   address: paymasterAddress,
+ *   data: verificationData,
+ *   validUntil: 1700000000n,
+ *   validAfter: 1600000000n
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export type PaymasterType = {
+	readonly address: AddressType;
+	readonly data: Uint8Array;
+	readonly validUntil?: bigint;
+	readonly validAfter?: bigint;
+};
+
+const PaymasterTypeSchema = S.declare<PaymasterType>(
+	(u): u is PaymasterType =>
+		u !== null && typeof u === "object" && "address" in u && "data" in u,
+	{ identifier: "Paymaster" },
+);
+
+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 BigIntFromInput: S.Schema<bigint, bigint | number | string> =
+	S.transformOrFail(
+		S.Union(S.BigIntFromSelf, S.Number, 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),
+		},
+	);
+
+/**
+ * Input type for Paymaster with string-encoded values.
+ *
+ * This is the JSON-RPC format used when configuring Paymasters.
+ *
+ * @example
+ * ```typescript
+ * const input: PaymasterInput = {
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   data: '0xabcdef',
+ *   validUntil: '1700000000',
+ *   validAfter: '1600000000'
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export type PaymasterInput = {
+	/** Paymaster contract address as hex string */
+	readonly address: string;
+	/** Paymaster-specific verification data as hex string */
+	readonly data: string;
+	/** Unix timestamp after which the Paymaster approval expires */
+	readonly validUntil?: bigint | number | string;
+	/** Unix timestamp before which the Paymaster approval is not valid */
+	readonly validAfter?: bigint | number | string;
+};
+
+/**
+ * Effect Schema for validating and transforming ERC-4337 Paymaster configurations.
+ *
+ * Transforms JSON-RPC format into native PaymasterType with proper
+ * Address, bigint, and Uint8Array types.
+ *
+ * @example
+ * ```typescript
+ * import * as Schema from 'effect/Schema'
+ * import { PaymasterSchema } from 'voltaire-effect/primitives/Paymaster'
+ *
+ * const paymaster = Schema.decodeSync(PaymasterSchema)({
+ *   address: '0x1234567890123456789012345678901234567890',
+ *   data: '0xabcdef',
+ *   validUntil: '1700000000'
+ * })
+ * ```
+ *
+ * @throws ParseError - When input validation fails
+ * @see PaymasterType - The decoded output type
+ * @see PaymasterInput - The encoded input type
+ * @since 0.0.1
+ */
+export const PaymasterSchema: S.Schema<PaymasterType, PaymasterInput> =
+	S.transformOrFail(
+		S.Struct({
+			address: AddressSchema,
+			data: HexStringToBytes,
+			validUntil: S.optional(BigIntFromInput),
+			validAfter: S.optional(BigIntFromInput),
+		}),
+		PaymasterTypeSchema,
+		{
+			strict: true,
+			decode: (input, _options, ast) => {
+				try {
+					const result: PaymasterType = {
+						address: input.address,
+						data: input.data,
+					};
+					if (input.validUntil !== undefined) {
+						(result as any).validUntil = input.validUntil;
+					}
+					if (input.validAfter !== undefined) {
+						(result as any).validAfter = input.validAfter;
+					}
+					return ParseResult.succeed(result);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, input, (e as Error).message),
+					);
+				}
+			},
+			encode: (state) =>
+				ParseResult.succeed({
+					address: state.address,
+					data: state.data,
+					validUntil: state.validUntil,
+					validAfter: state.validAfter,
+				}),
+		},
+	).annotations({ identifier: "PaymasterSchema" });

package/src/primitives/Paymaster/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @module Paymaster
+ * @description ERC-4337 Paymaster configurations for sponsored transactions.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Paymaster from 'voltaire-effect/primitives/Paymaster'
+ *
+ * function sponsorTransaction(paymaster: Paymaster.PaymasterType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export {
+	type PaymasterInput,
+	PaymasterSchema,
+	type PaymasterType,
+} from "./PaymasterSchema.js";

package/src/primitives/PeerId/PeerIdSchema.ts

@@ -0,0 +1,47 @@
+import { PeerId } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing a peer identifier in the P2P network.
+ * @since 0.0.1
+ */
+type PeerIdType = ReturnType<typeof PeerId.from>;
+
+const PeerIdTypeSchema = S.declare<PeerIdType>(
+	(u): u is PeerIdType => typeof u === "string" && u.length > 0,
+	{ identifier: "PeerId" },
+);
+
+/**
+ * Effect Schema for validating and transforming peer identifiers.
+ *
+ * Transforms a string into a validated PeerId type for P2P networking.
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { PeerIdSchema } from 'voltaire-effect/primitives/PeerId'
+ *
+ * const peerId = S.decodeSync(PeerIdSchema)('QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8...')
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const PeerIdSchema: S.Schema<PeerIdType, string> = S.transformOrFail(
+	S.String,
+	PeerIdTypeSchema,
+	{
+		strict: true,
+		decode: (s, _options, ast) => {
+			try {
+				return ParseResult.succeed(PeerId.from(s));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, s, (e as Error).message),
+				);
+			}
+		},
+		encode: (peerId) => ParseResult.succeed(peerId as string),
+	},
+).annotations({ identifier: "PeerIdSchema" });

package/src/primitives/PeerId/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @module PeerId
+ *
+ * @description
+ * PeerId module for Effect-based peer identifier handling.
+ * Provides Effect-wrapped operations for working with P2P network peer IDs.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as PeerId from 'voltaire-effect/primitives/PeerId'
+ *
+ * function connectToPeer(id: PeerId.PeerIdType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as PeerId from 'voltaire-effect/primitives/PeerId'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const peerId = PeerId.from('QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8...')
+ * Effect.runSync(peerId)
+ * ```
+ *
+ * @module
+ * @since 0.0.1
+ */
+
+export { PeerIdSchema } from "./PeerIdSchema.js";

package/src/primitives/PeerInfo/PeerInfoSchema.ts

@@ -0,0 +1,61 @@
+import { PeerInfo } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing detailed information about a P2P network peer.
+ * @since 0.0.1
+ */
+type PeerInfoType = ReturnType<typeof PeerInfo.from>;
+
+const PeerInfoTypeSchema = S.declare<PeerInfoType>(
+	(u): u is PeerInfoType => {
+		if (typeof u !== "object" || u === null) return false;
+		const obj = u as Record<string, unknown>;
+		return (
+			typeof obj.id === "string" &&
+			typeof obj.name === "string" &&
+			Array.isArray(obj.caps) &&
+			typeof obj.network === "object" &&
+			typeof obj.protocols === "object"
+		);
+	},
+	{ identifier: "PeerInfo" },
+);
+
+/**
+ * Effect Schema for validating and transforming peer information.
+ *
+ * Transforms raw peer data into a validated PeerInfoType containing
+ * peer ID, name, capabilities, network info, and protocols.
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { PeerInfoSchema } from 'voltaire-effect/primitives/PeerInfo'
+ *
+ * const peerInfo = S.decodeSync(PeerInfoSchema)({
+ *   id: 'QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8...',
+ *   name: 'Geth/v1.10.0',
+ *   caps: ['eth/66', 'eth/67'],
+ *   network: { localAddress: '127.0.0.1:30303' },
+ *   protocols: { eth: { version: 67 } }
+ * })
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const PeerInfoSchema: S.Schema<PeerInfoType, unknown> =
+	S.transformOrFail(S.Unknown, PeerInfoTypeSchema, {
+		strict: true,
+		decode: (value, _options, ast) => {
+			try {
+				return ParseResult.succeed(PeerInfo.from(value));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, value, (e as Error).message),
+				);
+			}
+		},
+		encode: (peerInfo) => ParseResult.succeed(peerInfo as unknown),
+	}).annotations({ identifier: "PeerInfoSchema" });