prysm-pulse/proto/prysm/v2/validator.proto

// Copyright 2020 Prysmatic Labs.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";

package ethereum.prysm.v2;

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";

import "proto/eth/ext/options.proto";

import "proto/eth/v1alpha1/validator.proto";
import "proto/eth/v1alpha1/beacon_block.proto";
import "proto/eth/v1alpha1/beacon_chain.proto";

import "proto/prysm/v2/beacon_block.proto";
import "proto/prysm/v2/sync_committee.proto";

option csharp_namespace = "Ethereum.Prysm.V2";
option go_package = "github.com/prysmaticlabs/prysm/proto/prysm/v2;v2";
option java_multiple_files = true;
option java_outer_classname = "ValidatorProto";
option java_package = "org.ethereum.prysm.v2";
option php_namespace = "Ethereum\\Prysm\\v2";

// Beacon node validator API
//
// The beacon node validator API enables a validator to connect
// and perform its obligations on the Ethereum 2.0 phase 0 beacon chain.
service BeaconNodeValidatorAltair {
  // Retrieves the latest valid beacon block to be proposed on the beacon chain.
  //
  // The server returns a new beacon block, without proposer signature, that can be
  // proposed on the beacon chain. The block should be filled with all the necessary
  // data for proposer to sign. This block is versioned from Altair onwards.
  rpc GetBlock(ethereum.eth.v1alpha1.BlockRequest) returns (BeaconBlockAltair) {
    option (google.api.http) = {
      get: "/eth/v2prysm/validator/block"
    };
  }

  // Sends the newly signed beacon block to beacon node.
  //
  // The validator sends the newly signed beacon block to the beacon node so the beacon block can
  // be included in the beacon chain. The beacon node is expected to validate and process the
  // beacon block into its state. This block is versioned from Altair onwards.
  rpc ProposeBlock(SignedBeaconBlockAltair) returns (ethereum.eth.v1alpha1.ProposeResponse) {
    option (google.api.http) = {
      post: "/prysm/v2/validator/block"
      body: "*"
    };
  }

  // Retrieves a sync committee message block root to be signed over as part of sync committee duty.
  rpc GetSyncMessageBlockRoot(google.protobuf.Empty) returns (SyncMessageBlockRootResponse) {
    option (google.api.http) = {
      get: "/prysm/v2/validator/sync_message_block_root"
    };
  }

  // Submits a sync committee message to be broadcasted over network. This is part of sync committee duty.
  rpc SubmitSyncMessage(SyncCommitteeMessage) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/prysm/v2/validator/sync_message"
      body: "*"
    };
  }

  // Retrieves the sync subcommittee index of a given validator.
  //
  // The server returns the sync subcommittee index given the validator public key,
  // if the validator does not exist in the sync committee then an error would be returned.
  // The subcommittee index is used for the aggregation of sync committee message.
  rpc GetSyncSubcommitteeIndex(SyncSubcommitteeIndexRequest) returns (SyncSubcommitteeIndexResponse) {
    option (google.api.http) = {
      get: "/prysm/v2/sync_subcommittee_index"
    };
  }

  // Retrieve sync committee contribution to the beacon node to aggregate all matching sync committee messages with the same slot and root.
  // the beacon node responses with a sync committee contribution object for the validator to sign over.
  rpc GetSyncCommitteeContribution(SyncCommitteeContributionRequest) returns (SyncCommitteeContribution) {
    option (google.api.http) = {
      post: "/prysm/v2/validator/contribution_and_proof"
      body: "*"
    };
  }

  // Submit a signed sync committee contribution and proof object, the beacon node will broadcast the
  // signed contribution and proof object.
  rpc SubmitSignedContributionAndProof(SignedContributionAndProof) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/prysm/v2/validator/signed_contribution_and_proof"
      body: "*"
    };
  }

  // Server-side stream of all signed blocks as they are received by
  // the beacon chain node.
  rpc StreamBlocks(ethereum.eth.v1alpha1.StreamBlocksRequest) returns (stream StreamBlocksResponse) {
    option (google.api.http) = {
            get: "/prysm/v2/validator/blocks/stream"
        };
  }
}

// SyncMessageBlockRootResponse for beacon chain validator to retrieve and
// to sign over the block root as part of sync committee duty to facilitate light client.
message SyncMessageBlockRootResponse {
  // The block root of the head block.
  bytes root = 1 [(ethereum.eth.ext.ssz_size) = "32"];
}

// SyncSubcommitteeIndexRequest requests sync subcommittee index given the validator public key.
message SyncSubcommitteeIndexRequest {
  // The validator's public key.
  bytes public_key = 1 [(ethereum.eth.ext.ssz_size) = "48"];
  // The slot of validator's assignment.
  uint64 slot = 2 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Slot"];
}

message SyncCommitteeContributionRequest {
  // Slot for which the aggregation request applies.
  uint64 slot = 1 [(ethereum.eth.ext.cast_type) = "github.com/prysmaticlabs/eth2-types.Slot"];
  // 48 byte public key of the validator.
  bytes public_key = 2 [(ethereum.eth.ext.ssz_size) = "48", (ethereum.eth.ext.spec_name) = "pubkey"];
  // Subnet ID of where this contribution and proof should be broadcast to.
  uint64 subnet_id = 3;
}

// SyncSubcommitteeIndexResponse responds index of the sync subcommittee of a given validator.
message SyncSubcommitteeIndexResponse {
  // The subcommittee index itself.
  // If the total validator count is not sufficient, there could be more than one index.
  repeated uint64 indices = 1;
}

message StreamBlocksResponse {
  oneof block {
    // Representing a phase 0 block.
    ethereum.eth.v1alpha1.SignedBeaconBlock phase0_block = 1 ;

    // Representing an altair block.
    SignedBeaconBlockAltair altair_block = 2;
  }
}