Pickles: add more documentation regarding verifiers #18362

dannywillems · 2026-01-24T20:57:49Z

There is a change in ffb3fab which is not only documentation. Please check.

dannywillems · 2026-01-24T21:01:30Z

src/lib/crypto/pickles/pickles.mli

+      actually verifies (0, 1, or 2)
+    - {b Max Proofs Verified:} The maximum across all branches in a proof system
+
+    Current Pickles supports max_proofs_verified up to 2 (N0, N1, N2).


This is what we want to generalize. We have enough "place" in our circuits to add more verification.

dannywillems · 2026-01-24T21:08:25Z

src/lib/crypto/pickles/pickles.mli

+    In code: [challenge_polynomial] in {!module:Wrap_verifier},
+    see also {!module:Step_verifier.finalize_other_proof}
+
+    {4 Challenge Polynomial Commitment (sg)}


This is an important part to understand the accumulation scheme. This comes from the paper "Proofs carrying data" in 2020.

dannywillems · 2026-01-24T21:09:45Z

src/lib/crypto/pickles/pickles.mli

+    The verifiers ({!module:Step_verifier}, {!module:Wrap_verifier}) use specific
+    notation for polynomial commitments and related values:
+
+    {4 Prover Commitments}


Note: if we want to digest different kinds of proofs, different than from the Kimchi ones, this is one part to change. The "Prover Commitments" are the prover messages of the protocol, and protocols depend in particular on prover messages.

dannywillems · 2026-01-24T21:10:21Z

src/lib/crypto/pickles/pickles.mli

+    time rather than runtime. This eliminates entire classes of bugs and makes
+    the code more robust, though it results in complex type signatures.
+
+    {4 MLMB (Max Local Max Proofs Verified)}


This is also to change if we want to change Pickles to accept more than two proofs.

dannywillems · 2026-01-24T21:11:14Z

src/lib/crypto/pickles/pickles.mli

+
+    {3 Challenge and Hash Flow Between Circuits}
+
+    {4 Fiat-Shamir Transcript Flow}


If we want to add different kinds of proofs, this is also a change we have to make: Fiat-Shamir Transcripts are different for each protocol.

dannywillems · 2026-01-24T21:11:37Z

src/lib/crypto/pickles/pickles.mli

+    {4 What Gets Passed vs Recomputed}
+
+    {b Passed from Wrap to Step:}
+    - [sponge_digest_before_evaluations]: Hash state at a checkpoint


This is important and one of the tricky part.

dannywillems · 2026-01-24T21:15:34Z

src/lib/crypto/pickles/step_verifier.ml

              let x = f messages in
              absorb sponge ty x ; x )
        in
-        let sample () = squeeze_challenge sponge in


Please review carefully these changes.

dannywillems · 2026-01-24T21:24:30Z

src/lib/crypto/pickles/wrap_verifier.mli

+    {2 Incremental Verification Flow (incrementally_verify_proof)}
+
+    {v
+    +-------------------------------------------------------------------------+


This should match the Kimchi verifier implementation.

dannywillems · 2026-01-24T21:25:33Z

src/lib/crypto/pickles/pickles.mli

+    {!module:Wrap_verifier} for the IVC step diagrams showing the precise
+    transcript flows in each circuit.
+
+    {b Important:} Challenges from previous proof rounds are verified within


dannywillems · 2026-01-24T21:25:48Z

src/lib/crypto/pickles/pickles.mli

+    commitments, public inputs, and prover messages, then squeezes out
+    challenges. The general pattern involves:
+
+    - Initializing the sponge with the verification key


I hope everything is there.

dannywillems · 2026-01-25T01:30:03Z

src/lib/crypto/pickles/step_verifier.mli

+    {3 Parameters}
+
+    - [~index]: The verification key polynomial commitments
+    - A function to extract field elements from the application state


It would be nice to document all the type variables here. It is mostly for the vector lengths, but still worth it as it would be faster for the reader to parse.

dannywillems · 2026-01-25T01:30:43Z

src/lib/crypto/pickles/step_verifier.mli


+(** {2 Message Hashing for Recursion} *)
+
+(** [hash_messages_for_next_step_proof] creates a staged function that hashes


To-do: add parameters to the function as it is often done in Caml doc.

dannywillems · 2026-01-25T01:32:49Z

src/lib/crypto/pickles/step_verifier.mli

+    This is the core constraint generation function that builds constraints
+    checking a wrap proof's validity by:
+    1. Reconstructing the Fiat-Shamir transcript and verifying challenges
+    2. Generating constraints for polynomial commitment openings via the IPA


Missing the challenge polynomial.

dannywillems added 3 commits January 24, 2026 17:43

Pickles: top level documentation

a8f4f76

Kimchi_pasta_snarky_backend: document scale_round

520bea1

Pickles/verifier: inline call to sponge

ffb3fab

dannywillems requested a review from a team as a code owner January 24, 2026 20:57

dannywillems commented Jan 24, 2026

View reviewed changes

dannywillems force-pushed the dw/endoscalar-mul-used branch 2 times, most recently from 9c0e0d0 to 3a6b941 Compare January 24, 2026 23:56

dannywillems added 5 commits January 24, 2026 21:07

Pickles/wrap_verifier: add top-level doc and doc exposed methods

c67e492

Pickles/wrap_verifier: document implementation

315ce0d

Pickles/Step_verifier: document interface and add top-level doc

e2bcf01

Pickles/step_verifier: document module implementation

34e06be

Pickles: wrap comments at 80 chars

277599d

dannywillems force-pushed the dw/endoscalar-mul-used branch from 3a6b941 to 277599d Compare January 25, 2026 00:07

dannywillems commented Jan 25, 2026

View reviewed changes

dannywillems added 4 commits January 26, 2026 15:53

Improve documentation regarding challenge polynomials in verifiers

6815a7d

Step/wrap verifier: remove doc of verify/incremental_verify

3a1cdc8

Step/wrap: update steps

36aab36

Pickles: simplify documentation

331eb18

dannywillems force-pushed the dw/endoscalar-mul-used branch 2 times, most recently from 961e830 to 4f1e6b6 Compare January 26, 2026 21:54

Pickles: remove dead/commented code

32f445f

dannywillems force-pushed the dw/endoscalar-mul-used branch from 4f1e6b6 to 32f445f Compare January 26, 2026 21:54


		{3 Challenge and Hash Flow Between Circuits}

		{4 Fiat-Shamir Transcript Flow}


		(** {2 Message Hashing for Recursion} *)

		(** [hash_messages_for_next_step_proof] creates a staged function that hashes

Pickles: add more documentation regarding verifiers #18362

Are you sure you want to change the base?

Pickles: add more documentation regarding verifiers #18362

Uh oh!

Conversation

dannywillems commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dannywillems Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dannywillems Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dannywillems commented Jan 24, 2026 •

edited

Loading

dannywillems Jan 24, 2026 •

edited

Loading

dannywillems Jan 24, 2026 •

edited

Loading