diff --git a/book/src/advanced-blobs.md b/book/src/advanced-blobs.md index 1577a59bec8..ed77da8a758 100644 --- a/book/src/advanced-blobs.md +++ b/book/src/advanced-blobs.md @@ -2,7 +2,7 @@ In the Deneb network upgrade, one of the changes is the implementation of EIP-4844, also known as [Proto-danksharding](https://blog.ethereum.org/2024/02/27/dencun-mainnet-announcement). Alongside with this, a new term named `blob` (binary large object) is introduced. Blobs are "side-cars" carrying transaction data in a block. They are mainly used by Ethereum layer 2 operators. As far as stakers are concerned, the main difference with the introduction of blobs is the increased storage requirement. -### FAQ +## FAQ 1. What is the storage requirement for blobs? diff --git a/book/src/advanced-datadir.md b/book/src/advanced-datadir.md index 8c7afa95c5c..6f03545383e 100644 --- a/book/src/advanced-datadir.md +++ b/book/src/advanced-datadir.md @@ -15,7 +15,7 @@ lighthouse --network mainnet --datadir /var/lib/my-custom-dir vc 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). After that, we simply run the beacon chain and validator client with the custom dir path. -### Relative Paths +## Relative Paths [#2682]: https://github.com/sigp/lighthouse/pull/2682 [#2846]: https://github.com/sigp/lighthouse/pull/2846 diff --git a/book/src/advanced-release-candidates.md b/book/src/advanced-release-candidates.md index 0925273bad0..9f00da9ae98 100644 --- a/book/src/advanced-release-candidates.md +++ b/book/src/advanced-release-candidates.md @@ -20,7 +20,7 @@ you're looking for stable Lighthouse**. From time to time, Lighthouse may use the terms "release candidate" and "pre release" interchangeably. A pre release is identical to a release candidate. -### Examples +## Examples [`v1.4.0-rc.0`] has `rc` in the version string and is therefore a release candidate. This release is *not* stable and is *not* intended for critical tasks on mainnet (e.g., staking). diff --git a/book/src/advanced_networking.md b/book/src/advanced_networking.md index ff8d826c40f..82a19fbcb19 100644 --- a/book/src/advanced_networking.md +++ b/book/src/advanced_networking.md @@ -5,7 +5,7 @@ be adjusted to handle a variety of network situations. This section outlines some of these configuration parameters and their consequences at the networking level and their general intended use. -### Target Peers +## Target Peers The beacon node has a `--target-peers` CLI parameter. This allows you to instruct the beacon node how many peers it should try to find and maintain. @@ -37,7 +37,7 @@ large peer count will not speed up sync. For these reasons, we recommend users do not modify the `--target-peers` count drastically and use the (recommended) default. -### NAT Traversal (Port Forwarding) +## NAT Traversal (Port Forwarding) Lighthouse, by default, uses port 9000 for both TCP and UDP. Since v4.5.0, Lighthouse will also attempt to make QUIC connections via UDP port 9001 by default. Lighthouse will still function if it is behind a NAT without any port mappings. Although @@ -61,7 +61,7 @@ TCP and UDP ports (9000 TCP/UDP, and 9001 UDP by default). > explicitly specify them using the `--enr-tcp-port` and `--enr-udp-port` as > explained in the following section. -### How to Open Ports +## How to Open Ports The steps to do port forwarding depends on the router, but the general steps are given below: @@ -93,7 +93,7 @@ Since V4.5.0 port 9001/UDP is also used for QUIC support. 5. To check that you have successfully opened 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. Note: this will only confirm if port 9000/TCP is open. You will need to ensure you have correctly setup port forwarding for the UDP ports (`9000` and `9001` by default). -### ENR Configuration +## ENR Configuration Lighthouse has a number of CLI parameters for constructing and modifying the local Ethereum Node Record (ENR). Examples are `--enr-address`, @@ -115,7 +115,7 @@ 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. -### IPv6 support +## IPv6 support As noted in the previous sections, two fundamental parts to ensure good connectivity are: The parameters that configure the sockets over which @@ -123,7 +123,7 @@ Lighthouse listens for connections, and the parameters used to tell other peers how to connect to your node. This distinction is relevant and applies to most nodes that do not run directly on a public network. -#### Configuring Lighthouse to listen over IPv4/IPv6/Dual stack +### Configuring Lighthouse to listen over IPv4/IPv6/Dual stack To listen over only IPv6 use the same parameters as done when listening over IPv4 only: @@ -151,7 +151,7 @@ To listen over both IPv4 and IPv6: UDP over IPv6. This will default to the value given to `--port6` + 1. This flag has no effect when listening over IPv6 only. -##### Configuration Examples +#### Configuration Examples > When using `--listen-address :: --listen-address 0.0.0.0 --port 9909`, listening will be set up as follows: > @@ -177,7 +177,7 @@ To listen over both IPv4 and IPv6: > It listens on the default value of `--port6` (`9090`) for TCP, and port `9999` for UDP. > QUIC will use port `9091` for UDP, which is the default `--port6` value (`9090`) + 1. -#### Configuring Lighthouse to advertise IPv6 reachable addresses +### Configuring Lighthouse to advertise IPv6 reachable addresses Lighthouse supports IPv6 to connect to other nodes both over IPv6 exclusively, and dual stack using one socket for IPv4 and another socket for IPv6. In both @@ -208,7 +208,7 @@ In the general case, a user will not require to set these explicitly. Update these options only if you can guarantee your node is reachable with these values. -#### Known caveats +### Known caveats IPv6 link local addresses are likely to have poor connectivity if used in topologies with more than one interface. Use global addresses for the general diff --git a/book/src/api-lighthouse.md b/book/src/api-lighthouse.md index cb2242122cc..6ef00578f70 100644 --- a/book/src/api-lighthouse.md +++ b/book/src/api-lighthouse.md @@ -16,7 +16,7 @@ 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` +## `/lighthouse/health` *Note: This endpoint is presently only available on Linux.* @@ -64,7 +64,7 @@ curl -X GET "http://localhost:5052/lighthouse/health" -H "accept: application/j ``` -### `/lighthouse/ui/health` +## `/lighthouse/ui/health` Returns information regarding the health of the host machine. @@ -102,7 +102,7 @@ curl -X GET "http://localhost:5052/lighthouse/ui/health" -H "accept: applicatio } ``` -### `/lighthouse/ui/validator_count` +## `/lighthouse/ui/validator_count` Returns an overview of validators. @@ -126,7 +126,7 @@ curl -X GET "http://localhost:5052/lighthouse/ui/validator_count" -H "accept: ap } ``` -### `/lighthouse/ui/validator_metrics` +## `/lighthouse/ui/validator_metrics` 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. @@ -165,7 +165,7 @@ Running this API without the flag `--validator-monitor-auto` in the beacon node } ``` -### `/lighthouse/syncing` +## `/lighthouse/syncing` Returns the sync status of the beacon node. @@ -196,7 +196,7 @@ There are two possible outcomes, depending on whether the beacon node is syncing } ``` -### `/lighthouse/peers` +## `/lighthouse/peers` ```bash curl -X GET "http://localhost:5052/lighthouse/peers" -H "accept: application/json" | jq @@ -265,7 +265,7 @@ curl -X GET "http://localhost:5052/lighthouse/peers" -H "accept: application/js ] ``` -### `/lighthouse/peers/connected` +## `/lighthouse/peers/connected` Returns information about connected peers. @@ -337,7 +337,7 @@ curl -X GET "http://localhost:5052/lighthouse/peers/connected" -H "accept: appl ] ``` -### `/lighthouse/proto_array` +## `/lighthouse/proto_array` ```bash curl -X GET "http://localhost:5052/lighthouse/proto_array" -H "accept: application/json" | jq @@ -345,20 +345,20 @@ curl -X GET "http://localhost:5052/lighthouse/proto_array" -H "accept: applicat *Example omitted for brevity.* -### `/lighthouse/validator_inclusion/{epoch}/{validator_id}` +## `/lighthouse/validator_inclusion/{epoch}/{validator_id}` See [Validator Inclusion APIs](./validator-inclusion.md). -### `/lighthouse/validator_inclusion/{epoch}/global` +## `/lighthouse/validator_inclusion/{epoch}/global` See [Validator Inclusion APIs](./validator-inclusion.md). -### `/lighthouse/eth1/syncing` +## `/lighthouse/eth1/syncing` Returns information regarding execution layer, as it is required for use in consensus layer -#### Fields +### Fields - `head_block_number`, `head_block_timestamp`: the block number and timestamp from the very head of the execution chain. Useful for understanding the immediate @@ -383,7 +383,7 @@ number and timestamp of the latest block we have in our block cache. `eth1_node_sync_status_percentage < 100.0` since the cache only cares about blocks a certain distance behind the head. -#### Example +### Example ```bash curl -X GET "http://localhost:5052/lighthouse/eth1/syncing" -H "accept: application/json" | jq @@ -403,11 +403,11 @@ curl -X GET "http://localhost:5052/lighthouse/eth1/syncing" -H "accept: applica } ``` -### `/lighthouse/eth1/block_cache` +## `/lighthouse/eth1/block_cache` Returns a list of all the execution layer blocks in the execution client voting cache. -#### Example +### Example ```bash curl -X GET "http://localhost:5052/lighthouse/eth1/block_cache" -H "accept: application/json" | jq @@ -434,11 +434,11 @@ curl -X GET "http://localhost:5052/lighthouse/eth1/block_cache" -H "accept: app } ``` -### `/lighthouse/eth1/deposit_cache` +## `/lighthouse/eth1/deposit_cache` Returns a list of all cached logs from the deposit contract. -#### Example +### Example ```bash curl -X GET "http://localhost:5052/lighthouse/eth1/deposit_cache" -H "accept: application/json" | jq @@ -473,7 +473,7 @@ curl -X GET "http://localhost:5052/lighthouse/eth1/deposit_cache" -H "accept: a } ``` -### `/lighthouse/liveness` +## `/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. @@ -498,7 +498,7 @@ curl -X POST "http://localhost:5052/lighthouse/liveness" -d '{"indices":["0","1" } ``` -### `/lighthouse/database/info` +## `/lighthouse/database/info` Information about the database's split point and anchor info. @@ -548,7 +548,7 @@ reconstruction has yet to be completed. For more information on the specific meanings of these fields see the docs on [Checkpoint Sync](./checkpoint-sync.md#reconstructing-states). -### `/lighthouse/merge_readiness` +## `/lighthouse/merge_readiness` Returns the current difficulty and terminal total difficulty of the network. Before [The Merge](https://ethereum.org/en/roadmap/merge/) on 15th September 2022, you will see that the current difficulty is less than the terminal total difficulty, An example is shown below: @@ -582,7 +582,7 @@ As all testnets and Mainnet have been merged, both values will be the same after } ``` -### `/lighthouse/analysis/attestation_performance/{index}` +## `/lighthouse/analysis/attestation_performance/{index}` Fetch information about the attestation performance of a validator index or all validators for a range of consecutive epochs. @@ -660,7 +660,7 @@ Caveats: This is because the state *prior* to the `start_epoch` needs to be loaded from the database, and loading a state on a boundary is most efficient. -### `/lighthouse/analysis/block_rewards` +## `/lighthouse/analysis/block_rewards` Fetch information about the block rewards paid to proposers for a range of consecutive blocks. @@ -714,7 +714,7 @@ Caveats: [block_reward_src]: https://github.com/sigp/lighthouse/tree/unstable/common/eth2/src/lighthouse/block_rewards.rs -### `/lighthouse/analysis/block_packing` +## `/lighthouse/analysis/block_packing` Fetch information about the block packing efficiency of blocks for a range of consecutive epochs. @@ -756,7 +756,7 @@ Caveats: This is because the state *prior* to the `start_epoch` needs to be loaded from the database, and loading a state on a boundary is most efficient. -### `/lighthouse/logs` +## `/lighthouse/logs` This is a Server Side Event subscription endpoint. This allows a user to read the Lighthouse logs directly from the HTTP API endpoint. This currently @@ -785,7 +785,7 @@ Should provide an output that emits log events as they occur: } ``` -### `/lighthouse/nat` +## `/lighthouse/nat` Checks if the ports are open. diff --git a/book/src/graffiti.md b/book/src/graffiti.md index 0846d384882..2ab320c7ff0 100644 --- a/book/src/graffiti.md +++ b/book/src/graffiti.md @@ -2,7 +2,7 @@ Lighthouse provides four options for setting validator graffiti. -### 1. Using the "--graffiti-file" flag on the validator client +## 1. Using the "--graffiti-file" flag on the validator client Users can specify a file with the `--graffiti-file` flag. This option is useful for dynamically changing graffitis for various use cases (e.g. drawing on the beaconcha.in graffiti wall). This file is loaded once on startup and reloaded everytime a validator is chosen to propose a block. @@ -28,7 +28,7 @@ default: Lighthouse Lighthouse will first search for the graffiti corresponding to the public key of the proposing validator, if there are no matches for the public key, then it uses the graffiti corresponding to the default key if present. -### 2. Setting the graffiti in the `validator_definitions.yml` +## 2. Setting the graffiti in the `validator_definitions.yml` Users can set validator specific graffitis in `validator_definitions.yml` with the `graffiti` key. This option is recommended for static setups where the graffitis won't change on every new block proposal. @@ -52,13 +52,13 @@ Below is an example of the validator_definitions.yml with validator specific gra graffiti: "somethingprofound" ``` -### 3. Using the "--graffiti" flag on the validator client +## 3. Using the "--graffiti" flag on the validator client Users can specify a common graffiti for all their validators using the `--graffiti` flag on the validator client. Usage: `lighthouse vc --graffiti example` -### 4. Using the "--graffiti" flag on the beacon node +## 4. Using the "--graffiti" flag on the beacon node Users can also specify a common graffiti using the `--graffiti` flag on the beacon node as a common graffiti for all validators. @@ -72,7 +72,7 @@ Usage: `lighthouse bn --graffiti fortytwo` > 4. If the `--graffiti` flag on the validator client is not passed, load the graffiti passed in the `--graffiti` flag on the beacon node. > 4. If the `--graffiti` flag is not passed, load the default Lighthouse graffiti. -### Set Graffiti via HTTP +## Set Graffiti via HTTP Use the [Lighthouse API](api-vc-endpoints.md) to set graffiti on a per-validator basis. This method updates the graffiti both in memory and in the `validator_definitions.yml` file. The new graffiti will be used in the next block proposal @@ -80,7 +80,7 @@ without requiring a validator client restart. Refer to [Lighthouse API](api-vc-endpoints.html#patch-lighthousevalidatorsvoting_pubkey) for API specification. -#### Example Command +### Example Command ```bash DATADIR=/var/lib/lighthouse diff --git a/book/src/homebrew.md b/book/src/homebrew.md index 486de371f86..da92dcb26ce 100644 --- a/book/src/homebrew.md +++ b/book/src/homebrew.md @@ -5,7 +5,7 @@ Lighthouse is available on Linux and macOS via the [Homebrew package manager](ht Please note that this installation method is maintained by the Homebrew community. It is not officially supported by the Lighthouse team. -### Installation +## Installation Install the latest version of the [`lighthouse`][formula] formula with: @@ -13,7 +13,7 @@ Install the latest version of the [`lighthouse`][formula] formula with: brew install lighthouse ``` -### Usage +## Usage If Homebrew is installed to your `PATH` (default), simply run: @@ -27,7 +27,7 @@ Alternatively, you can find the `lighthouse` binary at: "$(brew --prefix)/bin/lighthouse" --help ``` -### Maintenance +## Maintenance The [formula][] is kept up-to-date by the Homebrew community and a bot that lists for new releases. diff --git a/book/src/installation-source.md b/book/src/installation-source.md index ce7ac039766..be03a189de7 100644 --- a/book/src/installation-source.md +++ b/book/src/installation-source.md @@ -23,7 +23,7 @@ The rustup installer provides an easy way to update the Rust compiler, and works With Rust installed, follow the instructions below to install dependencies relevant to your operating system. -#### Ubuntu +### Ubuntu Install the following packages: @@ -42,7 +42,7 @@ sudo apt update && sudo apt install -y git gcc g++ make cmake pkg-config llvm-de After this, you are ready to [build Lighthouse](#build-lighthouse). -#### Fedora/RHEL/CentOS +### Fedora/RHEL/CentOS Install the following packages: @@ -52,7 +52,7 @@ yum -y install git make perl clang cmake After this, you are ready to [build Lighthouse](#build-lighthouse). -#### macOS +### macOS 1. Install the [Homebrew][] package manager. 1. Install CMake using Homebrew: @@ -65,7 +65,7 @@ brew install cmake After this, you are ready to [build Lighthouse](#build-lighthouse). -#### Windows +### Windows 1. Install [Git](https://git-scm.com/download/win). 1. Install the [Chocolatey](https://chocolatey.org/install) package manager for Windows. diff --git a/book/src/partial-withdrawal.md b/book/src/partial-withdrawal.md index 50145e574e0..26003e1f2fe 100644 --- a/book/src/partial-withdrawal.md +++ b/book/src/partial-withdrawal.md @@ -5,7 +5,7 @@ After the [Capella](https://ethereum.org/en/history/#capella) upgrade on 12 - if a validator has a withdrawal credential type `0x00`, the rewards will continue to accumulate and will be locked in the beacon chain. - if a validator has a withdrawal credential type `0x01`, any rewards above 32ETH will be periodically withdrawn to the withdrawal address. This is also known as the "validator sweep", i.e., once the "validator sweep" reaches your validator's index, your rewards will be withdrawn to the withdrawal address. At the time of writing, with 560,000+ validators on the Ethereum mainnet, you shall expect to receive the rewards approximately every 5 days. -### FAQ +## FAQ 1. How to know if I have the withdrawal credentials type `0x00` or `0x01`? diff --git a/book/src/pi.md b/book/src/pi.md index ddfea3f3997..b91ecab548c 100644 --- a/book/src/pi.md +++ b/book/src/pi.md @@ -11,14 +11,14 @@ Tested on: Raspberry Pi (`aarch64`). Compiling on a faster machine (i.e., `x86_64` desktop) may be convenient.* -### 1. Install Ubuntu +## 1. Install Ubuntu Follow the [Ubuntu Raspberry Pi installation instructions](https://ubuntu.com/download/raspberry-pi). **A 64-bit version is required** A graphical environment is not required in order to use Lighthouse. Only the terminal and an Internet connection are necessary. -### 2. Install Packages +## 2. Install Packages Install the Ubuntu dependencies: @@ -31,7 +31,7 @@ sudo apt update && sudo apt install -y git gcc g++ make cmake pkg-config llvm-de > - If there are difficulties, try updating the package manager with `sudo apt > update`. -### 3. Install Rust +## 3. Install Rust Install Rust as per [rustup](https://rustup.rs/): @@ -46,7 +46,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh > be found, run `source $HOME/.cargo/env`. After that, running `cargo version` should return the version, for example `cargo 1.68.2`. > - It's generally advisable to append `source $HOME/.cargo/env` to `~/.bashrc`. -### 4. Install Lighthouse +## 4. Install Lighthouse ```bash git clone https://github.com/sigp/lighthouse.git diff --git a/book/src/setup.md b/book/src/setup.md index df047630197..d3da68f97cc 100644 --- a/book/src/setup.md +++ b/book/src/setup.md @@ -123,7 +123,7 @@ test src/lib.rs - (line 10) ... ok test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.15s$ cargo test -p eth2_ssz ``` -#### test_logger +### test_logger The test_logger, located in `/common/logging/` can be used to create a `Logger` that by default returns a NullLogger. But if `--features 'logging/test_logger'` is passed while diff --git a/book/src/suggested-fee-recipient.md b/book/src/suggested-fee-recipient.md index 23adfc5197c..4a9be7b963a 100644 --- a/book/src/suggested-fee-recipient.md +++ b/book/src/suggested-fee-recipient.md @@ -95,7 +95,7 @@ client. | Required Headers | [`Authorization`](./api-vc-auth-header.md) | | Typical Responses | 202, 404 | -#### Example Request Body +### Example Request Body ```json { diff --git a/book/src/validator-inclusion.md b/book/src/validator-inclusion.md index 529c2185485..3c703c9c040 100644 --- a/book/src/validator-inclusion.md +++ b/book/src/validator-inclusion.md @@ -63,7 +63,7 @@ The following fields are returned: From this data you can calculate: -#### Justification/Finalization Rate +### Justification/Finalization Rate `previous_epoch_target_attesting_gwei / current_epoch_active_gwei` diff --git a/scripts/mdlint.sh b/scripts/mdlint.sh index 33967793f0b..ef37d93fa1e 100755 --- a/scripts/mdlint.sh +++ b/scripts/mdlint.sh @@ -3,7 +3,7 @@ #set -e # use markdownlint-cli docker to check for markdown file s -docker run -v ./book:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest '**/*.md' --ignore node_modules --fix --disable MD013 MD033 MD040 MD029 MD055 MD024 MD028 MD001 +docker run -v ./book:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest '**/*.md' --ignore node_modules --fix --disable MD013 MD033 MD040 MD029 MD055 MD024 MD028 # exit code exit_code=$(echo $?)