syntax = "proto3";
package rpc.v1;

import "google/protobuf/empty.proto";

// A service run by the Proxy which listens for incoming connections
// from workers and then notifies clients.
service NotifierService {
  // Notify a client that there has been an update for a `ChainId`.
  rpc Notify(Notification) returns (google.protobuf.Empty);
}

// Interface provided by each physical shard (aka "worker") of a validator or a local node.
// * All commands return either the current chain info or an error.
// * Repeating commands produces no changes and returns no error.
// * Some handlers may return cross-chain requests, that is, messages
//   to be communicated to other workers of the same validator.
service ValidatorWorker {
  // Propose a new block.
  rpc HandleBlockProposal(BlockProposal) returns (ChainInfoResult);

  // Process a certificate without value.
  rpc HandleLiteCertificate(LiteCertificate) returns (ChainInfoResult);

  // Process a certificate.
  rpc HandleCertificate(HandleCertificateRequest) returns (ChainInfoResult);

  // Handle information queries for this chain.
  rpc HandleChainInfoQuery(ChainInfoQuery) returns (ChainInfoResult);

  // Handle a (trusted!) cross-chain request.
  rpc HandleCrossChainRequest(CrossChainRequest) returns (google.protobuf.Empty);
}

// How to communicate with a validator or a local node.
service ValidatorNode {
  // Propose a new block.
  rpc HandleBlockProposal(BlockProposal) returns (ChainInfoResult);

  // Process a certificate without value.
  rpc HandleLiteCertificate(LiteCertificate) returns (ChainInfoResult);

  // Process a certificate.
  rpc HandleCertificate(HandleCertificateRequest) returns (ChainInfoResult);

  // Handle information queries for this chain.
  rpc HandleChainInfoQuery(ChainInfoQuery) returns (ChainInfoResult);

  // Subscribe to notifications for a set of Chain Ids.
  rpc Subscribe(SubscriptionRequest) returns (stream Notification);

  // Request the node's version info.
  rpc GetVersionInfo(google.protobuf.Empty) returns (VersionInfo);

  // Request the genesis configuration hash of the network this node is part of.
  rpc GetGenesisConfigHash(google.protobuf.Empty) returns (CryptoHash);

  // Downloads a blob content.
  rpc DownloadBlobContent(BlobId) returns (BlobContent);

  // Downloads a certificate value.
  rpc DownloadCertificateValue(CryptoHash) returns (CertificateValue);

  // Downloads a certificate.
  rpc DownloadCertificate(CryptoHash) returns (Certificate);

  // Downloads a batch of certificates.
  rpc DownloadCertificates(CertificatesBatchRequest) returns (CertificatesBatchResponse);

  // Returns the hash of the `Certificate` that last used a blob.
  rpc BlobLastUsedBy(BlobId) returns (CryptoHash);
}

// A request for a batch of certificates.
message CertificatesBatchRequest {
  repeated CryptoHash hashes = 1;
}

// A batch of certificates.
message CertificatesBatchResponse {
  repeated Certificate certificates = 1;
}

// Information about the Linera crate version the validator is running
message CrateVersion {
    uint32 major = 1;
    uint32 minor = 2;
    uint32 patch = 3;
}

// Information about the version of Linera the validator is running
message VersionInfo {
    CrateVersion crate_version = 1;
    string git_commit = 2;
    bool git_dirty = 3;
    string rpc_hash = 4;
    string graphql_hash = 5;
    string wit_hash = 6;
}

// A request for client to subscribe to notifications for a given `ChainId`
message SubscriptionRequest {
  repeated ChainId chain_ids = 1;
}

// Notify that a chain has a new certified block or a new message.
message Notification {
  ChainId chain_id = 1;
  bytes reason = 2;
}

// A wrapper around ChainInfoResponse which contains a serialized error variant
message ChainInfoResult {
  oneof inner {
    ChainInfoResponse chain_info_response = 1;
    // a bincode wrapper around `NodeError`
    bytes error = 2;
  }
}

