Upgrading a CorDapp to a newer platform version

This guide shows you how to upgrade your CorDapp from previous platform versions to benefit from the new features in the latest release.

Most of Corda’s public, non-experimental APIs are backwards compatible. See the full list of stable APIs. If you are working with a stable API, you don’t need to update your CorDapps. However, there are usually new features and other opt-in changes that may improve the security, performance, or usability of your CorDapp that are worth considering for any actively maintained software.

Corda releasePlatform version
4.1113
4.1012
4.911
4.810
4.79
4.68
4.57
4.46
4.35
4.24
4.14
4.04
3.33

No manual upgrade steps are required.

To upgrade your CorDapps to platform version 8, you need to:

  1. Upgrade existing nodes to version 4.6.
  2. Check that you are using Corda Gradle plugins version 5.0.12.

When upgrading to Corda 4.6 from a previous version, you need to upgrade your nodes because of the operational improvements for database schema harmonization that were introduced as part of this release.

Follow the steps below for each upgrade path.

  1. Remove any entries of transactionIsolationLevel, initialiseSchema, initialiseAppSchema, and runMigration from the database section of your node configuration file.
  2. Update any missing core schema changes by either running the Database Management Tool (recommended) or running the node in run-migration-scripts mode: java -jar corda.jar run-migration-scripts --core-schemas.

Version 4.6 doesn’t retro-fit the database changelog when upgrading from versions older than 4.0. Therefore, you need to upgrade to a previous 4.x version before upgrading to 4.6. For example, 3.3 to 4.5, and then 4.5 to 4.6.

You need to use version 5.0.12 of the Corda Gradle plugins to successfully build a CorDapp against platform version 8 and Corda 4.6.

ext.corda_gradle_plugins_version = '5.0.12'

You don’t need to perform a manual upgrade for this platform version.

You don’t need to perform a manual upgrade for this platform version.

To upgrade your CorDapps to platform version 5, you need to:

  1. Handle any source compatibility breaks.
  2. Update Gradle version and associated dependencies.

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)

If you try to compile this code in platform version 5, you’ll get the following error.

Type mismatch: inferred type is Any but AbstractParty was expected

This is because a new Destination interface (introduced in platform version 5) can cause type inference failures when using a variable as an AbstractParty which 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 subsequently a valid type for AbstractParty.

For more information on Destination, see the Changelog for platform version 5, or the KDocs for the interface.

To fix the issue, you must provide an explicit type hint 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.

Platform version 5 requires Gradle 5.4. 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 way.

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

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

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.