v0.1.2

dpm trace is a DPM component for inspecting Canton transactions.

It reads a committed update from a participant's JSON Ledger API and renders it
as an event tree: creates, exercises, archives and reassignments, with the
contract ids, parties, choice arguments, return values and payloads that
participant can see.

New in this release: the interactive visualizer

--visualize opens a session over one transaction instead of printing it and
exiting. It is for the questions a static tree answers badly: which events
involved a party, what a forty-field contract actually contains, and what the
transaction left behind.

./dpm-trace open examples/exercise-child-create.trace.json --visualize

• Move around. n/p step, j <n> jumps, tree prints the whole
  transaction with the cursor marked.
• Fold a deep tree. tree <depth> collapses below a level, and
  collapse/expand work on one subtree. Hidden counts are transitive -
  3 events hidden means three lines you cannot see, not three direct
  children - and each line names the command that reopens it.
• Find things. filter narrows what n and p visit, across nine fields:
  template, choice, party, contract, kind, package, id,
  payload and synchronizer. find jumps to the next match without
  changing the filter, and matches lists what the filter selects. Matching is
  substring and case-insensitive, because the value you have to hand is usually
  partial - the tail of a contract id from a log, a party without its
  fingerprint.
• Read large values. A contract with forty fields would print seventy
  lines, so values are cut and the cut names its own way out: payload
  expands, payload <text> prints only the matching lines.
• See what changed. diff lists the contracts created and archived. The
  archived side is derived, because a transaction tree carries no archived
  event - the Ledger API reports an archive as consuming: true on the
  exercise. A contract created and destroyed by the same transaction is marked
  ~ transient.
• Know what you are looking at. The prompt names the parties you are
  reading as, the header carries the projection note, and diff restates it in
  terms of what you cannot see.

vars prints the current event in full, s shows the Daml behind it when a
daml-debug-info/v1 file is supplied, and help lists the session commands.

docs/visualizer.md
covers the session in full, including why a projection is not a global record.

Install

Download the archive for your platform below and unpack it. The binary is
self-contained and sits at the root of the archive:

tar xzf dpm-trace_0.1.2_<os>_<arch>.tar.gz
./dpm-trace --version

That is enough to use it. Optionally, register it as a DPM component so it runs
as dpm trace instead of ./dpm-trace:

./dpm-trace install-plugin

Registration requires DPM with a Daml SDK installed. If you have neither:

curl https://get.digitalasset.com/install/install.sh | sh   # installs dpm
dpm install 3.5.1                                           # installs an SDK

Otherwise keep using ./dpm-trace; it is the same binary.

Usage

An update id identifies a committed transaction on a participant, in the format
1220e77482b473bfff30d376bd853f0a71df7ab6d41cc3f060dc5456603493acd06c. Canton
returns one from each successful submission, so with no ledger yet, start with
the examples below - they need no update id and no participant.

./dpm-trace <update-id> \
  --submitter http://localhost:<json-ledger-api-port> \
  --read-as '<party-id>'

Remote participants take the same shape, with a bearer token from --token,
--token-file, or DPM_TRACE_TOKEN / DPM_TRACE_TOKEN_FILE. --export trace.json writes a portable artifact and ./dpm-trace open renders it again
with no ledger connection.

The archive ships five example traces covering all four event kinds, so the
output can be seen without a ledger at all:

./dpm-trace open examples/create.trace.json
./dpm-trace open examples/exercise-child-create.trace.json
./dpm-trace open examples/archive.trace.json
./dpm-trace open examples/unassign.trace.json
./dpm-trace open examples/assign.trace.json

Add --visualize to any of them to open the session instead.

Reproducing the examples against a local Canton needs DPM and a Java runtime —
dpm build builds the DAR, and the Canton jar comes with DPM. See
examples/README.md in the archive. The reassignment pair needs two
synchronizers, which the shipped config does not set up.

Notes

Output is one participant's projection, not a global view of the transaction.
It does not imply access to private data outside that participant's rights.
The same update read as a different party can legitimately contain fewer
events, and every rendering is labelled accordingly.

The macOS binaries are unsigned. If Gatekeeper refuses one, clear the
quarantine attribute: xattr -d com.apple.quarantine ./dpm-trace.

Verify a download against checksums.txt:

shasum -a 256 -c checksums.txt --ignore-missing