voltaire-effect 0.2.23

package/src/primitives/CallTrace/CallTraceSchema.ts

@@ -0,0 +1,38 @@
+import type { CallTrace } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as Schema from "effect/Schema";
+
+/**
+ * Type representing an EVM call trace.
+ * Contains information about contract calls during EVM execution.
+ * @since 0.0.1
+ */
+type CallTraceType = CallTrace.CallTraceType;
+
+const CallTraceTypeSchema = Schema.declare<CallTraceType>(
+	(u): u is CallTraceType => {
+		if (typeof u !== "object" || u === null) return false;
+		return "type" in u && "from" in u && "gas" in u;
+	},
+	{ identifier: "CallTrace" },
+);
+
+/**
+ * Effect Schema for validating EVM call traces.
+ * Call traces contain detailed information about contract calls during execution.
+ *
+ * @example
+ * ```typescript
+ * import * as CallTrace from 'voltaire-effect/CallTrace'
+ * import * as Schema from 'effect/Schema'
+ *
+ * const trace = Schema.decodeSync(CallTrace.Schema)(traceData)
+ * ```
+ * @since 0.0.1
+ */
+export const CallTraceSchema: Schema.Schema<CallTraceType, CallTraceType> =
+	Schema.transformOrFail(CallTraceTypeSchema, CallTraceTypeSchema, {
+		strict: true,
+		decode: (t, _options, _ast) => ParseResult.succeed(t),
+		encode: (t) => ParseResult.succeed(t),
+	}).annotations({ identifier: "CallTraceSchema" });

package/src/primitives/CallTrace/flatten.ts

@@ -0,0 +1,21 @@
+import { CallTrace } from "@tevm/voltaire";
+
+type CallTraceType = CallTrace.CallTraceType;
+
+/**
+ * Flattens a call trace tree into a flat array.
+ * Recursively traverses all nested calls.
+ *
+ * @param trace - The root call trace
+ * @returns Flat array of all call traces in the tree
+ * @example
+ * ```typescript
+ * import * as CallTrace from 'voltaire-effect/CallTrace'
+ *
+ * const allCalls = CallTrace.flatten(rootTrace)
+ * const externalCalls = allCalls.filter(c => c.type === 'CALL')
+ * ```
+ * @since 0.0.1
+ */
+export const flatten = (trace: CallTraceType): CallTraceType[] =>
+	CallTrace.flatten(trace);

package/src/primitives/CallTrace/getCalls.ts

@@ -0,0 +1,20 @@
+import { CallTrace } from "@tevm/voltaire";
+
+type CallTraceType = CallTrace.CallTraceType;
+
+/**
+ * Gets the immediate child calls from a call trace.
+ *
+ * @param trace - The parent call trace
+ * @returns Array of child call traces (non-recursive)
+ * @example
+ * ```typescript
+ * import * as CallTrace from 'voltaire-effect/CallTrace'
+ *
+ * const childCalls = CallTrace.getCalls(parentTrace)
+ * console.log(`Found ${childCalls.length} direct subcalls`)
+ * ```
+ * @since 0.0.1
+ */
+export const getCalls = (trace: CallTraceType): readonly CallTraceType[] =>
+	CallTrace.getCalls(trace);

package/src/primitives/CallTrace/hasError.ts

@@ -0,0 +1,22 @@
+import { CallTrace } from "@tevm/voltaire";
+
+type CallTraceType = CallTrace.CallTraceType;
+
+/**
+ * Checks if a call trace contains an error.
+ *
+ * @param trace - The call trace to check
+ * @returns true if the trace or any nested call has an error
+ * @example
+ * ```typescript
+ * import * as CallTrace from 'voltaire-effect/CallTrace'
+ *
+ * const trace = CallTrace.from({ ... })
+ * if (CallTrace.hasError(trace)) {
+ *   console.log('Transaction reverted')
+ * }
+ * ```
+ * @since 0.0.1
+ */
+export const hasError = (trace: CallTraceType): boolean =>
+	CallTrace.hasError(trace);

package/src/primitives/CallTrace/index.ts

