cerc-io/lighthouse
16
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Updating the spec to align with what's implemented.

Browse Source 
- Filled the OpenAPI spec for some major functions:
  - /beacon/state
  - /beacon/get_finalized_checkpoint
  - /beacon/state_root
 - Created some new schemas in the spec, such as Shard, Checkpoint, Validator, Eth1Data, BeaconState, PendingAttestation, Crosslink
This commit is contained in:
Luke Anderson 2019-09-03 20:13:26 +10:00
parent c13f27e245
commit 777987a49e
No known key found for this signature in database
GPG Key ID: 44408169EC61E228
1 changed files with 311 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

320
docs/api_spec.yaml
View File

@ -527,7 +527,7 @@ paths:
validators:
type: array
items:
$ref: '#/components/schemas/ValidatorInfo'
$ref: '#/components/schemas/Validator'
/beacon/validators/activesetchanges:
get:
@ -974,7 +974,6 @@ paths:
503:
$ref: '#/components/responses/CurrentlySyncing'
#TODO fill out /beacon/state
/beacon/state:
get:
tags:
@ -1010,18 +1009,63 @@ paths:
format: bytes
pattern: "^0x[a-fA-F0-9]{64}$"
beacon_state:
#TODO: Need to add BeaconState Schema
$ref: '#/components/schemas/BeaconState'
400:
$ref: '#/components/responses/InvalidRequest'
500:
$ref: '#/components/responses/InternalError'
#TODO fill out /beacon/state_root
/beacon/state_root:
get:
tags:
- Phase0
summary: "Get the beacon state root, at a particular slot."
description: "Requests the beacon node to provide the root of the beacon state object, given a particular slot number."
parameters:
- name: slot
description: "The slot number at which the state should be provided."
in: query
required: true
schema:
type: integer
format: uint64
responses:
200:
description: Success response
content:
application/json:
schema:
type: object
properties:
root:
type: string
format: bytes
pattern: "^0x[a-fA-F0-9]{64}$"
description: "The state root"
400:
$ref: '#/components/responses/InvalidRequest'
500:
$ref: '#/components/responses/InternalError'
#TODO fill out current_finalized_checkpoint
/beacon/current_finalized_checkpoint:
get:
tags:
- Phase0
summary: "Get the current finalized checkpoint."
#TODO: is this description correct?
description: "Requests the beacon node to provide the checkpoint for the current finalized epoch."
responses:
200:
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/Checkpoint'
500:
$ref: '#/components/responses/InternalError'
#TODO fill spec
/spec:
@ -1134,6 +1178,28 @@ components:
pattern: "^0x[a-fA-F0-9]{64}$"
description: "A hex encoded ethereum address."
Shard:
type: integer
format: uint64
description: "A shard number."
example: 5
maximum: 1023
minimum: 0
Checkpoint:
type: object
description: "A checkpoint."
properties:
epoch:
type: integer
format: uint64
description: "The epoch to which the checkpoint applies."
root:
type: string
format: byte
pattern: "^0x[a-fA-F0-9]{64}$"
description: "A block root, which is being checkpointed."
Peer:
type: object
properties:
@ -1163,7 +1229,7 @@ components:
format: uint64
description: "The global ValidatorIndex value."
ValidatorInfo:
Validator:
type: object
properties:
public_key:
@ -1173,6 +1239,13 @@ components:
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."
effective_balance:
type: integer
format: uint64
description: "The effective balance of the validator, measured in Gwei."
slashed:
type: boolean
description: "Whether the validator has or has not been slashed."
activation_eligiblity_epoch:
type: integer
format: uint64
@ -1191,13 +1264,6 @@ components:
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
@ -1235,6 +1301,25 @@ components:
format: uint64
description: "Globally, the estimated most recent slot number, or current target slot number."
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."
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:
@ -1291,24 +1376,7 @@ components:
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."
$ref: '#/components/schemas/Eth1Data'
graffiti:
type: string
format: byte
@ -1442,6 +1510,161 @@ components:
pattern: "^0x[a-fA-F0-9]{192}$"
description: "Sender signature."
BeaconState:
type: object
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."
previous_justified_checkpoint:
$ref: '#/components/schemas/Checkpoint'
current_justified_checkpoint:
$ref: '#/components/schemas/Checkpoint'
finalized_checkpoint:
$ref: '#/components/schemas/Checkpoint'
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."
@ -1508,6 +1731,35 @@ components:
data:
$ref: '#/components/schemas/AttestationData'
PendingAttestation:
type: object
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"
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."
@ -1536,7 +1788,10 @@ components:
pattern: "^0x[a-fA-F0-9]{64}$"
description: "Target root from FFG vote."
crosslink:
title: CrossLink
$ref: '#/components/schemas/Crosslink'
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:
@ -1563,7 +1818,6 @@ components:
pattern: "^0x[a-fA-F0-9]{64}$"
description: "Root of the crosslinked shard data since the previous crosslink."
responses:
Success:
description: "Request successful."