validator.proto

// Copyright 2019 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.eth.v1alpha1;

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "eth/v1alpha1/beacon_block.proto";
import "eth/v1alpha1/attestation.proto";

option csharp_namespace = "Ethereum.Eth.v1alpha1";
option go_package = "github.com/prysmaticlabs/ethereumapis/eth/v1alpha1;eth";
option java_multiple_files = true;
option java_outer_classname = "ValidatorProto";
option java_package = "org.ethereum.eth.v1alpha1";
option php_namespace = "Ethereum\\Eth\\v1alpha1";

// 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"
        };
    }

    // DomainData fetches the current BLS signature domain version information from the
    // running beacon node's state. This information is used when validators sign
    // blocks and attestations appropriately based on their duty.
    rpc DomainData(DomainRequest) returns (DomainResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validator/domain"
        };
    }

    // WaitForActivation checks if a validator public key exists in the active validator 
    // registry of the current beacon state. If the validator is NOT yet active, it starts a 
    // server-side stream which updates the client whenever the validator becomes active in
    // the beacon node's state.
    //
    // The input to this endpoint is a list of validator public keys, and the corresponding
    // stream will respond until at least a single corresponding validator to those
    // keys is activated.
    rpc WaitForActivation(ValidatorActivationRequest) returns (stream ValidatorActivationResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validator/activation/stream"
        };
    }

    // WaitForChainStart queries the logs of the Validator Deposit Contract on the Ethereum
    // proof-of-work chain to verify the beacon chain has started its runtime and 
    // validators are ready to begin their responsibilities. 
    //
    // If the chain has not yet started, this endpoint starts a server-side stream which updates
    // the client when the beacon chain is ready.
    rpc WaitForChainStart(google.protobuf.Empty) returns (stream ChainStartResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validator/chainstart/stream"
        };
    }

    // ValidatorIndex retrieves a validator's index location in the beacon state's
    // validator registry looking up whether the validator exists based on its
    // public key. This method returns NOT_FOUND if no index is found for the public key
    // specified in the request.
    rpc ValidatorIndex(ValidatorIndexRequest) returns (ValidatorIndexResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validator/index"
        };
    }

	// ValidatorStatus returns a validator's status based on the current epoch.
	// The request can specify either a validator's public key or validator index.
	// 
	// The status response can be one of the following:
	//	DEPOSITED - validator's deposit has been recognized by Ethereum 1, not yet recognized by Ethereum 2.
	//	PENDING - validator is in Ethereum 2's activation queue.
	//	ACTIVE - validator is active.
	//	EXITING - validator has initiated an an exit request, or has dropped below the ejection balance and is being kicked out.
	//	EXITED - validator is no longer validating.
	//	SLASHING - validator has been kicked out due to meeting a slashing condition.
	//	UNKNOWN_STATUS - validator does not have a known status in the network.
    rpc ValidatorStatus(ValidatorStatusRequest) returns (ValidatorStatusResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/validator/status"
        };
    }

    // 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(SignedBeaconBlock) returns (ProposeResponse) {
        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 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 (AttestResponse) {
        option (google.api.http) = {
            post: "/eth/v1alpha1/validator/attestation"
        };
    }

    // Propose to leave the list of active validators.
    //
    // The beacon node is expected to validate the request and make it available for inclusion in
    // the next proposed block.
    rpc ProposeExit(SignedVoluntaryExit) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/eth/v1alpha1/validator/exit"
        };
    }
}

message DomainRequest {
    // The epoch for which the domain is being requested.
    uint64 epoch = 1;

    // The bytes domain specified by the validator.
    bytes domain = 2;
}

message DomainResponse {
    // The signature domain is a number used by validators when
    // signing data related to block proposals and attestations.
    uint64 signature_domain = 1;
}

message ValidatorActivationRequest {
    // A list of 48 byte validator public keys.
    repeated bytes public_keys = 1;
}

message ValidatorActivationResponse {
    message Status {
        // A 48 byte validator public key.
        bytes public_key = 1;

        // A wrapper representing a validator's status object.
        ValidatorStatusResponse status = 2;
    }
    // A list of validator statuses mapped 1-to-1 with the public keys
    // in the request.
    repeated Status statuses = 1;
}

message ChainStartResponse {
    // A boolean specifying whether or not the chain has started.
    bool started = 1;

    // The genesis time of the beacon chain.
    uint64 genesis_time = 2;
}

message ValidatorIndexRequest {
    // A 48 byte validator public key.
    bytes public_key = 1;
}

message ValidatorIndexResponse {
    // The validator's index in the beacon chain state's validator registry.
    uint64 index = 1;
}

message ValidatorStatusRequest {
    // A 48 byte validator public key.
    bytes public_key = 1;
}

