voltaire-effect 0.2.23

package/src/primitives/Brand/Brand.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from "vitest";
+import {
+	AddressString,
+	BlockNumber,
+	ChainId,
+	Gas,
+	Gwei,
+	Nonce,
+	NonNegativeInt,
+	PositiveInt,
+	TxHashString,
+	Wei,
+} from "./index.js";
+
+describe("Brand", () => {
+	describe("PositiveInt", () => {
+		it("accepts positive integers", () => {
+			expect(PositiveInt(1)).toBe(1);
+			expect(PositiveInt(100)).toBe(100);
+			expect(PositiveInt(21000)).toBe(21000);
+		});
+
+		it("rejects zero", () => {
+			expect(() => PositiveInt(0)).toThrow();
+		});
+
+		it("rejects negative numbers", () => {
+			expect(() => PositiveInt(-1)).toThrow();
+		});
+
+		it("rejects non-integers", () => {
+			expect(() => PositiveInt(1.5)).toThrow();
+		});
+
+		it("provides option method", () => {
+			expect(PositiveInt.option(5)._tag).toBe("Some");
+			expect(PositiveInt.option(-1)._tag).toBe("None");
+		});
+
+		it("provides either method", () => {
+			const success = PositiveInt.either(5);
+			expect(success._tag).toBe("Right");
+
+			const failure = PositiveInt.either(-1);
+			expect(failure._tag).toBe("Left");
+		});
+
+		it("provides is method", () => {
+			expect(PositiveInt.is(5)).toBe(true);
+			expect(PositiveInt.is(-1)).toBe(false);
+			expect(PositiveInt.is(1.5)).toBe(false);
+		});
+	});
+
+	describe("NonNegativeInt", () => {
+		it("accepts zero", () => {
+			expect(NonNegativeInt(0)).toBe(0);
+		});
+
+		it("accepts positive integers", () => {
+			expect(NonNegativeInt(100)).toBe(100);
+		});
+
+		it("rejects negative numbers", () => {
+			expect(() => NonNegativeInt(-1)).toThrow();
+		});
+	});
+
+	describe("Wei", () => {
+		it("accepts positive bigints", () => {
+			expect(Wei(1000000000000000000n)).toBe(1000000000000000000n);
+		});
+
+		it("accepts zero", () => {
+			expect(Wei(0n)).toBe(0n);
+		});
+
+		it("rejects negative bigints", () => {
+			expect(() => Wei(-1n)).toThrow();
+		});
+	});
+
+	describe("Gwei", () => {
+		it("accepts valid gwei values", () => {
+			expect(Gwei(20n)).toBe(20n);
+			expect(Gwei(0n)).toBe(0n);
+		});
+
+		it("rejects negative values", () => {
+			expect(() => Gwei(-1n)).toThrow();
+		});
+	});
+
+	describe("BlockNumber", () => {
+		it("accepts valid block numbers", () => {
+			expect(BlockNumber(0n)).toBe(0n);
+			expect(BlockNumber(19000000n)).toBe(19000000n);
+		});
+
+		it("rejects negative values", () => {
+			expect(() => BlockNumber(-1n)).toThrow();
+		});
+	});
+
+	describe("ChainId", () => {
+		it("accepts valid chain IDs", () => {
+			expect(ChainId(1n)).toBe(1n);
+			expect(ChainId(11155111n)).toBe(11155111n);
+		});
+
+		it("rejects zero", () => {
+			expect(() => ChainId(0n)).toThrow();
+		});
+
+		it("rejects negative values", () => {
+			expect(() => ChainId(-1n)).toThrow();
+		});
+	});
+
+	describe("Nonce", () => {
+		it("accepts valid nonces", () => {
+			expect(Nonce(0n)).toBe(0n);
+			expect(Nonce(42n)).toBe(42n);
+		});
+
+		it("rejects negative values", () => {
+			expect(() => Nonce(-1n)).toThrow();
+		});
+	});
+
+	describe("Gas", () => {
+		it("accepts valid gas values", () => {
+			expect(Gas(21000n)).toBe(21000n);
+		});
+
+		it("rejects zero", () => {
+			expect(() => Gas(0n)).toThrow();
+		});
+
+		it("rejects negative values", () => {
+			expect(() => Gas(-1n)).toThrow();
+		});
+	});
+
+	describe("Nominal types", () => {
+		describe("TxHashString", () => {
+			it("brands strings without validation", () => {
+				const hash = TxHashString("0xabc123");
+				expect(hash).toBe("0xabc123");
+			});
+
+			it("accepts any string", () => {
+				const invalid = TxHashString("not-a-hash");
+				expect(invalid).toBe("not-a-hash");
+			});
+		});
+
+		describe("AddressString", () => {
+			it("brands strings without validation", () => {
+				const addr = AddressString(
+					"0x742d35Cc6634C0532925a3b844Bc9e7595f251e3",
+				);
+				expect(addr).toBe("0x742d35Cc6634C0532925a3b844Bc9e7595f251e3");
+			});
+		});
+	});
+
+	describe("Type safety", () => {
+		it("branded types are not assignable to each other", () => {
+			const wei: Wei = Wei(100n);
+			const gwei: Gwei = Gwei(100n);
+
+			// @ts-expect-error - Wei is not assignable to Gwei
+			const _wrongAssignment: Gwei = wei;
+
+			// @ts-expect-error - Gwei is not assignable to Wei
+			const _wrongAssignment2: Wei = gwei;
+
+			// Both are bigints at runtime but TypeScript distinguishes them
+			expect(wei === 100n).toBe(true);
+			expect(gwei === 100n).toBe(true);
+		});
+
+		it("branded types can be used as their base type", () => {
+			const gas = Gas(21000n);
+
+			// Can use in arithmetic (bigint operations)
+			const doubled: bigint = gas * 2n;
+			expect(doubled).toBe(42000n);
+		});
+	});
+});

