Skip to content

Commit c9af6c3

Browse files
philknowsnflaig
andauthored
docs: update documentation Oct 2024 (#7178)
* docs update oct 2024 init * Reconfig quickstart nav and minor fixes * fix lint * spelling fixes * minor fixes and add to wordlist * prettier fix * add to wordlist * sort wordlist * modify dominance to include lighthouse * fix typescript casing and add recommendation * add selection and boost_factor with keymanager notice * update wordlist * remove builder enabled and add keymanager api * spelling --------- Co-authored-by: Nico Flaig <nflaig@protonmail.com>
1 parent aaac34a commit c9af6c3

21 files changed

+954
-138
lines changed

.wordlist.txt

+26
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
API
12
APIs
23
Andreas
34
Antonopoulos
@@ -13,6 +14,7 @@ Casper
1314
Chai
1415
ChainSafe
1516
Codespaces
17+
CoinCashew
1618
Corepack
1719
Customizations
1820
DPoS
@@ -29,6 +31,7 @@ ENRs
2931
ETH
3032
Edgington
3133
Erigon
34+
Esat
3235
EthStaker
3336
EtherScan
3437
Ethereum
@@ -37,15 +40,19 @@ FINDNODE
3740
FX
3841
Flamegraph
3942
Flamegraphs
43+
GPG
4044
Geth
4145
Github
46+
Goerli
47+
Golang
4248
Gossipsub
4349
Grafana
4450
Grandine
4551
HTTPS
4652
HackMD
4753
Hashicorp
4854
Homebrew
55+
Hyperledger
4956
IPFS
5057
IPv
5158
Infura
@@ -60,15 +67,18 @@ LGPLv
6067
LMD
6168
LPoS
6269
LTS
70+
LVM
6371
Lerna
6472
MEV
6573
MacOS
6674
Metamask
75+
MevBoost
6776
ModuleNotFoundError
6877
Monorepo
6978
NPM
7079
NVM
7180
Nethermind
81+
Nim
7282
NodeJS
7383
NodeSource
7484
OSI
@@ -81,9 +91,11 @@ Quickstart
8191
RPC
8292
Reth
8393
Ryzen
94+
SFTP
8495
SHA
8596
SSD
8697
SSZ
98+
Somer
8799
Stakehouse
88100
TOC
89101
TTD
@@ -103,13 +115,15 @@ backfill
103115
beaconcha
104116
blockRoot
105117
blockchain
118+
blockspace
106119
blst
107120
bootnode
108121
bootnodes
109122
bundlers
110123
chainConfig
111124
chainsafe
112125
chiado
126+
chmod
113127
cli
114128
cmd
115129
codebase
@@ -125,6 +139,8 @@ dApp
125139
dApps
126140
ddos
127141
decrypt
142+
decrypted
143+
derypted
128144
deserialization
129145
dev
130146
devcontainer
@@ -139,30 +155,38 @@ env
139155
envs
140156
ephemery
141157
ethers
158+
feeRecipient
142159
flamegraph
143160
flamegraphs
144161
floodsub
162+
fsSL
145163
getNetworkIdentity
146164
gnosis
165+
gpg
147166
heapdump
148167
heaptrack
149168
holesky
150169
interop
151170
js
171+
keymanager
152172
keypair
173+
keyrings
153174
keystore
154175
keystores
155176
libp
156177
lightclient
157178
linter
179+
liveness
158180
lldb
159181
llnode
160182
lockfile
161183
mainnet
162184
malloc
185+
mbps
163186
mdns
164187
merkle
165188
merkleization
189+
misconfiguration
166190
mmeshsub
167191
monorepo
168192
multiaddr
@@ -199,6 +223,7 @@ ssz
199223
stakers
200224
subnet
201225
subnets
226+
sudo
202227
tcp
203228
testnet
204229
testnets
@@ -215,6 +240,7 @@ vite
215240
vitest
216241
webpack
217242
wip
243+
xRelayPubKey
218244
xcode
219245
yaml
220246
yamux

docs/docusaurus.config.ts

+13-19
Original file line numberDiff line numberDiff line change
@@ -97,29 +97,23 @@ const config: Config = {
9797
style: "dark",
9898
links: [
9999
{
100-
title: "Docs",
101-
items: [
102-
{
103-
label: "Introduction",
104-
to: "/introduction",
105-
},
106-
],
100+
label: 'Lodestar Website',
101+
href: 'https://lodestar.chainsafe.io',
107102
},
108103
{
109-
title: "Community",
110-
items: [
111-
{
112-
label: "Discord",
113-
href: "https://discord.com/invite/yjyvFRP",
114-
},
115-
{
116-
label: "Twitter",
117-
href: "https://twitter.com/lodestar_eth",
118-
},
119-
],
104+
label: 'Discord',
105+
href: 'https://discord.com/invite/yjyvFRP',
106+
},
107+
{
108+
label: 'Twitter/X',
109+
href: 'https://x.com/lodestar_eth',
110+
},
111+
{
112+
label: 'Github',
113+
href: 'https://github.com/ChainSafe/lodestar',
120114
},
121115
],
122-
copyright: `Copyright © ${new Date().getFullYear()} ChainSafe, Inc.`,
116+
copyright: `Copyright © ${new Date().getFullYear()} ChainSafe. Built with Docusaurus.` ,
123117
},
124118
colorMode: {
125119
respectPrefersColorScheme: false,

docs/pages/google0c42298b7ec08b7e.html

-1
This file was deleted.

docs/pages/index.md

+14-10
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@ title: Home
44

55
![lodestar logo](../../assets/lodestar_icon_text_black_stroke.png)
66

7-
## Welcome to the Lodestar documentation
7+
## Welcome to the Lodestar Documentation
88

9-
> **Lodestar is an open-source Ethereum Consensus client and Typescript ecosystem, maintained by ChainSafe Systems**
9+
> **Lodestar is an open-source Ethereum Consensus client and TypeScript ecosystem, maintained by ChainSafe Systems**
1010
11-
### Getting started
11+
### Getting Started
1212

1313
- Follow the instructions for [build from source](./run/getting-started/installation#build-from-source), [binaries](./run/getting-started/installation#binaries), or [Docker](./run/getting-started/installation#docker-installation) to install Lodestar. Or use our [Lodestar Quickstart scripts](https://github.com/ChainSafe/lodestar-quickstart).
14-
- Use [Lodestar libraries](./supporting-libraries/index.md) in your next Ethereum Typescript project.
14+
- Use [Lodestar libraries](./supporting-libraries/index.md) in your next Ethereum TypeScript project.
1515
- Run a beacon node on [mainnet or a public testnet](./run/beacon-management/starting-a-node.md).
1616
- Utilize the whole stack by [starting a local testnet](./contribution/advanced-topics/setting-up-a-testnet.md).
1717
- View the Lodestar Beacon [CLI commands and options](./run/beacon-management/beacon-cli.md)
@@ -26,14 +26,18 @@ Hardware specifications minimum / recommended, to run the Lodestar client.
2626
| | Minimum | Recommended |
2727
| --------- | -------------------------------------- | -------------------------------------- |
2828
| Processor | Intel Core i3–9100 or AMD Ryzen 5 3450 | Intel Core i7–9700 or AMD Ryzen 7 4700 |
29-
| Memory | 16GB RAM | 32GB RAM |
30-
| Storage | 100GB available space SSD | 1TB available space SSD |
31-
| Internet | Broadband connection | Broadband connection |
29+
| Memory | 8 GB RAM | 16 GB RAM |
30+
| Storage | 130 GB available space SSD | 200 GB available space SSD |
31+
| Internet | Reliable broadband with 10mbps upload | Reliable broadband with >10mbps upload |
3232

33-
## About these docs
33+
### Execution Client
3434

35-
This documentation is open source, contribute at [Github Lodestar repository /docs](https://github.com/ChainSafe/lodestar/tree/unstable/docs).
35+
If you run the [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) on the same host, you will need to check their requirements and add them to the above requirements. Broadly, to run both an execution and a consensus client on the same machine, we recommend a 4 TB SSD and 32 GB RAM.
3636

37-
## Need assistance?
37+
## About These Docs
38+
39+
This documentation is open source, contribute on our [Github Lodestar repository /docs](https://github.com/ChainSafe/lodestar/tree/unstable/docs).
40+
41+
## Need Assistance?
3842

3943
If you have questions about this documentation, feel free to talk to us on our [ChainSafe Discord](https://discord.gg/yjyvFRP) or [open an issue](https://github.com/ChainSafe/lodestar/issues/new/choose) and a member of the team or our community will be happy to assist you.

docs/pages/introduction.md

+12-12
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,29 @@
11
# Introduction
22

3-
Ethereum is one of the most profoundly important inventions in recent history. It is a decentralized, open-source blockchain featuring smart contract functionality. It is the second-largest cryptocurrency by market capitalization, after Bitcoin, and is the most actively used blockchain. Ethereum was proposed in 2013 by programmer Vitalik Buterin. Development was crowdfunded in 2014, and the network went live on 30 July 2015, with 72 million coins premined. ChainSafe was founded not too long afterwards and has been actively working in the Ethereum space ever since. We are proud to develop Lodestar and to present this documentation as a resource for the Ethereum community.
3+
Ethereum is one of the most profoundly important inventions in recent history. It is a decentralized, open-source blockchain featuring smart contract functionality. It is the second-largest cryptocurrency by market capitalization, after Bitcoin, and is the second largest blockchain by market capitalization. Ethereum was proposed in 2013 by programmer Vitalik Buterin. Development was crowdfunded in 2014, and the network went live on 30 July 2015, with 72 million coins premined. ChainSafe was founded not too long afterwards in 2017 and has been actively working in the Ethereum ecosystem ever since. We are proud to develop Lodestar, the only TypeScript based consensus client, and to present this documentation as a resource for the Ethereum community.
44

55
## Proof of Stake
66

7-
In Ethereum's Proof of Stake (PoS) model, validators replace miners from the Proof of Work (PoW) system. Validators are Ethereum stakeholders who lock up a portion of their Ether as a stake. The protocol randomly selects these validators to propose new blocks. The chance of being chosen is tied to the size of their stake: the more Ether staked, the higher the probability of being selected to propose the block. Proposers receive transaction fees and block rewards as incentives. Validators are also responsible for voting on the validity of blocks proposed by other validators. However, they face penalties, known as slashing, for actions like double-signing, votes on a block that is not in the majority or going offline, ensuring network integrity and reliability. The PoS mechanism significantly reduces energy consumption compared to PoW, because it does not require extensive computational power. Moreover, PoS tends to facilitate faster transaction validations and block creations, enhancing the overall performance and scalability of the network.
7+
In Ethereum's Proof of Stake (PoS) model, validators replace miners from the Proof of Work (PoW) system. Validators are Ethereum stakeholders who lock up a portion of their Ether as a stake. The protocol randomly selects these validators to propose new blocks. The chance of being chosen is tied to the size of their stake: the more Ether staked, the higher the probability of being selected to propose the block. Proposers receive transaction fees and block rewards as incentives. Validators are also responsible for voting on the validity of blocks proposed by other validators. However, they also face penalties, known as slashing, for actions like signing two different block proposals in the same slot or voting on two different attestations for the same target epoch, which creates conflicting states. The PoS mechanism significantly reduces energy consumption compared to PoW, because it does not require extensive computational power. Moreover, PoS tends to facilitate faster transaction validations and block creations, enhancing the overall performance and scalability of the network.
88

99
## Consensus Clients
1010

11-
In an effort to promote client diversity there are several beacon-nodes being developed. Each is programmed in a different language and by a different team. The following is a list of the current beacon-node clients:
11+
In an effort to promote client diversity there are several consensus beacon nodes being developed. Each is programmed in a different language and by a different team. The following is a list of the current open source consensus clients in alphabetical order:
1212

13-
- [Lodestar](https://lodestar.chainsafe.io/)
14-
- [Prysm](https://prysmaticlabs.com/)
15-
- [Lighthouse](https://lighthouse.sigmaprime.io/)
16-
- [Teku](https://consensys.net/knowledge-base/ethereum-2/teku/)
17-
- [Nimbus](https://nimbus.team/)
18-
- [Grandine](https://grandine.io)
13+
- [Grandine (Rust)](https://grandine.io)
14+
- [Lighthouse (Rust)](https://lighthouse.sigmaprime.io/)
15+
- [Lodestar (TypeScript)](https://lodestar.chainsafe.io/)
16+
- [Nimbus (Nim)](https://nimbus.team/)
17+
- [Prysm (Golang)](https://prysmaticlabs.com/)
18+
- [Teku (Java)](https://consensys.net/knowledge-base/ethereum-2/teku/)
1919

2020
## Why Client Diversity?
2121

22-
The Ethereum network's robustness is significantly enhanced by its client diversity, whereby multiple, independently-developed clients conforming to a common specification facilitate seamless interaction and function equivalently across nodes. This client variety not only fosters a rich ecosystem but also provides a buffer against network-wide issues stemming from bugs or malicious attacks targeted at particular clients. For instance, during the Shanghai denial-of-service attack in 2016, the diversified client structure enabled the network to withstand the assault, underscoring the resilience afforded by multiple client configurations.
22+
The Ethereum network's robustness is significantly enhanced by its client diversity, whereby multiple, independently-developed clients conforming to a common specification, facilitating seamless interaction and function equivalently across different nodes. This client variety not only fosters a rich ecosystem but also provides a buffer against network-wide issues stemming from bugs or malicious attacks targeted at particular clients. For instance, during the Shanghai denial-of-service attack in 2016, the diversified client structure enabled the network to withstand the assault, underscoring the resilience afforded by multiple client configurations.
2323

24-
On the consensus layer, client distribution is crucial for maintaining network integrity and finality, ensuring transactions are irreversible once validated. A balanced spread of nodes across various clients helps mitigate risks associated with potential bugs or attacks that could, in extreme cases, derail the consensus process or lead to incorrect chain splits, thereby jeopardizing the network's stability and trust. While the data suggests a dominance of Prysm client on the consensus layer, efforts are ongoing to promote a more even distribution among others like Lighthouse, Teku, Nimbus and Grandine. Encouraging the adoption of minority clients, bolstering their documentation, and leveraging real-time client diversity dashboards are among the strategies being employed to enhance client diversity, which in turn fortifies the Ethereum consensus layer against adversities and fosters a healthier decentralized network ecosystem.
24+
On the consensus layer, client distribution is crucial for maintaining network integrity and finality, ensuring transactions are irreversible once validated. A balanced spread of nodes across various clients help to mitigate risks associated with potential bugs or attacks that could, in extreme cases, derail the consensus process (liveness failure) or lead to incorrect chain splits (forking), thereby jeopardizing the network's stability and trust. While the data suggests a [dominance of the Prysm and Lighthouse clients](https://clientdiversity.org) on the consensus layer, efforts are ongoing to promote a more even distribution among others clients. Encouraging the adoption of minority clients, bolstering their documentation, and leveraging real-time client diversity dashboards are among the strategies being employed to enhance client diversity, which in turn fortifies the Ethereum consensus layer against adversities and fosters a healthier decentralized network.
2525

26-
The non-finality event in May 2023 on the Ethereum network posed a significant challenge. The issue arose from attestations for a fork, which necessitated state replays to validate the attestations, causing a notable strain on system resources. As a result, nodes fell out of sync, which deterred the accurate tracking of the actual head of the chain. This situation was exacerbated by a decline in attestations during specific epochs, further hampering the consensus mechanism. The Lodestar team noticed late attestations several weeks prior to the event and implemented a feature that attempted to address such challenges by not processing untimely attestations, and thus not requiring expensive state replays​. While it was done for slightly different reasons, the result was the same. Lodestar was able to follow the chain correctly and helped to stabilize the network. This example underscored the importance of client diversity and network resilience against potential forks and replay attacks. These are considered realistic threats, especially in the context of system complexity like in Ethereum's consensus mechanism.
26+
The [non-finality event of May 2023](https://medium.com/offchainlabs/post-mortem-report-ethereum-mainnet-finality-05-11-2023-95e271dfd8b2) on the Ethereum network posed a significant challenge. The issue arose from attestations for a fork, which necessitated state replays to validate the attestations, causing a notable strain on system resources. As a result, nodes fell out of sync, which deterred the accurate tracking of the actual head of the chain. This situation was exacerbated by a decline in attestations during specific epochs, further hampering the consensus mechanism from reaching finality. The Lodestar team noticed late attestations several weeks prior to the event and implemented a feature that attempted to address such challenges by not processing untimely attestations, and thus not requiring expensive state replays​. While it was done for slightly different reasons, the result was the same. Lodestar was able to follow the chain correctly and helped to stabilize the network. This example underscored the importance of client diversity and network resilience against potential forks and replay attacks. These are considered realistic threats, especially in the context of system complexity like in Ethereum's consensus mechanism.
2727

2828
## Ethereum Reading List
2929

0 commit comments

Comments
 (0)