From 8f7367add7c5ec5b05650e35e8bfd1b957736369 Mon Sep 17 00:00:00 2001 From: Ryan Fowler Date: Thu, 19 Dec 2019 10:52:34 +0000 Subject: [PATCH 1/2] CORDA-3509: add documentation about Corda features and their corresponding platformVersion and network minimumPlatformVersion --- docs/source/api-contract-constraints.rst | 3 + docs/source/features-versions.rst | 85 ++++++++++++++++++++++++ docs/source/network-map.rst | 4 ++ 3 files changed, 92 insertions(+) create mode 100644 docs/source/features-versions.rst diff --git a/docs/source/api-contract-constraints.rst b/docs/source/api-contract-constraints.rst index ad00dbc65f..f019212989 100644 --- a/docs/source/api-contract-constraints.rst +++ b/docs/source/api-contract-constraints.rst @@ -12,6 +12,9 @@ API: Contract Constraints .. note:: Before reading this page, you should be familiar with the key concepts of :doc:`key-concepts-contracts`. +.. note:: As of Corda |corda_version| the `minimumPlatformVersion` required to use these features is 4 + (see :ref:`Network Parameters ` and :doc:`features-versions` for more details). + .. contents:: Reasons for Contract Constraints diff --git a/docs/source/features-versions.rst b/docs/source/features-versions.rst new file mode 100644 index 0000000000..f103bb7a9d --- /dev/null +++ b/docs/source/features-versions.rst @@ -0,0 +1,85 @@ +Corda Features to Versions +========================== + +New versions of Corda introduce new features. These fall into one of three categories which have subtle but important implications for +node owners, application developers and network operators. + +The first set are changes that have no impact on application developers or the Corda network protocol. An example would be support for +a new HSM or database system, for example, and which are of interest only to a node's operator. + +The second set are new or changed APIs, which are of interest to CorDapp developers. When a release of Corda ships such features, the +Platform Version of that node is incremented so that a CorDapp that relies on such a new or changed feature can detect this (eg to +prevent it from running on a node without the feature or to trigger an alternative optimised codepath if the feature is present). The +app developer should set the CorDapp's minimumPlatformVersion parameter to signal the minimum Platform Version against which the app +can run or has been tested. If the application has also been tested against a greater platform version and can exploit it if present, +the node can also set the targetPlatformVersion field. + +The third set of changes are those which could affect the operation of a Corda network. Examples would include a change to the +serialisation format or flow/wire protocol, or introduction of a new transaction component. These are changes to the core data model and +these features have the property that it is not safe for any node or application to take advantage of until all nodes on the network +are capable of understanding them. Such features are thus only enabled in a node if the network to which it is connected has published +a minimumPlatformVersion in its network parameters that is greater than or equal to the Corda Platform Version that introduced the +feature. For example, Corda 4.0 nodes, which implement Corda Platform Version 4, can only take advantage of the Corda Reference States +feature when connected to a network with mPV 4. + +Generally the rules work this way: + +- IF (CorDapp.mPV > node.PV) THEN + prevent the CorDapp from running (this signals that it cannot run without the new feature). +- IF (CorDapp.mPV <= node.PV AND CorDapp.targetPV < node.PV) THEN + this means the node is ahead of the CorDapp so it might choose to trigger some code paths that emulate some old behaviour that the + CorDapp expected on that version. +- IF (CorDapp.mPV <= node.PV AND CorDapp.targetPV == node.PV) THEN + just use the new mechanism because the CorDapp and the node are perfectly aligned. +- IF (CorDapp.mPV <= node.PV AND CorDapp.targetPV > node.PV) THEN + this means that the CorDapp is ahead of the running node, but it must have some alternative runtime code paths built in to be able + to simulate the new behaviour using old apis. + +.. list-table:: Corda Features + :header-rows: 1 + + * - Feature + - Corda Platform Version (PV) + - Min Network Platform Version (network mPV) + - Introduced in OS version + - Introduced in Enterprise version + * - Observer Nodes + - 2 + - 2 + - 2.0 + - n/a + * - Corda Serialization Framework + - 3 + - 3 + - 3.0 + - 3.0 + * - Hash Constraints + - 1 + - 1 + - 1.0 + - 1.0 + * - Whitelist Constraints + - 3 + - 3 + - 3.0 + - 3.0 + * - Inline Finality Flow + - 4 + - 3 + - 4.0 + - 4.0 + * - Reference States + - 4 + - 4 + - 4.0 + - 4.0 + * - Signature Constraints + - 4 + - 4 + - 4.0 + - 4.0 + * - Underlying Support for Accounts + - 5 + - 4 + - 4.3 + - 4.3 diff --git a/docs/source/network-map.rst b/docs/source/network-map.rst index fba6220071..9c7ffab830 100644 --- a/docs/source/network-map.rst +++ b/docs/source/network-map.rst @@ -97,6 +97,8 @@ cluster generated like this can be sized for the maximum size you may need, and More information can be found in :doc:`network-bootstrapper`. +.. _network-parameters: + Network parameters ------------------ @@ -152,6 +154,8 @@ The current set of network parameters: Encountering an owned contract in a JAR that is not signed by the rightful owner is most likely a sign of malicious behaviour, and should be reported. The transaction verification logic will throw an exception when this happens. +.. note:: To determine which `minimumPlatformVersion` a zone must mandate in order to permit all the features of Corda |corda_version| see :doc:`features-versions` + More parameters will be added in future releases to regulate things like allowed port numbers, whether or not IPv6 connectivity is required for zone members, required cryptographic algorithms and roll-out schedules (e.g. for moving to post quantum cryptography), parameters related to SGX and so on. From 338671e6b2de95158cd425cf372dda2c207bf42d Mon Sep 17 00:00:00 2001 From: Ryan Fowler Date: Mon, 27 Jan 2020 09:42:28 +0000 Subject: [PATCH 2/2] CORDA-3509: add documentation about Corda features and their corresponding platformVersion and network minimumPlatformVersion --- docs/source/features-versions.rst | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/docs/source/features-versions.rst b/docs/source/features-versions.rst index f103bb7a9d..9ed8801926 100644 --- a/docs/source/features-versions.rst +++ b/docs/source/features-versions.rst @@ -22,18 +22,13 @@ a minimumPlatformVersion in its network parameters that is greater than or equal feature. For example, Corda 4.0 nodes, which implement Corda Platform Version 4, can only take advantage of the Corda Reference States feature when connected to a network with mPV 4. -Generally the rules work this way: - -- IF (CorDapp.mPV > node.PV) THEN - prevent the CorDapp from running (this signals that it cannot run without the new feature). -- IF (CorDapp.mPV <= node.PV AND CorDapp.targetPV < node.PV) THEN - this means the node is ahead of the CorDapp so it might choose to trigger some code paths that emulate some old behaviour that the - CorDapp expected on that version. -- IF (CorDapp.mPV <= node.PV AND CorDapp.targetPV == node.PV) THEN - just use the new mechanism because the CorDapp and the node are perfectly aligned. -- IF (CorDapp.mPV <= node.PV AND CorDapp.targetPV > node.PV) THEN - this means that the CorDapp is ahead of the running node, but it must have some alternative runtime code paths built in to be able - to simulate the new behaviour using old apis. +If there is a Platform Version below which your application will not run or is not supported, then signal that with the application's +`CorDapp.mPV` field. This will prevent older nodes from running your app. Nodes which support newer Platform Versions may also use this +field to trigger code paths that emulate behaviours that were in force on that older Platform Version to maximise compatibility. However, +if you have tested your app against newer versions of Corda and know your node can take advantage of the new Platform Version behaviours +if present, you can signal this by using `CorDapp.targetPV` to declare the latest Platform Version against which the app has been tested +and is known to work. In this way, it is possible to ship CorDapps that can both run on all nodes supporting some minimum Platform Version +of Corda as well as opt in to newer features should they happen to be available on any given node. .. list-table:: Corda Features :header-rows: 1