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

Alter the versions you depend on in your Gradle file like so:

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

Note

You may wish to update your kotlinOptions to use language level 1.2, to benefit from the new features. 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.

You should also ensure you're using Gradle 4.10 (but not 5). If you use the Gradle wrapper, run:

./gradlew wrapper --gradle-version 4.10.3

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

Step 2. Update your Gradle build file

There are several adjustments that are beneficial to make to your Gradle build file, beyond simply incrementing the versions as described in step 1.

Provide app metadata. 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"
        licence "A liberal, open source licence"
        versionId 1
    }
    workflow {
        name "MegaApp flows"
        vendor "MegaCorp"
        licence "A really expensive proprietary licence"
        versionId 1
    }
}

Important

Watch out for the UK spelling of the word licence (with a c).

Name, vendor and licence 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 opts in to changes that might not be 100% backwards compatible, such as API semantics changes or disabling workarounds for bugs that may be in your apps, 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 minimum platform version is the platform version of the node that you require, so if you start using new APIs and features in Corda 4, you should set this to 4. Unfortunately Corda 3 and below do not know about this metadata and don't check it, so your app will still be loaded in such nodes and may exhibit undefined behaviour at runtime. However it's good to get in the habit of setting this properly for future releases.

Note

Whilst it's currently a convention that Corda releases have the platform version number as their major version i.e. Corda 3.3 implements platform version 3, this is not actually required and may in future not hold true. You should know the platform version of the node releases you want to target.

The new versionId number is a version code for your app, and is unrelated to Corda's own versions. It is used to block state downgrades: when a state constraint can be satisfied by multiple attachments, the version is tracked in the ledger and cannot decrement. This ensures security fixes in CorDapps stick and can't be reversed by downgrading states to an earlier version. See "contract_non-downgrade_rule_ref" for more information.

Split your app into contract and workflow JARs. 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.

In future, the version ID attached to the workflow JAR will also be used to help implement smoother upgrade and migration features. You may directly reference the gradle version number of your app when setting the CorDapp specific versionId identifiers if this follows the convention of always being a whole number starting from 1.

If you use the finance demo app, you should adjust your dependencies so you depend on the finance-contracts and finance-workflows artifacts from your own contract and workflow JAR respectively. Although a single finance jar still exists in Corda 4 for backwards compatibility, it should not be installed or used for updated apps. This way, only the code that needs to be on the ledger actually will be.

Step 3. Security: 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 three step process:

Change the flow that calls FinalityFlow
Change or create the flow that will receive the finalised transaction.
Make sure your application's minimum and target version numbers are both set to 4 (see step 2).

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