ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-04-13 22:23:31 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

CORDA-2655 - Document CorDapp upgradeability guarantees in Corda 4. (#4793)

Browse Source 
* 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.
This commit is contained in:
josecoll 2019-02-26 17:30:10 +00:00 committed by GitHub
parent d102a8ac11
commit c11f42fc05
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 86 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/api-contract-constraints.rst
View File

@ -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``
-------------------------------------------------------------------------------------------------------------------------------------------------

6
docs/source/app-upgrade-notes.rst
View File

@ -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.

77
docs/source/cordapp-upgradeability.rst Normal file
View File

@ -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.

2
docs/source/upgrading-cordapps.rst
View File

@ -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
-----------------------------