From 760cc1ec48acaa966b5c7893251576c91f342829 Mon Sep 17 00:00:00 2001 From: Katelyn Baker Date: Wed, 11 Apr 2018 13:05:50 +0100 Subject: [PATCH 1/2] RELEASE - merge v3.1 release notes / upgrade notes / changelog to master (#2937) * RELEASE - 3.1 upgrade and release notes * Update docs for change to vno * address vno change in release notes * Update release-notes.rst * make corda links * Review comments * Review comments * review comments * remove ref to reverted bugfix * Review comments --- docs/source/changelog.rst | 42 ++++++++++++------ docs/source/release-notes.rst | 59 +++++++++++++++++++++++++ docs/source/upgrade-notes.rst | 81 ++++++++++++++++++++++++++++++++++- 3 files changed, 169 insertions(+), 13 deletions(-) diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 64cd538e2d..9e239532b1 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -5,7 +5,16 @@ Here's a summary of what's changed in each Corda release. For guidance on how to release, see :doc:`upgrade-notes`. Unreleased ----------- +========== + +* java.security.cert.CRLReason added to the default Whitelist. + +* java.security.cert.X509CRL serialization support added. + +* Upgraded H2 to v1.4.197. + +* Shell (embedded available only in dev mode or via SSH) connects to the node via RPC instead of using the ``CordaRPCOps`` object directly. + To enable RPC connectivity ensure node’s ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present. * Errors thrown by a Corda node will now reported to a calling RPC client with attention to serialization and obfuscation of internal data. @@ -19,16 +28,12 @@ Unreleased only once when it was created. Whilst registering serializers that already exist is essentially a no-op, it's a performance overhead for a very frequent operation that hits a synchronisation point (and is thus flagged as contended by our perfomance suite) -* Update the fast-classpath-scanner dependent library version from 2.0.21 to 2.12.3 - - .. note:: Whilst this is not the latest version of this library, that being 2.18.1 at time of writing, versions later - than 2.12.3 (including 2.12.4) exhibit a different issue. - * Node can be shut down abruptly by ``shutdown`` function in `CordaRPCOps` or gracefully (draining flows first) through ``gracefulShutdown`` command from shell. * Carpenter Exceptions will be caught internally by the Serializer and rethrown as a ``NotSerializableException`` - * Specific details of the error encountered are logged to the node's log file. More information can be enabled by setting the debug level to ``trace`` ; this will cause the full stack trace of the error to be dumped into the log. + * Specific details of the error encountered are logged to the node's log file. More information can be enabled by setting the debug level to + ``trace`` ; this will cause the full stack trace of the error to be dumped into the log. * Parsing of ``NodeConfiguration`` will now fail if unknown configuration keys are found. @@ -40,14 +45,27 @@ Unreleased * java.math.BigInteger serialization support added. -* java.security.cert.CRLReason added to the default Whitelist. +.. _changelog_v3.1: -* java.security.cert.X509CRL serialization support added. +Version 3.1 +----------- -* Upgraded H2 to v1.4.197. +* Update the fast-classpath-scanner dependent library version from 2.0.21 to 2.12.3 -* Shell (embedded available only in dev mode or via SSH) connects to the node via RPC instead of using the ``CordaRPCOps`` object directly. - To enable RPC connectivity ensure node’s ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present. + .. note:: Whilst this is not the latest version of this library, that being 2.18.1 at time of writing, versions later + than 2.12.3 (including 2.12.4) exhibit a different issue. + +* Updated the api scanner gradle plugin to work the same way as the version in master. These changes make the api scanner more + accurate and fix a couple of bugs, and change the format of the api-current.txt file slightly. Backporting these changes + to the v3 branch will make it easier for us to ensure that apis are stable for future versions. These changes are + released in gradle plugins version 3.0.10. For more information on the api scanner see + the `documentation `_. + +* Fixed security vulnerability when using the ``HashAttachmentConstraint``. Added strict check that the contract JARs + referenced in a transaction were deployed on the node. + +* Fixed node's behaviour on startup when there is no connectivity to network map. Node continues to work normally if it has + all the needed network data, waiting in the background for network map to become available. .. _changelog_v3: diff --git a/docs/source/release-notes.rst b/docs/source/release-notes.rst index 40455396f8..fba39537be 100644 --- a/docs/source/release-notes.rst +++ b/docs/source/release-notes.rst @@ -1,6 +1,61 @@ Release notes ============= +.. _release_notes_v3_1: + +Release 3.1 +----------- + +This rapid follow-up to Corda 3.0 corrects an issue discovered by some users of Spring Boot and a number of other +smaller issues discovered post release. All users are recommended to upgrade. + +Special Thanks +~~~~~~~~~~~~~~ + +Without passionate and engaged users Corda would be all the poorer. As such, we are extremely grateful to +`Bret Lichtenwald `_ for helping nail down a reproducible test case for the +Spring Boot issue. + +Major Bug Fixes +~~~~~~~~~~~~~~~ + +* **Corda Serialization fails with "Unknown constant pool tag"** + + This issue is most often seen when running a CorDapp with a Rest API using / provided by ``Spring Boot``. + + The fundamental cause was ``Corda 3.0`` shipping with an out of date dependency for the + `fast-classpath-scanner `_ library, where the manifesting + bug was already fixed in a released version newer than our dependant one. In response, we've updated our dependent + version to one including that bug fix. + +* **Corda Versioning** + + Those eagle eyed amongst you will have noticed for the 3.0 release we altered the versioning scheme from that used by previous Corda + releases (1.0.0, 2.0.0, etc) with the addition of an prepended product name, resulting in ``corda-3.0``. The reason for this was so + that developers could clearly distinguish between the base open source platform and any distributions based on on Corda that may + be shipped in the future (including from R3), However, we have heard the complaints and feel the pain that's caused by various + tools not coping well with this change. As such, from now on the versioning scheme will be inverted, with this release being ``3.1-corda``. + + As to those curious as to why we dropped the patch number from the version string, the reason is very simple: there won't + be any patches applied to a release of Corda. Either a release will be a collection of bug fixes and non API breaking + changes, thus eliciting a minor version bump as with this release, or major functional changes or API additions and warrant + a major version bump. Thus, rather than leave a dangling ``.0`` patch version on every release we've just dropped it. In the + case where a major security flaw needed addressing, for example, then that would generate a release of a new minor version. + +Issues Fixed +~~~~~~~~~~~~ + +* RPC server leaks if a single client submits a lot of requests over time [`CORDA-1295 `_] +* Flaky startup, no db transaction in context, when using postgresql [`CORDA-1276 `_] +* Corda's JPA classes should not be final or have final methods [`CORDA-1267 `_] +* Backport api-scanner changes [`CORDA-1178 `_] +* Misleading error message shown when node is restarted after the flag day +* Hash constraints not working from Corda 3.0 onwards +* Serialisation Error between Corda 3 RC01 and Corda 3 +* Nodes don't start when network-map/doorman is down + +.. _release_notes_v3_0: + Release 3.0 ----------- @@ -294,6 +349,8 @@ Minor Changes * Numerous bug fixes and documentation tweaks. * Removed dependency on Jolokia WAR file. +.. _release_notes_v2_0: + Release 2.0 ----------- Following quickly on the heels of the release of Corda 1.0, Corda version 2.0 consolidates @@ -313,6 +370,8 @@ Adds the facility for transparent forwarding of transactions to some third party that entity simply run an Observer node they can simply recieve a stream of digitally signed, de-duplicated reports that can be used for reporting. +.. _release_notes_v1_0: + Release 1.0 ----------- Corda 1.0 is finally here! diff --git a/docs/source/upgrade-notes.rst b/docs/source/upgrade-notes.rst index 28d303566a..2f112d3f4c 100644 --- a/docs/source/upgrade-notes.rst +++ b/docs/source/upgrade-notes.rst @@ -31,6 +31,85 @@ We also strongly recommend cross referencing with the :doc:`changelog` to confir UNRELEASED ---------- +<<< Fill this in >>> + +v3.0 to v3.1 +------------ + +Gradle Plugin Version +^^^^^^^^^^^^^^^^^^^^^ + +Corda 3.1 uses version 3.1.0 of the gradle plugins and your ``build.gradle`` file should be updated to reflect this. + +.. sourcecode:: shell + + ext.corda_gradle_plugins_version = '3.1.0' + +You will also need to update the ``corda_release_version`` identifier in your project gradle file. + +.. sourcecode:: shell + + ext.corda_release_version = '3.1-corda' + +V2.0 to V3.0 +------------ + +Gradle Plugin Version +^^^^^^^^^^^^^^^^^^^^^ + +Corda 3.0 uses version 3.0.9 of the gradle plugins and your ``build.gradle`` file should be updated to reflect this. + +.. sourcecode:: shell + + ext.corda_gradle_plugins_version = '3.0.9' + +You will also need to update the ``corda_release_version`` identifier in your project gradle file. + +.. sourcecode:: shell + + ext.corda_release_version = 'corda-3.0' + +Network Map Service +^^^^^^^^^^^^^^^^^^^ + +With the re-designed network map service the following changes need to be made: + +* 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:`setting-up-a-corda-network.rst` on how to use the network + bootstrapper for deploying a local network. + +* 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. + +* 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. + +* 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. + +* For registering a node with the doorman the ``certificateSigningService`` config has been replaced by ``compatibilityZoneURL``. + +Corda Plugins +^^^^^^^^^^^^^ + +* Corda plugins have been modularised further so the following additional gradle entries are necessary: + For example: + + .. sourcecode:: groovy + dependencies { + classpath "net.corda.plugins:cordapp:$corda_gradle_plugins_version" + } + + 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 + * 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: @@ -405,4 +484,4 @@ Finance * Adjust imports of Cash flow references * Adjust the ``StartFlow`` permission in ``gradle.build`` files - * Adjust imports of the associated flows (``Cash*Flow``, ``TwoPartyTradeFlow``, ``TwoPartyDealFlow``) \ No newline at end of file + * Adjust imports of the associated flows (``Cash*Flow``, ``TwoPartyTradeFlow``, ``TwoPartyDealFlow``) From 91fd40c8061e06101aef2dc5bca5d123e00b0e13 Mon Sep 17 00:00:00 2001 From: Katelyn Baker Date: Wed, 11 Apr 2018 15:37:47 +0100 Subject: [PATCH 2/2] RELEASE: Merge V3.0 upgrade notes to master This should've been done at release... I clearly missed back-merging this file --- docs/source/upgrade-notes.rst | 100 +++++++++++++++++++++++++++++++++- 1 file changed, 98 insertions(+), 2 deletions(-) diff --git a/docs/source/upgrade-notes.rst b/docs/source/upgrade-notes.rst index 2f112d3f4c..b9634d252e 100644 --- a/docs/source/upgrade-notes.rst +++ b/docs/source/upgrade-notes.rst @@ -133,10 +133,65 @@ cordaCompile, cordaRuntime, cordapp JoinColumn(name = "transaction_id", referencedColumnName = "transaction_id"))) override var participants: MutableSet? = null, -* Shell - to use Shell ensure ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present. +AMQP +^^^^ + +Whilst the enablement of AMQP is a transparent change, as noted in the :doc:`serialization` documentation +the way classes, and states in particular, should be written to work with this new library may require some +alteration to your current implementation. + + * With AMQP enabled Java classes must be compiled with the -parameter flag. + + * If they aren't, then the error message will complain about ``arg`` being an unknown parameter. + * If recompilation is not viable, a custom serializer can be written as per :doc:`cordapp-custom-serializers` + * It is important to bear in mind that with AMQP there must be an implicit mapping between constructor + parameters and properties you wish included in the serialized form of a class. + + * See :doc:`serialization` for more information + + * Error messages of the form + + ``Constructor parameter - "" - doesn't refer to a property of "class "`` + + indicate that a class, in the above example ``some.class.being.serialized``, has a parameter on its primary constructor that + doesn't correlate to a property of the class. This is a problem because the Corda AMQP serialization library uses a class's + constructor (default, primary, or annotated) as the means by which instances of the serialized form are reconstituted. + + See the section "Mismatched Class Properties / Constructor Parameters" in the :doc:`serialization` documentation + +Database schema changes +^^^^^^^^^^^^^^^^^^^^^^^ + +An H2 database instance (represented on the filesystem as a file called `persistence.mv.db`) used in Corda 1.0 or 2.0 +cannot be directly reused with Corda 3.0 due to minor improvements and additions to stabilise the underlying schemas. + +Configuration +^^^^^^^^^^^^^ + +Nodes that do not require SSL to be enabled for RPC clients now need an additional port to be specified as part of their configuration. +To do this, add a block as follows to the nodes configuraiton: + + .. sourcecode:: script + + rpcSettings { + adminAddress "localhost:10007" + } + +to `node.conf` files. + +Also, the property `rpcPort` is now deprecated, so it would be preferable to substitute properties specified that way e.g., `rpcPort=10006` with a block as follows: + + .. sourcecode:: script + + rpcSettings { + address "localhost:10006" + adminAddress "localhost:10007" + } + +Equivalent changes should be performed on classes extending `CordformDefinition`. Testing -~~~~~~~ +^^^^^^^ * The registration mechanism for CorDapps in ``MockNetwork`` unit tests has changed: @@ -146,6 +201,47 @@ Testing * The ``unsetCordappPackages`` method is now redundant and has been removed +* Many classes have been moved between packages, so you will need to update your imports + + .. tip:: We have provided a several scripts (depending upon your operating system of choice) to smooth the upgrade + process for existing projects. This can be found at ``tools\scripts\update-test-packages.sh`` for the Bash shell and + ``tools/scripts/upgrade-test-packages.ps1`` for Windows Power Shell users in the source tree + +* setCordappPackages and unsetCordappPackages have been removed from the ledger/transaction DSL and the flow test framework, + and are now set via a constructor parameter or automatically when constructing the MockServices or MockNetwork object + +* Key constants e.g. ``ALICE_KEY`` have been removed; you can now use TestIdentity to make your own + +* The ledger/transaction DSL must now be provided with MockServices as it no longer makes its own + * In transaction blocks, input and output take their arguments as ContractStates rather than lambdas + * Also in transaction blocks, command takes its arguments as CommandDatas rather than lambdas + +* The MockServices API has changed; please refer to its API documentation + +* TestDependencyInjectionBase has been retired in favour of a JUnit Rule called SerializationEnvironmentRule + * This replaces the initialiseSerialization parameter of ledger/transaction and verifierDriver + * The withTestSerialization method is obsoleted by SerializationEnvironmentRule and has been retired + +* MockNetwork now takes a MockNetworkParameters builder to make it more Java-friendly, like driver's DriverParameters + * Similarly, the MockNetwork.createNode methods now take a MockNodeParameters builder + +* MockNode constructor parameters are now aggregated in MockNodeArgs for easier subclassing + +* MockNetwork.Factory has been retired as you can simply use a lambda + +* testNodeConfiguration has been retired, please use a mock object framework of your choice instead + +* MockNetwork.createSomeNodes and IntegrationTestCategory have been retired with no replacement + +* Starting a flow can now be done directly from a node object. Change calls of the form ``node.getServices().startFlow(...)`` + to ``node.startFlow(...)`` + +* Similarly a tranaction can be executed directly from a node object. Change calls of the form ``node.getDatabase().transaction({ it -> ... })`` + to ``node.transaction({() -> ... })`` + +* ``startFlow`` now returns a ``CordaFuture``, there is no need to call ``startFlow(...).getResultantFuture()`` + + V1.0 to V2.0 ------------