chore(l2): update prover docs #5105

xqft · 2025-10-29T21:03:44Z

Organizes and updates some older docs

Copilot

Pull Request Overview

This PR introduces comprehensive documentation for the ethrex prover system, reorganizing and expanding the existing L2 prover documentation. The changes focus on explaining how zero-knowledge proofs are generated for block execution using stateless execution and execution witnesses.

Adds new standalone prover documentation explaining stateless execution, execution witnesses, and zkVM integration
Reorganizes L2 architecture documentation by extracting detailed prover internals into dedicated files
Adds documentation for data availability, execution witnesses, and developer setup instructions

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/prover/prover.md	New comprehensive guide explaining prover architecture, stateless execution, and L2-specific checks
docs/prover/guest_program.md	New detailed documentation of the guest program execution steps and public inputs/outputs
docs/l2/fundamentals/execution_witness.md	New explanation of execution witness creation, MPT proofs, and trie restructuring edge cases
docs/l2/fundamentals/data_availability.md	New documentation on state diffs, blob data, and KZG commitments for data availability
docs/l2/architecture/prover.md	Simplified to high-level overview with references to detailed prover documentation
docs/l2/architecture/overview.md	Streamlined by removing detailed prover explanations now in dedicated files
docs/developers/l2/prover.md	New developer guide with setup instructions, GPU configuration, and environment variables
docs/SUMMARY.md	Updated with new documentation entries

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/l2/fundamentals/data_availability.md

docs/l2/fundamentals/execution_witness.md

docs/prover/prover.md

docs/SUMMARY.md

Co-authored-by: Copilot <[email protected]>

Updated validation steps to clarify state trie root comparison and merkle proof verification.

Co-authored-by: Copilot <[email protected]>

tomip01 · 2025-10-30T18:09:08Z

docs/developers/l2/prover.md

+      ETHREX_L2_SP1=true
+      # Check the if the verification contract is present on your preferred network. Don't define this if you want it to be deployed automatically.
+      ETHREX_DEPLOYER_SP1_VERIFIER_ADDRESS=<address>
+      # Set to true if you want proofs to be required


Suggested change

# Set to true if you want proofs to be required

# Set to true if you want RISC0 proofs to be required

tomip01 · 2025-10-30T18:09:56Z

docs/developers/l2/prover.md

+  - `make rm-db-l2 && make down`
+  - `make deploy-l1 && make init-l2` (if running a risc0 prover, see the next step before invoking the L1 contract deployer)


Suggested change

- `make rm-db-l2 && make down`

- `make deploy-l1 && make init-l2` (if running a risc0 prover, see the next step before invoking the L1 contract deployer)

- `make rm-db-l2 down`

- `make deploy-l1 init-l2` (if running a risc0 prover, see the next step before invoking the L1 contract deployer)

Also the make down will shut down a local L1. We could use the down-l2 or mention to start the L1 again init-l1-docker

tomip01 · 2025-10-30T18:15:27Z

docs/developers/l2/prover.md

