voltaire-effect 0.2.23

package/src/services/Contract/ContractTypes.ts

@@ -0,0 +1,412 @@
+/**
+ * @fileoverview Contract type definitions for type-safe contract interactions.
+ *
+ * @module ContractTypes
+ * @since 0.0.1
+ *
+ * @description
+ * Defines types for ABI handling, contract instances, and contract operations.
+ * Used by the Contract factory to create type-safe contract bindings.
+ *
+ * Main types:
+ * - {@link Abi} - Full ABI definition
+ * - {@link AbiItem} - Single ABI entry
+ * - {@link ContractInstance} - Type-safe contract binding
+ * - {@link EventFilter} - Event query parameters
+ * - {@link DecodedEvent} - Decoded event log
+ *
+ * Error types:
+ * - {@link ContractError} - Base contract error
+ * - {@link ContractCallError} - Read operation error
+ * - {@link ContractWriteError} - Write operation error
+ * - {@link ContractEventError} - Event query error
+ *
+ * @see {@link Contract} - Factory function using these types
+ */
+
+import type { BrandedAddress, BrandedHash, BrandedHex } from "@tevm/voltaire";
+import * as Data from "effect/Data";
+
+type AddressType = BrandedAddress.AddressType;
+type HashType = BrandedHash.HashType;
+type HexType = BrandedHex.HexType;
+
+/**
+ * Single item in an ABI definition.
+ *
+ * @description
+ * Can be a function, event, error, constructor, or fallback.
+ * This is a simplified ABI item type for basic usage.
+ *
+ * @since 0.0.1
+ */
+export type AbiItem = {
+	/** Item type (function, event, error, constructor, fallback, receive) */
+	readonly type: string;
+	/** Item name (undefined for constructor/fallback/receive) */
+	readonly name?: string;
+	/** Input parameters for functions/events/errors */
+	readonly inputs?: readonly {
+		type: string;
+		name?: string;
+		indexed?: boolean;
+	}[];
+	/** Output parameters for functions */
+	readonly outputs?: readonly { type: string; name?: string }[];
+	/** Function state mutability (pure, view, nonpayable, payable) */
+	readonly stateMutability?: string;
+	/** Whether event is anonymous */
+	readonly anonymous?: boolean;
+};
+
+/**
+ * Full ABI definition as an array of items.
+ *
+ * @description
+ * Standard Solidity ABI format as produced by solc.
+ * Used to create type-safe contract instances.
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * ```typescript
+ * const erc20Abi: Abi = [
+ *   { type: 'function', name: 'balanceOf', inputs: [{ type: 'address' }], outputs: [{ type: 'uint256' }], stateMutability: 'view' },
+ *   { type: 'function', name: 'transfer', inputs: [{ type: 'address' }, { type: 'uint256' }], outputs: [{ type: 'bool' }], stateMutability: 'nonpayable' },
+ *   { type: 'event', name: 'Transfer', inputs: [{ type: 'address', indexed: true }, { type: 'address', indexed: true }, { type: 'uint256' }] }
+ * ] as const
+ * ```
+ */
+export type Abi = readonly AbiItem[];
+
+import type * as Effect from "effect/Effect";
+import type { SignerService } from "../Signer/index.js";
+
+/**
+ * Block identifier for event filtering.
+ * Can be a named tag or a block number.
+ * @since 0.0.1
+ */
+export type BlockTag =
+	| "latest"
+	| "earliest"
+	| "pending"
+	| "safe"
+	| "finalized"
+	| bigint;
+
+/**
+ * Filter options for querying contract events.
+ * @since 0.0.1
+ */
+export interface EventFilter {
+	/** Start block for the query */
+	readonly fromBlock?: BlockTag;
+	/** End block for the query */
+	readonly toBlock?: BlockTag;
+	/** Indexed argument filters */
+	readonly args?: Record<string, unknown>;
+}
+
+/**
+ * Decoded event from a contract log.
+ * @since 0.0.1
+ */
+export interface DecodedEvent {
+	/** Name of the event */
+	readonly eventName: string;
+	/** Decoded event arguments */
+	readonly args: Record<string, unknown>;
+	/** Block number where the event was emitted */
+	readonly blockNumber: bigint;
+	/** Transaction hash that emitted the event */
+	readonly transactionHash: HexType;
+	/** Log index within the block */
+	readonly logIndex: number;
+}
+
+/**
+ * Base error class for contract operations.
+ * @since 0.0.1
+ */
+export class ContractError extends Data.TaggedError("ContractError")<{
+	/**
+	 * The original input that caused the error.
+	 */
+	readonly input: unknown;
+
+	/**
+	 * Human-readable error message.
+	 */
+	readonly message: string;
+
+	/**
+	 * JSON-RPC error code (if applicable).
+	 */
+	readonly code?: number;
+
+	/**
+	 * Optional underlying cause.
+	 */
+	readonly cause?: unknown;
+
+	/**
+	 * Optional context for debugging.
+	 */
+	readonly context?: Record<string, unknown>;
+}> {
+	constructor(
+		input: unknown,
+		message: string,
+		options?: {
+			code?: number;
+			context?: Record<string, unknown>;
+			cause?: unknown;
+		},
+	) {
+		super({
+			input,
+			message,
+			code: options?.code,
+			cause: options?.cause,
+			context: options?.context,
+		});
+	}
+}
+
+/**
+ * Error thrown when a contract read call fails.
+ * @since 0.0.1
+ */
+export class ContractCallError extends Data.TaggedError("ContractCallError")<{
+	readonly input: unknown;
+	readonly message: string;
+	readonly code?: number;
+	readonly cause?: unknown;
+	readonly context?: Record<string, unknown>;
+}> {
+	constructor(
+		input: unknown,
+		message: string,
+		options?: {
+			code?: number;
+			context?: Record<string, unknown>;
+			cause?: unknown;
+		},
+	) {
+		super({
+			input,
+			message,
+			code: options?.code,
+			cause: options?.cause,
+			context: options?.context,
+		});
+	}
+}
+
+/**
+ * Error thrown when a contract write transaction fails.
+ * @since 0.0.1
+ */
+export class ContractWriteError extends Data.TaggedError("ContractWriteError")<{
+	readonly input: unknown;
+	readonly message: string;
+	readonly code?: number;
+	readonly cause?: unknown;
+	readonly context?: Record<string, unknown>;
+}> {
+	constructor(
+		input: unknown,
+		message: string,
+		options?: {
+			code?: number;
+			context?: Record<string, unknown>;
+			cause?: unknown;
+		},
+	) {
+		super({
+			input,
+			message,
+			code: options?.code,
+			cause: options?.cause,
+			context: options?.context,
+		});
+	}
+}
+
+/**
+ * Error thrown when fetching contract events fails.
+ * @since 0.0.1
+ */
+export class ContractEventError extends Data.TaggedError("ContractEventError")<{
+	readonly input: unknown;
+	readonly message: string;
+	readonly code?: number;
+	readonly cause?: unknown;
+	readonly context?: Record<string, unknown>;
+}> {
+	constructor(
+		input: unknown,
+		message: string,
+		options?: {
+			code?: number;
+			context?: Record<string, unknown>;
+			cause?: unknown;
+		},
+	) {
+		super({
+			input,
+			message,
+			code: options?.code,
+			cause: options?.cause,
+			context: options?.context,
+		});
+	}
+}
+
+/**
+ * Type-safe contract instance with read, write, simulate, and event methods.
+ * @since 0.0.1
+ */
+export interface ContractInstance<TAbi extends Abi> {
+	/** Contract address */
+	readonly address: AddressType;
+	/** Contract ABI */
+	readonly abi: TAbi;
+	/** Read-only contract methods (view/pure functions) */
+	readonly read: ContractReadMethods<TAbi>;
+	/** State-changing contract methods */
+	readonly write: ContractWriteMethods<TAbi>;
+	/** Simulate state-changing methods without sending transactions */
+	readonly simulate: ContractSimulateMethods<TAbi>;
+	/** Query contract events */
+	readonly getEvents: <E extends ExtractEventNames<TAbi>>(
+		eventName: E,
+		filter?: EventFilter,
+	) => Effect.Effect<DecodedEvent[], ContractEventError>;
+}
+
+type ExtractViewFunctions<TAbi extends Abi> = Extract<
+	TAbi[number],
+	{ type: "function"; stateMutability: "view" | "pure" }
+>;
+
+type ExtractWriteFunctions<TAbi extends Abi> = Extract<
+	TAbi[number],
+	{ type: "function"; stateMutability: "nonpayable" | "payable" }
+>;
+
+/**
+ * Transaction options for write methods.
+ * @since 0.0.1
+ */
+export interface WriteOptions {
+	/** Value in wei to send with the transaction */
+	readonly value?: bigint;
+	/** Gas limit for the transaction */
+	readonly gas?: bigint;
+	/** Gas price for legacy transactions */
+	readonly gasPrice?: bigint;
+	/** Max fee per gas for EIP-1559 transactions */
+	readonly maxFeePerGas?: bigint;
+	/** Max priority fee for EIP-1559 transactions */
+	readonly maxPriorityFeePerGas?: bigint;
+	/** Transaction nonce */
+	readonly nonce?: bigint;
+}
+
+type ExtractEvents<TAbi extends Abi> = Extract<TAbi[number], { type: "event" }>;
+
+type ExtractEventNames<TAbi extends Abi> =
+	ExtractEvents<TAbi> extends { name: infer N }
+		? N extends string
+			? N
+			: never
+		: never;
+
+type AbiInputsToArgs<
+	TInputs extends readonly { type: string; name?: string }[],
+> = {
+	[K in keyof TInputs]: AbiTypeToTs<TInputs[K]["type"]>;
+};
+
+type AbiTypeToTs<T extends string> = T extends `uint${string}`
+	? bigint
+	: T extends `int${string}`
+		? bigint
+		: T extends "address"
+			? AddressType
+			: T extends "bool"
+				? boolean
+				: T extends "string"
+					? string
+					: T extends `bytes${string}`
+						? HexType
+						: T extends "bytes"
+							? HexType
+							: T extends `${string}[]`
+								? readonly unknown[]
+								: T extends `tuple`
+									? Record<string, unknown>
+									: unknown;
+
+type AbiOutputToTs<TOutputs extends readonly { type: string }[]> =
+	TOutputs extends readonly [{ type: infer T }]
+		? T extends string
+			? AbiTypeToTs<T>
+			: unknown
+		: TOutputs extends readonly []
+			? undefined
+			: Record<string, unknown>;
+
+type ContractReadMethods<TAbi extends Abi> = {
+	[F in ExtractViewFunctions<TAbi> as F["name"] extends string
+		? F["name"]
+		: never]: (
+		...args: F extends { inputs: infer I }
+			? I extends readonly { type: string }[]
+				? AbiInputsToArgs<I>
+				: []
+			: []
+	) => Effect.Effect<
+		F extends { outputs: infer O }
+			? O extends readonly { type: string }[]
+				? AbiOutputToTs<O>
+				: unknown
+			: unknown,
+		ContractCallError
+	>;
+};
+
+type WriteMethodArgs<TInputs> = TInputs extends readonly { type: string }[]
+	? AbiInputsToArgs<TInputs> extends readonly []
+		? [options?: WriteOptions]
+		: [...args: AbiInputsToArgs<TInputs>, options?: WriteOptions]
+	: [options?: WriteOptions];
+
+type ContractWriteMethods<TAbi extends Abi> = {
+	[F in ExtractWriteFunctions<TAbi> as F["name"] extends string
+		? F["name"]
+		: never]: (
+		...args: WriteMethodArgs<F extends { inputs: infer I } ? I : []>
+	) => Effect.Effect<HashType, ContractWriteError, SignerService>;
+};
+
+type ContractSimulateMethods<TAbi extends Abi> = {
+	[F in ExtractWriteFunctions<TAbi> as F["name"] extends string
+		? F["name"]
+		: never]: (
+		...args: F extends { inputs: infer I }
+			? I extends readonly { type: string }[]
+				? AbiInputsToArgs<I>
+				: []
+			: []
+	) => Effect.Effect<
+		F extends { outputs: infer O }
+			? O extends readonly { type: string }[]
+				? AbiOutputToTs<O>
+				: unknown
+			: unknown,
+		ContractCallError
+	>;
+};

