DAML SDK and Canton

Assuming that you’ve completed the previous “Getting Started with Canton” guide, you might now want to know, how you can build your own applications using the DAML SDK.

In this tutorial, you will learn how to run the DAML SDK Quickstart example on Canton. This guide (together with the DAML SDK quickstart), will teach you

  1. the main concepts of DAML
  2. how to compile your own DAML Archive (DAR)
  3. how to run the quickstart example on Canton
  4. how to use the generic contract browser Navigator on Canton.
  5. how to write your own DAML code
  6. how to integrate a conventional application with Canton

This tutorial builds on the DAML tutorial and mainly covers the difference of running the example on a distributed setup using Canton instead of running it on the DAML sandbox. This comes with a few known problems and this sections explains how to work around them.

Please run through the original DAML SDK tutorial to familiarise yourself with what you are going to do first. Then, come back here to get the same example running on Canton.

Starting the Quickstart Example

Please follow the DAML SDK installation guide to get the SDK locally installed and follow the quickstart download steps to get the example.

Starting from the location where you unpacked the Canton distribution, fetch the quickstart example into a directory named quickstart (as the example configuration files of examples/04-quickstart expect the files to be there):

daml new quickstart quickstart-java

Then, compile the DAML code into a DAR file (this will create the file .daml/dist/quickstart-0.0.1.dar):

cd quickstart
daml build
cd ..

Next, the original tutorial would ask you to start the Sandbox. We will start Canton using the distributed setup in examples/04-quickstart:

bin/canton -c examples/04-quickstart/quickstart.conf --bootstrap examples/04-quickstart/quickstart.canton

This will start four participant nodes, one for each party. All participant nodes will expose their own ledger API.

  1. Alice will be hosted by participant1, with ledger API on port 12011
  2. Bob will be hosted by participant2, with ledger API on port 12021
  3. USD_bank will be hosted by participant3, with ledger API on port 12031
  4. EUR_bank will be hosted by participant4, with ledger API on port 12041

Note that the examples/04-quickstart/quickstart.canton script performs a few setup steps to permission the parties, uploads the DAR and sets up a few initial contracts. It also calls the generate_navigator_config macro which will create one navigator configuration file per participant node (ui-backend-participantX.conf). Remember that the participant nodes are meant to be run by each individual organisation in their network. Hence, a single navigator instance can only connect to a single participant node.

Before starting the navigator instances, please copy or link the file quickstart/frontend-config.js to the directory where you are going to start navigator. This will ensure that you run Navigator with a few custom table views that greatly enhance the user experience of Navigator.

Now, start for every participant node one navigator instance by typing the following command in new terminals (OSX and Linux), changing the NUMBER for the appropriate participant instance (1-4).

NUMBER=1 && daml navigator server localhost "120${NUMBER}"1 -t wallclock --port "120${NUMBER}5" -c "ui-backend-participant${NUMBER}.conf"

For each instance, open a separate browser window in private mode, pointing to http://localhost:PORT, where PORT is the number provided as --port above. You will end up with a desktop looking like this.

Four instances of Navigator connected to their participant node individually.

Trying out the application

Following the tutorial, you should now try out to create a new IOU contract using Navigator. However, as you have already learned, the party identifiers for Canton are different. You can’t use Alice directly, you need to get the full identifier, which is key dependent.

Therefore, click on the current Iou contract in the contracts inventory, and copy Alice’ party identifier, something like Alice::019e12700d03f9c4e5cfb01323693a83349a3a4870ca2ed89060e73d262bd9419b, except that the last part will be different, because the key pair generated by the participant node will be different than used in this example. The same trick is needed to get to the party identifier of Bob in the subsequent steps: click on the listed contract in Bobs view.

Similarly, the tutorial will require you to enter contract ids. The contract ids for Canton are different and you need to copy paste the contract ids from the detail views. You can’t use e.g. #3:1.

Integrate with the ledger API

You can also run the example integration application. As in our setup, we use different ports and party identifiers, you have to start the example application using something like

mvn exec:java@run-quickstart -Dledgerport=12011 -Dparty="Alice::019e12700d03f9c4e5cfb01323693a83349a3a4870ca2ed89060e73d262bd9419b"

where you manually set the ledger API port and the party identifiers.

What Next?

Now that you have glimpsed at DAML and what a full DAML based solution looks like, it is maybe time for you to build your own first DAML application.

  1. Use the DAML language reference docs to master DAML.
  2. Build your own application that drives the models using one of the ledger clients.
  3. Create a simple UI using Navigators customized table views/ or use the HTTP JSON API Service to build your own UIs.
  4. Read up on how to write good DAML
  5. See how to compose workflows across multiple domains.