Upgrading CorDapps to newer platform versions

These notes provide information on upgrading your CorDapps from previous versions. Corda 4 provides stability for public, non-experimental APIs that have been committed to. A list can be found in the API stability guarantees page.

This means that you can upgrade your node across versions without recompiling or adjusting your CorDapps. You just have to upgrade your node and restart.

However, there are usually new features and other opt-in changes that may improve the security, performance or usability of your application that are worth considering for any actively maintained software.

Platform version matrix

Upgrading CorDapps to platform version 140

Platform version 140 which represents Corda 4.12 is a major platform upgrade. In this version, Corda has been upgraded to run on Java 17 and to use Kotlin 1.9.20. This also means that you must recompile Corda 4.12 CorDapps with Java 17 and Kotlin 1.9.20. Once recompiled and fully tested, you must sign CorDapps with the same key used to sign the 4.11 CorDapps.

Additionally, if a CorDapp has been updated to platform version 140, you must upgrade Corda nodes to Corda 4.12. For instructions on how to upgrade Corda nodes, see Corda Open Source Edition 4.11 to 4.12 upgrade guide.

Upgrading CorDapps to platform version 9, 10, 11, 12, and 13

No manual upgrade steps are required.

Upgrading CorDapps to platform version 8 or lower

Required actions relating to database optimisation in Corda 4.6

The operational improvements around database schema harmonisation that we have made in Corda 4.6 require a number of manual steps when upgrading to Corda 4.6 from a previous version. For more information, see the Corda Open Source 4.6 release notes available in the archived-docs directory of the corda/corda-docs-portal repo. The required steps for each upgrade path are described below.

Upgrading an existing node from Corda 4.5 (or earlier 4.x version) to version 4.6

1. Remove any entries of transactionIsolationLevel, initialiseSchema, or initialiseAppSchema from the database section of your node configuration file.
2. Update any missing core schema changes by running the node in run-migration-scripts mode: java -jar corda.jar run-migration-scripts --core-schemas.
3. Add Liquibase resources to CorDapps. In Corda 4.6, CorDapps that introduce custom schema need Liquibase migration scripts allowing them to create the schema upfront. For existing CorDapps that do not have migration scripts in their resources, they can be added as an external migration JAR file, as documented in the Corda Enterprise 4.6 database management scripts documentation (available in the archived-docs directory of the corda/corda-docs-portal repo).
4. Update the changelog for existing schemas. After upgrading the Corda JAR file and adding Liquibase scripts to the CorDapp(s), any custom schemas from the apps are present in the database, but the changelog entries in the Liquibase changelog table are missing (as they have been created by Liquibase). This will cause issues when starting the node, and also when running run-migration-scripts as tables that already exist cannot be recreated. By running the new sub-command sync-app-schemas, changelog entries are created for all existing mapped schemas from CorDapps: java -jar corda.jar sync-app-schemas.

Upgrading from Corda 3.x or Corda Enterprise 3.x

Corda 4.6 drops the support for retro-fitting the database changelog when migrating from Corda versions older than 4.0. Thus it is required to migrate to a previous 4.x version before migrating to Corda 4.6 - for example, 3.3 to 4.5, and then 4.5 to 4.6.

Corda Gradle Plugins version 5.1.1

To successfully build a CorDapp against Platform Version 8 and Corda 4.6, you need to use version 5.1.1 of the Corda Gradle Plugins:

ext.corda_gradle_plugins_version = '5.1.1'

Upgrading CorDapps to Platform Versions 6 and 7

No manual upgrade steps are required.

Upgrading CorDapps to Platform Version 5

This section provides instructions for upgrading your CorDapps from previous versions to take advantage of features and enhancements introduced in platform version 5.

Step 1. Handle any source compatibility breaks (if using Kotlin)

The following code, which compiled in Platform Version 4, will not compile in Platform Version 5:

data class Obligation(val amount: Amount<Currency>, val lender: AbstractParty, val borrower: AbstractParty)

val (lenderId, borrowerId) = if (anonymous) {
    val anonymousIdentitiesResult = subFlow(SwapIdentitiesFlow(lenderSession))
    Pair(anonymousIdentitiesResult[lenderSession.counterparty]!!, anonymousIdentitiesResult[ourIdentity]!!)
} else {
    Pair(lender, ourIdentity)
}

val obligation = Obligation(100.dollars, lenderId, borrowerId)

Compiling this code against Platform Version 5 will result in the following error:

Type mismatch: inferred type is Any but AbstractParty was expected

The issue here is that a new Destination interface introduced in Platform Version 5 can cause type inference failures when a variable is used as an AbstractParty but has an actual value that is one of Party or AnonymousParty. These subclasses implement Destination, while the superclass does not. Kotlin must pick a type for the variable, and so chooses the most specific ancestor of both AbstractParty and Destination. This is Any, which is not a valid type for use as an AbstractParty later. For more information on Destination, see the KDocs for the interface here.

Note that this is a Kotlin-specific issue. Java can instead choose ? extends AbstractParty & Destination here, which can later be used as AbstractParty.

To fix this, an explicit type hint must be provided to the compiler:

data class Obligation(val amount: Amount<Currency>, val lender: AbstractParty, val borrower: AbstractParty)

val (lenderId, borrowerId) = if (anonymous) {
    val anonymousIdentitiesResult = subFlow(SwapIdentitiesFlow(lenderSession))
    Pair(anonymousIdentitiesResult[lenderSession.counterparty]!!, anonymousIdentitiesResult[ourIdentity]!!)
} else {
    // This Pair now provides a type hint to the compiler
    Pair<AbstractParty, AbstractParty>(lender, ourIdentity)
}

val obligation = Obligation(100.dollars, lenderId, borrowerId)

This stops type inference from occurring and forces the variable to be of type AbstractParty.

Step 2. Update Gradle version and associated dependencies

Platform Version 5 requires Gradle 5.4 to build. If you use the Gradle wrapper, you can upgrade by running:

./gradlew wrapper --gradle-version 5.4.1

Otherwise, upgrade your installed copy in the usual manner for your operating system.

Additionally, you’ll need to add https://repo.gradle.org/gradle/libs-releases as a repository to your project, in order to pick up the gradle-api-tooling dependency. You can do this by adding the following to the repositories in your Gradle file:

maven { url 'https://repo.gradle.org/gradle/libs-releases' }