dpm trace

DPM component POC for participant-scoped Canton transaction visualization.

It demonstrates the proposal surface:

• trace: inspect a successful transaction by update id.
• trace --command-id: inspect a failed submission through completion data.
• open: reopen an exported trace artifact.
• prepare: prepare a command without committing it.
• compare: compare prepared transactions, successful transactions, or completions.

Setup

.venv/bin/python -m pip install -e .
./scripts/install-local-dpm-trace.sh

Optional local config:

cp .dpm-trace.example.json .dpm-trace.json

Example config:

{
  "ledgerUrl": "http://localhost:<json-ledger-api-port>",
  "readAs": "<party-id>",
  "darPaths": ["./path/to/app.dar"]
}

Trace

Inspect a successful transaction:

dpm trace <update-id>

With explicit participant context:

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

The bearer token can also be passed with --token, DPM_TRACE_TOKEN, or DPM_TRACE_TOKEN_FILE.

Inspect a failed submission by command id:

dpm trace --command-id <command-id> \
  --submitter http://localhost:<json-ledger-api-port> \
  --act-as '<party-id>' \
  --log-file /tmp/canton-participant.log \
  --access-token-file ./token.txt

Or inspect captured completion JSON:

dpm trace --completion-file completion.json \
  --log-file /tmp/canton-participant.log

With local Daml sources available, failed completions can point back to the contract line and column:

dpm trace --completion-file completion.json \
  --daml-yaml <path-to-daml-project>/daml.yaml

Export a trace artifact:

dpm trace <update-id> --export trace.json

Open the interactive transaction visualizer:

dpm trace <update-id> --visualize

Open

Reopen an exported trace artifact:

dpm trace open trace.json
dpm trace open trace.json --visualize

Prepare

Prepare a command without committing it:

dpm trace prepare \
  --submitter http://localhost:<json-ledger-api-port> \
  --act-as '<party-id>' \
  --template '<package-id>:Counter:Counter' \
  --arg owner='<party-id>' \
  --arg count=0 \
  --export prepared.json

Or pass a command file:

dpm trace prepare \
  --submitter http://localhost:<json-ledger-api-port> \
  --act-as '<party-id>' \
  --commands commands.json \
  --export prepared.json

prepare calls Canton's non-committing prepare API. It does not submit to the ledger.

Compare

Compare a prepared transaction with a successful transaction:

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

Compare a prepared transaction with a failed submission:

dpm trace compare \
  --prepared prepared.json \
  --command-id <command-id> \
  --submitter http://localhost:<json-ledger-api-port> \
  --act-as '<party-id>' \
  --log-file /tmp/canton-participant.log

Compare two successful transactions:

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

Compare a prepared transaction with a captured completion JSON:

dpm trace compare \
  --prepared prepared.json \
  --completion-file completion.json

Failed submission source demo

This fixture shows the CI-style path: consume a captured completion/error JSON and resolve it against local Daml sources.

dpm trace --completion-file examples/failed-with-source.completion.json \
  --daml-yaml <path-to-daml-project>/daml.yaml

The output includes a Source diagnostics block with file:line:column and a caret under the matching Daml code.

Notes

• Output is participant-scoped. It is not a global Canton transaction.
• Failed submissions may not have an update id. In that case comparison uses completion/error data.
• Source diagnostics use local source/project metadata when available. Compiler debug-info generation is out of scope for this PoC.