Skip to content

README.md

Latest commit

 

History

History
135 lines (101 loc) · 4.46 KB

README.md

File metadata and controls

135 lines (101 loc) · 4.46 KB

lambdaworks-math Latest Version

Overview

lambdaworks-math provides high-performance mathematical primitives for cryptographic applications, including zero-knowledge proofs, SNARKs, and STARKs. The library is designed with performance and developer experience in mind.

Usage

Add this to your Cargo.toml

[dependencies]
lambdaworks-math = "0.13.0"

Quick Examples

Working with Finite Fields

use lambdaworks_math::field::{
    element::FieldElement,
    fields::fft_friendly::stark_252_prime_field::Stark252PrimeField,
};

type FE = FieldElement<Stark252PrimeField>;

let a = FE::from(10u64);
let b = FE::from(5u64);

// Basic operations
let sum = &a + &b;
let product = &a * &b;
let quotient = (&a / &b).unwrap();
let inverse = a.inv().unwrap();
let power = a.pow(3u64);

Working with Elliptic Curves

use lambdaworks_math::elliptic_curve::{
    short_weierstrass::curves::bls12_381::curve::BLS12381Curve,
    traits::IsEllipticCurve,
};

let generator = BLS12381Curve::generator();
let doubled = generator.operate_with_self(2u64);
let sum = generator.operate_with(&doubled);

Polynomial Operations with FFT

use lambdaworks_math::{
    polynomial::Polynomial,
    field::element::FieldElement,
    field::fields::fft_friendly::stark_252_prime_field::Stark252PrimeField,
    fft::polynomial::FFTPoly,
};

type FE = FieldElement<Stark252PrimeField>;

// Create and evaluate polynomials efficiently
let coeffs = vec![FE::from(1), FE::from(2), FE::from(3), FE::from(4)];
let poly = Polynomial::new(&coeffs);

// FFT-based evaluation (for power-of-2 sized evaluations)
let evaluations = Polynomial::evaluate_fft::<Stark252PrimeField>(&poly, 1, None).unwrap();

Structure

This crate contains all the relevant mathematical building blocks needed for proof systems and cryptography:

Component Description Documentation
Finite Fields Montgomery and specialized field implementations README
Elliptic Curves BLS12-381, BN254, secp256k1, Pallas/Vesta, and more README
Polynomials Univariate, multilinear, and sparse polynomials README
FFT Radix-2 and Radix-4 NTT for polynomial operations README
Circle FFT FFT over the circle group for non-smooth fields (Mersenne31) README
MSM Pippenger's algorithm with adaptive window sizing README
Unsigned Integers Large integer arithmetic (U256, U384, etc.) Source

Supported Fields

Field Bits FFT-Friendly Notes
Stark252 252 Yes Used by Starknet
Goldilocks 64 Yes p = 2^64 - 2^32 + 1, hybrid SIMD + x86-64 asm
Mersenne31 31 No (use Circle FFT) Used in Stwo/Plonky3
BabyBear 31 Yes Used in RISC Zero/Plonky3
KoalaBear 31 Yes p = 2^31 - 2^24 + 1, with degree-4 extension
BLS12-381 (scalar) 255 Yes Pairing-friendly curve
BN254 (scalar) 254 Yes Ethereum's curve

Supported Curves

  • Pairing-friendly: BLS12-381, BLS12-377, BN254
  • Cycle curves: Pallas/Vesta (for recursive proofs)
  • Bitcoin/Ethereum: secp256k1, secp256r1
  • Edwards curves: Ed448-Goldilocks, Bandersnatch

Features

  • std (default): Standard library support
  • alloc: Enable allocation without full std
  • parallel: Rayon-based parallelization for FFT and MSM
# Enable parallel processing
lambdaworks-math = { version = "0.13.0", features = ["parallel"] }

# No-std with allocation
lambdaworks-math = { version = "0.13.0", default-features = false, features = ["alloc"] }

Performance

Benchmark results are available at lambdaclass.github.io/lambdaworks/bench.

Run benchmarks locally:

make benchmark BENCH=field

Optimizations

  • x86-64 Assembly: Hand-tuned assembly for field arithmetic (Stark252, Goldilocks)
  • SIMD: Vectorized operations for compatible fields
  • Adaptive MSM: Window size selection based on input size for optimal performance
  • LTO: Link-time optimization enabled for release builds
  • GPU Backends: CUDA and Metal acceleration available in separate crates