From 0b2c7acdb32a0daf81cf3f54e8ab35679f7083a7 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 13 May 2019 16:25:22 +1000 Subject: [PATCH] Fixed up markdown. - Removed TOC - Removed all the old spec stuff - Uploaded spec to SwaggerHub and provided a link to it. - Added a 'license' section to the API description. --- .../validator/0_beacon-node-validator-api.md | 216 +----------------- specs/validator/beacon_node_oapi.yaml | 5 +- 2 files changed, 7 insertions(+), 214 deletions(-) diff --git a/specs/validator/0_beacon-node-validator-api.md b/specs/validator/0_beacon-node-validator-api.md index 342e7f934..cf763f778 100644 --- a/specs/validator/0_beacon-node-validator-api.md +++ b/specs/validator/0_beacon-node-validator-api.md @@ -2,12 +2,6 @@ __NOTICE__: This document is a work-in-progress for researchers and implementers. This is an accompanying document to [Ethereum 2.0 Phase 0 -- Honest Validator](0_beacon-chain-validator.md) that describes an API exposed by the beacon node, which enables the validator client to participate in the Ethereum 2.0 protocol. -## Table of Contents - - - - - ## Outline This document outlines a minimal application programming interface (API) which is exposed by a `BeaconNode` for use by a `ValidatorClient` which aims to facilitate [_phase 0_](../../README.md#phase-0) of Ethereum 2.0. @@ -28,211 +22,7 @@ This specification is derived from a proposal and discussion on Issues [#1011](h ## Specification -### Entities -The following are the two entities that participate in this protocol: - - **`BeaconNode`**: - A beacon node instance, run with a `--rpc` flag to enable the RPC interface. Runs stand-alone. +The API specification has been written in [OpenAPI 3.0](https://swagger.io/docs/specification/about/) and is provided in the [beacon_node_oapi.yaml](beacon_node_oapi.yaml) file alongside this document. - - **`ValidatorClient`**: -A validator client instance, which must connect to at least one instance of `BeaconNode`. - - -### Endpoints -This section summarises API endpoints which are published by an instance of `BeaconNode`, for the exclusive use of `ValidatorClient` implementations. - -This proposal is a minimum set of messages necessary to enable effective communication, without any extra features. Anything extra is beyond the scope of this document. - -#### Summary Table -| Name | Type | Parameters | Returns | -| -------- | --- | ----- | ----- | -| [`get_client_version`](#get_client_version) | GET | N/A | `client_version` | -| [`get_genesis_time`](#get_genesis_time) | GET | N/A | `genesis_time` | -| [`get_syncing_status`](#get_syncing_status) | GET | N/A | `syncing_status` | -| [`get_duties`](#get_duties) | GET | `validator_pubkeys` | `syncing_status`, `current_version`, [`ValidatorDuty`]| -| [`produce_block`](#produce_block) | GET | `slot`, `randao_reveal` | `beacon_block` | -| [`publish_block`](#publish_block) | POST | `beacon_block` | N/A | -| [`produce_attestation`](#produce_attestation) | GET | `slot`, `shard` | `indexed_attestation` | -| [`publish_attestation`](#publish_attestation) | POST | `indexed_attestation` | N/A | Publishes the IndexedAttestation after having been signed by the ValidatorClient | - -#### Status Codes -For each of these endpoints the underlying transport protocol should provide status codes. Assuming this will be based on HTTP, one of the following standard status codes will always be included as part of a response: - -| Code | Meaning | -| --- | --- | -| `200` | The API call succeeded. | -| `40X` | The request was malformed. | -| `500` | The `BeaconNode` cannot complete the request due to an internal error. | -| `503` | The `BeaconNode` is currently syncing, try again later. _A call can be made to `get_syncing_status` to in order to find out how much has been synchronised._ | - -#### `get_client_version` -Requests that the `BeaconNode` identify information about its implementation in a format similar to a [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) field. - - - **Parameters**: N/A - - **Returns**: - - | Name | Type | Description | - | --- | --- | --- | - | `client_version` | bytes32 | An ASCII-encoded hex string which uniquely defines the implementation of the `BeaconNode` and its current software version. | - - **Note**: _Unlike most other endpoints, `get_client_version` does not return an error `503` while the `BeaconNode` is syncing, but instead returns status code `200`._ - - -#### `get_genesis_time` - Requests the `genesis_time` parameter from the `BeaconNode`, which should be consistent across all `BeaconNodes` that follow the same beacon chain. - - - **Parameters**: N/A - - **Returns**: - - | Name | Type | Description | - | --- | --- | --- | - | `genesis_time` | uint64 | The [`genesis_time`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#on-genesis), which is a fairly static configuration option for the `BeaconNode`. | - - **Note**: _Unlike most other endpoints, `get_genesis_time` does not return an error `503` while the `BeaconNode` is syncing, but instead returns status code `200`._ - - -#### `get_syncing_status` - Requests the `BeaconNode` to describe if it's currently syncing or not, and if it is, what block it is up to. This is modelled after the Eth1.0 JSON-RPC [`eth_syncing`](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_syncing) call. - - **Parameters**: N/A - - **Returns**: - - | Name | Type | Description | - | --- | --- | --- | - | `syncing` | `false` OR `SyncingStatus` | Either `false` if the node is not syncing, or a [`SyncingStatus`](#SyncingStatus) object if it is. | - - **Note**: _Unlike most other endpoints, `get_syncing_status` does not return an error `503` while the `BeaconNode` is syncing, but instead returns status code `200` with the `SyncingStatus` object._ - - -#### `get_duties` - Requests the BeaconNode to provide a set of “duties”, which are actions that should be performed by ValidatorClients. This API call should be polled at every slot, to ensure that any chain reorganisations are catered for, and to ensure that the currently connected `BeaconNode` is properly synchronised. - - - **Parameters**: - - | Name | Type | Description | - | --- | --- | --- | - | `validator_pubkeys` | [bytes48] | A list of unique validator public keys, where each item is a `0x` encoded hex string. | - - - **Returns**: - - | Name | Type | Description | - | --- | --- | --- | - | `current_version` | bytes4 | The `current_version`, as described by the current [`Fork`](#Fork). | - | `validator_duties` | [`ValidatorDuty`] | A list where each item is a custom [`ValidatorDuty`](#ValidatorDuty) object. | - - - #### `produce_block` - Requests a `BeaconNode` to produce a valid block, which can then be signed by a ValidatorClient. - - - **Parameters**: - - | Name | Type | Description | - | --- | --- | --- | - | `slot` | uint64 | The slot for which the block should be proposed. | - | `randao_reveal` | bytes | The ValidatorClient's randao reveal value. | - - - **Returns**: - - | Name | Type | Description | - | --- | --- | --- | - | `beacon_block` | `BeaconBlock` | A proposed [`BeaconBlock`](#BeaconBlock) object, but with the `signature` field left blank. - - - #### `publish_block` - Instructs the `BeaconNode` to publish a newly signed beacon block to the beacon network, to be included in the beacon chain. - - **Parameters**: - - | Name | Type | Description | - | --- | --- | --- | - | `beacon_block` | `BeaconBlock` | The [`BeaconBlock`](#BeaconBlock) object, as sent from the `BeaconNode` originally, but now with the `signature` field completed. - - - **Returns**: N/A - - - #### `produce_attestation` - Requests that the `BeaconNode` produce an `IndexedAttestation`, with a blank `signature` field, which the `ValidatorClient` will then sign. - - - **Parameters**: - - | Name | Type | Description | - | --- | --- | --- | - | `slot` | uint64 | The slot for which the attestation should be proposed. | - | `shard` | uint64 | The shard number for which the attestation is to be proposed. | - - - **Returns**: - - | Name | Type | Description | - | --- | --- | --- | - | `indexed_attestation` | `IndexedAttestation` | An [`IndexedAttestation`](#IndexedAttestation) structure with the `signature` field left blank. | - - #### `publish_attestation` - Instructs the `BeaconNode` to publish a newly signed `IndexedAttestation` object, to be incorporated into the beacon chain. - - - **Parameters**: - - | Name | Type | Description | - | --- | --- | --- | - | `indexed_attestation` | `IndexedAttestation` | An [`IndexedAttestation`](#IndexedAttestation) structure, as originally provided by the `BeaconNode`, but now with the `signature` field completed. | - - **Returns**: N/A - - - - ----- - -### Data Structures -Two new data objects are proposed for the sake of implementation, and several other data objects from the Eth2.0 specs are referenced. - -The `bytes` data types are encoded hex strings, with `0x` preceeding them. `uint64` are decimal encoded integers, and `None` may be `null`, which is distinct from `0`. - -#### `ValidatorDuty` -```asm -{ - - # The validator's public key, uniquely identifying them - 'validator_pubkey': 'bytes48', - # The index of the validator in the committee - 'committee_index': 'uint64', - # The slot at which the validator must attest. - 'attestation_slot': 'uint64', - # The shard in which the validator must attest - 'attestation_shard': 'uint64', - # The slot in which a validator must propose a block. This field can also be None. - 'block_production_slot': 'uint64' or None -} -``` - -#### `SyncingStatus` -As described by the [Eth1.0 JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_syncing).: -```asm -{ - # The block at which syncing started (will only be reset, after the sync reached his head) - 'startingBlock': 'uint64', - # The current block - 'currentBlock': 'uint64', - # The estimated highest block, or current target block number - 'highestBlock': 'uint64' -} -``` - -#### `Fork` -As described by [Fork](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#Fork) in the Eth2.0 specs. - -#### `BeaconBlock` -As described by [BeaconBlock](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#BeaconBlock) in the Eth2.0 specs. - -#### `IndexedAttestation` -As described by [IndexedAttestation](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#IndexedAttestation) in the Eth2.0 specs. - - - - -## Optional Extras - -#### Endpoint: `get_fork` - Requests the `BeaconNode` to provide which fork version it is currently on. - - **Parameters**: N/A - - **Returns**: - - | Name | Type | Description | - | --- | --- | --- | - | `fork` | [`Fork`](#Fork) | Provides the current version information for the fork which the `BeaconNode` is currently following. | - | `chain_id` | uint64 | Sometimes called the network id, this number discerns the active chain for the `BeaconNode`. Analagous to Eth1.0 JSON-RPC [`net_version`](https://github.com/ethereum/wiki/wiki/JSON-RPC#net_version). | - +For convenience, this specification has been uploaded to [SwaggerHub](https://swagger.io/tools/swaggerhub/) at the following URL: +[https://app.swaggerhub.com/apis/spble/beacon_node_api_for_validator/0.1](https://app.swaggerhub.com/apis/spble/beacon_node_api_for_validator/0.1) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 8d7267953..0c2937f3d 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -1,8 +1,11 @@ openapi: "3.0.2" info: title: "Minimal Beacon Node API for Validator" - description: "A minimal API specification for the beacon node, which enabling a validator to connect and perform its obligations on the Ethereum 2.0 phase 0 beacon chain." + description: "A minimal API specification for the beacon node, which enables a validator to connect and perform its obligations on the Ethereum 2.0 phase 0 beacon chain." version: "0.1" + license: + name: "Apache 2.0" + url: "https://www.apache.org/licenses/LICENSE-2.0.html" tags: - name: Necessary for validator description: The minimal set of endpoints to enable a working validator implementation.