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

remove APIs and add links to outside spec/stnards repos

This commit is contained in:
Danny Ryan 2019-08-16 13:35:23 -06:00
parent f9d703c126
commit 83566afa1b
No known key found for this signature in database
GPG Key ID: 2765A792E42CE07A
3 changed files with 8 additions and 668 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -37,6 +37,14 @@ See the [Eth 2.0 Phase 2 Wiki](https://hackmd.io/UzysWse1Th240HELswKqVA?view) fo
* [Beacon node API for validator](specs/validator/0_beacon-node-validator-api.md)
## Additional specifications for client implementers
Additional specifications and standards outside of core consensus can be found in the following repos:
* [Eth2.0 APIs](https://github.com/ethereum/eth2.0-apis)
* [Eth2.0 Metrics](https://github.com/ethereum/eth2.0-metrics/)
* [Interop Standards in Eth2.0-pm](https://github.com/ethereum/eth2.0-pm/tree/master/interop)
## Design goals
The following are the broad design goals for Ethereum 2.0:

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

@ -1,27 +0,0 @@
# 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.
## Outline
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. Currently, the only supported return data type is JSON.
## Background
The beacon node maintains the state of the beacon chain by communicating with other beacon nodes in the Ethereum 2.0 network. Conceptually, it does not maintain keypairs that participate with the beacon chain.
The validator client is a conceptually separate entity which utilizes private keys to perform validator related tasks, called "duties", on the beacon chain. 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.
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](https://github.com/sigp/lighthouse) could communicate with a running instance of the beacon node from [Prysm](https://github.com/prysmaticlabs/prysm), or a staking pool might create a decentrally managed validator client which utilizes 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).
## Specification
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 [here](https://app.swaggerhub.com/apis/spble/beacon_node_api_for_validator).

641
specs/validator/beacon_node_oapi.yaml
View File

@ -1,641 +0,0 @@
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.2.0"
license:
name: "Apache 2.0"
url: "https://www.apache.org/licenses/LICENSE-2.0.html"
tags:
- name: MinimalSet
description: The minimal set of endpoints to enable a working validator implementation.
- name: OptionalSet
description: Extra endpoints which are nice-to-haves.
paths:
/node/version:
get:
tags:
- 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:
200:
description: Request successful
content:
application/json:
schema:
$ref: '#/components/schemas/version'
500:
$ref: '#/components/responses/InternalError'
/node/genesis_time:
get:
tags:
- 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:
200:
description: Request successful
content:
application/json:
schema:
$ref: '#/components/schemas/genesis_time'
500:
$ref: '#/components/responses/InternalError'
/node/syncing:
get:
tags:
- 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:
200:
description: Request successful
content:
application/json:
schema:
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'
/node/fork:
get:
tags:
- OptionalSet
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 beacon node. Analogous to Eth1.0 JSON-RPC net_version."
500:
$ref: '#/components/responses/InternalError'
/validator/duties:
get:
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 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
required: true
description: "An array of hex-encoded BLS public keys"
schema:
type: array
items:
$ref: '#/components/schemas/pubkey'
minItems: 1
- name: epoch
in: query
required: false
schema:
type: integer
responses:
200:
description: Success response
content:
application/json:
schema:
type: array
items:
$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:
$ref: '#/components/responses/CurrentlySyncing'
/validator/block:
get:
tags:
- 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:
- 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 validator's randao reveal value."
schema:
type: string
format: byte
responses:
200:
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/BeaconBlock'
400:
$ref: '#/components/responses/InvalidRequest'
500:
$ref: '#/components/responses/InternalError'
503:
$ref: '#/components/responses/CurrentlySyncing'
post:
tags:
- MinimalSet
summary: "Publish a signed block."
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
required: true
description: "The `BeaconBlock` object, as sent from the beacon node originally, but now with the signature field completed."
schema:
$ref: '#/components/schemas/BeaconBlock'
responses:
200:
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:
$ref: '#/components/responses/InternalError'
503:
$ref: '#/components/responses/CurrentlySyncing'
/validator/attestation:
get:
tags:
- 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:
- 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 to be reported by the requesting validator. This bit will be inserted into the appropriate location in the returned `IndexedAttestation`."
schema:
type: integer
format: uint32
minimum: 0
maximum: 1
- 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:
200:
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/IndexedAttestation'
400:
$ref: '#/components/responses/InvalidRequest'
500:
$ref: '#/components/responses/InternalError'
503:
$ref: '#/components/responses/CurrentlySyncing'
post:
tags:
- MinimalSet
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
required: true
description: "An `IndexedAttestation` structure, as originally provided by the beacon node, but now with the signature field completed."
schema:
$ref: '#/components/schemas/IndexedAttestation'
responses:
200:
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:
$ref: '#/components/responses/InternalError'
503:
$ref: '#/components/responses/CurrentlySyncing'
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 unix time at which the Eth2.0 chain began."
example: 1557716289
ValidatorDuty:
type: object
properties:
validator_pubkey:
$ref: '#/components/schemas/pubkey'
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_proposal_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_slot:
type: integer
format: uint64
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 most recent slot sync'd by the beacon node."
highest_slot:
type: integer
format: uint64
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/master/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec."
allOf:
- $ref: '#/components/schemas/BeaconBlockCommon'
- type: object
properties:
body:
$ref: '#/components/schemas/BeaconBlockBody'
BeaconBlockHeader:
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
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`"
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/master/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/master/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/master/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/master/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/master/specs/core/0_beacon-chain.md#attestation) object from the Eth2.0 spec."
properties:
aggregation_bits:
type: string
format: byte
pattern: "^0x[a-fA-F0-9]+$"
description: "Attester aggregation bits."
custody_bits:
type: string
format: byte
pattern: "^0x[a-fA-F0-9]+$"
description: "Custody bits."
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/master/specs/core/0_beacon-chain.md#deposit) object from the Eth2.0 spec."
properties:
proof:
type: array
description: "Branch in the deposit tree."
items:
type: string
format: byte
pattern: "^0x[a-fA-F0-9]{64}$"
minItems: 32
maxItems: 32
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/master/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/master/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/master/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."
Fork:
type: object
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
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/master/specs/core/0_beacon-chain.md#indexedattestation) object from the Eth2.0 spec."
properties:
custody_bit_0_indices:
type: array
description: "Validator indices for 0 bits."
items:
type: integer
format: uint64
custody_bit_1_indices:
type: array
description: "Validator indices for 1 bits."
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:
type: object
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
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."
source_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."
target_root:
type: string
format: byte
pattern: "^0x[a-fA-F0-9]{64}$"
description: "Target root from FFG vote."
crosslink:
title: CrossLink
type: object
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
format: uint64
description: "The shard number."
start_epoch:
type: integer
format: uint64
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
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."
InvalidRequest:
description: "Invalid request syntax."
InternalError:
description: "Beacon node internal error."
CurrentlySyncing:
description: "Beacon node is currently syncing, try again later."
NotFound:
description: "The requested API endpoint does not exist."