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

Updated the API spec.

Browse Source 
- Moved ENR into it's own object
 - Moved the POST request parameters into the requestBody attribute (instead of query)
 - Updated IndexedAttestation to Attestation
 - Updated path for current_finalized_checkpoint
 - Completed the /spec and /spec and /spec/slots_per_epoch endpoints
 - Completed the /beacon/state/genesis endpoint
 - Completed the /spec/eth2_config endpoint
 - Fixed the prometheus example value
 - Added various example values to reflect real world values
 - Fixed incorrect indenting of Eth1Data
 - Added the whole ChainSpec schema
This commit is contained in:
Luke Anderson 2019-09-05 00:39:54 +10:00
parent 32ca8e951d
commit 4339e372c7
No known key found for this signature in database
GPG Key ID: 44408169EC61E228
1 changed files with 281 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

333
docs/api_spec.yaml
View File

@ -84,10 +84,7 @@ paths:
content:
application/json:
schema:
type: string
format: byte
example: "-IW4QHzEZbIB0YN47bVlsUrGbcL9vl21n7xF5gRKjMNkJ4MxfcwiqrsE7Ows8EnzOvC8P4ZyAjfOhr2ffk0bWAxDGq8BgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjzKzqo5c33ydUUHrWJ4FWwIXJa2MN9BBsgZkj6mhthp"
pattern: "^[^-A-Za-z0-9+/=]+$"
$ref: '#/components/schemas/ENR'
500:
$ref: '#/components/responses/InternalError'
@ -884,13 +881,13 @@ paths:
- 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'
requestBody:
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."
required: true
content:
application/json:
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."
@ -908,7 +905,7 @@ paths:
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."
description: "Requests that the beacon node produce an Attestation, with a blank signature field, which the validator will then sign."
parameters:
- name: validator_pubkey
in: query
@ -919,7 +916,7 @@ paths:
- 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`."
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`."
schema:
type: integer
format: uint32
@ -943,7 +940,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/IndexedAttestation'
$ref: '#/components/schemas/Attestation'
400:
$ref: '#/components/responses/InvalidRequest'
500:
@ -954,14 +951,14 @@ paths:
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'
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."
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Attestation'
responses:
200:
description: "The attestation was validated successfully and has been broadcast. It has also been integrated into the beacon node's database."
@ -1042,13 +1039,12 @@ paths:
format: bytes
pattern: "^0x[a-fA-F0-9]{64}$"
description: "The state root"
400:
$ref: '#/components/responses/InvalidRequest'
500:
$ref: '#/components/responses/InternalError'
/beacon/current_finalized_checkpoint:
/beacon/state/current_finalized_checkpoint:
get:
tags:
- Phase0
@ -1062,16 +1058,63 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/Checkpoint'
500:
$ref: '#/components/responses/InternalError'
#TODO fill spec
/spec:
/beacon/state/genesis:
get:
tags:
- Phase0
summary: "Get the full beacon state, as it was at genesis."
description: "Requests the beacon node to provide the full beacon state object and the state root, as it was for the genesis block."
responses:
200:
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/BeaconState'
application/yaml:
schema:
$ref: '#/components/schemas/BeaconState'
400:
$ref: '#/components/responses/InvalidRequest'
500:
$ref: '#/components/responses/InternalError'
/spec:
get:
tags:
- Phase0
summary: "Get the current ChainSpec configuration."
description: "Requests the beacon node to provide the configuration that it has used to start the beacon chain."
responses:
200:
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ChainSpec'
500:
$ref: '#/components/responses/InternalError'
#TODO fill spec/slots_per_epoch
/spec/slots_per_epoch:
get:
tags:
- Phase0
summary: "Get the configured number of slots per epoch."
description: "The number of slots in each epoch is part of the Eth2.0 spec. This function simply returns an integer representing this value."
responses:
200:
description: Success response
content:
application/json:
schema:
type: integer
format: uint64
example: 64
500:
$ref: '#/components/responses/InternalError'
/spec/deposit_contract:
get:
@ -1089,6 +1132,28 @@ paths:
500:
$ref: '#/components/responses/InternalError'
/spec/eth2_config:
get:
tags:
- Phase0
summary: "Gets the Eth2.0 spec, including the identifying string."
description: ""
responses:
200:
description: Success response
content:
application/json:
schema:
type: object
properties:
spec_constants:
type: string
example: "mainnet"
spec:
$ref: '#/components/schemas/ChainSpec'
500:
$ref: '#/components/responses/InternalError'
/metrics:
get:
tags:
@ -1100,9 +1165,7 @@ paths:
description: Request successful
content:
text/plain:
example:
summary: 'Promethius metrics'
value: "# HELP beacon_head_state_active_validators_total Count of active validators at the head of the chain
example: "# HELP beacon_head_state_active_validators_total Count of active validators at the head of the chain
# TYPE beacon_head_state_active_validators_total gauge
beacon_head_state_active_validators_total 16
# HELP beacon_head_state_current_justified_epoch Current justified epoch at the head of the chain
@ -1178,6 +1241,12 @@ components:
pattern: "^0x[a-fA-F0-9]{64}$"
description: "A hex encoded ethereum address."
ENR:
type: string
format: byte
example: "-IW4QHzEZbIB0YN47bVlsUrGbcL9vl21n7xF5gRKjMNkJ4MxfcwiqrsE7Ows8EnzOvC8P4ZyAjfOhr2ffk0bWAxDGq8BgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjzKzqo5c33ydUUHrWJ4FWwIXJa2MN9BBsgZkj6mhthp"
pattern: "^[^-A-Za-z0-9+/=]+$"
Shard:
type: integer
format: uint64
@ -1239,13 +1308,16 @@ 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."
example: "0x00ec7ef7780c9d151597924036262dd28dc60e1228f4da6fecf9d402cb3f3594"
effective_balance:
type: integer
format: uint64
description: "The effective balance of the validator, measured in Gwei."
example: 32000000000
slashed:
type: boolean
description: "Whether the validator has or has not been slashed."
example: false
activation_eligiblity_epoch:
type: integer
format: uint64
@ -1259,11 +1331,13 @@ components:
format: uint64
nullable: true
description: "Epoch when the validator was exited, or null if the validator has not exited."
example: 18446744073709551615
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."
example: 18446744073709551615
ValidatorDuty:
type: object
@ -1301,24 +1375,24 @@ 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."
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."
@ -1404,9 +1478,9 @@ components:
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'
$ref: '#/components/schemas/Attestation'
attestation_2:
$ref: '#/components/schemas/IndexedAttestation'
$ref: '#/components/schemas/Attestation'
attestations:
type: array
items:
@ -1818,6 +1892,161 @@ components:
pattern: "^0x[a-fA-F0-9]{64}$"
description: "Root of the crosslinked shard data since the previous crosslink."
ChainSpec:
type: object
description: "Stores all of the values which specify a particular chain. The `ChainSpec` object in Lighthouse"
properties:
far_future_epoch:
type: integer
format: uint64
example: 18446744073709551615
base_rewards_per_epoch:
type: integer
format: uint64
example: 5
deposit_contract_tree_depth:
type: integer
format: uint64
example: 32
seconds_per_day:
type: integer
format: uint64
example: 86400
target_committee_size:
type: integer
format: uint64
example: 128
min_per_epoch_churn_limit:
type: integer
format: uint64
example: 4
churn_limit_quotient:
type: integer
format: uint64
example: 65536
shuffle_round_count:
type: integer
format: uint8
example: 90
min_genesis_active_validator_count:
type: integer
format: uint64
example: 65536
min_genesis_time:
type: integer
format: uint64
example: 1578009600
min_deposit_amount:
type: integer
format: uint64
example: 1000000000
max_effective_balance:
type: integer
format: uint64
example: 32000000000
ejection_balance:
type: integer
format: uint64
example: 16000000000
effective_balance_increment:
type: integer
format: uint64
example: 1000000000
genesis_slot:
type: integer
format: uint64
example: 0
bls_withdrawal_prefix_byte:
type: string
format: byte
pattern: "^0x[a-fA-F0-9]{2}$"
example: "0x00"
milliseconds_per_slot:
type: integer
format: uint64
example: 6000
min_attestation_inclusion_delay:
type: integer
format: uint64
example: 1
min_seed_lookahead:
type: integer
format: uint64
example: 1
activation_exit_delay:
type: integer
format: uint64
example: 4
min_validator_withdrawability_delay:
type: integer
format: uint64
example: 256
persistent_committee_period:
type: integer
format: uint64
example: 2048
max_epochs_per_crosslink:
type: integer
format: uint64
example: 64
min_epochs_to_inactivity_penalty:
type: integer
format: uint64
example: 4
base_reward_factor:
type: integer
format: uint64
example: 64
whistleblower_reward_quotient:
type: integer
format: uint64
example: 512
proposer_reward_quotient:
type: integer
format: uint64
example: 8
inactivity_penalty_quotient:
type: integer
format: uint64
example: 33554432
min_slashing_penalty_quotient:
type: integer
format: uint64
example: 32
domain_beacon_proposer:
type: integer
format: uint32
example: 0
domain_randao:
type: integer
format: uint32
example: 1
domain_attestation:
type: integer
format: uint32
example: 2
domain_deposit:
type: integer
format: uint32
example: 3
domain_voluntary_exit:
type: integer
format: uint32
example: 4
domain_transfer:
type: integer
format: uint32
example: 5
boot_nodes:
type: array
items:
$ref: '#/components/schemas/ENR'
network_id:
type: integer
format: uint8
example: 2
responses:
Success:
description: "Request successful."