// An internal request between chains within a validator.
message CrossChainRequest {
  oneof inner {
    UpdateRecipient update_recipient = 1;
    ConfirmUpdatedRecipient confirm_updated_recipient = 2;
  }
}

// Communicate a number of messages from the sender to the recipient.
// Messages must be given by increasing block height.
message UpdateRecipient {
  ChainId sender = 1;
  ChainId recipient = 2;
  bytes bundle_vecs = 3;
}

// Acknowledge the height of the highest confirmed blocks communicated with `UpdateRecipient`.
message ConfirmUpdatedRecipient {
  ChainId sender = 1;
  ChainId recipient = 2;
  bytes latest_heights = 3;
}

// Request information on a chain.
message ChainInfoQuery {
  // The chain ID
  ChainId chain_id = 1;

  // Optionally test that the block height is as expected
  optional BlockHeight test_next_block_height = 2;

  // Query the current committees
  bool request_committees = 3;

  // Query the received messages that are waiting be picked in the next block.
  bool request_pending_message_bundles = 4;

  // Query a range of certificates hashes sent from the chain.
  optional bytes request_sent_certificate_hashes_in_range = 5;

  // Query new certificate removed from the chain.
  optional uint64 request_received_log_excluding_first_n = 6;

  // Query values from the chain manager, not just votes.
  bool request_manager_values = 7;

  // Request a signed vote for a leader timeout.
  bool request_leader_timeout = 8;

  // Query the balance of a given owner.
  optional Owner request_owner_balance = 10;

  // Request a signed vote for fallback mode.
  bool request_fallback = 11;
}

// An authenticated proposal for a new block.
message BlockProposal {
  // The ID of the chain (used for routing).
  ChainId chain_id = 1;

  // bincode-encoded content
  bytes content = 2;

  // Byte-encoded public key
  Owner owner = 3;

  // Signature value
  Signature signature = 4;

  // A lite certificate for a validated block that justifies the proposal in this round.
  optional bytes validated_block_certificate = 6;

  // Required blob
  bytes blobs = 7;
}

// A certified statement from the committee, without the value.
message LiteCertificate {
  // The ID of the chain the value belongs to.
  ChainId chain_id = 1;

  // The certified value's hash
  bytes hash = 2;

  // The round in which the value was certified.
  bytes round = 3;

  // Signatures on the value hash and round
  bytes signatures = 4;

  // Wait until all outgoing cross-chain messages from this certificate have
  // been received by the target chains.
  bool wait_for_outgoing_messages = 5;
}

// A certified statement from the committee, together with other certificates
// required for execution.
message HandleCertificateRequest {
  // The ID of the chain (used for routing).
  ChainId chain_id = 1;

  // Wait until all outgoing cross-chain messages from this certificate have
  // been received by the target chains.
  bool wait_for_outgoing_messages = 6;

  // Blobs required by this certificate
  bytes blobs = 7;

  // A certified statement from the committee.
  Certificate certificate = 8;
}

// A certified statement from the committee.
message Certificate {
  // The certified value
  bytes value = 1;

  // The round in which the value was certified.
  bytes round = 2;

  // Signatures on the value hash and round
  bytes signatures = 3;
}

message CertificateValue {
  bytes bytes = 1;
}

message ChainId {
  bytes bytes = 1;
}

message PublicKey {
  bytes bytes = 1;
}

message CryptoHash {
  bytes bytes = 1;
}

message Owner {
  bytes bytes = 1;
}

message Signature {
  bytes bytes = 1;
}

// A content-addressed blob ID i.e. the hash of the `BlobContent`.
message BlobId {
  bytes bytes = 1;
}

// A blob of binary data.
message BlobContent {
  bytes bytes = 1;
}

// Response to `ChainInfoQuery`
message ChainInfoResponse {
  // bincode-encoded chain info
  bytes chain_info = 1;

  // Optional signature for the response.
  optional Signature signature = 2;
}

message BlockHeight {
  uint64 height = 1;
}