voltaire-effect 0.2.23

package/src/services/Account/fromMnemonic.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Address } from "@tevm/voltaire";
+import { HDWallet } from "@tevm/voltaire/native";
+import * as Effect from "effect/Effect";
+import { KeccakLive } from "../../crypto/Keccak256/index.js";
+import { Secp256k1Live } from "../../crypto/Secp256k1/index.js";
+import { MnemonicAccount } from "./fromMnemonic.js";
+import { AccountService } from "./index.js";
+
+const TEST_MNEMONIC =
+	"abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
+const EXPECTED_ADDRESS = "0x9858effd232b4033e47d90003d41ec34ecaeda94";
+
+const makeAccount = (options?: Parameters<typeof MnemonicAccount>[1]) =>
+	Effect.gen(function* () {
+		return yield* AccountService;
+	}).pipe(
+		Effect.provide(MnemonicAccount(TEST_MNEMONIC, options)),
+		Effect.provide(Secp256k1Live),
+		Effect.provide(KeccakLive),
+	);
+
+describe("MnemonicAccount", () => {
+	it.effect("derives default address from BIP-39 test vector", () =>
+		Effect.gen(function* () {
+			const account = yield* makeAccount();
+			expect(Address.toHex(account.address)).toBe(EXPECTED_ADDRESS);
+			expect(account.hdKey).toBeDefined();
+			expect(account.hdKey?.startsWith("xpub")).toBe(true);
+		}),
+	);
+
+	it.effect("supports custom paths", () =>
+		Effect.gen(function* () {
+			const defaultAccount = yield* makeAccount();
+			const customAccount = yield* makeAccount({
+				path: "m/44'/60'/0'/0/0",
+			});
+			expect(Address.toHex(customAccount.address)).toBe(
+				Address.toHex(defaultAccount.address),
+			);
+		}),
+	);
+
+	it.effect("deriveChild matches addressIndex derivation", () =>
+		Effect.gen(function* () {
+			const base = yield* makeAccount();
+			expect(base.deriveChild).toBeDefined();
+
+			if (!base.deriveChild) throw new Error("deriveChild should be defined");
+			const child = yield* base.deriveChild(1);
+			const direct = yield* makeAccount({ addressIndex: 1 });
+
+			expect(Address.toHex(child.address)).toBe(Address.toHex(direct.address));
+		}),
+	);
+
+	it.effect("supports hardened child derivation", () =>
+		Effect.gen(function* () {
+			const base = yield* makeAccount();
+			if (!base.deriveChild) throw new Error("deriveChild should be defined");
+			const hardened = yield* base.deriveChild(HDWallet.HARDENED_OFFSET);
+			expect(hardened.hdKey).toBeDefined();
+			expect(hardened.hdKey?.startsWith("xpub")).toBe(true);
+		}),
+	);
+});

