Skip to content

Commit e5da82b

Browse files
greged93greged93
committed
feat: initial mdbook
1 parent 82dbc02 commit e5da82b

File tree

4 files changed

+391
-0
lines changed

4 files changed

+391
-0
lines changed

‎book/book.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[book]
2+
authors = ["Gregory Edison"]
3+
language = "en"
4+
src = "src"
5+
title = "Rollup node"

‎book/src/SUMMARY.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Summary
2+
3+
- [Introduction](./chapter_1.md)
4+
- [Running a Node](./running-a-node.md)

‎book/src/chapter_1.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Introduction
2+
3+
Welcome to the Scroll Rollup Node documentation.
4+
5+
## What is Scroll?
6+
7+
Scroll is a zkRollup on Ethereum that enables scaling while maintaining security and decentralization through
8+
zero-knowledge proofs. By moving computation and state storage off-chain while posting transaction data and validity
9+
proofs to Ethereum L1, Scroll achieves higher throughput and lower transaction costs while inheriting Ethereum's
10+
security guarantees.
11+
12+
## What is the Rollup Node?
13+
14+
The rollup node is responsible for constructing the Scroll L2 chain from data posted to Ethereum L1. At its core, the
15+
rollup node implements a derivation function: given the L1 chain state, it deterministically produces the corresponding
16+
L2 chain.
17+
18+
### Core Function
19+
20+
While conceptually the rollup node computes L2 as a pure function of L1 data, in practice it operates
21+
incrementally—processing new L1 blocks as they arrive and handling reorganizations when the L1 chain restructures. This
22+
incremental approach allows the node to efficiently maintain synchronization without reprocessing the entire chain
23+
history.
24+
25+
The derivation process works by:
26+
27+
1. **Monitoring L1**: Watching for batch commitments, finalization events, and cross-chain messages posted to Ethereum
28+
2. **Decoding Batches**: Extracting and decoding batch data (including blob data) to reconstruct transaction lists
29+
3. **Building Payloads**: Constructing execution payloads with the appropriate transactions and L1 messages
30+
4. **Executing Blocks**: Applying payloads through the execution engine to advance the L2 state
31+
32+
### Architecture
33+
34+
Built on the Reth framework, the rollup node employs an event-driven architecture where specialized components
35+
communicate through async channels:
36+
37+
- **L1 Watcher**: Tracks L1 events and maintains awareness of chain reorganizations
38+
- **Derivation Pipeline**: Transforms batch data from L1 into executable L2 payloads
39+
- **Engine Driver**: Interfaces with the execution engine via the Engine API
40+
- **Chain Orchestrator**: Coordinates the overall flow from L1 events to L2 blocks
41+
- **Network Layer**: Propagates blocks across the P2P network for faster synchronization
42+
43+
### Node Modes
44+
45+
The rollup node can operate in different configurations:
46+
47+
- **Follower Node**: Derives L2 blocks by processing batch data posted to L1, participating in P2P block propagation
48+
- **Sequencer Node**: Actively sequences new transactions into blocks and posts batches to L1
49+
50+
## About This Documentation
51+
52+
This documentation provides comprehensive guides for operating and understanding the Scroll rollup node, including setup
53+
instructions, configuration options, architecture details, and troubleshooting guidance.

‎book/src/running-a-node.md‎

