@@ -11,10 +11,10 @@ needs-hiero-approval: Yes
1111needs-hedera-review : Yes
1212hedera-review-date :
1313hedera-acceptance-decision :
14- discussions-to : https://github.com/hashgraph/Hiero-improvement-proposal/discussions/1132
14+ discussions-to : https://github.com/hashgraph/Hiero-improvement-proposal/pull/1137
1515status : Review
1616created : 2025-03-07
17- updated : 2026-01-14
17+ updated : 2026-01-20
1818---
1919
2020## Abstract
@@ -47,13 +47,18 @@ on the blockchain.
4747## Definitions
4848<dl >
4949<dt >Discoverable Node</dt >
50- <dd >A node that participates in a Hiero Ledger network, but is not a
50+ <dd >A node that participates in an Hiero Ledger network, but is not a
5151consensus node, is a discoverable node, and may be discovered via the node
5252discovery process. Discoverable nodes do not require on-chain upgrade
5353coordination and are generally managed as fully independent individual
5454entities. Each type of discoverable node has its own mechanism for discovering
5555and using resources specific to that type of node. The address book only
5656provides the type of node and one or more service endpoints.</dd >
57+ <dt >Network Governance</dt >
58+ <dd >Any process, account, set of accounts, smart contract, or other structure
59+ designated by the collective operators and/or owners of a particular Hiero
60+ network to govern the network and ensure that network-wide decisions are
61+ proper and correctly effected. One example is the Hedera governing council.</dd >
5762</dl >
5863
5964## User stories
@@ -62,15 +67,21 @@ provides the type of node and one or more service endpoints.</dd>
6267 block stream data.
63681 . As a Mirror Node, I want to present discoverable nodes to clients using
6469 on-chain data.
65- 1 . As a Hiero community member, I want to operate a discoverable node and
70+ 1 . As an Hiero community member, I want to operate a discoverable node and
6671 publish the type and endpoints on-chain so that others can find my service.
67721 . As the operator of a private Hiero ledger, I want to manage the discoverable
6873 nodes relevant to my ledger using on-chain data.
69741 . As a discoverable node operator, I want to publish and manage my discoverable
70- node on a Hiero ledger so that clients can reliably find and connect to my
75+ node on an Hiero ledger so that clients can reliably find and connect to my
7176 service.
72- 1 . As a Hiero network governing entity I want the option to reward trusted
77+ 1 . As an Hiero network governing entity I want the option to reward trusted
7378 providers of critical network infrastructure services on-chain.
79+ 1 . As an Hiero network governing entity I want the option to remove obsolete or
80+ misbehaving discoverable nodes.
81+ 1 . As an Hiero network governing entity I want to ensure that creation of
82+ discoverable nodes occurs at a reasonable rate and the fees fully compensate
83+ the network for the long-term cost of maintaining the list of discoverable
84+ nodes.
7485
7586## Specification
7687This HIP proposes the introduction of additional NodeService APIs that enable a
@@ -106,7 +117,9 @@ service AddressBookService {
106117 * book.
107118 * <p>
108119 * This transaction, once complete, SHALL remove the identified discoverable
109- * node from the network state.
120+ * node from the network state.<br/>
121+ * This transaction MUST be signed by the existing entry `admin_key` or
122+ * authorized by the Hiero network governance structure.
110123 */
111124 rpc deleteDiscoverableNode (proto.Transaction) returns (proto.TransactionResponse);
112125
@@ -162,6 +175,19 @@ message DiscoverableServiceEndpoint {
162175 * This value is REQUIRED.
163176 */
164177 uint32 port = 3;
178+
179+ /**
180+ * A flag indicating if this endpoint requires TLS.
181+ * <p>
182+ * If this value is set true, then connections to this endpoint MUST
183+ * enable TLS.
184+ * <p>
185+ * TLS endpoints MAY use self-signed certificates for this purpose,
186+ * but use of self-signed certificates SHOULD be limited to testing and
187+ * development environments to ensure production environments meet all
188+ * expected characteristics for transport layer security.
189+ */
190+ bool requires_tls = 4;
165191}
166192```
167193
@@ -209,7 +235,8 @@ message DiscoverableNodeCreateTransactionBody {
209235 * clients may submit requests.<br/>
210236 * Endpoints in this list MAY supply either IP address or FQDN, but MUST
211237 * NOT supply both values for the same endpoint.<br/>
212- * This list MUST NOT be empty.<br/>
238+ * Multiple endpoints in this list MAY resolve to the same interface.<br/>
239+ * This list MAY be empty.<br/>
213240 * This list MUST NOT contain more than `10` entries.
214241 */
215242 repeated DiscoverableServiceEndpoint service_endpoint = 4;
@@ -244,7 +271,13 @@ message DiscoverableNodeCreateTransactionBody {
244271 * If this value is set, this node SHALL NOT receive rewards unless the
245272 * `enable_node_rewards` field is set to `true` for this node.<br/>
246273 * Individual node operators SHALL have full authority to set, change, or
247- * remove their node account ID.
274+ * remove their node account ID.<br/>
275+ * If a node rewards account ID does not resolve to an existing and active
276+ * account that is capable of receiving the rewards when discoverable
277+ * node rewards are calculated, that node SHALL forfeit that specific
278+ * reward payment (if any).<br/>
279+ * Forfeit of any one node reward payment SHALL NOT impact previous or
280+ * future node reward payments.
248281 */
249282 proto.AccountID node_rewards_account = 6;
250283}
@@ -287,6 +320,8 @@ enum DiscoverableNodeType {
287320
288321A new Hiero API called DiscoverableNodeDelete will be added under the Node
289322Service. This API function is used by the node operator to delete a node.
323+ This API function MAY also be used by an Hiero network's governance
324+ structure to administratively delete a discoverable node when necessary.
290325
291326``` protobuf
292327message DiscoverableNodeDeleteTransactionBody {
@@ -520,16 +555,14 @@ message TransactionReceipt {
520555 [...]
521556
522557 /**
523- * The identifier of a newly created Node or DiscoverableNode.
558+ * The identifier of a newly created DiscoverableNode.
524559 * <p>
525- * This value SHALL be set following a `createNode` transaction.<br/>
526560 * This value SHALL be set following a `createDiscoverableNode`
527561 * transaction.<br/>
528562 * This value SHALL NOT be set following any other transaction.<br/>
529- * This value SHALL be unique within a given network.<br/>
530- * This value SHALL NOT match any consensus node ID in the same network.
563+ * This value SHALL be unique within a given network.
531564 */
532- uint64 node_id = 15 ;
565+ uint64 discoverable_node_id = 16 ;
533566
534567}
535568```
590623 * This was rejected for three reasons.
591624 1 . The existing Node transactions and state objects include a substantial
592625 amount of data that has no relevancy to discoverable nodes
593- 2 . The consensus nodes do not, and should not, include the additional
626+ 1 . The consensus nodes do not, and should not, include the additional
594627 information specific to discoverable nodes
595- 3 . The modification of discoverable nodes and consensus nodes have
628+ 1 . The modification of discoverable nodes and consensus nodes have
596629 vastly different risk profiles, and mandate very different signatory
597630 requirements.
5986311 . For the "node rewards" optional feature, we considered using the presence or
603636 for rewards MUST require a signature by the network governance account(s).
604637
605638## Open Issues
639+ 1 . Should we use a full Entity ID (0.0.1234 form) for discoverable node ID
640+ values, or is it reasonable to keep just a single integer (e.g. 28 or 18273)
641+ as the discoverable node ID.
6066421 . We intended to store a uint64 "reputation" value for each discoverable node,
607643 but have not determined an appropriate and workable mechanism for allowing
608644 network entities to "vote" on that reputation.
0 commit comments