voltaire-effect 0.2.23

package/src/primitives/Denomination/GweiSchema.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Effect Schema definitions for Gwei denomination values.
+ * Provides type-safe schemas for parsing and validating Gwei amounts.
+ * @module Denomination/GweiSchema
+ * @since 0.0.1
+ */
+
+import { Uint } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Branded type representing Gwei (10^9 Wei, commonly used for gas prices).
+ *
+ * @description
+ * Gwei (gigawei) is the most common unit for expressing gas prices in Ethereum.
+ * - 1 Gwei = 10^9 Wei = 0.000000001 ETH
+ * - Typical gas prices range from 1-500 Gwei
+ *
+ * @example
+ * ```typescript
+ * import type { GweiType } from 'voltaire-effect/primitives/Denomination'
+ *
+ * const gasPrice: GweiType = 30n as GweiType // 30 Gwei gas price
+ * ```
+ *
+ * @since 0.0.1
+ */
+export type GweiType = bigint & { readonly __tag: "Gwei" };
+
+/**
+ * Internal schema declaration for validating GweiType instances.
+ * Ensures the value is a non-negative bigint.
+ *
+ * @internal
+ */
+const GweiTypeSchema = S.declare<GweiType>(
+	(u): u is GweiType => typeof u === "bigint" && u >= 0n,
+	{ identifier: "Gwei" },
+);
+
+/**
+ * Effect Schema for validating Gwei values.
+ *
+ * @description
+ * Transforms bigint, number, or string inputs into branded GweiType values.
+ * Gwei is primarily used for gas prices and fee calculations.
+ *
+ * @example
+ * ```typescript
+ * import * as Denomination from 'voltaire-effect/primitives/Denomination'
+ * import * as Schema from 'effect/Schema'
+ *
+ * // Parse a gas price of 30 Gwei
+ * const gwei = Schema.decodeSync(Denomination.GweiSchema)(30n)
+ *
+ * // From string
+ * const fromStr = Schema.decodeSync(Denomination.GweiSchema)('50')
+ *
+ * // Encode back
+ * const encoded = Schema.encodeSync(Denomination.GweiSchema)(gwei)
+ * ```
+ *
+ * @throws ParseResult.Type - When the input is negative or cannot be converted
+ * @see {@link WeiSchema} for base unit values
+ * @see {@link EtherSchema} for human-readable amounts
+ * @since 0.0.1
+ */
+export const GweiSchema: S.Schema<GweiType, bigint | number | string> =
+	S.transformOrFail(
+		S.Union(S.BigIntFromSelf, S.Number, S.String),
+		GweiTypeSchema,
+		{
+			strict: true,
+			decode: (value, _options, ast) => {
+				try {
+					return ParseResult.succeed(Uint.from(value) as unknown as GweiType);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, value, (e as Error).message),
+					);
+				}
+			},
+			encode: (gwei) => ParseResult.succeed(gwei),
+		},
+	).annotations({ identifier: "GweiSchema" });

package/src/primitives/Denomination/WeiSchema.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Effect Schema definitions for Wei denomination values.
+ * Provides type-safe schemas for parsing and validating Wei amounts.
+ * @module Denomination/WeiSchema
+ * @since 0.0.1
+ */
+
+import { Uint } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Branded type representing Wei (smallest Ether unit, 10^-18 ETH).
+ *
+ * @description
+ * Wei is the smallest denomination of Ether. All Ethereum values are
+ * ultimately represented in Wei for precise arithmetic operations.
+ * - 1 Ether = 10^18 Wei
+ * - 1 Gwei = 10^9 Wei
+ *
+ * @example
+ * ```typescript
+ * import type { WeiType } from 'voltaire-effect/primitives/Denomination'
+ *
+ * const oneEth: WeiType = 1000000000000000000n as WeiType
+ * ```
+ *
+ * @since 0.0.1
+ */
+export type WeiType = bigint & { readonly __tag: "Wei" };
+
+/**
+ * Internal schema declaration for validating WeiType instances.
+ * Ensures the value is a non-negative bigint.
+ *
+ * @internal
+ */
+const WeiTypeSchema = S.declare<WeiType>(
+	(u): u is WeiType => typeof u === "bigint" && u >= 0n,
+	{ identifier: "Wei" },
+);
+
+/**
+ * Effect Schema for validating Wei values.
+ *
+ * @description
+ * Transforms bigint, number, or string inputs into branded WeiType values.
+ * Wei is the base unit for all Ethereum value calculations.
+ *
+ * @example
+ * ```typescript
+ * import * as Denomination from 'voltaire-effect/primitives/Denomination'
+ * import * as Schema from 'effect/Schema'
+ *
+ * // Parse 1 ETH in Wei
+ * const wei = Schema.decodeSync(Denomination.WeiSchema)(1000000000000000000n)
+ *
+ * // From string
+ * const fromStr = Schema.decodeSync(Denomination.WeiSchema)('1000000')
+ *
+ * // Encode back
+ * const encoded = Schema.encodeSync(Denomination.WeiSchema)(wei)
+ * ```
+ *
+ * @throws ParseResult.Type - When the input is negative or cannot be converted
+ * @see {@link GweiSchema} for gas price units
+ * @see {@link EtherSchema} for human-readable amounts
+ * @since 0.0.1
+ */
+export const WeiSchema: S.Schema<WeiType, bigint | number | string> =
+	S.transformOrFail(
+		S.Union(S.BigIntFromSelf, S.Number, S.String),
+		WeiTypeSchema,
+		{
+			strict: true,
+			decode: (value, _options, ast) => {
+				try {
+					return ParseResult.succeed(Uint.from(value) as unknown as WeiType);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, value, (e as Error).message),
+					);
+				}
+			},
+			encode: (wei) => ParseResult.succeed(wei),
+		},
+	).annotations({ identifier: "WeiSchema" });

