Add checkpoint-sync-url and restart-client flags

README.md

@@ -139,6 +139,44 @@ Grafana is started with the two pre-provisioned dashboards from [leanMetrics](ht
     - On Ctrl+C cleanup, the metrics stack is stopped automatically
 
     Note: Client metrics endpoints are always enabled regardless of this flag.
+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.
+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.
+
+### Checkpoint sync
+
+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.
+
+**Basic usage:**
+
+```sh
+# Restart zeam_0 using the default checkpoint URL
+NETWORK_DIR=local-devnet ./spin-node.sh --restart-client zeam_0
+
+# Restart multiple clients
+NETWORK_DIR=local-devnet ./spin-node.sh --restart-client zeam_0,ream_0
+```
+
+**Custom checkpoint URL:**
+
+```sh
+NETWORK_DIR=local-devnet ./spin-node.sh --restart-client zeam_0 \
+  --checkpoint-sync-url https://leanpoint.leanroadmap.org/lean/v0/states/finalized
+```
+
+**Default checkpoint URL:** `https://leanpoint.leanroadmap.org/lean/v0/states/finalized`
+
+**What happens:**
+1. Existing containers for the specified clients are stopped (no error if already stopped)
+2. Data directories are cleared
+3. Clients are started with `--checkpoint-sync-url` so they sync from the remote checkpoint instead of genesis
+
+**Deployment modes:**
+- **Local** (`NETWORK_DIR=local-devnet`): Uses Docker directly
+- **Ansible** (`NETWORK_DIR=ansible-devnet`): Uses Ansible to deploy to remote hosts
+
+**Supported clients:** zeam, ream, qlean, lantern, lighthouse, grandine, ethlambda
+
+> **Note:** All clients accept `--checkpoint-sync-url`. Client implementations may use different parameter names internally; update client-cmd scripts if parameters change.
 
 ### Clients supported
 

ansible-devnet/genesis/validator-config.yaml

@@ -14,6 +14,7 @@ validators:
       ip: "46.224.123.223"
       quic: 9001
     metricsPort: 9095
+    isAggregator: false
     count: 1 # number of indices for this node
 
   - name: "ream_0"
@@ -25,6 +26,7 @@ validators:
       ip: "77.42.27.219"
       quic: 9001
     metricsPort: 9095
+    isAggregator: false
     devnet: 1
     count: 1
 
@@ -36,6 +38,7 @@ validators:
       ip: "46.224.123.220"
       quic: 9001
     metricsPort: 9095
+    isAggregator: false
     count: 1
 
   - name: "lantern_0"
@@ -47,6 +50,7 @@ validators:
       ip: "46.224.135.177"
       quic: 9001
     metricsPort: 9095
+    isAggregator: false
     count: 1
 
   - name: "lighthouse_0"
@@ -58,6 +62,7 @@ validators:
       ip: "46.224.135.169"
       quic: 9001
     metricsPort: 9095
+    isAggregator: false
     count: 1
 
   - name: "grandine_0"
@@ -66,6 +71,7 @@ validators:
       ip: "37.27.250.20"
       quic: 9001
     metricsPort: 9095
+    isAggregator: false
     count: 1
 
   - name: "ethlambda_0"
@@ -74,4 +80,5 @@ validators:
       ip: "78.47.44.215"
       quic: 9001
     metricsPort: 9095
+    isAggregator: false
     count: 1

ansible/playbooks/site.yml

@@ -22,7 +22,6 @@
   import_playbook: clean-node-data.yml
   vars:
     genesis_dir: "{{ network_dir }}/genesis"
-    node_names: "{{ node_names }}"
   when: clean_data | default(false) | bool
 
 - name: Generate Genesis Files
@@ -40,5 +39,4 @@
 - name: Deploy Nodes
   import_playbook: deploy-nodes.yml
   vars:
-    node_names: "{{ node_names }}"
     skip_role_cleaning: "{{ clean_data | default(false) | bool }}"

client-cmds/ethlambda-cmd.sh

@@ -4,14 +4,28 @@
 
 binary_path="$scriptDir/../ethlambda/target/release/ethlambda"
 
+# Set aggregator flag based on isAggregator value
+aggregator_flag=""
+if [ "$isAggregator" == "true" ]; then
+    aggregator_flag="--is-aggregator"
+fi
+
+# Set checkpoint sync URL when restarting with checkpoint sync
+checkpoint_sync_flag=""
+if [ -n "${checkpoint_sync_url:-}" ]; then
+    checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
+fi
+
 # Command when running as binary
 node_binary="$binary_path \
       --custom-network-config-dir $configDir \
       --gossipsub-port $quicPort \
       --node-id $item \
       --node-key $configDir/$item.key \
       --metrics-address 0.0.0.0 \
-      --metrics-port $metricsPort"
+      --metrics-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag"
 
 # Command when running as docker container
 node_docker="ghcr.io/lambdaclass/ethlambda:devnet2 \
@@ -20,6 +34,8 @@ node_docker="ghcr.io/lambdaclass/ethlambda:devnet2 \
       --node-id $item \
       --node-key /config/$item.key \
       --metrics-address 0.0.0.0 \
-      --metrics-port $metricsPort"
+      --metrics-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag"
 
 node_setup="docker"

client-cmds/grandine-cmd.sh

@@ -1,5 +1,17 @@
 #!/bin/bash
 
+# Set aggregator flag based on isAggregator value
+aggregator_flag=""
+if [ "$isAggregator" == "true" ]; then
+    aggregator_flag="--is-aggregator"
+fi
+
+# Set checkpoint sync URL when restarting with checkpoint sync
+checkpoint_sync_flag=""
+if [ -n "${checkpoint_sync_url:-}" ]; then
+    checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
+fi
+
 node_binary="$grandine_bin \
         --genesis $configDir/config.yaml \
         --validator-registry-path $configDir/validators.yaml \
@@ -11,7 +23,9 @@ node_binary="$grandine_bin \
         --metrics \
         --http-address 0.0.0.0 \
         --http-port $metricsPort \
-        --hash-sig-key-dir $configDir/hash-sig-keys"
+        --hash-sig-key-dir $configDir/hash-sig-keys \
+        $aggregator_flag \
+        $checkpoint_sync_flag"
 
 node_docker="sifrai/lean:devnet-2 \
         --genesis /config/config.yaml \
@@ -24,7 +38,9 @@ node_docker="sifrai/lean:devnet-2 \
         --metrics \
         --http-address 0.0.0.0 \
         --http-port $metricsPort \
-        --hash-sig-key-dir /config/hash-sig-keys"
+        --hash-sig-key-dir /config/hash-sig-keys \
+        $aggregator_flag \
+        $checkpoint_sync_flag"
 
 # choose either binary or docker
 node_setup="docker"

client-cmds/lantern-cmd.sh

@@ -8,6 +8,18 @@ if [ -n "$devnet" ]; then
         devnet_flag="--devnet $devnet"
 fi
 
+# Set aggregator flag based on isAggregator value
+aggregator_flag=""
+if [ "$isAggregator" == "true" ]; then
+    aggregator_flag="--is-aggregator"
+fi
+
+# Set checkpoint sync URL when restarting with checkpoint sync
+checkpoint_sync_flag=""
+if [ -n "${checkpoint_sync_url:-}" ]; then
+    checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
+fi
+
 # Lantern's repo: https://github.com/Pier-Two/lantern
 node_binary="$scriptDir/lantern/build/lantern_cli \
         --data-dir $dataDir/$item \
@@ -22,7 +34,9 @@ node_binary="$scriptDir/lantern/build/lantern_cli \
         --metrics-port $metricsPort \
         --http-port 5055 \
         --log-level debug \
-        --hash-sig-key-dir $configDir/hash-sig-keys"
+        --hash-sig-key-dir $configDir/hash-sig-keys \
+        $aggregator_flag \
+        $checkpoint_sync_flag"
 
 node_docker="$LANTERN_IMAGE --data-dir /data \
         --genesis-config /config/config.yaml \
@@ -36,7 +50,9 @@ node_docker="$LANTERN_IMAGE --data-dir /data \
         --metrics-port $metricsPort \
         --http-port 5055 \
         --log-level debug \
-        --hash-sig-key-dir /config/hash-sig-keys"
+        --hash-sig-key-dir /config/hash-sig-keys \
+        $aggregator_flag \
+        $checkpoint_sync_flag"
 
 # choose either binary or docker
 node_setup="docker"

client-cmds/lighthouse-cmd.sh

@@ -3,6 +3,18 @@
 # Metrics enabled by default
 metrics_flag="--metrics"
 
+# Set aggregator flag based on isAggregator value
+aggregator_flag=""
+if [ "$isAggregator" == "true" ]; then
+    aggregator_flag="--is-aggregator"
+fi
+
+# Set checkpoint sync URL when restarting with checkpoint sync
+checkpoint_sync_flag=""
+if [ -n "${checkpoint_sync_url:-}" ]; then
+    checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
+fi
+
 node_binary="$lighthouse_bin lean_node \
       --datadir \"$dataDir/$item\" \
       --config \"$configDir/config.yaml\" \
@@ -14,7 +26,9 @@ node_binary="$lighthouse_bin lean_node \
       --socket-port $quicPort\
       $metrics_flag \
       --metrics-address 0.0.0.0 \
-      --metrics-port $metricsPort"
+      --metrics-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag"
 
 node_docker="hopinheimer/lighthouse:latest lighthouse lean_node \
       --datadir /data \
@@ -27,6 +41,8 @@ node_docker="hopinheimer/lighthouse:latest lighthouse lean_node \
       --socket-port $quicPort\
       $metrics_flag \
       --metrics-address 0.0.0.0 \
-      --metrics-port $metricsPort"
+      --metrics-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag"
 
 node_setup="docker"

client-cmds/qlean-cmd.sh

@@ -3,6 +3,19 @@
 #-----------------------qlean setup----------------------
 # expects "qlean" submodule or symlink inside "lean-quickstart" root directory
 # https://github.com/qdrvm/qlean-mini
+
+# Set aggregator flag based on isAggregator value
+aggregator_flag=""
+if [ "$isAggregator" == "true" ]; then
+    aggregator_flag="--is-aggregator"
+fi
+
+# Set checkpoint sync URL when restarting with checkpoint sync
+checkpoint_sync_flag=""
+if [ -n "${checkpoint_sync_url:-}" ]; then
+    checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
+fi
+
 node_binary="$scriptDir/qlean/build/src/executable/qlean \
       --modules-dir $scriptDir/qlean/build/src/modules \
       --genesis $configDir/config.yaml \
@@ -15,6 +28,8 @@ node_binary="$scriptDir/qlean/build/src/executable/qlean \
       --node-id $item --node-key $configDir/$privKeyPath \
       --listen-addr /ip4/0.0.0.0/udp/$quicPort/quic-v1 \
       --prometheus-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag \
       -ldebug \
       -ltrace"
 
@@ -29,6 +44,8 @@ node_docker="qdrvm/qlean-mini:devnet-2 \
       --node-id $item --node-key /config/$privKeyPath \
       --listen-addr /ip4/0.0.0.0/udp/$quicPort/quic-v1 \
       --prometheus-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag \
       -ldebug \
       -ltrace"
 

client-cmds/ream-cmd.sh

@@ -4,6 +4,18 @@
 # Metrics enabled by default
 metrics_flag="--metrics"
 
+# Set aggregator flag based on isAggregator value
+aggregator_flag=""
+if [ "$isAggregator" == "true" ]; then
+    aggregator_flag="--is-aggregator"
+fi
+
+# Set checkpoint sync URL when restarting with checkpoint sync
+checkpoint_sync_flag=""
+if [ -n "${checkpoint_sync_url:-}" ]; then
+    checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
+fi
+
 # modify the path to the ream binary as per your system
 node_binary="$scriptDir/../ream/target/release/ream --data-dir $dataDir/$item \
         lean_node \
@@ -15,7 +27,9 @@ node_binary="$scriptDir/../ream/target/release/ream --data-dir $dataDir/$item \
         $metrics_flag \
         --metrics-address 0.0.0.0 \
         --metrics-port $metricsPort \
-        --http-address 0.0.0.0"
+        --http-address 0.0.0.0 \
+        $aggregator_flag \
+        $checkpoint_sync_flag"
 
 node_docker="ghcr.io/reamlabs/ream:latest-devnet2 --data-dir /data \
         lean_node \
@@ -27,7 +41,9 @@ node_docker="ghcr.io/reamlabs/ream:latest-devnet2 --data-dir /data \
         $metrics_flag \
         --metrics-address 0.0.0.0 \
         --metrics-port $metricsPort \
-        --http-address 0.0.0.0"
+        --http-address 0.0.0.0 \
+        $aggregator_flag \
+        $checkpoint_sync_flag"
 
 # choose either binary or docker
 node_setup="docker"

client-cmds/zeam-cmd.sh

@@ -6,21 +6,37 @@
 # Metrics enabled by default
 metrics_flag="--metrics_enable"
 
+# Set aggregator flag based on isAggregator value
+aggregator_flag=""
+if [ "$isAggregator" == "true" ]; then
+    aggregator_flag="--is-aggregator"
+fi
+
+# Set checkpoint sync URL when restarting with checkpoint sync
+checkpoint_sync_flag=""
+if [ -n "${checkpoint_sync_url:-}" ]; then
+    checkpoint_sync_flag="--checkpoint-sync-url $checkpoint_sync_url"
+fi
+
 node_binary="$scriptDir/../zig-out/bin/zeam node \
       --custom_genesis $configDir \
       --validator_config $validatorConfig \
       --data-dir $dataDir/$item \
       --node-id $item --node-key $configDir/$item.key \
       $metrics_flag \
-      --api-port $metricsPort"
+      --api-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag"
 
 node_docker="--security-opt seccomp=unconfined blockblaz/zeam:devnet2 node \
       --custom_genesis /config \
       --validator_config $validatorConfig \
       --data-dir /data \
       --node-id $item --node-key /config/$item.key \
       $metrics_flag \
-      --api-port $metricsPort"
+      --api-port $metricsPort \
+      $aggregator_flag \
+      $checkpoint_sync_flag"
 
 # choose either binary or docker
 node_setup="docker"