Continue updating block stream definitions.

* Cleaned up `transaction_output.proto`.
   * Removed all currently unused options.
   * Adjusted ordering for better efficiency and clarity.
   * Reserved field numbers of all remaining transaction types
     for future use.
   * Documented, in an HTML comment, field types, names, and numbers
     for all remaining outputs.
* Cleaned up remaining items in several other block stream files.
   * This is a general "editing" update to clean up and clarify
     the text. This may include small structural changes for
     both clarity and data efficiency.

Signed-off-by: Joseph Sinclair <joseph.sinclair@swirldslabs.com>

block/stream/block_header.proto

@@ -44,22 +44,18 @@ import "basic_types.proto";
  * 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 Hedera API version
- *  - The Hedera Services version
- *  - The Hedera Platform version
  *  - The block number
  *  - The hash of the previous block
  *  - The hash algorithm used to generate the block hash
- *  - The digital signature algorithm used to sign the block hash
  *
- * All fields of this message are REQUIRED, with the exception that the _algorithms_ MAY
+ * 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 {
     /**
      * Version of the HAPI specification that was used to serialize the block.
      */
-    proto.SemanticVersion hapi_proto_version = 2;
+    proto.SemanticVersion hapi_proto_version = 1;
 
     /**
      * The block number of this block.<br/>
@@ -68,7 +64,7 @@ message BlockHeader {
      * in `number` sequence, and MAY assume the block stream has encountered data
      * loss, data corruption, or unauthorized modification.
      */
-    uint64 number = 5;
+    uint64 number = 2;
 
     /**
      * The running hash of the previous block.<br/>
@@ -79,12 +75,12 @@ message BlockHeader {
      * 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 = 6;
+    bytes start_running_hash = 3;
 
     /**
      * The hash algorithm used in this block.
      */
-    BlockHashAlgorithm hash_algorithm = 7;
+    BlockHashAlgorithm hash_algorithm = 4;
 }
 
 /**
@@ -95,5 +91,10 @@ message BlockHeader {
  * `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.
+     */
     SHA_384 = 0;
 }

block/stream/block_item.proto

