Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: Update specification text for address book service #346

Merged
merged 1 commit into from
Jun 12, 2024
Merged

feat: Update specification text for address book service #346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
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
Open in desktop
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.
iwsimon marked this conversation as resolved.
Show resolved Hide resolved
*
* 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
jsync-swirlds marked this conversation as resolved.
Show resolved Hide resolved
* 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
iwsimon marked this conversation as resolved.
Show resolved Hide resolved
* 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