Skip to content

Commit

Permalink
mdlint
Browse files Browse the repository at this point in the history
  • Loading branch information
@chong-he
chong-he committed Apr 10, 2024
1 parent c64f011 commit d5ee394
Show file tree
Hide file tree
Showing 4 changed files with 84 additions and 71 deletions.
86 changes: 47 additions & 39 deletions book/src/api-lighthouse.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`

*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
```
Expand Down Expand Up @@ -65,6 +65,7 @@ curl -X GET "http://localhost:5052/lighthouse/health" -H "accept: application/j
```

### `/lighthouse/ui/health`

Returns information regarding the health of the host machine.

```bash
Expand Down Expand Up @@ -102,7 +103,9 @@ curl -X GET "http://localhost:5052/lighthouse/ui/health" -H "accept: applicatio
```

### `/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
```
Expand All @@ -123,9 +126,10 @@ curl -X GET "http://localhost:5052/lighthouse/ui/validator_count" -H "accept: ap
}
```


### `/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
```
Expand All @@ -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": {
Expand All @@ -160,14 +166,17 @@ Running this API without the flag `--validator-monitor-auto` in the beacon node
```

### `/lighthouse/syncing`

Returns the sync status of the beacon node.

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

There are two possible outcomes, depending on whether the beacon node is syncing or synced.

1. Syncing:

```json
{
"data": {
Expand All @@ -178,7 +187,9 @@ There are two possible outcomes, depending on whether the beacon node is syncing
}
}
```

1. Synced:

```json
{
"data": "Synced"
Expand All @@ -191,7 +202,6 @@ There are two possible outcomes, depending on whether the beacon node is syncing
curl -X GET "http://localhost:5052/lighthouse/peers" -H "accept: application/json" | jq
```


```json
[
{
Expand Down Expand Up @@ -256,13 +266,13 @@ curl -X GET "http://localhost:5052/lighthouse/peers" -H "accept: application/js
```

### `/lighthouse/peers/connected`

Returns information about connected peers.

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



```json
[
{
Expand Down Expand Up @@ -355,23 +365,23 @@ from the very head of the execution chain. Useful for understanding the immediat
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

Expand Down Expand Up @@ -488,8 +498,6 @@ curl -X POST "http://localhost:5052/lighthouse/liveness" -d '{"indices":["0","1"
}
```



### `/lighthouse/database/info`

Information about the database's split point and anchor info.
Expand All @@ -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,
Expand Down Expand Up @@ -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`

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
```
Expand Down Expand Up @@ -574,16 +582,15 @@ As all testnets and Mainnet have been merged, both values will be the same after
}
```


### `/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:

Expand Down Expand Up @@ -649,8 +656,8 @@ 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`
Expand All @@ -659,16 +666,15 @@ Fetch information about the block rewards paid to proposers for a range of conse

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:

```bash
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
Expand Down Expand Up @@ -698,11 +704,11 @@ 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]:
Expand All @@ -715,8 +721,8 @@ 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
Expand Down Expand Up @@ -745,12 +751,11 @@ 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`

This is a Server Side Event subscription endpoint. This allows a user to read
Expand All @@ -764,6 +769,7 @@ curl -N "http://localhost:5052/lighthouse/logs"
```

Should provide an output that emits log events as they occur:

```json
{
"data": {
Expand All @@ -780,13 +786,15 @@ Should provide an output that emits log events as they occur:
```

### `/lighthouse/nat`

Checks if the ports are open.

```bash
curl -X GET "http://localhost:5052/lighthouse/nat" | jq
```

An open port will return:

```json
{
"data": true
Expand Down
Loading

0 comments on commit d5ee394

Please sign in to comment.