Portability, Compatibility, and Support Durations

The DAML Ecosystem offers a number of forward and backward compatibility guarantees aiming to give the Ecosystem as a whole the following properties. See Architecture for the terms used here and how they fit together.

Application Portability

A DAML application should not depend on the underlying Database or DLT used by a DAML Network.

Network Upgradeability

Ledger Operators should be able to upgrade DAML Network or Participant Nodes seamlessly to stay up to date with the latest features and fixes. A DAML application should be able to operate without significant change across such Network Upgrades.

SDK Upgradeability

Application Developers should be able to update their developer tools seamlessly to stay up to date with the latest features and fixes, and stay able to maintain and develop their existing applications.

Ledger API Compatibility: Application Portability

Application Portability and to some extent Network Upgradeability are achieved by intermediating through the Ledger API. As per Versioning, and Architecture, the Ledger API is independently semantically versioned, and the compatibility guarantees derived from that semantic versioning extend to the entire semantics of the API, including the behavior of DAML Packages on the Ledger. Since all interaction with a DAML Ledger happens through the DAML Ledger API, a DAML Application is guaranteed to work as long as the Participant Node exposes a compatible Ledger API version.

Specifically, if a DAML Application is built against Ledger API version X.Y.Z and a Participant Node exposes Ledger API version X.Y2.Z2, the application is guaranteed to work as long as Y2.Z2 >= Y.Z.

Currently, the Ledger API version is the same as the version of the Integration Components used in the Participant Node. This is mostly the case because there has been no need for the versions to diverge yet. This will likely change at the latest when one part of the ecosystem moves to version 2.X. Integration Components, DAML Drivers, and Participant Nodes advertise the Ledger API version they expose.

As a concrete example, DAML for Postgres 1.4.0 has the Participant Node integrated, and exposes Ledger API version 1.4.0 and the DAML for VMware Blockchain 1.0 Participant Nodes expose Ledger API version 1.6.0. So any application that runs on DAML for Postgres 1.4.0 will also run on DAML for VMware Blockchain 1.0.

Driver and Participant Compatibility: Network Upgradeability

Given the Ledger API Compatibility above, network upgrades are seamless if they preserve data, and Participant Nodes keep exposing the same or a newer minor version of the same major Ledger API Version. The semantic versioning of DAML Drivers and Participant Nodes gives this guarantee. Upgrades from one minor version to another are data preserving, and major Ledger API versions may only be removed with a new major version of Integration Components, DAML Drivers and Participant Nodes.

As an example, from an application standpoint, the only effect of upgrading DAML for Postgres 1.4.0 to DAML for Postgres 1.6.0 is an uptick in the Ledger API version. There may be significant changes to components or database schemas, but these are not public APIs.

SDK, Runtime Component, and Library Compatibility: SDK Upgradeability

As long as a major Ledger API version is supported (see Ledger API Support Duration), there will be supported versions of SDK, Runtime Components, and Libraries able to target all minor versions of that major version. This has the obvious caveat that new features may not be available with old Ledger API versions.

For example, an application built and compiled with SDK, Libraries and Runtime Components 1.4.0 against Ledger API 1.4.0, it can still be compiled using SDK 1.6.0 and can be run against Ledger API 1.4.0 using 1.6.0 libraries and runtime components.

Ledger API Support Duration

Major Ledger API versions behave like stable features in Status Definitions. They are supported from the time they are first released as “stable” to the point where they are removed from Integration Components and SDK following a 12 month deprecation cycle. The earliest point a major Ledger API version can be deprecated is with the release of the next major version. The earliest it can be removed is 12 months later with a major version release of the Integration Components.

Other than for hotfix releases, new releases of the Integration Components will only support the latest minor/patch version of each major Ledger API version.

As a result we can make this overall statement:

An application built using SDK, Libraries and Runtime Components U.V.W against Ledger API X.Y.Z can be maintained using any SDK, Library amd Runtime Components version U2.V2.W2 >= U.V.W as long as Ledger API major version X is still supported at the time of release of U2.V2.W2, and run against any DAML Network with Participant Nodes exposing Ledger API X.Y2.Z2 >= X.Y.Z.