state.platform_state.proto Maven / Gradle / Ivy
/**
* # 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";
// <<>> 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.
* 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 {
/**
* A version describing the current version of application software.
*
* This SHALL be the software version that created this state.
*/
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 = 2;
/**
* A snapshot of the consensus state at the end of the round.
*
* This SHALL be used for restart/reconnect.
*/
ConsensusSnapshot consensus_snapshot = 3;
/**
* 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 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.
* 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.
* This is computed by the consensus event stream.
*
* 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.
* The lowest judge generation before birth round mode was enabled.
*
* 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];
/**
* 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];
/**
* An address book for this round.
*
* This SHALL be the latest network-consensus view of consensus nodes.
*/
AddressBook address_book = 10004 [deprecated = true];
/**
* 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 = 10005 [deprecated = true];
}
/**
* A consensus snapshot.
* 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.
* The round number of this snapshot.
*/
uint64 round = 1;
/**
* A list of SHA-384 hash values.
* The hashes of all judges for this round.
*
* This list SHALL be ordered by creator ID.
* This list MUST be deterministically ordered.
*/
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 = 3;
/**
* A single consensus number.
* The consensus order of the next event to reach consensus.
*/
uint64 next_consensus_number = 4;
/**
* 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.
*/
proto.Timestamp consensus_timestamp = 5;
}
/**
* Records the minimum ancient indicator for all judges in a particular round.
*/
message MinimumJudgeInfo {
/**
* A consensus round.
* 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.
*
* This SHALL reflect the relevant minimum threshold, whether
* generation-based or birth-round-based.
*/
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 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.
*
* 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.
*
*/
message Address {
/**
* The ID of this member.
*
* This identifier SHALL be agreed upon by all consensus nodes.
*/
NodeId id = 1;
/**
* The nickname other consensus nodes will use to refer to this 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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 consensus node.
*
* This SHALL provide the public key used for signing.
*/
bytes signing_certificate = 9;
/**
* The agreement x509 certificate of the consensus node.
*
* This SHALL be used for establishing TLS connections.
*/
bytes agreement_certificate = 10;
/**
* A string that provides additional information about this consensus node.
*/
string memo = 11;
}
/**
* A consensus node identifier.
* This value uniquely identifies a single consensus node within the network.
*/
message NodeId {
/**
* A numeric identifier.
*/
uint64 id = 1;
}