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
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.