GitHub Logo HIP-690: Identify Community Nodes in Address Book and Related API

Author Kim Rader
Working Group Simi Hunjan, Ali Katamjani
Discussions-To https://github.com/hashgraph/hedera-improvement-proposal/discussions/691
Status Rejected
Needs Council Approval Yes
Review period ends Mon, 27 Mar 2023 07:00:00 +0000
Type Standards Track
Category Core
Created 2023-03-01
Updated 2023-05-17

Abstract

Add a property to the address book to indicate whether a node belongs to a council member or a community member. Update related protobuf message and mirror node response objects.

Motivation

As we begin onboarding node operators outside of council members as part of the community node project, there is a desire to be able to query using node Id whether a node is a community node or a council node.

This information is important to users when choosing a node to stake to. This information can be made available in Hashscan and then partners can expose this data when offering staking to customers. In order to support this, Mirror Node Explorer needs to reliably know which node is council or community, so they can expose this data. Although this can be done manually, it will be extremely hard to maintain as we grow community nodes, therefore we will need to define a systematic path to query if a node is community node or not.

Currently, council members have their accounts hardcoded. They need a way to rotate their account numbers. There is separate work going on to make that happen. Adding a community node flag is a required prerequisite.

Application developers need a way to know which nodes are council nodes vs community nodes so that they can identify these two types of nodes in applications.

Rationale

When Hedera begins allowing non-council members to run nodes, there will be more nodes coming online. This proposal seeks to provide a way to identify which nodes are council nodes and which are non-council (community) nodes.

Currently, each node has an address book configuration file which ties IP addresses to nodes and accounts to nodes. We propose a small addition to the address book to add a new property to indicate whether a given node is a council node or a community node. The information can then be read by outside applications via a small change to the mirror node API.

User stories

  • As an application developer, I need a reliable way to know which nodes are council nodes vs. community nodes so that I can appropriately identify them in my application.
  • As a developer for an application which supports staking, I want to be able to show my customers whether a node they are choosing to stake to is a council or a community node.
    • Users might trust council operated nodes over community hosted nodes
    • Today, we only have council nodes in the nodes page in the explorer
    • After community nodes are added there is not an immediate way to tell the node operator type (community vs. council)

Specification

The proposal is to add a new property ownershipType in the nodeAddress object in the address book file. Possible values are COUNCIL=0 and COMMUNITY=1, defined in a new enumeration NodeOwnershipType. COUNCIL is the default value and indicates that the node belongs to a council member. COMMUNITY indicates that the node belongs to a community member. If omitted the property defaults to 0 (COUNCIL), ensuring backwards compatibility.

The nodeAddress protobuf definition requires a new property ownershipType to transmit this information.

/**
* The data about a node, including its service endpoints and the Hedera account to be paid for
* services provided by the node (that is, queries answered and transactions submitted.)
*
* If the <tt>serviceEndpoint</tt> list is not set, or empty, then the endpoint given by the
* (deprecated) <tt>ipAddress</tt> and <tt>portno</tt> fields should be used.
*
* All fields are populated in the 0.0.102 address book file while only fields that start with # are
* populated in the 0.0.101 address book file.
*/
  message NodeAddress {
...
  /**
    * The ownership type of the node. Whether the node belongs to a council member or a community member.
    * If not present, defaults to 0 (COUNCIL).
    */
    NodeOwnershipType ownershipType = 11;
  }
  
  /**
  * Ownership type of the node. Whether the node belongs to a council member or a community member.
  */
  enum NodeOwnershipType {
      COUNCIL = 0;
      COMMUNITY = 1;
  }

The mirrornode REST API will also expose this datum. The /api/v1/network/nodes endpoint currently returns an array of "nodes" objects. A new property ownership_type will be added to the "nodes" JSON response object. Available values for the ownership_type property are COUNCIL and COMMUNITY.

An example /api/v1/network/nodes message REST API response with the new property is shown below.

{
  "nodes": [
    {
      "description": "address book 1",
      "file_id": "0.0.102",
      "max_stake": 50000,
      "memo": "0.0.4",
      "min_stake": 1000,
      "node_account_id": "0.0.4",
      "node_cert_hash": "0x01d173753810c0aae794ba72d5443c292e9ff962b01046220dd99f5816422696e0569c977e2f169e1e5688afc8f4aa16",
      "node_id": 1,
      "ownership_type": "COUNCIL",
      "public_key": "0x4a5ad514f0957fa170a676210c9bdbddf3bc9519702cf915fa6767a40463b96f",
      "reward_rate_start": 1000000,
      "service_endpoints": [
        {
          "ip_address_v4": "128.0.0.6",
          "port": 50216
        }
      ],
      "stake": 20000,
      "stake_not_rewarded": 19900,
      "stake_rewarded": 100,
      "staking_period": {
        "from": "1655164800.000000000",
        "to": "1655251200.000000000"
      },
      "timestamp": {
        "from": "187654.000123457",
        "to": null
      }
    }
  ],
  "links": {
    "next": null
  }
}

Backwards Compatibility

If not present in the address book configuration, the ownershipType property defaults to COUNCIL = 0. This ensures full backwards compatibility.

Security Implications

The address book is stored in state in system files 0.0.101 and 0.0.102. If a malicious node operator changes its own copies of the file, then this will result in the malicious node getting an ISS. The remainder of the network will ignore this invalid file.

How to Teach This

  • Hedera protobuf documentation
  • Hedera Mirror Node documentation - description and code examples of queries in the REST API documentation

Rejected Ideas

If community node operator node account IDs are not part of the Hedera system accounts (entities under 0.0.1000) then the application could say all council nodes are node account IDs under 0.0.1000 and all node account IDs greater than 1000 are community nodes. This idea was discussed but rejected because there have been requests by council members to move to new account numbers above 0.0.1000 and not one of the accounts in the privileged range, making this idea not a viable long term solution.

Also discussed was the idea of adding a flag instead of an enumerated value. This was rejected because an enumerated value adds more flexibility in the future if we want to add more ownership types.

Open Issues

None.

References

Copyright/license

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: