feat: 13135 Added PlatformState protobuf representation

platform/state/platform_state.proto

@@ -0,0 +1,197 @@
+/**
+ * # PlatformState
+ * Messages that hold platform state in the network state.
+ *
+ * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ * document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119)
+ * and clarified in [RFC8174](https://www.ietf.org/rfc/rfc8174).
+ */
+syntax = "proto3";
+
+package com.hedera.hapi.platform.state;
+
+/*
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+option java_package = "com.hedera.hapi.platform.state.legacy";
+// <<<pbj.java_package = "com.hedera.hapi.platform.state">>> This comment is special code for setting PBJ Compiler java package
+option java_multiple_files = true;
+
+import "basic_types.proto";
+import "timestamp.proto";
+
+/**
+ * The current state of platform consensus.<br/>
+ * This message stores the current consensus data for the platform
+ * in network state.
+ *
+ * The platform state SHALL represent the latest round's consensus.<br/>
+ * This data SHALL be used to ensure consistency and provide critical data for
+ * restart and reconnect.
+ */
+message PlatformState {
+
+    /**
+     * A version describing the current version of application software.
+     * <p>
+     * This SHALL be the software version that created this state.
+     */
+    proto.SemanticVersion creation_software_version = 1;
+
+    /**
+     * A number of non-ancient rounds.
+     * <p>
+     * This SHALL be the count of rounds considered non-ancient.
+     */
+    uint32 rounds_non_ancient = 2;
+
+    /**
+     * A snapshot of the consensus state at the end of the round.
+     * <p>
+     * This SHALL be used for restart/reconnect.
+     */
+    ConsensusSnapshot consensus_snapshot = 3;
+
+    /**
+     * A timestamp for the next scheduled time when a freeze will start.
+     * <p>
+     * If a freeze is not scheduled, this SHALL NOT be set.<br/>
+     * If a freeze is currently scheduled, this MUST be set, and MUST
+     * match the timestamp requested for that freeze.
+     */
+    proto.Timestamp freeze_time = 4;
+
+    /**
+     * A timestamp for the last time a freeze was performed.<br/>
+     * If not set, there has never been a freeze.
+     */
+    proto.Timestamp last_frozen_time = 5;
+
+    // Fields below are to be deprecated in the foreseeable future.
+
+    /**
+     * A running event hash.<br/>
+     * This is computed by the consensus event stream.
+     * <p>
+     * This will be _removed_ and the field number reserved once the consensus
+     * event stream is retired.
+     */
+     bytes legacy_running_event_hash = 10000 [deprecated = true];
+
+    /**
+     * A consensus generation.<br/>
+     * The lowest judge generation before birth round mode was enabled.
+     * <p>
+     * This SHALL be `MAX_UNSIGNED` if birth round mode has not yet been enabled.
+     */
+    uint64 lowest_judge_generation_before_birth_round_mode = 10001 [deprecated = true];
+
+    /**
+     * A consensus round.<br/>
+     * The last round before the birth round mode was enabled.
+     * Will be removed after the birth round migration.
+     * <p>
+     * This SHALL be `MAX_UNSIGNED` if birth round mode has not yet been enabled.
+     */
+    uint64 last_round_before_birth_round_mode = 10002 [deprecated = true];
+
+    /**
+     * A consensus node semantic version.<br/>
+     * The software version that enabled birth round mode.
+     * <p>
+     * This SHALL be unset if birth round migration has not yet happened.<br/>
+     * If birth round migration is complete, this SHALL be the _first_ software
+     * version that enabled birth round mode.
+    */
+    proto.SemanticVersion first_version_in_birth_round_mode = 10003 [deprecated = true];
+
+}
+
+
+/**
+ * A consensus snapshot.<br/>
+ * This is a snapshot of the consensus state for a particular round.
+ *
+ * This message SHALL record consensus data necessary for restart
+ * and reconnect.
+ */
+message ConsensusSnapshot {
+    /**
+     * A consensus round.<br/>
+     * The round number of this snapshot.
+     */
+    uint64 round = 1;
+    /**
+     * A list of SHA-384 hash values.<br/>
+     * The hashes of all judges for this round.
+     * <p>
+     * This list SHALL be ordered by creator ID.<br/>
+     * This list MUST be deterministically ordered.
+     */
+    repeated bytes judge_hashes = 2;
+
+    /**
+     * A list of minimum judge information entries.<br/>
+     * These are "minimum ancient" entries for non-ancient rounds.
+     */
+    repeated MinimumJudgeInfo minimum_judge_info_list = 3;
+
+    /**
+     * A single consensus number.<br/>
+     * The consensus order of the next event to reach consensus.
+     */
+    uint64 next_consensus_number = 4;
+
+    /**
+     * A "consensus" timestamp.<br/>
+     * The consensus timestamp of this snapshot.
+     * <p>
+     * Depending on the context this timestamp may have different meanings:
+     * <ul>
+     * <li>if there are transactions, the timestamp is equal to the timestamp of the last transaction</li>
+     * <li>if there are no transactions, the timestamp is equal to the timestamp of the last event</li>
+     * <li>if there are no events, the timestamp is equal to the timestamp of the previous round plus a small constant</li>
+     * </ul>
+     * <p>
+     * This SHALL be a consensus value and MAY NOT correspond to an actual
+     * "wall clock" timestamp.<br/>
+     * Consensus Timestamps SHALL always increase.
+     */
+    proto.Timestamp consensus_timestamp = 5;
+
+}
+
+/**
+ * Records the minimum ancient indicator for all judges in a particular round.
+ */
+message MinimumJudgeInfo {
+    /**
+     * A consensus round.<br/>
+     * The round this judge information applies to.
+     */
+    uint64 round = 1;
+
+    /**
+     * This is a minimum ancient threshold for all judges for a given round.
+     * The value should be interpreted as a generation if the birth
+     * round migration is not yet completed, and a birth round thereafter.
+     * <p>
+     * This SHALL reflect the relevant minimum threshold, whether
+     * generation-based or birth-round-based.
+     */
+    uint64 minimum_judge_ancient_threshold = 2;
+}