package/src/primitives/Denomination/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Denomination module for working with Ethereum value denominations.
+ * Provides Effect-based operations for converting between Wei, Gwei, and Ether.
+ *
+ * @description
+ * This module provides comprehensive support for Ethereum's three main denominations:
+ * - **Wei**: The smallest unit (10^-18 ETH), used for precise calculations
+ * - **Gwei**: Common for gas prices (10^9 Wei), used in fee estimation
+ * - **Ether**: The primary unit (10^18 Wei), used in wallets and UIs
+ *
+ * All values are represented as branded bigints for type safety, preventing
+ * accidental mixing of different denominations.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Denomination from 'voltaire-effect/primitives/Denomination'
+ *
+ * function displayEther(value: Denomination.EtherType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import * as Denomination from 'voltaire-effect/primitives/Denomination'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   // Create values in different denominations
+ *   const eth = yield* Denomination.fromEther(1n)
+ *   const gwei = yield* Denomination.fromGwei(30n)
+ *
+ *   // Convert between denominations
+ *   const weiFromEth = yield* Denomination.etherToWei(eth)
+ *   const weiFromGwei = yield* Denomination.gweiToWei(gwei)
+ *
+ *   return { weiFromEth, weiFromGwei }
+ * })
+ * ```
+ *
+ * @module Denomination
+ * @since 0.0.1
+ * @see {@link WeiSchema} for Wei validation
+ * @see {@link GweiSchema} for Gwei validation
+ * @see {@link EtherSchema} for Ether validation
+ */
+
+export { EtherSchema, type EtherType } from "./EtherSchema.js";

package/src/primitives/Domain/Domain.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "@effect/vitest";
+import { hash as keccak256 } from "@tevm/voltaire/Keccak256";
+import * as Schema from "effect/Schema";
+import * as Domain from "./index.js";
+
+describe("Domain.Struct", () => {
+	describe("decode", () => {
+		it("decodes valid domain object", () => {
+			const input = {
+				name: "MyDApp",
+				version: "1",
+				chainId: 1n,
+			};
+			const result = Schema.decodeSync(Domain.Struct)(input);
+			expect(result.name).toBe("MyDApp");
+			expect(result.version).toBe("1");
+		});
+
+		it("decodes with verifying contract", () => {
+			const input = {
+				name: "MyDApp",
+				version: "1",
+				chainId: 1n,
+				verifyingContract: `0x${"00".repeat(20)}`,
+			};
+			const result = Schema.decodeSync(Domain.Struct)(input);
+			expect(result.name).toBe("MyDApp");
+		});
+	});
+
+	describe("encode", () => {
+		it("encodes back to input format", () => {
+			const input = {
+				name: "MyDApp",
+				version: "1",
+				chainId: 1n,
+			};
+			const domain = Schema.decodeSync(Domain.Struct)(input);
+			const encoded = Schema.encodeSync(Domain.Struct)(domain);
+			expect(encoded.name).toBe("MyDApp");
+			expect(encoded.version).toBe("1");
+		});
+	});
+});
+
+describe("pure functions", () => {
+	it("toHash computes domain separator hash", () => {
+		const input = {
+			name: "MyDApp",
+			version: "1",
+			chainId: 1n,
+		};
+		const domain = Schema.decodeSync(Domain.Struct)(input);
+		const hash = Domain.toHash(domain, { keccak256 });
+		expect(hash).toBeInstanceOf(Uint8Array);
+		expect(hash.length).toBe(32);
+	});
+
+	it("getEIP712DomainType returns domain type fields", () => {
+		const input = {
+			name: "MyDApp",
+			version: "1",
+			chainId: 1n,
+		};
+		const domain = Schema.decodeSync(Domain.Struct)(input);
+		const fields = Domain.getEIP712DomainType(domain);
+		expect(Array.isArray(fields)).toBe(true);
+		expect(fields.some((f) => f.name === "name")).toBe(true);
+	});
+
+	it("getFieldsBitmap returns bitmap of present fields", () => {
+		const input = {
+			name: "MyDApp",
+			version: "1",
+		};
+		const domain = Schema.decodeSync(Domain.Struct)(input);
+		const bitmap = Domain.getFieldsBitmap(domain);
+		expect(bitmap).toBeInstanceOf(Uint8Array);
+	});
+});

package/src/primitives/Domain/Struct.ts

@@ -0,0 +1,165 @@
+import { Domain } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing an EIP-712 typed data domain.
+ * @since 0.0.1
+ */
+export type DomainType = ReturnType<typeof Domain.from>;
+
+const DomainTypeSchema = S.declare<DomainType>(
+	(u): u is DomainType => u !== null && typeof u === "object",
+	{ identifier: "Domain" },
+);
+
+/**
+ * Input type for creating an EIP-712 domain.
+ * @since 0.0.1
+ */
+export type DomainInput = {
+	readonly name?: string;
+	readonly version?: string;
+	readonly chainId?: bigint | number;
+	readonly verifyingContract?: Uint8Array | string;
+	readonly salt?: Uint8Array | string;
+};
+
+/**
+ * Effect Schema for EIP-712 domain structs.
+ *
+ * @description
+ * Transforms domain input objects into validated DomainType.
+ * Used for EIP-712 typed data signing.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as Domain from 'voltaire-effect/primitives/Domain'
+ * import * as S from 'effect/Schema'
+ *
+ * const domain = S.decodeSync(Domain.Struct)({
+ *   name: 'MyApp',
+ *   version: '1',
+ *   chainId: 1n
+ * })
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const input = S.encodeSync(Domain.Struct)(domain)
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Struct: S.Schema<DomainType, DomainInput> = S.transformOrFail(
+	S.Struct({
+		name: S.optional(S.String),
+		version: S.optional(S.String),
+		chainId: S.optional(S.Union(S.BigIntFromSelf, S.Number)),
+		verifyingContract: S.optional(S.Union(S.Uint8ArrayFromSelf, S.String)),
+		salt: S.optional(S.Union(S.Uint8ArrayFromSelf, S.String)),
+	}),
+	DomainTypeSchema,
+	{
+		strict: true,
+		decode: (input, _options, ast) => {
+			try {
+				return ParseResult.succeed(Domain.from(input as any));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, input, (e as Error).message),
+				);
+			}
+		},
+		encode: (domain) =>
+			ParseResult.succeed({
+				name: domain.name,
+				version: domain.version,
+				chainId: domain.chainId as any,
+				verifyingContract: domain.verifyingContract as any,
+				salt: domain.salt as any,
+			}),
+	},
+).annotations({ identifier: "Domain.Struct" });
+
+export { Struct as DomainSchema };
+
+/**
+ * Computes the EIP-712 domain separator hash.
+ *
+ * @param domain - The domain to hash
+ * @param crypto - Crypto provider with keccak256
+ * @returns The domain separator hash (32 bytes)
+ * @since 0.1.0
+ */
+export const toHash = (
+	domain: DomainType,
+	crypto: { keccak256: (data: Uint8Array) => Uint8Array },
+): Uint8Array => Domain.toHash(domain, crypto);
+
+/**
+ * Encodes EIP-712 type definitions.
+ *
+ * @param primaryType - The primary type name
+ * @param types - Type definitions
+ * @returns Encoded type string
+ * @since 0.1.0
+ */
+export const encodeType = (
+	primaryType: string,
+	types: Record<
+		string,
+		readonly { readonly name: string; readonly type: string }[]
+	>,
+): string => Domain.encodeType(primaryType, types);
+
+/**
+ * Computes the hash of an EIP-712 type.
+ *
+ * @param primaryType - The primary type name
+ * @param types - Type definitions
+ * @param crypto - Crypto provider with keccak256
+ * @returns Type hash (32 bytes)
+ * @since 0.1.0
+ */
+export const hashType = (
+	primaryType: string,
+	types: Record<
+		string,
+		readonly { readonly name: string; readonly type: string }[]
+	>,
+	crypto: { keccak256: (data: Uint8Array) => Uint8Array },
+): Uint8Array => Domain.hashType(primaryType, types, crypto);
+
+/**
+ * Gets the EIP-712 domain type definition.
+ *
+ * @param domain - The domain
+ * @returns Array of field definitions
+ * @since 0.1.0
+ */
+export const getEIP712DomainType = (
+	domain: DomainType,
+): Array<{ name: string; type: string }> => Domain.getEIP712DomainType(domain);
+
+/**
+ * Gets the fields bitmap for ERC-5267.
+ *
+ * @param domain - The domain
+ * @returns Bitmap bytes
+ * @since 0.1.0
+ */
+export const getFieldsBitmap = (domain: DomainType): Uint8Array =>
+	Domain.getFieldsBitmap(domain);
+
+/**
+ * Converts domain to ERC-5267 response format.
+ *
+ * @param domain - The domain
+ * @returns ERC-5267 response
+ * @since 0.1.0
+ */
+export const toErc5267Response = (
+	domain: DomainType,
+): ReturnType<typeof Domain.toErc5267Response> =>
+	Domain.toErc5267Response(domain);

package/src/primitives/Domain/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @module Domain
+ * @description Effect Schemas for EIP-712 typed data domains.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Domain from 'voltaire-effect/primitives/Domain'
+ *
+ * function hashDomain(domain: Domain.DomainType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Schemas
+ *
+ * | Schema | Input | Output |
+ * |--------|-------|--------|
+ * | `Domain.Struct` | DomainInput object | DomainType |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import * as Domain from 'voltaire-effect/primitives/Domain'
+ * import * as S from 'effect/Schema'
+ *
+ * // Decode (parse input)
+ * const domain = S.decodeSync(Domain.Struct)({
+ *   name: 'MyApp',
+ *   version: '1',
+ *   chainId: 1n
+ * })
+ *
+ * // Encode (format output)
+ * const input = S.encodeSync(Domain.Struct)(domain)
+ * ```
+ *
+ * ## Pure Functions
+ *
+ * ```typescript
+ * Domain.toHash(domain, { keccak256 })  // Uint8Array (32 bytes)
+ * Domain.encodeType(primaryType, types)  // string
+ * Domain.hashType(primaryType, types, { keccak256 })  // Uint8Array
+ * Domain.getEIP712DomainType(domain)  // Array<{ name, type }>
+ * Domain.getFieldsBitmap(domain)  // Uint8Array
+ * Domain.toErc5267Response(domain)  // ERC-5267 response
+ * ```
+ *
+ * @since 0.1.0
+ */
+export {
+	type DomainInput,
+	DomainSchema,
+	type DomainType,
+	encodeType,
+	getEIP712DomainType,
+	getFieldsBitmap,
+	hashType,
+	Struct,
+	toErc5267Response,
+	toHash,
+} from "./Struct.js";

