voltaire-effect 0.2.23 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voltaire-effect",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "Effect-TS integration for Voltaire Ethereum primitives library",
   "author": "TEVM",
   "license": "MIT",
@@ -79,7 +79,7 @@
   "sideEffects": false,
   "peerDependencies": {
     "effect": "^3.12.0",
-    "@tevm/voltaire": "0.2.23"
+    "@tevm/voltaire": "0.2.24"
   },
   "dependencies": {
     "@effect/platform": "^0.77.0"

package/src/crypto/Keccak256/index.ts

@@ -41,6 +41,7 @@
  */
 
 export { hash } from "./hash.js";
+export type { Keccak256Hash } from "@tevm/voltaire";
 export {
 	KeccakLive,
 	KeccakService,

package/src/index.ts

@@ -70,8 +70,8 @@ export * as SHA256 from "./crypto/SHA256/index.js";
 export * as X25519 from "./crypto/X25519/index.js";
 // JSON-RPC module
 export * as JsonRpc from "./jsonrpc/index.js";
-// Abi temporarily disabled - requires @tevm/voltaire subpath exports
-// export * as Abi from "./primitives/Abi/index.js";
+// ABI encoding/decoding
+export * as Abi from "./primitives/Abi/index.js";
 export * as AccessList from "./primitives/AccessList/index.js";
 export * as AccountState from "./primitives/AccountState/index.js";
 export * as Address from "./primitives/Address/index.js";

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

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as S from "effect/Schema";
+import { fromArray } from "./AbiSchema.js";
+import { decode } from "./decode.js";
+
+const erc20Abi = S.decodeUnknownSync(fromArray)([
+	{
+		type: "function",
+		name: "balanceOf",
+		stateMutability: "view",
+		inputs: [{ name: "account", type: "address" }],
+		outputs: [{ type: "uint256" }],
+	},
+]);
+
+describe("decode", () => {
+	describe("success cases", () => {
+		it.effect("decodes balanceOf result", () =>
+			Effect.gen(function* () {
+				const encoded = new Uint8Array(32);
+				encoded[31] = 100;
+				const result = yield* decode(erc20Abi, "balanceOf", encoded);
+				expect(result).toBeInstanceOf(Array);
+			}),
+		);
+	});
+
+	describe("error cases", () => {
+		it("fails for unknown function", async () => {
+			const exit = await Effect.runPromiseExit(
+				decode(erc20Abi, "unknownFunction", new Uint8Array(32)),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+});

package/src/primitives/Abi/decode.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Decodes function return values from ABI by function name.
+ * Provides Effect-based wrapper around the branded ABI decode method.
+ *
+ * @module Abi/decode
+ * @since 0.0.1
+ */
+
+import {
+	type Abi,
+	AbiDecodingError as AbiDecodingErrorClass,
+	type AbiDecodingError,
+	type AbiItemNotFoundError,
+	type ItemType,
+} from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+type AbiInput = readonly ItemType[];
+
+const toAbi = (input: AbiInput): Abi => input as unknown as Abi;
+
+type DecodeErrorType = AbiItemNotFoundError | AbiDecodingError;
+
+const isAbiError = (e: unknown): e is DecodeErrorType =>
+	e !== null &&
+	typeof e === "object" &&
+	"name" in e &&
+	(e.name === "AbiItemNotFoundError" || e.name === "AbiDecodingError");
+
+/**
+ * Decodes function return values from ABI by function name.
+ *
+ * @description
+ * Decodes the return data from a contract call using the function's output types.
+ *
+ * @param {AbiInput} abi - The contract ABI.
+ * @param {string} functionName - The function name whose outputs to decode.
+ * @param {Uint8Array} data - The encoded return data.
+ * @returns {Effect.Effect<readonly unknown[], AbiItemNotFoundError | AbiDecodingError>}
+ *   Effect yielding decoded return values.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { decode } from 'voltaire-effect/primitives/Abi'
+ *
+ * const result = await Effect.runPromise(
+ *   decode(abi, 'balanceOf', returnData)
+ * )
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const decode = (
+	abi: AbiInput,
+	functionName: string,
+	data: Uint8Array,
+): Effect.Effect<readonly unknown[], AbiItemNotFoundError | AbiDecodingError> =>
+	Effect.try({
+		try: () => toAbi(abi).decode(functionName, data),
+		catch: (e) =>
+			isAbiError(e)
+				? e
+				: new AbiDecodingErrorClass("Failed to decode function result", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});

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

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as S from "effect/Schema";
+import { fromArray } from "./AbiSchema.js";
+import { decodeData } from "./decodeData.js";
+
+const erc20Abi = S.decodeUnknownSync(fromArray)([
+	{
+		type: "function",
+		name: "transfer",
+		stateMutability: "nonpayable",
+		inputs: [
+			{ name: "to", type: "address" },
+			{ name: "amount", type: "uint256" },
+		],
+		outputs: [{ type: "bool" }],
+	},
+]);
+
+describe("decodeData", () => {
+	describe("error cases", () => {
+		it("fails for data too short", async () => {
+			const exit = await Effect.runPromiseExit(
+				decodeData(erc20Abi, new Uint8Array(2)),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails for unknown selector", async () => {
+			const exit = await Effect.runPromiseExit(
+				decodeData(erc20Abi, new Uint8Array(68)),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+});

package/src/primitives/Abi/decodeData.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Decodes function call data and identifies the function.
+ * Provides Effect-based wrapper around the branded ABI decodeData method.
+ *
+ * @module Abi/decodeData
+ * @since 0.0.1
+ */
+
+import {
+	type Abi,
+	AbiDecodingError as AbiDecodingErrorClass,
+	type AbiDecodingError,
+	type AbiInvalidSelectorError,
+	type AbiItemNotFoundError,
+	type ItemType,
+} from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+type AbiInput = readonly ItemType[];
+
+const toAbi = (input: AbiInput): Abi => input as unknown as Abi;
+
+type DecodeDataErrorType =
+	| AbiItemNotFoundError
+	| AbiInvalidSelectorError
+	| AbiDecodingError;
+
+const isAbiError = (e: unknown): e is DecodeDataErrorType =>
+	e !== null &&
+	typeof e === "object" &&
+	"name" in e &&
+	(e.name === "AbiItemNotFoundError" ||
+		e.name === "AbiInvalidSelectorError" ||
+		e.name === "AbiDecodingError");
+
+/**
+ * Decodes function call data and identifies the function.
+ *
+ * @description
+ * Parses encoded calldata to extract the function name and decoded arguments.
+ * The data must start with a 4-byte function selector.
+ *
+ * @param {AbiInput} abi - The contract ABI.
+ * @param {Uint8Array} data - The encoded function call data.
+ * @returns {Effect.Effect<{ functionName: string; args: readonly unknown[] }, AbiItemNotFoundError | AbiInvalidSelectorError | AbiDecodingError>}
+ *   Effect yielding the function name and decoded arguments.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { decodeData } from 'voltaire-effect/primitives/Abi'
+ *
+ * const decoded = await Effect.runPromise(
+ *   decodeData(abi, calldata)
+ * )
+ * console.log(decoded.functionName) // 'transfer'
+ * console.log(decoded.args) // ['0x...', 100n]
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const decodeData = (
+	abi: AbiInput,
+	data: Uint8Array,
+): Effect.Effect<
+	{ functionName: string; args: readonly unknown[] },
+	AbiItemNotFoundError | AbiInvalidSelectorError | AbiDecodingError
+> =>
+	Effect.try({
+		try: () => toAbi(abi).decodeData(data),
+		catch: (e) =>
+			isAbiError(e)
+				? e
+				: new AbiDecodingErrorClass("Failed to decode function data", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});

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

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as S from "effect/Schema";
+import { fromArray } from "./AbiSchema.js";
+import { decodeLog } from "./decodeLog.js";
+
+const erc20Abi = S.decodeUnknownSync(fromArray)([
+	{
+		type: "event",
+		name: "Transfer",
+		inputs: [
+			{ name: "from", type: "address", indexed: true },
+			{ name: "to", type: "address", indexed: true },
+			{ name: "value", type: "uint256", indexed: false },
+		],
+	},
+]);
+
+describe("decodeLog", () => {
+	describe("error cases", () => {
+		it("fails for unknown event", async () => {
+			const exit = await Effect.runPromiseExit(
+				decodeLog(erc20Abi, {
+					data: new Uint8Array(32),
+					topics: [new Uint8Array(32)],
+				}),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+});

package/src/primitives/Abi/decodeLog.ts

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Decodes event log data using ABI.
+ * Provides Effect-based wrapper for parsing log entries.
+ *
+ * @module Abi/decodeLog
+ * @since 0.0.1
+ */
+
+import {
+	type Abi,
+	AbiDecodingError as AbiDecodingErrorClass,
+	type AbiDecodingError,
+	type AbiItemNotFoundError,
+	type ItemType,
+	decodeLog as _decodeLog,
+} from "@tevm/voltaire/Abi";
+import type { HexType } from "@tevm/voltaire/Hex";
+import * as Effect from "effect/Effect";
+
+type AbiInput = readonly ItemType[];
+
+const toAbi = (input: AbiInput): Abi => input as unknown as Abi;
+
+type DecodeLogErrorType = AbiItemNotFoundError | AbiDecodingError;
+
+const isAbiError = (e: unknown): e is DecodeLogErrorType =>
+	e !== null &&
+	typeof e === "object" &&
+	"name" in e &&
+	(e.name === "AbiItemNotFoundError" || e.name === "AbiDecodingError");
+
+/**
+ * Log input structure.
+ */
+export interface LogInput {
+	data: HexType | Uint8Array;
+	topics: readonly (HexType | Uint8Array)[];
+}
+
+/**
+ * Decodes event log data using ABI.
+ *
+ * @description
+ * Parses a log entry to extract the event name and decoded parameters.
+ * Supports both regular events (matched by topic0) and anonymous events.
+ *
+ * @param {AbiInput} abi - The contract ABI.
+ * @param {LogInput} log - The log object with data and topics.
+ * @returns {Effect.Effect<{ event: string; params: Record<string, unknown> }, AbiItemNotFoundError | AbiDecodingError>}
+ *   Effect yielding the event name and decoded parameters.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { decodeLog } from 'voltaire-effect/primitives/Abi'
+ *
+ * const decoded = await Effect.runPromise(
+ *   decodeLog(abi, { data: '0x...', topics: ['0x...', ...] })
+ * )
+ * console.log(decoded.event) // 'Transfer'
+ * console.log(decoded.params) // { from: '0x...', to: '0x...', value: 100n }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const decodeLog = (
+	abi: AbiInput,
+	log: LogInput,
+): Effect.Effect<
+	{ event: string; params: Record<string, unknown> },
+	AbiItemNotFoundError | AbiDecodingError
+> =>
+	Effect.try({
+		try: () => _decodeLog(toAbi(abi), log),
+		catch: (e) =>
+			isAbiError(e)
+				? e
+				: new AbiDecodingErrorClass("Failed to decode log", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});

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

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Address, Bytes, Selector } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { decodeWrappedError } from "./decodeWrappedError.js";
+import { encodeWrappedError } from "./encodeWrappedError.js";
+
+describe("decodeWrappedError", () => {
+	describe("success cases", () => {
+		it.effect("decodes encoded wrapped error", () =>
+			Effect.gen(function* () {
+				const original = {
+					target: Address.from("0x742d35Cc6634C0532925a3b844Bc9e7595f251e3"),
+					selector: Selector.fromHex("0xa9059cbb"),
+					reason: Bytes.from(new Uint8Array([1, 2, 3])),
+					details: Bytes.from(new Uint8Array([4, 5, 6])),
+				};
+				const encoded = yield* encodeWrappedError(original);
+				const decoded = yield* decodeWrappedError(encoded);
+				expect(decoded.target).toBeDefined();
+				expect(decoded.selector).toBeDefined();
+			}),
+		);
+	});
+
+	describe("error cases", () => {
+		it("fails for data too short", async () => {
+			const exit = await Effect.runPromiseExit(
+				decodeWrappedError(new Uint8Array(2)),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails for invalid selector", async () => {
+			const exit = await Effect.runPromiseExit(
+				decodeWrappedError(new Uint8Array(100)),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+});

package/src/primitives/Abi/decodeWrappedError.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Decodes ERC-7751 wrapped error data.
+ * Provides Effect-based wrapper for wrapped error decoding.
+ *
+ * @module Abi/decodeWrappedError
+ * @since 0.0.1
+ */
+
+import {
+	AbiDecodingError as AbiDecodingErrorClass,
+	type AbiDecodingError,
+	type AbiInvalidSelectorError,
+	type WrappedErrorType,
+	decodeWrappedError as _decodeWrappedError,
+} from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+/**
+ * Decoded wrapped error structure (ERC-7751).
+ */
+export type WrappedErrorResult = WrappedErrorType;
+
+type DecodeWrappedErrorType = AbiDecodingError | AbiInvalidSelectorError;
+
+const isAbiError = (e: unknown): e is DecodeWrappedErrorType =>
+	e !== null &&
+	typeof e === "object" &&
+	"name" in e &&
+	(e.name === "AbiDecodingError" || e.name === "AbiInvalidSelectorError");
+
+/**
+ * Decodes ERC-7751 wrapped error data.
+ *
+ * @description
+ * Decodes a WrappedError from encoded bytes following the ERC-7751 specification.
+ * Expects data to start with the WrappedError selector (0x90bfb865).
+ *
+ * @param {Uint8Array} data - Encoded error data (selector + ABI-encoded params).
+ * @returns {Effect.Effect<WrappedErrorResult, AbiDecodingError | AbiInvalidSelectorError>}
+ *   Effect yielding decoded wrapped error.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { decodeWrappedError } from 'voltaire-effect/primitives/Abi'
+ *
+ * const decoded = await Effect.runPromise(
+ *   decodeWrappedError(errorData)
+ * )
+ * console.log(decoded.target) // Address of failing contract
+ * console.log(decoded.selector) // Function selector
+ * ```
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-7751
+ * @since 0.0.1
+ */
+export const decodeWrappedError = (
+	data: Uint8Array,
+): Effect.Effect<WrappedErrorResult, AbiDecodingError | AbiInvalidSelectorError> =>
+	Effect.try({
+		try: () => _decodeWrappedError(data) as WrappedErrorResult,
+		catch: (e) =>
+			isAbiError(e)
+				? e
+				: new AbiDecodingErrorClass("Failed to decode wrapped error", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as S from "effect/Schema";
+import { fromArray } from "./AbiSchema.js";
+import { encode } from "./encode.js";
+
+const erc20Abi = S.decodeUnknownSync(fromArray)([
+	{
+		type: "function",
+		name: "transfer",
+		stateMutability: "nonpayable",
+		inputs: [
+			{ name: "to", type: "address" },
+			{ name: "amount", type: "uint256" },
+		],
+		outputs: [{ type: "bool" }],
+	},
+]);
+
+describe("encode", () => {
+	describe("success cases", () => {
+		it.effect("encodes transfer function", () =>
+			Effect.gen(function* () {
+				const calldata = yield* encode(erc20Abi, "transfer", [
+					"0x742d35Cc6634C0532925a3b844Bc9e7595f251e3",
+					1000000000000000000n,
+				]);
+				expect(calldata).toBeInstanceOf(Uint8Array);
+				expect(calldata.length).toBeGreaterThan(4);
+			}),
+		);
+	});
+
+	describe("error cases", () => {
+		it("fails for unknown function", async () => {
+			const exit = await Effect.runPromiseExit(
+				encode(erc20Abi, "unknownFunction", []),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+});

package/src/primitives/Abi/encode.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Encodes function call data from ABI by function name.
+ * Provides Effect-based wrapper around the branded ABI encode method.
+ *
+ * @module Abi/encode
+ * @since 0.0.1
+ */
+
+import {
+	type Abi,
+	AbiEncodingError as AbiEncodingErrorClass,
+	type AbiEncodingError,
+	type AbiItemNotFoundError,
+	type ItemType,
+} from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+type AbiInput = readonly ItemType[];
+
+const toAbi = (input: AbiInput): Abi => input as unknown as Abi;
+
+type EncodeErrorType = AbiItemNotFoundError | AbiEncodingError;
+
+const isAbiError = (e: unknown): e is EncodeErrorType =>
+	e !== null &&
+	typeof e === "object" &&
+	"name" in e &&
+	(e.name === "AbiItemNotFoundError" || e.name === "AbiEncodingError");
+
+/**
+ * Encodes function call data from ABI by function name.
+ *
+ * @description
+ * Creates encoded calldata for invoking a contract function.
+ *
+ * @param {AbiInput} abi - The contract ABI.
+ * @param {string} functionName - The function name to encode.
+ * @param {readonly unknown[]} args - The function arguments.
+ * @returns {Effect.Effect<Uint8Array, AbiItemNotFoundError | AbiEncodingError>}
+ *   Effect yielding encoded calldata as bytes.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { encode } from 'voltaire-effect/primitives/Abi'
+ *
+ * const calldata = await Effect.runPromise(
+ *   encode(abi, 'transfer', [to, amount])
+ * )
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const encode = (
+	abi: AbiInput,
+	functionName: string,
+	args: readonly unknown[],
+): Effect.Effect<Uint8Array, AbiItemNotFoundError | AbiEncodingError> =>
+	Effect.try({
+		try: () => toAbi(abi).encode(functionName, [...args]),
+		catch: (e) =>
+			isAbiError(e)
+				? e
+				: new AbiEncodingErrorClass("Failed to encode function", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});

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

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { encodePacked } from "./encodePacked.js";
+
+describe("encodePacked", () => {
+	describe("success cases", () => {
+		it.effect("encodes address and uint256", () =>
+			Effect.gen(function* () {
+				const encoded = yield* encodePacked(
+					["address", "uint256"],
+					["0x742d35Cc6634C0532925a3b844Bc9e7595f251e3", 100n],
+				);
+				expect(typeof encoded).toBe("string");
+				expect(encoded.startsWith("0x")).toBe(true);
+			}),
+		);
+
+		it.effect("encodes string", () =>
+			Effect.gen(function* () {
+				const encoded = yield* encodePacked(["string"], ["hello"]);
+				expect(typeof encoded).toBe("string");
+			}),
+		);
+	});
+
+	describe("error cases", () => {
+		it("fails for type/value mismatch", async () => {
+			const exit = await Effect.runPromiseExit(
+				encodePacked(["address", "uint256"], ["0x123"]),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+});