Updates following review

* Added missing "discoverable" for node update transaction message name.
* Added missing detail in the "Discoverable Node" definition.
* Clarified that account ID is not relevant to discoverable nodes.
* Added a specification for the value in state used to store the
  discoverable node information.
* Added detail for admin key usage, network throttles, and related
  information to the security implications section.
* Added an SDK Considerations section.
* Added Mirror Node as a node type.
* Cleaned up some specification wording.
* Added some detail to the "reputation" open issue.
* Added some initial use cases, community ideas and revision are encouraged.

Signed-off-by: Joseph Sinclair <121976561+jsync-swirlds@users.noreply.github.com>

Author: jsync-swirlds

HIP/hip-1137.md

@@ -2,15 +2,15 @@
 hip: 1137
 title: Block Node discoverabilty via the network address book
 author: Joseph Sinclair <@jsync-swirlds>
-working-group: Joseph Sinclair <@jsync-swirlds>
-requested-by: Hedera Consensus Node Operators
+working-group: Joseph Sinclair <@jsync-swirlds>, Jasper Potts <@jasperpotts>, Richard Bair <@rbair>, Nana Essilfie-Conduah <@Nana-EC>, 
+requested-by: Mirror Node Operators, Relay Node Operators, SDK developers
 type: Standards Track
 category: Core
 needs-council-approval: Yes
 discussions-to: https://github.com/hashgraph/Hiero-improvement-proposal/discussions/1132
 status: Draft
 created: 2025-03-07
-updated: 2025-03-07
+updated: 2025-03-18
 ---
 
 ## Abstract
@@ -31,37 +31,66 @@ fees for providing both core and value-add services to clients. A service
 is of no value, however, if the service provider cannot be found. Offering a
 mechanism to find a Block Node by querying network state ensures a reliable
 and trustworthy source of data that is dynamically managed and updated by the
-Block Node operators themselves. Including a mechanism for reputation to be
-recorded and managed, we enable the full community of network users to share
-assessment of block node reliability and quality.
+Block Node operators themselves. Considering a future mechanism for reputation
+to be recorded and managed, we enable the full community of network users to
+share assessment of block node reliability and quality.
 
 ## Rationale
 Discoverability of services is critical to a broadly useful network and
 effective development of network applications. The addition of basic service
 discovery functionality supports the current addition of block nodes to the
 network, and lays groundwork for adding additional discovery mechanisms in
-future proposals.
+future proposals. While the proximate motivation for this capability is to
+enable discoverability of block nodes, it is also clear that block nodes are
+not the only form of discoverable nodes that could, or should, be published
+on the blockchain.
 
 ## Definitions
 <dl>
 <dt>Discoverable Node</dt>
-<dd>A node that participates in a Hiero Ledger network, is not a
-discoverable node, and may be discovered via the node discovery process.</dd>
+<dd>A node that participates in a Hiero Ledger network, but is not a
+consensus node, is a discoverable node, and may be discovered via the node
+discovery process. Discoverable nodes do not require on-chain upgrade
+coordination and are generally managed as fully independent individual
+entities. Each type of discoverable node has its own mechanism for discovering
+and using resources specific to that type of node. The address book only
+provides the type of node and one or more service endpoints.</dd>
 </dl>
 
 ## User stories
+1. As a RPC Relay client, I wish to find an RPC relay using on-chain data.
+1. As a Block Node, I need to connect to other block nodes found by inspecting
+   block stream data.
+1. As a Mirror Node, I want to present discoverable nodes to clients using
+   on-chain data.
+1. As a Hiero community member, I want to operate a discoverable node and
+   publish the type and endpoints on-chain so that others can find my service.
+1. As the operator of a private Hiero ledger, I want to mange the discoverable
+   nodes relevant to my ledger using on-chain data.
+1. As a discoverable node operator, I want to publish and manage my discoverable
+   node on a Hiero ledger so that clients can reliably find and connect to my
+   service.
 
 ## Specification
 This HIP proposes the introduction of additional NodeService APIs that enable a
 discoverable node operator to create, delete, and update discoverable nodes.
 
