hiero-ledger · mgarbs · Oct 15, 2025 · Oct 13, 2025
@@ -1,6 +1,6 @@
 ---
 hip: 869
-title: Dynamic Address Book
+title: Dynamic Address Book - Stage 1 - HAPI Endpoints
 author: Iris Simon <[email protected]>
 working-group: Kelly Greco <[email protected]>, Michael Heinrichs <[email protected]>, Mark Blackman <[email protected]>
 requested-by: Hedera
@@ -11,8 +11,8 @@ status: Final
 release: v0.56.0
 last-call-date-time: 2023-02-14T07:00:00Z
 created: 2024-01-22 
-discussions-to: https://github.com/hiero-ledger/hiero-improvement-proposals/pull/869
-updated: 2024-12-12
+discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/pull/869
+updated: 2025-06-17
 ---
 
 ## Abstract
@@ -63,43 +63,66 @@ Adopting a two-phase strategy, this approach facilitated the earlier release of
 
 **Node Operator** - Administrator of Hedera Consensus Nodes
 
+### User Story 1: Add a New Consensus Node
+**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.
 
-***User Stories:*** 
-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.
+**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.
 
-*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.*
+### User Story 2: Remove a Consensus Node
+**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.
 
-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.
+**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.
 
-*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.*
+### User Story 3: Modify a Node’s IP Address and Ports
+**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.
 
-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.
+**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.
 
-*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.*
+### User Story 4: Modify GRPC Proxy Endpoints
+**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.
 
-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.
+**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.
+### User Story 5: Modify Node Description
+**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.
 
-*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.*
+**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.
 
-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.
+### User Story 6: Modify Node’s Public Key
+**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.
 
-*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.*
+**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.
 
-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.
+### User Story 7: Modify Node’s Account ID
+**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.
 
-*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.*
+**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.
 
-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.
+### User Story 8: Modify Node’s X509 Certificate Hash
+**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.
 
-*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.*
+**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.
+
+### User Story 9: Create a New Node as a Node Operator
+**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.
+
+**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.
+
+### User Story 10: Delete an Existing Node as a Node Operator
+**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.
+
+**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.
 
-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.
 
-*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.*
 
 ## Specification
 
-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.
+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:
+
+| API Action   | Required Signatures                   |
+|--------------|---------------------------------------|
+| node_create  | Council signature **and** admin key   |
+| node_update  | Admin key only                        |
+| node_delete  | Admin key **or** council signature    |
 
 ```protobuf
 service AddressBookService {
@@ -134,13 +157,13 @@ service AddressBookService {
      * This transaction, once complete, SHALL modify the identified consensus
      * node state as requested.
      * <p>
-     * Hedera governing council authorization is REQUIRED for this transaction.
+     * This transaction is authorized by the node operator
      */
     rpc updateNode (proto.Transaction) returns (proto.TransactionResponse);
 }
-```
 
-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.
+
+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.
 
 ```protobuf
 message NodeCreateTransactionBody {
@@ -230,12 +253,12 @@ message NodeCreateTransactionBody {
      * This field MUST contain a valid `Key` value.<br/>
      * This field is REQUIRED and MUST NOT be set to an empty `KeyList`.
      */
+     */
     proto.Key admin_key = 7;
 }
-
 ```
 
-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.
+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.
 
 ```protobuf
 message NodeDeleteTransactionBody {
@@ -250,7 +273,7 @@ message NodeDeleteTransactionBody {
 }
 ```
 
-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.
+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.
 
 ```protobuf
 message NodeUpdateTransactionBody {
@@ -300,8 +323,6 @@ message NodeUpdateTransactionBody {
      * <blockquote>Example<blockquote>
      * Hedera Mainnet _requires_ that address be specified, and does not
      * permit DNS name (FQDN) to be specified.<br/>
-     * Mainnet also requires that the first entry be an "internal" IP
-     * address and the second entry be an "external" IP address.
      * </blockquote>
      * <blockquote>
      * Solo, however, _requires_ DNS name (FQDN) but also permits
@@ -428,8 +449,6 @@ message TransactionReceipt {
     * In the receipt of a NodeCreate, NodeUpdate, NodeDelete, the id of the newly created node.
     * An affected node identifier.<br/>
     * This value SHALL be set following a `createNode` transaction.<br/>
-    * This value SHALL be set following a `updateNode` transaction.<br/>
-    * This value SHALL be set following a `deleteNode` transaction.<br/>
     * This value SHALL NOT be set following any other transaction.
     */
     uint64 node_id = 15;
@@ -564,6 +583,37 @@ When executing the next `freeze` transaction with `freeze_type` set to `PREPARE_
 
 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.
 
+## Admin Key Provisioning and Operations
+
+### View Configured Admin Keys in Address Book
+Use the mirror node to query address book and current node admin keys - https://mainnet-public.mirrornode.hedera.com/api/v1/network/nodes
+
+### Initial Provisioning of Node Admin Key
+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.  
+
+#### Provisioning by Hedera Council-Controlled Account
+- 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. 
+- The `0.0.55` account, controlled by the Hedera Council, ensures a secure starting point for admin key management across the network.
+
+#### Initial Key Update to Node Operator’s Key
+- 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.
+- 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.
+
+### Ongoing Key Operations
+
+#### Creating a New Node
+- When a new node is added to the network, the node operator signs a `node_create` transaction using their admin key. 
+- 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.
+
+#### Updating the Admin Key
+- 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.
+- This dual-signature approach ensures a seamless transition while maintaining security throughout the key update process.
+
+#### Handling a Lost Admin Key
+- 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.
+- 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.
+
+
 ### Mirror node update
 The mirror node will process the new Node transactions and service_endpoint information, then return that information through its existing APIs.
 
@@ -633,20 +683,20 @@ To educate and facilitate a great customer experience, the following will be req
 
 ## Reference Implementation
 
-The reference implementation must be complete before any HIP is given the status of “Final”. The final implementation must include test code and documentation.
+Feature code integrated in Hedera Services and Protobuf repos
 
 ## Rejected Ideas
-
-TBD
+NA
 
 ## Open Issues
 
 Stage 2 - Full Dynamic Book Implementation
 
 ## References
 
-TBD
+NA
 
 ## Copyright/license
 
 This document is licensed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)
+