From c91db2a15befc0120319cc3c177869c188e81e63 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Wed, 8 May 2024 17:44:56 -0400 Subject: [PATCH 01/22] feat: 13135 Added PlatformState protobuf representation Signed-off-by: Ivan Malygin --- sdk/platform_state.proto | 151 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 sdk/platform_state.proto diff --git a/sdk/platform_state.proto b/sdk/platform_state.proto new file mode 100644 index 00000000..4612db0e --- /dev/null +++ b/sdk/platform_state.proto @@ -0,0 +1,151 @@ +syntax = "proto3"; + +package proto; + +option java_package = "com.hedera.hashgraph.sdk.proto"; +option java_multiple_files = true; + +import "basic_types.proto"; +import "timestamp.proto"; + +/** + * State managed and used by the platform. + */ +message PlatformState { + /** + * The address book for this round. + */ + NodeAddressBook addressBook = 1; + + /** + * The previous address book. A temporary workaround until dynamic address books are supported. + */ + NodeAddressBook previousAddressBook = 2; + + /** + * The round of this state. This state represents the handling of all transactions that have reached consensus in + * all previous rounds. All transactions from this round will eventually be applied to this state. The first state + * (genesis state) has a round of 0 because the first round is defined as round 1, and the genesis state is before + * any transactions are handled. + */ + int64 round = 3; + + /** + * The running event hash computed by the consensus event stream. This should be deleted once the consensus event + * stream is retired. + */ + bytes legacyRunningEventHash = 4; + + /** + * the consensus timestamp for this signed state + */ + Timestamp consensusTimestamp = 5; + /** + * The version of the application software that was responsible for creating this state. + */ + SoftwareVersion creationSoftwareVersion = 6; + + /** + * The epoch hash of this state. Updated every time emergency recovery is performed. + */ + bytes epochHash = 7; + /** + * The next epoch hash, used to update the epoch hash at the next round boundary. This field is not part of the hash + * and is not serialized. + */ + bytes nextEpochHash = 8; + + /** + * The number of non-ancient rounds. + */ + int32 roundsNonAncient = 9; + + /** + * A snapshot of the consensus state at the end of the round, used for restart/reconnect + */ + ConsensusSnapshot consensusSnapshot = 10; + + /** + * the time when the freeze starts + */ + Timestamp freezeTime = 11; + + /** + * the last time when a freeze was performed + */ + Timestamp lastFrozenTime = 12; + + /** + * Null if birth round migration has not yet happened, otherwise the software version that was first used when the + * birth round migration was performed. + */ + SoftwareVersion firstVersionInBirthRoundMode = 13; + + /** + * The last round before the birth round mode was enabled, or -1 if birth round mode has not yet been enabled. + */ + int64 lastRoundBeforeBirthRoundMode = 14; + + /** + * The lowest judge generation before the birth round mode was enabled, or -1 if birth round mode has not yet been + * enabled. + */ + int64 lowestJudgeGenerationBeforeBirthRoundMode = 15; +} + + +message SoftwareVersion { + /** + * The config version + */ + int32 configVersion = 1; + + /** + * The version of the HAPI module (Hedera API) + */ + SemanticVersion hapiVersion = 2; + + /** + * The version of the services module + */ + SemanticVersion servicesVersion = 3; +} + +message ConsensusSnapshot { + /** + * the round number of this snapshot + */ + int64 round = 1; + /** + * the hashes of all the judges for this round, ordered by their creator ID + */ + repeated bytes judgeHashes = 2; + /** + * for each non-ancient round, the minimum ancient indicator of the round's judges + */ + repeated MinimumJudgeInfo minimumJudgeInfoList = 3; + /** + * the consensus order of the next event that will reach consensus + */ + int64 nextConsensusNumber = 4; + /** + * the consensus time of this snapshot + */ + Timestamp consensusTimestamp = 5; +} + +/** + * Records the minimum ancient indicator for all judges in a particular round. + */ +message MinimumJudgeInfo { + /** + * The round number + */ + int64 round = 1; + /** + * the minimum ancient threshold for all judges for a given round. + * Will be a generation if the birth round migration has not yet happened, + * will be a birth round otherwise. + */ + int64 minimumJudgeAncientThreshold = 2; +} From 2cb4e0760a50e336a1dbdf8ba757d873fc925746 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Wed, 8 May 2024 18:19:49 -0400 Subject: [PATCH 02/22] Update sdk/platform_state.proto Signed-off-by: Ivan Malygin Co-authored-by: Joseph Sinclair <121976561+jsync-swirlds@users.noreply.github.com> --- sdk/platform_state.proto | 294 ++++++++++++++++++++++----------------- 1 file changed, 168 insertions(+), 126 deletions(-) diff --git a/sdk/platform_state.proto b/sdk/platform_state.proto index 4612db0e..9d7e247e 100644 --- a/sdk/platform_state.proto +++ b/sdk/platform_state.proto @@ -1,151 +1,193 @@ +/** + * # Platform Data + * A message that describes the current state of the platform entity. + * + * DESCRIPTION NEEDED + * + * ### Keywords + * 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 proto; +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.hashgraph.sdk.proto"; +option java_package = "com.hedera.hapi.platform.state.legacy"; +// <<>> This comment is special code for setting PBJ Compiler java package option java_multiple_files = true; import "basic_types.proto"; import "timestamp.proto"; /** - * State managed and used by the platform. + * SPECIFICATION REQUIRED */ message PlatformState { - /** - * The address book for this round. - */ - NodeAddressBook addressBook = 1; - - /** - * The previous address book. A temporary workaround until dynamic address books are supported. - */ - NodeAddressBook previousAddressBook = 2; - - /** - * The round of this state. This state represents the handling of all transactions that have reached consensus in - * all previous rounds. All transactions from this round will eventually be applied to this state. The first state - * (genesis state) has a round of 0 because the first round is defined as round 1, and the genesis state is before - * any transactions are handled. - */ - int64 round = 3; - - /** - * The running event hash computed by the consensus event stream. This should be deleted once the consensus event - * stream is retired. - */ - bytes legacyRunningEventHash = 4; - - /** - * the consensus timestamp for this signed state - */ - Timestamp consensusTimestamp = 5; - /** - * The version of the application software that was responsible for creating this state. - */ - SoftwareVersion creationSoftwareVersion = 6; - - /** - * The epoch hash of this state. Updated every time emergency recovery is performed. - */ - bytes epochHash = 7; - /** - * The next epoch hash, used to update the epoch hash at the next round boundary. This field is not part of the hash - * and is not serialized. - */ - bytes nextEpochHash = 8; - - /** - * The number of non-ancient rounds. - */ - int32 roundsNonAncient = 9; - - /** - * A snapshot of the consensus state at the end of the round, used for restart/reconnect - */ - ConsensusSnapshot consensusSnapshot = 10; - - /** - * the time when the freeze starts - */ - Timestamp freezeTime = 11; - - /** - * the last time when a freeze was performed - */ - Timestamp lastFrozenTime = 12; - - /** - * Null if birth round migration has not yet happened, otherwise the software version that was first used when the - * birth round migration was performed. - */ - SoftwareVersion firstVersionInBirthRoundMode = 13; - - /** - * The last round before the birth round mode was enabled, or -1 if birth round mode has not yet been enabled. - */ - int64 lastRoundBeforeBirthRoundMode = 14; - - /** - * The lowest judge generation before the birth round mode was enabled, or -1 if birth round mode has not yet been - * enabled. - */ - int64 lowestJudgeGenerationBeforeBirthRoundMode = 15; + /** + * The address book for this round. + */ + proto.NodeAddressBook address_book = 1; + + /** + * The previous address book. A temporary workaround until dynamic address books are supported. + */ + proto.NodeAddressBook previous_address_book = 2; + + /** + * The round of this state. This state represents the handling of all transactions that have reached consensus in + * all previous rounds. All transactions from this round will eventually be applied to this state. The first state + * (genesis state) has a round of 0 because the first round is defined as round 1, and the genesis state is before + * any transactions are handled. + */ + 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 + */ + proto.Timestamp consensus_timestamp = 5; + + /** + * The version of the application software that was responsible for creating this state. + */ + SoftwareVersion creation_software_version = 6; + + /** + * The epoch hash of this state. Updated every time 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 is not part of the hash + * and is not serialized. + */ + bytes next_epoch_hash = 8; + + /** + * The number of non-ancient rounds. + */ + uint32 rounds_non_ancient = 9; + + /** + * A snapshot of the consensus state at the end of the round, used for restart/reconnect + */ + ConsensusSnapshot consensus_snapshot = 10; + + /** + * the time when the freeze starts + */ + proto.Timestamp freeze_time = 11; + + /** + * the last time when a freeze was performed + */ + proto.Timestamp last_frozen_time = 12; + + /** + * Null if birth round migration has not yet happened, otherwise the software version that was first used when the + * birth round migration was performed. + */ + 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 the 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; } +/** + * SPECIFICATION REQUIRED + */ message SoftwareVersion { - /** - * The config version - */ - int32 configVersion = 1; - - /** - * The version of the HAPI module (Hedera API) - */ - SemanticVersion hapiVersion = 2; - - /** - * The version of the services module - */ - SemanticVersion servicesVersion = 3; + /** + * The config version + */ + uint32 config_version = 1; + + /** + * The version of the HAPI module (Hedera API) + */ + proto.SemanticVersion hapi_version = 2; + + /** + * The version of the services module + */ + proto.SemanticVersion services_version = 3; } +/** + * SPECIFICATION REQUIRED + */ message ConsensusSnapshot { - /** - * the round number of this snapshot - */ - int64 round = 1; - /** - * the hashes of all the judges for this round, ordered by their creator ID - */ - repeated bytes judgeHashes = 2; - /** - * for each non-ancient round, the minimum ancient indicator of the round's judges - */ - repeated MinimumJudgeInfo minimumJudgeInfoList = 3; - /** - * the consensus order of the next event that will reach consensus - */ - int64 nextConsensusNumber = 4; - /** - * the consensus time of this snapshot - */ - Timestamp consensusTimestamp = 5; + /** + * the round number of this snapshot + */ + uint64 round = 1; + + /** + * the hashes of all the judges for this round, ordered by their creator ID + */ + repeated bytes judge_hashes = 2; + + /** + * for each non-ancient round, the minimum ancient indicator of the round's judges + */ + repeated MinimumJudgeInfo minimum_judge_info_list = 3; + + /** + * the consensus order of the next event that will reach consensus + */ + uint64 next_consensus_number = 4; + + /** + * the consensus time of this snapshot + */ + proto.Timestamp consensus_timestamp = 5; } /** * Records the minimum ancient indicator for all judges in a particular round. */ message MinimumJudgeInfo { - /** - * The round number - */ - int64 round = 1; - /** - * the minimum ancient threshold for all judges for a given round. - * Will be a generation if the birth round migration has not yet happened, - * will be a birth round otherwise. - */ - int64 minimumJudgeAncientThreshold = 2; + /** + * The round number + */ + uint64 round = 1; + + /** + * the minimum ancient threshold for all judges for a given round. + * Will be a generation if the birth round migration has not yet happened, + * will be a birth round otherwise. + */ + uint64 minimum_judge_ancient_threshold = 2; } From 47b69d85b93a8335c780ebd6c65cf8d355d861da Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Wed, 8 May 2024 19:16:52 -0400 Subject: [PATCH 03/22] Moved platform_state.proto to platform/state directory. Updated the documentation according to the guidelines. Moved platform_state.proto to platform/state directory. Updated the documentation according to the guidelines. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 261 ++++++++++++++++++++++++++++ sdk/platform_state.proto | 193 -------------------- 2 files changed, 261 insertions(+), 193 deletions(-) create mode 100644 platform/state/platform_state.proto delete mode 100644 sdk/platform_state.proto diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto new file mode 100644 index 00000000..65bc9148 --- /dev/null +++ b/platform/state/platform_state.proto @@ -0,0 +1,261 @@ +/** + * PlatformState + * + * Describes the current state of the platform entity. + * + * The state MUST contain address books, round information, + * event hashes, consensus snapshots, and software versions. + * The state SHALL accurately represent the latest round's + * consensus.
+ * MUST ensure consistency and provide 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"; +// <<>> 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. + * + * MUST represent the handling of all transactions reaching + * consensus in all previous rounds.
+ * The first state (genesis state) SHALL have 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.
+ * SHOULD be deleted once the consensus event stream is retired. + */ + bytes legacy_running_event_hash = 4; + + /** + * The consensus timestamp for this signed state. + * + * MUST represent the consensus of the first transaction in this round. + */ + proto.Timestamp consensus_timestamp = 5; + + /** + * The version of the application software. + * + * MUST accurately reflect the software version that created this state. + */ + 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.
+ * 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 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 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, 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. + * + * MUST be -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. + * + * MUST be -1 if birth round mode has not yet been enabled. + */ + uint64 lowest_judge_generation_before_birth_round_mode = 15; +} + + +/** + * SoftwareVersion + * + * Contains 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 + * + * Stores a snapshot of the consensus state for the current round. + * + * SHALL accurately represent consensus data necessary for restart + * and reconnect. + */ +message ConsensusSnapshot { + /** + * The round number of this snapshot. + * + * MUST accurately reflect the round number. + */ + uint64 round = 1; + + /** + * The hashes of all judges for this round. + * + * Ordered by their creator ID. MUST be correctly ordered. + */ + repeated bytes judge_hashes = 2; + + /** + * Minimum ancient indicators for non-ancient rounds. + * + * MUST reflect the minimum ancient indicator of each round's judges. + */ + repeated MinimumJudgeInfo minimum_judge_info_list = 3; + + /** + * The consensus order of the next event to 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 + * + * Records the minimum ancient indicator for all judges in a round. + */ +message MinimumJudgeInfo { + /** + * The round number. + * + * MUST represent the correct round number. + */ + uint64 round = 1; + + /** + * Minimum ancient threshold for all judges in a round. + * + * MUST reflect the minimum threshold accurately, whether + * generation-based or birth-round-based. + */ + uint64 minimum_judge_ancient_threshold = 2; +} diff --git a/sdk/platform_state.proto b/sdk/platform_state.proto deleted file mode 100644 index 9d7e247e..00000000 --- a/sdk/platform_state.proto +++ /dev/null @@ -1,193 +0,0 @@ -/** - * # Platform Data - * A message that describes the current state of the platform entity. - * - * DESCRIPTION NEEDED - * - * ### Keywords - * 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"; -// <<>> This comment is special code for setting PBJ Compiler java package -option java_multiple_files = true; - -import "basic_types.proto"; -import "timestamp.proto"; - -/** - * SPECIFICATION REQUIRED - */ -message PlatformState { - /** - * The address book for this round. - */ - proto.NodeAddressBook address_book = 1; - - /** - * The previous address book. A temporary workaround until dynamic address books are supported. - */ - proto.NodeAddressBook previous_address_book = 2; - - /** - * The round of this state. This state represents the handling of all transactions that have reached consensus in - * all previous rounds. All transactions from this round will eventually be applied to this state. The first state - * (genesis state) has a round of 0 because the first round is defined as round 1, and the genesis state is before - * any transactions are handled. - */ - 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 - */ - proto.Timestamp consensus_timestamp = 5; - - /** - * The version of the application software that was responsible for creating this state. - */ - SoftwareVersion creation_software_version = 6; - - /** - * The epoch hash of this state. Updated every time 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 is not part of the hash - * and is not serialized. - */ - bytes next_epoch_hash = 8; - - /** - * The number of non-ancient rounds. - */ - uint32 rounds_non_ancient = 9; - - /** - * A snapshot of the consensus state at the end of the round, used for restart/reconnect - */ - ConsensusSnapshot consensus_snapshot = 10; - - /** - * the time when the freeze starts - */ - proto.Timestamp freeze_time = 11; - - /** - * the last time when a freeze was performed - */ - proto.Timestamp last_frozen_time = 12; - - /** - * Null if birth round migration has not yet happened, otherwise the software version that was first used when the - * birth round migration was performed. - */ - 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 the 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; -} - - -/** - * SPECIFICATION REQUIRED - */ -message SoftwareVersion { - /** - * The config version - */ - uint32 config_version = 1; - - /** - * The version of the HAPI module (Hedera API) - */ - proto.SemanticVersion hapi_version = 2; - - /** - * The version of the services module - */ - proto.SemanticVersion services_version = 3; -} - -/** - * SPECIFICATION REQUIRED - */ -message ConsensusSnapshot { - /** - * the round number of this snapshot - */ - uint64 round = 1; - - /** - * the hashes of all the judges for this round, ordered by their creator ID - */ - repeated bytes judge_hashes = 2; - - /** - * for each non-ancient round, the minimum ancient indicator of the round's judges - */ - repeated MinimumJudgeInfo minimum_judge_info_list = 3; - - /** - * the consensus order of the next event that will reach consensus - */ - uint64 next_consensus_number = 4; - - /** - * the consensus time of this snapshot - */ - proto.Timestamp consensus_timestamp = 5; -} - -/** - * Records the minimum ancient indicator for all judges in a particular round. - */ -message MinimumJudgeInfo { - /** - * The round number - */ - uint64 round = 1; - - /** - * the minimum ancient threshold for all judges for a given round. - * Will be a generation if the birth round migration has not yet happened, - * will be a birth round otherwise. - */ - uint64 minimum_judge_ancient_threshold = 2; -} From da7a41758a7c4ca82397c9a8c2583f360d843e6e Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 9 May 2024 16:37:05 -0400 Subject: [PATCH 04/22] Updated type of `lowest_judge_generation_before_birth_round_mode` to int64 as it can be negative. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 65bc9148..9799f72d 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -159,7 +159,7 @@ message PlatformState { * * MUST be -1 if birth round mode has not yet been enabled. */ - uint64 lowest_judge_generation_before_birth_round_mode = 15; + int64 lowest_judge_generation_before_birth_round_mode = 15; } From 9ab437a6d998419c57064f91708379cd67512bf7 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 9 May 2024 18:11:14 -0400 Subject: [PATCH 05/22] Added platform-specific `AddressBook`. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 116 +++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 2 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 9799f72d..8e32e4af 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -53,7 +53,7 @@ message PlatformState { * The address book MUST represent the latest consensus view of node * addresses. */ - proto.NodeAddressBook address_book = 1; + AddressBook address_book = 1; /** * The previous address book. @@ -62,7 +62,7 @@ message PlatformState { * If present, the previous address book SHOULD reflect the address * book from the preceding round. */ - proto.NodeAddressBook previous_address_book = 2; + AddressBook previous_address_book = 2; /** * The round of this state. @@ -259,3 +259,115 @@ message MinimumJudgeInfo { */ uint64 minimum_judge_ancient_threshold = 2; } +/** + * AddressBook + * + * Contains the address of every known member of the swirld.
+ * Getters SHALL be public, and setters SHALL NOT be public, making it read-only + * for apps.
+ * When `enableEventStreaming` is set to true, the memo field MUST be required + * and SHOULD be unique. + */ +message AddressBook { + /** + * The round when this address book was created. + */ + int64 round = 1; + + /** + * The node ID of the next address that can be added. + * + * MUST be greater than or equal to this value. + *
INVARIANT: `next_node_id` SHALL be greater than the node IDs + * of all addresses in the address book. + */ + NodeId next_node_id = 2; + + /** + * A list of all the addresses. + */ + repeated Address addresses = 3; +} + +/** + * Address + * + * Represents one address in an address book, including all the info about a member. + * + */ +message Address { + /** + * The ID of this member. + * + * SHALL be agreed upon by all members. + */ + NodeId id = 1; + + /** + * The nickname this member uses to refer to another member. + */ + string nickname = 2; + + /** + * The name that a member uses to refer to themselves. + */ + string self_name = 3; + + /** + * The member's nonnegative weight. + * + * SHALL be used for weighted voting. + */ + uint64 weight = 4; + + /** + * The IP or DNS name on the local network. + */ + string hostname_internal = 5; + + /** + * Port used on the local network. + */ + uint32 port_internal = 6; + + /** + * The IP or DNS name outside the NAT firewall. + */ + string hostname_external = 7; + + /** + * Port used outside the NAT firewall. + */ + uint32 port_external = 8; + + /** + * The signing x509 certificate of the member. + * + * SHALL contain the public key used for signing. + */ + bytes sig_cert = 9; + + /** + * The agreement x509 certificate of the member. + * + * SHALL be used for establishing TLS connections. + */ + bytes agree_cert = 10; + + /** + * A string that provides additional information about the node. + */ + string memo = 11; +} + +/** + * NodeId + * + * Uniquely identifies a Swirlds node. + */ +message NodeId { + /** + * The ID number. + */ + uint64 id = 1; +} \ No newline at end of file From 3520390cb4aa79310845947d8470371312f30f77 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Fri, 10 May 2024 10:57:19 -0400 Subject: [PATCH 06/22] Update platform/state/platform_state.proto Signed-off-by: Ivan Malygin Co-authored-by: Joseph Sinclair <121976561+jsync-swirlds@users.noreply.github.com> --- platform/state/platform_state.proto | 294 +++++++++++++++------------- 1 file changed, 156 insertions(+), 138 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 8e32e4af..e6444bad 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -1,14 +1,6 @@ /** - * PlatformState - * - * Describes the current state of the platform entity. - * - * The state MUST contain address books, round information, - * event hashes, consensus snapshots, and software versions. - * The state SHALL accurately represent the latest round's - * consensus.
- * MUST ensure consistency and provide critical data for restarts - * and reconnects. + * # 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 @@ -43,331 +35,357 @@ 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: + * The current state of platform consensus.
+ * This message stores the current consensus data for the platform + * in network state. + * + * The platform state SHALL represent the latest round's consensus.
+ * This data SHALL be used to ensure consistency and provide critical data for + * restart and reconnect. */ message PlatformState { /** - * The address book for this round. - * - * The address book MUST represent the latest consensus view of node - * addresses. + * An address book for this round. + *

+ * This SHALL be the latest network-consensus view of consensus nodes. */ AddressBook 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. + * A previous address book. + *

+ * If present, the previous address book SHALL be the address book from the + * most recent preceding round. + *

+ * This is a temporary workaround until dynamic address books are supported. */ AddressBook previous_address_book = 2; /** - * The round of this state. - * - * MUST represent the handling of all transactions reaching - * consensus in all previous rounds.
- * The first state (genesis state) SHALL have a round of 0, because - * the first round is defined as round 1. + * A consensus round.
+ * The round represented by this state. + *

+ * This message SHALL represent the network state after handling of all + * transactions reaching consensus in all previous rounds.
+ * The first state (genesis state) SHALL have a round of 0.
+ * The first round to handle transactions is defined as round `1`. */ uint64 round = 3; /** - * The running event hash. - * - * Computed by the consensus event stream.
- * SHOULD be deleted once the consensus event stream is retired. + * A running event hash.
+ * This is computed by the consensus event stream. + *

+ * This will be _deprecated_ once the consensus event stream is retired. */ bytes legacy_running_event_hash = 4; /** - * The consensus timestamp for this signed state. - * - * MUST represent the consensus of the first transaction in this round. + * A consensus timestamp for this state. + *

+ * This SHALL be the consensus timestamp of the first transaction in + * the current round. */ proto.Timestamp consensus_timestamp = 5; /** - * The version of the application software. - * - * MUST accurately reflect the software version that created this state. + * A version describing the current version of application software. + *

+ * This SHALL be the software version that created this state. */ SoftwareVersion creation_software_version = 6; /** - * The epoch hash of this state. - * - * MUST be updated whenever emergency recovery is performed. + * A SHA-384 hash that is the "epoch" hash of this state. + *

+ * This SHALL 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.
- * SHOULD NOT be part of the hash and MUST NOT be serialized. + * A SHA-384 hash that will be the next "epoch" hash. + *

+ * This SHALL be used to update the epoch hash at the next round boundary.
+ * This SHALL NOT be part of the hash and SHALL NOT be serialized. */ bytes next_epoch_hash = 8; /** - * The number of non-ancient rounds. - * - * MUST accurately reflect the count of rounds considered non-ancient. + * A number of non-ancient rounds. + *

+ * This SHALL be the count of rounds 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. + *

+ * This SHALL be used for restart/reconnect. */ ConsensusSnapshot consensus_snapshot = 10; /** - * The time when the freeze starts. - * - * If null, a freeze SHOULD NOT be scheduled. + * A timestamp for the next scheduled time when a freeze will start. + *

+ * If a freeze is not scheduled, this SHALL NOT be set. */ proto.Timestamp freeze_time = 11; /** - * The last time a freeze was performed. - * - * If null, there has never been a freeze. + * A timestamp for the last time a freeze was performed.
+ * If not set, there has never been a freeze. */ proto.Timestamp last_frozen_time = 12; /** - * Null if birth round migration has not yet happened. - * - * Otherwise, MUST represent the software version that first - * enabled birth round mode. + * A consensus node software version.
+ * The software version that enabled birth round mode. + *

+ * This SHALL be unset if birth round migration has not yet happened.
+ * Otherwise, this SHALL be the _first_ software version that enabled birth + * round mode. */ SoftwareVersion first_version_in_birth_round_mode = 13; /** + * A consensus round.
* The last round before the birth round mode was enabled. - * - * MUST be -1 if birth round mode has not yet been enabled. + *

+ * This SHALL be -1 if birth round mode has not yet been enabled. */ - uint64 last_round_before_birth_round_mode = 14; + int64 last_round_before_birth_round_mode = 14; /** + * A consensus generation.
* The lowest judge generation before birth round mode was enabled. - * - * MUST be -1 if birth round mode has not yet been enabled. + *

+ * This SHALL be -1 if birth round mode has not yet been enabled. */ int64 lowest_judge_generation_before_birth_round_mode = 15; } /** - * SoftwareVersion + * A consensus node software version. * - * Contains the software version details of the platform entity. + * This message records version information for configuration, the Hedera + * API, and the "Services" subsystems. */ message SoftwareVersion { /** - * The config version. - * - * MUST reflect the current configuration version. + * A single numeric version.
+ * This is the current configuration version read on node startup. */ uint32 config_version = 1; /** - * The version of the HAPI module (Hedera API). - * - * MUST accurately reflect the Hedera API version. + * A semantic version entry.
+ * This is the version of the HAPI module (Hedera API). */ proto.SemanticVersion hapi_version = 2; /** - * The version of the services module. - * - * MUST accurately reflect the services version. + * A semantic version entry.
+ * This is the version of the services module. */ proto.SemanticVersion services_version = 3; } /** - * ConsensusSnapshot + * A consensus snapshot.
+ * This is a snapshot of the consensus state for a particular round. * - * Stores a snapshot of the consensus state for the current round. - * - * SHALL accurately represent consensus data necessary for restart + * This message SHALL record consensus data necessary for restart * and reconnect. */ message ConsensusSnapshot { /** + * A consensus round.
* The round number of this snapshot. - * - * MUST accurately reflect the round number. */ uint64 round = 1; /** + * A list of SHA-384 hash values.
* The hashes of all judges for this round. - * - * Ordered by their creator ID. MUST be correctly ordered. + *

+ * This list SHALL be ordered by creator ID.
+ * This list MUST be deterministically ordered. */ repeated bytes judge_hashes = 2; /** - * Minimum ancient indicators for non-ancient rounds. - * - * MUST reflect the minimum ancient indicator of each round's judges. + * A list of minimum judge information entries.
+ * These are "minimum ancient" entries for non-ancient rounds. */ repeated MinimumJudgeInfo minimum_judge_info_list = 3; /** + * A single consensus number.
* The consensus order of the next event to reach consensus. - * - * MUST accurately represent the consensus order. */ uint64 next_consensus_number = 4; /** + * A "consensus" timestamp.
* The consensus timestamp of this snapshot. - * - * MUST accurately reflect the consensus time. + *

+ * This SHALL be a consensus value and MAY NOT correspond to an actual + * "wall clock" timestamp.
+ * Consensus Timestamps SHALL always increase. */ proto.Timestamp consensus_timestamp = 5; } - /** - * MinimumJudgeInfo - * - * Records the minimum ancient indicator for all judges in a round. + * Minimum ancient threshold information for round judges. + * This message records the minimum ancient threshold agreed by all judges in + * a round. */ message MinimumJudgeInfo { /** - * The round number. - * - * MUST represent the correct round number. + * A consensus round.
+ * The round this judge information applies to. */ uint64 round = 1; /** - * Minimum ancient threshold for all judges in a round. - * - * MUST reflect the minimum threshold accurately, whether + * Minimum ancient threshold for all judges in the round. + *

+ * This SHALL reflect the relevant minimum threshold, whether * generation-based or birth-round-based. */ uint64 minimum_judge_ancient_threshold = 2; } + /** - * AddressBook - * - * Contains the address of every known member of the swirld.
- * Getters SHALL be public, and setters SHALL NOT be public, making it read-only - * for apps.
- * When `enableEventStreaming` is set to true, the memo field MUST be required - * and SHOULD be unique. + * A network address book.
+ * The address book records the address of every known consensus node that + * participates in the network, including `0 weight` nodes.
*/ message AddressBook { /** + * A consensus round.
* The round when this address book was created. */ int64 round = 1; /** * The node ID of the next address that can be added. - * - * MUST be greater than or equal to this value. - *
INVARIANT: `next_node_id` SHALL be greater than the node IDs - * of all addresses in the address book. + *

+ * The next node identifier assigned SHALL be equal to this value.
+ * All existing node identifiers SHALL be strictly less than this value.
*/ NodeId next_node_id = 2; /** - * A list of all the addresses. + * A list of all consensus node addresses. + *

+ * This list SHALL NOT be empty. + * If a consensus node is not in this list it SHALL NOT participate in the + * network. */ repeated Address addresses = 3; } /** - * Address - * - * Represents one address in an address book, including all the info about a member. + * A single network address. + * This is one address in the network address book, including all required + * information to include that consensus node in the consensus gossip. * + * ### Implementation Detail + * When `enableEventStreaming` is set to true, the memo field is REQUIRED + * and MUST be unique. */ message Address { /** * The ID of this member. - * - * SHALL be agreed upon by all members. + *

+ * This identifier SHALL be agreed upon by all consensus nodes. */ NodeId id = 1; /** - * The nickname this member uses to refer to another member. + * The nickname this consensus node uses to refer to another consensus node. */ string nickname = 2; /** - * The name that a member uses to refer to themselves. + * The name that a consensus node uses to refer to themselves. */ string self_name = 3; /** - * The member's nonnegative weight. - * - * SHALL be used for weighted voting. + * A consensus weight.
+ * This value is the relative weight for this consensus node in the + * consensus voting algorithm. */ uint64 weight = 4; /** - * The IP or DNS name on the local network. + * A string network address.
+ * This value is the hostname assigned on the "internal" network + * interface behind any network firewalls, protocol gateways, or + * DNS translations. + *

+ * This value SHALL be either a FQDN host name or an IPv4 address. */ string hostname_internal = 5; /** - * Port used on the local network. + * Network port number.
+ * This value is the "translated" port number assigned on the "internal" + * network behind any network firewalls or other address translations. + *

+ * This value SHALL be between 1 and 65535. */ uint32 port_internal = 6; /** - * The IP or DNS name outside the NAT firewall. + * A string network address.
+ * This value is the hostname assigned on the "public" network + * interface visible to the general internet. + *

+ * This value SHALL be either a FQDN host name or an IPv4 address. */ string hostname_external = 7; /** - * Port used outside the NAT firewall. + * Network port number.
+ * This value is the port number visible to the general internet. + *

+ * This value SHALL be between 1 and 65535. */ uint32 port_external = 8; /** - * The signing x509 certificate of the member. - * - * SHALL contain the public key used for signing. + * The signing x509 certificate of the consensus node. + *

+ * This SHALL provide the public key used for signing. */ bytes sig_cert = 9; /** - * The agreement x509 certificate of the member. - * - * SHALL be used for establishing TLS connections. + * The agreement x509 certificate of the consensus node. + *

+ * This SHALL be used for establishing TLS connections. */ bytes agree_cert = 10; /** - * A string that provides additional information about the node. + * A string that provides additional information about this consensus node. */ string memo = 11; } /** - * NodeId - * - * Uniquely identifies a Swirlds node. + * A consensus node identifier.
+ * This value uniquely identifies a single consensus node within the network. */ message NodeId { /** - * The ID number. + * A numeric identifier. */ uint64 id = 1; -} \ No newline at end of file +} From 05d145a5f93749a725a86a120f38954682a3f1c3 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Tue, 11 Jun 2024 15:49:58 -0400 Subject: [PATCH 07/22] Addressed review comments. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 121 ++++++++++------------------ 1 file changed, 44 insertions(+), 77 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index e6444bad..f773788a 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -44,23 +44,6 @@ import "timestamp.proto"; * restart and reconnect. */ message PlatformState { - /** - * An address book for this round. - *

- * This SHALL be the latest network-consensus view of consensus nodes. - */ - AddressBook address_book = 1; - - /** - * A previous address book. - *

- * If present, the previous address book SHALL be the address book from the - * most recent preceding round. - *

- * This is a temporary workaround until dynamic address books are supported. - */ - AddressBook previous_address_book = 2; - /** * A consensus round.
* The round represented by this state. @@ -70,15 +53,7 @@ message PlatformState { * The first state (genesis state) SHALL have a round of 0.
* The first round to handle transactions is defined as round `1`. */ - uint64 round = 3; - - /** - * A running event hash.
- * This is computed by the consensus event stream. - *

- * This will be _deprecated_ once the consensus event stream is retired. - */ - bytes legacy_running_event_hash = 4; + uint64 round = 1; /** * A consensus timestamp for this state. @@ -86,56 +61,41 @@ message PlatformState { * This SHALL be the consensus timestamp of the first transaction in * the current round. */ - proto.Timestamp consensus_timestamp = 5; + proto.Timestamp consensus_timestamp = 3; /** * A version describing the current version of application software. *

* This SHALL be the software version that created this state. */ - SoftwareVersion creation_software_version = 6; - - /** - * A SHA-384 hash that is the "epoch" hash of this state. - *

- * This SHALL be updated whenever emergency recovery is performed. - */ - bytes epoch_hash = 7; - - /** - * A SHA-384 hash that will be the next "epoch" hash. - *

- * This SHALL be used to update the epoch hash at the next round boundary.
- * This SHALL NOT be part of the hash and SHALL NOT be serialized. - */ - bytes next_epoch_hash = 8; + SoftwareVersion creation_software_version = 4; /** * A number of non-ancient rounds. *

* This SHALL be the count of rounds considered non-ancient. */ - uint32 rounds_non_ancient = 9; + uint32 rounds_non_ancient = 5; /** * A snapshot of the consensus state at the end of the round. *

* This SHALL be used for restart/reconnect. */ - ConsensusSnapshot consensus_snapshot = 10; + ConsensusSnapshot consensus_snapshot = 6; /** * A timestamp for the next scheduled time when a freeze will start. *

* If a freeze is not scheduled, this SHALL NOT be set. */ - proto.Timestamp freeze_time = 11; + proto.Timestamp freeze_time = 7; /** * A timestamp for the last time a freeze was performed.
* If not set, there has never been a freeze. */ - proto.Timestamp last_frozen_time = 12; + proto.Timestamp last_frozen_time = 8; /** * A consensus node software version.
@@ -145,7 +105,7 @@ message PlatformState { * Otherwise, this SHALL be the _first_ software version that enabled birth * round mode. */ - SoftwareVersion first_version_in_birth_round_mode = 13; + SoftwareVersion first_version_in_birth_round_mode = 9; /** * A consensus round.
@@ -153,7 +113,17 @@ message PlatformState { *

* This SHALL be -1 if birth round mode has not yet been enabled. */ - int64 last_round_before_birth_round_mode = 14; + int64 last_round_before_birth_round_mode = 10; + + // Fields below are to be deprecated in the foreseeable future. + + /** + * A running event hash.
+ * This is computed by the consensus event stream. + *

+ * This will be _deprecated_ once the consensus event stream is retired. + */ + bytes legacy_running_event_hash = 10000; /** * A consensus generation.
@@ -161,7 +131,7 @@ message PlatformState { *

* This SHALL be -1 if birth round mode has not yet been enabled. */ - int64 lowest_judge_generation_before_birth_round_mode = 15; + int64 lowest_judge_generation_before_birth_round_mode = 10001; } @@ -264,7 +234,7 @@ message MinimumJudgeInfo { * The address book records the address of every known consensus node that * participates in the network, including `0 weight` nodes.
*/ -message AddressBook { +message Roster { /** * A consensus round.
* The round when this address book was created. @@ -306,22 +276,12 @@ message Address { */ NodeId id = 1; - /** - * The nickname this consensus node uses to refer to another consensus node. - */ - string nickname = 2; - - /** - * The name that a consensus node uses to refer to themselves. - */ - string self_name = 3; - /** * A consensus weight.
* This value is the relative weight for this consensus node in the * consensus voting algorithm. */ - uint64 weight = 4; + uint64 weight = 3; /** * A string network address.
@@ -331,7 +291,7 @@ message Address { *

* This value SHALL be either a FQDN host name or an IPv4 address. */ - string hostname_internal = 5; + string hostname_internal = 4; /** * Network port number.
@@ -340,7 +300,7 @@ message Address { *

* This value SHALL be between 1 and 65535. */ - uint32 port_internal = 6; + uint32 port_internal = 5; /** * A string network address.
@@ -349,7 +309,7 @@ message Address { *

* This value SHALL be either a FQDN host name or an IPv4 address. */ - string hostname_external = 7; + string hostname_external = 6; /** * Network port number.
@@ -357,26 +317,33 @@ message Address { *

* This value SHALL be between 1 and 65535. */ - uint32 port_external = 8; + uint32 port_external = 7; /** * The signing x509 certificate of the consensus node. *

* This SHALL provide the public key used for signing. */ - bytes sig_cert = 9; + bytes sig_cert = 8; - /** - * The agreement x509 certificate of the consensus node. - *

- * This SHALL be used for establishing TLS connections. - */ - bytes agree_cert = 10; + // Fields below are to be deprecated in the foreseeable future. + + /** + * The name that a consensus node uses to refer to themselves. + */ + string self_name = 10000; + + + /** + * The nickname this consensus node uses to refer to another consensus node. + */ + string nickname = 10001; + + /** + * A string that provides additional information about this consensus node. + */ + string memo = 10002; - /** - * A string that provides additional information about this consensus node. - */ - string memo = 11; } /** From 097ac74550ba4b6dc834caaa2a70e53d0674a3b7 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Wed, 12 Jun 2024 15:17:21 -0400 Subject: [PATCH 08/22] Removed Roster, Address and NodeId as they will be a part of another PR. Fixed `PlatformState` indices. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 144 ++-------------------------- 1 file changed, 8 insertions(+), 136 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index f773788a..57a891fa 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -61,41 +61,41 @@ message PlatformState { * This SHALL be the consensus timestamp of the first transaction in * the current round. */ - proto.Timestamp consensus_timestamp = 3; + proto.Timestamp consensus_timestamp = 2; /** * A version describing the current version of application software. *

* This SHALL be the software version that created this state. */ - SoftwareVersion creation_software_version = 4; + SoftwareVersion creation_software_version = 3; /** * A number of non-ancient rounds. *

* This SHALL be the count of rounds considered non-ancient. */ - uint32 rounds_non_ancient = 5; + uint32 rounds_non_ancient = 4; /** * A snapshot of the consensus state at the end of the round. *

* This SHALL be used for restart/reconnect. */ - ConsensusSnapshot consensus_snapshot = 6; + ConsensusSnapshot consensus_snapshot = 5; /** * A timestamp for the next scheduled time when a freeze will start. *

* If a freeze is not scheduled, this SHALL NOT be set. */ - proto.Timestamp freeze_time = 7; + proto.Timestamp freeze_time = 6; /** * A timestamp for the last time a freeze was performed.
* If not set, there has never been a freeze. */ - proto.Timestamp last_frozen_time = 8; + proto.Timestamp last_frozen_time = 7; /** * A consensus node software version.
@@ -105,7 +105,7 @@ message PlatformState { * Otherwise, this SHALL be the _first_ software version that enabled birth * round mode. */ - SoftwareVersion first_version_in_birth_round_mode = 9; + SoftwareVersion first_version_in_birth_round_mode = 8; /** * A consensus round.
@@ -113,7 +113,7 @@ message PlatformState { *

* This SHALL be -1 if birth round mode has not yet been enabled. */ - int64 last_round_before_birth_round_mode = 10; + int64 last_round_before_birth_round_mode = 9; // Fields below are to be deprecated in the foreseeable future. @@ -228,131 +228,3 @@ message MinimumJudgeInfo { */ uint64 minimum_judge_ancient_threshold = 2; } - -/** - * A network address book.
- * The address book records the address of every known consensus node that - * participates in the network, including `0 weight` nodes.
- */ -message Roster { - /** - * A consensus round.
- * The round when this address book was created. - */ - int64 round = 1; - - /** - * The node ID of the next address that can be added. - *

- * The next node identifier assigned SHALL be equal to this value.
- * All existing node identifiers SHALL be strictly less than this value.
- */ - NodeId next_node_id = 2; - - /** - * A list of all consensus node addresses. - *

- * This list SHALL NOT be empty. - * If a consensus node is not in this list it SHALL NOT participate in the - * network. - */ - repeated Address addresses = 3; -} - -/** - * A single network address. - * This is one address in the network address book, including all required - * information to include that consensus node in the consensus gossip. - * - * ### Implementation Detail - * When `enableEventStreaming` is set to true, the memo field is REQUIRED - * and MUST be unique. - */ -message Address { - /** - * The ID of this member. - *

- * This identifier SHALL be agreed upon by all consensus nodes. - */ - NodeId id = 1; - - /** - * A consensus weight.
- * This value is the relative weight for this consensus node in the - * consensus voting algorithm. - */ - uint64 weight = 3; - - /** - * A string network address.
- * This value is the hostname assigned on the "internal" network - * interface behind any network firewalls, protocol gateways, or - * DNS translations. - *

- * This value SHALL be either a FQDN host name or an IPv4 address. - */ - string hostname_internal = 4; - - /** - * Network port number.
- * This value is the "translated" port number assigned on the "internal" - * network behind any network firewalls or other address translations. - *

- * This value SHALL be between 1 and 65535. - */ - uint32 port_internal = 5; - - /** - * A string network address.
- * This value is the hostname assigned on the "public" network - * interface visible to the general internet. - *

- * This value SHALL be either a FQDN host name or an IPv4 address. - */ - string hostname_external = 6; - - /** - * Network port number.
- * This value is the port number visible to the general internet. - *

- * This value SHALL be between 1 and 65535. - */ - uint32 port_external = 7; - - /** - * The signing x509 certificate of the consensus node. - *

- * This SHALL provide the public key used for signing. - */ - bytes sig_cert = 8; - - // Fields below are to be deprecated in the foreseeable future. - - /** - * The name that a consensus node uses to refer to themselves. - */ - string self_name = 10000; - - - /** - * The nickname this consensus node uses to refer to another consensus node. - */ - string nickname = 10001; - - /** - * A string that provides additional information about this consensus node. - */ - string memo = 10002; - -} - -/** - * A consensus node identifier.
- * This value uniquely identifies a single consensus node within the network. - */ -message NodeId { - /** - * A numeric identifier. - */ - uint64 id = 1; -} From 2455e326891db50bca0f035c05034247b93770b0 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Wed, 12 Jun 2024 16:10:02 -0400 Subject: [PATCH 09/22] Update platform/state/platform_state.proto Signed-off-by: Ivan Malygin Co-authored-by: Joseph Sinclair <121976561+jsync-swirlds@users.noreply.github.com> --- platform/state/platform_state.proto | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 57a891fa..4200dd48 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -51,7 +51,7 @@ message PlatformState { * This message SHALL represent the network state after handling of all * transactions reaching consensus in all previous rounds.
* The first state (genesis state) SHALL have a round of 0.
- * The first round to handle transactions is defined as round `1`. + * The first round to handle transactions SHALL be round `1`. */ uint64 round = 1; @@ -87,7 +87,9 @@ message PlatformState { /** * A timestamp for the next scheduled time when a freeze will start. *

- * If a freeze is not scheduled, this SHALL NOT be set. + * If a freeze is not scheduled, this SHALL NOT be set.
+ * If a freeze is currently scheduled, this MUST be set, and MUST + * match the timestamp requested for that freeze. */ proto.Timestamp freeze_time = 6; @@ -102,8 +104,8 @@ message PlatformState { * The software version that enabled birth round mode. *

* This SHALL be unset if birth round migration has not yet happened.
- * Otherwise, this SHALL be the _first_ software version that enabled birth - * round mode. + * If birth round migration is complete, this SHALL be the _first_ software + * version that enabled birth round mode. */ SoftwareVersion first_version_in_birth_round_mode = 8; @@ -209,7 +211,7 @@ message ConsensusSnapshot { } /** - * Minimum ancient threshold information for round judges. + * Minimum ancient threshold information for round judges.
* This message records the minimum ancient threshold agreed by all judges in * a round. */ From 44fa0028fcfd1043abed1fe5319e6261d3f2a5cd Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Wed, 12 Jun 2024 16:52:13 -0400 Subject: [PATCH 10/22] Addressed review comments: Added `deprecated` tag amd changed the type of `last_round_before_birth_round_mode` and `lowest_judge_generation_before_birth_round_mode` to `uint64` Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 4200dd48..8ddd3d62 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -113,9 +113,9 @@ message PlatformState { * A consensus round.
* The last round before the birth round mode was enabled. *

- * This SHALL be -1 if birth round mode has not yet been enabled. + * This SHALL be `MAX_UNSIGNED` if birth round mode has not yet been enabled. */ - int64 last_round_before_birth_round_mode = 9; + uint64 last_round_before_birth_round_mode = 9; // Fields below are to be deprecated in the foreseeable future. @@ -125,15 +125,15 @@ message PlatformState { *

* This will be _deprecated_ once the consensus event stream is retired. */ - bytes legacy_running_event_hash = 10000; + bytes legacy_running_event_hash = 10000 [deprecated = true]; /** * A consensus generation.
* The lowest judge generation before birth round mode was enabled. *

- * This SHALL be -1 if birth round mode has not yet been enabled. + * This SHALL be `MAX_UNSIGNED` if birth round mode has not yet been enabled. */ - int64 lowest_judge_generation_before_birth_round_mode = 10001; + uint64 lowest_judge_generation_before_birth_round_mode = 10001 [deprecated = true]; } From 131b668e79bfdbd644d33c022dd72f72372188cc Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 13 Jun 2024 10:59:36 -0400 Subject: [PATCH 11/22] Update platform/state/platform_state.proto Signed-off-by: Ivan Malygin Co-authored-by: Joseph Sinclair <121976561+jsync-swirlds@users.noreply.github.com> --- platform/state/platform_state.proto | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 8ddd3d62..5c32f346 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -123,7 +123,8 @@ message PlatformState { * A running event hash.
* This is computed by the consensus event stream. *

- * This will be _deprecated_ once the consensus event stream is retired. + * This will be _removed_ and the field number reserved once the consensus + * event stream is retired. */ bytes legacy_running_event_hash = 10000 [deprecated = true]; From 8a331b63c0d2b0f58ab54d31ec0a80621a943aa3 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 13 Jun 2024 12:00:53 -0400 Subject: [PATCH 12/22] Addressed review comments - removed `SoftwareVersion` message and replaced it with `SemanticVersion` Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 33 +++-------------------------- 1 file changed, 3 insertions(+), 30 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 5c32f346..50008b0a 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -68,7 +68,7 @@ message PlatformState { *

* This SHALL be the software version that created this state. */ - SoftwareVersion creation_software_version = 3; + proto.SemanticVersion creation_software_version = 3; /** * A number of non-ancient rounds. @@ -100,14 +100,14 @@ message PlatformState { proto.Timestamp last_frozen_time = 7; /** - * A consensus node software version.
+ * A consensus node semantic version.
* The software version that enabled birth round mode. *

* This SHALL be unset if birth round migration has not yet happened.
* If birth round migration is complete, this SHALL be the _first_ software * version that enabled birth round mode. */ - SoftwareVersion first_version_in_birth_round_mode = 8; + proto.SemanticVersion first_version_in_birth_round_mode = 8; /** * A consensus round.
@@ -138,33 +138,6 @@ message PlatformState { } -/** - * A consensus node software version. - * - * This message records version information for configuration, the Hedera - * API, and the "Services" subsystems. - */ -message SoftwareVersion { - /** - * A single numeric version.
- * This is the current configuration version read on node startup. - */ - uint32 config_version = 1; - - /** - * A semantic version entry.
- * This is the version of the HAPI module (Hedera API). - */ - proto.SemanticVersion hapi_version = 2; - - /** - * A semantic version entry.
- * This is the version of the services module. - */ - proto.SemanticVersion services_version = 3; -} - - /** * A consensus snapshot.
* This is a snapshot of the consensus state for a particular round. From d554baad49d6942465c03af7953807f94bfee76b Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Fri, 14 Jun 2024 10:20:40 -0400 Subject: [PATCH 13/22] Addressed a review comment - deprecated `last_round_before_birth_round_mode` and updated its order. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 50008b0a..acf86d5c 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -109,14 +109,6 @@ message PlatformState { */ proto.SemanticVersion first_version_in_birth_round_mode = 8; - /** - * A consensus round.
- * The last round before the birth round mode was enabled. - *

- * This SHALL be `MAX_UNSIGNED` if birth round mode has not yet been enabled. - */ - uint64 last_round_before_birth_round_mode = 9; - // Fields below are to be deprecated in the foreseeable future. /** @@ -135,6 +127,15 @@ message PlatformState { * 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.
+ * The last round before the birth round mode was enabled. + * Will be removed after the birth round migration. + *

+ * This SHALL be `MAX_UNSIGNED` if birth round mode has not yet been enabled. + */ + uint64 last_round_before_birth_round_mode = 10002 [deprecated = true]; } From a6c7ceaa0426961fe9dab10ae0b72aeb6db6a1de Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Fri, 14 Jun 2024 12:27:18 -0400 Subject: [PATCH 14/22] Addressed a review comment - improved description for `minimum_judge_ancient_threshold`. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index acf86d5c..c48a6594 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -198,7 +198,9 @@ message MinimumJudgeInfo { uint64 round = 1; /** - * Minimum ancient threshold for all judges in the round. + * The minimum ancient threshold for all judges for a given round.
+ * Will be a generation if the birth round migration has not yet happened, + * will be a birth round otherwise. *

* This SHALL reflect the relevant minimum threshold, whether * generation-based or birth-round-based. From c9b5c6336e3cfc14f2d7954ca6ed0f4450781695 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Fri, 14 Jun 2024 12:32:51 -0400 Subject: [PATCH 15/22] Addressed a review comment - removed `round` and `consensusTimestamp` from `ConsensusSnapshot`, as these fields duplicate fields in `PlatformState` and mean exactly the same thing. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 20 +++----------------- 1 file changed, 3 insertions(+), 17 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index c48a6594..977929ea 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -147,11 +147,6 @@ message PlatformState { * and reconnect. */ message ConsensusSnapshot { - /** - * A consensus round.
- * The round number of this snapshot. - */ - uint64 round = 1; /** * A list of SHA-384 hash values.
@@ -160,29 +155,20 @@ message ConsensusSnapshot { * This list SHALL be ordered by creator ID.
* This list MUST be deterministically ordered. */ - repeated bytes judge_hashes = 2; + repeated bytes judge_hashes = 1; /** * A list of minimum judge information entries.
* These are "minimum ancient" entries for non-ancient rounds. */ - repeated MinimumJudgeInfo minimum_judge_info_list = 3; + repeated MinimumJudgeInfo minimum_judge_info_list = 2; /** * A single consensus number.
* The consensus order of the next event to reach consensus. */ - uint64 next_consensus_number = 4; + uint64 next_consensus_number = 3; - /** - * A "consensus" timestamp.
- * The consensus timestamp of this snapshot. - *

- * This SHALL be a consensus value and MAY NOT correspond to an actual - * "wall clock" timestamp.
- * Consensus Timestamps SHALL always increase. - */ - proto.Timestamp consensus_timestamp = 5; } /** From cbc1e2d3fb1d2b4f65b65cf5dfda82ce0a5ef3ab Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Fri, 14 Jun 2024 12:35:02 -0400 Subject: [PATCH 16/22] Addressed a review comment - updated comment for `MinimumJudgeInfo` Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 977929ea..4d95c750 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -172,9 +172,7 @@ message ConsensusSnapshot { } /** - * Minimum ancient threshold information for round judges.
- * This message records the minimum ancient threshold agreed by all judges in - * a round. + * Records the minimum ancient indicator for all judges in a particular round. */ message MinimumJudgeInfo { /** From f1f4dd1824c7b37dd379baf288dbf54c3e36ebca Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Fri, 14 Jun 2024 13:25:33 -0400 Subject: [PATCH 17/22] Update platform/state/platform_state.proto Signed-off-by: Ivan Malygin Co-authored-by: Joseph Sinclair <121976561+jsync-swirlds@users.noreply.github.com> --- platform/state/platform_state.proto | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 4d95c750..7c46c4fb 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -182,9 +182,9 @@ message MinimumJudgeInfo { uint64 round = 1; /** - * The minimum ancient threshold for all judges for a given round.
- * Will be a generation if the birth round migration has not yet happened, - * will be a birth round otherwise. + * 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. *

* This SHALL reflect the relevant minimum threshold, whether * generation-based or birth-round-based. From e00fa8a468b970eddcad1d9e980b87259e93af25 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 20 Jun 2024 11:22:35 -0400 Subject: [PATCH 18/22] Addressed Lazar's comment - removed `round` from `PlatformState` and put it back to `ConsensusSnapshot` Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 37 ++++++++++++----------------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 7c46c4fb..3c8764cd 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -44,45 +44,34 @@ import "timestamp.proto"; * restart and reconnect. */ message PlatformState { - /** - * A consensus round.
- * The round represented by this state. - *

- * This message SHALL represent the network state after handling of all - * transactions reaching consensus in all previous rounds.
- * The first state (genesis state) SHALL have a round of 0.
- * The first round to handle transactions SHALL be round `1`. - */ - uint64 round = 1; - /** * A consensus timestamp for this state. *

* This SHALL be the consensus timestamp of the first transaction in * the current round. */ - proto.Timestamp consensus_timestamp = 2; + proto.Timestamp consensus_timestamp = 1; /** * A version describing the current version of application software. *

* This SHALL be the software version that created this state. */ - proto.SemanticVersion creation_software_version = 3; + proto.SemanticVersion creation_software_version = 2; /** * A number of non-ancient rounds. *

* This SHALL be the count of rounds considered non-ancient. */ - uint32 rounds_non_ancient = 4; + uint32 rounds_non_ancient = 3; /** * A snapshot of the consensus state at the end of the round. *

* This SHALL be used for restart/reconnect. */ - ConsensusSnapshot consensus_snapshot = 5; + ConsensusSnapshot consensus_snapshot = 4; /** * A timestamp for the next scheduled time when a freeze will start. @@ -91,13 +80,13 @@ message PlatformState { * If a freeze is currently scheduled, this MUST be set, and MUST * match the timestamp requested for that freeze. */ - proto.Timestamp freeze_time = 6; + proto.Timestamp freeze_time = 5; /** * A timestamp for the last time a freeze was performed.
* If not set, there has never been a freeze. */ - proto.Timestamp last_frozen_time = 7; + proto.Timestamp last_frozen_time = 6; /** * A consensus node semantic version.
@@ -107,7 +96,7 @@ message PlatformState { * 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 = 8; + proto.SemanticVersion first_version_in_birth_round_mode = 7; // Fields below are to be deprecated in the foreseeable future. @@ -147,7 +136,11 @@ message PlatformState { * and reconnect. */ message ConsensusSnapshot { - + /** + * A consensus round.
+ * The round number of this snapshot. + */ + uint64 round = 1; /** * A list of SHA-384 hash values.
* The hashes of all judges for this round. @@ -155,19 +148,19 @@ message ConsensusSnapshot { * This list SHALL be ordered by creator ID.
* This list MUST be deterministically ordered. */ - repeated bytes judge_hashes = 1; + repeated bytes judge_hashes = 2; /** * A list of minimum judge information entries.
* These are "minimum ancient" entries for non-ancient rounds. */ - repeated MinimumJudgeInfo minimum_judge_info_list = 2; + repeated MinimumJudgeInfo minimum_judge_info_list = 3; /** * A single consensus number.
* The consensus order of the next event to reach consensus. */ - uint64 next_consensus_number = 3; + uint64 next_consensus_number = 4; } From b8e11105801ca3462fc53c02b459f4290624362a Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 20 Jun 2024 11:24:49 -0400 Subject: [PATCH 19/22] Addressed Lazar's comment - removed `consensus_timestamp` from `PlatformState` and put it back to `ConsensusSnapshot` Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 3c8764cd..e29c8179 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -44,34 +44,27 @@ import "timestamp.proto"; * restart and reconnect. */ message PlatformState { - /** - * A consensus timestamp for this state. - *

- * This SHALL be the consensus timestamp of the first transaction in - * the current round. - */ - proto.Timestamp consensus_timestamp = 1; /** * A version describing the current version of application software. *

* This SHALL be the software version that created this state. */ - proto.SemanticVersion creation_software_version = 2; + proto.SemanticVersion creation_software_version = 1; /** * A number of non-ancient rounds. *

* This SHALL be the count of rounds considered non-ancient. */ - uint32 rounds_non_ancient = 3; + uint32 rounds_non_ancient = 2; /** * A snapshot of the consensus state at the end of the round. *

* This SHALL be used for restart/reconnect. */ - ConsensusSnapshot consensus_snapshot = 4; + ConsensusSnapshot consensus_snapshot = 3; /** * A timestamp for the next scheduled time when a freeze will start. @@ -80,13 +73,13 @@ message PlatformState { * If a freeze is currently scheduled, this MUST be set, and MUST * match the timestamp requested for that freeze. */ - proto.Timestamp freeze_time = 5; + proto.Timestamp freeze_time = 4; /** * A timestamp for the last time a freeze was performed.
* If not set, there has never been a freeze. */ - proto.Timestamp last_frozen_time = 6; + proto.Timestamp last_frozen_time = 5; /** * A consensus node semantic version.
@@ -96,7 +89,7 @@ message PlatformState { * 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 = 7; + proto.SemanticVersion first_version_in_birth_round_mode = 6; // Fields below are to be deprecated in the foreseeable future. @@ -162,6 +155,16 @@ message ConsensusSnapshot { */ uint64 next_consensus_number = 4; + /** + * A "consensus" timestamp.
+ * The consensus timestamp of this snapshot. + *

+ * This SHALL be a consensus value and MAY NOT correspond to an actual + * "wall clock" timestamp.
+ * Consensus Timestamps SHALL always increase. + */ + proto.Timestamp consensus_timestamp = 5; + } /** From 132c25b9601b12bc5694e15c03786ead4b5afa1e Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 20 Jun 2024 13:49:31 -0400 Subject: [PATCH 20/22] Improved javadoc for `ConsensusSnapshot.consensus_timestamp` Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index e29c8179..135ea3e2 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -159,6 +159,11 @@ message ConsensusSnapshot { * A "consensus" timestamp.
* The consensus timestamp of this snapshot. *

+ * Depending on the context this timestamp may have different meanings: + *

  • if there are transactions, the timestamp is equal to the timestamp of the last transaction + *
  • if there are no transactions, the timestamp is equal to the timestamp of the last event + *
  • if there are no events, the timestamp is equal to the timestamp of the previous round plus a small constant + *

    * This SHALL be a consensus value and MAY NOT correspond to an actual * "wall clock" timestamp.
    * Consensus Timestamps SHALL always increase. From 52206e35033f77a00bce8f7b134d5d43b60f772a Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Thu, 20 Jun 2024 14:48:17 -0400 Subject: [PATCH 21/22] Addressed Cody's comment - moved `PlatformState.first_version_in_birth_round_mode` to the set of deprecated fields. Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index 135ea3e2..ea210a0a 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -81,16 +81,6 @@ message PlatformState { */ proto.Timestamp last_frozen_time = 5; - /** - * A consensus node semantic version.
    - * The software version that enabled birth round mode. - *

    - * This SHALL be unset if birth round migration has not yet happened.
    - * 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 = 6; - // Fields below are to be deprecated in the foreseeable future. /** @@ -118,6 +108,17 @@ message PlatformState { * 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.
    + * The software version that enabled birth round mode. + *

    + * This SHALL be unset if birth round migration has not yet happened.
    + * 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]; + } From dd4b50c564c229a6b0022a85f054eeb36b0f2416 Mon Sep 17 00:00:00 2001 From: Ivan Malygin Date: Mon, 1 Jul 2024 17:54:24 -0400 Subject: [PATCH 22/22] Fixed HTML tags. Co-authored-by: Joseph S. <121976561+jsync-swirlds@users.noreply.github.com> Signed-off-by: Ivan Malygin --- platform/state/platform_state.proto | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/platform/state/platform_state.proto b/platform/state/platform_state.proto index ea210a0a..452e8e9e 100644 --- a/platform/state/platform_state.proto +++ b/platform/state/platform_state.proto @@ -161,9 +161,11 @@ message ConsensusSnapshot { * The consensus timestamp of this snapshot. *

    * Depending on the context this timestamp may have different meanings: - *

  • if there are transactions, the timestamp is equal to the timestamp of the last transaction - *
  • if there are no transactions, the timestamp is equal to the timestamp of the last event - *
  • if there are no events, the timestamp is equal to the timestamp of the previous round plus a small constant + *
      + *
    • if there are transactions, the timestamp is equal to the timestamp of the last transaction
      • + *
    • if there are no transactions, the timestamp is equal to the timestamp of the last event
      • + *
    • if there are no events, the timestamp is equal to the timestamp of the previous round plus a small constant
      • + *
    *

    * This SHALL be a consensus value and MAY NOT correspond to an actual * "wall clock" timestamp.