Try it Live
Run BLS12-381 examples in the interactive playground
Source: bls12_381.zigTests: bls12_g2_operations.test.ts
BLS12-381
Pairing-friendly elliptic curve implementation for Ethereum 2.0 consensus layer signatures and EIP-2537 precompiled contracts.Overview
BLS12-381 is a Barreto-Lynn-Scott pairing-friendly curve designed for optimal security and performance in blockchain applications. It provides 128-bit security, efficient pairing operations, and signature aggregation capabilities essential for proof-of-stake consensus. Ethereum Use Cases:- Ethereum 2.0 Consensus: Validator signature aggregation
- BLS Signatures: Short signatures with efficient batch verification
- EIP-2537: Precompiled contracts for curve operations
- Light clients: Compact sync committee proofs
- Cross-chain bridges: Trustless interoperability proofs
Quick Start
Elliptic Curve Pairing Basics
BLS12-381 is a Barreto-Lynn-Scott curve with embedding degree 12, providing:- Efficient Pairings: Optimal ate pairing computable in ~1-2ms
- Signature Aggregation: Combine multiple signatures into one
- Batch Verification: Verify many signatures in one pairing check
- Short Signatures: G1 signatures (48 bytes) with G2 public keys (96 bytes)
e: G1 × G2 → GT where:
- G1: Points over base field Fp (48-byte compressed, 96-byte uncompressed)
- G2: Points over Fp2 extension (96-byte compressed, 192-byte uncompressed)
- GT: Elements in Fp12 (multiplicative group)
- Bilinearity:
e(aP, bQ) = e(P, Q)^(ab) - Non-degeneracy:
e(G1, G2) ≠ 1 - Computability: Polynomial time optimal ate pairing
API Reference
G1 Operations
G1 points are in the base field Fp (381-bit prime).G1 Addition
- Bytes 0-63: p1.x (Fp, padded to 64 bytes)
- Bytes 64-127: p1.y (Fp)
- Bytes 128-191: p2.x (Fp)
- Bytes 192-255: p2.y (Fp)
G1 Scalar Multiplication
- Bytes 0-127: G1 point (x || y)
- Bytes 128-159: Scalar (32-byte big-endian)
G1 Multi-Scalar Multiplication (MSM)
G2 Operations
G2 points are over Fp2 extension field (complex numbers over Fp).G2 Addition
G2 Scalar Multiplication
- Bytes 0-255: G2 point (x.c0 || x.c1 || y.c0 || y.c1)
- Bytes 256-287: Scalar (32-byte big-endian)
G2 Multi-Scalar Multiplication
Pairing Operations
Optimal Ate Pairing
- Each pair: G1 (128 bytes) || G2 (256 bytes)
- Last byte 0x01: Pairing check passed
- Last byte 0x00: Pairing check failed
Pairing Check (BLS Signature Verification)
Point Mapping
Map Field Element to G1
Map Field Element to G2
Use Cases
BLS Signature Aggregation
Ethereum 2.0 Validator Signatures
Implementation Details
C Library (BLST - Production)
- Library: BLST (Supranational)
- Location:
lib/blst/(git submodule) - Status: Audited, production-grade
- Performance: Assembly-optimized for x86_64, ARM64
- Features:
- Constant-time operations
- Side-channel resistant
- Multi-scalar multiplication (Pippenger)
- Compressed point support
- Official Ethereum Foundation recommendation
- Used in all major Ethereum clients (Prysm, Lighthouse, Teku)
- Extensive security audits (Trail of Bits, NCC Group)
- Performance leader in benchmarks
Zig FFI Wrapper
- Location:
src/crypto/crypto.zig - Purpose: Safe Zig bindings to BLST C library
- Features:
- Error handling wrapper
- Memory safety
- Type-safe point validation
TypeScript API
- Location:
src/crypto/crypto.zig(exported via FFI) - Runtime: Node.js native, Bun FFI, WASM
- Validation: Automatic point validation on all operations
WASM Limitations
BLST unavailable in WASM - C library requires native compilation. Alternatives:- noble/curves: Pure TS implementation (slower, ~10x)
- Stub implementations: Return errors for unsupported platforms
Error Handling
BLS12-381 operations throw typed errors that extendCryptoError:
Bls12381Error- Base error for BLS12-381 operationsInvalidScalarError- Invalid private key (extendsInvalidPrivateKeyError)SignatureError- Signature operation failed (extendsInvalidSignatureError)InvalidFieldElementError- Invalid field elementInvalidPointError- Point not on curveInvalidSubgroupError- Point not in correct subgroupPairingError- Pairing operation failed
Security Considerations
Production Requirements:- Use BLST library (audited, constant-time)
- Validate all deserialized points
- Check subgroup membership (especially G2)
- Verify scalar range [1, r-1]
- Rogue key attacks: Prevented by proof-of-possession
- Signature malleability: Use canonical point representations
- Domain separation: Hash with context string for different message types
- BLST uses constant-time operations
- No branching on secret data
- Resistant to cache-timing attacks
Performance
Native (BLST on x86_64):- G1 addition: ~0.015ms
- G1 multiplication: ~0.08ms
- G2 addition: ~0.025ms
- G2 multiplication: ~0.2ms
- Pairing: ~1.2ms
- Pairing check (2 pairs): ~2ms
- G1 MSM (100 points): ~8ms
- Batch operations with MSM
- Precompute static points
- Use compressed point formats
- Aggregate signatures before verification
Constants
EIP-2537 Precompiles
Status: Proposed (not yet activated on mainnet) Precompile Addresses:0x0b: BLS12_G1ADD0x0c: BLS12_G1MUL0x0d: BLS12_G1MULTIEXP0x0e: BLS12_G2ADD0x0f: BLS12_G2MUL0x10: BLS12_G2MULTIEXP0x11: BLS12_PAIRING0x12: BLS12_MAP_FP_TO_G10x13: BLS12_MAP_FP2_TO_G2
- G1 addition: 500 gas
- G1 multiplication: 12,000 gas
- Pairing (base): 115,000 gas
- Pairing (per pair): 23,000 gas
Related
- Precompiles: BLS12-381 Operations - EIP-2537 implementation
- BN254 - Alternative pairing curve for zkSNARKs
- KZG Commitments - Polynomial commitments using BLS12-381