package/src/services/Account/fromMnemonic.ts

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview HD Wallet mnemonic account implementation.
+ *
+ * @module fromMnemonic
+ * @since 0.0.1
+ *
+ * @description
+ * Provides a mnemonic-based account implementation that derives a private key
+ * from a BIP-39 mnemonic phrase using BIP-32/BIP-44 derivation paths.
+ *
+ * IMPORTANT: HDWallet requires native FFI and only works in native
+ * environments (Node.js/Bun with FFI support). WASM bundle not supported.
+ *
+ * @see {@link LocalAccount} - The underlying account implementation
+ * @see {@link AccountService} - The service interface
+ */
+
+import { type BrandedHex, Hex } from "@tevm/voltaire";
+import * as Bip39 from "@tevm/voltaire/Bip39";
+import { HDWallet } from "@tevm/voltaire/native";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+	KeccakService,
+	type KeccakServiceShape,
+} from "../../crypto/Keccak256/index.js";
+import {
+	Secp256k1Service,
+	type Secp256k1ServiceShape,
+} from "../../crypto/Secp256k1/index.js";
+import { AccountService } from "./AccountService.js";
+import { createLocalAccount } from "./LocalAccount.js";
+
+type HexType = BrandedHex.HexType;
+type HDWalletApi = typeof HDWallet;
+type ExtendedKeyType = ReturnType<HDWalletApi["fromSeed"]>;
+
+export interface MnemonicAccountOptions {
+	readonly account?: number;
+	readonly index?: number;
+	readonly addressIndex?: number;
+	readonly path?: string;
+	readonly passphrase?: string;
+}
+
+/**
+ * Creates an account layer from a BIP-39 mnemonic phrase.
+ *
+ * @description
+ * Derives a private key from the mnemonic using BIP-44 derivation path
+ * `m/44'/60'/{account}'/0/{addressIndex}` (default) or a custom `path`
+ * and creates a LocalAccount.
+ *
+ * IMPORTANT: This function requires native FFI and only works in native
+ * environments (Node.js/Bun). The WASM bundle does not support HD wallet.
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase (12-24 words)
+ * @param options - Derivation options
+ * @param options.account - Account index (default: 0)
+ * @param options.index - Address index (default: 0) (legacy alias)
+ * @param options.addressIndex - Address index (default: 0)
+ * @param options.path - Custom derivation path (overrides account/index)
+ * @param options.passphrase - Optional BIP-39 passphrase
+ * @returns Layer providing AccountService
+ *
+ * @since 0.0.1
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Effect, Layer } from 'effect'
+ * import { AccountService } from 'voltaire-effect'
+ * import { MnemonicAccount } from 'voltaire-effect/native'
+ * import { Secp256k1Live, KeccakLive } from 'voltaire-effect/crypto'
+ *
+ * const mnemonic = "test test test test test test test test test test test junk";
+ *
+ * const program = Effect.gen(function* () {
+ *   const account = yield* AccountService
+ *   console.log('Address:', account.address)
+ *   return account
+ * }).pipe(
+ *   Effect.provide(MnemonicAccount(mnemonic)),
+ *   Effect.provide(Secp256k1Live),
+ *   Effect.provide(KeccakLive)
+ * )
+ * ```
+ *
+ * @example Multiple accounts from same mnemonic
+ * ```typescript
+ * // First account (default: m/44'/60'/0'/0/0)
+ * const account0 = MnemonicAccount(mnemonic)
+ *
+ * // Second address in first account (m/44'/60'/0'/0/1)
+ * const account0Index1 = MnemonicAccount(mnemonic, { addressIndex: 1 })
+ *
+ * // Second account (m/44'/60'/1'/0/0)
+ * const account1 = MnemonicAccount(mnemonic, { account: 1 })
+ * ```
+ *
+ * @see {@link LocalAccount} - The underlying account implementation
+ * @see {@link AccountService} - The service interface
+ */
+/**
+ * Error class for HD wallet derivation failures.
+ *
+ * @since 0.0.1
+ */
+export class HDWalletDerivationError extends Error {
+	readonly _tag = "HDWalletDerivationError";
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = "HDWalletDerivationError";
+	}
+}
+
+const createHdAccount = (
+	hdKey: ExtendedKeyType,
+	deps: {
+		readonly secp256k1: Secp256k1ServiceShape;
+		readonly keccak: KeccakServiceShape;
+	},
+	HDWallet: HDWalletApi,
+) =>
+	Effect.gen(function* () {
+		const privateKey = yield* Effect.try({
+			try: () => HDWallet.getPrivateKey(hdKey),
+			catch: (e) =>
+				new HDWalletDerivationError("Failed to extract private key", {
+					cause: e,
+				}),
+		});
+
+		if (!privateKey) {
+			return yield* Effect.fail(
+				new HDWalletDerivationError("Failed to derive private key from HD key"),
+			);
+		}
+
+		const account = yield* createLocalAccount(
+			Hex.fromBytes(privateKey) as HexType,
+			deps,
+		);
+
+		const extendedPublicKey = yield* Effect.try({
+			try: () => HDWallet.toExtendedPublicKey(hdKey),
+			catch: (e) =>
+				new HDWalletDerivationError("Failed to export extended public key", {
+					cause: e,
+				}),
+		});
+
+		return {
+			...account,
+			hdKey: extendedPublicKey,
+			deriveChild: (index: number) =>
+				Effect.gen(function* () {
+					const childKey = yield* Effect.try({
+						try: () => HDWallet.deriveChild(hdKey, index),
+						catch: (e) =>
+							new HDWalletDerivationError(
+								`Failed to derive child at index ${index}`,
+								{ cause: e },
+							),
+					});
+					return yield* createHdAccount(childKey, deps, HDWallet);
+				}),
+		};
+	});
+
+export const MnemonicAccount = (
+	mnemonic: string,
+	options?: MnemonicAccountOptions,
+): Layer.Layer<
+	AccountService,
+	Error | HDWalletDerivationError,
+	Secp256k1Service | KeccakService
+> =>
+	Layer.scoped(
+		AccountService,
+		Effect.gen(function* () {
+			const secp256k1 = yield* Secp256k1Service;
+			const keccak = yield* KeccakService;
+
+			const accountIndex = options?.account ?? 0;
+			const addressIndex = options?.addressIndex ?? options?.index ?? 0;
+			const passphrase = options?.passphrase ?? "";
+			const path =
+				options?.path ?? `m/44'/60'/${accountIndex}'/0/${addressIndex}`;
+
+			if (!Bip39.validateMnemonic(mnemonic)) {
+				return yield* Effect.fail(new Error("Invalid mnemonic phrase"));
+			}
+
+			const seed = yield* Effect.promise(() =>
+				Bip39.mnemonicToSeed(mnemonic, passphrase),
+			);
+
+			const root = yield* Effect.try({
+				try: () => HDWallet.fromSeed(seed),
+				catch: (e) =>
+					new HDWalletDerivationError("Failed to create root HD wallet", {
+						cause: e,
+					}),
+			});
+
+			const derived = yield* Effect.try({
+				try: () => HDWallet.derivePath(root, path),
+				catch: (e) =>
+					new HDWalletDerivationError(`Failed to derive path ${path}`, {
+						cause: e,
+					}),
+			});
+
+			const account = yield* Effect.acquireRelease(
+				createHdAccount(derived, { secp256k1, keccak }, HDWallet),
+				(derivedAccount) => derivedAccount.clearKey(),
+			);
+
+			return account;
+		}),
+	);

