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

@@ -84,10 +84,7 @@ paths:
           content:
             application/json:
               schema:
-                type: string
+                $ref: '#/components/schemas/ENR'
-                format: byte
-                example: "-IW4QHzEZbIB0YN47bVlsUrGbcL9vl21n7xF5gRKjMNkJ4MxfcwiqrsE7Ows8EnzOvC8P4ZyAjfOhr2ffk0bWAxDGq8BgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjzKzqo5c33ydUUHrWJ4FWwIXJa2MN9BBsgZkj6mhthp"
-                pattern: "^[^-A-Za-z0-9+/=]+$"
         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:
+      requestBody:
-        - name: beacon_block
+        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."
-          in: query
+        required: true
-          required: true
+        content:
-          description: "The `BeaconBlock` object, as sent from the beacon node originally, but now with the signature field completed."
+          application/json:
-          schema:
+            schema:
-            $ref: '#/components/schemas/BeaconBlock'
+              $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)"
+      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)"
-      parameters:
+      requestBody:
-        - name: attestation
+        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."
-          in: query
+        required: true
-          required: true
+        content:
-          description: "An `IndexedAttestation` structure, as originally provided by the beacon node, but now with the signature field completed."
+          application/json:
-          schema:
+            schema:
-            $ref: '#/components/schemas/IndexedAttestation'
+              $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
+  /beacon/state/genesis:
-  /spec:
+    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:
+              example: "# HELP beacon_head_state_active_validators_total Count of active validators at the head of the chain
-                summary: 'Promethius metrics'
-                value: "# 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:
+    Eth1Data:
-    type: object
+      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."
+      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:
+      properties:
-      deposit_root:
+        deposit_root:
-        type: string
+          type: string
-        format: byte
+          format: byte
-        pattern: "^0x[a-fA-F0-9]{64}$"
+          pattern: "^0x[a-fA-F0-9]{64}$"
-        description: "Root of the deposit tree."
+          description: "Root of the deposit tree."
-      deposit_count:
+        deposit_count:
-        type: integer
+          type: integer
-        format: uint64
+          format: uint64
-        description: "Total number of deposits."
+          description: "Total number of deposits."
-      block_hash:
+        block_hash:
-        type: string
+          type: string
-        format: byte
+          format: byte
-        pattern: "^0x[a-fA-F0-9]{64}$"
+          pattern: "^0x[a-fA-F0-9]{64}$"
-        description: "Ethereum 1.x block hash."
+          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."