diff --git a/build.gradle b/build.gradle
index c1b7cef82a..ad5775a512 100644
--- a/build.gradle
+++ b/build.gradle
@@ -14,7 +14,7 @@ buildscript {
file("$projectDir/constants.properties").withInputStream { constants.load(it) }
// Our version: bump this on release.
- ext.corda_release_version = "3.0.0-SNAPSHOT"
+ ext.corda_release_version = "4.0.0-SNAPSHOT"
ext.corda_release_distribution = "com.r3.corda"
// Increment this on any release that changes public APIs anywhere in the Corda platform
diff --git a/docs/source/release-notes.rst b/docs/source/release-notes.rst
index 9656544a9b..b79eb584be 100644
--- a/docs/source/release-notes.rst
+++ b/docs/source/release-notes.rst
@@ -1,21 +1,19 @@
Release notes
=============
-.. note::
+|release|
+---------
- There have been three developer previews, namely Developer Preview 1 through 3. In this section we are discussing the developer preview releases in general unless explicitly
- stated otherwise (e.g., where referencing Developer Preview 3).
+This release is the first official release of Corda Enterprise - a commercial distribution of the open source Corda blockchain platform, designed for mission critical enterprise deployments.
+|release| supports Linux for production deployments, with Windows and Mac OS support for development and demonstration purposes only. Please refer to product documentation for details.
-Corda Enterprise 3.0 Developer Preview
---------------------------------------
-This release is an early access preview of Corda Enterprise 3.0 - a commercial distribution of the Corda blockchain platform designed for mission critical enterprise deployments.
-
-Corda Enterprise 3.0 Developer Preview 3 adds enterprise features to Open Source Corda 3.0 while remaining operationally compatible with it. Please refer to the release notes for Corda 3.0 if upgrading from an earlier version.
+|release| is operationally compatible with Open Source Corda 3.x while providing enterprise-grade features and performance.
Key new features and components
*******************************
-* **High Availability**:
+**High Availability**
+
This release introduces the Hot-Cold High Availability configuration for Corda Enterprise nodes, which addresses the following requirements:
- A logical Corda node continues to be available as long as at least one of the clustered physical nodes is available.
@@ -23,120 +21,138 @@ Key new features and components
- Continuity of flows throughout node failures.
- Support for rolling software upgrades in a live network.
- See :ref:`here <hot-cold_ref>` for further details on how to set-up and operate Hot-Cold node HA.
+ See :ref:`here <hot_cold_ref>` for further details on how to set-up and operate Hot-Cold node HA.
-* **Additional Supported SQL Databases**:
- :ref:`PostgreSQL 9.6 <postgres_ref>`, :ref:`Azure SQL and SQL Server 2017 <sql_server_ref>` are now supported SQL databases.
+**Additional Supported SQL Databases**
+
+ :ref:`PostgreSQL 9.6 <postgres_ref>`, :ref:`Azure SQL and SQL Server 2017 <sql_server_ref>` and :ref:`Oracle 11g and 12c <oracle_ref>` are now supported SQL databases.
Database settings can be specified as part of the node configuration file.
See :doc:`node-database` for further details.
-* **Database Migration Tool**:
- Corda Enterprise ships with a tool for tracking, managing and applying database schema migrations.
- A framework for data migration provides a way to upgrade the version of Corda Enterprise or installed CorDapps while preserving data integrity and service continuity.
+**Database Management and Migration Tool**
+
+ |release| ships with a tool for tracking, managing and applying database schema migrations.
+ A framework for data migration provides a way to upgrade the version of Corda Enterprise or installed CorDapps while preserving data integrity and service continuity. It is also used to prepare a database for first use with Corda Enterprise.
Based on `Liquibase <http://www.liquibase.org/>`_, the tool also allows exporting DDL and data to a file, allowing DBAs to inspect the SQL or apply the SQL statements and to apply them manually if necessary.
See :ref:`database migration <database_migration_ref>` for further details.
-* **New Network Map Service**:
+**Multi-threaded Flow Processing**
+
+ |release| enables multi-threaded processing of flows, resulting in vastly higher performance than Corda 3.0. In Corda flows are processed on a single thread and
+ thus individual flow steps are not processed concurrently. Corda Enterprise is able to process multiple flow steps concurrently, the number of which is only limited by
+ available CPU cores, memory and database configuration. This allows Corda Enterprise to process a greater number
+ of flows and transactions in a given time frame than Open Source Corda and to truly take advantage of large server
+ / VM configurations. The number of operating system threads that are used is determined by the ``flowThreadPoolSize`` configuration property.
+ See :doc:`corda-configuration-file` for further details.
+
+**New Network Map Architecture**
+
This release introduces the new network map architecture. The network map service has been redesigned to enable future increased network scalability and redundancy, reduced runtime operational overhead,
support for multiple notaries, and administration of network compatibility zones (CZ) and business networks.
A Corda Compatibility Zone (CZ) is defined as a grouping of participants and services (notaries, oracles,
doorman, network map server) configured within an operational Corda network to be interoperable and compatible with
each other.
- See :doc:`network-map` for further details.
+ See :doc:`Network Map <network-map>` and :ref:`bootstrapping the network <bootstrapping_ref>` for further details.
-* **Doorman Service**:
- In order to automate a node's network joining process, a Doorman service has been introduced with this release.
- The Doorman's main purpose is to restrict network access only to those nodes whose identity has been confirmed and their network joining request approved.
- It issues node-level certificates which are then used by other nodes in the network to confirm a node's identity and network permissions.
- See :doc:`running-doorman` for further details.
+**Corda Firewall**
-* **Signing Service**:
- Corda Enterprise 3.0 Developer Preview supports external Hardware Security Module (HSM) integration for certificate issuing and data signing.
- Doorman certificates (together with their keys) can be stored on secured hardware, constraining the way those certificates are accessed. Any usage of those certificates
- (e.g. data signing or node-level certificate generation) falls into a restrictive process that is automatically audited
- and can be configured to involve human-in-the-loop in order to prevent unauthorised access.
- See :doc:`signing-service` for further details.
+ |release| introduces the Bridge and Corda Firewall components to enable secure setup of a Corda Node in a DMZ environment.
+ See :doc:`Corda Firewall Overview <corda-firewall>` for further details.
-* **Operational Compatibility With Open Source Corda**
- Operational Compatibility with Corda Enterprise 3.0 Developer Preview 3 provides a baseline for wire stability and compatibility with the open-source Corda.
+**Improved Operational Metrics**
- Corda Enterprise 3.0 Developer Preview 3 delivers forward compatibility with future versions of Corda Enterprise:
+ |release| provides additional metrics compared to Corda. A richer collection of information is exported through JMX via :ref:`Jolokia for monitoring <jolokia_ref>`.
+
+**Operational Compatibility With Open Source Corda**
+
+ |release| provides a baseline for wire stability and compatibility with open-source releases of Corda from version 3.0 onwards.
+
+ It delivers forward compatibility with future versions of Corda Enterprise:
- Is operationally compatible with future versions of Corda Enterprise.
- Is upgradeable to future version of Corda Enterprise, preserving transaction and other data.
- Corda Enterprise 3.0 Developer Preview 3 delivers operational compatibility with open-source Corda:
+ It delivers operational compatibility with open-source Corda:
- - Can be used in networks seamlessly transacting with nodes running Corda 3.0 and future versions.
- - Can run CorDapps developed on Corda 3.0 and future versions.
- - Is compatible with ledger data created using Corda 3.0 and future versions.
+ - Can be used in networks seamlessly transacting with nodes running Corda 3.x and future versions.
+ - Can run CorDapps developed on Corda 3.x and future versions. Note that some database changes may be required to achieve this. See :doc:`node-operations-upgrading` for more information.
+ - Is compatible with ledger data created using Corda 3.x and future versions.
+ Furthermore, the RPC client-server communications transport protocol is now fully AMQP based.
-Further improvements and additions
-**********************************
+.. note:: RPC clients communicating with Corda Enterprise nodes must be linked against the enterprise RPC client binaries, because open-source Corda `3.x` does not yet use the AMQP serialisation protocol for RPC communication.
+ From Corda open-source version `4.x` onwards, the RPC client binaries will be compatible with the enterprise distribution.
+
+Further improvements, additions and changes
+*******************************************
+
+* Built-in flows have been improved to automatically utilise the new 'hospital' and retry functionality. For example, the :ref:`FinalityFlow <finality_flow_contract_constraints_ref>` now enables a node operator to easily address contract constraints validation errors when using mixed CorDapp versions. Furthermore, flows will attempt to automatically replay from their last saved checkpoint when, for example, a race condition has occurred for writing into the database or a database deadlock has been encountered. Flows will also retry notarisation attempts if a Highly Available Notary cluster member does not respond within the acceptable time period. There are configuration options which affect the behaviour of the retry functionality. See :doc:`corda-configuration-file` for further details.
+
+* |release| nodes will now fail to start if unknown property keys are found in configuration files. Any unsupported property can be moved to the newly introduced "custom" section. See :doc:`corda-configuration-file` for further details.
-* Corda nodes will now fail to start if unknown property keys are found in configuration files. Any unsupported property can be moved to the newly introduced "custom" section. See :doc:`corda-configuration-file.rst` for further details.
* Property keys with double quotes (e.g. `"key"`) in ``node.conf`` are no longer allowed. See :doc:`corda-configuration-file` for further details.
-* CorDapp specific configuration is now supported. ``CordappContext`` now exposes a ``CordappConfig`` object that is populated
- at CorDapp context creation time from a file source during runtime. See :doc:`cordapp-build-systems` for further details.
-* Flow framework multi-threading enabled, which provides vastly higher performance than Corda 3.0.
-* Additional JMX metrics exported via :ref:`Jolokia for monitoring <jolokia_ref>` and pro-active alert management.
-* Corda's web server now has its own ``web-server.conf`` file, separate from the ``node.conf`` used by the Corda node. See :doc:`corda-configuration-file.rst` for further details. :warning:`This module is deprecated and we aim to remove it in the future.`
+
+* Corda's web server now has its own ``web-server.conf`` file, separate from the ``node.conf`` used by the Corda node. See :doc:`corda-configuration-file` for further details. `Note that this module is deprecated and we intend to remove it in the future.`
+
+* |release| includes a new 'Blob Inspector' tool for viewing the contents of custom binary serialised files (such as ``node-info``, ``network-parameters``) in a human-readable format.
+ See :doc:`blob-inspector` for further details.
+
+* |release| introduces additional network parameters (event horizon) and component run-time validation (maximum allowed message size).
+ The event horizon is the span of time that is allowed to elapse before an offline node is considered to be permanently gone.
+
+* |release| adds certificate revocation list checking when running a node in a fully operational Corda Network environment backed by Network Services.
+ See :doc:`certificate-revocation` for further details.
+
+* |release| nodes support separate configuration parameters for specifying the location of the Doorman and the NetworkMap services independently of each other.
+
+* RPC Server now masks internal errors in responses returned to RPC clients for enhanced privacy.
+
+* Miscellaneous changes to the operation of the network bootstrapper tool, and node configuration changes.
+
Known issues
************
-The following lists known issues identified in this release. We will endeavour to fix these as part of the upcoming General Availability release of Corda Enterprise.
+The following list contains important known issues identified in this release. We will endeavour to fix these in future
+releases of Corda.
-* The database migration tool unnecessarily prints ``{}`` characters at the end of every log line [ENT-1720].
+* Certificate revocation revokes identities, not keys, and is currently irreversible. If your keys are lost or compromised,
+ new keys cannot be re-issued with the same X.500/legal entity name. It is strongly advised to backup your certificates
+ appropriately and to apply sensible policy for management of private keys.
-* Running the database migration tool over a node configured against a local SQLServer instance hosted in Docker results in ``ClassNotFoundException`` exception. [ENT-1717]
+* The finance CorDapp from Corda 3.0 and 3.1 cannot be used with |release|.
+ In a mixed-distribution network the finance CorDapp from |release| should be deployed on both Corda 3.0/3.1 and |release| nodes.
+ This will be fixed in the next release of open source Corda.
-* The database migration tool throws ``org.hibernate.AnnotationException`` in presence of ``MappedSchema`` sub-classes that reference other ``MappedSchema`` sub-classes. [ENT-1712]
+* Explorer GUI does not display correctly HA notaries or multiple notaries.
-* The database migration tool does not support relative paths in the JDBC url. [ENT-1698]
+* Certain characters in X500 party names prevent flows from being started from the shell [CORDA-1635].
-* Doorman crashes ungracefully when started with incorrect or no program arguments. Should display a meaningful message instead. [ENT-1661]
+* Missing configuration files for a network bootstrapper cause an exception [CORDA-1643].
+ Network bootstrapper should gracefully exit with a helpful error message.
-* The finance CorDapp from Open Source versions 3.0 and 3.1 cannot be loaded on Enterprise 3.0 GA. Use the Enterprise CorDapp on any Open Source nodes in a mixed network instead, or use contract whitelisting. [ENT-2040]
+* Java Lambda expressions with named parameters can cause flows to become not startable from shell [CORDA-1658].
-* Exception when starting a Corda node against a non-H2 database the first time. [ENT-1635]
+* Some ``java.time.*`` types cannot be used in mapped (JPA) schemas [CORDA-1392].
- This means the :ref:`database schema management <database_migration_ref>` process should be performed but the exception is confusing.
- Example: ``internal.Node.run - Exception during node startup {} java.lang.IllegalStateException:There are 65 outstanding database changes that need to be run. Please use the provided tools to update the database.``
+* |release| does not support class evolution using non-nullable properties [CORDA-1702].
-* ``CommandWithParties`` should be deprecated and not be used. [ENT-1610]
-
- The involved public keys resolution against known party names is non-deterministic and shouldn't be used as part of transactions' verification.
-
-* Transactions with no inputs and no time window still get "requesting signature by notary service" progress update despite no notarisation is actually involved. [ENT-1574]
-
-* Array of ``JoinColumn`` values for ``JoinColumns`` annotated entities result in compilation error due to Kotlin 1.1 API version. [CORDA-1269]
-
- Example: ``@JoinColumns(value = arrayOf(JoinColumn(name = "cash_txid"), JoinColumn(name = "cash_outidx")))`` does not work.
- Workaround 1: ``JoinColumns(value = *arrayOf(JoinColumn(name = "cash_txid"), JoinColumn(name = "cash_outidx")))`` works.
- Workaround 2: ``@JoinColumns(JoinColumn(name = "cash_txid"), JoinColumn(name = "cash_outidx"))`` also works.
-
-* Coin selection (eg. cash spending) soft locking may deadlock, especially when used together with multi-threading. [ENT-934]
-
- Reserving of states (soft locking) is automatically applied to fungible states before transactions are notarised, to preemptively avoid notarisation clashes to ensure that no two transactions attempt to spend the same fungible assets. Switching off multithreading may reduce the likelihood of failure, to disable multi-threading ensure ``enterpriseConfiguration.useMultiThreadedSMM`` in the node.conf is set to ``false``.
-
-Further notes
+Upgrade notes
*************
As per previous major releases, we have provided a comprehensive upgrade notes (:doc:`upgrade-notes`) to ease the upgrade
-of CorDapps to Corda Enterprise 3.0 Developer Preview. In line with our commitment to API stability, code level changes
-are fairly minimal.
+of CorDapps to |release|. In line with our commitment to API stability, code level changes are fairly minimal.
-From a build perspective, switching CorDapps built using Corda 3.0 to Corda Enterprise 3.0 Developer Preview is mostly effortless,
-and simply requires setting two Gradle build file variables:
+From a build perspective, switching CorDapps built using Corda 3.x to |release| is mostly effortless,
+and simply requires making the Corda Enterprise binaries available to Gradle, and changing two variables in the build file:
-.. sourcecode:: shell
- ext.corda_release_version = 'R3.CORDA-3.0.0-DEV-PREVIEW'
- ext.corda_release_distribution = 'com.r3.corda'
+.. parsed-literal:: shell
-Please note this release is distributed under the evaluation license and should not be used in a Production environment yet.
+ ext.corda_release_version = '|version|'
+ ext.corda_release_distribution = 'com.r3.corda'
-We look forward to hearing your feedback on this release!
+..
+
+Visit the `https://www.r3.com/corda-enterprise <https://www.r3.com/corda-enterprise/>`_ for more information about Corda Enterprise. Customers that have purchased support can access it online at `https://support.r3.com <https://support.r3.com/>`_.
diff --git a/docs/source/upgrade-notes.rst b/docs/source/upgrade-notes.rst
index 505fcb2bd6..b2bffa2541 100644
--- a/docs/source/upgrade-notes.rst
+++ b/docs/source/upgrade-notes.rst
@@ -1,546 +1,131 @@
Upgrading a CorDapp to a new platform version
=============================================
-These notes provide instructions for upgrading your CorDapps from previous versions to :ref:`V3.0 Developer Preview <changelog_r3_v3>` of Corda Enterprise.
+These notes provide instructions for upgrading your CorDapps from previous versions of Corda to version |release|.
.. contents::
- :depth: 3
+ :depth: 1
-General rules
--------------
-Always remember to update the version identifiers in your project gradle file. For example, Corda V3.0 uses:
+Upgrading from Corda Open Source
+--------------------------------
-.. sourcecode:: shell
+A prerequisite to upgrade to |release| is to ensure your CorDapp is upgraded to Open Source Corda 3.x.
+Please follow the instructions in `Corda V3.1 upgrade notes <https://docs.corda.net/releases/release-V3.1/upgrade-notes.html#v3-0-to-v3-1>`_
+and `Corda V3.0 upgrade notes <https://docs.corda.net/releases/release-V3.0/upgrade-notes.html#v2-0-to-v3-0>`_ section to complete this initial step.
- ext.corda_release_version = 'corda-3.0'
- ext.corda_release_distribution = 'net.corda'
- ext.corda_gradle_plugins_version = '3.0.9'
+.. 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.
-It may be necessary to update the version of major dependencies. This will be clearly stated in the upgrade notes for
-a particular version. For example, Corda V3.0 uses:
+Upgrading to |release| from Open Source 3.x requires updating build file properties. For Gradle:
-.. sourcecode:: shell
+.. parsed-literal:: shell
- ext.kotlin_version = '1.1.60'
- ext.quasar_version = '0.7.9'
+ ext.corda_release_distribution = 'com.r3.corda'
+ ext.corda_release_version = '|version|'
+ ext.corda_gradle_plugins_version = '4.0.25'
+..
-Please consult the relevant release notes of the release in question. If not specified, you may assume the
-versions you are currently using are still in force.
-
-We also strongly recommend cross referencing with the :doc:`changelog` to confirm changes.
-
-UNRELEASED
-----------
-
-<<< Fill this in >>>
-
-* API change: ``net.corda.core.schemas.PersistentStateRef`` fields (``index`` and ``txId``) incorrectly marked as nullable are now non-nullable,
- :doc:`changelog` contains the explanation.
-
- H2 database upgrade action:
-
- For Cordapps persisting custom entities with ``PersistentStateRef`` used as non Primary Key column, the backing table needs to be updated,
- In SQL replace ``your_transaction_id``/``your_output_index`` column names with your custom names, if entity didn't used JPA ``@AttributeOverrides``
- then default names are ``transaction_id`` and ``output_index``.
-
- .. sourcecode:: sql
-
- SELECT count(*) FROM [YOUR_PersistentState_TABLE_NAME] WHERE your_transaction_id IS NULL OR your_output_index IS NULL;
-
- In case your table already contains rows with NULL columns, and the logic doesn't distinguish between NULL and an empty string,
- all NULL column occurrences can be changed to an empty string:
-
- .. sourcecode:: sql
-
- UPDATE [YOUR_PersistentState_TABLE_NAME] SET your_transaction_id="" WHERE your_transaction_id IS NULL;
- UPDATE [YOUR_PersistentState_TABLE_NAME] SET your_output_index="" WHERE your_output_index IS NULL;
-
- If all rows have NON NULL ``transaction_ids`` and ``output_idx`` or you have assigned empty string values, then it's safe to update the table:
-
- .. sourcecode:: sql
-
- ALTER TABLE [YOUR_PersistentState_TABLE_NAME] ALTER COLUMN your_transaction_id SET NOT NULL;
- ALTER TABLE [YOUR_PersistentState_TABLE_NAME] ALTER COLUMN your_output_index SET NOT NULL;
-
- If the table already contains rows with NULL values, and the logic caters differently between NULL and an empty string,
- and the logic has to be preserved you would need to create copy of ``PersistentStateRef`` class with different name and use the new class in your entity.
-
- No action is needed for default node tables as ``PersistentStateRef`` is used as Primary Key only and the backing columns are automatically not nullable
- or custom Cordapp entities using ``PersistentStateRef`` as Primary Key.
-
-* H2 database upgrade - the table with a typo has been change, for each database instance and schema run the following SQL statement:
-
- ALTER TABLE [schema].NODE_ATTCHMENTS_CONTRACTS RENAME TO NODE_ATTACHMENTS_CONTRACTS;
-
- Schema is optional, run SQL when the node is not running.
-
-Upgrading to Corda Enterprise 3.0 Developer Preview
----------------------------------------------------
-A prerequisite to upgrade to Corda Enterprise 3.0 is to ensure your CorDapp is upgraded to Open Source Corda V3.x.
-Please follow the instructions in the "Upgrading to V3.x" section to complete this initial step.
-
-Upgrading to Corda Enterprise is now a simple task of updating the version identifiers as follows:
-
-.. sourcecode:: shell
-
- ext.corda_release_distribution = 'com.r3.corda' // Corda Enterprise
- ext.corda_release_version = 'R3.CORDA-3.0.0-DEV-PREVIEW-3' // Corda Enterprise
- ext.corda_gradle_plugins_version = '4.0.9'
-
-and specifying an additional repository entry to point to the location of the Corda Enterprise distribution:
+and specifying an additional repository entry to point to the location of the Corda Enterprise distribution. As an example:
.. sourcecode:: shell
repositories {
maven {
credentials {
- username "r3-corda-dev-preview"
+ username "username"
password "XXXXX"
}
- url 'https://ci-artifactory.corda.r3cev.com/artifactory/r3-corda-releases'
+ url 'https://artifactory.mycompany.com/artifactory/corda-enterprise'
}
}
-Upgrading to V3.x
------------------
+.. note:: |release| 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.
-Please refer to:
-
-* `Corda V3.1 upgrade notes <https://docs.corda.net/releases/release-V3.1/upgrade-notes.html#v3-0-to-v3-1>`_
-
-* `Corda V3.0 upgrade notes <https://docs.corda.net/releases/release-V3.0/upgrade-notes.html#v2-0-to-v3-0>`_
-
-Build
-^^^^^
-
-* Update the version identifiers in your project gradle file(s):
+.. 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:
.. sourcecode:: shell
- ext.corda_release_version = 'corda-3.0' // Corda (Open Source)
- ext.corda_gradle_plugins_version = '4.0.9'
- ext.kotlin_version = '1.2.20'
+ cordaCompile "net.corda:corda-core:$corda_release_version"
-* Add a new release identifier to specify the corda distribution type (Open Source or Corda Enterprise):
+ becomes:
+
+ .. sourcecode:: shell
+
+ cordaCompile "$corda_release_distribution:corda-core:$corda_release_version"
+
+
+|release| uses Kotlin API and language version 1.2. The specifics are
.. sourcecode:: shell
- ext.corda_release_distribution = 'net.corda' // Corda (Open Source)
+ ext.kotlin_version = '1.2.50'
-Network Map Service
-^^^^^^^^^^^^^^^^^^^
+.. 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.
-With the re-designed network map service the following changes need to be made:
+Certificate Revocation List (CRL) support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* The network map is no longer provided by a node and thus the ``networkMapService`` config is ignored. Instead the
- network map is either provided by the compatibility zone (CZ) operator (who operates the doorman) and available
- using the ``compatibilityZoneURL`` config, or is provided using signed node info files which are copied locally.
- See :doc:`network-map` for more details, and :doc:`network-bootstrapper` on how to use the network
- bootstrapper for deploying a local network.
+The newly added feature of certificate revocation (see :doc:`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.
-* Configuration for a notary has been simplified. ``extraAdvertisedServiceIds``, ``notaryNodeAddress``, ``notaryClusterAddresses``
- and ``bftSMaRt`` configs have been replaced by a single ``notary`` config object. See :doc:`corda-configuration-file`
- for more details.
+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.
-* The advertisement of the notary to the rest of the network, and its validation type, is no longer determined by the
- ``extraAdvertisedServiceIds`` config. Instead it has been moved to the control of the network operator via
- the introduction of network parameters. The network bootstrapper automatically includes the configured notaries
- when generating the network parameters file for a local deployment.
+.. 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.
-* Any nodes defined in a ``deployNodes`` gradle task performing the function of the network map can be removed, or the
- ``NetworkMap`` parameter can be removed for any "controller" node which is both the network map and a notary.
+Upgrading from Corda Enterprise 3.0 Developer Preview 3.0
+---------------------------------------------------------
+A limited distribution preview of |release| 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:
-* For registering a node with the doorman the ``certificateSigningService`` config has been replaced by ``compatibilityZoneURL``.
+* Update versions in your build files, for Gradle, as an example:
-Corda Plugins
-^^^^^^^^^^^^^
+ .. parsed-literal:: shell
-* Corda plugins have been modularised further so the following additional gradle entries are necessary:
+ ext.corda_release_version = '|version|'
+ ext.corda_gradle_plugins_version = '4.0.25'
+ ext.kotlin_version = '1.2.50'
+ ..
-.. sourcecode:: shell
+ .. 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.
- dependencies {
- classpath "net.corda.plugins:cordapp:$corda_gradle_plugins_version"
- }
+* For CorDapps depending on the `cordapp-plugin`, version `4.0.25` allows specifying distribution information. As an example:
- apply plugin: 'net.corda.plugins.cordapp'
-
- The plugin needs to be applied in all gradle build files where there is a dependency on Corda using any of:
- cordaCompile, cordaRuntime, cordapp
-
-
-* If you use the Corda quasar-utils plugin (required for testing Corda flows), it is necessary to specify the following
- identifier information in addition to the *dependencies* and *apply* directives:
- (note, this relates to Developer Preview 3 only and will be resolved in the GA release)
-
-.. sourcecode:: shell
-
- ext.quasar_group = 'com.github.corda.quasar'
- ext.quasar_version = '7629695563deae6cc95adcfbebcbc8322fd0241a'
-
- in addition to:
-
- dependencies {
- classpath "net.corda.plugins:quasar-utils:$corda_gradle_plugins_version"
- }
-
- apply plugin: 'net.corda.plugins.quasar-utils'
-
-* Corda Gradle plugins require Gradle version 4.1 or above
-
-* All gradle compile, test, and run-time dependencies (except gradle plugins) to Corda artifacts should now use the
- ``corda_release_distribution`` variable (was previously hardcoded to use ``net.corda``):
-
-.. sourcecode:: shell
-
- dependencies {
-
- // Corda integration dependencies
- cordaCompile "$corda_release_distribution:corda-core:$corda_release_version"
- cordaCompile "$corda_release_distribution:corda-finance:$corda_release_version"
- cordaCompile "$corda_release_distribution:corda-jackson:$corda_release_version"
- cordaCompile "$corda_release_distribution:corda-rpc:$corda_release_version"
- cordaCompile "$corda_release_distribution:corda-node-api:$corda_release_version"
- cordaCompile "$corda_release_distribution:corda-webserver-impl:$corda_release_version"
- cordaRuntime "$corda_release_distribution:corda:$corda_release_version"
- cordaRuntime "$corda_release_distribution:corda-webserver:$corda_release_version"
-
- testCompile "$corda_release_distribution:corda-node-driver:$corda_release_version"
- }
-
-* For existing contract ORM schemas that extend from `CommonSchemaV1.LinearState` or `CommonSchemaV1.FungibleState`,
- you will need to explicitly map the `participants` collection to a database table. Previously this mapping was done in the
- superclass, but that makes it impossible to properly configure the table name.
- The required change is to add the ``override var participants: MutableSet<AbstractParty>? = null`` field to your class, and
- add JPA mappings. For ex., see this example:
-
-.. sourcecode:: kotlin
-
- @Entity
- @Table(name = "cash_states_v2",
- indexes = arrayOf(Index(name = "ccy_code_idx2", columnList = "ccy_code")))
- class PersistentCashState(
-
- @ElementCollection
- @Column(name = "participants")
- @CollectionTable(name="cash_states_v2_participants", joinColumns = arrayOf(
- JoinColumn(name = "output_index", referencedColumnName = "output_index"),
- JoinColumn(name = "transaction_id", referencedColumnName = "transaction_id")))
- override var participants: MutableSet<AbstractParty>? = null,
-
-Configuration
-^^^^^^^^^^^^^
-Applies to both gradle deployNodes tasks and/or corda node configuration (node.conf).
-
-* Remove any references to ``networkMap``.
-
-.. sourcecode:: shell
-
- networkMap "O=Agent,L=Dallas,C=US"
-
-* Remove any references to ``advertisedServices`` (including notaries).
-
-.. sourcecode:: shell
-
- advertisedServices = ["corda.notary.validating"]
-
-* Add an explicit notary definition in the Notary node configuration only:
-
-.. sourcecode:: shell
-
- notary = [validating : true]
-
-* For existing contract ORM schemas that extend from ``CommonSchemaV1.LinearState`` or ``CommonSchemaV1.FungibleState``,
- you will need to explicitly map the ``participants`` collection to a database table. Previously this mapping was done
- in the superclass, but that makes it impossible to properly configure the table name. The required changes are to:
-
- * Add the ``override var participants: MutableSet<AbstractParty>? = null`` field to your class, and
- * Add JPA mappings
-
- For example:
-
- .. sourcecode:: kotlin
-
- @Entity
- @Table(name = "cash_states_v2",
- indexes = arrayOf(Index(name = "ccy_code_idx2", columnList = "ccy_code")))
- class PersistentCashState(
-
- @ElementCollection
- @Column(name = "participants")
- @CollectionTable(name="cash_states_v2_participants", joinColumns = arrayOf(
- JoinColumn(name = "output_index", referencedColumnName = "output_index"),
- JoinColumn(name = "transaction_id", referencedColumnName = "transaction_id")))
- override var participants: MutableSet<AbstractParty>? = null,
-
-* Shell - to use Shell ensure ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present.
-
-Databases
-^^^^^^^^^
-
-Drivers
-~~~~~~~
-
-* Alternative JDBC drivers are not bundled as part of Corda Enterprise releases. If you are running a node on a database different from H2 you need to provide the associated driver as described in :doc:`node-database`.
-
-Testing
-^^^^^^^
-
-Test Framework API stabilisation changes (introduced in Corda V3.0)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* MockNetwork API usage has been greatly simplified.
-
- All references to ``StartedNode<MockNode>`` or ``StartedNode<MockNetwork.MockNode>`` now become ``StartedMockNode``
-
- Calling a flow on a MockNode now becomes ``myMockNode.startFlow(myFlow)``
-
-* MockNode transaction demarcation has been simplified.
-
- All references to ``myMockNode.database.transaction { ... }`` now become ``myMockNode.transaction { ... }``
-
-Please also see `API Testing <https://docs.corda.net/releases/release-V3.0/api-testing.html>`_
-
-Contract tests
-~~~~~~~~~~~~~~
-
-* You must now create a ``MockServices`` object.
-
- ``MockServices`` provides a mock identity, key and storage service. ``MockServices`` takes as its first argument a
- list of the CorDapp packages to scan:
-
- .. sourcecode:: kotlin
-
- private val ledgerServices = MockServices(listOf("net.corda.examples.obligation", "net.corda.testing.contracts"))
-
- ``MockServices`` replaces the use of ``setCordappPackages`` and ``unsetCordappPackages``.
-
-* ``ledger`` is now defined as a ``MockServices`` method. This means that:
-
- .. sourcecode:: kotlin
-
- ledger {
-
- Becomes:
-
- .. sourcecode:: kotlin
-
- ledgerServices.ledger {
-
-* Within a mock ledger transaction, ``ContractState`` instances are passed to ``input`` and ``output`` as objects
- rather than lambdas. For example:
-
- .. sourcecode:: kotlin
-
- ledgerServices.ledger {
- transaction {
- input(OBLIGATION_CONTRACT_ID, DummyState())
- output(OBLIGATION_CONTRACT_ID, oneDollarObligation)
- }
- }
-
-* Within a mock ledger transaction, ``CommandData`` instances are passed to ``input`` and ``output`` as objects
- rather than lambdas, and the public keys must be passed as a list if there is more than one. For example:
-
- .. sourcecode:: kotlin
-
- ledgerServices.ledger {
- transaction {
- command(alice.publicKey, ObligationContract.Commands.Issue())
- command(listOf(alice.publicKey, bob.publicKey), ObligationContract.Commands.Issue())
- }
- }
-
-* The predefined test identities (e.g. ``ALICE`` and ``MINI_CORP``) have been removed.
-
- You must now define the test identities explicitly. For example:
-
- .. sourcecode:: kotlin
-
- val alice = TestIdentity(CordaX500Name(organisation = "Alice", locality = "TestLand", country = "GB"))
-
- ``TestIdentity`` exposes methods to get the ``name``, ``keyPair``, ``publicKey``, ``party`` and ``identity`` of the
- underlying ``TestIdentity``
-
-* Explicit invocation of transaction transformation (ie. using ``TransactionBuilder``) requires serialization engine
- to be initialized. In unit test this can be achieved by using the following jUnit rule:
-
- .. sourcecode:: kotlin
-
- @Rule
- @JvmField
- val testSerialization = SerializationEnvironmentRule()
-
-Flow tests
-~~~~~~~~~~
-
-* The registration mechanism for CorDapps in ``MockNetwork`` unit tests has changed:
-
- * CorDapp registration is now done via the ``cordappPackages`` constructor parameter of MockNetwork.
- This parameter is a list of ``String`` values which should be the package names of the CorDapps containing the contract verification code you wish to load
-
- * The ``unsetCordappPackages`` method is now redundant and has been removed.
-
-* Creation of Notaries in ``MockNetwork`` unit tests has changed.
-
- Previously the API call ``createNotaryNode(legalName = CordaX500ame(...))`` would be used to create a notary:
-
- .. sourcecode:: kotlin
-
- val notary = mockNetwork.createNotaryNode(legalName = CordaX500Name("Notary", "London", "UK"))
-
- Notaries are now defined as part of ``MockNetwork`` creation using a new ``MockNetworkNotarySpec`` class, as in the following example:
-
- .. sourcecode:: kotlin
-
- mockNetwork = MockNetwork(notarySpecs = listOf(MockNetworkNotarySpec(CordaX500Name("Notary","London","UK"))))
-
-* A notary is no longer specified when creating a standard node using the ``createPartyNode`` API call.
-
- Previously:
-
- .. sourcecode:: kotlin
-
- mockNetwork.createPartyNode(notary.network.myAddress, CordaX500Name("Node", "Madrid", "ES"))
-
- Becomes:
-
- .. sourcecode:: kotlin
-
- mockNetwork.createPartyNode(CordaX500Name("Node", "Madrid", "ES"))
-
-* Utility node creation API method ``createSomeNodes(...)`` has been removed, and nodes must be created individually.
-
- Previously:
-
- .. sourcecode:: java
-
- MockNetwork.BasketOfNodes nodes = net.createSomeNodes(3);
- nodeA = nodes.getPartyNodes().get(0);
- nodeB = nodes.getPartyNodes().get(1);
- nodeC = nodes.getPartyNodes().get(2);
-
- Becomes:
-
- .. sourcecode:: java
-
- nodeA = net.createNode(new MockNodeParameters());
- nodeB = net.createNode(new MockNodeParameters());
- nodeC = net.createNode(new MockNodeParameters());
- List<StartedNode<MockNode>> nodes = Arrays.asList(nodeA, nodeB, nodeC);
-
-* Flow framework instantiation of a flow has a slight variation in start syntax:
-
- Previously:
-
- .. sourcecode:: java
-
- CordaFuture<SignedTransaction> future = nodeA.getServices().startFlow(flow).getResultFuture();
-
- Becomes:
-
- .. sourcecode:: java
-
- CordaFuture<SignedTransaction> future = startFlow(nodeA.getServices(), flow).getResultFuture();
-
-* ``StartedNodeServices.startFlow`` must now be imported from ``net.corda.testing.node``
-
-* Do not use ``node.internals`` to register flows:
-
- Previous code would often look as follows:
-
- .. sourcecode:: kotlin
-
- protected fun registerFlowsAndServices(node: StartedNode<MockNetwork.MockNode>) {
- val mockNode = node.internals
- mockNode.registerInitiatedFlow(MyCustomFlow::class.java)
- }
-
- Becomes:
-
- .. sourcecode:: kotlin
-
- protected fun registerFlowsAndServices(mockNode: StartedNode<MockNetwork.MockNode>) {
- mockNode.registerInitiatedFlow(MyCustomFlow::class.java)
- }
-
-* Do not use ``node.internals`` to register Corda services
-
- Previously:
-
- .. sourcecode:: kotlin
-
- node.internals.installCordaService(CustomService::class.java)
-
- Becomes:
-
- .. sourcecode:: kotlin
-
- node.services.cordaService(CustomService::class.java)
-
-Better yet, use node factory to organize both register flows and services, for example, create class as follows:
-
- .. sourcecode:: kotlin
-
- class PrimesOracleNode(args: MockNodeArgs) : MockNetwork.MockNode(args) {
- override fun start() = super.start().apply {
- registerInitiatedFlow(QueryHandler::class.java)
- registerInitiatedFlow(SignHandler::class.java)
- services.cordaService(net.corda.examples.oracle.service.service.Oracle::class.java)
+ .. sourcecode:: groovy
+ cordapp {
+ info {
+ name "My CorDapp"
+ vendor "My Company"
+ version "1.0.1"
}
}
- and then pass it to ``createNode``:
+ .. 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.
- .. sourcecode:: kotlin
+Certificate Revocation List (CRL) support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- val oracle = mockNet.createNode(MockNodeParameters(legalName = CordaX500Name("Oracle", "New York", "US")), ::PrimesOracleNode)
+The newly added feature of certificate revocation (see :doc:`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.
-Node driver
-~~~~~~~~~~~
+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.
-* Driver instantiation now uses a new ``DriverParameters`` data class to encapsulate all available driver options.
-
- For example, previously:
-
- .. sourcecode:: kotlin
-
- driver(isDebug = true, waitForAllNodesToFinish = true) { ...
-
- Becomes:
-
- .. sourcecode:: kotlin
-
- driver(DriverParameters(isDebug = true, waitForAllNodesToFinish = true)) { ...
-
-* ``User`` has been moved from ``net.corda.nodeapi.User`` to ``net.corda.nodeapi.internal.config.User``
-
-* Notaries are defined by passing a list of ``NotarySpec`` objects to ``driver`` using the ``notarySpecs`` argument,
- instead of being defined manually in the driver block.
-
- ``notarySpecs`` defaults to providing a single validating notary
-
-* The ``waitForAllNodesToFinish`` function has been removed. It has been replaced with a ``waitForAllNodesToFinish``
- argument to ``driver``
-
-* No longer specify advertised services to the ``DriverDSL`` when starting nodes:
-
- Previously:
-
- .. sourcecode:: kotlin
-
- driver {
- startNode(providedName = CordaX500Name("Controller", "London", "GB"), advertisedServices = setOf(ServiceInfo(ValidatingNotaryService.type)))
-
- Becomes:
-
- .. sourcecode:: kotlin
-
- driver {
- startNode(providedName = CordaX500Name("Controller", "London", "GB")),
-
-Finance
-^^^^^^^
-
-* ``CASH_PROGRAM_ID`` has been moved to ``Cash.PROGRAM_ID``, where ``Cash`` is defined in the
- ``import net.corda.finance.contracts.asset`` package
+.. 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.
\ No newline at end of file