openapi: "3.0.2" info: title: "Lighthouse REST API" description: "" version: "0.1.0" license: name: "Apache 2.0" url: "https://www.apache.org/licenses/LICENSE-2.0.html" tags: - name: Phase0 description: Endpoints which will be implemented for phase 0 of Ethereum Serenity - name: Phase1 description: Endpoints which will be implemented for phase 1 of Ethereum Serenity - name: Future description: Potential future endpoints or optional nice-to-haves paths: /node/version: get: tags: - Phase0 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/deposit_contract: get: tags: - Phase0 summary: "Get the address of the Ethereum 1 deposit contract." description: "Requests the address of the deposit contract on the Ethereum 1 chain, which was used to start the current beacon chain." responses: 200: description: Request successful content: application/json: schema: $ref: '#/components/schemas/ethereum_address' 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." sync_status: $ref: '#/components/schemas/SyncingStatus' 500: $ref: '#/components/responses/InternalError' /node/fork: get: tags: - Phase0 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' /node/stats: get: tags: - Future summary: "Get operational information about the node." description: "Fetches some operational information about the node's process, such as memory usage, database size, etc." responses: 200: description: Request successful content: application/json: schema: type: object properties: memory_usage: type: integer format: uint64 description: "The amount of memory used by the currently running beacon node process, expressed in bytes." uptime: type: integer format: uint64 description: "The number of seconds that have elapsed since beacon node process was started." #TODO: what other useful process information could be expressed here? /node/network/peer_count: get: tags: - Phase0 summary: "The number of established peers" description: "Requests the beacon node to identify the number of peers with which an established connection is currently maintained." responses: 200: description: Request successful content: application/json: schema: type: integer format: uint64 example: 25 /node/network/peers: get: tags: - Phase0 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." responses: 200: description: Request successful content: application/json: schema: type: array items: $ref: '#/components/schemas/Peer' /node/network/listening: get: tags: - Phase0 summary: "Identify if the beacon node is listening for networking connections, and on what address." description: "Requests that the beacon node identify whether it is listening for incoming networking connections, and if so, what network address(es) are being used." responses: 200: description: Request successful content: application/json: schema: type: object properties: listening: type: boolean nullable: false description: "True if the node is listening for incoming network connections. False if networking has been disabled or if the node has been configured to only connect with a static set of peers." listen_address: $ref: '#/components/schemas/multiaddr' /node/network/stats: get: tags: - Future summary: "Get some simple network statistics from the node." description: "Request that the beacon node provide some historical summary information about its networking interface." #TODO: Do we actually collect these stats? Should we? responses: 200: description: Request successful content: application/json: schema: type: object properties: bytes_sent: type: integer format: uint64 description: "The total number of bytes sent by the beacon node since it was started." bytes_received: type: integer format: uint64 description: "The total number of bytes sent by the beacon node since it was started." peers_seen: type: integer format: uint64 description: "The total number of unique peers (by multiaddr) that have been discovered since the beacon node instance was started." #TODO: This might be too difficult to collect /node/network/block_discovery: get: tags: - Future summary: "Identify the time at which particular blocks were first seen." description: "Request the node to provide the time at which particular blocks were first seen on the network." parameters: - name: block_roots description: "Provide an array of block roots for which the discovered time is to be returned." in: query required: false schema: type: array items: type: string format: bytes pattern: "^0x[a-fA-F0-9]{64}$" responses: 200: description: Success response content: application/json: schema: type: array items: type: object properties: root: type: string format: bytes description: "The merkle root of the block." pattern: "^0x[a-fA-F0-9]{64}$" discovered_time: type: integer format: uint64 description: "UNIX time in milliseconds that the block was first discovered, either from a network peer or the validator client." #TODO: Add the endpoints that enable a validator to join, exit, withdraw, etc. /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' 406: description: "Duties cannot be provided for the requested epoch." 500: $ref: '#/components/responses/InternalError' 503: $ref: '#/components/responses/CurrentlySyncing' /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." 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: - Phase0 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: - Phase0 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: - Phase0 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' /chain/beacon/blocks: get: tags: - Phase0 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. /chain/beacon/chainhead: get: tags: - Phase0 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." responses: 200: description: Success response content: application/json: schema: type: object description: "The latest information about the head of the beacon chain." properties: block_root: type: string format: bytes pattern: "^0x[a-fA-F0-9]{64}$" description: "The merkle tree root of the canonical head block in the beacon node." block_slot: type: integer format: uint64 description: "The slot of the head block." finalized_slot: type: integer format: uint64 description: "The slot number of the most recent finalized slot." finalized_block_root: type: string format: bytes pattern: "^0x[a-fA-F0-9]{64}$" description: "The block root for the most recent finalized block." justified_slot: type: integer format: uint64 description: "The slot number of the most recent justified slot." justified_block_root: type: string format: bytes pattern: "^0x[a-fA-F0-9]{64}$" description: "The block root of the most recent justified block." previous_justified_slot: type: integer format: uint64 description: "The slot number of the second most recent justified slot." previous_justified_block_root: type: integer format: bytes pattern: "^0x[a-fA-F0-9]{64}$" description: "The block root of the second most recent justified block." /chain/beacon/attestations: get: tags: - Phase0 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. /chain/beacon/attestations/pending: get: tags: - Phase0 summary: 'Retrieve all pending attestations.' 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. /chain/beacon/validators: get: tags: - Phase0 summary: "List the set of active validators for an epoch." description: "Request the beacon node to list the active validators for the specified epoch, or the current epoch if none is specified." parameters: - name: epoch description: "The epoch for which the list of validators should be returned." in: query required: false schema: type: integer format: uint64 responses: 200: description: Success response content: application/json: schema: type: object properties: epoch: type: integer format: uint64 description: "The epoch in which the list of validators are active." validators: type: array items: $ref: '#/components/schemas/ValidatorInfo' /chain/beacon/validators/activesetchanges: get: tags: - Phase0 summary: "Retrieve the changes in active validator set." description: "Request that the beacon node describe the changes that occurred at the specified epoch, as compared with the prior epoch." parameters: - name: epoch description: "The epoch for which the validator change comparison should be made. The current epoch is used if this value is omitted." in: query required: false schema: type: integer format: uint64 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." activated_public_keys: type: array description: "The list of validator public keys which were activated in the epoch." items: $ref: '#/components/schemas/pubkey' exited_public_keys: type: array description: "The list of validator public keys which exited in the epoch." items: $ref: '#/components/schemas/pubkey' ejected_public_keys: type: array description: "The list of validator public keys which were ejected in the epoch." items: $ref: '#/components/schemas/pubkey' /chain/beacon/validators/assignments: get: tags: - Phase0 summary: "Retrieve the assigned responsibilities for validators in a particular epoch." description: "Request that the beacon node list the duties which have been assigned to the active validator set in a particular epoch." parameters: - name: epoch description: "The epoch for which the validator assignments should be made. The current epoch is used if this value is omitted." in: query required: false schema: type: integer format: uint64 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." duties: type: array items: $ref: '#/components/schemas/ValidatorDuty' #TODO: This does not include the crosslink committee value, which must be included for Phase1? /chain/beacon/validators/indices: get: tags: - Phase0 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." schema: type: array items: $ref: '#/components/schemas/pubkey' minItems: 1 responses: 200: description: Success response content: application/json: schema: type: array items: $ref: '#/components/schemas/ValidatorIndexMapping' /chain/beacon/validators/pubkeys: get: tags: - Phase0 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." minItems: 1 responses: 200: description: Success response content: application/json: schema: type: array items: $ref: '#/components/schemas/ValidatorIndexMapping' /chain/beacon/validators/balances: get: tags: - Phase0 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" /chain/beacon/validators/participation: get: tags: - Phase0 summary: "Retrieve aggregate information about validator participation in an epoch." description: "Retrieve some aggregate information about the participation of validators in a specified epoch (or the current epoch if none specified)." parameters: - name: epoch in: query required: false description: "The epoch at which the participation is to be measured." schema: type: integer format: uint64 responses: 200: description: Success response content: application/json: schema: type: object properties: epoch: type: string format: uint64 description: "The epoch for which the participation information is provided." finalized: type: boolean format: boolean description: "Whether the epoch has been finalized or not." global_participation_rate: type: number format: float description: "The percentage of validator participation in the given epoch." minimum: 0.0 maximum: 1.0 voted_ether: type: integer format: uint64 description: "The total amount of ether, expressed in Gwei, that has been used in voting for the specified epoch." eligible_ether: type: integer format: uint64 description: "The total amount of ether, expressed in Gwei, that is eligible for voting in the specified epoch." /chain/beacon/validators/queue: get: tags: - Phase0 summary: "Retrieve information about the validator queue at the specified epoch." description: "Retrieve information about the queue of validators for the specified epoch (or the current epoch if none specified)." parameters: - name: epoch in: query required: false description: "The epoch at which the validator queue is to be measured." schema: type: integer format: uint64 responses: 200: description: Success response content: application/json: schema: type: object properties: epoch: type: string format: uint64 description: "The epoch for which the validator queue information is provided." churn_limit: type: integer format: uint64 description: "The validator churn limit for the specified epoch." activation_public_keys: type: array description: "The public keys of validators which are queued for activation." items: $ref: "#/components/schemas/pubkey" exit_public_keys: type: array description: "The public keys of validators which are queued for exiting." items: $ref: '#/components/schemas/pubkey' 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 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. ethereum_address: type: string format: byte pattern: "^0x[a-fA-F0-9]{64}$" description: "A hex encoded ethereum address." Peer: type: object properties: connection_status: $ref: '#/components/schemas/ConnectionStatus' connection_duration: $ref: '#/components/schemas/connection_duration' multiaddr: $ref: '#/components/schemas/multiaddr' measured_delay: type: integer format: uint64 description: "The round trip network delay to the peer, measured in milliseconds" #TODO: Do we have the RTT information? ConnectionStatus: type: string #TODO: Define the ENUM and possible connection states ValidatorIndexMapping: type: object properties: pubkey: $ref: '#/components/schemas/pubkey' index: type: integer format: uint64 description: "The global ValidatorIndex value." ValidatorInfo: type: object properties: public_key: $ref: '#/components/schemas/pubkey' withdrawal_credentials: type: string format: bytes pattern: "^0x[a-fA-F0-9]{64}$" description: "The 32 byte hash of the public key which the validator uses for withdrawing their rewards." activation_eligiblity_epoch: type: integer format: uint64 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." withdrawable_epoch: type: integer format: uint64 nullable: true description: "Epoch when the validator is eligible to withdraw their funds, or null if the validator has not exited." slashed: type: boolean description: "Whether the validator has or has not been slashed." effective_balance: type: integer format: uint64 description: "The effective balance of the validator, measured in Gwei." 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 synchronised 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: $ref: '#/components/schemas/Attestation' 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." 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." 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." #TODO: Make response descriptions consistent 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." externalDocs: description: Ethereum 2.0 Specification on Github url: 'https://github.com/ethereum/eth2.0-specs' #TODO: Define the components of the WebSockets API