ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-26 16:11:12 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merged release notes, upgrade notes, and changelog from DP3 release branch to master. (#740)

Browse Source
This commit is contained in:
josecoll 2018-04-16 16:05:08 +01:00 committed by GitHub
parent 060fee84ab
commit 89aa2b57e5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 228 additions and 638 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/source/changelog.rst
View File

@ -7,8 +7,7 @@ release, see :doc:`upgrade-notes`.
Unreleased
----------
* Fix CORDA-1229. Setter-based serialization was broken with generic types when the property was stored
as the raw type, List for example.
* Upgraded H2 to v1.4.197.
* The network bootstrapper uses the existing network parameters file to update the current contracts whitelist, and no longer
needs the whitelist.txt file.
@ -30,13 +29,25 @@ Unreleased
.. 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.
* 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.
* Node can be shut down abruptly by ``shutdown`` function in `CordaRPCOps` or gracefully (draining flows first) through ``gracefulShutdown`` command from shell.
.. _changelog_r3_v3:
R3 Corda 3.0 Developer Preview
------------------------------
* Fix CORDA-1229. Setter-based serialization was broken with generic types when the property was stored as the raw type, List for example.
* 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.
* Fixed security vulnerability when using the ``HashAttachmentConstraint``. Added strict check that the contract JARs
referenced in a transaction were deployed on the node.
* Node can be shut down abruptly by ``shutdown`` function in `CordaRPCOps` or gracefully (draining flows first) through ``gracefulShutdown`` command from shell. Please refer to ::doc:`shell.rst` for more.
* Carpenter Exceptions will be caught internally by the Serializer and rethrown as a ``NotSerializableException``
@ -56,7 +67,9 @@ Unreleased
* java.security.cert.X509CRL serialization support added.
* Upgraded H2 to v1.4.197.
* Added ``NetworkMapCache.getNodesByLegalName`` for querying nodes belonging to a distributed service such as a notary cluster
where they all share a common identity. ``NetworkMapCache.getNodeByLegalName`` has been tightened to throw if more than
one node with the legal name is found.
* Per CorDapp configuration is now exposed. ``CordappContext`` now exposes a ``CordappConfig`` object that is populated
at CorDapp context creation time from a file source during runtime.
@ -95,13 +108,6 @@ Unreleased
* JDBC drivers for SQL server and PostgresSQL are no longer bundled as part of Corda releases. If you are running a node
on such databases you need to provide the associated driver as described in :doc:`node-database`.
* Shell (embedded shell 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.
R3 Corda 3.0 Developer Preview
------------------------------
* X.509 certificates now have an extension that specifies the Corda role the certificate is used for, and the role
hierarchy is now enforced in the validation code. See ``net.corda.core.internal.CertRole`` for the current implementation
until final documentation is prepared. Certificates at ``NODE_CA``, ``WELL_KNOWN_SERVICE_IDENTITY`` and above must
@ -290,6 +296,9 @@ R3 Corda 3.0 Developer Preview
will help make it clearer which parts of the api are stable. Scripts have been provided to smooth the upgrade
process for existing projects in the ``tools\scripts`` directory of the Corda repo.
* 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.
.. _changelog_v2:
Corda 2.0
@ -549,4 +558,4 @@ Corda 1.0
* ``@RPCSinceVersion``, ``RPCException`` and ``PermissionException`` have moved to ``net.corda.client.rpc``.
* Current implementation of SSL in ``CordaRPCClient`` has been removed until we have a better solution which doesn't rely
on the node's keystore.
on the node's keystore.

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

@ -3,278 +3,133 @@ Release notes
R3 Corda 3.0 Developer Preview
------------------------------
This Developer Preview takes us towards the launch of R3 Corda, R3's commercially supported enterprise blockchain platform.
This release is an early access preview of R3 Corda 3.0 - a commercial distribution of Corda blockchain platform designed for mission critical enterprise deployments.
Whilst the recent major releases of **Corda** ("Open Source") - V1.0 and V2.0 - have focused on providing API stability and
functionality, **R3 Corda** has been primarily focused on non-functional aspects of the platform: performance, scalability,
robustness, security, configurability, manageability, supportability and upgradeability.
R3 Corda 3.0 Developer Preview adds enterprise features to 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.
Here is a summary of some of the key new features in this preview, many of which will also appear in the next open
source release:
Key new features and components
*******************************
- support for :ref:`Azure SQL and SQL Server 2017 <sql_server_ref>` databases.
- integrated :ref:`database schema management <database_migration_ref>` tooling using `Liquibase <http://www.liquibase.org/>`_
- completely re-designed :doc:`network-map` Service.
- enabled :ref:`AMQP serialization <amqp_ref>` for peer to peer messaging, and vault transaction storage.
- pluggable :ref:`user authentication <authentication_ref>` and :ref:`fine-grained access control <rpc_security_mgmt_ref>`.
- re-designed Flow Framework manager in preparation for fully multi-threaded implementation.
- improvements to the Doorman certificate issuance process (including integration with HSMs).
- additional JMX metrics exported via :ref:`Jolokia for monitoring <jolokia_ref>` and pro-active alert management.
- a secure, remotely accessible, :ref:`SSH server <ssh_server>` in the node with built-in authorization and permissioning to enable remote
node administration without requiring console access to the underlying operating system.
- re-architected and re-designed Corda bridge management for secure P2P connectivity between participants.
- enhanced Explorer tool with new :ref:`flow triage <flow_triage>` user interface panel to visualize all currently running flows.
- preliminary implementation of Business Networks concept (a private sub group within a Corda Compatibility Zone).
* **High Availability**:
This release introduces the Hot-Cold High Availability configuration for R3 Corda nodes, which addresses the following requirements:
We also continue to make improvements in usability of our Test Framework APIs in preparation for declaring the test
framework API stable (in addition to the already-stabilised core APIs).
- A logical Corda node continues to be available as long as at least one of the clustered physical nodes is available.
- No loss, corruption or duplication of data on the ledger due to component outages.
- Continuity of flows throughout node failures.
- Support for rolling software upgrades in a live network.
Significant changes implemented in reaching this Developer Preview include:
See :ref:`here <hot-cold_ref>` for further details on how to set-up and operate Hot-Cold node HA.
* **AMQP**:
AMQP Serialization is now enabled for both peer to peer communication and the writing of states to the vault. This
change brings a serialisation format that will allow us to deliver enhanced security and wire stability. It is a key
prerequisite to enabling different Corda node versions to coexist on the same network and to enable easier upgrades.
* **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.
Database settings can be specified as part of the node configuration file.
See :doc:`node-database` for further details.
Details on the AMQP serialization framework can be found :ref:`here <amqp_ref>`. This provides an introduction and
overview of the framework whilst more specific details on object evolution as it relates to serialization is similarly
found in :doc:`serialization-default-evolution` and :doc:`serialization-enum-evolution` respectively.
.. note:: This release delivers the bulk of our transition from Kryo serialisation to AMQP serialisation. This means that many of the restrictions
that were documented in previous versions of Corda are now enforced.
In particular, you are advised to review the section titled :ref:`Custom Types <amqp_custom_types_ref>`.
To aid with the transition, we have included support in this release for default construction and instantiation of
objects with inaccessible private fields, but it is not guaranteed that this support will continue into future versions;
the restrictions documented at the link above are the canonical source.
* **Database Migration Tool**:
R3 Corda 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 R3 Corda or installed CorDapps while preserving data integrity and service continuity.
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**:
This release introduces the new network map architecture. The network map service has been completely redesigned and
implemented 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.
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.
We introduce the concept of network parameters, which will be used in a future version of Corda to specify precisely
the set of constants (or ranges of constants) upon which a set of nodes need to agree in order to be assured of seamless
inter-operation. Additional security controls ensure that all network map data is now signed, thus reducing the power
of the network operator to tamper with the map.
This release also adds Hardware Security Module (HSM) support to the doorman service (certificate authority).
By integrating with external HSMs, we have further strengthened the security of issuing network certificates and
signing of network map related data.
Further information can be found in the :doc:`changelog` and :doc:`network-map` documentation.
* **Third party database support**:
R3 Corda has been tested against Azure SQL and SQL Server 2017 databases (in addition to the existing default support
of H2 for development mode). This preview adds preliminary support for :ref:`PostgreSQL 9.6 <postgres_ref>`.
Support for Oracle 11g RC02 and Oracle 12c is currently under development. All required database settings can be
specified in the node configuration file. For configuration details see :doc:`node-database`.
* **Integrated database migration tooling**:
We have adopted and integrated `Liquibase <http://www.liquibase.org/>`_ , an open source database-independent library
for tracking, managing and applying database schema changes in order to ease the evolution (creation and migration) of
CorDapp custom contract schemas and facilitate the operational administration of a Corda nodes database.
We provide tooling to export DDL and data (as SQL statements) to a file to be inspected and/or manually applied by a DBA.
Please see :ref:`database migration <database_migration_ref>` for further details.
* **Pluggable user authentication and fine-grained access control**:
All RPC functions are now subject to permission checks (previously these only applied when starting flows).
We have also included experimental support for external user credentials data source and password encryption using the
`Apache Shiro <https://shiro.apache.org>`_ framework. Please see :ref:`RPC security management <rpc_security_mgmt_ref>` for further details.
* **Preliminary preview of new bridge management functionality**:
The bridge manager component is responsible for dynamically establishing remote connectivity with participant nodes
in a Corda peer to peer network. A new Bridge manager has been designed and implemented to be used integrally
within a :ref:`Corda node <config_amqp_bridge>` or deployed (in the final R3 Corda 3.0 release) as a standalone component in DMZ operational deployments,
where security concerns require separation of infrastructure messaging subsystems.
* **Preliminary preview of flow triage functionality**:
The explorer GUI was extended with a panel similar to the ``flow watch`` CRaSH shell command. It provides users with a view of all
flows currently executed on the node, with information about success/failure. The "Flow Triage" panel will be enhanced in the future
to enable operators to take corrective actions upon flow failures (eg. retry, terminate, amend and replay).
* **Experimental preview of a new operational Corda network grouping concept: Business Networks**:
Business Networks are introduced as a way to partition the global population of nodes (a Compatibility Zone) into
independent, possibly overlapping, groups. A Business Network operator (BNO) will have control over which nodes will
be admitted into a Business Network. Some nodes may choose not to register themselves in the global Network Map, and
will therefore remain invisible to nodes outside of their Business Network. Further documentation will be forthcoming
by the final R3 Corda 3.0 release.
See the "Business Network reference implementation" prototype example in the Explorer tool (instructions in README.md).
In addition to enhancements focused on non-functional capabilities, this release encompasses a number of functional
improvements, including:
* Doorman Service
In order to automate a node's network joining process, a new Doorman service has been introduced with this release.
* **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 nodes identity and network permissions.
More information on Doorman and how to run it can be found in :doc:`running-doorman`.
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.
* Hardware Security Module (HSM) for Doorman
To allow for increased security, R3 Corda introduces HSM integration. Doorman certificates (together with their keys)
can now be stored on secured hardware constraining the way those certificates are accessed. Any usage of those certificates
* **Signing Service**:
R3 Corda 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. The HSM integration is embodied
in our new Signing Service. More on this in :doc:`signing-service`.
and can be configured to involve human-in-the-loop in order to prevent unauthorised access.
See :doc:`signing-service` for further details.
* X.509 certificates now have an extension that specifies the Corda role the certificate is used for, and the role
hierarchy is now enforced in the validation code. This only has impact on those developing integrations with external
PKI solutions. In most cases it is managed transparently by Corda. A formal specification of the extension can be
found at see :doc:`permissioning-certificate-specification`.
* **Operational Compatibility With Corda**
Operational Compatibility With Corda R3 Corda 3.0 Developer Preview 3 provides a baseline for wire stability and compatibility with the open-source Corda.
* Custom Serializers
To allow interop with third party libraries that cannot be recompiled we add functionality that allows custom serializers
to be written for those classes. If needed, a proxy object can be created as an interim step that allows Corda's internal
serializers to operate on those types. A good example of this is the SIMM valuation demo which has a number of such
serializers defined in the plugin/custom serializers package
R3 Corda 3.0 Developer Preview 3 delivers forward compatibility with future versions of R3 Corda:
Please refer to the :doc:`changelog` for detailed explanations of all new features.
- Is operationally compatible with future versions of R3 Corda.
- Is upgradeable to future version of R3 Corda, preserving transaction and other data.
Finally, please note that although this developer preview has not yet been security audited, it is currently being subjected
to a full external secure code review and penetration test.
R3 Corda 3.0 Developer Preview 3 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.
Further improvements and additions
**********************************
* 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.`
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 R3 Corda.
* The database migration tool unnecessarily prints ``{}`` characters at the end of every log line [ENT-1720].
* Running the database migration tool over a node configured against a local SQLServer instance hosted in Docker results in ``ClassNotFoundException`` exception. [ENT-1717]
* The database migration tool throws ``org.hibernate.AnnotationException`` in presence of ``MappedSchema`` sub-classes that reference other ``MappedSchema`` sub-classes. [ENT-1712]
* The database migration tool does not support relative paths in the JDBC url. [ENT-1698]
* Doorman crashes ungracefully when started with incorrect or no program arguments. Should display a meaningful message instead. [ENT-1661]
* Exception when starting a Corda node against a non-H2 database the first time. [ENT-1635]
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.``
* ``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
*************
As per previous major releases, we have provided a comprehensive upgrade notes (:doc:`upgrade-notes`) to ease the upgrade
of CorDapps to R3 Corda 3.0 Developer Preview. In line with our commitment to API stability, code level changes
are fairly minimal, and mostly related to improvements to our nearly API stable test framework.
are fairly minimal.
From a build perspective, switching CorDapps built using Corda (the "Open Source" code) to R3 Corda is mostly effortless,
and simply requires setting two gradle build file variables:
From a build perspective, switching CorDapps built using Corda 3.0 to R3 Corda 3.0 Developer Preview is mostly effortless,
and simply requires setting two Gradle build file variables:
.. sourcecode:: shell
ext.corda_release_version = 'R3.CORDA-3.0.0-DEV-PREVIEW'
ext.corda_release_distribution = 'com.r3.corda'
Please note this release is distributed under license and should not be used in a Production environment yet.
Please note this release is distributed under the evaluation license and should not be used in a Production environment yet.
We look forward to hearing your feedback on this Developer Preview.
Corda 2.0
---------
Following quickly on the heels of the release of Corda 1.0, Corda version 2.0 consolidates
a number of security updates for our dependent libraries alongside the reintroduction of the Observer node functionality.
This was absent from version 1 but based on user feedback its re-introduction removes the need for complicated "isRelevant()" checks.
In addition the fix for a small bug present in the coin selection code of V1.0 is integrated from master.
* **Version Bump**
Due to the introduction of new APIs, Corda 2.0 has a platform version of 2. This will be advertised in the network map structures
and via the versioning APIs.
* **Observer Nodes**
Adds the facility for transparent forwarding of transactions to some third party observer, such as a regulator. By having
that entity simply run an Observer node they can simply receive a stream of digitally signed, de-duplicated reports that
can be used for reporting.
Corda 1.0
---------
Corda 1.0 is finally here!
This critical step in the Corda journey enables the developer community, clients, and partners to build on Corda with confidence.
Corda 1.0 is the first released version to provide API stability for Corda application (CorDapp) developers.
Corda applications will continue to work against this API with each subsequent release of Corda. The public API for Corda
will only evolve to include new features.
As of Corda 1.0, the following modules export public APIs for which we guarantee to maintain backwards compatibility,
unless an incompatible change is required for security reasons:
* **core**:
Contains the bulk of the APIs to be used for building CorDapps: contracts, transactions, flows, identity, node services,
cryptographic libraries, and general utility functions.
* **client-rpc**:
An RPC client interface to Corda, for use by both UI facing clients and integration with external systems.
* **client-jackson**:
Utilities and serialisers for working with JSON representations of basic types.
Our extensive testing frameworks will continue to evolve alongside future Corda APIs. As part of our commitment to ease of use and modularity
we have introduced a new test node driver module to encapsulate all test functionality in support of building standalone node integration
tests using our DSL driver.
Please read :doc:`corda-api` for complete details.
.. note:: it may be necessary to recompile applications against future versions of the API until we begin offering
`ABI (Application Binary Interface) <https://en.wikipedia.org/wiki/Application_binary_interface>`_ stability as well.
We plan to do this soon after this release of Corda.
Significant changes implemented in reaching Corda API stability include:
* **Flow framework**:
The Flow framework communications API has been redesigned around session based communication with the introduction of a new
``FlowSession`` to encapsulate the counterparty information associated with a flow.
All shipped Corda flows have been upgraded to use the new `FlowSession`. Please read :doc:`api-flows` for complete details.
* **Complete API cleanup**:
Across the board, all our public interfaces have been thoroughly revised and updated to ensure a productive and intuitive developer experience.
Methods and flow naming conventions have been aligned with their semantic use to ease the understanding of CorDapps.
In addition, we provide ever more powerful re-usable flows (such as `CollectSignaturesFlow`) to minimize the boiler-plate code developers need to write.
* **Simplified annotation driven scanning**:
CorDapp configuration has been made simpler through the removal of explicit configuration items in favour of annotations
and classpath scanning. As an example, we have now completely removed the `CordaPluginRegistry` configuration.
Contract definitions are no longer required to explicitly define a legal contract reference hash. In their place an
optional `LegalProseReference` annotation to specify a URI is used.
* **Java usability**:
All code has been updated to enable simple access to static API parameters. Developers no longer need to
call getter methods, and can reference static API variables directly.
In addition to API stability this release encompasses a number of major functional improvements, including:
* **Contract constraints**:
Provides a means with which to enforce a specific implementation of a State's verify method during transaction verification.
When loading an attachment via the attachment classloader, constraints of a transaction state are checked against the
list of attachment hashes provided, and the attachment is rejected if the constraints are not matched.
* **Signature Metadata support**:
Signers now have the ability to add metadata to their digital signatures. Whereas previously a user could only sign the Merkle root of a
transaction, it is now possible for extra information to be attached to a signature, such as a platform version
and the signature-scheme used.
.. image:: resources/signatureMetadata.png
* **Backwards compatibility and improvements to core transaction data structures**:
A new Merkle tree model has been introduced that utilises sub-Merkle trees per component type. Components of the
same type, such as inputs or commands, are grouped together and form their own Merkle tree. Then, the roots of
each group are used as leaves in the top-level Merkle tree. This model enables backwards compatibility, in the
sense that if new component types are added in the future, old clients will still be able to compute the Merkle root
and relay transactions even if they cannot read (deserialise) the new component types. Due to the above,
`FilterTransaction` has been made simpler with a structure closer to `WireTransaction`. This has the effect of making the API
more user friendly and intuitive for both filtered and unfiltered transactions.
* **Enhanced component privacy**:
Corda 1.0 is equipped with a scalable component visibility design based on the above sophisticated
sub-tree model and the introduction of nonces per component. Roughly, an initial base-nonce, the "privacy-salt",
is used to deterministically generate nonces based on the path of each component in the tree. Because each component
is accompanied by a nonce, we protect against brute force attacks, even against low-entropy components. In addition,
a new privacy feature is provided that allows non-validating notaries to ensure they see all inputs and if there was a
`TimeWindow` in the original transaction. Due to the above, a malicious user cannot selectively hide one or more
input states from the notary that would enable her to bypass the double-spending check. The aforementioned
functionality could also be applied to Oracles so as to ensure all of the commands are visible to them.
.. image:: resources/subTreesPrivacy.png
* **Full support for confidential identities**:
This includes rework and improvements to the identity service to handle both `well known` and `confidential` identities.
This work ships in an experimental module in Corda 1.0, called `confidential-identities`. API stabilisation of confidential
identities will occur as we make the integration of this privacy feature into applications even easier for developers.
* **Re-designed network map service**:
The foundations for a completely redesigned network map service have been implemented to enable future increased network
scalability and redundancy, support for multiple notaries, and administration of network compatibility zones and business networks.
Finally, please note that the 1.0 release has not yet been security audited.
We have provided a comprehensive :doc:`upgrade-notes` to ease the transition of migrating CorDapps to Corda 1.0
Upgrading to this release is strongly recommended, and you will be safe in the knowledge that core APIs will no longer break.
Thank you to all contributors for this release!
We look forward to hearing your feedback on this release!

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

@ -1,55 +1,49 @@
Upgrading a CorDapp to a new platform version
=============================================
These notes provide instructions for upgrading your CorDapps from previous versions, starting with the upgrade from our
first public Beta (:ref:`Milestone 12 <changelog_m12>`), to :ref:`V1.0 <changelog_v1>`.
These notes provide instructions for upgrading your CorDapps from previous versions to :ref:`V3.0 Developer Preview <changelog_r3_v3>` of R3 Corda (Enterprise Blockchain).
.. contents::
:depth: 3
General rules
-------------
Always remember to update the version identifiers in your project gradle file. For example, Corda V1.0 uses:
Always remember to update the version identifiers in your project gradle file. For example, Corda V3.0 uses:
.. sourcecode:: shell
ext.corda_release_version = '1.0.0'
ext.corda_release_version = 'corda-3.0'
ext.corda_release_distribution = 'net.corda'
ext.corda_gradle_plugins_version = '1.0.0'
ext.corda_gradle_plugins_version = '3.0.9'
It may be necessary to update the version of major dependencies. Corda V1.0 uses:
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:
.. sourcecode:: shell
ext.kotlin_version = '1.1.4'
ext.kotlin_version = '1.1.60'
ext.quasar_version = '0.7.9'
ext.junit_version = '4.12'
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.
V1.0 and V2.0 to R3 Corda V3.0 Developer Preview
------------------------------------------------
Build
^^^^^
Upgrading to R3 Corda V3.0 Developer Preview
--------------------------------------------
A prerequisite to upgrade to R3 Corda V3.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.
* Update the version identifiers in your project gradle file(s):
Upgrading to R3 Corda is now a simple task of updating the version identifiers as follows:
.. sourcecode:: shell
ext.corda_release_version = 'R3.CORDA-3.0.0-DEV-PREVIEW' // "CORDA-3.0.0-DEV-PREVIEW" (Open Source)
ext.corda_gradle_plugins_version = '3.0.3'
ext.corda_release_distribution = 'com.r3.corda' // R3 Corda
ext.corda_release_version = 'R3.CORDA-3.0.0-DEV-PREVIEW-3' // R3 Corda
ext.corda_gradle_plugins_version = '4.0.9'
* Add a new release identifier to specify the R3 release of corda:
.. sourcecode:: shell
ext.corda_release_distribution = 'com.r3.corda' // "net.corda" for Corda (Open Source)
* Add an additional repository entry to point to the location of the R3 Corda distribution:
and specifying an additional repository entry to point to the location of the R3 Corda distribution:
.. sourcecode:: shell
@ -63,6 +57,32 @@ Build
}
}
Upgrading to V3.x
-----------------
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):
.. 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'
* Add a new release identifier to specify the corda distribution type (Open Source or R3 Corda):
.. sourcecode:: shell
ext.corda_release_distribution = 'net.corda' // Corda (Open Source)
* Corda plugins have been modularised further so the following additional gradle entries are necessary:
.. sourcecode:: shell
@ -76,6 +96,24 @@ Build
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
@ -165,9 +203,32 @@ Applies to both gradle deployNodes tasks and/or corda node configuration (node.c
* Shell - to use Shell ensure ``rpcSettings.address`` and ``rpcSettings.adminAddress`` settings are present.
Databases
^^^^^^^^^
Drivers
~~~~~~~
* Alternative JDBC drivers are not bundled as part of R3 Corda 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
~~~~~~~~~~~~~~
@ -244,10 +305,9 @@ 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
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.
@ -257,11 +317,11 @@ Flow tests
val notary = mockNetwork.createNotaryNode(legalName = CordaX500Name("Notary", "London", "UK"))
Notaries are now defined as part of ``MockNetwork`` creation using ``notarySpecs``, as in the following example:
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(MockNetwork.NotarySpec(CordaX500Name("Notary","London","UK"))))
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.
@ -338,35 +398,49 @@ Flow tests
.. sourcecode:: kotlin
node.internals.installCordaService(CustomService::class.java)
node.internals.installCordaService(CustomService::class.java)
Becomes:
.. sourcecode:: kotlin
node.services.cordaService(CustomService::class.java)
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) {
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``:
.. sourcecode:: kotlin
val oracle = mockNet.createNode(MockNodeParameters(legalName = CordaX500Name("Oracle", "New York", "US")), ::PrimesOracleNode)
val oracle = mockNet.createNode(MockNodeParameters(legalName = CordaX500Name("Oracle", "New York", "US")), ::PrimesOracleNode)
Node driver
~~~~~~~~~~~
* 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,
@ -398,351 +472,3 @@ Finance
* ``CASH_PROGRAM_ID`` has been moved to ``Cash.PROGRAM_ID``, where ``Cash`` is defined in the
``import net.corda.finance.contracts.asset`` package
V1.0 to V2.0
------------
* You need to update the ``corda_release_version`` identifier in your project gradle file. The
corda_gradle_plugins_version should remain at 1.0.0:
.. sourcecode:: shell
ext.corda_release_version = '2.0.0'
ext.corda_gradle_plugins_version = '1.0.0'
Public Beta (M12) to V1.0
-------------------------
:ref:`From Milestone 14 <changelog_m14>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Build
^^^^^
* MockNetwork has moved.
A new test driver module dependency needs to be including in your project: ``corda-node-driver``. To continue using the
mock network for testing, add the following entry to your gradle build file:
.. sourcecode:: shell
testCompile "$corda_release_distribution:corda-node-driver:$corda_release_version"
.. note:: You may only need ``testCompile "$corda_release_distribution:corda-test-utils:$corda_release_version"`` if not using the Driver
DSL
Configuration
^^^^^^^^^^^^^
* ``CordaPluginRegistry`` has been removed:
* The one remaining configuration item ``customizeSerialisation``, which defined a optional whitelist of types for
use in object serialization, has been replaced with the ``SerializationWhitelist`` interface which should be
implemented to define a list of equivalent whitelisted classes
* You will need to rename your services resource file. 'resources/META-INF/services/net.corda.core.node.CordaPluginRegistry'
becomes 'resources/META-INF/services/net.corda.core.serialization.SerializationWhitelist'
* ``MockNode.testPluginRegistries`` was renamed to ``MockNode.testSerializationWhitelists``
* In general, the ``@CordaSerializable`` annotation is the preferred method for whitelisting, as described in
:doc:`serialization`
Missing imports
^^^^^^^^^^^^^^^
Use IntelliJ's automatic imports feature to intelligently resolve the new imports:
* Missing imports for contract types:
* CommercialPaper and Cash are now contained within the ``finance`` module, as are associated helpers functions. For
example:
CommercialPaper and Cash are now contained within the ``finance`` module, as are associated helpers functions.
For example:
``import net.corda.contracts.ICommercialPaperState`` becomes ``import net.corda.finance.contracts.ICommercialPaperState``
* ``import net.corda.contracts.asset.sumCashBy`` becomes ``import net.corda.finance.utils.sumCashBy``
* ``import net.corda.core.contracts.DOLLARS`` becomes ``import net.corda.finance.DOLLARS``
* ``import net.corda.core.contracts.issued by`` becomes ``import net.corda.finance.issued by``
* ``import net.corda.contracts.asset.Cash`` becomes ``import net.corda.finance.contracts.asset.Cash``
* Missing imports for utility functions:
* Many common types and helper methods have been consolidated into ``net.corda.core.utilities`` package. For example:
* ``import net.corda.core.crypto.commonName`` becomes ``import net.corda.core.utilities.commonName``
* ``import net.corda.core.crypto.toBase58String`` becomes ``import net.corda.core.utilities.toBase58String``
* ``import net.corda.core.getOrThrow`` becomes ``import net.corda.core.utilities.getOrThrow``
* Missing flow imports:
* In general, all reusable library flows are contained within the **core** API ``net.corda.core.flows`` package
* Financial domain library flows are contained within the **finance** module ``net.corda.finance.flows`` package
* Other flows that have moved include ``import net.corda.core.flows.ResolveTransactionsFlow``, which becomes
``import net.corda.core.internal.ResolveTransactionsFlow``
Core data structures
^^^^^^^^^^^^^^^^^^^^
* Missing ``Contract`` override:
* ``Contract.legalContractReference`` has been removed, and replaced by the optional annotation
``@LegalProseReference(uri = "<URI>")``
* Unresolved reference:
* ``AuthenticatedObject`` was renamed to ``CommandWithParties``
* Overrides nothing:
* ``LinearState.isRelevant`` was removed. Whether a node stores a ``LinearState`` in its vault depends on whether the
node is one of the state's ``participants``
* ``txBuilder.toLedgerTransaction`` now requires a ``ServiceHub`` parameter. This is used by the new Contract
Constraints functionality to validate and resolve attachments
Flow framework
^^^^^^^^^^^^^^
* ``FlowLogic`` communication has been upgraded to use explicit ``FlowSession`` instances to communicate between nodes:
* ``FlowLogic.send``/``FlowLogic.receive``/``FlowLogic.sendAndReceive`` has been replaced by ``FlowSession.send``/
``FlowSession.receive``/``FlowSession.sendAndReceive``. The replacement functions do not take a destination
parameter, as this is defined implictly by the session used
* Initiated flows now take in a ``FlowSession`` instead of ``Party`` in their constructor. If you need to access the
counterparty identity, it is in the ``counterparty`` property of the flow session
* ``FinalityFlow`` now returns a single ``SignedTransaction``, instead of a ``List<SignedTransaction>``
* ``TransactionKeyFlow`` was renamed to ``SwapIdentitiesFlow``
* ``SwapIdentitiesFlow`` must be imported from the *confidential-identities* package ``net.corda.confidential``
Node services (ServiceHub)
^^^^^^^^^^^^^^^^^^^^^^^^^^
* VaultQueryService: unresolved reference to ``vaultQueryService``.
* Replace all references to ``<services>.vaultQueryService`` with ``<services>.vaultService``
* Previously there were two vault APIs. Now there is a single unified API with the same functions: ``VaultService``.
* ``FlowLogic.ourIdentity`` has been introduced as a shortcut for retrieving our identity in a flow
* ``serviceHub.myInfo.legalIdentity`` no longer exists
* ``getAnyNotary`` has been removed. Use ``serviceHub.networkMapCache.notaryIdentities[0]`` instead
* ``ServiceHub.networkMapUpdates`` is replaced by ``ServiceHub.networkMapFeed``
* ``ServiceHub.partyFromX500Name`` is replaced by ``ServiceHub.wellKnownPartyFromX500Name``
* A "well known" party is one that isn't anonymous. This change was motivated by the confidential identities work
RPC Client
^^^^^^^^^^
* Missing API methods on the ``CordaRPCOps`` interface:
* ``verifiedTransactionsFeed`` has been replaced by ``internalVerifiedTransactionsFeed``
* ``verifiedTransactions`` has been replaced by ``internalVerifiedTransactionsSnapshot``
* Accessing the ``networkMapCache`` via ``services.nodeInfo().legalIdentities`` returns a list of identities.
The first element in the list is the Party object referring to a node's single identity.
* Accessing the ``networkMapCache`` via ``services.nodeInfo().legalIdentities`` returns a list of identities
* This change is in preparation for allowing a node to host multiple separate identities in the future
Testing
^^^^^^^
Please note that ``Clauses`` have been removed completely as of V1.0.
We will be revisiting this capability in a future release.
* CorDapps must be explicitly registered in ``MockNetwork`` unit tests:
This is done by calling ``setCordappPackages``, an extension helper function in the ``net.corda.testing`` package,
on the first line of your ``@Before`` method. This takes a variable number of ``String`` arguments which should be the
package names of the CorDapps containing the contract verification code you wish to load.
You should unset CorDapp packages in your ``@After`` method by using ``unsetCordappPackages()`` after ``stopNodes()``.
* CorDapps must be explicitly registered in ``DriverDSL`` and ``RPCDriverDSL`` integration tests:
* You must register package names of the CorDapps containing the contract verification code you wish to load using
the ``extraCordappPackagesToScan: List<String>`` constructor parameter of the driver DSL
Finance
^^^^^^^
* ``FungibleAsset`` interface simplification:
The following errors may be reported:
* override nothing (FungibleAsset): ``move``
* not a subtype of overridden FungibleAsset: ``withNewOwner``
* no longer need to override ``override val contractHash: SecureHash? = null``
* need to override ``override val contract: Class<out Contract>? = null``
Miscellaneous
^^^^^^^^^^^^^
* ``args[0].parseNetworkHostAndPort()`` becomes ``NetworkHostAndPort.parse(args[0])``
* There is no longer a ``NodeInfo.advertisedServices`` property
* The concept of advertised services has been removed from Corda. This is because it was vaguely defined and
real-world apps would not typically select random, unknown counterparties from the network map based on
self-declared capabilities
* We will introduce a replacement for this functionality, business networks, in a future release
* For now, services should be retrieved by legal name using ``NetworkMapCache.getNodeByLegalName``
Gotchas
^^^^^^^
* Be sure to use the correct identity when issuing cash:
* The third parameter to ``CashIssueFlow`` should be the *notary* (and not the *node identity*)
:ref:`From Milestone 13 <changelog_m13>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Core data structures
^^^^^^^^^^^^^^^^^^^^
* ``TransactionBuilder`` changes:
* Use convenience class ``StateAndContract`` instead of ``TransactionBuilder.withItems`` for passing
around a state and its contract.
* Transaction builder DSL changes:
* now need to explicitly pass the ContractClassName into all inputs and outputs.
* ``ContractClassName`` refers to the class containing the “verifier” method.
* ``ContractClassName`` is the name of the ``Contract`` subclass used to verify the transaction
* Contract verify method signature change:
* ``override fun verify(tx: TransactionForContract)`` becomes ``override fun verify(tx: LedgerTransaction)``
* You no longer need to override ``ContractState.contract`` function
Node services (ServiceHub)
^^^^^^^^^^^^^^^^^^^^^^^^^^
* ServiceHub API method changes:
* ``services.networkMapUpdates().justSnapshot`` becomes ``services.networkMapSnapshot()``
Configuration
^^^^^^^^^^^^^
* No longer need to define ``CordaPluginRegistry`` and configure ``requiredSchemas``:
* Custom contract schemas are automatically detected at startup time by class path scanning
* For testing purposes, use the ``SchemaService`` method to register new custom schemas (e.g.
``services.schemaService.registerCustomSchemas(setOf(YoSchemaV1))``)
Identity
^^^^^^^^
* Party names are now ``CordaX500Name``, not ``X500Name``:
* ``CordaX500Name`` specifies a predefined set of mandatory (organisation, locality, country) and optional fields
(common name, organisation unit, state) with validation checking
* Use new builder ``CordaX500Name.build(X500Name(target))`` or explicitly define the X500Name parameters using the
``CordaX500Name`` constructors
Testing
^^^^^^^
* MockNetwork testing:
* Mock nodes in node tests are now of type ``StartedNode<MockNode>``, rather than ``MockNode``
* ``MockNetwork`` now returns a ``BasketOf(<StartedNode<MockNode>>)``
* You must call internals on ``StartedNode`` to get ``MockNode`` (e.g. ``a = nodes.partyNodes[0].internals``)
* Host and port changes:
* Use string helper function ``parseNetworkHostAndPort`` to parse a URL on startup (e.g.
``val hostAndPort = args[0].parseNetworkHostAndPort()``)
* Node driver parameter changes:
* The node driver parameters for starting a node have been reordered
* The node’s name needs to be given as an ``CordaX500Name``, instead of using ``getX509Name``
:ref:`From Milestone 12 (First Public Beta) <changelog_m12>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Core data structures
^^^^^^^^^^^^^^^^^^^^
* Transaction building:
* You no longer need to specify the type of a ``TransactionBuilder`` as ``TransactionType.General``
* ``TransactionType.General.Builder(notary)`` becomes ``TransactionBuilder(notary)``
Build
^^^^^
* Gradle dependency reference changes:
* Module names have changed to include ``corda`` in the artifacts' JAR names:
.. sourcecode:: shell
compile "$corda_release_distribution:core:$corda_release_version" -> compile "$corda_release_distribution:corda-core:$corda_release_version"
compile "$corda_release_distribution:finance:$corda_release_version" -> compile "$corda_release_distribution:corda-finance:$corda_release_version"
compile "$corda_release_distribution:jackson:$corda_release_version" -> compile "$corda_release_distribution:corda-jackson:$corda_release_version"
compile "$corda_release_distribution:node:$corda_release_version" -> compile "$corda_release_distribution:corda-node:$corda_release_version"
compile "$corda_release_distribution:rpc:$corda_release_version" -> compile "$corda_release_distribution:corda-rpc:$corda_release_version"
Node services (ServiceHub)
^^^^^^^^^^^^^^^^^^^^^^^^^^
* ``ServiceHub`` API changes:
* ``services.networkMapUpdates`` becomes ``services.networkMapFeed``
* ``services.getCashBalances`` becomes a helper method in the *finance* module contracts package
(``net.corda.finance.contracts.getCashBalances``)
Finance
^^^^^^^
* Financial asset contracts (``Cash``, ``CommercialPaper``, ``Obligations``) are now a standalone CorDapp within the
``finance`` module:
* You need to import them from their respective packages within the ``finance`` module (e.g.
``net.corda.finance.contracts.asset.Cash``)
* You need to import the associated asset flows from their respective packages within ``finance`` module. For
example:
* ``net.corda.finance.flows.CashIssueFlow``
* ``net.corda.finance.flows.CashIssueAndPaymentFlow``
* ``net.corda.finance.flows.CashExitFlow``
This may require adjusting imports of Cash flow references and also of ``StartFlow`` permission in ``gradle.build`` files.
Associated flows (``Cash*Flow``, ``TwoPartyTradeFlow``, ``TwoPartyDealFlow``) must now be imported from this package.
* Adjust imports of Cash flow references
* Adjust the ``StartFlow`` permission in ``gradle.build`` files
* Adjust imports of the associated flows (``Cash*Flow``, ``TwoPartyTradeFlow``, ``TwoPartyDealFlow``)