gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-04-19 05:48:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Implement standard eth2.0 API (#1569)

Browse Source 
- Resolves #1550
- Resolves #824
- Resolves #825
- Resolves #1131
- Resolves #1411
- Resolves #1256
- Resolve #1177

- Includes the `ShufflingId` struct initially defined in #1492. That PR is now closed and the changes are included here, with significant bug fixes.
- Implement the https://github.com/ethereum/eth2.0-APIs in a new `http_api` crate using `warp`. This replaces the `rest_api` crate.
- Add a new `common/eth2` crate which provides a wrapper around `reqwest`, providing the HTTP client that is used by the validator client and for testing. This replaces the `common/remote_beacon_node` crate.
- Create a `http_metrics` crate which is a dedicated server for Prometheus metrics (they are no longer served on the same port as the REST API). We now have flags for `--metrics`, `--metrics-address`, etc.
- Allow the `subnet_id` to be an optional parameter for `VerifiedUnaggregatedAttestation::verify`. This means it does not need to be provided unnecessarily by the validator client.
- Move `fn map_attestation_committee` in `mod beacon_chain::attestation_verification` to a new `fn with_committee_cache` on the `BeaconChain` so the same cache can be used for obtaining validator duties.
- Add some other helpers to `BeaconChain` to assist with common API duties (e.g., `block_root_at_slot`, `head_beacon_block_root`).
- Change the `NaiveAggregationPool` so it can index attestations by `hash_tree_root(attestation.data)`. This is a requirement of the API.
- Add functions to `BeaconChainHarness` to allow it to create slashings and exits.
- Allow for `eth1::Eth1NetworkId` to go to/from a `String`.
- Add functions to the `OperationPool` to allow getting all objects in the pool.
- Add function to `BeaconState` to check if a committee cache is initialized.
- Fix bug where `seconds_per_eth1_block` was not transferring over from `YamlConfig` to `ChainSpec`.
- Add the `deposit_contract_address` to `YamlConfig` and `ChainSpec`. We needed to be able to return it in an API response.
- Change some uses of serde `serialize_with` and `deserialize_with` to a single use of `with` (code quality).
- Impl `Display` and `FromStr` for several BLS fields.
- Check for clock discrepancy when VC polls BN for sync state (with +/- 1 slot tolerance). This is not intended to be comprehensive, it was just easy to do.

- See #1434 for a per-endpoint overview.
- Seeking clarity here: https://github.com/ethereum/eth2.0-APIs/issues/75

- [x] Add docs for prom port to close #1256
- [x] Follow up on this #1177
- [x] ~~Follow up with #1424~~ Will fix in future PR.
- [x] Follow up with #1411
- [x] ~~Follow up with  #1260~~ Will fix in future PR.
- [x] Add quotes to all integers.
- [x] Remove `rest_types`
- [x] Address missing beacon block error. (#1629)
- [x] ~~Add tests for lighthouse/peers endpoints~~ Wontfix
- [x] ~~Follow up with validator status proposal~~ Tracked in #1434
- [x] Unify graffiti structs
- [x] ~~Start server when waiting for genesis?~~ Will fix in future PR.
- [x] TODO in http_api tests
- [x] Move lighthouse endpoints off /eth/v1
- [x] Update docs to link to standard

- ~~Blocked on #1586~~

Co-authored-by: Michael Sproul <michael@sigmaprime.io>
This commit is contained in:
Paul Hauner
2020-09-29 03:46:54 +00:00
parent 8e20176337
commit cdec3cec18
156 changed files with 8862 additions and 8916 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
book/src/SUMMARY.md
View File

@@ -14,20 +14,15 @@
* [Key recovery](./key-recovery.md)
* [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 Inclusion APIs](./validator-inclusion.md)
* [Validator Client API](./api-vc.md)
* [Prometheus Metrics](./advanced_metrics.md)
* [Advanced Usage](./advanced.md)
* [Database Configuration](./advanced_database.md)
* [Local Testnets](./local-testnets.md)
* [Contributing](./contributing.md)
* [Development Environment](./setup.md)
* [FAQs](./faq.md)

34
book/src/advanced_metrics.md Normal file
View File

@@ -0,0 +1,34 @@
# Prometheus Metrics
Lighthouse provides an extensive suite of metrics and monitoring in the
[Prometheus](https://prometheus.io/docs/introduction/overview/) export format
via a HTTP server built into Lighthouse.
These metrics are generally consumed by a Prometheus server and displayed via a
Grafana dashboard. These components are available in a docker-compose format at
[sigp/lighthouse-metrics](https://github.com/sigp/lighthouse-metrics).
## Beacon Node Metrics
By default, these metrics are disabled but can be enabled with the `--metrics`
flag. Use the `--metrics-address`, `--metrics-port` and
`--metrics-allow-origin` flags to customize the metrics server.
### Example
Start a beacon node with the metrics server enabled:
```bash
lighthouse bn --metrics
```
Check to ensure that the metrics are available on the default port:
```bash
curl localhost:5054/metrics
```
## Validator Client Metrics
The validator client does not *yet* expose metrics, however this functionality
is expected to be implemented in late-September 2020.

130
book/src/api-bn.md Normal file
View File

@@ -0,0 +1,130 @@
# 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.
> **Warning:** the standard API specification is still in flux and the Lighthouse implementation is partially incomplete. You can track the status of each endpoint at [#1434](https://github.com/sigp/lighthouse/issues/1434).
## 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.
- `--http-allow-origin`: specify the value of the `Access-Control-Allow-Origin`
header. The default is to not supply a header.
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].
### CLI Example
Start the beacon node with the HTTP server listening on [http://localhost:5052](http://localhost:5052):
```bash
lighthouse bn --http
```
## HTTP Request/Response Examples
This section contains some simple examples of using the HTTP API via `curl`.
All endpoints are documented in the [Eth2 Beacon Node API
specification][OpenAPI].
### 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`:
```bash
curl -X GET "http://localhost:5052/eth/v1/node/version" -H "accept: application/json"
```
The beacon node should respond with its version:
```json
{"data":{"version":"Lighthouse/v0.2.9-6f7b4768a/x86_64-linux"}}
```
If this doesn't work, the server might not be started or there might be a
network connection error.
### I cannot query my node from a web browser (e.g., Swagger)
By default, the API does not provide an `Access-Control-Allow-Origin` header,
which causes browsers to reject responses with a CORS error.
The `--http-allow-origin` flag can be used to add a wild-card CORS header:
```bash
lighthouse bn --http --http-allow-origin "*"
```
> **Warning:** Adding the wild-card allow-origin flag can pose a security risk.
> Only use it in production if you understand the risks of a loose CORS policy.
[OpenAPI]: https://ethereum.github.io/eth2.0-APIs/#/

179
book/src/api-lighthouse.md Normal file
View File

@@ -0,0 +1,179 @@
# Lighthouse Non-Standard APIs
Lighthouse fully supports the standardization efforts at
[github.com/ethereum/eth2.0-APIs](https://github.com/ethereum/eth2.0-APIs),
however sometimes development requires additional endpoints that shouldn't
necessarily be defined as a broad-reaching standard. 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
book/src/api-vc.md Normal file
View File

@@ -0,0 +1,3 @@
# Validator Client API
The validator client API is planned for release in late September 2020.

14
book/src/api.md
View File

@@ -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 web-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.
There are two 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
book/src/http.md
View File

@@ -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:
@@ -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

115
book/src/http/advanced.md
View File

@@ -1,115 +0,0 @@
# Lighthouse REST API: `/advanced`
The `/advanced` endpoints provide information Lighthouse specific data structures for advanced debugging.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/advanced/fork_choice`](#advancedfork_choice) | Get the `proto_array` fork choice object.
[`/advanced/operation_pool`](#advancedoperation_pool) | Get the Lighthouse `PersistedOperationPool` object.
## `/advanced/fork_choice`
Requests the `proto_array` fork choice object as represented in Lighthouse.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/advanced/fork_choice`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
{
"prune_threshold": 256,
"justified_epoch": 25,
"finalized_epoch": 24,
"nodes": [
{
"slot": 544,
"root": "0x27103c56d4427cb4309dd202920ead6381d54d43277c29cf0572ddf0d528e6ea",
"parent": null,
"justified_epoch": 16,
"finalized_epoch": 15,
"weight": 256000000000,
"best_child": 1,
"best_descendant": 296
},
{
"slot": 545,
"root": "0x09af0e8d4e781ea4280c9c969d168839c564fab3a03942e7db0bfbede7d4c745",
"parent": 0,
"justified_epoch": 16,
"finalized_epoch": 15,
"weight": 256000000000,
"best_child": 2,
"best_descendant": 296
},
],
"indices": {
"0xb935bb3651eeddcb2d2961bf307156850de982021087062033f02576d5df00a3": 59,
"0x8f4ec47a34c6c1d69ede64d27165d195f7e2a97c711808ce51f1071a6e12d5b9": 189,
"0xf675eba701ef77ee2803a130dda89c3c5673a604d2782c9e25ea2be300d7d2da": 173,
"0x488a483c8d5083faaf5f9535c051b9f373ba60d5a16e77ddb1775f248245b281": 37
}
}
```
_Truncated for brevity._
## `/advanced/operation_pool`
Requests the `PersistedOperationPool` object as represented in Lighthouse.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/advanced/operation_pool`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
{
"attestations": [
[
{
"v": [39, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 112, 118, 215, 252, 51, 186, 76, 156, 157, 99, 91, 4, 137, 195, 209, 224, 26, 233, 233, 184, 38, 89, 215, 177, 247, 97, 243, 119, 229, 69, 50, 90, 24, 0, 0, 0, 0, 0, 0, 0, 79, 37, 38, 210, 96, 235, 121, 142, 129, 136, 206, 214, 179, 132, 22, 19, 222, 213, 203, 46, 112, 192, 26, 5, 254, 26, 103, 170, 158, 205, 72, 3, 25, 0, 0, 0, 0, 0, 0, 0, 164, 50, 214, 67, 98, 13, 50, 180, 108, 232, 248, 109, 128, 45, 177, 23, 221, 24, 218, 211, 8, 152, 172, 120, 24, 86, 198, 103, 68, 164, 67, 202, 1, 0, 0, 0, 0, 0, 0, 0]
},
[
{
"aggregation_bits": "0x03",
"data": {
"slot": 807,
"index": 0,
"beacon_block_root": "0x7076d7fc33ba4c9c9d635b0489c3d1e01ae9e9b82659d7b1f761f377e545325a",
"source": {
"epoch": 24,
"root": "0x4f2526d260eb798e8188ced6b3841613ded5cb2e70c01a05fe1a67aa9ecd4803"
},
"target": {
"epoch": 25,
"root": "0xa432d643620d32b46ce8f86d802db117dd18dad30898ac781856c66744a443ca"
}
},
"signature": "0x8b1d624b0cd5a7a0e13944e90826878a230e3901db34ea87dbef5b145ade2fedbc830b6752a38a0937a1594211ab85b615d65f9eef0baccd270acca945786036695f4db969d9ff1693c505c0fe568b2fe9831ea78a74cbf7c945122231f04026"
}
]
]
],
"attester_slashings": [],
"proposer_slashings": [],
"voluntary_exits": []
}
```
_Truncated for brevity._

784
book/src/http/beacon.md
View File

@@ -1,784 +0,0 @@
# 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`](#beaconblock) | Get a `BeaconBlock` by slot or root.
[`/beacon/block_root`](#beaconblock_root) | Resolve a slot to a block root.
[`/beacon/fork`](#beaconfork) | Get the fork of the head of the chain.
[`/beacon/genesis_time`](#beacongenesis_time) | Get the genesis time from the beacon state.
[`/beacon/genesis_validators_root`](#beacongenesis_validators_root) | Get the genesis validators 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/state`](#beaconstate) | Get a `BeaconState` by slot or root.
[`/beacon/state_root`](#beaconstate_root) | Resolve a slot to a state root.
[`/beacon/state/genesis`](#beaconstategenesis) | Get a `BeaconState` at genesis.
[`/beacon/committees`](#beaconcommittees) | Get the shuffling for an epoch.
[`/beacon/proposer_slashing`](#beaconproposer_slashing) | Insert a proposer slashing
[`/beacon/attester_slashing`](#beaconattester_slashing) | Insert an attester slashing
## `/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`
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 [`SignedBeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/v0.10.0/specs/phase0/beacon-chain.md#signedbeaconblock) and the block root of the inner [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/v0.10.0/specs/phase0/beacon-chain.md#beaconblock).
### Example Response
```json
{
"root": "0xc35ddf4e71c31774e0594bd7eb32dfe50b54dbc40abd594944254b4ec8895196",
"beacon_block": {
"message": {
"slot": 0,
"proposer_index": 14,
"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/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/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/500
### 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._
## `/beacon/fork`
Request that the node return the `fork` of the current head.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/fork`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Returns
Returns an object containing the [`Fork`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#fork) of the current head.
### Example Response
```json
{
"previous_version": "0x00000000",
"current_version": "0x00000000",
"epoch": 0
}
```
## `/beacon/genesis_time`
Request that the node return the genesis time from the beacon state.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/genesis_time`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Returns
Returns an object containing the genesis time.
### Example Response
```json
1581576353
```
## `/beacon/genesis_validators_root`
Request that the node return the genesis validators root from the beacon state.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/genesis_validators_root`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Returns
Returns an object containing the genesis validators root.
### Example Response
```json
0x4fbf23439a7a9b9dd91650e64e8124012dde5e2ea2940c552b86f04eb47f95de
```
## `/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/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.12.1/specs/phase0/beacon-chain.md#beaconstate)
and its tree hash root.
### Example Response
```json
{
"root": "0x528e54ca5d4c957729a73f40fc513ae312e054c7295775c4a2b21f423416a72b",
"beacon_state": {
"genesis_time": 1575652800,
"genesis_validators_root": "0xa8a9226edee1b2627fb4117d7dea4996e64dec2998f37f6e824f74f2ce39a538",
"slot": 18478
}
}
```
_Truncated for brevity._
## `/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/genesis`
Request that the node return a beacon chain state at genesis (slot 0).
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/state/genesis`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Returns
Returns an object containing the genesis
[`BeaconState`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#beaconstate).
### Example Response
```json
{
"genesis_time": 1581576353,
"slot": 0,
"fork": {
"previous_version": "0x00000000",
"current_version": "0x00000000",
"epoch": 0
},
}
```
_Truncated for brevity._
## `/beacon/state/committees`
Request that the node return a beacon chain state at genesis (slot 0).
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/state/genesis`
Method | GET
JSON Encoding | Object
Query Parameters | `epoch`
Typical Responses | 200
### Returns
Returns an object containing the committees for a given epoch.
### Example Response
```json
[
{"slot":64,"index":0,"committee":[]},
{"slot":65,"index":0,"committee":[3]},
{"slot":66,"index":0,"committee":[]},
{"slot":67,"index":0,"committee":[14]},
{"slot":68,"index":0,"committee":[]},
{"slot":69,"index":0,"committee":[9]},
{"slot":70,"index":0,"committee":[]},
{"slot":71,"index":0,"committee":[11]},
{"slot":72,"index":0,"committee":[]},
{"slot":73,"index":0,"committee":[5]},
{"slot":74,"index":0,"committee":[]},
{"slot":75,"index":0,"committee":[15]},
{"slot":76,"index":0,"committee":[]},
{"slot":77,"index":0,"committee":[0]}
]
```
_Truncated for brevity._
## `/beacon/attester_slashing`
Accepts an `attester_slashing` and verifies it. If it is valid, it is added to the operations pool for potential inclusion in a future block. Returns a 400 error if the `attester_slashing` is invalid.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/attester_slashing`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200/400
### Parameters
Expects the following object in the POST request body:
```
{
attestation_1: {
attesting_indices: [u64],
data: {
slot: Slot,
index: u64,
beacon_block_root: Bytes32,
source: {
epoch: Epoch,
root: Bytes32
},
target: {
epoch: Epoch,
root: Bytes32
}
}
signature: Bytes32
},
attestation_2: {
attesting_indices: [u64],
data: {
slot: Slot,
index: u64,
beacon_block_root: Bytes32,
source: {
epoch: Epoch,
root: Bytes32
},
target: {
epoch: Epoch,
root: Bytes32
}
}
signature: Bytes32
}
}
```
### Returns
Returns `true` if the attester slashing was inserted successfully, or the corresponding error if it failed.
### Example
### Request Body
```json
{
"attestation_1": {
"attesting_indices": [0],
"data": {
"slot": 1,
"index": 0,
"beacon_block_root": "0x0000000000000000000000000000000000000000000000000100000000000000",
"source": {
"epoch": 1,
"root": "0x0000000000000000000000000000000000000000000000000100000000000000"
},
"target": {
"epoch": 1,
"root": "0x0000000000000000000000000000000000000000000000000100000000000000"
}
},
"signature": "0xb47f7397cd944b8d5856a13352166bbe74c85625a45b14b7347fc2c9f6f6f82acee674c65bc9ceb576fcf78387a6731c0b0eb3f8371c70db2da4e7f5dfbc451730c159d67263d3db56b6d0e009e4287a8ba3efcacac30b3ae3447e89dc71b5b9"
},
"attestation_2": {
"attesting_indices": [0],
"data": {
"slot": 1,
"index": 0,
"beacon_block_root": "0x0000000000000000000000000000000000000000000000000100000000000000",
"source": {
"epoch": 1,
"root": "0x0000000000000000000000000000000000000000000000000100000000000000"
},
"target": {
"epoch": 1,
"root": "0x0000000000000000000000000000000000000000000000000200000000000000"
}
},
"signature": "0x93fef587a63acf72aaf8df627718fd43cb268035764071f802ffb4370a2969d226595cc650f4c0bf2291ae0c0a41fcac1700f318603d75d34bcb4b9f4a8368f61eeea0e1f5d969d92d5073ba5fbadec102b45ec87d418d25168d2e3c74b9fcbb"
}
}
```
_Note: data sent here is for demonstration purposes only_
## `/beacon/proposer_slashing`
Accepts a `proposer_slashing` and verifies it. If it is valid, it is added to the operations pool for potential inclusion in a future block. Returns an 400 error if the `proposer_slashing` is invalid.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/beacon/proposer_slashing`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200/400
### Request Body
Expects the following object in the POST request body:
```
{
proposer_index: u64,
header_1: {
slot: Slot,
parent_root: Bytes32,
state_root: Bytes32,
body_root: Bytes32,
signature: Bytes32
},
header_2: {
slot: Slot,
parent_root: Bytes32,
state_root: Bytes32,
body_root: Bytes32,
signature: Bytes32
}
}
```
### Returns
Returns `true` if the proposer slashing was inserted successfully, or the corresponding error if it failed.
### Example
### Request Body
```json
{
"proposer_index": 0,
"header_1": {
"slot": 0,
"parent_root": "0x0101010101010101010101010101010101010101010101010101010101010101",
"state_root": "0x0101010101010101010101010101010101010101010101010101010101010101",
"body_root": "0x0101010101010101010101010101010101010101010101010101010101010101",
"signature": "0xb8970d1342c6d5779c700ec366efd0ca819937ca330960db3ca5a55eb370a3edd83f4cbb2f74d06e82f934fcbd4bb80609a19c2254cc8b3532a4efff9e80edf312ac735757c059d77126851e377f875593e64ba50d1dffe69a809a409202dd12"
},
"header_2": {
"slot": 0,
"parent_root": "0x0202020202020202020202020202020202020202020202020202020202020202",
"state_root": "0x0101010101010101010101010101010101010101010101010101010101010101",
"body_root": "0x0101010101010101010101010101010101010101010101010101010101010101",
"signature": "0xb60e6b348698a34e59b22e0af96f8809f977f00f95d52375383ade8d22e9102270a66c6d52b0434214897e11ca4896871510c01b3fd74d62108a855658d5705fcfc4ced5136264a1c6496f05918576926aa191b1ad311b7e27f5aa2167aba294"
}
}
```
_Note: data sent here is for demonstration purposes only_

182
book/src/http/lighthouse.md
View File

@@ -1,182 +0,0 @@
# Lighthouse REST API: `/lighthouse`
The `/lighthouse` endpoints provide lighthouse-specific information about the beacon node.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/lighthouse/syncing`](#lighthousesyncing) | Get the node's syncing status
[`/lighthouse/peers`](#lighthousepeers) | Get the peers info known by the beacon node
[`/lighthouse/connected_peers`](#lighthousepeers) | Get the connected_peers known by the beacon node
## `/lighthouse/syncing`
Requests the syncing state of a Lighthouse beacon node. Lighthouse as a
custom sync protocol, this request gets Lighthouse-specific sync information.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/lighthouse/syncing`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
If the node is undergoing a finalization sync:
```json
{
"SyncingFinalized": {
"start_slot": 10,
"head_slot": 20,
"head_root":"0x74020d0e3c3c02d2ea6279d5760f7d0dd376c4924beaaec4d5c0cefd1c0c4465"
}
}
```
If the node is undergoing a head chain sync:
```json
{
"SyncingHead": {
"start_slot":0,
"head_slot":1195
}
}
```
If the node is synced
```json
{
"Synced"
}
```
## `/lighthouse/peers`
Get all known peers info from the beacon node.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/lighthouse/peers`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
[
{
"peer_id" : "16Uiu2HAmTEinipUS3haxqucrn7d7SmCKx5XzAVbAZCiNW54ncynG",
"peer_info" : {
"_status" : "Healthy",
"client" : {
"agent_string" : "github.com/libp2p/go-libp2p",
"kind" : "Prysm",
"os_version" : "unknown",
"protocol_version" : "ipfs/0.1.0",
"version" : "unknown"
},
"connection_status" : {
"Disconnected" : {
"since" : 3
}
},
"listening_addresses" : [
"/ip4/10.3.58.241/tcp/9001",
"/ip4/35.172.14.146/tcp/9001",
"/ip4/35.172.14.146/tcp/9001"
],
"meta_data" : {
"attnets" : "0x0000000000000000",
"seq_number" : 0
},
"reputation" : 20,
"sync_status" : {
"Synced" : {
"status_head_slot" : 18146
}
}
}
},
{
"peer_id" : "16Uiu2HAm8XZfPv3YjktCjitSRtfS7UfHfEvpiUyHrdiX6uAD55xZ",
"peer_info" : {
"_status" : "Healthy",
"client" : {
"agent_string" : null,
"kind" : "Unknown",
"os_version" : "unknown",
"protocol_version" : "unknown",
"version" : "unknown"
},
"connection_status" : {
"Disconnected" : {
"since" : 5
}
},
"listening_addresses" : [],
"meta_data" : {
"attnets" : "0x0900000000000000",
"seq_number" : 0
},
"reputation" : 20,
"sync_status" : "Unknown"
}
},
]
```
## `/lighthouse/connected_peers`
Get all known peers info from the beacon node.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/lighthouse/connected_peers`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
[
{
"peer_id" : "16Uiu2HAm8XZfPv3YjktCjitSRtfS7UfHfEvpiUyHrdiX6uAD55xZ",
"peer_info" : {
"_status" : "Healthy",
"client" : {
"agent_string" : null,
"kind" : "Unknown",
"os_version" : "unknown",
"protocol_version" : "unknown",
"version" : "unknown"
},
"connection_status" : {
"Connected" : {
"in" : 5,
"out" : 2
}
},
"listening_addresses" : [],
"meta_data" : {
"attnets" : "0x0900000000000000",
"seq_number" : 0
},
"reputation" : 20,
"sync_status" : "Unknown"
}
},
]
```

148
book/src/http/network.md
View File

@@ -1,148 +0,0 @@
# 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/enr`](#networkenr) | Get the local node's `ENR` as base64 .
[`/network/peer_count`](#networkpeer_count) | Get the count of connected peers.
[`/network/peer_id`](#networkpeer_id) | Get a node's libp2p `PeerId`.
[`/network/peers`](#networkpeers) | List a node's connected peers (as `PeerIds`).
[`/network/listen_port`](#networklisten_port) | Get a node's libp2p listening port.
[`/network/listen_addresses`](#networklisten_addresses) | Get a list of libp2p multiaddr the node is listening on.
## `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"
```
## `/network/peer_count`
Requests the count of peers connected to the client.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/network/peer_count`
Method | GET
JSON Encoding | Number
Query Parameters | None
Typical Responses | 200
### Example Response
```json
5
```
## `/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/listen_port`
Requests the TCP port that the client's libp2p service is listening on.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/network/listen_port`
Method | GET
JSON Encoding | Number
Query Parameters | None
Typical Responses | 200
### Example Response
```json
9000
```
## `/network/listen_addresses`
Requests the list of multiaddr that the client's libp2p service is listening on.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/network/listen_addresses`
Method | GET
JSON Encoding | Array
Query Parameters | None
Typical Responses | 200
### Example Response
```json
[
"/ip4/127.0.0.1/tcp/9000",
"/ip4/192.168.31.115/tcp/9000",
"/ip4/172.24.0.1/tcp/9000",
"/ip4/172.21.0.1/tcp/9000",
"/ip4/172.17.0.1/tcp/9000",
"/ip4/172.18.0.1/tcp/9000",
"/ip4/172.19.0.1/tcp/9000",
"/ip4/172.42.0.1/tcp/9000",
"/ip6/::1/tcp/9000"
]
```

91
book/src/http/node.md
View File

@@ -1,91 +0,0 @@
# Lighthouse REST API: `/node`
The `/node` endpoints provide information about the lighthouse beacon node.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/node/version`](#nodeversion) | Get the node's version.
[`/node/syncing`](#nodesyncing) | Get the node's syncing status.
[`/node/health`](#nodehealth) | Get the node's health.
## `/node/version`
Requests the beacon node's version.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/node/version`
Method | GET
JSON Encoding | String
Query Parameters | None
Typical Responses | 200
### Example Response
```json
"Lighthouse-0.2.0-unstable"
```
## `/node/syncing`
Requests the syncing status of the beacon node.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/node/syncing`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
{
is_syncing: true,
sync_status: {
starting_slot: 0,
current_slot: 100,
highest_slot: 200,
}
}
```
## `/node/health`
Requests information about the health of the beacon node.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/node/health`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
{
"pid": 96160,
"pid_num_threads": 30,
"pid_mem_resident_set_size": 55476224,
"pid_mem_virtual_memory_size": 2081382400,
"sys_virt_mem_total": 16721076224,
"sys_virt_mem_available": 7423197184,
"sys_virt_mem_used": 8450183168,
"sys_virt_mem_free": 3496345600,
"sys_virt_mem_percent": 55.605743,
"sys_loadavg_1": 1.56,
"sys_loadavg_5": 2.61,
"sys_loadavg_15": 2.43
}
```

154
book/src/http/spec.md
View File

@@ -1,154 +0,0 @@
# Lighthouse REST API: `/spec`
The `/spec` endpoints provide information about Eth2.0 specifications that the node is running.
## Endpoints
HTTP Path | Description |
| --- | -- |
[`/spec`](#spec) | Get the full spec object that a node's running.
[`/spec/slots_per_epoch`](#specslots_per_epoch) | Get the number of slots per epoch.
[`/spec/eth2_config`](#specseth2_config) | Get the full Eth2 config object.
## `/spec`
Requests the full spec object that a node's running.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/spec`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
{
"genesis_slot": 0,
"base_rewards_per_epoch": 4,
"deposit_contract_tree_depth": 32,
"max_committees_per_slot": 64,
"target_committee_size": 128,
"min_per_epoch_churn_limit": 4,
"churn_limit_quotient": 65536,
"shuffle_round_count": 90,
"min_genesis_active_validator_count": 16384,
"min_genesis_time": 1578009600,
"min_deposit_amount": 1000000000,
"max_effective_balance": 32000000000,
"ejection_balance": 16000000000,
"effective_balance_increment": 1000000000,
"genesis_fork_version": "0x00000000",
"bls_withdrawal_prefix_byte": "0x00",
"genesis_delay": 172800,
"milliseconds_per_slot": 12000,
"min_attestation_inclusion_delay": 1,
"min_seed_lookahead": 1,
"max_seed_lookahead": 4,
"min_epochs_to_inactivity_penalty": 4,
"min_validator_withdrawability_delay": 256,
"shard_committee_period": 2048,
"base_reward_factor": 64,
"whistleblower_reward_quotient": 512,
"proposer_reward_quotient": 8,
"inactivity_penalty_quotient": 33554432,
"min_slashing_penalty_quotient": 32,
"domain_beacon_proposer": 0,
"domain_beacon_attester": 1,
"domain_randao": 2,
"domain_deposit": 3,
"domain_voluntary_exit": 4,
"safe_slots_to_update_justified": 8,
"eth1_follow_distance": 1024,
"seconds_per_eth1_block": 14,
"boot_nodes": [],
"network_id": 1
}
```
## `/spec/eth2_config`
Requests the full `Eth2Config` object.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/spec/eth2_config`
Method | GET
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Example Response
```json
{
"spec_constants": "mainnet",
"spec": {
"genesis_slot": 0,
"base_rewards_per_epoch": 4,
"deposit_contract_tree_depth": 32,
"max_committees_per_slot": 64,
"target_committee_size": 128,
"min_per_epoch_churn_limit": 4,
"churn_limit_quotient": 65536,
"shuffle_round_count": 90,
"min_genesis_active_validator_count": 16384,
"min_genesis_time": 1578009600,
"min_deposit_amount": 1000000000,
"max_effective_balance": 32000000000,
"ejection_balance": 16000000000,
"effective_balance_increment": 1000000000,
"genesis_fork_version": "0x00000000",
"bls_withdrawal_prefix_byte": "0x00",
"genesis_delay": 172800,
"milliseconds_per_slot": 12000,
"min_attestation_inclusion_delay": 1,
"min_seed_lookahead": 1,
"max_seed_lookahead": 4,
"min_epochs_to_inactivity_penalty": 4,
"min_validator_withdrawability_delay": 256,
"shard_committee_period": 2048,
"base_reward_factor": 64,
"whistleblower_reward_quotient": 512,
"proposer_reward_quotient": 8,
"inactivity_penalty_quotient": 33554432,
"min_slashing_penalty_quotient": 32,
"domain_beacon_proposer": 0,
"domain_beacon_attester": 1,
"domain_randao": 2,
"domain_deposit": 3,
"domain_voluntary_exit": 4,
"safe_slots_to_update_justified": 8,
"eth1_follow_distance": 1024,
"seconds_per_eth1_block": 14,
"boot_nodes": [],
"network_id": 1
}
}
```
## `/spec/slots_per_epoch`
Requests the `SLOTS_PER_EPOCH` parameter from the specs that the node is running.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/spec/slots_per_epoch`
Method | GET
JSON Encoding | Number
Query Parameters | None
Typical Responses | 200
### Example Response
```json
32
```

545
book/src/http/validator.md
View File

@@ -1,545 +0,0 @@
# 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 | HTTP Method | Description |
| - | - | ---- |
[`/validator/duties`](#validatorduties) | POST | Provides block and attestation production information for validators.
[`/validator/subscribe`](#validatorsubscribe) | POST | Subscribes a list of validators to the beacon node for a particular duty/slot.
[`/validator/duties/all`](#validatordutiesall) | GET |Provides block and attestation production information for all validators.
[`/validator/duties/active`](#validatordutiesactive) | GET | Provides block and attestation production information for all active validators.
[`/validator/block`](#validatorblock-get) | GET | Retrieves the current beacon block for the validator to publish.
[`/validator/block`](#validatorblock-post) | POST | Publishes a signed block to the network.
[`/validator/attestation`](#validatorattestation) | GET | Retrieves the current best attestation for a validator to publish.
[`/validator/aggregate_attestation`](#validatoraggregate_attestation) | GET | Gets an aggregate attestation for validators to sign and publish.
[`/validator/attestations`](#validatorattestations) | POST | Publishes a list of raw unaggregated attestations to their appropriate subnets.
[`/validator/aggregate_and_proofs`](#validatoraggregate_and_proofs) | POST | Publishes a list of Signed aggregate and proofs for validators who are aggregators.
## `/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": [],
"aggregator_modulo": 5,
},
{
"validator_pubkey": "0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42",
"validator_index": null,
"attestation_slot": null,
"attestation_committee_index": null,
"attestation_committee_position": null,
"block_proposal_slots": []
"aggregator_modulo": null,
}
]
```
## `/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.
## `/validator/subscribe`
Posts a list of `ValidatorSubscription` to subscribe validators to
particular slots to perform attestation duties.
This informs the beacon node to search for peers and subscribe to
required attestation subnets to perform the attestation duties required.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/subscribe`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200
### Request Body
Expects the following object in the POST request body:
```
[
{
validator_index: 10,
attestation_committee_index: 12,
slot: 3,
is_aggregator: true
}
]
```
The `is_aggregator` informs the beacon node if the validator is an aggregator
for this slot/committee.
### Returns
A null object on success and an error indicating any failures.
## `/validator/block` GET
Produces and returns an unsigned `BeaconBlock` object.
The block will be produced with the given `slot` and the parent block will be the
highest block in the canonical chain that has a slot less than `slot`. The
block will still be produced if some other block is also known to be at `slot`
(i.e., it may produce a block that would be slashable if signed).
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/block`
Method | GET
JSON Encoding | Object
Query Parameters | `slot`, `randao_reveal`
Typical Responses | 200
### Parameters
- `slot` (`Slot`): The slot number for which the block is to be produced.
- `randao_reveal` (`Signature`): 96 bytes `Signature` for the randomness.
### Returns
Returns a `BeaconBlock` object.
#### Response Body
```json
{
"slot": 33,
"parent_root": "0xf54de54bd33e33aee4706cffff4bd991bcbf522f2551ab007180479c63f4fe912",
"state_root": "0x615c887bad27bc05754d627d941e1730e1b4c77b2eb4378c195ac8a8203bbf26",
"body": {
"randao_reveal": "0x8d7b2a32b026e9c79aae6ec6b83eabae89d60cacd65ac41ed7d2f4be9dd8c89c1bf7cd3d700374e18d03d12f6a054c23006f64f0e4e8b7cf37d6ac9a4c7d815c858120c54673b7d3cb2bb1550a4d659eaf46e34515677c678b70d6f62dbf89f",
"eth1_data": {
"deposit_root": "0x66687aadf862bd776c8fc18b8e9f8e20089714856ee233b3902a591d0d5f2925",
"deposit_count": 8,
"block_hash": "0x2b32db6c2c0a6235fb1397e8225ea85e0f0e6e8c7b126d0016ccbde0e667151e"
},
"graffiti": "0x736967702f6c69676874686f7573652d302e312e312d7076572656c65617365",
"proposer_slashings": [],
"attester_slashings": [],
"attestations": [],
"deposits": [],
"voluntary_exits": []
}
}
```
## `/validator/block` POST
Accepts a `SignedBeaconBlock` for verification. If it is valid, it will be
imported into the local database and published on the network. Invalid blocks
will not be published to the network.
A block may be considered invalid because it is fundamentally incorrect, or its
parent has not yet been imported.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/block`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200/202
### Request Body
Expects a JSON encoded `SignedBeaconBlock` in the POST request body:
### Returns
Returns a null object if the block passed all block validation and is published to the network.
Else, returns a processing error description.
### Example
### Request Body
```json
{
"message": {
"slot": 33,
"parent_root": "0xf54de54bd33e33aee4706cffff4bd991bcbf522f2551ab007180479c63f4fe912",
"state_root": "0x615c887bad27bc05754d627d941e1730e1b4c77b2eb4378c195ac8a8203bbf26",
"body": {
"randao_reveal": "0x8d7b2a32b026e9c79aae6ec6b83eabae89d60cacd65ac41ed7d2f4be9dd8c89c1bf7cd3d700374e18d03d12f6a054c23006f64f0e4e8b7cf37d6ac9a4c7d815c858120c54673b7d3cb2bb1550a4d659eaf46e34515677c678b70d6f62dbf89f",
"eth1_data": {
"deposit_root": "0x66687aadf862bd776c8fc18b8e9f8e20089714856ee233b3902a591d0d5f2925",
"deposit_count": 8,
"block_hash": "0x2b32db6c2c0a6235fb1397e8225ea85e0f0e6e8c7b126d0016ccbde0e667151e"
},
"graffiti": "0x736967702f6c69676874686f7573652d302e312e312d7076572656c65617365",
"proposer_slashings": [
],
"attester_slashings": [
],
"attestations": [
],
"deposits": [
],
"voluntary_exits": [
]
}
},
"signature": "0x965ced900dbabd0a78b81a0abb5d03407be0d38762104316416347f2ea6f82652b5759396f402e85df8ee18ba2c60145037c73b1c335f4272f1751a1cd89862b7b4937c035e350d0108554bd4a8930437ec3311c801a65fe8e5ba022689b5c24"
}
```
## `/validator/attestation`
Produces and returns an unsigned `Attestation` from the current state.
The attestation will reference the `beacon_block_root` of the highest block in
the canonical chain with a slot equal to or less than the given `slot`.
An error will be returned if the given slot is more than
`SLOTS_PER_HISTORICAL_VECTOR` slots behind the current head block.
This endpoint is not protected against slashing. Signing the returned
attestation may result in a slashable offence.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/attestation`
Method | GET
JSON Encoding | Object
Query Parameters | `slot`, `committee_index`
Typical Responses | 200
### Parameters
- `slot` (`Slot`): The slot number for which the attestation is to be produced.
- `committee_index` (`CommitteeIndex`): The index of the committee that makes the attestation.
### Returns
Returns a `Attestation` object with a default signature. The `signature` field should be replaced by the valid signature.
#### Response Body
```json
{
"aggregation_bits": "0x01",
"data": {
"slot": 100,
"index": 0,
"beacon_block_root": "0xf22e4ec281136d119eabcd4d9d248aeacd042eb63d8d7642f73ad3e71f1c9283",
"source": {
"epoch": 2,
"root": "0x34c1244535c923f08e7f83170d41a076e4f1ec61013846b3a615a1d109d3c329"
},
"target": {
"epoch": 3,
"root": "0xaefd23b384994dc0c1a6b77836bdb2f24f209ebfe6c4819324d9685f4a43b4e1"
}
},
"signature": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
}
```
## `/validator/aggregate_attestation`
Requests an `AggregateAttestation` from the beacon node that has a
specific `attestation.data`. If no aggregate attestation is known this will
return a null object.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/aggregate_attestation`
Method | GET
JSON Encoding | Object
Query Parameters | `attestation_data`
Typical Responses | 200
### Returns
Returns a null object if the attestation data passed is not known to the beacon
node.
### Example
### Request Body
```json
{
"aggregation_bits": "0x03",
"data": {
"slot": 3,
"index": 0,
"beacon_block_root": "0x0b6a1f7a9baa38d00ef079ba861b7587662565ca2502fb9901741c1feb8bb3c9",
"source": {
"epoch": 0,
"root": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"target": {
"epoch": 0,
"root": "0xad2c360ab8c8523db278a7d7ced22f3810800f2fdc282defb6db216689d376bd"
}
},
"signature": "0xb76a1768c18615b5ade91a92e7d2ed0294f7e088e56e30fbe7e3aa6799c443b11bccadd578ca2cbd95d395ab689b9e4d03c88a56641791ab38dfa95dc1f4d24d1b19b9d36c96c20147ad03$649bd3c6c7e8a39cf2ffb99e07b4964d52854559f"
}
```
## `/validator/attestations`
Accepts a list of `Attestation` for verification. If they are valid, they will be imported
into the local database and published to the network. Invalid attestations will
not be published to the network.
An attestation may be considered invalid because it is fundamentally incorrect
or because the beacon node has not imported the relevant blocks required to
verify it.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/attestations`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200/202
### Request Body
Expects a JSON encoded list of signed `Attestation` objects in the POST request body. In
accordance with the naive aggregation scheme, the attestation _must_ have
exactly one of the `attestation.aggregation_bits` fields set.
### Returns
Returns a null object if the attestation passed all validation and is published to the network.
Else, returns a processing error description.
### Example
### Request Body
```json
{
"aggregation_bits": "0x03",
"data": {
"slot": 3,
"index": 0,
"beacon_block_root": "0x0b6a1f7a9baa38d00ef079ba861b7587662565ca2502fb9901741c1feb8bb3c9",
"source": {
"epoch": 0,
"root": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"target": {
"epoch": 0,
"root": "0xad2c360ab8c8523db278a7d7ced22f3810800f2fdc282defb6db216689d376bd"
}
},
"signature": "0xb76a1768c18615b5ade91a92e7d2ed0294f7e088e56e30fbe7e3aa6799c443b11bccadd578ca2cbd95d395ab689b9e4d03c88a56641791ab38dfa95dc1f4d24d1b19b9d36c96c20147ad03$649bd3c6c7e8a39cf2ffb99e07b4964d52854559f"
}
```
## `/validator/aggregate_and_proofs`
Accepts a list of `SignedAggregateAndProof` for publication. If they are valid
(the validator is an aggregator and the signatures can be verified) these
are published to the network on the global aggregate gossip topic.
### HTTP Specification
| Property | Specification |
| --- |--- |
Path | `/validator/aggregate_and_proofs`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200/202
### Request Body
Expects a JSON encoded list of `SignedAggregateAndProof` objects in the POST request body.
### Returns
Returns a null object if the attestation passed all validation and is published to the network.
Else, returns a processing error description.
### Example
### Request Body
```json
[
{
"message": {
"aggregator_index": 12,
"aggregate": {
"aggregation_bits": "0x03",
"data": {
"slot": 3,
"index": 0,
"beacon_block_root": "0x0b6a1f7a9baa38d00ef079ba861b7587662565ca2502fb9901741c1feb8bb3c9",
"source": {
"epoch": 0,
"root": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"target": {
"epoch": 0,
"root": "0xad2c360ab8c8523db278a7d7ced22f3810800f2fdc282defb6db216689d376bd"
}
},
"signature": "0xb76a1768c18615b5ade91a92e7d2ed0294f7e088e56e30fbe7e3aa6799c443b11bccadd578ca2cbd95d395ab689b9e4d03c88a56641791ab38dfa95dc1f4d24d1b19b9d36c96c20147ad03649bd3c6c7e8a39cf2ffb99e07b4964d52854559f"
},
"selection_proof": "0xb76a1768c18615b5ade91a92e7d2ed0294f7e088e56e30fbe7e3aa6799c443b11bccadd578ca2cbd95d395ab689b9e4d03c88a56641791ab38dfa95dc1f4d24d1b19b9d36c96c20147ad03649bd3c6c7e8a39cf2ffb99e07b4964d52854559f"
}
signature: "0xb76a1768c18615b5ade91a92e7d2ed0294f7e088e56e30fbe7e3aa6799c443b11bccadd578ca2cbd95d395ab689b9e4d03c88a56641791ab38dfa95dc1f4d24d1b19b9d36c96c20147ad03649bd3c6c7e8a39cf2ffb99e07b4964d52854559f"
}
]
```
_Note: The data in this request is for demonstrating types and does not
contain real data_

135
book/src/http/consensus.md → book/src/validator-inclusion.md
View File

@@ -1,16 +1,21 @@
# Lighthouse REST API: `/consensus`
# Validator Inclusion APIs
The `/consensus` endpoints provide information on results of the proof-of-stake
voting process used for finality/justification under Casper FFG.
The `/lighthouse/validator_inclusion` API endpoints provide information on
results of the proof-of-stake voting process used for finality/justification
under Casper FFG.
These endpoints are not stable or included in the Eth2 standard API. As such,
they are subject to change or removal without a change in major release
version.
## 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.
[`/lighthouse/validator_inclusion/{epoch}/global`](#global) | A global vote count for a given epoch.
[`/lighthouse/validator_inclusion/{epoch}/{validator_id}`](#individual) | A per-validator breakdown of votes in a given epoch.
## `/consensus/global_votes`
## Global
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
@@ -75,40 +80,27 @@ voting upon the previous epoch included in a block.
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
### HTTP Example
| 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
```bash
curl -X GET "http://localhost:5052/lighthouse/validator_inclusion/0/global" -H "accept: application/json" | jq
```
```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
"data": {
"current_epoch_active_gwei": 642688000000000,
"previous_epoch_active_gwei": 642688000000000,
"current_epoch_attesting_gwei": 366208000000000,
"current_epoch_target_attesting_gwei": 366208000000000,
"previous_epoch_attesting_gwei": 1000000000,
"previous_epoch_target_attesting_gwei": 1000000000,
"previous_epoch_head_attesting_gwei": 1000000000
}
}
```
## `/consensus/individual_votes`
## Individual
Returns a per-validator summary of how that validator performed during the
current epoch.
@@ -117,73 +109,26 @@ The [Global Votes](#consensusglobal_votes) endpoint is the summation of all of t
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:
### HTTP Example
```bash
curl -X GET "http://localhost:5052/lighthouse/validator_inclusion/0/42" -H "accept: application/json" | jq
```
{
epoch: Epoch,
pubkeys: [PublicKey]
}
```
### Returns
A report on the validators voting participation.
### Example
#### Request Body
```json
{
"epoch": 1203,
"pubkeys": [
"0x98f87bc7c8fa10408425bbeeeb3dc387e3e0b4bd92f57775b60b39156a16f9ec80b273a64269332d97bdb7d93ae05a16",
"0x42f87bc7c8fa10408425bbeeeb3dc3874242b4bd92f57775b60b39142426f9ec80b273a64269332d97bdb7d93ae05a42"
]
"data": {
"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": 32000000000,
"is_current_epoch_attester": false,
"is_current_epoch_target_attester": false,
"is_previous_epoch_attester": false,
"is_previous_epoch_target_attester": false,
"is_previous_epoch_head_attester": false
}
}
```
_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
}
]
```

111
book/src/websockets.md
View File

@@ -1,111 +0,0 @@
# Websocket API
**Note: the WebSocket server _only_ emits events. It does not accept any
requests. Use the [HTTP API](./http.md) for requests.**
By default, a Lighthouse `beacon_node` exposes a websocket server on `localhost:5053`.
The following CLI flags control the websocket server:
- `--no-ws`: disable the websocket server.
- `--ws-port`: specify the listen port of the server.
- `--ws-address`: specify the listen address of the server.
All clients connected to the websocket server will receive the same stream of events, all triggered
by the `BeaconChain`. Each event is a JSON object with the following schema:
```json
{
"event": "string",
"data": "object"
}
```
## Events
The following events may be emitted:
### Beacon Head Changed
Occurs whenever the canonical head of the beacon chain changes.
```json
{
"event": "beacon_head_changed",
"data": {
"reorg": "boolean",
"current_head_beacon_block_root": "string",
"previous_head_beacon_block_root": "string"
}
}
```
### Beacon Finalization
Occurs whenever the finalized checkpoint of the canonical head changes.
```json
{
"event": "beacon_finalization",
"data": {
"epoch": "number",
"root": "string"
}
}
```
### Beacon Block Imported
Occurs whenever the beacon node imports a valid block.
```json
{
"event": "beacon_block_imported",
"data": {
"block": "object"
}
}
```
### Beacon Block Rejected
Occurs whenever the beacon node rejects a block because it is invalid or an
error occurred during validation.
```json
{
"event": "beacon_block_rejected",
"data": {
"reason": "string",
"block": "object"
}
}
```
### Beacon Attestation Imported
Occurs whenever the beacon node imports a valid attestation.
```json
{
"event": "beacon_attestation_imported",
"data": {
"attestation": "object"
}
}
```
### Beacon Attestation Rejected
Occurs whenever the beacon node rejects an attestation because it is invalid or
an error occurred during validation.
```json
{
"event": "beacon_attestation_rejected",
"data": {
"reason": "string",
"attestation": "object"
}
}
```