Re-Designing the Network Map

Re-Designing the Network Map

Traditional blockchain architectures distribute transactions using a gossip protocol. Each node maintains connections to a handful of peers. When a node creates a transaction, it tells its peers, who tell their peers, and so on, until the transaction has reached every node on the network.

This model provides no privacy. Every node sees every other node’s transactions. To allow private communication between nodes, Corda replaces the gossip protocol with direct messaging between nodes based on IP addresses. The messages are encrypted using transport-layer security.

When messaging a peer, how can a node operator determine the counterparty’s IP address? This is achieved using a mapping of legal identities to IP addresses called the network map. The network map has several advantages:

• Ease-of-use. Node operators can transact in terms of legal identity names, rather than public keys or IP addresses (parties can still optionally be identified by public key only in transactions stored on ledger, for privacy purposes)
• Business requirements. Node operators can ensure they’re agreeing ledger updates with the correct counterparties
• Joining and leaving the network. The event of a node joining or leaving the network can be clearly communicated by updating the network map

Re-designing the network map

In Corda 1.x and Corda 2.x, the network map service was provided by a network map node. Each node would query the network map node for a copy of the network map upon joining the network, and subscribe for future updates.

This design was only temporary. It had several downsides:

• It doesn’t scale. A single node is expected to simultaneously maintain open connections to every other node on the network
• It’s unreliable. If the network map node goes offline, no new nodes can start up
• It’s not secure. An attacker perform man-in-the-middle attacks by intercepting the traffic from the network map node and modifying its contents

In Corda 3, the network map node has been replaced with a network map document served over HTTP. At start-up, each node creates and signs a data structure called a nodeInfo. Each nodeInfo contains a node’s legal identities, IP addresses and other information.

The node uploads this file to the compatibility zone’s network map server (a compatibility zone is a set of nodes and services — notaries, oracles, doorman, network map server — that are configured within a larger Corda network to be compatible with each other). The node then downloads and caches the signed nodeInfos of all the other nodes in the compatibility zone from the same server, which it periodically polls for updates.

Why the switch to this new design?

• It’s highly available. The distribution of the nodeInfos can be offloaded to CDNs like Amazon CloudFront or Akamai, which are highly scalable, available and attack-resistant
• It’s tamper-proof. Man-in-the-middle attackers cannot tamper with the nodeInfos, since they are signed by the nodes themselves

Using the new network map

Development networks

For rapid prototyping, development networks do not require a network map document to be served over HTTP. Instead, each node’s nodeInfo file is simply placed in an additional-node-infos folder on every other node.

To automate this process, a bootstrapper tool is provided. The bootstrapper automatically converts a set of node configuration files into a set of nodes, and copies each node’s nodeInfo file into every other node’s additional-node-infos folder. This replicates the new design without the requirement for a separate server.

The bootstrapper is run automatically when generating a development network using the Cordform
Gradle task. You can also perform the bootstrapping manually by following the instructions here. You must re-run the bootstrapper every time a node leaves or joins the network to ensure the nodeInfo files remain up-to-date.

Production networks

Production networks must create a network map server that implements the protocol described here. Each network operator will implement this protocol differently based on their network’s on-boarding process.

Find out more

To find out more, read the network map documentation and the bootstrapper documentation, or join the Corda community and dev team on the #cordaledger Slack channel.

If you encounter any issues with the new network map or other Corda features, post a question on Stack Overflow using the `corda` tag.