Skip to content

Commit b3108e6

Browse files
ch4r10t33rch4r10t33r
authored
Add checkpoint-sync-url and restart-client flags (blockblaz#116)
* feat: add isAggregator flag to validator configuration Add support for configuring nodes as aggregators through validator-config.yaml. This allows selective designation of nodes to perform aggregation duties by setting isAggregator: true in the validator configuration. Changes: - Add isAggregator field (default: false) to all validators in both local and ansible configs - Update parse-vc.sh to extract and export isAggregator flag - Modify all client command scripts to pass --is-aggregator flag when enabled - Add isAggregator status to node information output * Add checkpoint-sync-url and restart-client flags for all clients * Add log clarifying --restart-client requires --checkpoint-sync-url * Update default checkpoint-sync-url to include /lean/v0/states/finalized path * Fix Ansible recursion error for --restart-client with ansible deployment - Pass restart nodes (spin_nodes) to run-ansible.sh when using --restart-client - Remove recursive node_names definition in site.yml that caused max recursion depth - Add skip_genesis support for checkpoint-sync restarts (skip genesis generation) * Expand checkpoint sync documentation in README
1 parent db058b9 commit b3108e6

15 files changed

Lines changed: 270 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,44 @@ Grafana is started with the two pre-provisioned dashboards from [leanMetrics](ht
139139
- On Ctrl+C cleanup, the metrics stack is stopped automatically
140140

141141
Note: Client metrics endpoints are always enabled regardless of this flag.
142+
12. `--checkpoint-sync-url` specifies the URL to fetch finalized checkpoint state from for checkpoint sync. Default: `https://leanpoint.leanroadmap.org/lean/v0/states/finalized`. Only used when `--restart-client` is specified.
143+
13. `--restart-client` comma-separated list of client node names (e.g., `zeam_0,ream_0`). When specified, those clients are stopped, their data cleared, and restarted using checkpoint sync. Genesis is skipped. Use with `--checkpoint-sync-url` to override the default URL.
144+
145+
### Checkpoint sync
146+
147+
Checkpoint sync lets you restart clients by syncing from a remote checkpoint instead of from genesis. This is useful for joining an existing network (e.g., leanpoint mainnet) without replaying the full chain.
148+
149+
**Basic usage:**
150+
151+
```sh
152+
# Restart zeam_0 using the default checkpoint URL
153+
NETWORK_DIR=local-devnet ./spin-node.sh --restart-client zeam_0
154+
155+
# Restart multiple clients
156+
NETWORK_DIR=local-devnet ./spin-node.sh --restart-client zeam_0,ream_0
157+
```
158+
159+
**Custom checkpoint URL:**
160+
161+
```sh
162+
NETWORK_DIR=local-devnet ./spin-node.sh --restart-client zeam_0 \
163+
--checkpoint-sync-url https://leanpoint.leanroadmap.org/lean/v0/states/finalized
164+
```
165+
166+
**Default checkpoint URL:** `https://leanpoint.leanroadmap.org/lean/v0/states/finalized`
167+
168+
**What happens:**
169+
1. Existing containers for the specified clients are stopped (no error if already stopped)
170+
2. Data directories are cleared
171+
3. Clients are started with `--checkpoint-sync-url` so they sync from the remote checkpoint instead of genesis
172+
173+
**Deployment modes:**
174+
- **Local** (`NETWORK_DIR=local-devnet`): Uses Docker directly
175+
- **Ansible** (`NETWORK_DIR=ansible-devnet`): Uses Ansible to deploy to remote hosts
176+
177+
**Supported clients:** zeam, ream, qlean, lantern, lighthouse, grandine, ethlambda
178+
179+
> **Note:** All clients accept `--checkpoint-sync-url`. Client implementations may use different parameter names internally; update client-cmd scripts if parameters change.
142180
143181
### Clients supported
144182

‎ansible-devnet/genesis/validator-config.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ validators:
1414
ip: "46.224.123.223"
1515
quic: 9001
1616
metricsPort: 9095
17+
isAggregator: false
1718
count: 1 # number of indices for this node
1819

1920
- name: "ream_0"
@@ -25,6 +26,7 @@ validators:
2526
ip: "77.42.27.219"
2627
quic: 9001
2728
metricsPort: 9095
29+
isAggregator: false
2830
devnet: 1
2931
count: 1
3032

@@ -36,6 +38,7 @@ validators:
3638
ip: "46.224.123.220"
3739
quic: 9001
3840
metricsPort: 9095
41+
isAggregator: false
3942
count: 1
4043

4144
- name: "lantern_0"
@@ -47,6 +50,7 @@ validators:
4750
ip: "46.224.135.177"
4851
quic: 9001
4952
metricsPort: 9095
53+
isAggregator: false
5054
count: 1
5155

5256
- name: "lighthouse_0"
@@ -58,6 +62,7 @@ validators:
5862
ip: "46.224.135.169"
5963
quic: 9001
6064
metricsPort: 9095
65+
isAggregator: false
6166
count: 1
6267

6368
- name: "grandine_0"
@@ -66,6 +71,7 @@ validators:
6671
ip: "37.27.250.20"
6772
quic: 9001
6873
metricsPort: 9095
74+
isAggregator: false
6975
count: 1
7076

7177
- name: "ethlambda_0"
@@ -74,4 +80,5 @@ validators:
7480
ip: "78.47.44.215"
7581
quic: 9001
7682
metricsPort: 9095
83+
isAggregator: false
7784
count: 1

‎ansible/playbooks/site.yml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,6 @@
2222
import_playbook: clean-node-data.yml
2323
vars:
2424
genesis_dir: "{{ network_dir }}/genesis"
25-
node_names: "{{ node_names }}"
2625
when: clean_data | default(false) | bool
2726

2827
- name: Generate Genesis Files
@@ -40,5 +39,4 @@
4039
- name: Deploy Nodes
4140
import_playbook: deploy-nodes.yml
4241
vars:
43-
node_names: "{{ node_names }}"
4442
skip_role_cleaning: "{{ clean_data | default(false) | bool }}"

‎client-cmds/ethlambda-cmd.sh‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,28 @@
44

55
binary_path="$scriptDir/../ethlambda/target/release/ethlambda"
66

7+
# Set aggregator flag based on isAggregator value
8+
aggregator_flag=""
9+
if [ "$isAggregator" == "true" ]; then
10+
aggregator_flag="--is-aggregator"
11+
fi
12+
13+
# Set checkpoint sync URL when restarting with checkpoint sync
14+
checkpoint_sync_flag=""
15+
if [ -n "${checkpoint_sync_url:-}" ]; then
16+
checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
17+
fi
18+
719
# Command when running as binary
820
node_binary="$binary_path \
921
--custom-network-config-dir $configDir \
1022
--gossipsub-port $quicPort \
1123
--node-id $item \
1224
--node-key $configDir/$item.key \
1325
--metrics-address 0.0.0.0 \
14-
--metrics-port $metricsPort"
26+
--metrics-port $metricsPort \
27+
$aggregator_flag \
28+
$checkpoint_sync_flag"
1529

1630
# Command when running as docker container
1731
node_docker="ghcr.io/lambdaclass/ethlambda:devnet2 \
@@ -20,6 +34,8 @@ node_docker="ghcr.io/lambdaclass/ethlambda:devnet2 \
2034
--node-id $item \
2135
--node-key /config/$item.key \
2236
--metrics-address 0.0.0.0 \
23-
--metrics-port $metricsPort"
37+
--metrics-port $metricsPort \
38+
$aggregator_flag \
39+
$checkpoint_sync_flag"
2440

2541
node_setup="docker"

‎client-cmds/grandine-cmd.sh‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
#!/bin/bash
22

3+
# Set aggregator flag based on isAggregator value
4+
aggregator_flag=""
5+
if [ "$isAggregator" == "true" ]; then
6+
aggregator_flag="--is-aggregator"
7+
fi
8+
9+
# Set checkpoint sync URL when restarting with checkpoint sync
10+
checkpoint_sync_flag=""
11+
if [ -n "${checkpoint_sync_url:-}" ]; then
12+
checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
13+
fi
14+
315
node_binary="$grandine_bin \
416
--genesis $configDir/config.yaml \
517
--validator-registry-path $configDir/validators.yaml \
@@ -11,7 +23,9 @@ node_binary="$grandine_bin \
1123
--metrics \
1224
--http-address 0.0.0.0 \
1325
--http-port $metricsPort \
14-
--hash-sig-key-dir $configDir/hash-sig-keys"
26+
--hash-sig-key-dir $configDir/hash-sig-keys \
27+
$aggregator_flag \
28+
$checkpoint_sync_flag"
1529

1630
node_docker="sifrai/lean:devnet-2 \
1731
--genesis /config/config.yaml \
@@ -24,7 +38,9 @@ node_docker="sifrai/lean:devnet-2 \
2438
--metrics \
2539
--http-address 0.0.0.0 \
2640
--http-port $metricsPort \
27-
--hash-sig-key-dir /config/hash-sig-keys"
41+
--hash-sig-key-dir /config/hash-sig-keys \
42+
$aggregator_flag \
43+
$checkpoint_sync_flag"
2844

2945
# choose either binary or docker
3046
node_setup="docker"

‎client-cmds/lantern-cmd.sh‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,18 @@ if [ -n "$devnet" ]; then
88
devnet_flag="--devnet $devnet"
99
fi
1010

11+
# Set aggregator flag based on isAggregator value
12+
aggregator_flag=""
13+
if [ "$isAggregator" == "true" ]; then
14+
aggregator_flag="--is-aggregator"
15+
fi
16+
17+
# Set checkpoint sync URL when restarting with checkpoint sync
18+
checkpoint_sync_flag=""
19+
if [ -n "${checkpoint_sync_url:-}" ]; then
20+
checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
21+
fi
22+
1123
# Lantern's repo: https://github.com/Pier-Two/lantern
1224
node_binary="$scriptDir/lantern/build/lantern_cli \
1325
--data-dir $dataDir/$item \
@@ -22,7 +34,9 @@ node_binary="$scriptDir/lantern/build/lantern_cli \
2234
--metrics-port $metricsPort \
2335
--http-port 5055 \
2436
--log-level debug \
25-
--hash-sig-key-dir $configDir/hash-sig-keys"
37+
--hash-sig-key-dir $configDir/hash-sig-keys \
38+
$aggregator_flag \
39+
$checkpoint_sync_flag"
2640

2741
node_docker="$LANTERN_IMAGE --data-dir /data \
2842
--genesis-config /config/config.yaml \
@@ -36,7 +50,9 @@ node_docker="$LANTERN_IMAGE --data-dir /data \
3650
--metrics-port $metricsPort \
3751
--http-port 5055 \
3852
--log-level debug \
39-
--hash-sig-key-dir /config/hash-sig-keys"
53+
--hash-sig-key-dir /config/hash-sig-keys \
54+
$aggregator_flag \
55+
$checkpoint_sync_flag"
4056

4157
# choose either binary or docker
4258
node_setup="docker"

‎client-cmds/lighthouse-cmd.sh‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,18 @@
33
# Metrics enabled by default
44
metrics_flag="--metrics"
55

6+
# Set aggregator flag based on isAggregator value
7+
aggregator_flag=""
8+
if [ "$isAggregator" == "true" ]; then
9+
aggregator_flag="--is-aggregator"
10+
fi
11+
12+
# Set checkpoint sync URL when restarting with checkpoint sync
13+
checkpoint_sync_flag=""
14+
if [ -n "${checkpoint_sync_url:-}" ]; then
15+
checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
16+
fi
17+
618
node_binary="$lighthouse_bin lean_node \
719
--datadir \"$dataDir/$item\" \
820
--config \"$configDir/config.yaml\" \
@@ -14,7 +26,9 @@ node_binary="$lighthouse_bin lean_node \
1426
--socket-port $quicPort\
1527
$metrics_flag \
1628
--metrics-address 0.0.0.0 \
17-
--metrics-port $metricsPort"
29+
--metrics-port $metricsPort \
30+
$aggregator_flag \
31+
$checkpoint_sync_flag"
1832

1933
node_docker="hopinheimer/lighthouse:latest lighthouse lean_node \
2034
--datadir /data \
@@ -27,6 +41,8 @@ node_docker="hopinheimer/lighthouse:latest lighthouse lean_node \
2741
--socket-port $quicPort\
2842
$metrics_flag \
2943
--metrics-address 0.0.0.0 \
30-
--metrics-port $metricsPort"
44+
--metrics-port $metricsPort \
45+
$aggregator_flag \
46+
$checkpoint_sync_flag"
3147

3248
node_setup="docker"

‎client-cmds/qlean-cmd.sh‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,19 @@
33
#-----------------------qlean setup----------------------
44
# expects "qlean" submodule or symlink inside "lean-quickstart" root directory
55
# https://github.com/qdrvm/qlean-mini
6+
7+
# Set aggregator flag based on isAggregator value
8+
aggregator_flag=""
9+
if [ "$isAggregator" == "true" ]; then
10+
aggregator_flag="--is-aggregator"
11+
fi
12+
13+
# Set checkpoint sync URL when restarting with checkpoint sync
14+
checkpoint_sync_flag=""
15+
if [ -n "${checkpoint_sync_url:-}" ]; then
16+
checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
17+
fi
18+
619
node_binary="$scriptDir/qlean/build/src/executable/qlean \
720
--modules-dir $scriptDir/qlean/build/src/modules \
821
--genesis $configDir/config.yaml \
@@ -15,6 +28,8 @@ node_binary="$scriptDir/qlean/build/src/executable/qlean \
1528
--node-id $item --node-key $configDir/$privKeyPath \
1629
--listen-addr /ip4/0.0.0.0/udp/$quicPort/quic-v1 \
1730
--prometheus-port $metricsPort \
31+
$aggregator_flag \
32+
$checkpoint_sync_flag \
1833
-ldebug \
1934
-ltrace"
2035

@@ -29,6 +44,8 @@ node_docker="qdrvm/qlean-mini:devnet-2 \
2944
--node-id $item --node-key /config/$privKeyPath \
3045
--listen-addr /ip4/0.0.0.0/udp/$quicPort/quic-v1 \
3146
--prometheus-port $metricsPort \
47+
$aggregator_flag \
48+
$checkpoint_sync_flag \
3249
-ldebug \
3350
-ltrace"
3451

‎client-cmds/ream-cmd.sh‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,18 @@
44
# Metrics enabled by default
55
metrics_flag="--metrics"
66

7+
# Set aggregator flag based on isAggregator value
8+
aggregator_flag=""
9+
if [ "$isAggregator" == "true" ]; then
10+
aggregator_flag="--is-aggregator"
11+
fi
12+
13+
# Set checkpoint sync URL when restarting with checkpoint sync
14+
checkpoint_sync_flag=""
15+
if [ -n "${checkpoint_sync_url:-}" ]; then
16+
checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
17+
fi
18+
719
# modify the path to the ream binary as per your system
820
node_binary="$scriptDir/../ream/target/release/ream --data-dir $dataDir/$item \
921
lean_node \
@@ -15,7 +27,9 @@ node_binary="$scriptDir/../ream/target/release/ream --data-dir $dataDir/$item \
1527
$metrics_flag \
1628
--metrics-address 0.0.0.0 \
1729
--metrics-port $metricsPort \
18-
--http-address 0.0.0.0"
30+
--http-address 0.0.0.0 \
31+
$aggregator_flag \
32+
$checkpoint_sync_flag"
1933

2034
node_docker="ghcr.io/reamlabs/ream:latest-devnet2 --data-dir /data \
2135
lean_node \
@@ -27,7 +41,9 @@ node_docker="ghcr.io/reamlabs/ream:latest-devnet2 --data-dir /data \
2741
$metrics_flag \
2842
--metrics-address 0.0.0.0 \
2943
--metrics-port $metricsPort \
30-
--http-address 0.0.0.0"
44+
--http-address 0.0.0.0 \
45+
$aggregator_flag \
46+
$checkpoint_sync_flag"
3147

3248
# choose either binary or docker
3349
node_setup="docker"

‎client-cmds/zeam-cmd.sh‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,37 @@
66
# Metrics enabled by default
77
metrics_flag="--metrics_enable"
88

9+
# Set aggregator flag based on isAggregator value
10+
aggregator_flag=""
11+
if [ "$isAggregator" == "true" ]; then
12+
aggregator_flag="--is-aggregator"
13+
fi
14+
15+
# Set checkpoint sync URL when restarting with checkpoint sync
16+
checkpoint_sync_flag=""
17+
if [ -n "${checkpoint_sync_url:-}" ]; then
18+
checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
19+
fi
20+
921
node_binary="$scriptDir/../zig-out/bin/zeam node \
1022
--custom_genesis $configDir \
1123
--validator_config $validatorConfig \
1224
--data-dir $dataDir/$item \
1325
--node-id $item --node-key $configDir/$item.key \
1426
$metrics_flag \
15-
--api-port $metricsPort"
27+
--api-port $metricsPort \
28+
$aggregator_flag \
29+
$checkpoint_sync_flag"
1630

1731
node_docker="--security-opt seccomp=unconfined blockblaz/zeam:devnet2 node \
1832
--custom_genesis /config \
1933
--validator_config $validatorConfig \
2034
--data-dir /data \
2135
--node-id $item --node-key /config/$item.key \
2236
$metrics_flag \
23-
--api-port $metricsPort"
37+
--api-port $metricsPort \
38+
$aggregator_flag \
39+
$checkpoint_sync_flag"
2440

2541
# choose either binary or docker
2642
node_setup="docker"

0 commit comments

Comments
 (0)