Console Overview

Overview

Daml Hub is a cloud platform built to help you take your SaaS application from humble beginnings to mass adoption with as little development as possible.

Daml Hub is a great option for any developer looking to build a simpler, scalable backend for their application with a serverless experience.

Almost any application heavier than a pure web app can benefit from using Daml Hub as a backend. Developers are using Daml Hub to build applications like crypto exchanges, loan management platforms, medical claims management, digital rights management, and many more.

Workspace

After signing in to Daml Hub, you will be given your very own app-building workspace. The workspace is where you can manage your projects, ledgers and files. Each project can contain multiple ledgers that differ based on their deployments. Both projects and ledgers can be created and deleted within the workspace. For more information on ledgers, please see the Daml Ledger Model.

Screenshot Placeholder

The collections tab in the workspace is where you can upload and manage files containing Daml models and triggers, automation, and UI assets. By keeping your files in your workspace collection, it is easier to deploy and re-deploy them across multiple ledgers. Files can be deployed into a ledger from the workspace collection by clicking the button Deploy to..., or by simply dragging and dropping the file into a ledger.

The workspace is also home to fully functional, pre-built sample applications. You can deploy these applications to their own dedicated ledger with a single click. For more information and a quick start guide, see Sample Apps.

Ledger Limits

For users on the Daml Hub Free Tier, ledgers will be paused after 24 hours of inactivity. This means that the ledger and all of its deployed artifacts (user websites, automation, and integrations) are suspended. At any point within 90 days of the time it is paused, a ledger can be resumed from the Workspace.

After 90 consecutive days of inactivity, the paused ledger and all of its deployed artifacts will be permanently removed.

File Size Limit

The file size limit for all files, including .dar, .dit, .tar, .tgz, .tar.gz, and, .zip is 32 MB.

Ledger Explorer

In the Ledger Explorer, you can join existing Daml Hub applications and navigate to other applications you've visited in the past.

Screenshot Placeholder

Joining Other User's Apps

Obtain the Ledger ID of the app you would like to join from its owner, then click the Join by Ledger ID button in the Ledger Explorer page to add it to your Apps list.

After joining the app, a new tab will open and one of two things will happen. If it exists, you will be directed to the application's web interface. Otherwise, you will be brought to that application's Live Data view. In the Live Data view you can browse publicly available data, create contracts on the ledger, see your own current active contracts, and exercise choices.

All apps you've joined will appear as tiles on the Ledger Explorer page. Click on a tile to navigate to its Live Data view.

If an application you've joined is deleted by its owner, the tile will become inactive. You can remove inactive tiles from the list by clicking on them.

Quick Build

The Quick Build tab is revealed when you click "Wondering what to do next?". It shows you the building blocks of a Daml Hub app, and the file count of your current ledger. Click on a tile to upload Daml, Daml Triggers, automation, and UI assets directly to your ledger. These tiles also contain links to their corresponding sections of the Daml Hub documentation.

Screenshot Placeholder

Deployments

By clicking on a ledger in the workspace, you can view its contents. The Deployments tab is where you can manage deployed artifacts, configure new instances, and publish a frontend for your application.

After uploading a file to your ledger, it will appear in the Action Needed tile as a deployed artifact. Here, you will be prompted to configure the first instance that artifact. Daml and UI Asset artifacts only need to be deployed once to your ledger, while automation, trigger, or intergration artifacts can have multiple running instances.

Screenshot Placeholder

Deployed artifacts are listed in the Deployments table. Here you can easily manage and access each artifact's data, instances, code, and settings.

Screenshot Placeholder

Daml Models

Daml templates define the data model and the functional features of your application. For more information on Daml, and Daml modeling, see An Introduction to Daml.

Automation

Most applications powered by Daml Hub will include a combination of Daml templates and automation. You can write automated services in Python or by using Daml Triggers.

Daml Triggers

Daml Triggers allow you to write your app's automated processes in Daml. To deploy a Daml Trigger to Daml Hub, have all of the Daml templates compiled into one model .dar. Have the separate trigger project import this model in the dependencies of daml.yaml.

sdk-version: X.X.X
name: copy-trigger
source: daml
parties:
  - Alice
  - Bob
