Skip to content

Commit 91c3ab0

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 78d3c7c commit 91c3ab0

File tree

1 file changed

+368
-0
lines changed

1 file changed

+368
-0
lines changed

‎HIP/hip-1137.md

Lines changed: 368 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,368 @@
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+
message DiscoverableServiceEndpoint {
107+
oneof address {
108+
/**
109+
* A 32-bit IPv4 address or 128-bit IPv6 address.<br/>
110+
* This is the address of the endpoint, encoded in pure "big-endian"
111+
* (i.e. left to right) order (e.g. `127.0.0.1` has hex bytes in the
112+
* order `7F`, `00`, `00`, `01` and ::1 is `00`, `00`, `00`, `00`,
113+
* `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`, `00`,
114+
* `00`, `01`).<br/>
115+
* IPv6 MAY NOT be accessible to all clients.
116+
*/
117+
bytes ip_address = 1;
118+
119+
/**
120+
* A node domain name.
121+
* <p>
122+
* This MUST be the fully qualified domain name of the node.<br/>
123+
* This value MUST NOT exceed 250 ASCII characters.<br/>
124+
* This value MUST meet all other DNS name requirements.
125+
*/
126+
string domain_name = 2;
127+
}
128+
129+
/**
130+
* A TCP port to use.
131+
* <p>
132+
* This value MUST be between 0 and 65535, inclusive.<br/>
133+
* This value is REQUIRED.
134+
*/
135+
uint32 tcp_port = 3;
136+
}
137+
138+
```
139+
140+
A new Hiero API will be added called DiscoverableNodeCreate, which falls under
141+
the Node Service category. This function is used by the node operator to create
142+
a new node.
143+
144+
```protobuf
145+
message DiscoverableNodeCreateTransactionBody {
146+
/**
147+
* An administrative key controlled by the node operator.
148+
* <p>
149+
* This key MUST sign this transaction.<br/>
150+
* This key MUST sign each transaction to update this node.<br/>
151+
* This field MUST contain a valid `Key` value.<br/>
152+
* This field is REQUIRED and MUST NOT be set to an empty `KeyList`.
153+
*/
154+
proto.Key admin_key = 1;
155+
156+
/**
157+
* A node type.<br/>
158+
* This declares the type of discoverable node. Examples might include
159+
* a block node, an rpc relay, or a mirror node.
160+
* <p>
161+
* This field is REQUIRED.
162+
*/
163+
DiscoverableNodeType node_type = 2;
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 = 3;
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 = 4;
184+
}
185+
186+
/**
187+
* An enumeration of discoverable node types.
188+
*
189+
* These values SHALL represent all _supported_ discoverable nodes.
190+
*/
191+
enum DiscoverableNodeType {
192+
/**
193+
* This value MUST NOT be used.
194+
*/
195+
UNKNOWN = 0;
196+
197+
/**
198+
* A Block Node.<br/>
199+
* A Block Node stores the block chain, provides content proof services,
200+
* and delivers the block stream to other clients.
201+
*/
202+
BLOCK_NODE = 1;
203+
204+
/**
205+
* An RPC Relay node.<br/>
206+
* An RPC Relay Node is a proxy and translator between EVM tooling and a
207+
* Hiero consensus network.
208+
*/
209+
RPC_RELAY = 2;
210+
}
211+
212+
```
213+
214+
A new Hiero API called DiscoverableNodeDelete will be added under the Node
215+
Service. This API function is used by the node operator to delete a node.
216+
217+
```protobuf
218+
message NodeDeleteTransactionBody {
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+
230+
A new Hiero API called NodeUpdate will be added under the Node Service.
231+
This function is used by the node operator to update a node.
232+
233+
```protobuf
234+
message NodeUpdateTransactionBody {
235+
/**
236+
* A discoverable node identifier in the network state.
237+
* <p>
238+
* The node identified MUST exist in the discoverable address book.<br/>
239+
* The node identified MUST NOT be deleted.<br/>
240+
* This value is REQUIRED.
241+
*/
242+
uint64 node_id = 1;
243+
244+
/**
245+
* An administrative key controlled by the node operator.
246+
* <p>
247+
* This field is OPTIONAL.<br/>
248+
* If set, this key MUST sign this transaction.<br/>
249+
* If set, this key MUST sign each subsequent transaction to
250+
* update this node.<br/>
251+
* If set, this field MUST contain a valid `Key` value.<br/>
252+
* If set, this field MUST NOT be set to an empty `KeyList`.
253+
*/
254+
proto.Key admin_key = 2;
255+
256+
/**
257+
* A short description of the node.
258+
* <p>
259+
* This field is OPTIONAL.<br/>
260+
* This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.<br/>
261+
* If set, this value SHALL replace the previous value.
262+
*/
263+
google.protobuf.StringValue description = 3;
264+
265+
/**
266+
* A list of service endpoints for client calls.
267+
* <p>
268+
* This field is OPTIONAL.<br/>
269+
* These endpoints SHALL represent the published endpoints to which
270+
* clients may submit requests.<br/>
271+
* Endpoints in this list MAY supply either IP address or FQDN, but MUST
272+
* NOT supply both values for the same endpoint.<br/>
273+
* If set, this list MUST NOT be empty.<br/>
274+
* If set, this list MUST NOT contain more than `10` entries.<br/>
275+
* If set, this list SHALL _replace_ the previous list.
276+
*/
277+
repeated DiscoverableServiceEndpoint service_endpoint = 4;
278+
}
279+
```
280+
281+
The following are some changes to the existing API.
282+
283+
Added three HieroFunctionalities:
284+
285+
```protobuf
286+
enum HieroFunctionality {
287+
288+
[...]
289+
290+
/**
291+
* Create a discoverable node
292+
*/
293+
DiscoverableNodeCreate = 101;
294+
295+
/**
296+
* Update a discoverable node
297+
*/
298+
DiscoverableNodeUpdate = 102;
299+
300+
/**
301+
* Delete a discoverable node
302+
*/
303+
DiscoverableNodeDelete = 103;
304+
}
305+
```
306+
307+
Adjusted `node_id` in `TransactionReceipt`:
308+
309+
```protobuf
310+
message TransactionReceipt {
311+
312+
[...]
313+
314+
/**
315+
* The identifier of a newly created Node or DiscoverableNode.
316+
* <p>
317+
* This value SHALL be set following a `createNode` transaction.<br/>
318+
* This value SHALL be set following a `createDiscoverableNode`
319+
* transaction.<br/>
320+
* This value SHALL NOT be set following any other transaction.
321+
*/
322+
uint64 node_id = 15;
323+
324+
}
325+
```
326+
327+
### Mirror node update
328+
The mirror node will process the new Discoverable Node transactions and
329+
discoverable_service_endpoint information, then return that information through
330+
extensions to its existing APIs.
331+
332+
## Backwards Compatibility
333+
All changes for this HIP are net-new functionality. There is no predicted
334+
impact or change for existing functionality.
335+
336+
## Security Implications
337+
TBD
338+
339+
## How to Teach This
340+
TBD
341+
342+
## Reference Implementation
343+
344+
## Rejected Ideas
345+
346+
1. Use of the existing consensus node address book and transactions was
347+
considered.
348+
* This was rejected for three reasons.
349+
1. The existing Node transactions and state objects include a substantial
350+
amount of data that has no relevancy to discoverable nodes
351+
2. The consensus nodes do not, and should not, include the additional
352+
information specific to discoverable nodes
353+
3. The modification of discoverable nodes and consensus nodes have
354+
vastly different risk profiles, and mandate very different signatory
355+
requirements.
356+
357+
## Open Issues
358+
359+
1. We intend to store a uint64 "reputation" value for each discoverable node,
360+
but have not determined an appropriate and workable mechanism for allowing
361+
network entities to "vote" on that reputation.
362+
363+
## References
364+
365+
## Copyright/license
366+
<!-- SPDX-License-Identifier: Apache-2.0 -->
367+
This document is licensed under the Apache License, Version 2.0 --
368+
see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)

0 commit comments

Comments
 (0)