diff --git a/book.toml b/book.toml index d2c1f57fc05..c175794ab6a 100644 --- a/book.toml +++ b/book.toml @@ -28,10 +28,18 @@ after = ["links"] git-repository-url = "https://github.com/lambdaclass/ethrex" # make sections collapsible, and start with everything collapsed fold = { enable = true, level = 0 } - # Required for mdbook-mermaid additional-js = ["mermaid.min.js", "mermaid-init.js"] +# keep README links working in mdBook output +[output.html.redirect] +"/getting-started/README.html" = "/getting-started/index.html" +"/getting-started/installation/README.html" = "/getting-started/installation/index.html" +"/l1/running/README.html" = "/l1/running/index.html" +"/developers/l1/testing/README.html" = "/developers/l1/testing/index.html" +"/l2/fundamentals/README.html" = "/l2/fundamentals/index.html" +"/l2/architecture/README.html" = "/l2/architecture/index.html" + # Broken-link checker # https://github.com/Michael-F-Bryan/mdbook-linkcheck # Needs to be installed with `cargo install mdbook-linkcheck` diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 5b3c29032c1..2fdbb2efccc 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -36,6 +36,7 @@ - [Deploying a vanilla ethrex L2](./l2/deployment/vanilla.md) - [Deploying a validium ethrex L2](./l2/deployment/validium.md) - [Deploying a based ethrex L2](./l2/deployment/based.md) + - [Ethrex <> Aligned](./l2/deployment/aligned.md) - [Synchronous Composability PoC](./l2/deployment/synchronous_composability_poc.md) - [Deploying a shared bridge enabled L2](./l2/deployment/shared_bridge.md) - [Migrations](./l2/deployment/migrations.md) @@ -47,7 +48,6 @@ - [Run multiple provers](./l2/deployment/prover/multi-prover.md) - [Monitoring and metrics](./l2/monitoring.md) - [Admin server](./l2/admin.md) -- [Ethrex <> Aligned](./l2/aligned_integration.md) - [Architecture](./l2/architecture/README.md) - [Overview](./l2/architecture/overview.md) - [Sequencer](./l2/architecture/sequencer.md) diff --git a/docs/l2/aligned_integration.md b/docs/l2/aligned_integration.md deleted file mode 100644 index d936078ec4b..00000000000 --- a/docs/l2/aligned_integration.md +++ /dev/null @@ -1,307 +0,0 @@ -# Running Ethrex in Aligned Mode - -This document explains how to run an Ethrex L2 node in **Aligned mode** and highlights the key differences in component behavior compared to the default mode. - -- Check [How to Run (local devnet)](#how-to-run-local-devnet) for a development or testing. -- Check [How to Run (testnet)](#how-to-run-testnet) for a prod-like environment. - -## How to run (testnet) - -> [!IMPORTANT] -> For this guide we assumed that there is an L1 running with all Aligned environment set. - -### 1. Generate the prover ELF/VK - -Run: - -```bash -cd ethrex/crates/l2 -make build-prover- # optional: GPU=true -``` - -This will generate the SP1 ELF program and verification key under: - -- `crates/l2/prover/src/guest_program/src/sp1/out/riscv32im-succinct-zkvm-elf` -- `crates/l2/prover/src/guest_program/src/sp1/out/riscv32im-succinct-zkvm-vk-u32` - -### 2. Deploying L1 Contracts - -In a console with `ethrex/crates/l2` as the current directory, run the following command: - -```bash -COMPILE_CONTRACTS=true \ -ETHREX_L2_ALIGNED=true \ -ETHREX_DEPLOYER_ALIGNED_AGGREGATOR_ADDRESS= \ -ETHREX_L2_SP1=true \ -ETHREX_DEPLOYER_RANDOMIZE_CONTRACT_DEPLOYMENT=true \ -cargo run --release --features l2,l2-sql --manifest-path "../../Cargo.toml" -- l2 deploy \ - --eth-rpc-url \ - --private-key \ - --on-chain-proposer-owner \ - --bridge-owner \ - --genesis-l2-path "../../fixtures/genesis/l2.json" \ - --proof-sender.l1-address -``` - -> [!NOTE] -> This command requires the COMPILE_CONTRACTS env variable to be set, as the deployer needs the SDK to embed the proxy bytecode. -> In this step we are initiallizing the `OnChainProposer` contract with the `ALIGNED_PROOF_AGGREGATOR_SERVICE_ADDRESS` and skipping the rest of verifiers, you can find the address for the aligned aggegator service [here](https://docs.alignedlayer.com/guides/7_contract_addresses) -> Save the addresses of the deployed proxy contracts, as you will need them to run the L2 node. -> Accounts for the deployer, on-chain proposer owner, bridge owner, and proof sender must have funds. Add `--bridge-owner-pk ` if you want the deployer to immediately call `acceptOwnership` on behalf of that owner; otherwise, they can accept later. - -### 3. Deposit funds to the `AlignedBatcherPaymentService` contract from the proof sender - -```bash -aligned deposit-to-batcher \ ---network \ ---private_key \ ---rpc_url \ ---amount -``` - -> [!IMPORTANT] -> Using the [Aligned CLI](https://docs.alignedlayer.com/guides/9_aligned_cli) - -### 4. Running a node - -In a console with `ethrex/crates/l2` as the current directory, run the following command: - -```bash -cargo run --release --manifest-path ../../Cargo.toml --bin ethrex --features "l2,sp1" -- \ - l2 \ - --watcher.block-delay 0 \ - --network "../../fixtures/genesis/l2.json" \ - --l1.bridge-address \ - --l1.on-chain-proposer-address \ - --eth.rpc-url \ - --aligned \ - --aligned-network \ - --block-producer.coinbase-address \ - --committer.l1-private-key \ - --proof-coordinator.l1-private-key \ - --aligned.beacon-url \ - --datadir ethrex_l2 \ - --no-monitor -``` - -Both commiter and proof coordinator should have funds. - -Aligned params explanation: - -- `--aligned`: Enables aligned mode, enforcing all required parameters. -- `--aligned.beacon-url`: URL of the beacon client used by the Aligned SDK to verify proof aggregations, it has to support `/eth/v1/beacon/blobs` -- `--aligned-network`: Parameter used by the [Aligned SDK](https://docs.alignedlayer.com/guides/1.2_sdk_api_reference). - -If you can't find a beacon client URL which supports that endpoint, you can run your own with lighthouse and ethrex: - -Create secrets directory and jwt secret - -```bash -mkdir -p ethereum/secrets/ -cd ethereum/ -openssl rand -hex 32 | tr -d "\n" | tee ./secrets/jwt.hex -``` - -```bash -lighthouse bn --network --execution-endpoint http://localhost:8551 --execution-jwt --checkpoint-sync-url --http --purge-db-force --supernode -``` - -```bash -cargo run --release --manifest-path ../../Cargo.toml --bin ethrex -- --authrpc.jwtsecret --network -``` - -### 4. Running the Prover - -In a console with `ethrex/crates/l2` as the current directory, run the following command: - -```bash -make init-prover- GPU=true # The GPU parameter is optional -``` - -Then you should wait until aligned aggregates your proof - -## How to run (local devnet) - -> [!IMPORTANT] -> This guide assumes you have already generated the prover ELF/VK. See: [Generate the prover ELF/VK](#1-generate-the-prover-elfvk) - -### Set Up the Aligned Environment - -1. Clone the Aligned repository and checkout the currently supported release: - -```bash -git clone git@github.com:yetanotherco/aligned_layer.git -cd aligned_layer -git checkout tags/v0.19.1 -``` - -2. Edit the `aligned_layer/network_params.rs` file to send some funds to the `committer` and `integration_test` addresses: - -``` -prefunded_accounts: '{ - "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266": { "balance": "100000000000000ETH" }, - "0x70997970C51812dc3A010C7d01b50e0d17dc79C8": { "balance": "100000000000000ETH" }, - - ... - "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720": { "balance": "100000000000000ETH" }, -+ "0x4417092B70a3E5f10Dc504d0947DD256B965fc62": { "balance": "100000000000000ETH" }, -+ "0x3d1e15a1a55578f7c920884a9943b3b35d0d885b": { "balance": "100000000000000ETH" }, - }' -``` - -You can also decrease the seconds per slot in `aligned_layer/network_params.rs`: - -``` -# Number of seconds per slot on the Beacon chain - seconds_per_slot: 4 -``` - -Change `ethereum-genesis-generator` to 5.0.8 - -``` -ethereum_genesis_generator_params: - # The image to use for ethereum genesis generator - image: ethpandaops/ethereum-genesis-generator:5.0.8 -``` - -3. Make sure you have the latest version of [kurtosis](https://github.com/kurtosis-tech/kurtosis) installed and start the ethereum-package: - -``` -cd aligned_layer -make ethereum_package_start -``` - -If you need to stop it run `make ethereum_package_rm` - -4. Start the batcher: - -First, increase the `max_proof_size` in `aligned_layer/config-files/config-batcher-ethereum-package.yaml` `max_proof_size: 104857600 # 100 MiB` for example. - -``` -cd aligned_layer -make batcher_start_ethereum_package -``` - -This is the Aligned component that receives the proofs before sending them in a batch. - -> [!Warning] -> If you see the following error in the batcher: `[ERROR aligned_batcher] Unexpected error: Space limit exceeded: Message too long: 16940713 > 16777216` modify the file `aligned_layer/batcher/aligned-batcher/src/lib.rs` at line 433 with the following code: - -```Rust -use tokio_tungstenite::tungstenite::protocol::WebSocketConfig; - -let mut stream_config = WebSocketConfig::default(); -stream_config.max_frame_size = None; - -let ws_stream_future = - tokio_tungstenite::accept_async_with_config(raw_stream, Some(stream_config)); -``` - -### Initialize L2 node -1. In another terminal let's deploy the L1 contracts, specifying the `AlignedProofAggregatorService` contract address, and adding the required prover types (Risc0 or SP1): -``` -cd ethrex/crates/l2 -COMPILE_CONTRACTS=true \ -ETHREX_L2_ALIGNED=true \ -ETHREX_DEPLOYER_ALIGNED_AGGREGATOR_ADDRESS=0xcbEAF3BDe82155F56486Fb5a1072cb8baAf547cc \ -ETHREX_L2_SP1=true \ -ETHREX_L2_RISC0=true \ -make deploy-l1 -``` - -Both `ETHREX_L2_SP1` and `ETHREX_L2_RISC0` are optional - -> [!NOTE] -> This command requires the COMPILE_CONTRACTS env variable to be set, as the deployer needs the SDK to embed the proxy bytecode. - -You will see that some deposits fail with the following error: - -``` -2025-10-13T19:44:51.600047Z ERROR ethrex::l2::deployer: Failed to deposit address=0x0002869e27c6faee08cca6b765a726e7a076ee0f value_to_deposit=0 -2025-10-13T19:44:51.600114Z WARN ethrex::l2::deployer: Failed to make deposits: Deployer EthClient error: eth_sendRawTransaction request error: insufficient funds for gas * price + value: have 0 want 249957710190063 -``` - -This is because not all the accounts are pre-funded from the genesis. - -2. Send some funds to the Aligned batcher payment service contract from the proof sender: - -``` -cd aligned_layer/crates/cli -cargo run deposit-to-batcher \ ---network devnet \ ---private_key 0x39725efee3fb28614de3bacaffe4cc4bd8c436257e2c8bb887c4b5c4be45e76d \ ---amount 1ether -``` - -3. Start our l2 node: - -``` -cd ethrex/crates/l2 -ETHREX_ALIGNED_MODE=true \ -ETHREX_ALIGNED_BEACON_URL=http://127.0.0.1:58801 \ -ETHREX_ALIGNED_NETWORK=devnet \ -ETHREX_PROOF_COORDINATOR_DEV_MODE=false \ -SP1=true \ -RISC0=true \ -make init-l2 -``` - -Suggestion: -When running the integration test, consider increasing the `--committer.commit-time` to 2 minutes. This helps avoid having to aggregate the proofs twice. You can do this by adding the following flag to the `init-l2-no-metrics` target: - -``` ---committer.commit-time 120000 -``` - -4. Start prover(s) in different terminals: -```bash -cd ethrex/crates/l2 -make init-prover- GPU=true # The GPU flag is optional -``` - -### Aggregate proofs: - -After some time, you will see that the `l1_proof_verifier` is waiting for Aligned to aggregate the proofs. You can trigger an aggregation (for either sp1 or risc0 proofs) by running: - -```bash -cd aligned_layer -make proof_aggregator_start AGGREGATOR= - -# or with gpu acceleration -make proof_aggregator_start_gpu AGGREGATOR= -``` - -If successful, the `l1_proof_verifier` will print the following logs: - -``` -INFO ethrex_l2::sequencer::l1_proof_verifier: Proof for batch 1 aggregated by Aligned with commitment 0xa9a0da5a70098b00f97d96cee43867c7aa8f5812ca5388da7378454580af2fb7 and Merkle root 0xa9a0da5a70098b00f97d96cee43867c7aa8f5812ca5388da7378454580af2fb7 -INFO ethrex_l2::sequencer::l1_proof_verifier: Batches verified in OnChainProposer, with transaction hash 0x731d27d81b2e0f1bfc0f124fb2dd3f1a67110b7b69473cacb6a61dea95e63321 -``` - -## Behavioral Differences in Aligned Mode - -### Prover - -- Generates `Compressed` proofs instead of `Groth16`. -- Required because Aligned currently only accepts SP1 compressed proofs. - -### Proof Sender - -- Sends proofs to the **Aligned Batcher** instead of the `OnChainProposer` contract. -- Tracks the last proof sent using the rollup store. - -![Proof Sender Aligned Mode](./img/aligned_mode_proof_sender.png) - -### Proof Verifier - -- Spawned only in Aligned mode. -- Monitors whether the next proof has been aggregated by Aligned. -- Once verified, collects all already aggregated proofs and triggers the advancement of the `OnChainProposer` contract by sending a single transaction. - -![Aligned Mode Proof Verifier](./img/aligned_mode_proof_verifier.png) - -### OnChainProposer - -- Uses `verifyBatchesAligned()` instead of `verifyBatch()`. -- Receives an array of proofs to verify. -- Delegates proof verification to the `AlignedProofAggregatorService` contract. diff --git a/docs/l2/deployment/README.md b/docs/l2/deployment/README.md index 1af77096fec..dded04cee96 100644 --- a/docs/l2/deployment/README.md +++ b/docs/l2/deployment/README.md @@ -8,5 +8,6 @@ Use this section to choose the deployment method that best fits your needs and f - [Deploying a vanilla ethrex L2](./vanilla.md) - [Deploying a validium ethrex L2](./validium.md) - [Deploying a based ethrex L2](./based.md) +- [Ethrex <> Aligned](./aligned.md) - [Deploying a shared bridge enabled L2](./shared_bridge.md) - [Migrations](./migrations.md) diff --git a/docs/l2/deployment/aligned.md b/docs/l2/deployment/aligned.md new file mode 100644 index 00000000000..f34ce05c3d8 --- /dev/null +++ b/docs/l2/deployment/aligned.md @@ -0,0 +1,306 @@ +# Running Ethrex in Aligned Mode + +This guide extends the [Deploy an L2 overview](./overview.md) and shows how to run an ethrex L2 with **Aligned mode** enabled. It assumes: + +- You already installed the `ethrex` binary to your `$PATH` (for example from the repo root with `cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql --force`). +- You have the ethrex repository checked out locally for the `make` targets referenced below. + +- Check [How to Run (local devnet)](#how-to-run-local-devnet) for development or testing. +- Check [How to Run (testnet)](#how-to-run-testnet) for a prod-like environment. + +## How to run (testnet) + +> [!IMPORTANT] +> This guide assumes there is an L1 running with all Aligned environment set. + +### 1. Generate the prover ELF/VK + +From the ethrex repository root run: + +```bash +make -C crates/l2 build-prover- # optional: GPU=true +``` + +This will generate the SP1 ELF program and verification key under: + +- `crates/l2/prover/src/guest_program/src/sp1/out/riscv32im-succinct-zkvm-elf` +- `crates/l2/prover/src/guest_program/src/sp1/out/riscv32im-succinct-zkvm-vk-u32` + +### 2. Deploying L1 Contracts + +Run the deployer with the Aligned settings: + +```bash +COMPILE_CONTRACTS=true \ +ETHREX_L2_ALIGNED=true \ +ETHREX_DEPLOYER_ALIGNED_AGGREGATOR_ADDRESS= \ +ETHREX_L2_SP1=true \ +ETHREX_DEPLOYER_RANDOMIZE_CONTRACT_DEPLOYMENT=true \ +ethrex l2 deploy \ + --eth-rpc-url \ + --private-key \ + --on-chain-proposer-owner \ + --bridge-owner \ + --genesis-l2-path fixtures/genesis/l2.json \ + --proof-sender.l1-address +``` + +> [!NOTE] +> This command requires the `COMPILE_CONTRACTS` env variable to be set, as the deployer needs the SDK to embed the proxy bytecode. +> In this step we are initializing the `OnChainProposer` contract with the `ALIGNED_PROOF_AGGREGATOR_SERVICE_ADDRESS` and skipping the rest of verifiers; you can find the address for the aligned aggregator service [here](https://docs.alignedlayer.com/guides/7_contract_addresses). +> Save the addresses of the deployed proxy contracts, as you will need them to run the L2 node. +> Accounts for the deployer, on-chain proposer owner, bridge owner, and proof sender must have funds. Add `--bridge-owner-pk ` if you want the deployer to immediately call `acceptOwnership` on behalf of that owner; otherwise, they can accept later. +> If you enable more than one proving system (e.g., both `--sp1 true` and `--risc0 true`), all selected proving systems will be required (i.e., every batch must include a proof from each enabled system to settle on L1). + +### 3. Deposit funds to the `AlignedBatcherPaymentService` contract from the proof sender + +```bash +aligned deposit-to-batcher \ + --network \ + --private_key \ + --rpc_url \ + --amount +``` + +> [!IMPORTANT] +> Using the [Aligned CLI](https://docs.alignedlayer.com/guides/9_aligned_cli) + +### 4. Running a node + +Run the sequencer using the installed `ethrex` binary: + +```bash +ethrex l2 \ + --watcher.block-delay 0 \ + --network fixtures/genesis/l2.json \ + --l1.bridge-address \ + --l1.on-chain-proposer-address \ + --eth.rpc-url \ + --aligned \ + --aligned-network \ + --block-producer.coinbase-address \ + --committer.l1-private-key \ + --proof-coordinator.l1-private-key \ + --aligned.beacon-url \ + --datadir ethrex_l2 \ + --no-monitor +``` + +Both committer and proof coordinator should have funds. + +Aligned params explanation: + +- `--aligned`: Enables aligned mode, enforcing all required parameters. +- `--aligned.beacon-url`: URL of the beacon client used by the Aligned SDK to verify proof aggregations, it has to support `/eth/v1/beacon/blobs` +- `--aligned-network`: Parameter used by the [Aligned SDK](https://docs.alignedlayer.com/guides/1.2_sdk_api_reference). + +If you can't find a beacon client URL which supports that endpoint, you can run your own with lighthouse and ethrex: + +Create secrets directory and jwt secret + +```bash +mkdir -p ethereum/secrets/ +openssl rand -hex 32 | tr -d "\n" | tee ./ethereum/secrets/jwt.hex +``` + +```bash +lighthouse bn --network --execution-endpoint http://localhost:8551 --execution-jwt ./ethereum/secrets/jwt.hex --checkpoint-sync-url --http --purge-db-force --supernode +``` + +```bash +ethrex --authrpc.jwtsecret ./ethereum/secrets/jwt.hex --network +``` + +### 5. Running the Prover + +In another terminal start the prover(s): + +```bash +make -C crates/l2 init-prover- GPU=true # The GPU parameter is optional +``` + +Then you should wait until Aligned aggregates your proof. + +## How to run (local devnet) + +> [!IMPORTANT] +> This guide assumes you have already generated the prover ELF/VK. See: [Generate the prover ELF/VK](#1-generate-the-prover-elfvk) + +### Set Up the Aligned Environment + +1. Clone the Aligned repository and checkout the currently supported release: + + ```bash + git clone git@github.com:yetanotherco/aligned_layer.git + cd aligned_layer + git checkout tags/v0.19.1 + ``` + +2. Edit the `aligned_layer/network_params.rs` file to send some funds to the `committer` and `integration_test` addresses: + + ``` + prefunded_accounts: '{ + "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266": { "balance": "100000000000000ETH" }, + "0x70997970C51812dc3A010C7d01b50e0d17dc79C8": { "balance": "100000000000000ETH" }, + + ... + "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720": { "balance": "100000000000000ETH" }, + + "0x4417092B70a3E5f10Dc504d0947DD256B965fc62": { "balance": "100000000000000ETH" }, + + "0x3d1e15a1a55578f7c920884a9943b3b35d0d885b": { "balance": "100000000000000ETH" }, + }' + ``` + + You can also decrease the seconds per slot in `aligned_layer/network_params.rs`: + + ``` + # Number of seconds per slot on the Beacon chain + seconds_per_slot: 4 + ``` + + Change `ethereum-genesis-generator` to 5.0.8 + + ``` + ethereum_genesis_generator_params: + # The image to use for ethereum genesis generator + image: ethpandaops/ethereum-genesis-generator:5.0.8 + ``` + +3. Make sure you have the latest version of [kurtosis](https://github.com/kurtosis-tech/kurtosis) installed and start the ethereum-package: + + ``` + cd aligned_layer + make ethereum_package_start + ``` + + If you need to stop it run `make ethereum_package_rm` + +4. Start the batcher: + + First, increase the `max_proof_size` in `aligned_layer/config-files/config-batcher-ethereum-package.yaml` `max_proof_size: 104857600 # 100 MiB` for example. + + ``` + cd aligned_layer + make batcher_start_ethereum_package + ``` + + This is the Aligned component that receives the proofs before sending them in a batch. + +> [!WARNING] +> If you see the following error in the batcher: `[ERROR aligned_batcher] Unexpected error: Space limit exceeded: Message too long: 16940713 > 16777216` modify the file `aligned_layer/batcher/aligned-batcher/src/lib.rs` at line 433 with the following code: +> +> ```Rust +> use tokio_tungstenite::tungstenite::protocol::WebSocketConfig; +> +> let mut stream_config = WebSocketConfig::default(); +> stream_config.max_frame_size = None; +> +> let ws_stream_future = +> tokio_tungstenite::accept_async_with_config(raw_stream, Some(stream_config)); +> ``` + +### Initialize L2 node + +1. Deploy the L1 contracts, specifying the `AlignedProofAggregatorService` contract address, and adding the required prover types (Risc0 or SP1): + + ```bash + COMPILE_CONTRACTS=true \ + ETHREX_L2_ALIGNED=true \ + ETHREX_DEPLOYER_ALIGNED_AGGREGATOR_ADDRESS=0xcbEAF3BDe82155F56486Fb5a1072cb8baAf547cc \ + ETHREX_L2_SP1=true \ + ETHREX_L2_RISC0=true \ + make -C crates/l2 deploy-l1 + ``` + + Both `ETHREX_L2_SP1` and `ETHREX_L2_RISC0` are optional. + + > [!NOTE] + > This command requires the COMPILE_CONTRACTS env variable to be set, as the deployer needs the SDK to embed the proxy bytecode. + + You will see that some deposits fail with the following error: + + ``` + 2025-10-13T19:44:51.600047Z ERROR ethrex::l2::deployer: Failed to deposit address=0x0002869e27c6faee08cca6b765a726e7a076ee0f value_to_deposit=0 + 2025-10-13T19:44:51.600114Z WARN ethrex::l2::deployer: Failed to make deposits: Deployer EthClient error: eth_sendRawTransaction request error: insufficient funds for gas * price + value: have 0 want 249957710190063 + ``` + + This is because not all the accounts are pre-funded from the genesis. + +2. Send some funds to the Aligned batcher payment service contract from the proof sender: + + ```bash + cargo run --manifest-path aligned_layer/crates/cli/Cargo.toml deposit-to-batcher \ + --network devnet \ + --private_key 0x39725efee3fb28614de3bacaffe4cc4bd8c436257e2c8bb887c4b5c4be45e76d \ + --amount 1ether + ``` + +3. Start the L2 node: + + ```bash + ETHREX_ALIGNED_MODE=true \ + ETHREX_ALIGNED_BEACON_URL=http://127.0.0.1:58801 \ + ETHREX_ALIGNED_NETWORK=devnet \ + ETHREX_PROOF_COORDINATOR_DEV_MODE=false \ + SP1=true \ + RISC0=true \ + make -C crates/l2 init-l2 + ``` + + Suggestion: + When running the integration test, consider increasing the `--committer.commit-time` to 2 minutes. This helps avoid having to aggregate the proofs twice. You can do this by adding the following flag to the `init-l2-no-metrics` target: + + ``` + --committer.commit-time 120000 + ``` + +4. Start prover(s) in different terminals: + + ```bash + make -C crates/l2 init-prover- GPU=true # The GPU flag is optional + ``` + +### Aggregate proofs: + +After some time, you will see that the `l1_proof_verifier` is waiting for Aligned to aggregate the proofs. You can trigger an aggregation (for either sp1 or risc0 proofs) by running: + +```bash +make -C aligned_layer proof_aggregator_start AGGREGATOR= + +# or with gpu acceleration +make -C aligned_layer proof_aggregator_start_gpu AGGREGATOR= +``` + +If successful, the `l1_proof_verifier` will print the following logs: + +``` +INFO ethrex_l2::sequencer::l1_proof_verifier: Proof for batch 1 aggregated by Aligned with commitment 0xa9a0da5a70098b00f97d96cee43867c7aa8f5812ca5388da7378454580af2fb7 and Merkle root 0xa9a0da5a70098b00f97d96cee43867c7aa8f5812ca5388da7378454580af2fb7 +INFO ethrex_l2::sequencer::l1_proof_verifier: Batches verified in OnChainProposer, with transaction hash 0x731d27d81b2e0f1bfc0f124fb2dd3f1a67110b7b69473cacb6a61dea95e63321 +``` + +## Behavioral Differences in Aligned Mode + +### Prover + +- Generates `Compressed` proofs instead of `Groth16`. +- Required because Aligned currently only accepts SP1 compressed proofs. + +### Proof Sender + +- Sends proofs to the **Aligned Batcher** instead of the `OnChainProposer` contract. +- Tracks the last proof sent using the rollup store. + +![Proof Sender Aligned Mode](../img/aligned_mode_proof_sender.png) + +### Proof Verifier + +- Spawned only in Aligned mode. +- Monitors whether the next proof has been aggregated by Aligned. +- Once verified, collects all already aggregated proofs and triggers the advancement of the `OnChainProposer` contract by sending a single transaction. + +![Aligned Mode Proof Verifier](../img/aligned_mode_proof_verifier.png) + +### OnChainProposer + +- Uses `verifyBatchesAligned()` instead of `verifyBatch()`. +- Receives an array of proofs to verify. +- Delegates proof verification to the `AlignedProofAggregatorService` contract. diff --git a/docs/l2/deployment/overview.md b/docs/l2/deployment/overview.md index d8303da4b72..f673f6ed2fd 100644 --- a/docs/l2/deployment/overview.md +++ b/docs/l2/deployment/overview.md @@ -7,7 +7,7 @@ In addition to these classic functionalities, ethrex L2 provides a novel and con In this section, we will cover how to deploy any of these options. > [!NOTE] -> This section focuses solely on the step-by-step process for deploying ethrex L2 in any of its forms. For a deeper understanding of how each mode works under the hood, refer to the Fundamentals section. To learn more about the architecture of each mode, see the Architecture section. +> This section focuses solely on the step-by-step process for deploying ethrex L2 in any of its forms. For a deeper understanding of how each mode works under the hood, refer to the [Fundamentals](../fundamentals/README.md) section. To learn more about the architecture of each mode, see the [Architecture](../architecture/README.md) section. Before proceeding, note that this guide assumes you have ethrex installed. If you haven't installed it yet, follow one of the methods in the [Installation Guide](../../getting-started/installation/README.md). If you're looking to build from source, don't skip this section—we'll cover that method here, as it is independent of the deployment approach you choose later. @@ -30,34 +30,39 @@ Ensure you have the following installed on your system: cd ethrex ``` -2. Build the binary: +2. Install the binary to your `$PATH`: ```shell # For dummy proving - COMPILE_CONTRACTS=true cargo build --release --bin ethrex --features l2,l2-sql + COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql # For SP1 CPU proving (very slow, not recommended) - COMPILE_CONTRACTS=true cargo build --release --bin ethrex --features l2,l2-sql,sp1 + COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1 # For RISC0 CPU proving (very slow, not recommended) - COMPILE_CONTRACTS=true cargo build --release --bin ethrex --features l2,l2-sql,risc0 + COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,risc0 # For SP1 and RISC0 CPU proving (very slow, not recommended) - COMPILE_CONTRACTS=true cargo build --release --bin ethrex --features l2,l2-sql,sp1,risc0 + COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,risc0 # For SP1 GPU proving - COMPILE_CONTRACTS=true cargo build --release --bin ethrex --features l2,l2-sql,sp1,gpu + COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,gpu # For RISC0 GPU proving - COMPILE_CONTRACTS=true cargo build --release --bin ethrex --features l2,l2-sql,risc0,gpu + COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,risc0,gpu # For SP1 and RISC0 GPU proving - COMPILE_CONTRACTS=true cargo build --release --bin ethrex --features l2,l2-sql,sp1,risc0,gpu + COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,risc0,gpu ``` + By default `cargo install` places the binary at `~/.cargo/bin/ethrex` (make sure that directory is on your `$PATH`). Add `--force` to the commands above if you need to overwrite a previous installation. + > [!WARNING] > If you want your verifying keys generation to be reproducible, prepend `PROVER_REPRODUCIBLE_BUILD=true` to the above command: > > ```shell -> PROVER_REPRODUCIBLE_BUILD=true COMPILE_CONTRACTS=true cargo b -r --bin ethrex -F l2,l2-sql,sp1,risc0,gpu +> PROVER_REPRODUCIBLE_BUILD=true COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,risc0,gpu > ``` + +> [!IMPORTANT] +> Compiling with both `sp1` and `risc0` features only makes the binary capable of both. Settlement requires every proof you mark as required at deploy time (e.g., passing both `--sp1 true` and `--risc0 true` in `ethrex l2 deploy` will require both proofs). diff --git a/docs/l2/deployment/prover/overview.md b/docs/l2/deployment/prover/overview.md index c0a32350ca0..19dbdd7ada9 100644 --- a/docs/l2/deployment/prover/overview.md +++ b/docs/l2/deployment/prover/overview.md @@ -9,7 +9,7 @@ The next step is to run the prover—the component responsible for generating ZK In this section, we'll cover how to run one or more ethrex L2 provers. > [!NOTE] -> This section focuses solely on the step-by-step process for running an ethrex L2 prover in any of its forms. For a deeper understanding of this works under the hood, refer to the Fundamentals section. To learn more about the architecture of each mode, see the Architecture section. +> This section focuses solely on the step-by-step process for running an ethrex L2 prover in any of its forms. For a deeper understanding of how this works under the hood, refer to the [Fundamentals](../../fundamentals/README.md) section. To learn more about the architecture of each mode, see the [Architecture](../../architecture/README.md) section. Before proceeding, note that this guide assumes you have ethrex installed. If you haven't installed it yet, follow one of the methods in the [Installation Guide](../../../getting-started/installation/README.md). If you're looking to build from source, don't skip this section—we'll cover that method here, as it is independent of the deployment approach you choose later. @@ -32,33 +32,38 @@ Ensure you have the following installed on your system: cd ethrex ``` -2. Build the binary: +2. Install the binary to your `$PATH`: ```shell # For SP1 CPU proving (very slow, not recommended) - cargo build --release --bin ethrex --features l2,l2-sql,sp1 + cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1 # For RISC0 CPU proving (very slow, not recommended) - cargo build --release --bin ethrex --features l2,l2-sql,risc0 + cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,risc0 # For SP1 and RISC0 CPU proving (very slow, not recommended) - cargo build --release --bin ethrex --features l2,l2-sql,sp1,risc0 + cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,risc0 # For SP1 GPU proving - cargo build --release --bin ethrex --features l2,l2-sql,sp1,gpu + cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,gpu # For RISC0 GPU proving - cargo build --release --bin ethrex --features l2,l2-sql,risc0,gpu + cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,risc0,gpu # For SP1 and RISC0 GPU proving - cargo build --release --bin ethrex --features l2,l2-sql,sp1,risc0,gpu + cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,risc0,gpu ``` + `cargo install` places the binary at `~/.cargo/bin/ethrex`; ensure that directory is on your `$PATH`. Add `--force` if you need to reinstall. + > [!WARNING] > If you want your verifying keys generation to be reproducible, prepend `PROVER_REPRODUCIBLE_BUILD=true` to the above command. > > Example: > > ```shell -> PROVER_REPRODUCIBLE_BUILD=true COMPILE_CONTRACTS=true cargo b -r --bin ethrex -F l2,l2-sql,sp1,risc0,gpu +> PROVER_REPRODUCIBLE_BUILD=true COMPILE_CONTRACTS=true cargo install --locked --path cmd/ethrex --bin ethrex --features l2,l2-sql,sp1,risc0,gpu > ``` + +> [!IMPORTANT] +> Building with both `sp1` and `risc0` features enabled only enables both backends. Settlement will require every proof you mark as required at deploy time (e.g., passing both `--sp1 true` and `--risc0 true` in `ethrex l2 deploy` requires both proofs). diff --git a/docs/l2/deployment/validium.md b/docs/l2/deployment/validium.md index 92ccf615bae..d4c1f6cc56e 100644 --- a/docs/l2/deployment/validium.md +++ b/docs/l2/deployment/validium.md @@ -29,13 +29,22 @@ ethrex l2 deploy \ > [!IMPORTANT] > If you plan to prove your L2 using SP1, RISC0, or TEE, add the following extra arguments to the command above: +> > `--sp1 true` to require SP1 proofs for validating batch execution and state settlement. +> > `--sp1.verifier-address` to use an existing verifier instead of deploying one on the public network. Succinct Labs recommends their deployed canonical verifier gateways; see the list here. +> > `--risc0 true` to require RISC0 proofs for validating batch execution and state settlement. +> > `--risc0.verifier-address` to use an existing verifier instead of deploying one on the public network. RISC0 recommends their deployed canonical verifier gateways; see the list here. +> > `--tdx true` to require TEE proofs for validating batch execution and state settlement. +> > `--tdx.verifier-address` to use an existing verifier instead of deploying one on the public network. Do not pass this flag if you want to deploy a new verifier. +> > Enabling multiple proving backend will require running multiple provers, one for each backend. Refer to the [Run multiple provers](./prover/multi-prover.md) section for more details. +> +> If you enable more than one proving system (e.g., both `--sp1 true` and `--risc0 true`), all selected proving systems will be required (i.e., every batch must include a proof from each enabled system to settle on L1). > [!IMPORTANT] > Retrieve the deployed contract addresses from the console logs or the .env file generated during deployment (in the directory where you ran the command) for use in the next step. @@ -80,5 +89,10 @@ ethrex l2 \ > - Replace `L2_COINBASE_ADDRESS` with the address that will collect L2 block fees. To access these funds on L1, you'll need to withdraw them (see the Withdrawals section for details). > - Replace `L1_PROOF_SENDER_PRIVATE_KEY` and `L1_COMMITTER_PRIVATE_KEY` with the private keys for the `L1_PROOF_SENDER_ADDRESS` and `L1_COMMITTER_ADDRESS` from the deployment step. > - Replace `L1_RPC_URL` and `PATH_TO_L2_GENESIS_FILE` with the same values used in the deployment step. +> - Tune throughput with the gas caps: +> - `--block-producer.block-gas-limit` (env: `ETHREX_BLOCK_PRODUCER_BLOCK_GAS_LIMIT`, default: `30000000`): Sets the gas limit per L2 block. +> - `--committer.batch-gas-limit` (env: `ETHREX_COMMITTER_BATCH_GAS_LIMIT`): Sets the gas limit per batch sent to L1—should be at or above the block gas limit. +> +> You can use either the environment variables or the flags to configure these values. That's it! You now have a validium ethrex L2 up and running. However, one key component is still missing: state proving. The L2 state is considered final only after a batch execution ZK proof is successfully verified on-chain. Generating these proofs requires running a dedicated prover, which is covered in the Run an ethrex L2 Prover section. diff --git a/docs/l2/deployment/vanilla.md b/docs/l2/deployment/vanilla.md index 8acc5afe047..3849072d65a 100644 --- a/docs/l2/deployment/vanilla.md +++ b/docs/l2/deployment/vanilla.md @@ -28,13 +28,22 @@ ethrex l2 deploy \ > [!IMPORTANT] > If you plan to prove your L2 using SP1, RISC0, or TDX, add the following extra arguments to the command above: +> > `--sp1 true` to require SP1 proofs for validating batch execution and state settlement. +> > `--sp1.verifier-address` to use an existing verifier instead of deploying one on the public network. Succinct Labs recommends their deployed canonical verifier gateways; see the list here. +> > `--risc0 true` to require RISC0 proofs for validating batch execution and state settlement. +> > `--risc0.verifier-address` to use an existing verifier instead of deploying one on the public network. RISC0 recommends their deployed canonical verifier gateways; see the list here. +> > `--tdx true` to require TEE proofs for validating batch execution and state settlement. +> > `--tdx.verifier-address` to use an existing verifier instead of deploying one on the public network. Do not pass this flag if you want to deploy a new verifier. +> > Enabling multiple proving backend will require running multiple provers, one for each backend. Refer to the [Run multiple provers](./prover/multi-prover.md) section for more details. +> +> If you enable more than one proving system (e.g., both `--sp1 true` and `--risc0 true`), all selected proving systems will be required (i.e., every batch must include a proof from each enabled system to settle on L1). > [!IMPORTANT] > Retrieve the deployed contract addresses from the console logs or the .env file generated during deployment (in the directory where you ran the command) for use in the next step. @@ -78,5 +87,10 @@ ethrex l2 \ > - Replace `L2_COINBASE_ADDRESS` with the address that will collect L2 block fees. To access these funds on L1, you'll need to withdraw them (see the Withdrawals section for details). > - Replace `L1_PROOF_SENDER_PRIVATE_KEY` and `L1_COMMITTER_PRIVATE_KEY` with the private keys for the `L1_PROOF_SENDER_ADDRESS` and `L1_COMMITTER_ADDRESS` from the deployment step. > - Replace `L1_RPC_URL` and `PATH_TO_L2_GENESIS_FILE` with the same values used in the deployment step. +> - Tune throughput with the gas caps: +> - `--block-producer.block-gas-limit` (env: `ETHREX_BLOCK_PRODUCER_BLOCK_GAS_LIMIT`, default: `30000000`): Sets the gas limit per L2 block. +> - `--committer.batch-gas-limit` (env: `ETHREX_COMMITTER_BATCH_GAS_LIMIT`): Sets the gas limit per batch sent to L1—should be at or above the block gas limit. +> +> You can use either the environment variables or the flags to configure these values. That's it! You now have a vanilla ethrex L2 up and running. However, one key component is still missing: state proving. The L2 state is considered final only after a batch execution ZK proof is successfully verified on-chain. Generating these proofs requires running a dedicated prover, which is covered in the Run an ethrex L2 Prover section. diff --git a/docs/l2/introduction.md b/docs/l2/introduction.md index 76100accfdb..5ffef87bdae 100644 --- a/docs/l2/introduction.md +++ b/docs/l2/introduction.md @@ -1,6 +1,6 @@ # Introduction -Layer 2 (L2) solutions are protocols built on top of Ethereum to increase scalability and reduce transaction costs. L2s process transactions off-chain and periodically post data or proofs back to Ethereum mainnet, inheriting its security. +Layer 2 (L2) solutions are protocols built on top of Ethereum to increase scalability and reduce transaction costs. L2s process transactions off-chain and, in the case of Rollups, they periodically post data or proofs back to Ethereum Layer 1, inheriting its security. **Ethrex** is a framework that lets you launch your own L2 rollup or blockchain. With ethrex, you can deploy, run, and experiment with custom L2 networks, taking advantage of Ethereum's security while enabling high throughput and low fees.