corda/docs/source/upgrade-notes.rst

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 {
    info {
        name "MegaApp"
        vendor "MegaCorp"
        targetPlatformVersion 4
        minimumPlatformVersion 4
    }
}

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.

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:

1. Change the flow that calls FinalityFlow
2. 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

example-code/src/main/java/net/corda/docs/java/FinalityFlowMigration.java

To use the new API, this flow needs to be annotated with InitiatingFlow and a FlowSession to the participant of the transaction must be passed to FinalityFlow :

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

example-code/src/main/java/net/corda/docs/java/FinalityFlowMigration.java

If there are more than one transaction participants then a session to each one must be initiated, excluding the local party and the notary.

A responder flow has to be introduced, which will automatically run on the other participants' nodes, which will call ReceiveFinalityFlow to record the finalised transaction:

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

example-code/src/main/java/net/corda/docs/java/FinalityFlowMigration.java

For flows which are already initiating counterpart flows then it's a simple matter of using the existing flow session. Note however, the new FinalityFlow is inlined and so the sequence of sends and receives between the two flows will change and will be incompatible with your current flows. You can use the flow version API to write your flows in a backwards compatible way.

Here's what an upgraded initiating flow may look like:

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

example-code/src/main/java/net/corda/docs/java/FinalityFlowMigration.java

For the responder flow, insert a call to ReceiveFinalityFlow at the location where it's expecting to receive the finalised transaction. If the initiator is written in a backwards compatible way then so must the responder.

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

example-code/src/main/java/net/corda/docs/java/FinalityFlowMigration.java

The responder flow may be waiting for the finalised transaction to appear in the local node's vault using waitForLedgerCommit. This is no longer necessary with ReceiveFinalityFlow and the call to waitForLedgerCommit can be removed.

Step 4. Possibly, adjust unit test code

MockNodeParameters and functions creating it no longer use a lambda expecting a NodeConfiguration object. Use a MockNetworkConfigOverrides object instead. This is an API change we regret, but unfortunately in Corda 3 we accidentally exposed large amounts of the node internal code through this one API entry point. We have now insulated the test API from node internals and reduced the exposure.

Step 5. Security: refactor to avoid violating sealed packages

Hardly any apps will need to do anything in this step.

App isolation has been improved. Version 4 of the finance CorDapp (corda-finance.jar) is now built as a sealed and signed JAR file. This means classes in your own CorDapps cannot be placed under the following packages:

net.corda.finance
net.corda.finance.contracts
net.corda.finance.contracts.asset.cash.selection
net.corda.finance.contracts.asset
net.corda.finance.contracts.math
net.corda.finance.flows
net.corda.finance.internal
net.corda.finance.plugin
net.corda.finance.schemas
net.corda.finance.utils

In the unlikely event that you were injecting code into net.corda.* package namespaces from your own apps, you will need to move them into a new package, e.g. net/corda/finance/flows.MyClass.java can be moved to net/corda/finance/flows/company/MyClass.java. Also your classes are no longer able to access non-public members of finance CorDapp classes.

When recompiling your JARs for Corda 4, your own apps will also become sealed, meaning other JARs cannot place classes into your own packages. This is a security upgrade that ensures package-private visibility in Java code works correctly.

Step 6. Security: Add BelongsToContract annotations

In versions of the platform prior to v4, it was the responsibility of contract and flow logic to ensure that TransactionState objects contained the correct class name of the expected contract class. If these checks were omitted, it would be possible for a malicious counterparty to construct a transaction containing e.g. a cash state governed by a commercial paper contract. The contract would see that there were no commercial paper states in a transaction and do nothing, i.e. accept.

In Corda 4 the platform takes over this responsibility from the app, if the app has a target version of 4 or higher. A state is expected to be governed by a contract that is either:

1. The outer class of the state class, if the state is an inner class of a contract. This is a common design pattern.
2. Annotated with @BelongsToContract which specifies the contract class explicitly.

Learn more by reading "implicit_constraint_types". If an app targets Corda 3 or lower (i.e. does not specify a target version), states that point to contracts outside their package will trigger a log warning but validation will proceed.

Step 7. Consider adopting signature constraints

design/data-model-upgrades/signature-constraints are a new data model feature introduced in Corda 4. They make it much easier to deploy application upgrades smoothly and in a decentralised manner. We strongly recommend all apps move to using signature constraints as soon as feasible, as they represent the best tradeoff between the different upgrade control models.

Important

You will be able to use this feature if the compatibility zone you plan to deploy on has raised its minimum platform version to 4. Otherwise attempting to use signature constraints will throw an exception, because other nodes would not understand it or be able to check the correctness of the transaction. Please take this into account for your own schedule planning.

You can read more about signature constraints and what they do in api-contract-constraints. The TransactionBuilder class will automatically use them if your application JAR is signed. We recommend all JARs are signed. To start signing your JAR files, read cordapp_build_system_signing_cordapp_jar_ref.

Step 8. Consider adding extension points to your flows

In Corda 4 it is possible for flows in one app to subclass and take over flows from another. This allows you to create generic, shared flow logic that individual users can customise at pre-agreed points (protected methods). For example, a site-specific app could be developed that causes transaction details to be converted to a PDF and sent to a particular printer. This would be an inappropriate feature to put into shared business logic, but it makes perfect sense to put into a user-specific app they developed themselves.

If your flows could benefit from being extended in this way, read "flow-overriding" to learn more.