CORDA-2655 - Document CorDapp upgradeability guarantees in Corda 4. (c…

…orda#4793)

* Document CorDapp upgradeability guarantees.

* Incorporating feedback from RGB.

* Incorporating feedback from MH.

* Minor updates following re-review by RGB

* Updates following review by MH.

* Include new document in index.

* Incorporating review feedback from MH.

docs/source/api-contract-constraints.rst

@@ -192,6 +192,8 @@ will be selected based on a variety of factors so that the above holds true. If
 possible constraints, the ``TransactionBuilder`` will throw an exception.
 
 
+.. _constraints_whitelist_to_signature_ref:
+
 How to use the ``SignatureAttachmentConstraint`` if states were already created on the network with the ``WhitelistedByZoneAttachmentConstraint``
 -------------------------------------------------------------------------------------------------------------------------------------------------
 

docs/source/app-upgrade-notes.rst

@@ -154,6 +154,8 @@ Would become:
 
 See :ref:`cordapp_configuration_files_ref` for more information.
 
+.. _cordapp_upgrade_finality_flow_ref:
+
 Step 5. Security: Upgrade your use of FinalityFlow
 --------------------------------------------------
 
@@ -411,4 +413,6 @@ Corda 4 adds several new APIs that help you build applications. Why not explore:
 
 * The `new withEntityManager API <api/javadoc/net/corda/core/node/ServiceHub.html#withEntityManager-block->`_ for using JPA inside your flows and services.
 * :ref:`reference_states`, that let you use an input state without consuming it.
-* :ref:`state_pointers`, that make it easier to 'point' to one state from another and follow the latest version of a linear state.
+* :ref:`state_pointers`, that make it easier to 'point' to one state from another and follow the latest version of a linear state.
+
+Please also read the :doc:`CorDapp Upgradeability Guarantees <cordapp-upgradeability>` associated with CorDapp upgrading.

docs/source/cordapp-upgradeability.rst

@@ -0,0 +1,77 @@
+CorDapp Upgradeability Guarantees
+=================================
+
+Corda 4.0
+---------
+
+Corda 4 introduces a number of advanced features (such as signature constraints), and data security model improvements (such as attachments
+trust checking and classloader isolation of contract attachments for transaction building and verification).
+
+The following guarantees are made for CorDapps running on Corda 4.0
+
+- Compliant CorDapps compiled with previous versions of Corda (from 3.0) will execute without change on Corda 4.0
+
+  .. note:: by "compliant", we mean CorDapps that do not utilise Corda internal, non-stable or other non-committed public Corda APIs.
+
+  Recommendation: security hardening changes in flow processing, specifically the ``FinalityFlow``, recommend upgrading existing CorDapp
+  receiver flows to use the new APIs and thus opting in to platform version 4. See :ref:`cordapp_upgrade_finality_flow_ref` for more information.
+
+- All constraint types (hash, CZ whitelisted, signature) are consumable within the same transaction if there is an associated contract attachment that satisfies all of them.
+
+- CorDapp Contract states generated on ledger using hash constraints are not directly migratable to signature constraints in this release.
+  Your compatibility zone operator may whitelist a JAR previously used to issue hash constrained states, and then you can follow the manual
+  process described in the paragraph below to migrate these to signature constraints.
+
+- CorDapp Contract states generated on ledger using CZ whitelisted constraints are migratable to signature constraints using a manual process
+  that requires programmatic code changes. See :ref:`constraints_whitelist_to_signature_ref` for more information.
+
+- Explicit Contract Upgrades are only supported for hash and CZ whitelisted constraint types. See :ref:`explicit_contract_upgrades_ref` for more information.
+
+- CorDapp contract attachments are not trusted from remote peers over the p2p network for the purpose of transaction verification.
+  A node operator must locally install *all* versions of a Contract attachment to be able to resolve a chain of contract states from its original version.
+  The RPC ``uploadAttachment`` mechanism can be used to achieve this (as well as conventional loading of a CorDapp by installing it in the nodes /cordapp directory).
+  See :ref:`cordapp_install_ref` and :ref:`cordapp_contract_attachments_ref` for more information.
+
+- CorDapp contract attachment classloader isolation has some important side-effects and edge cases to consider:
+
+  1. Contract attachments should include all 3rd party library dependencies in the same packaged JAR - we call this a "Fat JAR",
+     meaning that all dependencies are resolvable by the classloader by only loading a single JAR.
+  2. Contract attachments that depend on other Contract attachments from a different packaged JAR are currently supported in so far as the Attachments Classloader
+     will attempt to resolve any external dependencies from the node's application classloader. It is thus paramount that dependent Contract
+     Attachments are loaded upon node startup from the respective /cordapps directory.
+
+- Rolling upgrades are partially supported.
+  A Node operator may choose to manually upload (via the RPC attachments uploader mechanism) a later version of a Contract Attachment than
+  the version their node is currently using for the purposes of transaction verification (received from remote peers). However, they will only
+  be able to build new transactions with the version that is currently loaded (installed from the nodes /cordapps directory) in their node.
+
+- Finance CorDapp (v4)
+  Whilst experimental, our test coverage has confirmed that states generated with the Finance CorDapp are interchangeable across Open Source
+  and Enterprise distributions. This has been made possible by releasing a single 4.0 version of the Finance Contracts CorDapp.
+  Please note the Finance application will be superseded shortly by the new Tokens SDK (https://github.com/corda/token-sdk)
+
+Later releases
+--------------
+
+The following additional capabilities are under consideration for delivery in follow-up releases to Corda 4.0:
+
+- CorDapp Contract states generated on ledger using hash constraints will be automatically migrated to signature constraints when building new transactions
+  where the latest installed contract Jar is signed as per :ref:`CorDapp Jar signing <cordapp_build_system_signing_cordapp_jar_ref>`.
+
+- CorDapp Contract states generated on ledger using CZ whitelisted constraints will be automatically migrated to signature constraints when building new transactions
+  where the latest installed contract Jar is signed as per :ref:`CorDapp Jar signing <cordapp_build_system_signing_cordapp_jar_ref>`.
+
+- Explicit Contract Upgrades will be supported for all constraint types: hash, CZ whitelisted and signature.
+  In practice, it should only be necessary to upgrade from hash or CZ whitelisted to new signature constrained contract types.
+  signature constrained Contracts are upgradeable seamlessly (through built in serialization and code signing controls) without requiring explicit upgrades.
+
+- Contract attachments will be able to explicitly declare their dependencies on other Contract attachments such that these are automatically
+  loaded by the Attachments Classloader (rendering the 4.0 fallback to application classloader mechanism redundant).
+  This improved modularity removes the need to "Fat JAR" all dependencies together in a single jar.
+
+- Rolling upgrades will be fully supported.
+  A Node operator will be able to pre-register (by hash or code signing public key) versions of CorDapps they are not yet ready to install locally,
+  but wish to use for the purposes of transaction verification with peers running later versions of a CorDapp.
+
+.. note:: Trusted downloading and execution of contract attachments from remote peers will not be integrated until secure JVM sand-boxing is available.
+

docs/source/upgrading-cordapps.rst

@@ -259,6 +259,8 @@ a drain is complete there should be no outstanding checkpoints or running flows.
 A node can be drained or undrained via RPC using the ``setFlowsDrainingModeEnabled`` method, and via the shell using
 the standard ``run`` command to invoke the RPC. See :doc:`shell` to learn more.
 
+.. _explicit_contract_upgrades_ref:
+
 Contract and state versioning
 -----------------------------