EVM Precompiles - Voltaire

Overview

Precompiled contracts are special Ethereum addresses (0x01-0x13+) that execute optimized native code instead of EVM bytecode. They provide gas-efficient implementations of computationally expensive operations like cryptographic primitives, hashing, and elliptic curve operations. Tevm provides low-level tree-shakable implementations of all standard precompiles in both TypeScript and Zig, with WASM compilation support for portable high-performance execution. For complete spec-compliant EVM implementations that use these precompiles, see evmts/guillotine and evmts/tevm-monorepo.

Complete Precompile Reference

Address	Name	Gas Cost	Hardfork	Category	Description
0x01	ECRECOVER	3,000	Frontier	Crypto	Recover ECDSA signer address
0x02	SHA256	60 + 12/word	Frontier	Hash	SHA-256 hash function
0x03	RIPEMD160	600 + 120/word	Frontier	Hash	RIPEMD-160 hash function
0x04	IDENTITY	15 + 3/word	Frontier	Data	Copy input to output
0x05	MODEXP	Dynamic	Byzantium	Math	Modular exponentiation
0x06	BN254_ADD	150	Byzantium	zkSNARKs	BN254 G1 point addition
0x07	BN254_MUL	6,000	Byzantium	zkSNARKs	BN254 G1 scalar multiplication
0x08	BN254_PAIRING	45,000 + 34,000k	Byzantium	zkSNARKs	BN254 pairing check
0x09	BLAKE2F	Dynamic	Istanbul	Hash	BLAKE2b compression function
0x0A	POINT_EVALUATION	50,000	Cancun	Blobs	KZG point evaluation (EIP-4844)
0x0B	BLS12_G1_ADD	500	Prague	ETH2	BLS12-381 G1 point addition
0x0C	BLS12_G1_MUL	12,000	Prague	ETH2	BLS12-381 G1 scalar multiplication
0x0D	BLS12_G1_MSM	Variable	Prague	ETH2	BLS12-381 G1 multi-scalar multiplication
0x0E	BLS12_G2_ADD	800	Prague	ETH2	BLS12-381 G2 point addition
0x0F	BLS12_G2_MUL	45,000	Prague	ETH2	BLS12-381 G2 scalar multiplication
0x10	BLS12_G2_MSM	Variable	Prague	ETH2	BLS12-381 G2 multi-scalar multiplication
0x11	BLS12_PAIRING	115,000 + 23,000k	Prague	ETH2	BLS12-381 pairing check
0x12	BLS12_MAP_FP_TO_G1	5,500	Prague	ETH2	Map field element to G1 (hash-to-curve)
0x13	BLS12_MAP_FP2_TO_G2	75,000	Prague	ETH2	Map Fp2 element to G2 (hash-to-curve)

Precompile Categories

Cryptography (0x01)

ECRECOVER recovers the Ethereum address from an ECDSA signature. Essential for transaction validation and signature verification.

Gas: 3,000 (fixed)
Input: 128 bytes (hash, v, r, s)
Output: 20-byte address
Use: Transaction signing, off-chain authentication

Hashing (0x02, 0x03, 0x09)

SHA256, RIPEMD160, BLAKE2F provide standard cryptographic hash functions.

SHA256: Bitcoin compatibility, Merkle trees
RIPEMD160: Bitcoin address generation
BLAKE2F: High-performance modern hash (Zcash)

Data Operations (0x04)

IDENTITY is a simple memcpy operation, mainly used for:

Gas benchmarking
Data copying in complex contracts
ABI encoding/decoding optimization

Mathematics (0x05)

MODEXP performs modular exponentiation: (base^exp) mod modulus

RSA signature verification
Zero-knowledge proof systems
Cryptographic protocols
Dynamic gas based on input sizes

zkSNARKs - BN254 Curve (0x06-0x08)

BN254 precompiles enable efficient zero-knowledge proofs:

ADD (150 gas): Point addition for proof verification
MUL (6,000 gas): Scalar multiplication
PAIRING (45k + 34k/pair): Bilinear pairing checks

Used by: Zcash, Tornado Cash, zkSync, StarkNet, Polygon zkEVM Security: ~100-bit (sufficient but aging)

Ethereum 2.0 - BLS12-381 Curve (0x0B-0x13)

BLS12-381 precompiles power Ethereum 2.0 consensus:

G1 Operations (128-byte points)

G1_ADD (500 gas): Fast point addition
G1_MUL (12,000 gas): Scalar multiplication
G1_MSM (variable): Batch operations with discounts

G2 Operations (256-byte points)

