voltaire-effect 0.2.23

package/src/primitives/EventSignature/String.ts

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Effect Schema for EVM event signatures (topic 0).
+ * @module EventSignature/String
+ * @since 0.1.0
+ *
+ * @description
+ * Event signatures are 32-byte keccak256 hashes of event definitions.
+ * They appear as topic 0 in event logs and are used to identify event types.
+ */
+
+import { EventSignature } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing a 32-byte event topic (keccak256 of event signature).
+ * @since 0.1.0
+ */
+export type EventSignatureType = ReturnType<typeof EventSignature.from>;
+
+/**
+ * Input types accepted for creating an EventSignature.
+ * @since 0.1.0
+ */
+export type EventSignatureLike = Parameters<typeof EventSignature.from>[0];
+
+const EventSignatureTypeSchema = S.declare<EventSignatureType>(
+	(u): u is EventSignatureType => u instanceof Uint8Array && u.length === 32,
+	{ identifier: "EventSignature" },
+);
+
+/**
+ * Schema for EventSignature from string (signature or hex).
+ *
+ * @description
+ * Transforms event signature strings to EventSignatureType.
+ * Accepts event definition strings or hex-encoded 32-byte topics.
+ * Encodes to hex string.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as EventSignature from 'voltaire-effect/primitives/EventSignature'
+ * import * as S from 'effect/Schema'
+ *
+ * // From event definition
+ * const sig = S.decodeSync(EventSignature.String)('Transfer(address,address,uint256)')
+ *
+ * // From hex string
+ * const fromHex = S.decodeSync(EventSignature.String)('0xddf252ad...')
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const hex = S.encodeSync(EventSignature.String)(sig)
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const String: S.Schema<EventSignatureType, string> = S.transformOrFail(
+	S.String,
+	EventSignatureTypeSchema,
+	{
+		strict: true,
+		decode: (value, _options, ast) => {
+			try {
+				if (value.includes("(")) {
+					return ParseResult.succeed(EventSignature.fromSignature(value));
+				}
+				return ParseResult.succeed(EventSignature.from(value));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, value, (e as Error).message),
+				);
+			}
+		},
+		encode: (sig) => ParseResult.succeed(EventSignature.toHex(sig)),
+	},
+).annotations({ identifier: "EventSignature.String" });
+
+export { String as EventSignatureSchema };
+
+/**
+ * Converts an EventSignature to hex string.
+ *
+ * @param sig - The event signature
+ * @returns hex string
+ * @since 0.1.0
+ */
+export const toHex = (
+	sig: EventSignatureType,
+): ReturnType<typeof EventSignature.toHex> => EventSignature.toHex(sig);
+
+/**
+ * Compares two event signatures for equality.
+ *
+ * @param a - First signature
+ * @param b - Second signature
+ * @returns true if equal
+ * @since 0.1.0
+ */
+export const equals = (a: EventSignatureType, b: EventSignatureType): boolean =>
+	EventSignature.equals(a, b);

