voltaire-effect 0.2.23 → 0.2.25

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

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Free function to get the transaction count in a block.
+ *
+ * @module Provider/functions/getBlockTransactionCount
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type BlockTag,
+	type GetBlockTransactionCountArgs,
+	ProviderResponseError,
+} from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets the number of transactions in a block.
+ *
+ * @param args - Block identifier (blockTag or blockHash)
+ * @returns Effect yielding the transaction count as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getBlockTransactionCount, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Get transaction count for latest block
+ *   const count = yield* getBlockTransactionCount({})
+ *
+ *   // Get by block hash
+ *   const countByHash = yield* getBlockTransactionCount({
+ *     blockHash: '0x...'
+ *   })
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getBlockTransactionCount = (
+	args: GetBlockTransactionCountArgs = {},
+): Effect.Effect<bigint, TransportError | ProviderResponseError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) => {
+		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<string>("eth_getBlockTransactionCountByHash", [hash])
+				.pipe(
+					Effect.flatMap((hex) =>
+						Effect.try({
+							try: () => BigInt(hex),
+							catch: (error) =>
+								new ProviderResponseError(
+									hex,
+									"Invalid hex from eth_getBlockTransactionCountByHash",
+									{ cause: error },
+								),
+						}),
+					),
+				);
+		}
+
+		const blockTag: BlockTag = args.blockTag ?? "latest";
+		return svc
+			.request<string>("eth_getBlockTransactionCountByNumber", [blockTag])
+			.pipe(
+				Effect.flatMap((hex) =>
+					Effect.try({
+						try: () => BigInt(hex),
+						catch: (error) =>
+							new ProviderResponseError(
+								hex,
+								"Invalid hex from eth_getBlockTransactionCountByNumber",
+								{ cause: error },
+							),
+					}),
+				),
+			);
+	});

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

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Free function to get the chain ID.
+ *
+ * @module Provider/functions/getChainId
+ * @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 chain ID of the connected Ethereum network.
+ *
+ * @returns Effect yielding the chain ID as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getChainId, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const chainId = yield* getChainId()
+ *   console.log('Chain ID:', chainId)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getChainId = (): Effect.Effect<
+	bigint,
+	TransportError | ProviderResponseError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<string>("eth_chainId").pipe(
+			Effect.flatMap((response) =>
+				parseHexToBigInt({ method: "eth_chainId", response }),
+			),
+		),
+	);

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

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Free function to get contract bytecode.
+ *
+ * @module Provider/functions/getCode
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { AddressInput, BlockTag } from "../types.js";
+import { toAddressHex } from "../utils.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets the bytecode at an address.
+ *
+ * @param address - The address to get code from
+ * @param blockTag - Block to query at (default: "latest")
+ * @returns Effect yielding the bytecode as hex string
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getCode, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const code = yield* getCode('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48')
+ *   console.log(`Code length: ${(code.length - 2) / 2} bytes`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getCode = (
+	address: AddressInput,
+	blockTag: BlockTag = "latest",
+): Effect.Effect<`0x${string}`, TransportError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<`0x${string}`>("eth_getCode", [toAddressHex(address), blockTag]),
+	);

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

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Free function to get the coinbase address.
+ *
+ * @module Provider/functions/getCoinbase
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets the coinbase address of the node.
+ *
+ * @returns Effect yielding the coinbase address
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getCoinbase, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const coinbase = yield* getCoinbase()
+ *   console.log('Coinbase:', coinbase)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('http://localhost:8545'))
+ * )
+ * ```
+ */
+export const getCoinbase = (): Effect.Effect<
+	`0x${string}`,
+	TransportError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<`0x${string}`>("eth_coinbase"),
+	);

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

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Free function to get fee history.
+ *
+ * @module Provider/functions/getFeeHistory
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { BlockTag, FeeHistoryType } from "../types.js";
+import { ProviderValidationError } from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+import type { ProviderResponseError } from "../types.js";
+
+/**
+ * Gets the fee history for a range of blocks.
+ *
+ * @param blockCount - Number of blocks to return (must be > 0)
+ * @param newestBlock - Newest block to include
+ * @param rewardPercentiles - Percentiles to sample for priority fees (0-100, ascending)
+ * @returns Effect yielding the fee history
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getFeeHistory, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const history = yield* getFeeHistory(10, 'latest', [25, 50, 75])
+ *   console.log('Oldest block:', history.oldestBlock)
+ *   console.log('Base fees:', history.baseFeePerGas)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getFeeHistory = (
+	blockCount: number,
+	newestBlock: BlockTag,
+	rewardPercentiles: number[],
+): Effect.Effect<
+	FeeHistoryType,
+	TransportError | ProviderResponseError | ProviderValidationError,
+	ProviderService
+> =>
+	Effect.gen(function* () {
+		if (blockCount <= 0) {
+			return yield* Effect.fail(
+				new ProviderValidationError(
+					{ blockCount, newestBlock, rewardPercentiles },
+					"blockCount must be greater than 0",
+				),
+			);
+		}
+
+		for (let i = 0; i < rewardPercentiles.length; i++) {
+			const p = rewardPercentiles[i];
+			if (p < 0 || p > 100) {
+				return yield* Effect.fail(
+					new ProviderValidationError(
+						{ blockCount, newestBlock, rewardPercentiles },
+						`Percentile ${p} must be between 0 and 100`,
+					),
+				);
+			}
+			if (i > 0 && p < rewardPercentiles[i - 1]) {
+				return yield* Effect.fail(
+					new ProviderValidationError(
+						{ blockCount, newestBlock, rewardPercentiles },
+						"Percentiles must be in ascending order",
+					),
+				);
+			}
+		}
+
+		const svc = yield* ProviderService;
+		return yield* svc.request<FeeHistoryType>("eth_feeHistory", [
+			`0x${blockCount.toString(16)}`,
+			newestBlock,
+			rewardPercentiles,
+		]);
+	});

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

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Free function to get filter changes.
+ *
+ * @module Provider/functions/getFilterChanges
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { FilterId, FilterChanges } from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets changes since last poll for the given filter.
+ *
+ * Returns logs for event filters, or hashes for block/pending transaction filters.
+ *
+ * @param filterId - Filter ID from createEventFilter/createBlockFilter/createPendingTransactionFilter
+ * @returns Effect yielding logs or hashes depending on filter type
+ *
+ * @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 changes = yield* getFilterChanges(filterId)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getFilterChanges = (
+	filterId: FilterId,
+): Effect.Effect<FilterChanges, TransportError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<FilterChanges>("eth_getFilterChanges", [filterId]),
+	);

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

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Free function to get all logs for an event filter.
+ *
+ * @module Provider/functions/getFilterLogs
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { FilterId, LogType } from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets all logs matching the filter since it was created.
+ *
+ * Only works for event filters created with createEventFilter.
+ *
+ * @param filterId - Filter ID from createEventFilter
+ * @returns Effect yielding array of logs
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { createEventFilter, getFilterLogs, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const filterId = yield* createEventFilter({
+ *     address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+ *   })
+ *   const logs = yield* getFilterLogs(filterId)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getFilterLogs = (
+	filterId: FilterId,
+): Effect.Effect<LogType[], TransportError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<LogType[]>("eth_getFilterLogs", [filterId]),
+	);

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

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Free function to get the current gas price.
+ *
+ * @module Provider/functions/getGasPrice
+ * @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 gas price in wei.
+ *
+ * @returns Effect yielding the gas price as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getGasPrice, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const gasPrice = yield* getGasPrice()
+ *   console.log('Gas price:', gasPrice, 'wei')
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getGasPrice = (): Effect.Effect<
+	bigint,
+	TransportError | ProviderResponseError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<string>("eth_gasPrice").pipe(
+			Effect.flatMap((response) =>
+				parseHexToBigInt({ method: "eth_gasPrice", response }),
+			),
+		),
+	);

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

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Free function to get the hashrate.
+ *
+ * @module Provider/functions/getHashrate
+ * @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 hashrate of the node.
+ *
+ * @returns Effect yielding the hashrate as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getHashrate, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const hashrate = yield* getHashrate()
+ *   console.log('Hashrate:', hashrate)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('http://localhost:8545'))
+ * )
+ * ```
+ */
+export const getHashrate = (): Effect.Effect<
+	bigint,
+	TransportError | ProviderResponseError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<string>("eth_hashrate").pipe(
+			Effect.flatMap((response) =>
+				parseHexToBigInt({ method: "eth_hashrate", response }),
+			),
+		),
+	);

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

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Free function to get logs matching a filter.
+ *
+ * @module Provider/functions/getLogs
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { LogFilter, LogType } from "../types.js";
+import { formatLogFilterParams } from "../utils.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets logs matching the given filter.
+ *
+ * @param filter - Log filter (blockHash XOR fromBlock/toBlock, plus optional address/topics)
+ * @returns Effect yielding array of matching logs
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getLogs, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const logs = yield* getLogs({
+ *     fromBlock: '0x100000',
+ *     toBlock: '0x100100',
+ *     address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+ *   })
+ *   console.log(`Found ${logs.length} logs`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getLogs = (
+	filter: LogFilter,
+): Effect.Effect<LogType[], TransportError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<LogType[]>("eth_getLogs", [formatLogFilterParams(filter)]),
+	);

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

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Free function to get the max priority fee per gas.
+ *
+ * @module Provider/functions/getMaxPriorityFeePerGas
+ * @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 suggested max priority fee per gas for EIP-1559 transactions.
+ *
+ * @returns Effect yielding the max priority fee as bigint
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getMaxPriorityFeePerGas, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const priorityFee = yield* getMaxPriorityFeePerGas()
+ *   console.log('Priority fee:', priorityFee, 'wei')
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getMaxPriorityFeePerGas = (): Effect.Effect<
+	bigint,
+	TransportError | ProviderResponseError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<string>("eth_maxPriorityFeePerGas").pipe(
+			Effect.flatMap((response) =>
+				parseHexToBigInt({ method: "eth_maxPriorityFeePerGas", response }),
+			),
+		),
+	);

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

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Free function to check mining status.
+ *
+ * @module Provider/functions/getMining
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Checks if the node is currently mining.
+ *
+ * @returns Effect yielding true if mining, false otherwise
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getMining, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const isMining = yield* getMining()
+ *   console.log('Mining:', isMining)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('http://localhost:8545'))
+ * )
+ * ```
+ */
+export const getMining = (): Effect.Effect<
+	boolean,
+	TransportError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<boolean>("eth_mining"),
+	);

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

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Free function to get Merkle-Patricia proof for an account.
+ *
+ * @module Provider/functions/getProof
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { AddressInput, BlockTag, HashInput, ProofType } from "../types.js";
+import { toAddressHex, toHashHex } from "../utils.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets a Merkle-Patricia proof for an account and storage slots.
+ *
+ * @param address - The address to get proof for
+ * @param storageKeys - Array of storage slots to include in proof
+ * @param blockTag - Block to query at (default: "latest")
+ * @returns Effect yielding the proof
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getProof, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const proof = yield* getProof(
+ *     '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *     ['0x0000000000000000000000000000000000000000000000000000000000000000']
+ *   )
+ *   console.log(`Account proof nodes: ${proof.accountProof.length}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getProof = (
+	address: AddressInput,
+	storageKeys: HashInput[],
+	blockTag: BlockTag = "latest",
+): Effect.Effect<ProofType, TransportError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<ProofType>("eth_getProof", [
+			toAddressHex(address),
+			storageKeys.map(toHashHex),
+			blockTag,
+		]),
+	);