ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-01-18 18:56:28 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge pull request #2955 from corda/kat/release/merge-3.1-releasenotes

Browse Source 
Kat/release/merge 3.1 releasenotes
This commit is contained in:
Katelyn Baker 2018-04-11 16:50:19 +01:00 committed by GitHub
commit 72bd530b11
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 267 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/source/changelog.rst
View File

@ -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 <https://github.com/corda/corda-gradle-plugins/tree/master/api-scanner>`_.
* 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:

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

@ -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 <https://github.com/bret540>`_ 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 <https://github.com/lukehutch/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 <https://r3-cev.atlassian.net/browse/CORDA-1295>`_]
* Flaky startup, no db transaction in context, when using postgresql [`CORDA-1276 <https://r3-cev.atlassian.net/browse/CORDA-1276>`_]
* Corda's JPA classes should not be final or have final methods [`CORDA-1267 <https://r3-cev.atlassian.net/browse/CORDA-1267>`_]
* Backport api-scanner changes [`CORDA-1178 <https://r3-cev.atlassian.net/browse/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!

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

@ -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:
@ -54,10 +133,65 @@ UNRELEASED
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.
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<N>`` 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 - "<some parameter of a constructor>" - doesn't refer to a property of "class <some.class.being.serialized>"``
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:
@ -67,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
------------
@ -405,4 +580,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``)
* Adjust imports of the associated flows (``Cash*Flow``, ``TwoPartyTradeFlow``, ``TwoPartyDealFlow``)