+Several messages refer to a "Node ID". This is a single entity number that
+is assigned on node creation by the network, and is unique within a particular
+shard and realm. Discoverable nodes are specific to a shard and realm, although
+nothing technically prevents a single system from being registered as a node in
+multiple shards or multiple realms. The consensus network may assign any value
+to a new node, except that a given Node ID must never be reused within a given
+shard or realm. The Node ID values for Discoverable Nodes must not match the
+Node ID value for any consensus node in the same network.
+
 ```protobuf
 service AddressBookService {
 
     [...]
 
     /**
-     * A transaction to create a new discoverable node in the network.
+     * A transaction to create a new discoverable node in the network
      * address book.
      * <p>
      * This transaction, once complete, SHALL add a new discoverable node to the
@@ -100,19 +129,18 @@ A new Hiero API element will be added, named DiscoverableServiceEndpoint.
  * more endpoints which enable the nodes to communicate both with other
  * nodes and with clients to receive requests.
  *
- * This message supports IP (V4 or V6) with address and TCP port,
- * and MAY include a FQDN instead of an IP address.<br/>
+ * This message supports a TCP port and IP address (V4 or V6),
+ * or MAY include a FQDN _instead of_ an IP address.<br/>
  */
 message DiscoverableServiceEndpoint {
     oneof address {
         /**
          * A 32-bit IPv4 address or 128-bit IPv6 address.<br/>
          * This is the address of the endpoint, encoded in pure "big-endian"
          * (i.e. left to right) order (e.g. `127.0.0.1` has hex bytes in the
-         * order `7F`, `00`, `00`, `01` and ::1 is `00`, `00`, `00`, `00`,
+         * order `7F`, `00`, `00`, `01` and `::1` is `00`, `00`, `00`, `00`,
          * `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`,
-         * `00`, `01`).<br/>
-         * IPv6 MAY NOT be accessible to all clients.
+         * `00`, `01`).
          */
         bytes ip_address = 1;
 
@@ -134,7 +162,6 @@ message DiscoverableServiceEndpoint {
      */
     uint32 tcp_port = 3;
 }
-
 ```
 
 A new Hiero API will be added called DiscoverableNodeCreate, which falls under
