cerc-io/lighthouse
16
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Update HTTP API docs (#1010)

Browse Source
This commit is contained in:
Age Manning 2020-04-16 20:31:43 +10:00 committed by GitHub
parent 6a21c9ba6f
commit 6edb4f655c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 2046 additions and 1781 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
beacon_node/rest_api/src/lib.rs
View File

@ -10,6 +10,7 @@ pub mod config;
mod consensus;
mod error;
mod helpers;
mod lighthouse;
mod metrics;
mod network;
mod node;

13
beacon_node/rest_api/src/lighthouse.rs Normal file
View File

@ -0,0 +1,13 @@
//! This contains a collection of lighthouse specific HTTP endpoints.
use crate::response_builder::ResponseBuilder;
use crate::ApiResult;
use eth2_libp2p::NetworkGlobals;
use hyper::{Body, Request};
use std::sync::Arc;
use types::EthSpec;
/// The syncing state of the beacon node.
pub fn syncing<T: EthSpec>(req: Request<Body>, network: Arc<NetworkGlobals<T>>) -> ApiResult {
ResponseBuilder::new(&req)?.body_no_ssz(&network.sync_state())
}

12
beacon_node/rest_api/src/router.rs
View File

@ -1,6 +1,6 @@
use crate::{
advanced, beacon, consensus, error::ApiError, helpers, metrics, network, node, spec, validator,
BoxFut, NetworkChannel,
advanced, beacon, consensus, error::ApiError, helpers, lighthouse, metrics, network, node,
spec, validator, BoxFut, NetworkChannel,
};
use beacon_chain::{BeaconChain, BeaconChainTypes};
use eth2_config::Eth2Config;
@ -57,9 +57,6 @@ pub fn route<T: BeaconChainTypes>(
current_slot,
))
}
(&Method::GET, "/node/lighthouse_syncing") => {
into_boxfut(node::lighthouse_syncing::<T::EthSpec>(req, network_globals))
}
// Methods for Network
(&Method::GET, "/network/enr") => {
@ -214,6 +211,11 @@ pub fn route<T: BeaconChainTypes>(
freezer_db_path,
)),
// Lighthouse specific
(&Method::GET, "/lighthouse/syncing") => {
into_boxfut(lighthouse::syncing::<T::EthSpec>(req, network_globals))
}
_ => Box::new(futures::future::err(ApiError::NotFound(
"Request path and/or method not found.".to_owned(),
))),

2
book/README.md
View File