package/src/services/Account/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Account module exports for cryptographic signing operations.
+ *
+ * @module Account
+ * @since 0.0.1
+ *
+ * @description
+ * This module provides the account service for cryptographic signing.
+ * Includes the service definition and two implementations:
+ *
+ * - {@link LocalAccount} - Signs locally with a private key
+ * - {@link JsonRpcAccount} - Delegates signing to a JSON-RPC provider
+ *
+ * Main exports:
+ * - {@link AccountService} - The service tag/interface
+ * - {@link LocalAccount} - Local private key layer
+ * - {@link JsonRpcAccount} - Remote JSON-RPC layer
+ * - {@link AccountError} - Error type for failed operations
+ *
+ * Type exports:
+ * - {@link AccountShape} - Service interface shape
+ * - {@link UnsignedTransaction} - Transaction for signing
+ *
+ * @example Using LocalAccount
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { AccountService, LocalAccount } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const account = yield* AccountService
+ *   return yield* account.signMessage(messageHex)
+ * }).pipe(Effect.provide(LocalAccount(privateKey)))
+ * ```
+ *
+ * @example Using JsonRpcAccount
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { AccountService, JsonRpcAccount, BrowserTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const account = yield* AccountService
+ *   return yield* account.signMessage(messageHex)
+ * }).pipe(
+ *   Effect.provide(JsonRpcAccount(userAddress)),
+ *   Effect.provide(BrowserTransport)
+ * )
+ * ```
+ *
+ * @see {@link SignerService} - Uses AccountService for transaction signing
+ */
+
+export {
+	AccountError,
+	AccountService,
+	type AccountShape,
+	type Authorization,
+	type AuthorizationInput,
+	type SignAuthorizationParams,
+	type SignedAuthorization,
+	type UnsignedAuthorization,
+	type UnsignedTransaction,
+} from "./AccountService.js";
+export { JsonRpcAccount } from "./JsonRpcAccount.js";
+export { LocalAccount } from "./LocalAccount.js";
+export { type ToAccountOptions, toAccount } from "./toAccount.js";

