Add voluntary exit content (#220)

* Add CLI option to disable built-in slashing protection for external signers. Signed-off-by: Byron Gravenorst <[email protected]> * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst <[email protected]> * updating submodule to latest * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst <[email protected]> * Fix markdown issue. Signed-off-by: Byron Gravenorst <[email protected]> * Add voluntary exit content. Signed-off-by: Byron Gravenorst <[email protected]> * Add voluntary exit content. Signed-off-by: Byron Gravenorst <[email protected]> * fix linter issue. Signed-off-by: Byron Gravenorst <[email protected]> * Update epoch information and add confirmation-enabled option. Signed-off-by: Byron Gravenorst <[email protected]> * Fix word usage. Signed-off-by: Byron Gravenorst <[email protected]> * Address reviewer feedback. Signed-off-by: Byron Gravenorst <[email protected]> * Address reviewer feedback. Signed-off-by: Byron Gravenorst <[email protected]>
Consensys · Dec 6, 2020 · 9612d7a · 9612d7a
1 parent 74a2f81
commit 9612d7a
Show file tree

Hide file tree

Showing 5 changed files with 316 additions and 2 deletions.
diff --git a/docs/HowTo/Get-Started/Run-Teku.md b/docs/HowTo/Get-Started/Run-Teku.md
@@ -19,7 +19,7 @@ on the same machine.
 
     By default, Teku connects to `mainnet`. Use the [`--network`](../../Reference/CLI/CLI-Syntax.md#network)
     command line option to specify an alternate network.
-    
+
     If the genesis state of a network is not yet known, then
     include the [`--eth1-endpoint`](../../Reference/CLI/CLI-Syntax.md#eth1-endpoint) command line
     option.

diff --git a/docs/HowTo/Voluntary-Exit.md b/docs/HowTo/Voluntary-Exit.md
@@ -0,0 +1,58 @@
+---
+title: Voluntarily exit a validaor
+---
+
+# Voluntarily exit a validator
+
+A voluntary exit is when a validator chooses to stop performing its duties, and exits the beacon
+chain.
+
+To voluntarily exit, the validator must continue performing its validator duties until successfully
+exited to avoid penalties.
+
+!!! important
+
+    Even if a validator has successfully exited, you cannot withdraw your funds until withdrawals are
+    enabled in a future phase of the Ethereum 2.0 network.
+
+## Initiate a voluntary exit
+
+Use the [`voluntary-exit`](../Reference/CLI/Subcommands/Voluntary-Exit.md) subcommand to initiate
+a voluntary exit for specified validators.
+
+!!! example
+
+    ```bash
+    teku voluntary-exit --beacon-node-api-endpoint=http://10.32.100.1:5051 \
+    --validator-keys=validator/keys/validator_888eef.json:validator/passwords/validator_888eef.txt \
+    --epoch=24500
+    ```
+
+In the command:
+
+* Specify the location of the beacon node using
+    [`--beacon-node-api-endpoint`](../Reference/CLI/Subcommands/Voluntary-Exit.md#beacon-node-api-endpoint).
+    You must have a running beacon node which has the [REST API enabled].
+* Specify the validators to exit using the
+   [`--validator-keys`](../Reference/CLI/Subcommands/Voluntary-Exit.md#validator-keys) option.
+* Specify the earliest epoch at which to exit using the [`--epoch`](../Reference/CLI/Subcommands/Voluntary-Exit.md#epoch)
+    option. If not specified, this defaults to the current epoch. You cannot specify a future epoch.
+
+If using an external signer such as [Web3Signer], then specify the external signer URL and
+public key of the exiting validator:
+
+!!! example
+
+   ```bash
+   teku voluntary-exit --beacon-node-api-endpoint=http://10.32.100.1:5051 \
+   --validators-external-signer-public-keys=888eef... \
+   --validators-external-signer-url=http://localhost:9000 \
+   --epoch=24500
+   ```
+
+Use the [`/eth/v1/beacon/pool/voluntary_exits`](https://consensys.github.io/teku/#operation/getEthV1BeaconPoolVoluntary_exits)
+API to check the pending exit queue.
+
+<!-- links -->
+[Web3Signer]: https://docs.web3signer.consensys.net/en/latest/
+[REST API enabled]: ../Reference/CLI/CLI-Syntax.md#rest-api-enabled
diff --git a/docs/Reference/CLI/Subcommands/Validator-Client.md b/docs/Reference/CLI/Subcommands/Validator-Client.md
@@ -1,5 +1,5 @@
 ---
-title: Subcommand options
+title: Validator client subcommand options
 ---
 
 # `validator-client`, `vc`

diff --git a/docs/Reference/CLI/Subcommands/Voluntary-Exit.md b/docs/Reference/CLI/Subcommands/Voluntary-Exit.md
@@ -0,0 +1,254 @@
+---
+title: Voluntary exit subcommand options
+---
+
+# `voluntary-exit`
+
+Create and sign a voluntary exit for the specified validator or set of validators.
+
+## Options
+
+### beacon-node-api-endpoint
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --beacon-node-api-endpoint=<ENDPOINT>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    teku voluntary-exit --beacon-node-api-endpoint=http://192.138.10.12
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_BEACON_NODE_ENDPOINT=http://192.138.10.12
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    beacon-node-api-endpoint: "http://192.138.10.12"
+    ```
+
+Endpoint of the beacon node's REST API. Default is `http://127.0.0.1:5051`.
+
+### config-file
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --config-file=<FILE>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    teku voluntary-exit --config-file=/home/me/me_node/config.yaml
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_CONFIG_FILE=/home/me/me_node/config.yaml
+    ```
+
+The path to the YAML configuration file.
+The default is `none`.
+
+### confirmation-enabled
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --confirmation-enabled=<BOOLEAN>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    teku voluntary-exit --confirmation-enabled=false
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_CONFIRMATION_ENABLED=false
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    confirmation-enabled: false
+    ```
+
+Specify whether to request confirmation when exiting a validator. Defaults to `true`.
+
+!!! danger
+
+    Exercise care when using this option because if set to `false`, exits are generated immediately
+    without any prompt.
+
+### epoch
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --epoch=<EPOCH>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    teku voluntary-exit --epoch=24500
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_EPOCH=24500
+    ```
+
+Earliest epoch that the voluntary exit can be processed. The specified epoch can be a past epoch,
+or current epoch. You cannot specify a future epoch. Defaults to the current epoch.
+
+!!! note
+
+    If there is a high number of validators that are queued to exit, then the validator exit may be
+    processed at a later epoch.
+
+### validator-keys
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --validator-keys=<KEY_DIR>:<PASS_DIR> | <KEY_FILE>:<PASS_FILE>[,<KEY_DIR>:<PASS_DIR> | <KEY_FILE>:<PASS_FILE>...]...
+    ```
+
+=== "Command Line for Directory"
+
+    ```bash
+    teku voluntary-exit --validator-keys=/home/validator/keys:home/validator/passwords
+    ```
+
+=== "Command Line for File"
+
+    ```bash
+    teku voluntary-exit --validator-keys=/home/validator/keys/validator_217179e.json:/home/validator/passwords/validator_217179e.txt
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATOR_KEYS=/home/validator/keys:home/validator/passwords
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validator-keys: "/home/validator/keys:home/validator/passwords"
+    ```
+
+Directory or file to load the encrypted keystores and passwords of the validators that you wish to
+exit. Keystore files must use the `.json` file extension, and password files must use the `.txt`
+file extension.
+
+When specifying directories, Teku expects to find identically named
+keystore and password files. For example `validator_217179e.json` and `validator_217179e.txt`.
+
+When specifying file names, Teku expects that the files exist.
+
+!!! note
+
+    The path separator is operating system dependent, and should be `;` in Windows rather than `:`.
+
+### validators-external-signer-public-keys
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --validators-external-signer-public-keys=<KEY>[,<KEY>...]
+    ```
+
+=== "Command Line"
+
+    ```bash
+    teku voluntary-exit --validators-external-signer-public-keys=0xa99a...e44c,0xb89b...4a0b
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATORS_EXTERNAL_SIGNER_PUBLIC_KEYS=0xa99a...e44c,0xb89b...4a0b
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validators-external-signer-public-keys: ["0xa99a...e44c","0xb89b...4a0b"]
+    ```
+
+List of public keys of validators that you wish to voluntarily exit when using an external signer
+(for example, [Web3Signer]).
+
+### validators-external-signer-timeout
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --validators-external-signer-timeout=<INTEGER>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    teku voluntary-exit --validators-external-signer-timeout=2000
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATORS_EXTERNAL_SIGNER_TIMEOUT=2000
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validators-external-signer-timeout: 2000
+    ```
+
+Timeout in milliseconds for requests to the external signer. Default is 1000.
+
+### validators-external-signer-url
+
+=== "Syntax"
+
+    ```bash
+    teku voluntary-exit --validators-external-signer-url=<URL>
+    ```
+
+=== "Command Line"
+
+    ```bash
+    teku voluntary-exit --validators-external-signer-url=http://localhost:9000
+    ```
+
+=== "Environment Variable"
+
+    ```bash
+    TEKU_VALIDATORS_EXTERNAL_SIGNER_URL=http://localhost:9000
+    ```
+
+=== "Configuration File"
+
+    ```bash
+    validators-external-signer-url: "http://localhost:9000"
+    ```
+
+URL of the external signer (for example, [Web3Signer]).
+
+<!-- links -->
+[Web3Signer]: https://docs.web3signer.consensys.net/en/latest/
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -72,6 +72,7 @@ nav:
         - Prevent slashing offences: HowTo/Prevent-Slashing.md
         - Find and connect to peers:
             - Improve P2P connectivity: HowTo/Find-and-Connect/Improve-Connectivity.md
+        - Voluntary exit: HowTo/Voluntary-Exit.md
         - Troubleshoot:
             - Solve common problems: HowTo/Troubleshoot/Troubleshooting.md
     - Concepts:
@@ -84,6 +85,7 @@ nav:
             - admin: Reference/CLI/Subcommands/Admin.md
             - slashing-protection: Reference/CLI/Subcommands/Slashing-Protection.md
             - validator-client, vc: Reference/CLI/Subcommands/Validator-Client.md
+            - voluntary-exit: Reference/CLI/Subcommands/Voluntary-Exit.md
             - Development and testing: Reference/CLI/Subcommands/Development.md
         - RESTful APIs:
           - Teku REST API methods: Reference/Rest_API/Rest.md