HIP-869: Dynamic Address Book - Stage 1 - HAPI Endpoints

service AddressBookService {
    /**
     * 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);

    /**
     * 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 (proto.Transaction) returns (proto.TransactionResponse);

    /**
     * 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 MUST be authorized by the node operator.
     */
    rpc updateNode (proto.Transaction) returns (proto.TransactionResponse);
}

message NodeCreateTransactionBody {
    /**
     * A Node account identifier.
     * <p>
     * This account identifier MUST be in the "account number" form.<br/>
     * This account identifier MUST NOT use the alias field.<br/>
     * If the identified account does not exist, this transaction SHALL fail.<br/>
     * Multiple nodes MAY share the same node account.<br/>
     * This field is REQUIRED.
     */
    proto.AccountID account_id = 1;

    /**
     * A short description of the node.
     * <p>
     * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.<br/>
     * This field is OPTIONAL.
     */
    string description = 2;

    /**
     * A list of service endpoints for gossip.
     * <p>
     * These endpoints SHALL represent the published endpoints to which other
     * consensus nodes may _gossip_ transactions.<br/>
     * These endpoints MUST specify a port.<br/>
     * This list MUST NOT be empty.<br/>
     * This list MUST NOT contain more than `10` entries.<br/>
     * The first two entries in this list SHALL be the endpoints published to
     * all consensus nodes.<br/>
     * All other entries SHALL be reserved for future use.
     * <p>
     * Each network may have additional requirements for these endpoints.
     * A client MUST check network-specific documentation for those
     * details.<br/>
     * If the network configuration value `gossipFqdnRestricted` is set, then
     * all endpoints in this list MUST supply only IP address.<br/>
     * If the network configuration value `gossipFqdnRestricted` is _not_ set,
     * then endpoints in this list MAY supply either IP address or FQDN, but
     * MUST NOT supply both values for the same endpoint.
     */
    repeated proto.ServiceEndpoint gossip_endpoint = 3;

    /**
     * A list of service endpoints for gRPC calls.
     * <p>
     * These endpoints SHALL represent the published gRPC endpoints to which
     * clients may submit transactions.<br/>
     * These endpoints MUST specify a port.<br/>
     * Endpoints in this list MAY supply either IP address or FQDN, but MUST
     * NOT supply both values for the same endpoint.<br/>
     * This list MUST NOT be empty.<br/>
     * This list MUST NOT contain more than `8` entries.
     */
    repeated proto.ServiceEndpoint service_endpoint = 4;

    /**
     * A certificate used to sign gossip events.
     * <p>
     * This value MUST be a certificate of a type permitted for gossip
     * signatures.<br/>
     * This value MUST be the DER encoding of the certificate presented.<br/>
     * This field is REQUIRED and MUST NOT be empty.
     */
    bytes gossip_ca_certificate = 5;

    /**
     * A hash of the node gRPC TLS certificate.
     * <p>
     * This value MAY be used to verify the certificate presented by the node
     * during TLS negotiation for gRPC.<br/>
     * This value MUST be a SHA-384 hash.<br/>
     * The TLS certificate to be hashed MUST first be in PEM format and MUST be
     * encoded with UTF-8 NFKD encoding to a stream of bytes provided to
     * the hash algorithm.<br/>
     * This field is OPTIONAL.
     */
    bytes grpc_certificate_hash = 6;

    /**
    * An administrative key controlled by the node operator.
     * <p>
     * This key MUST sign this transaction.<br/>
     * This key MUST sign each transaction to update this node.<br/>
     * 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;
}

message NodeDeleteTransactionBody {
    /**
     * A consensus node identifier in the network state.
     * <p>
     * The node identified MUST exist in the network address book.<br/>
     * The node identified MUST NOT be deleted.<br/>
     * This value is REQUIRED.
     */
    uint64 node_id = 1;
}