G2_ADD (800 gas): Extension field addition
G2_MUL (45,000 gas): More expensive than G1
G2_MSM (variable): Batch operations

Pairing & Hash-to-Curve

PAIRING (115k + 23k/pair): Signature verification
MAP_FP_TO_G1 (5,500 gas): Hash messages to G1
MAP_FP2_TO_G2 (75,000 gas): Hash messages to G2

Security: 128-bit (future-proof) Applications:

Validator signature aggregation
BLS multi-signatures
Threshold cryptography
Advanced zkSNARKs

Blob Data (0x0A)

POINT_EVALUATION verifies KZG commitments for EIP-4844 blob transactions:

Gas: 50,000 (fixed)
Enables proto-danksharding
Reduces rollup costs by 10-100x
Critical for Ethereum scalability

Gas Cost Patterns

Fixed Cost

Simple operations with predictable computation:

ECRECOVER: 3,000
BLS12_G1_ADD: 500
POINT_EVALUATION: 50,000

Linear Cost

Scales with input size:

SHA256: 60 + 12 per word
IDENTITY: 15 + 3 per word

Dynamic Cost

Complex calculation based on inputs:

MODEXP: Based on base/exp/mod sizes
BLS12_MSM: Batch discounts

Multi-Element Cost

Per-item pricing:

BN254_PAIRING: 45,000 + 34,000 per pair
BLS12_PAIRING: 115,000 + 23,000 per pair

Performance Comparison

Elliptic Curve Operations

Operation	BN254	BLS12-381	Security	Use Case
Point Add	150	500 (G1) / 800 (G2)	100-bit / 128-bit	zkSNARKs / ETH2
Scalar Mul	6,000	12,000 (G1) / 45,000 (G2)	100-bit / 128-bit	Proofs / Signatures
Pairing	45k+34k/pair	115k+23k/pair	100-bit / 128-bit	Verification

Hashing Performance

Function	Gas/KB	Speed	Use Case
SHA256	~380	Fast	Bitcoin compat
RIPEMD160	~3,750	Slower	Legacy
BLAKE2F	Variable	Fastest	Modern
Keccak256	~1,000	Fast	Native EVM

Usage Statistics

Most frequently used precompiles by gas consumption:

ECRECOVER (0x01) - Every transaction signature
BLS12_PAIRING (0x11) - ETH2 consensus (thousands per block)
POINT_EVALUATION (0x0A) - Blob transactions
BN254_PAIRING (0x08) - zkRollup proofs
SHA256 (0x02) - Bridge verifications

Least used:

RIPEMD160 (0x03) - Legacy Bitcoin compatibility
IDENTITY (0x04) - Specialized optimization

Implementation Guide

TypeScript

import { execute, PrecompileAddress } from '@tevm/voltaire/precompiles';
import { Hardfork } from '@tevm/voltaire/primitives/Hardfork';

// Execute any precompile
const result = execute(
  PrecompileAddress.ECRECOVER,
  input,        // Uint8Array
  gasLimit,     // bigint
  Hardfork.CANCUN
);

if (result.success) {
  console.log('Output:', result.output);
  console.log('Gas used:', result.gasUsed);
} else {
  console.error('Error:', result.error);
}

Zig

const std = @import("std");
const precompiles = @import("precompiles");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Execute precompile
    const result = try precompiles.ecrecover.execute(
        allocator,
        input,      // []const u8
        gas_limit,  // u64
    );
    defer result.deinit(allocator);

    if (result.success) {
        std.debug.print("Output: {any}\n", .{result.output});
    }
}

WASM

All precompiles available via WASM. Import and use like the TypeScript implementation.

Security Considerations

Input Validation

All precompiles validate:

Input length (exact or range)
Field element bounds (curve operations)
Point validity (on curve, in subgroup)
Gas sufficiency (before computation)

Invalid inputs return error, not false results.

Constant-Time Execution

Cryptographic precompiles use constant-time algorithms:

ECRECOVER: Prevents timing attacks on signatures
BN254/BLS12-381: Side-channel resistant scalar multiplication
MODEXP: Protects secret exponents

Gas DoS Protection

Dynamic gas prevents abuse:

MODEXP: Exponential cost for large inputs
MSM operations: Bounded by block gas limit
Pairing: Linear cost per pair

Curve Security

Curve	Security	Status	Notes
secp256k1	128-bit	Mature	Bitcoin/Ethereum standard
BN254	~100-bit	Aging	Sufficient for current zkSNARKs
BLS12-381	128-bit	Future-proof	ETH2, modern protocols

Hardfork Availability

import { Hardfork } from '@tevm/voltaire/primitives/Hardfork';

