voltaire-effect 0.2.23

package/src/services/NonceManager/NonceManager.test.ts

@@ -0,0 +1,468 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import {
+	ProviderService,
+	type ProviderShape,
+} from "../Provider/ProviderService.js";
+import { TransportError } from "../Transport/TransportService.js";
+import { DefaultNonceManager } from "./DefaultNonceManager.js";
+import { NonceError, NonceManagerService } from "./NonceManagerService.js";
+
+const createMockProvider = (
+	overrides: Partial<ProviderShape> = {},
+): ProviderShape => ({
+	getBlockNumber: () => Effect.succeed(18000000n),
+	getBlock: () => Effect.succeed({} as any),
+	getBlockTransactionCount: () => Effect.succeed(0n),
+	getBalance: () => Effect.succeed(0n),
+	getTransactionCount: () => Effect.succeed(5n),
+	getCode: () => Effect.succeed("0x"),
+	getStorageAt: () => Effect.succeed("0x"),
+	getTransaction: () => Effect.succeed({} as any),
+	getTransactionReceipt: () => Effect.succeed({} as any),
+	waitForTransactionReceipt: () => Effect.succeed({} as any),
+	call: () => Effect.succeed("0x"),
+	estimateGas: () => Effect.succeed(21000n),
+	createAccessList: () => Effect.succeed({} as any),
+	getLogs: () => Effect.succeed([]),
+	createEventFilter: () => Effect.succeed("0x1" as any),
+	createBlockFilter: () => Effect.succeed("0x1" as any),
+	createPendingTransactionFilter: () => Effect.succeed("0x1" as any),
+	getFilterChanges: () => Effect.succeed([]),
+	getFilterLogs: () => Effect.succeed([]),
+	uninstallFilter: () => Effect.succeed(true),
+	getChainId: () => Effect.succeed(1),
+	getGasPrice: () => Effect.succeed(20000000000n),
+	getMaxPriorityFeePerGas: () => Effect.succeed(1500000000n),
+	getFeeHistory: () => Effect.succeed({} as any),
+	watchBlocks: () => ({}) as any,
+	backfillBlocks: () => ({}) as any,
+	sendRawTransaction: () => Effect.succeed("0x" as `0x${string}`),
+	getUncle: () => Effect.succeed({} as any),
+	getProof: () => Effect.succeed({} as any),
+	getBlobBaseFee: () => Effect.succeed(0n),
+	getTransactionConfirmations: () => Effect.succeed(0n),
+	...overrides,
+});
+
+describe("NonceManagerService", () => {
+	describe("NonceError", () => {
+		it("creates error with message and address", () => {
+			const error = new NonceError({
+				address: "0x1234",
+				message: "test error",
+			});
+			expect(error.message).toBe("test error");
+			expect(error.address).toBe("0x1234");
+			expect(error._tag).toBe("NonceError");
+		});
+
+		it("creates error with cause", () => {
+			const cause = new Error("underlying");
+			const error = new NonceError({
+				address: "0x1234",
+				message: "Nonce fetch failed",
+				cause,
+			});
+			expect(error.cause).toBe(cause);
+		});
+	});
+
+	describe("DefaultNonceManager", () => {
+		describe("get", () => {
+			it.effect("returns on-chain nonce when delta is 0", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const result = yield* nonceManager.get(
+						"0x1234567890123456789012345678901234567890",
+						1,
+					);
+					expect(result).toBe(10n);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(10n),
+							}),
+						),
+					),
+				),
+			);
+
+			it.effect("preserves large nonces without precision loss", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const result = yield* nonceManager.get(
+						"0x1234567890123456789012345678901234567890",
+						1,
+					);
+					expect(result).toBe(9007199254740993n);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(9007199254740993n),
+							}),
+						),
+					),
+				),
+			);
+
+			it("normalizes address to lowercase", async () => {
+				let capturedAddress: string | undefined;
+				const mockProvider = createMockProvider({
+					getTransactionCount: (address) => {
+						capturedAddress = address as string;
+						return Effect.succeed(5n);
+					},
+				});
+
+				const TestProviderLayer = Layer.succeed(ProviderService, mockProvider);
+
+				const program = Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					return yield* nonceManager.get(
+						"0xABCD1234567890123456789012345678901234AB",
+						1,
+					);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(TestProviderLayer),
+				);
+
+				await Effect.runPromise(program);
+				expect(capturedAddress).toBe(
+					"0xABCD1234567890123456789012345678901234AB",
+				);
+			});
+
+			it.effect("propagates provider errors", () =>
+				Effect.gen(function* () {
+					const mockProvider = createMockProvider({
+						getTransactionCount: () =>
+							Effect.fail(
+								new TransportError({ code: -32000, message: "RPC failed" }),
+							),
+					});
+
+					const TestProviderLayer = Layer.succeed(
+						ProviderService,
+						mockProvider,
+					);
+
+					const program = Effect.gen(function* () {
+						const nonceManager = yield* NonceManagerService;
+						return yield* nonceManager.get(
+							"0x1234567890123456789012345678901234567890",
+							1,
+						);
+					}).pipe(
+						Effect.provide(DefaultNonceManager),
+						Effect.provide(TestProviderLayer),
+					);
+
+					const exit = yield* Effect.exit(program);
+					expect(Exit.isFailure(exit)).toBe(true);
+					if (Exit.isFailure(exit) && exit.cause._tag === "Fail") {
+						expect(exit.cause.error._tag).toBe("NonceError");
+						expect(exit.cause.error.message).toContain(
+							"Failed to get transaction count",
+						);
+					}
+				}),
+			);
+		});
+
+		describe("consume", () => {
+			it.effect("returns current nonce and increments delta", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const addr = "0x1234567890123456789012345678901234567890";
+					const n1 = yield* nonceManager.consume(addr, 1);
+					const n2 = yield* nonceManager.consume(addr, 1);
+					const n3 = yield* nonceManager.consume(addr, 1);
+					expect([n1, n2, n3]).toEqual([5n, 6n, 7n]);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(5n),
+							}),
+						),
+					),
+				),
+			);
+
+			it.effect("tracks delta per address", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const addr1 = "0x1111111111111111111111111111111111111111";
+					const addr2 = "0x2222222222222222222222222222222222222222";
+
+					const a1n1 = yield* nonceManager.consume(addr1, 1);
+					const a2n1 = yield* nonceManager.consume(addr2, 1);
+					const a1n2 = yield* nonceManager.consume(addr1, 1);
+					const a2n2 = yield* nonceManager.consume(addr2, 1);
+
+					expect(a1n1).toBe(10n);
+					expect(a1n2).toBe(11n);
+					expect(a2n1).toBe(10n);
+					expect(a2n2).toBe(11n);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(10n),
+							}),
+						),
+					),
+				),
+			);
+
+			it.effect("tracks delta per chainId", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const addr = "0x1111111111111111111111111111111111111111";
+
+					const mainnet1 = yield* nonceManager.consume(addr, 1);
+					const optimism1 = yield* nonceManager.consume(addr, 10);
+					const mainnet2 = yield* nonceManager.consume(addr, 1);
+					const optimism2 = yield* nonceManager.consume(addr, 10);
+
+					expect(mainnet1).toBe(10n);
+					expect(mainnet2).toBe(11n);
+					expect(optimism1).toBe(10n);
+					expect(optimism2).toBe(11n);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(10n),
+							}),
+						),
+					),
+				),
+			);
+		});
+
+		describe("increment", () => {
+			it.effect("increments delta without fetching", () =>
+				Effect.gen(function* () {
+					let fetchCount = 0;
+					const mockProvider = createMockProvider({
+						getTransactionCount: () => {
+							fetchCount++;
+							return Effect.succeed(5n);
+						},
+					});
+
+					const TestProviderLayer = Layer.succeed(
+						ProviderService,
+						mockProvider,
+					);
+
+					const program = Effect.gen(function* () {
+						const nonceManager = yield* NonceManagerService;
+						const addr = "0x1234567890123456789012345678901234567890";
+
+						yield* nonceManager.increment(addr, 1);
+						yield* nonceManager.increment(addr, 1);
+						yield* nonceManager.increment(addr, 1);
+
+						const beforeFetch = fetchCount;
+						const nonce = yield* nonceManager.get(addr, 1);
+
+						return {
+							nonce,
+							fetchesBefore: beforeFetch,
+							fetchesAfter: fetchCount,
+						};
+					}).pipe(
+						Effect.provide(DefaultNonceManager),
+						Effect.provide(TestProviderLayer),
+					);
+
+					const result = yield* program;
+					expect(result.fetchesBefore).toBe(0);
+					expect(result.fetchesAfter).toBe(1);
+					expect(result.nonce).toBe(8n);
+				}),
+			);
+		});
+
+		describe("reset", () => {
+			it.effect("clears delta for address", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const addr = "0x1234567890123456789012345678901234567890";
+
+					yield* nonceManager.consume(addr, 1);
+					yield* nonceManager.consume(addr, 1);
+					yield* nonceManager.consume(addr, 1);
+
+					yield* nonceManager.reset(addr, 1);
+
+					const result = yield* nonceManager.get(addr, 1);
+					expect(result).toBe(5n);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(5n),
+							}),
+						),
+					),
+				),
+			);
+
+			it.effect("only resets specified address", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const addr1 = "0x1111111111111111111111111111111111111111";
+					const addr2 = "0x2222222222222222222222222222222222222222";
+
+					yield* nonceManager.consume(addr1, 1);
+					yield* nonceManager.consume(addr1, 1);
+					yield* nonceManager.consume(addr2, 1);
+					yield* nonceManager.consume(addr2, 1);
+
+					yield* nonceManager.reset(addr1, 1);
+
+					const n1 = yield* nonceManager.get(addr1, 1);
+					const n2 = yield* nonceManager.get(addr2, 1);
+
+					expect(n1).toBe(5n);
+					expect(n2).toBe(7n);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(5n),
+							}),
+						),
+					),
+				),
+			);
+		});
+
+		describe("case insensitivity", () => {
+			it.effect("treats addresses with different cases as same", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+
+					const n1 = yield* nonceManager.consume(
+						"0xabcd1234567890123456789012345678901234ab",
+						1,
+					);
+					const n2 = yield* nonceManager.consume(
+						"0xABCD1234567890123456789012345678901234AB",
+						1,
+					);
+					const n3 = yield* nonceManager.consume(
+						"0xAbCd1234567890123456789012345678901234Ab",
+						1,
+					);
+
+					expect([n1, n2, n3]).toEqual([5n, 6n, 7n]);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(5n),
+							}),
+						),
+					),
+				),
+			);
+		});
+
+		describe("concurrent usage", () => {
+			it.effect("handles concurrent consumes correctly", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const addr = "0x1234567890123456789012345678901234567890";
+
+					const results = yield* Effect.all(
+						[
+							nonceManager.consume(addr, 1),
+							nonceManager.consume(addr, 1),
+							nonceManager.consume(addr, 1),
+							nonceManager.consume(addr, 1),
+							nonceManager.consume(addr, 1),
+						],
+						{ concurrency: 5 },
+					);
+
+					expect(
+						results.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+					).toEqual([0n, 1n, 2n, 3n, 4n]);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(0n),
+							}),
+						),
+					),
+				),
+			);
+
+			it.effect("handles high concurrency without race conditions", () =>
+				Effect.gen(function* () {
+					const nonceManager = yield* NonceManagerService;
+					const addr = "0x1234567890123456789012345678901234567890";
+
+					const results = yield* Effect.all(
+						Array.from({ length: 100 }, () => nonceManager.consume(addr, 1)),
+						{ concurrency: "unbounded" },
+					);
+
+					const expected = Array.from({ length: 100 }, (_, i) => BigInt(i));
+					expect(
+						results.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+					).toEqual(expected);
+				}).pipe(
+					Effect.provide(DefaultNonceManager),
+					Effect.provide(
+						Layer.succeed(
+							ProviderService,
+							createMockProvider({
+								getTransactionCount: () => Effect.succeed(0n),
+							}),
+						),
+					),
+				),
+			);
+		});
+	});
+
+	describe("exports", () => {
+		it("exports from index", async () => {
+			const { NonceManagerService, NonceError, DefaultNonceManager } =
+				await import("./index.js");
+			expect(NonceManagerService).toBeDefined();
+			expect(NonceError).toBeDefined();
+			expect(DefaultNonceManager).toBeDefined();
+		});
+	});
+});