package/src/services/Contract/estimateGas.test.ts

@@ -0,0 +1,124 @@
+// @ts-nocheck - TODO: Fix ABI type inference issues
+import { beforeEach, describe, expect, it, vi } from "@effect/vitest";
+import { Address, BrandedAbi } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as S from "effect/Schema";
+import { fromArray } from "../../primitives/Abi/AbiSchema.js";
+import { ProviderService } from "../Provider/index.js";
+import { Contract } from "./Contract.js";
+
+type HexType = `0x${string}`;
+
+const testAddress = Address("0x6B175474E89094C44Da98b954EecdEfaE6E286AB");
+
+const erc20Abi = S.decodeUnknownSync(fromArray)([
+	{
+		type: "function",
+		name: "transfer",
+		stateMutability: "nonpayable",
+		inputs: [
+			{ name: "to", type: "address" },
+			{ name: "amount", type: "uint256" },
+		],
+		outputs: [{ name: "success", type: "bool" }],
+	},
+	{
+		type: "function",
+		name: "deposit",
+		stateMutability: "payable",
+		inputs: [],
+		outputs: [],
+	},
+]);
+
+const mockProvider = {
+	estimateGas: vi.fn(),
+};
+
+const MockProviderLayer = Layer.succeed(ProviderService, mockProvider as any);
+
+describe("Contract.estimateGas", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("encodes data and calls provider.estimateGas", async () => {
+		const recipient = Address("0x1234567890123456789012345678901234567890");
+		const amount = 1000n;
+		mockProvider.estimateGas.mockReturnValue(Effect.succeed(45000n));
+
+		const program = Effect.gen(function* () {
+			const contract = yield* Contract(testAddress, erc20Abi);
+			return yield* Contract.estimateGas(contract, "transfer", [
+				recipient,
+				amount,
+			]);
+		});
+
+		const gas = await Effect.runPromise(
+			program.pipe(Effect.provide(MockProviderLayer)),
+		);
+
+		expect(gas).toBe(45000n);
+		expect(mockProvider.estimateGas).toHaveBeenCalledTimes(1);
+
+		const callArgs = mockProvider.estimateGas.mock.calls[0][0];
+		const expectedData = BrandedAbi.encodeFunction(
+			erc20Abi as unknown as BrandedAbi.Abi,
+			"transfer",
+			[recipient, amount],
+		);
+
+		expect(callArgs.to).toBe(Address.toHex(testAddress));
+		expect(callArgs.data as HexType).toBe(expectedData as HexType);
+	});
+
+	it("passes value for payable methods", async () => {
+		const value = 1000000000000000000n;
+		mockProvider.estimateGas.mockReturnValue(Effect.succeed(21000n));
+
+		const program = Effect.gen(function* () {
+			const contract = yield* Contract(testAddress, erc20Abi);
+			return yield* Contract.estimateGas(contract, "deposit", [{ value }]);
+		});
+
+		await Effect.runPromise(program.pipe(Effect.provide(MockProviderLayer)));
+
+		const callArgs = mockProvider.estimateGas.mock.calls[0][0];
+		const expectedData = BrandedAbi.encodeFunction(
+			erc20Abi as unknown as BrandedAbi.Abi,
+			"deposit",
+			[],
+		);
+
+		expect(callArgs.data as HexType).toBe(expectedData as HexType);
+		expect(callArgs.value).toBe(value);
+	});
+
+	it("maps provider errors to ContractCallError", async () => {
+		const recipient = Address("0x1234567890123456789012345678901234567890");
+		mockProvider.estimateGas.mockReturnValue(
+			Effect.fail(new Error("estimate failed")),
+		);
+
+		const program = Effect.gen(function* () {
+			const contract = yield* Contract(testAddress, erc20Abi);
+			return yield* Contract.estimateGas(contract, "transfer", [
+				recipient,
+				1000n,
+			]);
+		}).pipe(
+			Effect.catchTag("ContractCallError", (e) =>
+				Effect.succeed(`caught: ${e.message}`),
+			),
+		);
+
+		const result = await Effect.runPromise(
+			program.pipe(Effect.provide(MockProviderLayer)),
+		);
+
+		expect(result).toContain("caught:");
+		expect(result).toContain("estimate failed");
+	});
+});

