voltaire-effect 0.2.23 → 0.2.25

package/src/services/Provider/functions/waitForTransactionReceipt.ts

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview Free function to wait for a transaction receipt.
+ *
+ * @module Provider/functions/waitForTransactionReceipt
+ * @since 0.4.0
+ */
+
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import type { TransportError } from "../../Transport/TransportError.js";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type HashInput,
+	ProviderConfirmationsPendingError,
+	ProviderReceiptPendingError,
+	type ProviderResponseError,
+	ProviderTimeoutError,
+	type ReceiptType,
+} from "../types.js";
+import { parseHexToBigInt, toHashHex } from "../utils.js";
+
+/**
+ * Options for waiting for a transaction receipt.
+ */
+export interface WaitForTransactionReceiptOptions {
+	readonly confirmations?: number;
+	readonly timeout?: number;
+	readonly pollingInterval?: number;
+}
+
+/**
+ * Waits for a transaction to be mined and confirmed.
+ *
+ * @param hash - The transaction hash
+ * @param opts - Options for confirmations, timeout, and polling interval
+ * @returns Effect yielding the transaction receipt
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { waitForTransactionReceipt, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const receipt = yield* waitForTransactionReceipt('0x...', {
+ *     confirmations: 3,
+ *     timeout: 60000
+ *   })
+ *   console.log(`Transaction mined in block ${receipt.blockNumber}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const waitForTransactionReceipt = (
+	hash: HashInput,
+	opts?: WaitForTransactionReceiptOptions,
+): Effect.Effect<
+	ReceiptType,
+	TransportError | ProviderResponseError | ProviderTimeoutError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		Effect.gen(function* () {
+			const confirmations = opts?.confirmations ?? 1;
+			const timeout = opts?.timeout ?? 120_000;
+			const pollingInterval = opts?.pollingInterval ?? 4_000;
+			const hashHex = toHashHex(hash);
+
+			const pollReceipt = svc
+				.request<ReceiptType | null>("eth_getTransactionReceipt", [hashHex])
+				.pipe(
+					Effect.flatMap((receipt) =>
+						receipt
+							? Effect.succeed(receipt)
+							: Effect.fail(
+									new ProviderReceiptPendingError(hash, "Transaction pending"),
+								),
+					),
+				);
+
+			const receipt = yield* pollReceipt.pipe(
+				Effect.retry(
+					Schedule.spaced(Duration.millis(pollingInterval)).pipe(
+						Schedule.intersect(Schedule.recurUpTo(Duration.millis(timeout))),
+						Schedule.whileInput(
+							(e) =>
+								(e as ProviderReceiptPendingError)._tag ===
+								"ProviderReceiptPendingError",
+						),
+					),
+				),
+				Effect.catchTag("ProviderReceiptPendingError", () =>
+					Effect.fail(
+						new ProviderTimeoutError(
+							hash,
+							"Timeout waiting for transaction receipt",
+							{ timeoutMs: timeout },
+						),
+					),
+				),
+				Effect.timeoutFail({
+					duration: Duration.millis(timeout),
+					onTimeout: () =>
+						new ProviderTimeoutError(
+							hash,
+							"Timeout waiting for transaction receipt",
+							{ timeoutMs: timeout },
+						),
+				}),
+			);
+
+			if (confirmations <= 1) {
+				return receipt;
+			}
+
+			const receiptBlockNumber = yield* parseHexToBigInt({
+				method: "eth_getTransactionReceipt",
+				params: [hashHex],
+				response: receipt.blockNumber,
+			});
+			const targetBlock = receiptBlockNumber + BigInt(confirmations - 1);
+
+			const pollConfirmations = Effect.gen(function* () {
+				const currentBlockHex = yield* svc.request<string>("eth_blockNumber");
+				const currentBlock = yield* parseHexToBigInt({
+					method: "eth_blockNumber",
+					response: currentBlockHex,
+				});
+				if (currentBlock >= targetBlock) {
+					return receipt;
+				}
+				return yield* Effect.fail(
+					new ProviderConfirmationsPendingError(hash, "Waiting for confirmations"),
+				);
+			});
+
+			return yield* pollConfirmations.pipe(
+				Effect.retry(
+					Schedule.spaced(Duration.millis(pollingInterval)).pipe(
+						Schedule.intersect(Schedule.recurUpTo(Duration.millis(timeout))),
+						Schedule.whileInput(
+							(e) =>
+								(e as ProviderConfirmationsPendingError)._tag ===
+								"ProviderConfirmationsPendingError",
+						),
+					),
+				),
+				Effect.catchTag("ProviderConfirmationsPendingError", () =>
+					Effect.fail(
+						new ProviderTimeoutError(hash, "Timeout waiting for confirmations", {
+							timeoutMs: timeout,
+						}),
+					),
+				),
+				Effect.timeoutFail({
+					duration: Duration.millis(timeout),
+					onTimeout: () =>
+						new ProviderTimeoutError(hash, "Timeout waiting for confirmations", {
+							timeoutMs: timeout,
+						}),
+				}),
+			);
+		}),
+	);

package/src/services/Provider/functions/watchBlocks.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Free function to watch for new blocks with reorg detection.
+ *
+ * @module Provider/functions/watchBlocks
+ * @since 0.4.0
+ */
+
+import {
+	type BlockInclude,
+	type BlockStreamEvent,
+	BlockStream as CoreBlockStream,
+	type WatchOptions,
+} from "@tevm/voltaire/block";
+import * as Effect from "effect/Effect";
+import * as Runtime from "effect/Runtime";
+import * as Stream from "effect/Stream";
+import { TransportError } from "../../Transport/TransportError.js";
+import { ProviderService } from "../ProviderService.js";
+import { ProviderStreamError, type WatchBlocksError } from "../types.js";
+
+/**
+ * Watches for new blocks with reorg detection.
+ *
+ * Uses the core BlockStream to continuously poll for new blocks,
+ * tracking chain state to detect and report reorganizations.
+ *
+ * @param options - Watch options including optional fromBlock and include level
+ * @returns Stream yielding BlockStreamEvents (blocks or reorg events)
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Stream } from 'effect'
+ * import { watchBlocks, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = watchBlocks({ include: 'transactions' }).pipe(
+ *   Stream.tap((event) =>
+ *     Effect.sync(() => {
+ *       if (event.type === 'reorg') {
+ *         console.log('Reorg detected:', event.removed.length, 'blocks removed')
+ *       } else {
+ *         console.log('New blocks:', event.blocks.length)
+ *       }
+ *     })
+ *   ),
+ *   Stream.take(10),
+ *   Stream.runDrain,
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const watchBlocks = <TInclude extends BlockInclude = "header">(
+	options?: WatchOptions<TInclude>,
+): Stream.Stream<BlockStreamEvent<TInclude>, WatchBlocksError, ProviderService> =>
+	Stream.unwrap(
+		Effect.gen(function* () {
+			const svc = yield* ProviderService;
+			const runtime = yield* Effect.runtime<never>();
+			const provider = {
+				request: async ({
+					method,
+					params,
+				}: {
+					method: string;
+					params?: unknown[];
+				}) =>
+					Runtime.runPromise(runtime)(svc.request(method, params)),
+				on: () => {},
+				removeListener: () => {},
+			};
+			const coreStream = CoreBlockStream({ provider: provider as any });
+			const cleanup = () => {
+				(coreStream as unknown as { destroy?: () => void }).destroy?.();
+			};
+			return Stream.acquireRelease(
+				Effect.sync(() => coreStream.watch(options)),
+				() => Effect.sync(cleanup),
+			).pipe(
+				Stream.flatMap((generator) =>
+					Stream.fromAsyncIterable(
+						{ [Symbol.asyncIterator]: () => generator },
+						(error) =>
+							error instanceof TransportError
+								? error
+								: new ProviderStreamError(
+										{ method: "watchBlocks", options },
+										error instanceof Error
+											? error.message
+											: "BlockStream error",
+										{ cause: error instanceof Error ? error : undefined },
+									),
+					),
+				),
+			);
+		}),
+	);

package/src/services/Provider/index.ts

@@ -3,48 +3,6 @@
  *
  * @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
@@ -55,150 +13,36 @@ export type {
 	BlocksEvent,
 	WatchOptions,
 } from "@tevm/voltaire/block";
-export { Account } from "./Account.js";
-export { AccountService, type AccountShape } from "./AccountService.js";
+
+// Free functions (all blockchain operations)
+export * from "./functions/index.js";
+
+// Types and errors
+export * from "./types.js";
+
+// Service and layer
+export { ProviderService, type ProviderShape } from "./ProviderService.js";
+export { Provider } from "./Provider.js";
+
+// Contract actions
 export {
 	type ContractCall,
+	type MulticallError,
 	type MulticallParams,
 	type MulticallResults,
 	multicall,
+	type SimulateContractError,
 	type SimulateContractParams,
 	type SimulateContractResult,
 	type StateOverride,
 	simulateContract,
-} from "./actions/index.js";
-export {
 	type Abi,
+	type ReadContractError,
 	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";
+} from "./actions/index.js";
+
+// Simulate calls
 export {
 	type AssetChange,
 	type SimulateCallsError,
@@ -206,8 +50,15 @@ export {
 	type SimulationResult,
 	simulateCalls,
 } from "./simulateCalls.js";
-export { Transaction } from "./Transaction.js";
+
+// Utils
 export {
-	TransactionService,
-	type TransactionShape,
-} from "./TransactionService.js";
+	bytesToHex,
+	formatAccessList,
+	formatCallRequest,
+	formatLogFilterParams,
+	formatTransactionRequest,
+	parseHexToBigInt,
+	toAddressHex,
+	toHashHex,
+} from "./utils.js";