package/src/primitives/EventSignature/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @module EventSignature
+ * @description Effect Schemas for EVM event signatures (topic 0).
+ *
+ * Event signatures are 32-byte keccak256 hashes of event definitions.
+ * They appear as topic 0 in event logs.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as EventSignature from 'voltaire-effect/primitives/EventSignature'
+ *
+ * function filterLogs(eventSig: EventSignature.EventSignatureType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Schemas
+ *
+ * | Schema | Input | Output |
+ * |--------|-------|--------|
+ * | `EventSignature.String` | signature string | EventSignatureType |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import * as EventSignature from 'voltaire-effect/primitives/EventSignature'
+ * import * as S from 'effect/Schema'
+ *
+ * // From event definition
+ * const sig = S.decodeSync(EventSignature.String)('Transfer(address,address,uint256)')
+ *
+ * // To hex
+ * const hex = S.encodeSync(EventSignature.String)(sig)
+ * ```
+ *
+ * ## Pure Functions
+ *
+ * ```typescript
+ * EventSignature.toHex(sig)  // string
+ * EventSignature.equals(a, b)  // boolean
+ * ```
+ *
+ * @since 0.1.0
+ */
+export {
+	type EventSignatureLike,
+	EventSignatureSchema,
+	type EventSignatureType,
+	equals,
+	String,
+	toHex,
+} from "./String.js";

package/src/primitives/FeeMarket/FeeMarketSchema.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Effect Schema definitions for FeeMarket primitive type.
+ * Provides validation for EIP-1559/EIP-4844 fee market state.
+ * @module FeeMarket/FeeMarketSchema
+ * @since 0.0.1
+ */
+
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Represents EIP-1559 and EIP-4844 fee market state.
+ *
+ * @description
+ * Contains all parameters needed for fee market calculations:
+ * - Gas usage and limits for EIP-1559 base fee adjustment
+ * - Blob gas metrics for EIP-4844 blob pricing
+ *
+ * The state is used to:
+ * 1. Calculate the next block's base fee
+ * 2. Calculate blob base fee for data availability
+ * 3. Validate transaction fee parameters
+ *
+ * @example
+ * ```typescript
+ * import * as FeeMarket from 'voltaire-effect/primitives/FeeMarket'
+ * import { Effect } from 'effect'
+ *
+ * // Current block state
+ * const state = Effect.runSync(FeeMarket.from({
+ *   gasUsed: 15_000_000n,      // 50% of limit (target)
+ *   gasLimit: 30_000_000n,
+ *   baseFee: 20_000_000_000n,  // 20 gwei
+ *   excessBlobGas: 0n,
+ *   blobGasUsed: 0n
+ * }))
+ *
+ * // Calculate next block's base fee
+ * const nextBaseFee = Effect.runSync(
+ *   FeeMarket.BaseFee(state.gasUsed, state.gasLimit, state.baseFee)
+ * )
+ * ```
+ *
+ * @see {@link BaseFeePerGas} for base fee type
+ * @see {@link Blob} for blob data handling
+ * @since 0.0.1
+ */
+export type FeeMarketType = {
+	gasUsed: bigint;
+	gasLimit: bigint;
+	baseFee: bigint;
+	excessBlobGas: bigint;
+	blobGasUsed: bigint;
+};
+
+const FeeMarketTypeSchema = S.declare<FeeMarketType>(
+	(u): u is FeeMarketType =>
+		u !== null &&
+		typeof u === "object" &&
+		"gasUsed" in u &&
+		"gasLimit" in u &&
+		"baseFee" in u,
+	{ identifier: "FeeMarket" },
+);
+
+/**
+ * Input type for creating FeeMarket state.
+ *
+ * @description
+ * Accepts flexible numeric types (bigint, number, string) for all fields,
+ * which are normalized to bigint during construction.
+ *
+ * @see {@link FeeMarketType} for the validated output type
+ * @since 0.0.1
+ */
+export type FeeMarketInput = {
+	readonly gasUsed: bigint | number | string;
+	readonly gasLimit: bigint | number | string;
+	readonly baseFee: bigint | number | string;
+	readonly excessBlobGas: bigint | number | string;
+	readonly blobGasUsed: bigint | number | string;
+};
+
+/**
+ * Effect Schema for validating and transforming FeeMarket state.
+ *
+ * @description
+ * Converts flexible input types to normalized bigint values. Validates
+ * that all required fields are present and can be converted to bigint.
+ *
+ * @param input - FeeMarketInput with flexible numeric types
+ * @returns FeeMarketType with normalized bigint values
+ *
+ * @throws {ParseError} When any field cannot be converted to bigint
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { FeeMarketSchema } from 'voltaire-effect/primitives/FeeMarket'
+ *
+ * // Decode block state
+ * const state = S.decodeSync(FeeMarketSchema)({
+ *   gasUsed: 15000000n,
+ *   gasLimit: 30000000n,
+ *   baseFee: 20000000000n,
+ *   excessBlobGas: 0n,
+ *   blobGasUsed: 0n
+ * })
+ *
+ * // Works with mixed types
+ * const stateFromMixed = S.decodeSync(FeeMarketSchema)({
+ *   gasUsed: '15000000',
+ *   gasLimit: 30000000,
+ *   baseFee: 20000000000n,
+ *   excessBlobGas: 0,
+ *   blobGasUsed: '0'
+ * })
+ * ```
+ *
+ * @see {@link from} for Effect-based constructor
+ * @since 0.0.1
+ */
+export const FeeMarketSchema: S.Schema<FeeMarketType, FeeMarketInput> =
+	S.transformOrFail(
+		S.Struct({
+			gasUsed: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			gasLimit: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			baseFee: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			excessBlobGas: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			blobGasUsed: S.Union(S.BigIntFromSelf, S.Number, S.String),
+		}),
+		FeeMarketTypeSchema,
+		{
+			strict: true,
+			decode: (input, _options, ast) => {
+				try {
+					const state: FeeMarketType = {
+						gasUsed: BigInt(input.gasUsed),
+						gasLimit: BigInt(input.gasLimit),
+						baseFee: BigInt(input.baseFee),
+						excessBlobGas: BigInt(input.excessBlobGas),
+						blobGasUsed: BigInt(input.blobGasUsed),
+					};
+					return ParseResult.succeed(state);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, input, (e as Error).message),
+					);
+				}
+			},
+			encode: (state) =>
+				ParseResult.succeed({
+					gasUsed: state.gasUsed,
+					gasLimit: state.gasLimit,
+					baseFee: state.baseFee,
+					excessBlobGas: state.excessBlobGas,
+					blobGasUsed: state.blobGasUsed,
+				}),
+		},
+	).annotations({ identifier: "FeeMarketSchema" });

