corda/docs/source/network-map.rst

Network Map

The network map stores a collection of NodeInfo objects, each representing another node with which the node can interact. There are two sources from which a Corda node can retrieve NodeInfo objects:

1. the REST protocol with the network map service, which also provides a publishing API,
2. the additional-node-infos directory.

Protocol Design

The node info publishing protocol:

• Create a NodeInfo object, and sign it to create a SignedData<NodeInfo> object. TODO: We will need list of signatures in SignedData to support multiple node identities in the future.
• Serialise the signed data and POST the data to the network map server.
• The network map server validates the signature and acknowledges the registration with a HTTP 200 response, it will return HTTP 400 "Bad Request" if the data failed validation or if the public key wasn't registered with the network.
• The network map server will sign and distribute the new network map periodically.

Node side network map update protocol:

• The Corda node will query the network map service periodically according to the Expires attribute in the HTTP header.
• The network map service returns a signed NetworkMap object which looks as follows:

data class NetworkMap {
    val nodeInfoHashes: List<SecureHash>,
    val networkParametersHash: SecureHash
}

The object contains list of node info hashes and hash of the network parameters data structure (without the signatures).

• The node updates its local copy of NodeInfos if it is different from the newly downloaded NetworkMap.

Network Map service REST API:

Request method	Path	Description
POST	/network-map/publish	Publish new NodeInfo to the network map service, the legal identity in NodeInfo must match with the identity registered with the doorman.
GET	/network-map	Retrieve NetworkMap from the server, the NetworkMap object contains list of node info hashes and NetworkParameters hash.
GET	/network-map/node-info/{hash}	Retrieve NodeInfo object with the same hash.
GET	/network-map/parameters/{hash}	Retrieve NetworkParameters object with the same hash.

TODO: Access control of the network map will be added in the future.

The additional-node-infos directory

Each Corda node reads, and continuously polls, the files contained in a directory named additional-node-infos inside the node base directory.

Nodes expect to find a serialized SignedData<NodeInfo> object, the same object which is sent to network map server.

Whenever a node starts it writes on disk a file containing its own NodeInfo, this file is called nodeInfo-XXX where XXX is a long string.

Hence if an operator wants node A to see node B they can pick B's NodeInfo file from B base directory and drop it into A's additional-node-infos directory.

Network parameters

Network parameters are constants that every node participating in the network needs to agree on and use for interop purposes. The structure is distributed as a file containing serialized SignedData<NetworkParameters> with a signature from a sub-key of the compatibility zone root cert. Network map advertises the hash of currently used network parameters. The NetworkParameters structure contains: * minimumPlatformVersion - minimum version of Corda platform that is required for nodes in the network. * notaries - list of well known and trusted notary identities with information on validation type. * maxMessageSize - maximum P2P message size sent over the wire in bytes. * maxTransactionSize - maximum permitted transaction size in bytes. * modifiedTime - the time the network parameters were created by the CZ operator. * epoch - version number of the network parameters. Starting from 1, this will always increment on each new set of parameters.

The set of parameters is still under development and we may find the need to add additional fields.