Skip to content

Commit

Permalink
feat: 13135 Added PlatformState protobuf representation (#349)
Browse files Browse the repository at this point in the history 
* feat: 13135 Added PlatformState protobuf representation

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

* Update sdk/platform_state.proto

Signed-off-by: Ivan Malygin <[email protected]>
Co-authored-by: Joseph Sinclair <[email protected]>

* 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 <[email protected]>

* Updated type of `lowest_judge_generation_before_birth_round_mode` to int64 as it can be negative.

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

* Added platform-specific `AddressBook`.

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

* Update platform/state/platform_state.proto

Signed-off-by: Ivan Malygin <[email protected]>
Co-authored-by: Joseph Sinclair <[email protected]>

* Addressed review comments.

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

* Removed Roster, Address and NodeId as they will be a part of another PR.
Fixed `PlatformState` indices.

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

* Update platform/state/platform_state.proto

Signed-off-by: Ivan Malygin <[email protected]>
Co-authored-by: Joseph Sinclair <[email protected]>

* 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 <[email protected]>

* Update platform/state/platform_state.proto

Signed-off-by: Ivan Malygin <[email protected]>
Co-authored-by: Joseph Sinclair <[email protected]>

* Addressed review comments - removed `SoftwareVersion` message and replaced it with `SemanticVersion`

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

* Addressed a review comment - deprecated `last_round_before_birth_round_mode` and updated its order.
Signed-off-by: Ivan Malygin <[email protected]>

* Addressed a review comment - improved description for `minimum_judge_ancient_threshold`.

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

* 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 <[email protected]>

* Addressed a review comment - updated comment for `MinimumJudgeInfo`

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

* Update platform/state/platform_state.proto

Signed-off-by: Ivan Malygin <[email protected]>
Co-authored-by: Joseph Sinclair <[email protected]>

* Addressed Lazar's comment - removed `round` from `PlatformState` and put it back to `ConsensusSnapshot`

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

* Addressed Lazar's comment - removed `consensus_timestamp` from `PlatformState` and put it back to `ConsensusSnapshot`

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

* Improved javadoc for  `ConsensusSnapshot.consensus_timestamp`

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

* Addressed Cody's comment - moved `PlatformState.first_version_in_birth_round_mode` to the set of deprecated fields.

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

* Fixed HTML tags.

Co-authored-by: Joseph S. <[email protected]>
Signed-off-by: Ivan Malygin <[email protected]>

---------

Signed-off-by: Ivan Malygin <[email protected]>
Co-authored-by: Joseph Sinclair <[email protected]>
Signed-off-by: Valentin Tronkov <[email protected]>
  • Loading branch information
@imalygin @jsync-swirlds @vtronkov
2 people authored and vtronkov committed Jul 23, 2024
1 parent 1a6301b commit 30b3d5f
Showing 1 changed file with 197 additions and 0 deletions.
197 changes: 197 additions & 0 deletions platform/state/platform_state.proto
View file
Original file line number Diff line number Diff line change
@@ -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;
}

0 comments on commit 30b3d5f

Please sign in to comment.