// Check precompile availability
const precompiles = {
  [Hardfork.FRONTIER]: [0x01, 0x02, 0x03, 0x04],
  [Hardfork.BYZANTIUM]: [0x05, 0x06, 0x07, 0x08],
  [Hardfork.ISTANBUL]: [0x09],
  [Hardfork.CANCUN]: [0x0A],
  [Hardfork.PRAGUE]: [0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10, 0x11, 0x12, 0x13],
};

Always check hardfork before calling newer precompiles.

Implementation Status

Zig: Complete

All precompiles fully implemented with native C library integration:

secp256k1: libsecp256k1
BN254: arkworks (Rust FFI)
BLS12-381: blst
KZG: c-kzg-4844
Hashes: libwally-core

TypeScript: Functional

Production-ready: ECRECOVER, SHA256, RIPEMD160, IDENTITY, BLAKE2F
Stubs (use WASM): BLS12-381 operations (return correct size, calculate gas, no crypto)
Working: BN254 via @noble/curves, MODEXP, POINT_EVALUATION via c-kzg

For security-critical operations, always use Zig/WASM implementations.

Curve Documentation

BLS12-381 Overview - Complete guide to 9 BLS precompiles
BN254 Operations - zkSNARK curve primitives
Secp256k1 - ECDSA and ECRECOVER

Cryptography

Keccak256 - Native EVM hash (not a precompile)
KZG Commitments - Blob verification
Signature Schemes - ECDSA, BLS, Schnorr

Primitives

Transaction - Uses ECRECOVER
Address - Derived from signatures
Gas Constants - Precompile gas costs

References

EIPs:
- EIP-196/197: BN254 (Byzantium)
- EIP-198: MODEXP (Byzantium)
- EIP-152: BLAKE2F (Istanbul)
- EIP-4844: POINT_EVALUATION (Cancun)
- EIP-2537: BLS12-381 (Prague)
Standards:
- SEC2: secp256k1 specification
- FIPS 180-4: SHA-256
- RFC 1321: RIPEMD-160
- RFC 7693: BLAKE2
- BLS Signatures: BLS12-381
Libraries:
- blst: BLS12-381 (audited)
- c-kzg-4844: KZG commitments
- @noble/curves: Pure JS curves
- arkworks: BN254 Rust implementation

Contributing

Precompile implementations require:

Exact adherence to EIP specifications
Comprehensive test vectors
Gas cost validation
Security audits for crypto operations
Cross-language parity (TypeScript ↔ Zig)

See CONTRIBUTING.md

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

​Overview

​Complete Precompile Reference

​Precompile Categories

​Cryptography (0x01)

​Hashing (0x02, 0x03, 0x09)

​Data Operations (0x04)

​Mathematics (0x05)

​zkSNARKs - BN254 Curve (0x06-0x08)

​Ethereum 2.0 - BLS12-381 Curve (0x0B-0x13)

​G1 Operations (128-byte points)

​G2 Operations (256-byte points)

​Pairing & Hash-to-Curve

​Blob Data (0x0A)

​Gas Cost Patterns

​Fixed Cost

​Linear Cost

​Dynamic Cost

​Multi-Element Cost

​Performance Comparison

​Elliptic Curve Operations

​Hashing Performance

​Usage Statistics

​Implementation Guide

​TypeScript

​Zig

​WASM

​Security Considerations

​Input Validation

​Constant-Time Execution

​Gas DoS Protection

​Curve Security

​Hardfork Availability

​Implementation Status

​Zig: Complete

​TypeScript: Functional

​Related Documentation

​Curve Documentation

​Cryptography

​Primitives

​References

​Contributing

Overview

Complete Precompile Reference

Precompile Categories

Cryptography (0x01)

Hashing (0x02, 0x03, 0x09)

Data Operations (0x04)

Mathematics (0x05)

zkSNARKs - BN254 Curve (0x06-0x08)

Ethereum 2.0 - BLS12-381 Curve (0x0B-0x13)

G1 Operations (128-byte points)

G2 Operations (256-byte points)

Pairing & Hash-to-Curve

Blob Data (0x0A)

Gas Cost Patterns

Fixed Cost

Linear Cost

Dynamic Cost

Multi-Element Cost

Performance Comparison

Elliptic Curve Operations

Hashing Performance

Usage Statistics

Implementation Guide

TypeScript

Zig

WASM

Security Considerations

Input Validation

Constant-Time Execution

Gas DoS Protection

Curve Security

Hardfork Availability

Implementation Status

Zig: Complete

TypeScript: Functional

Related Documentation

Curve Documentation

Cryptography

Primitives

References

Contributing