Extending Daml applications

Note: Cross-SDK extensions require Daml-LF 1.8 or newer. This is the default starting from SDK 1.0. For older releases add build-options: ["--target=1.8"] to your daml.yaml to select Daml-LF 1.8.

Consider the following simple Daml model for carbon certificates:

module CarbonV1 where

template CarbonCert
  with
    issuer : Party
    owner : Party
    carbon_metric_tons : Int
  where
    signatory issuer, owner

It contains two templates. The above template representing a carbon compensation certificate. And a second template to create the CarbonCert via a Propose-Accept workflow.

Now we want to extend this model to add trust labels for certificates by third parties. We don’t want to make any changes to the already deployed model. Changes to a Daml model will result in changed package ID’s for the contained templates. This means that if a Daml model is already deployed, the modified Daml code will not be able to reference contracts instantiated with the old package. To avoid this problem, it’s best to put extensions in a new package.

In our example we call the new package carbon-label and implement the label template like

module CarbonLabel where

import CarbonV1

template CarbonLabel
  with
    cert : ContractId CarbonCert
    labelOwner : Party
  where
    signatory labelOwner

The CarbonLabel template references the CarbonCert contract of the carbon-1.0.0 packages by contract ID. Hence, we need to import the CarbonV1 module and add the carbon-1.0.0 to the dependencies in the daml.yaml file. Because we want to be independent of the Daml SDK used for both packages, we import the carbon-1.0.0 package as data dependency

name: carbon-label
version: 1.0.0
dependencies:
  - daml-prim
  - daml-stdlib
data-dependencies:
  - path/to/carbon-1.0.0.dar

Deploying an extension is simple: just upload the new package to the ledger with the daml ledger upload-dar command. In our example the ledger runs on the localhost:

daml ledger upload-dar --ledger-port 6865 --ledger-host localhost ./daml/dist/carbon-label-1.0.0.dar

If instead of just extending a Daml model you want to modify an already deployed template of your Daml model, you need to perform an upgrade of your Daml application. This is the content of the next section.