version: 0.0.1
# trigger-dependencies-begin
dependencies:
  - daml-prim
  - daml-stdlib
  - daml-trigger
  - copy-trigger-model-0.0.1.dar
# trigger-dependencies-end

Execute daml build on the trigger project, then upload both the model .dar and the trigger build separately to your Daml Hub ledger.

For more information on Daml Triggers see Runnning a Daml Trigger.

For limits on file size for .dar see file size limit above.

Python Bots

Python bots must be uploaded and deployed in the form of .tar, .tgz or .tar.gz files. You can read more about how to write and test bots here.

For limits on file size for .tar, .tgz, and, .tar.gz see file size limit above.

Integrations

Integrations are installable modules that allow your app to interact with the outside world by sending and receiving requests from external systems. Once installed in a Daml Hub app, an integration mediates between the Daml Hub ledger and an external system, managing connections to the external system, converting data to and from Daml contracts, and participating fully in the Daml security and permissions model. Integrations are uploaded and deployed in the form of .dit files and managed through the Daml Hub console. To get started, there is a standard package of some basic integrations available in the Workspace under After you create a project.... You can read more about how to configure and install integrations here.

App UI

The App UI feature of Daml Hub allows you to provide a frontend for your app by publishing files to be exposed by HTTPS over a ledger-specific subdomain. These files are associated with the underlying ledger, and any access to that ledger by a UI hosted in Daml Hub is authenticated and authorized through Daml Hub itself.

UI assets must be uploaded to Daml Hub and deployed in the form of .zip files. The .zip should contain a single root directory and the contents of that directory should contain an index.html, along with the rest of the resources for your UI. As an example, for DABL Chat, the ZIP file contains a toplevel build/ directory with all the assets for the UI. If there's anything outside that toplevel directory or if the build/index.html file is missing, the Daml Hub console will signal an error when you attempt to upload the UI .zip into the workspace collections. For limits on file size for .zip see file size limit above. (If you're building with npm, there is no need to include node_modules or any of the UI source. The UI .zip file only includes to need the build output.)

$ unzip -l dablchat-ui-0.2.0.zip
Archive:  dablchat-ui-0.2.0.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  10-23-2020 10:56   build/
      457  10-23-2020 10:56   build/favicon.ico
     2275  10-23-2020 10:56   build/index.html
     1290  10-23-2020 10:56   build/precache-manifest.4b024a2a5462fd8f8b4f3a3c11220b3e.js
    12933  10-23-2020 10:56   build/logo512.png
     1568  10-23-2020 10:56   build/asset-manifest.json
        0  10-23-2020 10:56   build/static/
        0  10-23-2020 10:56   build/static/css/
    19361  10-23-2020 10:56   build/static/css/main.4e40915c.chunk.css.map

  ... elided ...

      496  10-23-2020 10:56   build/manifest.json
     1181  10-23-2020 10:56   build/service-worker.js
       57  10-23-2020 10:56   build/robots.txt
     4452  10-23-2020 10:56   build/logo192.png
---------                     -------
  3825920                     30 files

When your UI Asset is deployed to its associated ledger, you can publish it to a unique subdomain.

Subdomains

Each ledger in the workspace is given two default domains. You can view these domains in the Ledger Settings tab. {ledgerID}.daml.app should be the primary domain for new and existing ledgers. The {ledgerId}.projectdabl.com domain will be deprecated on December 31, 2021. You can enable or disable these default domains at any time. If you have an existing ledger that uses the projectdabl.com domain, toggling the default domains will help in the process of testing and migrating to the daml.app domain. For more information about the daml.app domain and using the Daml Hub API, visit the API Docs.

Screenshot Placeholder

When you are finished migrating to the daml.app domain or if you've created a new ledger, be sure to disable the soon-to-be-deprecated projectdabl.com domain. That way the daml.app domain will be listed in the Deployments tab next to Subdomain: here:

Screenshot Placeholder

Custom Subdomains

