From fde025c193c58040b181ea276465ed7b6da92e6e Mon Sep 17 00:00:00 2001
From: Lucas Saldanha <lucas.saldanha@consensys.net>
Date: Mon, 5 Dec 2022 11:39:20 +1300
Subject: [PATCH] Added documentation for sentry nodes deployment (#397)

---
 docs/HowTo/Sentry-Nodes.md                    | 85 +++++++++++++++++++
 .../CLI/Subcommands/Validator-Client.md       |  4 +
 mkdocs.yml                                    |  1 +
 3 files changed, 90 insertions(+)
 create mode 100644 docs/HowTo/Sentry-Nodes.md

diff --git a/docs/HowTo/Sentry-Nodes.md b/docs/HowTo/Sentry-Nodes.md
new file mode 100644
index 000000000..94c5b01fb
--- /dev/null
+++ b/docs/HowTo/Sentry-Nodes.md
@@ -0,0 +1,85 @@
+---
+description: How to use sentry beacon nodes
+---
+
+!!! warning
+
+    Sentry beacon nodes is an early access feature and is subject to change.
+
+# Sentry beacon nodes
+
+You can calculate future block proposers ahead of time, which opens up an attack vector for attackers.
+A DoS attack on a validator's beacon node can cause the validator to miss its block proposal, thereby loosing
+the block proposal reward. You can mitigate this issue by using sentry nodes.
+
+!!! important
+
+    Only [validators executed seperately](Get-Started/Run-Teku.md#run-the-clients-separately) from
+    beacon nodes (remote validators) can use sentry nodes 
+
+When you configure your remote validator to use sentry beacon nodes, each beacon node (or cluster of
+beacon nodes) can be assigned a role. Each role determines which beacon node the remote validator
+sends request to when performing a task.
+
+Sentry nodes support three roles:
+
+- `duties_provider` - Beacon node used for requesting attestations and block duties.
+- `block_handler` - Beacon node used for block creation and publishing.
+- `attestation_publisher` - Beacon node used for publishing attestations.
+
+Only the `duties_provider` role is mandatory. You can assign multiple beacon node endpoints for each
+role.
+
+## Configure sentry nodes
+
+!!! important
+
+    The CLI option `--Xsentry-config-file=<file_path>` cannot be used with
+    [`--beacon-node-api-endpoint`](../Reference/CLI/Subcommands/Validator-Client.md#beacon-node-api-endpoint).
+
+Configure your sentry nodes in a JSON configuration file. To configure your remote validator to use the
+sentry node configuration, use the `--Xsentry-config-file=<file_path>` CLI option.
+
+The configuration file (in this example, `/etc/sentry-node-config.json`) uses the following format:
+
+```json
+{
+  "beacon_nodes": {
+    "duties_provider": {
+      "endpoints": [
+        "http://duties:9051"
+      ]
+    },
+    "block_handler": {
+      "endpoints": [
+        "http://block:9051"
+      ]
+    },
+    "attestation_publisher": {
+      "endpoints": [
+        "http://attestation:9051"
+      ]
+    }
+  }
+}
+```
+
+Start your remote validator with the `--Xsentry-config-file` option, for example:
+
+```bash
+teku validator --Xsentry-config-file=/etc/sentry-node-config.json
+```
+
+During startup the logs display output similar to:
+
+```bash
+...
+DEBUG | SentryNodesConfigLoader | 2022-10-03 01:31:48.260 INFO  - Loading sentry nodes configuration from /etc/sentry-node-config.json
+DEBUG | SentryNodesConfigLoader | 2022-10-03 01:31:48.277 INFO  - Duty provider beacon nodes: http://duties:9051
+DEBUG | SentryNodesConfigLoader | 2022-10-03 01:31:48.277 INFO  - Block handler beacon nodes: http://block:9051
+DEBUG | SentryNodesConfigLoader | 2022-10-03 01:31:48.278 INFO  - Attestation publisher beacon nodes: http://attestation:9051
+...
+```
+
+At this point, the remote validator knows what beacon nodes should be used for its tasks and
+no further configuration is required.
diff --git a/docs/Reference/CLI/Subcommands/Validator-Client.md b/docs/Reference/CLI/Subcommands/Validator-Client.md
index 556261244..09d234d98 100644
--- a/docs/Reference/CLI/Subcommands/Validator-Client.md
+++ b/docs/Reference/CLI/Subcommands/Validator-Client.md
@@ -38,6 +38,10 @@ comma-separated list of beacon node API endpoints.
 If multiple beacon node endpoints are configured, the first one is used as primary and others
 as failovers.
 
+!!! note
+
+    This option cannot be used with the [sentry beacon nodes early access feature](../../../HowTo/Sentry-Nodes.md).
+
 The default is `http://127.0.0.1:5051`.
 
 ## `config-file`
diff --git a/mkdocs.yml b/mkdocs.yml
index 17ead4cdf..53bd06a8b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -82,6 +82,7 @@ nav:
         - Voluntary exit: HowTo/Voluntary-Exit.md
         - Migrate database: HowTo/Migrate-Database.md
         - Prepare for The Merge: HowTo/Prepare-for-The-Merge.md
+        - Use sentry beacon nodes: HowTo/Sentry-Nodes.md
         - Troubleshoot:
             - Solve common problems: HowTo/Troubleshoot/Troubleshooting.md
     - Concepts: