> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/upgrades.md).

# Platform and Canton Network Upgrades

Upgrading the CAT-BM platform, and upgrading Canton Network protocol or validator components.

There are two independent upgrade tracks, and it helps to keep them separate.

<table><thead><tr><th width="230">Track</th><th width="200">Changes</th><th>Mechanism</th></tr></thead><tbody><tr><td><strong>CAT-BM Platform</strong></td><td>The operator, API, and UI</td><td><code>helm upgrade</code></td></tr><tr><td><strong>Canton Network</strong></td><td>The Canton participant, validator app, UIs, PQS, Wallet Gateway</td><td>Edit the <code>Validator</code> resource</td></tr></tbody></table>

You can upgrade either without the other, within a compatible range.

***

## 1. CAT-BM Platform Upgrades

```bash
helm upgrade catalyx-canton catalyx/catalyx-canton \
  -n <namespace> -f my-values.yaml
```

{% hint style="danger" %}
**Apply the CRDs first.** Helm never upgrades the resources in a chart's `crds/` directory. If a release changes the `Validator` or `Application` schema and you skip this, new fields will be silently pruned from resources you apply.

```bash
kubectl apply -f <chart>/crds
```

{% endhint %}

### What happens

The operator, API, and UI deployments are rolled. The UI runs multiple replicas by default and has a pod disruption budget, so it stays available. The operator and API run a single replica each — expect a brief interruption while they restart.

Once the new operator starts, it re-reconciles every existing validator. Validators are not restarted unless something they depend on has changed.

### Rolling back

```bash
helm rollback catalyx-canton -n <namespace>
```

{% hint style="warning" %}
Rolling back the chart does **not** roll back the CRDs, because Helm never managed them. If the upgrade introduced schema changes and you roll back the release, the newer CRDs remain in place. The older operator will ignore fields it does not understand.
{% endhint %}

***

## 2. Canton Network Version Upgrades

Canton networks upgrade on a schedule, and validators are expected to keep pace with the network's supported protocol versions.

A Canton version upgrade consists of updating validator software, applying any required migrations, validating the upgraded deployment, and, when applicable, participating in a coordinated network protocol upgrade.

The process is designed to maintain ledger continuity, preserve participant synchronization, and minimize disruption to running applications. Depending on the target release, an upgrade may involve only updating the validator software or may also require additional migration and network coordination activities.

***

### Types of Canton Upgrades

#### Version upgrade

Updates the validator software to a newer supported release. Each validator can do this independently, without network-wide coordination. This is what `spliceVersion` and the per-component `version` fields below cover.

Version upgrades typically involve:

* Updating the component image tag(s) — via `spliceVersion` or a pinned component `version`.
* Applying the change with `kubectl apply`, which the operator then rolls out.

During a standard version upgrade:

* Do not delete or recreate the validator's PostgreSQL databases.
* Do not modify `migrationId` unless explicitly required by the release.
* Do not modify onboarding or application secrets.
* Always review the release notes before upgrading.

#### Protocol upgrade

Changes the Canton Network protocol itself. These are coordinated across the network on a scheduled activation time. Modern Canton releases use the **Logical Synchronizer Upgrade (LSU)** mechanism — see below.

A protocol upgrade is coordinated by the network, not by CAT-BM — watch for announcements from your sponsoring Super Validator and the Canton Foundation rather than treating it like a version bump.

***

### Before you upgrade

{% stepper %}
{% step %}
**Confirm the target version is supported by the network**

