diff --git a/README.md b/README.md index 01e38f9a..65b881ae 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,9 @@ This repository is a modular Rust workspace for the Scroll rollup node. It is de ``` . -├── bin/ -│ └── rollup/ # Main binary crate (the node) -│ ├── src/ -│ └── assets/ +├── book/ # mdBook documentation (published to GitHub Pages) ├── crates/ # Internal library crates +│ ├── node/ # Main binary crate (the node) │ ├── codec/ │ ├── database/ │ │ ├── db/ @@ -27,20 +25,21 @@ This repository is a modular Rust workspace for the Scroll rollup node. It is de │ ├── chain-orchestrator/ │ ├── l1/ │ ├── network/ -│ ├── node/ │ ├── primitives/ │ ├── providers/ │ ├── scroll-wire/ │ ├── signer/ │ ├── sequencer/ │ └── watcher/ +├── sequencer-migration/ # Migration tooling from l2geth to l2reth +├── tests/ # Integration tests ├── Cargo.toml # Workspace manifest └── ... ``` ## Crate Descriptions -- **bin/rollup/**: The main binary crate. This is the entry point for running the rollup node. +- **crates/node/**: The main binary crate. This is the entry point for running the rollup node. - **crates/codec/**: Implements encoding/decoding logic for rollup data and payloads. - **crates/database/db/**: Database abstraction and storage logic for batches, blocks, and messages. - **crates/database/migration/**: Database schema migrations using SeaORM. @@ -56,6 +55,9 @@ This repository is a modular Rust workspace for the Scroll rollup node. It is de - **crates/scroll-wire/**: Wire protocol definitions for Scroll-specific networking. - **crates/sequencer/**: Sequencer logic for ordering and batching transactions. - **crates/watcher/**: Monitors L1 chain state and handles reorgs and notifications. +- **book/**: mdBook documentation published to [https://scroll-tech.github.io/rollup-node/](https://scroll-tech.github.io/rollup-node/) +- **tests/**: Integration tests for the rollup node, including E2E and sequencer migration tests +- **sequencer-migration/**: Scripts and tooling for migrating from l2geth to rollup-node (l2reth) ## Building the Project @@ -70,19 +72,20 @@ cargo build --bin rollup-node Or, from the binary crate directory: ```sh -cd bin/rollup +cd crates/node cargo build ``` ## Running the Node -After building, run the node with: +For comprehensive instructions on running a node, including: +- Hardware requirements +- Configuration options +- Example configurations for mainnet and sepolia +- Logging and debugging +- Troubleshooting -```sh -cargo run --workspace --bin rollup-node -- [ARGS] -``` - -Replace `[ARGS]` with any runtime arguments you require. +Please refer to the official documentation: **[https://scroll-tech.github.io/rollup-node/](https://scroll-tech.github.io/rollup-node/)** ## Running Tests @@ -116,61 +119,10 @@ cargo build --release --bin rollup-node The release binary will be located at `target/release/rollup-node`. -## Running a Sequencer Node - -To run a sequencer node you should build the binary in release mode using the instructions defined above. - -Then, you can run the sequencer node with the following command: - -### Using Private Key File -```sh -./target/release/rollup-node node --chain dev -d --sequencer.enabled --signer.key-file /path/to/your/private.key --http --http.api admin,debug,eth,net,trace,txpool,web3,rpc,reth,ots,flashbots,miner,mev -``` - -**Note**: The private key file should contain a hex-encoded private key (`64` characters, optionally prefixed with `0x`). - -### Using AWS KMS -```sh -./target/release/rollup-node node --chain dev -d --sequencer.enabled --signer.aws-kms-key-id arn:aws:kms:REGION:ACCOUNT:key/KEY-ID --http --http.api admin,debug,eth,net,trace,txpool,web3,rpc,reth,ots,flashbots,miner,mev -``` - -### Signer Configuration Notes +## Documentation -When running a sequencer, a signer is required unless the `--test` flag is specified. The two signing methods are mutually exclusive - use either `--signer.key-file` or `--signer.aws-kms-key-id`, but not both. - -**Private Key File**: Keep your private key file secure and never commit it to version control. - -**AWS KMS**: Requires KMS permissions `kms:GetPublicKey` and `kms:Sign` for the specified key. - -### General Information - -The above commands will start a dev node in sequencer mode with all rpc apis enabled. You can adjust the `--http.api` flag to include or exclude specific APIs as needed. - -The chain will be configured with a genesis that funds 20 addresses derived from the mnemonic: -``` -test test test test test test test test test test test junk -``` - -### Configuration Options - -A list of sequencer specific configuration options can be seen below: - -```sh - --scroll-sequencer-enabled - Enable the scroll block sequencer - --scroll-block-time - The block time for the sequencer [default: 2000] - --payload-building-duration - The payload building duration for the sequencer (milliseconds) [default: 500] - --max-l1-messages-per-block - The max L1 messages per block for the sequencer [default: 4] - --fee-recipient - The fee recipient for the sequencer [default: 0x5300000000000000000000000000000000000005] - --signer.key-file - Path to the hex-encoded private key file for the signer (optional 0x prefix). Mutually exclusive with AWS KMS key ID - --signer.aws-kms-key-id - AWS KMS Key ID or ARN for signing transactions. Mutually exclusive with key file -``` +- **[Official Documentation Book](https://scroll-tech.github.io/rollup-node/)** - Comprehensive guide for running follower and sequencer nodes +- **[Sequencer Migration Guide](./sequencer-migration/README.md)** - Documentation for migrating from l2geth to rollup-node ## Contributing diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 5b9b87d0..e63b526d 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,4 +2,5 @@ - [Introduction](./chapter_1.md) - [Running a Node](./running-a-node.md) +- [Running a Sequencer](./running-a-sequencer.md) - [Running with Docker Compose](./docker-operations.md) diff --git a/book/src/docker-operations.md b/book/src/docker-operations.md index 41233c8a..4bd3649e 100644 --- a/book/src/docker-operations.md +++ b/book/src/docker-operations.md @@ -247,7 +247,7 @@ your URLs and API keys are correct. ### Rollup Node Service -**Image**: `scrolltech/rollup-node:v0.0.1-rc67` +**Image**: `scrolltech/rollup-node:v1.0.5` **Port Mappings**: diff --git a/book/src/running-a-node.md b/book/src/running-a-node.md index 702c0154..b72c8a12 100644 --- a/book/src/running-a-node.md +++ b/book/src/running-a-node.md @@ -69,10 +69,10 @@ Replace: #### L1 Provider Configuration - `--l1.url `: L1 Ethereum RPC endpoint URL (required for follower nodes) -- `--l1.cups `: Compute units per second for rate limiting (default: 1000) +- `--l1.cups `: Compute units per second for rate limiting (default: 10000) - `--l1.max-retries `: Maximum retry attempts for L1 requests (default: 10) - `--l1.initial-backoff `: Initial backoff duration for retries in milliseconds (default: 100) -- `--l1.query-range `: Block range for querying L1 logs (default: 2000) +- `--l1.query-range `: Block range for querying L1 logs (default: 500) #### Blob Provider Configuration @@ -112,8 +112,8 @@ These can be used as reliable blob sources without requiring your own beacon nod #### Chain Orchestrator Configuration -- `--chain.optimistic-sync-trigger `: Block gap that triggers optimistic sync (default: 100) -- `--chain.chain-buffer-size `: In-memory chain buffer size (default: 100) +- `--chain.optimistic-sync-trigger `: Block gap that triggers optimistic sync (default: 1000) +- `--chain.chain-buffer-size `: In-memory chain buffer size (default: 2000) #### Engine Configuration @@ -125,7 +125,7 @@ These can be used as reliable blob sources without requiring your own beacon nod - `--http.addr
`: HTTP server listening address (default: 127.0.0.1) - `--http.port `: HTTP server port (default: 8545) - `--http.api `: Enabled RPC API namespaces (comma-separated) - - Available: `admin`, `debug`, `eth`, `net`, `trace`, `txpool`, `web3`, `rpc`, `reth`, `ots` + - Available: `admin`, `debug`, `eth`, `net`, `trace`, `txpool`, `web3`, `rpc`, `reth`, `ots`, `flashbots`, `miner`, `mev` - `--http.corsdomain `: CORS allowed origins (comma-separated) #### Rollup Node RPC @@ -247,7 +247,7 @@ Available log levels (from least to most verbose): ```bash RUST_LOG=info,scroll=debug,rollup=debug,sqlx=off \ ./target/release/rollup-node node \ - --chain scroll \ + --chain scroll-mainnet \ --datadir /var/lib/scroll-node \ --l1.url https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY \ --blob.s3_url https://scroll-mainnet-blob-data.s3.us-west-2.amazonaws.com/ \ diff --git a/book/src/running-a-sequencer.md b/book/src/running-a-sequencer.md new file mode 100644 index 00000000..eb1efc87 --- /dev/null +++ b/book/src/running-a-sequencer.md @@ -0,0 +1,355 @@ +# Running a Scroll Sequencer Node + +This guide covers how to run a Scroll rollup node in sequencer mode. A sequencer node is responsible for ordering transactions, building new blocks, and proposing them to the network. + +## What is a Sequencer Node? + +A sequencer node actively produces new blocks for the Scroll L2 chain. Unlike follower nodes that listen for blocks gossiped over L2 P2P and derive blocks from L1 data, sequencer nodes: + +- Accept transactions from the mempool +- Order transactions and build new blocks +- Include L1 messages in blocks according to configured inclusion strategy +- Sign blocks with a configured signer (private key or AWS KMS) +- Broadcast blocks to the network + +**Note:** Running a sequencer requires authorization. The sequencer's address must be registered as the authorized signer in the L1 system contract for blocks to be accepted by the network. + +## Prerequisites + +### Hardware Requirements + +Sequencer nodes have similar requirements to follower nodes: + +- **CPU**: 2+ cores @ 3 GHz +- **Memory**: 16 GB RAM + +### Building the Binary + +Build the rollup node binary in release mode for production use: + +```bash +cargo build --release --bin rollup-node +``` + +The release binary will be located at `target/release/rollup-node`. + +## Signer Configuration + +A sequencer node requires a signer to sign blocks. There are two signing methods available: + +### Option 1: Private Key File + +Store your private key in a file and reference it with the `--signer.key-file` flag. + +**Private Key File Format:** +- Hex-encoded private key (64 characters) +- Optional `0x` prefix +- No additional formatting or whitespace + +**Example private key file (`/secure/path/sequencer.key`):** +``` +0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef +``` + +**Security Best Practices:** +- Store the key file in a secure location with restricted permissions (`chmod 600`) +- Never commit private keys to version control +- Use file system encryption for the key file +- Regularly rotate sequencer keys +- Consider using hardware security modules (HSM) for production + +### Option 2: AWS KMS (not thoroughly tested!!) + +Use AWS Key Management Service (KMS) to manage your sequencer's signing key. This is the recommended approach for production deployments. + +**Requirements:** +- AWS account with KMS access +- KMS key created with signing capabilities +- IAM permissions for the sequencer node: + - `kms:GetPublicKey` - Retrieve the public key + - `kms:Sign` - Sign block hashes + +**KMS Key Format:** +``` +arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID +``` + +**Example:** +``` +arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012 +``` + +**Benefits of AWS KMS:** +- Keys never leave AWS infrastructure +- Centralized key management and rotation +- Audit logging of signing operations +- Fine-grained access control via IAM + +### Test Mode (Development Only) + +For development and testing, you can bypass signer requirements with the `--test` flag: + +```bash +--test +``` + +**Warning:** Never use test mode in production. It disables signature verification and is only suitable for local development. + +## Sequencer Configuration Flags + +### Core Sequencer Flags + +- `--sequencer.enabled`: Enable sequencer mode (default: `false`) +- `--sequencer.auto-start`: Automatically start sequencing on node startup (default: `false`) + +### Block Production Configuration + +- `--sequencer.block-time `: Time between blocks in milliseconds (default: `1000`) +- `--sequencer.payload-building-duration `: Time allocated for building each payload in milliseconds (default: `800`) +- `--sequencer.allow-empty-blocks`: Allow production of empty blocks when no transactions are available (default: `false`) + +### Fee Configuration + +- `--sequencer.fee-recipient
`: Address to receive block rewards and transaction fees (default: `0x5300000000000000000000000000000000000005` - Scroll fee vault) + +### L1 Message Inclusion + +The sequencer can include L1 messages in blocks using different strategies: + +- `--sequencer.l1-inclusion-mode `: Strategy for including L1 messages (default: `"finalized:2"`) + +**Available modes:** +- `finalized:N` - Include messages from finalized L1 blocks which have a block number <= current finalized - N (e.g., `finalized:2`) +- `depth:N` - Include messages from L1 blocks with a block number <= current head - N (e.g., `depth:10`) + +**Example:** +```bash +--sequencer.l1-inclusion-mode finalized:2 +``` + +- `--sequencer.max-l1-messages `: Override maximum L1 messages per block (optional) + +### Signer Configuration + +**Mutually exclusive options (choose one):** + +- `--signer.key-file `: Path to hex-encoded private key file +- `--signer.aws-kms-key-id `: AWS KMS key ID or ARN + +## Example Configurations + +### Development Sequencer (Test Mode) + +For local development and testing: + +```bash +./target/release/rollup-node node \ + --chain dev \ + --datadir ./data/sequencer \ + --test \ + --sequencer.enabled \ + --sequencer.auto-start \ + --sequencer.block-time 1000 \ + --http \ + --http.addr 0.0.0.0 \ + --http.port 8545 \ + --http.api admin,debug,eth,net,trace,txpool,web3,rpc,reth,ots,flashbots,miner,mev +``` + +**Notes:** +- Uses `--test` flag to bypass signer requirement +- Suitable for local development only +- Genesis funds available for testing + +### Production Sequencer with Private Key + +For production deployment with private key file: + +```bash +./target/release/rollup-node node \ + --chain scroll-mainnet \ + --datadir /var/lib/scroll-sequencer \ + --l1.url https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY \ + --blob.s3_url https://scroll-mainnet-blob-data.s3.us-west-2.amazonaws.com/ \ + --sequencer.enabled \ + --sequencer.auto-start \ + --sequencer.block-time 1000 \ + --sequencer.payload-building-duration 800 \ + --sequencer.l1-inclusion-mode finalized:2 \ + --sequencer.fee-recipient 0x5300000000000000000000000000000000000005 \ + --signer.key-file /secure/path/sequencer.key \ + --http \ + --http.addr 0.0.0.0 \ + --http.port 8545 \ + --http.api eth,net,web3,debug,trace +``` + +### Production Sequencer with AWS KMS + +For production deployment with AWS KMS: + +```bash +./target/release/rollup-node node \ + --chain scroll-mainnet \ + --datadir /var/lib/scroll-sequencer \ + --l1.url https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY \ + --blob.s3_url https://scroll-mainnet-blob-data.s3.us-west-2.amazonaws.com/ \ + --sequencer.enabled \ + --sequencer.auto-start \ + --sequencer.block-time 1000 \ + --sequencer.payload-building-duration 800 \ + --sequencer.l1-inclusion-mode finalized:2 \ + --sequencer.fee-recipient 0x5300000000000000000000000000000000000005 \ + --signer.aws-kms-key-id arn:aws:kms:us-west-2:123456789012:key/YOUR-KEY-ID \ + --http \ + --http.addr 0.0.0.0 \ + --http.port 8545 \ + --http.api eth,net,web3,debug,trace +``` + +### Sepolia Testnet Sequencer + +For testing on Sepolia testnet: + +```bash +./target/release/rollup-node node \ + --chain scroll-sepolia \ + --datadir /var/lib/scroll-sequencer-sepolia \ + --l1.url https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY \ + --blob.s3_url https://scroll-sepolia-blob-data.s3.us-west-2.amazonaws.com/ \ + --sequencer.enabled \ + --sequencer.auto-start \ + --signer.key-file /path/to/sepolia-sequencer.key \ + --http \ + --http.addr 0.0.0.0 \ + --http.port 8545 \ + --http.api eth,net,web3 +``` + +## Verifying Sequencer Operation + +### Check Sequencer is Producing Blocks + +Monitor the logs for block production: + +```bash +# Look for sequencer-related log entries +RUST_LOG=info,scroll=debug,rollup=debug ./target/release/rollup-node node ... +``` + +Expected log patterns: +- `Built payload` - Payload construction +- `Signed block` - Block signing +- `Broadcast block` - Block propagation + +### Query Latest Block + +Verify the sequencer is producing new blocks: + +```bash +# Check block number is incrementing +curl -X POST http://localhost:8545 \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "method": "eth_blockNumber", + "params": [], + "id": 1 + }' +``` + +Run this command multiple times (with `--sequencer.block-time` interval) to confirm blocks are being produced. + +## Logging and Debugging + +### Recommended Log Configuration for Sequencer + +For production sequencer operation with detailed logging: + +```bash +RUST_LOG=info,scroll=debug,rollup_node::sequencer=trace,scroll::engine=debug +``` + +### Sequencer-Specific Log Targets + +**Sequencer Operations:** +```bash +RUST_LOG=rollup_node::sequencer=trace +``` + +Monitor payload building, transaction selection, and block production. + +**Block Signing:** +```bash +RUST_LOG=rollup_node::signer=debug +``` + +Track signing operations and signer interactions. + +**L1 Message Processing:** +```bash +RUST_LOG=scroll::watcher=debug +``` + +Monitor L1 message detection and inclusion. + +## Troubleshooting + +### Sequencer Not Producing Blocks + +**Symptoms:** No new blocks appearing, logs show no sequencer activity + +**Possible causes:** +1. `--sequencer.auto-start` not enabled - Start sequencing manually via RPC +2. Signer configuration error - Check `--signer.*` flags +3. Not authorized on L1 - Verify sequencer address is registered in system contract +4. Insufficient gas for transactions - Check mempool has valid transactions +5. `--sequencer.allow-empty-blocks` not set and no transactions available + +**Solutions:** +- Enable auto-start: `--sequencer.auto-start` +- Verify signer configuration in logs +- Check authorization on L1 system contract +- Review logs with `RUST_LOG=rollup_node::sequencer=trace` + +### Signer Errors + +**Symptoms:** Errors mentioning "signer", "signature", or "key" + +**With `--signer.key-file`:** +- Verify file exists and is readable +- Check file permissions (`chmod 600`) +- Validate hex format (64 characters, optional `0x` prefix) +- Ensure no extra whitespace or newlines + +**With `--signer.aws-kms-key-id`:** +- Verify AWS credentials are configured +- Check IAM permissions (`kms:GetPublicKey`, `kms:Sign`) +- Confirm KMS key ARN is correct +- Check network connectivity to AWS +- Review AWS CloudTrail logs for KMS denials + +### Block Signing Failed + +**Symptoms:** Logs show "failed to sign" + +**Solutions:** +1. Check signer configuration is correct +2. For AWS KMS, verify network connectivity and IAM permissions +3. Ensure the signing key has not been disabled or deleted +4. Check system time is synchronized (important for KMS) + +### L1 Message Inclusion Errors + +**Symptoms:** Errors related to L1 messages, blocks rejected + +**Solutions:** +- Verify `--l1.url` is accessible and synced +- Check `--sequencer.l1-inclusion-mode` configuration appropriately +- Ensure L1 messages are being detected (check L1 watcher logs): `RUST_LOG=scroll::watcher=debug` + +## Additional Resources + +- [Running a Follower Node](./running-a-node.md) - Configuration for non-sequencer nodes +- [Docker Operations](./docker-operations.md) - Running node in Docker +- [Sequencer Migration Guide](../sequencer-migration/README.md) - Migrating from l2geth to rollup-node