package/src/primitives/Brand/index.ts

@@ -0,0 +1,292 @@
+/**
+ * @module Brand
+ * @description Effect Brand utilities for Ethereum primitive types.
+ *
+ * ## Why NOT use effect/Brand for existing primitives
+ *
+ * Voltaire primitives (Address, Hash, Hex, etc.) use **Uint8Array-based branded types**
+ * defined in @tevm/voltaire. These types use a custom brand symbol for performance:
+ *
+ * ```typescript
+ * // From @tevm/voltaire - AddressType is a branded Uint8Array
+ * type AddressType = Uint8Array & { readonly [brand]: "Address" }
+ * ```
+ *
+ * Effect's Brand module is designed for **primitive types** (string, number) and
+ * works by intersecting with `Brand.Brand<"Tag">`. This creates a conflict:
+ *
+ * 1. **Schema integration**: effect/Schema already provides `.brand()` and
+ *    `Schema.fromBrand()` which work seamlessly with Schema validation pipelines.
+ *    Using standalone Brand constructors would bypass Schema's parse/encode flow.
+ *
+ * 2. **Existing constructors**: @tevm/voltaire already exports constructors like
+ *    `Address()`, `Hash()` that do proper validation and return branded types.
+ *    Adding effect/Brand constructors would duplicate this functionality.
+ *
+ * 3. **Uint8Array base**: Effect Brand expects the base type to match exactly.
+ *    Uint8Array-based brands require additional handling that Schema provides.
+ *
+ * ## Current approach (RECOMMENDED)
+ *
+ * Use Schema-based validation with the existing branded types:
+ *
+ * ```typescript
+ * import * as Address from 'voltaire-effect/primitives/Address'
+ * import * as S from 'effect/Schema'
+ *
+ * // Decode hex string to AddressType (branded Uint8Array)
+ * const addr = S.decodeSync(Address.Hex)('0x742d35Cc6634C0532925a3b844Bc9e7595f251e3')
+ *
+ * // The result is already a branded AddressType
+ * type Check = typeof addr // AddressType
+ * ```
+ *
+ * ## When effect/Brand IS useful
+ *
+ * For NEW types that are based on primitives (string, number, bigint), effect/Brand
+ * can be useful. Examples below show how to create new branded types.
+ *
+ * @since 0.1.0
+ */
+
+import * as Brand from "effect/Brand";
+
+// ============================================================================
+// Example: Creating NEW branded types with effect/Brand
+// ============================================================================
+
+/**
+ * A branded positive integer type.
+ * Use for values that must always be > 0.
+ *
+ * @example
+ * ```typescript
+ * import { PositiveInt } from 'voltaire-effect/primitives/Brand'
+ *
+ * const gasLimit = PositiveInt(21000) // ok
+ * const invalid = PositiveInt(-1)     // throws
+ * ```
+ */
+export type PositiveInt = number & Brand.Brand<"PositiveInt">;
+
+/**
+ * Constructor for PositiveInt.
+ * Throws if the value is not a positive integer.
+ */
+export const PositiveInt = Brand.refined<PositiveInt>(
+	(n): n is Brand.Brand.Unbranded<PositiveInt> => Number.isInteger(n) && n > 0,
+	(n) => Brand.error(`Expected ${n} to be a positive integer`),
+);
+
+/**
+ * A branded non-negative integer type.
+ * Use for values that must be >= 0 (like array indices, gas values).
+ *
+ * @example
+ * ```typescript
+ * import { NonNegativeInt } from 'voltaire-effect/primitives/Brand'
+ *
+ * const index = NonNegativeInt(0)   // ok
+ * const invalid = NonNegativeInt(-1) // throws
+ * ```
+ */
+export type NonNegativeInt = number & Brand.Brand<"NonNegativeInt">;
+
+/**
+ * Constructor for NonNegativeInt.
+ * Throws if the value is not a non-negative integer.
+ */
+export const NonNegativeInt = Brand.refined<NonNegativeInt>(
+	(n): n is Brand.Brand.Unbranded<NonNegativeInt> =>
+		Number.isInteger(n) && n >= 0,
+	(n) => Brand.error(`Expected ${n} to be a non-negative integer`),
+);
+
+/**
+ * A branded Wei value (bigint).
+ * Represents Ethereum's smallest unit of ether.
+ *
+ * @example
+ * ```typescript
+ * import { Wei } from 'voltaire-effect/primitives/Brand'
+ *
+ * const amount = Wei(1000000000000000000n) // 1 ether in wei
+ * const invalid = Wei(-1n)                  // throws (negative wei)
+ * ```
+ */
+export type Wei = bigint & Brand.Brand<"Wei">;
+
+/**
+ * Constructor for Wei.
+ * Throws if the value is negative.
+ */
+export const Wei = Brand.refined<Wei>(
+	(n): n is Brand.Brand.Unbranded<Wei> => n >= 0n,
+	(n) => Brand.error(`Expected ${n} to be a non-negative Wei value`),
+);
+
+/**
+ * A branded Gwei value (bigint).
+ * Represents 10^9 wei, commonly used for gas prices.
+ *
+ * @example
+ * ```typescript
+ * import { Gwei } from 'voltaire-effect/primitives/Brand'
+ *
+ * const gasPrice = Gwei(20n) // 20 gwei
+ * ```
+ */
+export type Gwei = bigint & Brand.Brand<"Gwei">;
+
+/**
+ * Constructor for Gwei.
+ * Throws if the value is negative.
+ */
+export const Gwei = Brand.refined<Gwei>(
+	(n): n is Brand.Brand.Unbranded<Gwei> => n >= 0n,
+	(n) => Brand.error(`Expected ${n} to be a non-negative Gwei value`),
+);
+
+/**
+ * A branded block number type.
+ * Always a non-negative bigint.
+ *
+ * @example
+ * ```typescript
+ * import { BlockNumber } from 'voltaire-effect/primitives/Brand'
+ *
+ * const block = BlockNumber(19000000n)
+ * ```
+ */
+export type BlockNumber = bigint & Brand.Brand<"BlockNumber">;
+
+/**
+ * Constructor for BlockNumber.
+ */
+export const BlockNumber = Brand.refined<BlockNumber>(
+	(n): n is Brand.Brand.Unbranded<BlockNumber> => n >= 0n,
+	(n) => Brand.error(`Expected ${n} to be a valid block number`),
+);
+
+/**
+ * A branded chain ID type.
+ * Must be a positive bigint.
+ *
+ * @example
+ * ```typescript
+ * import { ChainId } from 'voltaire-effect/primitives/Brand'
+ *
+ * const mainnet = ChainId(1n)
+ * const sepolia = ChainId(11155111n)
+ * ```
+ */
+export type ChainId = bigint & Brand.Brand<"ChainId">;
+
+/**
+ * Constructor for ChainId.
+ */
+export const ChainId = Brand.refined<ChainId>(
+	(n): n is Brand.Brand.Unbranded<ChainId> => n > 0n,
+	(n) => Brand.error(`Expected ${n} to be a valid chain ID (positive)`),
+);
+
+/**
+ * A branded nonce type.
+ * Transaction nonce, always a non-negative bigint.
+ *
+ * @example
+ * ```typescript
+ * import { Nonce } from 'voltaire-effect/primitives/Brand'
+ *
+ * const nonce = Nonce(42n)
+ * ```
+ */
+export type Nonce = bigint & Brand.Brand<"Nonce">;
+
+/**
+ * Constructor for Nonce.
+ */
+export const Nonce = Brand.refined<Nonce>(
+	(n): n is Brand.Brand.Unbranded<Nonce> => n >= 0n,
+	(n) => Brand.error(`Expected ${n} to be a valid nonce (non-negative)`),
+);
+
+// ============================================================================
+// Nominal types (no runtime validation, just type distinction)
+// ============================================================================
+
+/**
+ * A nominal type for transaction hashes.
+ * Use when you already have a validated hex string and want type safety.
+ *
+ * @example
+ * ```typescript
+ * import { TxHashString } from 'voltaire-effect/primitives/Brand'
+ *
+ * // No validation, just type branding
+ * const hash = TxHashString('0x...')
+ * ```
+ */
+export type TxHashString = string & Brand.Brand<"TxHashString">;
+
+/**
+ * Nominal constructor for TxHashString.
+ * Does NOT validate - use for already-validated values.
+ */
+export const TxHashString = Brand.nominal<TxHashString>();
+
+/**
+ * A nominal type for address strings.
+ * Use when you already have a validated address and want type safety.
+ *
+ * @example
+ * ```typescript
+ * import { AddressString } from 'voltaire-effect/primitives/Brand'
+ *
+ * // No validation, just type branding
+ * const addr = AddressString('0x742d35Cc6634C0532925a3b844Bc9e7595f251e3')
+ * ```
+ */
+export type AddressString = string & Brand.Brand<"AddressString">;
+
+/**
+ * Nominal constructor for AddressString.
+ * Does NOT validate - use for already-validated values.
+ */
+export const AddressString = Brand.nominal<AddressString>();
+
+// ============================================================================
+// Combining brands
+// ============================================================================
+
+/**
+ * A value that is both positive and represents gas.
+ *
+ * @example
+ * ```typescript
+ * import { Gas } from 'voltaire-effect/primitives/Brand'
+ *
+ * const gas = Gas(21000n) // must be positive
+ * ```
+ */
+export type Gas = bigint & Brand.Brand<"Gas">;
+
+/**
+ * Constructor for Gas values.
+ */
+export const Gas = Brand.refined<Gas>(
+	(n): n is Brand.Brand.Unbranded<Gas> => n > 0n,
+	(n) => Brand.error(`Expected ${n} to be a valid gas value (positive)`),
+);
+
+// ============================================================================
+// Re-export Brand utilities for advanced usage
+// ============================================================================
+
+export {
+	/**
+	 * Create refined branded types with validation.
+	 * @see https://effect.website/docs/code-style/branded-types/
+	 */
+	Brand,
+};

