From 3bb996d22f1ced65ddf431584600c59f497d6aa9 Mon Sep 17 00:00:00 2001 From: Dimos Raptis Date: Wed, 6 Mar 2019 09:55:59 +0000 Subject: [PATCH] DOCS - clarify the upgrade policy for finality flow (#4853) --- docs/source/app-upgrade-notes.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/source/app-upgrade-notes.rst b/docs/source/app-upgrade-notes.rst index cd0d083913..9f864b162e 100644 --- a/docs/source/app-upgrade-notes.rst +++ b/docs/source/app-upgrade-notes.rst @@ -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 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 ------------------------------------------------------------- @@ -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 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``. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -222,7 +238,7 @@ to record the finalised transaction: :end-before: DOCEND SimpleNewResponderFlow :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 then simply restart it with the CorDapp and the transaction will be recorded.