miden_ace_codegen/
lib.rs

1//! ACE circuit codegen for Plonky3-based Miden AIRs.
2//!
3//! The pipeline is:
4//! 1. Capture AIR constraints into the `miden-constraint-compiler` IR.
5//! 2. Lower the constraint graph into a DAG that mirrors verifier constraints evaluation.
6//! 3. Emit an ACE circuit plus an `InputLayout` describing the MASM ACE-READ section order.
7//!
8//! The resulting circuit is intended to run inside the recursive verifier. All
9//! input layout decisions (point-major OOD ordering, aux/quotient coords, and
10//! alpha/beta randomness expansion) are centralized in this crate so tests can
11//! validate both layout and evaluation.
12//!
13//! Quick start:
14//! ```ignore
15//! use miden_ace_codegen::{AceConfig, LayoutKind, build_ace_circuit_for_air};
16//! use miden_air::ChipletsAir;
17//!
18//! let config = AceConfig { num_quotient_chunks: 8, layout: LayoutKind::Masm, num_airs: 1 };
19//! let circuit = build_ace_circuit_for_air(&ChipletsAir, config)?;
20//! ```
21//!
22//! Module map (data flow):
23//! - `pipeline`: public entry points that orchestrate layout + DAG + circuit emission.
24//! - `dag`: verifier-style DAG IR and lowering helpers.
25//! - `circuit`: off-VM circuit representation (inputs/constants/ops/root).
26//! - `factored`: shuffle/common split of a multi-AIR circuit, so per-proof-order variants share one
27//!   order-invariant section (used by the recursive verifier's circuit registry).
28//! - `factory`: cached per-order encoding and registry-leaf construction.
29//! - `layout`: READ-section layout and index mapping.
30//! - `encode`: ACE stream encoding + padding rules.
31//! - `masm`: shared renderer for relation-local MASM constraint evaluators.
32//! - `randomness`: challenge input planning for layouts + DAG lowering.
33//! - `quotient`: barycentric quotient recomposition helpers (used by DAG + tests).
34//! - `registry`: order tags, registry layout, subtree construction, and path authentication.
35
36// Core IR and lowering.
37mod circuit;
38mod dag;
39
40// Input layout and encoding.
41mod encode;
42mod factored;
43mod factory;
44mod layout;
45mod masm;
46mod quotient;
47mod randomness;
48mod registry;
49
50// High-level orchestration.
51mod pipeline;
52
53#[cfg(test)]
54mod tests;
55#[cfg(test)]
56mod unit_tests;
57
58/// Extension field degree (quadratic extension for Miden VM).
59pub const EXT_DEGREE: usize = 2;
60
61/// Errors returned by ACE codegen.
62#[derive(Debug, thiserror::Error)]
63pub enum AceError {
64    #[error("invalid input length: expected {expected}, got {got}")]
65    InvalidInputLength { expected: usize, got: usize },
66    #[error("invalid input layout: {message}")]
67    InvalidInputLayout { message: String },
68}
69
70#[cfg(any(test, feature = "testing"))]
71pub mod testing;
72
73/// Exposed for the lowering differential tests (`miden-air/tests/ace_codegen.rs`);
74/// production consumes the IR lowering through the pipeline.
75#[cfg(any(test, feature = "testing"))]
76pub use crate::dag::{PeriodicColumnData, build_verifier_dag, build_verifier_dag_from_ir};
77pub use crate::{
78    circuit::{AceCircuit, emit_circuit},
79    dag::{AceDag, DagBuilder, DagSnapshot, NodeId, NodeKind},
80    encode::EncodedCircuit,
81    factored::ShuffleEncodeBuffer,
82    factory::{FactoredCircuitFactory, FactoredEncodedCircuit, PackedLeafScratch},
83    layout::{InputCounts, InputKey, InputLayout},
84    masm::{MasmConstraintsEvalConfig, render_masm_constraints_eval},
85    pipeline::{
86        AceArtifacts, AceConfig, FactoredMultiAirCircuit, LayoutKind, build_ace_circuit_for_air,
87        build_ace_dag_for_air, build_factored_multi_air_ace_circuit, build_multi_air_ace_circuit,
88    },
89    registry::{
90        MAX_REGISTRY_AIRS, RegistryLayout, ceil_log2, factorial, fold_row_to_root, order_from_tag,
91        order_tag, padding_leaf, path_in_verified_tree, subtree_leaves, verify_row,
92    },
93};
miden_ace_codegen/lib.rs

miden_ace_codegen/
lib.rs
