Skip to content

Commit c03c8b3

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 c03c8b3

File tree

1 file changed

+361
-0
lines changed

1 file changed

+361
-0
lines changed

‎HIP/hip-1137.md

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

0 commit comments

Comments
 (0)