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

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
This commit is contained in:
Luke Anderson 2019-05-25 07:59:35 +10:00
parent 7b30c55cd4
commit edf0b9d05f
No known key found for this signature in database
GPG Key ID: 44408169EC61E228
2 changed files with 50 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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)

69
specs/validator/beacon_node_oapi.yaml
View File

@ -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