Skip to content

Commit 3f6c11d

Browse files
authored
Some updates to Lighthouse book (#6995)
* #6447 - Move some deprecated pages to a new section under `Archived` - Remove fallback log in mev as the log will not be present after VC using `/eth/v3/validator/blocks` endpoint by default - Add warning against using Btrfs file system (thank you @ChosunOne for the report) - Add data shared by @mcdee on tree states API queries time - Rename partial withdrawals to validator sweep to differentiate it from the upcoming execution layer partial withdrawals - Update NAT API response - Update docs on IPv6 - Rename .md files to follow a standard prefix section name, e.g., installation_*.md, advanced_*.md - Standardise .md files using underscore `_` instead of hyphen `-` to be consistent with other files naming conventions.
1 parent 2f37bf4 commit 3f6c11d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+221
-264
lines changed

book/.markdownlint.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ MD010:
88
MD013: false
99

1010
# MD028: set to false to allow blank line between blockquote: https://github.com/DavidAnson/markdownlint/blob/main/doc/md028.md
11-
# This is because the blockquotes are shown separatedly (a deisred outcome) when having a blank line in between
11+
# This is because the blockquotes are shown separately (a desired outcome) when having a blank line in between
1212
MD028: false
1313

1414
# MD024: set siblings_only to true so that same headings with different parent headings are allowed

book/src/SUMMARY.md

Lines changed: 48 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,58 +2,54 @@
22

33
* [Introduction](./intro.md)
44
* [Installation](./installation.md)
5-
* [Pre-Built Binaries](./installation-binaries.md)
6-
* [Docker](./docker.md)
7-
* [Build from Source](./installation-source.md)
8-
* [Raspberry Pi 4](./pi.md)
9-
* [Cross-Compiling](./cross-compiling.md)
10-
* [Homebrew](./homebrew.md)
11-
* [Update Priorities](./installation-priorities.md)
5+
* [Pre-Built Binaries](./installation_binaries.md)
6+
* [Docker](./installation_docker.md)
7+
* [Build from Source](./installation_source.md)
8+
* [Cross-Compiling](./installation_cross_compiling.md)
9+
* [Homebrew](./installation_homebrew.md)
10+
* [Update Priorities](./installation_priorities.md)
1211
* [Run a Node](./run_a_node.md)
13-
* [Become a Validator](./mainnet-validator.md)
14-
* [Validator Management](./validator-management.md)
15-
* [The `validator-manager` Command](./validator-manager.md)
16-
* [Creating validators](./validator-manager-create.md)
17-
* [Moving validators](./validator-manager-move.md)
18-
* [Managing validators](./validator-manager-api.md)
19-
* [Slashing Protection](./slashing-protection.md)
20-
* [Voluntary Exits](./voluntary-exit.md)
21-
* [Partial Withdrawals](./partial-withdrawal.md)
22-
* [Validator Monitoring](./validator-monitoring.md)
23-
* [Doppelganger Protection](./validator-doppelganger.md)
24-
* [Suggested Fee Recipient](./suggested-fee-recipient.md)
25-
* [Validator Graffiti](./graffiti.md)
12+
* [Become a Validator](./mainnet_validator.md)
13+
* [Validator Management](./validator_management.md)
14+
* [The `validator-manager` Command](./validator_manager.md)
15+
* [Creating validators](./validator_manager_create.md)
16+
* [Moving validators](./validator_manager_move.md)
17+
* [Managing validators](./validator_manager_api.md)
18+
* [Slashing Protection](./validator_slashing_protection.md)
19+
* [Voluntary Exits](./validator_voluntary_exit.md)
20+
* [Validator Sweep](./validator_sweep.md)
21+
* [Validator Monitoring](./validator_monitoring.md)
22+
* [Doppelganger Protection](./validator_doppelganger.md)
23+
* [Suggested Fee Recipient](./validator_fee_recipient.md)
24+
* [Validator Graffiti](./validator_graffiti.md)
2625
* [APIs](./api.md)
27-
* [Beacon Node API](./api-bn.md)
28-
* [Lighthouse API](./api-lighthouse.md)
29-
* [Validator Inclusion APIs](./validator-inclusion.md)
30-
* [Validator Client API](./api-vc.md)
31-
* [Endpoints](./api-vc-endpoints.md)
32-
* [Authorization Header](./api-vc-auth-header.md)
33-
* [Signature Header](./api-vc-sig-header.md)
34-
* [Prometheus Metrics](./advanced_metrics.md)
35-
* [Lighthouse UI (Siren)](./lighthouse-ui.md)
36-
* [Configuration](./ui-configuration.md)
37-
* [Authentication](./ui-authentication.md)
38-
* [Usage](./ui-usage.md)
39-
* [FAQs](./ui-faqs.md)
26+
* [Beacon Node API](./api_bn.md)
27+
* [Lighthouse API](./api_lighthouse.md)
28+
* [Validator Inclusion APIs](./api_validator_inclusion.md)
29+
* [Validator Client API](./api_vc.md)
30+
* [Endpoints](./api_vc_endpoints.md)
31+
* [Authorization Header](./api_vc_auth_header.md)
32+
* [Prometheus Metrics](./api_metrics.md)
33+
* [Lighthouse UI (Siren)](./ui.md)
34+
* [Configuration](./ui_configuration.md)
35+
* [Authentication](./ui_authentication.md)
36+
* [Usage](./ui_usage.md)
37+
* [FAQs](./ui_faqs.md)
4038
* [Advanced Usage](./advanced.md)
41-
* [Checkpoint Sync](./checkpoint-sync.md)
42-
* [Custom Data Directories](./advanced-datadir.md)
43-
* [Proposer Only Beacon Nodes](./advanced-proposer-only.md)
44-
* [Remote Signing with Web3Signer](./validator-web3signer.md)
39+
* [Checkpoint Sync](./advanced_checkpoint_sync.md)
40+
* [Custom Data Directories](./advanced_datadir.md)
41+
* [Proposer Only Beacon Nodes](./advanced_proposer_only.md)
42+
* [Remote Signing with Web3Signer](./advanced_web3signer.md)
4543
* [Database Configuration](./advanced_database.md)
46-
* [Database Migrations](./database-migrations.md)
47-
* [Key Management (Deprecated)](./key-management.md)
48-
* [Key Recovery](./key-recovery.md)
44+
* [Database Migrations](./advanced_database_migrations.md)
45+
* [Key Recovery](./advanced_key_recovery.md)
4946
* [Advanced Networking](./advanced_networking.md)
50-
* [Running a Slasher](./slasher.md)
51-
* [Redundancy](./redundancy.md)
52-
* [Release Candidates](./advanced-release-candidates.md)
53-
* [MEV](./builders.md)
54-
* [Merge Migration](./merge-migration.md)
55-
* [Late Block Re-orgs](./late-block-re-orgs.md)
56-
* [Blobs](./advanced-blobs.md)
47+
* [Running a Slasher](./advanced_slasher.md)
48+
* [Redundancy](./advanced_redundancy.md)
49+
* [Release Candidates](./advanced_release_candidates.md)
50+
* [MEV](./advanced_builders.md)
51+
* [Late Block Re-orgs](./advanced_re-orgs.md)
52+
* [Blobs](./advanced_blobs.md)
5753
* [Command Line Reference (CLI)](./help_general.md)
5854
* [Beacon Node](./help_bn.md)
5955
* [Validator Client](./help_vc.md)
@@ -62,7 +58,11 @@
6258
* [Import](./help_vm_import.md)
6359
* [Move](./help_vm_move.md)
6460
* [Contributing](./contributing.md)
65-
* [Development Environment](./setup.md)
61+
* [Development Environment](./contributing_setup.md)
6662
* [FAQs](./faq.md)
6763
* [Protocol Developers](./developers.md)
6864
* [Security Researchers](./security.md)
65+
* [Archived](./archived.md)
66+
* [Merge Migration](./archived_merge_migration.md)
67+
* [Raspberry Pi 4](./archived_pi.md)
68+
* [Key Management](./archived_key_management.md)

book/src/advanced.md

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,17 @@ elsewhere?
66
This section provides detailed information about configuring Lighthouse for specific use cases, and
77
tips about how things work under the hood.
88

9-
* [Checkpoint Sync](./checkpoint-sync.md): quickly sync the beacon chain to perform validator duties.
10-
* [Custom Data Directories](./advanced-datadir.md): modify the data directory to your preferred location.
11-
* [Proposer Only Beacon Nodes](./advanced-proposer-only.md): beacon node only for proposer duty for increased anonymity.
12-
* [Remote Signing with Web3Signer](./validator-web3signer.md): don't want to store your keystore in local node? Use web3signer.
9+
* [Checkpoint Sync](./advanced_checkpoint_sync.md): quickly sync the beacon chain to perform validator duties.
10+
* [Custom Data Directories](./advanced_datadir.md): modify the data directory to your preferred location.
11+
* [Proposer Only Beacon Nodes](./advanced_proposer_only.md): beacon node only for proposer duty for increased anonymity.
12+
* [Remote Signing with Web3Signer](./advanced_web3signer.md): don't want to store your keystore in local node? Use web3signer.
1313
* [Database Configuration](./advanced_database.md): understanding space-time trade-offs in the database.
14-
* [Database Migrations](./database-migrations.md): have a look at all previous Lighthouse database scheme versions.
15-
* [Key Management](./key-management.md): explore how to generate wallet with Lighthouse.
16-
* [Key Recovery](./key-recovery.md): explore how to recover wallet and validator with Lighthouse.
14+
* [Database Migrations](./advanced_database_migrations.md): have a look at all previous Lighthouse database scheme versions.
15+
* [Key Recovery](./advanced_key_recovery.md): explore how to recover wallet and validator with Lighthouse.
1716
* [Advanced Networking](./advanced_networking.md): open your ports to have a diverse and healthy set of peers.
18-
* [Running a Slasher](./slasher.md): contribute to the health of the network by running a slasher.
19-
* [Redundancy](./redundancy.md): want to have more than one beacon node as backup? This is for you.
20-
* [Release Candidates](./advanced-release-candidates.md): latest release of Lighthouse to get feedback from users.
21-
* [Maximal Extractable Value](./builders.md): use external builders for a potential higher rewards during block proposals
22-
* [Merge Migration](./merge-migration.md): look at what you need to do during a significant network upgrade: The Merge
23-
* [Late Block Re-orgs](./late-block-re-orgs.md): read information about Lighthouse late block re-orgs.
24-
* [Blobs](./advanced-blobs.md): information about blobs in Deneb upgrade
17+
* [Running a Slasher](./advanced_slasher.md): contribute to the health of the network by running a slasher.
18+
* [Redundancy](./advanced_redundancy.md): want to have more than one beacon node as backup? This is for you.
19+
* [Release Candidates](./advanced_release_candidates.md): latest release of Lighthouse to get feedback from users.
20+
* [Maximal Extractable Value](./advanced_builders.md): use external builders for a potential higher rewards during block proposals
21+
* [Late Block Re-orgs](./advanced_re-orgs.md): read information about Lighthouse late block re-orgs.
22+
* [Blobs](./advanced_blobs.md): information about blobs in Deneb upgrade
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,4 +38,4 @@ In the Deneb network upgrade, one of the changes is the implementation of EIP-48
3838
curl "http://localhost:5052/lighthouse/database/info" | jq
3939
```
4040

41-
Refer to [Lighthouse API](./api-lighthouse.md#lighthousedatabaseinfo) for an example response.
41+
Refer to [Lighthouse API](./api_lighthouse.md#lighthousedatabaseinfo) for an example response.
Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -83,11 +83,11 @@ is something afoot.
8383

8484
To update gas limit per-validator you can use the [standard key manager API][gas-limit-api].
8585

86-
Alternatively, you can use the [lighthouse API](api-vc-endpoints.md). See below for an example.
86+
Alternatively, you can use the [lighthouse API](api_vc_endpoints.md). See below for an example.
8787

8888
### Enable/Disable builder proposals via HTTP
8989

90-
Use the [lighthouse API](api-vc-endpoints.md) to enable/disable use of the builder API on a per-validator basis.
90+
Use the [lighthouse API](api_vc_endpoints.md) to enable/disable use of the builder API on a per-validator basis.
9191
You can also update the configured gas limit with these requests.
9292

9393
#### `PATCH /lighthouse/validators/:voting_pubkey`
@@ -98,7 +98,7 @@ You can also update the configured gas limit with these requests.
9898
|-------------------|--------------------------------------------|
9999
| Path | `/lighthouse/validators/:voting_pubkey` |
100100
| Method | PATCH |
101-
| Required Headers | [`Authorization`](./api-vc-auth-header.md) |
101+
| Required Headers | [`Authorization`](./api_vc_auth_header.md) |
102102
| Typical Responses | 200, 400 |
103103

104104
#### Example Path
@@ -147,7 +147,7 @@ INFO Published validator registrations to the builder network, count: 3, service
147147

148148
### Fee Recipient
149149

150-
Refer to [suggested fee recipient](suggested-fee-recipient.md) documentation.
150+
Refer to [suggested fee recipient](validator_fee_recipient.md) documentation.
151151

152152
### Validator definitions example
153153

@@ -244,16 +244,9 @@ INFO Builder payload ignored
244244
INFO Chain is unhealthy, using local payload
245245
```
246246

247-
In case of fallback you should see a log indicating that the locally produced payload was
248-
used in place of one from the builder:
249-
250-
```text
251-
INFO Reconstructing a full block using a local payload
252-
```
253-
254247
## Information for block builders and relays
255248

256-
Block builders and relays can query beacon node events from the [Events API](https://ethereum.github.io/beacon-APIs/#/Events/eventstream). An example of querying the payload attributes in the Events API is outlined in [Beacon node API - Events API](./api-bn.md#events-api)
249+
Block builders and relays can query beacon node events from the [Events API](https://ethereum.github.io/beacon-APIs/#/Events/eventstream). An example of querying the payload attributes in the Events API is outlined in [Beacon node API - Events API](./api_bn.md#events-api)
257250

258251
[mev-rs]: https://github.com/ralexstokes/mev-rs
259252
[mev-boost]: https://github.com/flashbots/mev-boost
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ Important information to be aware of:
134134
* It is safe to interrupt state reconstruction by gracefully terminating the node – it will pick up
135135
from where it left off when it restarts.
136136
* You can start reconstruction from the HTTP API, and view its progress. See the
137-
[`/lighthouse/database`](./api-lighthouse.md) APIs.
137+
[`/lighthouse/database`](./api_lighthouse.md) APIs.
138138

139139
For more information on historic state storage see the
140140
[Database Configuration](./advanced_database.md) page.

book/src/advanced_database.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,26 @@ that we have observed are:
6161
to apply. We observed no significant performance benefit from `--hierarchy-exponents 5,7,11`, and
6262
a substantial increase in space consumed.
6363

64+
The following table lists the data for different configurations. Note that the disk space requirement is for the `chain_db` and `freezer_db`, excluding the `blobs_db`.
65+
66+
| Hierarchy Exponents | Storage Requirement | Sequential Slot Query | Uncached Query | Time to Sync |
67+
|---|---|---|---|---|
68+
| 5,9,11,13,16,18,21 (default) | 418 GiB | 250-700 ms | up to 10 s | 1 week |
69+
| 5,7,11 (frequent snapshots) | 589 GiB | 250-700 ms | up to 6 s | 1 week |
70+
| 0,5,7,11 (per-slot diffs) | 2500 GiB | 250-700 ms | up to 4 s | 7 weeks |
71+
72+
[Jim](https://github.com/mcdee) has done some experiments to study the response time of querying random slots (uncached query) for `--hierarchy-exponents 0,5,7,11` (per-slot diffs) and `--hierarchy-exponents 5,9,11,13,17,21` (per-epoch diffs), as show in the figures below. From the figures, two points can be concluded:
73+
74+
- response time (y-axis) increases with slot number (x-axis) due to state growth.
75+
- response time for per-slot configuration in general is 2x faster than that of per-epoch.
76+
77+
In short, setting different configurations is a trade-off between disk space requirement, sync time and response time. The data presented here is useful to help users choosing the configuration that suit their needs.
78+
79+
_We acknowledge the data provided by [Jim](https://github.com/mcdee) and his consent for us to share it here._
80+
81+
![Response time for per-epoch archive](./imgs/per-epoch.png)
82+
![Response time for per-slot archive](./imgs/per-slot.png)
83+
6484
If in doubt, we recommend running with the default configuration! It takes a long time to
6585
reconstruct states in any given configuration, so it might be some time before the optimal
6686
configuration is determined.
File renamed without changes.
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ lighthouse --network mainnet --datadir /var/lib/my-custom-dir bn --staking
1212
lighthouse --network mainnet --datadir /var/lib/my-custom-dir vc
1313
```
1414

15-
The first step creates a `validators` directory under `/var/lib/my-custom-dir` which contains the imported keys and [`validator_definitions.yml`](./validator-management.md).
15+
The first step creates a `validators` directory under `/var/lib/my-custom-dir` which contains the imported keys and [`validator_definitions.yml`](./validator_management.md).
1616
After that, we simply run the beacon chain and validator client with the custom dir path.
1717

1818
## Relative Paths
File renamed without changes.

0 commit comments

Comments
 (0)