package/src/primitives/DomainSeparator/DomainSeparator.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Schema from "effect/Schema";
+import * as DomainSeparator from "./index.js";
+
+describe("DomainSeparator.Hex", () => {
+	describe("decode", () => {
+		it("decodes valid hex string", () => {
+			const hex = `0x${"ab".repeat(32)}`;
+			const result = Schema.decodeSync(DomainSeparator.Hex)(hex);
+			expect(result).toBeInstanceOf(Uint8Array);
+			expect(result.length).toBe(32);
+		});
+
+		it("fails for wrong hex length", () => {
+			const hex = `0x${"ab".repeat(16)}`;
+			expect(() => Schema.decodeSync(DomainSeparator.Hex)(hex)).toThrow();
+		});
+	});
+
+	describe("encode", () => {
+		it("encodes back to hex", () => {
+			const hex = `0x${"ab".repeat(32)}`;
+			const decoded = Schema.decodeSync(DomainSeparator.Hex)(hex);
+			const encoded = Schema.encodeSync(DomainSeparator.Hex)(decoded);
+			expect(encoded).toBe(hex);
+		});
+	});
+});
+
+describe("DomainSeparator.Bytes", () => {
+	describe("decode", () => {
+		it("decodes 32-byte Uint8Array", () => {
+			const bytes = new Uint8Array(32).fill(0xab);
+			const result = Schema.decodeSync(DomainSeparator.Bytes)(bytes);
+			expect(result).toBeInstanceOf(Uint8Array);
+			expect(result.length).toBe(32);
+		});
+
+		it("fails for wrong byte length", () => {
+			const bytes = new Uint8Array(16);
+			expect(() => Schema.decodeSync(DomainSeparator.Bytes)(bytes)).toThrow();
+		});
+	});
+
+	describe("encode", () => {
+		it("encodes back to bytes", () => {
+			const bytes = new Uint8Array(32).fill(0xab);
+			const decoded = Schema.decodeSync(DomainSeparator.Bytes)(bytes);
+			const encoded = Schema.encodeSync(DomainSeparator.Bytes)(decoded);
+			expect(encoded).toEqual(bytes);
+		});
+	});
+});
+
+describe("pure functions", () => {
+	it("equals returns true for equal separators", () => {
+		const a = Schema.decodeSync(DomainSeparator.Hex)(`0x${"ab".repeat(32)}`);
+		const b = Schema.decodeSync(DomainSeparator.Hex)(`0x${"ab".repeat(32)}`);
+		expect(DomainSeparator.equals(a, b)).toBe(true);
+	});
+
+	it("equals returns false for different separators", () => {
+		const a = Schema.decodeSync(DomainSeparator.Hex)(`0x${"ab".repeat(32)}`);
+		const b = Schema.decodeSync(DomainSeparator.Hex)(`0x${"cd".repeat(32)}`);
+		expect(DomainSeparator.equals(a, b)).toBe(false);
+	});
+});