Your validator's protocol version must remain compatible with the synchronizer. Check the network's published schedule; for the global Canton Network this is governed by the Global Synchronizer Foundation and published at the official [Super Validator Operations calendar](https://sv-cal.canton.foundation).
{% endstep %}

{% step %}
**Take an identity dump and confirm your database backups**

See [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps.md). Do this before every version change, not just major ones.
{% endstep %}

{% step %}
**Upgrade a non-production validator first**

Component versions are per validator, so a lower environment can run the new version while production stays put.
{% endstep %}

{% step %}
**Check the release notes**

See [Release Notes](/catalyx-blockchain-manager/canton-network/version-2.0/release-notes.md) for behaviour changes in the CatalyX release, and the Canton release notes for protocol changes.
{% endstep %}
{% endstepper %}

***

### Canton Network Version Upgrade Lifecycle

A Canton upgrade generally follows the same lifecycle, regardless of which track is involved:

1. **Release announcement** — the Canton Foundation (for network protocol changes) or IntellectEU (for CAT-BM platform releases) publishes release notes, upgrade instructions, and supported versions.
2. **Preparation** — review the release notes, schedule a maintenance window, and confirm backups and identity dumps are current. See [Before you upgrade](#before-you-upgrade). Testing the upgrade in DevNet or TestNet before upgrading Production is recommended.
3. **Upgrade** — apply the platform upgrade, the validator component upgrade, or both, depending on what changed.
4. **Execute Migration (when required)** — some releases require a domain migration, coordinated by the network. See [Domain migrations](#domain-migrations).
5. **Network protocol upgrade (when applicable)** — coordinated across the network using the Logical Synchronizer Upgrade (LSU) mechanism. See [Logical Synchronizer Upgrade (LSU)](#logical-synchronizer-upgrade-lsu).
6. **Post-upgrade validation** — confirm the validator is `Ready`, the participant is connected and synchronized, and applications start successfully.

***

### Upgrading validator components <a href="#upgrading-validator-components" id="upgrading-validator-components"></a>

Canton networks upgrade on a schedule, and validators are expected to keep pace with the network's supported protocol versions.

#### The simple case

If the validator uses `spec.network.spliceVersion`, one change upgrades the participant, validator app, and both UIs together:

```yaml
spec:
  network:
    spliceVersion: "0.6.13"
```

```bash
kubectl apply -f my-validator.yaml
```

The operator rolls each component in turn. Watch the validator's [Summary](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/summary.md) tab as components return to `Ready`.

#### Pinned components

A component with its own `version` ignores `spliceVersion`. Check for pinned versions before upgrading:

```bash
kubectl -n <namespace> get validator my-validator \
  -o jsonpath='{.spec.participant.version} {.spec.validator.version} {.spec.ui.wallet.version} {.spec.ui.cns.version}'
```

Independently versioned components — PQS and the Wallet Gateway — always need their own `version` set, and never follow `spliceVersion`.

{% hint style="warning" %}
**Azure KMS bypasses this entirely.** When Azure KMS is enabled, the participant runs the KMS-enabled image from `spec.kms.azure.preBuiltImage`, and both `spec.participant.version` and `spliceVersion` are ignored for the participant. Upgrading such a validator means obtaining an updated KMS image. Factor that into your upgrade lead time.
{% endhint %}

***

### Logical Synchronizer Upgrade (LSU)

When a release includes a protocol upgrade, the Canton Network coordinates the transition using the **Logical Synchronizer Upgrade (LSU)** mechanism.

The process consists of:

1. Deploying the next-generation synchronizer alongside the existing infrastructure.
2. Running both synchronizers in parallel.
3. Validators upgrading to software supporting both protocol versions.
4. Scheduling the protocol switch through network governance.
5. Validators automatically switching to the new logical synchronizer.
6. Retiring the previous synchronizer infrastructure after the retention period.

This approach allows applications to continue operating throughout the protocol transition without requiring data migration or ledger reloading.

The upgrade process allows:

* Parallel operation of old and new synchronizers.
* Validators to support both protocol versions during the transition.
* Automatic switching to the new logical synchronizer at the scheduled upgrade time.
* Continuous application availability throughout the upgrade.
* Retirement of the previous synchronizer after a defined retention period.

{% hint style="success" %}
LSU significantly reduces maintenance effort and enables seamless protocol upgrades across the network — no manual database migration or ledger reload is required on the validator side.
{% endhint %}

***

### Domain migrations

When a network performs a domain migration, the migration is coordinated by the network, not by CAT-BM. Two fields participate:

<table><thead><tr><th width="290">Field</th><th>Purpose</th></tr></thead><tbody><tr><td><code>spec.network.migrationId</code></td><td>The migration the validator is operating against.</td></tr><tr><td><code>spec.validator.dumpPath</code></td><td>Path to a migration dump, when the migration requires one.</td></tr></tbody></table>

{% hint style="warning" %}
Domain migrations are network-wide events with their own timing and procedure. Coordinate them with IntellectEU support and your sponsoring Super Validator — do not change `migrationId` speculatively.
{% endhint %}

***

## Rollback Considerations

Rollback depends on what was upgraded.

**Platform** — see [Rolling back](#rolling-back) above for reverting a Helm release. Note that CRDs are never rolled back by Helm.

**Validator components** — if no irreversible migration has occurred, `spliceVersion` and pinned component versions can generally be reverted to a previous supported release.

**Applications (Daml packages)** — rollback is more constrained. If new contract types or fields have already been introduced on the ledger, reverting to a previous package version may not be possible; a new package version may instead need to be published to migrate contracts back to a compatible state.

{% hint style="warning" %}
Always take an identity dump and confirm your database backups before starting any upgrade — see [Identity Dumps & Database Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-dumps.md) — so recovery options remain available regardless of the rollback path.
{% endhint %}

***

## Application Upgrade Considerations

Application upgrades should support mixed-version deployments during the transition. The recommended approach combines:

* **Asynchronous rollout** — application providers and users independently deploy upgraded frontends, backends, and Daml packages.
* **Synchronous switch-over** — all participants activate the new workflows at an agreed point in time, once the required packages have been deployed. This minimizes the risk of workflow failures caused by version mismatches.

This lets existing workflows keep operating while each organization upgrades on its own schedule.

***

## Best Practices

**Before upgrading:**

* Review the release notes.
* Create a database backup and a Validator Identity Dump.
* Verify migration requirements.
* Schedule a maintenance window.
* Test the upgrade in DevNet or TestNet before Production.

**After upgrading:**

* Verify validator health (`Ready` status).
* Confirm participant synchronization.
* Test wallet connectivity.
* Verify application functionality.
* Review logs for startup or migration errors.
* Monitor the deployment until it is fully operational.

***

## Version compatibility

{% hint style="info" %}
The `Validator` and `Application` custom resources are served at `catalyx.manager.canton/v1alpha1`.

**Field-level changes may still occur in a future minor release.** Treat the CRD schema as stable in shape but not frozen in detail, and read the release notes before upgrading the platform. Keep your `Validator` resources under version control so a schema change is a reviewable diff rather than a surprise.
{% endhint %}

***

## Consequences of Running an Outdated Validator <a href="#consequences-of-running-an-outdated-validator" id="consequences-of-running-an-outdated-validator"></a>

If a validator remains on an older version after the Canton Network has moved forward, the following issues may occur:

* Application initialization failures.
* Package compatibility conflicts.
* Migration failures.
* Validator remaining in **Pending** state.
* Failure to join or synchronize with the network.
* Inability to deploy newer applications or packages.
* Reduced compatibility with newer Canton protocol features.
* Unsupported configuration for future incident resolution.

In some cases, the validator must be upgraded before normal operation can resume.

***

## Getting help

Upgrade paths, supported version combinations, and migration procedures for a specific deployment are provided by IntellectEU support. See [Contact Support](/catalyx-blockchain-manager/canton-network/version-2.0/support-and-resources.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/upgrades.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.