voltaire-effect 0.2.23

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

@@ -0,0 +1,86 @@
+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 { findFunction } from "./findFunction.js";
+
+const erc20Abi = S.decodeUnknownSync(fromArray)([
+	{
+		type: "function",
+		name: "transfer",
+		inputs: [
+			{ name: "to", type: "address" },
+			{ name: "amount", type: "uint256" },
+		],
+		outputs: [{ type: "bool" }],
+		stateMutability: "nonpayable",
+	},
+	{
+		type: "function",
+		name: "balanceOf",
+		inputs: [{ name: "account", type: "address" }],
+		outputs: [{ type: "uint256" }],
+		stateMutability: "view",
+	},
+	{
+		type: "event",
+		name: "Transfer",
+		inputs: [
+			{ name: "from", type: "address", indexed: true },
+			{ name: "to", type: "address", indexed: true },
+			{ name: "value", type: "uint256", indexed: false },
+		],
+	},
+]);
+
+describe("findFunction", () => {
+	describe("success cases", () => {
+		it.effect("finds transfer function", () =>
+			Effect.gen(function* () {
+				const fn = yield* findFunction(erc20Abi, "transfer");
+				expect(fn).not.toBeUndefined();
+				expect(fn?.name).toBe("transfer");
+				expect(fn?.inputs.length).toBe(2);
+			}),
+		);
+
+		it.effect("finds balanceOf function", () =>
+			Effect.gen(function* () {
+				const fn = yield* findFunction(erc20Abi, "balanceOf");
+				expect(fn).not.toBeUndefined();
+				expect(fn?.name).toBe("balanceOf");
+				expect(fn?.stateMutability).toBe("view");
+			}),
+		);
+
+		it.effect("returns undefined for unknown function", () =>
+			Effect.gen(function* () {
+				const fn = yield* findFunction(erc20Abi, "unknownFunction");
+				expect(fn).toBeUndefined();
+			}),
+		);
+
+		it.effect("returns undefined for event name", () =>
+			Effect.gen(function* () {
+				const fn = yield* findFunction(erc20Abi, "Transfer");
+				expect(fn).toBeUndefined();
+			}),
+		);
+
+		it.effect("returns undefined with empty ABI", () =>
+			Effect.gen(function* () {
+				const fn = yield* findFunction([], "transfer");
+				expect(fn).toBeUndefined();
+			}),
+		);
+	});
+
+	describe("is infallible", () => {
+		it.effect("never fails", () =>
+			Effect.gen(function* () {
+				const fn = yield* findFunction(erc20Abi, "nonexistent");
+				expect(fn).toBeUndefined();
+			}),
+		);
+	});
+});

