lodestar
lodestar copied to clipboard
ChainSafe
Documentation Updates
Problem description
We would like to update our documentation. We would like to foster communication between the team and the community to make sure the docs included all of the best and none of the rest!! 🥷
Solution description
We are researching the other client docs and will incorporate the most important sections from each to create a complete set of docs for Lodestar and the broader consensus client ecosystem.
Additional context
Lodestar Docs: https://chainsafe.github.io/lodestar Lighthouse Docs: https://lighthouse-book.sigmaprime.io/ Prysm Docs: https://docs.prylabs.network/docs/getting-started Teku Docs: https://docs.teku.consensys.net/ Nim Docs: https://nimbus.guide/
Potential Layout
-
Introduction
- Proof-of-Stake
- Consensus Clients
- Ethereum Readings
-
Getting Started
- Installation
- Install from Source
- Using Docker
- Creating a JWT
- Block Exploration
- Installation
-
Beacon Management
- Configuration
- Available Flags
- Using a Configuration File
- Connecting to Peers
- Firewall Management
- NAT
- ENR
- MEV and Builder Management
- Database
- Syncing
- Checkpoint Sync
- Optimistic Sync
- Historical Sync
- Configuration
-
Validator Management
- Configuration
- Available Flags
- Using a Configuration File
- Proposer Settings File
- Key Management
- Fee Recipient
- Key Recovery
- External signer / Web3Signer
- Withdrawals
- Multiple and Fall-Back Validation
- Configuration
-
Logging and Metrics
-
Light Client
-
Prover
-
API
- Making API calls
- Using the
debugAPI
-
Troubleshooting
- Common Installation Issues
- Common Sync Issues
- Common Validation Issues
- Common Execution Layer Issues
-
Supporting Libraries
-
libp2p -
@chainsafe/libp2p-gossipsub -
@chainsafe/ssz -
@chainsafe/blsand@chainsafe/blst-ts
-
-
Contribution
- Bug Reports
- Getting started
- Repo Architecture
- Testing
- Unit Tests
- Spec Tests
- e2e Tests
- Simulation Tests
- Performance Tests
- Submitting a PR
-
Advanced Topics
- Migrating from Other Clients
- Slashing Protection
- Setting up a Testnet
- Doppelganger Detection
- Weak Subjectivity
Comments forwarded from discord by @wemeetagain:
- Install with Docker: lacking an example as in the 'Install from source' page -eg:
docker run lodestar --help - Validator management: lacking a section mentioning how to clear the lockfiles in case of a power outage, etc
- generally: consistency in style (use of 'eg:' vs 'ex:')
- Prometheus and Grafana: would be nice to include a screenshot of a working dashboard
- generally: Ensure urls are markdown links vs plaintext (see Prometheus and Grafana for an example of plaintext urls). markdown links need to be https://foo.com rather than just https://foo.com
- MEV Builder Integration: refresh stale introduction paragraphs
- Client monitoring: see if we can find a "specification" link that isn't a docs.google.com link
- Lodestar package structure: refresh graphviz graph node names
@wemeetagain would like to tackle typescript/javascript usage of lodestar packages
As suggested in the standup we could embed a API reference page (similar to CLI reference), I used redoc previously to do this and the results were pretty good, see Docker HUB API for an example.
This should be really easy to achieve once we know how to generate a openapi.json file which is already required by https://github.com/ChainSafe/lodestar/issues/1060. Redoc just needs a reference to the generated file (https://github.com/Redocly/redoc#tldr-final-code-example) and will generate everything from that. File should be ideally served from the same domain as the docs page itself.
New contributor guide/getting started section for developers: Examples:
- Add new API? What files do I need to update?
- How do I add a new network?
As discussed in Turkey, it makes sense to PR a documentation structure change to outline the docs better, then continuously contribute to updating the content within it. This way, we minimize issues with conflicts and rebasing your branch here https://github.com/ChainSafe/lodestar/tree/mkeil/redo-docs. The new structure contained within here are laid out much better and we can continuously update the content as we dedicate more time to making it more complete @matthewkeil .
As discussed on the March 5, 2024 standup, it was discussed that we would begin migration to Docusaurus for Lodestar docs due to its flexibility, React-based framework, and compatibility with current web technologies. It is important to note that this is not just platform change, but also an opportunity for us to vastly improve DevEx as described by some suggestions here: https://github.com/ChainSafe/lodestar/discussions/6493#discussioncomment-8632292
As part of migration we also need to figure out how to identify external links to our documentation and update as many to link the new doc URLs. From Github insights, the following traffic we can identify to our repo is:
- ethereum.org
- https://ethereum.org/en/developers/docs/nodes-and-clients/light-clients/
- lodestar.chainsafe.io
- chainsafe.github.io (our current docs)
- beaconscan.com
- blog.ethereum.org
- dev.to
- Search engines:
- google.com
- search.brave.com
- bing
As of today, our Google indexer shows the following external links to our documentation are:
For some alignment on how other ChainSafe projects are setting up their Docusaurus pages, see https://handbook.chainsafe.io/development/documentation/