Versioning¶
Canton release version¶
The Canton release version (release version for short) is the primary version assigned to a Canton release. It is semantically versioned, i.e., breaking changes to a public API will always lead to a major version increase of the release version. The public APIs encompassed by the release version are the following:
- Ledger API server (for participants)
- Non-preview and non-testing Admin API & Console commands
- Error code format (machine-readable parts, see also the error code documentation)
- Canton configuration file format
- Command line arguments
- Internal storage (data continuity between non-major upgrades)
- Canton protocol version
As a result, Canton components are always safely upgradeable with respect to these APIs. In particular, the inclusion of the Canton protocol version as a Public API guarantees that any two Canton components of the same release version can interact with each other and can be independently upgraded within a major version without any loss of interoperability (see also the documentation on the Canton protocol version).
For application developers and operators¶
Applications using Canton have the following guarantees:
- Participants can be upgraded independently of each other and of applications and domains within a major release version.
- Domain drivers can be upgraded independently of applications and connected participants within a major release version.
- Major versions of anything are supported for a minimum of 12 months from the release of the next major release version.
As a result, applications written today can keep running unchanged for a minimum of 12 months while upgrading participants and domains within a major release version. See also the versioning as well as portability, compatibility and support duration guarantees that hold for any Daml application.
For Canton participant and domain operators¶
In addition to the Canton release version, the Canton protocol version is another important version for participant and domain operators. It has major, minor and patch digits.
Canton protocol version¶
The Canton protocol determines how different Canton components interact with each other. We version it using the Canton protocol version (protocol version for short) and conceptually, two Canton components can interact (are interoperable) if they support the same protocol version. For example, a participant can connect to a domain if it supports the protocol version that is spoken on the domain, and a mediator can become the mediator for a domain, if it supports the protocol version required by the domain. If two Canton components have the same major release version, they also share at least one protocol version and can thus interact with each other.
A Canton component advertises the highest protocol version it supports and supports all previous protocol versions of the same major version. That is, a participant or driver supporting a certain protocol version, is able to transact with all other participants or drivers supporting a lower or equal protocol version but may not be able to transact with participants or drivers supporting a higher Canton protocol if they are configured to use a more recent version of the protocol. For example, a release of a participant supporting protocol version 1.3.0 will be able to connect to all domains configured to use protocol version <= 1.3.0. It won’t be able to connect to a domain configured to use protocol version > 1.3.0. As a result, minor and patch version upgrades of Canton components can be done independently without any loss of interoperability.
To see the highest protocol version a Canton component supports (e.g., 1.5.0), run
canton --version
(where canton is an alias for the path pointing to the Canton release binary bin/canton).
Configuring the protocol version¶
A Canton driver or domain operator is able to configure the protocol version spoken on the domain (e.g. 1.3.2). If the domain operator sets the protocol version spoken on a domain too high, they may exclude participants that don’t support this protocol version yet.
For example, if the domain operator sets the protocol version on a domain to 1.3.0, participants that only support protocol version 1.2.0 aren’t able to connect to the domain. They would be able to connect and transact on the domain, if the protocol version set on the domain is set to 1.2.0 or lower. Note that this is always possible in such a scenario because if a domains supports protocol version 1.3.0, it also supports protocol version 1.2.0.
Minimum protocol version¶
Similar to how a domain operator is able to configure the protocol version spoken on a domain, a participant operator is able to configure a minimum protocol version for a participant. Configuring a minimum protocol version guarantees that a participant will only connect to domain that use at least this protocol version or a newer one. This is especially desirable to ensure that a participant only connects to domains that have certain security patches applied or that support particular protocol features.
Support and bug fixes¶
Canton protocol major versions are supported for a minimum of 12 months from the release of the next major version. Within a major version, only the latest minor version receives security and bug fixes.