ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-19 04:57:58 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Provides more information about the default initiating subflows. Minor tweaks.

Browse Source
This commit is contained in:
Joel Dudley 2018-02-08 16:50:28 +00:00 committed by GitHub
parent ff972508bd
commit 2986e2f5a9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 25 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
docs/source/api-flows.rst
View File

@ -473,7 +473,6 @@ explicit in the ``initiateFlow`` function call. To port existing code:
Subflows Subflows
-------- --------
Subflows are pieces of reusable flows that may be run by calling ``FlowLogic.subFlow``. There are two broad categories Subflows are pieces of reusable flows that may be run by calling ``FlowLogic.subFlow``. There are two broad categories
of subflows, inlined and initiating ones. The main difference lies in the counter-flow's starting method, initiating of subflows, inlined and initiating ones. The main difference lies in the counter-flow's starting method, initiating
ones initiate counter-flows automatically, while inlined ones expect some parent counter-flow to run the inlined ones initiate counter-flows automatically, while inlined ones expect some parent counter-flow to run the inlined
@ -481,7 +480,6 @@ counter-part.
Inlined subflows Inlined subflows
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
Inlined subflows inherit their calling flow's type when initiating a new session with a counterparty. For example, say Inlined subflows inherit their calling flow's type when initiating a new session with a counterparty. For example, say
we have flow A calling an inlined subflow B, which in turn initiates a session with a party. The FlowLogic type used to we have flow A calling an inlined subflow B, which in turn initiates a session with a party. The FlowLogic type used to
determine which counter-flow should be kicked off will be A, not B. Note that this means that the other side of this determine which counter-flow should be kicked off will be A, not B. Note that this means that the other side of this
@ -499,7 +497,6 @@ In the code inlined subflows appear as regular ``FlowLogic`` instances, `without
Initiating subflows Initiating subflows
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
Initiating subflows are ones annotated with the ``@InitiatingFlow`` annotation. When such a flow initiates a session its Initiating subflows are ones annotated with the ``@InitiatingFlow`` annotation. When such a flow initiates a session its
type will be used to determine which ``@InitiatedBy`` flow to kick off on the counterparty. type will be used to determine which ``@InitiatedBy`` flow to kick off on the counterparty.
@ -508,32 +505,38 @@ An example is the ``@InitiatingFlow InitiatorFlow``/``@InitiatedBy ResponderFlow
.. note:: Initiating flows are versioned separately from their parents. .. note:: Initiating flows are versioned separately from their parents.
Core initiating subflows Core initiating subflows
^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~
Corda-provided initiating subflows are a little different to standard ones as they are versioned together with the Corda-provided initiating subflows are a little different to standard ones as they are versioned together with the
platform, and their initiated counter-flows are registered explicitly, so there is no need for the ``InitiatedBy`` platform, and their initiated counter-flows are registered explicitly, so there is no need for the ``InitiatedBy``
annotation. annotation.
An example is the ``FinalityFlow``/``FinalityHandler`` flow pair. Library flows
^^^^^^^^^^^^^
Corda installs four initiating subflow pairs on each node by default:
Built-in subflows * ``FinalityFlow``/``FinalityHandler``, which should be used to notarise and record a transaction and broadcast it to
^^^^^^^^^^^^^^^^^ all relevant parties
* ``NotaryChangeFlow``/``NotaryChangeHandler``, which should be used to change a state's notary
* ``ContractUpgradeFlow.Initiate``/``ContractUpgradeHandler``, which should be used to change a state's contract
* ``SwapIdentitiesFlow``/``SwapIdentitiesHandler``, which is used to exchange confidential identities with a
counterparty
Corda provides a number of built-in flows that should be used for handling common tasks. The most important are: .. warning:: ``SwapIdentitiesFlow``/``SwapIdentitiesHandler`` are only installed if the ``confidential-identities`` module
is included. The ``confidential-identities`` module is still not stabilised, so the
``SwapIdentitiesFlow``/``SwapIdentitiesHandler`` API may change in future releases. See :doc:`corda-api`.
Corda also provides a number of built-in inlined subflows that should be used for handling common tasks. The most
important are:
* ``CollectSignaturesFlow`` (inlined), which should be used to collect a transaction's required signatures * ``CollectSignaturesFlow`` (inlined), which should be used to collect a transaction's required signatures
* ``FinalityFlow`` (initiating), which should be used to notarise and record a transaction as well as to broadcast it to
all relevant parties
* ``SendTransactionFlow`` (inlined), which should be used to send a signed transaction if it needed to be resolved on * ``SendTransactionFlow`` (inlined), which should be used to send a signed transaction if it needed to be resolved on
the other side. the other side.
* ``ReceiveTransactionFlow`` (inlined), which should be used receive a signed transaction * ``ReceiveTransactionFlow`` (inlined), which should be used receive a signed transaction
* ``ContractUpgradeFlow`` (initiating), which should be used to change a state's contract
* ``NotaryChangeFlow`` (initiating), which should be used to change a state's notary
Let's look at three very common examples. Let's look at some of these flows in more detail.
FinalityFlow FinalityFlow
^^^^^^^^^^^^ ~~~~~~~~~~~~
``FinalityFlow`` allows us to notarise the transaction and get it recorded in the vault of the participants of all ``FinalityFlow`` allows us to notarise the transaction and get it recorded in the vault of the participants of all
the transaction's states: the transaction's states:
@ -571,7 +574,7 @@ Only one party has to call ``FinalityFlow`` for a given transaction to be record
**not** need to be called by each participant individually. **not** need to be called by each participant individually.
CollectSignaturesFlow/SignTransactionFlow CollectSignaturesFlow/SignTransactionFlow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The list of parties who need to sign a transaction is dictated by the transaction's commands. Once we've signed a The list of parties who need to sign a transaction is dictated by the transaction's commands. Once we've signed a
transaction ourselves, we can automatically gather the signatures of the other required signers using transaction ourselves, we can automatically gather the signatures of the other required signers using
``CollectSignaturesFlow``: ``CollectSignaturesFlow``:
@ -608,7 +611,7 @@ transaction and provide their signature if they are satisfied:
:dedent: 12 :dedent: 12
SendTransactionFlow/ReceiveTransactionFlow SendTransactionFlow/ReceiveTransactionFlow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Verifying a transaction received from a counterparty also requires verification of every transaction in its Verifying a transaction received from a counterparty also requires verification of every transaction in its
dependency chain. This means the receiving party needs to be able to ask the sender all the details of the chain. dependency chain. This means the receiving party needs to be able to ask the sender all the details of the chain.
The sender will use ``SendTransactionFlow`` for sending the transaction and then for processing all subsequent The sender will use ``SendTransactionFlow`` for sending the transaction and then for processing all subsequent
@ -663,7 +666,6 @@ We can also send and receive a ``StateAndRef`` dependency chain and automaticall
Why inlined subflows? Why inlined subflows?
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
Inlined subflows provide a way to share commonly used flow code `while forcing users to create a parent flow`. Take for Inlined subflows provide a way to share commonly used flow code `while forcing users to create a parent flow`. Take for
example ``CollectSignaturesFlow``. Say we made it an initiating flow that automatically kicks off example ``CollectSignaturesFlow``. Say we made it an initiating flow that automatically kicks off
``SignTransactionFlow`` that signs the transaction. This would mean malicious nodes can just send any old transaction to ``SignTransactionFlow`` that signs the transaction. This would mean malicious nodes can just send any old transaction to

3
docs/source/api-identity.rst
View File

@ -3,6 +3,9 @@ API: Identity
.. note:: Before reading this page, you should be familiar with the key concepts of :doc:`key-concepts-identity`. .. note:: Before reading this page, you should be familiar with the key concepts of :doc:`key-concepts-identity`.
.. warning:: The ``confidential-identities`` module is still not stabilised, so this API may change in future releases.
See :doc:`corda-api`.
.. contents:: .. contents::
Party Party

2
docs/source/running-a-node.rst
View File

@ -19,7 +19,7 @@ Start the nodes with ``runnodes`` by running the following command from the root
* Linux/macOS: ``build/nodes/runnodes`` * Linux/macOS: ``build/nodes/runnodes``
* Windows: ``call build\nodes\runnodes.bat`` * Windows: ``call build\nodes\runnodes.bat``
.. warn:: On macOS, do not click/change focus until all the node terminal windows have opened, or some processes may .. warning:: On macOS, do not click/change focus until all the node terminal windows have opened, or some processes may
fail to start. fail to start.
If you receive an ``OutOfMemoryError`` exception when interacting with the nodes, you need to increase the amount of If you receive an ``OutOfMemoryError`` exception when interacting with the nodes, you need to increase the amount of

2
docs/source/tutorial-cordapp.rst
View File

@ -215,7 +215,7 @@ Start the nodes by running the following command from the root of the ``cordapp-
* Unix/Mac OSX: ``kotlin-source/build/nodes/runnodes`` * Unix/Mac OSX: ``kotlin-source/build/nodes/runnodes``
* Windows: ``call kotlin-source\build\nodes\runnodes.bat`` * Windows: ``call kotlin-source\build\nodes\runnodes.bat``
.. warn:: On Unix/Mac OSX, do not click/change focus until all seven additional terminal windows have opened, or some .. warning:: On Unix/Mac OSX, do not click/change focus until all seven additional terminal windows have opened, or some
nodes may fail to start. nodes may fail to start.
For each node, the ``runnodes`` script creates a node tab/window: For each node, the ``runnodes`` script creates a node tab/window: