Corda

A Corda network consists of a number of nodes, which communicate using persistent protocols to create and validate transactions.

A node can perform three discrete functions. Each function is provided as a service, and a single node can perform several of them.

Notary

• Notary clusters prevent double-spending.

• Notary clusters function as time-stamping authorities. A transaction with a time-stamp window can only be notarized during that window.

• Notary clusters can validate transactions. In that case, they are called validating notaries.

• A single network can have several notaries, each running a different consensus algorithm.

Oracle

• An oracle is a service that only signs a given transaction if the relevant fact is true.

• The fact in question is included in the transaction as a part of the command.

Standard Node

All nodes have a vault and are able to evolve their private ledgers and initiate protocols communicating with other nodes, notaries, and oracles.

Setting Up Your Own Network

Certificates

Every node in a given Corda network must have an identity certificate signed by the network’s root CA. See Network permissioning for more information.

Configuration

A node can be configured by adding/editing node.conf in the node’s directory. For details see Node configuration.

An example configuration:

myLegalName : "O=Bank A,L=London,C=GB"
keyStorePassword : "cordacadevpass"
trustStorePassword : "trustpass"
dataSourceProperties : {
    dataSourceClassName : org.h2.jdbcx.JdbcDataSource
    "dataSource.url" : "jdbc:h2:file:"${baseDirectory}"/persistence"
    "dataSource.user" : sa
    "dataSource.password" : ""
}
p2pAddress : "my-corda-node:10002"
rpcSettings = {
    useSsl = false
    standAloneBroker = false
    address : "my-corda-node:10003"
    adminAddress : "my-corda-node:10004"
}
webAddress : "localhost:10004"
rpcUsers : [
    { username=user1, password=letmein, permissions=[ StartFlow.net.corda.protocols.CashProtocol ] }
]
devMode : true
// certificateSigningService : "https://testnet.certificate.corda.net"

The most important fields regarding network configuration are:

• p2pAddress: It specifies a host and port to which Artemis will bind for

  messaging with other nodes. Note that the address bound will not be

  my-corda-node, but rather :: (all addresses on all network interfaces). The hostname must be externally resolvable by other nodes in the network. In the above configuration, this is the resolvable name of a machine in a VPN.

• rpcAddress: The address to which Artemis will bind for RPC calls.

• webAddress: The address the webserver should bind. Note that the port must be distinct from that of p2pAddress and rpcAddress if they are on the same machine.

Bootstrapping the Network

The nodes see each other using the network map, which is a collection of statically signed node-info files, one for each node in the network. Most production deployments will use a highly available, secure distribution of the network map via HTTP.

For test deployments where the nodes (at least initially) reside on the same filesystem, these node-info files can be placed directly in the node’s additional-node-infos directory from where the node will pick them up and store them in its local network map-cache. The node generates its own node-info file on startup.

In addition to the network map, all the nodes on a network must use the same set of network parameters. These are a set of constants that guarantee interoperability between nodes. The HTTP network map distributes the network parameters which the node downloads automatically. In the absence of this, the network parameters must be generated locally. This can be done with the network bootstrapper. This is a tool that scans all the node configurations from a common directory to generate the network parameters file which is copied to the nodes’ directories. It also copies each node’s node-info file to every other node so that they can all transact with each other.

The bootstrapper tool can be built with the command:

gradlew buildBootstrapperJar

The resulting jar can be found in tools/bootstrapper/build/libs/.

To use it, create a directory containing a node.conf file for each node you want to create. Then, run the following command:

java -jar network-bootstrapper.jar <nodes-root-dir>

For example, running the command on a directory containing the following files would generate directories containing three nodes, notary, party A, and party B:

.
├── notary.conf             // The notary's node.conf file
├── partya.conf             // Party A's node.conf file
└── partyb.conf             // Party B's node.conf file

This tool only bootstraps a network. It cannot dynamically update if a new node needs to join the network or if an existing one has changed something in its node-info, e.g. their P2P address. For this, the new node-info file will need to be placed in the other nodes’ additional-node-infos directory. A simple way to do this is to use rsync.

Whitelisting Contracts

If you want to create a Zone whitelist (see API: Contract Constraints), you can pass in a list of CorDapp jars:

`java -jar network-bootstrapper.jar

..`

The CorDapp jars will be hashed and scanned for Contract classes. By default, the tool will generate a file named whitelist.txt containing an entry for each contract with the hash of the jar.

For example:

net.corda.finance.contracts.asset.Obligation:decd098666b9657314870e192ced0c3519c2c9d395507a238338f8d003929de8
net.corda.finance.contracts.asset.Cash:decd098666b9657314870e192ced0c3519c2c9d395507a238338f8d003929de9

These will be added to the NetworkParameters.whitelistedContractImplementations. See Network Map.

This means that by default the Network bootstrapper tool will whitelist all contracts found in all passed CorDapps.

If there is a whitelist.txt file in the root dir already, the tool will append the new jar hashes or contracts to it.

The zone operator will maintain this whitelist file, and, using the tool, will append new versions of CorDapps to it.

WARNING:

• The zone operator must ensure that this file is append only.

• If the operator removes hashes from the list, all transactions pointing to that

  the version will suddenly fail the constraint verification, and the entire chain will be

  compromised.

• If a contract is removed from the whitelist, all states created from that moment on will be constrained by the HashAttachmentConstraint.

NOTE: In future releases, a tamper-proof way of maintaining the contract whitelist will be provided.

For fine-grained control of constraints, in the event that multiple contracts live in the same jar, the tool reads from another file:exclude_whitelist.txt, which contains a list of contracts that should not be whitelisted, and thus default to the very restrictive: HashAttachmentConstraint

For example:

net.corda.finance.contracts.asset.Cash
net.corda.finance.contracts.asset.CommercialPaper

Starting the Nodes

You may now start the nodes in any order. You should see a banner, some log lines, and eventually Node started up and registered, indicating that the node is fully started.

In terms of process management, there is no prescribed method. You may start the jars by hand or perhaps use systems and friends.

Logging

Only a handful of important lines are printed to the console. For details/diagnosing problems, check the logs.

Logging is standard log4j2 and may be configured accordingly. Logs are by default redirected to files in NODE_DIRECTORY/logs/.

Connecting to the Nodes

Once a node has started up successfully, you may connect to it as a client to initiate protocols/query state, etc. Depending on your network setup, you may need to tunnel to do this remotely.

See Using the client RPC API for how to establish an RPC link.

NOTE: A client is always associated with a single node with a single identity, which only sees their part of the ledger.