Baby JubJub Python Bindings

Fast Python bindings for the Baby JubJub elliptic curve, powered by Rust.

Research Prototype Warning

This library is a research prototype and should NOT be used in production systems.

• The hash_to_point implementation is NOT cryptographically secure
• It uses a simple hash-to-scalar-to-point method that introduces bias
• Proper hash-to-curve methods (RFC 9380) are not implemented
• This library is intended for research and experimentation only
• No security audits have been performed

Overview

This library provides Python bindings to the babyjubjub-rs Rust library, offering high-performance elliptic curve operations for the Baby JubJub curve.

Baby JubJub is a twisted Edwards curve embedded in the BN254 scalar field, designed for efficient use in zero-knowledge proof systems like Circom, zkSync, and Tornado Cash.

Features

• Fast: Native Rust implementation provides 100x speedup over pure Python
• Complete API: Point addition, scalar multiplication, compression, hashing
• Thread-safe: GIL is released during expensive operations for true parallelism
• Well-tested: Comprehensive test suite with 26+ tests
• Cross-platform: Supports Linux, macOS, and Windows (Python 3.10+)
• Easy to use: Simple Python API with no Rust knowledge required

Performance

Individual operations are highly optimized:

Point addition:           1.85 µs
Scalar multiplication:    3.38 µs
Compression:              0.67 µs
Uncompressed serialize:   0.07 µs
Uncompressed deserialize: 0.15 µs

The library includes both compressed (32-byte) and uncompressed (64-byte) serialization. Uncompressed serialization is significantly faster for multiprocessing scenarios where points need frequent serialization.

Installation

pip install babyjubjub-py

From source

# Clone the repository
cd /path/to/babyjubjub-py

# Install maturin
pip install maturin

# Build and install
maturin develop --release

Quick Start

import babyjubjub_py as bjj

# Get the generator point
G = bjj.ECPoint.generator()

# Scalar multiplication
P = bjj.ECPoint.from_scalar("123")

# Point addition
Q = bjj.ECPoint.from_scalar("456")
R = P.add(Q)

# Hash to curve point
H = bjj.ECPoint.hash_to_point(b"Hello, World!")

# Compression
compressed = P.to_bytes()
P_restored = bjj.ECPoint.from_bytes(compressed)

API Reference

ECPoint class

Constructors

• ECPoint(x_hex: str, y_hex: str) - Create from coordinates
• ECPoint.generator() - Get the base point (B8)
• ECPoint.infinity() - Get the identity point
• ECPoint.from_scalar(scalar: str) - Create as scalar * G
• ECPoint.from_bytes(bytes: list[int]) - Decompress from 32 bytes
• ECPoint.hash_to_point(data: bytes) - Hash arbitrary data to a point

Methods

• add(other: ECPoint) -> ECPoint - Point addition
• neg() -> ECPoint - Point negation
• sub(other: ECPoint) -> ECPoint - Point subtraction
• scalar_mult(scalar: str) -> ECPoint - Scalar multiplication
• is_infinity() -> bool - Check if identity
• x_hex() -> str - Get x coordinate as hex string
• y_hex() -> str - Get y coordinate as hex string
• to_bytes() -> list[int] - Compress to 32 bytes

Module Constants

• __version__ - Library version
• CURVE_NAME - "Baby JubJub"
• CURVE_ORDER - Order of the curve subgroup

Baby JubJub Curve Details

• Curve equation: ax² + y² = 1 + dx²y² (twisted Edwards)
• Base field: BN254 scalar field (254-bit prime)
• Order: 21888242871839275222246405745257275088614511777268538073601725287587578984328
• Cofactor: 8

Use Cases

• Zero-knowledge proofs: Circom, zkSync, Aztec
• EdDSA signatures: Privacy-preserving signatures
• Commitment schemes: Pedersen commitments
• Threshold cryptography: Distributed key generation
• Cryptographic protocols: Any application requiring Baby JubJub curve operations

Development

Requirements

• Rust 1.56+ (install via rustup)
• Python 3.8+
• Maturin

Building

# Development build (fast iteration)
maturin develop

# Release build (optimized)
maturin build --release

# Run tests
python test_basic.py

Project Structure

babyjubjub-py/
├── Cargo.toml          # Rust dependencies
├── pyproject.toml      # Python packaging
├── src/
│   └── lib.rs          # PyO3 bindings
├── test_basic.py       # Python tests
└── README.md

Example Usage in Applications

The library can be integrated into cryptographic applications requiring Baby JubJub operations:

from babyjubjub_py import ECPoint

# Use in your cryptographic protocol
def my_protocol(data):
    # Hash input to curve point
    point = ECPoint.hash_to_point(data)
    
    # Perform operations
    secret = "123456789"
    commitment = point.scalar_mult(secret)
    
    return commitment

License

Apache-2.0 (same as babyjubjub-rs)

Credits

• Built on babyjubjub-rs by arnaucube
• Uses PyO3 for Python bindings

Alternatives

• Pure Python: pybabyjubjub - slower but no dependencies
• Full Rust: Use babyjubjub-rs directly

Troubleshooting

Import Error

ImportError: cannot import name 'ECPoint' from 'babyjubjub_py'

Solution: Rebuild the library with maturin develop --release

Performance Issues

If operations are slow:

1. Ensure you built with --release flag
2. Check Python version (3.10+ recommended)
3. Verify Rust is using the release profile

Installation Errors

If pip install fails:

1. Install Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
2. Install Python dev headers: sudo apt-get install python3-dev
3. Install build tools: sudo apt-get install build-essential

Contributing

Contributions welcome! Please feel free to:

• Report bugs
• Suggest features
• Submit pull requests
• Improve documentation

Support

For issues or questions:

• Open an issue on GitHub
• Check the babyjubjub-rs documentation
• Review the PyO3 user guide

---

Status: Research Prototype / Beta

Version: 0.1.1

Warning: Not for production use. See security warning at top of README.