daml-analyzer

A Static analysis tool for inspecting cross-package interactions in compiled Daml packages (.dar files).

Highlights tab showing an overview of all interactions and choices.

What it does

Given a compiled Daml package, daml-analyzer reports all cross-package interaction the code performs against contracts or interfaces defined in other packages — Create, Exercise, Fetch, ExerciseInterface, ImplementsInterface, and so on. The tool tracks the caller choice that triggered it, the target package, module, template/interface and choice it reaches, whether the choice is consuming, and the source file:line:col (when available). The output is a JSON, a Graphviz DOT, and an HTML report.

The HTML report bundles the viewer with the JSON already embedded. You can open it in any browser. See viewer/README.md for the standalone viewer.

Who this is for

Developers building protocols for Canton and auditors reviewing Canton deployments.

Status

This project is under active development.

We have successfully run daml-analyzer on the full Splice corpus (165 DARs) and all the files in the utilities (53 DARs).

We would love to hear from users and get feedback from the community.

Build

sbt compile           
sbt assembly # makes jar

Run

There are 3 ways to run the tool:

1. Download the JAR (recommended for most users). Every release on the Releases page also has a daml-analyzer-<version>.jar and a .sha256 checksum. It requires Java 21+.

   curl -LO https://github.com/Certora/daml-analyzer/releases/download/v0.1.4/daml-analyzer-0.1.4.jar
   java -Xss4m -jar daml-analyzer-0.1.4.jar foo.dar -o out/

   The JAR is large, so we recommend fetching it in a setup step (CI job, npm script, Makefile target) rather than committing it to your repository.

2. dpm certora-analyze foo.dar -o out/: as a DPM component, for projects on DPM 3.5+ that opt in to components in daml.yaml. See dpm-component/README.md for more.

3. sbt "run foo.dar -o out/": for developing on this repo. sbt assembly builds the same JAR as the release. You can find it in target/scala-2.13/.

See the various ways to run below. You can either run sbt "run ..." or java -jar ....

Command	Output
sbt "run dars-dir/ -o out/"	For each *.dar directly in dars-dir (not recursive): <name>.{json,dot} in out/ and one aggregated out/report.html for all DARs
sbt "run a.dar b.dar more-dars/ -o out/"	Any mix of DARs and directories, analyzed together; same outputs as the row above
sbt "run foo.dar -o out/"	Writes out/foo.{json,dot,html} (default -f all)
sbt "run foo.dar -f html"	HTML report to stdout
sbt "run foo.dar -f json"	JSON to stdout
sbt "run foo.dar -f dot"	DOT to stdout
sbt "run foo.dar -f html -o out/"	Only out/foo.html
sbt "run dars-dir/"	Error because batch mode (more than one DAR, or a directory) requires -o
sbt "run --help"	Print usage

NOTE: if two DARs have the same file name, e.g. c/same.dar and e/same.dar, their outputs are named c_same.{json,dot} and e_same.{json,dot}, and the report shows their paths if they hold the same package and version.

NOTE: if batch mode finds only one DAR (e.g. a directory with a single DAR in it), the report is out/<name>.html, not out/report.html.

Multi-package projects. In a multi-package project, dpm build writes each package's DAR into that package's own .daml/dist/ directory, e.g. token/.daml/dist/token-1.0.0.dar and vault/.daml/dist/vault-1.0.0.dar. The analyzer does not search for DARs, so you must list them on the command line. Analyzing them in one call is what produces the single merged out/report.html for the whole project:

# name each package's DAR. A mix of DAR files and directories works too.
java -Xss4m -jar daml-analyzer-0.1.4.jar token/.daml/dist/*.dar vault/.daml/dist/*.dar -o out/

If you make the JAR file, run like so:

java -jar target/scala-2.13/daml-analyzer-0.1.4.jar foo.dar -o out/

NOTE: you can pass -Xss4m to the java ... command to increase the JVM thread stack. sbt run and sbt test already uses this flag (build.sbt).

Visualize the results

Two options depending on the output format you produced.

HTML report (recommended)

sbt "run foo.dar -o out/"
open out/foo.html                     # single DAR
open out/report.html                  # batch mode: all DARs in one aggregated report

As a concrete example, run daml-analyzer on the Splice dar files here:

1. clone the splice repo
2. run sbt assembly
3. run sbt "run path/to/splice/dars -o path/to/out/dir"
4. open path/to/out/dir/report.html

Manual JSON upload (fallback)

If you produced JSON without HTML (-f json), open viewer/index.html in any browser and pick the .json files with the file input. See viewer/README.md.

Summary table: rows are target packages, columns are interaction-type counts. Click a row to see findings grouped by the choice that triggered them.

Diff tab: comparing two versions of the same package. Edges are green for added interactions, red dashed for removed, amber for changed, and gray for unchanged.

DOT → PNG with Graphviz

dot -Tpng path/to/foo.dot -o path/to/foo.png

Test

sbt test

AI Acknowledgement

Claude Code, Codex, Gemini, Copilot, and ChatGPT were used for assistance at various points. All suggestions were reviewed by the authors.