HIP-1137 Block Node Discoverability

* Add new HIP document describing discoverable nodes * This may be block nodes, rpc relays, or any other node that should be discoverable by any network participant. Signed-off-by: Joseph Sinclair <[email protected]>
hashgraph · Mar 7, 2025 · 0f8a0b2 · 0f8a0b2
1 parent ffac4ba
commit 0f8a0b2
Showing 1 changed file with 362 additions and 0 deletions.
diff --git a/HIP/hip-1137.md b/HIP/hip-1137.md
@@ -0,0 +1,362 @@
+---
+hip: 1137
+title: Block Node discoverabilty via the network address book
+author: Joseph Sinclair <@jsync-swirlds>
+working-group: 
+requested-by: 
+type: Standards Track
+category: Core
+needs-council-approval: Yes
+discussions-to: https://github.com/hashgraph/Hiero-improvement-proposal/discussions/1132
+status: Draft
+last-call-date-time: 
+created: 2025-03-06
+updated: 2025-03-06
+---
+
+## Abstract
+With the addition of Block Nodes to the Hiero ledger, clients will need a
+reliable mechanism to find functioning block nodes. This HIP proposes to add
+a new type of address book entry, and transactions to enable block node
+operators to add and manage their nodes in the network. A mechanism is also
+proposed to enable the community to generate and record a "reputation" value
+for block nodes as a means for clients to filter block nodes and make rational
+decisions regarding block node reliability and quality.
+
+## Motivation
+Block Nodes are a critical component of any Hiero ledger. The Block Nodes
+manage and provide access to Block Stream and state snapshot data, as well
+as content proof for both blocks and state. Block Nodes may also provide
+additional value-add services integral to their core function, and may charge
+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.
+
+## 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.
+
+## 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>
+</dl>
+
+## User stories
+
+## Specification
+This HIP proposes the introduction of additional NodeService APIs that enable a
+discoverable node operator to create, delete, and update discoverable nodes.
+
+```protobuf
+service AddressBookService {
+
+    [...]
+
+    /**
+     * 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
+     * network state.<br/>
+     * The new discoverable node SHALL be visible and discoverable upon
+     * completion of this transaction.
+     */
+    rpc createDiscoverableNode (proto.Transaction) returns (proto.TransactionResponse);
+
+    /**
+     * A transaction to remove a discoverable node from the network address
+     * book.
+     * <p>
+     * This transaction, once complete, SHALL remove the identified discoverable
+     * node from the network state.
+     */
+    rpc deleteDiscoverableNode (proto.Transaction) returns (proto.TransactionResponse);
+
+    /**
+     * A transaction to update an existing discoverable node in the network
+     * address book.
+     * <p>
+     * This transaction, once complete, SHALL modify the identified discoverable
+     * node state as requested.
+     */
+    rpc updateDiscoverableNode (proto.Transaction) returns (proto.TransactionResponse);
+}
+```
+
+A new Hiero API element will be added, named DiscoverableServiceEndpoint.
+
+```protobuf
+/**
+ * A discoverable network node endpoint.<br/>
+ * Each discoverable network node in the global address book publishes one or
+ * 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/>
+ *
+ * When the `domain_name` field is set, the `ip_address` field
+ * MUST NOT be set.<br/>
+ * When the `ip_address` field is set, the `domain_name` field
+ * MUST NOT be set.
+ */
+message DiscoverableServiceEndpoint {
+    /**
+     * 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`, `00`,
+     * `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `01`).<br/>
+     * IPv6 MAY NOT be accessible to all clients due to persistent limitations
+     * in global internet routing.
+     */
+    bytes ip_address = 1;
+
+    /**
+     * A TCP port to use.
+     * <p>
+     * This value MUST be between 0 and 65535, inclusive.<br/>
+     * This value is REQUIRED.
+     */
+    uint32 tcp_port = 2;
+
+    /**
+     * A node domain name.
+     * <p>
+     * This MUST be the fully qualified domain name of the node.<br/>
+     * This value MUST NOT exceed 250 ASCII characters.<br/>
+     * This value MUST meet all other DNS name requirements.<br/>
+     * When the `domain_name` field is set, the `ipAddress`
+     * field MUST NOT be set.<br/>
+     * When the `ipAddress` field is set, the `domain_name`
+     * field MUST NOT be set.
+     */
+    string domain_name = 3;
+}
+
+```
+
+A new Hiero API will be added called DiscoverableNodeCreate, which falls under
+the Node Service category. This function is used by the node operator to create
+a new node.
+
+```protobuf
+message DiscoverableNodeCreateTransactionBody {
+    /**
+     * A Node account identifier.
+     * <p>
+     * This account identifier MUST be in the "account number" form.<br/>
+     * This account identifier MUST NOT use the alias field.<br/>
+     * If the identified account does not exist, this transaction
+     * SHALL fail.<br/>
+     * Multiple nodes MAY share the same node account.<br/>
+     * This field is REQUIRED.
+     */
+    proto.AccountID account_id = 1;
+
+    /**
+     * A short description of the node.
+     * <p>
+     * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.<br/>
+     * This field is OPTIONAL.
+     */
+    string description = 2;
+
+    /**
+     * A list of service endpoints for client calls.
+     * <p>
+     * These endpoints SHALL represent the published endpoints to which
+     * clients may submit requests.<br/>
+     * Endpoints in this list MAY supply either IP address or FQDN, but MUST
+     * NOT supply both values for the same endpoint.<br/>
+     * This list MUST NOT be empty.<br/>
+     * This list MUST NOT contain more than `10` entries.
+     */
+    repeated DiscoverableServiceEndpoint service_endpoint = 3;
+
+    /**
+     * An administrative key controlled by the node operator.
+     * <p>
+     * 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`.
+     */
+    proto.Key admin_key = 7;
+}
+
+```
+
+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 {
+    /**
+     * 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.
+     */
+    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.
+
+```protobuf
+message NodeUpdateTransactionBody {
+    /**
+     * 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.
+     */
+    uint64 node_id = 1;
+
+    /**
+     * An account identifier.
+     * <p>
+     * This field is OPTIONAL.<br/>
+     * If set, this SHALL replace the node account identifier.<br/>
+     * If set, this transaction MUST be signed by the active `key` for _both_
+     * the current node account _and_ the identified new node account.
+     */
+    proto.AccountID account_id = 2;
+
+    /**
+     * A short description of the node.
+     * <p>
+     * This field is OPTIONAL.<br/>
+     * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.<br/>
+     * If set, this value SHALL replace the previous value.
+     */
+    google.protobuf.StringValue description = 3;
+
+    /**
+     * A list of service endpoints for client calls.
+     * <p>
+     * This field is OPTIONAL.<br/>
+     * These endpoints SHALL represent the published endpoints to which
+     * clients may submit requests.<br/>
+     * Endpoints in this list MAY supply either IP address or FQDN, but MUST
+     * NOT supply both values for the same endpoint.<br/>
+     * If set, this list MUST NOT be empty.<br/>
+     * If set, this list MUST NOT contain more than `10` entries.
+     */
+    repeated DiscoverableServiceEndpoint service_endpoint = 3;
+
+    /**
+     * An administrative key controlled by the node operator.
+     * <p>
+     * This field is OPTIONAL.<br/>
+     * If set, this key MUST sign this transaction.<br/>
+     * 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`.
+     */
+    proto.Key admin_key = 7;
+}
+```
+
+The following are some changes to the existing API.
+
+Added three HieroFunctionalities:
+
+```protobuf
+enum HieroFunctionality {
+
+    [...]
+
+    /**
+    * Create a discoverable node
+    */
+    DiscoverableNodeCreate = 101;
+
+    /**
+     * Update a discoverable node
+     */
+    DiscoverableNodeUpdate = 102;
+
+    /**
+     * Delete a discoverable node
+     */
+    DiscoverableNodeDelete = 103;
+}
+```
+
+Adjusted `node_id` in `TransactionReceipt`:
+
+```protobuf
+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.
+    */
+    uint64 node_id = 15;
+
+}
+```
+
+### 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.
+
+## Backwards Compatibility
+All changes for this HIP are net-new functionality. There is no predicted
+impact or change for existing functionality.
+
+## Security Implications
+TBD
+
+## 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.
+      1. The existing Node transactions and state objects include a substantial
+         amount of data that has no relevancy to discoverable nodes
+      2. The consensus nodes do not, and should not, include the additional
+         information specific to discoverable nodes
+      3. The modification of discoverable nodes and consensus nodes have
+         vastly different risk profiles, and mandate very different signatory
+         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.
+
+## References
+
+## Copyright/license
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+This document is licensed under the Apache License, Version 2.0 --
+see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)