types: add CheckpointSummary type

Author: bmwill

src/types/checkpoint.rs

@@ -0,0 +1,68 @@
+use super::Bls12381PublicKey;
+use super::CheckpointContentsDigest;
+use super::CheckpointDigest;
+use super::Digest;
+use super::GasCostSummary;
+
+pub type CheckpointSequenceNumber = u64;
+pub type CheckpointTimestamp = u64;
+pub type EpochId = u64;
+pub type StakeUnit = u64;
+pub type ProtocolVersion = u64;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum CheckpointCommitment {
+    ECMHLiveObjectSetDigest(Digest),
+    // Other commitment types (e.g. merkle roots) go here.
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EndOfEpochData {
+    /// next_epoch_committee is `Some` if and only if the current checkpoint is
+    /// the last checkpoint of an epoch.
+    /// Therefore next_epoch_committee can be used to pick the last checkpoint of an epoch,
+    /// which is often useful to get epoch level summary stats like total gas cost of an epoch,
+    /// or the total number of transactions from genesis to the end of an epoch.
+    /// The committee is stored as a vector of validator pub key and stake pairs. The vector
+    /// should be sorted based on the Committee data structure.
+    pub next_epoch_committee: Vec<(Bls12381PublicKey, StakeUnit)>,
+
+    /// The protocol version that is in effect during the epoch that starts immediately after this
+    /// checkpoint.
+    pub next_epoch_protocol_version: ProtocolVersion,
+
+    /// Commitments to epoch specific state (e.g. live object set)
+    pub epoch_commitments: Vec<CheckpointCommitment>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CheckpointSummary {
+    pub epoch: EpochId,
+    pub sequence_number: CheckpointSequenceNumber,
+    /// Total number of transactions committed since genesis, including those in this
+    /// checkpoint.
+    pub network_total_transactions: u64,
+    pub content_digest: CheckpointContentsDigest,
+    pub previous_digest: Option<CheckpointDigest>,
+    /// The running total gas costs of all transactions included in the current epoch so far
+    /// until this checkpoint.
+    pub epoch_rolling_gas_cost_summary: GasCostSummary,
+
+    /// Timestamp of the checkpoint - number of milliseconds from the Unix epoch
+    /// Checkpoint timestamps are monotonic, but not strongly monotonic - subsequent
+    /// checkpoints can have same timestamp if they originate from the same underlining consensus commit
+    pub timestamp_ms: CheckpointTimestamp,
+
+    /// Commitments to checkpoint-specific state (e.g. txns in checkpoint, objects read/written in
+    /// checkpoint).
+    pub checkpoint_commitments: Vec<CheckpointCommitment>,
+
+    /// Present only on the final checkpoint of the epoch.
+    pub end_of_epoch_data: Option<EndOfEpochData>,
+
+    /// CheckpointSummary is not an evolvable structure - it must be readable by any version of the
+    /// code. Therefore, in order to allow extensions to be added to CheckpointSummary, we allow
+    /// opaque data to be added to checkpoints which can be deserialized based on the current
+    /// protocol version.
+    pub version_specific_data: Vec<u8>,
+}

src/types/mod.rs

@@ -1,10 +1,12 @@
 mod address;
+mod checkpoint;
 mod crypto;
 mod digest;
 mod gas;
 mod object_id;
 
 pub use address::Address;
+pub use checkpoint::{CheckpointCommitment, CheckpointSummary, EndOfEpochData};
 pub use crypto::{
     Bls12381PrivateKey, Bls12381PublicKey, Bls12381Signature, Ed25519PrivateKey, Ed25519PublicKey,
     Ed25519Signature, Secp256k1PrivateKey, Secp256k1PublicKey, Secp256k1Signature,