From 0d06f6bcc1bb16dc77d85067e480ce3623b94934 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Wed, 8 May 2019 15:04:27 +1000 Subject: [PATCH 01/19] Added the first draft of the BN-VC API RFC, as it was listed on the issue #1011. --- .../0_beacon-node-validator-client-api.md | 235 ++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 specs/validator/0_beacon-node-validator-client-api.md diff --git a/specs/validator/0_beacon-node-validator-client-api.md b/specs/validator/0_beacon-node-validator-client-api.md new file mode 100644 index 000000000..fff4107ca --- /dev/null +++ b/specs/validator/0_beacon-node-validator-client-api.md @@ -0,0 +1,235 @@ +# ETH2.0 Beacon Node & Validator Client RPC Proposal + +## Outline + +This issue proposes a minimal communications specification between a beacon node and validator client, targeting _phase 0_ of the Eth2.0 specification. The protocol is designed to be a simple local communications interface, permitting two separate binaries to communicate. + +This specification is intended to describe communication abstractly, without choosing any particular protocol. The protocol used (e.g. gRPC/JSON-RPC) is discussed in a separate issue: #1012. + +This issue follows on from a discussion during the [Client Architecture](https://notes.ethereum.org/iuPB2YjKQMGua0nwCZJVAQ) session at the [Sydney Implementers meeting](https://notes.ethereum.org/7w7diW1-St2_Yu-YHjg6NA). This also follow from the [Client Architecture Roundtable](https://hackmd.io/s/rJl05Lk6X) in Prague. +There is an editable version of this document, here: https://hackmd.io/r7D61hs4RWKm8nz_O2iinQ + +### Background +The beacon node maintains the state of the beacon chain by communicating with other beacon nodes in the Ethereum Serenity network. Conceptually, it does not maintain keypairs that participate with the beacon chain. + +The validator client is conceptually a separate entity which utilises private keys to perform validator related tasks on the beacon chain, which we call validator "duties". This includes the production of beacon blocks and signing of attestations. + +Since it is recommended to separate these concerns in the client implementations, it is necessary for us to clearly define the communication between them. + +The goal of this specification is to promote interoperability between beacon nodes and validator clients derived from different projects. For example, the validator client from Lighthouse, could communicate with a running instance of the beacon node from Prysm. + +This proposal has been adapted from the [Lighthouse gRPC protocol specification](https://github.com/sigp/lighthouse/blob/master/protos/src/services.proto). + +There is also another [WIP proposal for a Minimum Validator Interface](https://notes.ethereum.org/Ia2kvjy0RX2J-GxrWfoCAQ), which describes additional functions possibly necessary for phase 1 and beyond. + +## 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. + + - **`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). | + From 4d2e752bb90437afb73ce58253cb68122fac16e6 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Wed, 8 May 2019 23:51:53 +1000 Subject: [PATCH 02/19] Started updating the markdown description of the BNVC REST API, removing stuff specific to the issue and conforming to standard text layout. --- ...-api.md => 0_beacon-node-validator-api.md} | 25 +++++++++++-------- 1 file changed, 14 insertions(+), 11 deletions(-) rename specs/validator/{0_beacon-node-validator-client-api.md => 0_beacon-node-validator-api.md} (87%) diff --git a/specs/validator/0_beacon-node-validator-client-api.md b/specs/validator/0_beacon-node-validator-api.md similarity index 87% rename from specs/validator/0_beacon-node-validator-client-api.md rename to specs/validator/0_beacon-node-validator-api.md index fff4107ca..342e7f934 100644 --- a/specs/validator/0_beacon-node-validator-client-api.md +++ b/specs/validator/0_beacon-node-validator-api.md @@ -1,26 +1,30 @@ -# ETH2.0 Beacon Node & Validator Client RPC Proposal +# Ethereum 2.0 Phase 0 -- Beacon Node API for Validator + +__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 issue proposes a minimal communications specification between a beacon node and validator client, targeting _phase 0_ of the Eth2.0 specification. The protocol is designed to be a simple local communications interface, permitting two separate binaries to communicate. +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 specification is intended to describe communication abstractly, without choosing any particular protocol. The protocol used (e.g. gRPC/JSON-RPC) is discussed in a separate issue: #1012. - -This issue follows on from a discussion during the [Client Architecture](https://notes.ethereum.org/iuPB2YjKQMGua0nwCZJVAQ) session at the [Sydney Implementers meeting](https://notes.ethereum.org/7w7diW1-St2_Yu-YHjg6NA). This also follow from the [Client Architecture Roundtable](https://hackmd.io/s/rJl05Lk6X) in Prague. -There is an editable version of this document, here: https://hackmd.io/r7D61hs4RWKm8nz_O2iinQ +The API is a REST interface, accessed via HTTP, designed for use as a local communications protocol between binaries. ### Background The beacon node maintains the state of the beacon chain by communicating with other beacon nodes in the Ethereum Serenity network. Conceptually, it does not maintain keypairs that participate with the beacon chain. -The validator client is conceptually a separate entity which utilises private keys to perform validator related tasks on the beacon chain, which we call validator "duties". This includes the production of beacon blocks and signing of attestations. +The validator client is a conceptually separate entity which utilises private keys to perform validator related tasks on the beacon chain, which we call validator "duties". These duties includes the production of beacon blocks and signing of attestations. -Since it is recommended to separate these concerns in the client implementations, it is necessary for us to clearly define the communication between them. +Since it is recommended to separate these concerns in the client implementations, we must clearly define the communication between them. The goal of this specification is to promote interoperability between beacon nodes and validator clients derived from different projects. For example, the validator client from Lighthouse, could communicate with a running instance of the beacon node from Prysm. -This proposal has been adapted from the [Lighthouse gRPC protocol specification](https://github.com/sigp/lighthouse/blob/master/protos/src/services.proto). +This specification is derived from a proposal and discussion on Issues [#1011](https://github.com/ethereum/eth2.0-specs/issues/1011) and [#1012](https://github.com/ethereum/eth2.0-specs/issues/1012) -There is also another [WIP proposal for a Minimum Validator Interface](https://notes.ethereum.org/Ia2kvjy0RX2J-GxrWfoCAQ), which describes additional functions possibly necessary for phase 1 and beyond. ## Specification @@ -33,7 +37,6 @@ The following are the two entities that participate in this protocol: 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. From 39fd625d350a456f4020d07e13cd56dbe3514d9b Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Thu, 9 May 2019 23:49:59 +1000 Subject: [PATCH 03/19] Started porting the API proposal into OpenAPI 3 format. --- specs/validator/beacon_node_oapi.yaml | 152 ++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 specs/validator/beacon_node_oapi.yaml diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml new file mode 100644 index 000000000..3eac70a35 --- /dev/null +++ b/specs/validator/beacon_node_oapi.yaml @@ -0,0 +1,152 @@ +openapi: "3.0.2" +info: + title: "Beacon Node API for Validator" + description: "A beacon node API for enabling a validator to perform its obligations on the Ethereum 2.0 phase 0 beacon chain." + version: "0.1" +paths: + /node/version: + get: + summary: "Get version string of the running beacon node." + description: "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." + responses: + 200: + description: Success + content: + application/json: + schema: + title: Duties + type: object + + /node/genesis_time: + get: + summary: "Get the genesis_time parameter from beacon node configuration." + description: "Requests the genesis_time parameter from the BeaconNode, which should be consistent across all BeaconNodes that follow the same beacon chain." + responses: + 200: + description: Success + content: + application/json: + schema: + title: genesis_time + type: integer + + /node/syncing: + get: + summary: "Poll to see if the the beacon node is syncing." + description: "Requests the beacon node 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 call.." + responses: + 200: + description: Success + content: + application/json: + schema: + title: genesis_time + type: integer + + + + /validator/duties: + get: + summary: "Get validator duties for the requested validators." + description: "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: validator_pubkeys + in: query + required: true + schema: + type: array + items: + type: string + format: byte + responses: + 200: + description: Success response + content: + application/json: + schema: + title: Duties + type: object + 503: + description: Beacon node syncing + + + /validator/block: + get: + summary: "Produce a new block, without signature." + description: "Requests a BeaconNode to produce a valid block, which can then be signed by a ValidatorClient." + parameters: + - name: slot + in: query + required: true + schema: + type: integer + - name: randao_reveal + in: query + required: true + schema: + type: string + format: byte + responses: + 200: + description: Success response + content: + application/json: + schema: + type: object + title: BeaconBlock + post: + summary: "Publish a signed block" + description: "Instructs the BeaconNode to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." + parameters: + - name: beacon_block + in: query + required: true + schema: + type: object + title: BeaconBlock + responses: + 200: + description: Success response + 503: + description: Beacon node syncing + + + /validator/attestation: + get: + summary: "Produce an attestation, without signature." + description: "Requests that the BeaconNode produce an IndexedAttestation, with a blank signature field, which the ValidatorClient will then sign." + parameters: + - name: slot + in: query + required: true + schema: + type: integer + - name: shard + in: query + required: true + schema: + type: integer + responses: + 200: + description: Success response + content: + application/json: + schema: + type: object + title: IndexedAttestation + post: + summary: "Published a signed attestation." + description: "Instructs the BeaconNode to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain." + parameters: + - name: attestation + in: query + required: true + description: "An IndexedAttestation structure, as originally provided by the BeaconNode, but now with the signature field completed." + schema: + type: object + title: IndexedAttestation + responses: + 200: + description: Success response + 503: + description: Beacon node syncing From b918cc3de35d6474f022c95e39402bac900dfec1 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Fri, 10 May 2019 14:03:59 +1000 Subject: [PATCH 04/19] Fleshed out a whole lot more of the OpenAPI specification for the API. --- specs/validator/beacon_node_oapi.yaml | 240 +++++++++++++++++++++++--- 1 file changed, 213 insertions(+), 27 deletions(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 3eac70a35..0a583bdd6 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -10,12 +10,13 @@ paths: description: "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." responses: 200: - description: Success + description: Request successful content: application/json: schema: - title: Duties - type: object + $ref: '#/components/schemas/client_version' + 500: + $ref: '#/components/responses/InternalError' /node/genesis_time: get: @@ -23,12 +24,14 @@ paths: description: "Requests the genesis_time parameter from the BeaconNode, which should be consistent across all BeaconNodes that follow the same beacon chain." responses: 200: - description: Success + description: Request successful content: application/json: schema: - title: genesis_time - type: integer + $ref: '#/components/schemas/genesis_time' + 500: + $ref: '#/components/responses/InternalError' + /node/syncing: get: @@ -36,13 +39,19 @@ paths: description: "Requests the beacon node 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 call.." responses: 200: - description: Success + description: Request successful content: application/json: schema: - title: genesis_time - type: integer - + type: object + properties: + is_syncing: + type: boolean + description: "A boolean of whether the node is currently syncing or not." + sync_status: + $ref: '#/components/schemas/SyncingStatus' + 500: + $ref: '#/components/responses/InternalError' /validator/duties: @@ -53,21 +62,28 @@ paths: - name: validator_pubkeys in: query required: true + description: "An array of hex-encoded BLS public keys" schema: type: array items: - type: string - format: byte + $ref: '#/components/schemas/pubkey' + minItems: 1 responses: 200: description: Success response content: application/json: schema: - title: Duties - type: object + type: array + items: + $ref: '#/components/schemas/ValidatorDuty' + 400: + $ref: '#/components/responses/InvalidRequest' + 500: + $ref: '#/components/responses/InternalError' 503: - description: Beacon node syncing + $ref: '#/components/responses/CurrentlySyncing' + /validator/block: @@ -78,11 +94,14 @@ paths: - name: slot in: query required: true + description: "The slot for which the block should be proposed." schema: type: integer + format: uint64 - name: randao_reveal in: query required: true + description: "The ValidatorClient's randao reveal value." schema: type: string format: byte @@ -92,8 +111,13 @@ paths: content: application/json: schema: - type: object - title: BeaconBlock + $ref: '#/components/schemas/BeaconBlock' + 400: + $ref: '#/components/responses/InvalidRequest' + 500: + $ref: '#/components/responses/InternalError' + 503: + $ref: '#/components/responses/CurrentlySyncing' post: summary: "Publish a signed block" description: "Instructs the BeaconNode to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." @@ -101,14 +125,18 @@ paths: - name: beacon_block in: query required: true + description: "The BeaconBlock object, as sent from the BeaconNode originally, but now with the signature field completed." schema: - type: object - title: BeaconBlock + $ref: '#/components/schemas/BeaconBlock' responses: 200: - description: Success response + $ref: '#/components/responses/Success' + 400: + $ref: '#/components/responses/InvalidRequest' + 500: + $ref: '#/components/responses/InternalError' 503: - description: Beacon node syncing + $ref: '#/components/responses/CurrentlySyncing' /validator/attestation: @@ -119,11 +147,13 @@ paths: - name: slot in: query required: true + description: "The slot for which the attestation should be proposed." schema: type: integer - name: shard in: query required: true + description: "The shard number for which the attestation is to be proposed." schema: type: integer responses: @@ -132,8 +162,14 @@ paths: content: application/json: schema: - type: object - title: IndexedAttestation + $ref: '#/components/schemas/IndexedAttestation' + 400: + $ref: '#/components/responses/InvalidRequest' + 500: + $ref: '#/components/responses/InternalError' + 503: + $ref: '#/components/responses/CurrentlySyncing' + post: summary: "Published a signed attestation." description: "Instructs the BeaconNode to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain." @@ -143,10 +179,160 @@ paths: required: true description: "An IndexedAttestation structure, as originally provided by the BeaconNode, but now with the signature field completed." schema: - type: object - title: IndexedAttestation + $ref: '#/components/schemas/IndexedAttestation' responses: 200: - description: Success response + $ref: '#/components/responses/Success' + 400: + $ref: '#/components/responses/InvalidRequest' + 500: + $ref: '#/components/responses/InternalError' 503: - description: Beacon node syncing + $ref: '#/components/responses/CurrentlySyncing' + +components: + schemas: + ValidatorDuty: + type: object + properties: + validator_pubkey: + $ref: '#/components/schemas/pubkey' + committee_index: + type: integer + format: uint64 + description: "The index of the validator in the committee." + attestation_slot: + type: integer + format: uint64 + description: "The slot at which the validator must attest." + attestation_shard: + type: integer + format: uint64 + description: "The shard in which the validator must attest." + block_production_slot: + type: integer + format: uint64 + nullable: true + description: "The slot in which a validator must propose a block, or `null` if block production is not required." + SyncingStatus: + type: object + nullable: true + properties: + starting_block: + type: integer + format: uint64 + description: "The block at which syncing started (will only be reset after the sync reached its head)" + current_block: + type: integer + format: uint64 + description: "The current highest block sync'd by the beacon node." + highest_block: + type: integer + format: uint64 + description: "The estimated highest block, or current target block number." + BeaconBlock: + type: object + description: "The [BeaconBlock](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) from the Eth2.0 spec." + Fork: + type: object + description: "The [Fork](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#Fork) from the Eth2.0 spec." + properties: + previous_version: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{8}$" + description: "Previous fork version" + current_version: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{8}$" + description: "Current fork version" + epoch: + type: integer + format: uint64 + description: "Fork epoch number" + IndexedAttestation: + type: object + description: "The [IndexedAttestation](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#indexedattestation) from the Eth2.0 spec." + properties: + custody_bit_0_indicies: + type: array + description: "Validator indicies for 0 bits." + items: + type: integer + format: uint64 + custody_bit_1_indicies: + type: array + description: "Validator indicies for 1 bits." + items: + type: integer + format: uint64 + data: + $ref: '#/components/schemas/AttestationData' + + AttestationData: + type: object + description: "The [AttestationData](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestationdata) from the Eth2.0 spec." + properties: + beacon_block_root: + $ref: '#/components/schemas/merkle_root' + source_epoch: + type: integer + format: uint64 + description: "Source epoch from FFG vote" + source_root: + $ref: '#/components/schemas/merkle_root' + target_epoch: + type: integer + format: uint64 + description: "Target epoch from FFG vote" + target_root: + $ref: '#/components/schemas/merkle_root' + crosslink: + $ref: '#/components/schemas/CrossLink' + CrossLink: + type: object + description: "The [Crosslink](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) from the Eth2.0 spec." + properties: + shard: + type: integer + format: uint64 + description: "The shard number" + epoch: + type: integer + format: uint64 + description: "The epoch number" + parent_root: + $ref: '#/components/schemas/merkle_root' + data_root: + $ref: '#/components/schemas/merkle_root' + + pubkey: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{96}$" + description: "The validator's BLS public key, uniquely identifying them." + client_version: + type: string + description: "A string which uniquely identifies the client implementation and its version; similar to [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3)." + example: "Lighthouse / v0.1.5 (Linux x86_64)" + genesis_time: + type: integer + format: uint64 + description: "The genesis_time configured for the beacon node, which is the time the Eth1.0 validator deposit smart contract has enough ETH staked (i.e. Eth2.0 begins)." + merkle_root: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "A 32 byte merkle root, used in all kinds of scenarios." + + + responses: + Success: + description: Request successful + InvalidRequest: + description: Invalid request syntax + InternalError: + description: Beacon node internal error + CurrentlySyncing: + description: Beacon node is currently syncing, try again later From 48ed25b2bdb1807b4170fbde4414ffd9baa08609 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 13 May 2019 15:07:15 +1000 Subject: [PATCH 05/19] Fleshed out a lot more of the API, nearly ready. - Added all the fields from BeaconBlock(Body) - Tagged all paths as 'Minimum for validator' - Removed BeaconNode and ValidatorClient conventions - Moved the basic non-object schema components to the top - Broke out common beacon block properties into the BeaconBlockCommon object - Fixed links to Eth2.0 spec --- specs/validator/beacon_node_oapi.yaml | 371 ++++++++++++++++++++++---- 1 file changed, 315 insertions(+), 56 deletions(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 0a583bdd6..a2e4559f2 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -1,27 +1,31 @@ openapi: "3.0.2" info: - title: "Beacon Node API for Validator" - description: "A beacon node API for enabling a validator to perform its obligations on the Ethereum 2.0 phase 0 beacon chain." + 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." version: "0.1" paths: /node/version: get: + tags: + - Minimum for validator summary: "Get version string of the running beacon node." - description: "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." + description: "Requests that the beacon node 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." responses: 200: description: Request successful content: application/json: schema: - $ref: '#/components/schemas/client_version' + $ref: '#/components/schemas/version' 500: - $ref: '#/components/responses/InternalError' - + $ref: '#/components/responses/InternalError' + /node/genesis_time: get: + tags: + - Minimum for validator summary: "Get the genesis_time parameter from beacon node configuration." - description: "Requests the genesis_time parameter from the BeaconNode, which should be consistent across all BeaconNodes that follow the same beacon chain." + description: "Requests the genesis_time parameter from the beacon node, which should be consistent across all beacon nodes that follow the same beacon chain." responses: 200: description: Request successful @@ -31,10 +35,12 @@ paths: $ref: '#/components/schemas/genesis_time' 500: $ref: '#/components/responses/InternalError' - + /node/syncing: get: + tags: + - Minimum for validator summary: "Poll to see if the the beacon node is syncing." description: "Requests the beacon node 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 call.." responses: @@ -52,13 +58,15 @@ paths: $ref: '#/components/schemas/SyncingStatus' 500: $ref: '#/components/responses/InternalError' - - + + /validator/duties: get: + tags: + - Minimum for validator summary: "Get validator duties for the requested validators." - description: "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: + description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators. 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 beacon node is properly synchronised." + parameters: - name: validator_pubkeys in: query required: true @@ -83,14 +91,16 @@ paths: $ref: '#/components/responses/InternalError' 503: $ref: '#/components/responses/CurrentlySyncing' - - - + + + /validator/block: get: + tags: + - Minimum for validator summary: "Produce a new block, without signature." - description: "Requests a BeaconNode to produce a valid block, which can then be signed by a ValidatorClient." - parameters: + description: "Requests a beacon node to produce a valid block, which can then be signed by a validator." + parameters: - name: slot in: query required: true @@ -101,7 +111,7 @@ paths: - name: randao_reveal in: query required: true - description: "The ValidatorClient's randao reveal value." + description: "The validator's randao reveal value." schema: type: string format: byte @@ -119,13 +129,15 @@ paths: 503: $ref: '#/components/responses/CurrentlySyncing' post: + tags: + - Minimum for validator summary: "Publish a signed block" - description: "Instructs the BeaconNode to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." - parameters: + description: "Instructs the beacon node to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." + parameters: - name: beacon_block in: query required: true - description: "The BeaconBlock object, as sent from the BeaconNode originally, but now with the signature field completed." + description: "The `BeaconBlock` object, as sent from the beacon node originally, but now with the signature field completed." schema: $ref: '#/components/schemas/BeaconBlock' responses: @@ -137,13 +149,15 @@ paths: $ref: '#/components/responses/InternalError' 503: $ref: '#/components/responses/CurrentlySyncing' - - + + /validator/attestation: get: + tags: + - Minimum for validator summary: "Produce an attestation, without signature." - description: "Requests that the BeaconNode produce an IndexedAttestation, with a blank signature field, which the ValidatorClient will then sign." - parameters: + description: "Requests that the beacon node produce an IndexedAttestation, with a blank signature field, which the validator will then sign." + parameters: - name: slot in: query required: true @@ -169,15 +183,17 @@ paths: $ref: '#/components/responses/InternalError' 503: $ref: '#/components/responses/CurrentlySyncing' - + post: + tags: + - Minimum for validator summary: "Published a signed attestation." - description: "Instructs the BeaconNode to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain." + description: "Instructs the beacon node to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain." parameters: - name: attestation in: query required: true - description: "An IndexedAttestation structure, as originally provided by the BeaconNode, but now with the signature field completed." + description: "An `IndexedAttestation` structure, as originally provided by the beacon node, but now with the signature field completed." schema: $ref: '#/components/schemas/IndexedAttestation' responses: @@ -192,6 +208,30 @@ paths: components: schemas: + pubkey: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{96}$" + description: "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._" + example: "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc" + + version: + type: string + description: "A string which uniquely identifies the client implementation and its version; similar to [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3)." + example: "Lighthouse / v0.1.5 (Linux x86_64)" + + genesis_time: + type: integer + format: uint64 + description: "The genesis_time configured for the beacon node, which is the time the Eth1.0 validator deposit smart contract has enough ETH staked (i.e. Eth2.0 begins)." + example: 1557716289 + + merkle_root: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "A 32 byte merkle root, used in all kinds of scenarios." + ValidatorDuty: type: object properties: @@ -214,6 +254,7 @@ components: format: uint64 nullable: true description: "The slot in which a validator must propose a block, or `null` if block production is not required." + SyncingStatus: type: object nullable: true @@ -230,12 +271,248 @@ components: type: integer format: uint64 description: "The estimated highest block, or current target block number." + + BeaconBlock: + allOf: + - $ref: '#/components/schemas/BeaconBlockCommon' + - type: object + description: "The [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec." + properties: + body: + $ref: '#/components/schemas/BeaconBlockBody' + + + BeaconBlockHeader: + allOf: + - $ref: '#/components/schemas/BeaconBlockCommon' + - type: object + properties: + body_root: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{64}$" + description: "The tree hash merkle root of the `BeaconBlockBody` for the `BeaconBlock`" + + + + + BeaconBlockBody: type: object - description: "The [BeaconBlock](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) from the Eth2.0 spec." + description: "The [`BeaconBlockBody`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblockbody) object from the Eth2.0 spec." + properties: + randao_reveal: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{192}$" + description: "The RanDAO reveal value provided by the validator." + eth1_data: + title: Eth1Data + type: object + description: "The [`Eth1Data`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#eth1data) object from the Eth2.0 spec." + properties: + deposit_root: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "Root of the deposit tree." + deposit_count: + type: integer + format: uint64 + description: "Total number of deposits." + block_hash: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "Ethereum 1.x block hash" + graffiti: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + proposer_slashings: + type: array + items: + title: ProposerSlashings + type: object + description: "The [`ProposerSlashing`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#proposerslashing) object from the Eth2.0 spec." + properties: + proposer_index: + type: integer + format: uint64 + description: "The index of the proposer to be slashed." + header_1: + $ref: '#/components/schemas/BeaconBlockHeader' + header_2: + $ref: '#/components/schemas/BeaconBlockHeader' + attester_slashings: + type: array + items: + title: AttesterSlashings + type: object + description: "The [`AttesterSlashing`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attesterslashing) object from the Eth2.0 spec." + properties: + attestation_1: + $ref: '#/components/schemas/IndexedAttestation' + attestation_2: + $ref: '#/components/schemas/IndexedAttestation' + attestations: + type: array + items: + title: Attestation + type: object + description: "The [`Attestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestation) object from the Eth2.0 spec." + properties: + aggregation_bitfield: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]+$" + description: "Attester aggregation bitfield." + custody_bitfield: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]+$" + description: "Custody bitfield" + signature: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{192}$" + description: "BLS aggregate signature." + data: + $ref: '#/components/schemas/AttestationData' + deposits: + type: array + items: + title: Deposit + type: object + description: "The [`Deposit`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#deposit) object from the Eth2.0 spec." + properties: + proof: + type: array + description: "Branch in the deposit tree." + items: + oneOf: + - type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + - type: integer + format: uint64 + enum: [32] + example: 32 + description: "The DEPOSIT_CONTRACT_TREE_DEPTH value." + minItems: 2 + maxItems: 2 + index: + type: integer + format: uint64 + description: "Index in the deposit tree." + data: + title: DepositData + type: object + description: "The [`DepositData`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#depositdata) object from the Eth2.0 spec." + properties: + pubkey: + $ref: '#/components/schemas/pubkey' + withdrawal_credentials: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "The withdrawal credentials." + amount: + type: integer + format: uint64 + description: "Amount in Gwei." + signature: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{192}$" + description: "Container self-signature." + + voluntary_exits: + type: array + items: + title: VoluntaryExit + type: object + description: "The [`VoluntaryExit`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#voluntaryexit) object from the Eth2.0 spec." + properties: + epoch: + type: integer + format: uint64 + description: "Minimum epoch for processing exit." + validator_index: + type: integer + format: uint64 + description: "Index of the exiting validator." + signature: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{192}$" + description: "Validator signature." + transfers: + type: array + items: + title: Transfer + type: object + description: "The [`Transfer`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#transfer) object from the Eth2.0 spec." + properties: + sender: + type: integer + format: uint64 + description: "Sender index." + recipient: + type: integer + format: uint64 + description: "Recipient index." + amount: + type: integer + format: uint64 + description: "Amount in Gwei" + fee: + type: integer + format: uint64 + description: "Fee in Gwei for block producer" + slot: + type: integer + format: uint64 + description: "Inclusion slot" + pubkey: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{96}$" + description: "Sender withdrawal public key" + signature: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{192}$" + description: "Sender signature" + + BeaconBlockCommon: + # An object to collect the common fields between the BeaconBlockHeader and the BeaconBlock objects + type: object + properties: + slot: + type: integer + format: uint64 + description: "The slot to which this block corresponds." + parent_root: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{64}$" + description: "The signing merkle root of the parent `BeaconBlock`" + state_root: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{64}$" + description: "The tree hash merkle root of the `BeaconState` for the `BeaconBlock`" + signature: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{192}$" + example: "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + description: "The BLS signature of the `BeaconBlock` made by the validator of the block" + Fork: type: object - description: "The [Fork](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#Fork) from the Eth2.0 spec." + description: "The [`Fork`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#Fork) object from the Eth2.0 spec." properties: previous_version: type: string @@ -251,9 +528,10 @@ components: type: integer format: uint64 description: "Fork epoch number" + IndexedAttestation: type: object - description: "The [IndexedAttestation](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#indexedattestation) from the Eth2.0 spec." + description: "The [`IndexedAttestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#indexedattestation) object from the Eth2.0 spec." properties: custody_bit_0_indicies: type: array @@ -269,10 +547,10 @@ components: format: uint64 data: $ref: '#/components/schemas/AttestationData' - - AttestationData: + + AttestationData: type: object - description: "The [AttestationData](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestationdata) from the Eth2.0 spec." + description: "The [`AttestationData`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestationdata) object from the Eth2.0 spec." properties: beacon_block_root: $ref: '#/components/schemas/merkle_root' @@ -290,9 +568,10 @@ components: $ref: '#/components/schemas/merkle_root' crosslink: $ref: '#/components/schemas/CrossLink' + CrossLink: type: object - description: "The [Crosslink](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) from the Eth2.0 spec." + description: "The [`Crosslink`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec." properties: shard: type: integer @@ -306,27 +585,7 @@ components: $ref: '#/components/schemas/merkle_root' data_root: $ref: '#/components/schemas/merkle_root' - - pubkey: - type: string - format: byte - pattern: "^0x[a-fA-F0-9]{96}$" - description: "The validator's BLS public key, uniquely identifying them." - client_version: - type: string - description: "A string which uniquely identifies the client implementation and its version; similar to [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3)." - example: "Lighthouse / v0.1.5 (Linux x86_64)" - genesis_time: - type: integer - format: uint64 - description: "The genesis_time configured for the beacon node, which is the time the Eth1.0 validator deposit smart contract has enough ETH staked (i.e. Eth2.0 begins)." - merkle_root: - type: string - format: byte - pattern: "^0x[a-fA-F0-9]{64}$" - description: "A 32 byte merkle root, used in all kinds of scenarios." - - + responses: Success: description: Request successful From d10baf1dcea19b29fc9e755dc322bb149a7474d1 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 13 May 2019 15:18:56 +1000 Subject: [PATCH 06/19] Added optional path, , renamed tags, and fixed up whitespace issues. --- specs/validator/beacon_node_oapi.yaml | 51 ++++++++++++++++----------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index a2e4559f2..01eef87a4 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -7,7 +7,7 @@ paths: /node/version: get: tags: - - Minimum for validator + - Necessary for validator summary: "Get version string of the running beacon node." description: "Requests that the beacon node 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." responses: @@ -23,7 +23,7 @@ paths: /node/genesis_time: get: tags: - - Minimum for validator + - Necessary for validator summary: "Get the genesis_time parameter from beacon node configuration." description: "Requests the genesis_time parameter from the beacon node, which should be consistent across all beacon nodes that follow the same beacon chain." responses: @@ -36,11 +36,10 @@ paths: 500: $ref: '#/components/responses/InternalError' - /node/syncing: get: tags: - - Minimum for validator + - Necessary for validator summary: "Poll to see if the the beacon node is syncing." description: "Requests the beacon node 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 call.." responses: @@ -59,11 +58,10 @@ paths: 500: $ref: '#/components/responses/InternalError' - /validator/duties: get: tags: - - Minimum for validator + - Necessary for validator summary: "Get validator duties for the requested validators." description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators. 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 beacon node is properly synchronised." parameters: @@ -92,12 +90,10 @@ paths: 503: $ref: '#/components/responses/CurrentlySyncing' - - /validator/block: get: tags: - - Minimum for validator + - Necessary for validator summary: "Produce a new block, without signature." description: "Requests a beacon node to produce a valid block, which can then be signed by a validator." parameters: @@ -130,7 +126,7 @@ paths: $ref: '#/components/responses/CurrentlySyncing' post: tags: - - Minimum for validator + - Necessary for validator summary: "Publish a signed block" description: "Instructs the beacon node to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." parameters: @@ -150,11 +146,10 @@ paths: 503: $ref: '#/components/responses/CurrentlySyncing' - /validator/attestation: get: tags: - - Minimum for validator + - Necessary for validator summary: "Produce an attestation, without signature." description: "Requests that the beacon node produce an IndexedAttestation, with a blank signature field, which the validator will then sign." parameters: @@ -183,10 +178,9 @@ paths: $ref: '#/components/responses/InternalError' 503: $ref: '#/components/responses/CurrentlySyncing' - post: tags: - - Minimum for validator + - Necessary for validator summary: "Published a signed attestation." description: "Instructs the beacon node to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain." parameters: @@ -206,6 +200,29 @@ paths: 503: $ref: '#/components/responses/CurrentlySyncing' + /node/fork: + get: + tags: + - Optional + summary: "Get fork information from running beacon node." + description: "Requests the beacon node to provide which fork version it is currently on." + responses: + 200: + description: Request successful + content: + application/json: + schema: + type: object + properties: + fork: + $ref: '#/components/schemas/Fork' + chain_id: + type: integer + format: uint64 + description: "Sometimes called the network id, this number discerns the active chain for the BeaconNode. Analagous to Eth1.0 JSON-RPC net_version." + 500: + $ref: '#/components/responses/InternalError' + components: schemas: pubkey: @@ -272,7 +289,6 @@ components: format: uint64 description: "The estimated highest block, or current target block number." - BeaconBlock: allOf: - $ref: '#/components/schemas/BeaconBlockCommon' @@ -282,7 +298,6 @@ components: body: $ref: '#/components/schemas/BeaconBlockBody' - BeaconBlockHeader: allOf: - $ref: '#/components/schemas/BeaconBlockCommon' @@ -294,9 +309,6 @@ components: pattern: "^0x[a-fA-F0-9]{64}$" description: "The tree hash merkle root of the `BeaconBlockBody` for the `BeaconBlock`" - - - BeaconBlockBody: type: object description: "The [`BeaconBlockBody`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblockbody) object from the Eth2.0 spec." @@ -426,7 +438,6 @@ components: format: byte pattern: "^0x[a-fA-F0-9]{192}$" description: "Container self-signature." - voluntary_exits: type: array items: From 2035aea0b8e5123536985bf76b176cb33232a6a9 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 13 May 2019 15:52:34 +1000 Subject: [PATCH 07/19] Formatting clean up. - Moved /node/fork up with other node endpoints - Added descriptions and ordering to tags - Removed common merkle_root schema, to be more specific in descriptions. - Moved BeaconBlockCommon next to appropriate schemas. - Lots of small grammar improvements, full stops at end of descriptions. --- specs/validator/beacon_node_oapi.yaml | 206 +++++++++++++------------- 1 file changed, 104 insertions(+), 102 deletions(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 01eef87a4..8d7267953 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -3,6 +3,11 @@ 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." version: "0.1" +tags: + - name: Necessary for validator + description: The minimal set of endpoints to enable a working validator implementation. + - name: Optional + description: Extra endpoints which are nice-to-haves. paths: /node/version: get: @@ -19,7 +24,6 @@ paths: $ref: '#/components/schemas/version' 500: $ref: '#/components/responses/InternalError' - /node/genesis_time: get: tags: @@ -57,6 +61,28 @@ paths: $ref: '#/components/schemas/SyncingStatus' 500: $ref: '#/components/responses/InternalError' + /node/fork: + get: + tags: + - Optional + summary: "Get fork information from running beacon node." + description: "Requests the beacon node to provide which fork version it is currently on." + responses: + 200: + description: Request successful + content: + application/json: + schema: + type: object + properties: + fork: + $ref: '#/components/schemas/Fork' + chain_id: + type: integer + format: uint64 + description: "Sometimes called the network id, this number discerns the active chain for the BeaconNode. Analagous to Eth1.0 JSON-RPC net_version." + 500: + $ref: '#/components/responses/InternalError' /validator/duties: get: @@ -127,7 +153,7 @@ paths: post: tags: - Necessary for validator - summary: "Publish a signed block" + summary: "Publish a signed block." description: "Instructs the beacon node to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." parameters: - name: beacon_block @@ -200,29 +226,6 @@ paths: 503: $ref: '#/components/responses/CurrentlySyncing' - /node/fork: - get: - tags: - - Optional - summary: "Get fork information from running beacon node." - description: "Requests the beacon node to provide which fork version it is currently on." - responses: - 200: - description: Request successful - content: - application/json: - schema: - type: object - properties: - fork: - $ref: '#/components/schemas/Fork' - chain_id: - type: integer - format: uint64 - description: "Sometimes called the network id, this number discerns the active chain for the BeaconNode. Analagous to Eth1.0 JSON-RPC net_version." - 500: - $ref: '#/components/responses/InternalError' - components: schemas: pubkey: @@ -231,24 +234,15 @@ components: pattern: "^0x[a-fA-F0-9]{96}$" description: "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._" example: "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc" - version: type: string description: "A string which uniquely identifies the client implementation and its version; similar to [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3)." example: "Lighthouse / v0.1.5 (Linux x86_64)" - genesis_time: type: integer format: uint64 description: "The genesis_time configured for the beacon node, which is the time the Eth1.0 validator deposit smart contract has enough ETH staked (i.e. Eth2.0 begins)." example: 1557716289 - - merkle_root: - type: string - format: byte - pattern: "^0x[a-fA-F0-9]{64}$" - description: "A 32 byte merkle root, used in all kinds of scenarios." - ValidatorDuty: type: object properties: @@ -271,7 +265,6 @@ components: format: uint64 nullable: true description: "The slot in which a validator must propose a block, or `null` if block production is not required." - SyncingStatus: type: object nullable: true @@ -290,15 +283,15 @@ components: description: "The estimated highest block, or current target block number." BeaconBlock: + description: "The [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec." allOf: - $ref: '#/components/schemas/BeaconBlockCommon' - type: object - description: "The [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec." properties: body: $ref: '#/components/schemas/BeaconBlockBody' - BeaconBlockHeader: + description: "The [`BeaconBlockHeader`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblockheader) object from the Eth2.0 spec." allOf: - $ref: '#/components/schemas/BeaconBlockCommon' - type: object @@ -308,7 +301,30 @@ components: format: bytes pattern: "^0x[a-fA-F0-9]{64}$" description: "The tree hash merkle root of the `BeaconBlockBody` for the `BeaconBlock`" - + BeaconBlockCommon: + # An abstract object to collect the common fields between the BeaconBlockHeader and the BeaconBlock objects + type: object + properties: + slot: + type: integer + format: uint64 + description: "The slot to which this block corresponds." + parent_root: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{64}$" + description: "The signing merkle root of the parent `BeaconBlock`." + state_root: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{64}$" + description: "The tree hash merkle root of the `BeaconState` for the `BeaconBlock`." + signature: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{192}$" + example: "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + description: "The BLS signature of the `BeaconBlock` made by the validator of the block." BeaconBlockBody: type: object description: "The [`BeaconBlockBody`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblockbody) object from the Eth2.0 spec." @@ -336,7 +352,7 @@ components: type: string format: byte pattern: "^0x[a-fA-F0-9]{64}$" - description: "Ethereum 1.x block hash" + description: "Ethereum 1.x block hash." graffiti: type: string format: byte @@ -383,7 +399,7 @@ components: type: string format: byte pattern: "^0x[a-fA-F0-9]+$" - description: "Custody bitfield" + description: "Custody bitfield." signature: type: string format: byte @@ -476,50 +492,25 @@ components: amount: type: integer format: uint64 - description: "Amount in Gwei" + description: "Amount in Gwei." fee: type: integer format: uint64 - description: "Fee in Gwei for block producer" + description: "Fee in Gwei for block producer." slot: type: integer format: uint64 - description: "Inclusion slot" + description: "Inclusion slot." pubkey: type: string format: byte pattern: "^0x[a-fA-F0-9]{96}$" - description: "Sender withdrawal public key" + description: "Sender withdrawal public key." signature: type: string format: byte pattern: "^0x[a-fA-F0-9]{192}$" - description: "Sender signature" - - BeaconBlockCommon: - # An object to collect the common fields between the BeaconBlockHeader and the BeaconBlock objects - type: object - properties: - slot: - type: integer - format: uint64 - description: "The slot to which this block corresponds." - parent_root: - type: string - format: bytes - pattern: "^0x[a-fA-F0-9]{64}$" - description: "The signing merkle root of the parent `BeaconBlock`" - state_root: - type: string - format: bytes - pattern: "^0x[a-fA-F0-9]{64}$" - description: "The tree hash merkle root of the `BeaconState` for the `BeaconBlock`" - signature: - type: string - format: bytes - pattern: "^0x[a-fA-F0-9]{192}$" - example: "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" - description: "The BLS signature of the `BeaconBlock` made by the validator of the block" + description: "Sender signature." Fork: type: object @@ -529,17 +520,16 @@ components: type: string format: byte pattern: "^0x[a-fA-F0-9]{8}$" - description: "Previous fork version" + description: "Previous fork version." current_version: type: string format: byte pattern: "^0x[a-fA-F0-9]{8}$" - description: "Current fork version" + description: "Current fork version." epoch: type: integer format: uint64 - description: "Fork epoch number" - + description: "Fork epoch number." IndexedAttestation: type: object description: "The [`IndexedAttestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#indexedattestation) object from the Eth2.0 spec." @@ -558,51 +548,63 @@ components: format: uint64 data: $ref: '#/components/schemas/AttestationData' - AttestationData: type: object description: "The [`AttestationData`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestationdata) object from the Eth2.0 spec." properties: beacon_block_root: - $ref: '#/components/schemas/merkle_root' + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "LMD GHOST vote." source_epoch: type: integer format: uint64 - description: "Source epoch from FFG vote" + description: "Source epoch from FFG vote." source_root: - $ref: '#/components/schemas/merkle_root' + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "Source root from FFG vote." target_epoch: type: integer format: uint64 - description: "Target epoch from FFG vote" + description: "Target epoch from FFG vote." target_root: - $ref: '#/components/schemas/merkle_root' + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "Target root from FFG vote." crosslink: - $ref: '#/components/schemas/CrossLink' - - CrossLink: - type: object - description: "The [`Crosslink`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec." - properties: - shard: - type: integer - format: uint64 - description: "The shard number" - epoch: - type: integer - format: uint64 - description: "The epoch number" - parent_root: - $ref: '#/components/schemas/merkle_root' - data_root: - $ref: '#/components/schemas/merkle_root' + title: CrossLink + type: object + description: "The [`Crosslink`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec." + properties: + shard: + type: integer + format: uint64 + description: "The shard number." + epoch: + type: integer + format: uint64 + description: "The epoch number." + parent_root: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "Root of the previous crosslink." + data_root: + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + description: "Root of the crosslinked shard data since the previous crosslink." responses: Success: - description: Request successful + description: "Request successful." InvalidRequest: - description: Invalid request syntax + description: "Invalid request syntax." InternalError: - description: Beacon node internal error + description: "Beacon node internal error." CurrentlySyncing: - description: Beacon node is currently syncing, try again later + description: "Beacon node is currently syncing, try again later." From 0b2c7acdb32a0daf81cf3f54e8ab35679f7083a7 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 13 May 2019 16:25:22 +1000 Subject: [PATCH 08/19] 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. From ac7a40376ba787b55abfc96aa87d0741a6fdb437 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 13 May 2019 16:26:45 +1000 Subject: [PATCH 09/19] Included a link to the API document in the root README.md file. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ad7204f21..ec8056956 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ Core specifications for eth2.0 client validation can be found in [specs/core](sp * [General test format](specs/test_formats/README.md) * [Merkle proof formats](specs/light_client/merkle_proofs.md) * [Light client syncing protocol](specs/light_client/sync_protocol.md) +* [Beacon node API for validator](specs/validator/0_beacon-node-validator-api.md) ### Design goals From 67921ab96fdd1ed108fb5bc2f8d7d75871083a8b Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 13 May 2019 16:30:53 +1000 Subject: [PATCH 10/19] Fixed up some small wording in the API readme. --- specs/validator/0_beacon-node-validator-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/validator/0_beacon-node-validator-api.md b/specs/validator/0_beacon-node-validator-api.md index cf763f778..5c597aa75 100644 --- a/specs/validator/0_beacon-node-validator-api.md +++ b/specs/validator/0_beacon-node-validator-api.md @@ -4,9 +4,9 @@ __NOTICE__: This document is a work-in-progress for researchers and implementers ## 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 beacon node for use by a validator client implementation which aims to facilitate [_phase 0_](../../README.md#phase-0) of Ethereum 2.0. -The API is a REST interface, accessed via HTTP, designed for use as a local communications protocol between binaries. +The API is a REST interface, accessed via HTTP, designed for use as a local communications protocol between binaries. The only supported return data type is currently JSON. ### Background The beacon node maintains the state of the beacon chain by communicating with other beacon nodes in the Ethereum Serenity network. Conceptually, it does not maintain keypairs that participate with the beacon chain. From 73c9d126dee0a4dafab4bbf00197ea56a2a3da94 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 20 May 2019 13:49:06 +1000 Subject: [PATCH 11/19] Updated API spec with suggestions by @hwwhww. - Corrected to use American English instead of Australian - Fixed spelling mistake with indices - Changed tag to 'MinimalSet' and 'OptionalSet' - Added a response to the list of components - Renamed 'block_production' to 'block_proposal' --- .../validator/0_beacon-node-validator-api.md | 2 +- specs/validator/beacon_node_oapi.yaml | 38 ++++++++++--------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/specs/validator/0_beacon-node-validator-api.md b/specs/validator/0_beacon-node-validator-api.md index 5c597aa75..ec0300e9a 100644 --- a/specs/validator/0_beacon-node-validator-api.md +++ b/specs/validator/0_beacon-node-validator-api.md @@ -11,7 +11,7 @@ The API is a REST interface, accessed via HTTP, designed for use as a local comm ### Background The beacon node maintains the state of the beacon chain by communicating with other beacon nodes in the Ethereum Serenity network. Conceptually, it does not maintain keypairs that participate with the beacon chain. -The validator client is a conceptually separate entity which utilises private keys to perform validator related tasks on the beacon chain, which we call validator "duties". These duties includes the production of beacon blocks and signing of attestations. +The validator client is a conceptually separate entity which utilizes private keys to perform validator related tasks on the beacon chain, which we call validator "duties". These duties include the production of beacon blocks and signing of attestations. Since it is recommended to separate these concerns in the client implementations, we must clearly define the communication between them. diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 0c2937f3d..e0e3da7d2 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -7,15 +7,15 @@ info: name: "Apache 2.0" url: "https://www.apache.org/licenses/LICENSE-2.0.html" tags: - - name: Necessary for validator + - name: MinimalSet description: The minimal set of endpoints to enable a working validator implementation. - - name: Optional + - name: OptionalSet description: Extra endpoints which are nice-to-haves. paths: /node/version: get: tags: - - Necessary for validator + - MinimalSet summary: "Get version string of the running beacon node." description: "Requests that the beacon node 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." responses: @@ -30,7 +30,7 @@ paths: /node/genesis_time: get: tags: - - Necessary for validator + - MinimalSet summary: "Get the genesis_time parameter from beacon node configuration." description: "Requests the genesis_time parameter from the beacon node, which should be consistent across all beacon nodes that follow the same beacon chain." responses: @@ -46,7 +46,7 @@ paths: /node/syncing: get: tags: - - Necessary for validator + - MinimalSet summary: "Poll to see if the the beacon node is syncing." description: "Requests the beacon node 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 call.." responses: @@ -67,7 +67,7 @@ paths: /node/fork: get: tags: - - Optional + - OptionalSet summary: "Get fork information from running beacon node." description: "Requests the beacon node to provide which fork version it is currently on." responses: @@ -83,16 +83,16 @@ paths: chain_id: type: integer format: uint64 - description: "Sometimes called the network id, this number discerns the active chain for the BeaconNode. Analagous to Eth1.0 JSON-RPC net_version." + description: "Sometimes called the network id, this number discerns the active chain for the beacon node. Analagous to Eth1.0 JSON-RPC net_version." 500: $ref: '#/components/responses/InternalError' /validator/duties: get: tags: - - Necessary for validator + - MinimalSet summary: "Get validator duties for the requested validators." - description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators. 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 beacon node is properly synchronised." + description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators. 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 beacon node is properly synchronized." parameters: - name: validator_pubkeys in: query @@ -122,7 +122,7 @@ paths: /validator/block: get: tags: - - Necessary for validator + - MinimalSet summary: "Produce a new block, without signature." description: "Requests a beacon node to produce a valid block, which can then be signed by a validator." parameters: @@ -155,7 +155,7 @@ paths: $ref: '#/components/responses/CurrentlySyncing' post: tags: - - Necessary for validator + - MinimalSet summary: "Publish a signed block." description: "Instructs the beacon node to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." parameters: @@ -178,7 +178,7 @@ paths: /validator/attestation: get: tags: - - Necessary for validator + - MinimalSet summary: "Produce an attestation, without signature." description: "Requests that the beacon node produce an IndexedAttestation, with a blank signature field, which the validator will then sign." parameters: @@ -209,7 +209,7 @@ paths: $ref: '#/components/responses/CurrentlySyncing' post: tags: - - Necessary for validator + - MinimalSet summary: "Published a signed attestation." description: "Instructs the beacon node to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain." parameters: @@ -263,7 +263,7 @@ components: type: integer format: uint64 description: "The shard in which the validator must attest." - block_production_slot: + block_proposal_slot: type: integer format: uint64 nullable: true @@ -537,15 +537,15 @@ components: type: object description: "The [`IndexedAttestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#indexedattestation) object from the Eth2.0 spec." properties: - custody_bit_0_indicies: + custody_bit_0_indices: type: array - description: "Validator indicies for 0 bits." + description: "Validator indices for 0 bits." items: type: integer format: uint64 - custody_bit_1_indicies: + custody_bit_1_indices: type: array - description: "Validator indicies for 1 bits." + description: "Validator indices for 1 bits." items: type: integer format: uint64 @@ -611,3 +611,5 @@ components: description: "Beacon node internal error." CurrentlySyncing: description: "Beacon node is currently syncing, try again later." + NotFound: + description: "The requested API endpoint does not exist." From 490cf9e347c5229127af94e0bfa431d3a0f38b16 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 20 May 2019 13:56:25 +1000 Subject: [PATCH 12/19] Updated version number to reflect small changes. --- specs/validator/beacon_node_oapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index e0e3da7d2..e995e9c84 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -2,7 +2,7 @@ openapi: "3.0.2" info: title: "Minimal Beacon Node API for Validator" 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.1" license: name: "Apache 2.0" url: "https://www.apache.org/licenses/LICENSE-2.0.html" From 8e67dec7e40a241ace49efd1e02114c2830ddb7a Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 20 May 2019 16:43:21 +1000 Subject: [PATCH 13/19] Fixed misinterpretation of the proof array in the Deposit object, bumped version. --- specs/validator/beacon_node_oapi.yaml | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index e995e9c84..900b8eefa 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -2,7 +2,7 @@ openapi: "3.0.2" info: title: "Minimal Beacon Node API for Validator" 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.1" + version: "0.1.2" license: name: "Apache 2.0" url: "https://www.apache.org/licenses/LICENSE-2.0.html" @@ -421,17 +421,11 @@ components: type: array description: "Branch in the deposit tree." items: - oneOf: - - type: string - format: byte - pattern: "^0x[a-fA-F0-9]{64}$" - - type: integer - format: uint64 - enum: [32] - example: 32 - description: "The DEPOSIT_CONTRACT_TREE_DEPTH value." - minItems: 2 - maxItems: 2 + type: string + format: byte + pattern: "^0x[a-fA-F0-9]{64}$" + minItems: 32 + maxItems: 32 index: type: integer format: uint64 From 7b30c55cd4a774af76d53013c1c5e0b8f63a1604 Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Thu, 23 May 2019 13:10:34 -0400 Subject: [PATCH 14/19] minor copy edits to vc api --- specs/validator/0_beacon-node-validator-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/validator/0_beacon-node-validator-api.md b/specs/validator/0_beacon-node-validator-api.md index ec0300e9a..afecc395c 100644 --- a/specs/validator/0_beacon-node-validator-api.md +++ b/specs/validator/0_beacon-node-validator-api.md @@ -15,7 +15,7 @@ The validator client is a conceptually separate entity which utilizes private ke Since it is recommended to separate these concerns in the client implementations, we must clearly define the communication between them. -The goal of this specification is to promote interoperability between beacon nodes and validator clients derived from different projects. For example, the validator client from Lighthouse, could communicate with a running instance of the beacon node from Prysm. +The goal of this specification is to promote interoperability between beacon nodes and validator clients derived from different projects and to encourage innovation in validator clients independet of beacon node development. For example, the validator client from Lighthouse could communicate with a running instance of the beacon node from Prysm, or a staking pool might create a decentrally managed validator client plugging into the same API. This specification is derived from a proposal and discussion on Issues [#1011](https://github.com/ethereum/eth2.0-specs/issues/1011) and [#1012](https://github.com/ethereum/eth2.0-specs/issues/1012) From edf0b9d05fd77d3c1a1035f4e97252cfc18d9d8e Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Sat, 25 May 2019 07:59:35 +1000 Subject: [PATCH 15/19] Addressed some of @djrtwo's suggestions. - Rewording of specification goal paragraph - Clarify get duties description regarding chain reorgs. - Add epoch parameter to get duties, and new error 406 - Block publishing action is clarified around validation, with a new status code 202 - The validator pubkey and PoC bit are passed to produce attestation - Attestation publishing action is clarified around validation, new status code 202 - Rewording of genesis_time, 'block' -> 'slot' - Update Crosslink to latest spec - Added missing signature field to IndexedAttestation --- .../validator/0_beacon-node-validator-api.md | 2 +- specs/validator/beacon_node_oapi.yaml | 69 +++++++++++++------ 2 files changed, 50 insertions(+), 21 deletions(-) diff --git a/specs/validator/0_beacon-node-validator-api.md b/specs/validator/0_beacon-node-validator-api.md index afecc395c..c53ce37ac 100644 --- a/specs/validator/0_beacon-node-validator-api.md +++ b/specs/validator/0_beacon-node-validator-api.md @@ -15,7 +15,7 @@ The validator client is a conceptually separate entity which utilizes private ke Since it is recommended to separate these concerns in the client implementations, we must clearly define the communication between them. -The goal of this specification is to promote interoperability between beacon nodes and validator clients derived from different projects and to encourage innovation in validator clients independet of beacon node development. For example, the validator client from Lighthouse could communicate with a running instance of the beacon node from Prysm, or a staking pool might create a decentrally managed validator client plugging into the same API. +The goal of this specification is to promote interoperability between beacon nodes and validator clients derived from different projects and to encourage innovation in validator client implementations, independently from beacon node development. For example, the validator client from Lighthouse could communicate with a running instance of the beacon node from Prysm, or a staking pool might create a decentrally managed validator client which utilises the same API. This specification is derived from a proposal and discussion on Issues [#1011](https://github.com/ethereum/eth2.0-specs/issues/1011) and [#1012](https://github.com/ethereum/eth2.0-specs/issues/1012) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 900b8eefa..c98fbd048 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -92,7 +92,7 @@ paths: tags: - MinimalSet summary: "Get validator duties for the requested validators." - description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators. 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 beacon node is properly synchronized." + description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganisation (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, this API call should be polled at every slot to ensure that chain reorganisations are recognised, and to ensure that the beacon node is properly synchronized." parameters: - name: validator_pubkeys in: query @@ -103,6 +103,11 @@ paths: items: $ref: '#/components/schemas/pubkey' minItems: 1 + - name: epoch + in: query + required: false + schema: + type: integer responses: 200: description: Success response @@ -114,6 +119,8 @@ paths: $ref: '#/components/schemas/ValidatorDuty' 400: $ref: '#/components/responses/InvalidRequest' + 406: + description: "Duties cannot be provided for the requested epoch." 500: $ref: '#/components/responses/InternalError' 503: @@ -157,7 +164,7 @@ paths: tags: - MinimalSet summary: "Publish a signed block." - description: "Instructs the beacon node to publish a newly signed beacon block to the beacon network, to be included in the beacon chain." + description: "Instructs the beacon node to broadcast a newly signed beacon block to the beacon network, to be included in the beacon chain. The beacon node is not required to validate the signed `BeaconBlock`, and a successful response (20X) only indicates that the broadcast has been successful. The beacon node is expected to integrate the new block into its state, and therefore validate the block internally, however blocks which fail the validation are still broadcast but a different status code is returned (202)" parameters: - name: beacon_block in: query @@ -167,7 +174,9 @@ paths: $ref: '#/components/schemas/BeaconBlock' responses: 200: - $ref: '#/components/responses/Success' + description: "The block was validated successfully and has been broadcast. It has also been integrated into the beacon node's database." + 202: + description: "The block failed validation, but was successfully broadcast anyway. It was not integrated into the beacon node's database." 400: $ref: '#/components/responses/InvalidRequest' 500: @@ -182,6 +191,18 @@ paths: summary: "Produce an attestation, without signature." description: "Requests that the beacon node produce an IndexedAttestation, with a blank signature field, which the validator will then sign." parameters: + - name: validator_pubkey + in: query + required: true + description: "Uniquely identifying which validator this attestation is to be produced for." + schema: + $ref: '#/components/schemas/pubkey' + - name: poc_bit + in: query + required: true + description: "The proof-of-custody bit that is reported by this " + schema: + # Still need to establish a schema for this. - name: slot in: query required: true @@ -210,8 +231,8 @@ paths: post: tags: - MinimalSet - summary: "Published a signed attestation." - description: "Instructs the beacon node to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain." + summary: "Publish a signed attestation." + description: "Instructs the beacon node to broadcast a newly signed IndexedAttestation object to the intended shard subnet. The beacon node is not required to validate the signed IndexedAttestation, and a successful response (20X) only indicates that the broadcast has been successful. The beacon node is expected to integrate the new attestation into its state, and therefore validate the attestation internally, however attestations which fail the validation are still broadcast but a different status code is returned (202)" parameters: - name: attestation in: query @@ -221,7 +242,9 @@ paths: $ref: '#/components/schemas/IndexedAttestation' responses: 200: - $ref: '#/components/responses/Success' + description: "The attestation was validated successfully and has been broadcast. It has also been integrated into the beacon node's database." + 202: + description: "The attestation failed validation, but was successfully broadcast anyway. It was not integrated into the beacon node's database." 400: $ref: '#/components/responses/InvalidRequest' 500: @@ -244,17 +267,13 @@ components: genesis_time: type: integer format: uint64 - description: "The genesis_time configured for the beacon node, which is the time the Eth1.0 validator deposit smart contract has enough ETH staked (i.e. Eth2.0 begins)." + description: "The genesis_time configured for the beacon node, which is the unix time at which the Eth2.0 chain began." example: 1557716289 ValidatorDuty: type: object properties: validator_pubkey: $ref: '#/components/schemas/pubkey' - committee_index: - type: integer - format: uint64 - description: "The index of the validator in the committee." attestation_slot: type: integer format: uint64 @@ -272,18 +291,18 @@ components: type: object nullable: true properties: - starting_block: + starting_slot: type: integer format: uint64 - description: "The block at which syncing started (will only be reset after the sync reached its head)" - current_block: + description: "The slot at which syncing started (will only be reset after the sync reached its head)" + current_slot: type: integer format: uint64 - description: "The current highest block sync'd by the beacon node." - highest_block: + description: "The most recent slot sync'd by the beacon node." + highest_slot: type: integer format: uint64 - description: "The estimated highest block, or current target block number." + description: "Globally, the estimated most recent slot number, or current target slot number." BeaconBlock: description: "The [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec." @@ -543,6 +562,12 @@ components: items: type: integer format: uint64 + signature: + type: string + format: bytes + pattern: "^0x[a-fA-F0-9]{192}$" + example: "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505" + description: "The BLS signature of the `IndexedAttestation`, created by the validator of the attestation." data: $ref: '#/components/schemas/AttestationData' AttestationData: @@ -575,16 +600,20 @@ components: crosslink: title: CrossLink type: object - description: "The [`Crosslink`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec." + description: "The [`Crosslink`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec, contains data from epochs [`start_epoch`, `end_epoch`)." properties: shard: type: integer format: uint64 description: "The shard number." - epoch: + start_epoch: type: integer format: uint64 - description: "The epoch number." + description: "The first epoch which the crosslinking data references." + end_epoch: + type: integer + format: uint64 + description: "The 'end' epoch referred to by the crosslinking data; no data in this Crosslink should refer to the `end_epoch` since it is not included in the crosslinking data interval." parent_root: type: string format: byte From af798a3065f2fe293a1823ebe843ada31b11863a Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 27 May 2019 11:21:23 +1000 Subject: [PATCH 16/19] Minor updates. - Fixed spelling (and made American English) - Clarified the schema for the new poc_bit field, and description. --- specs/validator/beacon_node_oapi.yaml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index c98fbd048..6dca1a107 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -83,7 +83,7 @@ paths: chain_id: type: integer format: uint64 - description: "Sometimes called the network id, this number discerns the active chain for the beacon node. Analagous to Eth1.0 JSON-RPC net_version." + description: "Sometimes called the network id, this number discerns the active chain for the beacon node. Analogous to Eth1.0 JSON-RPC net_version." 500: $ref: '#/components/responses/InternalError' @@ -92,7 +92,7 @@ paths: tags: - MinimalSet summary: "Get validator duties for the requested validators." - description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganisation (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, this API call should be polled at every slot to ensure that chain reorganisations are recognised, and to ensure that the beacon node is properly synchronized." + description: "Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, this API call should be polled at every slot to ensure that chain reorganizations are recognized, and to ensure that the beacon node is properly synchronized." parameters: - name: validator_pubkeys in: query @@ -200,9 +200,12 @@ paths: - name: poc_bit in: query required: true - description: "The proof-of-custody bit that is reported by this " + description: "The proof-of-custody bit that is to be reported by the requesting validator. This bit will be inserted into the appropriate location in the returned `IndexedAttestation`." schema: - # Still need to establish a schema for this. + type: integer + format: uint32 + minimum: 0 + maximum: 1 - name: slot in: query required: true From fa177e03553f444c1ba1ae845f23470f9e9d7b1d Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Mon, 27 May 2019 13:01:36 +1000 Subject: [PATCH 17/19] Bumped API version number to 0.2.0 --- specs/validator/beacon_node_oapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 6dca1a107..940f82137 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -2,7 +2,7 @@ openapi: "3.0.2" info: title: "Minimal Beacon Node API for Validator" 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.2" + version: "0.2.0" license: name: "Apache 2.0" url: "https://www.apache.org/licenses/LICENSE-2.0.html" From 56698602ab325871d703bacf3bb12a392421cbf1 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Tue, 28 May 2019 10:48:41 +1000 Subject: [PATCH 18/19] Updated all absolute URLs to the eth2.0-specs repo so that they point to the master branch (instead of dev). --- specs/validator/beacon_node_oapi.yaml | 30 +++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/specs/validator/beacon_node_oapi.yaml b/specs/validator/beacon_node_oapi.yaml index 940f82137..74be21fac 100644 --- a/specs/validator/beacon_node_oapi.yaml +++ b/specs/validator/beacon_node_oapi.yaml @@ -308,7 +308,7 @@ components: description: "Globally, the estimated most recent slot number, or current target slot number." BeaconBlock: - description: "The [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec." + description: "The [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec." allOf: - $ref: '#/components/schemas/BeaconBlockCommon' - type: object @@ -316,7 +316,7 @@ components: body: $ref: '#/components/schemas/BeaconBlockBody' BeaconBlockHeader: - description: "The [`BeaconBlockHeader`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblockheader) object from the Eth2.0 spec." + description: "The [`BeaconBlockHeader`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconblockheader) object from the Eth2.0 spec." allOf: - $ref: '#/components/schemas/BeaconBlockCommon' - type: object @@ -352,7 +352,7 @@ components: description: "The BLS signature of the `BeaconBlock` made by the validator of the block." BeaconBlockBody: type: object - description: "The [`BeaconBlockBody`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblockbody) object from the Eth2.0 spec." + description: "The [`BeaconBlockBody`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconblockbody) object from the Eth2.0 spec." properties: randao_reveal: type: string @@ -362,7 +362,7 @@ components: eth1_data: title: Eth1Data type: object - description: "The [`Eth1Data`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#eth1data) object from the Eth2.0 spec." + description: "The [`Eth1Data`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#eth1data) object from the Eth2.0 spec." properties: deposit_root: type: string @@ -387,7 +387,7 @@ components: items: title: ProposerSlashings type: object - description: "The [`ProposerSlashing`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#proposerslashing) object from the Eth2.0 spec." + description: "The [`ProposerSlashing`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#proposerslashing) object from the Eth2.0 spec." properties: proposer_index: type: integer @@ -402,7 +402,7 @@ components: items: title: AttesterSlashings type: object - description: "The [`AttesterSlashing`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attesterslashing) object from the Eth2.0 spec." + description: "The [`AttesterSlashing`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attesterslashing) object from the Eth2.0 spec." properties: attestation_1: $ref: '#/components/schemas/IndexedAttestation' @@ -413,7 +413,7 @@ components: items: title: Attestation type: object - description: "The [`Attestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestation) object from the Eth2.0 spec." + description: "The [`Attestation`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attestation) object from the Eth2.0 spec." properties: aggregation_bitfield: type: string @@ -437,7 +437,7 @@ components: items: title: Deposit type: object - description: "The [`Deposit`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#deposit) object from the Eth2.0 spec." + description: "The [`Deposit`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#deposit) object from the Eth2.0 spec." properties: proof: type: array @@ -455,7 +455,7 @@ components: data: title: DepositData type: object - description: "The [`DepositData`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#depositdata) object from the Eth2.0 spec." + description: "The [`DepositData`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#depositdata) object from the Eth2.0 spec." properties: pubkey: $ref: '#/components/schemas/pubkey' @@ -478,7 +478,7 @@ components: items: title: VoluntaryExit type: object - description: "The [`VoluntaryExit`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#voluntaryexit) object from the Eth2.0 spec." + description: "The [`VoluntaryExit`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#voluntaryexit) object from the Eth2.0 spec." properties: epoch: type: integer @@ -498,7 +498,7 @@ components: items: title: Transfer type: object - description: "The [`Transfer`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#transfer) object from the Eth2.0 spec." + description: "The [`Transfer`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#transfer) object from the Eth2.0 spec." properties: sender: type: integer @@ -533,7 +533,7 @@ components: Fork: type: object - description: "The [`Fork`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#Fork) object from the Eth2.0 spec." + description: "The [`Fork`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#Fork) object from the Eth2.0 spec." properties: previous_version: type: string @@ -551,7 +551,7 @@ components: description: "Fork epoch number." IndexedAttestation: type: object - description: "The [`IndexedAttestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#indexedattestation) object from the Eth2.0 spec." + description: "The [`IndexedAttestation`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#indexedattestation) object from the Eth2.0 spec." properties: custody_bit_0_indices: type: array @@ -575,7 +575,7 @@ components: $ref: '#/components/schemas/AttestationData' AttestationData: type: object - description: "The [`AttestationData`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestationdata) object from the Eth2.0 spec." + description: "The [`AttestationData`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attestationdata) object from the Eth2.0 spec." properties: beacon_block_root: type: string @@ -603,7 +603,7 @@ components: crosslink: title: CrossLink type: object - description: "The [`Crosslink`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec, contains data from epochs [`start_epoch`, `end_epoch`)." + description: "The [`Crosslink`](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec, contains data from epochs [`start_epoch`, `end_epoch`)." properties: shard: type: integer From c32328fdf2d13796343cc5cd33bd1c5a1c9043e7 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Tue, 28 May 2019 10:49:40 +1000 Subject: [PATCH 19/19] Fixed swagger URL so that the version number isn't specified (defaults to latest). --- specs/validator/0_beacon-node-validator-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/validator/0_beacon-node-validator-api.md b/specs/validator/0_beacon-node-validator-api.md index c53ce37ac..2a5fe7fcd 100644 --- a/specs/validator/0_beacon-node-validator-api.md +++ b/specs/validator/0_beacon-node-validator-api.md @@ -25,4 +25,4 @@ This specification is derived from a proposal and discussion on Issues [#1011](h 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. 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) +[https://app.swaggerhub.com/apis/spble/beacon_node_api_for_validator](https://app.swaggerhub.com/apis/spble/beacon_node_api_for_validator)