Skip to main content

Bringing Git-based DAR dependencies to Canton's package manager

· Moonsong Labs

TL;DR: dpm can now resolve Daml dependencies from prebuilt .dar files hosted in Git repositories.

  • One line in daml.yaml replaces the folder of copied DARs, the download script, and the README asking you to “keep these in sync”.
  • dpm fetches the file, caches it, pins branches and tags to an exact commit, and hands damlc a local path.
  • Builds behave the same on every laptop and in CI.

The problem: vendored DARs everywhere

Before this change, dpm could resolve three kinds of dependencies: packages shipped with the SDK (daml-prim, daml-stdlib, daml-script), packages published to an OCI registry, and DAR files on the local disk. Many of the DARs Canton applications rely on fit none of the first two. The clearest case is the Splice packages: the token standard APIs, Amulet, the wallet, and the utility libraries. Splice publishes them as prebuilt files under daml/dars/ in its repository.

So the ecosystem settled on a workaround: copy the DARs into your own repository and point data-dependencies at them with relative paths. Some prominent projects that do this:

  • BitSafe’s Decentralization Manager commits 17 prebuilt DARs under daml/dars/, mostly Splice and Utility packages. Some are duplicated across versions, such as splice-amulet-0.1.17.dar next to splice-amulet-0.1.19.dar. A single package, governance-token-custody, references seven of them:

    data-dependencies:
      - ../governance-action-v1/.daml/dist/governance-action-v1-0.1.0.dar
      - ../dars/splice-api-token-holding-v1-1.0.0.dar
      - ../dars/splice-api-token-metadata-v1-1.0.0.dar
      - ../dars/splice-api-token-transfer-instruction-v1-1.0.0.dar
      - ../dars/splice-util-0.1.4.dar
      - ../dars/splice-wallet-0.1.18.dar
      - ../dars/utility-registry-app-v0-0.7.0.dar
      - ../dars/utility-registry-v0-0.6.0.dar
    
  • Digital Asset’s own Canton Network Quickstart vendors Splice DARs under quickstart/daml/dars/. A README there tells readers where the files came from and warns them to “ensure that you track SDK version updates”.

  • OpenZeppelin’s canton-stablecoin, ChainSafe’s canton-erc20, and RedStone’s Canton connector all follow the same pattern: a local dars/ or splice-dars/ folder holding copies of the Splice token standard APIs.

This works, but it has a cost:

  • The source is lost. A file called splice-util-0.1.4.dar says nothing about which Splice commit or release line produced it. A README is the only record, and it drifts.
  • Upgrades are manual. Moving to a new Splice release means finding the right files upstream, downloading them, replacing the copies, and updating every relative path that references them.
  • Binaries pile up in Git history. Every upgrade adds another set of DARs to the repository, and old versions often stay around “just in case”.
  • The work is repeated in every project. Each team writes the same scripts and the same “where these came from” notes.

The solution: one line change in your daml.yaml

With Git dependencies, the vendored copy and its relative path become a reference to the source:

data-dependencies:
  - git:github.com/canton-network/splice#main?path=daml/dars/splice-api-token-holding-v1-1.0.0.dar
  - git:github.com/canton-network/splice#main?path=daml/dars/splice-api-token-metadata-v1-1.0.0.dar
  - git:github.com/canton-network/splice#main?path=daml/dars/splice-util-0.1.4.dar

The format is git:<host>/<owner>/<repo>#<ref>?path=<file>.dar:

  • <host>/<owner>/<repo> is any Git repository reachable over HTTPS, such as GitHub, GitLab, or a self-hosted server.
  • <ref> is a branch, a tag, or a commit SHA.
  • path is the location of the DAR inside the repository.

Git DARs work under both dependencies and data-dependencies, with the same meaning as today. Local DARs, SDK packages and OCI dependencies keep working alongside them, so a project can migrate one line at a time.

If you reference the same repository many times, define it once as an alias under artifact-locations:

artifact-locations:
  "@splice":
    url: "git:github.com/canton-network/splice"

data-dependencies:
  - "@splice#main?path=daml/dars/splice-api-token-holding-v1-1.0.0.dar"
  - "@splice#main?path=daml/dars/splice-util-0.1.4.dar"

Try for yourself

The dpm-git-links-demo project is a small Daml app built as an example of this feature. Its daml.yaml declares two Git DARs, and the build fails if either one does not resolve, so the project checks itself:

dependencies:
  - git:github.com/Moonsong-Labs/test-daml-hello#master?path=dist/test-daml-hello-sdk-3.7.1-lf-2.3.dar

data-dependencies:
  - git:github.com/canton-network/splice#release-line-0.6.8?path=daml/dars/splice-amulet-0.1.19.dar

All you need is a dpm version 1.1.0 or later (it ships with Daml SDK 3.7; the demo uses SDK 3.7.1), a Java 17 runtime for dpm test, and network access to github.com for the first fetch.

1. Install

dpm install package

dpm makes a shallow clone of each repository over HTTPS, takes the requested DAR and stores it under ~/.dpm/cache. Later installs reuse the cache and do not touch the network.

