Skip to content

Commit

Permalink
Update specification text for address book service
Browse files Browse the repository at this point in the history 
* Updated specification/API comments
* Consolidated review changes
   * Adjusted wording for consistency and clarity
   * Adjusted formatting for consistency
   * Updated query.proto with package changes
   * Corrected gossip certificate encoding
   * Adjusted gossip endpoint to state that networks may or
     may not require those endpoints to have or not have
     a DNS entry.
      * Further clarified that DNS vs. Address is network-specific.
      * Matched updated wording based on recent discussions
   * Removed references to status in state Node message.
   * Removed status enum as requested.
   * Added deleted flag to match recent updates.

Signed-off-by: Joseph Sinclair <joseph.sinclair@swirldslabs.com>
  • Loading branch information
@jsync-swirlds
jsync-swirlds committed Jun 5, 2024
1 parent b4292bc commit 580c35b
Show file tree
Hide file tree
Showing 15 changed files with 2,372 additions and 2,008 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,4 +78,5 @@ secring.*
### Custom items
.idea
*.sw*
*.iml

149 changes: 125 additions & 24 deletions services/address_book_service.proto
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
syntax = "proto3";

package proto;
package com.hedera.hapi.node.addressbook;

/*
* Hedera Network Services Protobuf
*
* Copyright (C) 2024 Hedera Hashgraph, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
Expand All @@ -29,37 +27,140 @@ import "transaction_response.proto";
import "transaction.proto";

/**
* Transactions for the AddressBook Service, those HAPI APIs facilitate changes to the nodes used across the Hedera network.
* All those transactions needs to be signed by the Hedera Council. Steps needed below:
* 1. The node operator creates and signs the transaction with their key (the key on the node operator account)
* 2. The node operator hands this transaction to Alex, who then gives it to the council to sign
* 3. When signed and submitted, the server will verify that account 2 keys have signed, and the keys on the operator account have signed.
* Hedera council should have ability to make all edits in addition to add/remove nodes
* The Address Book service provides the ability for Hedera network node
* administrators to add, update, and remove consensus nodes. This addition,
* update, or removal of a consensus node requires governing council approval,
* but each node operator may update their own operational attributes without
* additional approval, reducing overhead for routine operations.
*
* Most operations are `privileged operations` and require governing council
* approval.
*
* ### For a node creation transaction.
* - The node operator SHALL create a `createNode` transaction.
* - The node operator SHALL sign this transaction with the active `key` for
* the account to be assigned as the "node account".
* - The node operator MUST deliver the signed transaction to the Hedera
* council representative.
* - The Hedera council representative SHALL arrange for council members to
* review and sign the transaction.
* - Once sufficient council members have signed the transaction, the
* Hedera council representative SHALL submit the transaction to the
* network.
* - Upon receipt of a valid and signed node creation transaction the network
* software SHALL
* - Validate the threshold signature for the Hedera governing council
* - Validate the signature of the active `key` for the account to be
* assigned as the "node account".
* - Create the new node in state, this new node SHALL NOT be active in the
* network at this time.
* - When executing the next `freeze` transaction with `freeze_type` set to
* `PREPARE_UPGRADE`, update network configuration and bring the
* new node to an active status within the network. The node to be added
* SHALL be active in the network following this upgrade.
*
* ### For a node deletion transaction.
* - The node operator or Hedera council representative SHALL create a
* `deleteNode` transaction.
* - If the node operator creates the transaction
* - The node operator MUST sign this transaction with the active `key`
* for the account assigned as the "node account".
* - The node operator SHALL deliver the signed transaction to the Hedera
* council representative.
* - The Hedera council representative SHALL arrange for council members to
* review and sign the transaction.
* - Once sufficient council members have signed the transaction, the
* Hedera council representative SHALL submit the transaction to the
* network.
* - Upon receipt of a valid and signed node deletion transaction the network
* software SHALL
* - Validate the threshold signature for the Hedera governing council
* - Remove the existing node from network state. The node SHALL still
* be active in the network at this time.
* - When executing the next `freeze` transaction with `freeze_type` set to
* `PREPARE_UPGRADE`, update network configuration and remove the
* node to be deleted from the network. The node to be deleted SHALL NOT
* be active in the network following this upgrade.
*
* ### For a node update transaction.
* - The node operator or Hedera council representative SHALL create an
* `updateNode` transaction.
* - If the node operator creates the transaction
* - The node operator MUST sign this transaction with the active `key`
* for the account assigned as the current "node account".
* - If the transaction changes the value of the "node account" the
* node operator MUST _also_ sign this transaction with the active `key`
* for the account to be assigned as the new "node account".
* - The node operator SHALL submit the transaction to the
* network. Hedera council approval SHALL NOT be sought for this
* transaction
* - If the Hedera council representative creates the transaction
* - The Hedera council representative SHALL arrange for council members
* to review and sign the transaction.
* - Once sufficient council members have signed the transaction, the
* Hedera council representative SHALL submit the transaction to the
* network.
* - Upon receipt of a valid and signed node update transaction the network
* software SHALL
* - If the transaction is signed by the Hedera governing council
* - Validate the threshold signature for the Hedera governing council
* - If the transaction is signed by the active `key` for the node account
* - Validate the signature of the active `key` for the account assigned
* as the "node account".
* - If the transaction modifies the value of the "node account",
* - Validate the signature of the _new_ `key` for the account to be
* assigned as the new "node account".
* - Modify the node information held in network state with the changes
* requested in the update transaction. The node changes SHALL NOT be
* applied to network configuration, and SHALL NOT affect network
* operation at this time.
* - When executing the next `freeze` transaction with `freeze_type` set to
* `PREPARE_UPGRADE`, update network configuration according to the
* modified information in network state. The requested changes SHALL
* affect network operation following this upgrade.
*/
service AddressBookService {
/**
* Prepare to add a new node to the network.
* When a valid council member initiates a HAPI transaction to add a new node,
* then the network should acknowledge the transaction and update the network’s Address Book within 24 hours.
* The added node will not be active until the network is upgraded.
*/
rpc createNode (Transaction) returns (TransactionResponse);
* A transaction to create a new consensus node in the network.
* address book.
* <p>
* This transaction, once complete, SHALL add a new consensus node to the
* network state.<br/>
* The new consensus node SHALL remain in state, but SHALL NOT participate
* in network consensus until the network updates the network configuration.
* <p>
* Hedera governing council authorization is REQUIRED for this transaction.
*/
rpc createNode (proto.Transaction) returns (proto.TransactionResponse);

/**
* Prepare to delete the node to the network.
* The deleted node will not be deleted until the network is upgraded.
* Such a deleted node can never be reused.
* A transaction to remove a consensus node from the network address
* book.
* <p>
* This transaction, once complete, SHALL remove the identified consensus
* node from the network state.
* <p>
* Hedera governing council authorization is REQUIRED for this transaction.
*/
rpc deleteNode (Transaction) returns (TransactionResponse);
rpc deleteNode (proto.Transaction) returns (proto.TransactionResponse);

/**
* Prepare to update the node to the network.
* The node will not be updated until the network is upgraded.
* A transaction to update an existing consensus node from the network
* address book.
* <p>
* This transaction, once complete, SHALL modify the identified consensus
* node state as requested.
* <p>
* This transaction MAY be authorized by either the node operator OR the
* Hedera governing council.
*/
rpc updateNode (Transaction) returns (TransactionResponse);
rpc updateNode (proto.Transaction) returns (proto.TransactionResponse);

/**
* Retrieves the node information by node Id.
* A transaction to query the current state of a consensus node in the
* network address book state.
* <p>
* Hedera governing council authorization is REQUIRED for this transaction.
*/
rpc getNodeInfo (Query) returns (Response);
rpc getNodeInfo (proto.Query) returns (proto.Response);
}
Loading

0 comments on commit 580c35b

Please sign in to comment.