Skip to content

Circle classifier engine reuse review

2026-10-27. Source review for epic #112, not a proof, benchmark, security audit or backend qualification. No build, proof job, benchmark or installation was run for this review.

Recommendation

Use direct STWO 2.2.0 plus its matching constraint framework, pinned and locked, for the first fixed classifier AIR. Reuse its field/FFT/FRI/Merkle machinery, FrameworkEval and LogUp; author the exact classifier and SHA-256 constraints. A fixed arithmetic/Boolean circuit lowered to gate rows is an implementation option, not a zkVM. Keep SASH/Nitroo as a source of patterns and a later GPU candidate. Its LLM command does not implement Hallmark's classifier statement or transcript commitment. This is an engineering inference from the interfaces and build boundaries below, not measured superiority.

The existing Hallmark SASH source pin is eb95bfa887299d1637550228d42086c27cbb2b3b, archive SHA-256 98f3fbdcb2359898804ce06752db29afd046452704dcc5722c6bf18801827abe; see response-case.json. Inspection also used the ignored extracted copy of that public source. Do not change the existing LLM source pins to introduce this classifier backend.

The direct-engine commit archive was fetched into memory for identification only: 366,290 bytes, SHA-256 16b0ed550eac992ccaec06242670e5c07085b4ad829a6f25e9f5cc5037b5dedd. Its licence is Apache-2.0. Lock dependency resolution separately; an upstream archive hash does not pin registry dependencies.

Reuse and build boundary

Aspect Direct STWO release Existing SASH/Nitroo pin
Version STWO and framework 2.2.0; tag resolves to 289c20de80b7c7f508de9c46151fb81dae404154 Vendored STWO/framework 2.1.0; identify by SASH archive hash, not only the package version
Toolchain nightly-2025-07-14, edition 2021 Same nightly for vendored engine; SASH prover edition 2024
Licence Apache-2.0 workspace Apache-2.0 vendored workspace; retain SASH/StarkWare/Nitroo notices when copying code
Dependencies stwo = "=2.2.0", stwo-constraint-framework = "=2.2.0"; enable prover, optionally parallel for prover SASH depends on both engines by path with prover, parallel; CUDA is a separate SASH feature
Build trap Core manifest has no CUDA/CMake build dependency Engine build.rs invokes CUDA CMake and links cudart on non-Mac hosts even without SASH's CUDA feature; Mac exits the build script, but Hallmark additionally patches unconditional FFI link attributes

Primary sources: release workspace, release toolchain, core manifest, framework manifest, SASH prover manifest, vendored workspace, CUDA build script, and Hallmark's native patch / notices.

Do not use moving dev examples as release documentation. At review, dev resolves to 826591c6c371376810ca8213b5812d5daf6d5092, uses nightly-2026-01-15 and edition 2024; the repository announces migration to starkware-libs/proving. The release inspected here remains 2.2.0. Development manifest, toolchain, repository notice.

Exact implementation pointers

  • AIR: implement FrameworkEval::{log_size,max_constraint_log_degree_bound,evaluate}; read fixed selectors/wiring with get_preprocessed_column, witnesses with next_trace_mask, and enforce equations with add_constraint. FrameworkComponent::new and TraceLocationAllocator::new_with_preprocessed_columns support static column enrollment. A framework component's columns have one common size; pad intentionally or split components. Framework interface, component implementation.
  • Copy constraints: the PLONK example puts (wire_id,value) tuples into relation!(...,2), uses RelationEntry, draws lookup challenges after committing the base trace, generates fractions with LogupTraceGenerator, and calls finalize_logup_in_pairs. It demonstrates the reusable mechanism, not a production circuit contract. Release PLONK example.
  • LogUp: LookupElements::draw/combine randomizes tuples; LogupAtRow constrains a rational sum to a supplied claimed sum. Consequently a verifier must enforce the intended total balance, including public-boundary contributions; accepting arbitrary claimed sums does not establish copy equality. LogUp implementation.
  • Verifier: instantiate AIR and CommitmentSchemeVerifier independently, replay the agreed commitment/challenge transcript, then call stwo::core::verifier::verify. The engine takes components/configuration from its caller; it does not enroll Hallmark's program. Verifier source.

The release uses core::vcs_lifted, FriConfig::fold_step and PcsConfig::lifting_log_size; SASH's fork uses core::vcs and FriConfig::line_fold_step. Their serialized proofs and roots must not be assumed interchangeable. Pin the chosen API, proof format and parameters as a new backend identity. Release FRI, fork FRI.

Keep SHA-256 inside the relation

Preserve the exact classifier input preimage: u32be(len(tag)) || tag || CBOR([salt32, profile32, count, byte_values]), with tag = hallmark/v1/input. This differs from the transcript-opening commitment in SPEC §3. SHA-256 uses 32-bit words, Boolean functions/rotations, message scheduling, modular additions, padding and a 64-bit bit-length field. A bit/limb gate lowering is feasible in principle: Boolean constraints, bounded carries and exact recomposition express these operations over M31. It is new implementation work; no cost or passing proof is established here. FIPS 180-4 §§3–6.

M31's modulus is 2^31-1; neither an arbitrary uint32 SHA word nor a full signed int32 range has a unique one-field encoding. Use explicit bounded limbs/bits and carries; prevent field aliases in public inputs and integer comparisons. From<u32> reduces modulo the field, and from_u32_unchecked does not validate a transport value. Field implementation.