+  - `make rm-db-l2 && make down`
+  - `make deploy-l1 && make init-l2` (if running a risc0 prover, see the next step before invoking the L1 contract deployer)
+
+- If running with a local L1 (for development), you will need to manually deploy the risc0 contracts by following the instructions [here](https://github.com/risc0/risc0-ethereum/tree/main/contracts/script).


We could mention how to deploy the sp1 verifier contract with the deployer

xqft · 2025-10-31T18:05:56Z

We should add more details on the prover's inputs/outputs, what it commits as public values and what remains private, and which computation it does with each value, as this is one of the most critical aspects of the prover (thank you @MauroToscano for the feedback!)

avilagaston9 · 2025-11-11T16:48:04Z

docs/developers/l2/prover.md

+
+### L1 block proving
+
+ethrex-prover is able to generate execution proofs of Ethereum Mainnet/Testnet blocks. An example binary was created for this purpose in `crates/l2/prover/bench`. Refer to its README for usage.


The path crates/l2/prover/bench does not exist

avilagaston9 · 2025-11-11T16:51:16Z

docs/developers/l2/prover.md

+   - Start the L2 locally on port `1729`.
+4. In a new terminal &rarr; `make init-prover-<sp1|risc0|exec> # GPU=true`.
+
+After this initialization we should have the prover running in `dev_mode` &rarr; No real proofs.


With sp1 or risc0 real proofs will be created

tomip01 · 2025-11-11T18:24:46Z

docs/developers/l2/prover.md

+
+## Dev Mode
+
+To run the blockchain (`proposer`) and prover in conjunction, start the `Prover`, use the following command:


I think the sentence is more clear with something like this

Suggested change

To run the blockchain (`proposer`) and prover in conjunction, start the `Prover`, use the following command:

To run the blockchain (`proposer`) and prover in conjunction by starting the `Prover` with:

tomip01 · 2025-11-11T18:27:41Z

docs/developers/l2/prover.md

+> Used for development purposes.
+
+1. `cd crates/l2`
+2. `make rm-db-l2 && make down`


If you want you can use:

Suggested change

2. `make rm-db-l2 && make down`

2. `make rm-db-l2 down`

tomip01 · 2025-11-11T18:32:28Z

docs/developers/l2/prover.md

+   - Add the `user` you are using to the `docker` group &rarr; command: `sudo usermod -aG docker $USER`. (needs reboot, doing it after CUDA installation)
+   - `id -nG` after reboot to check if the user is in the group.
+2. Install [Rust](https://www.rust-lang.org/tools/install)
+3. Install [RISC0](https://dev.risczero.com/api/zkvm/install)


do we want to add sp1?

tomip01 · 2025-11-11T18:55:59Z

docs/developers/l2/prover.md

+  - `make rm-db-l2 && make down`
+  - `make deploy-l1 && make init-l2` (if running a risc0 prover, see the next step before invoking the L1 contract deployer)


Also the make down will shut down a local L1. We could use the down-l2 or mention to start the L1 again init-l1-docker

gianbelinche · 2025-11-13T19:16:34Z

docs/l2/fundamentals/data_availability.md

+Going a bit further, instead of posting the entire transaction, we could just post which accounts have been modified and their new values (this includes deployed contracts and their bytecode of course). This can reduce the size a lot for most cases; in the case of a regular transfer as above, we only need to record balance updates of two accounts, which requires sending just two `(address, balance)` pairs, so (20 + 32) * 2 = 104 bytes, or around half as before. Some other clever techniques and compression algorithms can push down the publishing cost of this and other transactions much further.
+
+This is called `state diffs`. Instead of publishing entire transactions for data availability, we only publish whatever state they modified. This is enough for anyone to reconstruct the entire state of the chain.


We don't post state diffs anymore, we now just post the list of transactions

xqft added 2 commits October 29, 2025 17:46

update docs

9669756

fixes

5fbb04b

xqft requested a review from a team as a code owner October 29, 2025 21:03

Copilot AI review requested due to automatic review settings October 29, 2025 21:03

github-actions bot assigned xqft Oct 29, 2025

github-actions bot added the L2 Rollup client label Oct 29, 2025

github-project-automation bot added this to ethrex_l2 Oct 29, 2025

Copilot AI reviewed Oct 29, 2025

View reviewed changes

xqft and others added 7 commits October 30, 2025 11:02

Update docs/l2/fundamentals/data_availability.md

ef5fd8d

Co-authored-by: Copilot <[email protected]>

Update docs/l2/fundamentals/data_availability.md

1eb7ba9

Co-authored-by: Copilot <[email protected]>

Update docs/l2/fundamentals/execution_witness.md

d4baf8e

Co-authored-by: Copilot <[email protected]>

Clarify validation steps in guest_program.md

09ef46e

Updated validation steps to clarify state trie root comparison and merkle proof verification.

Update docs/l2/fundamentals/execution_witness.md

c87f6f2

Co-authored-by: Copilot <[email protected]>

Update docs/prover/prover.md

003b3e8

Co-authored-by: Copilot <[email protected]>

Update docs/SUMMARY.md

5aacc7c

Co-authored-by: Copilot <[email protected]>

xqft changed the title ~~chore(l2): update docs~~ chore(l2): update prover docs Oct 30, 2025

Merge branch 'main' into l2/update_docs

488b396

tomip01 reviewed Oct 30, 2025

View reviewed changes

avilagaston9 reviewed Nov 11, 2025

View reviewed changes

tomip01 reviewed Nov 11, 2025

View reviewed changes

Merge branch 'main' of github.com:lambdaclass/ethrex into l2/update_docs

5cfa00d

gianbelinche reviewed Nov 13, 2025

View reviewed changes

	# Set to true if you want proofs to be required
	# Set to true if you want RISC0 proofs to be required

		- `make rm-db-l2 && make down`
		- `make deploy-l1 && make init-l2` (if running a risc0 prover, see the next step before invoking the L1 contract deployer)


		### L1 block proving

		ethrex-prover is able to generate execution proofs of Ethereum Mainnet/Testnet blocks. An example binary was created for this purpose in `crates/l2/prover/bench`. Refer to its README for usage.


		## Dev Mode

		To run the blockchain (`proposer`) and prover in conjunction, start the `Prover`, use the following command:

		Going a bit further, instead of posting the entire transaction, we could just post which accounts have been modified and their new values (this includes deployed contracts and their bytecode of course). This can reduce the size a lot for most cases; in the case of a regular transfer as above, we only need to record balance updates of two accounts, which requires sending just two `(address, balance)` pairs, so (20 + 32) * 2 = 104 bytes, or around half as before. Some other clever techniques and compression algorithms can push down the publishing cost of this and other transactions much further.

		This is called `state diffs`. Instead of publishing entire transactions for data availability, we only publish whatever state they modified. This is enough for anyone to reconstruct the entire state of the chain.

chore(l2): update prover docs #5105

Are you sure you want to change the base?

chore(l2): update prover docs #5105

Uh oh!

Conversation

xqft commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

xqft commented Oct 31, 2025

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

xqft commented Oct 29, 2025 •

edited

Loading