Skip to content

Commit 5da10d8

Browse files
srypssryps
authored
poa validator set cli tools (#94)
* poa cli tool wip * change requests * fix spawn.bash * add_validator works * clippy and less clones * fmt * testnet docs and cleanup * change requests * allow address or pubkey for poa cmd
1 parent c255717 commit 5da10d8

4 files changed

Lines changed: 727 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ monitoring/data-grafana/
55
monitoring/data-prometheus/
66
assets
77
.testnet
8+
.claude
89

910
# Docs and env
1011
example/docs/

‎docs/local-testnet/README.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# Testnet Setup Guide
2+
3+
This guide explains how to create and manage a local Emerald testnet using the Makefile and the Proof-of-Authority (PoA) utilities.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Creating a New Network](#creating-a-new-network)
9+
- [Managing Validators with PoA Tools](#managing-validators-with-poa-tools)
10+
- [Network Configuration](#network-configuration)
11+
- [Troubleshooting](#troubleshooting)
12+
13+
## Overview
14+
15+
Malaketh-layered uses Malachite BFT consensus connected to Reth execution clients via Engine API. The testnet setup creates multiple validator nodes that reach consensus on blocks with instant finality.
16+
17+
### Architecture
18+
19+
- **Consensus Layer**: Malachite BFT (instant finality)
20+
- **Execution Layer**: Reth (Ethereum execution client)
21+
- **Connection**: Engine API with JWT authentication
22+
- **Validator Management**: ValidatorManager PoA smart contract at `0x0000000000000000000000000000000000002000`
23+
24+
## Creating a New Network
25+
26+
### Quick Start: 3-Validator Network
27+
28+
The default configuration creates a 3-validator network:
29+
30+
```bash
31+
make
32+
```
33+
34+
This command performs the following steps:
35+
36+
1. Cleans previous testnet data
37+
2. Builds the project (Solidity contracts + Rust binaries)
38+
3. Generates testnet configuration for 3 nodes
39+
4. Creates validator keys and node directories
40+
5. Extracts validator public keys
41+
6. Generates genesis file with initial validators
42+
7. Starts Docker containers (Reth nodes, Prometheus, Grafana, Otterscan)
43+
8. Configures peer connections
44+
9. Spawns Malachite consensus nodes
45+
46+
**Monitoring**: Grafana dashboard available at http://localhost:3000
47+
48+
### 4-Validator Network
49+
50+
To create a network with 4 validators:
51+
52+
```bash
53+
make four
54+
```
55+
56+
### What Happens During Network Creation
57+
58+
1. **Configuration Generation** (`./scripts/generate_testnet_config.sh`)
59+
- Creates `.testnet/testnet_config.toml` with network parameters
60+
61+
2. **Validator Key Generation**
62+
63+
```bash
64+
cargo run --bin malachitebft-eth-app -- testnet \
65+
--home nodes \
66+
--testnet-config .testnet/testnet_config.toml
67+
```
68+
69+
- Creates `nodes/0/`, `nodes/1/`, etc.
70+
- Each node gets a `config/priv_validator_key.json`
71+
72+
3. **Public Key Extraction**
73+
74+
```bash
75+
cargo run --bin malachitebft-eth-app show-pubkey \
76+
nodes/0/config/priv_validator_key.json
77+
```
78+
79+
- Outputs public keys to `nodes/validator_public_keys.txt`
80+
81+
4. **Genesis File Generation**
82+
83+
```bash
84+
cargo run --bin malachitebft-eth-utils genesis \
85+
--public-keys-file ./nodes/validator_public_keys.txt
86+
```
87+
88+
- Creates `assets/genesis.json` with:
89+
- Initial validator set (3 validators with power 100 each)
90+
- ValidatorManager contract deployed at genesis
91+
- Ethereum genesis block configuration
92+
93+
5. **Network Startup**
94+
- Docker Compose starts Reth execution clients
95+
- Each Reth node initializes from `assets/genesis.json`
96+
- Peer connections established
97+
- Malachite consensus nodes spawn and connect to Reth via Engine API
98+
99+
## Managing Validators with PoA Tools
100+
101+
Once the network is running, you can manage validators using the Rust-based PoA utilities.
102+
103+
### Prerequisites
104+
105+
- Network must be running (`make` or `make four`)
106+
- RPC endpoint accessible (default: `http://127.0.0.1:8545`)
107+
- Contract owner private key (mnemonic "test test test test test test test test test test test junk")
108+
109+
**notes: **
110+
111+
- `make` creates testnet validator keys under relative path `nodes/{0,1,2}/config/priv_validator_key.json`.
112+
- for local testnet the PoA contract owner private key is `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80` which corresponds to signer index 0 of the menomnic shown above.
113+
114+
### List Current Validators
115+
116+
View all registered validators and their voting power:
117+
118+
```bash
119+
cargo run --bin malachitebft-eth-utils poa list
120+
```
121+
122+
**Output:**
123+
124+
```
125+
Total validators: 3
126+
127+
Validator #1:
128+
Power: 100
129+
Pubkey: 04681eaaa34e491e6c8335abc9ea92b024ef52eb91442ca3b84598c79a79f31b75...
130+
Validator address: 0x1234567890abcdef...
131+
132+
Validator #2:
133+
Power: 100
134+
...
135+
```
136+
137+
### Add a New Validator
138+
139+
To add a new validator to the active set:
140+
141+
First get the pubkey of the validator you want to add by running:
142+
143+
```bash
144+
cargo run --bin malachitebft-eth-app show-pubkey \
145+
path/to/new/validator/priv_validator_key.json
146+
```
147+
148+
Then run the following command, replacing the placeholder values:
149+
150+
```bash
151+
cargo run --bin malachitebft-eth-utils poa add-validator \
152+
--validator-pubkey 0x04abcdef1234567890... \
153+
--power 100 \
154+
--owner-private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
155+
```
156+
157+
**Parameters:**
158+
159+
- `--validator-pubkey`: Uncompressed secp256k1 public key (65 bytes with `0x04` prefix, or 64 bytes raw)
160+
- `--power`: Voting weight (default: 100)
161+
- `--owner-private-key`: Private key of the ValidatorManager contract owner
162+
163+
**Optional flags:**
164+
165+
- `--rpc-url`: RPC endpoint (default: `http://127.0.0.1:8545`)
166+
- `--contract-address`: ValidatorManager address (default: `0x0000000000000000000000000000000000002000`)
167+
168+
### Remove a Validator
169+
170+
To remove a validator from the active set:
171+
172+
```bash
173+
cargo run --bin malachitebft-eth-utils poa remove-validator \
174+
--validator-pubkey 0x04681eaaa34e491e6c8335abc9ea92b024ef52eb91442ca3b84598c79a79f31b75... \
175+
--owner-private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
176+
```
177+
178+
### Update Validator Power
179+
180+
To change a validator's voting weight:
181+
182+
```bash
183+
cargo run --bin malachitebft-eth-utils poa update-validator \
184+
--validator-pubkey 0x04681eaaa34e491e6c8335abc9ea92b024ef52eb91442ca3b84598c79a79f31b75... \
185+
--power 200 \
186+
--owner-private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
187+
```
188+
189+
## Network Configuration
190+
191+
### Default Addresses
192+
193+
- **ValidatorManager Contract**: `0x0000000000000000000000000000000000002000`
194+
- **RPC Endpoints**:
195+
- Node 0: `http://127.0.0.1:8545`
196+
- Node 1: `http://127.0.0.1:8546`
197+
- Node 2: `http://127.0.0.1:8547`
198+
- Node 3 (if running): `http://127.0.0.1:8548`
199+
200+
### Genesis Validators
201+
202+
The genesis file is generated with 3 initial validators, each with power 100. Validator public keys are extracted from:
203+
204+
- `nodes/0/config/priv_validator_key.json`
205+
- `nodes/1/config/priv_validator_key.json`
206+
- `nodes/2/config/priv_validator_key.json`
207+
208+
## Network Operations
209+
210+
### Stop the Network
211+
212+
```bash
213+
make stop
214+
```
215+
216+
This stops all Docker containers but preserves data.
217+
218+
### Clean the Network
219+
220+
```bash
221+
make clean
222+
```
223+
224+
**Warning**: This deletes:
225+
226+
- All node data (`nodes/`)
227+
- Genesis file (`assets/genesis.json`)
228+
- Testnet config (`.testnet/`)
229+
- Docker volumes (Reth databases)
230+
- Prometheus/Grafana data
231+
232+
### Restart a Clean Network
233+
234+
```bash
235+
make clean
236+
make
237+
```
238+
239+
## Troubleshooting
240+
241+
### Network Won't Start
242+
243+
1. **Check if ports are in use**:
244+
245+
```bash
246+
lsof -i :8545 # RPC port
247+
lsof -i :30303 # P2P port
248+
```
249+
250+
2. **View Docker logs**:
251+
252+
```bash
253+
docker compose logs reth0
254+
docker compose logs reth1
255+
```
256+
257+
3. **Verify genesis file exists**:
258+
259+
```bash
260+
ls -la assets/genesis.json
261+
```
262+
263+
4. **Check emerald logs**:
264+
```bash
265+
tail -f nodes/0/emerald.log
266+
```
267+
268+
### Validator Operations Fail
269+
270+
1. **Verify network is running**:
271+
272+
```bash
273+
curl -X POST http://127.0.0.1:8545 \
274+
-H "Content-Type: application/json" \
275+
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
276+
```
277+
278+
2. **Check validator public key format**:
279+
- Must be hex-encoded secp256k1 public key
280+
- Can be 64 bytes (raw) or 65 bytes (with `0x04` prefix)
281+
- Include `0x` prefix
282+
283+
3. **Verify contract owner key**:
284+
- Default: `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`
285+
286+
### Public Key Extraction
287+
288+
To get a validator's public key from their private key file:
289+
290+
```bash
291+
cargo run --bin malachitebft-eth-app show-pubkey \
292+
nodes/0/config/priv_validator_key.json
293+
```
294+
295+
## Monitoring
296+
297+
The `make` command starts monitoring services:
298+
299+
- **Grafana**: http://localhost:3000 (metrics dashboards)
300+
- **Prometheus**: http://localhost:9090 (raw metrics)
301+
- **Otterscan**: http://localhost:5100 (block explorer)
302+
303+
## References
304+
305+
- [Main README](../../README.md) - Project overview and architecture
306+
- [Makefile](../../Makefile) - Build and deployment automation
307+
- [ValidatorManager.sol](../../solidity/src/ValidatorManager.sol) - Validator registry contract
308+
- [utils/src/poa.rs](../../utils/src/poa.rs) - PoA management utilities

0 commit comments

Comments
 (0)