Getting a Participant Node
What is a Participant Node on Tranquility?
A node has a number of components which allow a participant to execute transactions between ledgers that are connected to the Tranquility RLN Network. At SETL we call that collection of ledgers a ‘Settlement Domain’. Becoming a participant involves:
- Downloading the LedgerSwarm software comprising a simple Kafka consumer/producer component and a simple ledger with a front-end which will allow you to create your first transactions and to approve or reject transactions created by others.
- Choosing a partition name. This must be unique amongst all participants in the same Settlement Domain (Tranquility).
- Obtaining certificates and private keys from the Domain Controller.
- Preparing a server including setting up urls which point to that server.
- Deploying the software and the certificates to a server of your choice.
- Starting the participant on the server.
Participant Node Components
Tranquility passes payloads between participants using Kafka. It can be thought of as a transaction manager which directs messages between participants and keeps the state of a transaction until it goes final. If you want to participate with others on Tranquility, you have to have certificates and keys that allow you to identify yourself and to sign the various payloads that are passed between participants. Without these, you cannot connect to the Kafka topics that allow you to produce and consume payloads as part of a transaction.
Participant Ledger
Every participant in a LedgerSwarm domain needs a ledger. LedgerSwarm is designed to work with any ledger, traditional or DLT. To get going on the Tranquility test net, this process will install a test ledger which will keep track of balances in account so you can see the effect of transactions. In a live installation you will need to like the participant to your own banking or custody ledger.
Smart Contract Wallet
Smart Contracts on LedgerSwarm are JSON state objects which contain both code and data. The data changes when parties to the smart contract call functions in the code. When a smart contract is initialised, you can be assigned as a party to that contract with a defined role. Your role will determine which functions you can call and in what stage of the contract lifecycle you can make that call. For example, you could not redeem a loan before it has been made! If you want to participate in smart contracts you will need the LedgerSwarm smart contract wallet.
Smart Contract Host
LedgerSwarm smart contracts need to be hosted somewhere. The job of a host is to maintain the golden record of the smart contract state, to update that state when a party calls a function and to distribute the new state to the contract parties. Any participant on Tranquility can be a smart contract host and can offer a range of smart contract templates for their customers and other participants to use.
Preparing to Set up your Node
To install a node you will need a server to deploy it to. This server must be able to access the internet to connect to the Kafka topics hosted by the Tranquility test network. The server should also have a domain name set up with the A record pointing to the server's IP address. You will also be setting up a number of sub-domains which the node will use to route the browser to some of the sample front-end apps that will be installed. You do not need a TLS certificate as the install procedure will create them using Lets Encrypt
Before you deploy anything to this server, you will need to download, to your local machine, the ls-standalone-participant repo and make some changes to it. When those changes are complete, we will copy the necessary files to your server.
To get the repo, go to your command line and clone it as follows
Now follow these instructions
Step 1:
Setting Common Variables
Find the common file and amend the exported variables to reflect your chosen participant name and the default username and passwords for the apps.
For example if you chose the name mybank and the domain that points to your server is mydomain you might fill in the file as follows.
export PARTICIPANT_URL="mybank.mydomain.io"
export PARTICIPANT_USERNAME="mybank"
export PARTICIPANT_PASSWORD="password-for-mybank"
export FRONTEND_USERNAME="mybank"
export FRONTEND_PASSWORD="password-for-mybank"
# smart contract (optional)
export SMART_CONTRACT_WALLET_URL="wallet.mybank.mydomain.io"
export SMART_CONTRACT_HOST_URL="host.mybank.mydomain.io"
export SMART_CONTRACT_CONTRACT_URL="contracts.mybank.mydomain.io"
export ASSEMBLER_URL=""
export ASSEMBLER_USERNAME=""
export ASSEMBLER_PASSWORD=""
# participant only
export PARTICIPANT_NAME="MYBANK"
export PARTICIPANT_NAME_LOWERCASE="mybank"
export PARTICIPANT_FRONTEND_URL="ledger.mybank.mydomain.io"
# demo participant only
export PARTICIPANT_DEMO_URL="demo.mybank.mydomain.io"
export PARTICIPANT_DOMAIN="TRANQUILITY"
Step 2:
Certificates, Keys and Topics
Ask the domain controller to create certificates and topics. Send them the 'PARTICIPANT_NAME' you have chosen (for the example above thise would be MYBANK). The domain controller will need to enable that participant on the Tranquility network by setting up the neccessary Kafka topics for you to connect to. The domain controller will also send you a collection of certificates and private keys for you to unpack and install.
You will receive a certificates zip file from the domain controller.
Unzip the folder, there should be two folders (kafka_ca_ed and kafka_ca_p256).
Put these folders in the /certificates folder. If there are already folders with those names, you can delete them or overwrite them.
Step 3:
Copying Files to your Server
Before copying files to your server, you should log on to the server, and in the home directory create a new sub-directory called ls-standalone-participant. This is the directory into which files will be copied.
Back on your local machine, run copy-to-server and enter the IP address of the destination server. (Copies this project to a pre-existing folder called ls-standalone-participant.)
Step 4:
Setting up the Server
The next step is to ensure that the server has all the installed software needed to run a LedgerSwarm node. This step will also ensure that the ports that are used by LedgerSwarm are properly configured.
Go to the server, change to the ls-standalone-participant direcgtory and run ./new-server to prepare the server.
this will install docker and other software needed for LedgerSwarm. It will also configure the ports on the firewall.
Step 5:
Starting the Participant Node
From the ls-standalone-participant directory on the server, run ./start-participant to create a new ledgerswarm participant
This will take a few minutes to install a number of docker images and to initialise them some example data. It will also configure the reverse-proxy software, Traefik, to create TLS certificates for each of the sub-domains you specified in your common file.
When this has finished, The participant can be accessed in a browser using https://PARTICIPANT_FRONTEND_URL. So for the example shown above that would be https://ledger.mybank.mydomain.io. The username and password are what was assigend to the FRONTEND_USERNAME and FRONTEND_PASSWORD variables in the common file.
Optional Components
Step 6 (smart contract wallet and host):
Installing the smart contract wallet and host
Run ./start-smart-contract to create a new smart contract host and wallet.
The smart contract wallet can be accessed via https://SMART_CONTRACT_WALLET_URL. The username and password are SMART_CONTRACT_USERNAME and SMART_CONTRACT_PASSWORD.
Step 7 (hosting a smart contract template):
Deploying a smart contract template to the host
The smart contract host that has been created will have no smart contract templates. New templates can be added to the smart contract host via SMART_CONTRACT_CONTRACT_URL. The username and password are FRONTEND_USERNAME and FRONTEND_PASSWORD.
Examples of smart contract templates can be found here:
- https://github.com/ledger-swarm/ls-smartcontract-issue
- https://github.com/ledger-swarm/ls-smartcontract-paymentmandate
- https://github.com/ledger-swarm/ls-smartcontract-cheque
Before adding these or other templates check to see if they specify the Smart Contract accounts and RLN accounts permitted to be used in the contract. If so, ensure the these objects contain the relevant accounts.
In the examples above there are the partitions and partyMembers objects.
The partitions object is an array of PARTICIPANT_NAMEs. When the smart contract is initiated the user creating it will choose to and from accounts from that list. The identifiers in the list have a dash and a common name added to them to make it easy to recognise the name.
The partyMembers object is an array of smart contract accounts (PARTICIPANT_NAME) that can be chosen from to have permissions over the smart contract.
Step 8 (Participant Demo):
A Demonstration frontend that showcases LedgerSwarm
Run ./start-participant-demo to start the Participant Demo
The demo app can be accessed via https://PARTICIPANT_DEMO_URL. The username and password are FRONTEND_USERNAME and FRONTEND_PASSWORD.
Step 9 (Portainer):
Monitoring Hub
Run ./start in /portainer to start portainer. Portainer will show you the health of each of the docker containers that make up the LedgerSwarm participant node.
Upon first load when creating the admin user there is a 5 minute security timeout from when the container was started.
Note:
The ./stop command will stop all docker containers.