voltaire-effect 0.2.23

package/src/services/Provider/REFACTOR_PLAN.md

@@ -0,0 +1,203 @@
+# ProviderService Refactor Plan
+
+## Goal
+Split monolithic ProviderService into focused, composable services with comprehensive JSON-RPC coverage.
+
+## New Service Architecture
+
+### Core Services (split from ProviderService)
+
+#### 1. BlocksService
+- `getBlock(args)` - eth_getBlockByNumber, eth_getBlockByHash
+- `getBlockNumber()` - eth_blockNumber
+- `getBlockTransactionCount(args)` - eth_getBlockTransactionCountByNumber, eth_getBlockTransactionCountByHash
+- `getUncle(args, uncleIndex)` - eth_getUncleByBlockNumberAndIndex, eth_getUncleByBlockHashAndIndex
+- `getBlockReceipts(blockTag)` - eth_getBlockReceipts
+
+#### 2. AccountService
+- `getBalance(address, blockTag?)` - eth_getBalance
+- `getTransactionCount(address, blockTag?)` - eth_getTransactionCount
+- `getCode(address, blockTag?)` - eth_getCode
+- `getStorageAt(address, slot, blockTag?)` - eth_getStorageAt
+- `getProof(address, storageKeys, blockTag?)` - eth_getProof
+
+#### 3. TransactionService
+- `getTransaction(hash)` - eth_getTransactionByHash
+- `getTransactionByBlockHashAndIndex(blockHash, index)` - eth_getTransactionByBlockHashAndIndex
+- `getTransactionByBlockNumberAndIndex(blockNumber, index)` - eth_getTransactionByBlockNumberAndIndex
+- `getTransactionReceipt(hash)` - eth_getTransactionReceipt
+- `waitForTransactionReceipt(hash, opts?)` - polling wrapper
+- `sendRawTransaction(signedTx)` - eth_sendRawTransaction
+- `getTransactionConfirmations(hash)` - computed from block difference
+
+#### 4. SimulationService
+- `call(tx, blockTag?, stateOverride?, blockOverrides?)` - eth_call
+- `estimateGas(tx, blockTag?, stateOverride?)` - eth_estimateGas
+- `createAccessList(tx)` - eth_createAccessList
+- `simulateV1(payload, blockTag?)` - eth_simulateV1 (multi-block simulation with state/block overrides)
+
+#### 5. EventsService
+- `getLogs(filter)` - eth_getLogs
+- `createEventFilter(filter?)` - eth_newFilter
+- `createBlockFilter()` - eth_newBlockFilter
+- `createPendingTransactionFilter()` - eth_newPendingTransactionFilter
+- `getFilterChanges(filterId)` - eth_getFilterChanges
+- `getFilterLogs(filterId)` - eth_getFilterLogs
+- `uninstallFilter(filterId)` - eth_uninstallFilter
+
+#### 6. NetworkService
+- `getChainId()` - eth_chainId
+- `getGasPrice()` - eth_gasPrice
+- `getMaxPriorityFeePerGas()` - eth_maxPriorityFeePerGas
+- `getFeeHistory(blockCount, newestBlock, rewardPercentiles)` - eth_feeHistory
+- `getBlobBaseFee()` - eth_blobBaseFee
+- `getSyncing()` - eth_syncing
+- `getAccounts()` - eth_accounts
+- `getCoinbase()` - eth_coinbase
+- `netVersion()` - net_version
+
+#### 7. StreamingService
+- `watchBlocks(options?)` - Stream of new blocks with reorg detection
+- `backfillBlocks(options)` - Stream of historical blocks
+
+### New Services
+
+#### 8. DebugService
+- `traceTransaction(hash, config?)` - debug_traceTransaction
+- `traceCall(tx, blockRef?, config?)` - debug_traceCall
+- `traceBlockByNumber(blockNumber, config?)` - debug_traceBlockByNumber
+- `traceBlockByHash(blockHash, config?)` - debug_traceBlockByHash
+- `getBadBlocks()` - debug_getBadBlocks
+- `getRawBlock(blockTag)` - debug_getRawBlock
+- `getRawHeader(blockTag)` - debug_getRawHeader
+- `getRawReceipts(blockTag)` - debug_getRawReceipts
+- `getRawTransaction(hash)` - debug_getRawTransaction
+- `storageRangeAt(blockHash, txIndex, address, startKey, maxResults)` - debug_storageRangeAt
+
+#### 9. EngineApiService (for consensus layer integration)
+- `newPayloadV3(executionPayload, expectedBlobVersionedHashes, parentBeaconBlockRoot)` - engine_newPayloadV3
+- `newPayloadV4(...)` - engine_newPayloadV4
+- `newPayloadV5(...)` - engine_newPayloadV5
+- `forkchoiceUpdatedV3(forkchoiceState, payloadAttributes?)` - engine_forkchoiceUpdatedV3
+- `getPayloadV3(payloadId)` - engine_getPayloadV3
+- `getPayloadV4(payloadId)` - engine_getPayloadV4
+- `getPayloadV5(payloadId)` - engine_getPayloadV5
+- `getPayloadV6(payloadId)` - engine_getPayloadV6
+- `getPayloadBodiesByHashV1(blockHashes)` - engine_getPayloadBodiesByHashV1
+- `getPayloadBodiesByRangeV1(start, count)` - engine_getPayloadBodiesByRangeV1
+- `getBlobsV1(versionedHashes)` - engine_getBlobsV1
+- `getBlobsV2(...)` - engine_getBlobsV2
+- `getBlobsV3(...)` - engine_getBlobsV3
+- `exchangeCapabilities(capabilities)` - engine_exchangeCapabilities
+
+### ProviderService (Composition)
+ProviderService becomes a convenience type that combines all core services:
+```typescript
+export type ProviderShape = 
+  BlocksShape & 
+  AccountShape & 
+  TransactionShape & 
+  SimulationShape & 
+  EventsShape & 
+  NetworkShape & 
+  StreamingShape;
+```
+
+## File Structure
+```
+services/
+├── Blocks/
+│   ├── BlocksService.ts      # Service definition
+│   ├── Blocks.ts             # Live implementation
+│   ├── index.ts
+│   └── Blocks.test.ts
+├── Account/
+│   ├── AccountService.ts
+│   ├── Account.ts
+│   ├── index.ts
+│   └── Account.test.ts
+├── Transaction/
+│   ├── TransactionService.ts
+│   ├── Transaction.ts
+│   ├── index.ts
+│   └── Transaction.test.ts
+├── Simulation/
+│   ├── SimulationService.ts
+│   ├── Simulation.ts
+│   ├── simulateV1.ts         # eth_simulateV1 implementation
+│   ├── index.ts
+│   └── Simulation.test.ts
+├── Events/
+│   ├── EventsService.ts
+│   ├── Events.ts
+│   ├── index.ts
+│   └── Events.test.ts
+├── Network/
+│   ├── NetworkService.ts
+│   ├── Network.ts
+│   ├── index.ts
+│   └── Network.test.ts
+├── Streaming/
+│   ├── StreamingService.ts
+│   ├── Streaming.ts
+│   ├── index.ts
+│   └── Streaming.test.ts
+├── Debug/
+│   ├── DebugService.ts
+│   ├── Debug.ts
+│   ├── index.ts
+│   └── Debug.test.ts
+├── Engine/
+│   ├── EngineApiService.ts
+│   ├── EngineApi.ts
+│   ├── index.ts
+│   └── EngineApi.test.ts
+├── Provider/
+│   ├── ProviderService.ts    # Composition of all services
+│   ├── Provider.ts           # Convenience layer combining all
+│   └── index.ts
+```
+
+## eth_simulateV1 Specification
+Multi-block transaction simulation with state/block overrides:
+
+```typescript
+interface SimulatePayload {
+  blockStateCalls: SimBlock[];
+  traceTransfers?: boolean;
+  validation?: boolean;
+  returnFullTransactions?: boolean;
+}
+
+interface SimBlock {
+  blockOverrides?: BlockOverrides;
+  stateOverrides?: StateOverride;
+  calls: CallRequest[];
+}
+
+interface SimulatedBlock {
+  baseFeePerGas: bigint;
+  blobGasUsed: bigint;
+  calls: SimCallResult[];
+  gasLimit: bigint;
+  gasUsed: bigint;
+  hash: `0x${string}`;
+  number: bigint;
+  timestamp: bigint;
+}
+
+interface SimCallResult {
+  returnData: `0x${string}`;
+  logs: Log[];
+  gasUsed: bigint;
+  status: `0x${string}`;  // 0x1 success, 0x0 revert
+  error?: SimulateError;
+}
+```
+
+## Implementation Notes
+1. Each service is a separate Effect Context.Tag
+2. Services depend on TransportService for RPC calls
+3. Provider layer composes all service layers
+4. Backward compatibility: ProviderService interface unchanged
+5. All services follow branded types + namespace pattern

