prysm-pulse/proto/eth/v1alpha1/validator.proto

syntax = "proto3";
package ethereum.eth.v1alpha1;

import "github.com/gogo/protobuf/gogoproto/gogo.proto";
import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "proto/eth/v1alpha1/beacon_block.proto";
import "proto/eth/v1alpha1/attestation.proto";

option go_package = "github.com/prysmaticlabs/prysm/proto/eth/v1alpha1;eth";

// 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 BeaconNodeValidator {
    // Retrieves validator duties for the requested validators.
    //
    // The duties consist of:
    //   Proposer - the validator that creates a beacon chain block.
    //   Attester — a validator that is part of a committee that needs to sign off on a beacon chain
    //    block while simultaneously creating a cross link to a recent shard block on a particular shard chain.
    // The server returns a list of duties which are the actions should be performed by validators for a given epoch.
    // Validator duties should be polled every epoch, but due to chain reorg of >MIN_SEED_LOOKAHEAD could occur,
    // the validator duties could chain. For complete safety, it is recommended to poll at every slot to ensure
    // validator is fully aware of any sudden chain reorg.
    rpc GetDuties(DutiesRequest) returns (DutiesResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validator/duties"
        };
    }

    // 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.
    rpc GetBlock(BlockRequest) returns (BeaconBlock) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/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.
    rpc ProposeBlock(BeaconBlock) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/eth/v1alpha1/validator/block"
        };
    }

    // Retrieves the latest valid attestation data to be attested on the beacon chain.
    //
    // The server returns the latest valid attestation data which represents the correct vote
    // for the head of the beacon chain,
    rpc GetAttestationData(AttestationDataRequest) returns (AttestationData) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validator/attestation"
        };
    }

    // Sends the newly signed attestation to beacon node.
    //
    // The validator sends the newly signed attestation to the beacon node for the attestation to
    // be included in the beacon chain. The beacon node is expected to validate and aggregate the
    // attestations into the state.
    rpc ProposeAttestation(Attestation) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/eth/v1alpha1/validator/attestation"
        };
    }
}

message DutiesRequest {
    // Epoch at which validators should perform their duties.
    uint64 epoch = 1;
    // Array of byte encoded BLS public keys.
    repeated bytes public_keys = 2 [(gogoproto.moretags) = "ssz-size:\"?,48\""];
}

message DutiesResponse {
    repeated Duty duties = 1;
    message Duty {
        // 48 byte BLS public key for the validator who's assigned to perform the following duty.
        bytes public_key = 1 [(gogoproto.moretags) = "ssz-size:\"48\""];
        // Slot at which a validator must attest.
        uint64 attestation_slot = 2;
        // Shard at which a validator must attest.
        uint64 attestation_shard = 3;
        // Slot at which a validator must propose on beacon chain,
        // when returns 0, the block production is not required, meaning
        // the validator did not get assigned to be a proposer for the
        // input epoch.
        uint64 block_proposal_slot = 4;
    }
}

message BlockRequest {
    // Slot for which the block should be proposed.
    uint64 slot = 1;
    // Validator's 32 byte randao reveal secret of the current epoch.
    bytes randao_reveal = 2 [(gogoproto.moretags) = "ssz-size:\"48\""];
}

message AttestationDataRequest {
    // The proof of custody bit is a byte with a single bit set as reported
    // by the requesting validator. To be used for proof of custody game in phase 1.
    bytes proof_of_custody_bit = 1;
    // Slot for which the attestation should be proposed.
    uint64 slot = 2;
    // Shard for which the attestation is to be proposed.
    uint64 shard = 3;
}

// An Ethereum 2.0 validator.
message Validator {
    // 96 byte BLS public key used for the validator's activities.
    bytes public_key = 1 [(gogoproto.moretags) = "ssz-size:\"48\" spec-name:\"pubkey\""];

    // 32 byte hash of the withdrawal destination public key.
    bytes withdrawal_credentials = 2 [(gogoproto.moretags) = "ssz-size:\"32\""];

    // The validators current effective balance in gwei.
    uint64 effective_balance = 3;

    // Whether or not the validator has been slashed.
    bool slashed = 4;

    // Epoch when the validator became eligible for activation. This field may
    // be zero if the validator was present in the Ethereum 2.0 genesis.
    uint64 activation_eligibility_epoch = 5;

    // Epoch when the validator was activated. This field may be zero if the
    // validator was present in the Ethereum 2.0 genesis.
    uint64 activation_epoch = 6;

    // Epoch when the validator was exited. This field may be zero if the
    // validator has not exited.
    uint64 exit_epoch = 7;

    // Epoch when the validator is eligible to withdraw their funds. This field
    // may be zero if the validator has not exited.
    uint64 withdrawable_epoch = 8;
}