How starkware-libs/stwo works
Project type and purpose
• This is a Rust workspace hosting a multi-crate library and toolchain for generating and verifying CSTARK proofs.
• The main deliverable is the stwo crate (the core prover/verifier) plus an optional no_std verifier binary (ensure-verifier-no_std).
• Supporting crates provide utilities (air-utils), derive-macro code generation (air-utils-derive), a constraint-framework, no_std shims, and example/benchmark code.
File structure
• Top-level
• Workspace manifest (Cargo.toml, WORKSPACE), CI/config files under .github/, helper scripts.
• crates/ folder
• air-utils-derive: Rust derive macros for allocation/iteration boilerplate
• air-utils: runtime data structures and trace utilities
• constraint-framework: core abstractions for constraints, component evaluators, CPU & SIMD provers
• examples: demo implementations and benches (Poseidon, Blake, PLONK, etc.)
• std-shims: minimal std library replacements for no_std environments
• stwo: the heart of the system (core logic, prover modules, channel, tracing)
• Top-level binary
• -verifier-no_std: CLI app producing a no_std-compatible verifier
• Config and tooling
• Scripts for benchmarks, clippy, fmt; GitHub Actions workflows for CI/benchmarks/coverage.
README for insights
• Confirms it is a next-generation CSTARK prover/verifier library in Rust.
• Emphasizes performance (CPU & SIMD backends), flexibility, and ongoing development status.
• Points to benchmark scripts and hosted benchmark visualizations.
Main components and their interactions
a. Components
• Sub-libraries:
– air-utils-derive
– air-utils
– constraint-framework
– std-shims
• Core library: stwo
• Binary: ensure-verifier-no_std
• Examples & Benchmark harness
• CI/CD & tooling (GitHub Actions, Cargo, codecov)
b. Dependencies / interactions
• air-utils-derive → generates code used by air-utils & constraint-framework
• air-utils & constraint-framework → foundational data structures & algorithms
• stwo → depends on air-utils, constraint-framework, std-shims for its core modules (core, prover, channel, tracing)
• -verifier-no_std → depends on stwo & std-shims to build a compact verifier binary
• examples → import stwo, air-utils, and constraint-framework to demonstrate usage
• CI workflows pull everything together: build, test, bench, coverage
c. Architectural patterns and principles
• Layered library architecture (derive macros → utilities → framework → core)
• Plug-in backends (CPU & SIMD) behind unified prover interfaces
• Zero-std compatibility via std-shims and feature flags
• Monorepo workspace for tightly coupled crates with shared versioning
d. Key technologies
• Rust Cargo workspaces
• Procedural macros (derive)
• SIMD & multi-threading for performance
• CI with GitHub Actions and codecov
• Shell scripts for benchmarks & code hygiene
Putting it all together
• Start at the bottom with air-utils-derive and std-shims.
• Above them place air-utils and constraint-framework.
• Above those, center stwo (core library).