616 lines
23 KiB
YAML
616 lines
23 KiB
YAML
openapi: "3.0.2"
|
|
info:
|
|
title: "Minimal Beacon Node API for Validator"
|
|
description: "A minimal API specification for the beacon node, which enables a validator to connect and perform its obligations on the Ethereum 2.0 phase 0 beacon chain."
|
|
version: "0.1.1"
|
|
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. Analagous 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. This API call should be polled at every slot, to ensure that any chain reorganisations are catered for, and to ensure that the currently connected beacon node is properly synchronized."
|
|
parameters:
|
|
- name: validator_pubkeys
|
|
in: query
|
|
required: true
|
|
description: "An array of hex-encoded BLS public keys"
|
|
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/ValidatorDuty'
|
|
400:
|
|
$ref: '#/components/responses/InvalidRequest'
|
|
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 publish a newly signed beacon block to the beacon network, to be included in the beacon chain."
|
|
parameters:
|
|
- name: beacon_block
|
|
in: query
|
|
required: true
|
|
description: "The `BeaconBlock` object, as sent from the beacon node originally, but now with the signature field completed."
|
|
schema:
|
|
$ref: '#/components/schemas/BeaconBlock'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
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: 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: "Published a signed attestation."
|
|
description: "Instructs the beacon node to publish a newly signed IndexedAttestation object, to be incorporated into the beacon chain."
|
|
parameters:
|
|
- name: attestation
|
|
in: query
|
|
required: true
|
|
description: "An `IndexedAttestation` structure, as originally provided by the beacon node, but now with the signature field completed."
|
|
schema:
|
|
$ref: '#/components/schemas/IndexedAttestation'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
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 time the Eth1.0 validator deposit smart contract has enough ETH staked (i.e. Eth2.0 begins)."
|
|
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
|
|
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_block:
|
|
type: integer
|
|
format: uint64
|
|
description: "The block at which syncing started (will only be reset after the sync reached its head)"
|
|
current_block:
|
|
type: integer
|
|
format: uint64
|
|
description: "The current highest block sync'd by the beacon node."
|
|
highest_block:
|
|
type: integer
|
|
format: uint64
|
|
description: "The estimated highest block, or current target block number."
|
|
|
|
BeaconBlock:
|
|
description: "The [`BeaconBlock`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) object from the Eth2.0 spec."
|
|
allOf:
|
|
- $ref: '#/components/schemas/BeaconBlockCommon'
|
|
- type: object
|
|
properties:
|
|
body:
|
|
$ref: '#/components/schemas/BeaconBlockBody'
|
|
BeaconBlockHeader:
|
|
description: "The [`BeaconBlockHeader`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblockheader) object from the Eth2.0 spec."
|
|
allOf:
|
|
- $ref: '#/components/schemas/BeaconBlockCommon'
|
|
- type: object
|
|
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/dev/specs/core/0_beacon-chain.md#beaconblockbody) object from the Eth2.0 spec."
|
|
properties:
|
|
randao_reveal:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{192}$"
|
|
description: "The RanDAO reveal value provided by the validator."
|
|
eth1_data:
|
|
title: Eth1Data
|
|
type: object
|
|
description: "The [`Eth1Data`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#eth1data) object from the Eth2.0 spec."
|
|
properties:
|
|
deposit_root:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{64}$"
|
|
description: "Root of the deposit tree."
|
|
deposit_count:
|
|
type: integer
|
|
format: uint64
|
|
description: "Total number of deposits."
|
|
block_hash:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{64}$"
|
|
description: "Ethereum 1.x block hash."
|
|
graffiti:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{64}$"
|
|
proposer_slashings:
|
|
type: array
|
|
items:
|
|
title: ProposerSlashings
|
|
type: object
|
|
description: "The [`ProposerSlashing`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#proposerslashing) object from the Eth2.0 spec."
|
|
properties:
|
|
proposer_index:
|
|
type: integer
|
|
format: uint64
|
|
description: "The index of the proposer to be slashed."
|
|
header_1:
|
|
$ref: '#/components/schemas/BeaconBlockHeader'
|
|
header_2:
|
|
$ref: '#/components/schemas/BeaconBlockHeader'
|
|
attester_slashings:
|
|
type: array
|
|
items:
|
|
title: AttesterSlashings
|
|
type: object
|
|
description: "The [`AttesterSlashing`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attesterslashing) object from the Eth2.0 spec."
|
|
properties:
|
|
attestation_1:
|
|
$ref: '#/components/schemas/IndexedAttestation'
|
|
attestation_2:
|
|
$ref: '#/components/schemas/IndexedAttestation'
|
|
attestations:
|
|
type: array
|
|
items:
|
|
title: Attestation
|
|
type: object
|
|
description: "The [`Attestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestation) object from the Eth2.0 spec."
|
|
properties:
|
|
aggregation_bitfield:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]+$"
|
|
description: "Attester aggregation bitfield."
|
|
custody_bitfield:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]+$"
|
|
description: "Custody bitfield."
|
|
signature:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{192}$"
|
|
description: "BLS aggregate signature."
|
|
data:
|
|
$ref: '#/components/schemas/AttestationData'
|
|
deposits:
|
|
type: array
|
|
items:
|
|
title: Deposit
|
|
type: object
|
|
description: "The [`Deposit`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#deposit) object from the Eth2.0 spec."
|
|
properties:
|
|
proof:
|
|
type: array
|
|
description: "Branch in the deposit tree."
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{64}$"
|
|
- type: integer
|
|
format: uint64
|
|
enum: [32]
|
|
example: 32
|
|
description: "The DEPOSIT_CONTRACT_TREE_DEPTH value."
|
|
minItems: 2
|
|
maxItems: 2
|
|
index:
|
|
type: integer
|
|
format: uint64
|
|
description: "Index in the deposit tree."
|
|
data:
|
|
title: DepositData
|
|
type: object
|
|
description: "The [`DepositData`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#depositdata) object from the Eth2.0 spec."
|
|
properties:
|
|
pubkey:
|
|
$ref: '#/components/schemas/pubkey'
|
|
withdrawal_credentials:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{64}$"
|
|
description: "The withdrawal credentials."
|
|
amount:
|
|
type: integer
|
|
format: uint64
|
|
description: "Amount in Gwei."
|
|
signature:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{192}$"
|
|
description: "Container self-signature."
|
|
voluntary_exits:
|
|
type: array
|
|
items:
|
|
title: VoluntaryExit
|
|
type: object
|
|
description: "The [`VoluntaryExit`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#voluntaryexit) object from the Eth2.0 spec."
|
|
properties:
|
|
epoch:
|
|
type: integer
|
|
format: uint64
|
|
description: "Minimum epoch for processing exit."
|
|
validator_index:
|
|
type: integer
|
|
format: uint64
|
|
description: "Index of the exiting validator."
|
|
signature:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{192}$"
|
|
description: "Validator signature."
|
|
transfers:
|
|
type: array
|
|
items:
|
|
title: Transfer
|
|
type: object
|
|
description: "The [`Transfer`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#transfer) object from the Eth2.0 spec."
|
|
properties:
|
|
sender:
|
|
type: integer
|
|
format: uint64
|
|
description: "Sender index."
|
|
recipient:
|
|
type: integer
|
|
format: uint64
|
|
description: "Recipient index."
|
|
amount:
|
|
type: integer
|
|
format: uint64
|
|
description: "Amount in Gwei."
|
|
fee:
|
|
type: integer
|
|
format: uint64
|
|
description: "Fee in Gwei for block producer."
|
|
slot:
|
|
type: integer
|
|
format: uint64
|
|
description: "Inclusion slot."
|
|
pubkey:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{96}$"
|
|
description: "Sender withdrawal public key."
|
|
signature:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{192}$"
|
|
description: "Sender signature."
|
|
|
|
Fork:
|
|
type: object
|
|
description: "The [`Fork`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#Fork) object from the Eth2.0 spec."
|
|
properties:
|
|
previous_version:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{8}$"
|
|
description: "Previous fork version."
|
|
current_version:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{8}$"
|
|
description: "Current fork version."
|
|
epoch:
|
|
type: integer
|
|
format: uint64
|
|
description: "Fork epoch number."
|
|
IndexedAttestation:
|
|
type: object
|
|
description: "The [`IndexedAttestation`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#indexedattestation) 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
|
|
data:
|
|
$ref: '#/components/schemas/AttestationData'
|
|
AttestationData:
|
|
type: object
|
|
description: "The [`AttestationData`](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#attestationdata) object from the Eth2.0 spec."
|
|
properties:
|
|
beacon_block_root:
|
|
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/dev/specs/core/0_beacon-chain.md#crosslink) object from the Eth2.0 spec."
|
|
properties:
|
|
shard:
|
|
type: integer
|
|
format: uint64
|
|
description: "The shard number."
|
|
epoch:
|
|
type: integer
|
|
format: uint64
|
|
description: "The epoch number."
|
|
parent_root:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{64}$"
|
|
description: "Root of the previous crosslink."
|
|
data_root:
|
|
type: string
|
|
format: byte
|
|
pattern: "^0x[a-fA-F0-9]{64}$"
|
|
description: "Root of the crosslinked shard data since the previous crosslink."
|
|
|
|
responses:
|
|
Success:
|
|
description: "Request successful."
|
|
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."
|