shgraph.hapi.0.54.1.source-code.address_book_service.proto Maven / Gradle / Ivy
syntax = "proto3";
package proto;
/*
* Copyright (C) 2024 Hedera Hashgraph, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
option java_package = "com.hederahashgraph.service.proto.java";
// <<>> This comment is special code for setting PBJ Compiler java package
import "query.proto";
import "response.proto";
import "transaction_response.proto";
import "transaction.proto";
/**
* 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 {
/**
* A transaction to create a new consensus node in the network.
* address book.
*
* This transaction, once complete, SHALL add a new consensus node to the
* network state.
* The new consensus node SHALL remain in state, but SHALL NOT participate
* in network consensus until the network updates the network configuration.
*
* Hedera governing council authorization is REQUIRED for this transaction.
*/
rpc createNode (proto.Transaction) returns (proto.TransactionResponse);
/**
* A transaction to remove a consensus node from the network address
* book.
*
* This transaction, once complete, SHALL remove the identified consensus
* node from the network state.
*
* Hedera governing council authorization is REQUIRED for this transaction.
*/
rpc deleteNode (proto.Transaction) returns (proto.TransactionResponse);
/**
* A transaction to update an existing consensus node from the network
* address book.
*
* This transaction, once complete, SHALL modify the identified consensus
* node state as requested.
*
* This transaction MAY be authorized by either the node operator OR the
* Hedera governing council.
*/
rpc updateNode (proto.Transaction) returns (proto.TransactionResponse);
}