Skip to content

Commit

Permalink
Refactor docs for standard API
Browse files Browse the repository at this point in the history
  • Loading branch information
@paulhauner
paulhauner committed Sep 21, 2020
1 parent 6f7b476 commit 008c206
Show file tree
Hide file tree
Showing 15 changed files with 333 additions and 2,263 deletions.
16 changes: 5 additions & 11 deletions book/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,20 +15,14 @@
* [Validator Management](./validator-management.md)
* [Importing from the Eth2 Launchpad](./validator-import-launchpad.md)
* [Local Testnets](./local-testnets.md)
* [API](./api.md)
* [HTTP (RESTful JSON)](./http.md)
* [/node](./http/node.md)
* [/beacon](./http/beacon.md)
* [/validator](./http/validator.md)
* [/consensus](./http/consensus.md)
* [/network](./http/network.md)
* [/spec](./http/spec.md)
* [/advanced](./http/advanced.md)
* [/lighthouse](./http/lighthouse.md)
* [WebSocket](./websockets.md)
* [APIs](./api.md)
* [Beacon Node API](./api-bn.md)
* [/lighthouse](./api-lighthouse.md)
* [Validator Client API](./api-vc.md)
* [Advanced Usage](./advanced.md)
* [Database Configuration](./advanced_database.md)
* [Prometheus Metrics](./advanced_metrics.md)
* [Validator Inclusion APIs](./validator-inclusion.md)
* [Contributing](./contributing.md)
* [Development Environment](./setup.md)
* [FAQs](./faq.md)
93 changes: 93 additions & 0 deletions book/src/api-bn.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Beacon Node API

Lighthouse implements the standard [Eth2 Beacon Node API
specification][OpenAPI]. Please follow that link for a full description of each API endpoint.

## Starting the server

A Lighthouse beacon node can be configured to expose a HTTP server by supplying the `--http` flag. The default listen address is `127.0.0.1:5052`.

The following CLI flags control the HTTP server:

- `--http`: enable the HTTP server (required even if the following flags are
provided).
- `--http-port`: specify the listen port of the server.
- `--http-address`: specify the listen address of the server.