package/src/services/Contract/estimateGas.ts

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Contract gas estimation helper.
+ *
+ * @module Contract/estimateGas
+ * @since 0.0.1
+ */
+
+import { Address, BrandedAbi, type BrandedAddress } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../Provider/index.js";
+import {
+	type Abi,
+	type AbiItem,
+	ContractCallError,
+	type ContractInstance,
+	type WriteOptions,
+} from "./ContractTypes.js";
+
+type AddressType = BrandedAddress.AddressType;
+
+type WriteMethodName<TAbi extends Abi> = keyof ContractInstance<TAbi>["write"];
+
+type WriteMethodArgs<
+	TAbi extends Abi,
+	TFunctionName extends WriteMethodName<TAbi>,
+> = ContractInstance<TAbi>["write"][TFunctionName] extends (
+	...args: infer P
+) => unknown
+	? P
+	: never;
+
+const isWriteOptions = (value: unknown): value is WriteOptions =>
+	value !== null &&
+	typeof value === "object" &&
+	!Array.isArray(value) &&
+	("value" in value ||
+		"gas" in value ||
+		"gasPrice" in value ||
+		"maxFeePerGas" in value ||
+		"maxPriorityFeePerGas" in value ||
+		"nonce" in value);
+
+const getAddressHex = (address: AddressType | `0x${string}`): `0x${string}` =>
+	(typeof address === "string"
+		? address
+		: Address.toHex(address as AddressType)) as `0x${string}`;
+
+const findFunctionInputs = (
+	abiItems: readonly AbiItem[],
+	functionName: string,
+	argLength: number,
+) => {
+	const matches = abiItems.filter(
+		(item): item is AbiItem & { name: string } =>
+			item.type === "function" && item.name === functionName,
+	);
+	if (matches.length === 0) return undefined;
+
+	const exact = matches.find((fn) => (fn.inputs?.length ?? 0) === argLength);
+	if (exact) return exact.inputs ?? [];
+
+	const withOptions = matches.find(
+		(fn) => (fn.inputs?.length ?? 0) + 1 === argLength,
+	);
+	if (withOptions) return withOptions.inputs ?? [];
+
+	return matches[0].inputs ?? [];
+};
+
+/**
+ * Estimates gas for a contract method call.
+ *
+ * @param contract - Contract instance
+ * @param methodName - Method to estimate gas for
+ * @param args - Method arguments (optionally ending with write options)
+ * @returns Effect yielding estimated gas
+ *
+ * @example
+ * ```typescript
+ * const gas = yield* Contract.estimateGas(token, "transfer", [to, amount])
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const estimateGas = <
+	TAbi extends Abi,
+	TFunctionName extends WriteMethodName<TAbi>,
+>(
+	contract: ContractInstance<TAbi>,
+	methodName: TFunctionName,
+	args?: WriteMethodArgs<TAbi, TFunctionName>,
+): Effect.Effect<bigint, ContractCallError, ProviderService> =>
+	Effect.gen(function* () {
+		const provider = yield* ProviderService;
+		const addressHex = getAddressHex(contract.address as AddressType);
+		const abiItems = contract.abi as readonly AbiItem[];
+		const functionLabel = String(methodName);
+		const inputArgs = (args ?? []) as readonly unknown[];
+
+		const inputs = findFunctionInputs(
+			abiItems,
+			functionLabel,
+			inputArgs.length,
+		);
+		if (!inputs) {
+			return yield* Effect.fail(
+				new ContractCallError(
+					{ address: addressHex, method: functionLabel, args: inputArgs },
+					`Function ${functionLabel} not found in ABI`,
+				),
+			);
+		}
+
+		const inputCount = inputs.length;
+		const lastArg = inputArgs[inputArgs.length - 1];
+		const hasOptions = isWriteOptions(lastArg) && inputArgs.length > inputCount;
+
+		const callArgs = hasOptions ? inputArgs.slice(0, -1) : inputArgs;
+		const options = hasOptions ? (lastArg as WriteOptions) : undefined;
+
+		const data = yield* Effect.try({
+			try: () =>
+				BrandedAbi.encodeFunction(
+					abiItems as unknown as BrandedAbi.Abi,
+					functionLabel,
+					callArgs,
+				),
+			catch: (e) =>
+				new ContractCallError(
+					{
+						address: addressHex,
+						method: functionLabel,
+						args: callArgs,
+						value: options?.value,
+					},
+					e instanceof Error ? e.message : "Encode error",
+					{ cause: e instanceof Error ? e : undefined },
+				),
+		});
+
+		return yield* provider
+			.estimateGas({
+				to: addressHex,
+				data,
+				value: options?.value,
+				gas: options?.gas,
+			})
+			.pipe(
+				Effect.mapError(
+					(e) =>
+						new ContractCallError(
+							{
+								address: addressHex,
+								method: functionLabel,
+								args: callArgs,
+								value: options?.value,
+							},
+							e.message,
+							{ cause: e },
+						),
+				),
+			);
+	});