voltaire-effect 0.2.23 → 0.2.25

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

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Free function to get the protocol version.
+ *
+ * @module Provider/functions/getProtocolVersion
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets the Ethereum protocol version.
+ *
+ * @returns Effect yielding the protocol version as string
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getProtocolVersion, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const version = yield* getProtocolVersion()
+ *   console.log('Protocol version:', version)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getProtocolVersion = (): Effect.Effect<
+	string,
+	TransportError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<string>("eth_protocolVersion"),
+	);

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

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Free function to get storage at a slot.
+ *
+ * @module Provider/functions/getStorageAt
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { AddressInput, BlockTag, HashInput } from "../types.js";
+import { toAddressHex, toHashHex } from "../utils.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets storage at a specific slot for an address.
+ *
+ * @param address - The contract address
+ * @param slot - The storage slot to read
+ * @param blockTag - Block to query at (default: "latest")
+ * @returns Effect yielding the storage value as hex string
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getStorageAt, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const value = yield* getStorageAt(
+ *     '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *     '0x0000000000000000000000000000000000000000000000000000000000000000'
+ *   )
+ *   console.log(`Storage slot 0: ${value}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getStorageAt = (
+	address: AddressInput,
+	slot: HashInput,
+	blockTag: BlockTag = "latest",
+): Effect.Effect<`0x${string}`, TransportError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<`0x${string}`>("eth_getStorageAt", [
+			toAddressHex(address),
+			toHashHex(slot),
+			blockTag,
+		]),
+	);

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

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Free function to get syncing status.
+ *
+ * @module Provider/functions/getSyncing
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import type { SyncingStatus } from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets the syncing status of the node.
+ *
+ * @returns Effect yielding false if not syncing, or an object with sync progress
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getSyncing, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const status = yield* getSyncing()
+ *   if (status === false) {
+ *     console.log('Node is fully synced')
+ *   } else {
+ *     console.log('Syncing:', status.currentBlock, '/', status.highestBlock)
+ *   }
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getSyncing = (): Effect.Effect<
+	SyncingStatus,
+	TransportError,
+	ProviderService
+> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc.request<false | { startingBlock: string; currentBlock: string; highestBlock: string }>(
+			"eth_syncing",
+		).pipe(
+			Effect.map((result) => {
+				if (result === false) return false;
+				return {
+					startingBlock: result.startingBlock,
+					currentBlock: result.currentBlock,
+					highestBlock: result.highestBlock,
+				};
+			}),
+		),
+	);

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

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Free function to get a transaction by hash.
+ *
+ * @module Provider/functions/getTransaction
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import type { TransportError } from "../../Transport/TransportError.js";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type HashInput,
+	ProviderNotFoundError,
+	type TransactionType,
+} from "../types.js";
+import { toHashHex } from "../utils.js";
+
+/**
+ * Gets a transaction by its hash.
+ *
+ * @param hash - The transaction hash
+ * @returns Effect yielding the transaction
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getTransaction, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const tx = yield* getTransaction('0x...')
+ *   console.log(`From: ${tx.from}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getTransaction = (
+	hash: HashInput,
+): Effect.Effect<TransactionType, TransportError | ProviderNotFoundError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc
+			.request<TransactionType | null>("eth_getTransactionByHash", [toHashHex(hash)])
+			.pipe(
+				Effect.flatMap((result) =>
+					result === null
+						? Effect.fail(
+								new ProviderNotFoundError(hash, "Transaction not found", {
+									resource: "transaction",
+								}),
+							)
+						: Effect.succeed(result),
+				),
+			),
+	);

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

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Free function to get a transaction by block hash and index.
+ *
+ * @module Provider/functions/getTransactionByBlockHashAndIndex
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import type { TransportError } from "../../Transport/TransportError.js";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type HashInput,
+	ProviderNotFoundError,
+	type TransactionIndexInput,
+	type TransactionType,
+} from "../types.js";
+import { toHashHex } from "../utils.js";
+
+/**
+ * Converts transaction index to hex string.
+ */
+const toIndexHex = (index: TransactionIndexInput): `0x${string}` => {
+	if (typeof index === "string") return index;
+	return `0x${BigInt(index).toString(16)}`;
+};
+
+/**
+ * Gets a transaction by block hash and transaction index.
+ *
+ * @param blockHash - The block hash
+ * @param index - The transaction index in the block
+ * @returns Effect yielding the transaction
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getTransactionByBlockHashAndIndex, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const tx = yield* getTransactionByBlockHashAndIndex('0x...blockHash', 0)
+ *   console.log(`Transaction hash: ${tx.hash}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getTransactionByBlockHashAndIndex = (
+	blockHash: HashInput,
+	index: TransactionIndexInput,
+): Effect.Effect<TransactionType, TransportError | ProviderNotFoundError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc
+			.request<TransactionType | null>("eth_getTransactionByBlockHashAndIndex", [
+				toHashHex(blockHash),
+				toIndexHex(index),
+			])
+			.pipe(
+				Effect.flatMap((result) =>
+					result === null
+						? Effect.fail(
+								new ProviderNotFoundError(
+									{ blockHash, index },
+									"Transaction not found",
+									{ resource: "transaction" },
+								),
+							)
+						: Effect.succeed(result),
+				),
+			),
+	);

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

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Free function to get a transaction by block number and index.
+ *
+ * @module Provider/functions/getTransactionByBlockNumberAndIndex
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import type { TransportError } from "../../Transport/TransportError.js";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type BlockTag,
+	ProviderNotFoundError,
+	type TransactionIndexInput,
+	type TransactionType,
+} from "../types.js";
+
+/**
+ * Converts transaction index to hex string.
+ */
+const toIndexHex = (index: TransactionIndexInput): `0x${string}` => {
+	if (typeof index === "string") return index;
+	return `0x${BigInt(index).toString(16)}`;
+};
+
+/**
+ * Converts block tag or bigint to RPC block identifier.
+ */
+const toBlockId = (blockTag: BlockTag | bigint): BlockTag => {
+	if (typeof blockTag === "bigint") {
+		return `0x${blockTag.toString(16)}` as BlockTag;
+	}
+	return blockTag;
+};
+
+/**
+ * Gets a transaction by block number/tag and transaction index.
+ *
+ * @param blockTag - The block number or tag
+ * @param index - The transaction index in the block
+ * @returns Effect yielding the transaction
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getTransactionByBlockNumberAndIndex, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Get first transaction in block 18000000
+ *   const tx = yield* getTransactionByBlockNumberAndIndex(18000000n, 0)
+ *   console.log(`Transaction hash: ${tx.hash}`)
+ *
+ *   // Get from latest block
+ *   const latestTx = yield* getTransactionByBlockNumberAndIndex('latest', 0)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getTransactionByBlockNumberAndIndex = (
+	blockTag: BlockTag | bigint,
+	index: TransactionIndexInput,
+): Effect.Effect<TransactionType, TransportError | ProviderNotFoundError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc
+			.request<TransactionType | null>("eth_getTransactionByBlockNumberAndIndex", [
+				toBlockId(blockTag),
+				toIndexHex(index),
+			])
+			.pipe(
+				Effect.flatMap((result) =>
+					result === null
+						? Effect.fail(
+								new ProviderNotFoundError(
+									{ blockTag, index },
+									"Transaction not found",
+									{ resource: "transaction" },
+								),
+							)
+						: Effect.succeed(result),
+				),
+			),
+	);

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

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Free function to get transaction confirmations.
+ *
+ * @module Provider/functions/getTransactionConfirmations
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import type { TransportError } from "../../Transport/TransportError.js";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type HashInput,
+	type ProviderResponseError,
+	type ReceiptType,
+} from "../types.js";
+import { parseHexToBigInt, toHashHex } from "../utils.js";
+
+/**
+ * Gets the number of confirmations for a transaction.
+ *
+ * @param hash - The transaction hash
+ * @returns Effect yielding the number of confirmations (0n if not yet mined)
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getTransactionConfirmations, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const confirmations = yield* getTransactionConfirmations('0x...')
+ *   if (confirmations >= 12n) {
+ *     console.log('Transaction is confirmed')
+ *   }
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getTransactionConfirmations = (
+	hash: HashInput,
+): Effect.Effect<bigint, TransportError | ProviderResponseError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		Effect.gen(function* () {
+			const hashHex = toHashHex(hash);
+			const receipt = yield* svc.request<ReceiptType | null>(
+				"eth_getTransactionReceipt",
+				[hashHex],
+			);
+			if (!receipt) {
+				return 0n;
+			}
+			const currentBlockHex = yield* svc.request<string>("eth_blockNumber");
+			const receiptBlock = yield* parseHexToBigInt({
+				method: "eth_getTransactionReceipt",
+				params: [hashHex],
+				response: receipt.blockNumber,
+			});
+			const currentBlock = yield* parseHexToBigInt({
+				method: "eth_blockNumber",
+				response: currentBlockHex,
+			});
+			if (currentBlock < receiptBlock) {
+				return 0n;
+			}
+			return currentBlock - receiptBlock + 1n;
+		}),
+	);

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

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

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

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Free function to get a transaction receipt by hash.
+ *
+ * @module Provider/functions/getTransactionReceipt
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import type { TransportError } from "../../Transport/TransportError.js";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type HashInput,
+	ProviderNotFoundError,
+	type ReceiptType,
+} from "../types.js";
+import { toHashHex } from "../utils.js";
+
+/**
+ * Gets a transaction receipt by its hash.
+ *
+ * @param hash - The transaction hash
+ * @returns Effect yielding the receipt
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getTransactionReceipt, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const receipt = yield* getTransactionReceipt('0x...')
+ *   console.log(`Status: ${receipt.status}`)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getTransactionReceipt = (
+	hash: HashInput,
+): Effect.Effect<ReceiptType, TransportError | ProviderNotFoundError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) =>
+		svc
+			.request<ReceiptType | null>("eth_getTransactionReceipt", [toHashHex(hash)])
+			.pipe(
+				Effect.flatMap((result) =>
+					result === null
+						? Effect.fail(
+								new ProviderNotFoundError(hash, "Transaction receipt not found", {
+									resource: "receipt",
+								}),
+							)
+						: Effect.succeed(result),
+				),
+			),
+	);

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

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Free function to get an uncle block by index.
+ *
+ * @module Provider/functions/getUncle
+ * @since 0.4.0
+ */
+
+import * as Effect from "effect/Effect";
+import { ProviderService } from "../ProviderService.js";
+import {
+	type BlockTag,
+	type GetUncleArgs,
+	type UncleBlockType,
+	ProviderNotFoundError,
+} from "../types.js";
+import type { TransportError } from "../../Transport/TransportError.js";
+
+/**
+ * Gets an uncle block by block identifier and uncle index.
+ *
+ * @param args - Block identifier (blockTag or blockHash)
+ * @param uncleIndex - The index of the uncle in the block
+ * @returns Effect yielding the uncle block
+ *
+ * @since 0.4.0
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { getUncle, Provider, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Get first uncle of a block by number
+ *   const uncle = yield* getUncle({ blockTag: '0x1234' }, 0)
+ *
+ *   // Get by block hash
+ *   const uncleByHash = yield* getUncle({
+ *     blockHash: '0x...'
+ *   }, 0)
+ * }).pipe(
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ */
+export const getUncle = (
+	args: GetUncleArgs = {},
+	uncleIndex: number | bigint,
+): Effect.Effect<UncleBlockType, TransportError | ProviderNotFoundError, ProviderService> =>
+	Effect.flatMap(ProviderService, (svc) => {
+		const indexHex = `0x${BigInt(uncleIndex).toString(16)}`;
+
+		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<UncleBlockType | null>("eth_getUncleByBlockHashAndIndex", [
+					hash,
+					indexHex,
+				])
+				.pipe(
+					Effect.flatMap((result) =>
+						result === null
+							? Effect.fail(
+									new ProviderNotFoundError(
+										{ ...args, uncleIndex },
+										"Uncle not found",
+										{ resource: "uncle" },
+									),
+								)
+							: Effect.succeed(result),
+					),
+				);
+		}
+
+		const blockTag: BlockTag = args.blockTag ?? "latest";
+		return svc
+			.request<UncleBlockType | null>("eth_getUncleByBlockNumberAndIndex", [
+				blockTag,
+				indexHex,
+			])
+			.pipe(
+				Effect.flatMap((result) =>
+					result === null
+						? Effect.fail(
+								new ProviderNotFoundError(
+									{ ...args, uncleIndex },
+									"Uncle not found",
+									{ resource: "uncle" },
+								),
+							)
+						: Effect.succeed(result),
+				),
+			);
+	});