package/src/primitives/FeeMarket/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview FeeMarket primitive module for EIP-1559 and EIP-4844 fee calculations.
+ *
+ * @description
+ * Provides comprehensive fee market state management for Ethereum's dynamic
+ * fee mechanism. Includes EIP-1559 base fee calculations and EIP-4844 blob
+ * fee calculations for data availability.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as FeeMarket from 'voltaire-effect/primitives/FeeMarket'
+ *
+ * function processFeeMarket(market: FeeMarket.FeeMarketType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * Key concepts:
+ * - EIP-1559: Dynamic base fee adjusting to target 50% block utilization
+ * - EIP-4844: Blob gas pricing for data availability (proto-danksharding)
+ * - Base fee: Protocol minimum, burned (not paid to validators)
+ * - Blob base fee: Separate market for blob data pricing
+ *
+ * @module FeeMarket
+ * @since 0.0.1
+ * @see {@link BaseFeePerGas} for base fee type
+ * @see {@link EffectiveGasPrice} for calculated effective price
+ * @see {@link FeeOracle} for fee estimation service
+ */
+
+export {
+	type FeeMarketInput,
+	FeeMarketSchema,
+	type FeeMarketType,
+} from "./FeeMarketSchema.js";

package/src/primitives/FeeOracle/Struct.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Effect Schema definitions for FeeOracle primitive type.
+ * Provides validation for gas fee estimation data.
+ * @module FeeOracle/FeeOracleSchema
+ * @since 0.0.1
+ */
+
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Validated fee oracle data type.
+ *
+ * @description
+ * Contains recommended fee parameters for EIP-1559 transactions.
+ * All fee values are in wei.
+ *
+ * Properties:
+ * - baseFee: Current base fee from the latest block
+ * - priorityFee: Recommended tip for validators
+ * - maxFee: Recommended maximum fee (should be ≥ baseFee + priorityFee)
+ * - gasPrice: Legacy gas price (optional, for legacy transactions)
+ * - estimatedTime: Expected seconds until inclusion (optional)
+ *
+ * @example
+ * ```typescript
+ * import * as FeeOracle from 'voltaire-effect/primitives/FeeOracle'
+ * import { Effect } from 'effect'
+ *
+ * // From fee estimation service
+ * const fees = Effect.runSync(FeeOracle.from({
+ *   baseFee: 20_000_000_000n,     // 20 gwei
+ *   priorityFee: 2_000_000_000n,  // 2 gwei
+ *   maxFee: 50_000_000_000n,      // 50 gwei
+ *   estimatedTime: 12             // ~12 seconds
+ * }))
+ *
+ * // Validate the fee parameters
+ * Effect.runSync(FeeOracle.validate(fees))
+ *
+ * // Get effective price for cost calculation
+ * const effective = Effect.runSync(FeeOracle.effectiveGasPrice(fees))
+ * ```
+ *
+ * @see {@link effectiveGasPrice} to calculate effective price
+ * @see {@link validate} to verify fee parameters
+ * @since 0.0.1
+ */
+export type FeeOracleType = {
+	readonly baseFee: bigint;
+	readonly priorityFee: bigint;
+	readonly maxFee: bigint;
+	readonly gasPrice?: bigint;
+	readonly estimatedTime?: number;
+};
+
+const FeeOracleTypeSchema = S.declare<FeeOracleType>(
+	(u): u is FeeOracleType =>
+		u !== null &&
+		typeof u === "object" &&
+		"baseFee" in u &&
+		"priorityFee" in u &&
+		"maxFee" in u,
+	{ identifier: "FeeOracle" },
+);
+
+/**
+ * Input type for creating FeeOracle data.
+ *
+ * @description
+ * Accepts flexible numeric types for fee values. All values are
+ * normalized to bigint during construction.
+ *
+ * @see {@link FeeOracleType} for validated output type
+ * @since 0.0.1
+ */
+export type FeeOracleInput = {
+	readonly baseFee: bigint | number | string;
+	readonly priorityFee: bigint | number | string;
+	readonly maxFee: bigint | number | string;
+	readonly gasPrice?: bigint | number | string;
+	readonly estimatedTime?: number;
+};
+
+/**
+ * Effect Schema for validating fee oracle data.
+ *
+ * @description
+ * Validates and transforms fee estimation input to normalized bigint values.
+ *
+ * @param input - FeeOracleInput with flexible numeric types
+ * @returns FeeOracleType with normalized bigint values
+ *
+ * @throws {ParseError} When required fields are missing or invalid
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { FeeOracleSchema } from 'voltaire-effect/primitives/FeeOracle'
+ *
+ * const fees = S.decodeSync(FeeOracleSchema)({
+ *   baseFee: '20000000000',
+ *   priorityFee: 2,
+ *   maxFee: 50000000000n,
+ *   estimatedTime: 12
+ * })
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const FeeOracleSchema: S.Schema<FeeOracleType, FeeOracleInput> =
+	S.transformOrFail(
+		S.Struct({
+			baseFee: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			priorityFee: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			maxFee: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			gasPrice: S.optional(S.Union(S.BigIntFromSelf, S.Number, S.String)),
+			estimatedTime: S.optional(S.Number),
+		}),
+		FeeOracleTypeSchema,
+		{
+			strict: true,
+			decode: (input, _options, ast) => {
+				try {
+					const result: FeeOracleType = {
+						baseFee: BigInt(input.baseFee),
+						priorityFee: BigInt(input.priorityFee),
+						maxFee: BigInt(input.maxFee),
+					};
+					if (input.gasPrice !== undefined) {
+						(result as any).gasPrice = BigInt(input.gasPrice);
+					}
+					if (input.estimatedTime !== undefined) {
+						(result as any).estimatedTime = input.estimatedTime;
+					}
+					return ParseResult.succeed(result);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, input, (e as Error).message),
+					);
+				}
+			},
+			encode: (state) =>
+				ParseResult.succeed({
+					baseFee: state.baseFee,
+					priorityFee: state.priorityFee,
+					maxFee: state.maxFee,
+					gasPrice: state.gasPrice,
+					estimatedTime: state.estimatedTime,
+				}),
+		},
+	).annotations({ identifier: "FeeOracleSchema" });

package/src/primitives/FeeOracle/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview FeeOracle primitive module for gas fee estimation.
+ *
+ * @description
+ * FeeOracle provides fee estimation data for EIP-1559 transactions. It
+ * encapsulates the recommended fee parameters:
+ *
+ * - baseFee: Current block base fee
+ * - priorityFee: Suggested validator tip
+ * - maxFee: Recommended maximum fee
+ * - estimatedTime: Expected inclusion time (optional)
+ *
+ * Use with gas price oracles or fee estimation services to get optimal
+ * transaction parameters for current network conditions.
+ *
+ * @module FeeOracle
+ * @since 0.0.1
+ * @see {@link BaseFeePerGas} for base fee type
+ * @see {@link MaxFeePerGas} for max fee type
+ * @see {@link MaxPriorityFeePerGas} for priority fee type
+ * @see {@link EffectiveGasPrice} for calculated price
+ * @see {@link FeeMarket} for fee market state
+ */
+
+export {
+	type FeeOracleInput,
+	FeeOracleSchema,
+	type FeeOracleType,
+} from "./Struct.js";

package/src/primitives/FilterId/Hex.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Effect Schema for Ethereum JSON-RPC filter identifiers.
+ * @module FilterId/FilterIdSchema
+ * @since 0.0.1
+ *
+ * @description
+ * Filter IDs are unique identifiers returned by eth_newFilter, eth_newBlockFilter,
+ * and eth_newPendingTransactionFilter. They are used to poll for new results
+ * with eth_getFilterChanges and to uninstall filters with eth_uninstallFilter.
+ */
+
+import { FilterId } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Branded type representing an Ethereum JSON-RPC filter identifier.
+ *
+ * @description
+ * Filter IDs are hex-encoded identifiers used for tracking:
+ * - Event log filters (eth_newFilter)
+ * - Block filters (eth_newBlockFilter)
+ * - Pending transaction filters (eth_newPendingTransactionFilter)
+ *
+ * @example
+ * ```typescript
+ * import { FilterId } from 'voltaire-effect/primitives'
+ *
+ * // Filter ID returned from eth_newFilter
+ * const filterId: FilterIdType = FilterId.from('0x1')
+ * ```
+ *
+ * @see {@link Schema} for validation
+ * @since 0.0.1
+ */
+export type FilterIdType = ReturnType<typeof FilterId.from>;
+
+/**
+ * Internal schema declaration for FilterId validation.
+ * @internal
+ */
+const FilterIdTypeSchema = S.declare<FilterIdType>(
+	(u): u is FilterIdType => {
+		if (typeof u !== "string") return false;
+		try {
+			FilterId.from(u);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+	{ identifier: "FilterId" },
+);
+
+/**
+ * Effect Schema for validating and transforming filter IDs.
+ *
+ * @description
+ * Validates that the input is a valid hex-encoded filter identifier.
+ * Filter IDs are typically small hex values returned by the JSON-RPC API.
+ *
+ * @example
+ * ```typescript
+ * import * as S from 'effect/Schema'
+ * import { Schema } from 'voltaire-effect/primitives/FilterId'
+ *
+ * const parse = S.decodeSync(Schema)
+ *
+ * // Parse filter ID from JSON-RPC response
+ * const filterId = parse('0x1')
+ * const filterId2 = parse('0xabc')
+ *
+ * // Use in filter polling
+ * // await provider.send('eth_getFilterChanges', [filterId])
+ * ```
+ *
+ * @throws {ParseError} When input is not a valid hex string
+ * @see {@link from} for Effect-based creation
+ * @since 0.0.1
+ */
+export const Schema: S.Schema<FilterIdType, string> = S.transformOrFail(
+	S.String,
+	FilterIdTypeSchema,
+	{
+		strict: true,
+		decode: (s, _options, ast) => {
+			try {
+				return ParseResult.succeed(FilterId.from(s));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, s, (e as Error).message),
+				);
+			}
+		},
+		encode: (f) => ParseResult.succeed(f as string),
+	},
+).annotations({ identifier: "FilterIdSchema" });

package/src/primitives/FilterId/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview FilterId module for Ethereum JSON-RPC filter identifiers.
+ * @module FilterId
+ * @since 0.0.1
+ *
+ * @description
+ * Filter IDs are unique identifiers returned by Ethereum JSON-RPC filter methods.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as FilterId from 'voltaire-effect/primitives/FilterId'
+ *
+ * function pollFilter(filterId: FilterId.FilterIdType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * Filter IDs are returned by Ethereum JSON-RPC filter methods:
+ * - eth_newFilter: Creates a filter for event logs
+ * - eth_newBlockFilter: Creates a filter for new blocks
+ * - eth_newPendingTransactionFilter: Creates a filter for pending transactions
+ *
+ * These IDs are used with:
+ * - eth_getFilterChanges: Poll for new results
+ * - eth_getFilterLogs: Get all logs matching the filter
+ * - eth_uninstallFilter: Remove the filter
+ *
+ * This module provides:
+ * - Type-safe branded FilterIdType
+ * - Effect Schema for validation
+ * - Effect-based creation with error handling
+ *
+ * @example
+ * ```typescript
+ * import * as FilterId from 'voltaire-effect/primitives/FilterId'
+ * import * as Effect from 'effect/Effect'
+ * import * as S from 'effect/Schema'
+ *
+ * // Create from JSON-RPC response
+ * const filterId = Effect.runSync(FilterId.from('0x1'))
+ *
+ * // Using the Schema for validation
+ * const parsed = S.decodeSync(FilterId.Schema)('0xabc')
+ *
+ * // In Effect.gen
+ * const program = Effect.gen(function* () {
+ *   const id = yield* FilterId.from('0x1')
+ *   // Use id with eth_getFilterChanges
+ * })
+ * ```
+ *
+ * @see {@link Schema} for Effect Schema integration
+ * @see {@link from} for Effect-based creation
+ * @see {@link FilterIdError} for error handling
+ */
+export { type FilterIdType, Schema } from "./Hex.js";