voltaire-effect 0.2.23

package/src/crypto/Secp256k1/Secp256k1Service.ts

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Secp256k1 service definition for Effect-based applications.
+ * Provides the service tag and shape interface for secp256k1 cryptographic operations.
+ *
+ * @module Secp256k1/Secp256k1Service
+ * @since 0.0.1
+ */
+
+import type { HashType } from "@tevm/voltaire/Hash";
+import type {
+	Secp256k1PublicKeyType,
+	Secp256k1SignatureType,
+} from "@tevm/voltaire/Secp256k1";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type {
+	InvalidPrivateKeyError,
+	InvalidPublicKeyError,
+	InvalidRecoveryIdError,
+	InvalidSignatureError,
+	Secp256k1Error,
+} from "./errors.js";
+
+/**
+ * Options for secp256k1 signing operations.
+ *
+ * @description
+ * Configuration options for the sign operation, primarily for controlling
+ * the RFC 6979 deterministic nonce generation.
+ *
+ * @example Using extra entropy
+ * ```typescript
+ * import { sign } from 'voltaire-effect/crypto/Secp256k1'
+ *
+ * const options: SignOptions = {
+ *   extraEntropy: crypto.getRandomValues(new Uint8Array(32))
+ * }
+ * const signature = await Effect.runPromise(sign(hash, key, options))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export interface SignOptions {
+	/**
+	 * Additional entropy for RFC 6979 nonce generation.
+	 *
+	 * @description
+	 * When set to a Uint8Array, it is mixed into the nonce generation for
+	 * additional randomness beyond the deterministic RFC 6979 algorithm.
+	 * When set to `true`, random entropy is automatically generated.
+	 * When undefined or `false`, standard RFC 6979 is used.
+	 */
+	readonly extraEntropy?: Uint8Array | boolean;
+}
+
+/**
+ * Shape interface for secp256k1 cryptographic service operations.
+ *
+ * @description
+ * Defines the contract for secp256k1 ECDSA implementations. This interface
+ * specifies the three core operations: sign, recover, and verify.
+ *
+ * Used as the service shape for {@link Secp256k1Service}.
+ *
+ * @since 0.0.1
+ */
+export interface Secp256k1ServiceShape {
+	/**
+	 * Signs a message hash using secp256k1 ECDSA.
+	 *
+	 * @param {HashType} messageHash - The 32-byte message hash to sign
+	 * @param {Uint8Array} privateKey - The 32-byte private key
+	 * @param {SignOptions} [options] - Optional signing options for extra entropy
+	 * @returns {Effect.Effect<Secp256k1SignatureType, InvalidPrivateKeyError | Secp256k1Error>}
+	 *   Effect containing the 65-byte recoverable signature
+	 */
+	readonly sign: (
+		messageHash: HashType,
+		privateKey: Uint8Array,
+		options?: SignOptions,
+	) => Effect.Effect<
+		Secp256k1SignatureType,
+		InvalidPrivateKeyError | Secp256k1Error
+	>;
+
+	/**
+	 * Recovers the public key from a signature and message hash.
+	 *
+	 * @param {Secp256k1SignatureType} signature - The 65-byte recoverable signature
+	 * @param {HashType} messageHash - The 32-byte message hash
+	 * @returns {Effect.Effect<Secp256k1PublicKeyType, InvalidSignatureError | InvalidRecoveryIdError | Secp256k1Error>}
+	 *   Effect containing the 65-byte uncompressed public key
+	 */
+	readonly recover: (
+		signature: Secp256k1SignatureType,
+		messageHash: HashType,
+	) => Effect.Effect<
+		Secp256k1PublicKeyType,
+		InvalidSignatureError | InvalidRecoveryIdError | Secp256k1Error
+	>;
+
+	/**
+	 * Verifies a secp256k1 signature against a message hash and public key.
+	 *
+	 * @param {Secp256k1SignatureType} signature - The 65-byte signature
+	 * @param {HashType} messageHash - The 32-byte message hash
+	 * @param {Secp256k1PublicKeyType} publicKey - The 65-byte uncompressed public key
+	 * @returns {Effect.Effect<boolean, InvalidSignatureError | InvalidPublicKeyError | Secp256k1Error>}
+	 *   Effect containing true if signature is valid
+	 */
+	readonly verify: (
+		signature: Secp256k1SignatureType,
+		messageHash: HashType,
+		publicKey: Secp256k1PublicKeyType,
+	) => Effect.Effect<
+		boolean,
+		InvalidSignatureError | InvalidPublicKeyError | Secp256k1Error
+	>;
+}
+
+/**
+ * Secp256k1 cryptographic service for Effect-based applications.
+ *
+ * @description
+ * An Effect Context.Tag that provides the standard Ethereum elliptic curve
+ * (secp256k1) for transaction and message signing. The service pattern enables
+ * swapping implementations for testing or alternative backends.
+ *
+ * The service exposes three operations:
+ * - `sign` - Create a recoverable signature from a message hash and private key
+ * - `recover` - Recover the public key from a signature and message hash
+ * - `verify` - Verify a signature against a public key
+ *
+ * @example Basic usage with Effect.gen
+ * ```typescript
+ * import { Secp256k1Service, Secp256k1Live } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const secp = yield* Secp256k1Service
+ *   const sig = yield* secp.sign(messageHash, privateKey)
+ *   const pubKey = yield* secp.recover(sig, messageHash)
+ *   return yield* secp.verify(sig, messageHash, pubKey)
+ * }).pipe(Effect.provide(Secp256k1Live))
+ *
+ * const isValid = await Effect.runPromise(program) // true
+ * ```
+ *
+ * @example Signing a transaction
+ * ```typescript
+ * import { Secp256k1Service, Secp256k1Live } from 'voltaire-effect/crypto/Secp256k1'
+ * import { KeccakService, KeccakLive } from 'voltaire-effect/crypto/Keccak256'
+ * import * as Effect from 'effect/Effect'
+ * import * as Layer from 'effect/Layer'
+ *
+ * const signTx = (txBytes: Uint8Array, privateKey: Uint8Array) =>
+ *   Effect.gen(function* () {
+ *     const keccak = yield* KeccakService
+ *     const secp = yield* Secp256k1Service
+ *     const txHash = yield* keccak.hash(txBytes)
+ *     return yield* secp.sign(txHash, privateKey)
+ *   })
+ *
+ * const CryptoLive = Layer.merge(KeccakLive, Secp256k1Live)
+ * const signature = await Effect.runPromise(signTx(tx, key).pipe(Effect.provide(CryptoLive)))
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * import { Secp256k1Service, Secp256k1Live } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const secp = yield* Secp256k1Service
+ *   return yield* secp.sign(messageHash, privateKey)
+ * }).pipe(
+ *   Effect.catchTag('InvalidPrivateKeyError', (e) =>
+ *     Effect.fail(new Error(`Invalid key: ${e.message}`))
+ *   ),
+ *   Effect.provide(Secp256k1Live)
+ * )
+ * ```
+ *
+ * @see {@link Secp256k1Live} - Production implementation
+ * @see {@link Secp256k1Test} - Test implementation
+ * @see {@link sign} - Standalone sign function
+ * @see {@link recover} - Standalone recover function
+ * @see {@link verify} - Standalone verify function
+ * @since 0.0.1
+ */
+export class Secp256k1Service extends Context.Tag("Secp256k1Service")<
+	Secp256k1Service,
+	Secp256k1ServiceShape
+>() {}

