3.5 Manual Peering
Manual peering enables node operators to manually manage nodes' neighbors, orthogonal to the peering protocols described in Section 3.3 - Peer Discovery and Section 3.4 - Peer Selection. This section defines manual peering protocol.
Manual peering can be additional protection against eclipse attacks as the manual peering is completely in the hands of the node operator based on real-world trust. Furthermore, it allows operating nodes without exposing their IP addresses to the network.
3.5.2 Detailed design
The known peers are given by the node operator, containing peers' public key and IP address. They are divided into two groups by comparing their public keys to the node's public key lexicographically:
- Chosen neighbors (outbound): If
node < peer, the node proactively sends a peering request to the peer.
- Accepted neighbors (inbound): If
node > peer, the node awaits the peer to send a peering request and accept it.
After the group of peers is decided, the node shall either send peering requests to the chosen neighbors or wait for peering requests from accepted neighbors. The connections are checked every
reconnectInterval, if a connection is dropped, the node shall try to re-establish it until the peer is removed or the node shutdowns.
A node removes a peer by closing the connection directly without sending a drop message described in Section 3.4 - Peer Selection to the peer. Thus, the removed peer shall still try to reconnect to the node every
reconnectInterval, until its operator removes the node from the manual peering list. That is, it is the node operators' responsibility to monitor and manage the known peer list in manual peering.
3.5.3 Request and response
Connections among manual peers are TCP connections. After the connection is established, nodes shall perform handshakes to validate the connected peer. Each handshake request and response shall be encapsulated into a
data and signed with the ed25519 private key of the sender's identity that contains the related public key to allow the receiver to verify the signature. All the received requests and responses shall be verified and those with invalid version numbers and signatures be discarded.
Request and Response Layout
|data||ByteArray||Contains the handshake request/response.|
|public_key||ByteArray||The ed25519 public key of the peer's identity used to verify its signature.|
|signature||ByteArray||The ed25519 signature of the `data` field, signed by using the private key of the peer's identity.|
|version||uint32||The version of the handshake protocol.|
|to_addr||ByteArray||The address of the peer.|
|timestamp||time||The unix timestamp of the handshake request.|
|req_hash||ByteArray||The sha256 digest of the corresponding received handshake request.|