package/src/primitives/Abi/findFunction.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Finds a function in an ABI by name.
+ * Provides Effect-based wrapper for looking up functions.
+ *
+ * @module Abi/findFunction
+ * @since 0.0.1
+ */
+
+import {
+	type Function as AbiFunction,
+	Item,
+	type ItemType,
+} from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+/**
+ * Type alias for ABI input.
+ * @internal
+ */
+type AbiInput = readonly ItemType[];
+
+/**
+ * Finds a function in an ABI by name.
+ *
+ * @description
+ * Searches the ABI for a function with the given name.
+ * Returns the function definition or undefined if not found.
+ *
+ * This is an infallible operation that always succeeds.
+ *
+ * @param {AbiInput} abi - The contract ABI.
+ * @param {string} name - The function name to find.
+ * @returns {Effect.Effect<AbiFunction.FunctionType | undefined, never>}
+ *   Effect yielding the function or undefined.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { findFunction } from 'voltaire-effect/primitives/Abi'
+ *
+ * const fn = Effect.runSync(findFunction(abi, 'transfer'))
+ * if (fn) {
+ *   console.log(fn.inputs)
+ * }
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const findFunction = (
+	abi: AbiInput,
+	name: string,
+): Effect.Effect<AbiFunction.FunctionType | undefined, never> =>
+	Effect.sync(
+		() =>
+			Item.getItem(abi, name, "function") as
+				| AbiFunction.FunctionType
+				| undefined,
+	);

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

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as S from "effect/Schema";
+import { ErrorSchema, EventSchema, FunctionSchema } from "./AbiSchema.js";
+import { format } from "./format.js";
+
+describe("format", () => {
+	describe("function formatting", () => {
+		it.effect("formats transfer function", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "transfer",
+					stateMutability: "nonpayable",
+					inputs: [
+						{ name: "to", type: "address" },
+						{ name: "amount", type: "uint256" },
+					],
+					outputs: [{ type: "bool" }],
+				});
+				const formatted = yield* format(fn as any);
+				expect(formatted).toContain("transfer");
+				expect(formatted).toContain("address");
+				expect(formatted).toContain("uint256");
+			}),
+		);
+
+		it.effect("formats function with no inputs", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "totalSupply",
+					stateMutability: "view",
+					inputs: [],
+					outputs: [{ type: "uint256" }],
+				});
+				const formatted = yield* format(fn as any);
+				expect(formatted).toContain("totalSupply");
+			}),
+		);
+
+		it.effect("formats function with multiple outputs", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "getReserves",
+					stateMutability: "view",
+					inputs: [],
+					outputs: [
+						{ name: "reserve0", type: "uint112" },
+						{ name: "reserve1", type: "uint112" },
+						{ name: "blockTimestampLast", type: "uint32" },
+					],
+				});
+				const formatted = yield* format(fn as any);
+				expect(formatted).toContain("getReserves");
+			}),
+		);
+	});
+
+	describe("event formatting", () => {
+		it.effect("formats Transfer event", () =>
+			Effect.gen(function* () {
+				const evt = S.decodeUnknownSync(EventSchema)({
+					type: "event",
+					name: "Transfer",
+					inputs: [
+						{ name: "from", type: "address", indexed: true },
+						{ name: "to", type: "address", indexed: true },
+						{ name: "value", type: "uint256", indexed: false },
+					],
+				});
+				const formatted = yield* format(evt as any);
+				expect(formatted).toContain("Transfer");
+				expect(formatted).toContain("address");
+			}),
+		);
+	});
+
+	describe("error formatting", () => {
+		it.effect("formats error", () =>
+			Effect.gen(function* () {
+				const err = S.decodeUnknownSync(ErrorSchema)({
+					type: "error",
+					name: "InsufficientBalance",
+					inputs: [
+						{ name: "available", type: "uint256" },
+						{ name: "required", type: "uint256" },
+					],
+				});
+				const formatted = yield* format(err as any);
+				expect(formatted).toContain("InsufficientBalance");
+			}),
+		);
+	});
+
+	describe("is infallible", () => {
+		it.effect("never fails", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "test",
+					stateMutability: "nonpayable",
+					inputs: [],
+					outputs: [],
+				});
+				const formatted = yield* format(fn as any);
+				expect(formatted).toContain("test");
+			}),
+		);
+	});
+});

package/src/primitives/Abi/format.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Formats ABI item as human-readable string.
+ * Provides Effect-based wrapper for ABI formatting.
+ *
+ * @module Abi/format
+ * @since 0.0.1
+ */
+
+import { Item } from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+/**
+ * Formats an ABI item as a human-readable string.
+ *
+ * @description
+ * Converts an ABI item to its canonical human-readable representation,
+ * e.g., "function transfer(address to, uint256 amount) returns (bool)".
+ *
+ * This is an infallible operation that always succeeds.
+ *
+ * @param {object} item - The ABI item to format.
+ * @returns {Effect.Effect<string, never>}
+ *   Effect yielding the formatted string.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { format } from 'voltaire-effect/primitives/Abi'
+ *
+ * const fn = { type: 'function', name: 'transfer', inputs: [...], outputs: [...] }
+ * const formatted = Effect.runSync(format(fn))
+ * // 'function transfer(address to, uint256 amount) returns (bool)'
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const format = (
+	item: Parameters<typeof Item.format>[0],
+): Effect.Effect<string, never> => Effect.sync(() => Item.format(item));

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

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as S from "effect/Schema";
+import { EventSchema, FunctionSchema } from "./AbiSchema.js";
+import { formatWithArgs } from "./formatWithArgs.js";
+
+describe("formatWithArgs", () => {
+	describe("function formatting with args", () => {
+		it.effect("formats transfer with args", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "transfer",
+					stateMutability: "nonpayable",
+					inputs: [
+						{ name: "to", type: "address" },
+						{ name: "amount", type: "uint256" },
+					],
+					outputs: [{ type: "bool" }],
+				});
+				const formatted = yield* formatWithArgs(fn as any, [
+					"0x742d35Cc6634C0532925a3b844Bc9e7595f251e3",
+					1000n,
+				]);
+				expect(formatted).toContain("transfer");
+				expect(formatted).toContain(
+					"0x742d35Cc6634C0532925a3b844Bc9e7595f251e3",
+				);
+				expect(formatted).toContain("1000");
+			}),
+		);
+
+		it.effect("formats function with no args", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "totalSupply",
+					stateMutability: "view",
+					inputs: [],
+					outputs: [{ type: "uint256" }],
+				});
+				const formatted = yield* formatWithArgs(fn as any, []);
+				expect(formatted).toContain("totalSupply");
+			}),
+		);
+
+		it.effect("formats with bigint args", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "transfer",
+					stateMutability: "nonpayable",
+					inputs: [
+						{ name: "to", type: "address" },
+						{ name: "amount", type: "uint256" },
+					],
+					outputs: [{ type: "bool" }],
+				});
+				const formatted = yield* formatWithArgs(fn as any, [
+					"0x1234567890123456789012345678901234567890",
+					1000000000000000000n,
+				]);
+				expect(formatted).toContain("1000000000000000000");
+			}),
+		);
+	});
+
+	describe("event formatting with args", () => {
+		it.effect("formats event with args", () =>
+			Effect.gen(function* () {
+				const evt = S.decodeUnknownSync(EventSchema)({
+					type: "event",
+					name: "Transfer",
+					inputs: [
+						{ name: "from", type: "address", indexed: true },
+						{ name: "to", type: "address", indexed: true },
+						{ name: "value", type: "uint256", indexed: false },
+					],
+				});
+				const formatted = yield* formatWithArgs(evt as any, [
+					"0x1111111111111111111111111111111111111111",
+					"0x2222222222222222222222222222222222222222",
+					500n,
+				]);
+				expect(formatted).toContain("Transfer");
+			}),
+		);
+	});
+
+	describe("is infallible", () => {
+		it.effect("never fails", () =>
+			Effect.gen(function* () {
+				const fn = S.decodeUnknownSync(FunctionSchema)({
+					type: "function",
+					name: "test",
+					stateMutability: "nonpayable",
+					inputs: [],
+					outputs: [],
+				});
+				const formatted = yield* formatWithArgs(fn as any, []);
+				expect(formatted).toContain("test");
+			}),
+		);
+	});
+});

package/src/primitives/Abi/formatWithArgs.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Formats ABI item with argument values.
+ * Provides Effect-based wrapper for ABI formatting with args.
+ *
+ * @module Abi/formatWithArgs
+ * @since 0.0.1
+ */
+
+import { Item } from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+/**
+ * Formats an ABI item with argument values.
+ *
+ * @description
+ * Converts an ABI item to its human-readable representation with
+ * actual argument values substituted, e.g.,
+ * "function transfer(0x123..., 1000)".
+ *
+ * This is an infallible operation that always succeeds.
+ *
+ * @param {object} item - The ABI item to format.
+ * @param {readonly unknown[]} args - The argument values.
+ * @returns {Effect.Effect<string, never>}
+ *   Effect yielding the formatted string with args.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { formatWithArgs } from 'voltaire-effect/primitives/Abi'
+ *
+ * const fn = { type: 'function', name: 'transfer', inputs: [...] }
+ * const formatted = Effect.runSync(formatWithArgs(fn, ['0x123...', 1000n]))
+ * // 'function transfer(0x123..., 1000)'
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const formatWithArgs = (
+	item: Parameters<typeof Item.formatWithArgs>[0],
+	args: readonly unknown[],
+): Effect.Effect<string, never> =>
+	Effect.sync(() => Item.formatWithArgs(item, args as never));

package/src/primitives/Abi/function/errors.ts

@@ -0,0 +1,69 @@
+import {
+	AbiDecodingError,
+	AbiEncodingError,
+	AbiInvalidSelectorError,
+} from "@tevm/voltaire/Abi";
+
+export class FunctionEncodingError extends AbiEncodingError {
+	constructor(
+		message: string,
+		options?: {
+			code?: string | number;
+			context?: Record<string, unknown>;
+			docsPath?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, {
+			code: options?.code ?? "FUNCTION_ENCODING_ERROR",
+			context: options?.context,
+			docsPath: options?.docsPath || "/primitives/abi/function",
+			cause: options?.cause,
+		});
+		this.name = "FunctionEncodingError";
+	}
+}
+
+export class FunctionDecodingError extends AbiDecodingError {
+	constructor(
+		message: string,
+		options?: {
+			code?: string | number;
+			context?: Record<string, unknown>;
+			docsPath?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, {
+			code: options?.code ?? "FUNCTION_DECODING_ERROR",
+			context: options?.context,
+			docsPath: options?.docsPath || "/primitives/abi/function",
+			cause: options?.cause,
+		});
+		this.name = "FunctionDecodingError";
+	}
+}
+
+export class FunctionInvalidSelectorError extends AbiInvalidSelectorError {
+	constructor(
+		message: string,
+		options: {
+			code?: string | number;
+			value: unknown;
+			expected: string;
+			context?: Record<string, unknown>;
+			docsPath?: string;
+			cause?: Error;
+		},
+	) {
+		super(message, {
+			code: options?.code ?? "FUNCTION_INVALID_SELECTOR",
+			value: options.value,
+			expected: options.expected,
+			context: options?.context,
+			docsPath: options?.docsPath || "/primitives/abi/function",
+			cause: options?.cause,
+		});
+		this.name = "FunctionInvalidSelectorError";
+	}
+}

package/src/primitives/Abi/function/index.ts

@@ -0,0 +1,24 @@
+import { Function as FunctionNamespace } from "@tevm/voltaire/Abi";
+
+export const {
+	getSelector,
+	getSignature,
+	encodeParams,
+	decodeParams,
+	encodeResult,
+	decodeResult,
+	Signature,
+	Params,
+	DecodeParams,
+	Result,
+	DecodeResult,
+	GetSelector,
+} = FunctionNamespace;
+
+export {
+	FunctionDecodingError,
+	FunctionEncodingError,
+	FunctionInvalidSelectorError,
+} from "./errors.js";
+
+export { FunctionNamespace as Function };

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

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as S from "effect/Schema";
+import { ErrorSchema } from "./AbiSchema.js";
+import { getErrorSignature } from "./getErrorSignature.js";
+
+describe("getErrorSignature", () => {
+	describe("success cases", () => {
+		it.effect("gets InsufficientBalance error signature", () =>
+			Effect.gen(function* () {
+				const err = S.decodeUnknownSync(ErrorSchema)({
+					type: "error",
+					name: "InsufficientBalance",
+					inputs: [
+						{ name: "available", type: "uint256" },
+						{ name: "required", type: "uint256" },
+					],
+				});
+				const sig = yield* getErrorSignature(err as any);
+				expect(sig).toBe("InsufficientBalance(uint256,uint256)");
+			}),
+		);
+
+		it.effect("gets Unauthorized error signature", () =>
+			Effect.gen(function* () {
+				const err = S.decodeUnknownSync(ErrorSchema)({
+					type: "error",
+					name: "Unauthorized",
+					inputs: [{ name: "caller", type: "address" }],
+				});
+				const sig = yield* getErrorSignature(err as any);
+				expect(sig).toBe("Unauthorized(address)");
+			}),
+		);
+
+		it.effect("gets error with no inputs", () =>
+			Effect.gen(function* () {
+				const err = S.decodeUnknownSync(ErrorSchema)({
+					type: "error",
+					name: "InvalidAmount",
+					inputs: [],
+				});
+				const sig = yield* getErrorSignature(err as any);
+				expect(sig).toBe("InvalidAmount()");
+			}),
+		);
+
+		it.effect("gets error with multiple complex types", () =>
+			Effect.gen(function* () {
+				const err = S.decodeUnknownSync(ErrorSchema)({
+					type: "error",
+					name: "TransferFailed",
+					inputs: [
+						{ name: "from", type: "address" },
+						{ name: "to", type: "address" },
+						{ name: "amount", type: "uint256" },
+					],
+				});
+				const sig = yield* getErrorSignature(err as any);
+				expect(sig).toBe("TransferFailed(address,address,uint256)");
+			}),
+		);
+	});
+
+	describe("is infallible", () => {
+		it.effect("never fails", () =>
+			Effect.gen(function* () {
+				const err = S.decodeUnknownSync(ErrorSchema)({
+					type: "error",
+					name: "Test",
+					inputs: [],
+				});
+				const sig = yield* getErrorSignature(err as any);
+				expect(sig).toBe("Test()");
+			}),
+		);
+	});
+});

package/src/primitives/Abi/getErrorSignature.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Gets the canonical signature of an error.
+ * Provides Effect-based wrapper for getting error signatures.
+ *
+ * @module Abi/getErrorSignature
+ * @since 0.0.1
+ */
+
+import { Error as AbiError } from "@tevm/voltaire/Abi";
+import * as Effect from "effect/Effect";
+
+/**
+ * Gets the canonical signature of an error.
+ *
+ * @description
+ * Returns the canonical string representation of an error signature,
+ * e.g., "InsufficientBalance(uint256)".
+ *
+ * This is an infallible operation that always succeeds.
+ *
+ * @param {AbiError.ErrorType} error - The error ABI item.
+ * @returns {Effect.Effect<string, never>}
+ *   Effect yielding the error signature string.
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { getErrorSignature } from 'voltaire-effect/primitives/Abi'
+ *
+ * const err = { type: 'error', name: 'InsufficientBalance', inputs: [...] }
+ * const sig = Effect.runSync(getErrorSignature(err))
+ * // 'InsufficientBalance(uint256)'
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const getErrorSignature = (
+	error: AbiError.ErrorType,
+): Effect.Effect<string, never> =>
+	Effect.sync(() => AbiError.getSignature(error));