@@ -149,13 +176,17 @@ message DiscoverableNodeCreateTransactionBody {
      * This key MUST sign this transaction.<br/>
      * This key MUST sign each transaction to update this node.<br/>
      * This field MUST contain a valid `Key` value.<br/>
-     * This field is REQUIRED and MUST NOT be set to an empty `KeyList`.
+     * This field is REQUIRED and MUST NOT be set to an empty `KeyList`.<br/>
+     * It is RECOMMENDED that this key be composed of one or more unique public
+     * keys that are not associated with any network account.<br/>
+     * This key MAY be a complex key containing `KeyList` or `ThresholdKey`
+     * elements, but SHOULD NOT be a contract ID key.
      */
     proto.Key admin_key = 1;
 
     /**
      * A node type.<br/>
-     * This declares the type of discoverable node.  Examples might include
+     * This declares the type of discoverable node. Examples might include
      * a block node, an rpc relay, or a mirror node.
      * <p>
      * This field is REQUIRED.
@@ -190,7 +221,7 @@ message DiscoverableNodeCreateTransactionBody {
  */
 enum DiscoverableNodeType {
     /**
-     * This value MUST NOT be used.
+     * This value indicates unset or missing data and MUST NOT be used.
      */
     UNKNOWN = 0;
 
@@ -202,42 +233,60 @@ enum DiscoverableNodeType {
     BLOCK_NODE = 1;
 
     /**
-     * An RPC Relay node.<br/>
-     * An RPC Relay Node is a proxy and translator between EVM tooling and a
+     * A Hiero Mirror Node.<br/>
+     * A Mirror Node is an advanced indexing and query service that provides
+     * fast and flexible access to query the block chain and transaction
+     * history. A Mirror Node typically stores all recent blockchain data, and
+     * some store the entire history of the network.
+     */
+    MIRROR_NODE = 2;
+
+    /**
+     * A RPC Relay node.<br/>
+     * A RPC Relay Node is a proxy and translator between EVM tooling and a
      * Hiero consensus network.
      */
-    RPC_RELAY = 2;
+    RPC_RELAY = 3;
 }
-
 ```
 
 A new Hiero API called DiscoverableNodeDelete will be added under the Node
 Service. This API function is used by the node operator to delete a node.
 
 ```protobuf
-message NodeDeleteTransactionBody {
+message DiscoverableNodeDeleteTransactionBody {
     /**
      * A discoverable node identifier in the network state.
      * <p>
      * The node identified MUST exist in the discoverable address book.<br/>
      * The node identified MUST NOT be deleted.<br/>
      * This value is REQUIRED.
+     * <p>
+     * A given value for `node_id` SHALL be unique within a given
+     * shard or realm.<br/>
+     * A given value for `node_id` SHALL NOT be reused, even if the
+     * corresponding entry is deleted.
      */
     uint64 node_id = 1;
 }
 ```
 
-A new Hiero API called NodeUpdate will be added under the Node Service.
-This function is used by the node operator to update a node.
+A new Hiero API called DiscoverableNodeUpdate will be added under the Node
+Service. This function is used by the node operator to update a node.
 
 ```protobuf
-message NodeUpdateTransactionBody {
+message DiscoverableNodeUpdateTransactionBody {
     /**
      * A discoverable node identifier in the network state.
      * <p>
      * The node identified MUST exist in the discoverable address book.<br/>
      * The node identified MUST NOT be deleted.<br/>
      * This value is REQUIRED.
+     * <p>
+     * A given value for `node_id` SHALL be unique within a given
+     * shard or realm.<br/>
+     * A given value for `node_id` SHALL NOT be reused, even if the
+     * corresponding entry is deleted.
      */
     uint64 node_id = 1;
 
@@ -249,7 +298,11 @@ message NodeUpdateTransactionBody {
      * If set, this key MUST sign each subsequent transaction to
      * update this node.<br/>
      * If set, this field MUST contain a valid `Key` value.<br/>
-     * If set, this field MUST NOT be set to an empty `KeyList`.
+     * If set, this field MUST NOT be set to an empty `KeyList`.<br/>
+     * It is RECOMMENDED that this key be composed of one or more unique public
+     * keys that are not associated with any network account.<br/>
+     * This key MAY be a complex key containing `KeyList` or `ThresholdKey`
+     * elements, but SHOULD NOT be a contract ID key.
      */
     proto.Key admin_key = 2;
 
@@ -278,6 +331,57 @@ message NodeUpdateTransactionBody {
 }
 ```
 
+The Hiero consensus network will store discoverable node information in state
+with the following message structure.
+
+```protobuf
+message DiscoverableAddressBookNode {
+    /**
+     * A discoverable node identifier.
+     * <p>
+     * This value SHALL be set.<br/>
+     * This value SHALL be unique within a given network.<br/>
+     * This value SHALL NOT match any consensus node ID in the same network.
+     * <p>
+     * A given value for `node_id` MUST be unique within a given
+     * shard or realm.<br/>
+     * A given value for `node_id` MUST NOT be reused, even if the
+     * corresponding entry is later deleted.
+     */
+    uint64 node_id = 1;
+
+    /**
+     * An administrative key controlled by the node operator.
+     * <p>
+     * This key MUST sign each transaction to update this node.<br/>
+     * This field SHALL contain a valid `Key` value.<br/>
+     * This field SHALL NOT be set to an empty `KeyList`.<br/>
+     * It is RECOMMENDED that this key be composed of one or more unique public
+     * keys that are not associated with any network account.<br/>
+     * This key MAY be a complex key containing `KeyList` or `ThresholdKey`
+     * elements, but SHOULD NOT be a contract ID key.
+     */
+    proto.Key admin_key = 2;
+
+    /**
+     * A short description of the node.
+     * <p>
+     * This value SHALL NOT exceed 100 bytes when encoded as UTF-8.
+     */
+    string description = 3;
+
+    /**
+     * A list of service endpoints for client calls.
+     * <p>
+     * These endpoints SHALL represent the published endpoints to which
+     * clients may submit requests.<br/>
+     * This list SHALL NOT be empty.<br/>
+     * This list SHALL NOT contain more than `10` entries.
+     */
+    repeated DiscoverableServiceEndpoint service_endpoint = 4;
+}
+```
+
 The following are some changes to the existing API.
 
 Added three HieroFunctionalities:
@@ -312,12 +416,14 @@ message TransactionReceipt {
     [...]
 
     /**
-    * The identifier of a newly created Node or DiscoverableNode.
-    * <p>
-    * This value SHALL be set following a `createNode` transaction.<br/>
-    * This value SHALL be set following a `createDiscoverableNode`
-    * transaction.<br/>
-    * This value SHALL NOT be set following any other transaction.
+     * The identifier of a newly created Node or DiscoverableNode.
+     * <p>
+     * This value SHALL be set following a `createNode` transaction.<br/>
+     * This value SHALL be set following a `createDiscoverableNode`
+     * transaction.<br/>
+     * This value SHALL NOT be set following any other transaction.<br/>
+     * This value SHALL be unique within a given network.<br/>
+     * This value SHALL NOT match any consensus node ID in the same network.
     */
     uint64 node_id = 15;
 
@@ -327,22 +433,48 @@ message TransactionReceipt {
 ### Mirror node update
 The mirror node will process the new Discoverable Node transactions and
 discoverable_service_endpoint information, then return that information through
-extensions to its existing APIs.
+extensions to its existing APIs or new APIs, as needed.
+One _possible_ extension would be to add a `/api/v1/network/discoverableNodes`
+resource which accepts a `nodeType` query parameter and returns a list of nodes
+with that type, or a list of all discoverable nodes if the parameter is not
+supplied.
+
+### SDK Considerations
+Each SDK will need to implement the following _new_ transactions.
+- `createDiscoverableNode`
+- `updateDiscoverableNode`
+- `deleteDiscoverableNode`
+There is no change to existing transactions. The create transaction sets the
+same `node_id` field in the transaction receipt used by the existing
+non-discoverable nodeCreate transaction.
 
 ## Backwards Compatibility
 All changes for this HIP are net-new functionality. There is no predicted
 impact or change for existing functionality.
 
 ## Security Implications
-TBD
+The signatory for all discoverable node transactions (create, update, delete)
+is the assigned `admin_key` value for that node. This maintains management of
+each discoverable node firmly with the creator/operator. Discoverable nodes do
+not participate in any form of consensus network rewards, so no account
+identifier is required for a discoverable node. It is RECOMMENDED that the
+`admin_key` be composed of one or more unique public keys that are not
+associated with any network account.
+
+The network throttles will need to be updated to place appropriate limits on
+the number of discoverable node transactions. Such transactions should not be
+frequent, and relevant throttles should have corresponding limits.
+
+We do not expect to place any restriction on who can create a discoverable node,
+and the only limitation to who can update or delete a discoverable node is that
+the transaction must be signed by the `admin_key` for that node.
 
 ## How to Teach This
 TBD
 
 ## Reference Implementation
 
 ## Rejected Ideas
-
 1. Use of the existing consensus node address book and transactions was
    considered.
    * This was rejected for three reasons.
@@ -355,10 +487,14 @@ TBD
          requirements.
 
 ## Open Issues
-
 1. We intend to store a uint64 "reputation" value for each discoverable node,
    but have not determined an appropriate and workable mechanism for allowing
    network entities to "vote" on that reputation.
+   * One concept discussed is to use something similar to a
+     "proof of space-time" and a "proof of streaming" for block nodes
+     (as one example) as an automated "reputation" modifier. How this would
+     be integrated with community sentiment remains an open question.
+   * This concept should be the subject of a future HIP.
 
 ## References