Skip to content

Commit 74efee3

Browse files
nuke-web3nuke-web3
authored
Add locad devnet guide (#3350)
* oneshot local devnet guide w/ claude * tested to work with docker, but really upstream tooling needs some tweaks
1 parent 89c7fe8 commit 74efee3

2 files changed

Lines changed: 185 additions & 0 deletions

File tree

‎docs/guides/deploy/local.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
description: Deploy an Evolve EVM chain locally for development and testing using ev-toolbox and local-da.
3+
---
4+
5+
# 🏠 Local Development Deployment
6+
7+
This guide walks you through deploying a complete Evolve EVM chain on your local machine using [ev-toolbox](https://github.com/evstack/ev-toolbox). It uses the **local-da** mock DA layer so there are no external dependencies or token costs.
8+
9+
## 🏗️ How it works
10+
11+
The local stack is split into two Docker Compose stacks that share a Docker network (`evstack_shared`):
12+
13+
```mermaid
14+
graph TB
15+
subgraph "da-local stack"
16+
LOCAL_DA[local-da<br/>:7980]
17+
end
18+
19+
subgraph "single-sequencer stack"
20+
SEQ_RETH[ev-reth<br/>:8545 JSON-RPC]
21+
SEQ_EVM[ev-node-evm<br/>aggregator mode]
22+
SEQ_RETH <--> SEQ_EVM
23+
end
24+
25+
SEQ_EVM -->|Post blobs| LOCAL_DA
26+
27+
classDef sequencer fill:#e1f5fe
28+
classDef da fill:#fff3e0
29+
class SEQ_RETH,SEQ_EVM sequencer
30+
class LOCAL_DA da
31+
```
32+
33+
The `da-local` stack is started first because it creates the shared Docker network that the sequencer stack joins.
34+
35+
## 💻 Prerequisites {#prerequisites}
36+
37+
- [Docker](https://docs.docker.com/get-docker/) 20.10 or later
38+
- [Docker Compose](https://docs.docker.com/compose/install/) v2 or later
39+
- [Git](https://git-scm.com/)
40+
41+
## 🛠️ Step 1 — Clone ev-toolbox {#clone}
42+
43+
```bash
44+
git clone --depth 1 https://github.com/evstack/ev-toolbox.git
45+
cd ev-toolbox/ev-stacks/stacks
46+
```
47+
48+
## 🌐 Step 2 — Start local-da {#start-local-da}
49+
50+
The `da-local` stack must be started first. It creates the `evstack_shared` Docker network that the sequencer stack joins.
51+
52+
```bash
53+
cd da-local
54+
docker compose up -d
55+
```
56+
57+
Verify it is running:
58+
59+
```bash
60+
docker logs local-da
61+
```
62+
63+
Expected output:
64+
65+
```
66+
INF NewLocalDA: initialized LocalDA component=da
67+
INF Listening on component=da host=0.0.0.0 maxBlobSize=1970176 port=7980
68+
INF server started component=da listening_on=0.0.0.0:7980
69+
```
70+
71+
## 🔑 Step 3 — Create the passphrase file {#passphrase}
72+
73+
The sequencer signs blocks with a key protected by a passphrase. Create the passphrase file in the single-sequencer directory:
74+
75+
```bash
76+
cd ../single-sequencer
77+
echo -n "devpassword" > passphrase
78+
```
79+
80+
:::tip
81+
For local development, any string works as a passphrase. Keep it simple — you will not need it again unless you restart with a wiped volume.
82+
:::
83+
84+
## 🚀 Step 4 — Start the sequencer {#start-sequencer}
85+
86+
Make the entrypoint script executable (required after `git clone` on some systems), then start the stack using the local-DA variant of the compose file:
87+
88+
```bash
89+
chmod +x entrypoint.sequencer.sh
90+
docker compose -f docker-compose.da.local.yml up -d
91+
```
92+
93+
Monitor startup:
94+
95+
```bash
96+
docker compose -f docker-compose.da.local.yml logs -f
97+
```
98+
99+
A healthy startup looks like:
100+
101+
```
102+
single-sequencer | 🚀 INIT: Starting EVM Sequencer initialization
103+
single-sequencer | ✅ SUCCESS: Sequencer initialization completed
104+
single-sequencer | ✅ SUCCESS: Exported genesis.json to /volumes/sequencer_export/genesis.json
105+
single-sequencer | ✅ SUCCESS: Successfully retrieved genesis hash: 0x6aec2...
106+
single-sequencer | 🚀 INIT: Starting EVM sequencer with command: evm start ...
107+
single-sequencer | INF Starting aggregator node component=main
108+
single-sequencer | INF produced block component=executor height=1
109+
single-sequencer | INF produced block component=executor height=2
110+
```
111+
112+
:::info DA submission errors
113+
You may see errors like `DA layer submission failed: method 'blob.Submit' not found`. This is a known version mismatch between the current local-da Docker images and ev-node-evm. It is **non-fatal** — blocks are produced and the JSON-RPC is fully functional for local development. You can ignore these errors.
114+
:::
115+
116+
## ✅ Step 5 — Verify {#verify}
117+
118+
The sequencer JSON-RPC port (`8545`) is not exposed to the host by default. To expose it for local testing, create an override file:
119+
120+
```bash
121+
cat > docker-compose.override.yml << 'EOF'
122+
services:
123+
ev-reth-sequencer:
124+
ports:
125+
- "8545:8545"
126+
EOF
127+
128+
docker compose -f docker-compose.da.local.yml -f docker-compose.override.yml up -d
129+
```
130+
131+
Then query the chain:
132+
133+
```bash
134+
curl -s -X POST http://localhost:8545 \
135+
-H 'Content-Type: application/json' \
136+
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
137+
```
138+
139+
The `result` field (a hex block number) should increment with each call as new blocks are produced.
140+
141+
## 🔍 Useful commands {#commands}
142+
143+
```bash
144+
# Check container status
145+
docker ps
146+
147+
# Follow all sequencer logs
148+
docker compose -f docker-compose.da.local.yml logs -f
149+
150+
# Follow just the ev-node logs (block production)
151+
docker logs -f single-sequencer
152+
153+
# Follow just the reth logs
154+
docker logs -f ev-reth-sequencer
155+
156+
# Stop everything
157+
docker compose -f docker-compose.da.local.yml down
158+
cd ../da-local && docker compose down
159+
```
160+
161+
## ⚙️ Configuration {#configuration}
162+
163+
All configuration is via environment variables in `.env` and the `docker-compose.da.local.yml` file.
164+
165+
| Variable | Default | Description |
166+
| ----------------------------------- | ------- | -------------------------------------------------------- |
167+
| `SEQUENCER_EV_RETH_PROMETHEUS_PORT` | `9000` | Host port for ev-reth Prometheus metrics |
168+
| `SEQUENCER_EV_NODE_PROMETHEUS_PORT` | `26660` | Host port for ev-node Prometheus metrics |
169+
| `DA_SIGNING_ADDRESSES` | (empty) | DA signing addresses — leave empty for local-da |
170+
| `EVM_BLOCK_TIME` | `500ms` | How often the sequencer produces blocks (set in compose) |
171+
172+
To change the block time or other settings, edit `docker-compose.da.local.yml` directly or add them to your `docker-compose.override.yml`.
173+
174+
## 🎉 Next Steps {#next-steps}
175+
176+
Once your local chain is running:
177+
178+
- [Testnet Deployment](./testnet.md) — deploy with real Celestia DA and a multi-node setup
179+
- [Local DA Guide](../da/local-da.md) — more about the `local-da` mock DA node
180+
- [Metrics](../metrics.md) — add Prometheus + Grafana monitoring
181+
182+
:::warning
183+
This setup is for development only. The `local-da` mock does not provide real data availability guarantees. Do not use it for any production environment.
184+
:::

‎docs/guides/deploy/overview.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ When you're ready to test with real network conditions, you can deploy to testne
3838

3939
Choose the deployment approach that matches your current needs:
4040

41+
- [🏠 Local Development](./local.md) - Run everything on your machine with local-da (no external dependencies)
4142
- [🌐 Testnet Deployment](./testnet.md) - Deploy on testnet with external DA networks
4243

4344
:::warning Disclaimer

0 commit comments

Comments
 (0)