@@ -0,0 +1,13 @@
+/**
+ * CallTrace module for analyzing EVM execution traces.
+ * Provides utilities for working with call hierarchies and detecting errors.
+ * @module
+ * @since 0.0.1
+ */
+export {
+	CallTraceSchema,
+	CallTraceSchema as Schema,
+} from "./CallTraceSchema.js";
+export { flatten } from "./flatten.js";
+export { getCalls } from "./getCalls.js";
+export { hasError } from "./hasError.js";

package/src/primitives/Chain/ChainSchema.ts

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview Effect Schema definitions for Ethereum chain configuration.
+ * Provides type-safe schemas for parsing and validating chain definitions.
+ * @module Chain/ChainSchema
+ * @since 0.0.1
+ */
+
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Ethereum hardfork identifiers.
+ *
+ * @description
+ * Represents the various Ethereum protocol upgrades (hardforks) that have
+ * occurred over time. Each hardfork introduces new features or changes
+ * to the EVM and network behavior.
+ *
+ * @since 0.0.1
+ */
+export type Hardfork =
+	| "chainstart"
+	| "homestead"
+	| "dao"
+	| "tangerineWhistle"
+	| "spuriousDragon"
+	| "byzantium"
+	| "constantinople"
+	| "petersburg"
+	| "istanbul"
+	| "muirGlacier"
+	| "berlin"
+	| "london"
+	| "arrowGlacier"
+	| "grayGlacier"
+	| "paris"
+	| "shanghai"
+	| "cancun"
+	| "prague";
+
+/**
+ * Metadata about an Ethereum chain's configuration.
+ *
+ * @description
+ * Contains technical details about a chain's behavior including block times,
+ * gas limits, hardfork activation blocks, and layer information.
+ *
+ * @since 0.0.1
+ */
+export interface ChainMetadata {
+	blockTime: number;
+	gasLimit: number;
+	isTestnet: boolean;
+	isL2: boolean;
+	l1ChainId?: number;
+	latestHardfork: Hardfork;
+	hardforks: Partial<Record<Hardfork, number>>;
+	websocketUrls?: string[];
+}
+
+/**
+ * Native currency configuration for a chain.
+ *
+ * @description
+ * Defines the native currency used on a chain (e.g., ETH on Ethereum,
+ * MATIC on Polygon). All EVM chains have 18 decimals by convention.
+ *
+ * @since 0.0.1
+ */
+export interface NativeCurrency {
+	/** Display name (e.g., "Ether") */
+	name: string;
+	/** Symbol (e.g., "ETH") */
+	symbol: string;
+	/** Decimal places (typically 18) */
+	decimals: number;
+}
+
+/**
+ * Block explorer configuration.
+ *
+ * @description
+ * Configuration for a chain's block explorer, used for generating
+ * transaction and address URLs.
+ *
+ * @since 0.0.1
+ */
+export interface Explorer {
+	/** Display name (e.g., "Etherscan") */
+	name: string;
+	/** Base URL (e.g., "https://etherscan.io") */
+	url: string;
+}
+
+/**
+ * Branded type representing an Ethereum chain configuration.
+ *
+ * @description
+ * A complete chain configuration including chain ID, name, native currency,
+ * RPC endpoints, and block explorers. Compatible with viem/wagmi chain format.
+ *
+ * @since 0.0.1
+ */
+export interface ChainType {
+	readonly __tag: "Chain";
+	id: number;
+	name: string;
+	nativeCurrency: NativeCurrency;
+	rpcUrls?: { default: { http: readonly string[] } };
+	blockExplorers?: { default: Explorer };
+}
+
+const ChainTypeSchema = S.declare<ChainType>(
+	(u): u is ChainType => {
+		if (typeof u !== "object" || u === null) return false;
+		const chain = u as Record<string, unknown>;
+		return (
+			typeof chain.id === "number" &&
+			typeof chain.name === "string" &&
+			typeof chain.nativeCurrency === "object" &&
+			chain.nativeCurrency !== null
+		);
+	},
+	{ identifier: "Chain" },
+);
+
+/**
+ * Input type for creating a Chain.
+ *
+ * @description
+ * The minimal input required to create a ChainType. At minimum, a chain
+ * needs an ID, name, and native currency. RPC URLs and block explorers
+ * are optional.
+ *
+ * @since 0.0.1
+ */
+export interface ChainInput {
+	id: number;
+	name: string;
+	nativeCurrency: NativeCurrency;
+	rpcUrls?: { default: { http: readonly string[] } };
+	blockExplorers?: { default: Explorer };
+}
+
+const ChainInputSchema = S.Struct({
+	id: S.Number,
+	name: S.String,
+	nativeCurrency: S.Struct({
+		name: S.String,
+		symbol: S.String,
+		decimals: S.Number,
+	}),
+	rpcUrls: S.optional(
+		S.Struct({
+			default: S.Struct({
+				http: S.Array(S.String),
+			}),
+		}),
+	),
+	blockExplorers: S.optional(
+		S.Struct({
+			default: S.Struct({
+				name: S.String,
+				url: S.String,
+			}),
+		}),
+	),
+});
+
+/**
+ * Effect Schema for validating Ethereum chain configurations.
+ *
+ * @description
+ * Transforms chain input data into branded ChainType values. Validates
+ * that the chain ID is positive and all required fields are present.
+ *
+ * @example
+ * ```typescript
+ * import * as Chain from 'voltaire-effect/primitives/Chain'
+ * import * as Schema from 'effect/Schema'
+ *
+ * // Create Ethereum mainnet config
+ * const ethereum = Schema.decodeSync(Chain.ChainSchema)({
+ *   id: 1,
+ *   name: 'Ethereum',
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 }
+ * })
+ *
+ * // With RPC URLs
+ * const withRpc = Schema.decodeSync(Chain.ChainSchema)({
+ *   id: 1,
+ *   name: 'Ethereum',
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ *   rpcUrls: { default: { http: ['https://eth.llamarpc.com'] } }
+ * })
+ * ```
+ *
+ * @throws ParseResult.Type - When chain ID is invalid or required fields missing
+ * @see {@link from} for Effect-wrapped chain creation
+ * @since 0.0.1
+ */
+export const ChainSchema: S.Schema<ChainType, ChainInput> = S.transformOrFail(
+	ChainInputSchema,
+	ChainTypeSchema,
+	{
+		strict: true,
+		decode: (value, _options, ast) => {
+			if (typeof value.id !== "number" || value.id <= 0) {
+				return ParseResult.fail(
+					new ParseResult.Type(
+						ast,
+						value,
+						"Chain ID must be a positive integer",
+					),
+				);
+			}
+			return ParseResult.succeed({
+				__tag: "Chain" as const,
+				...value,
+			} as ChainType);
+		},
+		encode: (chain) =>
+			ParseResult.succeed({
+				id: chain.id,
+				name: chain.name,
+				nativeCurrency: chain.nativeCurrency,
+				rpcUrls: chain.rpcUrls,
+				blockExplorers: chain.blockExplorers,
+			}),
+	},
+).annotations({ identifier: "ChainSchema" });

