voltaire-effect 0.2.23

package/src/services/Provider/index.ts

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Provider module exports for read-only blockchain operations.
+ *
+ * @module Provider
+ * @since 0.0.1
+ *
+ * @description
+ * This module provides the provider service for querying Ethereum
+ * blockchain data. It includes the service definition, layer implementation,
+ * and all related types.
+ *
+ * Main exports:
+ * - {@link ProviderService} - The service tag/interface
+ * - {@link Provider} - The live implementation layer
+ * - {@link ProviderResponseError} - Invalid or unexpected responses
+ * - {@link ProviderNotFoundError} - Missing resources
+ * - {@link ProviderValidationError} - Invalid inputs
+ * - {@link ProviderTimeoutError} - Timeout while waiting
+ *
+ * Type exports:
+ * - {@link BlockTag} - Block identifier type
+ * - {@link BlockType} - Block data structure
+ * - {@link TransactionType} - Transaction data structure
+ * - {@link ReceiptType} - Transaction receipt structure
+ * - {@link LogType} - Event log structure
+ * - {@link CallRequest} - eth_call parameters
+ * - {@link LogFilter} - eth_getLogs parameters
+ *
+ * @example Typical usage
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import {
+ *   ProviderService,
+ *   Provider,
+ *   HttpTransport
+ * } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const provider = yield* ProviderService
+ *   return yield* provider.getBlockNumber()
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ *
+ * @see {@link TransportService} - Required dependency for RPC communication
+ */
+
+// Re-export block streaming types for convenience
+export type {
+	BackfillOptions,
+	BlockInclude,
+	BlockStreamEvent,
+	BlocksEvent,
+	WatchOptions,
+} from "@tevm/voltaire/block";
+export { Account } from "./Account.js";
+export { AccountService, type AccountShape } from "./AccountService.js";
+export {
+	type ContractCall,
+	type MulticallParams,
+	type MulticallResults,
+	multicall,
+	type SimulateContractParams,
+	type SimulateContractResult,
+	type StateOverride,
+	simulateContract,
+} from "./actions/index.js";
+export {
+	type Abi,
+	type ReadContractParams,
+	readContract,
+} from "./actions/readContract.js";
+export { Blocks } from "./Blocks.js";
+export { BlocksService, type BlocksShape } from "./BlocksService.js";
+export { Events } from "./Events.js";
+export { EventsService, type EventsShape } from "./EventsService.js";
+export {
+	createBlockFilter,
+	createEventFilter,
+	createPendingTransactionFilter,
+	getFilterChanges,
+	getFilterLogs,
+	uninstallFilter,
+} from "./filters.js";
+export {
+	calculateBlobGasPrice,
+	estimateBlobGas,
+	getBlobBaseFee,
+} from "./getBlobBaseFee.js";
+export { Network } from "./Network.js";
+export {
+	NetworkService,
+	type NetworkShape,
+	type SyncingStatus,
+	type WorkResult,
+} from "./NetworkService.js";
+export { Provider } from "./Provider.js";
+export {
+	type AccessListInput,
+	type AccessListType,
+	type AddressInput,
+	type BackfillBlocksError,
+	type BlockTag,
+	type BlockType,
+	type CallError,
+	type CallRequest,
+	type CreateAccessListError,
+	type CreateBlockFilterError,
+	type CreateEventFilterError,
+	type CreatePendingTransactionFilterError,
+	type EstimateGasError,
+	type EventFilter,
+	type FeeHistoryType,
+	type FilterChanges,
+	type FilterId,
+	type GetAccountsError,
+	type GetBalanceError,
+	type GetBlobBaseFeeError,
+	type GetBlockArgs,
+	type GetBlockError,
+	type GetBlockNumberError,
+	type GetBlockReceiptsArgs,
+	type GetBlockReceiptsError,
+	type GetBlockTransactionCountArgs,
+	type GetBlockTransactionCountError,
+	type GetChainIdError,
+	type GetCodeError,
+	type GetCoinbaseError,
+	type GetFeeHistoryError,
+	type GetFilterChangesError,
+	type GetFilterLogsError,
+	type GetGasPriceError,
+	type GetHashrateError,
+	type GetLogsError,
+	type GetMaxPriorityFeePerGasError,
+	type GetMiningError,
+	type GetProofError,
+	type GetProtocolVersionError,
+	type GetStorageAtError,
+	type GetSyncingError,
+	type GetTransactionByBlockHashAndIndexError,
+	type GetTransactionByBlockNumberAndIndexError,
+	type GetTransactionConfirmationsError,
+	type GetTransactionCountError,
+	type GetTransactionError,
+	type GetTransactionReceiptError,
+	type GetUncleArgs,
+	type GetUncleCountArgs,
+	type GetUncleCountError,
+	type GetUncleError,
+	type GetWorkError,
+	type HashInput,
+	type LogFilter,
+	type LogType,
+	type NetVersionError,
+	type ProofType,
+	ProviderConfirmationsPendingError,
+	type ProviderError,
+	ProviderNotFoundError,
+	ProviderReceiptPendingError,
+	ProviderResponseError,
+	ProviderService,
+	type ProviderShape,
+	ProviderStreamError,
+	ProviderTimeoutError,
+	ProviderValidationError,
+	type ReceiptType,
+	type RpcTransactionRequest,
+	type SendRawTransactionError,
+	type SendTransactionError,
+	type SignError,
+	type SignTransactionError,
+	type SimulateV1Error,
+	type SimulateV2Error,
+	type StorageProofType,
+	type SubmitHashrateError,
+	type SubmitWorkError,
+	type SubscribeError,
+	type TransactionIndexInput,
+	type TransactionType,
+	type UncleBlockType,
+	type UninstallFilterError,
+	type UnsubscribeError,
+	type WaitForTransactionReceiptError,
+	type WatchBlocksError,
+} from "./ProviderService.js";
+export { Simulation } from "./Simulation.js";
+export {
+	type SimulateV1BlockResult,
+	type SimulateV1CallResult,
+	type SimulateV1Payload,
+	type SimulateV1Result,
+	type SimulateV2Payload,
+	type SimulateV2Result,
+	SimulationService,
+	type SimulationShape,
+} from "./SimulationService.js";
+export { Streaming } from "./Streaming.js";
+export { StreamingService, type StreamingShape } from "./StreamingService.js";
+export {
+	type AssetChange,
+	type SimulateCallsError,
+	type SimulateCallsParams,
+	type SimulationResult,
+	simulateCalls,
+} from "./simulateCalls.js";
+export { Transaction } from "./Transaction.js";
+export {
+	TransactionService,
+	type TransactionShape,
+} from "./TransactionService.js";

