Package and contract operations

Goal

Distribute a DAR to every required Canton participant, verify package parity, and deploy governance contracts through the multi-party contracts workflow.

Audience

This guide is for Decentralization Manager operators who administer a connected peer set and have access to each participant's Canton Admin API and Ledger API.

Before you start

Confirm all of the following:

• Every operator runs a Decentralization Manager instance and has configured the other participants as peers.
• The coordinator can reach each peer over the Noise port.
• Every peer has accepted the planned maintenance window and package source.
• The Decentralized Party already exists.
• The coordinator knows each participant ID and member party ID.
• The Decentralization Manager instance can use Canton's PackageService and InteractiveSubmissionService.
• Authentication is configured. Do not use insecure mode in a shared or production environment.
• No other workflow is running on the participating nodes. The reviewed implementation supports one workflow at a time per node.
• At least two participants are available for DAR distribution. The reviewed contracts workflow requires at least three participants.

<aside> ⚠️

Distributing a DAR installs executable package code on every accepting participant. Verify the artifact through your approved software supply-chain process before you start. The reviewed repository does not establish checksum or signature enforcement as a package-acceptance control.

</aside>

Choose the correct operation

Task	Operation	Use
Upload a DAR to the current node only	POST /dars/upload	Local development or controlled diagnosis. Do not use it to establish production package parity.
Upload a DAR to the coordinator and selected peers	POST /dars/distribute	Normal multi-party package distribution.
Upload DARs and create contracts in one coordinated workflow	POST /contracts or Deploy Contracts in the UI	Multi-party preparation, signing, and execution of contract creation.

Distribute a DAR

1. Prepare the request

Set the coordinator URL, the DAR path, and the peer participant IDs. The peer_ids array must not be empty for POST /dars/distribute.

export DECPM_URL="<https://manager.example.com>"
export DAR_PATH="./governance-core.dar"
DAR_DATA=$(base64 < "$DAR_PATH" | tr -d '\n')

Keep the bearer token outside shell history and logs. Add your approved authorization header to each request when authentication is enabled.

2. Start distribution

curl --fail-with-body -X POST "$DECPM_URL/dars/distribute" \
  -H 'Content-Type: application/json' \
  -d "{
    \"dar_files\": [
      {
        \"filename\": \"$(basename "$DAR_PATH")\",
        \"data\": \"$DAR_DATA\"
      }
    ],
    \"peer_ids\": [
      \"participant-2::1220...\",
      \"participant-3::1220...\"
    ]
  }"

The coordinator creates a DAR distribution workflow and sends an invitation to each selected peer.

3. Accept invitations on every peer

On each peer, open the pending invitations view and inspect the workflow before accepting it. Accept only when the coordinator, participants, package filename, source, and maintenance window match the approved change.

The repository exposes invitation endpoints, but this guide does not treat their payloads as a supported public contract. Use the reviewed UI path unless the versioned API reference documents the invitation endpoints.

4. Monitor the workflow

Poll the coordinator until the workflow reaches a terminal state:

curl --fail-with-body "$DECPM_URL/dars/distribute/status"

The reviewed workflow has three stages:

1. Wait for the invited peers.
2. Upload the DAR to each participant through Canton's PackageService.UploadDarFile.
3. Complete and disconnect the peers.

Do not start contract deployment while the distribution workflow is waiting, running, failed, or cancelled.

5. Verify package parity

Check the coordinator's vetted packages:

curl --fail-with-body "$DECPM_URL/packages/vetted"

Then compare packages across peers:

curl --fail-with-body "$DECPM_URL/packages/compare-peers"

The peer-comparison route is admin-only in the reviewed implementation. Repeat the vetted-package check directly on every node if the comparison route is unavailable.

Expected outcome: every required participant reports the same intended package ID before any contract is created.

Deploy governance contracts

The contracts workflow creates contracts through Canton's interactive submission service. It does not replace the propose, confirm, execute lifecycle for later governed actions.

1. Confirm prerequisites

Before deployment:

• Verify package parity on every participant.
• Confirm the contract template and field order against the exact DAR version.
• Confirm the decentralized party, member parties, participant IDs, operator party, threshold, and confirmation timeout.
• Record the intended package ID and template identifier in the change record.

2. Start from the UI

From the Decentralized Party card:

1. Select Deploy Contracts.
2. Add the approved DARs if they are not already distributed.
3. Add each contract definition, including package, module, entity, and ordered field values.
4. Review the participants and operator party.
5. Start the workflow.

UI labels and DAR reuse behavior can vary by release. Verify the package state before deciding whether to upload again.

3. Start through the API

The following example deploys one GovernanceRules contract. Replace every placeholder with values from the target environment and package version.