message NodeUpdateTransactionBody {
    /**
     * A consensus node identifier in the network state.
     * <p>
     * The node identified MUST exist in the network address book.<br/>
     * The node identified MUST NOT be deleted.<br/>
     * This value is REQUIRED.
     */
    uint64 node_id = 1;

    /**
     * An account identifier.
     * <p>
     * If set, this SHALL replace the node account identifier.<br/>
     * If set, this transaction MUST be signed by the active `key` for _both_
     * the current node account _and_ the identified new node account.
     */
    proto.AccountID account_id = 2;

    /**
     * A short description of the node.
     * <p>
     * This value, if set, MUST NOT exceed 100 bytes when encoded as UTF-8.<br/>
     * If set, this value SHALL replace the previous value.
     */
    google.protobuf.StringValue description = 3;

    /**
     * A list of service endpoints for gossip.
     * <p>
     * If set, this list MUST meet the following requirements.
     * <hr/>
     * These endpoints SHALL represent the published endpoints to which other
     * consensus nodes may _gossip_ transactions.<br/>
     * These endpoints SHOULD NOT specify both address and DNS name.<br/>
     * This list MUST NOT be empty.<br/>
     * This list MUST NOT contain more than `10` entries.<br/>
     * The first two entries in this list SHALL be the endpoints published to
     * all consensus nodes.<br/>
     * All other entries SHALL be reserved for future use.
     * <p>
     * Each network may have additional requirements for these endpoints.
     * A client MUST check network-specific documentation for those
     * details.<br/>
     * <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
     * address.
     * </blockquote></blockquote>
     * <p>
     * If set, the new list SHALL replace the existing list.
     */
    repeated proto.ServiceEndpoint gossip_endpoint = 4;

    /**
     * A list of service endpoints for gRPC calls.
     * <p>
     * If set, this list MUST meet the following requirements.
     * <hr/>
     * These endpoints SHALL represent the published endpoints to which clients
     * may submit transactions.<br/>
     * These endpoints SHOULD specify address and port.<br/>
     * These endpoints MAY specify a DNS name.<br/>
     * These endpoints SHOULD NOT specify both address and DNS name.<br/>
     * This list MUST NOT be empty.<br/>
     * This list MUST NOT contain more than `8` entries.
     * <p>
     * Each network may have additional requirements for these endpoints.
     * A client MUST check network-specific documentation for those
     * details.
     * <p>
     * If set, the new list SHALL replace the existing list.
     */
    repeated proto.ServiceEndpoint service_endpoint = 5;

    /**
     * A certificate used to sign gossip events.
     * <p>
     * This value MUST be a certificate of a type permitted for gossip
     * signatures.<br/>
     * This value MUST be the DER encoding of the certificate presented.
     * <p>
     * If set, the new value SHALL replace the existing bytes value.
     */
    google.protobuf.BytesValue gossip_ca_certificate = 6;

    /**
     * A hash of the node gRPC TLS certificate.
     * <p>
     * This value MAY be used to verify the certificate presented by the node
     * during TLS negotiation for gRPC.<br/>
     * This value MUST be a SHA-384 hash.<br/>
     * The TLS certificate to be hashed MUST first be in PEM format and MUST be
     * encoded with UTF-8 NFKD encoding to a stream of bytes provided to
     * the hash algorithm.<br/>
     * <p>
     * If set, the new value SHALL replace the existing hash value.
     */
    google.protobuf.BytesValue grpc_certificate_hash = 7;

    /**
    * An administrative key controlled by the node operator.
     * <p>
     * This field is OPTIONAL.<br/>
     * If set, this key MUST sign this transaction.<br/>
     * If set, this key MUST sign each subsequent transaction to
     * update this node.<br/>
     * If set, this field MUST contain a valid `Key` value.<br/>
     * If set, this field MUST NOT be set to an empty `KeyList`.
     */
    proto.Key admin_key = 8;
}

enum HederaFunctionality {

	[...]

    /**
    * Create a node
    */
    NodeCreate = 89;

    /**
     * Update a node
     */
    NodeUpdate = 90;

    /**
     * Delete a node
     */
    NodeDelete = 91;
}

