Status Definitions and Compatibility

Semantic versioning, release cadence, and support duration are defined in Releases and Versioning. This page defines: the public API surface, status labels, and the compatibility rules between components.

The public API

Stable features and components constitute the “public API” in the sense of Semantic Versioning. The following surfaces have documented compatibility contracts:

Surface	Compatibility contract
Ledger API	Ships as part of Canton releases, which are versioned according to Semantic Versioning; the API version a participant serves is discoverable at runtime via the Version Service
Canton protocol versions	Negotiated at connection time; nodes set a floor with `minimum-protocol-version`
Canton Network Token Standard and other Splice Daml interfaces	Daml interfaces are the stable public API for on-ledger integration; see Splice API overview
Splice HTTP endpoints in `*-external` API definitions	Intended to stay backwards compatible across releases; at this point, there might be some cases where backwards compatibility is broken as Splice is still in early stages of development. Any breaking changes in `external` APIs are documented in the release notes. See Splice HTTP APIs
PQS SQL API	A set of functions that should be the only database artifacts readers interact with; see PQS SQL API

The following are explicitly not part of the public API and may change between releases without notice:

Splice HTTP endpoints in *-internal API definitions (Splice HTTP APIs)
Daml templates and choices of the Splice applications — implementation details behind the interface-based standards (Splice API overview)
The PQS database schema — the provisioned functions are the only database artifacts readers should interact with (PQS SQL API)

Feature status labels

Features or components covered by these docs are Stable by default. Features and components that are not Stable are called “Early Access” and called out explicitly. Early Access features are opt-in whenever possible, needing to be activated with special commands or flags needing to be started up separately, or requiring the use of additional endpoints. Alpha Alpha components and features are early preview versions of features being actively developed to become a stable part of the ecosystem. At the Alpha stage, they are not yet feature complete, may have poor runtime characteristics, are subject to frequent change, and may not be fully documented. Alpha features can be evaluated, and used in PoCs, but should not be relied upon for large projects or production use where breakages or changes to APIs would be costly. Beta Beta components and features are preview versions of features that are close to maturity. They are characterized by being considered feature complete, and the APIs close to the final public APIs. It is relatively safe to build on Beta features as long as the documented caveats to runtime characteristics are understood and bugs and minor API adjustments are not too costly.

Status comparison

	Stable	Beta	Alpha
Functional Completeness	Functionally complete	Considered functionally complete, but subject to change according to usability testing	MVP-level functionality covering at least a few core use-cases
Performance	Unless stated otherwise, the feature can be used without concern about system performance.	Current performance impacts and expected performance for the stable release are documented.	Using the feature may have significant undocumented impact on overall system performance.
Stability & Error Recovery	The feature is long-term stable and supports recovery fit for a production system.	No known reproducible crashes which can’t be recovered from. There is still an expectation that new issues may be discovered.	The feature may not be stable and lack error recovery.
Covered by Semantic Versioning	Yes, part of the “public API”.	No, but breaking changes will be documented.	No, and changes may be poorly documented.

Early access protocol versions

Feature status and protocol version status are separate axes. A synchronizer may run an alpha or beta protocol version. The use of early access protocol versions is intended for non-production environments and is not covered by support. See Enable early access protocol features for the configuration.

Compatibility

The live version pairings for each network are published on the Version Compatibility Dashboard. The rules behind those pairings:

Node to synchronizer: compatibility is governed by the Canton protocol version, negotiated when a node connects. Operators control the floor with minimum-protocol-version; a synchronizer’s protocol version is implied by its Splice version.
Application to ledger: applications built against the Token Standard Daml interfaces remain compatible across Splice upgrades; the interfaces exist to decouple application code from Splice implementation upgrades (Splice API overview).
Daml packages across SDK versions: governed by Smart Contract Upgrade, which defines when a new package version can replace an old one without ledger migration.
Network upgrades: upgrades are validated through the DevNet → TestNet → MainNet progression described in Releases and Versioning.

Deprecation

Features and components may be labeled Deprecated. Deprecations are announced in the release notes.

​The public API

​Feature status labels

​Status comparison

​Early access protocol versions

​Compatibility

​Deprecation