voltaire-effect 0.3.0 → 1.0.1

package/src/jsonrpc/Txpool.ts

@@ -1,16 +1,21 @@
-import { nextId } from "./IdCounter.js";
+import * as Effect from "effect/Effect";
+import { IdCounterService } from "./IdCounter.js";
 import type { JsonRpcRequestType } from "./Request.js";
 
 function makeRequest(
 	method: string,
 	params: unknown[] = [],
-): JsonRpcRequestType {
-	return {
-		jsonrpc: "2.0",
-		method,
-		params,
-		id: nextId(),
-	};
+): Effect.Effect<JsonRpcRequestType, never, IdCounterService> {
+	return Effect.gen(function* () {
+		const counter = yield* IdCounterService;
+		const id = yield* counter.next();
+		return {
+			jsonrpc: "2.0",
+			method,
+			params,
+			id,
+		};
+	});
 }
 
 export const StatusRequest = () => makeRequest("txpool_status");

package/src/jsonrpc/Wallet.ts

@@ -1,16 +1,21 @@
-import { nextId } from "./IdCounter.js";
+import * as Effect from "effect/Effect";
+import { IdCounterService } from "./IdCounter.js";
 import type { JsonRpcRequestType } from "./Request.js";
 
 function makeRequest(
 	method: string,
 	params: unknown[] = [],
-): JsonRpcRequestType {
-	return {
-		jsonrpc: "2.0",
-		method,
-		params,
-		id: nextId(),
-	};
+): Effect.Effect<JsonRpcRequestType, never, IdCounterService> {
+	return Effect.gen(function* () {
+		const counter = yield* IdCounterService;
+		const id = yield* counter.next();
+		return {
+			jsonrpc: "2.0",
+			method,
+			params,
+			id,
+		};
+	});
 }
 
 export const SwitchEthereumChainRequest = (chainId: string) =>

package/src/jsonrpc/Web3.ts

@@ -1,16 +1,21 @@
-import { nextId } from "./IdCounter.js";
+import * as Effect from "effect/Effect";
+import { IdCounterService } from "./IdCounter.js";
 import type { JsonRpcRequestType } from "./Request.js";
 
 function makeRequest(
 	method: string,
 	params: unknown[] = [],
-): JsonRpcRequestType {
-	return {
-		jsonrpc: "2.0",
-		method,
-		params,
-		id: nextId(),
-	};
+): Effect.Effect<JsonRpcRequestType, never, IdCounterService> {
+	return Effect.gen(function* () {
+		const counter = yield* IdCounterService;
+		const id = yield* counter.next();
+		return {
+			jsonrpc: "2.0",
+			method,
+			params,
+			id,
+		};
+	});
 }
 
 export const ClientVersionRequest = () => makeRequest("web3_clientVersion");

package/src/jsonrpc/index.ts

@@ -85,7 +85,7 @@ export {
 	UserRejectedRequestError,
 } from "./errors.js";
 export * as Hardhat from "./Hardhat.js";
