refactor(stark): the grinding factor is not "security_bits" - #979
Merged
Conversation
Three local bindings read `proof_options.grinding_factor` and named it
`security_bits`, then passed it to functions whose own parameter is
`grinding_factor`:
prover.rs:2286 let security_bits = air.context().proof_options.grinding_factor;
verifier.rs:1582 let security_bits = air.context().proof_options.grinding_factor;
verifier.rs:1665 let security_bits = air.context().proof_options.grinding_factor;
Grinding is not the security level. It is one term in the query round's error,
and it cannot move the commit-phase term at all — so a reader who takes these
bindings at their word concludes the proof carries 20 bits of security, or that
raising the grinding factor raises security generally. Neither follows.
`grinding_factor` is what every function behind these call sites already calls
the argument (`grinding::is_valid_nonce`, `generate_nonce`,
`generate_nonce_maybe_gpu`), so the rename removes a mismatch rather than
introducing a new convention. Nothing is shadowed: the name appeared in these
two files only as the struct field being read.
Eight identifier occurrences, no behaviour, no field moved. The one operator-
facing message in the area already says the right thing — `error!("Grinding
factor not satisfied")` — so no text needed correcting alongside the names.
diegokingston
approved these changes
Sep 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Renames three local bindings that called the grinding factor
security_bits. Follow-up to#976, deliberately kept out of it so that PR stayed one idea.
+8 / −8 over 2 files, one signed commit. Base
main.What was wrong
Grinding is not the security level. It is one term in the FRI query round's error, and it
cannot move the commit-phase term (
eps_C) at all — so a reader who takes these bindingsat their word concludes the proof carries 20 bits of security, or that raising the grinding
factor raises security generally. Neither follows.
#976 removed the same confusion where it did real damage:
security_bitsthere was a querybudget that had never modelled
eps_C, described in docs as the security the systemdelivers. This PR is the cheap half of that fix — the naming, in the two files #976 did
not touch. It is not load-bearing on #976 and can merge in either order; it just reads
oddly to fix the doc claim and leave the variable.
The change
grinding_factor, which is what every function behind these call sites already names theargument —
grinding::is_valid_nonce,generate_nonce,generate_nonce_maybe_gpu, all ofwhich declare
grinding_factor: u8. So the callers were passingsecurity_bitsintogrinding_factor; the rename removes a mismatch rather than introducing a convention.✓ Nothing is shadowed:
grinding_factorappeared in these two files only as the structfield being read, never as a local.
✓ No message or doc needed correcting alongside the names. The one operator-facing string
in the area already says the right thing —
error!("Grinding factor not satisfied")atverifier.rs:1672— andgrinding.rsnever uses the word "security" at all. A rename thatleft a message lying would be half a fix; there was no such message.
Bit-inert
Eight identifier occurrences. No
ProofOptionsfield moves — none is even written here,only read — and no expression changes, so every proof this produces or accepts is
byte-identical. The change cannot be observed except by reading the source.
The differential that would prove it, if asked: run
cargo test --release -p stark --liband-p lambda-vm-prover --libatmainand at this head and require the resultlines, failure names included, to be identical. It is not proposed as necessary — an
8-line identifier rename with no expression change is verifiable by reading the diff, which
is 8 lines — but it is the same instrument #976 used and it is available.
Evidence
Laptop, at this head:
223 was pre-registered before the run, derived as #976's 224 minus the one test that branch
adds and this one does not.