package/src/services/Provider/Simulation.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Live implementation of SimulationService using ProviderService.
+ *
+ * @module Simulation
+ * @since 0.3.0
+ */
+
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ProviderService } from "./ProviderService.js";
+import { SimulationService } from "./SimulationService.js";
+
+/**
+ * Live implementation of the Simulation layer.
+ *
+ * @since 0.3.0
+ */
+export const Simulation: Layer.Layer<
+	SimulationService,
+	never,
+	ProviderService
+> = Layer.effect(
+	SimulationService,
+	Effect.gen(function* () {
+		const provider = yield* ProviderService;
+		return {
+			call: provider.call,
+			estimateGas: provider.estimateGas,
+			createAccessList: provider.createAccessList,
+			simulateV1: provider.simulateV1,
+			simulateV2: provider.simulateV2,
+		};
+	}),
+);

package/src/services/Provider/SimulationService.ts

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Simulation service definition for call and simulation JSON-RPC methods.
+ *
+ * @module SimulationService
+ * @since 0.3.0
+ */
+
+import type { HexType } from "@tevm/voltaire/Hex";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type {
+	AccessListType,
+	BlockOverrides,
+	BlockTag,
+	CallError,
+	CallRequest,
+	CreateAccessListError,
+	EstimateGasError,
+	LogType,
+	SimulateV1Error,
+	SimulateV2Error,
+	StateOverride,
+} from "./ProviderService.js";
+
+/**
+ * Single block simulation input for eth_simulateV1.
+ *
+ * @since 0.3.0
+ */
+export interface SimulateV1BlockCall {
+	/** Optional block overrides applied during the simulation */
+	readonly blockOverrides?: BlockOverrides;
+	/** Optional state overrides applied during the simulation */
+	readonly stateOverrides?: StateOverride;
+	/** Calls to execute within the block */
+	readonly calls: readonly CallRequest[];
+}
+
+/**
+ * Payload for eth_simulateV1.
+ *
+ * @since 0.3.0
+ */
+export interface SimulateV1Payload {
+	/** Sequence of block simulations to execute */
+	readonly blockStateCalls: readonly SimulateV1BlockCall[];
+	/** Enable transfer tracing (if supported by node) */
+	readonly traceTransfers?: boolean;
+	/** Enable validation mode (if supported by node) */
+	readonly validation?: boolean;
+	/** Return full transaction objects (if supported) */
+	readonly returnFullTransactions?: boolean;
+}
+
+/**
+ * Call result from eth_simulateV1.
+ *
+ * @since 0.3.0
+ */
+export interface SimulateV1CallResult {
+	/** Call execution status (0x1 success, 0x0 revert) */
+	readonly status: `0x${string}`;
+	/** Return data (hex) */
+	readonly returnData: `0x${string}`;
+	/** Gas used (hex) */
+	readonly gasUsed: `0x${string}`;
+	/** Logs emitted by the call */
+	readonly logs?: LogType[];
+	/** Optional error information */
+	readonly error?: { code?: number; message?: string };
+}
+
+/**
+ * Simulated block result from eth_simulateV1.
+ *
+ * @since 0.3.0
+ */
+export interface SimulateV1BlockResult {
+	/** Base fee per gas (hex) */
+	readonly baseFeePerGas?: `0x${string}`;
+	/** Blob gas used (hex) */
+	readonly blobGasUsed?: `0x${string}`;
+	/** Calls executed in the block */
+	readonly calls: SimulateV1CallResult[];
+	/** Gas limit (hex) */
+	readonly gasLimit?: `0x${string}`;
+	/** Gas used (hex) */
+	readonly gasUsed?: `0x${string}`;
+	/** Simulated block hash */
+	readonly hash?: `0x${string}`;
+	/** Simulated block number (hex) */
+	readonly number?: `0x${string}`;
+	/** Simulated block timestamp (hex) */
+	readonly timestamp?: `0x${string}`;
+}
+
+/**
+ * Result type for eth_simulateV1.
+ *
+ * @since 0.3.0
+ */
+export type SimulateV1Result = SimulateV1BlockResult[];
+
+/**
+ * Payload for eth_simulateV2 (draft / evolving).
+ *
+ * @since 0.3.0
+ */
+export type SimulateV2Payload = Record<string, unknown>;
+
+/**
+ * Result type for eth_simulateV2 (draft / evolving).
+ *
+ * @since 0.3.0
+ */
+export type SimulateV2Result = unknown;
+
+/**
+ * Shape of the Simulation service.
+ *
+ * @since 0.3.0
+ */
+export type SimulationShape = {
+	/** Executes a call without sending a transaction */
+	readonly call: (
+		tx: CallRequest,
+		blockTag?: BlockTag,
+		stateOverride?: StateOverride,
+		blockOverrides?: BlockOverrides,
+	) => Effect.Effect<HexType | `0x${string}`, CallError>;
+	/** Estimates gas for a transaction */
+	readonly estimateGas: (
+		tx: CallRequest,
+		blockTag?: BlockTag,
+		stateOverride?: StateOverride,
+	) => Effect.Effect<bigint, EstimateGasError>;
+	/** Creates an access list for a transaction */
+	readonly createAccessList: (
+		tx: CallRequest,
+	) => Effect.Effect<AccessListType, CreateAccessListError>;
+	/** Simulates multiple blocks and calls (if supported) */
+	readonly simulateV1?: (
+		payload: SimulateV1Payload,
+		blockTag?: BlockTag,
+	) => Effect.Effect<SimulateV1Result, SimulateV1Error>;
+	/** Simulates with the V2 API (draft / evolving, if supported) */
+	readonly simulateV2?: <TResult = SimulateV2Result>(
+		payload: SimulateV2Payload,
+		blockTag?: BlockTag,
+	) => Effect.Effect<TResult, SimulateV2Error>;
+};
+
+/**
+ * Simulation service for call/simulation JSON-RPC operations.
+ *
+ * @since 0.3.0
+ */
+export class SimulationService extends Context.Tag("SimulationService")<
+	SimulationService,
+	SimulationShape
+>() {}

