diff --git a/beacon_node/rest_api/src/lib.rs b/beacon_node/rest_api/src/lib.rs index 4dc858c1dbf..2702f38c90f 100644 --- a/beacon_node/rest_api/src/lib.rs +++ b/beacon_node/rest_api/src/lib.rs @@ -10,6 +10,7 @@ pub mod config; mod consensus; mod error; mod helpers; +mod lighthouse; mod metrics; mod network; mod node; diff --git a/beacon_node/rest_api/src/lighthouse.rs b/beacon_node/rest_api/src/lighthouse.rs new file mode 100644 index 00000000000..48a64e3fbad --- /dev/null +++ b/beacon_node/rest_api/src/lighthouse.rs @@ -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(req: Request, network: Arc>) -> ApiResult { + ResponseBuilder::new(&req)?.body_no_ssz(&network.sync_state()) +} diff --git a/beacon_node/rest_api/src/router.rs b/beacon_node/rest_api/src/router.rs index 3c5c7dc7b00..ee391ae0db4 100644 --- a/beacon_node/rest_api/src/router.rs +++ b/beacon_node/rest_api/src/router.rs @@ -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( current_slot, )) } - (&Method::GET, "/node/lighthouse_syncing") => { - into_boxfut(node::lighthouse_syncing::(req, network_globals)) - } // Methods for Network (&Method::GET, "/network/enr") => { @@ -214,6 +211,11 @@ pub fn route( freezer_db_path, )), + // Lighthouse specific + (&Method::GET, "/lighthouse/syncing") => { + into_boxfut(lighthouse::syncing::(req, network_globals)) + } + _ => Box::new(futures::future::err(ApiError::NotFound( "Request path and/or method not found.".to_owned(), ))), diff --git a/book/README.md b/book/README.md index 45448c4ef04..973e4f838a4 100644 --- a/book/README.md +++ b/book/README.md @@ -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 diff --git a/book/book.toml b/book/book.toml index df47f4d7b3e..7b143710a5f 100644 --- a/book/book.toml +++ b/book/book.toml @@ -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" + diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 6b072e6be05..ee589d9ed05 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -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) diff --git a/book/src/http.md b/book/src/http.md index fe164fd05ff..e07440e8da8 100644 --- a/book/src/http.md +++ b/book/src/http.md @@ -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 diff --git a/book/src/http/advanced.md b/book/src/http/advanced.md new file mode 100644 index 00000000000..822b6ffffd6 --- /dev/null +++ b/book/src/http/advanced.md @@ -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._ diff --git a/book/src/http/beacon.md b/book/src/http/beacon.md new file mode 100644 index 00000000000..eba59e3e831 --- /dev/null +++ b/book/src/http/beacon.md @@ -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_ + + + + + diff --git a/book/src/http/consensus.md b/book/src/http/consensus.md new file mode 100644 index 00000000000..c71b78ce3e9 --- /dev/null +++ b/book/src/http/consensus.md @@ -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 + } +] +``` diff --git a/book/src/http/lighthouse.md b/book/src/http/lighthouse.md new file mode 100644 index 00000000000..cc6ec2a1197 --- /dev/null +++ b/book/src/http/lighthouse.md @@ -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" +} +``` diff --git a/book/src/http/network.md b/book/src/http/network.md new file mode 100644 index 00000000000..2ac0c83ba49 --- /dev/null +++ b/book/src/http/network.md @@ -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" +] +``` diff --git a/book/src/http_node.md b/book/src/http/node.md similarity index 52% rename from book/src/http_node.md rename to book/src/http/node.md index 4e4768bb8ea..3c32c6c1ccd 100644 --- a/book/src/http_node.md +++ b/book/src/http/node.md @@ -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" -} -``` diff --git a/book/src/http/spec.md b/book/src/http/spec.md new file mode 100644 index 00000000000..9fb8c0c988f --- /dev/null +++ b/book/src/http/spec.md @@ -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 +``` \ No newline at end of file diff --git a/book/src/http/validator.md b/book/src/http/validator.md new file mode 100644 index 00000000000..c3bf3b9cdaf --- /dev/null +++ b/book/src/http/validator.md @@ -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_ diff --git a/book/src/http_advanced.md b/book/src/http_advanced.md index 822b6ffffd6..5dad7cab676 100644 --- a/book/src/http_advanced.md +++ b/book/src/http_advanced.md @@ -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 diff --git a/book/src/http_beacon.md b/book/src/http_beacon.md index f5fd6e765ff..dd0313133da 100644 --- a/book/src/http_beacon.md +++ b/book/src/http_beacon.md @@ -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 diff --git a/book/src/http_consensus.md b/book/src/http_consensus.md index c71b78ce3e9..2d8b80aa125 100644 --- a/book/src/http_consensus.md +++ b/book/src/http_consensus.md @@ -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 diff --git a/book/src/http_network.md b/book/src/http_network.md index 26e007d52e0..e224ebc3a5a 100644 --- a/book/src/http_network.md +++ b/book/src/http_network.md @@ -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" -] -``` \ No newline at end of file +# /network diff --git a/book/src/http_spec.md b/book/src/http_spec.md index 9fb8c0c988f..dc94c2005b1 100644 --- a/book/src/http_spec.md +++ b/book/src/http_spec.md @@ -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 -``` \ No newline at end of file +# /spec diff --git a/book/src/http_validator.md b/book/src/http_validator.md index 525a57e59f8..29c0bac2e72 100644 --- a/book/src/http_validator.md +++ b/book/src/http_validator.md @@ -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 diff --git a/book/src/local-testnets.md b/book/src/local-testnets.md index 3846bd603bc..387df1dd45a 100644 --- a/book/src/local-testnets.md +++ b/book/src/local-testnets.md @@ -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) +```