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 Create DAML App example on Canton. This guide (together with the DAML SDK getting started guide), will teach you

  1. The main concepts of DAML
  2. How to compile your own DAML Archive (DAR)
  3. How to run the Create DAML App example on Canton
  4. How to write your own DAML code
  5. 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 section explains how to work around them.

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

Starting Canton

Please follow the DAML SDK installation guide to get the SDK locally installed.

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

daml new create-daml-app create-daml-app

Then, compile the DAML code into a DAR file (this will create the file .daml/dist/create-daml-app-0.1.0.dar), and run the code generation step used by the UI:

cd create-daml-app
daml build
daml codegen js .daml/dist/create-daml-app-0.1.0.dar -o daml.js

You will also need to install the dependancies for the UI:

cd ui
yarn install

Next, the original tutorial would ask you to start the Sandbox and the HTTP JSON API with daml start. We will instead start Canton using the distributed setup in examples/04-create-daml-app, and will later start the HTTP JSON API separately.

Return to the directory where you unpacked the Canton distribution, and start canton with:

bin/canton -c examples/04-create-daml-app/canton.conf --bootstrap examples/04-create-daml-app/init.canton

Note

You may have to make the canton binary executable with chmod +x bin/canton

This will start two participant nodes, and will allocate the parties Alice and Bob. Each participant node will expose its own ledger API: #. Alice will be hosted by participant1, with its ledger API on port 12011 #. Bob will be hosted by participant2, with its ledger API on port 12021

Note that the examples/04-create-daml-app/init.canton script performs a few setup steps to permission the parties and upload the DAR.

Leave Canton running and switch to a new terminal window.

Running the Create DAML App example

Right now, the Create DAML App UI is configured to use the HTTP JSON API on port 7575. Each instance of the HTTP JSON API connects to one participant so we’ll only be able to run one instance of the UI application at a time, connected to one participant (assuming we don’t want to tweak the UI application).

Once Canton is running, start the HTTP JSON API connected to the ledger api on port 12011 (corresponding to Alice’s participant), and connected to the UI on the expected port 7575:

daml json-api \
    --ledger-host localhost \
    --ledger-port 12011 \
    --http-port 7575 \
    --allow-insecure-tokens

Leave this running. The UI can then be started from a 3rd terminal window with:

cd create-daml-app/ui
export REACT_APP_LEDGER_ID=participant1
yarn start

Note that we have to configure the ledger ID used by the UI to match the name of the participant that we’re running against. This is done using the environment variable REACT_APP_LEDGER_ID.

In order to login as Alice we need to know Alice’s party ID. Return to the running instance of Canton and enter the following command to the Canton console:

participant1.parties.list(filterParty="Alice").head.party

The result should look something like this:

res1: PartyId = PartyId(
  UniqueIdentifier(
    Identifier("Alice"),
    Namespace(
      Fingerprint(
        "016e41879bcbcfb629cfd26e8287a5fd4407ad06bd8f45cdd71d27bda401802a55"
      )
    )
  )
)

In this case, Alice’s party ID is Alice::016e41879bcbcfb629cfd26e8287a5fd4407ad06bd8f45cdd71d27bda401802a55, but your Fingerprint will differ. Enter Alice’s party ID in the UI to login as Alice.

Logging into Create DAML App as Alice

Note

The Sandbox performs party allocation implicitly, which is why you didn’t need this step when running the Create DAML App example against Sandbox. Canton, as well as other production ledgers, requires explicit party allocation. See the Provisioning Identities section of the Ledger API documentation for more information.

You can login as Bob using participant2 by following essentially the same process:

  1. Stop the UI and HTTP JSON API
  2. Restart the HTTP JSON API, this time using the option -- ledger-port=12021
  3. Restart the UI, with the ledger ID re-configured using the environment variable REACT_APP_LEDGER_ID=participant2
  4. Fetch Bob’s party ID from participant2 using the Canton console
  5. Login using Bob’s party ID

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 following the example of the Create DAML App template used in this tutorial.
  4. Read up on how to write good DAML.
  5. See how to compose workflows across multiple domains.