message ServiceEndpoint {

	[...]

    /**
     * A node domain name.<br/>
     * This MUST be the fully qualified domain(DNS) name of the node.<br/>
     * This value MUST NOT be more than 253 characters.
     * domain_name and ipAddressV4 are mutually exclusive.
     * When the `domain_name` field is set, the `ipAddressV4` field MUST NOT be set.<br/>
     * When the `ipAddressV4` field is set, the `domain_name` field MUST NOT be set.
     */
    string domain_name = 3;
}

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;

}

enum ResponseCodeEnum {

	[...]

    /**
     * A transaction failed because the consensus node identified is
     * deleted from the address book.
     */
    NODE_DELETED = 338;

    /**
     * A transaction failed because the consensus node identified is not valid or
     * does not exist in state.
     */
    INVALID_NODE_ID = 339;

    /**
     * A transaction failed because one or more entries in the list of
     * service endpoints for the `gossip_endpoint` field is invalid.<br/>
     * The most common cause for this response is a service endpoint that has
     * the domain name (DNS) set rather than address and port.
     */
    INVALID_GOSSIP_ENDPOINT = 340;

    /**
     * A transaction failed because the node account identifier provided
     * does not exist or is not valid.<br/>
     * One common source of this error is providing a node account identifier
     * using the "alias" form rather than "numeric" form.
     */
    INVALID_NODE_ACCOUNT_ID = 341;

    /**
     * A transaction failed because the description field cannot be encoded
     * as UTF-8 or is more than 100 bytes when encoded.
     */
    INVALID_NODE_DESCRIPTION = 342;

    /**
     * A transaction failed because one or more entries in the list of
     * service endpoints for the `service_endpoint` field is invalid.<br/>
     * The most common cause for this response is a service endpoint that has
     * the domain name (DNS) set rather than address and port.
     */
    INVALID_SERVICE_ENDPOINT = 343;

    /**
     * A transaction failed because the TLS certificate provided for the
     * node is missing or invalid.<br/>
     * The certificate MUST be a TLS certificate of a type permitted for gossip
     * signatures.<br/>
     * The value presented MUST be a UTF-8 NFKD encoding of the TLS
     * certificate.<br/>
     * The certificate encoded MUST be in PEM format.<br/>
     * The `gossip_ca_certificate` field is REQUIRED and MUST NOT be empty.
     */
    INVALID_GOSSIP_CA_CERTIFICATE = 344;

    /**
     * A transaction failed because the hash provided for the gRPC certificate
     * is present but invalid.<br/>
     * The `grpc_certificate_hash` MUST be a SHA-384 hash.<br/>
     * The input hashed MUST be a UTF-8 NFKD encoding of the actual TLS
     * certificate.<br/>
     * The certificate to be encoded MUST be in PEM format.
     */
    INVALID_GRPC_CERTIFICATE = 345;

    /**
     * The maximum number of nodes allowed in the address book have been created.
     */
    MAX_NODES_CREATED = 347;

    /**
     * In ServiceEndpoint, domain_name and ipAddressV4 are mutually exclusive
     */
    IP_FQDN_CANNOT_BE_SET_FOR_SAME_ENDPOINT = 348;

    /**
     *  Fully qualified domain name is not allowed in gossip_endpoint
     */
    GOSSIP_ENDPOINT_CANNOT_HAVE_FQDN = 349;

    /**
     * In ServiceEndpoint, domain_name size too large
     */
    FQDN_SIZE_TOO_LARGE = 350;

    /**
     * ServiceEndpoint is invalid
     */
    INVALID_ENDPOINT = 351;

    /**
     * The number of gossip endpoints exceeds the limit
     */
    GOSSIP_ENDPOINTS_EXCEEDED_LIMIT = 352;

    /**
     * The number of service endpoints exceeds the limit
     */
    SERVICE_ENDPOINTS_EXCEEDED_LIMIT = 356;

    /*
     * The IPv4 address is invalid
     */
    INVALID_IPV4_ADDRESS = 357;
    
    /*
     * The node account is not allowed to be updated
     */
    UPDATE_NODE_ACCOUNT_NOT_ALLOWED = 359;

}