Skip to content

Commit 0f8a0b2

Browse files
jsync-swirldsjsync-swirlds
committed
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 <121976561+jsync-swirlds@users.noreply.github.com>
1 parent ffac4ba commit 0f8a0b2

File tree

1 file changed

+362
-0
lines changed

1 file changed

+362
-0
lines changed

‎HIP/hip-1137.md

Lines changed: 362 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,362 @@
1+
---
2+
hip: 1137
3+
title: Block Node discoverabilty via the network address book
4+
author: Joseph Sinclair <@jsync-swirlds>
5+
working-group:
6+
requested-by:
7+
type: Standards Track
8+
category: Core
9+
needs-council-approval: Yes
10+
discussions-to: https://github.com/hashgraph/Hiero-improvement-proposal/discussions/1132
11+
status: Draft
12+
last-call-date-time:
13+
created: 2025-03-06
14+
updated: 2025-03-06
15+
---
16+
17+
## Abstract
18+
With the addition of Block Nodes to the Hiero ledger, clients will need a
19+
reliable mechanism to find functioning block nodes. This HIP proposes to add
20+
a new type of address book entry, and transactions to enable block node
21+
operators to add and manage their nodes in the network. A mechanism is also
22+
proposed to enable the community to generate and record a "reputation" value
23+
for block nodes as a means for clients to filter block nodes and make rational
24+
decisions regarding block node reliability and quality.
25+
26+
## Motivation
27+
Block Nodes are a critical component of any Hiero ledger. The Block Nodes
28+
manage and provide access to Block Stream and state snapshot data, as well
29+
as content proof for both blocks and state. Block Nodes may also provide
30+
additional value-add services integral to their core function, and may charge
31+
fees for providing both core and value-add services to clients. A service
32+
is of no value, however, if the service provider cannot be found. Offering a
33+
mechanism to find a Block Node by querying network state ensures a reliable
34+
and trustworthy source of data that is dynamically managed and updated by the
35+
Block Node operators themselves. Including a mechanism for reputation to be
36+
recorded and managed, we enable the full community of network users to share
37+
assessment of block node reliability and quality.
38+
39+
## Rationale
40+
Discoverability of services is critical to a broadly useful network and
41+
effective development of network applications. The addition of basic service
42+
discovery functionality supports the current addition of block nodes to the
43+
network, and lays groundwork for adding additional discovery mechanisms in
44+
future proposals.
45+
46+
## Definitions
47+
<dl>
48+
<dt>Discoverable Node</dt>
49+
<dd>A node that participates in a Hiero Ledger network, is not a
50+
discoverable node, and may be discovered via the node discovery process.</dd>
51+
</dl>
52+
53+
## User stories
54+
55+
## Specification
56+
This HIP proposes the introduction of additional NodeService APIs that enable a
57+
discoverable node operator to create, delete, and update discoverable nodes.
58+
59+
```protobuf
60+
service AddressBookService {
61+
62+
[...]
63+
64+
/**
65+
* A transaction to create a new discoverable node in the network.
66+
* address book.
67+
* <p>
68+
* This transaction, once complete, SHALL add a new discoverable node to the
69+
* network state.<br/>
70+
* The new discoverable node SHALL be visible and discoverable upon
71+
* completion of this transaction.
72+
*/
73+
rpc createDiscoverableNode (proto.Transaction) returns (proto.TransactionResponse);
74+
75+
/**
76+
* A transaction to remove a discoverable node from the network address
77+
* book.
78+
* <p>
79+
* This transaction, once complete, SHALL remove the identified discoverable
80+
* node from the network state.
81+
*/
82+
rpc deleteDiscoverableNode (proto.Transaction) returns (proto.TransactionResponse);
83+
84+
/**
85+
* A transaction to update an existing discoverable node in the network
86+
* address book.
87+
* <p>
88+
* This transaction, once complete, SHALL modify the identified discoverable
89+
* node state as requested.
90+
*/
91+
rpc updateDiscoverableNode (proto.Transaction) returns (proto.TransactionResponse);
92+
}
93+
```
94+
95+
A new Hiero API element will be added, named DiscoverableServiceEndpoint.
96+
97+
```protobuf
98+
/**
99+
* A discoverable network node endpoint.<br/>
100+
* Each discoverable network node in the global address book publishes one or
101+
* more endpoints which enable the nodes to communicate both with other
102+
* nodes and with clients to receive requests.
103+
*
104+
* This message supports IP (V4 or V6) with address and TCP port,
105+
* and MAY include a FQDN instead of an IP address.<br/>
106+
*
107+
* When the `domain_name` field is set, the `ip_address` field
108+
* MUST NOT be set.<br/>
109+
* When the `ip_address` field is set, the `domain_name` field
110+
* MUST NOT be set.
111+
*/
112+
message DiscoverableServiceEndpoint {
113+
/**
114+
* A 32-bit IPv4 address or 128-bit IPv6 address.<br/>
115+
* This is the address of the endpoint, encoded in pure "big-endian"
116+
* (i.e. left to right) order (e.g. `127.0.0.1` has hex bytes in the
117+
* order `7F`, `00`, `00`, `01` and ::1 is `00`, `00`, `00`, `00`, `00`,
118+
* `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `01`).<br/>
119+
* IPv6 MAY NOT be accessible to all clients due to persistent limitations
120+
* in global internet routing.
121+
*/
122+
bytes ip_address = 1;
123+
124+
/**
125+
* A TCP port to use.
126+
* <p>
127+
* This value MUST be between 0 and 65535, inclusive.<br/>
128+
* This value is REQUIRED.
129+
*/
130+
uint32 tcp_port = 2;
131+
132+
/**
133+
* A node domain name.
134+
* <p>
135+
* This MUST be the fully qualified domain name of the node.<br/>
136+
* This value MUST NOT exceed 250 ASCII characters.<br/>
137+
* This value MUST meet all other DNS name requirements.<br/>
138+
* When the `domain_name` field is set, the `ipAddress`
139+
* field MUST NOT be set.<br/>
140+
* When the `ipAddress` field is set, the `domain_name`
141+
* field MUST NOT be set.
142+
*/
143+
string domain_name = 3;
144+
}
145+
146+
```
147+
148+
A new Hiero API will be added called DiscoverableNodeCreate, which falls under
149+
the Node Service category. This function is used by the node operator to create
150+
a new node.
151+
152+
```protobuf
153+
message DiscoverableNodeCreateTransactionBody {
154+
/**
155+
* A Node account identifier.
156+
* <p>
157+
* This account identifier MUST be in the "account number" form.<br/>
158+
* This account identifier MUST NOT use the alias field.<br/>
159+
* If the identified account does not exist, this transaction
160+
* SHALL fail.<br/>
161+
* Multiple nodes MAY share the same node account.<br/>
162+
* This field is REQUIRED.
163+
*/
164+
proto.AccountID account_id = 1;
165+
166+
/**
167+
* A short description of the node.
168+
* <p>
169+
* This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.<br/>
170+
* This field is OPTIONAL.
171+
*/
172+
string description = 2;
173+
174+
/**
175+
* A list of service endpoints for client calls.
176+
* <p>
177+
* These endpoints SHALL represent the published endpoints to which
178+
* clients may submit requests.<br/>
179+
* Endpoints in this list MAY supply either IP address or FQDN, but MUST
180+
* NOT supply both values for the same endpoint.<br/>
181+
* This list MUST NOT be empty.<br/>
182+
* This list MUST NOT contain more than `10` entries.
183+
*/
184+
repeated DiscoverableServiceEndpoint service_endpoint = 3;
185+
186+
/**
187+
* An administrative key controlled by the node operator.
188+
* <p>
189+
* This key MUST sign this transaction.<br/>
190+
* This key MUST sign each transaction to update this node.<br/>
191+
* This field MUST contain a valid `Key` value.<br/>
192+
* This field is REQUIRED and MUST NOT be set to an empty `KeyList`.
193+
*/
194+
proto.Key admin_key = 7;
195+
}
196+
197+
```
198+
199+
A new Hiero API called DiscoverableNodeDelete will be added under the Node
200+
Service. This API function is used by the node operator to delete a node.
201+
202+
```protobuf
203+
message NodeDeleteTransactionBody {
204+
/**
205+
* A discoverable node identifier in the network state.
206+
* <p>
207+
* The node identified MUST exist in the discoverable address book.<br/>
208+
* The node identified MUST NOT be deleted.<br/>
209+
* This value is REQUIRED.
210+
*/
211+
uint64 node_id = 1;
212+
}
213+
```
214+
215+
A new Hiero API called NodeUpdate will be added under the Node Service.
216+
This function is used by the node operator to update a node.
217+
218+
```protobuf
219+
message NodeUpdateTransactionBody {
220+
/**
221+
* A discoverable node identifier in the network state.
222+
* <p>
223+
* The node identified MUST exist in the discoverable address book.<br/>
224+
* The node identified MUST NOT be deleted.<br/>
225+
* This value is REQUIRED.
226+
*/
227+
uint64 node_id = 1;
228+
229+
/**
230+
* An account identifier.
231+
* <p>
232+
* This field is OPTIONAL.<br/>
233+
* If set, this SHALL replace the node account identifier.<br/>
234+
* If set, this transaction MUST be signed by the active `key` for _both_
235+
* the current node account _and_ the identified new node account.
236+
*/
237+
proto.AccountID account_id = 2;
238+
239+
/**
240+
* A short description of the node.
241+
* <p>
242+
* This field is OPTIONAL.<br/>
243+
* This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.<br/>
244+
* If set, this value SHALL replace the previous value.
245+
*/
246+
google.protobuf.StringValue description = 3;
247+
248+
/**
249+
* A list of service endpoints for client calls.
250+
* <p>
251+
* This field is OPTIONAL.<br/>
252+
* These endpoints SHALL represent the published endpoints to which
253+
* clients may submit requests.<br/>
254+
* Endpoints in this list MAY supply either IP address or FQDN, but MUST
255+
* NOT supply both values for the same endpoint.<br/>
256+
* If set, this list MUST NOT be empty.<br/>
257+
* If set, this list MUST NOT contain more than `10` entries.
258+
*/
259+
repeated DiscoverableServiceEndpoint service_endpoint = 3;
260+
261+
/**
262+
* An administrative key controlled by the node operator.
263+
* <p>
264+
* This field is OPTIONAL.<br/>
265+
* If set, this key MUST sign this transaction.<br/>
266+
* If set, this key MUST sign each subsequent transaction to
267+
* update this node.<br/>
268+
* If set, this field MUST contain a valid `Key` value.<br/>
269+
* If set, this field MUST NOT be set to an empty `KeyList`.
270+
*/
271+
proto.Key admin_key = 7;
272+
}
273+
```
274+
275+
The following are some changes to the existing API.
276+
277+
Added three HieroFunctionalities:
278+
279+
```protobuf
280+
enum HieroFunctionality {
281+
282+
[...]
283+
284+
/**
285+
* Create a discoverable node
286+
*/
287+
DiscoverableNodeCreate = 101;
288+
289+
/**
290+
* Update a discoverable node
291+
*/
292+
DiscoverableNodeUpdate = 102;
293+
294+
/**
295+
* Delete a discoverable node
296+
*/
297+
DiscoverableNodeDelete = 103;
298+
}
299+
```
300+
301+
Adjusted `node_id` in `TransactionReceipt`:
302+
303+
```protobuf
304+
message TransactionReceipt {
305+
306+
[...]
307+
308+
/**
309+
* The identifier of a newly created Node or DiscoverableNode.
310+
* <p>
311+
* This value SHALL be set following a `createNode` transaction.<br/>
312+
* This value SHALL be set following a `createDiscoverableNode`
313+
* transaction.<br/>
314+
* This value SHALL NOT be set following any other transaction.
315+
*/
316+
uint64 node_id = 15;
317+
318+
}
319+
```
320+
321+
### Mirror node update
322+
The mirror node will process the new Discoverable Node transactions and
323+
discoverable_service_endpoint information, then return that information through
324+
extensions to its existing APIs.
325+
326+
## Backwards Compatibility
327+
All changes for this HIP are net-new functionality. There is no predicted
328+
impact or change for existing functionality.
329+
330+
## Security Implications
331+
TBD
332+
333+
## How to Teach This
334+
TBD
335+
336+
## Reference Implementation
337+
338+
## Rejected Ideas
339+
340+
1. Use of the existing consensus node address book and transactions was
341+
considered.
342+
* This was rejected for three reasons.
343+
1. The existing Node transactions and state objects include a substantial
344+
amount of data that has no relevancy to discoverable nodes
345+
2. The consensus nodes do not, and should not, include the additional
346+
information specific to discoverable nodes
347+
3. The modification of discoverable nodes and consensus nodes have
348+
vastly different risk profiles, and mandate very different signatory
349+
requirements.
350+
351+
## Open Issues
352+
353+
1. We intend to store a uint64 "reputation" value for each discoverable node,
354+
but have not determined an appropriate and workable mechanism for allowing
355+
network entities to "vote" on that reputation.
356+
357+
## References
358+
359+
## Copyright/license
360+
<!-- SPDX-License-Identifier: Apache-2.0 -->
361+
This document is licensed under the Apache License, Version 2.0 --
362+
see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)

0 commit comments

Comments
 (0)