voltaire-effect 0.2.23

package/src/primitives/validation/assertInRange.ts

@@ -0,0 +1,60 @@
+import {
+	IntegerOverflowError,
+	IntegerUnderflowError,
+} from "@tevm/voltaire/errors";
+
+export function assertInRange(
+	value: number,
+	min: number,
+	max: number,
+	name: string,
+): void {
+	if (value < min) {
+		throw new IntegerUnderflowError(
+			`${name} value ${value} is below minimum ${min}`,
+			{
+				value,
+				min,
+				type: name,
+			},
+		);
+	}
+	if (value > max) {
+		throw new IntegerOverflowError(
+			`${name} value ${value} exceeds maximum ${max}`,
+			{
+				value,
+				max,
+				type: name,
+			},
+		);
+	}
+}
+
+export function assertInRangeBigInt(
+	value: bigint,
+	min: bigint,
+	max: bigint,
+	name: string,
+): void {
+	if (value < min) {
+		throw new IntegerUnderflowError(
+			`${name} value ${value} is below minimum ${min}`,
+			{
+				value,
+				min,
+				type: name,
+			},
+		);
+	}
+	if (value > max) {
+		throw new IntegerOverflowError(
+			`${name} value ${value} exceeds maximum ${max}`,
+			{
+				value,
+				max,
+				type: name,
+			},
+		);
+	}
+}

package/src/primitives/validation/assertInt.ts