The pinned Nitroo examples/framework/core contain no SHA-256 AIR found by a source search for sha256, SHA256, SHA-256; SASH's sha2 dependency and host manifest/proof hashes are not such a gadget. Host hashing utility. Blake2s for STARK commitments/Fiat–Shamir can coexist with SHA-256 for the proved Hallmark transcript; the two hashes serve different roles.

Required safeguards before borrowing the example

These are application review requirements inferred from the cited code, not demonstrated upstream vulnerabilities:

  1. Enroll the preprocessed root outside the proof, with exact column order/sizes, wiring, selector values, constants, model/policy identity and resource/PCS parameters. Check the received root against that enrollment. The PLONK test reuses the prover-returned component and accepts proof.commitments[0]; that test is not independent program enrollment.
  2. Make copy multiplicities fixed preprocessing or otherwise constrain them to the enrolled wiring. The example reads mult from the witness. Reproduce gate signs deliberately: its op=0 equation is c + a*b = 0, not c=a*b. Include public values/output wires in actual constraints, not merely transcript hashing. PLONK source.
  3. Freeze exact boolean/range/carry rules, signed rounding including ties, padding and all active chunks. Reject changed private traces, wiring, constants, public fields, omitted chunks and transcript boundaries. A native trace generator or host SHA check cannot replace an AIR constraint. These obligations come from Hallmark's SPEC and epic acceptance contract.
  4. Bind statement, configuration and claimed sums in the same explicit transcript order on both sides. Use a deliberate PCS configuration: PcsConfig::default() has only three FRI queries and is a test profile. The source's security_bits() is grinding plus query/blowup arithmetic, not a complete application soundness proof. PCS config.
  5. Validate proof shapes, field encodings, column counts, sizes and allocation limits before verifier indexing; the core uses indexing, unwrap and configuration assertions. A fresh worker must accept only proof + caller-enrolled statement/program parameters, with no witness, checkpoint or classifier replay. Sharing the STWO verifier still supplies no independent cryptographic implementation. Verifier source.

First falsification: a small fixed SHA-256 plus byte-rule circuit, honest fresh-worker acceptance, and mutations of a private SHA bit/carry, wire copy, constant, digest byte and decision. Continue to the unchanged trained MLP/CNN only after that relation and independent program enrollment pass. Measure compilation/preprocessing, witness, proof, serialization, fresh verification and caller binding separately; this review supplies no projected timings, hiding guarantee or hardware claim.

Implementation handoff

The smallest existing runnable API fixture, from the extracted direct-engine root on the pinned nightly, is below. It was inspected, not executed here. The crate manifest enables its prover dependencies; the test generates and verifies a small proof. It retains the enrollment limitations described above. Example crate manifest.

cargo +nightly-2025-07-14 test --release --locked -p stwo-examples \
  plonk::tests::test_simd_plonk_prove -- --exact --nocapture

Concrete layout for a Hallmark adaptation (proposal): preprocessed columns hold wire IDs, exact fanout multiplicities, arithmetic selectors/constants and boundary selectors; the base witness contains only wire values. Require one producer per wire; source rows for private inputs must be deliberate enrolled rows, with every bit/range obligation constrained. Account for every padded row in the multiplicities or disable its entries using enrolled selectors. The interaction may keep the example's two fractions per row: (qa+qb)/(qa*qb) for the two consumed tuples and -fanout/qc for the produced tuple. LogupTraceGenerator::new_col, write_frac, finalize_col, finalize_last emit two secure columns (eight base-field columns). Fully write every packed row; the generator uses uninitialized backing memory. log_size >= LOG_N_LANES is required by packed allocation/index arithmetic. Generator source.

Adaptation sequence:

  1. Commit the enrolled preprocessing with tree_builder().extend_evals(...); commit(channel); then commit the base witness. Mix the canonical public statement and frozen config on both sides before challenge generation.
  2. Draw the relation with LookupElements::draw; generate interaction columns and require their resulting sum to be zero, or the exact verifier-computed public contribution. Commit them.
  3. Instantiate the component using the static allocator and the same enforced sum, then prove(&[&component], channel, scheme).
  4. Fresh verifier checks the preprocessed root and fixed shapes first. It commits enrolled root/sizes, commits the proof's base root, draws its own lookup elements, commits the interaction root, independently constructs the AIR, then calls verify. It never reads prover-returned component state. CommitmentSchemeVerifier::commit(root, log_sizes, channel) only absorbs a root and registers sizes; equality with an enrolled root is the application's responsibility. PCS verifier API.

For the integer graph, honest reachable-value intervals are insufficient by themselves: constrain malicious witness ranges, every remainder/tie/sign branch and reconstruction. Establish that each integer equation's full residual interval contains no nonzero multiple of p, including allowed witness assignments. If that cannot be shown for an accumulator, split it into bounded limbs/carries. This is the specific obligation that permits a field equality to imply the intended integer equality; no check of that obligation was performed in this source review.

Derive the polynomial degree bound for the adapted AIR as well: a varying preprocessed selector multiplied by a*b is cubic in committed columns. The implemented candidate instead commits a product column t, constrains t=a*b, and applies the selector to t. It uses one LogUp entry per interaction column. Every resulting expression is quadratic, so log_size+1 covers constraint evaluation; the split composition and trace trees share the log_size+4 commitment domain. The earlier cubic/domain experiments failed and are not accepted proofs. Degree/batching interface.