Skip to content

Commit a69413b

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 a69413b

File tree

1 file changed

+360
-0
lines changed

1 file changed

+360
-0
lines changed

‎HIP/hip-1137.md

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

0 commit comments

Comments
 (0)