package/src/primitives/Chain/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Chain module for working with Ethereum chain configurations.
+ * Provides Effect-based operations for validating and creating chain definitions.
+ *
+ * @description
+ * This module provides comprehensive support for defining and validating
+ * Ethereum chain configurations.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Chain from 'voltaire-effect/primitives/Chain'
+ *
+ * function switchChain(chain: Chain.ChainType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * Chain configs include:
+ * - Chain ID (unique network identifier)
+ * - Network name
+ * - Native currency (ETH, MATIC, etc.)
+ * - RPC endpoints
+ * - Block explorers
+ *
+ * The format is compatible with viem/wagmi chain definitions.
+ *
+ * @example
+ * ```typescript
+ * import * as Chain from 'voltaire-effect/primitives/Chain'
+ * import * as Effect from 'effect/Effect'
+ *
+ * // Create a chain configuration
+ * const ethereum = Effect.runSync(Chain.from({
+ *   id: 1,
+ *   name: 'Ethereum',
+ *   nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ *   rpcUrls: { default: { http: ['https://eth.llamarpc.com'] } },
+ *   blockExplorers: { default: { name: 'Etherscan', url: 'https://etherscan.io' } }
+ * }))
+ * ```
+ *
+ * @module Chain
+ * @since 0.0.1
+ * @see {@link ChainSchema} for schema-based validation
+ * @see {@link from} for Effect-wrapped creation
+ */
+export {
+	type ChainInput,
+	type ChainMetadata,
+	ChainSchema,
+	ChainSchema as Schema,
+	type ChainType,
+	type Explorer,
+	type Hardfork,
+	type NativeCurrency,
+} from "./ChainSchema.js";

package/src/primitives/ChainHead/ChainHeadSchema.ts

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Effect Schema definitions for blockchain head information.
+ * Provides type-safe schemas for parsing and validating chain head data.
+ * @module ChainHead/ChainHeadSchema
+ * @since 0.0.1
+ */
+
+import { ChainHead } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing the head of a blockchain.
+ *
+ * @description
+ * Contains information about the latest block in a blockchain, including:
+ * - Block number (height)
+ * - Block hash
+ * - Timestamp
+ * - Difficulty (for PoW chains)
+ * - Total difficulty (cumulative)
+ *
+ * @since 0.0.1
+ */
+export type ChainHeadType = ChainHead.ChainHeadType;
+
+/**
+ * Internal schema declaration for validating ChainHeadType instances.
+ * Ensures the object has required number, hash, and timestamp properties.
+ *
+ * @internal
+ */
+const ChainHeadTypeSchema = S.declare<ChainHeadType>(
+	(u): u is ChainHeadType =>
+		u !== null &&
+		typeof u === "object" &&
+		"number" in u &&
+		"hash" in u &&
+		"timestamp" in u,
+	{ identifier: "ChainHead" },
+);
+
+/**
+ * Input type for creating a ChainHead.
+ *
+ * @description
+ * The input required to create a ChainHeadType. Accepts flexible input
+ * types (bigint, number, string) for numeric fields.
+ *
+ * @since 0.0.1
+ */
+export type ChainHeadInput = {
+	/** Block number/height */
+	readonly number: bigint | number | string;
+	/** Block hash as bytes or hex string */
+	readonly hash: Uint8Array | string;
+	/** Unix timestamp */
+	readonly timestamp: bigint | number | string;
+	/** Block difficulty (optional, for PoW) */
+	readonly difficulty?: bigint | number | string;
+	/** Total cumulative difficulty (optional) */
+	readonly totalDifficulty?: bigint | number | string;
+};
+
+/**
+ * Effect Schema for validating blockchain head data.
+ *
+ * @description
+ * Transforms input data into branded ChainHeadType values. Validates
+ * that all required fields are present and properly formatted.
+ *
+ * @example
+ * ```typescript
+ * import * as ChainHead from 'voltaire-effect/primitives/ChainHead'
+ * import * as Schema from 'effect/Schema'
+ *
+ * // Create chain head from block data
+ * const head = Schema.decodeSync(ChainHead.ChainHeadSchema)({
+ *   number: 19000000n,
+ *   hash: '0xabc123...',
+ *   timestamp: 1700000000n
+ * })
+ *
+ * // With difficulty (for PoW chains)
+ * const powHead = Schema.decodeSync(ChainHead.ChainHeadSchema)({
+ *   number: 15000000n,
+ *   hash: '0x...',
+ *   timestamp: 1660000000n,
+ *   difficulty: 12000000000000000n,
+ *   totalDifficulty: 58750000000000000000000n
+ * })
+ * ```
+ *
+ * @throws ParseResult.Type - When required fields are missing or invalid
+ * @see {@link from} for Effect-wrapped chain head creation
+ * @since 0.0.1
+ */
+export const ChainHeadSchema: S.Schema<ChainHeadType, ChainHeadInput> =
+	S.transformOrFail(
+		S.Struct({
+			number: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			hash: S.Union(S.Uint8ArrayFromSelf, S.String),
+			timestamp: S.Union(S.BigIntFromSelf, S.Number, S.String),
+			difficulty: S.optional(S.Union(S.BigIntFromSelf, S.Number, S.String)),
+			totalDifficulty: S.optional(
+				S.Union(S.BigIntFromSelf, S.Number, S.String),
+			),
+		}),
+		ChainHeadTypeSchema,
+		{
+			strict: true,
+			decode: (input, _options, ast) => {
+				try {
+					return ParseResult.succeed(ChainHead.from(input as any));
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, input, (e as Error).message),
+					);
+				}
+			},
+			encode: (chainHead) =>
+				ParseResult.succeed({
+					number: chainHead.number,
+					hash: chainHead.hash as any,
+					timestamp: chainHead.timestamp,
+					difficulty: chainHead.difficulty,
+					totalDifficulty: chainHead.totalDifficulty,
+				}),
+		},
+	).annotations({ identifier: "ChainHeadSchema" });

