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.

3.5.1 Motivation

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

Name	Type	Description
data	ByteArray	Contains the handshake request/response.
public_key	ByteArray[32]	The ed25519 public key of the peer's identity used to verify its signature.
signature	ByteArray[32]	The ed25519 signature of the `data` field, signed by using the private key of the peer's identity.

Handshake request

Name	Type	Description
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.

Handshake response

Name	Type	Description
req_hash	ByteArray[32]	The sha256 digest of the corresponding received handshake request.