voltaire-effect 0.2.23

package/src/crypto/Bn254/Bn254Service.ts

@@ -0,0 +1,369 @@
+/**
+ * @fileoverview BN254 (alt_bn128) elliptic curve service for Effect-based applications.
+ * Provides pairing operations for zkSNARK verification and EVM precompiles.
+ * @module Bn254Service
+ * @since 0.0.1
+ */
+
+import { BN254 } from "@tevm/voltaire";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+/**
+ * G1 point on the BN254 curve.
+ * @since 0.0.1
+ */
+export type BN254G1PointType = {
+	x: bigint;
+	y: bigint;
+	z: bigint;
+};
+
+/**
+ * G2 point on the BN254 curve (extension field).
+ * @since 0.0.1
+ */
+export type BN254G2PointType = {
+	x: { c0: bigint; c1: bigint };
+	y: { c0: bigint; c1: bigint };
+	z: { c0: bigint; c1: bigint };
+};
+
+/**
+ * Error thrown when a BN254 curve operation fails.
+ *
+ * @description
+ * Contains the operation that failed, error message, and optional cause.
+ *
+ * Common failure reasons:
+ * - Invalid point (not on curve)
+ * - Invalid scalar value
+ * - Pairing check input validation failure
+ *
+ * @since 0.0.1
+ */
+export class Bn254Error extends Data.TaggedError("Bn254Error")<{
+	/** The BN254 operation that failed */
+	readonly operation:
+		| "g1Add"
+		| "g1Mul"
+		| "g1Generator"
+		| "g2Add"
+		| "g2Mul"
+		| "g2Generator"
+		| "pairingCheck";
+	/** Human-readable error message */
+	readonly message: string;
+	/** Underlying error that caused this failure */
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Shape interface for BN254 (alt_bn128) elliptic curve operations.
+ *
+ * @description
+ * Defines the contract for BN254 curve operations including G1/G2 point
+ * arithmetic and pairing checks. BN254 is used in Ethereum for zkSNARK
+ * verification via EVM precompiles.
+ *
+ * @see {@link Bn254Service} - The service using this shape
+ * @since 0.0.1
+ */
+export interface Bn254ServiceShape {
+	/**
+	 * Adds two G1 points on the BN254 curve.
+	 *
+	 * @description
+	 * Performs elliptic curve point addition on G1. This operation is
+	 * available as EVM precompile at address 0x06.
+	 *
+	 * @param a - First G1 point
+	 * @param b - Second G1 point
+	 * @returns Effect containing the sum point, or Bn254Error if operation fails
+	 */
+	readonly g1Add: (
+		a: BN254G1PointType,
+		b: BN254G1PointType,
+	) => Effect.Effect<BN254G1PointType, Bn254Error>;
+
+	/**
+	 * Multiplies a G1 point by a scalar.
+	 *
+	 * @description
+	 * Performs scalar multiplication on G1. This operation is
+	 * available as EVM precompile at address 0x07.
+	 *
+	 * @param point - The G1 point
+	 * @param scalar - The scalar multiplier (bigint)
+	 * @returns Effect containing the product point, or Bn254Error if operation fails
+	 */
+	readonly g1Mul: (
+		point: BN254G1PointType,
+		scalar: bigint,
+	) => Effect.Effect<BN254G1PointType, Bn254Error>;
+
+	/**
+	 * Returns the G1 generator point for BN254.
+	 *
+	 * @description
+	 * Returns the standard generator point for the G1 group.
+	 *
+	 * @returns Effect containing the G1 generator point, or Bn254Error if operation fails
+	 */
+	readonly g1Generator: () => Effect.Effect<BN254G1PointType, Bn254Error>;
+
+	/**
+	 * Adds two G2 points on the BN254 curve.
+	 *
+	 * @description
+	 * Performs elliptic curve point addition on the G2 extension field.
+	 *
+	 * @param a - First G2 point
+	 * @param b - Second G2 point
+	 * @returns Effect containing the sum point, or Bn254Error if operation fails
+	 */
+	readonly g2Add: (
+		a: BN254G2PointType,
+		b: BN254G2PointType,
+	) => Effect.Effect<BN254G2PointType, Bn254Error>;
+
+	/**
+	 * Multiplies a G2 point by a scalar.
+	 *
+	 * @description
+	 * Performs scalar multiplication on the G2 extension field.
+	 *
+	 * @param point - The G2 point
+	 * @param scalar - The scalar multiplier (bigint)
+	 * @returns Effect containing the product point, or Bn254Error if operation fails
+	 */
+	readonly g2Mul: (
+		point: BN254G2PointType,
+		scalar: bigint,
+	) => Effect.Effect<BN254G2PointType, Bn254Error>;
+
+	/**
+	 * Returns the G2 generator point for BN254.
+	 *
+	 * @description
+	 * Returns the standard generator point for the G2 group.
+	 *
+	 * @returns Effect containing the G2 generator point, or Bn254Error if operation fails
+	 */
+	readonly g2Generator: () => Effect.Effect<BN254G2PointType, Bn254Error>;
+
+	/**
+	 * Performs a pairing check on pairs of G1 and G2 points.
+	 *
+	 * @description
+	 * Verifies that the product of pairings equals the identity element.
+	 * This is the core operation for zkSNARK verification. Available as
+	 * EVM precompile at address 0x08.
+	 *
+	 * @param pairs - Array of [G1, G2] point pairs
+	 * @returns Effect containing true if pairing check passes, or Bn254Error if operation fails
+	 */
+	readonly pairingCheck: (
+		pairs: ReadonlyArray<readonly [BN254G1PointType, BN254G2PointType]>,
+	) => Effect.Effect<boolean, Bn254Error>;
+}
+
+/**
+ * BN254 (alt_bn128) elliptic curve service for Effect-based applications.
+ *
+ * @description
+ * BN254 (also known as alt_bn128) is a pairing-friendly elliptic curve
+ * used in Ethereum for zkSNARK verification. It provides efficient
+ * bilinear pairings enabling zero-knowledge proofs.
+ *
+ * EVM Precompiles:
+ * - 0x06: G1 point addition (ecAdd)
+ * - 0x07: G1 scalar multiplication (ecMul)
+ * - 0x08: Pairing check (ecPairing)
+ *
+ * Key features:
+ * - zkSNARK proof verification
+ * - EVM precompile compatibility
+ * - Bilinear pairing operations
+ * - Used in zkRollups, Tornado Cash, etc.
+ *
+ * @example
+ * ```typescript
+ * import { Bn254Service, Bn254Live } from 'voltaire-effect/crypto'
+ * import * as Effect from 'effect/Effect'
+ *
+ * // G1 operations
+ * const program = Effect.gen(function* () {
+ *   const bn254 = yield* Bn254Service
+ *
+ *   // Get generator and perform scalar multiplication
+ *   const g1 = yield* bn254.g1Generator()
+ *   const point2x = yield* bn254.g1Mul(g1, 2n)
+ *
+ *   // Point addition
+ *   const sum = yield* bn254.g1Add(g1, point2x)
+ *
+ *   return sum
+ * }).pipe(Effect.provide(Bn254Live))
+ *
+ * const result = await Effect.runPromise(program)
+ * ```
+ *
+ * @see {@link Bn254Live} - Production layer using native BN254
+ * @see {@link Bn254Test} - Test layer with deterministic output
+ * @see {@link g1Add}, {@link g1Mul}, {@link pairingCheck} - Standalone functions
+ * @since 0.0.1
+ */
+export class Bn254Service extends Context.Tag("Bn254Service")<
+	Bn254Service,
+	Bn254ServiceShape
+>() {}
+
+/**
+ * Production layer for Bn254Service using native BN254 implementation.
+ *
+ * @description
+ * Provides the live implementation backed by the high-performance native
+ * BN254 implementation from @tevm/voltaire. Use this layer in production
+ * applications for real cryptographic operations.
+ *
+ * @example
+ * ```typescript
+ * import { Bn254Service, Bn254Live } from 'voltaire-effect/crypto'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const bn254 = yield* Bn254Service
+ *   const g1 = yield* bn254.g1Generator()
+ *   return yield* bn254.g1Mul(g1, 42n)
+ * }).pipe(Effect.provide(Bn254Live))
+ * ```
+ *
+ * @see {@link Bn254Service} - The service definition
+ * @see {@link Bn254Test} - Test layer for unit testing
+ * @since 0.0.1
+ */
+export const Bn254Live = Layer.succeed(Bn254Service, {
+	g1Add: (a, b) =>
+		Effect.try({
+			try: () => BN254.G1.add(a as never, b as never),
+			catch: (e) =>
+				new Bn254Error({
+					operation: "g1Add",
+					message: `G1 point addition failed: ${e}`,
+					cause: e,
+				}),
+		}),
+	g1Mul: (point, scalar) =>
+		Effect.try({
+			try: () => BN254.G1.mul(point as never, scalar),
+			catch: (e) =>
+				new Bn254Error({
+					operation: "g1Mul",
+					message: `G1 scalar multiplication failed: ${e}`,
+					cause: e,
+				}),
+		}),
+	g1Generator: () =>
+		Effect.try({
+			try: () => BN254.G1.generator(),
+			catch: (e) =>
+				new Bn254Error({
+					operation: "g1Generator",
+					message: `Failed to get G1 generator: ${e}`,
+					cause: e,
+				}),
+		}),
+	g2Add: (a, b) =>
+		Effect.try({
+			try: () => BN254.G2.add(a as never, b as never),
+			catch: (e) =>
+				new Bn254Error({
+					operation: "g2Add",
+					message: `G2 point addition failed: ${e}`,
+					cause: e,
+				}),
+		}),
+	g2Mul: (point, scalar) =>
+		Effect.try({
+			try: () => BN254.G2.mul(point as never, scalar),
+			catch: (e) =>
+				new Bn254Error({
+					operation: "g2Mul",
+					message: `G2 scalar multiplication failed: ${e}`,
+					cause: e,
+				}),
+		}),
+	g2Generator: () =>
+		Effect.try({
+			try: () => BN254.G2.generator(),
+			catch: (e) =>
+				new Bn254Error({
+					operation: "g2Generator",
+					message: `Failed to get G2 generator: ${e}`,
+					cause: e,
+				}),
+		}),
+	pairingCheck: (pairs) =>
+		Effect.try({
+			try: () => BN254.Pairing.pairingCheck(pairs as never),
+			catch: (e) =>
+				new Bn254Error({
+					operation: "pairingCheck",
+					message: `Pairing check failed: ${e}`,
+					cause: e,
+				}),
+		}),
+});
+
+const mockG1Point: BN254G1PointType = {
+	x: 1n,
+	y: 2n,
+	z: 1n,
+} as BN254G1PointType;
+const mockG2Point: BN254G2PointType = {
+	x: { c0: 1n, c1: 0n },
+	y: { c0: 1n, c1: 0n },
+	z: { c0: 1n, c1: 0n },
+} as BN254G2PointType;
+
+/**
+ * Test layer for Bn254Service returning deterministic mock values.
+ *
+ * @description
+ * Provides a mock implementation for unit testing that returns predictable
+ * values without performing actual curve operations. Use this layer to test
+ * code that depends on Bn254Service without cryptographic overhead.
+ *
+ * Mock behaviors:
+ * - All G1 operations return a fixed mock G1 point
+ * - All G2 operations return a fixed mock G2 point
+ * - Pairing check always returns true
+ *
+ * @example
+ * ```typescript
+ * import { Bn254Service, Bn254Test } from 'voltaire-effect/crypto'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const testProgram = Effect.gen(function* () {
+ *   const bn254 = yield* Bn254Service
+ *   const result = yield* bn254.pairingCheck([])
+ *   return result // always true in test mode
+ * }).pipe(Effect.provide(Bn254Test))
+ * ```
+ *
+ * @see {@link Bn254Service} - The service definition
+ * @see {@link Bn254Live} - Production implementation
+ * @since 0.0.1
+ */
+export const Bn254Test = Layer.succeed(Bn254Service, {
+	g1Add: (_a, _b) => Effect.succeed(mockG1Point),
+	g1Mul: (_point, _scalar) => Effect.succeed(mockG1Point),
+	g1Generator: () => Effect.succeed(mockG1Point),
+	g2Add: (_a, _b) => Effect.succeed(mockG2Point),
+	g2Mul: (_point, _scalar) => Effect.succeed(mockG2Point),
+	g2Generator: () => Effect.succeed(mockG2Point),
+	pairingCheck: (_pairs) => Effect.succeed(true),
+});

package/src/crypto/Bn254/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview BN254 (alt_bn128) elliptic curve module for Effect.
+ *
+ * @description
+ * Provides BN254 (alt_bn128) pairing-friendly elliptic curve operations
+ * for zkSNARK verification and EVM precompile compatibility.
+ *
+ * EVM Precompiles:
+ * - 0x06: ecAdd (G1 point addition)
+ * - 0x07: ecMul (G1 scalar multiplication)
+ * - 0x08: ecPairing (pairing check)
+ *
+ * Key features:
+ * - zkSNARK proof verification
+ * - Bilinear pairing operations
+ * - G1 and G2 group arithmetic
+ * - Used in zkRollups, Tornado Cash, etc.
+ *
+ * @example
+ * ```typescript
+ * import { g1Generator, g1Mul, pairingCheck, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const g1 = yield* g1Generator()
+ *   const point = yield* g1Mul(g1, 42n)
+ *   return point
+ * }).pipe(Effect.provide(Bn254Live))
+ *
+ * const result = await Effect.runPromise(program)
+ * ```
+ *
+ * @module Bn254
+ * @since 0.0.1
+ */
+
+export {
+	Bn254Error,
+	Bn254Live,
+	Bn254Service,
+	type Bn254ServiceShape,
+	Bn254Test,
+} from "./Bn254Service.js";
+export {
+	g1Add,
+	g1Generator,
+	g1Mul,
+	g2Add,
+	g2Generator,
+	g2Mul,
+	pairingCheck,
+} from "./operations.js";
+export type {
+	G1PointType as BN254G1PointType,
+	G2PointType as BN254G2PointType,
+} from "./types.js";

package/src/crypto/Bn254/operations.ts

@@ -0,0 +1,259 @@
+/**
+ * @fileoverview Standalone BN254 curve operations for Effect-based applications.
+ * @module Bn254/operations
+ * @since 0.0.1
+ */
+
+import * as Effect from "effect/Effect";
+import {
+	type BN254G1PointType,
+	type BN254G2PointType,
+	type Bn254Error,
+	Bn254Service,
+} from "./Bn254Service.js";
+
+/**
+ * Adds two G1 points on the BN254 curve.
+ *
+ * @description
+ * Performs elliptic curve point addition on the G1 group of BN254.
+ * This corresponds to EVM precompile at address 0x06 (ecAdd).
+ *
+ * @param a - First G1 point
+ * @param b - Second G1 point
+ * @returns Effect containing the sum point or Bn254Error, requiring Bn254Service
+ *
+ * @example
+ * ```typescript
+ * import { g1Add, g1Generator, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const g = yield* g1Generator()
+ *   const sum = yield* g1Add(g, g) // 2G
+ *   return sum
+ * }).pipe(Effect.provide(Bn254Live))
+ * ```
+ *
+ * @see {@link g1Mul} - Scalar multiplication
+ * @see {@link Bn254Service} - Full service interface
+ * @since 0.0.1
+ */
+export const g1Add = (
+	a: BN254G1PointType,
+	b: BN254G1PointType,
+): Effect.Effect<BN254G1PointType, Bn254Error, Bn254Service> =>
+	Effect.gen(function* () {
+		const bn254 = yield* Bn254Service;
+		return yield* bn254.g1Add(a, b);
+	});
+
+/**
+ * Multiplies a G1 point by a scalar on the BN254 curve.
+ *
+ * @description
+ * Performs scalar multiplication on the G1 group of BN254.
+ * This corresponds to EVM precompile at address 0x07 (ecMul).
+ *
+ * @param point - The G1 point
+ * @param scalar - The scalar multiplier (bigint)
+ * @returns Effect containing the product point or Bn254Error, requiring Bn254Service
+ *
+ * @example
+ * ```typescript
+ * import { g1Mul, g1Generator, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const g = yield* g1Generator()
+ *   const point42 = yield* g1Mul(g, 42n)
+ *   return point42
+ * }).pipe(Effect.provide(Bn254Live))
+ * ```
+ *
+ * @see {@link g1Add} - Point addition
+ * @see {@link Bn254Service} - Full service interface
+ * @since 0.0.1
+ */
+export const g1Mul = (
+	point: BN254G1PointType,
+	scalar: bigint,
+): Effect.Effect<BN254G1PointType, Bn254Error, Bn254Service> =>
+	Effect.gen(function* () {
+		const bn254 = yield* Bn254Service;
+		return yield* bn254.g1Mul(point, scalar);
+	});
+
+/**
+ * Returns the G1 generator point for BN254.
+ *
+ * @description
+ * Returns the standard generator point for the G1 group of BN254.
+ * All other G1 points can be derived from this via scalar multiplication.
+ *
+ * @returns Effect containing the G1 generator point or Bn254Error, requiring Bn254Service
+ *
+ * @example
+ * ```typescript
+ * import { g1Generator, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const g = await Effect.runPromise(
+ *   g1Generator().pipe(Effect.provide(Bn254Live))
+ * )
+ * ```
+ *
+ * @see {@link g1Mul} - Use generator with scalar multiplication
+ * @since 0.0.1
+ */
+export const g1Generator = (): Effect.Effect<
+	BN254G1PointType,
+	Bn254Error,
+	Bn254Service
+> =>
+	Effect.gen(function* () {
+		const bn254 = yield* Bn254Service;
+		return yield* bn254.g1Generator();
+	});
+
+/**
+ * Adds two G2 points on the BN254 curve.
+ *
+ * @description
+ * Performs elliptic curve point addition on the G2 extension field group.
+ *
+ * @param a - First G2 point
+ * @param b - Second G2 point
+ * @returns Effect containing the sum point or Bn254Error, requiring Bn254Service
+ *
+ * @example
+ * ```typescript
+ * import { g2Add, g2Generator, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const g = yield* g2Generator()
+ *   const sum = yield* g2Add(g, g)
+ *   return sum
+ * }).pipe(Effect.provide(Bn254Live))
+ * ```
+ *
+ * @see {@link g2Mul} - Scalar multiplication on G2
+ * @since 0.0.1
+ */
+export const g2Add = (
+	a: BN254G2PointType,
+	b: BN254G2PointType,
+): Effect.Effect<BN254G2PointType, Bn254Error, Bn254Service> =>
+	Effect.gen(function* () {
+		const bn254 = yield* Bn254Service;
+		return yield* bn254.g2Add(a, b);
+	});
+
+/**
+ * Multiplies a G2 point by a scalar on the BN254 curve.
+ *
+ * @description
+ * Performs scalar multiplication on the G2 extension field group.
+ *
+ * @param point - The G2 point
+ * @param scalar - The scalar multiplier (bigint)
+ * @returns Effect containing the product point or Bn254Error, requiring Bn254Service
+ *
+ * @example
+ * ```typescript
+ * import { g2Mul, g2Generator, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const g = yield* g2Generator()
+ *   const point42 = yield* g2Mul(g, 42n)
+ *   return point42
+ * }).pipe(Effect.provide(Bn254Live))
+ * ```
+ *
+ * @see {@link g2Add} - Point addition on G2
+ * @since 0.0.1
+ */
+export const g2Mul = (
+	point: BN254G2PointType,
+	scalar: bigint,
+): Effect.Effect<BN254G2PointType, Bn254Error, Bn254Service> =>
+	Effect.gen(function* () {
+		const bn254 = yield* Bn254Service;
+		return yield* bn254.g2Mul(point, scalar);
+	});
+
+/**
+ * Returns the G2 generator point for BN254.
+ *
+ * @description
+ * Returns the standard generator point for the G2 group of BN254.
+ *
+ * @returns Effect containing the G2 generator point or Bn254Error, requiring Bn254Service
+ *
+ * @example
+ * ```typescript
+ * import { g2Generator, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const g = await Effect.runPromise(
+ *   g2Generator().pipe(Effect.provide(Bn254Live))
+ * )
+ * ```
+ *
+ * @see {@link g2Mul} - Use generator with scalar multiplication
+ * @since 0.0.1
+ */
+export const g2Generator = (): Effect.Effect<
+	BN254G2PointType,
+	Bn254Error,
+	Bn254Service
+> =>
+	Effect.gen(function* () {
+		const bn254 = yield* Bn254Service;
+		return yield* bn254.g2Generator();
+	});
+
+/**
+ * Performs a pairing check on pairs of G1 and G2 points.
+ *
+ * @description
+ * Verifies that the product of pairings equals the identity element:
+ * e(A1, B1) * e(A2, B2) * ... = 1
+ *
+ * This is the core operation for zkSNARK verification and corresponds
+ * to EVM precompile at address 0x08 (ecPairing).
+ *
+ * @param pairs - Array of [G1, G2] point pairs
+ * @returns Effect containing true if pairing check passes or Bn254Error, requiring Bn254Service
+ *
+ * @example
+ * ```typescript
+ * import { pairingCheck, g1Generator, g2Generator, Bn254Live } from 'voltaire-effect/crypto/Bn254'
+ * import * as Effect from 'effect/Effect'
+ *
+ * // Verify a zkSNARK proof
+ * const verifyProof = Effect.gen(function* () {
+ *   const g1 = yield* g1Generator()
+ *   const g2 = yield* g2Generator()
+ *
+ *   // Construct pairing pairs from proof elements
+ *   const pairs = [[g1, g2], [proofA, proofB]] as const
+ *
+ *   const isValid = yield* pairingCheck(pairs)
+ *   return isValid
+ * }).pipe(Effect.provide(Bn254Live))
+ * ```
+ *
+ * @see {@link g1Generator}, {@link g2Generator} - Get generator points
+ * @see {@link Bn254Service} - Full service interface
+ * @since 0.0.1
+ */
+export const pairingCheck = (
+	pairs: ReadonlyArray<readonly [BN254G1PointType, BN254G2PointType]>,
+): Effect.Effect<boolean, Bn254Error, Bn254Service> =>
+	Effect.gen(function* () {
+		const bn254 = yield* Bn254Service;
+		return yield* bn254.pairingCheck(pairs);
+	});

package/src/crypto/Bn254/types.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview BN254 point types.
+ * @module Bn254/types
+ * @since 0.0.1
+ */
+
+/**
+ * G1 point type - element of the first pairing group
+ */
+export type G1PointType = Uint8Array & { readonly __brand: "BN254G1Point" };
+
+/**
+ * G2 point type - element of the second pairing group
+ */
+export type G2PointType = Uint8Array & { readonly __brand: "BN254G2Point" };