eth2_emulator.yaml

openapi: 3.0.0
info:
  title: eth2_emulator
  version: '0.1.0'
  description: |-
    API specification for the Eth2 Emulator of Mousse
    Designed for rollups

    Ref: [Phase 0 Beacon Node API](https://ethereum.github.io/eth2.0-APIs/)
  contact:
    name: Naoya Okanami
    email: minaminaoy@gmail.com
    url: 'https://twitter.com/vinami'
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
servers:
  - url: 'http://localhost:3030'
    description: ''
paths:
  '/shards/{shard}/bid':
    parameters:
      - schema:
          type: integer
        name: shard
        in: path
        required: true
        description: Shard number
    post:
      summary: Publish Bid
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-shards-bid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bid'
            examples: {}
        description: ''
      description: |
        Publish a bid. 
        Assume the receiving node broadcast to the corresponding shard.
      tags:
        - Shards
  '/shards/{shard}/bid_with_data':
    parameters:
      - schema:
          type: integer
        name: shard
        in: path
        required: true
        description: Shard number
    post:
      summary: Publish Bid With Data
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-shards-bid_with_data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BidWithData'
            examples: {}
        description: ''
      description: |
        Publish a bid with data. 
        Assume the receiving node broadcast to the corresponding shard.
      tags:
        - Shards
  /config:
    parameters: []
    get:
      summary: Get Config
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: Not Found
      operationId: get-config
      description: |
        Config for auto mode.
      tags:
        - Config
    post:
      summary: Set Config
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: Not Found
      operationId: post-config
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Config'
            examples: {}
        description: ''
      description: |
        Config for auto mode.
      tags:
        - Config
  /beacon/blocks:
    parameters: []
    get:
      summary: Get Beacon Blocks
      tags:
        - Beacon
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BeaconBlock'
        '404':
          description: Not Found
      operationId: get-beacon-blocks
      description: Get beacon blocks of beacon chain in the latest order.
      parameters:
        - schema:
            type: integer
            default: 100
          in: query
          name: count
        - schema:
            type: integer
          in: query
          name: page
  /beacon/finalized_blocks:
    parameters: []
    get:
      summary: Get Finalized Blocks
      tags:
        - Beacon
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BeaconBlock'
        '404':
          description: Not Found
      operationId: get-beacon-finalized_blocks-block_id
      description: Get finalized beacon blocks of beacon chain in the latest order.
      parameters:
        - schema:
            type: integer
            default: 100
          in: query
          name: count
        - schema:
            type: integer
          in: query
          name: page
  /beacon/finalized_checkpoint:
    get:
      summary: Get Finalized Checkpoint
      tags:
        - Beacon
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkpoint'
        '404':
          description: Not Found
      operationId: get-beacon-finalized_checkpoint
      description: Get the finalized checkpoint
  '/simulator/slot/process/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-slot_num
  '/simulator/slot/process_without_shard_data_inclusion/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot Without Shard Data Inclusion
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-without-shard-data-inclusion-slot_num
  '/simulator/slot/process_without_shard_blob_proposal/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot Without Shard Blob Proposal
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-without-shard-blob-proposal-slot_num
  '/simulator/slot/process_without_shard_header_inclusion/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot Without Shard Header Inclusion
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-without-shard-header-inclusion-slot_num
  '/simulator/slot/process_without_shard_header_confirmation/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot Without Shard Header Confirmation
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-without-shard-header-confirmation-slot_num
  '/simulator/slot/process_without_beacon_chain_finality/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot Without Beacon Chain Finality
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-without-beacon-chain-finality-slot_num
  '/simulator/slot/process_without_beacon_block_proposal/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot Without Beacon Block Proposal
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-without-beacon-block-proposal-slot_num
  '/simulator/slot/process_random/{slot_num}':
    parameters:
      - schema:
          type: string
        name: slot_num
        in: path
        required: true
    post:
      summary: Process Slot Random Failure
      tags:
        - Simulator
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: post-simulator-slot-process-random-slot_num
  /utils/data_commitment:
    parameters: []
    post:
      summary: Calc Data Commitment From Base64 Encoded Text
      operationId: post-utils-data_commitment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataCommitment'
        '404':
          description: Not Found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string
      description: Calculate the data commitment from a base64-encoded data.
      tags:
        - Utils
  /utils/request_logs:
    get:
      summary: Get Request Logs
      tags:
        - Utils
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RequestLog'
        '404':
          description: Not Found
      operationId: get-utils-request_logs
      description: Get the log of the API requests.
  /beacon/states:
    get:
      summary: Get Beacon States
      tags:
        - Beacon
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BeaconState'
        '404':
          description: Not Found
      operationId: get-beacon-states
      description: Get beacon states of beacon chain in the latest order.
      parameters:
        - schema:
            type: integer
            default: 100
          in: query
          name: count
        - schema:
            type: integer
          in: query
          name: page
  /beacon/blocks/head:
    get:
      summary: Get Head of Beacon Chain
      tags:
        - Beacon
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      operationId: get-beacon-blocks-head
      description: Get the head of beacon chain.
  /simulator/init:
    post:
      summary: Init Simulator
      operationId: post-simulator-init
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
      tags:
        - Simulator
      description: Initialize the simulator.
  /utils/current_status_for_polling:
    get:
      summary: Get Current Status For Polling
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  slot:
                    type: integer
                  config:
                    $ref: '#/components/schemas/Config'
      operationId: get-utils-current_status_for_polling
      description: The no logging endpoint for polling used by the dashboard.
components:
  schemas:
    Bid:
      title: Bid
      type: object
      x-examples: {}
      properties:
        message:
          type: object
          properties:
            shard:
              type: integer
            slot:
              type: integer
            commitment:
              $ref: '#/components/schemas/DataCommitment'
            fee:
              type: integer
        signature:
          type: string
    SignedShardHeader:
      title: SignedShardHeader
      type: object
      properties:
        message:
          $ref: '#/components/schemas/ShardHeader'
        signature:
          type: string
    ShardHeader:
      title: ShardHeader
      type: object
      properties:
        slot:
          type: integer
        shard:
          type: integer
        commitment:
          $ref: '#/components/schemas/DataCommitment'
        degree_proof:
          type: string
    DataCommitment:
      title: DataCommitment
      type: object
      properties:
        point:
          type: integer
        length:
          type: integer
    FinalizedCommitment:
      title: FinalizedCommitment
      type: object
      properties:
        commitment:
          $ref: '#/components/schemas/DataCommitment'
        beacon_bock_header:
          $ref: '#/components/schemas/BeaconBlockHeader'
    BeaconBlockHeader:
      title: BeaconBlockHeader
      type: object
      properties:
        slot:
          type: integer
        parent_root:
          type: string
        state_root:
          type: string
    BeaconBlock:
      title: BeaconBlock
      type: object
      properties:
        slot:
          type: integer
        shard_headers:
          type: array
          items:
            $ref: '#/components/schemas/SignedShardHeader'
    PendingShardHeader:
      title: PendingShardHeader
      type: object
      description: Omitted the votes field.
      properties:
        slot:
          type: integer
        shard:
          type: integer
        commitment:
          $ref: '#/components/schemas/DataCommitment'
        root:
          type: string
        confirmed:
          type: boolean
    LightClientUpdate:
      title: LightClientUpdate
      type: object
      description: 'https://github.com/ethereum/eth2.0-specs/blob/cc80dd758cf5120b11af3747f5826de5cdcbd87c/specs/lightclient/sync-protocol.md#lightclientstore'
      properties:
        header:
          $ref: '#/components/schemas/BeaconBlockHeader'
        finality_header:
          $ref: '#/components/schemas/BeaconBlockHeader'
        finality_branch:
          type: array
          items:
            type: string
    BeaconState:
      title: BeaconState
      type: object
      properties:
        previous_epoch_pending_shard_headers:
          type: string
        current_epoch_pending_shard_headers:
          type: string
        grandparent_epoch_confirmed_commitments:
          type: string
        shard_gasprice:
          type: integer
    RequestLog:
      title: RequestLog
      type: object
      x-tags:
        - Utils
      properties:
        log_id:
          type: integer
        date:
          type: string
        endpoint:
          type: string
    Checkpoint:
      title: Checkpoint
      type: object
      x-tags:
        - Beacon
      properties:
        epoch:
          type: integer
        root:
          type: integer
    Config:
      title: Config
      type: object
      properties:
        auto:
          type: boolean
        slot:
          type: integer
        failure_rate:
          type: number
    BidWithData:
      title: BidWithData
      type: object
      properties:
        bid:
          $ref: '#/components/schemas/Bid'
        data:
          type: string
          description: Base64 String
  parameters: {}
tags:
  - name: Beacon
    description: Query to a virtual beacon node.
  - name: Shards
    description: Query to a virtual shard node.
  - name: Simulator
    description: Query to a virtual eth2 simulator.
  - name: Utils
    description: Useful function endpoints.
  - name: Config
    description: Endpoints for emulator configuration.