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 ```