From c11f42fc05adc2746aba7517f6a8496a724e2d69 Mon Sep 17 00:00:00 2001 From: josecoll Date: Tue, 26 Feb 2019 17:30:10 +0000 Subject: [PATCH] CORDA-2655 - Document CorDapp upgradeability guarantees in Corda 4. (#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 | 2 + docs/source/app-upgrade-notes.rst | 6 +- docs/source/cordapp-upgradeability.rst | 77 ++++++++++++++++++++++++ docs/source/upgrading-cordapps.rst | 2 + 4 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 docs/source/cordapp-upgradeability.rst diff --git a/docs/source/api-contract-constraints.rst b/docs/source/api-contract-constraints.rst index 6da31d01a6..b92cb94978 100644 --- a/docs/source/api-contract-constraints.rst +++ b/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`` ------------------------------------------------------------------------------------------------------------------------------------------------- diff --git a/docs/source/app-upgrade-notes.rst b/docs/source/app-upgrade-notes.rst index 15bee7a3c1..cd0d083913 100644 --- a/docs/source/app-upgrade-notes.rst +++ b/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 `_ 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. \ No newline at end of file +* :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 ` associated with CorDapp upgrading. \ No newline at end of file diff --git a/docs/source/cordapp-upgradeability.rst b/docs/source/cordapp-upgradeability.rst new file mode 100644 index 0000000000..1e7dc56eb7 --- /dev/null +++ b/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 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 `. + +- 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. + diff --git a/docs/source/upgrading-cordapps.rst b/docs/source/upgrading-cordapps.rst index 638e12847d..6d885c029b 100644 --- a/docs/source/upgrading-cordapps.rst +++ b/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 -----------------------------