-export { nextId, resetId } from "./IdCounter.js";
+export { IdCounterService, IdCounterLive } from "./IdCounter.js";
 export * as Net from "./Net.js";
 export {
 	from as requestFrom,

package/src/primitives/Abi/AbiSchema.ts

@@ -12,9 +12,8 @@ import * as S from "effect/Schema";
 
 /**
  * Type alias for Abi instances returned by the Abi factory.
- * @internal
  */
-type AbiInstance = ReturnType<typeof Abi>;
+export type AbiInstance = ReturnType<typeof Abi>;
 
 // =============================================================================
 // StateMutability Schema
@@ -444,7 +443,7 @@ const AbiInstanceGuardSchema = S.declare<AbiInstance>(
  *
  * @since 0.1.0
  */
-export const AbiSchema = AbiInstanceGuardSchema;
+export const AbiSchema: S.Schema<AbiInstance, AbiInstance> = AbiInstanceGuardSchema;
 
 /**
  * Schema that parses raw ABI arrays into Abi instances.
@@ -464,7 +463,7 @@ export const AbiSchema = AbiInstanceGuardSchema;
  *
  * @since 0.1.0
  */
-export const fromArray = S.transformOrFail(
+export const fromArray: S.Schema<AbiInstance, S.Schema.Encoded<typeof AbiSchemaInternal>> = S.transformOrFail(
 	AbiSchemaInternal,
 	AbiInstanceGuardSchema,
 	{

package/src/primitives/Abi/fromBytecode.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import * as Effect from "effect/Effect";
+import * as Data from "effect/Data";
+
+// Note: The actual fromBytecode function imports from @shazow/whatsabi which
+// requires @noble/hashes@^1, but this repo uses @noble/hashes@^2.
+// We test the error type directly here without importing the problematic module.
+
+// Duplicate the error class for testing purposes
+class AbiBytecodeError extends Data.TaggedError("AbiBytecodeError")<{
+	readonly message: string;
+	readonly bytecode?: string;
+	readonly cause?: unknown;
+}> {}
+
+describe("fromBytecode", () => {
+	describe("error typing", () => {
+		it("AbiBytecodeError has correct tag", () => {
+			const error = new AbiBytecodeError({
+				message: "test error",
+				bytecode: "0x123",
+			});
+			expect(error._tag).toBe("AbiBytecodeError");
+		});
+
+		it("can be caught with Effect.catchTag", async () => {
+			const program = Effect.fail(
+				new AbiBytecodeError({ message: "test" })
+			).pipe(
+				Effect.catchTag("AbiBytecodeError", (e) =>
+					Effect.succeed({ caught: true, message: e.message })
+				)
+			);
+
+			const result = await Effect.runPromise(program);
+			expect(result).toEqual({ caught: true, message: "test" });
+		});
+
+		it("preserves bytecode context in error", () => {
+			const error = new AbiBytecodeError({
+				message: "test error",
+				bytecode: "0x608060",
+			});
+			expect(error.bytecode).toBe("0x608060");
+		});
+	});
+});

package/src/primitives/Abi/fromBytecode.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Recovers ABI from EVM bytecode using static analysis.
+ * Uses WhatsABI to analyze bytecode and extract function/event signatures.
+ *
+ * @module Abi/fromBytecode
+ * @since 0.0.1
+ */
+
+import { abiFromBytecode as whatsabiFromBytecode } from "@shazow/whatsabi";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+
+/**
+ * Error thrown when bytecode analysis fails.
+ */
+export class AbiBytecodeError extends Data.TaggedError("AbiBytecodeError")<{
+	readonly message: string;
+	readonly bytecode?: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Recovered ABI item from bytecode analysis.
+ * Note: Names may be missing or placeholder values since they're not in bytecode.
+ */
+export type RecoveredAbiItem = {
+	readonly type: "function" | "event";
+	readonly selector?: string;
+	readonly name?: string;
+	readonly inputs?: ReadonlyArray<{ type: string; name: string }>;
+	readonly outputs?: ReadonlyArray<{ type: string; name: string }>;
+	readonly stateMutability?: "nonpayable" | "payable" | "view" | "pure";
+};
+
+/**
+ * Recovers an ABI from EVM bytecode using static analysis.
+ *
+ * @description
+ * Analyzes EVM bytecode to extract function selectors and attempt to
+ * recover function/event signatures. This is useful when source code
+ * is not available or the contract is not verified on any block explorer.
+ *
+ * Note that recovered ABIs may be incomplete:
+ * - Function/event names may be missing (only selectors available)
+ * - Parameter names are typically placeholders
+ * - Some functions may not be detected
+ *
+ * @param {string} bytecode - The EVM bytecode as hex string (with or without 0x prefix).
+ * @returns {Effect.Effect<ReadonlyArray<RecoveredAbiItem>, AbiBytecodeError>}
+ *   Effect yielding the recovered ABI items.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { fromBytecode } from 'voltaire-effect/primitives/Abi'
+ *
+ * const bytecode = '0x608060405234801561001057...'
+ * const abi = await Effect.runPromise(fromBytecode(bytecode))
+ * // => [{ type: 'function', selector: '0xa9059cbb', ... }]
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const fromBytecode = (
+	bytecode: string,
+): Effect.Effect<ReadonlyArray<RecoveredAbiItem>, AbiBytecodeError> =>
+	Effect.try({
+		try: () => {
+			if (!bytecode || bytecode === "0x" || bytecode === "0x0") {
+				return [] as ReadonlyArray<RecoveredAbiItem>;
+			}
+			const result = whatsabiFromBytecode(bytecode);
+			return result as unknown as ReadonlyArray<RecoveredAbiItem>;
+		},
+		catch: (e) =>
+			new AbiBytecodeError({
+				message: `Failed to recover ABI from bytecode: ${e instanceof Error ? e.message : String(e)}`,
+				bytecode: bytecode.slice(0, 100) + (bytecode.length > 100 ? "..." : ""),
+				cause: e,
+			}),
+	});

package/src/primitives/Abi/index.ts

@@ -77,3 +77,6 @@ export { getSelector } from "./getSelector.js";
 export { AbiParseError, parse } from "./parse.js";
 export { AbiItemParseError, parseItem } from "./parseItem.js";
 export { parseLogs, type ParsedLog, type ParseLogsInput } from "./parseLogs.js";
+
+// Bytecode analysis
+export { AbiBytecodeError, fromBytecode, type RecoveredAbiItem } from "./fromBytecode.js";

package/src/primitives/AccessList/from.ts

@@ -9,18 +9,13 @@ import {
   type BrandedAccessList,
   type Item,
 } from "@tevm/voltaire/AccessList";
-import type {
-  InvalidFormatError,
-  InvalidLengthError,
-} from "@tevm/voltaire/errors";
-
-type AccessListError = InvalidFormatError | InvalidLengthError;
+import { ValidationError } from "@tevm/voltaire/errors";
 
 /**
  * Create AccessList from array or bytes
  *
  * @param value - AccessList items or RLP bytes
- * @returns Effect yielding BrandedAccessList or failing with AccessListError
+ * @returns Effect yielding BrandedAccessList or failing with ValidationError
  * @example
  * ```typescript
  * import * as AccessList from 'voltaire-effect/primitives/AccessList'
@@ -32,8 +27,16 @@ type AccessListError = InvalidFormatError | InvalidLengthError;
  */
 export const from = (
   value: readonly Item[] | Uint8Array,
-): Effect.Effect<BrandedAccessList, AccessListError> =>
+): Effect.Effect<BrandedAccessList, ValidationError> =>
   Effect.try({
     try: () => AccessList.from(value),
-    catch: (e) => e as AccessListError,
+    catch: (error) =>
+      new ValidationError(
+        error instanceof Error ? error.message : "Invalid access list input",
+        {
+          value,
+          expected: "array of {address, storageKeys} or RLP-encoded bytes",
+          cause: error instanceof Error ? error : undefined,
+        },
+      ),
   });

package/src/primitives/Address/Checksummed.ts

@@ -7,10 +7,9 @@
  */
 
 import { Address, type AddressType } from "@tevm/voltaire/Address";
-import * as Effect from "effect/Effect";
+import { hash as keccak256 } from "@tevm/voltaire/Keccak256";
 import * as ParseResult from "effect/ParseResult";
 import * as S from "effect/Schema";
-import { KeccakService } from "../../crypto/Keccak256/index.js";
 import { AddressTypeSchema } from "./AddressSchema.js";
 
 /**
@@ -36,22 +35,19 @@ import { AddressTypeSchema } from "./AddressSchema.js";
  * S.decodeSync(Address.Checksummed)('0x742d35cc6634c0532925a3b844bc9e7595f251e3') // Error!
  * ```
  *
- * @example Encoding (requires KeccakService)
+ * @example Encoding (sync)
  * ```typescript
  * import * as Address from 'voltaire-effect/primitives/Address'
  * import * as S from 'effect/Schema'
- * import * as Effect from 'effect/Effect'
- * import { KeccakLive } from 'voltaire-effect/crypto/Keccak256'
  *
  * const addr = S.decodeSync(Address.Hex)('0x742d35cc6634c0532925a3b844bc9e7595f251e3')
- * const program = S.encode(Address.Checksummed)(addr)
- * const checksummed = await Effect.runPromise(program.pipe(Effect.provide(KeccakLive)))
+ * const checksummed = S.encodeSync(Address.Checksummed)(addr)
  * // "0x742d35Cc6634C0532925a3b844Bc9e7595f251e3"
  * ```
  *
  * @since 0.1.0
  */
-export const Checksummed: S.Schema<AddressType, string, KeccakService> =
+export const Checksummed: S.Schema<AddressType, string> =
 	S.transformOrFail(S.String, AddressTypeSchema, {
 		strict: true,
 		decode: (s, _options, ast) => {
@@ -69,25 +65,23 @@ export const Checksummed: S.Schema<AddressType, string, KeccakService> =
 				);
 			}
 		},
-		encode: (addr, _options, _ast) =>
-			Effect.gen(function* () {
-				const keccak = yield* KeccakService;
-				const hex = Address.toHex(addr).slice(2).toLowerCase();
-				const hashResult = yield* keccak.hash(new TextEncoder().encode(hex));
-				const hashHex = Array.from(hashResult)
-					.map((b) => b.toString(16).padStart(2, "0"))
-					.join("");
+		encode: (addr, _options, _ast) => {
+			const hex = Address.toHex(addr).slice(2).toLowerCase();
+			const hashResult = keccak256(new TextEncoder().encode(hex));
+			const hashHex = Array.from(hashResult as Uint8Array)
+				.map((b) => b.toString(16).padStart(2, "0"))
+				.join("");
 
-				let checksummed = "0x";
-				for (let i = 0; i < hex.length; i++) {
-					const char = hex[i];
-					if (char >= "a" && char <= "f") {
-						const hashNibble = Number.parseInt(hashHex[i], 16);
-						checksummed += hashNibble >= 8 ? char.toUpperCase() : char;
-					} else {
-						checksummed += char;
-					}
+			let checksummed = "0x";
+			for (let i = 0; i < hex.length; i++) {
+				const char = hex[i];
+				if (char >= "a" && char <= "f") {
+					const hashNibble = Number.parseInt(hashHex[i], 16);
+					checksummed += hashNibble >= 8 ? char.toUpperCase() : char;
+				} else {
+					checksummed += char;
 				}
-				return checksummed;
-			}),
+			}
+			return ParseResult.succeed(checksummed);
+		},
 	}).annotations({ identifier: "Address.Checksummed" });

package/src/primitives/Address/from.ts

@@ -5,24 +5,13 @@
  */
 import { Effect } from "effect";
 import { Address, type AddressType } from "@tevm/voltaire/Address";
-import type {
-  InvalidAddressError,
-  InvalidHexFormatError,
-  InvalidAddressLengthError,
-  InvalidValueError,
-} from "@tevm/voltaire/Address";
-
-type AddressError =
-  | InvalidAddressError
-  | InvalidHexFormatError
-  | InvalidAddressLengthError
-  | InvalidValueError;
+import { ValidationError } from "@tevm/voltaire/errors";
 
 /**
  * Create Address from hex string, bytes, or number
  *
  * @param value - Hex string, Uint8Array, number, or bigint
- * @returns Effect yielding AddressType or failing with AddressError
+ * @returns Effect yielding AddressType or failing with ValidationError
  * @example
  * ```typescript
  * import * as Address from 'voltaire-effect/primitives/Address'
@@ -34,8 +23,16 @@ type AddressError =
  */
 export const from = (
   value: string | Uint8Array | number | bigint,
-): Effect.Effect<AddressType, AddressError> =>
+): Effect.Effect<AddressType, ValidationError> =>
   Effect.try({
     try: () => Address.from(value),
-    catch: (e) => e as AddressError,
+    catch: (error) =>
+      new ValidationError(
+        error instanceof Error ? error.message : "Invalid address input",
+        {
+          value,
+          expected: "20-byte hex string or Uint8Array",
+          cause: error instanceof Error ? error : undefined,
+        },
+      ),
   });

package/src/primitives/Address/toHex.ts

@@ -4,6 +4,7 @@
  * @since 0.1.0
  */
 import { Address, type AddressType } from "@tevm/voltaire/Address";
+import type { HexType } from "@tevm/voltaire/Hex";
 
 /**
  * Convert Address to lowercase hex string
@@ -15,4 +16,4 @@ import { Address, type AddressType } from "@tevm/voltaire/Address";
  * Address.toHex(addr) // "0x742d35cc6634c0532925a3b844bc9e7595f251e3"
  * ```
  */
-export const toHex = (addr: AddressType): string => Address.toHex(addr);
+export const toHex = (addr: AddressType): HexType => Address.toHex(addr);

package/src/primitives/Base64/from.ts

@@ -5,6 +5,7 @@
  */
 import { Effect } from "effect";
 import { Base64, type BrandedBase64, type BrandedBase64Url } from "@tevm/voltaire/Base64";
+import { ValidationError } from "@tevm/voltaire/errors";
 
 /**
  * Create validated standard Base64 string from input
@@ -18,10 +19,18 @@ import { Base64, type BrandedBase64, type BrandedBase64Url } from "@tevm/voltair
  */
 export const from = (
   value: string | Uint8Array,
-): Effect.Effect<BrandedBase64, Error> =>
+): Effect.Effect<BrandedBase64, ValidationError> =>
   Effect.try({
     try: () => Base64.from(value),
-    catch: (e) => e as Error,
+    catch: (error) =>
+      new ValidationError(
+        error instanceof Error ? error.message : "Invalid Base64 input",
+        {
+          value,
+          expected: "valid Base64 string or Uint8Array",
+          cause: error instanceof Error ? error : undefined,
+        },
+      ),
   });
 
 /**
@@ -32,8 +41,16 @@ export const from = (
  */
 export const fromUrlSafe = (
   value: string | Uint8Array,
-): Effect.Effect<BrandedBase64Url, Error> =>
+): Effect.Effect<BrandedBase64Url, ValidationError> =>
   Effect.try({
     try: () => Base64.fromUrlSafe(value),
-    catch: (e) => e as Error,
+    catch: (error) =>
+      new ValidationError(
+        error instanceof Error ? error.message : "Invalid URL-safe Base64 input",
+        {
+          value,
+          expected: "valid URL-safe Base64 string or Uint8Array",
+          cause: error instanceof Error ? error : undefined,
+        },
+      ),
   });

package/src/primitives/Blob/from.ts

@@ -5,7 +5,7 @@
  */
 import { BrandedBlob as BlobNamespace } from "@tevm/voltaire";
 import { Effect } from "effect";
-import type { InvalidBlobDataSizeError } from "@tevm/voltaire/Blob";
+import { ValidationError } from "@tevm/voltaire/errors";
 
 type BrandedBlob = BlobNamespace.BrandedBlob;
 
@@ -15,7 +15,7 @@ type BrandedBlob = BlobNamespace.BrandedBlob;
  * If input is 131072 bytes, returns as-is. Otherwise encodes with padding.
  *
  * @param value - Uint8Array (either 131072 bytes blob or data to encode)
- * @returns Effect yielding BrandedBlob or failing with InvalidBlobDataSizeError
+ * @returns Effect yielding BrandedBlob or failing with ValidationError
  * @example
  * ```typescript
  * import * as Blob from 'voltaire-effect/primitives/Blob'
@@ -31,8 +31,16 @@ type BrandedBlob = BlobNamespace.BrandedBlob;
  */
 export const from = (
 	value: Uint8Array,
-): Effect.Effect<BrandedBlob, InvalidBlobDataSizeError> =>
+): Effect.Effect<BrandedBlob, ValidationError> =>
 	Effect.try({
 		try: () => BlobNamespace.from(value),
-		catch: (e) => e as InvalidBlobDataSizeError,
+		catch: (error) =>
+			new ValidationError(
+				error instanceof Error ? error.message : "Invalid blob input",
+				{
+					value,
+					expected: "Uint8Array (131072 bytes or data to encode)",
+					cause: error instanceof Error ? error : undefined,
+				},
+			),
 	});

package/src/primitives/BlockHash/index.ts

@@ -47,8 +47,8 @@ export { Hex } from "./Hex.js";
 // Re-export pure functions from voltaire
 import { BlockHash } from "@tevm/voltaire";
 
-export const equals = BlockHash.equals;
-export const toHex = BlockHash.toHex;
+export const equals: (a: BlockHashType, b: BlockHashType) => boolean = BlockHash.equals;
+export const toHex: (hash: BlockHashType) => string = BlockHash.toHex;
 
 // Type export
 import type { BlockHash as _BlockHash } from "@tevm/voltaire";

package/src/primitives/BlockNumber/index.ts

@@ -51,9 +51,9 @@ export { Number } from "./Number.js";
 // Re-export pure functions from voltaire
 import { BlockNumber } from "@tevm/voltaire";
 
-export const equals = BlockNumber.equals;
-export const toBigInt = BlockNumber.toBigInt;
-export const toNumber = BlockNumber.toNumber;
+export const equals: (a: BlockNumberType, b: BlockNumberType) => boolean = BlockNumber.equals;
+export const toBigInt: (blockNumber: BlockNumberType) => bigint = BlockNumber.toBigInt;
+export const toNumber: (blockNumber: BlockNumberType) => number = BlockNumber.toNumber;
 
 // Type export
 import type { BlockNumber as _BlockNumber } from "@tevm/voltaire";

package/src/primitives/Bytecode/from.ts

@@ -5,12 +5,21 @@
  */
 import { Effect } from "effect";
 import { from as _from } from "@tevm/voltaire/Bytecode";
+import { ValidationError } from "@tevm/voltaire/errors";
 import type { BrandedBytecode } from "./types.js";
 
 export const from = (
 	value: string | Uint8Array,
-): Effect.Effect<BrandedBytecode, Error> =>
+): Effect.Effect<BrandedBytecode, ValidationError> =>
 	Effect.try({
 		try: () => _from(value),
-		catch: (e) => e as Error,
+		catch: (error) =>
+			new ValidationError(
+				error instanceof Error ? error.message : "Invalid bytecode input",
+				{
+					value,
+					expected: "hex string or Uint8Array",
+					cause: error instanceof Error ? error : undefined,
+				},
+			),
 	});

package/src/primitives/ContractSignature/verifySignature.ts

@@ -12,6 +12,7 @@ import {
 	type BrandedAddress,
 	type BrandedHash,
 	ContractSignature,
+	Hex,
 	Secp256k1,
 } from "@tevm/voltaire";
 import * as Data from "effect/Data";
@@ -247,11 +248,8 @@ export const verifySignature = (
 		});
 
 		// Build EIP-1271 isValidSignature call data
-		const hashHex =
-			hash instanceof Uint8Array
-				? `0x${Buffer.from(hash).toString("hex")}`
-				: `0x${Buffer.from(hash).toString("hex")}`;
-		const sigHex = `0x${Buffer.from(signatureBytes).toString("hex")}`;
+		const hashHex = Hex(hash);
+		const sigHex = Hex(signatureBytes);
 
 		// isValidSignature(bytes32 hash, bytes signature) selector: 0x1626ba7e
 		// ABI encode: selector + hash (32 bytes) + offset to signature (32) + signature length (32) + signature data

package/src/primitives/Ens/from.ts

@@ -5,28 +5,29 @@
  */
 import { Effect } from "effect";
 import { Ens } from "@tevm/voltaire";
+import { ValidationError } from "@tevm/voltaire/errors";
 import type { EnsType } from "./String.js";
 
-type EnsError =
-  | Ens.DisallowedCharacterError
-  | Ens.EmptyLabelError
-  | Ens.IllegalMixtureError
-  | Ens.InvalidLabelExtensionError
-  | Ens.InvalidUtf8Error
-  | Ens.WholeConfusableError;
-
 /**
  * Create ENS name from string
  *
  * @param name - ENS name string
- * @returns Effect yielding EnsType or failing with EnsError
+ * @returns Effect yielding EnsType or failing with ValidationError
  * @example
  * ```typescript
  * const ens = await Effect.runPromise(Ens.from('vitalik.eth'))
  * ```
  */
-export const from = (name: string): Effect.Effect<EnsType, EnsError> =>
+export const from = (name: string): Effect.Effect<EnsType, ValidationError> =>
   Effect.try({
     try: () => Ens.from(name),
-    catch: (e) => e as EnsError,
+    catch: (error) =>
+      new ValidationError(
+        error instanceof Error ? error.message : "Invalid ENS name",
+        {
+          value: name,
+          expected: "valid ENS name (e.g., vitalik.eth)",
+          cause: error instanceof Error ? error : undefined,
+        },
+      ),
   });