In addition to default ledger domains, Pro users have access to Daml Hub's custom subdomain feature. It allows you to specify, reserve and assign custom subdomains to your ledgers. A ledger's custom subdomain can be edited in its Deployments tab next to Subdomain: or in the Ledger Settings tab. Click the edit icon and enter the custom subdomain you would like to assign to this ledger. Custom subdomains must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. By pressing save, the subdomain will be reserved to your account and will act as an alias to your ledger's default domains. You can remove or re-assign the custom subdomain at any time.

Screenshot Placeholder

You can also manage your account's custom subdomains in the Subdomains tab of your Account Settings. A custom subdomain can be either reserved or active. When a custom subdomain has the status reserved, it means that you've claimed the domain but it has yet to be assigned to a ledger. When a custom subdomain has the status active, it means that you've claimed the domain and it has been assigned to a ledger.

Screenshot Placeholder

In the Subdomains tab of your Account Settings you can reserve subdomains, assign them to ledgers, remove them from ledgers, re-assign them to different ledgers and delete them from your account.

Live Data

The Live Data tab allows you to explore the Daml contracts on your ledger.

The table displays a list of contracts filtered by party. Therefore, the contracts listed at any given time are those that the selected party can view and take action on. You can manually add parties by clicking the Add Party button.

You can view a specific contract's data by selecting it from the center column. Additionally, you can exercise choices on behalf of your currently selected party. Daml contracts can be created in two ways: either by clicking the Add Contract button and creating a new contract from a template or by exercising a choice on an existing contract. New contracts are temporarily marked with a green dot to indicate that they have been recently created.

Screenshot Placeholder

When creating a contract from a template, be advised of the following type structure:

  • Primitives - For Int, Decimal, Text, Timestamp, Scenario, and ContractId simply enter the value in the empty field. Date lets you select the date you want from a calendar. Party and Bool inputs contain dropdowns where you select the desired value.

    Note: The Party dropdown will only display the parties that are visible to you. If you've created the ledger, you will see all the parties of each joined user. If you've joined someone else's ledger, you will only be privy to the parties that you've created. If you would like to input a party that you don't have visibility to, you will need to ask that party's user for their party ID, and paste it into the dropdown directly.

  • Lists - Enter each value of the list separately and press enter. An empty list is created by default if you don't enter any values. If you wish to delete a single value, press on the x that appears above it.

  • Optionals - Optional primitives are inline whereas optional records and variants are on newlines. To input an optional value, click on the view button and fill in the fields. The information is saved even when you collapse the window. If you don't want to enter anything, leave the fields blank.

  • Maps - Maps are represented as key-value pairs. Keys and values have their respectively separate input fields.

  • User-Defined Types - Variants appear as dropdowns and records as blocks containing their values. Variants with constructors appear as dropdown menus. Each constructor is an item on the dropdown. Once a constructor is chosen, the input fields for it appear below.

The representation of user-defined types may become arbitrarily complicated and this user interface assumes a relatively simple structure of the latter.

Sample Apps

Deploy your own Daml Hub Sample App

After signing in to the Daml Hub console, a few sample apps will appear at the bottom of the workspace. These are simple Daml Hub applications, built by Daml Hub engineers. Deploy them onto a ledger to get started with a fully implemented example.

  1. In the bottom section of the workspace, pick an app to deploy, and click Deploy.

Screenshot Placeholder

  1. Click on the ledger you just deployed to.

Screenshot Placeholder

  1. Configure the deployed artifacts in your ledger.

Go to the Deployments tab. The uncongifured deployment will appear under Action Needed. Click Deploy Instance. It will take a couple of minutes to deploy.

Screenshot Placeholder

Click on each automation row and within it click on the Configure New Instance. Configure an instance of each automation as the UserAdmin party. You may view the status of these instances in that deployment's instance table.

Screenshot Placeholder

  1. You're live!

Back on the Deployments tab of your ledger, clicking View Site will navigate you to a running instance of your app's UI.

Screenshot Placeholder

  1. Explore your app in the Daml Hub console

After deploying your sample app, you can inspect active contracts on the ledger and create new ones from the Live Data tab, upgrade and view your artifacts in the Deployments tab, and learn more about your ledger in Ledger Settings.

If you want to modify a sample app according to your needs you can find the source code on:

DABL Chat Github

OpenWork Board Github.

DABL Chess Github (coming soon!)

Inviting Users to your Application

