mxx

mxx is a Rust and CUDA library for lattice-cryptography research and implementation work at Machina iO. It provides primitive-level building blocks for polynomial and matrix arithmetic, trapdoor sampling, key-homomorphic encodings, and higher-level constructions of lattice-based schemes.

Specifically, this repository provides implementations of the following works:

• BGG+ encodings, available at src/bgg/
• WEE25 matrix commitment, available at src/commit/.
• Lookup-table evaluation over BGG+ encodings available at src/lookup/.
• Evaluation and decryption of GSW-FHE over BGG+ encodings, following this construction, available at src/gadgets/fhe/.
• Benchmark estimation for pseudorandom obfuscation based on AKY24, available at src/io/aky24_io/.
• Benchmark estimation for Diamond iO, available at src/io/diamond_io/.

Requirements

• Rust with support for edition 2024.
• OpenFHE C++ libraries installed in the system location expected by build.rs. Follow the OpenFHE installation guide, but run those steps against our fork, MachinaIO/openfhe-development, rather than the upstream OpenFHE repository. The build script links OPENFHEpke, OPENFHEbinfhe, and OPENFHEcore.
• OpenMP support through the system C/C++ toolchain.
• For GPU builds, a CUDA toolkit with nvcc and the CUDA runtime libraries.

Cargo Features

The default feature set is CPU-only and keeps matrix backing storage in memory.

Feature	Effect
disk	Enables disk-backed matrix storage through libc and memmap2. Without this feature, src/matrix/base/memory.rs is used.
gpu	Enables CUDA-backed polynomial/matrix paths, GPU samplers, GPU lookup and BGG paths, GPU-aware circuit evaluation, and native CUDA compilation from cuda/.

GPU builds use these environment variables. Their defaults are defined in build.rs.

Variable	Purpose
CUDA_ARCH	CUDA SM architecture passed to nvcc.
CUDA_HOME	CUDA installation root used to locate nvcc and libraries.
CUDA_LIB_DIR	CUDA library directory linked by Cargo.
NVCC	Explicit CUDA compiler path.

Runtime parallelism and batching are also controlled by environment helpers in src/env.rs, including MXX_CIRCUIT_PARALLEL_GATES, LUT_PREIMAGE_CHUNK_SIZE, GGH15_GATE_PARALLELISM, BGG_POLY_ENCODING_SLOT_PARALLELISM, SLOT_TRANSFER_SLOT_PARALLELISM, AUX_SAMPLING_CHUNK_WIDTH, and MXX_MUL_DECOMPOSE_COLUMN_CHUNK_WIDTH.

Common Commands

CPU-only type checking:

cargo check

Type check with disk-backed storage:

cargo check --features disk

Type check with CUDA support:

cargo check --features gpu

Run a targeted unit test by name when validating a narrow change:

cargo test <test_name>

Format Rust code when Rust files are changed:

cargo +nightly fmt --all

Run benchmarks explicitly by bench target:

cargo bench --bench bench_matrix_mul_cpu
cargo bench --bench bench_preimage_cpu
cargo bench --features gpu --bench bench_matrix_mul_gpu
cargo bench --features gpu --bench bench_preimage_gpu

License

The Cargo manifest declares MIT OR Apache-2.0. See LICENSE for the checked-in license text.