status-im
/
eth2.0-specs
mirror of https://github.com/status-im/eth2.0-specs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Luke Anderson 2019-05-13 16:25:22 +10:00
parent 2035aea0b8
commit 0b2c7acdb3
No known key found for this signature in database
GPG Key ID: 44408169EC61E228
2 changed files with 7 additions and 214 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
specs/validator/0_beacon-node-validator-api.md
View File

@ -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. __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
<!-- TOC -->
<!-- /TOC -->
## Outline ## 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. 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 ## Specification
### Entities 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.
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.
- **`ValidatorClient`**: For convenience, this specification has been uploaded to [SwaggerHub](https://swagger.io/tools/swaggerhub/) at the following URL:
A validator client instance, which must connect to at least one instance of `BeaconNode`. [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)
### 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). |

5
specs/validator/beacon_node_oapi.yaml
View File

@ -1,8 +1,11 @@
openapi: "3.0.2" openapi: "3.0.2"
info: info:
title: "Minimal Beacon Node API for Validator" 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" version: "0.1"
license:
name: "Apache 2.0"
url: "https://www.apache.org/licenses/LICENSE-2.0.html"
tags: tags:
- name: Necessary for validator - name: Necessary for validator
description: The minimal set of endpoints to enable a working validator implementation. description: The minimal set of endpoints to enable a working validator implementation.