enum ValidatorStatus {
  UNKNOWN_STATUS = 0;
  DEPOSITED = 1;
  PENDING = 2;
  ACTIVE = 3;
  EXITING = 4;
  SLASHING = 5;
  EXITED = 6;
}

message ValidatorStatusResponse {
    // The corresponding validator status.
    ValidatorStatus status = 1;

    // The block number of the Ethereum proof-of-work chain
	// where the deposit for the validator was included.
    uint64 eth1_deposit_block_number = 2;

    // The slot in the beacon chain in which the validator's
    // deposit was included in a block.
    int64 deposit_inclusion_slot = 3;

    // The epoch in the beacon chain in which the validator
    // is determined as active.
    int64 activation_epoch = 4;

    // The position in the activation queue of pending validators.
    int64 position_in_activation_queue = 5;
}

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;
}

message DutiesResponse {
    repeated Duty duties = 1;
    message Duty {
        // The committee a validator is assigned to.
        repeated uint64 committee = 1;

        // The index into the committee where the validator belongs in.
        uint64 committee_index = 2;

        // Slot at which a validator must attest.
        uint64 attester_slot = 3;

        // Slot at which a validator must propose a beacon chain block.
        uint64 proposer_slot = 4;

        // 48 byte BLS public key for the validator who's assigned to perform a duty.
        bytes public_key = 5;

        // The current status of the validator assigned to perform the duty.
        ValidatorStatus status = 6;

        // The index of the validator in the beacon state.
        uint64 validator_index = 7;
    }
}

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;

    // Validator's 32 byte graffiti message for the new block.
    bytes graffiti = 3;
}

message ProposeResponse {
    // The block root of the successfully proposed beacon block.
    bytes block_root = 1;
}

message AttestationDataRequest {
    // Slot for which the attestation should be created.
    uint64 slot = 1;

    // Committee index the attestation should be created for.
    uint64 committee_index = 2;
}

message AttestResponse {
    // The root of the attestation data successfully submitted to the beacon node.
    bytes attestation_data_root = 1;
}

// An Ethereum 2.0 validator.
message Validator {
    // 48 byte BLS public key used for the validator's activities.
    bytes public_key = 1;

    // 32 byte hash of the withdrawal destination public key.
    bytes withdrawal_credentials = 2;

    // 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. This
    // field is FAR_FUTURE_EPOCH if the validator has not been activated.
    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. This field is
    // FAR_FUTURE_EPOCH if the validator has not been activated.
    uint64 activation_epoch = 6;

    // Epoch when the validator was exited. This field is FAR_FUTURE_EPOCH if
    // the validator has not exited.
    // FAR_FUTURE_EPOCH is a constant defined by the official Ethereum 2.0 specification:
    // https://github.com/ethereum/eth2.0-specs/blob/v0.9.2/specs/core/0_beacon-chain.md#constants
    uint64 exit_epoch = 7;

    // Epoch when the validator is eligible to withdraw their funds. This field
    // is FAR_FUTURE_EPOCH if the validator has not exited.
    // FAR_FUTURE_EPOCH is a constant defined by the official Ethereum 2.0 specification:
    // https://github.com/ethereum/eth2.0-specs/blob/v0.9.2/specs/core/0_beacon-chain.md#constants
    uint64 withdrawable_epoch = 8;
}

// ValidatorParticipation stores participation metrics during a given epoch.
message ValidatorParticipation {
    // Percentage of validator participation in the given epoch. This field
    // contains a value between 0 and 1.
    float global_participation_rate = 1;

    // The total amount of ether, in gwei, that has been used in voting.
    uint64 voted_ether = 2;

    // The total amount of ether, in gwei, that is eligible for voting.
    uint64 eligible_ether = 3;   
}

// ValidatorInfo gives information about the state of a validator at a certain epoch.
message ValidatorInfo {
    // The validator's 48 byte BLS public key.
    bytes public_key = 1;

    // The validator's index in the beacon state.
    uint64 index = 2;

    // The epoch for which the information pertains.
    uint64 epoch = 3;

    // The validator's current status.
    ValidatorStatus status = 4;

    // The unix timestamp when the validator enters the next state.
    // This could be in the past.  Some values depend on chain operation and so will vary from epoch to epoch.
    // Specific times for each state are as follows:
    // - state == DEPOSITED: time at which Ethereum 1 deposit will be stored on-chain by Ethereum 2 (variable, can be 0).
    // - state == PENDING: time at which validator will be activated (variable).
    // - state == ACTIVE: no value (next transition depends on user and network actions).
    // - state == EXITING: time at which validator will exit.
    // - state == SLASHING: time at which validator will exit.
    // - state == EXITED: time at which validator funds will be withdrawable.
    uint64 transition_timestamp = 5;

    // The validator's current balance in GWei.
    uint64 balance = 6;

    // The validator's current effective balance in GWei.
    // Only valid for states ACTIVE, EXITING, SLASHING.
    uint64 effective_balance = 7;
}