Review changes

* Adjusted wording for consistency and clarity * Adjusted formatting for consistency * Added standard file header information * Updated query.proto with package changes Signed-off-by: Joseph Sinclair <[email protected]>
hashgraph · May 7, 2024 · a41924d · a41924d
1 parent 422da49
commit a41924d
Show file tree

Hide file tree

Showing 7 changed files with 106 additions and 47 deletions.
diff --git a/services/address_book_service.proto b/services/address_book_service.proto
@@ -94,7 +94,7 @@ import "transaction.proto";
  *   `updateNode` transaction.
  *    - If the node operator creates the transaction
  *       - The node operator MUST sign this transaction with the active `key`
- *         for the account assigned as the "node account".
+ *         for the account assigned as the current "node account".
  *       - If the transaction changes the value of the "node account" the
  *         node operator MUST _also_ sign this transaction with the active `key`
  *         for the account to be assigned as the new "node account".
@@ -128,7 +128,7 @@ service AddressBookService {
      * This transaction, once complete, SHALL add a new consensus node to the
      * network state.<br/>
      * The new consensus node SHALL remain in state, but SHALL NOT participate
-     * in network consensus until the network updates the consensus roster.
+     * in network consensus until the network updates the network configuration.
      * <p>
      * Hedera governing council authorization is REQUIRED for this transaction.
      */
@@ -139,7 +139,7 @@ service AddressBookService {
      * book.
      * <p>
      * This transaction, once complete, SHALL remove the identified consensus
-     * node from the network.
+     * node from the network state.
      * <p>
      * Hedera governing council authorization is REQUIRED for this transaction.
      */
@@ -150,7 +150,7 @@ service AddressBookService {
      * address book.
      * <p>
      * This transaction, once complete, SHALL modify the identified consensus
-     * node as requested.
+     * node state as requested.
      * <p>
      * This transaction MAY be authorized by either the node operator OR the
      * Hedera governing council.
@@ -159,7 +159,7 @@ service AddressBookService {
 
     /**
      * A transaction to query the current state of a consensus node in the
-     * network address book.
+     * network address book state.
      * <p>
      * Hedera governing council authorization is REQUIRED for this transaction.
      */

diff --git a/services/node_create.proto b/services/node_create.proto
@@ -1,3 +1,12 @@
+/**
+ * # Node Create
+ * Messages to add a consensus node to the network address book.
+ *
+ * ### 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).
+ */
 syntax = "proto3";
 
 package com.hedera.hapi.node.addressbook;

diff --git a/services/node_delete.proto b/services/node_delete.proto
@@ -1,3 +1,12 @@
+/**
+ * # Node Delete
+ * Messages to remove a consensus node from the network address book.
+ *
+ * ### 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).
+ */
 syntax = "proto3";
 
 package com.hedera.hapi.node.addressbook;

diff --git a/services/node_get_info.proto b/services/node_get_info.proto
@@ -1,3 +1,13 @@
+/**
+ * # Node Get Info
+ * Messages to request information about a consensus node present in the
+ * network address book.
+ *
+ * ### 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).
+ */
 syntax = "proto3";
 
 package com.hedera.hapi.node.addressbook;
@@ -45,14 +55,16 @@ import "response_header.proto";
  */
 message NodeGetInfoQuery {
     /**
-     * Standard information sent with every query operation.<br/>
+     * Standard information sent with every query operation.
+     * <p>
      * This includes the signed payment and what kind of response is requested
      * (cost, state proof, both, or neither).
      */
     proto.QueryHeader header = 1;
 
     /**
-     * A consensus node identifier for which information is requested.<br/>
+     * A consensus node identifier for which information is requested.
+     * <p>
      * If the identified node is not valid, this request SHALL fail with
      * a response code `INVALID_NODE_ID`.<br/>
      * If the identified node is not present in the network state,
@@ -67,28 +79,32 @@ message NodeGetInfoQuery {
  */
 message NodeInfo {
     /**
-     * A consensus node identifier in the network state.<br/>
+     * A consensus node identifier in the network state.
+     * <p>
      * This value identifies this node within the network address book.<br/>
      * This value is REQUIRED.
      */
     uint64 node_id = 1;
 
     /**
-     * An account identifier.<br/>
+     * An account identifier.
+     * <p>
      * This account MUST be owned by the entity responsible for the node.<br/>
      * This account SHALL be charged transaction fees for any transactions that
      * are submitted to the network by this node and fail due diligence checks.
      */
     proto.AccountID account_id = 2;
 
     /**
-     * A short description of the consensus node.<br/>
+     * A short description of the consensus node.
+     * <p>
      * This value, if present, MUST NOT exceed 100 bytes when encoded as UTF-8.
      */
     string description = 3;
 
     /**
-     * A list of service endpoints.<br/>
+     * A list of service endpoints for gossip.
+     * <p>
      * These endpoints SHALL specify address and port.<br/>
      * These endpoints SHALL NOT specify a DNS name.<br/>
      * This list SHALL NOT be empty.<br/>
@@ -100,41 +116,44 @@ message NodeInfo {
     repeated proto.ServiceEndpoint gossip_endpoint = 4;
 
     /**
-     * A list of service endpoints.<br/>
-     * These endpoints SHALL represent the published endpoints to which clients
-     * may submit transactions.<br/>
+     * A list of service endpoints for gRPC calls.
+     * <p>
+     * These endpoints SHALL represent the published gRPC endpoints to which
+     * clients may submit transactions.<br/>
      * These endpoints SHALL specify address and port.<br/>
-     * These endpoints SHALL NOT specify DNS name.<br/>
+     * These endpoints MAY specify DNS name.<br/>
      * This list SHALL NOT be empty.<br/>
      * This list SHALL NOT contain more than `8` entries.
      */
     repeated proto.ServiceEndpoint service_endpoint = 5;
 
     /**
-     * A certificate used to sign gossip events.<br/>
+     * A certificate used to sign gossip events.
+     * <p>
      * This value SHALL be a certificate of a type permitted for gossip
      * signatures.<br/>
-     * The value presented SHALL be a UTF-8 NFKD encoding of the TLS
-     * certificate.<br/>
-     * The certificate encoded SHALL be in PEM format.<br/>
+     * This value SHALL be a UTF-8 NFKD encoding of the
+     * certificate presented in PEM format.<br/>
      * This field is REQUIRED and MUST NOT be empty.
      */
     bytes gossip_ca_certificate = 6;
 
     /**
-     * A hash of the node gRPC TLS certificate.<br/>
+     * A hash of the node gRPC TLS certificate.
+     * <p>
      * This value MAY be used to verify the certificate presented by the node
      * during TLS negotiation for gRPC.<br/>
      * This value MUST be a SHA-384 hash.<br/>
-     * The value to be hashed MUST be a UTF-8 NFKD encoding of the TLS
-     * certificate.<br/>
-     * The certificate to be encoded MUST be in PEM format.<br/>
+     * The TLS certificate to be hashed SHALL first be in PEM format and SHALL
+     * be encoded with UTF-8 NFKD encoding to a stream of bytes provided to
+     * the hash algorithm.<br/>
      * This field is OPTIONAL.
      */
     bytes grpc_certificate_hash = 7;
 
     /**
-     * A consensus weight.<br/>
+     * A consensus weight.
+     * <p>
      * Each node SHALL have a weight in consensus calculations.<br/>
      * The consensus weight of a node SHALL be calculated based on the amount
      * of HBAR staked to that node.<br/>
@@ -144,7 +163,8 @@ message NodeInfo {
     uint64 weight = 8;
 
     /**
-     * A flag indicating this node was removed from the network.<br/>
+     * A flag indicating this node was removed from the network.
+     * <p>
      * This flag SHALL NOT be set unless a `deleteNode` transaction previously
      * succeeded identifying that node.<br/>
      * If this flag is set, the associated node SHALL NOT participate in the
@@ -153,7 +173,8 @@ message NodeInfo {
     bool deleted = 10;
 
     /**
-     * A ledger ID.<br/>
+     * A ledger ID.
+     * <p>
      * This identifies the network that responded to this query.
      * The specific values are documented in [HIP-198]
      * (https://hips.hedera.com/hip/hip-198).
@@ -166,14 +187,16 @@ message NodeInfo {
  */
 message NodeGetInfoResponse {
     /**
-     * The standard response information for queries.<br/>
+     * The standard response information for queries.
+     * <p>
      * This includes the values requested in the `QueryHeader`
      * (cost, state proof, both, or neither).
      */
     proto.ResponseHeader header = 1;
 
     /**
-     * The requested detail information.<br/>
+     * The requested detail information.
+     * <p>
      * This message SHALL contain the full detail for the node identified in the
      * query request.
      */

diff --git a/services/node_update.proto b/services/node_update.proto
@@ -1,3 +1,12 @@
+/**
+ * # Node Update
+ * Messages to modify a consensus node in the network address book.
+ *
+ * ### 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).
+ */
 syntax = "proto3";
 
 package com.hedera.hapi.node.addressbook;
@@ -31,11 +40,11 @@ import "basic_types.proto";
  * - This transaction SHALL enable the node operator, as identified by the
  *   node account, to modify operational attributes of the node.
  * - This transaction MUST be signed by the active `key` for the current node
- *   account.
+ *   account or by the Hedera governing council.
  * - This transaction SHALL NOT change any field that is not set (is null) in
  *   this transaction body.
  * - This SHALL create a pending update to the node, but the change SHALL NOT
- *   be applied to the active configuration.
+ *   be immediately applied to the active configuration.
  * - All pending node updates SHALL be applied to the active network
  *   configuration during the next `freeze` transaction with the field
  *   `freeze_type` set to `PREPARE_UPGRADE`.

diff --git a/services/query.proto b/services/query.proto
@@ -202,6 +202,6 @@ message Query {
         /**
          * Get all information about a node
          */
-        NodeGetInfoQuery nodeGetInfo = 59;
+        com.hedera.hapi.node.addressbook.NodeGetInfoQuery nodeGetInfo = 59;
     }
 }
diff --git a/services/state/addressbook/node.proto b/services/state/addressbook/node.proto
@@ -46,29 +46,33 @@ option java_multiple_files = true;
  */
 message Node {
     /**
-     * A consensus node identifier.<br/>
+     * A consensus node identifier.
+     * <p>
      * Node identifiers SHALL be unique _within_ a shard and realm,
      * but a node SHALL NOT, ever, serve multiple shards or realms,
      * therefore the node identifier MAY be repeated _between_ shards and realms.
      */
     uint64 node_id = 1;
 
     /**
-     * An account identifier.<br/>
+     * An account identifier.
+     * <p>
      * This account MUST be owned by the entity responsible for the node.<br/>
      * This account SHALL be charged transaction fees for any transactions that
      * are submitted to the network by this node and fail due diligence checks.
      */
     proto.AccountID account_id = 2;
 
     /**
-     * A short description of the node.<br/>
+     * A short description of the node.
+     * <p>
      * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.
      */
     string description = 3;
 
     /**
-     * A list of service endpoints.<br/>
+     * A list of service endpoints.
+     * <p>
      * These endpoints SHALL specify address and port.<br/>
      * These endpoints SHALL NOT specify a DNS name.<br/>
      * This list SHALL NOT be empty.<br/>
@@ -80,7 +84,8 @@ message Node {
     repeated proto.ServiceEndpoint gossip_endpoint = 4;
 
     /**
-     * A list of service endpoints.<br/>
+     * A list of service endpoints for gRPC calls.
+     * <p>
      * These endpoints SHALL represent the published endpoints to which clients
      * may submit transactions.<br/>
      * These endpoints SHALL specify address and port.<br/>
@@ -91,30 +96,32 @@ message Node {
     repeated proto.ServiceEndpoint service_endpoint = 5;
 
     /**
-     * A certificate used to sign gossip events.<br/>
+     * A certificate used to sign gossip events.
+     * <p>
      * This value SHALL be a certificate of a type permitted for gossip
      * signatures.<br/>
-     * The value presented SHALL be a UTF-8 NFKD encoding of the TLS
-     * certificate.<br/>
-     * The certificate encoded SHALL be in PEM format.<br/>
+     * This value SHALL be a UTF-8 NFKD encoding of the
+     * certificate presented in PEM format.<br/>
      * This field is REQUIRED and MUST NOT be empty.
      */
     bytes gossip_ca_certificate = 6;
 
     /**
-     * A hash of the node gRPC certificate.<br/>
+     * A hash of the node gRPC certificate.
+     * <p>
      * This value MAY be used to verify the certificate presented by the node
      * during TLS negotiation for gRPC.<br/>
      * This value MUST be a SHA-384 hash.<br/>
-     * The value to be hashed MUST be a UTF-8 NFKD encoding of the TLS
-     * certificate.<br/>
-     * The certificate to be encoded MUST be in PEM format.<br/>
+     * The TLS certificate to be hashed SHALL first be in PEM format and SHALL
+     * be encoded with UTF-8 NFKD encoding to a stream of bytes provided to
+     * the hash algorithm.<br/>
      * This field is OPTIONAL.
      */
     bytes grpc_certificate_hash = 7;
 
     /**
-     * A consensus weight.<br/>
+     * A consensus weight.
+     * <p>
      * Each node SHALL have a weight in consensus calculations.<br/>
      * The consensus weight of a node SHALL be calculated based on the amount
      * of HBAR staked to that node.<br/>
@@ -165,15 +172,17 @@ enum NodeStatus {
 
     /**
      * A consensus node in this state is newly created but not yet active on
-     * the network.<br/>
+     * the network.
+     * <p>
      * The node SHALL become active following the next `freeze` transaction
      * with the field `freeze_type` set to `PREPARE_UPGRADE`.
      */
     PENDING_ADDITION = 1;
 
     /**
      * A consensus node in this state is subject to a request to delete
-     * that node.<br/>
+     * that node.
+     * <p>
      * The node SHALL be removed from the network following the next
      * `freeze` transaction with the field `freeze_type` set to
      * `PREPARE_UPGRADE`.