To invite users to your application, distribute the Ledger ID -- copyable from the Deployments tab -- to your users. They will be able to join your application by using the Ledger Explorer, with the steps outlined here.

After they join your app, their party ID should appear in the parties list, as well as in any party dropdown when creating contracts or exercising choices in the Live Data console.

Integrations

Installing and Managing Integrations

Installing Integration Types

Daml Hub integrations available for installation are shown in the "Browse Integrations" tab of the ledger view. An integration may be installed into a ledger by clicking the "Deploy" button for the corresponding integration.

Screenshot Placeholder

Once the integration has been installed into the ledger, the tile will update to show a "Go to deployment" link that will show the deployment tab for the ledger. This will allow instances of that integration to be installed and managed within the ledger.

Screenshot Placeholder

If there are multiple versions of an integration that are availble to install, they will be listed in a dropdown in the upper right corner of the respective tile. Unless you have a specific reason to install a different version of an integration, it's best to install the latest version, which will be the default selection of the drop down. As you set the dropdown, the tile will update to show information relevant to the selected version. This includes the deployment status of the integration. (Note that it's possible to have multiple versions of the same integration installed, which can be useful when migrating from one version to the next.)

Screenshot Placeholder

Once an integration is installed, the integration becomes available for deployment within the deployments tab for the ledger:

Screenshot Placeholder