package/src/services/Provider/Streaming.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Live implementation of StreamingService using ProviderService.
+ *
+ * @module Streaming
+ * @since 0.3.0
+ */
+
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ProviderService } from "./ProviderService.js";
+import { StreamingService } from "./StreamingService.js";
+
+/**
+ * Live implementation of the Streaming layer.
+ *
+ * @since 0.3.0
+ */
+export const Streaming: Layer.Layer<StreamingService, never, ProviderService> =
+	Layer.effect(
+		StreamingService,
+		Effect.gen(function* () {
+			const provider = yield* ProviderService;
+			return {
+				watchBlocks: provider.watchBlocks,
+				backfillBlocks: provider.backfillBlocks,
+				subscribe: provider.subscribe,
+				unsubscribe: provider.unsubscribe,
+			};
+		}),
+	);

package/src/services/Provider/StreamingService.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Streaming service definition for streaming JSON-RPC calls.
+ *
+ * @module StreamingService
+ * @since 0.3.0
+ */
+
+import type {
+	BackfillOptions,
+	BlockInclude,
+	BlockStreamEvent,
+	BlocksEvent,
+	WatchOptions,
+} from "@tevm/voltaire/block";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
+import type {
+	BackfillBlocksError,
+	SubscribeError,
+	UnsubscribeError,
+	WatchBlocksError,
+} from "./ProviderService.js";
+
+/**
+ * Shape of the Streaming service.
+ *
+ * @since 0.3.0
+ */
+export type StreamingShape = {
+	/** Watch for new blocks with reorg detection */
+	readonly watchBlocks: <TInclude extends BlockInclude = "header">(
+		options?: WatchOptions<TInclude>,
+	) => Stream.Stream<BlockStreamEvent<TInclude>, WatchBlocksError>;
+	/** Backfill historical blocks */
+	readonly backfillBlocks: <TInclude extends BlockInclude = "header">(
+		options: BackfillOptions<TInclude>,
+	) => Stream.Stream<BlocksEvent<TInclude>, BackfillBlocksError>;
+	/** Subscribes to JSON-RPC streams (eth_subscribe) */
+	readonly subscribe?: (
+		subscription: string,
+		params?: readonly unknown[],
+	) => Effect.Effect<`0x${string}`, SubscribeError>;
+	/** Unsubscribes from JSON-RPC streams (eth_unsubscribe) */
+	readonly unsubscribe?: (
+		subscriptionId: `0x${string}`,
+	) => Effect.Effect<boolean, UnsubscribeError>;
+};
+
+/**
+ * Streaming service for block streams and subscriptions.
+ *
+ * @since 0.3.0
+ */
+export class StreamingService extends Context.Tag("StreamingService")<
+	StreamingService,
+	StreamingShape
+>() {}