@@ -180,7 +180,7 @@ message BlockItem {
  */
 message FilteredBlockItem {
     /**
-     * A SHA384 hash of an item filtered from the stream.
+     * A SHA-384 hash of an item filtered from the stream.
      */
     bytes item_hash = 1;
 }

block/stream/consensus_service.proto

@@ -3,63 +3,8 @@
  * Block stream messages that report the results of transactions handled by the `Consensus` service.
  *
  * ### Topic Running Hash Calculation
- * Some messages include a topic running hash. This value has changed over time, with the
- * known versions listed here.
- *
- * <hr style="margin: 0.2em -1em 0.2em -1em; height: 0.5em; border-style: solid none solid none; border-width: 2px;"/>
- *
- * This 48-byte field is the output of a SHA-384 digest with input data determined by the
- * value of the `topic_running_hash_version` field.<br/>
- * All new transactions SHALL use `topic_running_hash_version` `3`.<br/>
- * The bytes of each uint64 or uint32 encoded for the hash input MUST be in Big-Endian format.
- * ---
- * If the `topic_running_hash_version` is '0' or '1', then the input data to the SHA-384 digest are,
- * in order:
- *  1. The previous running hash of the topic (48 bytes)
- *  1. The topic's shard (8 bytes)
- *  1. The topic's realm (8 bytes)
- *  1. The topic's number (8 bytes)
- *  1. The number of seconds since the epoch when the `ConsensusSubmitMessage` reached
- *     consensus (8 bytes)
- *  1. The number of nanoseconds within the second when the `ConsensusSubmitMessage` reached
- *     consensus (4 bytes)
- *  1. The `topic_sequence_number` field (8 bytes)
- *  1. The message bytes from the `ConsensusSubmitMessage` (variable).
- * ---
- * If the `topic_running_hash_version` is '2', then the input data to the SHA-384 digest are, in
- * order:
- *  1. The previous running hash of the topic (48 bytes)
- *  1. The `topic_running_hash_version` field (8 bytes)
- *  1. The topic's shard (8 bytes)
- *  1. The topic's realm (8 bytes)
- *  1. The topic's number (8 bytes)
- *  1. The number of seconds since the epoch when the `ConsensusSubmitMessage` reached
- *     consensus (8 bytes)
- *  1. The number of nanoseconds within the second when the `ConsensusSubmitMessage` reached
- *     consensus (4 bytes)
- *  1. The `topic_sequence_number` field (8 bytes)
- *  1. The output of a SHA-384 digest of the message bytes from the `ConsensusSubmitMessage`
- *     (48 bytes)
- * ---
- * If the `topic_running_hash_version` is '3', then the input data to the SHA-384 digest
- * are, in order:
- *  1. The previous running hash of the topic (48 bytes)
- *  1. The `topic_running_hash_version` field (8 bytes)
- *  1. The payer account's shard (8 bytes)
- *  1. The payer account's realm (8 bytes)
- *  1. The payer account's number (8 bytes)
- *  1. The topic's shard (8 bytes)
- *  1. The topic's realm (8 bytes)
- *  1. The topic's number (8 bytes)
- *  1. The number of seconds since the epoch when the `ConsensusSubmitMessage` reached
- *     consensus (8 bytes)
- *  1. The number of nanoseconds within the second when the `ConsensusSubmitMessage` reached
- *     consensus (4 bytes)
- *  1. The `topic_sequence_number` field (8 bytes)
- *  1. The output of a SHA-384 digest of the message bytes from the `ConsensusSubmitMessage`
- *     (48 bytes)
- *
- * <hr style="margin: 0.2em -1em 0.2em -1em; height: 0.5em; border-style: solid none solid none; border-width: 2px;"/>
+ * Submitted messages include a topic running hash. This value has changed over time, with the
+ * known versions detailed in the `RunningHashVersion` enumeration.
  *
  * ### Keywords
  * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
@@ -117,11 +62,92 @@ message DeleteTopicOutput {}
  * Block Stream data for a `submitMessage` transaction.
  *
  * This message SHALL NOT duplicate information already contained in the original transaction.
+ * The actual topic running hash SHALL be present in a `StateChanges` block item, and is not
+ * duplicated here.<br/>
  */
 message SubmitMessageOutput {
     /**
      * The version of inputs to the SHA-384 running hash.<br/>
-     * For all current transactions, this value SHALL be `3`.
+     * For all current transactions, this value SHALL be `WITH_MESSAGE_DIGEST_AND_PAYER`.
+     */
+    RunningHashVersion topic_running_hash_version = 1;
+
+    /**
+     * A version of the topic running hash.
+     *
+     * The inputs to the topic running hash have changed over time. This is tracked in earlier
+     * record streams as an integer. For the block stream we chose to use an enumeration for
+     * both efficiency and clarity. Placing the most recent, and most common/highest volume,
+     * version as `0` reduces the serialized size of this message by not serializing that
+     * default value.
+     *
+     * <hr style="margin: 0.2em 5em 0.2em 5em; height: 0.5em; border-style: solid none solid none; border-width: 2px;"/>
+     *
+     * The topic running hash is a 48-byte value that is the output of a SHA-384 digest with
+     * input data determined by the value of the `topic_running_hash_version` field.<br/>
+     * All new transactions SHALL use `topic_running_hash_version`
+     * `WITH_MESSAGE_DIGEST_AND_PAYER`.<br/>
      */
-    uint64 topic_running_hash_version = 3;
+    enum RunningHashVersion {
+        /**
+         * The most recent version.<br/>
+         * This version SHALL include, in order
+         * <ol>
+         *  <li>The previous running hash of the topic (48 bytes)</li>
+         *  <li>The `topic_running_hash_version` field (8 bytes)</li>
+         *  <li>The payer account's shard (8 bytes)</li>
+         *  <li>The payer account's realm (8 bytes)</li>
+         *  <li>The payer account's number (8 bytes)</li>
+         *  <li>The topic's shard (8 bytes)</li>
+         *  <li>The topic's realm (8 bytes)</li>
+         *  <li>The topic's number (8 bytes)</li>
+         *  <li>The number of seconds since the epoch when the `ConsensusSubmitMessage` reached
+         *      consensus (8 bytes)</li>
+         *  <li>The number of nanoseconds within the second when the `ConsensusSubmitMessage`
+         *      reached consensus (4 bytes)</li>
+         *  <li>The `topic_sequence_number` field (8 bytes)</li>
+         *  <li>The output of a SHA-384 digest of the message bytes from the
+         *      `ConsensusSubmitMessage` (48 bytes)</li>
+         * </ol>
+         */
+        WITH_MESSAGE_DIGEST_AND_PAYER = 0;
+
+        /**
+         * An earlier version.<br/>
+         * This version SHALL include, in order
+         * <ol>
+         *  <li>The previous running hash of the topic (48 bytes)</li>
+         *  <li>The `topic_running_hash_version` field (8 bytes)</li>
+         *  <li>The topic's shard (8 bytes)</li>
+         *  <li>The topic's realm (8 bytes)</li>
+         *  <li>The topic's number (8 bytes)</li>
+         *  <li>The number of seconds since the epoch when the `ConsensusSubmitMessage` reached
+         *      consensus (8 bytes)</li>
+         *  <li>The number of nanoseconds within the second when the `ConsensusSubmitMessage`
+         *      reached consensus (4 bytes)</li>
+         *  <li>The `topic_sequence_number` field (8 bytes)</li>
+         *  <li>The output of a SHA-384 digest of the message bytes from the
+         *      `ConsensusSubmitMessage` (48 bytes)</li>
+         * </ol>
+         */
+        WITH_MESSAGE_DIGEST = 1;
+
+        /**
+         * The original version, used at genesis.<br/>
+         * This version SHALL include, in order
+         * <ol>
+         *  <li>The previous running hash of the topic (48 bytes)</li>
+         *  <li>The topic's shard (8 bytes)</li>
+         *  <li>The topic's realm (8 bytes)</li>
+         *  <li>The topic's number (8 bytes)</li>
+         *  <li>The number of seconds since the epoch when the `ConsensusSubmitMessage` reached
+         *      consensus (8 bytes)</li>
+         *  <li>The number of nanoseconds within the second when the `ConsensusSubmitMessage`
+         *      reached consensus (4 bytes)</li>
+         *  <li>The `topic_sequence_number` field (8 bytes)</li>
+         *  <li>The message bytes from the `ConsensusSubmitMessage` (variable)</li>
+         * </ol>
+         */
+        WITH_FULL_MESSAGE = 2;
+    }
 }