package/src/primitives/DomainSeparator/Hex.ts

@@ -0,0 +1,105 @@
+import { DomainSeparator } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing an EIP-712 domain separator (32-byte hash).
+ * @since 0.1.0
+ */
+export type DomainSeparatorType = ReturnType<typeof DomainSeparator.from>;
+
+const DomainSeparatorTypeSchema = S.declare<DomainSeparatorType>(
+	(u): u is DomainSeparatorType => u instanceof Uint8Array && u.length === 32,
+	{ identifier: "DomainSeparator" },
+);
+
+/**
+ * Schema for DomainSeparator encoded as a hex string.
+ *
+ * @description
+ * Transforms hex strings to DomainSeparatorType and vice versa.
+ * Accepts hex strings with 0x prefix.
+ * Encodes to lowercase hex.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as DomainSeparator from 'voltaire-effect/primitives/DomainSeparator'
+ * import * as S from 'effect/Schema'
+ *
+ * const separator = S.decodeSync(DomainSeparator.Hex)('0x...')
+ * ```
+ *
+ * @example Encoding
+ * ```typescript
+ * const hex = S.encodeSync(DomainSeparator.Hex)(separator)
+ * // "0xabcd..."
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Hex: S.Schema<DomainSeparatorType, string> = S.transformOrFail(
+	S.String,
+	DomainSeparatorTypeSchema,
+	{
+		strict: true,
+		decode: (value, _options, ast) => {
+			try {
+				return ParseResult.succeed(DomainSeparator.fromHex(value));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, value, (e as Error).message),
+				);
+			}
+		},
+		encode: (separator) =>
+			ParseResult.succeed(DomainSeparator.toHex(separator)),
+	},
+).annotations({ identifier: "DomainSeparator.Hex" });
+
+export { Hex as DomainSeparatorSchema };
+
+/**
+ * Schema for DomainSeparator from Uint8Array bytes.
+ *
+ * @description
+ * Transforms 32-byte Uint8Array to DomainSeparatorType.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as DomainSeparator from 'voltaire-effect/primitives/DomainSeparator'
+ * import * as S from 'effect/Schema'
+ *
+ * const separator = S.decodeSync(DomainSeparator.Bytes)(bytes)
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Bytes: S.Schema<DomainSeparatorType, Uint8Array> =
+	S.transformOrFail(S.Uint8ArrayFromSelf, DomainSeparatorTypeSchema, {
+		strict: true,
+		decode: (bytes, _options, ast) => {
+			try {
+				return ParseResult.succeed(DomainSeparator.fromBytes(bytes));
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, bytes, (e as Error).message),
+				);
+			}
+		},
+		encode: (separator) => ParseResult.succeed(separator),
+	}).annotations({ identifier: "DomainSeparator.Bytes" });
+
+export { Bytes as DomainSeparatorFromBytesSchema };
+
+/**
+ * Compares two domain separators for equality.
+ *
+ * @param a - First domain separator
+ * @param b - Second domain separator
+ * @returns true if equal
+ * @since 0.1.0
+ */
+export const equals = (
+	a: DomainSeparatorType,
+	b: DomainSeparatorType,
+): boolean => DomainSeparator.equals(a, b);