gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-05-08 01:05:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3 from chong-he/unstable

Browse Source 
Merge Unstable
This commit is contained in:
chonghe
2023-09-15 20:38:31 +08:00
committed by GitHub
parent 9091ebdd4c d386a07b0c
commit 5a5bbe7b39
46 changed files with 1305 additions and 868 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
book/src/SUMMARY.md
View File

@@ -56,3 +56,4 @@
* [Contributing](./contributing.md)
* [Development Environment](./setup.md)
* [FAQs](./faq.md)
* [Protocol Developers](./developers.md)

12
book/src/advanced_networking.md
View File

@@ -121,13 +121,13 @@ nodes that do not run directly on a public network.
To listen over only IPv6 use the same parameters as done when listening over
IPv4 only:
- `--listen-addresses :: --port 9909` will listen over IPv6 using port `9909` for
- `--listen-address :: --port 9909` will listen over IPv6 using port `9909` for
TCP and UDP.
- `--listen-addresses :: --port 9909 --discovery-port 9999` will listen over
- `--listen-address :: --port 9909 --discovery-port 9999` will listen over
IPv6 using port `9909` for TCP and port `9999` for UDP.
To listen over both IPv4 and IPv6:
- Set two listening addresses using the `--listen-addresses` flag twice ensuring
- Set two listening addresses using the `--listen-address` flag twice ensuring
the two addresses are one IPv4, and the other IPv6. When doing so, the
`--port` and `--discovery-port` flags will apply exclusively to IPv4. Note
that this behaviour differs from the Ipv6 only case described above.
@@ -139,16 +139,16 @@ To listen over both IPv4 and IPv6:
##### Configuration Examples
- `--listen-addresses :: --listen-addresses 0.0.0.0 --port 9909` will listen
- `--listen-address :: --listen-address 0.0.0.0 --port 9909` will listen
over IPv4 using port `9909` for TCP and UDP. It will also listen over IPv6 but
using the default value for `--port6` for UDP and TCP (`9090`).
- `--listen-addresses :: --listen-addresses --port 9909 --discovery-port6 9999`
- `--listen-address :: --listen-address --port 9909 --discovery-port6 9999`
will have the same configuration as before except for the IPv6 UDP socket,
which will use port `9999`.
#### Configuring Lighthouse to advertise IPv6 reachable addresses
Lighthouse supports IPv6 to connect to other nodes both over IPv6 exclusively,
and dual stack using one socket for IPv6 and another socket for IPv6. In both
and dual stack using one socket for IPv4 and another socket for IPv6. In both
scenarios, the previous sections still apply. In summary:
> Beacon nodes must advertise their publicly reachable socket address

51
book/src/developers.md Normal file
View File

@@ -0,0 +1,51 @@
# For Protocol Developers
_Documentation for protocol developers._
This section lists Lighthouse-specific decisions that are not strictly spec'd and may be useful for
other protocol developers wishing to interact with lighthouse.
## Custom ENR Fields
Lighthouse currently uses the following ENR fields:
### Ethereum Consensus Specified
| Field | Description |
| ---- | ---- |
| `eth2` | The `ENRForkId` in SSZ bytes specifying which fork the node is on |
| `attnets` | An SSZ bitfield which indicates which of the 64 subnets the node is subscribed to for an extended period of time |
| `syncnets` | An SSZ bitfield which indicates which of the sync committee subnets the node is subscribed to |
### Lighthouse Custom Fields
Lighthouse is currently using the following custom ENR fields.
| Field | Description |
| ---- | ---- |
| `quic` | The UDP port on which the QUIC transport is listening on IPv4 |
| `quic6` | The UDP port on which the QUIC transport is listening on IPv6 |
## Custom RPC Messages
The specification leaves room for implementation-specific errors. Lighthouse uses the following
custom RPC error messages.
### Goodbye Reason Codes
| Code | Message | Description |
| ---- | ---- | ---- |
| 128 | Unable to Verify Network | Teku uses this, so we adopted it. It relates to having a fork mismatch |
| 129 | Too Many Peers | Lighthouse can close a connection because it has reached its peer-limit and pruned excess peers |
| 250 | Bad Score | The node has been dropped due to having a bad peer score |
| 251 | Banned | The peer has been banned and disconnected |
| 252 | Banned IP | The IP the node is connected to us with has been banned |
### Error Codes
| Code | Message | Description |
| ---- | ---- | ---- |
| 139 | Rate Limited | The peer has been rate limited so we return this error as a response |

