Are there any official migration guide for moving a production deployment from Canton 2.x to Canton 3.x?

Hello Team,

While reviewing the documentation, we found upgrade procedures for Canton nodes and protocol-version upgrades, as well as release-specific migration notes. However, we could not find a consolidated migration guide for upgrading an existing Canton 2.x deployment to Canton 3.x.

Could you please clarify:

1. Is there an official migration guide for Canton 2.x → Canton 3.x?

2. What is the recommended upgrade path for production deployments?

3. Are there any mandatory intermediate versions that should be used?

4. What are the major breaking changes operators should be aware of?

5. Are there any special considerations for:

• participant nodes

• sequencers/synchronizers

• topology transactions

• database migrations

• external KMS/HSM integrations

Any references, best practices, or migration runbooks would be greatly appreciated.

Thank you.

Hi @k_arya,

Unfortunately, there is no public step-by-step guide for moving a production deployment from 2.x to 3.x. DA’s 2.10 LTS FAQ says 2.10 is the version to be on to prepare for 3.x, that “Migration to v3.0 should be considered based on the use case you wish to deliver”, and asks you to “discuss this in more detail with your representative”. It also mentions a direct upgrade path from 2.10 LTS and a migration document, but I couldn’t find that document published.

What is clear is that this is a major-version move with protocol, SDK and API changes. 2.x and 3.x use different protocol versions, and Canton 3 doesn’t accept DARs built with the 2.x SDK, so the app has to be ported to the 3.x SDK and APIs. DA has a high-level list of the changes, and this community write-up about porting a 2.9.4 app to 3.4 shows the real gotchas.

For the 2.10 side, a DA engineer shared how to get your packages ready for the move to Daml 3.

If you can share more about your setup, maybe we can help further here on the forum. Hope that helps!