Deploying the integration makes its resources available for use. Integrations generally contain a Daml model that represents their data model and also integration types that can be deployed to connect the ledger to the outside world. The Daml model bundled within an integration is exactly like any other Daml model installed into a ledger. It's possible to inspect the Daml code for the integration's Daml model, create and inspect contracts defined within that model, and exercise choices on those contracts. (In fact, ledger actions taken on an integration model's contracts are usually the public API for that integration. ie: Creating a contract to send an outbound message, etc.)

Screenshot Placeholder

Creating and Managing deployments

Once an integration has been installed into a ledger, instances of integration types defined within that integration may be deployed into the ledger for use. Clicking on an integration type displays a screen showing configuration options for that integration.

Screenshot Placeholder

Every integration has two standard configuration fields - a field for a label describing the purpose of the specific integration, and a field identifying the ledger party the integration will run as. When running, the integration has only the rights of the "Run As" party - It can only see events relating to the contracts visible to that party and can only exercise choices on behalf of that party. If there is a need for an integration to run as more than a single party, a separate deployment of the integration must be created for each party. Some integrations also allow for additonal configuration fields beyond just these two.

Once the integration has been launched, it appears on a list of deployments of that type of integration. Additional deployments (running as different parties or with different configuration settings) can be added by clicking on Configure New Instance. Deployments may also be selected, to allow them to be disabled or removed entirely.

Screenshot Placeholder

There are also options available under View Details for inspecting and adjusting the configuration of the integration, viewing the detailed status of the integration, and seeing a technical log of how the integration is operating.

You can view running integrations as listed on the Deployments screen. Clicking on the name of the integration links to the deployment list for that specific integration and the screen for creating new deployments of that type.

For integrations that have inbound webhooks, the URL's of those hooks are visible under the detailed status for that integration deployment.

Screenshot Placeholder

Core Integrations

Daml Hub ships with two special purpose core integrations. These are not typical integrations in that they do not strictly integrate with external systems, but they are intended for solving specific problems without additonal code. The first is a periodic timer integration that allows ledger choices to be exercised in response to a periodic timer. The second is a Loopback integration that allows ledger commands to be issued in response to events occurring on the ledger.

Custom Integration Types

If you have an interest in adding custom integration types to Daml Hub, either for your own use or for the community, please contact Digital Asset for more details.

Ledger Initialization with Daml Script

Daml script is a development tool with a simple API that runs against an actual ledger. Using it with Daml Hub achieves automated and accurate ledger bootstrapping, enabling you to skip manual onboarding and other preliminary logic to initialize the state of your ledger.

Migrating Scenarios to Daml Script

The simplest way to write Daml script is to use pre-existing scenarios and make simple changes to them. The Daml docs have a migration guide that explains this simple translation. Otherwise, the Daml docs also have a guide for writing Daml Script from scratch, which is very similar to writing scenarios.

Changing the scenario code of your .dar will ultimately change its hash. To avoid this, create a directory containing the project with your Daml models, and create a new project in that directory containing a single file for your Daml Script.

Now, copy your scenario code into the single file of your script project. Convert it to Daml Script and import the contracts used in your models, as well as Daml.Script.

In the case of onboarding ledger parties, your Daml script should include a record containing the ledger parties in your workflow. This record is passed in as the argument for your script. Below is an example of a script that takes parties as input:

  module Setup where

  import Actors.Intern
  import Actors.Analyst
  import Actors.Associate
  import Actors.VicePresident
  import Actors.SeniorVP
  import Actors.ManagingDirector

  import Daml.Script

  data LedgerParties = LedgerParties with
    intern : Party
    analyst : Party
    associate : Party
    vicePresident : Party
    seniorVP : Party
    managingDirector: Party
      deriving (Eq, Show)


  initialize : LedgerParties -> Script ()
  initialize parties = do
    let intern = parties.intern
        analyst = parties.analyst
        associate = parties.associate
        vicePresident = parties.vicePresident
        seniorVP = parties.seniorVP
        managingDirector = parties.managingDirector

    -- continue with the rest of your script's logic...

Configure your build with Daml Script

In the daml.yaml file of your script project, add daml-script to the list of dependencies, the ledger parties that you specified as arguments to your script, and under data-dependencies add the name of the corresponding .dar containing your models. If you are not using a separate project for your script, you can exclude that line.

sdk-version: 1.3.0
name: bootstrap-script1
source: daml
init-script: Setup:initialize
parties:
  - Intern
  - Analyst
  - Associate
  - VicePresident
  - SeniorVP
  - ManagingDirector
version: 0.0.1
dependencies:
  - daml-prim
  - daml-stdlib
  - daml-script
data-dependencies:
  - ../bootstrap/.daml/dist/bootstrap-0.0.1.dar
sandbox-options:
  - --wall-clock-time

Deploy your .dar to a Daml Hub ledger

In the terminal, execute the command daml build in your script project. Then, upload the .dar containing your models to an empty ledger in Daml Hub.

For limits on file size for .dar see file size limit above.

Download the script’s ledger parties from Daml Hub

Next, add the ledger parties from your script to your ledger in the Identities view. All this is doing is initializing parties, so there will be no contracts yet.

Screenshot Placeholder

Now, download these parties and their access tokens to use as inputs to your script. Daml Hub produces a participants.json for you in the Ledger Settings tab.

Screenshot Placeholder

Add the participants.json file to your script project.

Initialize ledger inputs

As the final step, create a file named ledger-parties.json in your script project.

The json here must be formatted [party_name] : value, which is the reverse mapping of the party_participants field in participants.json. Here is an example of the contents of ledger-parties.json:

{
  "intern": "ledger-party-2b645725-41d2-441d-b259-fb8dab0aad11",
  "analyst": "ledger-party-0423c1fe-2287-4bd0-a20b-9624b4005d13",
  "associate": "ledger-party-581594c7-bd48-489b-a62d-9ec79c214cdf",
  "vicePresident": "ledger-party-964ef06c-e7f3-41fe-8517-426797944b00",
  "seniorVP": "ledger-party-0ae3d20a-b418-4b10-a20c-6f9ee0410233",
  "managingDirector": "ledger-party-dab32e1e-c472-4930-96e5-f105c3303cb5"
}

Run the script against your ledger

Now that you have all the inputs for our Daml Script, we need to run it against the ledger with the following command:

daml script --participant-config participants.json --json-api --dar <Name of .dar that contains the Daml Script> --script-name <Name of Daml Script function> --input-file ledger-parties.json

The command consists of our participant-config being the participants.json file, the json-api tag because Daml Hub uses the JSON API, the name of the dar that contains the Daml Script which in the example would be .daml/dist/bootstrap-script1-0.0.1.dar, the name of the script function which in the example would be Setup:initialize, and the input file ledger-parties.json.

After running this command, go back to your Daml Hub ledger, and you will see the contracts created by the Daml script bootstrap process.

For more details on Daml Script, visit the Daml docs .