stream.output.block_header.proto Maven / Gradle / Ivy
/**
* # Block Header
* The block header reports information required to correctly process a block.
* This includes versions, block number, and algorithms used.
*
* ### 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.block.stream.output;
/*
* 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.block.stream.output.protoc";
// <<>> This comment is special code for setting PBJ Compiler java package
option java_multiple_files = true;
import "basic_types.proto";
import "timestamp.proto";
/**
* A Block Header.
*
* Each block in the block stream SHALL begin with a block header.
* The block header SHALL provide the base minimum information needed to
* correctly interpret and process that block, or stop processing
* if appropriate.
* The block header MUST describe, at minimum, the following items.
* - The version of the block stream data
* - The block number
* - The hash of the previous block
* - The hash algorithm used to generate the block hash
*
* All fields of this message are REQUIRED, with the exception that
* `hash_algorithm` MAY be _transmitted_ as a default value to improve
* data efficiency.
*/
message BlockHeader {
/**
* A version of the HAPI specification.
* This is the API version that was used to serialize the block.
*/
proto.SemanticVersion hapi_proto_version = 1;
/**
* A version of the consensus node software.
* This is the software version that executed the transactions
* within this block.
*/
proto.SemanticVersion software_version = 2;
/**
* A block number for this block.
*
* This value MUST be exactly `1` more than the previous block.
* Client systems SHOULD optimistically reject any block with a gap or
* reverse in `number` sequence, and MAY assume the block stream has
* encountered data loss, data corruption, or unauthorized modification.
*/
uint64 number = 3;
/**
* A block root hash for the previous block.
*
* This value MUST match the block merkle tree root hash of the previous
* block in the block stream.
* This value SHALL be empty for the genesis block, and SHALL NOT be empty
* for any other block.
* Client systems SHOULD optimistically reject any block with a
* `previous_block_proof_hash` that does not match the block hash of the
* previous block and MAY assume the block stream has encountered data
* loss, data corruption, or unauthorized modification.
*
* The process for computing a block hash is somewhat complex, and involves
* creating a "virtual" merkle tree to obtain the root merkle hash of
* that virtual tree.
* The merkle tree SHALL have a 4 part structure with 2 internal nodes,
* structured in a strictly binary tree.
*
* - The merkle tree root SHALL be the parent of both
* internal nodes.
*
* - The first "internal" node SHALL be the parent of the
* two "left-most" nodes.
*
* - The first leaf MUST be the previous block hash, and is a
* single 48-byte value.
* - The second leaf MUST be the root of a, strictly binary,
* merkle tree composed of all "input" block items in
* the block.
* Input items SHALL be transactions, system transactions,
* and events.
* Leaf nodes in this subtree SHALL be ordered in the
* same order that the block items are encountered
* in the stream.
*
*
* - The second "internal" node SHALL be the parent of the
* two "right-most" nodes.
*
* - The third leaf MUST be the root of a, strictly binary,
* merkle tree composed of all "output" block items in
* the block.
* Output items SHALL be transaction result, transaction
* output, and state changes.
* Leaf nodes in this subtree SHALL be ordered in the
* same order that the block items are encountered
* in the stream.
* - The fourth leaf MUST be the merkle tree root hash for
* network state at the end of the block, and is a single
* 48-byte value.
*
*
*
*
* - The block hash SHALL be the SHA-384 hash calculated for the root
* of this merkle tree.
*
*/
bytes previous_block_hash = 4;
/**
* A consensus timestamp for the start of this block.
*
* This SHALL be the timestamp assigned by the hashgraph consensus
* algorithm to the first transaction of this block.
*/
proto.Timestamp first_transaction_consensus_time = 5;
/**
* A hash algorithm used for this block, including the block proof.
*
* This SHOULD always be `SHA2_384`, currently.
*/
proto.BlockHashAlgorithm hash_algorithm = 6;
/**
* A version for the network address book.
* The address book version is needed to determine the correct public
* key(s) to use to validate block signatures and state proofs.
*
* This MUST be the version of the address book that signed this
* block.
*/
proto.SemanticVersion address_book_version = 7;
}