Project Ubin Phase 2 - Corda

This repository contains the source code and test scripts for the Corda prototype in Project Ubin Phase 2.

Ubin Phase 2 is a collaborative design and rapid prototyping project, exploring the use of Distributed Ledger Technologies (DLT) for Real-Time Gross Settlement.

• Read the Project Ubin Phase 2 Report here.
• For more detailed documentation, refer to the Technical Reports: Overview, Corda and Testing.

All CorDapp code is in Kotlin and uses custom Corda libraries which are based on Corda v1.0 with additonal fixes for Project Ubin use cases. The libraries are hosted in the following artifactory: https://ci-artifactory.corda.r3cev.com/artifactory/ubin

A copy of the libraries are also stored in the repository below: https://github.com/project-ubin/ubin-corda-core.git

Additional notes:

• An external service (mock RTGS service) is to be deployed for Pledge and Redeem functions. It can be found in the ubin-ext-service
• A common UI can be found in the ubin-ui repository

A. Pre-Requisites

You will need the following installed on your machine before you can start:

• JDK 8 installed and available on your path.
• Latest version of IntelliJ IDEA (note the community edition is free)
• h2 web console (download the "platform-independent zip")
• Git

For more detailed information, see the getting set up page on the Corda docsite.

B. Getting Started

To get started, clone this repository with:

git clone https://github.com/project-ubin/ubin-corda.git

C. Build CorDapp

1. Go to newly created folder

cd ubin-corda

2. Build CorDapp with Gradle

$ ./gradlew clean build deployNodes

3. CorDapp can be found at:

ubin-corda/build/nodes/<anyofthefolder>/plugins/

# Example:
ubin-corda/build/nodes/MASRegulator/plugins/

D. Running the network locally:

$ cd build/nodes
$ ./runnodes

All the nodes (defined in the deployNodes gradle task in the project root) will start in console. From this point the CorDapp can be controlled via web APIs or websites hosted by the nodes.

Set Up New Network

Note: Following steps have been tested in Ubuntu 16.04 LTS

A. Pre-Requisites

You will need the following components set up/installed:

• 15 Ubuntu (Xenial - LTS 16.04) VMs (11 banks, 1 MAS Central Bank node, 1 MAS as Regulator node, 1 Network Map, 1 Notary) with minimum specifications of 1 core, 3.5 GB RAM
• JDK 8 installed and available on your path.
• Git

B. Network setup step:

1. Set up network map

2. Set up notary

3. Set up bank nodes

4. Set up Ubin external service (MEPS+ mock service)

The script configure.sh from ubin-corda-deployment repository takes in 5 input parameters:

• Node type (value: networkmap, notary, node)
• Virtual machine (VM) username
• Network Map Name
• Notary type (default value is "nonValidating")
• Network Map IP address

1. Set Up Network Map

1. SSH to Network Map virtual machine.

2. Clone ubin-corda-deployment repository

$ git clone https://github.com/project-ubin/ubin-corda-deployment.git

3. Determine network map node name (e.q. Network Map)

4. Get virtual machine IP address with following command:

$ hostname -i

5. Execute configure.sh script with:

sudo ./configure.sh networkmap <<VM Username>> <<Network Map Name>> nonValidating <<Network Map IP>>

Example:

# Network map name is "Network Map"
# Network map IP address is "10.0.0.47"
# VM username is "dltusr"

chmod +x configure.sh
sudo ./configure.sh networkmap dltusr "Network Map" nonValidating 10.0.0.47

Note: Network map IP address is required in the set up of notary node and additional bank nodes

2. Set Up Notary

1. SSH to Notary virtual machine.

2. Clone ubin-corda-deployment repository

$ git clone https://github.com/project-ubin/ubin-corda-deployment.git

3. Determine Notary node name (e.g. Notary)

4. Get network map IP Address from the previous step (network map setup).

5. Execute configure.sh script with:

sudo ./configure.sh networkmap <<VM Username>> <<Network Map Name>> nonValidating <<Network Map IP>>>

Example:

# Notary name is "Notary"
# Network map IP address is "10.0.0.47"
# VM username is "dltusr"
$ chmod +x configure.sh
$ sudo ./configure.sh notary dltusr "Notary" nonValidating 10.0.0.47

3. Set Up Bank Nodes

1. SSH to bank nodes virtual machine.

2. Clone ubin-corda-deployment repository

$ git clone https://github.com/project-ubin/ubin-corda-deployment.git

3. Determine bank node name (usually the bank SWIFT code).

4. Get network map IP Address from the previous step (network map setup).

5. Go to ubin-corda-deployment directory.

6. Verify config.properties to ensure ApproveRedeemURI is configured with the Central Bank domain name.

ApproveRedeemURI=http://<<host>>:9001/meps/redeem

Note: Replace host with Central Bank virtual machine host/domain name.

7. Execute configure.sh script with:

$ sudo ./configure.sh notary <<VM Username>> <<Notary Name>> nonValidating <<Network Map IP>>

Example:

# Nodename name is "BankA"
# Network map IP address is "10.0.0.47"
# VM username is "dltusr"

$ chmod +x configure.sh
$ sudo ./configure.sh node dltusr "BankA" nonValidating 10.0.0.47

Note: do not name the Corda node with a name containing "node".

4. Setup Ubin External Service

Ubin external service should be set up in the Central Bank virtual machine. This is a mock service of the current RTGS system, MEPS+.

Build

1. Clone the repository locally

$ git clone https://github.com/project-ubin/ubin-ext-service.git

2. Go to newly created folder

$ cd ubin-ext-service

3. Build project using gradle

$ ./gradlew build

4. Build artifact can be found at

build/libs/ubin-ext-service-0.0.1-SNAPSHOT.jar

Start External Service