Lines changed: 329 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,329 @@
1+
# Running a Scroll Rollup Node
2+
3+
This guide covers how to run a Scroll rollup node as a follower node.
4+
5+
## Hardware Requirements
6+
7+
The following are the recommended hardware specifications for running a Scroll rollup node:
8+
9+
### Recommended Requirements
10+
11+
- **CPU**: 2 cores @ 3 GHz
12+
- **Memory**: 16 GB RAM
13+
14+
These specifications are based on production deployments and should provide sufficient resources for stable operation as
15+
a follower node.
16+
17+
## Building the Node
18+
19+
### Prerequisites
20+
21+
- Rust toolchain (stable)
22+
- Cargo package manager
23+
24+
### Compilation
25+
26+
To build the rollup node binary:
27+
28+
```bash
29+
cargo build --release --bin rollup-node
30+
```
31+
32+
This will create an optimized production binary at `target/release/rollup-node`.
33+
34+
For development builds (faster compilation, slower runtime):
35+
36+
```bash
37+
cargo build --bin rollup-node
38+
```
39+
40+
## Running the Node
41+
42+
### Basic Command
43+
44+
To run the node as a follower:
45+
46+
```bash
47+
./target/release/rollup-node node \
48+
--chain <CHAIN_NAME> \
49+
--l1.url <L1_RPC_URL> \
50+
--blob.s3_url <BLOB_SOURCE_URL> \
51+
--http \
52+
--http.addr 0.0.0.0 \
53+
--http.port 8545
54+
```
55+
56+
Replace:
57+
58+
- `<CHAIN_NAME>`: The chain to follow (e.g., `scroll-mainnet`, `scroll-sepolia`, or `dev`)
59+
- `<L1_RPC_URL>`: HTTP(S) URL of an Ethereum L1 RPC endpoint
60+
- `<BLOB_SOURCE_URL>`: Blob data source URL (use Scroll's S3 URLs or your own beacon node)
61+
62+
### Essential Configuration Flags
63+
64+
#### Chain Configuration
65+
66+
- `--chain <CHAIN>`: Specify the chain to sync (`scroll-mainnet`, `scroll-sepolia`, or `dev`)
67+
- `-d, --datadir <PATH>`: Directory for node data storage (default: platform-specific)
68+
69+
#### L1 Provider Configuration
70+
71+
- `--l1.url <URL>`: L1 Ethereum RPC endpoint URL (required for follower nodes)
72+
- `--l1.cups <NUMBER>`: Compute units per second for rate limiting (default: 1000)
73+
- `--l1.max-retries <NUMBER>`: Maximum retry attempts for L1 requests (default: 10)
74+
- `--l1.initial-backoff <MS>`: Initial backoff duration for retries in milliseconds (default: 100)
75+
- `--l1.query-range <BLOCKS>`: Block range for querying L1 logs (default: 2000)
76+
77+
#### Blob Provider Configuration
78+
79+
The node requires access to blob data for derivation. Configure one or more blob sources:
80+
81+
- `--blob.beacon_node_urls <URL>`: Beacon node URLs for fetching blobs (comma-separated for multiple)
82+
- `--blob.s3_url <URL>`: S3-compatible storage URL for blob data
83+
- `--blob.anvil_url <URL>`: Anvil blob provider URL (for testing)
84+
85+
**Scroll-Provided S3 Blob Storage:**
86+
87+
Scroll provides public S3 blob storage endpoints for both networks:
88+
89+
- **Mainnet**: `https://scroll-mainnet-blob-data.s3.us-west-2.amazonaws.com/`
90+
- **Sepolia**: `https://scroll-sepolia-blob-data.s3.us-west-2.amazonaws.com/`
91+
92+
These can be used as reliable blob sources without requiring your own beacon node infrastructure.
93+
94+
#### Consensus Configuration
95+
96+
- `--consensus.algorithm <ALGORITHM>`: Consensus algorithm to use
97+
- `system-contract` (default): Validates blocks against authorized signer from L1
98+
- `noop`: No consensus validation (testing only)
99+
- `--consensus.authorized-signer <ADDRESS>`: Static authorized signer address (when using system-contract without L1
100+
provider)
101+
102+
#### Database Configuration
103+
104+
- `--rollup-node-db.path <PATH>`: Custom database path (default: `<datadir>/scroll.db`)
105+
106+
#### Network Configuration
107+
108+
- `--network.bridge`: Enable bridging blocks from eth wire to scroll wire protocol (default: true)
109+
- `--network.scroll-wire`: Enable the scroll wire protocol (default: true)
110+
- `--network.sequencer-url <URL>`: Sequencer RPC URL for following the sequencer
111+
- `--network.valid_signer <ADDRESS>`: Valid signer address for network validation
112+
113+
#### Chain Orchestrator Configuration
114+
115+
- `--chain.optimistic-sync-trigger <BLOCKS>`: Block gap that triggers optimistic sync (default: 100)
116+
- `--chain.chain-buffer-size <SIZE>`: In-memory chain buffer size (default: 100)
117+
118+
#### Engine Configuration
119+
120+
- `--engine.sync-at-startup`: Attempt to sync on startup (default: true)
121+
122+
#### HTTP RPC Configuration
123+
124+
- `--http`: Enable HTTP RPC server
125+
- `--http.addr <ADDRESS>`: HTTP server listening address (default: 127.0.0.1)
126+
- `--http.port <PORT>`: HTTP server port (default: 8545)
127+
- `--http.api <APIS>`: Enabled RPC API namespaces (comma-separated)
128+
- Available: `admin`, `debug`, `eth`, `net`, `trace`, `txpool`, `web3`, `rpc`, `reth`, `ots`
129+
- `--http.corsdomain <ORIGINS>`: CORS allowed origins (comma-separated)
130+
131+
#### Rollup Node RPC
132+
133+
- `--rpc.rollup-node`: Enable the rollup node RPC namespace (provides rollup-specific methods)
134+
135+
### Example Configurations
136+
137+
#### Scroll Mainnet Follower
138+
139+
```bash
140+
./target/release/rollup-node node \
141+
--chain scroll-mainnet \
142+
--datadir /var/lib/scroll-node \
143+
--l1.url https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY \
144+
--blob.s3_url https://scroll-mainnet-blob-data.s3.us-west-2.amazonaws.com/ \
145+
--http \
146+
--http.addr 0.0.0.0 \
147+
--http.port 8545 \
148+
--http.api eth,net,web3,debug,trace
149+
```
150+
151+
#### Scroll Sepolia Testnet Follower
152+
153+
```bash
154+
./target/release/rollup-node node \
155+
--chain scroll-sepolia \
156+
--datadir /var/lib/scroll-node-sepolia \
157+
--l1.url https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY \
158+
--blob.s3_url https://scroll-sepolia-blob-data.s3.us-west-2.amazonaws.com/ \
159+
--http \
160+
--http.addr 0.0.0.0 \
161+
--http.port 8545 \
162+
--http.api eth,net,web3
163+
```
164+
165+
## Logging and Debugging
166+
167+
The node uses Rust's `tracing` framework for structured logging. Configure log levels using the `RUST_LOG` environment
168+
variable.
169+
170+
### Log Level Configuration
171+
172+
The general format is: `RUST_LOG=<default_level>,<target>=<level>,...`
173+
174+
#### Recommended Log Configuration
175+
176+
For production with detailed rollup-specific logging:
177+
178+
```bash
179+
RUST_LOG=info,scroll=trace,rollup=trace,sqlx=off,scroll_txpool=trace ./target/release/rollup-node node ...
180+
```
181+
182+
This configuration:
183+
184+
- Sets default log level to `info`
185+
- Enables detailed `trace` logging for scroll-specific components
186+
- Enables detailed `trace` logging for rollup components
187+
- Disables verbose sqlx database query logging
188+
- Enables detailed `trace` logging for transaction pool operations
189+
190+
### Useful Log Targets
191+
192+
For debugging specific components, you can adjust individual log targets:
193+
194+
#### L1 Watcher
195+
196+
```bash
197+
RUST_LOG=scroll::watcher=debug
198+
```
199+
200+
Monitor L1 event watching, batch commits, and chain reorganizations.
201+
202+
#### Derivation Pipeline
203+
204+
```bash
205+
RUST_LOG=scroll::derivation_pipeline=debug
206+
```
207+
208+
Track batch decoding and payload attribute streaming.
209+
210+
#### Engine Driver
211+
212+
```bash
213+
RUST_LOG=scroll::engine=debug
214+
```
215+
216+
Debug engine API interactions and forkchoice updates.
217+
218+
#### Network Layer
219+
220+
```bash
221+
RUST_LOG=scroll::network=debug
222+
```
223+
224+
Monitor P2P networking and block propagation.
225+
226+
#### Database Operations
227+
228+
```bash
229+
RUST_LOG=scroll::db=debug
230+
```
231+
232+
Debug database queries and operations.
233+
234+
### Log Level Options
235+
236+
Available log levels (from least to most verbose):
237+
238+
- `error`: Only error messages
239+
- `warn`: Warnings and errors
240+
- `info`: General informational messages (recommended for production)
241+
- `debug`: Detailed debugging information
242+
- `trace`: Very detailed trace information (use for specific debugging)
243+
244+
### Combined Example with Logging
245+
246+
```bash
247+
RUST_LOG=info,scroll=debug,rollup=debug,sqlx=off \
248+
./target/release/rollup-node node \
249+
--chain scroll \
250+
--datadir /var/lib/scroll-node \
251+
--l1.url https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY \
252+
--blob.s3_url https://scroll-mainnet-blob-data.s3.us-west-2.amazonaws.com/ \
253+
--http \
254+
--http.addr 0.0.0.0 \
255+
--http.port 8545 \
256+
--http.api eth,net,web3
257+
```
258+
259+
## Verifying Node Operation
260+
261+
### Check Sync Status
262+
263+
Once the node is running, you can verify it's syncing properly:
264+
265+
```bash
266+
curl -X POST http://localhost:8545 \
267+
-H "Content-Type: application/json" \
268+
-d '{
269+
"jsonrpc": "2.0",
270+
"method": "eth_syncing",
271+
"params": [],
272+
"id": 1
273+
}'
274+
```
275+
276+
### Get Latest Block
277+
278+
```bash
279+
curl -X POST http://localhost:8545 \
280+
-H "Content-Type: application/json" \
281+
-d '{
282+
"jsonrpc": "2.0",
283+
"method": "eth_blockNumber",
284+
"params": [],
285+
"id": 1
286+
}'
287+
```
288+
289+
### Check Node Health
290+
291+
Monitor the node logs for:
292+
293+
- Successful L1 event processing
294+
- Block derivation progress
295+
- Engine API health
296+
- Database operations
297+
298+
Look for log entries indicating successful block processing and chain advancement.
299+
300+
## Troubleshooting
301+
302+
### Common Issues
303+
304+
**Node not syncing:**
305+
306+
- Verify L1 RPC endpoint is accessible and synced
307+
- Ensure beacon node URLs are correct and responsive
308+
- Check network connectivity
309+
- Review logs with `RUST_LOG=debug` for detailed error messages
310+
311+
**High memory usage:**
312+
313+
- Adjust `--chain.chain-buffer-size` to reduce memory footprint
314+
- Ensure system has adequate RAM (16GB recommended)
315+
316+
**Database errors:**
317+
318+
- Verify disk space is available
319+
- Check file permissions on datadir
320+
- Consider using a different database path with `--datadir`
321+
322+
**L1 connection errors:**
323+
324+
- Verify L1 RPC endpoint is reliable and has sufficient rate limits
325+
- Adjust `--l1.max-retries` and `--l1.initial-backoff` for unstable connections
326+
- Consider using a dedicated or archive L1 node
327+
328+
For additional support and detailed implementation information, refer to the project's CLAUDE.md and source code
329+
documentation.

0 commit comments

Comments
 (0)