Canton Smart Contract Upgrades (SCU)

Overview

Canton apps evolve, but contracts are immutable and distributed across organizations' validators — you can't run a single migration script, and you can't force everyone to upgrade at once. Smart Contract Upgrade (SCU) solves this by letting multiple versions of a package coexist on the ledger with controlled cross-version rules. SCU has rules you must follow.

Package versioning is the foundation

Every package has a name and version in daml.yaml. Upload a new version (same name, higher version) and both versions live on the ledger simultaneously. Existing contracts stay associated with the version that created them but can be read and exercised through the newer version's code when compatibility permits — enabling zero-downtime upgrades without pre-migrating old contracts.

What's allowed vs what breaks

Use SCU when:

• Adding optional fields to existing templates
• Adding new choices to existing templates
• You need existing contracts to work with new code without migration / want zero downtime

Use a new template when:

• The change is fundamentally incompatible — removing fields, changing types
• The new workflow is logically distinct, or you want clean old/new separation

Validate compatibility with dpm upgrade-check (checks upgrade validity between package versions). See canton-daml-packaging for package mechanics and naming (m6-package-naming).