package/src/services/Account/toAccount.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Address, type BrandedHex, Signature, TypedData } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import {
+	AccountService,
+	toAccount,
+	type UnsignedTransaction,
+} from "./index.js";
+
+type HexType = BrandedHex.HexType;
+
+type TypedDataType = TypedData.TypedDataType;
+
+const TEST_ADDRESS = "0x0000000000000000000000000000000000000001" as const;
+const TEST_HASH =
+	"0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8" as HexType;
+const TEST_SIGNATURE_HEX = `0x${"11".repeat(64)}1b` as HexType;
+const TEST_SIGNATURE_BYTES = new Uint8Array(65).fill(0x22);
+
+const typedData: TypedDataType = TypedData.from({
+	types: {
+		EIP712Domain: [
+			{ name: "name", type: "string" },
+			{ name: "version", type: "string" },
+			{ name: "chainId", type: "uint256" },
+		],
+		Person: [
+			{ name: "name", type: "string" },
+			{ name: "wallet", type: "address" },
+		],
+	},
+	primaryType: "Person",
+	domain: {
+		name: "Test",
+		version: "1",
+		chainId: 1,
+	},
+	message: {
+		name: "Alice",
+		wallet: Address.fromHex("0x0000000000000000000000000000000000000001"),
+	},
+});
+
+describe("toAccount", () => {
+	const captured: {
+		message?: HexType;
+		tx?: UnsignedTransaction;
+		typedData?: TypedDataType;
+	} = {};
+
+	it.effect("exposes custom signers and normalizes signatures", () =>
+		Effect.gen(function* () {
+			const account = yield* AccountService;
+			expect(account.type).toBe("hardware");
+			expect(Address.toHex(account.address)).toBe(TEST_ADDRESS);
+
+			const message = "0x48656c6c6f" as HexType;
+			const tx: UnsignedTransaction = {
+				to: Address.fromHex("0x0000000000000000000000000000000000000002"),
+				value: 1000000000000000000n,
+				nonce: 0n,
+				gasLimit: 21000n,
+				chainId: 1n,
+			};
+
+			const sigMessage = yield* account.signMessage(message);
+			const sigTx = yield* account.signTransaction(tx);
+			const sigTyped = yield* account.signTypedData(typedData);
+
+			expect(Signature.toHex(sigMessage)).toBe(TEST_SIGNATURE_HEX);
+			expect(Signature.toHex(sigTx)).toBe(
+				Signature.toHex(Signature.fromBytes(TEST_SIGNATURE_BYTES)),
+			);
+			expect(Signature.toHex(sigTyped)).toBe(TEST_SIGNATURE_HEX);
+			expect(captured.message).toBe(message);
+			expect(captured.tx).toEqual(tx);
+			expect(captured.typedData).toEqual(typedData);
+		}).pipe(
+			Effect.provide(
+				toAccount({
+					address: TEST_ADDRESS,
+					signMessage: (message) => {
+						return Effect.sync(() => {
+							captured.message = message;
+							return TEST_SIGNATURE_HEX;
+						});
+					},
+					signTransaction: (tx) => {
+						return Effect.sync(() => {
+							captured.tx = tx;
+							return TEST_SIGNATURE_BYTES;
+						});
+					},
+					signTypedData: (data) => {
+						return Effect.sync(() => {
+							captured.typedData = data;
+							return TEST_SIGNATURE_HEX;
+						});
+					},
+				}),
+			),
+		),
+	);
+
+	it.effect("fails for unsupported sign/signAuthorization by default", () =>
+		Effect.gen(function* () {
+			const account = yield* AccountService;
+
+			const signResult = yield* Effect.either(
+				account.sign({ hash: TEST_HASH }),
+			);
+			expect(signResult._tag).toBe("Left");
+			if (signResult._tag === "Left") {
+				expect(signResult.left._tag).toBe("AccountError");
+			}
+
+			const authResult = yield* Effect.either(
+				account.signAuthorization({
+					contractAddress: TEST_ADDRESS,
+					chainId: 1n,
+					nonce: 0n,
+				}),
+			);
+			expect(authResult._tag).toBe("Left");
+			if (authResult._tag === "Left") {
+				expect(authResult.left._tag).toBe("AccountError");
+			}
+		}).pipe(
+			Effect.provide(
+				toAccount({
+					address: TEST_ADDRESS,
+					signMessage: () => Effect.succeed(TEST_SIGNATURE_HEX),
+					signTransaction: () => Effect.succeed(TEST_SIGNATURE_HEX),
+					signTypedData: () => Effect.succeed(TEST_SIGNATURE_HEX),
+				}),
+			),
+		),
+	);
+});

