Add voluntary exit via validator manager (#6612)

* #4303
* #4804


  -Add voluntary exit feature to the validator manager
-Add delete all validators by using the keyword "all"

Author: chong-he

Cargo.lock

@@ -28,6 +28,10 @@ Commands:
   delete
           Deletes one or more validators from a validator client using the HTTP
           API.
+  exit
+          Exits one or more validators using the HTTP API. It can also be used
+          to generate a presigned voluntary exit message for a particular future
+          epoch.
   help
           Print this message or the help of the given subcommand(s)
 

book/src/help_vm.md

@@ -32,4 +32,4 @@ The `validator-manager` boasts the following features:
 
 - [Creating and importing validators using the `create` and `import` commands.](./validator_manager_create.md)
 - [Moving validators between two VCs using the `move` command.](./validator_manager_move.md)
-- [Managing validators such as delete, import and list validators.](./validator_manager_api.md)
+- [Managing validators such as exit, delete, import and list validators.](./validator_manager_api.md)

book/src/validator_manager.md

@@ -2,6 +2,54 @@
 
 The `lighthouse validator-manager` uses the [Keymanager API](https://ethereum.github.io/keymanager-APIs/#/) to list, import and delete keystores via the HTTP API. This requires the validator client running with the flag `--http`. By default, the validator client HTTP address is `http://localhost:5062`. If a different IP address or port is used, add the flag `--vc-url http://IP:port_number` to the command below.
 
+## Exit
+
+The `exit` command exits one or more validators from the validator client. To `exit`:
+
+> **Important note: Once the --beacon-node flag is used, it will publish the voluntary exit to the network. This action is irreversible.**
+
+```bash
+lighthouse vm exit --vc-token <API-TOKEN-PATH> --validators pubkey1,pubkey2 --beacon-node http://beacon-node-url:5052
+```
+
+Example:
+
+```bash
+lighthouse vm exit --vc-token ~/.lighthouse/mainnet/validators/api-token.txt --validators 0x8885c29b8f88ee9b9a37b480fd4384fed74bda33d85bc8171a904847e65688b6c9bb4362d6597fd30109fb2def6c3ae4,0xa262dae3dcd2b2e280af534effa16bedb27c06f2959e114d53bd2a248ca324a018dc73179899a066149471a94a1bc92f --beacon-node http://localhost:5052
+```
+
+If successful, the following log will be returned:
+
+```text
+Successfully validated and published voluntary exit for validator 0x8885c29b8f88ee9b9a37b480fd4384fed74bda33d85bc8171a904847e65688b6c9bb4362d6597fd30109fb2def6c3ae4
+Successfully validated and published voluntary exit for validator
+0xa262dae3dcd2b2e280af534effa16bedb27c06f2959e114d53bd2a248ca324a018dc73179899a066149471a94a1bc92f
+```
+
+To exit all validators on the validator client, use the keyword `all`:
+
+```bash
+lighthouse vm exit --vc-token ~/.lighthouse/mainnet/validators/api-token.txt --validators all --beacon-node http://localhost:5052
+```
+
+To check the voluntary exit status, refer to [the list command](./validator_manager_api.md#list).
+
+The following command will only generate a presigned voluntary exit message and save it to a file named `{validator_pubkey}.json`. It **will not** publish the voluntary exit to the network.
+
+To generate a presigned exit message and save it to a file, use the flag `--presign`:
+
+```bash
+lighthouse vm exit --vc-token ~/.lighthouse/mainnet/validators/api-token.txt --validators all --presign
+```
+
+To generate a presigned exit message for a particular (future) epoch, use the flag `--exit-epoch`:
+
+```bash
+lighthouse vm exit --vc-token ~/.lighthouse/mainnet/validators/api-token.txt --validators all --presign --exit-epoch 1234567 
+```
+
+The generated presigned exit message will only be valid at or after the specified exit-epoch, in this case, epoch 1234567.
+
 ## Delete
 
 The `delete` command deletes one or more validators from the validator client. It will also modify the `validator_definitions.yml` file automatically so there is no manual action required from the user after the delete. To `delete`:
@@ -16,6 +64,12 @@ Example:
 lighthouse vm delete --vc-token ~/.lighthouse/mainnet/validators/api-token.txt --validators 0x8885c29b8f88ee9b9a37b480fd4384fed74bda33d85bc8171a904847e65688b6c9bb4362d6597fd30109fb2def6c3ae4,0xa262dae3dcd2b2e280af534effa16bedb27c06f2959e114d53bd2a248ca324a018dc73179899a066149471a94a1bc92f
 ```
 
+To delete all validators on the validator client, use the keyword `all`:
+
+```bash
+lighthouse vm delete --vc-token ~/.lighthouse/mainnet/validators/api-token.txt --validators all
+```
+
 ## Import
 
 The `import` command imports validator keystores generated by the `ethstaker-deposit-cli`. To import a validator keystore:
@@ -37,3 +91,26 @@ To list the validators running on the validator client:
 ```bash
 lighthouse vm list --vc-token ~/.lighthouse/mainnet/validators/api-token.txt
 ```
+
+The `list` command can also be used to check the voluntary exit status of validators. To do so, use both `--beacon-node` and `--validators` flags. The `--validators` flag accepts a comma-separated list of validator public keys, or the keyword `all` to check the voluntary exit status of all validators attached to the validator client.
+
+```bash
+lighthouse vm list --vc-token ~/.lighthouse/mainnet/validators/api-token.txt --validators 0x8de7ec501d574152f52a962bf588573df2fc3563fd0c6077651208ed20f24f3d8572425706b343117b48bdca56808416 --beacon-node http://localhost:5052
+```
+
+If the validator voluntary exit has been accepted by the chain, the following log will be returned:
+
+```text
+Voluntary exit for validator 0x8de7ec501d574152f52a962bf588573df2fc3563fd0c6077651208ed20f24f3d8572425706b343117b48bdca56808416 has been accepted into the beacon chain, but not yet finalized. Finalization may take several minutes or longer. Before finalization there is a low probability that the exit may be reverted.
+Current epoch: 2, Exit epoch: 7, Withdrawable epoch: 263
+Please keep your validator running till exit epoch
+Exit epoch in approximately 480 secs
+```
+
+When the exit epoch is reached, querying the status will return:
+
+```text
+Validator 0x8de7ec501d574152f52a962bf588573df2fc3563fd0c6077651208ed20f24f3d8572425706b343117b48bdca56808416 has exited at epoch: 7
+```
+
+You can safely shut down the validator client at this point.

book/src/validator_manager_api.md

@@ -10,6 +10,8 @@ A validator can initiate a voluntary exit provided that the validator is current
 It takes at a minimum 5 epochs (32 minutes) for a validator to exit after initiating a voluntary exit.
 This number can be much higher depending on how many other validators are queued to exit.
 
+You can also perform voluntary exit for one or more validators using the validator manager, see [Managing Validators](./validator_manager_api.md#exit) for more details.
+
 ## Initiating a voluntary exit
 
 In order to initiate an exit, users can use the `lighthouse account validator exit` command.

book/src/validator_voluntary_exit.md

@@ -10,6 +10,7 @@ use types::*;
 use validator_manager::{
     create_validators::CreateConfig,
     delete_validators::DeleteConfig,
+    exit_validators::ExitConfig,
     import_validators::ImportConfig,
     list_validators::ListConfig,
     move_validators::{MoveConfig, PasswordSource, Validators},
@@ -119,6 +120,12 @@ impl CommandLineTest<DeleteConfig> {
     }
 }
 
+impl CommandLineTest<ExitConfig> {
+    fn validators_exit() -> Self {
+        Self::default().flag("exit", None)
+    }
+}
+
 #[test]
 pub fn validator_create_without_output_path() {
     CommandLineTest::validators_create().assert_failed();
@@ -443,6 +450,8 @@ pub fn validator_list_defaults() {
             let expected = ListConfig {
                 vc_url: SensitiveUrl::parse("http://localhost:5062").unwrap(),
                 vc_token_path: PathBuf::from("./token.json"),
+                beacon_url: None,
+                validators_to_display: vec![],
             };
             assert_eq!(expected, config);
         });
@@ -468,3 +477,106 @@ pub fn validator_delete_defaults() {
             assert_eq!(expected, config);
         });
 }
+
+#[test]
+pub fn validator_delete_missing_validator_flag() {
+    CommandLineTest::validators_delete()
+        .flag("--vc-token", Some("./token.json"))
+        .assert_failed();
+}
+
+#[test]
+pub fn validator_exit_defaults() {
+    CommandLineTest::validators_exit()
+        .flag(
+            "--validators",
+            Some(&format!("{},{}", EXAMPLE_PUBKEY_0, EXAMPLE_PUBKEY_1)),
+        )
+        .flag("--vc-token", Some("./token.json"))
+        .flag("--beacon-node", Some("http://localhost:5052"))
+        .assert_success(|config| {
+            let expected = ExitConfig {
+                vc_url: SensitiveUrl::parse("http://localhost:5062").unwrap(),
+                vc_token_path: PathBuf::from("./token.json"),
+                validators_to_exit: vec![
+                    PublicKeyBytes::from_str(EXAMPLE_PUBKEY_0).unwrap(),
+                    PublicKeyBytes::from_str(EXAMPLE_PUBKEY_1).unwrap(),
+                ],
+                beacon_url: Some(SensitiveUrl::parse("http://localhost:5052").unwrap()),
+                exit_epoch: None,
+                presign: false,
+            };
+            assert_eq!(expected, config);
+        });
+}
+
+#[test]
+pub fn validator_exit_exit_epoch_and_presign_flags() {
+    CommandLineTest::validators_exit()
+        .flag(
+            "--validators",
+            Some(&format!("{},{}", EXAMPLE_PUBKEY_0, EXAMPLE_PUBKEY_1)),
+        )
+        .flag("--vc-token", Some("./token.json"))
+        .flag("--exit-epoch", Some("1234567"))
+        .flag("--presign", None)
+        .assert_success(|config| {
+            let expected = ExitConfig {
+                vc_url: SensitiveUrl::parse("http://localhost:5062").unwrap(),
+                vc_token_path: PathBuf::from("./token.json"),
+                validators_to_exit: vec![
+                    PublicKeyBytes::from_str(EXAMPLE_PUBKEY_0).unwrap(),
+                    PublicKeyBytes::from_str(EXAMPLE_PUBKEY_1).unwrap(),
+                ],
+                beacon_url: None,
+                exit_epoch: Some(Epoch::new(1234567)),
+                presign: true,
+            };
+            assert_eq!(expected, config);
+        });
+}
+
+#[test]
+pub fn validator_exit_missing_validator_flag() {
+    CommandLineTest::validators_exit()
+        .flag("--vc-token", Some("./token.json"))
+        .assert_failed();
+}
+
+#[test]
+pub fn validator_exit_using_beacon_and_presign_flags() {
+    CommandLineTest::validators_exit()
+        .flag("--vc-token", Some("./token.json"))
+        .flag(
+            "--validators",
+            Some(&format!("{},{}", EXAMPLE_PUBKEY_0, EXAMPLE_PUBKEY_1)),
+        )
+        .flag("--beacon-node", Some("http://localhost:1001"))
+        .flag("--presign", None)
+        .assert_failed();
+}
+
+#[test]
+pub fn validator_exit_using_beacon_and_exit_epoch_flags() {
+    CommandLineTest::validators_exit()
+        .flag("--vc-token", Some("./token.json"))
+        .flag(
+            "--validators",
+            Some(&format!("{},{}", EXAMPLE_PUBKEY_0, EXAMPLE_PUBKEY_1)),
+        )
+        .flag("--beacon-node", Some("http://localhost:1001"))
+        .flag("--exit-epoch", Some("1234567"))
+        .assert_failed();
+}
+
+#[test]
+pub fn validator_exit_exit_epoch_flag_without_presign_flag() {
+    CommandLineTest::validators_exit()
+        .flag("--vc-token", Some("./token.json"))
+        .flag(
+            "--validators",
+            Some(&format!("{},{}", EXAMPLE_PUBKEY_0, EXAMPLE_PUBKEY_1)),
+        )
+        .flag("--exit-epoch", Some("1234567"))
+        .assert_failed();
+}

lighthouse/tests/validator_manager.rs

@@ -26,6 +26,7 @@ use std::time::Duration;
 use task_executor::test_utils::TestRuntime;
 use tempfile::{tempdir, TempDir};
 use tokio::sync::oneshot;
+use types::ChainSpec;
 use validator_services::block_service::BlockService;
 use zeroize::Zeroizing;
 
@@ -61,6 +62,7 @@ pub struct ApiTester {
     pub _server_shutdown: oneshot::Sender<()>,
     pub validator_dir: TempDir,
     pub secrets_dir: TempDir,
+    pub spec: Arc<ChainSpec>,
 }
 
 impl ApiTester {
@@ -69,6 +71,19 @@ impl ApiTester {
     }
 
     pub async fn new_with_http_config(http_config: HttpConfig) -> Self {
+        let slot_clock =
+            TestingSlotClock::new(Slot::new(0), Duration::from_secs(0), Duration::from_secs(1));
+        let genesis_validators_root = Hash256::repeat_byte(42);
+        let spec = Arc::new(E::default_spec());
+        Self::new_with_options(http_config, slot_clock, genesis_validators_root, spec).await
+    }
+
+    pub async fn new_with_options(
+        http_config: HttpConfig,
+        slot_clock: TestingSlotClock,
+        genesis_validators_root: Hash256,
+        spec: Arc<ChainSpec>,
+    ) -> Self {
         let validator_dir = tempdir().unwrap();
         let secrets_dir = tempdir().unwrap();
         let token_path = tempdir().unwrap().path().join(PK_FILENAME);
@@ -91,20 +106,15 @@ impl ApiTester {
             ..Default::default()
         };
 
-        let spec = Arc::new(E::default_spec());
-
         let slashing_db_path = validator_dir.path().join(SLASHING_PROTECTION_FILENAME);
         let slashing_protection = SlashingDatabase::open_or_create(&slashing_db_path).unwrap();
 
-        let slot_clock =
-            TestingSlotClock::new(Slot::new(0), Duration::from_secs(0), Duration::from_secs(1));
-
         let test_runtime = TestRuntime::default();
 
         let validator_store = Arc::new(LighthouseValidatorStore::new(
             initialized_validators,
             slashing_protection,
-            Hash256::repeat_byte(42),
+            genesis_validators_root,
             spec.clone(),
             Some(Arc::new(DoppelgangerService::default())),
             slot_clock.clone(),
@@ -127,7 +137,7 @@ impl ApiTester {
             validator_store: Some(validator_store.clone()),
             graffiti_file: None,
             graffiti_flag: Some(Graffiti::default()),
-            spec,
+            spec: spec.clone(),
             config: http_config,
             sse_logging_components: None,
             slot_clock,
@@ -161,6 +171,7 @@ impl ApiTester {
             _server_shutdown: shutdown_tx,
             validator_dir,
             secrets_dir,
+            spec,
         }
     }
 

validator_client/http_api/src/test_utils.rs

@@ -17,12 +17,15 @@ ethereum_serde_utils = { workspace = true }
 hex = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
+slot_clock = { workspace = true }
 tokio = { workspace = true }
 tree_hash = { workspace = true }
 types = { workspace = true }
 zeroize = { workspace = true }
 
 [dev-dependencies]
+beacon_chain = { workspace = true }
+http_api = { workspace = true }
 regex = { workspace = true }
 tempfile = { workspace = true }
 validator_http_api = { workspace = true }