gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-04-29 18:53:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make API friendly to block explorers (#702)

Browse Source 
* Add validator index to duties response

* Add `get_state` method to beacon chain

* Improve /beacon/validators endpoint

* Add validators/all and validators/active endpoints

* Start refactor of HTTP docs

* Document /beacon/heads endpoint

* Remove some unused API endpoints

* Improve API docs

* Add methods to get all validator duties

* Improve docs

* Remove dead links

* Make tables left-justified

* Add /consensus/vote_count endpoint

* Add /consensus/individual_votes endpoint

* Update formatting

* Tidy

* Add committees endpoint

* Strictly require 0x prefix for serde in BLS

* Update docs to have 0x prefix

* Fix failing tests

* Add unfinished code

* Improve testing, fix bugs

* Tidy, ensure all beacon endpoints smoke tested

* Fix pubkey cache error

* Address comments with docs
This commit is contained in:
Paul Hauner
2019-12-19 11:45:28 +11:00
committed by GitHub
parent d756bc9ecd
commit 251aea645c
28 changed files with 1831 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
book/src/SUMMARY.md
View File

@@ -9,6 +9,10 @@
* [Simple Local Testnet](./simple-testnet.md)
* [API](./api.md)
* [HTTP (RESTful JSON)](./http.md)
* [/beacon](./http_beacon.md)
* [/validator](./http_validator.md)
* [/consensus](./http_consensus.md)
* [/network](./http_network.md)
* [WebSocket](./websockets.md)
* [Contributing](./contributing.md)
* [Development Environment](./setup.md)

4
book/src/css/custom.css Normal file
View File

@@ -0,0 +1,4 @@
table {
margin: 0;
border-collapse: collapse;
}

96
book/src/http.md
View File

@@ -1,85 +1,39 @@
# HTTP API
[![Swagger Badge]][Swagger Link]
[Swagger Badge]: https://img.shields.io/badge/Open%20API-0.2.0-success
[Swagger Link]: https://app.swaggerhub.com/apis-docs/spble/lighthouse_rest_api/0.2.0
**The Lighthouse API is documented in Open API format and is available at
[SwaggerHub: Lighthouse REST
API](https://app.swaggerhub.com/apis-docs/spble/lighthouse_rest_api/0.2.0).**
By default, a Lighthouse `beacon_node` exposes a HTTP server on `localhost:5052`.
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:
- `--no-api`: disable the HTTP server.
- `--api-port`: specify the listen port of the server.
- `--api-address`: specify the listen address of the 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.
## Examples
The API is logically divided into several core endpoints, each documented in
detail:
In addition to the complete Open API docs (see above), some examples are
provided below.
Endpoint | Description |
| --- | -- |
[`/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.
_Examples assume there is a Lighthouse node exposing a HTTP API on
`localhost:5052`. Responses are JSON._
_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._
### Get the node's beacon chain head
## Troubleshooting
```bash
$ curl localhost:5052/beacon/head
### 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`:
{"slot":0,"block_root":"0x827bf71805540aa13f6d8c7d18b41b287b2094a4d7a28cbb8deb061dbf5df4f5","state_root":"0x90a78d73294bc9c7519a64e1912161be0e823eb472012ff54204e15a4d717fa5"}%
```
curl "localhost:5052/beacon/head"
### Get the node's finalized checkpoint
```bash
$ curl localhost:5052/beacon/latest_finalized_checkpoint
{"epoch":0,"root":"0x0000000000000000000000000000000000000000000000000000000000000000"}%
```
### Get the node's ENR
```bash
$ curl localhost:5052/network/enr
"-IW4QFyf1VlY5pZs0xZuvKMRZ9_cdl9WMCDAAJXZiZiuGcfRYoU40VPrYDLQj5prneJIz3zcbTjHp9BbThc-yiymJO8HgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5"%
```
### Get a list of connected peer ids
```bash
$ curl localhost:5052/network/peers
["QmeMFRTWfo3KbVG7dEBXGhyRMa29yfmnJBXW84rKuGEhuL"]%
```
### Get the node's peer id
```bash
$ curl localhost:5052/network/peer_id
"QmRD1qs2AqNNRdBcGHUGpUGkpih5cmdL32mhh22Sy79xsJ"%
```
### Get the list of listening libp2p addresses
Lists all the libp2p multiaddrs that the node is listening on.
```bash
$ curl localhost:5052/network/listen_addresses
["/ip4/127.0.0.1/tcp/9000","/ip4/192.168.1.121/tcp/9000","/ip4/172.17.0.1/tcp/9000","/ip4/172.42.0.1/tcp/9000","/ip6/::1/tcp/9000","/ip6/fdd3:c293:1bc::203/tcp/9000","/ip6/fdd3:c293:1bc:0:9aa9:b2ea:c610:44db/tcp/9000"]%
```
### Pretty-print the genesis state and state root
Returns the genesis state and state root in your terminal, in YAML.
```bash
$ curl --header "Content-Type: application/yaml" "localhost:5052/beacon/state?slot=0"
{"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"}
```

431
book/src/http_beacon.md Normal file
View File

@@ -0,0 +1,431 @@
# Lighthouse REST API: `/beacon`
The `/beacon` endpoints provide information about the canonical head of the
beacon chain and also historical information about beacon blocks and states.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/beacon/head`](#beaconhead) | Info about the block at the head of the chain.
[`/beacon/heads`](#beaconheads) | Returns a list of all known chain heads.
[`/beacon/block_root`](#beaconblock_root) | Resolve a slot to a block root.
[`/beacon/block`](#beaconblock) | Get a `BeaconBlock` by slot or root.
[`/beacon/state_root`](#beaconstate_root) | Resolve a slot to a state root.
[`/beacon/state`](#beaconstate) | Get a `BeaconState` by slot or root.
[`/beacon/validators`](#beaconvalidators) | Query for one or more validators.
[`/beacon/validators/all`](#beaconvalidatorsall) | Get all validators.
[`/beacon/validators/active`](#beaconvalidatorsactive) | Get all active validators.
[`/beacon/committees`](#beaconcommittees) | Get the shuffling for an epoch.
## `/beacon/head`
Requests information about the head of the beacon chain, from the node's
perspective.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/head`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
{
"slot": 37923,
"block_root": "0xe865d4805395a0776b8abe46d714a9e64914ab8dc5ff66624e5a1776bcc1684b",
"state_root": "0xe500e3567ab273c9a6f8a057440deff476ab236f0983da27f201ee9494a879f0",
"finalized_slot": 37856,
"finalized_block_root": "0xbdae152b62acef1e5c332697567d2b89e358628790b8273729096da670b23e86",
"justified_slot": 37888,
"justified_block_root": "0x01c2f516a407d8fdda23cad4ed4381e4ab8913d638f935a2fe9bd00d6ced5ec4",
"previous_justified_slot": 37856,
"previous_justified_block_root": "0xbdae152b62acef1e5c332697567d2b89e358628790b8273729096da670b23e86"
}
```
## `/beacon/heads`
Returns the roots of all known head blocks. Only one of these roots is the
canonical head and that is decided by the fork choice algorithm. See [`/beacon/head`](#beaconhead) for the canonical head.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/heads`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
[
{
"beacon_block_root": "0x226b2fd7c5f3d31dbb21444b96dfafe715f0017cd16545ecc4ffa87229496a69",
"beacon_block_slot": 38373
},
{
"beacon_block_root": "0x41ed5b253c4fc841cba8a6d44acbe101866bc674c3cfa3c4e9f7388f465aa15b",
"beacon_block_slot": 38375
}
]
```
## `/beacon/block_root`
Returns the block root for the given slot in the canonical chain. If there
is a re-org, the same slot may return a different root.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/block_root`
Method | GET
JSON Encoding | Object
Query Parameters | `slot`
Typical Responses | 200, 404
## Parameters
- `slot` (`Slot`): the slot to be resolved to a root.
### Example Response
```json
"0xc35ddf4e71c31774e0594bd7eb32dfe50b54dbc40abd594944254b4ec8895196"
```
## `/beacon/block`
Request that the node return a beacon chain block that matches the provided
criteria (a block `root` or beacon chain `slot`). Only one of the parameters
should be provided as a criteria.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/block`
Method | GET
JSON Encoding | Object
Query Parameters | `slot`, `root`
Typical Responses | 200, 404
### Parameters
Accepts **only one** of the following parameters:
- `slot` (`Slot`): Query by slot number. Any block returned must be in the canonical chain (i.e.,
either the head or an ancestor of the head).
- `root` (`Bytes32`): Query by tree hash root. A returned block is not required to be in the
canonical chain.
### Returns
Returns an object containing a single [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/v0.9.2/specs/core/0_beacon-chain.md#beaconblock) and its signed root.
### Example Response
```json
{
"root": "0xc35ddf4e71c31774e0594bd7eb32dfe50b54dbc40abd594944254b4ec8895196",
"beacon_block": {
"slot": 0,
"parent_root": "0x0000000000000000000000000000000000000000000000000000000000000000",
"state_root": "0xf15690b6be4ed42ea1ee0741eb4bfd4619d37be8229b84b4ddd480fb028dcc8f",
"body": {
"randao_reveal": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"eth1_data": {
"deposit_root": "0x0000000000000000000000000000000000000000000000000000000000000000",
"deposit_count": 0,
"block_hash": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"graffiti": "0x0000000000000000000000000000000000000000000000000000000000000000",
"proposer_slashings": [],
"attester_slashings": [],
"attestations": [],
"deposits": [],
"voluntary_exits": []
},
"signature": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
}
}
```
## `/beacon/state_root`
Returns the state root for the given slot in the canonical chain. If there
is a re-org, the same slot may return a different root.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/state_root`
Method | GET
JSON Encoding | Object
Query Parameters | `slot`
Typical Responses | 200, 404
## Parameters
- `slot` (`Slot`): the slot to be resolved to a root.
### Example Response
```json
"0xf15690b6be4ed42ea1ee0741eb4bfd4619d37be8229b84b4ddd480fb028dcc8f"
```
## `/beacon/state`
Request that the node return a beacon chain state that matches the provided
criteria (a state `root` or beacon chain `slot`). Only one of the parameters
should be provided as a criteria.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/state`
Method | GET
JSON Encoding | Object
Query Parameters | `slot`, `root`
Typical Responses | 200, 404
### Parameters
Accepts **only one** of the following parameters:
- `slot` (`Slot`): Query by slot number. Any state returned must be in the canonical chain (i.e.,
either the head or an ancestor of the head).
- `root` (`Bytes32`): Query by tree hash root. A returned state is not required to be in the
canonical chain.
### Returns
Returns an object containing a single
[`BeaconState`](https://github.com/ethereum/eth2.0-specs/blob/v0.9.2/specs/core/0_beacon-chain.md#beaconstate)
and its tree hash root.
### Example Response
```json
{
"root": "0x528e54ca5d4c957729a73f40fc513ae312e054c7295775c4a2b21f423416a72b",
"beacon_state": {
"genesis_time": 1575652800,
"slot": 18478
}
}
```
_Truncated for brevity._
## `/beacon/validators`
Request that the node returns information about one or more validator public
keys. This request takes the form of a `POST` request to allow sending a large
number of pubkeys in the request.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/validators`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Request Body
Expects the following object in the POST request body:
```
{
state_root: Bytes32,
pubkeys: [PublicKey]
}
```
The `state_root` field indicates which `BeaconState` should be used to collect
the information. The `state_root` is optional and omitting it will result in
the canonical head state being used.
### Returns
Returns an object describing several aspects of the given validator.
### Example
### Request Body
```json
{
"pubkeys": [
"0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42"
]
}
```
_Note: for demonstration purposes the second pubkey is some unknown pubkey._
### Response Body
```json
[
{
"pubkey": "0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"validator_index": 14935,
"balance": 3228885987,
"validator": {
"pubkey": "0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"withdrawal_credentials": "0x00b7bec22d5bda6b2cca1343d4f640d0e9ccc204a06a73703605c590d4c0d28e",
"effective_balance": 3200000000,
"slashed": false,
"activation_eligibility_epoch": 0,
"activation_epoch": 0,
"exit_epoch": 18446744073709551615,
"withdrawable_epoch": 18446744073709551615
}
},
{
"pubkey": "0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42",
"validator_index": null,
"balance": null,
"validator": null
}
]
```
## `/beacon/validators/all`
Returns all validators.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/validators/all`
Method | GET
JSON Encoding | Object
Query Parameters | `state_root` (optional)
Typical Responses | 200
### Parameters
The optional `state_root` (`Bytes32`) query parameter indicates which
`BeaconState` should be used to collect the information. When omitted, the
canonical head state will be used.
### Returns
The return format is identical to the [`/beacon/validators`](#beaconvalidators) response body.
## `/beacon/validators/active`
Returns all validators that are active in the state defined by `state_root`.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/validators/active`
Method | GET
JSON Encoding | Object
Query Parameters | `state_root` (optional)
Typical Responses | 200
### Parameters
The optional `state_root` (`Bytes32`) query parameter indicates which
`BeaconState` should be used to collect the information. When omitted, the
canonical head state will be used.
### Returns
The return format is identical to the [`/beacon/validators`](#beaconvalidators) response body.
## `/beacon/committees`
Request the committees (a.k.a. "shuffling") for all slots and committee indices
in a given `epoch`.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/committees`
Method | GET
JSON Encoding | Object
Query Parameters | `epoch`
Typical Responses | 200
### Parameters
The `epoch` (`Epoch`) query parameter is required and defines the epoch for
which the committees will be returned. All slots contained within the response will
be inside this epoch.
### Returns
A list of beacon committees.
### Example Response
```json
[
{
"slot": 4768,
"index": 0,
"committee": [
1154,
492,
9667,
3089,
8987,
1421,
224,
11243,
2127,
2329,
188,
482,
486
]
},
{
"slot": 4768,
"index": 1,
"committee": [
5929,
8482,
5528,
6130,
14343,
9777,
10808,
12739,
15234,
12819,
5423,
6320,
9991
]
}
]
```
_Truncated for brevity._

189
book/src/http_consensus.md Normal file
View File

@@ -0,0 +1,189 @@
# Lighthouse REST API: `/consensus`
The `/consensus` endpoints provide information on results of the proof-of-stake
voting process used for finality/justification under Casper FFG.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/consensus/global_votes`](#consensusglobal_votes) | A global vote count for a given epoch.
[`/consensus/individual_votes`](#consensusindividual_votes) | A per-validator breakdown of votes in a given epoch.
## `/consensus/global_votes`
Returns a global count of votes for some given `epoch`. The results are included
both for the current and previous (`epoch - 1`) epochs since both are required
by the beacon node whilst performing per-epoch-processing.
Generally, you should consider the "current" values to be incomplete and the
"previous" values to be final. This is because validators can continue to
include attestations from the _current_ epoch in the _next_ epoch, however this
is not the case for attestations from the _previous_ epoch.
```
`epoch` query parameter
|
| --------- values are calcuated here
| |
v v
Epoch: |---previous---|---current---|---next---|
|-------------|
^
|
window for including "current" attestations
in a block
```
The votes are expressed in terms of staked _effective_ `Gwei` (i.e., not the number of
individual validators). For example, if a validator has 32 ETH staked they will
increase the `current_epoch_attesting_gwei` figure by `32,000,000,000` if they
have an attestation included in a block during the current epoch. If this
validator has more than 32 ETH, that extra ETH will not count towards their
vote (that is why it is _effective_ `Gwei`).
The following fields are returned:
- `current_epoch_active_gwei`: the total staked gwei that was active (i.e.,
able to vote) during the current epoch.
- `current_epoch_attesting_gwei`: the total staked gwei that had one or more
attestations included in a block during the current epoch (multiple
attestations by the same validator do not increase this figure).
- `current_epoch_target_attesting_gwei`: the total staked gwei that attested to
the majority-elected Casper FFG target epoch during the current epoch. This
figure must be equal to or less than `current_epoch_attesting_gwei`.
- `previous_epoch_active_gwei`: as above, but during the previous epoch.
- `previous_epoch_attesting_gwei`: see `current_epoch_attesting_gwei`.
- `previous_epoch_target_attesting_gwei`: see `current_epoch_target_attesting_gwei`.
- `previous_epoch_head_attesting_gwei`: the total staked gwei that attested to a
head beacon block that is in the canonical chain.
From this data you can calculate some interesting figures:
#### Participation Rate
`previous_epoch_attesting_gwei / previous_epoch_active_gwei`
Expresses the ratio of validators that managed to have an attestation
voting upon the previous epoch included in a block.
#### Justification/Finalization Rate
`previous_epoch_target_attesting_gwei / previous_epoch_active_gwei`
When this value is greater than or equal to `2/3` it is possible that the
beacon chain may justify and/or finalize the epoch.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/consensus/global_votes`
Method | GET
JSON Encoding | Object
Query Parameters | `epoch`
Typical Responses | 200
### Parameters
Requires the `epoch` (`Epoch`) query parameter to determine which epoch will be
considered the current epoch.
### Returns
A report on global validator voting participation.
### Example
```json
{
"current_epoch_active_gwei": 52377600000000,
"previous_epoch_active_gwei": 52377600000000,
"current_epoch_attesting_gwei": 50740900000000,
"current_epoch_target_attesting_gwei": 49526000000000,
"previous_epoch_attesting_gwei": 52377600000000,
"previous_epoch_target_attesting_gwei": 51063400000000,
"previous_epoch_head_attesting_gwei": 9248600000000
}
```
## `/consensus/individual_votes`
Returns a per-validator summary of how that validator performed during the
current epoch.
The [Global Votes](#consensusglobal_votes) endpoint is the summation of all of these
individual values, please see it for definitions of terms like "current_epoch",
"previous_epoch" and "target_attester".
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/consensus/individual_votes`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Request Body
Expects the following object in the POST request body:
```
{
epoch: Epoch,
pubkeys: [PublicKey]
}
```
### Returns
A report on the validators voting participation.
### Example
#### Request Body
```json
{
"epoch": 1203,
"pubkeys": [
"0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42"
]
}
```
_Note: for demonstration purposes the second pubkey is some unknown pubkey._
#### Response Body
```json
[
{
"epoch": 1203,
"pubkey": "0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"validator_index": 14935,
"vote": {
"is_slashed": false,
"is_withdrawable_in_current_epoch": false,
"is_active_in_current_epoch": true,
"is_active_in_previous_epoch": true,
"current_epoch_effective_balance_gwei": 3200000000,
"is_current_epoch_attester": true,
"is_current_epoch_target_attester": true,
"is_previous_epoch_attester": true,
"is_previous_epoch_target_attester": true,
"is_previous_epoch_head_attester": false
}
},
{
"epoch": 1203,
"pubkey": "0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42",
"validator_index": null,
"vote": null
}
]
```

75
book/src/http_network.md Normal file
View File

@@ -0,0 +1,75 @@
# Lighthouse REST API: `/network`
The `/network` endpoints provide information about the p2p network that
Lighthouse uses to communicate with other beacon nodes.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/network/peer_id`](#networkpeer_id) | Get a node's libp2p `PeerId`.
[`/network/peers`](#networkpeers) | List a node's libp2p peers (as `PeerIds`).
[`/network/enr`](#networkenr) | Get a node's discovery `ENR` address.
## `/network/peer_id`
Requests the beacon node's local `PeerId`.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/network/peer_id`
Method | GET
JSON Encoding | String (base58)
Query Parameters | None
Typical Responses | 200
### Example Response
```json
"QmVFcULBYZecPdCKgGmpEYDqJLqvMecfhJadVBtB371Avd"
```
## `/network/peers`
Requests one `MultiAddr` for each peer connected to the beacon node.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/network/peers`
Method | GET
JSON Encoding | [String] (base58)
Query Parameters | None
Typical Responses | 200
### Example Response
```json
[
"QmaPGeXcfKFMU13d8VgbnnpeTxcvoFoD9bUpnRGMUJ1L9w",
"QmZt47cP8V96MgiS35WzHKpPbKVBMqr1eoBNTLhQPqpP3m"
]
```
## `network/enr`
Requests the beacon node for its listening `ENR` address.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/network/enr`
Method | GET
JSON Encoding | String (base64)
Query Parameters | None
Typical Responses | 200
### Example Response
```json
"-IW4QPYyGkXJSuJ2Eji8b-m4PTNrW4YMdBsNOBrYAdCk8NLMJcddAiQlpcv6G_hdNjiLACOPTkqTBhUjnC0wtIIhyQkEgmlwhKwqAPqDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhA1sBKo0yCfw4Z_jbggwflNfftjwKACu-a-CoFAQHJnrm"
```

153
book/src/http_validator.md Normal file
View File

@@ -0,0 +1,153 @@
# Lighthouse REST API: `/validator`
The `/validator` endpoints provide the minimum functionality required for a validator
client to connect to the beacon node and produce blocks and attestations.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/validator/duties`](#validatorduties) | Provides block and attestation production information for validators.
[`/validator/duties/all`](#validatordutiesall) | Provides block and attestation production information for all validators.
[`/validator/duties/active`](#validatordutiesactive) | Provides block and attestation production information for all active validators.
## `/validator/duties`
Request information about when a validator must produce blocks and attestations
at some given `epoch`. The information returned always refers to the canonical
chain and the same input parameters may yield different results after a re-org.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/duties`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Request Body
Expects the following object in the POST request body:
```
{
epoch: Epoch,
pubkeys: [PublicKey]
}
```
Duties are assigned on a per-epoch basis, all duties returned will contain
slots that are inside the given `epoch`. A set of duties will be returned for
each of the `pubkeys`.
Validators who are not known to the beacon chain (e.g., have not yet deposited)
will have `null` values for most fields.
### Returns
A set of duties for each given pubkey.
### Example
#### Request Body
```json
{
"epoch": 1203,
"pubkeys": [
"0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42"
]
}
```
_Note: for demonstration purposes the second pubkey is some unknown pubkey._
#### Response Body
```json
[
{
"validator_pubkey": "0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"validator_index": 14935,
"attestation_slot": 38511,
"attestation_committee_index": 3,
"attestation_committee_position": 39,
"block_proposal_slots": []
},
{
"validator_pubkey": "0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42",
"validator_index": null,
"attestation_slot": null,
"attestation_committee_index": null,
"attestation_committee_position": null,
"block_proposal_slots": []
}
]
```
## `/validator/duties/all`
Returns the duties for all validators, equivalent to calling [Validator
Duties](#validator-duties) while providing all known validator public keys.
Considering that duties for non-active validators will just be `null`, it is
generally more efficient to query using [Active Validator
Duties](#active-validator-duties).
This endpoint will only return validators that were in the beacon state
in the given epoch. For example, if the query epoch is 10 and some validator
deposit was included in epoch 11, that validator will not be included in the
result.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/duties/all`
Method | GET
JSON Encoding | Object
Query Parameters | `epoch`
Typical Responses | 200
### Parameters
The duties returned will all be inside the given `epoch` (`Epoch`) query
parameter. This parameter is required.
### Returns
The return format is identical to the [Validator Duties](#validator-duties) response body.
## `/validator/duties/active`
Returns the duties for all active validators, equivalent to calling [Validator
Duties](#validator-duties) while providing all known validator public keys that
are active in the given epoch.
This endpoint will only return validators that were in the beacon state
in the given epoch. For example, if the query epoch is 10 and some validator
deposit was included in epoch 11, that validator will not be included in the
result.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/duties/active`
Method | GET
JSON Encoding | Object
Query Parameters | `epoch`
Typical Responses | 200
### Parameters
The duties returned will all be inside the given `epoch` (`Epoch`) query
parameter. This parameter is required.
### Returns
The return format is identical to the [Validator Duties](#validator-duties) response body.