binius_frontend/lib.rs
1// Copyright 2025 Irreducible Inc.
2// Copyright 2026 The Binius Developers
3
4//! Circuit construction frontend for Binius64.
5//!
6//! This crate provides the [`CircuitBuilder`] API for constructing arithmetic circuits
7//! that compile to Binius64 constraint systems. You describe your computation as a graph
8//! of operations on 64-bit words, and the frontend compiles it to AND/IMUL/BMUL constraints.
9//!
10//! # Usage Flow
11//!
12//! Use [`CircuitBuilder`] to construct your circuit. Call methods like `add_witness()`
13//! and `add_inout()` to create [`Wire`]s - handles to 64-bit values that will exist during
14//! proof generation. Use operations like `band()`, `bxor()`, and `iadd_32()` to transform
15//! these wires, building up your computation graph.
16//!
17//! When you call `build()`, the builder compiles your graph into a [`Circuit`]. This circuit
18//! contains the optimized constraint system and everything needed for proof generation.
19//!
20//! To generate a witness, create a [`WitnessFiller`] from the circuit. Assign concrete values
21//! to your input wires, then call `populate_wire_witness()` to compute all intermediate values
22//! through circuit evaluation.
23//!
24//! Use [`CircuitStat`] to inspect metrics like constraint counts and wire usage, helpful for
25//! optimization and debugging.
26//!
27//! # Layout
28//!
29//! - `builder` — the vocabulary a circuit author writes.
30//! - `ir` — the gate graph those calls build, held as dense index maps.
31//! - `gates` — the shape, the constraints and the instruction of each gate kind.
32//! - `pass` — transformations over the graph, and the pipeline that runs them.
33//! - `lower` — the constraints a graph emits, over wires rather than value indices.
34//! - `eval_form` — the bytecode that fills a witness, and the interpreters that run it.
35//! - `artifact` — what a build hands back: the circuit, its witnesses, its statistics.
36//!
37//! Every module reads `ir`, and nothing reads `builder`.
38
39#![warn(missing_docs)]
40#![warn(rustdoc::missing_crate_level_docs)]
41
42mod artifact;
43mod builder;
44mod eval_form;
45mod gates;
46mod ir;
47mod lower;
48mod pass;
49
50pub use artifact::{
51 chip::{
52 self, ChipGadget, ChipRef, CircuitM4, CircuitM4Error, EmbeddedCircuit, PopulateM4Error,
53 },
54 circuit::Circuit,
55 stat::{self, CircuitStat},
56 witness::{AssertionFailure, BatchWitnessFiller, PopulateError, WitnessFiller},
57};
58pub use builder::{CircuitBuilder, Options};
59pub use eval_form::{BatchPopulateError, MAX_ASSERTION_FAILURES};
60pub use ir::{
61 Wire,
62 hints::{self, Hint},
63};