api.proto

/*
 * This protobuf file contains the definition of the public API endpoints as
 * well as messages. All client implementations should use this reference
 * protobuf to implement a compatible drand client.
 */
syntax = "proto3";

package drand;

option go_package = "github.com/drand/drand/protobuf/drand";
/*option go_package = "drand";*/

import "drand/common.proto";

service Public {
    // PublicRand is the method that returns the publicly verifiable randomness
    // generated by the drand network.
    rpc PublicRand(PublicRandRequest) returns (PublicRandResponse);

    rpc PublicRandStream(PublicRandRequest) returns (stream PublicRandResponse);

    // PrivateRand is the method that returns the private randomness generated
    // by the drand node only.
    rpc PrivateRand(PrivateRandRequest) returns (PrivateRandResponse);

    // ChainInfo returns the information related to the chain this node
    // participates to
    rpc ChainInfo(drand.ChainInfoRequest) returns (drand.ChainInfoPacket);

    // Home is a simple endpoint
    rpc Home(HomeRequest) returns (HomeResponse);
}

// PublicRandRequest requests a public random value that has been generated in a
// unbiasable way and verifiable.
message PublicRandRequest {
    // round uniquely identifies a beacon. If round == 0 (or unspecified), then
    // the response will contain the last.
    uint64 round = 1;
}

// PublicRandResponse holds a signature which is the random value. It can be
// verified thanks to the distributed public key of the nodes that have ran the
// DKG protocol and is unbiasable. The randomness can be verified using the BLS
// verification routine with the message "round || previous_rand".
message PublicRandResponse {
    uint64 round = 1;
    bytes signature = 2;
    bytes previous_signature = 3;
    // randomness is simply there to demonstrate - it is the hash of the
    // signature. It should be computed locally.
    bytes randomness = 4;
}

// PrivateRandRequest is the message to send when requesting a private random
// value.
message PrivateRandRequest {
    // Request is the ECIES encryption of an ephemereal public key towards which
    // to encrypt the private randomness. The format of the bytes is denoted by
    // the ECIES encryption used by drand.
    bytes request = 1;
}

message PrivateRandResponse {
    // Responses is the ECIES encryption of the private randomness using the
    // ephemereal public key sent in the request.  The format of the bytes is
    // denoted by the ECIES  encryption used by drand.
    bytes response = 1;
}


message HomeRequest {
}

message HomeResponse {
    string status = 1;
}