1. Update the application.properties file

ubin-ext-service/application.properties

With Corda configurations:

PledgeURI=http://<host>:9001/api/fund/pledge
RedeemURI=http://<host>:9001/api/fund/redeem
Dlt=Corda

Note:

• Replace host with Central Bank host/domain name.
• RedeemURI is not used in Corda, it is just a placeholder.

2. Copy built JAR artifact and properties files to the Central Bank VM

ubin-ext-service/build/libs/ubin-ext-service-0.0.1-SNAPSHOT.jar
ubin-ext-service/application.properties

Note: Ensure both files are in the same directory

3. From Central Bank VM, start the mock service application

$ java -jar -Dspring.config.location=application.properties -Dserver.port=9001 ubin-ext-service-0.0.1-SNAPSHOT.jar

Central Deployment and Server Admin

A. Getting Started

1. Go to Node 0 Virtual Machine

2. From the home directory, clone the ubin-corda-deployment repository

$ git clone https://github.com/project-ubin/ubin-corda-deployment.git

3. Update configuration variable with target environment detail

username='username'
host_prefix='cordavm'
host_suffix='.example.com'
notary_host='notary.example.com'
networkmap_host='networkmap.example.com'
nm_db_url='jdbc:h2:tcp://networkmap.example.com:11000/node'
nm_db_user='sa'

Note:

• Populate username with VM username - This script assumes all vm in the network has the same username
• This script assumes VMs hostname is in following format:

    <host_prefix><number><host_suffix>
  

• Number in hostname is assumed to be in consecutive order.

  #Example:
  
  node1.example.com
  node2.example.com
  ...
  node13.example.com
  
  #host_prefix: node
  #host_suffx: .example.com
  

B. CorDapp Deployment

1. Copy CorDapp JARs into VM Node 0 into the following directory with SCP/FTP:

/home/<username>/ubin-corda-deployment/plugin

Note: Replace username with your VM username

2. Log in to VM Node 0 using SSH

3. Go to ubin-corda-deployment directory

4. Execute manage.sh to deploy CorDapp to all nodes in the network except the Notary and the Network Map. The script assumes that the nodes are named sequentially (e.g. 0 to 12):

$ ./manage.sh deploy 0 12

This step does the following:

• Delete everything in /app/corda/plugins
• Copy all plugins file from deployment node (VM Node 0) to the target node's /app/corda/plugins folder
• Restart Corda and webserver in the node
• Repeat for selected Nodes

Note: 0 and 12 in Step 4 represents the range of nodes. If you only require deployment on nodes 2-4, change the parameters to "deploy 2 4".

C. Restart All Nodes

1. Log in to VM Node 0 using SSH

2. Go to ubin-corda-deployment directory

3. Execute manage.sh to restart all nodes in the network (e.g. Node 0 - Node 12):

$ ./manage.sh restart 0 12

Note: 0 and 12 in Step 3 represents the range of nodes. If you only require deployment on nodes 2-4, change the parameters to "deploy 2 4".

D. Stop All Nodes

1. Log in to VM Node 0 using SSH

2. Go to ubin-corda-deployment directory

3. Execute manage.sh to stop all nodes in the network (e.g. Node 0 - Node 12):

$ ./manage.sh stop 0 12

Note: 0 and 12 in Step 3 represents the range of nodes. If you only require deployment on nodes 2-4, change the parameters to "deploy 2 4".

E. Clear All Data in Vault

1. Log in to VM Node 0 using SSH

2. Check that you are in home directory

3. Go to ubin-corda-deployment

4. Stop all Corda nodes (node 0 to 12) using:

$ ./manage.sh stop 0 12

5. Clear all data in network (node 0 to 12) - note that the data is not recoverable:

$ ./manage.sh reset 0 12

6. Restart all nodes 0 to 12:

$ ./manage.sh restart 0 12

F. Update Node Names

1. Stop the Corda server and webserver

2. Go to /app/corda

3. Update node.conf with command:

$ vi node.conf

4. Change myLegalName in "O" key :

"O=BOTKSGSX, L=Singapore, C=Singapore"

5. Delete the certificates folder. The certificates will be regenerated automatically upon Corda server start up

6. To purge the old entries in the Network Map, login to the h2 DB of the Network Map (nm0) and delete the old entries in NODE_NETWORK_MAP_NODES table

Note:

As of Corda v1.0, 'CN' / Common Name field in the X500 is no longer supported. It is used only for services identity. In addition, words such as "node" is blacklisted in CordaX500Name and therefore should not be used.

G. Database Admin

(Based on instructions in https://docs.corda.net/node-database.html)

1. Install h2 client locally and run h2.sh (Unix) or h2.bat (Windows)

2. Enter the JDBC URL with format:

jdbc:h2:tcp://<<CORDA NODE HOST>>:<<H2 DATABASE PORT>>/node

# Example:
jdbc:h2:tcp://<host>:11000/node

Note: Replace host with the node virtual machine host/domain name

3. Username and password is as per default 4. Connect to browse h2 DB

H. Individual Node CorDapp Deployment

1. Copy new/updated CorDapp JARs to the following directory in the Corda Node VM:

/app/corda/plugins

2. Restart Corda nodes:

$ sudo systemctl restart corda
$ sudo systemctl restart corda-webserver

Note:

• Replace "restart" with "start" or "stop" to simply start/stop the services
• Replace "restart" with "status" to view the latest logs
• Log location: /app/corda/logs
• Once the CorDapp JARs are uploaded and replaced, the Corda server (service) must be restarted

Test Scripts

Postman is the main testing tool used for this prototype. The Postman collection and environments are located in the test-scripts folder in this repository. The API definitions can be found in the Technical Report repository.

License

Copyright 2017 The Association of Banks in Singapore

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.