curl --fail-with-body -X POST "$DECPM_URL/contracts" \
  -H 'Content-Type: application/json' \
  -d '{
    "decentralized_party_id": "governed-app::1220...",
    "participant_ids": [
      "participant-1::1220...",
      "participant-2::1220...",
      "participant-3::1220..."
    ],
    "participant_parties": [
      "member-1::1220...",
      "member-2::1220...",
      "member-3::1220..."
    ],
    "operator_party": "operator::1220...",
    "contracts": [
      {
        "id": "governance-rules",
        "name": "GovernanceRules",
        "package_id": "#governance-core-<version>",
        "module_name": "Governance.Rules",
        "entity_name": "GovernanceRules",
        "fields": [
          { "type": "decentralized_party" },
          {
            "type": "party_set",
            "parties": [
              "member-1::1220...",
              "member-2::1220...",
              "member-3::1220..."
            ]
          },
          { "type": "int64", "value": 2 },
          { "type": "rel_time", "microseconds": 1800000000 },
          { "type": "none" }
        ]
      }
    ]
  }'

For GovernanceRules, all five fields are required and must remain in template order. Use party_set for a Daml Set Party. Do not substitute attestors_set.

4. Accept the contracts invitation

Every selected peer reviews and accepts the contracts workflow. Acceptance authorizes that peer to upload the DAR locally and participate in the prepared submission.

5. Monitor deployment

curl --fail-with-body "$DECPM_URL/contracts/status"

The reviewed workflow performs these operations:

1. Wait for all invited peers.
2. Upload DARs to every participant.
3. Prepare contract-creation submissions on the coordinator.
4. Collect signatures from every participating node.
5. Execute the signed submissions on Canton.
6. Complete and disconnect the peers.

6. Verify the result

Query governance state for the Decentralized Party:

curl --fail-with-body \
  "$DECPM_URL/governance/state?party_id=governed-app::1220..."

You can also query the created template directly:

curl --fail-with-body \
  "$DECPM_URL/contracts/query?party_id=governed-app::1220...&package_id=%23governance-core-<version>&module_name=Governance.Rules&entity_name=GovernanceRules&interface=false"

Record the workflow instance, package ID, created contract ID, participants, template identifier, and completion time.

Expected outcome: the contract is active and visible to the intended parties, and every required participant retains package parity.

Failure handling

A peer does not receive an invitation

• Confirm mutual peer records and Noise reachability.
• Confirm the peer is not busy with another workflow.
• Confirm the peer's public address and Noise key have not changed.
• Do not bypass the peer by switching to local-only upload for a production deployment.

A DAR upload succeeds on some nodes and fails on others

Stop before contract creation. Package upload is a local Canton operation, so a failed workflow can leave partial package state.

1. Query GET /dars/distribute/status.
2. Query GET /packages/vetted on every participant.
3. Resolve the failing node's Canton Admin API, authorization, storage, or package error.
4. Recompare all participants.
5. Retry only after confirming that the operation is safe for the observed workflow state.

The reviewed implementation does not document automatic rollback or endpoint idempotency.

Contract preparation or execution times out

Do not submit the same deployment again immediately.

1. Query GET /contracts/status.
2. Query GET /workflows and inspect the contracts workflow instance.
3. Query the target template to determine whether the contract already exists.
4. Capture sanitized coordinator and peer logs.
5. Retry, cancel, or dismiss only after you know whether Canton accepted the interactive submission.

If the prepared or executed submission state remains ambiguous, stop and escalate rather than retrying.

The coordinator becomes unavailable

The reviewed architecture treats the coordinator as the single point of progress for the active workflow. Peers retry a bounded number of times and then abort. Restore the coordinator, inspect workflow and Canton state, and confirm the recovery path before retrying.

A peer declines or rejects the workflow

Treat the workflow as not approved. Resolve the change request with that operator. Do not reissue the workflow until the peer has approved the artifact and contract definition.

Upgrade and migration boundary

Uploading a new DAR does not migrate active contracts. Daml package versions can coexist, and existing proposals remain bound to the package version that created them.

Before deploying a replacement version:

1. Identify active contracts and in-flight proposals on the old package.
2. Decide whether to drain, cancel, or migrate them.
3. Verify compatibility with the current Decentralization Manager and Canton versions.
4. Publish a separate migration and rollback plan.
5. Distribute and verify the new DAR before creating replacement contracts.

Do not silently change the semantics of an existing template version.

Operational record

For each run, retain:

• Approved source and immutable artifact reference.
• Artifact checksum or signature produced by the external approval process.
• Decentralization Manager version or commit.
• Canton version.
• Coordinator and participant IDs.
• Package filename and package ID.
• Workflow instance and terminal state.
• Contract package, module, entity, and contract ID.
• Sanitized error records and remediation notes.

Do not store access tokens, client secrets, Noise private keys, or database encryption keys in the change record.

Technical sources

• Repository at reviewed commit
• Architecture and workflow definitions
• Operator guide
• Custom Daml template and contracts workflow guide
• README and API route index

Next actions

• Use Decentralization Manager governance lifecycle to propose, confirm, and execute the first governed action.
• Use Decentralization Manager backup, recovery, and mesh upgrades when an operation does not reach a terminal state.
• Review Decentralization Manager compatibility, releases, and troubleshooting and create a version-specific migration plan before replacing active contract packages.

Related pages

• Decentralization Manager governance lifecycle
• Decentralization Manager module selection and custom Daml
• Decentralization Manager backup, recovery, and mesh upgrades
• Decentralization Manager API and workflow reference
• Decentralization Manager compatibility, releases, and troubleshooting

Next step

👉 Exercise the deployed contracts: Decentralization Manager governance lifecycle.