The schema of the API aligns with the standard Eth2 Beacon Node API as defined
at [github.com/ethereum/eth2.0-APIs](https://github.com/ethereum/eth2.0-APIs).
An interactive specification is available [here][OpenAPI].

## Examples

### View the head of the beacon chain

Returns the block header at the head of the canonical chain.

```bash
curl -X GET "http://localhost:5052/eth/v1/beacon/headers/head" -H "accept:
application/json"
```

```json
{
"data": {
"root": "0x4381454174fc28c7095077e959dcab407ae5717b5dca447e74c340c1b743d7b2",
"canonical": true,
"header": {
"message": {
"slot": 3199,
"proposer_index": "19077",
"parent_root": "0xf1934973041c5896d0d608e52847c3cd9a5f809c59c64e76f6020e3d7cd0c7cd",
"state_root": "0xe8e468f9f5961655dde91968f66480868dab8d4147de9498111df2b7e4e6fe60",
"body_root": "0x6f183abc6c4e97f832900b00d4e08d4373bfdc819055d76b0f4ff850f559b883"
},
"signature": "0x988064a2f9cf13fe3aae051a3d85f6a4bca5a8ff6196f2f504e32f1203b549d5f86a39c6509f7113678880701b1881b50925a0417c1c88a750c8da7cd302dda5aabae4b941e3104d0cf19f5043c4f22a7d75d0d50dad5dbdaf6991381dc159ab"
}
}
}
```

### View the status of a validator

Shows the status of validator at index `1` at the `head` state.

```bash
curl -X GET "http://localhost:5052/eth/v1/beacon/states/head/validators/1" -H "accept: application/json"
```

```json
{
"data": {
"index": "1",
"balance": "63985937939",
"status": "Active",
"validator": {
"pubkey": "0x873e73ee8b3e4fcf1d2fb0f1036ba996ac9910b5b348f6438b5f8ef50857d4da9075d0218a9d1b99a9eae235a39703e1",
"withdrawal_credentials": "0x00b8cdcf79ba7e74300a07e9d8f8121dd0d8dd11dcfd6d3f2807c45b426ac968",
"effective_balance": 32000000000,
"slashed": false,
"activation_eligibility_epoch": 0,
"activation_epoch": 0,
"exit_epoch": 18446744073709552000,
"withdrawable_epoch": 18446744073709552000
}
}
}
```

## Troubleshooting

### HTTP API is unavailable or refusing connections

Ensure the `--http` flag has been supplied at the CLI.

You can quickly check that the HTTP endpoint is up using `curl`:

```
curl "localhost:5052/beacon/head"
{"slot":37934,"block_root":"0x4d3ae7ebe8c6ef042db05958ec76e8f7be9d412a67a0defa6420a677249afdc7","state_root":"0x1c86b13ffc70a41e410eccce20d33f1fe59d148585ea27c2afb4060f75fe6be2","finalized_slot":37856,"finalized_block_root":"0xbdae152b62acef1e5c332697567d2b89e358628790b8273729096da670b23e86","justified_slot":37888,"justified_block_root":"0x01c2f516a407d8fdda23cad4ed4381e4ab8913d638f935a2fe9bd00d6ced5ec4","previous_justified_slot":37856,"previous_justified_block_root":"0xbdae152b62acef1e5c332697567d2b89e358628790b8273729096da670b23e86"}
```

[OpenAPI]: https://ethereum.github.io/eth2.0-APIs/#/
180 changes: 180 additions & 0 deletions book/src/api-lighthouse.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
# Lighthouse APIs


Lighthouse fully supports the standards efforts at
[github.com/ethereum/eth2.0-APIs](https://github.com/ethereum/eth2.0-APIs),
however sometimes the Lighthouse developers require additional endpoints that
shouldn't necessarily be defined as a standard for all Eth2 clients to follow.
Such endpoints are placed behind the `/lighthouse` path.

The endpoints behind the `/lighthouse` path are:

- Not intended to be stable.
- Not guaranteed to be safe.
- For testing and debugging purposes only.

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`

*Presently only available on Linux.*

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

```json
{
"data": {
"pid": 1728254,
"pid_num_threads": 47,
"pid_mem_resident_set_size": 510054400,
"pid_mem_virtual_memory_size": 3963158528,
"sys_virt_mem_total": 16715530240,
"sys_virt_mem_available": 4065374208,
"sys_virt_mem_used": 11383402496,
"sys_virt_mem_free": 1368662016,
"sys_virt_mem_percent": 75.67906,
"sys_loadavg_1": 4.92,
"sys_loadavg_5": 5.53,
"sys_loadavg_15": 5.58
}
}
```

### `/lighthouse/syncing`

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

```json
{
"data": {
"SyncingFinalized": {
"start_slot": 3104,
"head_slot": 343744,
"head_root": "0x1b434b5ed702338df53eb5e3e24336a90373bb51f74b83af42840be7421dd2bf"
}
}
}
```

### `/lighthouse/peers`

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

```json
[
{
"peer_id": "16Uiu2HAmA9xa11dtNv2z5fFbgF9hER3yq35qYNTPvN7TdAmvjqqv",
"peer_info": {
"_status": "Healthy",
"score": {
"score": 0
},
"client": {
"kind": "Lighthouse",
"version": "v0.2.9-1c9a055c",
"os_version": "aarch64-linux",
"protocol_version": "lighthouse/libp2p",
"agent_string": "Lighthouse/v0.2.9-1c9a055c/aarch64-linux"
},
"connection_status": {
"status": "disconnected",
"connections_in": 0,
"connections_out": 0,
"last_seen": 1082,
"banned_ips": []
},
"listening_addresses": [
"/ip4/80.109.35.174/tcp/9000",
"/ip4/127.0.0.1/tcp/9000",
"/ip4/192.168.0.73/tcp/9000",
"/ip4/172.17.0.1/tcp/9000",
"/ip6/::1/tcp/9000"
],
"sync_status": {
"Advanced": {
"info": {
"status_head_slot": 343829,
"status_head_root": "0xe34e43efc2bb462d9f364bc90e1f7f0094e74310fd172af698b5a94193498871",
"status_finalized_epoch": 10742,
"status_finalized_root": "0x1b434b5ed702338df53eb5e3e24336a90373bb51f74b83af42840be7421dd2bf"
}
}
},
"meta_data": {
"seq_number": 160,
"attnets": "0x0000000800000080"
}
}
}
]
```

### `/lighthouse/peers/connected`

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

```json
[
{
"peer_id": "16Uiu2HAkzJC5TqDSKuLgVUsV4dWat9Hr8EjNZUb6nzFb61mrfqBv",
"peer_info": {
"_status": "Healthy",
"score": {
"score": 0
},
"client": {
"kind": "Lighthouse",
"version": "v0.2.8-87181204+",
"os_version": "x86_64-linux",
"protocol_version": "lighthouse/libp2p",
"agent_string": "Lighthouse/v0.2.8-87181204+/x86_64-linux"
},
"connection_status": {
"status": "connected",
"connections_in": 1,
"connections_out": 0,
"last_seen": 0,
"banned_ips": []
},
"listening_addresses": [
"/ip4/34.204.178.218/tcp/9000",
"/ip4/127.0.0.1/tcp/9000",
"/ip4/172.31.67.58/tcp/9000",
"/ip4/172.17.0.1/tcp/9000",
"/ip6/::1/tcp/9000"
],
"sync_status": "Unknown",
"meta_data": {
"seq_number": 1819,
"attnets": "0xffffffffffffffff"
}
}
}
]
```

### `/lighthouse/proto_array`

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

*Example omitted for brevity.*

### `/lighthouse/validator_inclusion/{epoch}/{validator_id}`

See [Validator Inclusion APIs](./validator-inclusion.md).

### `/lighthouse/validator_inclusion/{epoch}/global`

See [Validator Inclusion APIs](./validator-inclusion.md).
3 changes: 3 additions & 0 deletions book/src/api-vc.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Validator Client API

The validator client API is planned for release in late September 2020.
14 changes: 5 additions & 9 deletions book/src/api.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
# APIs

The Lighthouse `beacon_node` provides two APIs for local consumption:
Lighthouse allows users to query the state of Eth2.0 using a
industry-standard, RESTful HTTP/JSON APIs.

- A [RESTful JSON HTTP API](http.html) which provides beacon chain, node and network
information.
- A read-only [WebSocket API](websockets.html) providing beacon chain events, as they occur.
Read about the two different APIs served by Lighthouse:


## Security

These endpoints are not designed to be exposed to the public Internet or
untrusted users. They may pose a considerable DoS attack vector when used improperly.
- [Beacon Node API](./api-bn.md)
- [Validator Client API](./api-vc.md) (not yet released).
26 changes: 8 additions & 18 deletions book/src/http.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# HTTP API

[OpenAPI Specification](https://ethereum.github.io/eth2.0-APIs/#/)

## Beacon Node

A Lighthouse beacon node can be configured to expose a HTTP server by supplying the `--http` flag. The default listen address is `localhost:5052`.

The following CLI flags control the HTTP server:
Expand All @@ -9,24 +13,10 @@ The following CLI flags control the HTTP server:
- `--http-port`: specify the listen port of the server.
- `--http-address`: specify the listen address of the server.

The API is logically divided into several core endpoints, each documented in
detail:

Endpoint | Description |
| --- | -- |
[`/node`](./http/node.md) | General information about the beacon node.
[`/beacon`](./http/beacon.md) | General information about the beacon chain.
[`/validator`](./http/validator.md) | Provides functionality to validator clients.
[`/consensus`](./http/consensus.md) | Proof-of-stake voting statistics.
[`/network`](./http/network.md) | Information about the p2p network.
[`/spec`](./http/spec.md) | Information about the specs that the client is running.
[`/advanced`](./http/advanced.md) | Provides endpoints for advanced inspection of Lighthouse specific objects.
[`/lighthouse`](./http/lighthouse.md) | Provides lighthouse specific endpoints.

_Please note: The OpenAPI format at
[SwaggerHub: Lighthouse REST
API](https://app.swaggerhub.com/apis-docs/spble/lighthouse_rest_api/0.2.0) has
been **deprecated**. This documentation is now the source of truth for the REST API._
The schema of the API aligns with the standard Eth2 Beacon Node API as defined
at [github.com/ethereum/eth2.0-APIs](https://github.com/ethereum/eth2.0-APIs).
It is an easy-to-use RESTful HTTP/JSON API. An interactive specification is
available [here](https://ethereum.github.io/eth2.0-APIs/#/).

## Troubleshooting

Expand Down
Loading

0 comments on commit 008c206

Please sign in to comment.