package/src/services/Provider/simulateCalls.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+	TransportError,
+	TransportService,
+} from "../Transport/TransportService.js";
+import { simulateCalls } from "./simulateCalls.js";
+
+const ERC20_TRANSFER_TOPIC =
+	"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" as const;
+
+const padAddressTopic = (address: string) =>
+	`0x${address.toLowerCase().replace(/^0x/, "").padStart(64, "0")}` as const;
+
+const padUint256 = (value: bigint) =>
+	`0x${value.toString(16).padStart(64, "0")}` as const;
+
+describe("simulateCalls", () => {
+	it("captures ERC20 and ETH asset changes", async () => {
+		const account = "0x1111111111111111111111111111111111111111";
+		const token = "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+		const contract = "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+		const recipient = "0x2222222222222222222222222222222222222222";
+		const internalRecipient = "0x3333333333333333333333333333333333333333";
+
+		const simulateResponse = [
+			{
+				calls: [
+					{
+						status: "0x1",
+						returnData: "0x",
+						gasUsed: "0x5208",
+						logs: [
+							{
+								address: token,
+								topics: [
+									ERC20_TRANSFER_TOPIC,
+									padAddressTopic(account),
+									padAddressTopic(recipient),
+								],
+								data: padUint256(500n),
+								blockNumber: "0x1",
+								transactionHash: "0x".padEnd(66, "0"),
+								transactionIndex: "0x0",
+								blockHash: "0x".padEnd(66, "0"),
+								logIndex: "0x0",
+								removed: false,
+							},
+						],
+					},
+				],
+			},
+		];
+
+		const traceResponse = {
+			callTrace: {
+				calls: [
+					{
+						from: contract,
+						to: internalRecipient,
+						value: "0x2",
+					},
+				],
+			},
+		};
+
+		const transport = Layer.succeed(TransportService, {
+			request: <T>(method: string) =>
+				Effect.try({
+					try: () => {
+						if (method === "eth_simulateV1") return simulateResponse as T;
+						if (method === "debug_traceCall") return traceResponse as T;
+						throw new Error(`Unexpected method: ${method}`);
+					},
+					catch: (e) =>
+						new TransportError({
+							code: -32603,
+							message: (e as Error).message,
+						}),
+				}),
+		});
+
+		const result = await Effect.runPromise(
+			simulateCalls({
+				account,
+				calls: [{ to: contract, value: 1n }],
+			}).pipe(Effect.provide(transport)),
+		);
+
+		expect(result).toHaveLength(1);
+		const [first] = result;
+		expect(first.success).toBe(true);
+		expect(first.gasUsed).toBe(21000n);
+		expect(first.returnData).toBe("0x");
+		expect(first.logs).toHaveLength(1);
+
+		expect(first.assetChanges).toHaveLength(3);
+
+		const erc20Change = first.assetChanges.find(
+			(change) => change.asset.toLowerCase() === token,
+		);
+		expect(erc20Change).toBeDefined();
+		expect(erc20Change?.from).toBe(account);
+		expect(erc20Change?.to).toBe(recipient);
+		expect(erc20Change?.amount).toBe(500n);
+		expect(erc20Change?.type).toBe("transfer");
+
+		const ethTopLevel = first.assetChanges.find(
+			(change) =>
+				change.asset === "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" &&
+				change.to === contract,
+		);
+		expect(ethTopLevel?.from).toBe(account);
+		expect(ethTopLevel?.amount).toBe(1n);
+		expect(ethTopLevel?.type).toBe("transfer");
+
+		const ethInternal = first.assetChanges.find(
+			(change) =>
+				change.asset === "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" &&
+				change.to === internalRecipient,
+		);
+		expect(ethInternal?.from).toBe(contract);
+		expect(ethInternal?.amount).toBe(2n);
+		expect(ethInternal?.type).toBe("transfer");
+	});
+});