package/src/crypto/Secp256k1/Secp256k1Test.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview Test layer for Secp256k1Service.
+ * Provides deterministic mock values for unit testing.
+ *
+ * @module Secp256k1/Secp256k1Test
+ * @since 0.0.1
+ */
+
+import type {
+	Secp256k1PublicKeyType,
+	Secp256k1SignatureType,
+} from "@tevm/voltaire/Secp256k1";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+	Secp256k1Service,
+	type Secp256k1ServiceShape,
+} from "./Secp256k1Service.js";
+
+/**
+ * Mock 65-byte signature filled with zeros.
+ * @internal
+ */
+const mockSignature = new Uint8Array(65) as unknown as Secp256k1SignatureType;
+
+/**
+ * Mock 65-byte public key filled with zeros.
+ * @internal
+ */
+const mockPublicKey = new Uint8Array(65) as unknown as Secp256k1PublicKeyType;
+
+/**
+ * Test implementation of Secp256k1ServiceShape.
+ * @internal
+ */
+const testImpl: Secp256k1ServiceShape = {
+	sign: (_messageHash, _privateKey, _options) => Effect.succeed(mockSignature),
+	recover: (_signature, _messageHash) => Effect.succeed(mockPublicKey),
+	verify: (_signature, _messageHash, _publicKey) => Effect.succeed(true),
+};
+
+/**
+ * Test layer for Secp256k1Service returning deterministic mock values.
+ *
+ * @description
+ * Provides a mock secp256k1 implementation for unit testing without
+ * cryptographic overhead. All operations return deterministic values:
+ * - `sign` returns a 65-byte zero-filled signature
+ * - `recover` returns a 65-byte zero-filled public key
+ * - `verify` always returns `true`
+ *
+ * This layer is useful for:
+ * - Unit tests that need deterministic output
+ * - Performance tests that want to isolate non-crypto logic
+ * - Tests where cryptographic correctness is not the focus
+ *
+ * @example Using in tests
+ * ```typescript
+ * import { Secp256k1Service, Secp256k1Test } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ * import { describe, it, expect } from 'vitest'
+ *
+ * describe('TransactionService', () => {
+ *   it('should sign transactions', async () => {
+ *     const program = Effect.gen(function* () {
+ *       const secp = yield* Secp256k1Service
+ *       return yield* secp.sign(fakeHash, fakeKey)
+ *     })
+ *
+ *     const sig = await Effect.runPromise(program.pipe(Effect.provide(Secp256k1Test)))
+ *     expect(sig.length).toBe(65)
+ *   })
+ *
+ *   it('should verify returns true in test mode', async () => {
+ *     const program = Effect.gen(function* () {
+ *       const secp = yield* Secp256k1Service
+ *       return yield* secp.verify(fakeSig, fakeHash, fakePubKey)
+ *     })
+ *
+ *     const isValid = await Effect.runPromise(program.pipe(Effect.provide(Secp256k1Test)))
+ *     expect(isValid).toBe(true)
+ *   })
+ * })
+ * ```
+ *
+ * @example Combining with other test layers
+ * ```typescript
+ * import { Secp256k1Test } from 'voltaire-effect/crypto/Secp256k1'
+ * import { KeccakTest } from 'voltaire-effect/crypto/Keccak256'
+ * import * as Layer from 'effect/Layer'
+ *
+ * const CryptoTest = Layer.merge(Secp256k1Test, KeccakTest)
+ *
+ * const result = await Effect.runPromise(program.pipe(Effect.provide(CryptoTest)))
+ * ```
+ *
+ * @see {@link Secp256k1Service} - The service tag
+ * @see {@link Secp256k1Live} - Production implementation
+ * @since 0.0.1
+ */
+export const Secp256k1Test = Layer.succeed(Secp256k1Service, testImpl);

