voltaire-effect 0.2.23 → 0.2.25

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

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Free function to execute eth_call.
+ *
+ * @module Provider/functions/call
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { BlockTag, CallRequest, CallError } from "../types.js";
+import { formatCallRequest } from "../utils.js";
+
+/**
+ * Executes a call without sending a transaction.
+ *
+ * @param request - The call request parameters
+ * @param blockTag - Block to execute against (default: "latest")
+ * @returns Effect yielding the call result as hex string
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { call, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const result = yield* call({
+ *     to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *     data: '0x70a08231000000000000000000000000d8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
+ *   })
+ *   console.log(`Result: ${result}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const call = (
+	request: CallRequest,
+	blockTag: BlockTag = "latest",
+): Effect.Effect<`0x${string}`, CallError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<`0x${string}`>("eth_call", [formatCallRequest(request), blockTag]),
+	);

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

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Free function to create an access list for a transaction.
+ *
+ * @module Provider/functions/createAccessList
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { BlockTag, CallRequest, CreateAccessListError, AccessListType } from "../types.js";
+import { formatCallRequest } from "../utils.js";
+
+/**
+ * Result from createAccessList containing access list and gas used.
+ */
+export interface CreateAccessListResult {
+	readonly accessList: AccessListType["accessList"];
+	readonly gasUsed: bigint;
+}
+
+/**
+ * Creates an access list for a transaction.
+ *
+ * @param request - The call request parameters
+ * @param blockTag - Block to analyze against (default: "latest")
+ * @returns Effect yielding the access list and gas estimate
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { createAccessList, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const { accessList, gasUsed } = yield* createAccessList({
+ *     from: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+ *     to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *     data: '0x...'
+ *   })
+ *   console.log(`Gas used: ${gasUsed}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const createAccessList = (
+	request: CallRequest,
+	blockTag: BlockTag = "latest",
+): Effect.Effect<CreateAccessListResult, CreateAccessListError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc
+			.request<AccessListType>("eth_createAccessList", [formatCallRequest(request), blockTag])
+			.pipe(
+				Effect.map((result) => ({
+					accessList: result.accessList,
+					gasUsed: BigInt(result.gasUsed),
+				})),
+			),
+	);

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

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Free function to create a block filter.
+ *
+ * @module Provider/functions/createBlockFilter
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { FilterId } from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Creates a filter to notify when new blocks are mined.
+ *
+ * @returns Effect yielding filter ID for use with getFilterChanges
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { createBlockFilter, getFilterChanges, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const filterId = yield* createBlockFilter()
+ *   const newBlockHashes = yield* getFilterChanges(filterId)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const createBlockFilter = (): Effect.Effect<
+	FilterId,
+	TransportError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<FilterId>("eth_newBlockFilter", []),
+	);

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

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Free function to create an event filter.
+ *
+ * @module Provider/functions/createEventFilter
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { EventFilter, FilterId } from "../types.js";
+import { formatLogFilterParams } from "../utils.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Creates a filter for logs matching the given criteria.
+ *
+ * @param filter - Event filter parameters (address, topics, fromBlock, toBlock)
+ * @returns Effect yielding filter ID for use with getFilterChanges/getFilterLogs
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { createEventFilter, getFilterChanges, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const filterId = yield* createEventFilter({
+ *     address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+ *   })
+ *   const changes = yield* getFilterChanges(filterId)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const createEventFilter = (
+	filter: EventFilter = {},
+): Effect.Effect<FilterId, TransportError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<FilterId>("eth_newFilter", [formatLogFilterParams(filter)]),
+	);

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

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Free function to create a pending transaction filter.
+ *
+ * @module Provider/functions/createPendingTransactionFilter
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { FilterId } from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Creates a filter to notify when new pending transactions are added to the mempool.
+ *
+ * @returns Effect yielding filter ID for use with getFilterChanges
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { createPendingTransactionFilter, getFilterChanges, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const filterId = yield* createPendingTransactionFilter()
+ *   const pendingTxHashes = yield* getFilterChanges(filterId)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const createPendingTransactionFilter = (): Effect.Effect<
+	FilterId,
+	TransportError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<FilterId>("eth_newPendingTransactionFilter", []),
+	);

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

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Free function to estimate gas for a transaction.
+ *
+ * @module Provider/functions/estimateGas
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { BlockTag, CallRequest, EstimateGasError } from "../types.js";
+import { formatCallRequest, parseHexToBigInt } from "../utils.js";
+
+/**
+ * Estimates gas for a transaction.
+ *
+ * @param request - The call request parameters
+ * @param blockTag - Block to estimate against (default: "latest")
+ * @returns Effect yielding the estimated gas as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { estimateGas, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const gas = yield* estimateGas({
+ *     from: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+ *     to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *     data: '0x...'
+ *   })
+ *   console.log(`Estimated gas: ${gas}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const estimateGas = (
+	request: CallRequest,
+	blockTag: BlockTag = "latest",
+): Effect.Effect<bigint, EstimateGasError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc
+			.request<string>("eth_estimateGas", [formatCallRequest(request), blockTag])
+			.pipe(
+				Effect.flatMap((response) =>
+					parseHexToBigInt({ method: "eth_estimateGas", response, params: [request, blockTag] }),
+				),
+			),
+	);

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

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Free function to get available accounts.
+ *
+ * @module Provider/functions/getAccounts
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets the list of accounts owned by the node.
+ *
+ * @returns Effect yielding an array of account addresses
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getAccounts, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const accounts = yield* getAccounts()
+ *   console.log('Accounts:', accounts)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('http://localhost:8545'))
+ * )
+ * ```
+ */
+export const getAccounts = (): Effect.Effect<
+	`0x${string}`[],
+	TransportError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<`0x${string}`[]>("eth_accounts"),
+	);

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

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Free function to get account balance.
+ *
+ * @module Provider/functions/getBalance
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { AddressInput, BlockTag } from "../types.js";
+import { toAddressHex, parseHexToBigInt } from "../utils.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+import type { ProviderResponseError } from "../types.js";
+
+/**
+ * Gets the balance of an address in wei.
+ *
+ * @param address - The address to check balance for
+ * @param blockTag - Block to query at (default: "latest")
+ * @returns Effect yielding the balance as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getBalance, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const balance = yield* getBalance('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')
+ *   console.log(`Balance: ${balance} wei`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getBalance = (
+	address: AddressInput,
+	blockTag: BlockTag = "latest",
+): Effect.Effect<bigint, TransportError | ProviderResponseError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc
+			.request<string>("eth_getBalance", [toAddressHex(address), blockTag])
+			.pipe(
+				Effect.flatMap((response) =>
+					parseHexToBigInt({ method: "eth_getBalance", response, params: [address, blockTag] }),
+				),
+			),
+	);

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

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Free function to get the blob base fee.
+ *
+ * @module Provider/functions/getBlobBaseFee
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import { parseHexToBigInt } from "../utils.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+import type { ProviderResponseError } from "../types.js";
+
+/**
+ * Gets the current blob base fee (EIP-4844).
+ *
+ * @returns Effect yielding the blob base fee as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getBlobBaseFee, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const blobFee = yield* getBlobBaseFee()
+ *   console.log('Blob base fee:', blobFee, 'wei')
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getBlobBaseFee = (): Effect.Effect<
+	bigint,
+	TransportError | ProviderResponseError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<string>("eth_blobBaseFee").pipe(
+			Effect.flatMap((response) =>
+				parseHexToBigInt({ method: "eth_blobBaseFee", response }),
+			),
+		),
+	);

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

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Free function to get a block by tag, number, or hash.
+ *
+ * @module Provider/functions/getBlock
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type BlockTag,
+	type BlockType,
+	type GetBlockArgs,
+	ProviderNotFoundError,
+} from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets a block by tag, number, or hash.
+ *
+ * @param args - Block identifier (blockTag, blockNumber, or blockHash) and includeTransactions flag
+ * @returns Effect yielding the block
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getBlock, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Get latest block
+ *   const latest = yield* getBlock({})
+ *
+ *   // Get by block number
+ *   const block = yield* getBlock({ blockNumber: 18000000n })
+ *
+ *   // Get by hash with full transactions
+ *   const withTxs = yield* getBlock({
+ *     blockHash: '0x...',
+ *     includeTransactions: true
+ *   })
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getBlock = (
+	args: GetBlockArgs = {},
+): Effect.Effect<BlockType, TransportError | ProviderNotFoundError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) => {
+		const includeTransactions = args.includeTransactions ?? false;
+
+		if ("blockHash" in args && args.blockHash !== undefined) {
+			const hash =
+				typeof args.blockHash === "string"
+					? args.blockHash
+					: `0x${Buffer.from(args.blockHash).toString("hex")}`;
+			return svc
+				.request<BlockType | null>("eth_getBlockByHash", [hash, includeTransactions])
+				.pipe(
+					Effect.flatMap((result) =>
+						result === null
+							? Effect.fail(
+									new ProviderNotFoundError(args, "Block not found", {
+										resource: "block",
+									}),
+								)
+							: Effect.succeed(result),
+					),
+				);
+		}
+
+		let blockId: BlockTag;
+		if ("blockNumber" in args && args.blockNumber !== undefined) {
+			blockId = `0x${args.blockNumber.toString(16)}` as BlockTag;
+		} else {
+			blockId = args.blockTag ?? "latest";
+		}
+
+		return svc
+			.request<BlockType | null>("eth_getBlockByNumber", [blockId, includeTransactions])
+			.pipe(
+				Effect.flatMap((result) =>
+					result === null
+						? Effect.fail(
+								new ProviderNotFoundError(args, "Block not found", {
+									resource: "block",
+								}),
+							)
+						: Effect.succeed(result),
+				),
+			);
+	});

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

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Free function to get the current block number.
+ *
+ * @module Provider/functions/getBlockNumber
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import { ProviderResponseError } from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets the current block number from the connected Ethereum node.
+ *
+ * @returns Effect yielding the current block number as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getBlockNumber, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const blockNumber = yield* getBlockNumber()
+ *   console.log('Current block:', blockNumber)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getBlockNumber = (): Effect.Effect<
+	bigint,
+	TransportError | ProviderResponseError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<string>("eth_blockNumber").pipe(
+			Effect.flatMap((hex) =>
+				Effect.try({
+					try: () => BigInt(hex),
+					catch: (error) =>
+						new ProviderResponseError(hex, "Invalid hex from eth_blockNumber", {
+							cause: error,
+						}),
+				}),
+			),
+		),
+	);

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

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Free function to get all transaction receipts for a block.
+ *
+ * @module Provider/functions/getBlockReceipts
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type BlockTag,
+	type GetBlockReceiptsArgs,
+	type ReceiptType,
+	ProviderNotFoundError,
+} from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets all transaction receipts for a block.
+ *
+ * @param args - Block identifier (blockTag, blockNumber, or blockHash)
+ * @returns Effect yielding an array of transaction receipts
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getBlockReceipts, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Get receipts for latest block
+ *   const receipts = yield* getBlockReceipts({})
+ *
+ *   // Get by block number
+ *   const receiptsByNumber = yield* getBlockReceipts({
+ *     blockNumber: 18000000n
+ *   })
+ *
+ *   // Get by block hash
+ *   const receiptsByHash = yield* getBlockReceipts({
+ *     blockHash: '0x...'
+ *   })
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getBlockReceipts = (
+	args: GetBlockReceiptsArgs = {},
+): Effect.Effect<ReceiptType[], TransportError | ProviderNotFoundError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) => {
+		let blockId: string;
+
+		if ("blockHash" in args && args.blockHash !== undefined) {
+			blockId =
+				typeof args.blockHash === "string"
+					? args.blockHash
+					: `0x${Buffer.from(args.blockHash).toString("hex")}`;
+		} else if ("blockNumber" in args && args.blockNumber !== undefined) {
+			blockId = `0x${args.blockNumber.toString(16)}`;
+		} else {
+			blockId = args.blockTag ?? "latest";
+		}
+
+		return svc.request<ReceiptType[] | null>("eth_getBlockReceipts", [blockId]).pipe(
+			Effect.flatMap((result) =>
+				result === null
+					? Effect.fail(
+							new ProviderNotFoundError(args, "Block receipts not found", {
+								resource: "blockReceipts",
+							}),
+						)
+					: Effect.succeed(result),
+			),
+		);
+	});