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:
- Phase0
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:
- Phase0
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."
summary:"Get the node's Ethereum Node Record (ENR)."
description:"The Ethereum Node Record (ENR) contains a compressed public key, an IPv4 address, a TCP port and a UDP port, which is all encoded using base64. This endpoint fetches the base64 encoded version of the ENR for the running beacon node."
description:"Requests the node to provide it's libp2p ['peer ID'](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md), which is a base58 encoded SHA2-256 'multihash' of the node's public key struct."
summary:"List the networking peers with which the node is communicating."
description:"Requests that the beacon node identify all of the peers with which it is communicating, including established connections and connections which it is attempting to establish."
summary:"Get the TCP port number for the libp2p listener."
description:"Libp2p is configured to listen to a particular TCP port upon startup of the beacon node. This endpoint returns the port number that the beacon node is listening on. Please note, this is for the libp2p communications, not for discovery."
summary:"Identify the port and addresses listened to by the beacon node."
description:"Libp2p is configured to listen to a particular address, on a particular port. This address is represented the [`multiaddr`](https://multiformats.io/multiaddr/) format, and this endpoint requests the beacon node to list all listening addresses in this format."
summary:"Detail the current perspective of the beacon node."
description:"Request the beacon node to identify the most up-to-date information about the beacon chain from its perspective. This includes the latest block, which slots have been finalized, etc."
description:"Request that the beacon node return beacon chain blocks that match the provided criteria (a block root or beacon chain slot). Only one of the parameters can be be provided at a time."
parameters:
- name:root
description:"Filter by block root."
in:query
required:false
schema:
type:string
format:bytes
pattern:"^0x[a-fA-F0-9]{64}$"
- name:slot
description:"Filter blocks by slot number. Only one block which has been finalized, or is believed to be the canonical block for that slot, is returned."
summary:"Retrieve the canonical block root, given a particular slot."
description:"Request that the beacon node return the root of the canonical beacon chain block, which matches the provided slot number."
parameters:
- name:slot
description:"Filter blocks by slot number. Only one block which has been finalized, or is believed to be the canonical block for that slot, is returned."
summary:'Retrieve blocks by root, slot, or epoch.'
description:"Request that the node return beacon chain blocks that match the provided criteria (a block root, beacon chain slot, or epoch). Only one of the parameters should be provided as a criteria."
parameters:
- name:root
description:"Filter by block root, returning a single block."
in:query
required:false
schema:
type:string
format:bytes
pattern:"^0x[a-fA-F0-9]{64}$"
- name:slot
description:"Filter blocks by slot number. It is possible that multiple blocks will be returned if the slot has not yet been finalized, or if the node has seen blocks from multiple forks."
#TODO: Is this description accurate?
in:query
required:false
schema:
type:integer
format:uint64
- name:epoch
description:"Filter blocks by epoch, returning all blocks found for the provided epoch. It is possible that multiple blocks will be returned with the same slot number if the slot has not yet been finalized, or if the node has seen blocks from multiple forks."
#TODO: Should this actually return no more than one block per slot, if it has been finalized? i.e. not blocks on multiple forks?
in:query
required:false
schema:
type:integer
format:uint64
responses:
200:
description:Success response.
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/BeaconBlock'
400:
$ref:'#/components/responses/InvalidRequest'
#TODO: Make this request error more specific if one of the parameters is not provided correctly.
summary:'Retrieve attestations by root, slot, or epoch.'
description:"Request that the node return all attestations which it has seen, that match the provided criteria (a block root, beacon chain slot, or epoch). Only one of the parameters should be provided as a criteria."
parameters:
- name:root
description:"Filter by block root, returning attestations associated with that block."
in:query
required:false
schema:
type:string
format:bytes
pattern:"^0x[a-fA-F0-9]{64}$"
- name:slot
description:"Filter attestations by slot number."
#TODO: Is this description accurate?
in:query
required:false
schema:
type:integer
format:uint64
- name:epoch
description:"Filter attestations by epoch number."
#TODO: Should this actually return no more than one block per slot, if it has been finalized? i.e. not blocks on multiple forks?
in:query
required:false
schema:
type:integer
format:uint64
responses:
200:
description:Success response.
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/Attestation'
400:
$ref:'#/components/responses/InvalidRequest'
#TODO: Make this request error more specific if one of the parameters is not provided correctly.
description:"Request that the node return all attestations which is currently holding in a pending state; i.e. is not associated with a finalized slot."
responses:
200:
description:Success response.
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/Attestation'
400:
$ref:'#/components/responses/InvalidRequest'
#TODO: Make this request error more specific if one of the parameters is not provided correctly.
summary:"Resolve a set of validator public keys to their validator indices."
description:"Attempt to resolve the public key of a set of validators to their corresponding ValidatorIndex values. Generally the mapping from validator public key to index should never change, however it is possible in some scenarios."
parameters:
- name:pubkeys
in:query
required:true
description:"An array of hex-encoded BLS public keys, for which the ValidatorIndex values should be returned."
summary:"Resolve a set of validator indicies to their public keys."
description:"Attempt to resolve the ValidatorIndex of a set of validators to their corresponding public keys. Generally the mapping from ValidatorIndex to public key should never change, however it is possible in some scenarios."
parameters:
- name:indices
in:query
required:true
description:"An array of ValidatorIndex values, for which the public keys should be returned."
schema:
type:array
items:
type:integer
format:uint64
description:"The ValidatorIndex values to be resolved."
summary:"Retrieve the balances of validators at a specified epoch."
description:"Retrieve the balances of validators at a specified epoch (or the current epoch if none specified). The list of balances can be filtered by providing a list of validator public keys or indices."
parameters:
- name:epoch
in:query
required:false
description:"The epoch at which the balances are to be measured."
schema:
type:integer
format:uint64
- name:validator_pubkeys
in:query
required:false
description:"An array of hex-encoded BLS public keys, for which the balances should be returned."
schema:
type:array
items:
$ref:'#/components/schemas/pubkey'
minItems:1
- name:validator_indices
in:query
required:false
description:"An array of ValidatorIndex values, for which the balances should be returned."
schema:
type:array
items:
$ref:'#/components/schemas/pubkey'
minItems:1
responses:
200:
description:Success response
content:
application/json:
schema:
type:object
properties:
epoch:
type:integer
format:uint64
description:"The epoch for which the returned active validator changes are provided."
balances:
type:array
items:
title:ValidatorBalances
type:object
properties:
pubkey:
$ref:'#/components/schemas/pubkey'
index:
type:integer
format:uint64
description:"The global ValidatorIndex of the validator."
balance:
type:integer
format:uint64
description:"The balance of the validator at the specified epoch, expressed in Gwei"
#TODO: Add the endpoints that enable a validator to join, exit, withdraw, etc.
/beacon/validator/duties:
get:
tags:
- Phase0
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. If no epoch parameter is provided, then the current epoch is assumed."
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
format:uint64
responses:
200:
description:Success response
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/ValidatorDuty'
400:
$ref:'#/components/responses/InvalidRequest'
500:
$ref:'#/components/responses/InternalError'
503:
$ref:'#/components/responses/CurrentlySyncing'
/beacon/validator/block:
get:
tags:
- Phase0
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."
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)"
description:"The `BeaconBlock` object, as sent from the beacon node originally, but now with the signature field completed. Must be sent in JSON format in the body of the request."
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 `Attestation`."
description:"Instructs the beacon node to broadcast a newly signed Attestation object to the intended shard subnet. The beacon node is not required to validate the signed Attestation, 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)"
requestBody:
description:"An `Attestation` structure, as originally provided by the beacon node, but now with the signature field completed. Must be sent in JSON format in the body of the request."
summary:"Get the full beacon state, at a particular slot or block root."
description:"Requests the beacon node to provide the full beacon state object, and the state root, given a particular slot number or block root. If no parameters are provided, the latest slot of the beacon node (the 'head' slot) is used."
parameters:
- name:root
description:"The block root at which the state should be provided."
in:query
required:false
schema:
type:string
format:bytes
pattern:"^0x[a-fA-F0-9]{64}$"
- name:slot
description:"The slot number at which the state should be provided."
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
connection_duration:
type:integer
format:uint64
description:"The number of seconds that an established network connection has persisted."
#TODO: Is it reasonable to store the connection duration? Do we have this information? Need to ask Age.
example:3600
multiaddr:
type:string
description:"The multiaddr address of a network peer."
nullable:true
#TODO Define an example and pattern for a multiaddr string.
description:"The epoch when the validator became or will become eligible for activation. This field may be zero if the validator was present in the Ethereum 2.0 genesis."
activation_epoch:
type:integer
format:uint64
description:"Epoch when the validator was or will be activated. This field may be zero if the validator was present in the Ethereum 2.0 genesis."
exit_epoch:
type:integer
format:uint64
nullable:true
description:"Epoch when the validator was exited, or null if the validator has not exited."
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."
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`."
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."
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."
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."
description:"The [`BeaconState`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconstate) object from the Eth2.0 spec."
properties:
genesis_time:
$ref:'#/components/schemas/genesis_time'
slot:
type:integer
format:uint64
description:"The latest slot, which the state represents."
fork:
$ref:'#/components/schemas/Fork'
latest_block_header:
$ref:'#/components/schemas/BeaconBlockHeader'
#TODO: Are these descriptions correct?
block_roots:
type:array
description:"The historical block roots."
minLength:8192
maxLength:8192#The SLOTS_PER_HISTORICAL_ROOT value from the Eth2.0 Spec.
items:
type:string
format:byte
pattern:"^0x[a-fA-F0-9]{64}$"
description:"A block root"
state_roots:
type:array
description:"The historical state roots."
minLength:8192
maxLength:8192#The SLOTS_PER_HISTORICAL_ROOT value from the Eth2.0 Spec.
items:
type:string
format:byte
pattern:"^0x[a-fA-F0-9]{64}$"
description:"A state root"
historical_roots:
type:array
#TODO: are these historical *state* roots?
description:"The historical state roots."
maxLength:16777216#The HISTORICAL_ROOTS_LIMIT value from the Eth2.0 Spec.
items:
type:string
format:byte
pattern:"^0x[a-fA-F0-9]{64}$"
description:"A state root"
eth1_data:
$ref:'#/components/schemas/Eth1Data'
eth1_data_votes:
type:array
description:"The validator votes for the Eth1Data."
maxLength:1024#The SLOTS_PER_ETH1_VOTING_PERIOD value from the Eth2.0 spec.
items:
$ref:'#/components/schemas/Eth1Data'
eth1_deposit_index:
type:integer
format:uint64
#TODO: Clarify this description
description:"The index of the Eth1 deposit."
validators:
type:array
description:"A list of the current validators."
maxLength:1099511627776
items:
$ref:'#/components/schemas/Validator'
balances:
type:array
description:"An array of the validator balances."
maxLength:1099511627776
items:
type:integer
format:uint64
description:"The validator balance in GWei."
start_shard:
$ref:'#/components/schemas/Shard'
randao_mixes:
type:array
description:"The hashes for the randao mix."
minLength:65536
maxLength:65536#The EPOCHS_PER_HISTORICAL_VECTOR value from the Eth2.0 spec.
items:
type:string
format:byte
pattern:"^0x[a-fA-F0-9]{64}$"
description:"A randao mix hash."
active_index_roots:
type:array
description:"Active index digests for light clients."
minLength:65536
maxLength:65536#The EPOCHS_PER_HISTORICAL_VECTOR value from the Eth2.0 spec.
items:
type:string
format:byte
pattern:"^0x[a-fA-F0-9]{64}$"
description:"Active index digest"
compact_committees_roots:
type:array
description:"Committee digests for light clients."
minLength:65536
maxLength:65536#The EPOCHS_PER_HISTORICAL_VECTOR value from the Eth2.0 spec.
items:
type:string
format:byte
pattern:"^0x[a-fA-F0-9]{64}$"
description:"Committee digest."
slashings:
type:array
description:"Per-epoch sums of slashed effective balances."
minLength:8192
maxLength:8192#The EPOCHS_PER_SLASHINGS_VECTOR value from the Eth2.0 spec.
items:
type:integer
format:uint64
description:"Sum of slashed balance for an epoch."
previous_epoch_attestations:
type:array
description:"A list of attestations in the previous epoch."
maxLength:8192# MAX_ATTESTATIONS * SLOTS_PER_EPOCH from the Eth2.0 spec.
items:
$ref:'#/components/schemas/PendingAttestation'
current_epoch_attestations:
type:array
description:"A list of attestations in the current epoch."
maxLength:8192# MAX_ATTESTATIONS * SLOTS_PER_EPOCH from the Eth2.0 spec.
items:
$ref:'#/components/schemas/PendingAttestation'
previous_crosslinks:
type:array
description:"The shard crosslinks from the previous epoch."
minLength:1024
maxLength:1024#The SHARD_COUNT value from the Eth2.0 spec
items:
$ref:'#/components/schemas/Crosslink'
current_crosslinks:
type:array
description:"The shard crosslinks for the current epoch."
minLength:1024
maxLength:1024#The SHARD_COUNT value from the Eth2.0 spec
items:
$ref:'#/components/schemas/Crosslink'
justification_bits:
type:array
description:"Bit set for every recent justified epoch."
minLength:4
maxLength:4#The JUSTIFICATION_BITS_LENGTH from the Eth2.0 spec.
items:
type:boolean
#TODO: Check this description
description:"Whethere the recent epochs have been finalized."
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."
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_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'
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."
description:"The [`PendingAttestation`](https://github.com/ethereum/eth2.0-specs/blob/v0.8.3/specs/core/0_beacon-chain.md#pendingattestation) object from the Eth2.0 spec."
properties:
aggregation_bits:
type:array
description:"The bits representing aggregation of validator signatures and attestations."
maxLength:4096#The MAX_VALIDATORS_PER_COMMITTEE value from the Eth2.0 spec.
items:
type:boolean
description:"Whether the validator has been aggregated or not"
data:
$ref:'#/components/schemas/AttestationData'
inclusion_delay:
type:integer
format:uint64
description:"The Slot at which it should be included."
proposer_index:
type:integer
format:uint64
#TODO: This is the block proposer index, not the attestaion right?
description:"The ValidatorIndex of the block proposer"
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."
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."
