ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-06-05 09:00:53 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Updates to master after GA release (#1167)

Browse Source
This commit is contained in:
Michele Sollecito 2018-07-03 10:25:13 +01:00 committed by GitHub
parent 7c7acc216c
commit 6c0ac1217c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 177 additions and 576 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
build.gradle
View File

@ -14,7 +14,7 @@ buildscript {
file("$projectDir/constants.properties").withInputStream { constants.load(it) } file("$projectDir/constants.properties").withInputStream { constants.load(it) }
// Our version: bump this on release. // 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" ext.corda_release_distribution = "com.r3.corda"
// Increment this on any release that changes public APIs anywhere in the Corda platform // Increment this on any release that changes public APIs anywhere in the Corda platform

174
docs/source/release-notes.rst
View File

@ -1,21 +1,19 @@
Release notes 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 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.
stated otherwise (e.g., where referencing Developer Preview 3). |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 |release| is operationally compatible with Open Source Corda 3.x while providing enterprise-grade features and performance.
--------------------------------------
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.
Key new features and components 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: 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. - 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. - Continuity of flows throughout node failures.
- Support for rolling software upgrades in a live network. - 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**: **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.
: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. Database settings can be specified as part of the node configuration file.
See :doc:`node-database` for further details. See :doc:`node-database` for further details.
* **Database Migration Tool**: **Database Management and 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. |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. 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. 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, 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. 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, 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 doorman, network map server) configured within an operational Corda network to be interoperable and compatible with
each other. 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**: **Corda Firewall**
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.
* **Signing Service**: |release| introduces the Bridge and Corda Firewall components to enable secure setup of a Corda Node in a DMZ environment.
Corda Enterprise 3.0 Developer Preview supports external Hardware Security Module (HSM) integration for certificate issuing and data signing. See :doc:`Corda Firewall Overview <corda-firewall>` for further details.
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.
* **Operational Compatibility With Open Source Corda** **Improved Operational Metrics**
Operational Compatibility with Corda Enterprise 3.0 Developer Preview 3 provides a baseline for wire stability and compatibility with the open-source Corda.
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 operationally compatible with future versions of Corda Enterprise.
- Is upgradeable to future version of Corda Enterprise, preserving transaction and other data. - 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 be used in networks seamlessly transacting with nodes running Corda 3.x and future versions.
- Can run CorDapps developed on Corda 3.0 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.0 and future versions. - 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. * 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. * 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.`
* 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. * |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.
* 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.` 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 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. * |release| does not support class evolution using non-nullable properties [CORDA-1702].
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.``
* ``CommandWithParties`` should be deprecated and not be used. [ENT-1610] Upgrade notes
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
************* *************
As per previous major releases, we have provided a comprehensive upgrade notes (:doc:`upgrade-notes`) to ease the upgrade 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 of CorDapps to |release|. In line with our commitment to API stability, code level changes are fairly minimal.
are fairly minimal.
From a build perspective, switching CorDapps built using Corda 3.0 to Corda Enterprise 3.0 Developer Preview is mostly effortless, From a build perspective, switching CorDapps built using Corda 3.x to |release| is mostly effortless,
and simply requires setting two Gradle build file variables: 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' .. parsed-literal:: shell
ext.corda_release_distribution = 'com.r3.corda'
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/>`_.

577
docs/source/upgrade-notes.rst
View File

@ -1,546 +1,131 @@
Upgrading a CorDapp to a new platform version 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:: .. contents::
:depth: 3 :depth: 1
General rules Upgrading from Corda Open Source
------------- --------------------------------
Always remember to update the version identifiers in your project gradle file. For example, Corda V3.0 uses:
.. 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' .. note::
ext.corda_release_distribution = 'net.corda' There is no requirement to upgrade your CorDapp to Corda Enterprise in order to run it on Corda Enterprise. If
ext.corda_gradle_plugins_version = '3.0.9' 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 Upgrading to |release| from Open Source 3.x requires updating build file properties. For Gradle:
a particular version. For example, Corda V3.0 uses:
.. sourcecode:: shell .. parsed-literal:: shell
ext.kotlin_version = '1.1.60' ext.corda_release_distribution = 'com.r3.corda'
ext.quasar_version = '0.7.9' 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 and specifying an additional repository entry to point to the location of the Corda Enterprise distribution. As an example:
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:
.. sourcecode:: shell .. sourcecode:: shell
repositories { repositories {
maven { maven {
credentials { credentials {
username "r3-corda-dev-preview" username "username"
password "XXXXX" 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: .. 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:
* `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):
.. sourcecode:: shell .. sourcecode:: shell
ext.corda_release_version = 'corda-3.0' // Corda (Open Source) cordaCompile "net.corda:corda-core:$corda_release_version"
ext.corda_gradle_plugins_version = '4.0.9'
ext.kotlin_version = '1.2.20'
* 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 .. 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 The newly added feature of certificate revocation (see :doc:`certificate-revocation`) introduces a few changes to the node configuration.
network map is either provided by the compatibility zone (CZ) operator (who operates the doorman) and available In the configuration file it is required to explicitly specify how strictly the node should apply the CRL check. For that purpose the `crlCheckSoftFail`
using the ``compatibilityZoneURL`` config, or is provided using signed node info files which are copied locally. parameter is now expected to be set explicitly in the node's SSL configuration.
See :doc:`network-map` for more details, and :doc:`network-bootstrapper` on how to use the network Setting the `crlCheckSoftFail` to true, relaxes the CRL checking policy. In this mode, the SSL communication
bootstrapper for deploying a local network. 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`` Older versions of Corda do not have CRL distribution points embedded in the SSL certificates.
and ``bftSMaRt`` configs have been replaced by a single ``notary`` config object. See :doc:`corda-configuration-file` As such, in order to be able to reuse node and SSL certificates generated in those versions of Corda, the `crlCheckSoftFail` needs
for more details. 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 .. note::
``extraAdvertisedServiceIds`` config. Instead it has been moved to the control of the network operator via Mitigation of this issue and thus being able to use the `strict` mode (i.e. with `crlCheckSoftFail` = false)
the introduction of network parameters. The network bootstrapper automatically includes the configured notaries of the CRL checking with the certificates generated in previous versions of Corda is going to be added in the near future.
when generating the network parameters file for a local deployment.
* Any nodes defined in a ``deployNodes`` gradle task performing the function of the network map can be removed, or the Upgrading from Corda Enterprise 3.0 Developer Preview 3.0
``NetworkMap`` parameter can be removed for any "controller" node which is both the network map and a notary. ---------------------------------------------------------
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 { * For CorDapps depending on the `cordapp-plugin`, version `4.0.25` allows specifying distribution information. As an example:
classpath "net.corda.plugins:cordapp:$corda_gradle_plugins_version"
}
apply plugin: 'net.corda.plugins.cordapp' .. sourcecode:: groovy
cordapp {
The plugin needs to be applied in all gradle build files where there is a dependency on Corda using any of: info {
cordaCompile, cordaRuntime, cordapp name "My CorDapp"
vendor "My Company"
version "1.0.1"
* 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)
} }
} }
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. .. note::
Mitigation of this issue and thus being able to use the `strict` mode (i.e. with `crlCheckSoftFail` = false)
For example, previously: of the CRL checking with the certificates generated in previous versions of Corda is going to be added in the near future.
.. 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