Skip to main content

Try it Live

Run BLS12-381 examples in the interactive playground

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
Security Level: 128-bit (comparable to 3072-bit RSA or 256-bit ECC)

Quick Start

Elliptic Curve Pairing Basics

BLS12-381 is a Barreto-Lynn-Scott curve with embedding degree 12, providing:
  1. Efficient Pairings: Optimal ate pairing computable in ~1-2ms
  2. Signature Aggregation: Combine multiple signatures into one
  3. Batch Verification: Verify many signatures in one pairing check
  4. Short Signatures: G1 signatures (48 bytes) with G2 public keys (96 bytes)
Pairing Map: 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)
Properties:
  • 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

Input Format: 256 bytes
  • 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)
Output Format: 128 bytes (result point)

G1 Scalar Multiplication

Input Format: 160 bytes
  • Bytes 0-127: G1 point (x || y)
  • Bytes 128-159: Scalar (32-byte big-endian)

G1 Multi-Scalar Multiplication (MSM)

Use case: Efficient batch operations (validators, proof aggregation)

G2 Operations

G2 points are over Fp2 extension field (complex numbers over Fp).

G2 Addition

Input Format: 512 bytes (two G2 points) Output Format: 256 bytes (result G2 point)

G2 Scalar Multiplication

Input Format: 288 bytes
  • 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

Input Format: Multiple of 384 bytes
  • Each pair: G1 (128 bytes) || G2 (256 bytes)
Output Format: 32 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

Use case: Hash-to-curve for deterministic point generation

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
Why BLST?
  • 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:
  1. noble/curves: Pure TS implementation (slower, ~10x)
  2. Stub implementations: Return errors for unsupported platforms

Error Handling

BLS12-381 operations throw typed errors that extend CryptoError:
Error Types:
  • Bls12381Error - Base error for BLS12-381 operations
  • InvalidScalarError - Invalid private key (extends InvalidPrivateKeyError)
  • SignatureError - Signature operation failed (extends InvalidSignatureError)
  • InvalidFieldElementError - Invalid field element
  • InvalidPointError - Point not on curve
  • InvalidSubgroupError - Point not in correct subgroup
  • PairingError - 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]
Point Validation:
Signature Security:
  • Rogue key attacks: Prevented by proof-of-possession
  • Signature malleability: Use canonical point representations
  • Domain separation: Hash with context string for different message types
Timing Side-Channels:
  • 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
Optimization Tips:
  • 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_G1ADD
  • 0x0c: BLS12_G1MUL
  • 0x0d: BLS12_G1MULTIEXP
  • 0x0e: BLS12_G2ADD
  • 0x0f: BLS12_G2MUL
  • 0x10: BLS12_G2MULTIEXP
  • 0x11: BLS12_PAIRING
  • 0x12: BLS12_MAP_FP_TO_G1
  • 0x13: BLS12_MAP_FP2_TO_G2
Gas Costs (EIP-2537):
  • G1 addition: 500 gas
  • G1 multiplication: 12,000 gas
  • Pairing (base): 115,000 gas
  • Pairing (per pair): 23,000 gas

References