package/src/crypto/Secp256k1/errors.ts

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview Error types and mapping helpers for Secp256k1 Effect wrappers.
+ *
+ * @module Secp256k1/errors
+ * @since 0.0.1
+ */
+
+import {
+	InvalidPrivateKeyError as VoltaireInvalidPrivateKeyError,
+	InvalidPublicKeyError as VoltaireInvalidPublicKeyError,
+	InvalidSignatureError as VoltaireInvalidSignatureError,
+	Secp256k1Error as VoltaireSecp256k1Error,
+} from "@tevm/voltaire/Secp256k1";
+import * as Data from "effect/Data";
+
+/**
+ * Base error for all Secp256k1 cryptographic operations.
+ *
+ * @since 0.0.1
+ */
+export class Secp256k1Error extends Data.TaggedError("Secp256k1Error")<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Invalid private key format or value.
+ *
+ * @since 0.0.1
+ */
+export class InvalidPrivateKeyError extends Data.TaggedError(
+	"InvalidPrivateKeyError",
+)<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Invalid public key format or not on curve.
+ *
+ * @since 0.0.1
+ */
+export class InvalidPublicKeyError extends Data.TaggedError(
+	"InvalidPublicKeyError",
+)<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Invalid signature format or components.
+ *
+ * @since 0.0.1
+ */
+export class InvalidSignatureError extends Data.TaggedError(
+	"InvalidSignatureError",
+)<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Recovery ID is invalid for signature recovery.
+ *
+ * @since 0.0.1
+ */
+export class InvalidRecoveryIdError extends Data.TaggedError(
+	"InvalidRecoveryIdError",
+)<{
+	readonly message: string;
+	readonly recoveryId: number;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Union of all Secp256k1 error types.
+ *
+ * @since 0.0.1
+ */
+export type Secp256k1Errors =
+	| Secp256k1Error
+	| InvalidPrivateKeyError
+	| InvalidPublicKeyError
+	| InvalidSignatureError
+	| InvalidRecoveryIdError;
+
+export type Secp256k1Operation = "sign" | "recover" | "verify";
+
+const getMessage = (error: unknown): string =>
+	error instanceof Error ? error.message : String(error);
+
+const getRecoveryId = (error: unknown): number | undefined => {
+	if (!error || typeof error !== "object") return undefined;
+	const candidate =
+		(error as { recoveryId?: unknown }).recoveryId ??
+		(error as { v?: unknown }).v;
+	return typeof candidate === "number" ? candidate : undefined;
+};
+
+/**
+ * Maps unknown errors to specific Secp256k1 error types.
+ *
+ * @since 0.0.1
+ */
+export function mapToSecp256k1Error(
+	error: unknown,
+	operation: "sign",
+): InvalidPrivateKeyError | Secp256k1Error;
+export function mapToSecp256k1Error(
+	error: unknown,
+	operation: "recover",
+): InvalidSignatureError | InvalidRecoveryIdError | Secp256k1Error;
+export function mapToSecp256k1Error(
+	error: unknown,
+	operation: "verify",
+): InvalidSignatureError | InvalidPublicKeyError | Secp256k1Error;
+export function mapToSecp256k1Error(
+	error: unknown,
+	operation: Secp256k1Operation,
+): Secp256k1Errors {
+	const message = getMessage(error);
+	const normalized = message.toLowerCase();
+	const isPrivateKey =
+		normalized.includes("private key") || normalized.includes("scalar");
+	const isPublicKey =
+		normalized.includes("public key") || normalized.includes("point");
+	const isSignature = normalized.includes("signature");
+	const isRecovery =
+		normalized.includes("recovery") || normalized.includes("recovery id");
+	const recoveryId = getRecoveryId(error);
+
+	switch (operation) {
+		case "sign": {
+			if (error instanceof InvalidPrivateKeyError) return error;
+			if (error instanceof Secp256k1Error) return error;
+			if (error instanceof VoltaireInvalidPrivateKeyError) {
+				return new InvalidPrivateKeyError({
+					message: error.message,
+					cause: error,
+				});
+			}
+			if (error instanceof VoltaireSecp256k1Error) {
+				return new Secp256k1Error({ message: error.message, cause: error });
+			}
+			if (isPrivateKey) {
+				return new InvalidPrivateKeyError({
+					message: `Invalid private key: ${message}`,
+					cause: error,
+				});
+			}
+			return new Secp256k1Error({
+				message: `sign failed: ${message}`,
+				cause: error,
+			});
+		}
+		case "recover": {
+			if (error instanceof InvalidSignatureError) return error;
+			if (error instanceof InvalidRecoveryIdError) return error;
+			if (error instanceof Secp256k1Error) return error;
+			if (error instanceof VoltaireInvalidSignatureError) {
+				return new InvalidSignatureError({
+					message: error.message,
+					cause: error,
+				});
+			}
+			if (error instanceof VoltaireSecp256k1Error) {
+				return new Secp256k1Error({ message: error.message, cause: error });
+			}
+			if (isRecovery) {
+				return new InvalidRecoveryIdError({
+					message: `Invalid recovery ID: ${message}`,
+					recoveryId: recoveryId ?? -1,
+					cause: error,
+				});
+			}
+			if (isSignature) {
+				return new InvalidSignatureError({
+					message: `Invalid signature: ${message}`,
+					cause: error,
+				});
+			}
+			return new Secp256k1Error({
+				message: `recover failed: ${message}`,
+				cause: error,
+			});
+		}
+		case "verify": {
+			if (error instanceof InvalidSignatureError) return error;
+			if (error instanceof InvalidPublicKeyError) return error;
+			if (error instanceof Secp256k1Error) return error;
+			if (error instanceof VoltaireInvalidSignatureError) {
+				return new InvalidSignatureError({
+					message: error.message,
+					cause: error,
+				});
+			}
+			if (error instanceof VoltaireInvalidPublicKeyError) {
+				return new InvalidPublicKeyError({
+					message: error.message,
+					cause: error,
+				});
+			}
+			if (error instanceof VoltaireSecp256k1Error) {
+				return new Secp256k1Error({ message: error.message, cause: error });
+			}
+			if (isPublicKey) {
+				return new InvalidPublicKeyError({
+					message: `Invalid public key: ${message}`,
+					cause: error,
+				});
+			}
+			if (isSignature) {
+				return new InvalidSignatureError({
+					message: `Invalid signature: ${message}`,
+					cause: error,
+				});
+			}
+			return new Secp256k1Error({
+				message: `verify failed: ${message}`,
+				cause: error,
+			});
+		}
+	}
+}

package/src/crypto/Secp256k1/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Secp256k1 elliptic curve cryptography module for Effect.
+ *
+ * @description
+ * This module provides the secp256k1 elliptic curve cryptographic operations
+ * wrapped in Effect for type-safe, composable digital signature workflows.
+ *
+ * Secp256k1 is the standard Ethereum curve used for:
+ * - Transaction signing and verification
+ * - Message signing (personal_sign, EIP-712)
+ * - Public key recovery from signatures
+ * - Account/address derivation
+ *
+ * The module exports:
+ * - {@link sign} - Sign a message hash with a private key
+ * - {@link recover} - Recover public key from signature
+ * - {@link verify} - Verify signature against public key
+ * - {@link Secp256k1Service} - Effect service for dependency injection
+ * - {@link Secp256k1Live} - Production implementation
+ * - {@link Secp256k1Test} - Test implementation with mock values
+ *
+ * @example Signing a message
+ * ```typescript
+ * import { sign, Secp256k1Live } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const signature = await Effect.runPromise(sign(messageHash, privateKey))
+ * ```
+ *
+ * @example Full sign-verify workflow using service
+ * ```typescript
+ * import { Secp256k1Service, Secp256k1Live } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const secp = yield* Secp256k1Service
+ *   const sig = yield* secp.sign(messageHash, privateKey)
+ *   const pubKey = yield* secp.recover(sig, messageHash)
+ *   return yield* secp.verify(sig, messageHash, pubKey)
+ * }).pipe(Effect.provide(Secp256k1Live))
+ * ```
+ *
+ * @module Secp256k1
+ * @since 0.0.1
+ */
+
+export {
+	InvalidPrivateKeyError,
+	InvalidPublicKeyError,
+	InvalidRecoveryIdError,
+	InvalidSignatureError,
+	mapToSecp256k1Error,
+	Secp256k1Error,
+	type Secp256k1Errors,
+} from "./errors.js";
+export { recover } from "./recover.js";
+export { Secp256k1Live } from "./Secp256k1Live.js";
+export {
+	Secp256k1Service,
+	type Secp256k1ServiceShape,
+	type SignOptions,
+} from "./Secp256k1Service.js";
+export { Secp256k1Test } from "./Secp256k1Test.js";
+export { sign } from "./sign.js";
+export { verify } from "./verify.js";

package/src/crypto/Secp256k1/recover.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Secp256k1 public key recovery function for Effect-based applications.
+ * Provides a functional Effect wrapper around secp256k1 ECDSA public key recovery.
+ *
+ * @module Secp256k1/recover
+ * @since 0.0.1
+ */
+
+import type { HashType } from "@tevm/voltaire/Hash";
+import type {
+	Secp256k1PublicKeyType,
+	Secp256k1SignatureType,
+} from "@tevm/voltaire/Secp256k1";
+import * as Secp256k1 from "@tevm/voltaire/Secp256k1";
+import * as Effect from "effect/Effect";
+import type {
+	InvalidRecoveryIdError,
+	InvalidSignatureError,
+	Secp256k1Error,
+} from "./errors.js";
+import { mapToSecp256k1Error } from "./errors.js";
+
+/**
+ * Recovers the public key from a secp256k1 signature and message hash.
+ *
+ * @description
+ * Uses the recovery ID (v value) embedded in the 65-byte signature to
+ * mathematically recover the original signer's public key. This is the
+ * inverse operation of signing and is essential for Ethereum's ecrecover.
+ *
+ * The recovered public key is the 65-byte uncompressed format:
+ * - Prefix byte (0x04)
+ * - X coordinate (32 bytes)
+ * - Y coordinate (32 bytes)
+ *
+ * This function is used internally by ecrecover and is useful for:
+ * - Verifying transaction signatures
+ * - Recovering signer addresses from signed messages
+ * - Implementing EIP-191 and EIP-712 verification
+ *
+ * @param {Secp256k1SignatureType} signature - The 65-byte recoverable signature
+ *   containing r (32 bytes), s (32 bytes), and v (1 byte recovery ID).
+ * @param {HashType} messageHash - The 32-byte message hash that was signed.
+ *
+ * @returns {Effect.Effect<Secp256k1PublicKeyType, InvalidSignatureError | InvalidRecoveryIdError | Secp256k1Error>}
+ *   An Effect that:
+ *   - Succeeds with a 65-byte uncompressed public key (branded Uint8Array)
+ *   - Fails with InvalidSignatureError if recovery fails
+ *   - Fails with InvalidRecoveryIdError if the recovery ID is invalid
+ *   - Fails with Secp256k1Error for other cryptographic failures
+ *
+ * @throws {InvalidSignatureError} When the signature is malformed.
+ * @throws {InvalidRecoveryIdError} When the recovery ID is invalid.
+ * @throws {Secp256k1Error} When recovery fails for cryptographic reasons.
+ *
+ * @example Basic recovery
+ * ```typescript
+ * import { recover } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const publicKey = await Effect.runPromise(recover(signature, messageHash))
+ * console.log(publicKey.length) // 65 (uncompressed)
+ * ```
+ *
+ * @example Deriving an Ethereum address from recovered key
+ * ```typescript
+ * import { recover } from 'voltaire-effect/crypto/Secp256k1'
+ * import { hash as keccak } from 'voltaire-effect/crypto/Keccak256'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const pubKey = yield* recover(signature, messageHash)
+ *   // Remove 0x04 prefix, hash, take last 20 bytes
+ *   const pubKeyHash = yield* keccak(pubKey.slice(1))
+ *   return pubKeyHash.slice(-20) // The address
+ * })
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * import { recover } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = recover(signature, messageHash).pipe(
+ *   Effect.catchTag('InvalidSignatureError', (e) =>
+ *     Effect.fail(new Error(`Invalid signature: ${e.message}`))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link sign} - Sign a message hash
+ * @see {@link verify} - Verify signature without recovery
+ * @see {@link Secp256k1Service} - Service interface for dependency injection
+ * @since 0.0.1
+ */
+export const recover = (
+	signature: Secp256k1SignatureType,
+	messageHash: HashType,
+): Effect.Effect<
+	Secp256k1PublicKeyType,
+	InvalidSignatureError | InvalidRecoveryIdError | Secp256k1Error
+> =>
+	Effect.try({
+		try: () => Secp256k1.recoverPublicKey(signature, messageHash),
+		catch: (e) => mapToSecp256k1Error(e, "recover"),
+	});