Markdown linter (#5494)

* linter * Add markdown linter * add env * only check markdown * Add token * Update .github/workflows/test-suite.yml * Markdown linter * Exit code * Update script * rename * mdlint * Add an empty line after end of file * Testing disable * add text * update mdlint.sh * ori validator inclusion * Add config yml file * Remove MD041 and fix advanced-datadir file * FIx validator inclusion file conflict * Merge branch 'unstable' into markdown-linter * change files * Merge branch 'markdown-linter' of https://github.com/chong-he/lighthouse into markdown-linter * mdlint * Remove MD025 * Remove MD036 * Remove MD045 * Removr MD001 * Set MD028 to false * Remove MD024 * Remove MD055 * Remove MD029 * Remove MD040 * Set MD040 to false * Set MD033 to false * Set MD013 to false * Rearrange yml file * Update mdlint.sh and test * Test remove fix * Test with fix * Test with space * Fix summary indentation * Test mdlint.sh * Update mdlint.sh * Test * Update * Test fix * Test again * Fix * merge into check-code * Update scripts/mdlint.sh Co-authored-by: Mac L <mjladson@pm.me> * Update scripts/mdlint.sh Co-authored-by: Mac L <mjladson@pm.me> * Remove set -e * Add comment * Merge pull request #7 from chong-he/unstable Merge unstable to markdown branch * mdlint * Merge branch 'unstable' into markdown-linter * mdlint
2026-03-23 06:44:35 +00:00 · 2024-05-24 10:45:19 +08:00
parent 7073242ccc
commit 3070cb7c39
68 changed files with 720 additions and 637 deletions
--- a/book/src/api-lighthouse.md
+++ b/book/src/api-lighthouse.md
@@ -16,12 +16,12 @@ 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.*

 Returns information regarding the health of the host machine.
+
 ```bash
 curl -X GET "http://localhost:5052/lighthouse/health" -H  "accept: application/json" | jq
 ```
@@ -64,7 +64,8 @@ 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.

 ```bash
@@ -101,8 +102,10 @@ 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.
+
 ```bash
 curl -X GET "http://localhost:5052/lighthouse/ui/validator_count" -H "accept: application/json" | jq
 ```
@@ -123,9 +126,10 @@ 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.
+
 ```bash
 curl -X POST "http://localhost:5052/lighthouse/ui/validator_metrics" -d '{"indices": [12345]}' -H "Content-Type: application/json" | jq
 ```
@@ -150,7 +154,9 @@ curl -X POST "http://localhost:5052/lighthouse/ui/validator_metrics" -d '{"indic
  }
 }
 ```
+
 Running this API without the flag `--validator-monitor-auto` in the beacon node will return null:
+
 ```json
 {
  "data": {
@@ -159,8 +165,10 @@ 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.
+
 ```bash
 curl -X GET "http://localhost:5052/lighthouse/syncing" -H  "accept: application/json" | jq
 ```
@@ -168,6 +176,7 @@ curl -X GET "http://localhost:5052/lighthouse/syncing" -H  "accept: application/
 There are two possible outcomes, depending on whether the beacon node is syncing or synced.

 1. Syncing:
+
   ```json
    {
      "data": {
@@ -178,20 +187,21 @@ There are two possible outcomes, depending on whether the beacon node is syncing
      }
    }
   ```
+
 1. Synced:
+
   ```json
   {
     "data": "Synced"
   }
   ```

-### `/lighthouse/peers`
+## `/lighthouse/peers`

 ```bash
 curl -X GET "http://localhost:5052/lighthouse/peers" -H  "accept: application/json" | jq
 ```

-
 ```json
 [
  {
@@ -255,14 +265,14 @@ curl -X GET "http://localhost:5052/lighthouse/peers" -H  "accept: application/js
 ]
 ```

-### `/lighthouse/peers/connected`
+## `/lighthouse/peers/connected`
+
 Returns information about connected peers.
+
 ```bash
 curl -X GET "http://localhost:5052/lighthouse/peers/connected" -H  "accept: application/json" | jq
 ```

-
-
 ```json
 [
 {
@@ -327,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
@@ -335,45 +345,45 @@ 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
 health of the execution node that the beacon node is connected to.
 - `latest_cached_block_number` & `latest_cached_block_timestamp`: the block
 number and timestamp of the latest block we have in our block cache.
-	- For correct execution client voting this timestamp should be later than the
+  - For correct execution client voting this timestamp should be later than the
 `voting_target_timestamp`.

 - `voting_target_timestamp`: The latest timestamp allowed for an execution layer block in this voting period.
 - `eth1_node_sync_status_percentage` (float): An estimate of how far the head of the
  execution node is from the head of the execution chain.
-	- `100.0` indicates a fully synced execution node.
-	- `0.0` indicates an execution node that has not verified any blocks past the
-		genesis block.
+  - `100.0` indicates a fully synced execution node.
+  - `0.0` indicates an execution node that has not verified any blocks past the
+  genesis block.
 - `lighthouse_is_cached_and_ready`: Is set to `true` if the caches in the
-	beacon node are ready for block production.
-	- This value might be set to
-	`false` whilst `eth1_node_sync_status_percentage == 100.0` if the beacon
-	node is still building its internal cache.
-	- This value might be set to `true` whilst
-	`eth1_node_sync_status_percentage < 100.0` since the cache only cares
-	about blocks a certain distance behind the head.
+ beacon node are ready for block production.
+  - This value might be set to
+ `false` whilst `eth1_node_sync_status_percentage == 100.0` if the beacon
+ node is still building its internal cache.
+  - This value might be set to `true` whilst
+ `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
@@ -393,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
@@ -424,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
@@ -463,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.
@@ -488,9 +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.

@@ -498,7 +506,6 @@ Information about the database's split point and anchor info.
 curl "http://localhost:5052/lighthouse/database/info" | jq
 ```

-
 ```json
 {
  "schema_version": 18,
@@ -541,9 +548,10 @@ 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 15<sup>th</sup> September 2022, you will see that the current difficulty is less than the terminal total difficulty, An example is shown below:
+
 ```bash
 curl -X GET "http://localhost:5052/lighthouse/merge_readiness" | jq
 ```
@@ -574,16 +582,15 @@ 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.

 Two query parameters are required:

-* `start_epoch` (inclusive): the first epoch to compute attestation performance for.
-* `end_epoch` (inclusive): the final epoch to compute attestation performance for.
+- `start_epoch` (inclusive): the first epoch to compute attestation performance for.
+- `end_epoch` (inclusive): the final epoch to compute attestation performance for.

 Example:

@@ -649,18 +656,18 @@ curl -X GET "http://localhost:5052/lighthouse/analysis/attestation_performance/g

 Caveats:

-* For maximum efficiency the start_epoch should satisfy `(start_epoch * slots_per_epoch) % slots_per_restore_point == 1`.
-  This is because the state _prior_ to the `start_epoch` needs to be loaded from the database,
+- For maximum efficiency the start_epoch should satisfy `(start_epoch * slots_per_epoch) % slots_per_restore_point == 1`.
+  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.

 Two query parameters are required:

-* `start_slot` (inclusive): the slot of the first block to compute rewards for.
-* `end_slot` (inclusive): the slot of the last block to compute rewards for.
+- `start_slot` (inclusive): the slot of the first block to compute rewards for.
+- `end_slot` (inclusive): the slot of the last block to compute rewards for.

 Example:

@@ -668,7 +675,6 @@ Example:
 curl -X GET "http://localhost:5052/lighthouse/analysis/block_rewards?start_slot=1&end_slot=1" | jq
 ```

-
 The first few lines of the response would look like:

 ```json
@@ -698,25 +704,25 @@ The first few lines of the response would look like:

 Caveats:

-* Presently only attestation and sync committee rewards are computed.
-* The output format is verbose and subject to change. Please see [`BlockReward`][block_reward_src]
+- Presently only attestation and sync committee rewards are computed.
+- The output format is verbose and subject to change. Please see [`BlockReward`][block_reward_src]
  in the source.
-* For maximum efficiency the `start_slot` should satisfy `start_slot % slots_per_restore_point == 1`.
-  This is because the state _prior_ to the `start_slot` needs to be loaded from the database, and
+- For maximum efficiency the `start_slot` should satisfy `start_slot % slots_per_restore_point == 1`.
+  This is because the state *prior* to the `start_slot` needs to be loaded from the database, and
  loading a state on a boundary is most efficient.

 [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.

 Two query parameters are required:

-* `start_epoch` (inclusive): the epoch of the first block to compute packing efficiency for.
-* `end_epoch` (inclusive): the epoch of the last block to compute packing efficiency for.
+- `start_epoch` (inclusive): the epoch of the first block to compute packing efficiency for.
+- `end_epoch` (inclusive): the epoch of the last block to compute packing efficiency for.

 ```bash
 curl -X GET "http://localhost:5052/lighthouse/analysis/block_packing_efficiency?start_epoch=1&end_epoch=1" | jq
@@ -745,13 +751,12 @@ An excerpt of the response looks like:

 Caveats:

-* `start_epoch` must not be `0`.
-* For maximum efficiency the `start_epoch` should satisfy `(start_epoch * slots_per_epoch) % slots_per_restore_point == 1`.
-  This is because the state _prior_ to the `start_epoch` needs to be loaded from the database, and
+- `start_epoch` must not be `0`.
+- For maximum efficiency the `start_epoch` should satisfy `(start_epoch * slots_per_epoch) % slots_per_restore_point == 1`.
+  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
@@ -764,6 +769,7 @@ curl -N "http://localhost:5052/lighthouse/logs"
 ```

 Should provide an output that emits log events as they occur:
+
 ```json
 {
 "data": {
@@ -779,7 +785,8 @@ Should provide an output that emits log events as they occur:
 }
 ```

-### `/lighthouse/nat`
+## `/lighthouse/nat`
+
 Checks if the ports are open.

 ```bash
@@ -787,6 +794,7 @@ curl -X GET "http://localhost:5052/lighthouse/nat" | jq
 ```

 An open port will return:
+
 ```json
 {
  "data": true