eth2.0-specs/specs/validator/beacon_node_oapi.yaml

openapi: "3.0.2"
info:
  title: "Beacon Node API for Validator"
  description: "A beacon node API for enabling a validator to perform its obligations on the Ethereum 2.0 phase 0 beacon chain."
  version: "0.1"
paths:
  /node/version:
    get:
      summary: "Get version string of the running beacon node."
      description: "Requests that the BeaconNode 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/client_version'
        500:
          $ref: '#/components/responses/InternalError' 
  
  /node/genesis_time:
    get:
      summary: "Get the genesis_time parameter from beacon node configuration."
      description: "Requests the genesis_time parameter from the BeaconNode, which should be consistent across all BeaconNodes 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:
      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'
                
                
  /validator/duties:
    get:
      summary: "Get validator duties for the requested validators."
      description: "Requests the BeaconNode to provide a set of _duties_, which are actions that should be performed by ValidatorClients. 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 BeaconNode is properly synchronised."
      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:
      summary: "Produce a new block, without signature."
      description: "Requests a BeaconNode to produce a valid block, which can then be signed by a ValidatorClient."
      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 ValidatorClient'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:
      summary: "Publish a signed block"
      description: "Instructs the BeaconNode 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 BeaconNode 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:
      summary: "Produce an attestation, without signature."
      description: "Requests that the BeaconNode produce an IndexedAttestation, with a blank signature field, which the ValidatorClient 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:
      summary: "Published a signed attestation."
      description: "Instructs the BeaconNode 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 BeaconNode, 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:
    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_production_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:
      type: object
      description: "The [BeaconBlock](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#beaconblock) from the Eth2.0 spec."
    Fork:
      type: object
      description: "The [Fork](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#Fork) 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) from the Eth2.0 spec."
      properties:
        custody_bit_0_indicies:
          type: array
          description: "Validator indicies for 0 bits."
          items:
            type: integer
            format: uint64
        custody_bit_1_indicies:
          type: array
          description: "Validator indicies 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) from the Eth2.0 spec."
      properties:
        beacon_block_root:
          $ref: '#/components/schemas/merkle_root'
        source_epoch:
          type: integer
          format: uint64
          description: "Source epoch from FFG vote"
        source_root:
          $ref: '#/components/schemas/merkle_root'
        target_epoch:
          type: integer
          format: uint64
          description: "Target epoch from FFG vote"
        target_root:
          $ref: '#/components/schemas/merkle_root'
        crosslink:
          $ref: '#/components/schemas/CrossLink'
    CrossLink:
      type: object
      description: "The [Crosslink](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/core/0_beacon-chain.md#crosslink) 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:
          $ref: '#/components/schemas/merkle_root'
        data_root:
          $ref: '#/components/schemas/merkle_root'
          
    pubkey:
      type: string
      format: byte
      pattern: "^0x[a-fA-F0-9]{96}$"
      description: "The validator's BLS public key, uniquely identifying them."
    client_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)."
    merkle_root:
      type: string
      format: byte
      pattern: "^0x[a-fA-F0-9]{64}$"
      description: "A 32 byte merkle root, used in all kinds of scenarios."
      
  
  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