Skip to content

Protocol Design - Networking

Part of work in progress Living Whitepaper

This page is part of the Living Whitepaper revisions currently underway to replace the original static whitepaper. These efforts include the Protocol Design and Node Implementation sections of the docs, which will cover and expand on details and topics covered in the original whitepaper.

See the bottom of the page for related whitepaper sections and other related details. Some of the sections and headers on this page may be in draft form or just suggestions/framework for later consideration. If you are interested in helping with revisions please connect with us on the #documentation channel on our Discord server.

TCP messages

TCP is used for traffic on the live network and for bulk data transfer on the bootstrap network.

Network Details

Port Type Default Details
7075 TCP Enabled
  • Node bootstrapping server
  • Share port configuration in config-node.toml, option node.peering_port
  • Binds to all adapters; unicast
  • Contents: Raw nano protocol stream
  • Transmits the ledger to new nodes in bulk
  • If blocked other nodes will not be able retrieve the ledger from this node
7076 TCP Disabled
  • RPC server
  • Port configurable in config-rpc.toml, option rpc.port
  • Enable in config-node.toml, option rpc.enable or by starting nano_rpc manually
  • Binds to localhost by default for security reasons, configurable in config-rpc.toml, option rpc.address; unicast
  • Contents: Unencrypted HTTP requests containing JSON object bodies
  • Allows the node to be queried or controlled through HTTP requests
  • If blocked the node will not be able to be queried or controlled by HTTP
  • WARNING: Exposing this port externally while setting enable_control option to true in configs could expose your wallet, allow the node to be stopped remotely and open your node up to other dangerous activity. See the Node Security page for more details.
7078 TCP Disabled
  • Websocket server
  • Port configurable in config-node.toml, option node.websocket.port
  • Enable in config-node.toml, option node.websocket.enable
  • Binds to localhost by default due to data throughput potentially being very high; producer-subscriber broadcast
  • Contents: Standard websocket frames containing JSON-encoded objects
  • See WebSocket Support for details on configuration

IPV4/IPV6 addressing

The system is built to only operate on IPv6 and uses IPv4-mapped IPv6 addresses to connect to IPv4 hosts.

Node telemetry

In v21 node telemetry was added to node. This allows peers to communicate telemetry metrics to each other. For specific details on the message format see telemetry_ack in the protocol specification.

The nodes are designed to reply to telemetry_req messages. They avoid replying if messages are received from the same peer in quick succession; the minimum time until another reply is 60 seconds on the main network, 15 seconds on beta. This is done to reduce bandwidth.

Telemetry messages bypass the node's bandwidth limiter so that services monitoring the network can still do so during when the network is heavily used. Sending telemetry_req frequently within this exclusion zone could see your ip blacklisted by other peers. The node safely handles this for you by doing ongoing requests periodically and only sent when valid to do so.

Signing

Telemetry_ack messages are signed using ED25519 as follows:

ED25519(key = node id public key, message = "node id || block count || cemented count|| unchecked count || account count || bandwidth capacity || peer count || protocol version || uptime || genesis block hash || major version || minor version || patch version || pre-release version || maker || timestamp since UTC epoch || active difficulty")

The node id used in the initial handshake is used for signing. The genesis block hash should be in big endian. The data is signed so that it cannot be forged by a Man In The Middle (MITM) attack.

Peer disconnections

Sending incorrectly signed telemetry data to peers will result in being blacklisted as it is seen as malicious, make sure the signing is correct! Verify signatures against known signing done by node by testing local telemetry. Nodes with a different genesis block hash will also be disconnected.

Peering process

Initial identification of peers is a node implementation detail, but once a node successfully connects with another using the protocol handshake, the keepalive messages each node sends will include a random selection of the IP addresses of 8 of their peers. Any new IP addresses will be included in the list of potential peers the node will attempt to connect with during bootstrapping, vote request, telemetry and other activities.

Live traffic

Bootstrap traffic

Existing whitepaper sections related to this page: