From 4339e372c7f859ac3d0135d8caaa9e73899f7ded Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Thu, 5 Sep 2019 00:39:54 +1000 Subject: [PATCH] Updated the API spec. - 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 --- docs/api_spec.yaml | 333 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 281 insertions(+), 52 deletions(-) diff --git a/docs/api_spec.yaml b/docs/api_spec.yaml index 2356d1f66..ced07e96d 100644 --- a/docs/api_spec.yaml +++ b/docs/api_spec.yaml @@ -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."