ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-06-23 09:25:36 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

DOCS - clarify the upgrade policy for finality flow (#4853)

Browse Source
This commit is contained in:
Dimos Raptis
2019-03-06 09:55:59 +00:00
committed by Shams Asari
parent 0faf56917e
commit 3bb996d22f
1 changed files with 19 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -30,6 +30,8 @@ Although the RPC API is backwards compatible with Corda 3, the RPC wire protocol
updated in lockstep with the node to use the new version of the RPC library. Corda 4 delivers RPC wire stability and therefore in future you updated in lockstep with the node to use the new version of the RPC library. Corda 4 delivers RPC wire stability and therefore in future you
will be able to update the node and apps without updating RPC clients. will be able to update the node and apps without updating RPC clients.
.. _cordapp_upgrade_version_numbers_ref:
Step 2. Adjust the version numbers in your Gradle build files Step 2. Adjust the version numbers in your Gradle build files
------------------------------------------------------------- -------------------------------------------------------------
@ -163,11 +165,25 @@ The previous ``FinalityFlow`` API is insecure. It doesn't have a receive flow, s
all signed transactions that are sent to it, without checks. It is **highly** recommended that existing CorDapps migrate all signed transactions that are sent to it, without checks. It is **highly** recommended that existing CorDapps migrate
away to the new API, as otherwise things like business network membership checks won't be reliably enforced. away to the new API, as otherwise things like business network membership checks won't be reliably enforced.
This is a three step process: The flows that make use of ``FinalityFlow`` in a CorDapp can be classified in the following 2 basic categories:
* **non-initiating flows**: these are flows that finalise a transaction without the involvement of a counterpart flow at all.
* **initiating flows**: these are flows that initiate a counterpart (responder) flow.
There is a main difference between these 2 different categories, which is relevant to how the CorDapp can be upgraded.
The second category of flows can be upgraded to use the new ``FinalityFlow`` in a backwards compatible way, which means the upgraded CorDapp can be deployed at the various nodes using a *rolling deployment*.
On the other hand, the first category of flows cannot be upgraded to the new ``FinalityFlow`` in a backwards compatible way, so the changes to these flows need to be deployed simultaneously at all the nodes, using a *lockstep deployment*.
.. note:: A *lockstep deployment* is one, where all the involved nodes are stopped, upgraded to the new version of the CorDapp and then re-started.
As a result, there can't be any nodes running different versions of the CorDapp at any time.
A *rolling deployment* is one, where every node can be stopped, upgraded to the new version of the CorDapp and re-started independently and on its own pace.
As a result, there can be nodes running different versions of the CorDapp and transact with each other successfully.
The upgrade is a three step process:
1. Change the flow that calls ``FinalityFlow``. 1. Change the flow that calls ``FinalityFlow``.
2. Change or create the flow that will receive the finalised transaction. 2. Change or create the flow that will receive the finalised transaction.
3. Make sure your application's minimum and target version numbers are both set to 4 (see step 2). 3. Make sure your application's minimum and target version numbers are both set to 4 (see :ref:`cordapp_upgrade_version_numbers_ref`).
Upgrading a non-initiating flow Upgrading a non-initiating flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -222,7 +238,7 @@ to record the finalised transaction:
:end-before: DOCEND SimpleNewResponderFlow :end-before: DOCEND SimpleNewResponderFlow
:dedent: 4 :dedent: 4
.. note:: All the nodes in your business network will need the new CorDapp, otherwise they won't know how to receive the transaction. **This .. note:: As described above, all the nodes in your business network will need the new CorDapp, otherwise they won't know how to receive the transaction. **This
includes nodes which previously didn't have the old CorDapp.** If a node is sent a transaction and it doesn't have the new CorDapp loaded includes nodes which previously didn't have the old CorDapp.** If a node is sent a transaction and it doesn't have the new CorDapp loaded
then simply restart it with the CorDapp and the transaction will be recorded. then simply restart it with the CorDapp and the transaction will be recorded.