TL;DR: dpm can now resolve Daml dependencies from prebuilt .dar files hosted in Git repositories.
- One line in
daml.yamlreplaces the folder of copied DARs, the download script, and the README asking you to “keep these in sync”. dpmfetches the file, caches it, pins branches and tags to an exact commit, and handsdamlca 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 assplice-amulet-0.1.17.darnext tosplice-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/orsplice-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.darsays 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.pathis 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
--checkconfirms 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:
| Form | Example |
|---|---|
| File at a branch, tag or commit | git:github.com/org/repo#<ref>?path=dars/foo.dar |
| Alias under artifact-locations | "@alias#<ref>?path=dars/foo.dar" |
| One GitHub release asset | git:github.com/org/repo?release=v1.0.0&asset=foo.dar |
| Every .dar in a GitHub release | git:github.com/org/repo?release=v1.0.0 |
| A browser link, added from the CLI | dpm 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.
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 buildanddpm testwork exactly as before, now with Git-hosted DARs included.
Limitations and good practice
- Use browser URLs with
dpm add dar, not indaml.yaml. Dependencies in the file must begit:lines. A rawhttps://entry fails withhttp dependencies not yet supported. dependenciesis stricter thandata-dependencies. It needs the same SDK version and LF target across the dependency closure. Most Splice DARs belong underdata-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.
dpmfetches 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.