package/src/primitives/ChainHead/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview ChainHead module for working with blockchain head information.
+ * Provides Effect-based operations for creating and validating chain head data.
+ *
+ * @description
+ * This module provides tools for working with blockchain head information,
+ * which represents the latest block in a chain. Chain heads are essential for:
+ * - Tracking blockchain progress
+ * - Determining confirmation depth
+ * - Syncing with the network
+ * - Validating new blocks
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as ChainHead from 'voltaire-effect/primitives/ChainHead'
+ *
+ * function processHead(head: ChainHead.ChainHeadType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as ChainHead from 'voltaire-effect/primitives/ChainHead'
+ * import * as Effect from 'effect/Effect'
+ *
+ * // Create a chain head from block data
+ * const head = Effect.runSync(ChainHead.from({
+ *   number: 19000000n,
+ *   hash: '0xabc123...',
+ *   timestamp: 1700000000n
+ * }))
+ *
+ * // Using Schema for validation
+ * import * as S from 'effect/Schema'
+ * const parsed = S.decodeSync(ChainHead.ChainHeadSchema)({
+ *   number: 19000000n,
+ *   hash: '0x...',
+ *   timestamp: 1700000000n
+ * })
+ * ```
+ *
+ * @module ChainHead
+ * @since 0.0.1
+ * @see {@link ChainHeadSchema} for schema-based validation
+ * @see {@link from} for Effect-wrapped creation
+ */
+export {
+	type ChainHeadInput,
+	ChainHeadSchema,
+	type ChainHeadType,
+} from "./ChainHeadSchema.js";

package/src/primitives/ChainId/BigInt.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Effect Schema for ChainId from bigint encoding.
+ * Provides bidirectional transformation between bigints and ChainIdType.
+ *
+ * @module BigInt
+ * @since 0.1.0
+ */
+
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+import type { ChainIdType } from "./Number.js";
+
+/**
+ * Internal schema declaration for ChainIdType.
+ * Validates that a value is a positive integer.
+ *
+ * @internal
+ */
+const ChainIdTypeSchema = S.declare<ChainIdType>(
+	(u): u is ChainIdType =>
+		typeof u === "number" && Number.isInteger(u) && u > 0,
+	{ identifier: "ChainId" },
+);
+
+/**
+ * Schema for ChainId encoded as a bigint.
+ *
+ * @description
+ * Transforms bigints to ChainIdType and vice versa.
+ * Validates that the input is a positive integer within safe number range.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as ChainId from 'voltaire-effect/primitives/ChainId'
+ * import * as S from 'effect/Schema'
+ *
+ * const mainnet = S.decodeSync(ChainId.BigInt)(1n)
+ * const sepolia = S.decodeSync(ChainId.BigInt)(11155111n)
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const bigint = S.encodeSync(ChainId.BigInt)(chainId)
+ * // 1n
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const BigInt: S.Schema<ChainIdType, bigint> = S.transformOrFail(
+	S.BigIntFromSelf,
+	ChainIdTypeSchema,
+	{
+		strict: true,
+		decode: (n, _options, ast) => {
+			if (n <= 0n) {
+				return ParseResult.fail(
+					new ParseResult.Type(
+						ast,
+						n,
+						`Chain ID must be a positive integer, got ${n}`,
+					),
+				);
+			}
+			if (n > globalThis.BigInt(globalThis.Number.MAX_SAFE_INTEGER)) {
+				return ParseResult.fail(
+					new ParseResult.Type(
+						ast,
+						n,
+						`Chain ID exceeds safe integer range: ${n}`,
+					),
+				);
+			}
+			return ParseResult.succeed(globalThis.Number(n) as ChainIdType);
+		},
+		encode: (chainId, _options, _ast) => {
+			return ParseResult.succeed(globalThis.BigInt(chainId));
+		},
+	},
+).annotations({ identifier: "ChainId.BigInt" });