package/src/services/Account/toAccount.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Factory for creating custom account layers from user-provided signers.
+ *
+ * @module toAccount
+ * @since 0.0.1
+ *
+ * @description
+ * Allows consumers to bring their own signing implementation (hardware wallets,
+ * remote signers, HSMs) and expose it as an AccountService layer.
+ *
+ * @see {@link AccountService} - The service interface
+ */
+
+import {
+	Address,
+	type BrandedAddress,
+	type BrandedHex,
+	type BrandedSignature,
+	Signature,
+	type TypedData,
+} from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+	AccountError,
+	AccountService,
+	type AccountShape,
+	type Authorization,
+	type SignAuthorizationParams,
+	type UnsignedAuthorization,
+	type UnsignedTransaction,
+} from "./AccountService.js";
+
+type AddressType = BrandedAddress.AddressType;
+type HexType = BrandedHex.HexType;
+type SignatureType = BrandedSignature.SignatureType;
+type TypedDataType = TypedData.TypedDataType;
+type AddressInput = AddressType | `0x${string}`;
+type SignatureInput = SignatureType | HexType | Uint8Array;
+
+type SignerEffect<TInput, TOutput> = (
+	input: TInput,
+) => Effect.Effect<TOutput, unknown>;
+
+type OptionalSignerEffect<TInput, TOutput> = (
+	input: TInput,
+) => Effect.Effect<TOutput, unknown>;
+
+export type ToAccountOptions = {
+	/** The account address. */
+	readonly address: AddressInput;
+	/** Account type (defaults to "hardware"). */
+	readonly type?: AccountShape["type"];
+	/** Optional public key for local/hardware accounts. */
+	readonly publicKey?: HexType;
+	/** Optional extended public key for HD accounts. */
+	readonly hdKey?: string;
+	/** Sign a personal message (EIP-191). */
+	readonly signMessage: SignerEffect<HexType, SignatureInput>;
+	/** Sign an unsigned transaction. */
+	readonly signTransaction: SignerEffect<UnsignedTransaction, SignatureInput>;
+	/** Sign typed structured data (EIP-712). */
+	readonly signTypedData: SignerEffect<TypedDataType, SignatureInput>;
+	/** Optional raw hash signer (no prefix). */
+	readonly sign?: OptionalSignerEffect<{ hash: HexType }, SignatureInput>;
+	/** Optional EIP-7702 authorization signer. */
+	readonly signAuthorization?: OptionalSignerEffect<
+		UnsignedAuthorization | SignAuthorizationParams,
+		Authorization
+	>;
+	/** Optional cleanup for sensitive key material. */
+	readonly clearKey?: () => Effect.Effect<void>;
+	/** Optional child derivation for HD accounts. */
+	readonly deriveChild?: (index: number) => Effect.Effect<AccountShape, Error>;
+};
+
+const toAddressType = (address: AddressInput): AddressType =>
+	typeof address === "string" ? Address.fromHex(address) : address;
+
+const toSignatureType = (signature: SignatureInput): SignatureType => {
+	if (Signature.is(signature)) return signature as SignatureType;
+	if (typeof signature === "string") {
+		return Signature.fromHex(signature) as SignatureType;
+	}
+	return Signature.fromBytes(signature) as SignatureType;
+};
+
+const mapToAccountError =
+	(input: unknown, message: string) => (error: unknown) =>
+		error instanceof AccountError
+			? error
+			: new AccountError(input, message, {
+					cause: error instanceof Error ? error : undefined,
+				});
+
+const unsupported = (action: string, input: unknown) =>
+	Effect.fail(
+		new AccountError(input, `${action} is not supported by this account`),
+	);
+
+/**
+ * Creates an account layer from user-provided signing functions.
+ *
+ * @description
+ * Wraps custom signers (hardware wallets, remote signers, HSMs) into the
+ * AccountService interface. Signature results can be provided as a branded
+ * Signature, hex string, or raw bytes (65-byte ECDSA).
+ *
+ * @param options - Custom account configuration and signers
+ * @returns Layer providing AccountService
+ *
+ * @since 0.0.1
+ */
+export const toAccount = (
+	options: ToAccountOptions,
+): Layer.Layer<AccountService> =>
+	Layer.succeed(AccountService, {
+		address: toAddressType(options.address),
+		type: options.type ?? "hardware",
+		publicKey: options.publicKey,
+		hdKey: options.hdKey,
+		signMessage: (message) =>
+			options
+				.signMessage(message)
+				.pipe(
+					Effect.map(toSignatureType),
+					Effect.mapError(
+						mapToAccountError(
+							{ action: "signMessage", message },
+							"Failed to sign message",
+						),
+					),
+				),
+		sign: (params) =>
+			(options.sign
+				? options.sign(params)
+				: unsupported("sign", { action: "sign", params })
+			).pipe(
+				Effect.map(toSignatureType),
+				Effect.mapError(
+					mapToAccountError({ action: "sign", params }, "Failed to sign hash"),
+				),
+			),
+		signTransaction: (tx) =>
+			options
+				.signTransaction(tx)
+				.pipe(
+					Effect.map(toSignatureType),
+					Effect.mapError(
+						mapToAccountError(
+							{ action: "signTransaction", tx },
+							"Failed to sign transaction",
+						),
+					),
+				),
+		signTypedData: (typedData) =>
+			options
+				.signTypedData(typedData)
+				.pipe(
+					Effect.map(toSignatureType),
+					Effect.mapError(
+						mapToAccountError(
+							{ action: "signTypedData", typedData },
+							"Failed to sign typed data",
+						),
+					),
+				),
+		signAuthorization: (authorization) =>
+			(options.signAuthorization
+				? options.signAuthorization(authorization)
+				: unsupported("signAuthorization", {
+						action: "signAuthorization",
+						authorization,
+					})
+			).pipe(
+				Effect.mapError(
+					mapToAccountError(
+						{ action: "signAuthorization", authorization },
+						"Failed to sign authorization",
+					),
+				),
+			),
+		clearKey: options.clearKey ?? (() => Effect.void),
+		deriveChild: options.deriveChild,
+	});