voltaire-effect 0.2.23 → 0.2.25

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);
+		});
+	});
+});

package/src/primitives/Abi/encodePacked.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview ABI encodePacked - compact encoding without padding.
+ * Provides Effect-based wrapper for packed encoding.
+ *
+ * @module Abi/encodePacked
+ * @since 0.0.1
+ */
+
+import {
+	AbiEncodingError as AbiEncodingErrorClass,
+	type AbiEncodingError,
+	type AbiParameterMismatchError,
+	encodePacked as _encodePacked,
+} from "@tevm/voltaire/Abi";
+import type { HexType } from "@tevm/voltaire/Hex";
+import * as Effect from "effect/Effect";
+
+type EncodePackedErrorType = AbiParameterMismatchError | AbiEncodingError;
+
+const isAbiError = (e: unknown): e is EncodePackedErrorType =>
+	e !== null &&
+	typeof e === "object" &&
+	"name" in e &&
+	(e.name === "AbiParameterMismatchError" || e.name === "AbiEncodingError");
+
+/**
+ * Encodes values in packed format (no padding).
+ *
+ * @description
+ * Performs ABI encoding without padding, used for creating hashes
+ * where standard ABI encoding would waste space.
+ *
+ * @param {readonly string[]} types - Array of Solidity type strings.
+ * @param {readonly unknown[]} values - Array of values to encode.
+ * @returns {Effect.Effect<HexType, AbiParameterMismatchError | AbiEncodingError>}
+ *   Effect yielding encoded hex string.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { encodePacked } from 'voltaire-effect/primitives/Abi'
+ *
+ * const encoded = await Effect.runPromise(
+ *   encodePacked(['address', 'uint256'], [address, amount])
+ * )
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const encodePacked = (
+	types: readonly string[],
+	values: readonly unknown[],
+): Effect.Effect<HexType, AbiParameterMismatchError | AbiEncodingError> =>
+	Effect.try({
+		try: () => _encodePacked(types, values),
+		catch: (e) =>
+			isAbiError(e)
+				? e
+				: new AbiEncodingErrorClass("Failed to encode packed", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});

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

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Address, Bytes, Selector } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import { encodeWrappedError } from "./encodeWrappedError.js";
+
+describe("encodeWrappedError", () => {
+	describe("success cases", () => {
+		it.effect("encodes wrapped error", () =>
+			Effect.gen(function* () {
+				const encoded = yield* encodeWrappedError({
+					target: Address.from("0x742d35Cc6634C0532925a3b844Bc9e7595f251e3"),
+					selector: Selector.fromHex("0xa9059cbb"),
+					reason: Bytes.from(new Uint8Array([1, 2, 3])),
+					details: Bytes.from(new Uint8Array([4, 5, 6])),
+				});
+				expect(encoded).toBeInstanceOf(Uint8Array);
+				expect(encoded.length).toBeGreaterThan(4);
+			}),
+		);
+	});
+});

package/src/primitives/Abi/encodeWrappedError.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Encodes ERC-7751 wrapped error data.
+ * Provides Effect-based wrapper for wrapped error encoding.
+ *
+ * @module Abi/encodeWrappedError
+ * @since 0.0.1
+ */
+
+import {
+	AbiEncodingError as AbiEncodingErrorClass,
+	type AbiEncodingError,
+	type WrappedErrorType,
+	encodeWrappedError as _encodeWrappedError,
+} from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+/**
+ * Wrapped error input structure (ERC-7751).
+ */
+export type WrappedErrorInput = WrappedErrorType;
+
+/**
+ * Encodes ERC-7751 wrapped error data.
+ *
+ * @description
+ * Creates encoded error data following the ERC-7751 specification:
+ * `error WrappedError(address target, bytes4 selector, bytes reason, bytes details)`
+ *
+ * @param {WrappedErrorInput} wrappedError - Wrapped error data.
+ * @returns {Effect.Effect<Uint8Array, AbiEncodingError>}
+ *   Effect yielding encoded error data (selector + ABI-encoded params).
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { encodeWrappedError } from 'voltaire-effect/primitives/Abi'
+ * import * as Address from '@tevm/voltaire/Address'
+ * import * as Selector from '@tevm/voltaire/Selector'
+ *
+ * const encoded = await Effect.runPromise(
+ *   encodeWrappedError({
+ *     target: Address.from('0x1234...'),
+ *     selector: Selector.fromHex('0xabcd1234'),
+ *     reason: new Uint8Array([...]),
+ *     details: new Uint8Array([...])
+ *   })
+ * )
+ * ```
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-7751
+ * @since 0.0.1
+ */
+export const encodeWrappedError = (
+	wrappedError: WrappedErrorInput,
+): Effect.Effect<Uint8Array, AbiEncodingError> =>
+	Effect.try({
+		try: () => _encodeWrappedError(wrappedError),
+		catch: (e) =>
+			e instanceof AbiEncodingErrorClass
+				? e
+				: new AbiEncodingErrorClass("Failed to encode wrapped error", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});

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

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as S from "effect/Schema";
+import { fromArray } from "./AbiSchema.js";
+import {
+	findSelectorCollisions,
+	hasSelectorCollisions,
+} from "./findSelectorCollisions.js";
+
+const normalAbi = S.decodeUnknownSync(fromArray)([
+	{
+		type: "function",
+		name: "transfer",
+		stateMutability: "nonpayable",
+		inputs: [
+			{ name: "to", type: "address" },
+			{ name: "amount", type: "uint256" },
+		],
+		outputs: [{ type: "bool" }],
+	},
+	{
+		type: "function",
+		name: "balanceOf",
+		stateMutability: "view",
+		inputs: [{ name: "account", type: "address" }],
+		outputs: [{ type: "uint256" }],
+	},
+]);
+
+describe("findSelectorCollisions", () => {
+	describe("success cases", () => {
+		it.effect("returns empty array for normal ABI", () =>
+			Effect.gen(function* () {
+				const collisions = yield* findSelectorCollisions(normalAbi);
+				expect(collisions).toEqual([]);
+			}),
+		);
+	});
+});
+
+describe("hasSelectorCollisions", () => {
+	describe("success cases", () => {
+		it.effect("returns false for normal ABI", () =>
+			Effect.gen(function* () {
+				const hasCollisions = yield* hasSelectorCollisions(normalAbi);
+				expect(hasCollisions).toBe(false);
+			}),
+		);
+	});
+});

package/src/primitives/Abi/findSelectorCollisions.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Finds function selector collisions in an ABI.
+ * Provides Effect-based wrapper for collision detection.
+ *
+ * @module Abi/findSelectorCollisions
+ * @since 0.0.1
+ */
+
+import {
+	type ItemType,
+	findSelectorCollisions as _findSelectorCollisions,
+	hasSelectorCollisions as _hasSelectorCollisions,
+} from "@tevm/voltaire/Abi";
+import type { HexType } from "@tevm/voltaire/Hex";
+import * as Effect from "effect/Effect";
+
+type AbiInput = readonly ItemType[];
+
+/**
+ * Selector collision information.
+ */
+export interface SelectorCollision {
+	selector: HexType;
+	functions: readonly ItemType[];
+}
+
+/**
+ * Finds function selector collisions in an ABI.
+ *
+ * @description
+ * Detects when multiple functions in an ABI share the same 4-byte selector.
+ * This can happen due to the birthday paradox with 4-byte hashes.
+ *
+ * @param {AbiInput} abi - The contract ABI to check.
+ * @returns {Effect.Effect<readonly SelectorCollision[], never>}
+ *   Effect yielding array of collisions (empty if none).
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { findSelectorCollisions } from 'voltaire-effect/primitives/Abi'
+ *
+ * const collisions = await Effect.runPromise(
+ *   findSelectorCollisions(abi)
+ * )
+ * if (collisions.length > 0) {
+ *   console.warn('Selector collisions detected:', collisions)
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const findSelectorCollisions = (
+	abi: AbiInput,
+): Effect.Effect<readonly SelectorCollision[], never> =>
+	Effect.sync(() => _findSelectorCollisions([...abi]) as SelectorCollision[]);
+
+/**
+ * Checks if an ABI has any function selector collisions.
+ *
+ * @description
+ * Quick check for the presence of selector collisions.
+ *
+ * @param {AbiInput} abi - The contract ABI to check.
+ * @returns {Effect.Effect<boolean, never>}
+ *   Effect yielding true if collisions exist.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { hasSelectorCollisions } from 'voltaire-effect/primitives/Abi'
+ *
+ * const hasCollisions = await Effect.runPromise(
+ *   hasSelectorCollisions(abi)
+ * )
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const hasSelectorCollisions = (
+	abi: AbiInput,
+): Effect.Effect<boolean, never> =>
+	Effect.sync(() => _hasSelectorCollisions([...abi]));

package/src/primitives/Abi/index.ts

@@ -21,33 +21,59 @@ export {
 	ReceiveSchema,
 	StateMutabilitySchema,
 } from "./AbiSchema.js";
-export { decodeError } from "./decodeError.js";
-export { decodeEventLog } from "./decodeEventLog.js";
-export { decodeFunction } from "./decodeFunction.js";
-export { decodeFunctionData } from "./decodeFunctionData.js";
-export { decodeFunctionResult } from "./decodeFunctionResult.js";
+
+// Core encoding
+export { encode } from "./encode.js";
+export { encodePacked } from "./encodePacked.js";
+export { encodeWrappedError, type WrappedErrorInput } from "./encodeWrappedError.js";
+
+// Core decoding
+export { decode } from "./decode.js";
+export { decodeData } from "./decodeData.js";
+export { decodeLog, type LogInput } from "./decodeLog.js";
+export { decodeWrappedError, type WrappedErrorResult } from "./decodeWrappedError.js";
+
 // Error encoding/decoding
+export { decodeError } from "./decodeError.js";
 export { encodeError } from "./encodeError.js";
+
 // Event encoding/decoding
+export { decodeEventLog } from "./decodeEventLog.js";
 export { encodeEventLog } from "./encodeEventLog.js";
+
 // Function encoding/decoding
+export { decodeFunction } from "./decodeFunction.js";
+export { decodeFunctionData } from "./decodeFunctionData.js";
+export { decodeFunctionResult } from "./decodeFunctionResult.js";
 export { encodeFunction } from "./encodeFunction.js";
 export { encodeFunctionData } from "./encodeFunctionData.js";
 export { encodeFunctionResult } from "./encodeFunctionResult.js";
+
+// Lookup functions
 export { findError } from "./findError.js";
 export { findEvent } from "./findEvent.js";
-// Lookup functions
 export { findFunction } from "./findFunction.js";
+
+// Selector collision detection
+export {
+	findSelectorCollisions,
+	hasSelectorCollisions,
+	type SelectorCollision,
+} from "./findSelectorCollisions.js";
+
 // Formatting
 export { format } from "./format.js";
 export { formatWithArgs } from "./formatWithArgs.js";
+
+// Getters
 export { getErrorSignature } from "./getErrorSignature.js";
 export { getEvent } from "./getEvent.js";
 export { getEventSignature } from "./getEventSignature.js";
 export { getFunction } from "./getFunction.js";
 export { getFunctionSignature } from "./getFunctionSignature.js";
-// Selectors and signatures
 export { getSelector } from "./getSelector.js";
+
 // Parsing
 export { AbiParseError, parse } from "./parse.js";
 export { AbiItemParseError, parseItem } from "./parseItem.js";
+export { parseLogs, type ParsedLog, type ParseLogsInput } from "./parseLogs.js";

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

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as S from "effect/Schema";
+import { fromArray } from "./AbiSchema.js";
+import { parseLogs } from "./parseLogs.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("parseLogs", () => {
+	describe("success cases", () => {
+		it.effect("returns empty array for no matching logs", () =>
+			Effect.gen(function* () {
+				const parsed = yield* parseLogs(erc20Abi, [
+					{ data: new Uint8Array(32), topics: [new Uint8Array(32)] },
+				]);
+				expect(parsed).toEqual([]);
+			}),
+		);
+
+		it.effect("returns empty array for empty logs", () =>
+			Effect.gen(function* () {
+				const parsed = yield* parseLogs(erc20Abi, []);
+				expect(parsed).toEqual([]);
+			}),
+		);
+	});
+});

package/src/primitives/Abi/parseLogs.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Parses multiple event logs using ABI.
+ * Provides Effect-based wrapper for batch log parsing.
+ *
+ * @module Abi/parseLogs
+ * @since 0.0.1
+ */
+
+import { type Abi, type ItemType } 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;
+
+/**
+ * Log input structure for parseLogs.
+ */
+export interface ParseLogsInput {
+	data: Uint8Array | string;
+	topics: readonly (Uint8Array | string)[];
+}
+
+/**
+ * Parsed log result.
+ */
+export interface ParsedLog {
+	eventName: string;
+	args: Record<string, unknown>;
+}
+
+/**
+ * Parses multiple event logs using ABI.
+ *
+ * @description
+ * Parses an array of log entries, returning successfully decoded logs.
+ * Logs that don't match any event in the ABI are silently filtered out.
+ *
+ * @param {AbiInput} abi - The contract ABI.
+ * @param {readonly ParseLogsInput[]} logs - Array of log objects.
+ * @returns {Effect.Effect<readonly ParsedLog[], never>}
+ *   Effect yielding array of parsed logs (never fails).
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { parseLogs } from 'voltaire-effect/primitives/Abi'
+ *
+ * const parsed = await Effect.runPromise(
+ *   parseLogs(abi, logs)
+ * )
+ * // [{ eventName: 'Transfer', args: { from, to, value } }]
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const parseLogs = (
+	abi: AbiInput,
+	logs: readonly ParseLogsInput[],
+): Effect.Effect<readonly ParsedLog[], never> =>
+	Effect.sync(() => toAbi(abi).parseLogs(logs));