Cordite Network Map
An open source Corda Network Map implementation
The Network Map design in Corda 3 has been a significant and very useful change. By defining a formal protocol, it has opened the possibility for compatibility zone operators to govern their zones in a manner suitable for their operations. If you’re interested to learn more, I highly recommend Mike Hearn’s excellent article:
We did this because we recognised that many teams, like ours, need an implementation they can use in their networks. The lack of one can sometimes be an impediment to the Corda adoption journey.
We’ve also added an innovation to help our journey towards greater decentralisation. More about this later.
The service is being used in the Cordite test networks and has been stable for a few months. The code quality, test coverage, and documentation is now suitable for open source distribution.
“cause nothing compares to U”
The Cordite Network Map Service (Cordite NMS for short) implements the Corda Doorman certification protocol used to acquire the identity of the node for the compatibility zone.
It also innovates with a new certification protocol that we call CertMan. This allows for a node operator to register the node’s identity using a pre-existing EV PKI certificate. DV and OV certificates can also be used, depending on the configuration of the service.
How CertMan works
CertMan assumes that most organisations have acquired their own certificates to enable secure communications for their digital services. Assuming this is the case for your organisation, CertMan will issue Corda nodes certificates (as a set of JKS files) in exchange for a proof of ownership against the organisation’s certificate. These certificates can be issued indirectly from a number of well-known root certificate authorities (CAs). There are options to choose the exact set of trusted root CAs, for example, whether to bypass the PKIX verification, to turn off strict EV certificates, and more.
Here’s a generalised sequence for using CertMan:
A glimmer of the future
This work forms a small step towards a larger vision: we think that the adoption of Corda can be accelerated by allowing grass-roots growth of networks that coalesce under the one CordaNet. We think that the best way of achieving this is to decentralise governance and inter-connectivity between discreet compatibility zones. Regarding governance, R3 and the Corda community have been doing a fantastic job to allow for collaborative control. For connectivity, we think it may be possible to allow for the organic composition of inter-compatibile-zones from constituent zones. More on this in future posts.
“Fly me to the moon …”
Running the Cordite NMS using Docker
Starting up the Cordite NMS is very easy when using Docker:
$ docker run -e NMS_TLS=false -p 8080:8080 cordite/network-map
The service will run on
http://localhost:8080. You can use this in your
myLegalName="CN=cordite foundation, O=cordite.foundation, L=Antarctica, C=AQ"
devMode : false
keyStorePassword : "cordacadevpass"
trustStorePassword : "trustpass"
compatibilityZoneURL : "http://localhost:8080"
The service will, by default, enable the
You can provide your own TLS certificate and key for the service using:
$ docker run \
-e NMS_TLS_CERT_PATH=<your-cert-path> \
-e NMS_TLS_KEY_PATH=<your-key-path> \
-p 8080:8080 cordite/network-map
Managing notaries and the whitelist
The Cordite NMS is designed to be simple to setup and maintain on commodity cloud hardware. One design choice is that its database is a simple filesystem. The location of the database is configurable (see Appendix A). Here’s the top level structure of the directory — note the
inputs directory contains the
whitelist.txt file required for zone constraints in Corda 3 and the validating and non-validating notary
nodeInfo-* files. You alter these files directly at run-time. The NMS will watch the
inputs directory for changes and will periodically publish changes to this directory as a network parameter update.
You can also use the Swagger API hosted on
Finally, most (but not all) of the API is exposed in the NMS user interface.
Working with CertMan
Let’s say, as a node operator, you have a certificate and private key stored in the files
domain.key respectively. We can receive our node’s JKS files using the following command line:
openssl dgst -sha256 -sign domain.key domain.crt | \
base64 | \
cat domain.crt - | \
curl -k -X POST -d @- http://<network-map-host-and-port>/certman/api/generate -o keys.zip
Here we sign our public certificate with our private key and concatenate the certificate and signature as a payload to the API end-point
/certman/api/generate. The returned zip file will contain the three
jks files required by Corda. Unzip these into the Corda
certificates directory and you’re good to go.
The certificate that’s presented to CertMan will be checked against the default set of root certificate authorities shipped with the JRE. If you’re not happy with this set, you can specify your own set of trusted authorities using
NMS_CERTMAN_TRUSTSTORE_PASSWORD. You can also control PKIX verification using
NMS_CERTMAN_PKIX and whether strict EV certificates are required using
We encourage the community to try it out and provide feedback! The source is Apache Licence v2 and we very much encourage contributions :-)
Appendix A: Configuration parameters
Here’s the full list of system properties and environment variables you can use to control your instance.