@ -3,7 +3,7 @@
Contains an [mdBook](https://github.com/rust-lang-nursery/mdBook) that serves
as the primary source of Lighthouse user documentation.
The book is hosted at [lighthouse-book.sigmaprime.io](http://lighthouse-book.sigmaprime.io).i
The book is hosted at [lighthouse-book.sigmaprime.io](http://lighthouse-book.sigmaprime.io)
## Usage

4
book/book.toml
View File

@ -1,5 +1,5 @@
[book]
authors = ["Paul Hauner"]
authors = ["Paul Hauner", "Age Manning"]
language = "en"
multilingual = false
src = "src"
@ -7,3 +7,5 @@ title = "Lighthouse Book"
[output.html]
additional-css =["src/css/custom.css"]
default-theme = "coal"

13
book/src/SUMMARY.md
View File

@ -9,12 +9,13 @@
* [Local Testnets](./local-testnets.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)
* [/spec](./http_spec.md)
* [/advanced](./http_advanced.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)
* [Advanced Usage](./advanced.md)
* [Database Configuration](./advanced_database.md)

15
book/src/http.md
View File

@ -14,13 +14,14 @@ detail:
Endpoint | Description |
| --- | -- |
[`/node`](./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.
[`/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

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

@ -0,0 +1,115 @@
# 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 Normal file
View File

@ -0,0 +1,784 @@
# 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.11.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.11.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.11.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_

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
}
]
```

54
book/src/http/lighthouse.md Normal file
View File

@ -0,0 +1,54 @@
# 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/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"
}
```

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

@ -0,0 +1,148 @@
# 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"
]
```

47
book/src/http_node.md → book/src/http/node.md
View File

@ -8,8 +8,6 @@ HTTP Path | Description |
| --- | -- |
[`/node/version`](#nodeversion) | Get the node's version.
[`/node/syncing`](#nodesyncing) | Get the node's syncing status.
[`/node/syncing`](#nodelighthouse_syncing) | Get the node's syncing status
(Lighthouse specific).
## `/node/version`
@ -57,48 +55,3 @@ Typical Responses | 200
}
}
```
## `/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 | `/node/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"
}
```

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

@ -0,0 +1,154 @@
# 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",
"min_genesis_delay": 86400,
"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,
"persistent_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",
"min_genesis_delay": 86400,
"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,
"persistent_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 Normal file
View File

@ -0,0 +1,545 @@
# 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) | GET | 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_

116
book/src/http_advanced.md
View File

@ -1,115 +1 @@
# 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._
# /advanced

708
book/src/http_beacon.md
View File

@ -1,707 +1 @@
# 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/attester_slashing`](#beaconattester_slashing) | Insert an attester slashing
[`/beacon/block`](#beaconblock) | Get a `BeaconBlock` by slot or root.
[`/beacon/block_root`](#beaconblock_root) | Resolve a slot to a block root.
[`/beacon/committees`](#beaconcommittees) | Get the shuffling for an epoch.
[`/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/proposer_slashing`](#beaconproposer_slashing) | Insert a proposer slashing
[`/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/genesis_time`](#beacongenesis_time) | Get the genesis time from the beacon state.
[`/beacon/fork`](#beaconfork) | Get the fork of the head of the chain.
[`/beacon/validators`](#beaconvalidators) | Query for one or more validators.
[`/beacon/validators/active`](#beaconvalidatorsactive) | Get all active validators.
[`/beacon/validators/all`](#beaconvalidatorsall) | Get all validators.
## `/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/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/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/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_
## `/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.11.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.11.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/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/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.11.1/specs/phase0/beacon-chain.md#fork) of the current head.
### Example Response
```json
{
"previous_version": "0x00000000",
"current_version": "0x00000000",
"epoch": 0
}
```
## `/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/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/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

190
book/src/http_consensus.md
View File

@ -1,189 +1 @@
# 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
}
]
```
# /consensus

149
book/src/http_network.md
View File

@ -1,148 +1 @@
# 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/peer_count`](#networkpeer_count) | Get the count of connected peers.
[`/network/peers`](#networkpeers) | List a node's libp2p peers (as `PeerIds`).
[`/network/enr`](#networkenr) | Get a node's discovery `ENR` address.
[`/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/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/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/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"
```
## `/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"
]
```
# /network

155
book/src/http_spec.md
View File

@ -1,154 +1 @@
# 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",
"min_genesis_delay": 86400,
"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,
"persistent_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",
"min_genesis_delay": 86400,
"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,
"persistent_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
```
# /spec

402
book/src/http_validator.md
View File

@ -1,401 +1 @@
# 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) | GET | Provides block and attestation production information for validators.
[`/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`](#validatorblockget) | GET | Retrieves the current beacon
block for the validator to publish.
[`/validator/block`](#validatorblockpost) | POST | Publishes a signed block to the
network.
[`/validator/attestation`](#validatorattestation) | GET | Retrieves the current best attestation for a validator to publish.
[`/validator/attestations`](#validatorattestations) | POST | Publishes a list
of raw unaggregated attestations to their appropriate subnets
[`/validator/aggregate_attestation`](#validatoraggregateattestation) | GET | Gets an aggregate attestation for validators to sign and publish.
[`/validator/aggregate_attestations`](#validatoraggregateattestation) | POST |
Publishes a list of aggregated attestations for validators who are aggregators
[`/validator/subscribe`](#validatorsubscribe) | POST | Subscribes a list of
validators to the beacon node for a particular duty/slot.
## `/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/block`
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/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/block`
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`
Accepts an `Attestation` for verification. If it is valid, it 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/attestation`
Method | POST
JSON Encoding | Object
Query Parameters | None
Typical Responses | 200/202
### Request Body
Expects a JSON encoded signed `Attestation` object 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

11
book/src/local-testnets.md
View File

@ -139,3 +139,14 @@ all subsequent nodes will update automatically.
This node should now connect to the original node, sync and follow it's head.
## 4. Updating genesis time
To re-use a testnet directory one may simply update the genesis time and repeat
the process.
To update the genesis time of a `genesis.ssz` file, use the following command:
```bash
$ lcli change-genesis-time ~/.lighthouse/testnet/genesis.ssz $(date +%s)
```