Skip to content

docs(l2): clarify config parameters #2582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
+17 −17
Open

docs(l2): clarify config parameters #2582

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
0efce07
some docs
tomip01 Apr 24, 2025
42a6338
clarify dev_mode
tomip01 Apr 24, 2025
0bcfb0e
clarify arbitrary blob gas price
tomip01 Apr 24, 2025
ac380ba
rename prover server to coordinator
tomip01 Apr 24, 2025
9021ebd
Merge branch 'main' into docs/l2-sequencer
tomip01 Apr 25, 2025
41f622e
Merge branch 'main' into docs/l2-sequencer
tomip01 Apr 25, 2025
4202288
Merge branch 'main' into docs/l2-sequencer
tomip01 Apr 25, 2025
a33b38a
Merge branch 'main' into docs/l2-sequencer
tomip01 Apr 28, 2025
eb10ab9
Merge branch 'main' into docs/l2-sequencer
ilitteri Apr 28, 2025
c89384f
correct l1-watcher
tomip01 Apr 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions crates/l2/docs/sequencer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
- [Block Producer](#block-producer)
- [L1 Watcher](#l1-watcher)
- [L1 Transaction Sender (a.k.a. L1 Committer)](#l1-transaction-sender-aka-l1-committer)
- [Prover Server](#prover-server)
- [Proof Coordinator](#proof-coordinator)
- [Configuration](#configuration)

## Components
Expand All @@ -21,9 +21,7 @@ Creates Blocks with a connection to the `auth.rpc` port.

### L1 Watcher

This component handles the L1->L2 messages. Without rest, it is always watching the L1 for new deposit events defined as `DepositInitiated()` that contain the deposit transaction to be executed on the L2. Once a new deposit event is detected, it will insert the deposit transaction into the L2.

In the future, it will also be watching for other L1->L2 messages.
This component monitors the L1 for new deposits made by users. For that, it queries the CommonBridge contract on L1 at regular intervals (defined by the config file) for new DepositInitiated() events. Once a new deposit event is detected, it creates the corresponding deposit transaction on the L2.

### L1 Transaction Sender (a.k.a. L1 Committer)

Expand All @@ -33,11 +31,11 @@ Commit transactions are sent when the Proposer wants to commit to a new block. T

Verify transactions are sent by the Proposer after the prover has successfully generated a proof of block execution to verify it. These transactions contain the proof to be verified in the L1.

### Prover Server
### Proof Coordinator

The Prover Server is a simple TCP server that manages communication with a component called the `Prover Client`. The Prover Client acts as a simple TCP client, handling incoming requests to prove a block. It then "calls" a zkVM, generates the Groth16 proof, and sends it back to the Server. In this setup, the state is managed solely by the Prover Server, which, in theory, makes it less error-prone than the zkVMs.
The Proof Coordinator is a simple TCP server that manages communication with a component called the `Proof Sender`. The Proof Sender acts as a simple TCP client, handling incoming requests to prove a block. It then "calls" a zkVM, generates the Groth16 proof, and sends it back to the Coordinator. In this setup, the state is managed solely by the Proof Coordinator, which, in theory, makes it less error-prone than the zkVMs.
Copy link
Collaborator

@jrchatruc jrchatruc Apr 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is incorrect. The proof coordinator manages communication with the prover itself, it is not involved with the proof sender at all. In this sentence you can essentially replace all instances of proof sender with just prover.

Also, being a client, the prover does not handle requests to prove a block, but rather makes requests to prove blocks to the coordinator, which returns the proof input data required to produce said proof.

In this setup, the state is managed solely by the Proof Coordinator, which, in theory, makes it less error-prone than the zkVMs.

I would remove the in theory part, and instead explain that the idea here is to centralize in one place the job of deciding which block needs to be proven next and how to get the data for said proving to reduce complexity, making the prover (client) a dumb part of the system that simply asks for things to prove and proves them.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While we're at it, let's also add a ProofSender section explaining what the sender does (i.e. sending the proofs to L1 for verification once they are ready)


For more information about the Prover Server, the Prover Client, and the proving process itself, see the [Prover Docs](./prover.md).
For more information about the Proof Coordinator, the Proof Sender, and the proving process itself, see the [Prover Docs](./prover.md).

## Configuration

Expand All @@ -53,8 +51,8 @@ The following environment variables are available to configure the Proposer cons

- Under the `[deployer]` section:

- `l1_address`: L1 account which will deploy the common bridge contracts in L1.
- `l1_private key`: Its private key.
- `l1_address`: L1 account which will deploy the common bridge contracts in L1 with funds available for deployments.
- `l1_private key`: Private key corresponding to the above address.
- `pico_contract_verifier`: Address which will verify the `pico` proofs.
- `pico_deploy_verifier`: Whether to deploy the `pico` verifier contract or not.
- `risc0_contract_verifier`: Address which will verify the `risc0` proofs.
Expand All @@ -64,22 +62,23 @@ The following environment variables are available to configure the Proposer cons

- Under the `[watcher]` section:

- `bridge_address`: Address of the bridge contract on L1.
- `check_interval_ms`: Interval in milliseconds to check for new events.
- `max_block_step`: Maximum number of blocks to look for when checking for new events.
- `l2_proposer_private_key`: Private key of the L2 proposer.
- `bridge_address`: Address of the bridge contract on L1. This address is used to retrieve logs emitted by deposit events.
- `check_interval_ms`: Interval in milliseconds to check for new events. If no new events or messages are detected, it does nothing.
- `max_block_step`: Defines the maximum range of blocks to scan for new events during each polling cycle. Specifically, events are queried from last_block_fetched up to last_block_fetched + max_block_step. If the chain hasn’t progressed that far yet, the scan will end at the current latest block instead. This ensures we only query blocks that actually exist.
- `l2_proposer_private_key`: Private key of the L2 proposer.

- Under the `[proposer]` section:

- `interval_ms`: Interval in milliseconds to produce new blocks for the proposer.
- `interval_ms`: Interval in milliseconds at which the proposer wakes up to produce a new block.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interval in milliseconds at which the proposer builds a new block out of the current transactions on the mempool

- `coinbase address`: Address which will receive the execution fees.

- Under the `[committer]` section:

- `l1_address`: Address of the L1 committer.
- `l1_address`: Address of a funded account that it will be used to send commit transactions to the L1.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Address of a funded account that it will be used to send commit transactions to the L1.

Address of a funded account that will be used to send commit transactions to the L1.

- `l1_private_key`: Its private key.
- `commit_time_ms`: Sleep time after sending the commit transaction.
- `commit_time_ms`: Sleep time after sending the commit transaction with the proofs to the L1. If no new block has been fetched, we wait another `commit_time_ms` and check again.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The commit transaction does not contain the proofs, but rather the new state root of the L2, plus the state diff and a few other small things (deposits processed, withdrawals merkle root, etc)

If no new block has been fetched, we wait another commit_time_ms and check again.

If no new block has been built, the committer will simply wait another commit_time_ms and check again.

- `on_chain_proposer_address`: Address of the on-chain committer.
- `arbitrary_base_blob_gas_price`: Sets the minimum price floor for blob transactions when posting L2 data to the L1. This parameter allows you to control the lower bound of what the sequencer is willing to pay for blob storage. Higher values ensure faster inclusion in L1 blocks but increase operating costs, while lower values reduce costs but may cause delays.

- Under the `[prover_server]` section:

Expand All @@ -88,7 +87,8 @@ The following environment variables are available to configure the Proposer cons
- `l1_private_key`: Its private key.
- `listen_ip`: IP to listen for proof data requests.
- `listen_port`: Port to listen for proof data requests.
- `dev_mode`: Whether `dev_mode` is activated or not.
- `proof_send_interval_ms`: Interval in which the committer wakes up and send commitments to the L1
Copy link
Collaborator

@jrchatruc jrchatruc Apr 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interval in which the committer wakes up and send commitments to the L1

Periodicity with which the proof sender looks for new proofs to send to the L1 for verification.

- `dev_mode`: Whether `dev_mode` is activated or not. If it is activated, proofs won't be verified just executed. This can be seen on the OnChainProposer contract, specifically on the verify function, proofs will be ignored.
Copy link
Collaborator

@jrchatruc jrchatruc Apr 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whether dev_mode is activated or not. If it is activated, proofs won't be verified just executed. This can be seen on the OnChainProposer contract, specifically on the verify function, proofs will be ignored.

Whether dev_mode is activated or not. If it is activated, the prover won't actually generate proofs, but just execute the blocks it is given, and the proof sender will send empty proofs to the L1. The L1, in turn, will ignore proofs.


If you want to use a different configuration file, you can set the:

Expand Down