Moved platform_state.proto to platform/state directory.

Updated the documentation according to the guidelines.

Signed-off-by: Ivan Malygin <[email protected]>

platform/state/platform_state.proto

@@ -0,0 +1,196 @@
+/**
+ * # Platform Data
+ * A message that describes the current state of the platform entity.
+ *
+ * This message represents the consensus state of the platform and MUST include
+ * information on address books, round numbers, event hashes, consensus snapshots,
+ * and software version data. The state data MUST accurately reflect the latest round's
+ * consensus, ensuring consistency and providing critical data for restarts and reconnects.
+ *
+ * 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";
+
+/**
+ * PlatformState MUST represent the current consensus state of the platform entity.
+ * The state SHOULD contain the following components:
+ */
+message PlatformState {
+    /**
+     * The address book for this round.
+     * The address book MUST represent the latest consensus view of node addresses.
+     */
+    proto.NodeAddressBook address_book = 1;
+
+    /**
+     * The previous address book. A temporary workaround until dynamic address books are supported.
+     * If present, the previous address book SHOULD reflect the address book from the preceding round.
+     */
+    proto.NodeAddressBook previous_address_book = 2;
+
+    /**
+     * The round of this state. This state MUST represent the handling of all transactions that have reached consensus
+     * in all previous rounds. The first state (genesis state) has a round of 0 because the first round is defined as round 1.
+     */
+    uint64 round = 3;
+
+    /**
+     * The running event hash computed by the consensus event stream. This SHOULD be deleted once the consensus event stream is retired.
+     */
+    bytes legacy_running_event_hash = 4;
+
+    /**
+     * The consensus timestamp for this signed state. This timestamp MUST represent the consensus of the first transaction in this round.
+     */
+    proto.Timestamp consensus_timestamp = 5;
+
+    /**
+     * The version of the application software that created this state. This MUST accurately reflect the software version of the platform entity.
+     */
+    SoftwareVersion creation_software_version = 6;
+
+    /**
+     * The epoch hash of this state. MUST be updated whenever emergency recovery is performed.
+     */
+    bytes epoch_hash = 7;
+
+    /**
+     * The next epoch hash, used to update the epoch hash at the next round boundary. This field SHOULD NOT be part of the hash
+     * and MUST NOT be serialized.
+     */
+    bytes next_epoch_hash = 8;
+
+    /**
+     * The number of non-ancient rounds.
+     * MUST accurately reflect the count of rounds that are considered non-ancient.
+     */
+    uint32 rounds_non_ancient = 9;
+
+    /**
+     * A snapshot of the consensus state at the end of the round. MUST be used for restart/reconnect.
+     */
+    ConsensusSnapshot consensus_snapshot = 10;
+
+    /**
+     * The time when the freeze starts.
+     * If null, a freeze SHOULD NOT be scheduled.
+     */
+    proto.Timestamp freeze_time = 11;
+
+    /**
+     * The last time when a freeze was performed.
+     * If null, there has never been a freeze.
+     */
+    proto.Timestamp last_frozen_time = 12;
+
+    /**
+     * Null if birth round migration has not yet happened. Otherwise, this MUST represent the software version that first enabled birth round mode.
+     */
+    SoftwareVersion first_version_in_birth_round_mode = 13;
+
+    /**
+     * The last round before the birth round mode was enabled, or -1 if birth round mode has not yet been enabled.
+     */
+    uint64 last_round_before_birth_round_mode = 14;
+
+    /**
+     * The lowest judge generation before birth round mode was enabled, or -1 if birth round mode has not yet been enabled.
+     */
+    uint64 lowest_judge_generation_before_birth_round_mode = 15;
+}
+
+/**
+ * SoftwareVersion MUST contain the software version details of the platform entity.
+ */
+message SoftwareVersion {
+    /**
+     * The config version. MUST reflect the current configuration version.
+     */
+    uint32 config_version = 1;
+
+    /**
+     * The version of the HAPI module (Hedera API). MUST accurately reflect the Hedera API version.
+     */
+    proto.SemanticVersion hapi_version = 2;
+
+    /**
+     * The version of the services module. MUST accurately reflect the services version.
+     */
+    proto.SemanticVersion services_version = 3;
+}
+
+/**
+ * ConsensusSnapshot MUST store a snapshot of the consensus state for the current round.
+ */
+message ConsensusSnapshot {
+    /**
+     * The round number of this snapshot. MUST accurately reflect the round number.
+     */
+    uint64 round = 1;
+
+    /**
+     * The hashes of all the judges for this round, ordered by their creator ID. MUST be correctly ordered.
+     */
+    repeated bytes judge_hashes = 2;
+
+    /**
+     * For each non-ancient round, the minimum ancient indicator of the round's judges.
+     * MUST accurately reflect the minimum ancient indicator for each round.
+     */
+    repeated MinimumJudgeInfo minimum_judge_info_list = 3;
+
+    /**
+     * The consensus order of the next event that will reach consensus.
+     * MUST accurately represent the consensus order.
+     */
+    uint64 next_consensus_number = 4;
+
+    /**
+     * The consensus timestamp of this snapshot. MUST accurately reflect the consensus time.
+     */
+    proto.Timestamp consensus_timestamp = 5;
+}
+
+/**
+ * MinimumJudgeInfo MUST record the minimum ancient indicator for all judges in a particular round.
+ */
+message MinimumJudgeInfo {
+    /**
+     * The round number. MUST represent the correct round number.
+     */
+    uint64 round = 1;
+
+    /**
+     * The minimum ancient threshold for all judges for a given round.
+     * MUST accurately reflect the minimum threshold, whether generation-based or birth-round-based.
+     */
+    uint64 minimum_judge_ancient_threshold = 2;
+}