Upgrading apps to Corda 4

These notes provide instructions for upgrading your CorDapps from previous versions. Corda provides backwards compatibility for public, non-experimental APIs that have been committed to. A list can be found in the corda-api 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. This guide shows you how to upgrade your app to benefit from the new features in the latest release.

Step 1. Adjust the version numbers in your Gradle build files

ext.corda_release_version = '4.0'
ext.corda_gradle_plugins_version = '4.0.36'
ext.kotlin_version = '1.2.71'
ext.quasar_version = '0.7.10'

Important

Apps targeting Corda 4 may not at this time use Kotlin 1.3, as it was released too late in the development cycle for us to risk an upgrade. Sorry! Future work on app isolation will make it easier for apps to use newer Kotlin versions than the node itself uses.

Step 2. Add a "cordapp" section to your Gradle build file

This is used by the Corda Gradle build plugin to populate your app JAR with useful information. It should look like this:

cordapp {
    targetPlatformVersion 4
    minimumPlatformVersion 4
    contract {
        name "MegaApp Contracts"
        vendor "MegaCorp"
        license "A liberal, open source license"
        versionId 1
    }
    workflow {
        name "MegaApp flows"
        vendor "MegaCorp"
        license "A really expensive proprietary license"
    }
}

Name and vendor can be set to any string you like, they don't have to be Corda identities. Target versioning is a new concept introduced in Corda 4. Learn more by reading versioning. Setting a target version of 4 disables workarounds for various bugs that may exist in your app, so by doing this you are promising that you have thoroughly tested your app on the new version. Using a high target version is a good idea because some features and improvements are only available to apps that opt in.

The duplication between contract and workflow blocks exists because you should split your app into two separate JARs/modules, one that contains on-ledger validation code like states and contracts, and one for the rest (called by convention the "workflows" module although it can contain a lot more than just flows: services would also go here, for instance). For simplicity, here we use one JAR for both, but this is in general an anti-pattern and can result in your flow logic code being sent over the network to arbitrary third party peers, even though they don't need it.

Step 3. Upgrade your use of FinalityFlow

The previous FinalityFlow API is insecure. It doesn't have a receive flow, so requires counterparty nodes to accept any and all signed transactions that are sent to it, without checks. It is highly recommended that existing CorDapps migrate away to the new API, as otherwise things like business network membership checks won't be reliably enforced.

This is a two step process:

Change the flow that calls FinalityFlow
Change or create the flow that will receive the finalised transaction.

As an example, let's take a very simple flow that finalises a transaction without the involvement of a counterpart flow:

example-code/src/main/kotlin/net/corda/docs/kotlin/FinalityFlowMigration.kt