corda/docs/source/upgrade-notes.rst

Upgrading a CorDapp to a new platform version

These notes provide instructions for upgrading your CorDapps from previous versions of Corda to version .

UNRELEASED

FinalityFlow

The previous FinalityFlow API is insecure. It requires a handler flow in the counterparty node which accepts 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 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.

Upgrading from Corda Open Source

A prerequisite to upgrade to is to ensure your CorDapp is upgraded to Open Source Corda 3.x. Please follow the instructions in Corda V3.1 upgrade notes and Corda V3.0 upgrade notes section to complete this initial step.

Note

There is no requirement to upgrade your CorDapp to Corda Enterprise in order to run it on Corda Enterprise. If you wish your CorDapp to be compatible with nodes running Open Source, then compiling against Open Source Corda V3.x will suffice.

Upgrading to from Open Source 3.x requires updating build file properties. For Gradle:

ext.corda_release_distribution = 'com.r3.corda'
ext.corda_release_version = '3.1'
ext.corda_gradle_plugins_version = '4.0.25'

and specifying an additional repository entry to point to the location of the Corda Enterprise distribution. As an example:

repositories {
    maven {
        credentials {
            username "username"
            password "XXXXX"
        }
        url 'https://artifactory.mycompany.com/artifactory/corda-enterprise'
    }
}

Note

binaries are not available in a public repository. In order to make the dependencies available for development, either create a mirror repository and upload them there, or add them to the local Maven repository.

Note

While the Corda Gradle Plugins need no changes apart from the version, ensure that Corda Enterprise dependencies are referenced with the right distribution. As an example:

cordaCompile "net.corda:corda-core:$corda_release_version"

becomes:

cordaCompile "$corda_release_distribution:corda-core:$corda_release_version"

uses Kotlin API and language version 1.2. The specifics are

ext.kotlin_version = '1.2.50'

Note

Explicit overriding of properties ext.quasar_group and ext.quasar_version is not necessary anymore for CorDapps depending on the quasar-utils plugin. You can remove these two lines from which ever file.

Certificate Revocation List (CRL) support

The newly added feature of certificate revocation (see certificate-revocation) introduces a few changes to the node configuration. In the configuration file it is required to explicitly specify how strictly the node should apply the CRL check. For that purpose the crlCheckSoftFail parameter is now expected to be set explicitly in the node's SSL configuration. Setting the crlCheckSoftFail to true, relaxes the CRL checking policy. In this mode, the SSL communication will fail only when the certificate revocation status can be checked and the certificate is revoked. Otherwise it will succeed. If crlCheckSoftFail is false, then an SSL failure can occur if the certificate revocation status cannot be checked (e.g. due to a network failure), as well as when a certificate is revoked.

Older versions of Corda do not have CRL distribution points embedded in the SSL certificates. As such, in order to be able to reuse node and SSL certificates generated in those versions of Corda, the crlCheckSoftFail needs to be set to true.

Note

Mitigation of this issue and thus being able to use the strict mode (i.e. with crlCheckSoftFail = false) of the CRL checking with the certificates generated in previous versions of Corda is going to be added in the near future.

Upgrading from Corda Enterprise 3.0 Developer Preview 3.0

A limited distribution preview of was made available to a small number of users. If your app uses this version, here are some specific notes on how to upgrade to the Generally Available release:

• Update versions in your build files, for Gradle, as an example:

  ext.corda_release_version = '3.1'
  ext.corda_gradle_plugins_version = '4.0.25'
  ext.kotlin_version = '1.2.50'

  Note

  Explicit overriding of properties ext.quasar_group and ext.quasar_version is not necessary anymore for CorDapps depending on the quasar-utils plugin. You can remove these two lines from which ever file.

• For CorDapps depending on the cordapp-plugin, version 4.0.25 allows specifying distribution information. As an example:

  cordapp {
    info {
      name "My CorDapp"
      vendor "My Company"
      version "1.0.1"
    }
  }

  Note

  Properties name and version of a CorDapp's distribution information are derived automatically by the cordapp-plugin if not provided. The vendor property should be provided explicitly. A warning is raised by Corda Enterprise nodes for CorDapps that do not specify the vendor property.

Certificate Revocation List (CRL) support

The newly added feature of certificate revocation (see certificate-revocation) introduces a few changes to the node configuration. In the configuration file it is required to explicitly specify how strictly the node should apply the CRL check. For that purpose the crlCheckSoftFail parameter is now expected to be set explicitly in the node's SSL configuration. Setting the crlCheckSoftFail to true, relaxes the CRL checking policy. In this mode, the SSL communication will fail only when the certificate revocation status can be checked and the certificate is revoked. Otherwise it will succeed. If crlCheckSoftFail is false, then an SSL failure can occur if the certificate revocation status cannot be checked (e.g. due to a network failure), as well as when a certificate is revoked.

Older versions of Corda do not have CRL distribution points embedded in the SSL certificates. As such, in order to be able to reuse node and SSL certificates generated in those versions of Corda, the crlCheckSoftFail needs to be set to true.

Note

Mitigation of this issue and thus being able to use the strict mode (i.e. with crlCheckSoftFail = false) of the CRL checking with the certificates generated in previous versions of Corda is going to be added in the near future.

Upgrading from Corda Enterprise 3

API Changes

• MockNetwork: MockNodeParameters and functions creating it no longer use a lambda expecting a NodeConfiguration object. Use a MockNetworkConfigOverrides object instead.