package/src/services/Provider/Transaction.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Live implementation of TransactionService using ProviderService.
+ *
+ * @module Transaction
+ * @since 0.3.0
+ */
+
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ProviderService } from "./ProviderService.js";
+import { TransactionService } from "./TransactionService.js";
+
+/**
+ * Live implementation of the Transaction layer.
+ *
+ * @since 0.3.0
+ */
+export const Transaction: Layer.Layer<
+	TransactionService,
+	never,
+	ProviderService
+> = Layer.effect(
+	TransactionService,
+	Effect.gen(function* () {
+		const provider = yield* ProviderService;
+		return {
+			getTransaction: provider.getTransaction,
+			getTransactionReceipt: provider.getTransactionReceipt,
+			getTransactionByBlockHashAndIndex:
+				provider.getTransactionByBlockHashAndIndex,
+			getTransactionByBlockNumberAndIndex:
+				provider.getTransactionByBlockNumberAndIndex,
+			sendRawTransaction: provider.sendRawTransaction,
+			sendTransaction: provider.sendTransaction,
+			waitForTransactionReceipt: provider.waitForTransactionReceipt,
+			getTransactionConfirmations: provider.getTransactionConfirmations,
+		};
+	}),
+);

package/src/services/Provider/TransactionService.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Transaction service definition for transaction-related JSON-RPC calls.
+ *
+ * @module TransactionService
+ * @since 0.3.0
+ */
+
+import type { HexType } from "@tevm/voltaire/Hex";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type {
+	BlockTag,
+	GetTransactionByBlockHashAndIndexError,
+	GetTransactionByBlockNumberAndIndexError,
+	GetTransactionConfirmationsError,
+	GetTransactionError,
+	GetTransactionReceiptError,
+	HashInput,
+	ReceiptType,
+	RpcTransactionRequest,
+	SendRawTransactionError,
+	SendTransactionError,
+	TransactionIndexInput,
+	TransactionType,
+	WaitForTransactionReceiptError,
+} from "./ProviderService.js";
+
+/**
+ * Shape of the Transaction service.
+ *
+ * @since 0.3.0
+ */
+export type TransactionShape = {
+	/** Gets a transaction by hash */
+	readonly getTransaction: (
+		hash: HashInput,
+	) => Effect.Effect<TransactionType, GetTransactionError>;
+	/** Gets a transaction receipt */
+	readonly getTransactionReceipt: (
+		hash: HashInput,
+	) => Effect.Effect<ReceiptType, GetTransactionReceiptError>;
+	/** Gets a transaction by block hash and index (if supported) */
+	readonly getTransactionByBlockHashAndIndex?: (
+		blockHash: HashInput,
+		index: TransactionIndexInput,
+	) => Effect.Effect<TransactionType, GetTransactionByBlockHashAndIndexError>;
+	/** Gets a transaction by block number/tag and index (if supported) */
+	readonly getTransactionByBlockNumberAndIndex?: (
+		blockTag: BlockTag | bigint,
+		index: TransactionIndexInput,
+	) => Effect.Effect<TransactionType, GetTransactionByBlockNumberAndIndexError>;
+	/** Sends a signed raw transaction */
+	readonly sendRawTransaction: (
+		signedTx: HexType | `0x${string}`,
+	) => Effect.Effect<`0x${string}`, SendRawTransactionError>;
+	/** Sends a transaction via unlocked JSON-RPC account (if supported) */
+	readonly sendTransaction?: (
+		tx: RpcTransactionRequest,
+	) => Effect.Effect<`0x${string}`, SendTransactionError>;
+	/** Waits for a transaction to be confirmed */
+	readonly waitForTransactionReceipt: (
+		hash: HashInput,
+		opts?: {
+			confirmations?: number;
+			timeout?: number;
+			pollingInterval?: number;
+		},
+	) => Effect.Effect<ReceiptType, WaitForTransactionReceiptError>;
+	/** Gets the number of confirmations for a transaction */
+	readonly getTransactionConfirmations: (
+		hash: HashInput,
+	) => Effect.Effect<bigint, GetTransactionConfirmationsError>;
+};
+
+/**
+ * Transaction service for transaction-related JSON-RPC operations.
+ *
+ * @since 0.3.0
+ */
+export class TransactionService extends Context.Tag("TransactionService")<
+	TransactionService,
+	TransactionShape
+>() {}

package/src/services/Provider/actions/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Provider actions for contract interactions.
+ * @module Provider/actions
+ * @since 0.0.1
+ */
+
+export {
+	type ContractCall,
+	type MulticallError,
+	type MulticallParams,
+	type MulticallResults,
+	multicall,
+} from "./multicall.js";
+export {
+	type Abi,
+	type ReadContractError,
+	type ReadContractParams,
+	readContract,
+} from "./readContract.js";
+export {
+	type SimulateContractError,
+	type SimulateContractParams,
+	type SimulateContractResult,
+	type StateOverride,
+	simulateContract,
+} from "./simulateContract.js";