Skip to content

Commit e02adbf

Browse files
michaelsproulchong-he
michaelsproul
and
chong-he
authored
Update docs for v4.6.0 (#4982)
* Update DB migration docs * Document VC broadcast modes * Update downgrade example (#6) * update downgrade example * Add period * Add v4.1.0 --------- Co-authored-by: chonghe <[email protected]>
1 parent 6c0c41c commit e02adbf

File tree

2 files changed

+77
-32
lines changed

2 files changed

+77
-32
lines changed

‎book/src/database-migrations.md

Lines changed: 49 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -16,37 +16,32 @@ validator client or the slasher**.
1616

1717
| Lighthouse version | Release date | Schema version | Downgrade available? |
1818
|--------------------|--------------|----------------|----------------------|
19-
| v2.0.0 | Oct 2021 | v5 | no |
20-
| v2.1.0 | Jan 2022 | v8 | no |
21-
| v2.2.0 | Apr 2022 | v8 | no |
22-
| v2.3.0 | May 2022 | v9 | yes from <= v3.3.0 |
23-
| v2.4.0 | Jul 2022 | v9 | yes from <= v3.3.0 |
24-
| v2.5.0 | Aug 2022 | v11 | yes |
25-
| v3.0.0 | Aug 2022 | v11 | yes |
26-
| v3.1.0 | Sep 2022 | v12 | yes |
27-
| v3.2.0 | Oct 2022 | v12 | yes |
28-
| v3.3.0 | Nov 2022 | v13 | yes |
29-
| v3.4.0 | Jan 2023 | v13 | yes |
30-
| v3.5.0 | Feb 2023 | v15 | yes before Capella |
31-
| v4.0.1 | Mar 2023 | v16 | yes before Capella |
19+
| v4.6.0 | Dec 2023 | v18 | yes before Deneb |
20+
| v4.5.0 | Sep 2023 | v17 | yes |
21+
| v4.4.0 | Aug 2023 | v17 | yes |
22+
| v4.3.0 | Jul 2023 | v17 | yes |
3223
| v4.2.0 | May 2023 | v17 | yes |
24+
| v4.1.0 | Apr 2023 | v16 | no |
25+
| v4.0.1 | Mar 2023 | v16 | no |
3326

34-
> **Note**: All point releases (e.g. v2.3.1) are schema-compatible with the prior minor release
35-
> (e.g. v2.3.0).
27+
> **Note**: All point releases (e.g. v4.4.1) are schema-compatible with the prior minor release
28+
> (e.g. v4.4.0).
3629
3730
> **Note**: Support for old schemas is gradually removed from newer versions of Lighthouse. We
38-
usually do this after a major version has been out for a while and everyone has upgraded. In this
39-
case the above table will continue to record the deprecated schema changes for reference.
31+
usually do this after a major version has been out for a while and everyone has upgraded. Deprecated
32+
schema versions for previous releases are archived under
33+
[Full list of schema versions](#full-list-of-schema-versions). If you get stuck and are unable
34+
to upgrade a **testnet** node to the latest version, sometimes it is possible to upgrade via an
35+
intermediate version (e.g. upgrade from v3.5.0 to v4.6.0 via v4.0.1). This is never necessary
36+
on mainnet.
4037

4138
## How to apply a database downgrade
4239

4340
To apply a downgrade you need to use the `lighthouse db migrate` command with the correct parameters.
4441

4542
1. Make sure you have a copy of the latest version of Lighthouse. This will be the version that
4643
knows about the latest schema change, and has the ability to revert it.
47-
2. Work out the schema version you would like to downgrade to by checking the table above, or the
48-
Lighthouse release notes. E.g. if you want to downgrade from v2.3.0, which upgraded the version
49-
from v8 to v9, then you'll want to _downgrade_ to v8 in order to run v2.2.x or earlier.
44+
2. Work out the schema version you would like to downgrade to by checking the table above, or the [Full list of schema versions](#full-list-of-schema-versions) below. E.g. if you want to downgrade from v4.2.0, which upgraded the version from v16 to v17, then you'll want to downgrade to v16 in order to run v4.0.1.
5045
3. **Ensure that downgrading is feasible**. Not all schema upgrades can be reverted, and some of
5146
them are time-sensitive. The release notes will state whether a downgrade is available and
5247
whether any caveats apply to it.
@@ -59,14 +54,13 @@ To apply a downgrade you need to use the `lighthouse db migrate` command with th
5954
sudo -u "$LH_USER" lighthouse db migrate --to "$VERSION" --datadir "$LH_DATADIR" --network "$NET"
6055
```
6156

62-
For example if you want to downgrade to Lighthouse v2.1 or v2.2 from v2.3 and you followed Somer
63-
Esat's guide, you would run:
57+
For example if you want to downgrade to Lighthouse v4.0.1 from v4.2.0 and you followed Somer Esat's guide, you would run:
6458

6559
```
66-
sudo -u lighthousebeacon lighthouse db migrate --to 8 --datadir /var/lib/lighthouse --network mainnet
60+
sudo -u lighthousebeacon lighthouse db migrate --to 16 --datadir /var/lib/lighthouse --network mainnet
6761
```
6862

69-
Where `lighthouse` is Lighthouse v2.3.0+. After the downgrade succeeds you can then replace your
63+
Where `lighthouse` is Lighthouse v4.2.0+. After the downgrade succeeds you can then replace your
7064
global `lighthouse` binary with the older version and start your node again.
7165

7266
## How to apply a database upgrade
@@ -161,35 +155,59 @@ lighthouse db version --network mainnet
161155

162156
## How to prune historic states
163157

164-
Pruning historic states helps in managing the disk space used by the Lighthouse beacon node by removing old beacon
165-
states from the freezer database. This can be especially useful when the database has accumulated a significant amount
166-
of historic data. This command is intended for nodes synced before 4.4.1, as newly synced node no longer store
158+
Pruning historic states helps in managing the disk space used by the Lighthouse beacon node by removing old beacon
159+
states from the freezer database. This can be especially useful when the database has accumulated a significant amount
160+
of historic data. This command is intended for nodes synced before 4.4.1, as newly synced node no longer store
167161
historic states by default.
168162

169163
Here are the steps to prune historic states:
170164

171165
1. Before running the prune command, make sure that the Lighthouse beacon node is not running. If you are using systemd, you might stop the Lighthouse beacon node with a command like:
172-
166+
173167
```bash
174168
sudo systemctl stop lighthousebeacon
175169
```
176170

177171
2. Use the `prune-states` command to prune the historic states. You can do a test run without the `--confirm` flag to check that the database can be pruned:
178-
172+
179173
```bash
180174
sudo -u "$LH_USER" lighthouse db prune-states --datadir "$LH_DATADIR" --network "$NET"
181175
```
182176

183177
3. If you are ready to prune the states irreversibly, add the `--confirm` flag to commit the changes:
184-
178+
185179
```bash
186180
sudo -u "$LH_USER" lighthouse db prune-states --confirm --datadir "$LH_DATADIR" --network "$NET"
187181
```
188182

189183
The `--confirm` flag ensures that you are aware the action is irreversible, and historic states will be permanently removed.
190184

191185
4. After successfully pruning the historic states, you can restart the Lighthouse beacon node:
192-
186+
193187
```bash
194188
sudo systemctl start lighthousebeacon
195189
```
190+
191+
## Full list of schema versions
192+
193+
| Lighthouse version | Release date | Schema version | Downgrade available? |
194+
|--------------------|--------------|----------------|-------------------------------------|
195+
| v4.6.0 | Dec 2023 | v18 | yes before Deneb |
196+
| v4.5.0 | Sep 2023 | v17 | yes |
197+
| v4.4.0 | Aug 2023 | v17 | yes |
198+
| v4.3.0 | Jul 2023 | v17 | yes |
199+
| v4.2.0 | May 2023 | v17 | yes |
200+
| v4.1.0 | Apr 2023 | v16 | yes before Capella using <= v4.5.0 |
201+
| v4.0.1 | Mar 2023 | v16 | yes before Capella using <= v4.5.0 |
202+
| v3.5.0 | Feb 2023 | v15 | yes before Capella using <= v4.5.0 |
203+
| v3.4.0 | Jan 2023 | v13 | yes using <= 4.5.0 |
204+
| v3.3.0 | Nov 2022 | v13 | yes using <= 4.5.0 |
205+
| v3.2.0 | Oct 2022 | v12 | yes using <= 4.5.0 |
206+
| v3.1.0 | Sep 2022 | v12 | yes using <= 4.5.0 |
207+
| v3.0.0 | Aug 2022 | v11 | yes using <= 4.5.0 |
208+
| v2.5.0 | Aug 2022 | v11 | yes using <= 4.5.0 |
209+
| v2.4.0 | Jul 2022 | v9 | yes using <= v3.3.0 |
210+
| v2.3.0 | May 2022 | v9 | yes using <= v3.3.0 |
211+
| v2.2.0 | Apr 2022 | v8 | no |
212+
| v2.1.0 | Jan 2022 | v8 | no |
213+
| v2.0.0 | Oct 2021 | v5 | no |

‎book/src/redundancy.md

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,34 @@ lighthouse bn \
7575
Prior to v3.2.0 fallback beacon nodes also required the `--subscribe-all-subnets` and
7676
`--import-all-attestations` flags. These flags are no longer required as the validator client will
7777
now broadcast subscriptions to all connected beacon nodes by default. This broadcast behaviour
78-
can be disabled using the `--disable-run-on-all` flag for `lighthouse vc`.
78+
can be disabled using the `--broadcast none` flag for `lighthouse vc` (or `--disable-run-on-all`
79+
[deprecated]).
80+
81+
### Broadcast modes
82+
83+
Since v4.6.0, the Lighthouse VC can be configured to broadcast messages to all configured beacon
84+
nodes rather than just the first available.
85+
86+
The flag to control this behaviour is `--broadcast`, which takes multiple comma-separated values
87+
from this list:
88+
89+
- `subscriptions`: Send subnet subscriptions & other control messages which keep the beacon nodes
90+
primed and ready to process messages. It is recommended to leave this enabled.
91+
- `attestations`: Send attestations & aggregates to all beacon nodes. This can improve
92+
propagation of attestations throughout the network, at the cost of increased load on the beacon
93+
nodes and increased bandwidth between the VC and the BNs.
94+
- `blocks`: Send proposed blocks to all beacon nodes. This can improve propagation of blocks
95+
throughout the network, at the cost of slightly increased load on the beacon nodes and increased
96+
bandwidth between the VC and the BNs. If you are looking to improve performance in a multi-BN
97+
setup this is the first option we would recommend enabling.
98+
- `sync-committee`: Send sync committee signatures & aggregates to all beacon nodes. This can
99+
improve propagation of sync committee messages with similar tradeoffs to broadcasting
100+
attestations, although occuring less often due to the infrequency of sync committee duties.
101+
- `none`: Disable all broadcasting. This option only has an effect when provided alone, otherwise
102+
it is ignored. Not recommended except for expert tweakers.
103+
104+
The default is `--broadcast subscriptions`. To also broadcast blocks for example, use
105+
`--broadcast subscriptions,blocks`.
79106

80107
## Redundant execution nodes
81108

0 commit comments

Comments
 (0)