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 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, containing list of node info hashes and the network parameters hashes.

* 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           | /api/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            | /api/network-map                  | Retrieve ``NetworkMap`` from the server, the ``NetworkMap`` object contains list of node info hashes and NetworkParameters hash.                       |
+----------------+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| GET            | /api/network-map/node-info/{hash} | Retrieve ``NodeInfo`` object with the same hash.                                                                                                       |
+----------------+-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| GET            | /api/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.