package/src/services/Provider/simulateCalls.ts

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview Simulate multiple calls and derive asset changes.
+ *
+ * @module Provider/simulateCalls
+ * @since 0.0.1
+ */
+
+import { Address } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import { TransportError } from "../Transport/TransportError.js";
+import { TransportService } from "../Transport/TransportService.js";
+import {
+	type AddressInput,
+	type BlockTag,
+	type CallRequest,
+	type LogType,
+	ProviderResponseError,
+} from "./ProviderService.js";
+
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const;
+const NATIVE_ASSET = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" as const;
+const ERC20_TRANSFER_TOPIC =
+	"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" as const;
+
+type HexString = `0x${string}`;
+
+type SimulateV1CallResult = {
+	status: string;
+	returnData: HexString;
+	gasUsed: HexString;
+	logs?: LogType[];
+	error?: { code?: number; message?: string };
+};
+
+type SimulateV1BlockResult = {
+	calls: SimulateV1CallResult[];
+};
+
+type SimulateV1Result = SimulateV1BlockResult[];
+
+export type AssetChange = {
+	asset: HexString;
+	from: HexString;
+	to: HexString;
+	amount: bigint;
+	type: "transfer" | "mint" | "burn";
+};
+
+export type SimulationResult = {
+	success: boolean;
+	returnData: HexString;
+	gasUsed: bigint;
+	logs: LogType[];
+	assetChanges: AssetChange[];
+};
+
+export interface SimulateCallsParams {
+	readonly calls: readonly CallRequest[];
+	readonly account?: AddressInput;
+	readonly blockTag?: BlockTag;
+}
+
+/**
+ * Error union for simulateCalls.
+ */
+export type SimulateCallsError = TransportError | ProviderResponseError;
+
+type RawCallTrace = {
+	from?: string;
+	to?: string;
+	value?: string | bigint | number;
+	calls?: readonly RawCallTrace[];
+};
+
+const normalizeAddress = (
+	input?: AddressInput | string | null,
+): HexString | undefined => {
+	if (!input) return undefined;
+	const hex = typeof input === "string" ? input : Address.toHex(input);
+	return hex.toLowerCase() as HexString;
+};
+
+const toHexQuantity = (value: bigint): HexString =>
+	`0x${value.toString(16)}` as HexString;
+
+const parseHexToBigInt = (value?: string | bigint | number | null): bigint => {
+	if (typeof value === "bigint") return value;
+	if (typeof value === "number") return BigInt(value);
+	if (typeof value !== "string") return 0n;
+	if (value === "0x" || value === "") return 0n;
+	try {
+		return BigInt(value);
+	} catch {
+		return 0n;
+	}
+};
+
+const topicToAddress = (topic: string): HexString | undefined => {
+	if (!topic.startsWith("0x")) return undefined;
+	const hex = topic.slice(2).toLowerCase();
+	if (hex.length < 40) return undefined;
+	const padded = hex.padStart(64, "0");
+	return `0x${padded.slice(24)}` as HexString;
+};
+
+const classifyTransfer = (from: HexString, to: HexString) => {
+	if (from === ZERO_ADDRESS) return "mint" as const;
+	if (to === ZERO_ADDRESS) return "burn" as const;
+	return "transfer" as const;
+};
+
+const formatCall = (call: CallRequest, account?: AddressInput) => {
+	const formatted: Record<string, unknown> = {};
+	const from = normalizeAddress(call.from ?? account);
+	const to = normalizeAddress(call.to ?? undefined);
+	if (from) formatted.from = from;
+	if (to) formatted.to = to;
+	if (call.data) formatted.data = call.data as HexString;
+	if (call.value !== undefined) formatted.value = toHexQuantity(call.value);
+	if (call.gas !== undefined) formatted.gas = toHexQuantity(call.gas);
+	return formatted;
+};
+
+const extractCallTrace = (trace: unknown): RawCallTrace | null => {
+	if (!trace || typeof trace !== "object") return null;
+	const maybe = trace as { callTrace?: unknown; result?: unknown };
+	if (maybe.callTrace && typeof maybe.callTrace === "object") {
+		return maybe.callTrace as RawCallTrace;
+	}
+	if (maybe.result && typeof maybe.result === "object") {
+		return maybe.result as RawCallTrace;
+	}
+	return trace as RawCallTrace;
+};
+
+const collectTraceTransfers = (calls?: readonly RawCallTrace[]) => {
+	if (!calls || calls.length === 0) return [] as AssetChange[];
+	const changes: AssetChange[] = [];
+	for (const call of calls) {
+		const from = normalizeAddress(call.from ?? undefined);
+		const to = normalizeAddress(call.to ?? undefined);
+		const amount = parseHexToBigInt(call.value ?? undefined);
+		if (amount > 0n && from && to) {
+			changes.push({
+				asset: NATIVE_ASSET,
+				from,
+				to,
+				amount,
+				type: classifyTransfer(from, to),
+			});
+		}
+		if (call.calls && call.calls.length > 0) {
+			changes.push(...collectTraceTransfers(call.calls));
+		}
+	}
+	return changes;
+};
+
+const extractErc20Transfers = (logs: LogType[]): AssetChange[] => {
+	const changes: AssetChange[] = [];
+	for (const log of logs) {
+		const topic = log.topics?.[0]?.toLowerCase();
+		if (topic !== ERC20_TRANSFER_TOPIC) continue;
+		const from = topicToAddress(log.topics[1] ?? "");
+		const to = topicToAddress(log.topics[2] ?? "");
+		if (!from || !to) continue;
+		const amount = parseHexToBigInt(log.data);
+		changes.push({
+			asset: normalizeAddress(log.address) ?? (log.address as HexString),
+			from,
+			to,
+			amount,
+			type: classifyTransfer(from, to),
+		});
+	}
+	return changes;
+};
+
+const extractCallValueTransfer = (
+	call: CallRequest,
+	account?: AddressInput,
+): AssetChange | null => {
+	const amount = call.value ?? 0n;
+	if (amount <= 0n) return null;
+	const from = normalizeAddress(call.from ?? account);
+	const to = normalizeAddress(call.to ?? undefined);
+	if (!from || !to) return null;
+	return {
+		asset: NATIVE_ASSET,
+		from,
+		to,
+		amount,
+		type: classifyTransfer(from, to),
+	};
+};
+
+export const simulateCalls = (
+	params: SimulateCallsParams,
+): Effect.Effect<SimulationResult[], SimulateCallsError, TransportService> =>
+	Effect.gen(function* () {
+		const transport = yield* TransportService;
+		const blockTag = params.blockTag ?? "latest";
+
+		const request = <T>(method: string, rpcParams?: unknown[]) =>
+			transport.request<T>(method, rpcParams).pipe(
+				Effect.mapError(
+					(error) =>
+						new TransportError(error.input, error.message, {
+							cause: error,
+							context: { method, params: rpcParams },
+						}),
+				),
+			);
+
+		const formattedCalls = params.calls.map((call) =>
+			formatCall(call, params.account),
+		);
+		const payload = { blockStateCalls: [{ calls: formattedCalls }] };
+		const simulateParams = [payload, blockTag];
+		const response = yield* request<SimulateV1Result>(
+			"eth_simulateV1",
+			simulateParams,
+		);
+
+		if (!Array.isArray(response) || response.length === 0) {
+			return yield* Effect.fail(
+				new ProviderResponseError(
+					{ method: "eth_simulateV1", response },
+					"Invalid response from eth_simulateV1",
+				),
+			);
+		}
+
+		const blockResult = response[0];
+		if (!blockResult || !Array.isArray(blockResult.calls)) {
+			return yield* Effect.fail(
+				new ProviderResponseError(
+					{ method: "eth_simulateV1", response },
+					"Missing call results in eth_simulateV1 response",
+				),
+			);
+		}
+
+		const traceResults = yield* Effect.forEach(
+			params.calls,
+			(call) =>
+				request<unknown>("debug_traceCall", [
+					formatCall(call, params.account),
+					blockTag,
+					{ tracer: "callTracer" },
+				]).pipe(Effect.catchAll(() => Effect.succeed(null))),
+			{ concurrency: "unbounded" },
+		);
+
+		return params.calls.map((call, index) => {
+			const result = blockResult.calls[index];
+			const success = result?.status?.toLowerCase() === "0x1";
+			const returnData = result?.returnData ?? "0x";
+			const gasUsed = parseHexToBigInt(result?.gasUsed ?? "0x0");
+			const logs = success && Array.isArray(result?.logs) ? result.logs : [];
+
+			const assetChanges: AssetChange[] = [];
+			assetChanges.push(...extractErc20Transfers(logs));
+
+			const valueTransfer = extractCallValueTransfer(call, params.account);
+			if (valueTransfer) assetChanges.push(valueTransfer);
+
+			const trace = extractCallTrace(traceResults[index]);
+			if (trace?.calls?.length) {
+				assetChanges.push(...collectTraceTransfers(trace.calls));
+			}
+
+			return {
+				success,
+				returnData,
+				gasUsed,
+				logs,
+				assetChanges,
+			};
+		});
+	});