package/src/services/NonceManager/NonceManagerService.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview NonceManager service definition for transaction nonce management.
+ *
+ * @module NonceManagerService
+ * @since 0.0.1
+ *
+ * @description
+ * The NonceManagerService provides a high-level interface for managing transaction
+ * nonces. It tracks local nonce deltas to allow multiple transactions to be sent
+ * without waiting for each to be mined.
+ *
+ * This is essential for high-throughput applications that need to send multiple
+ * transactions in quick succession.
+ *
+ * @see {@link DefaultNonceManager} - The live implementation layer
+ * @see {@link ProviderService} - Required dependency for fetching on-chain nonces
+ */
+
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import type * as Effect from "effect/Effect";
+import type { ProviderService } from "../Provider/index.js";
+
+/**
+ * Error thrown when a nonce operation fails.
+ *
+ * @description
+ * Contains the address and error details for debugging.
+ *
+ * @since 0.0.1
+ *
+ * @example Handling NonceError
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { NonceManagerService, NonceError } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const nonceManager = yield* NonceManagerService
+ *   return yield* nonceManager.get('0x...')
+ * }).pipe(
+ *   Effect.catchTag('NonceError', (error) => {
+ *     console.error('Failed for address:', error.address, error.message)
+ *     return Effect.succeed(0)
+ *   })
+ * )
+ * ```
+ */
+export class NonceError extends Data.TaggedError("NonceError")<{
+	readonly address: string;
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Shape of the nonce manager service.
+ *
+ * @description
+ * Defines the nonce management operations available through NonceManagerService.
+ *
+ * @since 0.0.1
+ */
+export type NonceManagerShape = {
+	/**
+	 * Gets the current nonce for an address on a specific chain.
+	 *
+	 * @description
+	 * Fetches the pending nonce from the provider and adds the local delta.
+	 * Does not consume the nonce (delta remains unchanged).
+	 *
+	 * @param address - The address to get the nonce for
+	 * @param chainId - The chain ID to scope the nonce to
+	 * @returns The current nonce (on-chain pending + local delta)
+	 */
+	readonly get: (
+		address: string,
+		chainId: number,
+	) => Effect.Effect<bigint, NonceError, ProviderService>;
+
+	/**
+	 * Gets and consumes the next nonce for an address on a specific chain.
+	 *
+	 * @description
+	 * Fetches the pending nonce, adds the local delta, then increments the delta.
+	 * Use this when preparing to send a transaction.
+	 * This operation is atomic - safe for concurrent calls.
+	 *
+	 * @param address - The address to consume a nonce for
+	 * @param chainId - The chain ID to scope the nonce to
+	 * @returns The nonce to use for the next transaction
+	 */
+	readonly consume: (
+		address: string,
+		chainId: number,
+	) => Effect.Effect<bigint, NonceError, ProviderService>;
+
+	/**
+	 * Increments the local delta for an address on a specific chain.
+	 *
+	 * @description
+	 * Adds 1 to the tracked delta without fetching from the provider.
+	 * Useful when you know a transaction was sent externally.
+	 *
+	 * @param address - The address to increment the delta for
+	 * @param chainId - The chain ID to scope the nonce to
+	 */
+	readonly increment: (address: string, chainId: number) => Effect.Effect<void>;
+
+	/**
+	 * Resets the local delta for an address on a specific chain.
+	 *
+	 * @description
+	 * Clears the tracked delta, so the next get() will return the
+	 * on-chain pending nonce. Use after transactions are confirmed
+	 * or if you need to resync with the network.
+	 *
+	 * @param address - The address to reset
+	 * @param chainId - The chain ID to scope the nonce to
+	 */
+	readonly reset: (address: string, chainId: number) => Effect.Effect<void>;
+};
+
+/**
+ * NonceManager service for transaction nonce management.
+ *
+ * @description
+ * Provides methods for getting, consuming, and managing transaction nonces.
+ * Tracks local deltas to allow multiple transactions to be prepared without
+ * waiting for previous ones to be mined.
+ *
+ * The service maintains a delta per address that is added to the on-chain
+ * pending nonce. This allows:
+ * - Sending multiple transactions quickly
+ * - Proper nonce sequencing without race conditions
+ * - Easy reset when transactions are confirmed
+ *
+ * Requires ProviderService for fetching on-chain nonces.
+ *
+ * @since 0.0.1
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import {
+ *   NonceManagerService,
+ *   DefaultNonceManager,
+ *   Provider,
+ *   HttpTransport
+ * } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const nonceManager = yield* NonceManagerService
+ *
+ *   // Get next nonce for transaction
+ *   const nonce = yield* nonceManager.consume('0x1234...')
+ *
+ *   // Use nonce in transaction...
+ *
+ *   return nonce
+ * }).pipe(
+ *   Effect.provide(DefaultNonceManager),
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://...'))
+ * )
+ * ```
+ *
+ * @example Multiple transactions
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const nonceManager = yield* NonceManagerService
+ *   const address = '0x1234...'
+ *
+ *   // Get nonces for 3 transactions
+ *   const nonce1 = yield* nonceManager.consume(address) // e.g., 5n
+ *   const nonce2 = yield* nonceManager.consume(address) // e.g., 6n
+ *   const nonce3 = yield* nonceManager.consume(address) // e.g., 7n
+ *
+ *   // Send transactions with these nonces...
+ *
+ *   // After all confirmed, reset
+ *   yield* nonceManager.reset(address)
+ * })
+ * ```
+ *
+ * @see {@link DefaultNonceManager} - The live implementation layer
+ * @see {@link NonceError} - Error type for failed operations
+ * @see {@link ProviderService} - Required dependency
+ */
+export class NonceManagerService extends Context.Tag("NonceManagerService")<
+	NonceManagerService,
+	NonceManagerShape
+>() {}

package/src/services/NonceManager/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview NonceManager module exports for transaction nonce management.
+ *
+ * @module NonceManager
+ * @since 0.0.1
+ *
+ * @description
+ * This module provides the nonce manager service for tracking and managing
+ * transaction nonces. It includes the service definition, layer implementation,
+ * and all related types.
+ *
+ * Main exports:
+ * - {@link NonceManagerService} - The service tag/interface
+ * - {@link DefaultNonceManager} - The live implementation layer
+ * - {@link NonceError} - Error type for failed operations
+ *
+ * @example Typical usage
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import {
+ *   NonceManagerService,
+ *   DefaultNonceManager,
+ *   Provider,
+ *   HttpTransport
+ * } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const nonceManager = yield* NonceManagerService
+ *   const nonce = yield* nonceManager.consume('0x1234...')
+ *   return nonce
+ * }).pipe(
+ *   Effect.provide(DefaultNonceManager),
+ *   Effect.provide(Provider),
+ *   Effect.provide(HttpTransport('https://...'))
+ * )
+ * ```
+ *
+ * @see {@link ProviderService} - Required dependency for RPC communication
+ */
+
+export { DefaultNonceManager } from "./DefaultNonceManager.js";
+export {
+	NonceError,
+	NonceManagerService,
+	type NonceManagerShape,
+} from "./NonceManagerService.js";