// Copyright (c) The Libra Core Contributors
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

package types;

import "validator_set.proto";

/// Even though we don't always need all hashes, we pass them in and return them
/// always so that we keep them in sync on the client and don't make the client
/// worry about which one(s) to pass in which cases
///
/// This structure serves a dual purpose.
///
/// First, if this structure is signed by 2f+1 validators it signifies the state
/// of the ledger at version `version` -- it contains the transaction
/// accumulator at that version which commits to all historical transactions.
/// This structure may be expanded to include other information that is derived
/// from that accumulator (e.g. the current time according to the time contract)
/// to reduce the number of proofs a client must get.
///
/// Second, the structure contains a `consensus_data_hash` value. This is the
/// hash of an internal data structure that represents a block that is voted on
/// by consensus.
///
/// Combining these two concepts when the consensus algorithm votes on a block B
/// it votes for a LedgerInfo with the `version` being the latest version that
/// will be committed if B gets 2f+1 votes. It sets `consensus_data_hash` to
/// represent B so that if those 2f+1 votes are gathered, the block is valid to
/// commit
message LedgerInfo {
  // Current latest version of the system
  uint64 version = 1;

  // Root hash of transaction accumulator at this version
  bytes transaction_accumulator_hash = 2;

  // Hash of consensus-specific data that is opaque to all parts of the system
  // other than consensus.  This is needed to verify signatures because
  // consensus signing includes this hash
  bytes consensus_data_hash = 3;

  // The block id of the last committed block corresponding to this ledger info.
  // This field is not particularly interesting to the clients, but can be used
  // by the validators for synchronization.
  bytes consensus_block_id = 4;

  // Epoch number corresponds to the set of validators that are active for this
  // ledger info. The main motivation for keeping the epoch number in the
  // LedgerInfo is to ensure that the client has enough information to verify
  // that the signatures for this info are coming from the validators that
  // indeed form a quorum. Without epoch number a potential attack could reuse
  // the signatures from the validators in one epoch in order to sign the wrong
  // info belonging to another epoch, in which these validators do not form a
  // quorum. The very first epoch number is 0.
  uint64 epoch_num = 5;

  // Timestamp that represents the microseconds since the epoch (unix time) that is
  // generated by the proposer of the block.  This is strictly increasing with every block.
  // If a client reads a timestamp > the one they specified for transaction expiration time,
  // they can be certain that their transaction will never be included in a block in the future
  // (assuming that their transaction has not yet been included)
  uint64 timestamp_usecs = 6;

  // An optional field with the validator set for the next epoch in case it's the last
  // ledger info in the current epoch.
  ValidatorSet next_validator_set = 7;
}

/// The validator node returns this structure which includes signatures
/// from each validator to confirm the state.  The client needs to only pass
/// back the LedgerInfo element since the validator node doesn't need to know
/// the signatures again when the client performs a query, those are only there
/// for the client to be able to verify the state
message LedgerInfoWithSignatures {
  // Signatures of the root node from each validator
  repeated ValidatorSignature signatures = 1;

  LedgerInfo ledger_info = 2;
}

message ValidatorSignature {
  // The account address of the validator, which can be used for retrieving its
  // public key during the given epoch.
  bytes validator_id = 1;
  bytes signature = 2;
}