@@ -0,0 +1,121 @@
+import {
+	IntegerOverflowError,
+	IntegerUnderflowError,
+} from "@tevm/voltaire/errors";
+
+const INT8_MIN = -128;
+const INT8_MAX = 127;
+const INT16_MIN = -32768;
+const INT16_MAX = 32767;
+const INT32_MIN = -2147483648;
+const INT32_MAX = 2147483647;
+const INT64_MIN = -9223372036854775808n;
+const INT64_MAX = 9223372036854775807n;
+const INT128_MIN = -170141183460469231731687303715884105728n;
+const INT128_MAX = 170141183460469231731687303715884105727n;
+const INT256_MIN =
+	-57896044618658097711785492504343953926634992332820282019728792003956564819968n;
+const INT256_MAX =
+	57896044618658097711785492504343953926634992332820282019728792003956564819967n;
+
+export function assertInt8(value: number, name = "int8"): void {
+	if (value < INT8_MIN) {
+		throw new IntegerUnderflowError(`${name} below minimum (-128)`, {
+			value,
+			min: INT8_MIN,
+			type: name,
+		});
+	}
+	if (value > INT8_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (127)`, {
+			value,
+			max: INT8_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertInt16(value: number, name = "int16"): void {
+	if (value < INT16_MIN) {
+		throw new IntegerUnderflowError(`${name} below minimum (-32768)`, {
+			value,
+			min: INT16_MIN,
+			type: name,
+		});
+	}
+	if (value > INT16_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (32767)`, {
+			value,
+			max: INT16_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertInt32(value: number, name = "int32"): void {
+	if (value < INT32_MIN) {
+		throw new IntegerUnderflowError(`${name} below minimum (-2147483648)`, {
+			value,
+			min: INT32_MIN,
+			type: name,
+		});
+	}
+	if (value > INT32_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (2147483647)`, {
+			value,
+			max: INT32_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertInt64(value: bigint, name = "int64"): void {
+	if (value < INT64_MIN) {
+		throw new IntegerUnderflowError(`${name} below minimum (-2^63)`, {
+			value,
+			min: INT64_MIN,
+			type: name,
+		});
+	}
+	if (value > INT64_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (2^63-1)`, {
+			value,
+			max: INT64_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertInt128(value: bigint, name = "int128"): void {
+	if (value < INT128_MIN) {
+		throw new IntegerUnderflowError(`${name} below minimum (-2^127)`, {
+			value,
+			min: INT128_MIN,
+			type: name,
+		});
+	}
+	if (value > INT128_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (2^127-1)`, {
+			value,
+			max: INT128_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertInt256(value: bigint, name = "int256"): void {
+	if (value < INT256_MIN) {
+		throw new IntegerUnderflowError(`${name} below minimum (-2^255)`, {
+			value,
+			min: INT256_MIN,
+			type: name,
+		});
+	}
+	if (value > INT256_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (2^255-1)`, {
+			value,
+			max: INT256_MAX,
+			type: name,
+		});
+	}
+}

package/src/primitives/validation/assertSize.ts

@@ -0,0 +1,68 @@
+import { InvalidSizeError } from "@tevm/voltaire/errors";
+
+export function assertSize(
+	data: Uint8Array | string,
+	expectedSize: number,
+	name = "data",
+): void {
+	const actualSize = getSize(data);
+	if (actualSize !== expectedSize) {
+		throw new InvalidSizeError(
+			`${name} must be ${expectedSize} bytes, got ${actualSize}`,
+			{
+				value: data,
+				actualSize,
+				expectedSize,
+			},
+		);
+	}
+}
+
+export function assertMaxSize(
+	data: Uint8Array | string,
+	maxSize: number,
+	name = "data",
+): void {
+	const actualSize = getSize(data);
+	if (actualSize > maxSize) {
+		throw new InvalidSizeError(
+			`${name} exceeds maximum ${maxSize} bytes, got ${actualSize}`,
+			{
+				value: data,
+				actualSize,
+				expectedSize: maxSize,
+				context: { constraint: "max" },
+			},
+		);
+	}
+}
+
+export function assertMinSize(
+	data: Uint8Array | string,
+	minSize: number,
+	name = "data",
+): void {
+	const actualSize = getSize(data);
+	if (actualSize < minSize) {
+		throw new InvalidSizeError(
+			`${name} must be at least ${minSize} bytes, got ${actualSize}`,
+			{
+				value: data,
+				actualSize,
+				expectedSize: minSize,
+				context: { constraint: "min" },
+			},
+		);
+	}
+}
+
+function getSize(data: Uint8Array | string): number {
+	if (data instanceof Uint8Array) {
+		return data.length;
+	}
+	if (typeof data === "string") {
+		const hex = data.startsWith("0x") ? data.slice(2) : data;
+		return Math.floor(hex.length / 2);
+	}
+	return 0;
+}

package/src/primitives/validation/assertUint.ts

@@ -0,0 +1,114 @@
+import {
+	IntegerOverflowError,
+	IntegerUnderflowError,
+} from "@tevm/voltaire/errors";
+
+const UINT8_MAX = 255;
+const UINT16_MAX = 65535;
+const UINT32_MAX = 4294967295;
+const UINT64_MAX = 18446744073709551615n;
+const UINT128_MAX = 340282366920938463463374607431768211455n;
+const UINT256_MAX =
+	115792089237316195423570985008687907853269984665640564039457584007913129639935n;
+
+export function assertUint8(value: number, name = "uint8"): void {
+	if (value < 0) {
+		throw new IntegerUnderflowError(`${name} cannot be negative`, {
+			value,
+			min: 0,
+			type: name,
+		});
+	}
+	if (value > UINT8_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (255)`, {
+			value,
+			max: UINT8_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertUint16(value: number, name = "uint16"): void {
+	if (value < 0) {
+		throw new IntegerUnderflowError(`${name} cannot be negative`, {
+			value,
+			min: 0,
+			type: name,
+		});
+	}
+	if (value > UINT16_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (65535)`, {
+			value,
+			max: UINT16_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertUint32(value: number, name = "uint32"): void {
+	if (value < 0) {
+		throw new IntegerUnderflowError(`${name} cannot be negative`, {
+			value,
+			min: 0,
+			type: name,
+		});
+	}
+	if (value > UINT32_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (4294967295)`, {
+			value,
+			max: UINT32_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertUint64(value: bigint, name = "uint64"): void {
+	if (value < 0n) {
+		throw new IntegerUnderflowError(`${name} cannot be negative`, {
+			value,
+			min: 0n,
+			type: name,
+		});
+	}
+	if (value > UINT64_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (2^64-1)`, {
+			value,
+			max: UINT64_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertUint128(value: bigint, name = "uint128"): void {
+	if (value < 0n) {
+		throw new IntegerUnderflowError(`${name} cannot be negative`, {
+			value,
+			min: 0n,
+			type: name,
+		});
+	}
+	if (value > UINT128_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (2^128-1)`, {
+			value,
+			max: UINT128_MAX,
+			type: name,
+		});
+	}
+}
+
+export function assertUint256(value: bigint, name = "uint256"): void {
+	if (value < 0n) {
+		throw new IntegerUnderflowError(`${name} cannot be negative`, {
+			value,
+			min: 0n,
+			type: name,
+		});
+	}
+	if (value > UINT256_MAX) {
+		throw new IntegerOverflowError(`${name} exceeds maximum (2^256-1)`, {
+			value,
+			max: UINT256_MAX,
+			type: name,
+		});
+	}
+}

package/src/primitives/validation/index.ts

@@ -0,0 +1,23 @@
+export {
+	assertNonNegative,
+	assertNonZero,
+	assertPositive,
+} from "./assertCommon.js";
+export { assertInRange, assertInRangeBigInt } from "./assertInRange.js";
+export {
+	assertInt8,
+	assertInt16,
+	assertInt32,
+	assertInt64,
+	assertInt128,
+	assertInt256,
+} from "./assertInt.js";
+export { assertMaxSize, assertMinSize, assertSize } from "./assertSize.js";
+export {
+	assertUint8,
+	assertUint16,
+	assertUint32,
+	assertUint64,
+	assertUint128,
+	assertUint256,
+} from "./assertUint.js";

package/src/services/AbiEncoder/AbiEncoder.test.ts

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview Tests for AbiEncoder service.
+ */
+
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as S from "effect/Schema";
+import { fromArray } from "../../primitives/Abi/AbiSchema.js";
+import {
+	AbiDecodeError,
+	AbiEncodeError,
+	AbiEncoderService,
+} from "./AbiEncoderService.js";
+import { DefaultAbiEncoder } from "./DefaultAbiEncoder.js";
+
+const ERC20_ABI = S.decodeUnknownSync(fromArray)([
+	{
+		type: "function",
+		name: "transfer",
+		stateMutability: "nonpayable",
+		inputs: [
+			{ name: "to", type: "address" },
+			{ name: "amount", type: "uint256" },
+		],
+		outputs: [{ name: "", type: "bool" }],
+	},
+	{
+		type: "function",
+		name: "balanceOf",
+		stateMutability: "view",
+		inputs: [{ name: "account", type: "address" }],
+		outputs: [{ name: "", type: "uint256" }],
+	},
+	{
+		type: "event",
+		name: "Transfer",
+		inputs: [
+			{ name: "from", type: "address", indexed: true },
+			{ name: "to", type: "address", indexed: true },
+			{ name: "value", type: "uint256", indexed: false },
+		],
+	},
+]);
+
+describe("AbiEncoderService", () => {
+	describe("encodeFunction", () => {
+		it.skip("returns hex starting with selector (requires encodeFunction export)", () => {
+			// Test skipped: BrandedAbi.encodeFunction is not exported from @tevm/voltaire
+		});
+
+		it.effect("fails with AbiEncodeError for unknown function", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const result = yield* encoder
+					.encodeFunction(ERC20_ABI, "unknownFunction", [])
+					.pipe(Effect.either);
+
+				expect(result._tag).toBe("Left");
+				if (result._tag === "Left") {
+					expect(result.left).toBeInstanceOf(AbiEncodeError);
+					expect(result.left._tag).toBe("AbiEncodeError");
+					expect(result.left.functionName).toBe("unknownFunction");
+				}
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+	});
+
+	describe("decodeFunction", () => {
+		it.effect("decodes function result successfully", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const encodedResult =
+					"0x0000000000000000000000000000000000000000000000000000000000000001";
+				const result = yield* encoder.decodeFunction(
+					ERC20_ABI,
+					"transfer",
+					encodedResult,
+				);
+
+				expect(result).toEqual([true]);
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+
+		it.effect("fails with AbiDecodeError for invalid hex", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const result = yield* encoder
+					.decodeFunction(ERC20_ABI, "transfer", "0xinvalid")
+					.pipe(Effect.either);
+
+				expect(result._tag).toBe("Left");
+				if (result._tag === "Left") {
+					expect(result.left).toBeInstanceOf(AbiDecodeError);
+					expect(result.left._tag).toBe("AbiDecodeError");
+					expect(result.left.data).toBe("0xinvalid");
+				}
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+	});
+
+	describe("encodeEventTopics", () => {
+		it.effect("returns event selector as first topic", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const result = yield* encoder.encodeEventTopics(ERC20_ABI, "Transfer");
+
+				expect(result.length).toBeGreaterThanOrEqual(1);
+				expect(result[0]).toMatch(/^0x[a-fA-F0-9]{64}$/);
+				expect(result[0]).toBe(
+					"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+				);
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+
+		it.effect("handles indexed args correctly", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const fromAddress = "0x1111111111111111111111111111111111111111";
+				const toAddress = "0x2222222222222222222222222222222222222222";
+				const result = yield* encoder.encodeEventTopics(ERC20_ABI, "Transfer", [
+					fromAddress,
+					toAddress,
+				]);
+
+				expect(result.length).toBe(3);
+				expect(result[0]).toBe(
+					"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+				);
+				expect(result[1]).toMatch(/^0x[a-fA-F0-9]{64}$/);
+				expect(result[2]).toMatch(/^0x[a-fA-F0-9]{64}$/);
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+
+		it.effect("works without args (just selector)", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const result = yield* encoder.encodeEventTopics(
+					ERC20_ABI,
+					"Transfer",
+					[],
+				);
+
+				expect(result.length).toBe(1);
+				expect(result[0]).toBe(
+					"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+				);
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+	});
+
+	describe("decodeEventLog", () => {
+		it.effect("decodes event log successfully", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const topics = [
+					"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+					"0x0000000000000000000000001111111111111111111111111111111111111111",
+					"0x0000000000000000000000002222222222222222222222222222222222222222",
+				] as const;
+				const data =
+					"0x00000000000000000000000000000000000000000000000000000000000003e8";
+
+				const result = yield* encoder.decodeEventLog(
+					ERC20_ABI,
+					"Transfer",
+					data,
+					topics,
+				);
+
+				expect(result).toBeDefined();
+				expect(typeof result).toBe("object");
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+
+		it.effect("fails with AbiDecodeError for missing event", () =>
+			Effect.gen(function* () {
+				const encoder = yield* AbiEncoderService;
+				const result = yield* encoder
+					.decodeEventLog(ERC20_ABI, "NonExistentEvent", "0x", [])
+					.pipe(Effect.either);
+
+				expect(result._tag).toBe("Left");
+				if (result._tag === "Left") {
+					expect(result.left).toBeInstanceOf(AbiDecodeError);
+					expect(result.left._tag).toBe("AbiDecodeError");
+				}
+			}).pipe(Effect.provide(DefaultAbiEncoder)),
+		);
+	});
+});

package/src/services/AbiEncoder/AbiEncoderService.ts

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview ABI encoding/decoding service definition.
+ *
+ * @module AbiEncoderService
+ * @since 0.0.1
+ *
+ * @description
+ * Provides Effect-based ABI encoding and decoding operations for:
+ * - Function call encoding/decoding
+ * - Event topic encoding
+ * - Event log decoding
+ *
+ * All operations are wrapped in Effect for proper error handling.
+ *
+ * @see {@link DefaultAbiEncoder} - The live implementation layer
+ */
+
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import type * as Effect from "effect/Effect";
+
+/**
+ * Error thrown when ABI encoding fails.
+ *
+ * @since 0.0.1
+ */
+export class AbiEncodeError extends Data.TaggedError("AbiEncodeError")<{
+	readonly functionName: string;
+	readonly args: readonly unknown[];
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Error thrown when ABI decoding fails.
+ *
+ * @since 0.0.1
+ */
+export class AbiDecodeError extends Data.TaggedError("AbiDecodeError")<{
+	readonly data: `0x${string}`;
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Shape of the ABI encoder service.
+ *
+ * @since 0.0.1
+ */
+export type AbiEncoderShape = {
+	/**
+	 * Encodes a function call with the given arguments.
+	 *
+	 * @param abi - The contract ABI
+	 * @param functionName - The function name to encode
+	 * @param args - The arguments to encode
+	 * @returns Encoded calldata as hex
+	 */
+	readonly encodeFunction: (
+		abi: readonly unknown[],
+		functionName: string,
+		args: readonly unknown[],
+	) => Effect.Effect<`0x${string}`, AbiEncodeError>;
+
+	/**
+	 * Decodes function return data.
+	 *
+	 * @param abi - The contract ABI
+	 * @param functionName - The function name that was called
+	 * @param data - The raw return data
+	 * @returns Decoded result values
+	 */
+	readonly decodeFunction: (
+		abi: readonly unknown[],
+		functionName: string,
+		data: `0x${string}`,
+	) => Effect.Effect<readonly unknown[], AbiDecodeError>;
+
+	/**
+	 * Encodes event topics for filtering logs.
+	 *
+	 * @param abi - The contract ABI
+	 * @param eventName - The event name
+	 * @param args - Optional indexed argument values for filtering
+	 * @returns Array of topic hashes
+	 */
+	readonly encodeEventTopics: (
+		abi: readonly unknown[],
+		eventName: string,
+		args?: readonly unknown[],
+	) => Effect.Effect<readonly `0x${string}`[], AbiEncodeError>;
+
+	/**
+	 * Decodes an event log into structured data.
+	 *
+	 * @param abi - The contract ABI
+	 * @param eventName - The event name
+	 * @param data - The log data
+	 * @param topics - The log topics
+	 * @returns Decoded event arguments as a record
+	 */
+	readonly decodeEventLog: (
+		abi: readonly unknown[],
+		eventName: string,
+		data: `0x${string}`,
+		topics: readonly `0x${string}`[],
+	) => Effect.Effect<Record<string, unknown>, AbiDecodeError>;
+};
+
+/**
+ * ABI encoding/decoding service.
+ *
+ * @description
+ * Provides methods for encoding function calls, decoding return data,
+ * and working with event logs. All operations return Effects that may
+ * fail with AbiEncodeError or AbiDecodeError.
+ *
+ * @since 0.0.1
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { AbiEncoderService, DefaultAbiEncoder } from 'voltaire-effect'
+ *
+ * const abi = [
+ *   { type: 'function', name: 'balanceOf', inputs: [{ type: 'address' }], outputs: [{ type: 'uint256' }] }
+ * ] as const
+ *
+ * const program = Effect.gen(function* () {
+ *   const encoder = yield* AbiEncoderService
+ *   const calldata = yield* encoder.encodeFunction(abi, 'balanceOf', ['0x1234...'])
+ *   return calldata
+ * }).pipe(
+ *   Effect.provide(DefaultAbiEncoder)
+ * )
+ * ```
+ */
+export class AbiEncoderService extends Context.Tag("AbiEncoderService")<
+	AbiEncoderService,
+	AbiEncoderShape
+>() {}