Skip to content

Commit 69ab5d1

Browse files
Mark-SwirldsMark-Swirlds
authored
Updates to HIP-869 (#1307)
Signed-off-by: Mark-Swirlds <mark@hashgraph.com>
1 parent 71237b3 commit 69ab5d1

1 file changed

Lines changed: 85 additions & 35 deletions

File tree

‎HIP/hip-869.md‎

Lines changed: 85 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
hip: 869
3-
title: Dynamic Address Book
3+
title: Dynamic Address Book - Stage 1 - HAPI Endpoints
44
author: Iris Simon <iris.simon@swirldslabs.com>
55
working-group: Kelly Greco <kelly@swirldslabs.com>, Michael Heinrichs <michael@swirldslabs.com>, Mark Blackman <mark@swirldslabs.com>
66
requested-by: Hedera
@@ -11,8 +11,8 @@ status: Final
1111
release: v0.56.0
1212
last-call-date-time: 2023-02-14T07:00:00Z
1313
created: 2024-01-22
14-
discussions-to: https://github.com/hiero-ledger/hiero-improvement-proposals/pull/869
15-
updated: 2024-12-12
14+
discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/pull/869
15+
updated: 2025-06-17
1616
---
1717

1818
## Abstract
@@ -63,43 +63,66 @@ Adopting a two-phase strategy, this approach facilitated the earlier release of
6363

6464
**Node Operator** - Administrator of Hedera Consensus Nodes
6565

66+
### User Story 1: Add a New Consensus Node
67+
**As the Council**, we want to submit a NodeCreate HAPI transaction, signed by both the council signature and the node admin key, to add a new consensus node to the Hedera network upon the next maintenance window, so that management of Hedera's Address Book is automated.
6668

67-
***User Stories:***
68-
1. As the Council, we want to submit signed HAPI transactions to add a new consensus node to the Hedera network upon the next maintenance window, so that management of Hedera's Address book is automated.
69+
**Acceptance:** When the council initiates a NodeCreate HAPI transaction to add a new node with both council and admin signatures, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
6970

70-
*Acceptance: When the council initiates a HAPI transaction to add a new node, then the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.*
71+
### User Story 2: Remove a Consensus Node
72+
**As the Council**, we want to submit a NodeDelete HAPI transaction, signed by either the council signature or the node admin key, to remove a consensus node from the Hedera network upon the next maintenance window, so that management of Hedera's Address Book is automated.
7173

72-
2. As the Council, we want to submit signed HAPI transactions to remove a consensus node from the Hedera network upon the next maintenance window, so that management of Hedera's Address book is automated.
74+
**Acceptance:** When the council submits a NodeDelete HAPI transaction to remove a node, authorized by either the council signature or the node admin key, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
7375

74-
*Acceptance: When the council submits a HAPI transaction to remove a node, then the network should acknowledge the transaction and performs the update to the network’s Address Book at the next maintenance window.*
76+
### User Story 3: Modify a Node’s IP Address and Ports
77+
**As a Node Operator**,I want to submit a NodeUpdate HAPI transaction, signed by the node admin key, to modify one or both of an existing node's IP addresses and/or ports, so I can independently perform address book-related node operations.
7578

76-
3. As a Node Operator, I want to submit a signed HAPI transaction that modifies one or both of an existing node's IP addresses and/or ports, so I can independently perform address book related node operations.
79+
**Acceptance:** When a Node Operator submits a NodeUpdate HAPI transaction, signed with the node admin key, to modify a node's primary IP address:port or secondary IP address:port, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
7780

78-
*Acceptance: When a Node Operator submits a HAPI transaction to modify a node's primary IP address:port or secondary IP address:port, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.*
81+
### User Story 4: Modify GRPC Proxy Endpoints
82+
**As a Node Operator**, I want to submit a NodeUpdate HAPI transaction, signed by the node admin key, to modify a list of GRPC proxy endpoints supporting either IP and FQDN address formats per entry, so I can independently perform address book-related node operations.
7983

80-
4. As a Node Operator, I want to submit a signed HAPI transaction that modifies a list of GRPC proxy endpoints supporting both IP and FQDN address formats, so I can independently perform address book related node operations.
84+
**Acceptance:** When a Node Operator submits a NodeUpdate HAPI transaction, signed with the node admin key, to modify a node's IP address:port or FQDN:port, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
85+
### User Story 5: Modify Node Description
86+
**As a Node Operator**, I want to submit a NodeUpdate HAPI transaction, signed by the node admin key, to modify a node’s description within the Address Book, so I can independently perform address book-related node operations.
8187

82-
*Acceptance: When a Node Operator submits a HAPI transaction to modify a node's IP address:port or FQDN:port, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.*
88+
**Acceptance:** When a Node Operator submits a NodeUpdate HAPI transaction, signed with the node admin key, to modify a node's associated Description Field, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
8389

84-
5. As a Node Operator, I want to submit a signed HAPI transaction that modifies a node’s description within the Address Book, so I can independently perform address book related node operations.
90+
### User Story 6: Modify Node’s Public Key
91+
**As a Node Operator**, I want to submit a NodeUpdate HAPI transaction, signed by the node admin key, to modify a node’s public key within the Address Book used for signing, so I can independently perform address book-related node operations.
8592

86-
*Acceptance: When a Node Operator submits a HAPI transaction to modify a node's associated Description Field, then the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.*
93+
**Acceptance:** When a Node Operator submits a NodeUpdate HAPI transaction, signed with the node admin key, to modify a node's associated Public Key, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
8794

88-
6. As a Node Operator, I want to submit a signed HAPI transaction that modifies a node’s public key within the Address Book used for signing, so I can independently perform address book related node operations.
95+
### User Story 7: Modify Node’s Account ID
96+
**As a Node Operator**, I want to submit a NodeUpdate HAPI transaction, signed by the node admin key, to modify a node’s Account ID within the Address Book, so I can independently perform address book-related node operations.
8997

90-
*Acceptance: When a Node Operator submits a HAPI transaction to modify a node's associated Public Key, then the network acknowledges the transaction and performs the update the network’s Address Book at the next maintenance window.*
98+
**Acceptance:** When a Node Operator submits a NodeUpdate HAPI transaction, signed with the node admin key, to modify a node's Account ID, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
9199

92-
7. As a Node Operator, I want to submit a signed HAPI transaction that modifies a node’s Account ID within the Address Book, so I can independently perform address book related node operations.
100+
### User Story 8: Modify Node’s X509 Certificate Hash
101+
**As a Node Operator**, I want to submit a NodeUpdate HAPI transaction, signed by the node admin key, to modify a node’s X509 certificate hash within the Address Book, so I can independently perform address book-related node operations.
93102

94-
*Acceptance: When a Node Operator submits a HAPI transaction to modify a node's Account ID, then the network acknowledges the transaction and performs the update the network’s Address Book at the next maintenance window.*
103+
**Acceptance:** When a Node Operator submits a NodeUpdate HAPI transaction, signed with the node admin key, to modify a node's associated X509 certificate hash, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
104+
105+
### User Story 9: Create a New Node as a Node Operator
106+
**As a Node Operator**, I want to submit a NodeCreate HAPI transaction, signed by both the council signature and the node admin key, to add a new node to the Hedera network upon the next maintenance window, so that I can contribute to the expansion of Hedera's Address Book.
107+
108+
**Acceptance:** When a Node Operator initiates a NodeCreate HAPI transaction to create a new node with both council and node admin signatures, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
109+
110+
### User Story 10: Delete an Existing Node as a Node Operator
111+
**As a Node Operator**, I want to submit a NodeDelete HAPI transaction, signed by either the council signature or the node admin key, to remove a node from the Hedera network upon the next maintenance window, so that I can manage nodes within Hedera's Address Book when necessary.
112+
113+
**Acceptance:** When a Node Operator submits a HAPI transaction to delete a node, signed with either the council signature or the node admin key, the network acknowledges the transaction and performs the update to the network’s Address Book at the next maintenance window.
95114

96-
8. As a Node Operator, I want to submit a signed HAPI transaction that modifies a node’s X509 certificate hash within the Address Book, so I can independently perform address book related node operations.
97115

98-
*Acceptance: When a Node Operator submits a HAPI transaction to modify a node's associated X509 certificate hash, then the network acknowledges the transaction and performs the update the network’s Address Book at the next maintenance window.*
99116

100117
## Specification
101118

102-
This HIP proposes the introduction of a new NodeService API that enables a node operator to create, delete, and update nodes. All of these transactions must be signed by the Hedera Council.
119+
This HIP proposes introducing a new AddressBookService API that empowers node operators to create, delete, and update nodes within the Hedera network. Each operation requires specific transaction authorizations, with signatures from either the Hedera Council, the node admin key, or both, depending on the API action. Below is a table of the authorization required by endpoint:
120+
121+
| API Action | Required Signatures |
122+
|--------------|---------------------------------------|
123+
| node_create | Council signature **and** admin key |
124+
| node_update | Admin key only |
125+
| node_delete | Admin key **or** council signature |
103126

104127
```protobuf
105128
service AddressBookService {
@@ -134,13 +157,13 @@ service AddressBookService {
134157
* This transaction, once complete, SHALL modify the identified consensus
135158
* node state as requested.
136159
* <p>
137-
* Hedera governing council authorization is REQUIRED for this transaction.
160+
* This transaction is authorized by the node operator
138161
*/
139162
rpc updateNode (proto.Transaction) returns (proto.TransactionResponse);
140163
}
141-
```
142164
143-
A new Hedera API will be added called NodeCreate, which falls under the Node Service category. This function is used by the node operator to create a new node. To complete this transaction, both the node operator and a council member must sign it.
165+
166+
A new Hedera API will be added called NodeCreate, which falls under the AddressBookService category. This function is used by the council or node operator to create a new node. To complete this transaction, both the node operator and a council member must sign it.
144167
145168
```protobuf
146169
message NodeCreateTransactionBody {
@@ -230,12 +253,12 @@ message NodeCreateTransactionBody {
230253
* This field MUST contain a valid `Key` value.<br/>
231254
* This field is REQUIRED and MUST NOT be set to an empty `KeyList`.
232255
*/
256+
*/
233257
proto.Key admin_key = 7;
234258
}
235-
236259
```
237260

238-
A new Hedera API called NodeDelete will be added under the Node Service. This API function is used by the node operator to delete a node. To perform this transaction, both the node operator and a council member need to sign it.
261+
A new Hedera API called NodeDelete will be added under the AddressBookService. This API function is used by either the council or the node operator to delete a node. To perform this transaction, either the node operator or the council need to sign it.
239262

240263
```protobuf
241264
message NodeDeleteTransactionBody {
@@ -250,7 +273,7 @@ message NodeDeleteTransactionBody {
250273
}
251274
```
252275

253-
A new Hedera API called NodeUpdate will be added under the Node Service. This function is used by the node operator to update a node. For this transaction, both the node operator and council member need to sign it.
276+
A new Hedera API called NodeUpdate will be added under the AddressBookService. This function is used by the node operator to update a node. For this transaction only the node operator need to sign it.
254277

255278
```protobuf
256279
message NodeUpdateTransactionBody {
@@ -300,8 +323,6 @@ message NodeUpdateTransactionBody {
300323
* <blockquote>Example<blockquote>
301324
* Hedera Mainnet _requires_ that address be specified, and does not
302325
* permit DNS name (FQDN) to be specified.<br/>
303-
* Mainnet also requires that the first entry be an "internal" IP
304-
* address and the second entry be an "external" IP address.
305326
* </blockquote>
306327
* <blockquote>
307328
* Solo, however, _requires_ DNS name (FQDN) but also permits
@@ -428,8 +449,6 @@ message TransactionReceipt {
428449
* In the receipt of a NodeCreate, NodeUpdate, NodeDelete, the id of the newly created node.
429450
* An affected node identifier.<br/>
430451
* This value SHALL be set following a `createNode` transaction.<br/>
431-
* This value SHALL be set following a `updateNode` transaction.<br/>
432-
* This value SHALL be set following a `deleteNode` transaction.<br/>
433452
* This value SHALL NOT be set following any other transaction.
434453
*/
435454
uint64 node_id = 15;
@@ -564,6 +583,37 @@ When executing the next `freeze` transaction with `freeze_type` set to `PREPARE_
564583

565584
All HIPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The HIP must explain how the author proposes to deal with these incompatibilities. HIP submissions without a sufficient backward compatibility treatise may be rejected outright.
566585

586+
## Admin Key Provisioning and Operations
587+
588+
### View Configured Admin Keys in Address Book
589+
Use the mirror node to query address book and current node admin keys - https://mainnet-public.mirrornode.hedera.com/api/v1/network/nodes
590+
591+
### Initial Provisioning of Node Admin Key
592+
When the Dynamic Address Book feature is enabled on Hedera mainnet, the network must be initialized with default node admin keys, which can be updated to node operator controlled keys over time.
593+
594+
#### Provisioning by Hedera Council-Controlled Account
595+
- Upon upgrading to a software version that supports the Dynamic Address Book, each consensus node will automatically assign the `0.0.55` addressBookAdmin key to the `admin_key` field for all nodes listed in the Address Book.
596+
- The `0.0.55` account, controlled by the Hedera Council, ensures a secure starting point for admin key management across the network.
597+
598+
#### Initial Key Update to Node Operator’s Key
599+
- To transition control to the node operator, an initial `NodeUpdate` transaction will be signed by both the Hedera Council and the node operator’s designated admin key.
600+
- This transaction updates the `admin_key` field in the Address Book to reflect the node operator's admin key, transferring ongoing administrative responsibility to the node operator.
601+
602+
### Ongoing Key Operations
603+
604+
#### Creating a New Node
605+
- When a new node is added to the network, the node operator signs a `node_create` transaction using their admin key.
606+
- This transaction is then submitted to the Hedera Council, which reviews, signs, and submits it to the network, completing the onboarding process for the new node.
607+
608+
#### Updating the Admin Key
609+
- If a node operator needs to update the admin key, they submit a `node_update` transaction signed with both the old and new admin keys.
610+
- This dual-signature approach ensures a seamless transition while maintaining security throughout the key update process.
611+
612+
#### Handling a Lost Admin Key
613+
- In the event that a node operator’s admin private key is lost, the node must be removed from the Address Book by submitting a `node_delete` transaction.
614+
- Following deletion, a new entry for the node can be created using the standard `node_create` transaction, reassigning a new admin key and restoring node operations.
615+
616+
567617
### Mirror node update
568618
The mirror node will process the new Node transactions and service_endpoint information, then return that information through its existing APIs.
569619

@@ -633,20 +683,20 @@ To educate and facilitate a great customer experience, the following will be req
633683

634684
## Reference Implementation
635685

636-
The reference implementation must be complete before any HIP is given the status of “Final”. The final implementation must include test code and documentation.
686+
Feature code integrated in Hedera Services and Protobuf repos
637687

638688
## Rejected Ideas
639-
640-
TBD
689+
NA
641690

642691
## Open Issues
643692

644693
Stage 2 - Full Dynamic Book Implementation
645694

646695
## References
647696

648-
TBD
697+
NA
649698

650699
## Copyright/license
651700

652701
This document is licensed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)
702+

0 commit comments

Comments
 (0)