cerc-io/lighthouse
16
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Update Lighthouse Book API and Advanced Usage section (#4300)

Browse Source 
## Issue Addressed

Update Information in Lighthouse Book

## Proposed Changes

- move Validator Graffiti from Advanced Usage to Validator Management
- update API response and command
- some items that aren't too sure I put it in comment, which can be seen in raw/review format but not live


## Additional Info

Please provide any additional information. For example, future considerations
or information useful for reviewers.


Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com>
This commit is contained in:
chonghe 2023-06-02 03:17:36 +00:00
parent 749a242b0f
commit 6c769ed86c
20 changed files with 706 additions and 278 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
book/src/SUMMARY.md
View File

@ -18,10 +18,11 @@
* [Validator Monitoring](./validator-monitoring.md)
* [Doppelganger Protection](./validator-doppelganger.md)
* [Suggested Fee Recipient](./suggested-fee-recipient.md)
* [Validator Graffiti](./graffiti.md)
* [APIs](./api.md)
* [Beacon Node API](./api-bn.md)
* [/lighthouse](./api-lighthouse.md)
* [Validator Inclusion APIs](./validator-inclusion.md)
* [Lighthouse API](./api-lighthouse.md)
* [Validator Inclusion APIs](./validator-inclusion.md)
* [Validator Client API](./api-vc.md)
* [Endpoints](./api-vc-endpoints.md)
* [Authorization Header](./api-vc-auth-header.md)
@ -36,7 +37,6 @@
* [Advanced Usage](./advanced.md)
* [Checkpoint Sync](./checkpoint-sync.md)
* [Custom Data Directories](./advanced-datadir.md)
* [Validator Graffiti](./graffiti.md)
* [Proposer Only Beacon Nodes](./advanced-proposer-only.md)
* [Remote Signing with Web3Signer](./validator-web3signer.md)
* [Database Configuration](./advanced_database.md)
@ -46,9 +46,8 @@
* [Advanced Networking](./advanced_networking.md)
* [Running a Slasher](./slasher.md)
* [Redundancy](./redundancy.md)
* [Pre-Releases](./advanced-pre-releases.md)
* [Release Candidates](./advanced-release-candidates.md)
* [MEV and Lighthouse](./builders.md)
* [Maximal Extractable Value (MEV)](./builders.md)
* [Merge Migration](./merge-migration.md)
* [Late Block Re-orgs](./late-block-re-orgs.md)
* [Contributing](./contributing.md)

4
book/src/advanced-pre-releases.md
View File

@ -1,4 +0,0 @@
# Pre-Releases
Pre-releases are now referred to as [Release Candidates](./advanced-release-candidates.md). The terms may
be used interchangeably.

7
book/src/advanced-release-candidates.md
View File

@ -7,7 +7,7 @@
[`v1.4.0`]: https://github.com/sigp/lighthouse/releases/tag/v1.4.0
From time-to-time, Lighthouse *release candidates* will be published on the [sigp/lighthouse]
repository. These releases have passed the usual automated testing, however the developers would
repository. Release candidates are previously known as Pre-Releases. These releases have passed the usual automated testing, however the developers would
like to see it running "in the wild" in a variety of configurations before declaring it an official,
stable release. Release candidates are also used by developers to get feedback from users regarding the
ergonomics of new features or changes.
@ -36,8 +36,9 @@ Users may wish to try a release candidate for the following reasons:
- To help detect bugs and regressions before they reach production.
- To provide feedback on annoyances before they make it into a release and become harder to change or revert.
There can also be a scenario that a bug has been found and requires an urgent fix. An example of incidence is [v4.0.2-rc.0](https://github.com/sigp/lighthouse/releases/tag/v4.0.2-rc.0) which contains a hot-fix to address high CPU usage experienced after the [Capella](https://ethereum.org/en/history/#capella) upgrade on 12<sup>th</sup> April 2023. In this scenario, we will announce the release candidate on [Github](https://github.com/sigp/lighthouse/releases) and also on [Discord](https://discord.gg/cyAszAh) to recommend users to update to the release candidate version.
## When *not* to use a release candidate
It is not recommended to use release candidates for any critical tasks on mainnet (e.g., staking).
To test critical features, try one of the testnets (e.g., Prater).
Other than the above scenarios, it is generally not recommended to use release candidates for any critical tasks on mainnet (e.g., staking). To test new release candidate features, try one of the testnets (e.g., Goerli).

16
book/src/advanced.md
View File

@ -6,4 +6,18 @@ elsewhere?
This section provides detailed information about configuring Lighthouse for specific use cases, and
tips about how things work under the hood.
* [Advanced Database Configuration](./advanced_database.md): understanding space-time trade-offs in the database.
* [Checkpoint Sync](./checkpoint-sync.md): quickly sync the beacon chain to perform validator duties.
* [Custom Data Directories](./advanced-datadir.md): modify the data directory to your preferred location.
* [Proposer Only Beacon Nodes](./advanced-proposer-only.md): beacon node only for proposer duty for increased anonymity.
* [Remote Signing with Web3Signer](./validator-web3signer.md): don't want to store your keystore in local node? Use web3signer.
* [Database Configuration](./advanced_database.md): understanding space-time trade-offs in the database.
* [Database Migrations](./database-migrations.md): have a look at all previous Lighthouse database scheme versions.
* [Key Management](./key-management.md): explore how to generate wallet with Lighthouse.
* [Key Recovery](./key-recovery.md): explore how to recover wallet and validator with Lighthouse.
* [Advanced Networking](./advanced_networking.md): open your ports to have a diverse and healthy set of peers.
* [Running a Slasher](./slasher.md): contribute to the health of the network by running a slasher.
* [Redundancy](./redundancy.md): want to have more than one beacon node as backup? This is for you.
* [Release Candidates](./advanced-release-candidates.md): latest release of Lighthouse to get feedback from users.
* [Maximal Extractable Value](./builders.md): use external builders for a potential higher rewards during block proposals
* [Merge Migration](./merge-migration.md): look at what you need to do during a significant network upgrade: The Merge
* [Late Block Re-orgs](./late-block-re-orgs.md): read information about Lighthouse late block re-orgs.

26
book/src/advanced_database.md
View File

@ -23,13 +23,17 @@ states to slow down dramatically. A lower _slots per restore point_ value (SPRP)
frequent restore points, while a higher SPRP corresponds to less frequent. The table below shows
some example values.
| Use Case | SPRP | Yearly Disk Usage | Load Historical State |
|--------------------------|------|-------------------|-----------------------|
| Block explorer/analysis | 32 | 1.4 TB | 155 ms |
| Hobbyist (prev. default) | 2048 | 23.1 GB | 10.2 s |
| Validator only (default) | 8192 | 5.7 GB | 41 s |
| Use Case | SPRP | Yearly Disk Usage* | Load Historical State |
|----------------------------|------|-------------------|-----------------------|
| Research | 32 | 3.4 TB | 155 ms |
| Block explorer/analysis | 128 | 851 GB | 620 ms |
| Enthusiast (prev. default) | 2048 | 53.6 GB | 10.2 s |
| EHobbyist | 4096 | 26.8 GB | 20.5 s |
| Validator only (default) | 8192 | 8.1 GB | 41 s |
As you can see, it's a high-stakes trade-off! The relationships to disk usage and historical state
*Last update: May 2023.
As we can see, it's a high-stakes trade-off! The relationships to disk usage and historical state
load time are both linear – doubling SPRP halves disk usage and doubles load time. The minimum SPRP
is 32, and the maximum is 8192.
@ -38,9 +42,11 @@ The default value is 8192 for databases synced from scratch using Lighthouse v2.
The values shown in the table are approximate, calculated using a simple heuristic: each
`BeaconState` consumes around 18MB of disk space, and each block replayed takes around 5ms. The
**Yearly Disk Usage** column shows the approx size of the freezer DB _alone_ (hot DB not included),
and the **Load Historical State** time is the worst-case load time for a state in the last slot
before a restore point.
**Yearly Disk Usage** column shows the approximate size of the freezer DB _alone_ (hot DB not included), calculated proportionally using the total freezer database disk usage.
The **Load Historical State** time is the worst-case load time for a state in the last slot
before a restore point.
As an example, we use an SPRP of 4096 to calculate the total size of the freezer database until May 2023. It has been about 900 days since the genesis, the total disk usage by the freezer database is therefore: 900/365*26.8 GB = 66 GB.
### Defaults
@ -68,6 +74,8 @@ The historical state cache size can be specified with the flag `--historic-state
lighthouse beacon_node --historic-state-cache-size 4
```
> Note: This feature will cause high memory usage.
## Glossary
* _Freezer DB_: part of the database storing finalized states. States are stored in a sparser

26
book/src/advanced_networking.md
View File

@ -51,7 +51,7 @@ peers for your node and overall improve the Ethereum consensus network.
Lighthouse currently supports UPnP. If UPnP is enabled on your router,
Lighthouse will automatically establish the port mappings for you (the beacon
node will inform you of established routes in this case). If UPnP is not
enabled, we recommend you manually set up port mappings to both of Lighthouse's
enabled, we recommend you to manually set up port mappings to both of Lighthouse's
TCP and UDP ports (9000 by default).
> Note: Lighthouse needs to advertise its publicly accessible ports in
@ -63,6 +63,28 @@ TCP and UDP ports (9000 by default).
> explicitly specify them using the `--enr-tcp-port` and `--enr-udp-port` as
> explained in the following section.
### How to Open Ports
The steps to do port forwarding depends on the router, but the general steps are given below:
1. Determine the default gateway IP:
- On Linux: open a terminal and run `ip route | grep default`, the result should look something similar to `default via 192.168.50.1 dev wlp2s0 proto dhcp metric 600`. The `192.168.50.1` is your router management default gateway IP.
- On MacOS: open a terminal and run `netstat -nr|grep default` and it should return the default gateway IP.
- On Windows: open a command prompt and run `ipconfig` and look for the `Default Gateway` which will show you the gateway IP.
The default gateway IP usually looks like 192.168.X.X. Once you obtain the IP, enter it to a web browser and it will lead you to the router management page.
2. Login to the router management page. The login credentials are usually available in the manual or the router, or it can be found on a sticker underneath the router. You can also try the login credentials for some common router brands listed [here](https://www.noip.com/support/knowledgebase/general-port-forwarding-guide/).
3. Navigate to the port forward settings in your router. The exact step depends on the router, but typically it will fall under the "Advanced" section, under the name "port forwarding" or "virtual server".
4. Configure a port forwarding rule as below:
- Protocol: select `TCP/UDP` or `BOTH`
- External port: `9000`
- Internal port: `9000`
- IP address: Usually there is a dropdown list for you to select the device. Choose the device that is running Lighthouse
5. To check that you have successfully open the ports, go to [yougetsignal](https://www.yougetsignal.com/tools/open-ports/) and enter `9000` in the `port number`. If it shows "open", then you have successfully set up port forwarding. If it shows "closed", double check your settings, and also check that you have allowed firewall rules on port 9000.
### ENR Configuration
@ -81,7 +103,7 @@ and if it is, it will update your ENR to the correct public IP and port address
(meaning you do not need to set it manually). Lighthouse persists its ENR, so
on reboot it will re-load the settings it had discovered previously.
Modifying the ENR settings can degrade the discovery of your node making it
Modifying the ENR settings can degrade the discovery of your node, making it
harder for peers to find you or potentially making it harder for other peers to
find each other. We recommend not touching these settings unless for a more
advanced use case.

56
book/src/api-bn.md
View File

@ -5,7 +5,7 @@ specification][OpenAPI]. Please follow that link for a full description of each
## Starting the server
A Lighthouse beacon node can be configured to expose a HTTP server by supplying the `--http` flag. The default listen address is `127.0.0.1:5052`.
A Lighthouse beacon node can be configured to expose an HTTP server by supplying the `--http` flag. The default listen address is `http://127.0.0.1:5052`.
The following CLI flags control the HTTP server:
@ -55,11 +55,8 @@ Additional risks to be aware of include:
## CLI Example
Start the beacon node with the HTTP server listening on [http://localhost:5052](http://localhost:5052):
Start a beacon node and an execution node according to [Run a node](./run_a_node.md). Note that since [The Merge](https://ethereum.org/en/roadmap/merge/), an execution client is required to be running along with a beacon node. Hence, the query on Beacon Node APIs requires users to run both. While there are some Beacon Node APIs that you can query with only the beacon node, such as the [node version](https://ethereum.github.io/beacon-APIs/#/Node/getNodeVersion), in general an execution client is required to get the updated information about the beacon chain, such as [state root](https://ethereum.github.io/beacon-APIs/#/Beacon/getStateRoot), [headers](https://ethereum.github.io/beacon-APIs/#/Beacon/getBlockHeaders) and many others, which are dynamically progressing with time.
```bash
lighthouse bn --http
```
## HTTP Request/Response Examples
@ -77,40 +74,46 @@ curl -X GET "http://localhost:5052/eth/v1/beacon/headers/head" -H "accept: appl
```json
{
"execution_optimistic": false,
"finalized": false,
"data": {
"root": "0x4381454174fc28c7095077e959dcab407ae5717b5dca447e74c340c1b743d7b2",
"root": "0x9059bbed6b8891e0ba2f656dbff93fc40f8c7b2b7af8fea9df83cfce5ee5e3d8",
"canonical": true,
"header": {
"message": {
"slot": "3199",
"proposer_index": "19077",
"parent_root": "0xf1934973041c5896d0d608e52847c3cd9a5f809c59c64e76f6020e3d7cd0c7cd",
"state_root": "0xe8e468f9f5961655dde91968f66480868dab8d4147de9498111df2b7e4e6fe60",
"body_root": "0x6f183abc6c4e97f832900b00d4e08d4373bfdc819055d76b0f4ff850f559b883"
"slot": "6271829",
"proposer_index": "114398",
"parent_root": "0x1d2b4fa8247f754a7a86d36e1d0283a5e425491c431533716764880a7611d225",
"state_root": "0x2b48adea290712f56b517658dde2da5d36ee01c41aebe7af62b7873b366de245",
"body_root": "0x6fa74c995ce6f397fa293666cde054d6a9741f7ec280c640bee51220b4641e2d"
},
"signature": "0x988064a2f9cf13fe3aae051a3d85f6a4bca5a8ff6196f2f504e32f1203b549d5f86a39c6509f7113678880701b1881b50925a0417c1c88a750c8da7cd302dda5aabae4b941e3104d0cf19f5043c4f22a7d75d0d50dad5dbdaf6991381dc159ab"
"signature": "0x8258e64fea426033676a0045c50543978bf173114ba94822b12188e23cbc8d8e89e0b5c628a881bf3075d325bc11341105a4e3f9332ac031d89a93b422525b79e99325928a5262f17dfa6cc3ddf84ca2466fcad86a3c168af0d045f79ef52036"
}
}
}
```
The `jq` tool is used to format the JSON data properly. If it returns `jq: command not found`, then you can install `jq` with `sudo apt install -y jq`. After that, run the command again, and it should return the head state of the beacon chain.
### View the status of a validator
Shows the status of validator at index `1` at the `head` state.
```bash
curl -X GET "http://localhost:5052/eth/v1/beacon/states/head/validators/1" -H "accept: application/json" | jq
curl -X GET "http://localhost:5052/eth/v1/beacon/states/head/validators/1" -H "accept: application/json"
```
```json
{
"execution_optimistic": false,
"finalized": false,
"data": {
"index": "1",
"balance": "63985937939",
"status": "Active",
"balance": "32004587169",
"status": "active_ongoing",
"validator": {
"pubkey": "0x873e73ee8b3e4fcf1d2fb0f1036ba996ac9910b5b348f6438b5f8ef50857d4da9075d0218a9d1b99a9eae235a39703e1",
"withdrawal_credentials": "0x00b8cdcf79ba7e74300a07e9d8f8121dd0d8dd11dcfd6d3f2807c45b426ac968",
"pubkey": "0xa1d1ad0714035353258038e964ae9675dc0252ee22cea896825c01458e1807bfad2f9969338798548d9858a571f7425c",
"withdrawal_credentials": "0x01000000000000000000000015f4b914a0ccd14333d850ff311d6dafbfbaa32b",
"effective_balance": "32000000000",
"slashed": false,
"activation_eligibility_epoch": "0",
@ -121,6 +124,7 @@ curl -X GET "http://localhost:5052/eth/v1/beacon/states/head/validators/1" -H "
}
}
```
You can replace `1` in the above command with the validator index that you would like to query. Other API query can be done similarly by changing the link according to the Beacon API.
## Serving the HTTP API over TLS
> **Warning**: This feature is currently experimental.
@ -147,9 +151,18 @@ openssl req -x509 -nodes -newkey rsa:4096 -keyout key.pem -out cert.pem -days 36
Note that currently Lighthouse only accepts keys that are not password protected.
This means we need to run with the `-nodes` flag (short for 'no DES').
Once generated, we can run Lighthouse:
Once generated, we can run Lighthouse and an execution node according to [Run a node](./run_a_node.md). In addition, add the flags `--http-enable-tls --http-tls-cert cert.pem --http-tls-key key.pem` to Lighthouse, the command should look like:
```bash
lighthouse bn --http --http-enable-tls --http-tls-cert cert.pem --http-tls-key key.pem
lighthouse bn \
--network mainnet \
--execution-endpoint http://localhost:8551 \
--execution-jwt /secrets/jwt.hex \
--checkpoint-sync-url https://mainnet.checkpoint.sigp.io \
--http \
--http-enable-tls \
--http-tls-cert cert.pem \
--http-tls-key key.pem
```
Note that the user running Lighthouse must have permission to read the
certificate and key.
@ -159,6 +172,7 @@ The API is now being served at `https://localhost:5052`.
To test connectivity, you can run the following:
```bash
curl -X GET "https://localhost:5052/eth/v1/node/version" -H "accept: application/json" --cacert cert.pem | jq
```
### Connecting a validator client
In order to connect a validator client to a beacon node over TLS, the validator
@ -201,13 +215,13 @@ Ensure the `--http` flag has been supplied at the CLI.
You can quickly check that the HTTP endpoint is up using `curl`:
```bash
curl -X GET "http://localhost:5052/eth/v1/node/version" -H "accept: application/json" | jq
curl -X GET "http://localhost:5052/eth/v1/node/version" -H "accept:application/json"
```
The beacon node should respond with its version:
```json
{"data":{"version":"Lighthouse/v0.2.9-6f7b4768a/x86_64-linux"}}
{"data":{"version":"Lighthouse/v4.1.0-693886b/x86_64-linux"}
```
If this doesn't work, the server might not be started or there might be a

290
book/src/api-lighthouse.md
View File

@ -1,8 +1,8 @@
# Lighthouse Non-Standard APIs
Lighthouse fully supports the standardization efforts at
[github.com/ethereum/beacon-APIs](https://github.com/ethereum/beacon-APIs),
however sometimes development requires additional endpoints that shouldn't
[github.com/ethereum/beacon-APIs](https://github.com/ethereum/beacon-APIs).
However, sometimes development requires additional endpoints that shouldn't
necessarily be defined as a broad-reaching standard. Such endpoints are placed
behind the `/lighthouse` path.
@ -16,10 +16,12 @@ Although we don't recommend that users rely on these endpoints, we
document them briefly so they can be utilized by developers and
researchers.
### `/lighthouse/health`
*Note: This endpoint is presently only available on Linux.*
*Presently only available on Linux.*
Returns information regarding the health of the host machine.
```bash
curl -X GET "http://localhost:5052/lighthouse/health" -H "accept: application/json" | jq
```
@ -63,7 +65,7 @@ curl -X GET "http://localhost:5052/lighthouse/health" -H "accept: application/j
```
### `/lighthouse/ui/health`
Returns information regarding the health of the host machine.
```bash
curl -X GET "http://localhost:5052/lighthouse/ui/health" -H "accept: application/json" | jq
@ -83,24 +85,24 @@ curl -X GET "http://localhost:5052/lighthouse/ui/health" -H "accept: applicatio
"global_cpu_frequency": 3.4,
"disk_bytes_total": 502390845440,
"disk_bytes_free": 9981386752,
"network_name": "wlp0s20f3",
"network_bytes_total_received": 14105556611,
"network_bytes_total_transmit": 3649489389,
"nat_open": true,
"connected_peers": 80,
"sync_state": "Synced",
"system_uptime": 660706,
"app_uptime": 105,
"system_name": "Arch Linux",
"kernel_version": "5.19.13-arch1-1",
"os_version": "Linux rolling Arch Linux",
"host_name": "Computer1"
"network_name": "wlp0s20f3",
"network_bytes_total_received": 14105556611,
"network_bytes_total_transmit": 3649489389,
"nat_open": true,
"connected_peers": 80,
"sync_state": "Synced",
}
}
```
### `/lighthouse/ui/validator_count`
Returns an overview of validators.
```bash
curl -X GET "http://localhost:5052/lighthouse/ui/validator_count" -H "accept: application/json" | jq
```
@ -121,9 +123,9 @@ curl -X GET "http://localhost:5052/lighthouse/ui/validator_count" -H "accept: ap
}
```
### `/lighthouse/ui/validator_metrics`
Re-exposes certain metrics from the validator monitor to the HTTP API.
Will only return metrics for the validators currently being monitored and are present in the POST data.
Re-exposes certain metrics from the validator monitor to the HTTP API. This API requires that the beacon node to have the flag `--validator-monitor-auto`. This API will only return metrics for the validators currently being monitored and present in the POST data, or the validators running in the validator client.
```bash
curl -X POST "http://localhost:5052/lighthouse/ui/validator_metrics" -d '{"indices": [12345]}' -H "Content-Type: application/json" | jq
```
@ -148,24 +150,40 @@ curl -X POST "http://localhost:5052/lighthouse/ui/validator_metrics" -d '{"indic
}
}
```
Running this API without the flag `--validator-monitor-auto` in the beacon node will return null:
```json
{
"data": {
"validators": {}
}
}
```
### `/lighthouse/syncing`
Returns the sync status of the beacon node.
```bash
curl -X GET "http://localhost:5052/lighthouse/syncing" -H "accept: application/json" | jq
```
```json
{
"data": {
"SyncingFinalized": {
"start_slot": 3104,
"head_slot": 343744,
"head_root": "0x1b434b5ed702338df53eb5e3e24336a90373bb51f74b83af42840be7421dd2bf"
There are two possible outcomes, depending on whether the beacon node is syncing or synced.
1. Syncing:
```json
{
"data": {
"SyncingFinalized": {
"start_slot": "5478848",
"target_slot": "5478944"
}
}
}
}
}
```
```
1. Synced:
```json
{
"data": "Synced"
}
```
### `/lighthouse/peers`
@ -173,96 +191,137 @@ curl -X GET "http://localhost:5052/lighthouse/syncing" -H "accept: application/
curl -X GET "http://localhost:5052/lighthouse/peers" -H "accept: application/json" | jq
```
```json
[
{
"peer_id": "16Uiu2HAmA9xa11dtNv2z5fFbgF9hER3yq35qYNTPvN7TdAmvjqqv",
"peer_id": "16Uiu2HAm2ZoWQ2zkzsMFvf5o7nXa7R5F7H1WzZn2w7biU3afhgov",
"peer_info": {
"_status": "Healthy",
"score": {
"score": 0
"Real": {
"lighthouse_score": 0,
"gossipsub_score": -18371.409037358582,
"ignore_negative_gossipsub_score": false,
"score": -21.816048231863316
}
},
"client": {
"kind": "Lighthouse",
"version": "v0.2.9-1c9a055c",
"os_version": "aarch64-linux",
"protocol_version": "lighthouse/libp2p",
"agent_string": "Lighthouse/v0.2.9-1c9a055c/aarch64-linux"
"version": "v4.1.0-693886b",
"os_version": "x86_64-linux",
"protocol_version": "eth2/1.0.0",
"agent_string": "Lighthouse/v4.1.0-693886b/x86_64-linux"
},
"connection_status": {
"status": "disconnected",
"connections_in": 0,
"connections_out": 0,
"last_seen": 1082,
"last_seen": 9028,
"banned_ips": []
},
"listening_addresses": [
"/ip4/80.109.35.174/tcp/9000",
"/ip4/127.0.0.1/tcp/9000",
"/ip4/192.168.0.73/tcp/9000",
"/ip4/172.17.0.1/tcp/9000",
"/ip6/::1/tcp/9000"
"/ip4/212.102.59.173/tcp/23452",
"/ip4/23.124.84.197/tcp/23452",
"/ip4/127.0.0.1/tcp/23452",
"/ip4/192.168.0.2/tcp/23452",
"/ip4/192.168.122.1/tcp/23452"
],
"seen_addresses": [
"23.124.84.197:23452"
],
"sync_status": {
"Advanced": {
"Synced": {
"info": {
"status_head_slot": 343829,
"status_head_root": "0xe34e43efc2bb462d9f364bc90e1f7f0094e74310fd172af698b5a94193498871",
"status_finalized_epoch": 10742,
"status_finalized_root": "0x1b434b5ed702338df53eb5e3e24336a90373bb51f74b83af42840be7421dd2bf"
"head_slot": "5468141",
"head_root": "0x7acc017a199c0cf0693a19e0ed3a445a02165c03ea6f46cb5ffb8f60bf0ebf35",
"finalized_epoch": "170877",
"finalized_root": "0xbbc3541637976bd03b526de73e60a064e452a4b873b65f43fa91fefbba140410"
}
}
},
"meta_data": {
"seq_number": 160,
"attnets": "0x0000000800000080"
}
"V2": {
"seq_number": 501,
"attnets": "0x0000020000000000",
"syncnets": "0x00"
}
},
"subnets": [],
"is_trusted": false,
"connection_direction": "Outgoing",
"enr": "enr:-L64QI37ReMIki2Uqln3pcgQyAH8Y3ceSYrtJp1FlDEGSM37F7ngCpS9k-SKQ1bOHp0zFCkNxpvFlf_3o5OUkBRw0qyCAfqHYXR0bmV0c4gAAAIAAAAAAIRldGgykGKJQe8DABAg__________-CaWSCdjSCaXCEF3xUxYlzZWNwMjU2azGhAmoW921eIvf8pJhOvOwuxLSxKnpLY2inE_bUILdlZvhdiHN5bmNuZXRzAIN0Y3CCW5yDdWRwgluc"
}
}
]
```
### `/lighthouse/peers/connected`
Returns information about connected peers.
```bash
curl -X GET "http://localhost:5052/lighthouse/peers/connected" -H "accept: application/json" | jq
```
```json
[
{
"peer_id": "16Uiu2HAkzJC5TqDSKuLgVUsV4dWat9Hr8EjNZUb6nzFb61mrfqBv",
{
"peer_id": "16Uiu2HAmCAvpoYE6ABGdQJaW4iufVqNCTJU5AqzyZPB2D9qba7ZU",
"peer_info": {
"_status": "Healthy",
"score": {
"score": 0
"Real": {
"lighthouse_score": 0,
"gossipsub_score": 0,
"ignore_negative_gossipsub_score": false,
"score": 0
}
},
"client": {
"kind": "Lighthouse",
"version": "v0.2.8-87181204+",
"version": "v3.5.1-319cc61",
"os_version": "x86_64-linux",
"protocol_version": "lighthouse/libp2p",
"agent_string": "Lighthouse/v0.2.8-87181204+/x86_64-linux"
"protocol_version": "eth2/1.0.0",
"agent_string": "Lighthouse/v3.5.1-319cc61/x86_64-linux"
},
"connection_status": {
"status": "connected",
"connections_in": 1,
"connections_out": 0,
"last_seen": 0,
"banned_ips": []
"connections_in": 0,
"connections_out": 1,
"last_seen": 0
},
"listening_addresses": [
"/ip4/34.204.178.218/tcp/9000",
"/ip4/144.91.92.17/tcp/9000",
"/ip4/127.0.0.1/tcp/9000",
"/ip4/172.31.67.58/tcp/9000",
"/ip4/172.17.0.1/tcp/9000",
"/ip6/::1/tcp/9000"
"/ip4/172.19.0.3/tcp/9000"
],
"sync_status": "Unknown",
"seen_addresses": [
"144.91.92.17:9000"
],
"sync_status": {
"Synced": {
"info": {
"head_slot": "5468930",
"head_root": "0x25409073c65d2f6f5cee20ac2eff5ab980b576ca7053111456063f8ff8f67474",
"finalized_epoch": "170902",
"finalized_root": "0xab59473289e2f708341d8e5aafd544dd88e09d56015c90550ea8d16c50b4436f"
}
}
},
"meta_data": {
"seq_number": 1819,
"attnets": "0xffffffffffffffff"
}
"V2": {
"seq_number": 67,
"attnets": "0x0000000080000000",
"syncnets": "0x00"
}
},
"subnets": [
{
"Attestation": "39"
}
],
"is_trusted": false,
"connection_direction": "Outgoing",
"enr": "enr:-Ly4QHd3RHJdkuR1iE6MtVtibC5S-aiWGPbwi4cG3wFGbqxRAkAgLDseTzPFQQIehQ7LmO7KIAZ5R1fotjMQ_LjA8n1Dh2F0dG5ldHOIAAAAAAAQAACEZXRoMpBiiUHvAwAQIP__________gmlkgnY0gmlwhJBbXBGJc2VjcDI1NmsxoQL4z8A7B-NS29zOgvkTX1YafKandwOtrqQ1XRnUJj3se4hzeW5jbmV0cwCDdGNwgiMog3VkcIIjKA"
}
}
]
@ -297,7 +356,8 @@ health of the execution node that the beacon node is connected to.
- `latest_cached_block_number` & `latest_cached_block_timestamp`: the block
number and timestamp of the latest block we have in our block cache.
- For correct execution client voting this timestamp should be later than the
`voting_period_start_timestamp`.
`voting_target_timestamp`.
- `voting_target_timestamp`: The latest timestamp allowed for an execution layer block in this voting period.
- `eth1_node_sync_status_percentage` (float): An estimate of how far the head of the
execution node is from the head of the execution chain.
@ -420,11 +480,11 @@ curl -X GET "http://localhost:5052/lighthouse/beacon/states/0/ssz" | jq
### `/lighthouse/liveness`
POST request that checks if any of the given validators have attested in the given epoch. Returns a list
of objects, each including the validator index, epoch, and `is_live` status of a requested validator.
of objects, each including the validator index, epoch, and `is_live` status of a requested validator.
This endpoint is used in doppelganger detection, and will only provide accurate information for the
current, previous, or next epoch.
This endpoint is used in doppelganger detection, and can only provide accurate information for the current, previous, or next epoch.
> Note that for this API, if you insert an arbitrary epoch other than the previous, current or next epoch of the network, it will return `"code:400"` and `BAD_REQUEST`.
```bash
curl -X POST "http://localhost:5052/lighthouse/liveness" -d '{"indices":["0","1"],"epoch":"1"}' -H "content-type: application/json" | jq
@ -442,6 +502,8 @@ curl -X POST "http://localhost:5052/lighthouse/liveness" -d '{"indices":["0","1"
}
```
### `/lighthouse/database/info`
Information about the database's split point and anchor info.
@ -450,26 +512,29 @@ Information about the database's split point and anchor info.
curl "http://localhost:5052/lighthouse/database/info" | jq
```
```json
{
"schema_version": 5,
"schema_version": 16,
"config": {
"slots_per_restore_point": 2048,
"slots_per_restore_point": 8192,
"slots_per_restore_point_set_explicitly": false,
"block_cache_size": 5,
"historic_state_cache_size": 1,
"compact_on_init": false,
"compact_on_prune": true
"compact_on_prune": true,
"prune_payloads": true
},
"split": {
"slot": "2034912",
"state_root": "0x11c8516aa7d4d1613e84121e3a557ceca34618b4c1a38f05b66ad045ff82b33b"
"slot": "5485952",
"state_root": "0xcfe5d41e6ab5a9dab0de00d89d97ae55ecaeed3b08e4acda836e69b2bef698b4"
},
"anchor": {
"anchor_slot": "2034720",
"oldest_block_slot": "1958881",
"oldest_block_parent": "0x1fd3d855d03e9df28d8a41a0f9cb9d4c540832b3ca1c3e1d7e09cd75b874cc87",
"state_upper_limit": "2035712",
"state_lower_limit": "0"
"anchor_slot": "5414688",
"oldest_block_slot": "0",
"oldest_block_parent": "0x0000000000000000000000000000000000000000000000000000000000000000",
"state_upper_limit": "5414912",
"state_lower_limit": "8192"
}
}
```
@ -504,12 +569,12 @@ Manually provide `SignedBeaconBlock`s to backfill the database. This is intended
for use by Lighthouse developers during testing only.
### `/lighthouse/merge_readiness`
Returns the current difficulty and terminal total difficulty of the network. Before [The Merge](https://ethereum.org/en/roadmap/merge/) on 15<sup>th</sup> September 2022, you will see that the current difficulty is less than the terminal total difficulty, An example is shown below:
```bash
curl -X GET "http://localhost:5052/lighthouse/merge_readiness" | jq
```
```
```json
{
"data":{
"type":"ready",
@ -521,6 +586,21 @@ curl -X GET "http://localhost:5052/lighthouse/merge_readiness" | jq
}
```
As all testnets and Mainnet have been merged, both values will be the same after The Merge. An example of response on the Goerli testnet:
```json
{
"data": {
"type": "ready",
"config": {
"terminal_total_difficulty": "10790000"
},
"current_difficulty": "10790000"
}
}
```
### `/lighthouse/analysis/attestation_performance/{index}`
Fetch information about the attestation performance of a validator index or all validators for a
@ -611,20 +691,35 @@ Two query parameters are required:
Example:
```bash
curl -X GET "http://localhost:5052/lighthouse/analysis/block_rewards?start_slot=1&end_slot=32" | jq
curl -X GET "http://localhost:5052/lighthouse/analysis/block_rewards?start_slot=1&end_slot=1" | jq
```
The first few lines of the response would look like:
```json
[
{
"block_root": "0x51576c2fcf0ab68d7d93c65e6828e620efbb391730511ffa35584d6c30e51410",
"attestation_rewards": {
"total": 4941156,
"total": 637260,
"block_root": "0x4a089c5e390bb98e66b27358f157df825128ea953cee9d191229c0bcf423a4f6",
"meta": {
"slot": "1",
"parent_slot": "0",
"proposer_index": 93,
"graffiti": "EF #vm-eth2-raw-iron-prater-101"
},
..
},
..
]
"attestation_rewards": {
"total": 637260,
"prev_epoch_total": 0,
"curr_epoch_total": 637260,
"per_attestation_rewards": [
{
"50102": 780,
}
]
}
}
]
```
Caveats:
@ -653,6 +748,8 @@ Two query parameters are required:
curl -X GET "http://localhost:5052/lighthouse/analysis/block_packing_efficiency?start_epoch=1&end_epoch=1" | jq
```
An excerpt of the response looks like:
```json
[
{
@ -707,3 +804,16 @@ Should provide an output that emits log events as they occur:
}
}
```
### `/lighthouse/nat`
Checks if the ports are open.
```bash
curl -X GET "http://localhost:5052/lighthouse/nat" | jq
```
An open port will return:
```json
{
"data": true
}

400
book/src/api-vc-endpoints.md
View File

@ -17,8 +17,11 @@ HTTP Path | Description |
[`POST /lighthouse/validators/mnemonic`](#post-lighthousevalidatorsmnemonic) | Create a new validator from an existing mnemonic.
[`POST /lighthouse/validators/web3signer`](#post-lighthousevalidatorsweb3signer) | Add web3signer validators.
The query to Lighthouse API endpoints requires authorization, see [Authorization Header](./api-vc-auth-header.md).
In addition to the above endpoints Lighthouse also supports all of the [standard keymanager APIs](https://ethereum.github.io/keymanager-APIs/).
## `GET /lighthouse/version`
Returns the software version and `git` commit hash for the Lighthouse binary.
@ -32,15 +35,28 @@ Returns the software version and `git` commit hash for the Lighthouse binary.
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200 |
### Example Response Body
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X GET "http://localhost:5062/lighthouse/version" -H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq
```
Example Response Body:
```json
{
"data": {
"version": "Lighthouse/v0.2.11-fc0654fbe+/x86_64-linux"
"version": "Lighthouse/v4.1.0-693886b/x86_64-linux"
}
}
```
> Note: The command provided in this documentation links to the API token file. In this documentation, it is assumed that the API token file is located in `/var/lib/lighthouse/validators/API-token.txt`. If your database is saved in another directory, modify the `DATADIR` accordingly. If you are having permission issue with accessing the API token file, you can modify the header to become `-H "Authorization: Bearer $(sudo cat ${DATADIR}/validators/api-token.txt)"`.
> As an alternative, you can also provide the API token directly, for example, `-H "Authorization: Bearer api-token-0x02dc2a13115cc8c83baf170f597f22b1eb2930542941ab902df3daadebcb8f8176`. In this case, you obtain the token from the file `API token.txt` and the command becomes:
```bash
curl -X GET "http://localhost:5062/lighthouse/version" -H "Authorization: Bearer api-token-0x02dc2a13115cc8c83baf170f597f22b1eb2930542941ab902df3daadebcb8f8176" | jq
```
## `GET /lighthouse/health`
@ -57,24 +73,48 @@ Returns information regarding the health of the host machine.
*Note: this endpoint is presently only available on Linux.*
### Example Response Body
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X GET "http://localhost:5062/lighthouse/health" -H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq
```
Example Response Body:
```json
{
"data": {
"pid": 1476293,
"pid_num_threads": 19,
"pid_mem_resident_set_size": 4009984,
"pid_mem_virtual_memory_size": 1306775552,
"sys_virt_mem_total": 33596100608,
"sys_virt_mem_available": 23073017856,
"sys_virt_mem_used": 9346957312,
"sys_virt_mem_free": 22410510336,
"sys_virt_mem_percent": 31.322334,
"sys_loadavg_1": 0.98,
"sys_loadavg_5": 0.98,
"sys_loadavg_15": 1.01
}
"data": {
"sys_virt_mem_total": 8184274944,
"sys_virt_mem_available": 1532280832,
"sys_virt_mem_used": 6248341504,
"sys_virt_mem_free": 648790016,
"sys_virt_mem_percent": 81.27775,
"sys_virt_mem_cached": 1244770304,
"sys_virt_mem_buffers": 42373120,
"sys_loadavg_1": 2.33,
"sys_loadavg_5": 2.11,
"sys_loadavg_15": 2.47,
"cpu_cores": 4,
"cpu_threads": 8,
"system_seconds_total": 103095,
"user_seconds_total": 750734,
"iowait_seconds_total": 60671,
"idle_seconds_total": 3922305,
"cpu_time_total": 4794222,
"disk_node_bytes_total": 982820896768,
"disk_node_bytes_free": 521943703552,
"disk_node_reads_total": 376287830,
"disk_node_writes_total": 48232652,
"network_node_bytes_total_received": 143003442144,
"network_node_bytes_total_transmit": 185348289905,
"misc_node_boot_ts_seconds": 1681740973,
"misc_os": "linux",
"pid": 144072,
"pid_num_threads": 27,
"pid_mem_resident_set_size": 15835136,
"pid_mem_virtual_memory_size": 2179018752,
"pid_process_seconds_total": 54
}
}
```
@ -91,7 +131,13 @@ Returns information regarding the health of the host machine.
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200 |
### Example Response Body
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X GET "http://localhost:5062/lighthouse/ui/health" -H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq
```
Example Response Body
```json
{
@ -130,7 +176,12 @@ Returns the graffiti that will be used for the next block proposal of each valid
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200 |
### Example Response Body
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X GET "http://localhost:5062/lighthouse/ui/graffiti" -H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq
```
Example Response Body
```json
{
@ -155,71 +206,115 @@ Returns the Ethereum proof-of-stake consensus specification loaded for this vali
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200 |
### Example Response Body
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X GET "http://localhost:5062/lighthouse/spec" -H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq
```
Example Response Body
```json
{
"data": {
"CONFIG_NAME": "mainnet",
"MAX_COMMITTEES_PER_SLOT": "64",
"TARGET_COMMITTEE_SIZE": "128",
"MIN_PER_EPOCH_CHURN_LIMIT": "4",
"CHURN_LIMIT_QUOTIENT": "65536",
"SHUFFLE_ROUND_COUNT": "90",
"MIN_GENESIS_ACTIVE_VALIDATOR_COUNT": "1024",
"MIN_GENESIS_TIME": "1601380800",
"GENESIS_DELAY": "172800",
"MIN_DEPOSIT_AMOUNT": "1000000000",
"MAX_EFFECTIVE_BALANCE": "32000000000",
"EJECTION_BALANCE": "16000000000",
"EFFECTIVE_BALANCE_INCREMENT": "1000000000",
"HYSTERESIS_QUOTIENT": "4",
"HYSTERESIS_DOWNWARD_MULTIPLIER": "1",
"HYSTERESIS_UPWARD_MULTIPLIER": "5",
"PROPORTIONAL_SLASHING_MULTIPLIER": "3",
"GENESIS_FORK_VERSION": "0x00000002",
"BLS_WITHDRAWAL_PREFIX": "0x00",
"SECONDS_PER_SLOT": "12",
"MIN_ATTESTATION_INCLUSION_DELAY": "1",
"MIN_SEED_LOOKAHEAD": "1",
"MAX_SEED_LOOKAHEAD": "4",
"MIN_EPOCHS_TO_INACTIVITY_PENALTY": "4",
"MIN_VALIDATOR_WITHDRAWABILITY_DELAY": "256",
"SHARD_COMMITTEE_PERIOD": "256",
"BASE_REWARD_FACTOR": "64",
"WHISTLEBLOWER_REWARD_QUOTIENT": "512",
"PROPOSER_REWARD_QUOTIENT": "8",
"INACTIVITY_PENALTY_QUOTIENT": "16777216",
"MIN_SLASHING_PENALTY_QUOTIENT": "32",
"SAFE_SLOTS_TO_UPDATE_JUSTIFIED": "8",
"DOMAIN_BEACON_PROPOSER": "0x00000000",
"DOMAIN_BEACON_ATTESTER": "0x01000000",
"DOMAIN_RANDAO": "0x02000000",
"DOMAIN_DEPOSIT": "0x03000000",
"DOMAIN_VOLUNTARY_EXIT": "0x04000000",
"DOMAIN_SELECTION_PROOF": "0x05000000",
"DOMAIN_AGGREGATE_AND_PROOF": "0x06000000",
"DOMAIN_APPLICATION_MASK": "0x00000001",
"MAX_VALIDATORS_PER_COMMITTEE": "2048",
"SLOTS_PER_EPOCH": "32",
"EPOCHS_PER_ETH1_VOTING_PERIOD": "32",
"SLOTS_PER_HISTORICAL_ROOT": "8192",
"EPOCHS_PER_HISTORICAL_VECTOR": "65536",
"EPOCHS_PER_SLASHINGS_VECTOR": "8192",
"HISTORICAL_ROOTS_LIMIT": "16777216",
"VALIDATOR_REGISTRY_LIMIT": "1099511627776",
"MAX_PROPOSER_SLASHINGS": "16",
"MAX_ATTESTER_SLASHINGS": "2",
"MAX_ATTESTATIONS": "128",
"MAX_DEPOSITS": "16",
"MAX_VOLUNTARY_EXITS": "16",
"ETH1_FOLLOW_DISTANCE": "1024",
"TARGET_AGGREGATORS_PER_COMMITTEE": "16",
"RANDOM_SUBNETS_PER_VALIDATOR": "1",
"EPOCHS_PER_RANDOM_SUBNET_SUBSCRIPTION": "256",
"SECONDS_PER_ETH1_BLOCK": "14",
"DEPOSIT_CONTRACT_ADDRESS": "0x48b597f4b53c21b48ad95c7256b49d1779bd5890"
}
"data": {
"CONFIG_NAME": "prater",
"PRESET_BASE": "mainnet",
"TERMINAL_TOTAL_DIFFICULTY": "10790000",
"TERMINAL_BLOCK_HASH": "0x0000000000000000000000000000000000000000000000000000000000000000",
"TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH": "18446744073709551615",
"SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY": "128",
"MIN_GENESIS_ACTIVE_VALIDATOR_COUNT": "16384",
"MIN_GENESIS_TIME": "1614588812",
"GENESIS_FORK_VERSION": "0x00001020",
"GENESIS_DELAY": "1919188",
"ALTAIR_FORK_VERSION": "0x01001020",
"ALTAIR_FORK_EPOCH": "36660",
"BELLATRIX_FORK_VERSION": "0x02001020",
"BELLATRIX_FORK_EPOCH": "112260",
"CAPELLA_FORK_VERSION": "0x03001020",
"CAPELLA_FORK_EPOCH": "162304",
"SECONDS_PER_SLOT": "12",
"SECONDS_PER_ETH1_BLOCK": "14",
"MIN_VALIDATOR_WITHDRAWABILITY_DELAY": "256",
"SHARD_COMMITTEE_PERIOD": "256",
"ETH1_FOLLOW_DISTANCE": "2048",
"INACTIVITY_SCORE_BIAS": "4",
"INACTIVITY_SCORE_RECOVERY_RATE": "16",
"EJECTION_BALANCE": "16000000000",
"MIN_PER_EPOCH_CHURN_LIMIT": "4",
"CHURN_LIMIT_QUOTIENT": "65536",
"PROPOSER_SCORE_BOOST": "40",
"DEPOSIT_CHAIN_ID": "5",
"DEPOSIT_NETWORK_ID": "5",
"DEPOSIT_CONTRACT_ADDRESS": "0xff50ed3d0ec03ac01d4c79aad74928bff48a7b2b",
"MAX_COMMITTEES_PER_SLOT": "64",
"TARGET_COMMITTEE_SIZE": "128",
"MAX_VALIDATORS_PER_COMMITTEE": "2048",
"SHUFFLE_ROUND_COUNT": "90",
"HYSTERESIS_QUOTIENT": "4",
"HYSTERESIS_DOWNWARD_MULTIPLIER": "1",
"HYSTERESIS_UPWARD_MULTIPLIER": "5",
"SAFE_SLOTS_TO_UPDATE_JUSTIFIED": "8",
"MIN_DEPOSIT_AMOUNT": "1000000000",
"MAX_EFFECTIVE_BALANCE": "32000000000",
"EFFECTIVE_BALANCE_INCREMENT": "1000000000",
"MIN_ATTESTATION_INCLUSION_DELAY": "1",
"SLOTS_PER_EPOCH": "32",
"MIN_SEED_LOOKAHEAD": "1",
"MAX_SEED_LOOKAHEAD": "4",
"EPOCHS_PER_ETH1_VOTING_PERIOD": "64",
"SLOTS_PER_HISTORICAL_ROOT": "8192",
"MIN_EPOCHS_TO_INACTIVITY_PENALTY": "4",
"EPOCHS_PER_HISTORICAL_VECTOR": "65536",
"EPOCHS_PER_SLASHINGS_VECTOR": "8192",
"HISTORICAL_ROOTS_LIMIT": "16777216",
"VALIDATOR_REGISTRY_LIMIT": "1099511627776",
"BASE_REWARD_FACTOR": "64",
"WHISTLEBLOWER_REWARD_QUOTIENT": "512",
"PROPOSER_REWARD_QUOTIENT": "8",
"INACTIVITY_PENALTY_QUOTIENT": "67108864",
"MIN_SLASHING_PENALTY_QUOTIENT": "128",
"PROPORTIONAL_SLASHING_MULTIPLIER": "1",
"MAX_PROPOSER_SLASHINGS": "16",
"MAX_ATTESTER_SLASHINGS": "2",
"MAX_ATTESTATIONS": "128",
"MAX_DEPOSITS": "16",
"MAX_VOLUNTARY_EXITS": "16",
"INACTIVITY_PENALTY_QUOTIENT_ALTAIR": "50331648",
"MIN_SLASHING_PENALTY_QUOTIENT_ALTAIR": "64",
"PROPORTIONAL_SLASHING_MULTIPLIER_ALTAIR": "2",
"SYNC_COMMITTEE_SIZE": "512",
"EPOCHS_PER_SYNC_COMMITTEE_PERIOD": "256",
"MIN_SYNC_COMMITTEE_PARTICIPANTS": "1",
"INACTIVITY_PENALTY_QUOTIENT_BELLATRIX": "16777216",
"MIN_SLASHING_PENALTY_QUOTIENT_BELLATRIX": "32",
"PROPORTIONAL_SLASHING_MULTIPLIER_BELLATRIX": "3",
"MAX_BYTES_PER_TRANSACTION": "1073741824",
"MAX_TRANSACTIONS_PER_PAYLOAD": "1048576",
"BYTES_PER_LOGS_BLOOM": "256",
"MAX_EXTRA_DATA_BYTES": "32",
"MAX_BLS_TO_EXECUTION_CHANGES": "16",
"MAX_WITHDRAWALS_PER_PAYLOAD": "16",
"MAX_VALIDATORS_PER_WITHDRAWALS_SWEEP": "16384",
"DOMAIN_DEPOSIT": "0x03000000",
"BLS_WITHDRAWAL_PREFIX": "0x00",
"RANDOM_SUBNETS_PER_VALIDATOR": "1",
"DOMAIN_SYNC_COMMITTEE": "0x07000000",
"TARGET_AGGREGATORS_PER_SYNC_SUBCOMMITTEE": "16",
"DOMAIN_BEACON_ATTESTER": "0x01000000",
"DOMAIN_VOLUNTARY_EXIT": "0x04000000",
"DOMAIN_SYNC_COMMITTEE_SELECTION_PROOF": "0x08000000",
"DOMAIN_CONTRIBUTION_AND_PROOF": "0x09000000",
"EPOCHS_PER_RANDOM_SUBNET_SUBSCRIPTION": "256",
"TARGET_AGGREGATORS_PER_COMMITTEE": "16",
"DOMAIN_APPLICATION_MASK": "0x00000001",
"DOMAIN_AGGREGATE_AND_PROOF": "0x06000000",
"DOMAIN_RANDAO": "0x02000000",
"DOMAIN_SELECTION_PROOF": "0x05000000",
"DOMAIN_BEACON_PROPOSER": "0x00000000",
"SYNC_COMMITTEE_SUBNET_COUNT": "4"
}
}
```
@ -240,13 +335,13 @@ file may be read by a local user with access rights.
| Required Headers | - |
| Typical Responses | 200 |
### Example Path
Command:
```
localhost:5062/lighthouse/auth
```bash
curl http://localhost:5062/lighthouse/auth | jq
```
### Example Response Body
Example Response Body
```json
{
@ -267,7 +362,14 @@ Lists all validators managed by this validator client.
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200 |
### Example Response Body
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X GET "http://localhost:5062/lighthouse/validators/" -H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq
```
Example Response Body
```json
{
@ -304,13 +406,14 @@ Get a validator by their `voting_pubkey`.
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200, 400 |
### Example Path
Command:
```
localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc893050fd0dadc7a28949f9d0a72f2805d027521b45441101f0cc1cde
```bash
DATADIR=/var/lib/lighthouse
curl -X GET "http://localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc893050fd0dadc7a28949f9d0a72f2805d027521b45441101f0cc1cde" -H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" | jq
```
### Example Response Body
Example Response Body
```json
{
@ -323,7 +426,7 @@ localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc8
## `PATCH /lighthouse/validators/:voting_pubkey`
Update some values for the validator with `voting_pubkey`.
Update some values for the validator with `voting_pubkey`. The following example updates a validator from `enabled: true` to `enabled: false`
### HTTP Specification
@ -334,13 +437,8 @@ Update some values for the validator with `voting_pubkey`.
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200, 400 |
### Example Path
```
localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc893050fd0dadc7a28949f9d0a72f2805d027521b45441101f0cc1cde
```
### Example Request Body
Example Request Body
```json
{
@ -348,12 +446,29 @@ localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc8
}
```
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X PATCH "http://localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc893050fd0dadc7a28949f9d0a72f2805d027521b45441101f0cc1cde" \
-H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" \
-H "Content-Type: application/json" \
-d "{\"enabled\":false}" | jq
```
### Example Response Body
```json
null
```
A `null` response indicates that the request is successful. At the same time, `lighthouse vc` will log:
```
INFO Disabled validator voting_pubkey: 0xb0148e6348264131bf47bcd1829590e870c836dc893050fd0dadc7a28949f9d0a72f2805d027521b45441101f0cc1cde
INFO Modified key_cache saved successfully
```
## `POST /lighthouse/validators/`
Create any number of new validators, all of which will share a common mnemonic
@ -392,6 +507,28 @@ Validators are generated from the mnemonic according to
]
```
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X POST http://localhost:5062/lighthouse/validators \
-H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" \
-H "Content-Type: application/json" \
-d '[
{
"enable": true,
"description": "validator_one",
"deposit_gwei": "32000000000",
"graffiti": "Mr F was here",
"suggested_fee_recipient": "0xa2e334e71511686bcfe38bb3ee1ad8f6babcc03d"
},
{
"enable": false,
"description": "validator two",
"deposit_gwei": "34000000000"
}
]' | jq
```
### Example Response Body
```json
@ -416,6 +553,14 @@ Validators are generated from the mnemonic according to
]
}
}
```
`lighthouse vc` will log:
```
INFO Enabled validator voting_pubkey: 0x8ffbc881fb60841a4546b4b385ec5e9b5090fd1c4395e568d98b74b94b41a912c6101113da39d43c101369eeb9b48e50, signing_method: local_keystore
INFO Modified key_cache saved successfully
INFO Disabled validator voting_pubkey: 0xa9fadd620dc68e9fe0d6e1a69f6c54a0271ad65ab5a509e645e45c6e60ff8f4fc538f301781193a08b55821444801502
```
## `POST /lighthouse/validators/keystore`
@ -474,6 +619,19 @@ Import a keystore into the validator client.
}
```
We can use [JSON to String Converter](https://jsontostring.com/) so that the above data can be properly presented as a command. The command is as below:
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X POST http://localhost:5062/lighthouse/validators/keystore \
-H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" \
-H "Content-Type: application/json" \
-d "{\"enable\":true,\"password\":\"mypassword\",\"keystore\":{\"crypto\":{\"kdf\":{\"function\":\"scrypt\",\"params\":{\"dklen\":32,\"n\":262144,\"r\":8,\"p\":1,\"salt\":\"445989ec2f332bb6099605b4f1562c0df017488d8d7fb3709f99ebe31da94b49\"},\"message\":\"\"},\"checksum\":{\"function\":\"sha256\",\"params\":{},\"message\":\"abadc1285fd38b24a98ac586bda5b17a8f93fc1ff0778803dc32049578981236\"},\"cipher\":{\"function\":\"aes-128-ctr\",\"params\":{\"iv\":\"65abb7e1d02eec9910d04299cc73efbe\"},\"message\":\"6b7931a4447be727a3bb5dc106d9f3c1ba50671648e522f213651d13450b6417\"}},\"uuid\":\"5cf2a1fb-dcd6-4095-9ebf-7e4ee0204cab\",\"path\":\"m/12381/3600/0/0/0\",\"pubkey\":\"b0d2f05014de27c6d7981e4a920799db1c512ee7922932be6bf55729039147cf35a090bd4ab378fe2d133c36cbbc9969\",\"version\":4,\"description\":\"\"}}" | jq
```
As this is an example for demonstration, the above command will return `InvalidPassword`. However, with a keystore file and correct password, running the above command will import the keystore to the validator client. An example of a success message is shown below:
### Example Response Body
```json
{
@ -484,6 +642,13 @@ Import a keystore into the validator client.
}
}
```
`lighthouse vc` will log:
```bash
INFO Enabled validator voting_pubkey: 0xb0d2f05014de27c6d7981e4a920799db1c512ee7922932be6bf55729039147cf35a090bd4ab378fe2d133c36cbb, signing_method: local_keystore
INFO Modified key_cache saved successfully
```
## `POST /lighthouse/validators/mnemonic`
@ -521,6 +686,16 @@ generated with the path `m/12381/3600/i/42`.
}
```
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X POST http://localhost:5062/lighthouse/validators/mnemonic \
-H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" \
-H "Content-Type: application/json" \
-d '{"mnemonic":" theme onion deal plastic claim silver fancy youth lock ordinary hotel elegant balance ridge web skill burger survey demand distance legal fish salad cloth","key_derivation_path_offset":0,"validators":[{"enable":true,"description":"validator_one","deposit_gwei":"32000000000"}]}' | jq
```
### Example Response Body
```json
@ -537,6 +712,13 @@ generated with the path `m/12381/3600/i/42`.
}
```
`lighthouse vc` will log:
```
INFO Enabled validator voting_pubkey: 0xa062f95fee747144d5e511940624bc6546509eeaeae9383257a9c43e7ddc58c17c2bab4ae62053122184c381b90db380, signing_method: local_keystore
INFO Modified key_cache saved successfully
```
## `POST /lighthouse/validators/web3signer`
Create any number of new validators, all of which will refer to a
@ -575,9 +757,29 @@ The following fields may be omitted or nullified to obtain default values:
- `root_certificate_path`
- `request_timeout_ms`
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X POST http://localhost:5062/lighthouse/validators/web3signer \
-H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)" \
-H "Content-Type: application/json" \
-d "[{\"enable\":true,\"description\":\"validator_one\",\"graffiti\":\"Mr F was here\",\"suggested_fee_recipient\":\"0xa2e334e71511686bcfe38bb3ee1ad8f6babcc03d\",\"voting_public_key\":\"0xa062f95fee747144d5e511940624bc6546509eeaeae9383257a9c43e7ddc58c17c2bab4ae62053122184c381b90db380\",\"url\":\"http://path-to-web3signer.com\",\"request_timeout_ms\":12000}]"
```
### Example Response Body
*No data is included in the response body.*
```json
null
```
A `null` response indicates that the request is successful. At the same time, `lighthouse vc` will log:
```
INFO Enabled validator voting_pubkey: 0xa062f95fee747144d5e511940624bc6546509eeaeae9383257a9c43e7ddc58c17c2bab4ae62053122184c381b90db380, signing_method: remote_signer
```
## `GET /lighthouse/logs`
@ -607,4 +809,4 @@ logs emitted are INFO level or higher.
"total": 1
}
}
```
```

6
book/src/api-vc.md
View File

@ -14,13 +14,13 @@ signers. It also includes some Lighthouse-specific endpoints which are described
## Starting the server
A Lighthouse validator client can be configured to expose a HTTP server by supplying the `--http` flag. The default listen address is `127.0.0.1:5062`.
A Lighthouse validator client can be configured to expose a HTTP server by supplying the `--http` flag. The default listen address is `http://127.0.0.1:5062`.
The following CLI flags control the HTTP server:
- `--http`: enable the HTTP server (required even if the following flags are
provided).
- `--http-address`: specify the listen address of the server. It is almost always unsafe to use a non-default HTTP listen address. Use with caution. See the **Security** section below for more information.
- `--http-address`: specify the listen address of the server. It is almost always unsafe to use a non-default HTTP listen address. Use this with caution. See the **Security** section below for more information.
- `--http-port`: specify the listen port of the server.
- `--http-allow-origin`: specify the value of the `Access-Control-Allow-Origin`
header. The default is to not supply a header.
@ -28,7 +28,7 @@ The following CLI flags control the HTTP server:
## Security
The validator client HTTP server is **not encrypted** (i.e., it is **not HTTPS**). For
this reason, it will listen by default on `127.0.0.1`.
this reason, it will listen by default on `http://127.0.0.1`.
It is unsafe to expose the validator client to the public Internet without
additional transport layer security (e.g., HTTPS via nginx, SSH tunnels, etc.).

37
book/src/builders.md
View File

@ -1,4 +1,4 @@
# MEV and Lighthouse
# Maximal Extractable Value (MEV)
Lighthouse is able to interact with servers that implement the [builder
API](https://github.com/ethereum/builder-specs), allowing it to produce blocks without having
@ -103,11 +103,31 @@ Each field is optional.
}
```
Command:
```bash
DATADIR=/var/lib/lighthouse
curl -X PATCH "http://localhost:5062/lighthouse/validators/0xb0148e6348264131bf47bcd1829590e870c836dc893050fd0dadc7a28949f9d0a72f2805d027521b45441101f0cc1cde" \
-H "Authorization: Bearer $(sudo cat ${DATADIR}/validators/api-token.txt)" \
-H "Content-Type: application/json" \
-d '{
"builder_proposals": true,
"gas_limit": 30000001
}' | jq
```
#### Example Response Body
```json
null
```
A `null` response indicates that the request is successful. At the same time, `lighthouse vc` will show a log which looks like:
```
INFO Published validator registrations to the builder network, count: 3, service: preparation
```
### Fee Recipient
Refer to [suggested fee recipient](suggested-fee-recipient.md) documentation.
@ -167,9 +187,18 @@ consider using it for the chance of out-sized rewards, this flag may be useful:
The number provided indicates the minimum reward that an external payload must provide the proposer for it to be considered
for inclusion in a proposal. For example, if you'd only like to use an external payload for a reward of >= 0.25 ETH, you
would provide your beacon node with `--builder-profit-threshold 250000000000000000`. If it's your turn to propose and the
most valuable payload offered by builders is only 0.1 ETH, the local execution engine's payload will be used. Currently,
this threshold just looks at the value of the external payload. No comparison to the local payload is made, although
this feature will likely be added in the future.
most valuable payload offered by builders is only 0.1 ETH, the local execution engine's payload will be used.
Since the [Capella](https://ethereum.org/en/history/#capella) upgrade, a comparison of the external payload and local payload will be made according to the [engine_getPayloadV2](https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadv2) API. The logic is as follows:
```
if local payload value >= builder payload value:
use local payload
else if builder payload value >= builder_profit_threshold or builder_profit_threshold == 0:
use builder payload
else:
use local payload
```
## Checking your builder config

6
book/src/checkpoint-sync.md
View File

@ -34,7 +34,7 @@ INFO Loaded checkpoint block and state state_root: 0xe8252c68784a8d5cc7e54
```
> **Security Note**: You should cross-reference the `block_root` and `slot` of the loaded checkpoint
> against a trusted source like a friend's node, or a block explorer.
> against a trusted source like a friend's node, a block explorer or some [public endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/).
Once the checkpoint is loaded Lighthouse will sync forwards to the head of the chain.
@ -62,6 +62,10 @@ INFO Downloading historical blocks est_time: 5 hrs 0 mins, speed: 111.96 slots/
Once backfill is complete, a `INFO Historical block download complete` log will be emitted.
> Note: Since [v4.1.0](https://github.com/sigp/lighthouse/releases/tag/v4.1.0), Lighthouse implements rate-limited backfilling to mitigate validator performance issues after a recent checkpoint sync. This means that the speed at which historical blocks are downloaded is limited, typically to less than 20 slots/sec. This will not affect validator performance. However, if you would still prefer to sync the chain as fast as possible, you can add the flag `--disable-backfill-rate-limiting` to the beacon node.
> Note: Since [v4.2.0](https://github.com/sigp/lighthouse/releases/tag/v4.2.0), Lighthouse limits the backfill sync to only sync backwards to the weak subjectivity point (approximately 5 months). This will help to save disk space. However, if you would like to sync back to the genesis, you can add the flag `--genesis-backfill` to the beacon node.
## FAQ
1. What if I have an existing database? How can I use checkpoint sync?

25
book/src/database-migrations.md
View File

@ -29,6 +29,7 @@ validator client or the slasher**.
| v3.4.0 | Jan 2023 | v13 | yes |
| v3.5.0 | Feb 2023 | v15 | yes before Capella |
| v4.0.1 | Mar 2023 | v16 | yes before Capella |
| v4.2.0 | May 2023 | v17 | yes |
> **Note**: All point releases (e.g. v2.3.1) are schema-compatible with the prior minor release
> (e.g. v2.3.0).
@ -82,24 +83,36 @@ on downgrades above.
To check the schema version of a running Lighthouse instance you can use the HTTP API:
```bash
curl "http://localhost:5052/lighthouse/database/info"
curl "http://localhost:5052/lighthouse/database/info" | jq
```
```json
{
"schema_version": 8,
"schema_version": 16,
"config": {
"slots_per_restore_point": 8192,
"slots_per_restore_point_set_explicitly": true,
"slots_per_restore_point_set_explicitly": false,
"block_cache_size": 5,
"historic_state_cache_size": 1,
"compact_on_init": false,
"compact_on_prune": true
"compact_on_prune": true,
"prune_payloads": true
},
"split": {
"slot": "5485952",
"state_root": "0xcfe5d41e6ab5a9dab0de00d89d97ae55ecaeed3b08e4acda836e69b2bef698b4"
},
"anchor": {
"anchor_slot": "5414688",
"oldest_block_slot": "0",
"oldest_block_parent": "0x0000000000000000000000000000000000000000000000000000000000000000",
"state_upper_limit": "5414912",
"state_lower_limit": "8192"
}
}
```
The `schema_version` key indicates that this database is using schema version 8.
The `schema_version` key indicates that this database is using schema version 16.
Alternatively, you can check the schema version with the `lighthouse db` command.
@ -118,7 +131,7 @@ Several conditions need to be met in order to run `lighthouse db`:
2. The command must run as the user that owns the beacon node database. If you are using systemd then
your beacon node might run as a user called `lighthousebeacon`.
3. The `--datadir` flag must be set to the location of the Lighthouse data directory.
4. The `--network` flag must be set to the correct network, e.g. `mainnet`, `prater` or `sepolia`.
4. The `--network` flag must be set to the correct network, e.g. `mainnet`, `goerli` or `sepolia`.
The general form for a `lighthouse db` command is:

2
book/src/key-management.md
View File

@ -3,7 +3,7 @@
[launchpad]: https://launchpad.ethereum.org/
>
> **Note: While Lighthouse is able to generate the validator keys and the deposit data file to submit to the deposit contract, we strongly recommend using the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) to create validators keys and the deposit data file. This is because the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) which has the option to assign a withdrawal address during the key generation process, while Lighthouse wallet will always generate keys with withdrawal credentials of type 0x00. This means that users who created keys using Lighthouse will have to update their withdrawal credentials in the future to enable withdrawals. In addition, Lighthouse generates the deposit data file in the form of `*.rlp`, which cannot be uploaded to the [Staking launchpad][launchpad] that accepts only `*.json` file. This means that users have to directly interact with the deposit contract to be able to submit the deposit if they were to generate the files using Lighthouse.**
> **Note: While Lighthouse is able to generate the validator keys and the deposit data file to submit to the deposit contract, we strongly recommend using the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) to create validators keys and the deposit data file. This is because the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) has the option to assign a withdrawal address during the key generation process, while Lighthouse wallet will always generate keys with withdrawal credentials of type 0x00. This means that users who created keys using Lighthouse will have to update their withdrawal credentials in the future to enable withdrawals. In addition, Lighthouse generates the deposit data file in the form of `*.rlp`, which cannot be uploaded to the [Staking launchpad][launchpad] that accepts only `*.json` file. This means that users have to directly interact with the deposit contract to be able to submit the deposit if they were to generate the files using Lighthouse.**
Lighthouse uses a _hierarchical_ key management system for producing validator
keys. It is hierarchical because each validator key can be _derived_ from a

35
book/src/merge-migration.md
View File

@ -1,15 +1,13 @@
# Merge Migration
This document provides detail for users who want to run a Lighthouse node on post-merge Ethereum.
> The merge occurred on mainnet in September 2022.
[The Merge](https://ethereum.org/en/roadmap/merge/) has occurred on mainnet on 15<sup>th</sup> September 2022. This document provides detail of what users need to do in the past (before The Merge) to run a Lighthouse node on a post-merge Ethereum network. This document now serves as a record of the milestone upgrade.
## Necessary Configuration
There are two configuration changes required for a Lighthouse node to operate correctly throughout
the merge:
1. You *must* run your own execution engine such as Geth or Nethermind alongside Lighthouse.
1. You *must* run your own execution engine such as Besu, Erigon, Geth or Nethermind alongside Lighthouse.
You *must* update your `lighthouse bn` configuration to connect to the execution engine using new
flags which are documented on this page in the
[Connecting to an execution engine](#connecting-to-an-execution-engine) section.
@ -23,11 +21,19 @@ engine to a merge-ready version.
## When?
You must configure your node to be merge-ready before the Bellatrix fork occurs on the network
on which your node is operating.
All networks (**Mainnet**, **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**, **Gnosis**) have successfully undergone the Bellatrix fork and transitioned to a post-merge Network. Your node must have a merge-ready configuration to continue operating. Table below lists the date at which Bellatrix and The Merge occurred:
* **Mainnet**, **Goerli (Prater)**, **Ropsten**, **Sepolia**, **Kiln**, **Gnosis**: the Bellatrix fork has
already occurred. You must have a merge-ready configuration right now.
<div align="center">
| Network | Bellatrix | The Merge | Remark |
|-------------------|--------------------------------------------|----|----|
| Ropsten | 2<sup>nd</sup> June 2022 | 8<sup>th</sup> June 2022 | Deprecated
| Sepolia | 20<sup>th</sup> June 2022 | 6<sup>th</sup> July 2022 | |
| Goerli | 4<sup>th</sup> August 2022 | 10<sup>th</sup> August 2022 | Previously named `Prater`|
| Mainnet | 6<sup>th</sup> September 2022 | 15<sup>th</sup> September 2022 |
| Gnosis| 30<sup>th</sup> November 2022 | 8<sup>th</sup> December 2022
</div>
## Connecting to an execution engine
@ -41,7 +47,7 @@ present in post-merge blocks. Two new flags are used to configure this connectio
If you set up an execution engine with `--execution-endpoint` then you *must* provide a JWT secret
using `--execution-jwt`. This is a mandatory form of authentication that ensures that Lighthouse
has authority to control the execution engine.
has the authority to control the execution engine.
> Tip: the --execution-jwt-secret-key <STRING> flag can be used instead of --execution-jwt <FILE>.
> This is useful, for example, for users who wish to inject the value into a Docker container without
@ -88,7 +94,7 @@ lighthouse \
beacon_node \
--http \
--execution-endpoint http://localhost:8551
--execution-jwt ~/.ethereum/geth/jwtsecret
--execution-jwt /path/to/jwtsecret
```
The changes here are:
@ -104,8 +110,7 @@ The changes here are:
not be `8551`, see their documentation for details.
3. Add the `--execution-jwt` flag.
- This is the path to a file containing a 32-byte secret for authenticating the BN with the
execution engine. In this example our execution engine is Geth, so we've chosen the default
location for Geth. Your execution engine might have a different path. It is critical that both
execution engine. It is critical that both
the BN and execution engine reference a file with the same value, otherwise they'll fail to
communicate.
@ -117,7 +122,7 @@ a deprecation warning will be logged and Lighthouse *may* remove these flags in
### The relationship between `--eth1-endpoints` and `--execution-endpoint`
Pre-merge users will be familiar with the `--eth1-endpoints` flag. This provides a list of Ethereum
"eth1" nodes (e.g., Geth, Nethermind, etc). Each beacon node (BN) can have multiple eth1 endpoints
"eth1" nodes (Besu, Erigon, Geth or Nethermind). Each beacon node (BN) can have multiple eth1 endpoints
and each eth1 endpoint can have many BNs connection (many-to-many relationship). The eth1 node
provides a source of truth for the [deposit
contract](https://ethereum.org/en/staking/deposit-contract/) and beacon chain proposers include this
@ -128,7 +133,7 @@ achieve this.
To progress through the Bellatrix upgrade nodes will need a *new* connection to an "eth1" node;
`--execution-endpoint`. This connection has a few different properties. Firstly, the term "eth1
node" has been deprecated and replaced with "execution engine". Whilst "eth1 node" and "execution
engine" still refer to the same projects (Geth, Nethermind, etc) the former refers to the pre-merge
engine" still refer to the same projects (Besu, Erigon, Geth or Nethermind), the former refers to the pre-merge
versions and the latter refers to post-merge versions. Secondly, there is a strict one-to-one
relationship between Lighthouse and the execution engine; only one Lighthouse node can connect to
one execution engine. Thirdly, it is impossible to fully verify the post-merge chain without an
@ -138,7 +143,7 @@ impossible to reliably *propose* blocks without it.
Since an execution engine is a hard requirement in the post-merge chain and the execution engine
contains the transaction history of the Ethereum chain, there is no longer a need for the
`--eth1-endpoints` flag for information about the deposit contract. The `--execution-endpoint` can
be used for all such queries. Therefore we can say that where `--execution-endpoint` is included
be used for all such queries. Therefore we can say that where `--execution-endpoint` is included,
`--eth1-endpoints` should be omitted.
## FAQ

12
book/src/redundancy.md
View File

@ -8,7 +8,7 @@ There are three places in Lighthouse where redundancy is notable:
1. ❌ NOT SUPPORTED: Using a redundant execution node in `lighthouse bn --execution-endpoint`
1. ☠️ BAD: Running redundant `lighthouse vc` instances with overlapping keypairs.
I mention (3) since it is unsafe and should not be confused with the other two
We mention (3) since it is unsafe and should not be confused with the other two
uses of redundancy. **Running the same validator keypair in more than one
validator client (Lighthouse, or otherwise) will eventually lead to slashing.**
See [Slashing Protection](./slashing-protection.md) for more information.
@ -49,6 +49,7 @@ There are a few interesting properties about the list of `--beacon-nodes`:
> provided (if it is desired). It will only be used as default if no `--beacon-nodes` flag is
> provided at all.
### Configuring a redundant Beacon Node
In our previous example, we listed `http://192.168.1.1:5052` as a redundant
@ -56,10 +57,9 @@ node. Apart from having sufficient resources, the backup node should have the
following flags:
- `--http`: starts the HTTP API server.
- `--http-address 0.0.0.0`: this allows *any* external IP address to access the
HTTP server (a firewall should be configured to deny unauthorized access to port
`5052`). This is only required if your backup node is on a different host.
- `--execution-endpoint`: see [Merge Migration](./merge-migration.md).
- `--http-address local_IP`: where `local_IP` is the private IP address of the computer running the beacon node. This is only required if your backup beacon node is on a different host.
> Note: You could also use `--http-address 0.0.0.0`, but this allows *any* external IP address to access the HTTP server. As such, a firewall should be configured to deny unauthorized access to port `5052`.
- `--execution-endpoint`: see [Merge Migration](./merge-migration.md).
- `--execution-jwt`: see [Merge Migration](./merge-migration.md).
For example one could use the following command to provide a backup beacon node:
@ -67,7 +67,7 @@ For example one could use the following command to provide a backup beacon node:
```bash
lighthouse bn \
--http \
--http-address 0.0.0.0 \
--http-address local_IP \
--execution-endpoint http://localhost:8551 \
--execution-jwt /secrets/jwt.hex
```

9
book/src/slasher.md
View File

@ -8,10 +8,9 @@ extra income for your validators. However it is currently only recommended for e
of the immaturity of the slasher UX and the extra resources required.
## Minimum System Requirements
* Quad-core CPU
* 16 GB RAM
* 256 GB solid state storage (in addition to space for the beacon node DB)
* 256 GB solid state storage (in addition to the space requirement for the beacon node DB)
## How to Run
@ -28,7 +27,7 @@ messages are filtered for relevancy, and all relevant messages are checked for s
to the slasher database.
You **should** run with debug logs, so that you can see the slasher's internal machinations, and
provide logs to the devs should you encounter any bugs.
provide logs to the developers should you encounter any bugs.
## Configuration
@ -97,7 +96,7 @@ Both database backends LMDB and MDBX place a hard limit on the size of the datab
file. You can use the `--slasher-max-db-size` flag to set this limit. It can be adjusted after
initialization if the limit is reached.
By default the limit is set to accommodate the default history length and around 300K validators but
By default the limit is set to accommodate the default history length and around 600K validators (with about 30% headroom) but
you can set it lower if running with a reduced history length. The space required scales
approximately linearly in validator count and history length, i.e. if you halve either you can halve
the space required.
@ -108,7 +107,7 @@ If you want an estimate of the database size you can use this formula:
4.56 GB * (N / 256) * (V / 250000)
```
where `V` is the validator count and `N` is the history length.
where `N` is the history length and `V` is the validator count.
You should set the maximum size higher than the estimate to allow room for growth in the validator
count.

10
book/src/suggested-fee-recipient.md
View File

@ -103,6 +103,8 @@ client.
}
```
Command:
```bash
DATADIR=$HOME/.lighthouse/mainnet
PUBKEY=0xa9735061c84fc0003657e5bd38160762b7ef2d67d280e00347b1781570088c32c06f15418c144949f5d736b1d3a6c591
@ -115,11 +117,15 @@ curl -X POST \
http://localhost:5062/eth/v1/validator/${PUBKEY}/feerecipient | jq
```
Note that an authorization header is required to interact with the API. This is specified with the header `-H "Authorization: Bearer $(cat ${DATADIR}/validators/api-token.txt)"` which read the API token to supply the authentication. Refer to [Authorization Header](./api-vc-auth-header.md) for more information. If you are having permission issue with accessing the API token file, you can modify the header to become `-H "Authorization: Bearer $(sudo cat ${DATADIR}/validators/api-token.txt)"`.
#### Successful Response (202)
```json
null
```
A `null` response indicates that the request is successful.
### Querying the fee recipient
The same path with a `GET` request can be used to query the fee recipient for a given public key at any time.
@ -131,6 +137,8 @@ The same path with a `GET` request can be used to query the fee recipient for a
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 200, 404 |
Command:
```bash
DATADIR=$HOME/.lighthouse/mainnet
PUBKEY=0xa9735061c84fc0003657e5bd38160762b7ef2d67d280e00347b1781570088c32c06f15418c144949f5d736b1d3a6c591
@ -163,6 +171,8 @@ This is useful if you want the fee recipient to fall back to the validator clien
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
| Typical Responses | 204, 404 |
Command:
```bash
DATADIR=$HOME/.lighthouse/mainnet
PUBKEY=0xa9735061c84fc0003657e5bd38160762b7ef2d67d280e00347b1781570088c32c06f15418c144949f5d736b1d3a6c591

4
book/src/validator-inclusion.md
View File

@ -8,6 +8,8 @@ These endpoints are not stable or included in the Ethereum consensus standard AP
they are subject to change or removal without a change in major release
version.
In order to apply these APIs, you need to have historical states information in the database of your node. This means adding the flag `--reconstruct-historic-states` in the beacon node or using the [/lighthouse/database/reconstruct API](./api-lighthouse.md#lighthousedatabasereconstruct). Once the state reconstruction process is completed, you can apply these APIs to any epoch.
## Endpoints
HTTP Path | Description |
@ -29,7 +31,7 @@ is not the case for attestations from the _previous_ epoch.
```
`epoch` query parameter
|
| --------- values are calcuated here
| --------- values are calculated here
| |
v v
Epoch: |---previous---|---current---|---next---|

4
book/src/validator-web3signer.md
View File

@ -5,7 +5,7 @@
[Teku]: https://github.com/consensys/teku
[Web3Signer] is a tool by Consensys which allows *remote signing*. Remote signing is when a
Validator Client (VC) out-sources the signing of messages to remote server (e.g., via HTTPS). This
Validator Client (VC) out-sources the signing of messages to a remote server (e.g., via HTTPS). This
means that the VC does not hold the validator private keys.
## Warnings
@ -47,7 +47,7 @@ remote signer:
client_identity_password: "password"
```
When using this file, the Lighthouse VC will perform duties for the `0xa5566..` validator and defer
When using this file, the Lighthouse VC will perform duties for the `0xa5566..` validator and refer
to the `https://my-remote-signer.com:1234` server to obtain any signatures. It will load a
"self-signed" SSL certificate from `/home/paul/my-certificates/my-remote-signer.pem` (on the
filesystem of the VC) to encrypt the communications between the VC and Web3Signer. It will use