openapi2proto-bn.proto

syntax = "proto3";

package beaconnodeapi;

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

message GetValidatorAggregateAndProofRequest {
    // SSZ serialized AttestationData that validator want's aggregated
    string attestation_data = 1;
}

message GetValidatorAttestationRequest {
    // The committee index for which the attestation should be proposed.
    string committee_index = 1;

    // The slot for which the attestation should be proposed.
    int32 slot = 2;

    // Uniquely identifying which validator this attestation is to be produced for.
    string validator_pubkey = 3;
}

message GetValidatorBeaconCommitteeSubscriptionCommitteeIndexAttestationsRequest {
    // SSZ serialized AttestationData that validator want's aggregated
    string attestation_data = 1;

    // Index of validator committee
    double committee_index = 2;
}

message GetValidatorBlockRequest {
    // The validator's randao reveal value.
    string randao_reveal = 1;

    // The slot for which the block should be proposed.
    string slot = 2;
}

message GetValidatorDutiesEpochAttesterRequest {
    // Should only be allowed 1 epoch
    string epoch = 1;

    // An array of hex-encoded BLS public keys
    repeated string validator_pubkeys = 2;
}

message GetValidatorDutiesEpochProposerRequest {
    int32 epoch = 1;
}

message GetValidatorPubkeyRequest {
    string pubkey = 1;
}

service BeaconNodeAPIService {
    // Get fork information from running beacon node.
    // 
    // Requests the beacon node to provide which fork version it is currently on.
    rpc GetBeaconFork(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/beacon/fork"
        };
    }

    // Get fork information from running beacon node.
    // 
    // Requests the beacon node to provide which fork version it is currently on.
    rpc GetBeaconForkStream(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/beacon/fork/stream"
        };
    }

    // Get the genesis_time parameter from beacon node configuration.
    // 
    // Requests the genesis_time parameter from the beacon node, which should be consistent across all beacon nodes that follow the same beacon chain.
    rpc GetBeaconGenesis(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/beacon/genesis"
        };
    }

    // Poll to see if the the beacon node is syncing.
    // 
    // 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..
    rpc GetNodeSyncing(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/node/syncing"
        };
    }

    // Get version string of the running beacon node.
    // 
    // Requests that the beacon node 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.
    rpc GetNodeVersion(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/node/version"
        };
    }

    // Get aggregated attestations
    // 
    // Aggregates all attestations matching given attestation data
    rpc GetValidatorAggregateAndProof(GetValidatorAggregateAndProofRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/validator/aggregate_and_proof"
        };
    }

    // Produce an attestation, without signature.
    // 
    // Requests that the beacon node produce an Attestation, with a blank signature field, which the validator will then sign.
    rpc GetValidatorAttestation(GetValidatorAttestationRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/validator/attestation"
        };
    }

    // Get unaggregated wire attestations
    // 
    // Endpoint should aggregate all collected attestations and produce AggregateAndProof without proof. Validator running on weak hardware is expected to add proof and publish
    rpc GetValidatorBeaconCommitteeSubscriptionCommitteeIndexAttestations(GetValidatorBeaconCommitteeSubscriptionCommitteeIndexAttestationsRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/validator/beacon_committee_subscription/{committee_index}/attestations"
        };
    }

    // Produce a new block, without signature.
    // 
    // Requests a beacon node to produce a valid block, which can then be signed by a validator.
    rpc GetValidatorBlock(GetValidatorBlockRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/validator/block"
        };
    }

    // Get attester duties
    // 
    // Requests the beacon node to provide a set of _duties_, which are actions that should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, this API call should be polled at every slot to ensure that chain reorganizations are recognized, and to ensure that the beacon node is properly synchronized.
    rpc GetValidatorDutiesEpochAttester(GetValidatorDutiesEpochAttesterRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/validator/duties/{epoch}/attester"
        };
    }

    // Get block proposers duties
    // 
    // Request beacon node to provide all validators that are suppose to propose block in given epoch
    rpc GetValidatorDutiesEpochProposer(GetValidatorDutiesEpochProposerRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/validator/duties/{epoch}/proposer"
        };
    }

    // Get validator details.
    // 
    // Requests the beacon node to provide details about validator or 404 if validator is not present in validator registry
    rpc GetValidatorPubkey(GetValidatorPubkeyRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/validator/{pubkey}"
        };
    }

    // Publish aggregate and proof
    // 
    // Verifies given aggregate and proof and publishes it on appropriate gossipsub topic.
    rpc PostValidatorAggregateAndProof(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/validator/aggregate_and_proof"
        };
    }

    // Publish a signed attestation.
    // 
    // Instructs the beacon node to broadcast a newly signed Attestation object to the intended shard subnet. The beacon node is not required to validate the signed Attestation, and a successful response (20X) only indicates that the broadcast has been successful. The beacon node is expected to integrate the new attestation into its state, and therefore validate the attestation internally, however attestations which fail the validation are still broadcast but a different status code is returned (202)
    rpc PostValidatorAttestation(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/validator/attestation"
        };
    }

    // Subscribe beacon node to commitee attestation subnet
    // 
    // If validator is connected to multiple nodes, it should send this request to all of them to insure subnet network stability.
    rpc PostValidatorBeaconCommitteeSubscriptions(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/validator/beacon_committee_subscriptions"
        };
    }

    // Publish a signed block.
    // 
    // Instructs the beacon node to broadcast a newly signed beacon block to the beacon network, to be included in the beacon chain. The beacon node is not required to validate the signed `BeaconBlock`, and a successful response (20X) only indicates that the broadcast has been successful. The beacon node is expected to integrate the new block into its state, and therefore validate the block internally, however blocks which fail the validation are still broadcast but a different status code is returned (202)
    rpc PostValidatorBlock(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/validator/block"
        };
    }
}