42
book/src/faq.md
View File

@@ -40,6 +40,7 @@
- [How do I check the version of Lighthouse that is running?](#misc-version)
- [Does Lighthouse have pruning function like the execution client to save disk space?](#misc-prune)
- [Can I use a HDD for the freezer database and only have the hot db on SSD?](#misc-freezer)
- [Can Lighthouse log in local timestamp instead of UTC?](#misc-timestamp)
## Beacon Node
@@ -436,16 +437,14 @@ Monitoring](./validator-monitoring.md) for more information. Lighthouse has also
### <a name="net-bn-vc"></a> My beacon node and validator client are on different servers. How can I point the validator client to the beacon node?
The settings are as follows:
1. On the beacon node:
Specify `lighthouse bn --http-address local_IP` so that the beacon node is listening on the local network rather than on the `localhost`.
1. On the validator client:
The setting on the beacon node is the same for both cases below. In the beacon node, specify `lighthouse bn --http-address local_IP` so that the beacon node is listening on the local network rather than `localhost`. You can find the `local_IP` by running the command `hostname -I | awk '{print $1}'` on the server running the beacon node.
1. If the beacon node and validator clients are on different servers *in the same network*, the setting in the validator client is as follows:
Use the flag `--beacon-nodes` to point to the beacon node. For example, `lighthouse vc --beacon-nodes http://local_IP:5052` where `local_IP` is the local IP address of the beacon node and `5052` is the default `http-port` of the beacon node.
If you have firewall setup, e.g., `ufw`, you will need to allow port 5052 (assuming that the default port is used) with `sudo ufw allow 5052`. Note: this will allow all IP addresses to access the HTTP API of the beacon node. If you are on an untrusted network (e.g., a university or public WiFi) or the host is exposed to the internet, use apply IP-address filtering as described later in this section.
You can test that the setup is working with by running the following command on the validator client host:
```bash
@@ -453,8 +452,25 @@ The settings are as follows:
```
You can refer to [Redundancy](./redundancy.md) for more information.
It is also worth noting that the `--beacon-nodes` flag can also be used for redundancy of beacon nodes. For example, let's say you have a beacon node and a validator client running on the same host, and a second beacon node on another server as a backup. In this case, you can use `lighthouse vc --beacon-nodes http://localhost:5052, http://local_IP:5052` on the validator client.
2. If the beacon node and validator clients are on different servers *and different networks*, it is necessary to perform port forwarding of the SSH port (e.g., the default port 22) on the router, and also allow firewall on the SSH port. The connection can be established via port forwarding on the router.
In the validator client, use the flag `--beacon-nodes` to point to the beacon node. However, since the beacon node and the validator client are on different networks, the IP address to use is the public IP address of the beacon node, i.e., `lighthouse vc --beacon-nodes http://public_IP:5052`. You can get the public IP address of the beacon node by running the command ` dig +short myip.opendns.com @resolver1.opendns.com` on the server running the beacon node.
Additionally, port forwarding of port 5052 on the router connected to the beacon node is required for the vc to connect to the bn. To do port forwarding, refer to [how to open ports](./advanced_networking.md#how-to-open-ports).
If you have firewall setup, e.g., `ufw`, you will need to allow connections to port 5052 (assuming that the default port is used). Since the beacon node HTTP/HTTPS API is public-facing (i.e., the 5052 port is now exposed to the internet due to port forwarding), we strongly recommend users to apply IP-address filtering to the BN/VC connection from malicious actors. This can be done using the command:
```
sudo ufw allow from vc_IP_address proto tcp to any port 5052
```
where `vc_IP_address` is the public IP address of the validator client. The command will only allow connections to the beacon node from the validator client IP address to prevent malicious attacks on the beacon node over the internet.
It is also worth noting that the `--beacon-nodes` flag can also be used for redundancy of beacon nodes. For example, let's say you have a beacon node and a validator client running on the same host, and a second beacon node on another server as a backup. In this case, you can use `lighthouse vc --beacon-nodes http://localhost:5052, http://IP-address:5052` on the validator client.
### <a name="net-ip"></a> Should I do anything to the beacon node or validator client settings if I have a relocation of the node / change of IP address?
No. Lighthouse will auto-detect the change and update your Ethereum Node Record (ENR). You just need to make sure you are not manually setting the ENR with `--enr-address` (which, for common use cases, this flag is not used).
@@ -513,11 +529,9 @@ There is no pruning of Lighthouse database for now. However, since v4.2.0, a fea
Yes, you can do so by using the flag `--freezer-dir /path/to/freezer_db` in the beacon node.
### <a name="misc-timestamp"></a> Can Lighthouse log in local timestamp instead of UTC?
The reason why Lighthouse logs in UTC is due to the dependency on an upstream library that is [yet to be resolved](https://github.com/sigp/lighthouse/issues/3130). Alternatively, using the flag `disable-log-timestamp` in combination with systemd will suppress the UTC timestamps and print the logs in local timestamps.

2
book/src/setup.md
View File

@@ -14,7 +14,7 @@ The additional requirements for developers are:
don't have `anvil` available on your `PATH`.
- [`cmake`](https://cmake.org/cmake/help/latest/command/install.html). Used by
some dependencies. See [`Installation Guide`](./installation.md) for more info.
- [`java 11 runtime`](https://openjdk.java.net/projects/jdk/). 11 is the minimum,
- [`java 17 runtime`](https://openjdk.java.net/projects/jdk/). 17 is the minimum,
used by web3signer_tests.
- [`libpq-dev`](https://www.postgresql.org/docs/devel/libpq.html). Also know as
`libpq-devel` on some systems.

23
book/src/ui-configuration.md
View File

@@ -9,23 +9,20 @@ following configuration screen.
## Connecting to the Clients
This allows you to enter the address and ports of the associated Lighthouse
Both the Beacon node and the Validator client need to have their HTTP APIs enabled. These ports should be accessible from the computer running Siren. This allows you to enter the address and ports of the associated Lighthouse
Beacon node and Lighthouse Validator client.
> The Beacon Node must be run with the `--gui` flag set.
To enable the HTTP API for the beacon node, utilize the `--gui` CLI flag. This action ensures that the HTTP API can be accessed by other software on the same machine.
If you run Siren in the browser (by entering `localhost` in the browser), you will need to allow CORS in the HTTP API. This can be done by adding the flag `--http-allow-origin "*"` for both beacon node and validator client. If you would like to access Siren beyond the local computer, we recommend using an SSH tunnel. This requires a tunnel for 3 ports: `80` (assuming the port is unchanged as per the [installation guide](./ui-installation.md#docker-recommended), `5052` (for beacon node) and `5062` (for validator client). You can use the command below to perform SSH tunneling:
```bash
ssh -N -L 80:127.0.0.1:80 -L 5052:127.0.0.1:5052 -L 5062:127.0.0.1:5062 username@local_ip
```
> The Beacon Node must be run with the `--gui` flag set.
where `username` is the username of the server and `local_ip` is the local IP address of the server. Note that with the `-N` option in an SSH session, you will not be able to execute commands in the CLI to avoid confusion with ordinary shell sessions. The connection will appear to be "hung" upon a successful connection, but that is normal. Once you have successfully connected to the server via SSH tunneling, you should be able to access Siren by entering `localhost` in a web browser.
If you require accessibility from another machine within the network, configure the `--http-address` to match the local LAN IP of the system running the Beacon Node and Validator Client.
You can also access Siren using the app downloaded in the [Siren release page](https://github.com/sigp/siren/releases). To access Siren beyond the local computer, you can use SSH tunneling for ports `5052` and `5062` using the command:
> To access from another machine on the same network (192.168.0.200) set the Beacon Node and Validator Client `--http-address` as `192.168.0.200`.
```bash
ssh -N -L 5052:127.0.0.1:5052 -L 5062:127.0.0.1:5062 username@local_ip
```
In a similar manner, the validator client requires activation of the `--http` flag, along with the optional consideration of configuring the `--http-address` flag. If `--http-address` flag is set on the Validator Client, then the `--unencrypted-http-transport` flag is required as well. These settings will ensure compatibility with Siren's connectivity requirements.
If you run Siren in the browser (by entering `localhost` in the browser), you will need to allow CORS in the HTTP API. This can be done by adding the flag `--http-allow-origin "*"` for both beacon node and validator client.
A green tick will appear once Siren is able to connect to both clients. You
can specify different ports for each client by clicking on the advanced tab.
@@ -37,7 +34,7 @@ The API Token is a secret key that allows you to connect to the validator
client. The validator client's HTTP API is guarded by this key because it
contains sensitive validator information and the ability to modify
validators. Please see [`Validator Authorization`](./api-vc-auth-header.md)
for further details.
for further details.
Siren requires this token in order to connect to the Validator client.
The token is located in the default data directory of the validator
@@ -49,7 +46,7 @@ entered.
## Name
This is your name, it can be modified and is solely used for aesthetics.
This is your name, it can be modified and is solely used for aesthetics.
## Device

47
book/src/ui-faqs.md
View File

@@ -1,7 +1,7 @@
# Frequently Asked Questions
## 1. Are there any requirements to run Siren?
Yes, Siren requires Lighthouse v3.5.1 or higher to function properly. These releases can be found on the [releases](https://github.com/sigp/lighthouse/releases) page of the Lighthouse repository.
Yes, the most current Siren version requires Lighthouse v4.3.0 or higher to function properly. These releases can be found on the [releases](https://github.com/sigp/lighthouse/releases) page of the Lighthouse repository.
## 2. Where can I find my API token?
The required Api token may be found in the default data directory of the validator client. For more information please refer to the lighthouse ui configuration [`api token section`](./api-vc-auth-header.md).
@@ -9,13 +9,41 @@ The required Api token may be found in the default data directory of the validat
## 3. How do I fix the Node Network Errors?
If you receive a red notification with a BEACON or VALIDATOR NODE NETWORK ERROR you can refer to the lighthouse ui configuration and [`connecting to clients section`](./ui-configuration.md#connecting-to-the-clients).
## 4. How do I change my Beacon or Validator address after logging in?
Once you have successfully arrived to the main dashboard, use the sidebar to access the settings view. In the top right hand corner there is a `Configuration` action button that will redirect you back to the configuration screen where you can make appropriate changes.
## 4. How do I connect Siren to Lighthouse from a different computer on the same network?
The most effective approach to enable access for a local network computer to Lighthouse's HTTP API ports is by configuring the `--http-address` to match the local LAN IP of the system running the beacon node and validator client. For instance, if the said node operates at `192.168.0.200`, this IP can be specified using the `--http-address` parameter as `--http-address 192.168.0.200`.
Subsequently, by designating the host as `192.168.0.200`, you can seamlessly connect Siren to this specific beacon node and validator client pair from any computer situated within the same network.
## 5. Why doesn't my validator balance graph show any data?
If your graph is not showing data, it usually means your validator node is still caching data. The application must wait at least 3 epochs before it can render any graphical visualizations. This could take up to 20min.
## 5. How can I use Siren to monitor my validators remotely when I am not at home?
## 4. Does Siren support reverse proxy or DNS named addresses?
There are two primary methods to access your Beacon Node and Validator Client remotely: setting up a VPN or utilizing SSH-reverse tunneling.
Most contemporary home routers provide options for VPN access in various ways. A VPN permits a remote computer to establish a connection with internal computers within a home network. With a VPN configuration in place, connecting to the VPN enables you to treat your computer as if it is part of your local home network. The connection process involves following the setup steps for connecting via another machine on the same network on the Siren configuration page and [`connecting to clients section`](./ui-configuration.md#connecting-to-the-clients).
In the absence of a VPN, an alternative approach involves utilizing an SSH tunnel. To achieve this, you need remote SSH access to the computer hosting the Beacon Node and Validator Client pair (which necessitates a port forward in your router). In this context, while it is not obligatory to set a `--http-address` flag on the Beacon Node and Validator Client, you can configure an SSH tunnel to the local ports on the node and establish a connection through the tunnel. For instructions on setting up an SSH tunnel, refer to [`Connecting Siren via SSH tunnel`](./ui-faqs.md#6-how-do-i-connect-siren-to-lighthouse-via-a-ssh-tunnel) for detailed guidance.
## 6. How do I connect Siren to Lighthouse via a ssh tunnel?
If you would like to access Siren beyond the local network (i.e across the internet), we recommend using an SSH tunnel. This requires a tunnel for 3 ports: `80` (assuming the port is unchanged as per the [installation guide](./ui-installation.md#docker-recommended), `5052` (for beacon node) and `5062` (for validator client). You can use the command below to perform SSH tunneling:
```bash
ssh -N -L 80:127.0.0.1:80 -L 5052:127.0.0.1:5052 -L 5062:127.0.0.1:5062 username@local_ip
```
Where `username` is the username of the server and `local_ip` is the local IP address of the server. Note that with the `-N` option in an SSH session, you will not be able to execute commands in the CLI to avoid confusion with ordinary shell sessions. The connection will appear to be "hung" upon a successful connection, but that is normal. Once you have successfully connected to the server via SSH tunneling, you should be able to access Siren by entering `localhost` in a web browser.
You can also access Siren using the app downloaded in the [Siren release page](https://github.com/sigp/siren/releases). To access Siren beyond the local computer, you can use SSH tunneling for ports `5052` and `5062` using the command:
```bash
ssh -N -L 5052:127.0.0.1:5052 -L 5062:127.0.0.1:5062 username@local_ip
```
## 7. Does Siren support reverse proxy or DNS named addresses?
Yes, if you need to access your beacon or validator from an address such as `https://merp-server:9909/eth2-vc` you should follow the following steps for configuration:
1. Toggle `https` as your protocol
2. Add your address as `merp-server/eth2-vc`
@@ -24,3 +52,10 @@ Yes, if you need to access your beacon or validator from an address such as `htt
If you have configured it correctly you should see a green checkmark indicating Siren is now connected to your Validator Client and Beacon Node.
If you have separate address setups for your Validator Client and Beacon Node respectively you should access the `Advance Settings` on the configuration and repeat the steps above for each address.
## 8. How do I change my Beacon or Validator address after logging in?
Once you have successfully arrived to the main dashboard, use the sidebar to access the settings view. In the top right hand corner there is a `Configuration` action button that will redirect you back to the configuration screen where you can make appropriate changes.
## 9. Why doesn't my validator balance graph show any data?
If your graph is not showing data, it usually means your validator node is still caching data. The application must wait at least 3 epochs before it can render any graphical visualizations. This could take up to 20min.

2
book/src/validator-manager-create.md
View File

@@ -124,7 +124,6 @@ The command will create two files:
The VC which will receive the validators needs to have the following flags at a minimum:
- `--http`
- `--http-port 5062`
- `--enable-doppelganger-protection`
Therefore, the VC command might look like:
@@ -133,7 +132,6 @@ Therefore, the VC command might look like:
lighthouse \
vc \
--http \
--http-port 5062 \
--enable-doppelganger-protection
```

7
book/src/validator-manager-move.md
View File

@@ -69,7 +69,6 @@ In reality, many host configurations are possible. For example:
The source VC needs to have the following flags at a minimum:
- `--http`
- `--http-port 5062`
- `--http-allow-keystore-export`
Therefore, the source VC command might look like:
@@ -78,7 +77,6 @@ Therefore, the source VC command might look like:
lighthouse \
vc \
--http \
--http-port 5062 \
--http-allow-keystore-export
```
@@ -87,7 +85,6 @@ lighthouse \
The destination VC needs to have the following flags at a minimum:
- `--http`
- `--http-port 5062`
- `--enable-doppelganger-protection`
Therefore, the destination VC command might look like:
@@ -96,7 +93,6 @@ Therefore, the destination VC command might look like:
lighthouse \
vc \
--http \
--http-port 5062 \
--enable-doppelganger-protection
```
@@ -167,6 +163,8 @@ At the same time, `lighthouse vc` will log:
INFO Importing keystores via standard HTTP API, count: 1
INFO Enabled validator voting_pubkey: 0xab6e29f1b98fedfca878edce2b471f1b5ee58ee4c3bd216201f98254ef6f6eac40a53d74c8b7da54f51d3e85cacae92f, signing_method: local_keystore
INFO Modified key_cache saved successfully
```
Once the operation completes successfully, there is nothing else to be done. The
validators have been removed from the `src-host` and enabled at the `dest-host`.
If the `--enable-doppelganger-protection` flag was used it may take 2-3 epochs
@@ -183,6 +181,7 @@ lighthouse \
--dest-vc-token ~/.lighthouse/mainnet/validators/api-token.txt \
--validators 0x9096aab771e44da149bd7c9926d6f7bb96ef465c0eeb4918be5178cd23a1deb4aec232c61d85ff329b54ed4a3bdfff3a,0x90fc4f72d898a8f01ab71242e36f4545aaf87e3887be81632bb8ba4b2ae8fb70753a62f866344d7905e9a07f5a9cdda1
```
Any errors encountered during the operation should include information on how to
proceed. Assistance is also available on our
[Discord](https://discord.gg/cyAszAh).