A release moves as one: the engine, the API contract and the Daml packages. Most releases change only what runs off the ledger; one that moves a package id is a vetting event, which every node that uses the package takes part in.

​
What a release carries

A DAR keeps its package’s own name and version, which move independently of the release’s. The release notes say when a release moves a package id or changes the DA Registry release the packages are built against.

​
The API contract

Within /v1, a release only adds: a route, an optional request field, a response field, a problem slug, an enum value in a response. A client ignores what it does not know, and treats an unknown enum value or slug as a case of its own. Removing or renaming anything, changing a type, a meaning or a default, or tightening what a request accepts ships as /v2, or behind a deprecation window of at least one minor release that the release notes name.

​
The engine’s database

The engine migrates its database forward when it starts. A migration, once applied to a database that persists, is never edited: every schema change ships as a new migration, and the engine refuses to start when a migration it carries differs from the one the database applied. Never start an older engine on a database a newer one has migrated.

​
Package versions and vetting

Every asset runs on the same packages. Recording an asset deploys no contract, so the package you review is the one that runs every asset. A package id is the hash of the compiled package. It moves when the package’s Daml changes, or when an archive it is built against changes: the token standard’s, or the DA Registry’s. Each build checks every production package’s id against the recorded one, so an id moves only by a deliberate change, which the release notes name. A moved id is a vetting event. Canton runs a package only on the nodes that have vetted it. Compare package-ids.txt between the release you run and the one you take:
  • If the ids are the same, nothing on the ledger changes, and no node has anything to vet.
  • If an id moved, every node that uses the package vets the new one before it acts on it. Until a node has, the engine refuses an act that node takes part in with 409 package-not-vetted, naming the package and the party; the same request goes through once the node has vetted it.
Canton keeps one package id per name and version. Once a version of a package is on a network, a change to it ships under a new version. Digital Asset vets each Registry release for a support window, then unvets it. A deployment follows DA’s releases rather than choosing them: when NodeAsset moves to a new DA release, DA’s new packages go on every node first, and NodeAsset’s ids move with it.

​
Verify a release

Every DAR is published without its Daml source. Each counterparty verifies the DARs it vets the same way before uploading them.

​
The order of an upgrade

1

Read the release notes

Verify the assets, and compare package-ids.txt with the release you run.
2

If the DA Registry release moved

DA’s new packages go on every Canton node first.
3

If a package id moved

Every other party vets the new packages on its own node, and your Canton node uploads and vets them. Each is that node owner’s own decision.
4

Replace the engine

Back up the engine’s database (Backup and recovery), stop the engine, replace the jar and start it. It migrates its database as it starts.
5

Check it

Settle the smallest transaction end to end, and read GET /v1/health and GET /v1/system.
Related: Install · Backup and recovery · Downloads