Update to "Boilerplate" and formatting.

* Modified all copyright notices to remove unnecessary text and match general guidelines. * Fixed a few items noted in offline review prior to DevCon-24a * Reformat to match current guidelines for line length and field descriptions. Signed-off-by: Joseph Sinclair <joseph.sinclair@swirldslabs.com>
hashgraph · May 13, 2024 · 7c15751 · 7c15751
1 parent 76b8d19
commit 7c15751
Show file tree

Hide file tree

Showing 36 changed files with 1,867 additions and 1,499 deletions.
diff --git a/block/block_service.proto b/block/block_service.proto
diff --git a/block/stream/block.proto b/block/stream/block.proto
@@ -1,26 +1,26 @@
 /**
  * # Block Stream
  * The base element of the block stream _at rest_.
- * A `Block` contains a record of all transactions, results, and outputs for a block in the chain.
- * Each `Block` also contains a state proof for validation and a header with version and
- * algorithm information.
+ * A `Block` contains a record of all transactions, results, and outputs for
+ * a block in the chain. Each `Block` also contains a state proof for
+ * validation and a header with version and algorithm information.
  *
- * Block entries are not designed for streaming, but for storing blocks in persistent
- * storage, verifying block stream data, and as query responses when a block is
- * requested from a block node.
+ * Block entries are not designed for streaming, but for storing blocks in
+ * persistent storage, verifying block stream data, and as query responses
+ * when a block is requested from a block node.
  *
  * ### 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).
+ * 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;
 
 /*
- * Hedera Network Services Protobuf
- *
  * Copyright (C) 2024 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -45,26 +45,27 @@ import "stream/block_item.proto";
 /**
  * A single complete Hedera block chain block.
  *
- * This is a single block structure and SHALL NOT represent the primary mechanism to
- * transmit a block stream.<br/>
- * The primary mechanism for transmitting block stream data SHALL be to stream individual
- * block items to the block node(s).<br/>
- * The only delimiter between blocks when streamed SHALL be the `BlockHeader` item and
- * `BlockStateProof` item.
+ * This is a single block structure and SHALL NOT represent the primary
+ * mechanism to transmit a block stream.<br/>
+ * The primary mechanism for transmitting block stream data SHALL be to
+ * stream individual block items to the block node(s).<br/>
+ * The only delimiter between blocks when streamed SHALL be the `BlockHeader`
+ * item and `BlockStateProof` item.
  *
  * This block SHALL be verifiable as correct using only data in the block,
  * including the `BlockStateProof`, and public keys for the consensus nodes.
  */
 message Block {
-  /**
-   * A list of items that, together, make up this block.
-   * <p>
-   * This list SHALL begin with a `BlockHeader`.<br/>
-   * This list SHALL end with a `BlockStateProof`.<br/>
-   * Items in this list SHALL be in exactly the same order produced by consensus.<br/>
-   * Items in this list MAY be filtered, if so requested.<br/>
-   * If this list is filtered, removed items SHALL be replaced with
-   * `FilteredBlockItem` entries.<br/>
-   */
-  repeated BlockItem items = 1;
+    /**
+     * A list of items that, together, make up this block.
+     * <p>
+     * This list SHALL begin with a `BlockHeader`.<br/>
+     * This list SHALL end with a `BlockStateProof`.<br/>
+     * Items in this list SHALL be in exactly the same order produced by
+     * consensus.<br/>
+     * Items in this list MAY be filtered, if so requested.<br/>
+     * If this list is filtered, removed items SHALL be replaced with
+     * `FilteredBlockItem` entries.<br/>
+     */
+    repeated BlockItem items = 1;
 }
diff --git a/block/stream/block_header.proto b/block/stream/block_header.proto
@@ -1,20 +1,20 @@
 /**
  * # Block Header
- * The block header reports information required to correctly process a block.  This includes
- * versions, block number, and algorithms used.
+ * 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).
+ * 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;
 
 /*
- * Hedera Network Services Protobuf
- *
  * Copyright (C) 2024 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -40,16 +40,18 @@ import "basic_types.proto";
  * A Block Header.
  *
  * Each block in the block stream SHALL begin with a block header.<br/>
- * The block header SHALL provide the base minimum information needed to correctly interpret
- * and process that block, or stop processing if appropriate.<br/>
+ * The block header SHALL provide the base minimum information needed to
+ * correctly interpret and process that block, or stop processing
+ * if appropriate.<br/>
  * 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.
+ * 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 {
     /**
@@ -58,22 +60,26 @@ message BlockHeader {
     proto.SemanticVersion hapi_proto_version = 1;
 
     /**
-     * The block number of this block.<br/>
+     * The block number of this block.
+     * <p>
      * This value MUST be exactly `1` more than the previous block.<br/>
-     * 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.
+     * 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 = 2;
 
     /**
-     * The running hash of the previous block.<br/>
-     * This value MUST match the block hash of the previous block in the block stream.<br/>
-     * This value SHALL be empty for the genesis block, and SHALL NOT be empty for
-     * any other block.<br/>
-     * Client systems SHOULD optimistically reject any block with a `start_running_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 running hash of the previous block.
+     * <p>
+     * This value MUST match the block hash of the previous block in the
+     * block stream.<br/>
+     * This value SHALL be empty for the genesis block, and SHALL NOT be empty
+     * for any other block.<br/>
+     * Client systems SHOULD optimistically reject any block with a
+     * `start_running_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.
      */
     bytes start_running_hash = 3;
 
@@ -86,15 +92,18 @@ message BlockHeader {
 /**
  * A specific hash algorithm used within a block.
  *
- * We did not reuse HashAlgorithm here because in all cases for now it will be `SHA_384` and
- * if that is the default value then we can save space by not serializing it, whereas
- * `HASH_ALGORITHM_UNKNOWN` is the default for HashAlgorithm.
+ * We did not reuse HashAlgorithm here because in all cases for now it will
+ * be `SHA_384` and if that is the default value then we can save space by
+ * not serializing it, whereas `HASH_ALGORITHM_UNKNOWN` is the
+ * default for HashAlgorithm.
  */
 enum BlockHashAlgorithm {
     /**
-     * A SHA2 algorithm SHA-384 hash.<br/>
-     * This is the default value, if a field of this enumerated type is not set, then
-     * this is the value that will be decoded when the serialized message is read.
+     * A SHA2 algorithm SHA-384 hash.
+     * <p>
+     * This is the default value, if a field of this enumerated type is
+     * not set, then this is the value that will be decoded when the
+     * serialized message is read.
      */
     SHA_384 = 0;
 }