2. Pinning: movable refs become commits

Branches and tags move, and builds should not. On install, dpm resolves every branch or tag to the commit it currently points at and rewrites the line in daml.yaml:

 data-dependencies:
-  - git:github.com/canton-network/splice#release-line-0.6.8?path=daml/dars/splice-amulet-0.1.19.dar
+  - git:github.com/canton-network/splice#a412530c82570bccab384052638a08fdbf3ad6e4?path=daml/dars/splice-amulet-0.1.19.dar

This rewrite is the point of the feature, not a side effect. Commit the pinned daml.yaml and every teammate and CI job builds against exactly the same bytes. The dependency is reproducible, and its origin is written in the file itself. If an artifact-locations alias was used, pinning expands it to the full git: line.

This behaviour matches OCI dependencies, where the line is also rewritten with the resolved digest (@sha256:…).

To upgrade, point the line back at a branch or tag (for example main, or a newer tag) and run dpm install package again. The diff in review shows exactly which commit you moved from and to.

3. Build and test as usual

dpm build
dpm test

Nothing changes here. dpm passes the cached local DAR paths to damlc through the normal resolution step, and damlc never makes a network request.

4. Gate CI on it

dpm update --check
  • --check confirms that the project is ready to build: every repository file is pinned to a commit and present in the cache, and every release asset has been downloaded. It never modifies the project, which makes it a useful pre-build step in CI that catches unpinned refs before they are merged.

Other ways to declare a dependency

The demo’s samples/ folder covers every supported form:

FormExample
File at a branch, tag or commitgit:github.com/org/repo#<ref>?path=dars/foo.dar
Alias under artifact-locations"@alias#<ref>?path=dars/foo.dar"
One GitHub release assetgit:github.com/org/repo?release=v1.0.0&asset=foo.dar
Every .dar in a GitHub releasegit:github.com/org/repo?release=v1.0.0
A browser link, added from the CLIdpm add dar https://github.com/org/repo/blob/main/dars/foo.dar --data-dependencies
Structured mapping (SDK 3.6 or later)git: with url, ref and path

The last form is the quickest way to start: copy the link from the GitHub file browser view, and dpm add dar rewrites it into the canonical git: line, fetches it and pins it.

How it works under the hood

Git DARs reuse the architecture that already exists for OCI dependencies. During dpm install package or dpm update, dpm parses each git: line, makes a shallow clone of the repository at the given ref (only that commit, with no history), and caches the requested DAR under ~/.dpm/cache/git/<host>/<owner>/<repo>/.... Branches and tags are pinned to commit SHAs in daml.yaml. During build, test and IDE workflows, dpm gives damlc the resolved local paths, exactly as it does for OCI artifacts. The compiler is unchanged and stays offline.

Concurrent installs that share the same cache are safe, because fetches into a cached repository are locked and files are written atomically.

Read: Technical design page.

What this gives Canton/Daml teams

  • No more vendored binaries. dars/ folders and their copy scripts can go. The repository holds your code, not other people’s builds.
  • Dependency origin in plain sight. Every external DAR states its repository, its commit and its path, right in daml.yaml.
  • Reproducible builds. Pinned commits mean the same bytes on every machine and in every CI run.
  • Reviewable upgrades. Moving to a new Splice release becomes a one-line diff per dependency, not a binary swap.
  • One workflow. dpm install package, dpm build and dpm test work exactly as before, now with Git-hosted DARs included.

Limitations and good practice

  • Use browser URLs with dpm add dar, not in daml.yaml. Dependencies in the file must be git: lines. A raw https:// entry fails with http dependencies not yet supported.
  • dependencies is stricter than data-dependencies. It needs the same SDK version and LF target across the dependency closure. Most Splice DARs belong under data-dependencies, which is also how existing projects consume them.
  • Release assets are GitHub-only. On the other hand, files inside a repository work on any HTTPS Git host. Note that Splice publishes its DARs in the repository tree, not as release assets, so use ?path= for Splice.
  • To re-resolve from scratch, delete .daml/. For a cold cache, also delete ~/.dpm/cache/git.
  • Public repositories only. dpm fetches over HTTPS without credentials, so the repository must be public. SSH URLs and private repositories are not supported.

Full documentation is in the official Canton docs, under Git Dars and in the Canton 3.7.0 release notes (https://docs.canton.network/global-synchronizer/release-notes/canton-releases/3-7-0). The demo README covers every declaration form with its expected output, and the technical design page has the full design.

Contributing to the Canton ecosystem

Moonsong Labs built Git-based DAR dependencies for dpm with support from the Canton Development Fund.

Moonsong is a Canton Foundation member and a service provider on the Canton Network. Our dedicated Canton practice includes Daml-certified engineers with experience building for regulated finance.

GitHub Repo: Daml Package Manager Repo

Moonsong Labs Joins Canton Ecosystem

All articles

Build what’s next. Together.

Partner with a team that understands the technology and the institutional environment it needs to operate in.

Let’s Talk