voltaire-effect 0.2.23

package/src/crypto/Signers/Signers.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Signers tests require WASM initialization.
+ * The tests are excluded from voltaire-effect's test run because the underlying
+ * Voltaire signers module uses Keccak256Wasm which requires explicit init.
+ * Run from root with: pnpm vitest run voltaire-effect/src/crypto/Signers/Signers.test.ts
+ */
+
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Signers from "./index.js";
+
+describe("Signers", () => {
+	const testPrivateKey =
+		"0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+
+	describe("fromPrivateKey", () => {
+		it.effect("creates a signer from hex string with 0x prefix", () =>
+			Effect.gen(function* () {
+				const result = yield* Signers.fromPrivateKey(testPrivateKey);
+				expect(result.address).toBeDefined();
+				expect(result.address.startsWith("0x")).toBe(true);
+				expect(result.publicKey).toBeInstanceOf(Uint8Array);
+				expect(result.publicKey.length).toBe(64);
+			}),
+		);
+
+		it.effect("creates a signer from hex string without 0x prefix", () =>
+			Effect.gen(function* () {
+				const result = yield* Signers.fromPrivateKey(testPrivateKey.slice(2));
+				expect(result.address).toBeDefined();
+				expect(result.publicKey.length).toBe(64);
+			}),
+		);
+
+		it.effect("creates a signer from Uint8Array", () =>
+			Effect.gen(function* () {
+				const privateKeyBytes = new Uint8Array([
+					0xac, 0x09, 0x74, 0xbe, 0xc3, 0x9a, 0x17, 0xe3, 0x6b, 0xa4, 0xa6,
+					0xb4, 0xd2, 0x38, 0xff, 0x94, 0x4b, 0xac, 0xb4, 0x78, 0xcb, 0xed,
+					0x5e, 0xfc, 0xae, 0x78, 0x4d, 0x7b, 0xf4, 0xf2, 0xff, 0x80,
+				]);
+				const result = yield* Signers.fromPrivateKey(privateKeyBytes);
+				expect(result.address).toBeDefined();
+				expect(result.publicKey.length).toBe(64);
+			}),
+		);
+
+		it("fails with invalid private key length", async () => {
+			const exit = await Effect.runPromiseExit(
+				Signers.fromPrivateKey("0x1234"),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+
+	describe("signMessage", () => {
+		it.effect("signs a string message", () =>
+			Effect.gen(function* () {
+				const signer = yield* Signers.fromPrivateKey(testPrivateKey);
+				const signature = yield* signer.signMessage("Hello, Ethereum!");
+				expect(signature.startsWith("0x")).toBe(true);
+				expect(signature.length).toBe(132);
+			}),
+		);
+
+		it.effect("signs a Uint8Array message", () =>
+			Effect.gen(function* () {
+				const signer = yield* Signers.fromPrivateKey(testPrivateKey);
+				const message = new TextEncoder().encode("Hello");
+				const signature = yield* signer.signMessage(message);
+				expect(signature.startsWith("0x")).toBe(true);
+				expect(signature.length).toBe(132);
+			}),
+		);
+
+		it.effect("produces deterministic signatures", () =>
+			Effect.gen(function* () {
+				const signer = yield* Signers.fromPrivateKey(testPrivateKey);
+				const sig1 = yield* signer.signMessage("test");
+				const sig2 = yield* signer.signMessage("test");
+				expect(sig1).toEqual(sig2);
+			}),
+		);
+	});
+
+	describe("signTypedData", () => {
+		it.effect("signs EIP-712 typed data", () =>
+			Effect.gen(function* () {
+				const signer = yield* Signers.fromPrivateKey(testPrivateKey);
+				const typedData = {
+					types: {
+						EIP712Domain: [
+							{ name: "name", type: "string" },
+							{ name: "version", type: "string" },
+						],
+						Message: [{ name: "content", type: "string" }],
+					},
+					primaryType: "Message",
+					domain: { name: "MyApp", version: "1" },
+					message: { content: "Hello" },
+				};
+				const signature = yield* signer.signTypedData(typedData);
+				expect(signature.startsWith("0x")).toBe(true);
+				expect(signature.length).toBe(132);
+			}),
+		);
+	});
+
+	describe("getSignerAddress", () => {
+		it.effect("returns the signer address", () =>
+			Effect.gen(function* () {
+				const signer = yield* Signers.fromPrivateKey(testPrivateKey);
+				const address = yield* Signers.getAddress(signer);
+				expect(address).toBe(signer.address);
+			}),
+		);
+	});
+
+	describe("SignersService", () => {
+		it.effect("provides fromPrivateKey through service layer", () =>
+			Effect.gen(function* () {
+				const signers = yield* Signers.SignersService;
+				const result = yield* signers.fromPrivateKey(testPrivateKey);
+				expect(result.address).toBeDefined();
+				expect(result.publicKey.length).toBe(64);
+			}).pipe(Effect.provide(Signers.SignersLive)),
+		);
+
+		it.effect("provides getAddress through service layer", () =>
+			Effect.gen(function* () {
+				const signer = yield* Signers.fromPrivateKey(testPrivateKey);
+				const signers = yield* Signers.SignersService;
+				const result = yield* signers.getAddress(signer);
+				expect(result).toBe(signer.address);
+			}).pipe(Effect.provide(Signers.SignersLive)),
+		);
+
+		it.effect("works with test layer", () =>
+			Effect.gen(function* () {
+				const signers = yield* Signers.SignersService;
+				const result = yield* signers.fromPrivateKey(`0x${"00".repeat(32)}`);
+				expect(result.address).toBe(
+					"0x0000000000000000000000000000000000000000",
+				);
+			}).pipe(Effect.provide(Signers.SignersTest)),
+		);
+	});
+});

package/src/crypto/Signers/SignersLive.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Production implementation of SignersService.
+ * @module Signers/SignersLive
+ * @since 0.0.1
+ */
+import * as Layer from "effect/Layer";
+import {
+	fromPrivateKey,
+	getAddress,
+	recoverTransactionAddress,
+} from "./operations.js";
+import { SignersService } from "./SignersService.js";
+
+/**
+ * Production layer for SignersService using native implementation.
+ *
+ * @description
+ * Provides real signing operations using secp256k1 for signatures.
+ * Supports EIP-191 personal sign, transaction signing, and EIP-712 typed data.
+ *
+ * @example
+ * ```typescript
+ * import { SignersService, SignersLive } from 'voltaire-effect/crypto/Signers'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const signers = yield* SignersService
+ *   const signer = yield* signers.fromPrivateKey(privateKey)
+ *   return yield* signers.getAddress(signer)
+ * }).pipe(Effect.provide(SignersLive))
+ * ```
+ *
+ * @since 0.0.1
+ * @see {@link SignersTest} for unit testing
+ */
+export const SignersLive = Layer.succeed(SignersService, {
+	fromPrivateKey,
+	getAddress,
+	recoverTransactionAddress,
+});

package/src/crypto/Signers/SignersService.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview SignersService Effect service definition for cryptographic signing.
+ * @module
+ * @since 0.0.1
+ */
+
+import type { CryptoError, InvalidPrivateKeyError } from "@tevm/voltaire";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+
+/**
+ * Represents an Ethereum signer capable of signing messages, transactions, and typed data.
+ *
+ * @since 0.0.1
+ */
+export interface Signer {
+	/** The Ethereum address derived from the signer's public key */
+	readonly address: string;
+	/** The 64-byte uncompressed public key (without 04 prefix) */
+	readonly publicKey: Uint8Array;
+	/** Signs a message using EIP-191 personal sign format */
+	readonly signMessage: (
+		message: string | Uint8Array,
+	) => Effect.Effect<string, CryptoError>;
+	/** Signs a transaction and returns the signed transaction */
+	readonly signTransaction: (
+		transaction: unknown,
+	) => Effect.Effect<unknown, CryptoError>;
+	/** Signs EIP-712 typed data */
+	readonly signTypedData: (
+		typedData: unknown,
+	) => Effect.Effect<string, CryptoError>;
+}
+
+/**
+ * Shape of the SignersService interface.
+ *
+ * @since 0.0.1
+ */
+export interface SignersServiceShape {
+	/** Creates a signer from a private key */
+	readonly fromPrivateKey: (
+		privateKey: string | Uint8Array,
+	) => Effect.Effect<Signer, InvalidPrivateKeyError>;
+
+	/** Gets the Ethereum address from a signer */
+	readonly getAddress: (signer: Signer) => Effect.Effect<string, never>;
+
+	/** Recovers the sender address from a signed transaction */
+	readonly recoverTransactionAddress: (
+		transaction: unknown,
+	) => Effect.Effect<string, CryptoError>;
+}
+
+/**
+ * Effect service tag for cryptographic signing operations.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const signers = yield* SignersService
+ *   const signer = yield* signers.fromPrivateKey(privateKey)
+ *   const address = yield* signers.getAddress(signer)
+ *   return address
+ * })
+ * ```
+ *
+ * @since 0.0.1
+ */
+export class SignersService extends Context.Tag("SignersService")<
+	SignersService,
+	SignersServiceShape
+>() {}

package/src/crypto/Signers/SignersTest.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Test implementation of SignersService.
+ * @module Signers/SignersTest
+ * @since 0.0.1
+ */
+
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+	type Signer,
+	SignersService,
+	type SignersServiceShape,
+} from "./SignersService.js";
+
+const mockSigner: Signer = {
+	address: "0x0000000000000000000000000000000000000000",
+	publicKey: new Uint8Array(64),
+	signMessage: (_message) => Effect.succeed(`0x${"00".repeat(65)}`),
+	signTransaction: (transaction) => Effect.succeed(transaction),
+	signTypedData: (_typedData) => Effect.succeed(`0x${"00".repeat(65)}`),
+};
+
+const testImpl: SignersServiceShape = {
+	fromPrivateKey: (_privateKey) => Effect.succeed(mockSigner),
+	getAddress: (signer) => Effect.succeed(signer.address),
+	recoverTransactionAddress: (_transaction) =>
+		Effect.succeed("0x0000000000000000000000000000000000000000"),
+};
+
+/**
+ * Test layer for SignersService returning deterministic mock values.
+ *
+ * @description
+ * Provides mock implementations for unit testing. Returns a signer with
+ * the zero address and mock signatures.
+ * Use when testing application logic without cryptographic overhead.
+ *
+ * @example
+ * ```typescript
+ * import { SignersService, SignersTest, fromPrivateKey } from 'voltaire-effect/crypto/Signers'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const testProgram = fromPrivateKey('0x...').pipe(Effect.provide(SignersTest))
+ * // Returns mock signer with zero address
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const SignersTest = Layer.succeed(SignersService, testImpl);

package/src/crypto/Signers/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Ethereum signers module for Effect.
+ * Provides cryptographic signing of messages, transactions, and typed data.
+ *
+ * @module Signers
+ * @since 0.0.1
+ *
+ * @description
+ * Signers handle cryptographic signing operations for Ethereum. Each signer
+ * encapsulates a private key and provides methods for:
+ *
+ * - Message signing (EIP-191 personal_sign)
+ * - Transaction signing
+ * - Typed data signing (EIP-712)
+ *
+ * @example
+ * ```typescript
+ * import { SignersService, SignersLive, fromPrivateKey, getAddress } from 'voltaire-effect/crypto/Signers'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const signer = yield* fromPrivateKey('0x...')
+ *   const address = yield* getAddress(signer)
+ *   const sig = yield* signer.signMessage('Hello World')
+ *   return { address, sig }
+ * }).pipe(Effect.provide(SignersLive))
+ * ```
+ *
+ * @see {@link https://eips.ethereum.org/EIPS/eip-191 | EIP-191}
+ * @see {@link https://eips.ethereum.org/EIPS/eip-712 | EIP-712}
+ */
+export {
+	fromPrivateKey,
+	getAddress,
+	getAddress as getSignerAddress,
+	recoverTransactionAddress,
+} from "./operations.js";
+export { SignersLive } from "./SignersLive.js";
+export {
+	type Signer,
+	SignersService,
+	type SignersServiceShape,
+} from "./SignersService.js";
+export { SignersTest } from "./SignersTest.js";

package/src/crypto/Signers/operations.ts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Signer operations for Effect.
+ * @module Signers/operations
+ * @since 0.0.1
+ */
+
+import { Signers } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import type { Signer } from "./SignersService.js";
+
+type CryptoError = Error;
+type InvalidPrivateKeyError = Error & { code: "INVALID_PRIVATE_KEY" };
+
+/**
+ * Creates a signer from a private key.
+ *
+ * @description
+ * Constructs a Signer object that can sign messages, transactions, and typed data.
+ * The signer derives the Ethereum address and public key from the private key.
+ *
+ * @param privateKey - The 32-byte private key as hex string or Uint8Array
+ * @returns Effect containing a Signer object
+ *
+ * @example
+ * ```typescript
+ * import { fromPrivateKey, SignersLive } from 'voltaire-effect/crypto/Signers'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const signer = yield* fromPrivateKey('0x...')
+ *   const sig = yield* signer.signMessage('Hello')
+ *   return sig
+ * }).pipe(Effect.provide(SignersLive))
+ * ```
+ *
+ * @throws InvalidPrivateKeyError if the private key is invalid
+ * @see {@link getAddress} to get the signer's address
+ * @since 0.0.1
+ */
+export const fromPrivateKey = (
+	privateKey: string | Uint8Array,
+): Effect.Effect<Signer, InvalidPrivateKeyError> =>
+	Effect.try({
+		try: () => {
+			const impl = Signers.PrivateKeySignerImpl.fromPrivateKey({ privateKey });
+			return {
+				address: impl.address,
+				publicKey: impl.publicKey,
+				signMessage: (message: string | Uint8Array) =>
+					Effect.tryPromise({
+						try: () => impl.signMessage(message),
+						catch: (e) => e as CryptoError,
+					}),
+				signTransaction: (transaction: unknown) =>
+					Effect.tryPromise({
+						try: () => impl.signTransaction(transaction),
+						catch: (e) => e as CryptoError,
+					}),
+				signTypedData: (typedData: unknown) =>
+					Effect.tryPromise({
+						try: () => impl.signTypedData(typedData),
+						catch: (e) => e as CryptoError,
+					}),
+			} as Signer;
+		},
+		catch: (e) => e as InvalidPrivateKeyError,
+	});
+
+/**
+ * Gets the Ethereum address from a signer.
+ *
+ * @description
+ * Returns the 20-byte Ethereum address derived from the signer's public key.
+ * The address is checksummed per EIP-55.
+ *
+ * @param signer - The signer object
+ * @returns Effect containing the Ethereum address as 0x-prefixed hex string
+ *
+ * @example
+ * ```typescript
+ * import { fromPrivateKey, getAddress, SignersLive } from 'voltaire-effect/crypto/Signers'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const signer = yield* fromPrivateKey('0x...')
+ *   return yield* getAddress(signer)
+ * }).pipe(Effect.provide(SignersLive))
+ * ```
+ *
+ * @throws Never fails
+ * @since 0.0.1
+ */
+export const getAddress = (signer: Signer): Effect.Effect<string, never> =>
+	Effect.succeed(signer.address);
+
+/**
+ * Recovers the sender address from a signed transaction.
+ *
+ * @description
+ * Uses ecrecover to extract the Ethereum address that signed a transaction.
+ * This is how nodes verify transaction authenticity.
+ *
+ * @param transaction - The signed transaction object
+ * @returns Effect containing the recovered Ethereum address
+ *
+ * @example
+ * ```typescript
+ * import { recoverTransactionAddress, SignersLive } from 'voltaire-effect/crypto/Signers'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = recoverTransactionAddress(signedTx).pipe(Effect.provide(SignersLive))
+ * ```
+ *
+ * @throws CryptoError if signature recovery fails
+ * @since 0.0.1
+ */
+export const recoverTransactionAddress = (
+	transaction: unknown,
+): Effect.Effect<string, CryptoError> =>
+	Effect.tryPromise({
+		try: () => Signers.recoverTransactionAddress(transaction),
+		catch: (e) => e as CryptoError,
+	});

package/src/crypto/Verify/errors.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Error types for signature verification operations.
+ * @module Verify/errors
+ * @since 0.0.1
+ */
+
+import * as Data from "effect/Data";
+
+/**
+ * Error when signature recovery fails.
+ *
+ * @description
+ * Thrown when the signature cannot be recovered to a valid public key.
+ * This can happen with malformed signatures or invalid recovery IDs.
+ *
+ * @since 0.0.1
+ */
+export class SignatureRecoveryError extends Data.TaggedError(
+	"SignatureRecoveryError",
+)<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {
+	/**
+	 * Creates a new SignatureRecoveryError.
+	 *
+	 * @param message - Error description
+	 * @param options - Optional cause
+	 */
+	static of(
+		message: string,
+		options?: { cause?: unknown },
+	): SignatureRecoveryError {
+		return new SignatureRecoveryError({ message, cause: options?.cause });
+	}
+}
+
+/**
+ * Error when address derivation from public key fails.
+ *
+ * @description
+ * Thrown when the recovered public key cannot be converted to an address.
+ *
+ * @since 0.0.1
+ */
+export class AddressDerivationError extends Data.TaggedError(
+	"AddressDerivationError",
+)<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {
+	/**
+	 * Creates a new AddressDerivationError.
+	 *
+	 * @param message - Error description
+	 * @param options - Optional cause
+	 */
+	static of(
+		message: string,
+		options?: { cause?: unknown },
+	): AddressDerivationError {
+		return new AddressDerivationError({ message, cause: options?.cause });
+	}
+}
+
+/**
+ * Error when message hashing fails.
+ *
+ * @description
+ * Thrown when EIP-191 message hashing encounters an error.
+ *
+ * @since 0.0.1
+ */
+export class MessageHashError extends Data.TaggedError("MessageHashError")<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {
+	/**
+	 * Creates a new MessageHashError.
+	 *
+	 * @param message - Error description
+	 * @param options - Optional cause
+	 */
+	static of(message: string, options?: { cause?: unknown }): MessageHashError {
+		return new MessageHashError({ message, cause: options?.cause });
+	}
+}
+
+/**
+ * Union type of all verification errors.
+ *
+ * @since 0.0.1
+ */
+export type VerifyError =
+	| SignatureRecoveryError
+	| AddressDerivationError
+	| MessageHashError;

package/src/crypto/Verify/hashMessage.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview EIP-191 personal message hashing for Effect.
+ * @module Verify/hashMessage
+ * @since 0.0.1
+ */
+
+import type { Keccak256Hash } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import { KeccakService } from "../Keccak256/index.js";
+
+/**
+ * EIP-191 prefix for personal_sign messages.
+ * @see https://eips.ethereum.org/EIPS/eip-191
+ */
+const EIP191_PREFIX = "\x19Ethereum Signed Message:\n";
+
+/**
+ * Hashes a message according to EIP-191 personal_sign format.
+ *
+ * @description
+ * Creates the hash: keccak256("\x19Ethereum Signed Message:\n" + len + message)
+ *
+ * This is the standard format used by `personal_sign` in Ethereum wallets.
+ * The prefix prevents signed messages from being valid transactions.
+ *
+ * @param message - The message to hash (string or bytes)
+ * @returns Effect containing the 32-byte hash, requiring KeccakService
+ *
+ * @example
+ * ```typescript
+ * import { hashMessage, KeccakLive } from 'voltaire-effect/crypto/Verify'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = hashMessage('Hello, Ethereum!').pipe(Effect.provide(KeccakLive))
+ * const hash = await Effect.runPromise(program)
+ * ```
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-191
+ * @since 0.0.1
+ */
+export const hashMessage = (
+	message: string | Uint8Array,
+): Effect.Effect<Keccak256Hash, never, KeccakService> =>
+	Effect.gen(function* () {
+		const keccak = yield* KeccakService;
+
+		// Convert string to bytes if needed
+		const messageBytes =
+			typeof message === "string" ? new TextEncoder().encode(message) : message;
+
+		// Create length string
+		const lenStr = String(messageBytes.length);
+		const lenBytes = new TextEncoder().encode(lenStr);
+
+		// Prefix bytes
+		const prefixBytes = new TextEncoder().encode(EIP191_PREFIX);
+
+		// Concatenate: prefix + len + message
+		const totalLength =
+			prefixBytes.length + lenBytes.length + messageBytes.length;
+		const data = new Uint8Array(totalLength);
+		data.set(prefixBytes, 0);
+		data.set(lenBytes, prefixBytes.length);
+		data.set(messageBytes, prefixBytes.length + lenBytes.length);
+
+		// Hash the complete message
+		return yield* keccak.hash(data);
+	});