github.com/Tri-stone/burrow@v0.25.0/docs/ADRs/draft/adr-2_identify-tx.md (about)

     1  ---
     2  adr: 2
     3  title: Identify Transaction
     4  author: Casey Kuhlman (@compleatang), Silas Davis (@silasdavis), Pierrick Hymbert (@phymbert)
     5  discussions-to: https://chat.hyperledger.org/channel/burrow-contributors
     6  status: Draft
     7  type: Standards Track
     8  category: State, Consensus, Governance, Gateway
     9  created: 2018-09-10
    10  ---
    11  
    12  ## Node keys and validators registry
    13  This ADR introduces Identify Transaction to register and track node key related to their validator key.
    14  
    15  ## Motivation
    16  
    17  There is 2 different kind of keys in a running Burrow node:
    18  - ABCI validator key (even if not a block validator)
    19  - P2P node key
    20  
    21  This is basically segregation:
    22  
    23  1. The node key is used (a lot) for the station-to-station (STS) protocol (kind of peer-to-peer TLS).
    24  This effectively runs down the entropy in the key from the perspective of what you have revealed to a potential attacker.
    25  Having a separate transport level key to your identity's signing key is 'good practice'.
    26  1. Validator key may in principle have real-world value (validator voting power == bond) by keeping it used for the single purpose of signing votes the attack surface area (and frequency of signatures) is reduced.
    27  Actually the node key doesn't get used for signatures, but it is still 'exposed' through the STS DH.
    28  
    29  So we end up with a 1-to-1 key correspondence but we have no way of mapping the two.
    30  
    31  This is a reasonable think to give every node a validator key, and it is its primary identity, then a network-wide registry is necessary.
    32  
    33  There is a lot of features/use cases where being able to lookup the p2p address (ID and NetAddress for that matter) will be useful, such as:
    34  1. state channels/subnets.
    35  1. Ops who often spent time trying to figure who's node is who's
    36  1. Filter peers sync by node ID or address, allowing to forbid a peer to pull the chain state if it is not present in this registry
    37  
    38  ## Specification
    39  Nodes submit their p2p identities by way of a handshake between the node private validator and the node p2p key.
    40  
    41  The node broadcasts a transaction of a new type `IdentifyTx` signed by the validator key with the node key.
    42  
    43  It also allows to register and notify a replacement node key identity.
    44  
    45  Burrow verifies a multisig of this tx of two inputs: validator key, node key.
    46  
    47  If they mutually sign then that key mapping gets added to network-wide registry, a simple store.
    48  
    49  A new transaction type is available:
    50  ```go
    51  type IdentifyTx struct {
    52      // Sender
    53  	Input *TxInput
    54  	// Validator address
    55  	Address crypto.Address
    56  	// Validator public key
    57  	PubKey crypto.PublicKey
    58  	// Node
    59  	Node *RegisteredNode
    60  	// The RegisteredNode.String() multisigned by the node key and the validator key
    61  	Signature []byte
    62  }
    63  
    64  type RegisteredNode {
    65      // Peer moniker name
    66  	Moniker string
    67  	// Node key id (crypto address)
    68  	ID p2p.ID
    69  	// Node key public key
    70  	PublicKey crypto.PublicKey
    71  	// Net address
    72  	NetAddress string
    73  }
    74  ```
    75  
    76  A registry is available in the blockchain state, accessible by a getter method:
    77  ```go
    78  // GetNetworkRegistry returns for each validator address, the list of their identified node at the current state
    79  func (s *State) GetNetworkRegistry() (map[crypto.Address][]*RegisteredNode, error)
    80  ```
    81  
    82  A new route is available in node info:
    83  `
    84  GET /network/registry
    85  `
    86  
    87  Which returns:
    88  ```javascript
    89  [
    90      {
    91          "address": "$VALIDATOR_ADDRESS",
    92          "pubKey":  "$VALIDATOR_PUB_KEY",
    93          "moniker": "$VALIDATOR_MONIKER",
    94          "nodeKey": "$VALIDATOR_NODE_KEY_ID",
    95          "netAddress": "$VALIDATOR_NODE_ADDRESS"
    96      }
    97  ]
    98  ```