package/src/primitives/BuilderBid/BuilderBidSchema.ts

@@ -0,0 +1,116 @@
+import type { AddressType } from "@tevm/voltaire/Address";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+import { Hex as AddressSchema } from "../Address/Hex.js";
+
+export type BuilderBidType = {
+	readonly builderPubkey: Uint8Array;
+	readonly builderAddress: AddressType;
+	readonly value: bigint;
+	readonly gasLimit: bigint;
+	readonly gasUsed: bigint;
+	readonly slot: bigint;
+	readonly parentHash: Uint8Array;
+	readonly blockHash: Uint8Array;
+	readonly feeRecipient: AddressType;
+	readonly timestamp: bigint;
+};
+
+const BuilderBidTypeSchema = S.declare<BuilderBidType>(
+	(u): u is BuilderBidType =>
+		u !== null &&
+		typeof u === "object" &&
+		"builderPubkey" in u &&
+		"builderAddress" in u &&
+		"value" in u &&
+		"slot" in u,
+	{ identifier: "BuilderBid" },
+);
+
+const HexStringToBytes: S.Schema<Uint8Array, string> = S.transformOrFail(
+	S.String,
+	S.Uint8ArrayFromSelf,
+	{
+		strict: true,
+		decode: (s, _options, ast) => {
+			try {
+				const hex = s.startsWith("0x") ? s.slice(2) : s;
+				if (hex.length === 0) return ParseResult.succeed(new Uint8Array(0));
+				if (hex.length % 2 !== 0) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, s, "Invalid hex string length"),
+					);
+				}
+				const bytes = new Uint8Array(hex.length / 2);
+				for (let i = 0; i < bytes.length; i++) {
+					bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+				}
+				return ParseResult.succeed(bytes);
+			} catch (e) {
+				return ParseResult.fail(
+					new ParseResult.Type(ast, s, (e as Error).message),
+				);
+			}
+		},
+		encode: (bytes) => {
+			const hex = Array.from(bytes)
+				.map((b) => b.toString(16).padStart(2, "0"))
+				.join("");
+			return ParseResult.succeed(`0x${hex}`);
+		},
+	},
+);
+
+const BigIntFromInput: S.Schema<bigint, bigint | number | string> =
+	S.transformOrFail(
+		S.Union(S.BigIntFromSelf, S.Number, S.String),
+		S.BigIntFromSelf,
+		{
+			strict: true,
+			decode: (s, _options, ast) => {
+				try {
+					return ParseResult.succeed(BigInt(s));
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, s, (e as Error).message),
+					);
+				}
+			},
+			encode: (n) => ParseResult.succeed(n),
+		},
+	);
+
+export type BuilderBidInput = {
+	readonly builderPubkey: string;
+	readonly builderAddress: string;
+	readonly value: bigint | number | string;
+	readonly gasLimit: bigint | number | string;
+	readonly gasUsed: bigint | number | string;
+	readonly slot: bigint | number | string;
+	readonly parentHash: string;
+	readonly blockHash: string;
+	readonly feeRecipient: string;
+	readonly timestamp: bigint | number | string;
+};
+
+export const BuilderBidSchema: S.Schema<BuilderBidType, BuilderBidInput> =
+	S.transform(
+		S.Struct({
+			builderPubkey: HexStringToBytes,
+			builderAddress: AddressSchema,
+			value: BigIntFromInput,
+			gasLimit: BigIntFromInput,
+			gasUsed: BigIntFromInput,
+			slot: BigIntFromInput,
+			parentHash: HexStringToBytes,
+			blockHash: HexStringToBytes,
+			feeRecipient: AddressSchema,
+			timestamp: BigIntFromInput,
+		}),
+		BuilderBidTypeSchema,
+		{
+			strict: true,
+			decode: (d) => d as BuilderBidType,
+			encode: (e) => e,
+		},
+	).annotations({ identifier: "BuilderBidSchema" });

package/src/primitives/BuilderBid/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @module BuilderBid
+ *
+ * @description
+ * MEV builder bid for block construction proposals.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as BuilderBid from 'voltaire-effect/primitives/BuilderBid'
+ *
+ * function evaluateBid(bid: BuilderBid.BuilderBidType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Schemas
+ *
+ * | Schema | Input | Output |
+ * |--------|-------|--------|
+ * | `BuilderBidSchema` | BuilderBidInput | BuilderBidType |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import * as BuilderBid from 'voltaire-effect/primitives/BuilderBid'
+ * import * as S from 'effect/Schema'
+ *
+ * const bid = S.decodeSync(BuilderBid.BuilderBidSchema)(input)
+ * ```
+ *
+ * @since 0.1.0
+ */
+export {
+	type BuilderBidInput,
+	BuilderBidSchema,
+	type BuilderBidType,
+} from "./BuilderBidSchema.js";