construction of them that automatically handles many of the concerns outlined above.</p>
</div>
<divclass="section"id="theory">
<h2>Theory<aclass="headerlink"href="#theory"title="Permalink to this headline">¶</a></h2>
<p>A <em>continuation</em> is a suspended stack frame stored in a regular object that can be passed around, serialised,
unserialised and resumed from where it was suspended. This concept is sometimes referred to as “fibers”. This may
sound abstract but don’t worry, the examples below will make it clearer. The JVM does not natively support
continuations, so we implement them using a library called Quasar which works through behind-the-scenes
bytecode rewriting. You don’t have to know how this works to benefit from it, however.</p>
<p>We use continuations for the following reasons:</p>
<ulclass="simple">
<li>It allows us to write code that is free of callbacks, that looks like ordinary sequential code.</li>
<li>A suspended continuation takes far less memory than a suspended thread. It can be as low as a few hundred bytes.
In contrast a suspended Java thread stack can easily be 1mb in size.</li>
<li>It frees the developer from thinking (much) about persistence and serialisation.</li>
</ul>
<p>A <em>state machine</em> is a piece of code that moves through various <em>states</em>. These are not the same as states in the data
model (that represent facts about the world on the ledger), but rather indicate different stages in the progression
of a multi-stage flow. Typically writing a state machine would require the use of a big switch statement and some
explicit variables to keep track of where you’re up to. The use of continuations avoids this hassle.</p>
</div>
<divclass="section"id="a-two-party-trading-flow">
<h2>A two party trading flow<aclass="headerlink"href="#a-two-party-trading-flow"title="Permalink to this headline">¶</a></h2>
<p>We would like to implement the “hello world” of shared transaction building flows: a seller wishes to sell some
<em>asset</em> (e.g. some commercial paper) in return for <em>cash</em>. The buyer wishes to purchase the asset using his cash. They
want the trade to be atomic so neither side is exposed to the risk of settlement failure. We assume that the buyer
and seller have found each other and arranged the details on some exchange, or over the counter. The details of how
the trade is arranged isn’t covered in this article.</p>
<p>Our flow has two parties (B and S for buyer and seller) and will proceed as follows:</p>
<olclass="arabic simple">
<li>S sends a <codeclass="docutils literal"><spanclass="pre">StateAndRef</span></code> pointing to the state they want to sell to B, along with info about the price they require
B to pay.</li>
<li>B sends to S a <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> that includes the state as input, B’s cash as input, the state with the new
owner key as output, and any change cash as output. It contains a single signature from B but isn’t valid because
it lacks a signature from S authorising movement of the asset.</li>
<li>S signs it and hands the now finalised <codeclass="docutils literal"><spanclass="pre">SignedTransaction</span></code> back to B.</li>
<p>You can find the implementation of this flow in the file <codeclass="docutils literal"><spanclass="pre">finance/src/main/kotlin/net/corda/flows/TwoPartyTradeFlow.kt</span></code>.</p>
<spanclass="k">override</span><spanclass="k">fun</span><spanclass="nf">toString</span><spanclass="p">()</span><spanclass="p">=</span><spanclass="s">"The submitted asset didn't match the expected type: $expectedTypeName vs $typeName"</span>
<spanclass="p">}</span>
<spanclass="c1">// This object is serialised to the network and is the first flow message the seller sends to the buyer.</span>
<p>This code defines several classes nested inside the main <codeclass="docutils literal"><spanclass="pre">TwoPartyTradeFlow</span></code> singleton. Some of the classes are
simply flow messages or exceptions. The other two represent the buyer and seller side of the flow.</p>
<p>Going through the data needed to become a seller, we have:</p>
<li><codeclass="docutils literal"><spanclass="pre">notaryNode:</span><spanclass="pre">NodeInfo</span></code> - the entry in the network map for the chosen notary. See “<spanclass="xref doc">consensus</span>” for more
<li><codeclass="docutils literal"><spanclass="pre">assetToSell:</span><spanclass="pre">StateAndRef<OwnableState></span></code> - a pointer to the ledger entry that represents the thing being sold.</li>
<li><codeclass="docutils literal"><spanclass="pre">price:</span><spanclass="pre">Amount<Currency></span></code> - the agreed on price that the asset is being sold for (without an issuer constraint).</li>
<li><codeclass="docutils literal"><spanclass="pre">myKeyPair:</span><spanclass="pre">KeyPair</span></code> - the key pair that controls the asset being sold. It will be used to sign the transaction.</li>
</ul>
<p>And for the buyer:</p>
<ulclass="simple">
<li><codeclass="docutils literal"><spanclass="pre">acceptablePrice:</span><spanclass="pre">Amount<Currency></span></code> - the price that was agreed upon out of band. If the seller specifies
a price less than or equal to this, then the trade will go ahead.</li>
<li><codeclass="docutils literal"><spanclass="pre">typeToBuy:</span><spanclass="pre">Class<out</span><spanclass="pre">OwnableState></span></code> - the type of state that is being purchased. This is used to check that the
sell side of the flow isn’t trying to sell us the wrong thing, whether by accident or on purpose.</li>
</ul>
<p>Alright, so using this flow shouldn’t be too hard: in the simplest case we can just create a Buyer or Seller
with the details of the trade, depending on who we are. We then have to start the flow in some way. Just
calling the <codeclass="docutils literal"><spanclass="pre">call</span></code> function ourselves won’t work: instead we need to ask the framework to start the flow for
us. More on that in a moment.</p>
</div>
<divclass="section"id="suspendable-functions">
<h2>Suspendable functions<aclass="headerlink"href="#suspendable-functions"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal"><spanclass="pre">call</span></code> function of the buyer/seller classes is marked with the <codeclass="docutils literal"><spanclass="pre">@Suspendable</span></code> annotation. What does this mean?</p>
<p>As mentioned above, our flow framework will at points suspend the code and serialise it to disk. For this to work,
any methods on the call stack must have been pre-marked as <codeclass="docutils literal"><spanclass="pre">@Suspendable</span></code> so the bytecode rewriter knows to modify
the underlying code to support this new feature. A flow is suspended when calling either <codeclass="docutils literal"><spanclass="pre">receive</span></code>, <codeclass="docutils literal"><spanclass="pre">send</span></code> or
<codeclass="docutils literal"><spanclass="pre">sendAndReceive</span></code> which we will learn more about below. For now, just be aware that when one of these methods is
invoked, all methods on the stack must have been marked. If you forget, then in the unit test environment you will
get a useful error message telling you which methods you didn’t mark. The fix is simple enough: just add the annotation
and try again.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Java 9 is likely to remove this pre-marking requirement completely.</p>
<pclass="last">Accessing the vault from inside an @Suspendable function (e.g. via <codeclass="docutils literal"><spanclass="pre">serviceHub.vaultService</span></code>) can cause a serialisation error when the fiber suspends. Instead, vault access should be performed from a helper non-suspendable function, which you then call from the @Suspendable function. We are working to fix this.</p>
<h2>Starting your flow<aclass="headerlink"href="#starting-your-flow"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal"><spanclass="pre">StateMachineManager</span></code> is the class responsible for taking care of all running flows in a node. It knows
how to register handlers with the messaging system (see “<aclass="reference internal"href="messaging.html"><spanclass="doc">Networking and messaging</span></a>”) and iterate the right state machine
when messages arrive. It provides the send/receive/sendAndReceive calls that let the code request network
interaction and it will save/restore serialised versions of the fiber at the right times.</p>
<p>Flows can be invoked in several ways. For instance, they can be triggered by scheduled events,
see “<aclass="reference internal"href="event-scheduling.html"><spanclass="doc">Event scheduling</span></a>” to learn more about this. Or they can be triggered directly via the Java-level node RPC
APIs from your app code.</p>
<p>You request a flow to be invoked by using the <codeclass="docutils literal"><spanclass="pre">CordaRPCOps.startFlowDynamic</span></code> method. This takes a
Java reflection <codeclass="docutils literal"><spanclass="pre">Class</span></code> object that describes the flow class to use (in this case, either <codeclass="docutils literal"><spanclass="pre">Buyer</span></code> or <codeclass="docutils literal"><spanclass="pre">Seller</span></code>).
It also takes a set of arguments to pass to the constructor. Because it’s possible for flow invocations to
be requested by untrusted code (e.g. a state that you have been sent), the types that can be passed into the
flow are checked against a whitelist, which can be extended by apps themselves at load time. There are also a series
of inlined extension functions of the form <codeclass="docutils literal"><spanclass="pre">CordaRPCOps.startFlow</span></code> which help with invoking flows in a type
safe manner.</p>
<p>The process of starting a flow returns a <codeclass="docutils literal"><spanclass="pre">FlowHandle</span></code> that you can use to either observe
the result, observe its progress and which also contains a permanent identifier for the invoked flow in the form
of the <codeclass="docutils literal"><spanclass="pre">StateMachineRunId</span></code>.</p>
<p>In a two party flow only one side is to be manually started using <codeclass="docutils literal"><spanclass="pre">CordaRPCOps.startFlow</span></code>. The other side
has to be registered by its node to respond to the initiating flow via <codeclass="docutils literal"><spanclass="pre">PluginServiceHub.registerFlowInitiator</span></code>.
<p>This is telling the buyer node to fire up an instance of <codeclass="docutils literal"><spanclass="pre">Buyer</span></code> (the code in the lambda) when the initiating flow
is a seller (<codeclass="docutils literal"><spanclass="pre">Seller::class</span></code>).</p>
</div>
<divclass="section"id="implementing-the-seller">
<h2>Implementing the seller<aclass="headerlink"href="#implementing-the-seller"title="Permalink to this headline">¶</a></h2>
<p>Let’s implement the <codeclass="docutils literal"><spanclass="pre">Seller.call</span></code> method. This will be run when the flow is invoked.</p>
<spanclass="n">logger</span><spanclass="p">.</span><spanclass="n">trace</span><spanclass="p">{</span><spanclass="s">"Received partially signed transaction: ${it.id}"</span><spanclass="p">}</span>
<spanclass="c1">// Download and check all the things that this transaction depends on and verify it is contract-valid,</span>
<spanclass="c1">// even though it is missing signatures.</span>
<spanclass="k">throw</span><spanclass="n">IllegalArgumentException</span><spanclass="p">(</span><spanclass="s">"Transaction is not sending us the right amount of cash"</span><spanclass="p">)</span>
<p>Let’s break this down. We fill out the initial flow message with the trade info, and then call <codeclass="docutils literal"><spanclass="pre">sendAndReceive</span></code>.
This function takes a few arguments:</p>
<ulclass="simple">
<li>The party on the other side.</li>
<li>The thing to send. It’ll be serialised and sent automatically.</li>
<li>Finally a type argument, which is the kind of object we’re expecting to receive from the other side. If we get
back something else an exception is thrown.</li>
</ul>
<p>Once <codeclass="docutils literal"><spanclass="pre">sendAndReceive</span></code> is called, the call method will be suspended into a continuation and saved to persistent
storage. If the node crashes or is restarted, the flow will effectively continue as if nothing had happened. Your
code may remain blocked inside such a call for seconds, minutes, hours or even days in the case of a flow that
needs human interaction!</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<p>There are a couple of rules you need to bear in mind when writing a class that will be used as a continuation.
The first is that anything on the stack when the function is suspended will be stored into the heap and kept alive by
<p>The second is that as well as being kept on the heap, objects reachable from the stack will be serialised. The state
of the function call may be resurrected much later! Kryo doesn’t require objects be marked as serialisable, but even so,
doing things like creating threads from inside these calls would be a bad idea. They should only contain business
logic and only do I/O via the methods exposed by the flow framework.</p>
<pclass="last">It’s OK to keep references around to many large internal node services though: these will be serialised using a
special token that’s recognised by the platform, and wired up to the right instance when the continuation is
loaded off disk again.</p>
</div>
<p>The buyer is supposed to send us a transaction with all the right inputs/outputs/commands in response to the opening
message, with their cash put into the transaction and their signature on it authorising the movement of the cash.</p>
<p>You get back a simple wrapper class, <codeclass="docutils literal"><spanclass="pre">UntrustworthyData<SignedTransaction></span></code>, which is just a marker class that reminds
us that the data came from a potentially malicious external source and may have been tampered with or be unexpected in
other ways. It doesn’t add any functionality, but acts as a reminder to “scrub” the data before use.</p>
<p>Our “scrubbing” has three parts:</p>
<olclass="arabic simple">
<li>Check that the expected signatures are present and correct. At this point we expect our own signature to be missing,
because of course we didn’t sign it yet, and also the signature of the notary because that must always come last.</li>
<li>We resolve the transaction, which we will cover below.</li>
<li>We verify that the transaction is paying us the demanded price.</li>
</ol>
</div>
<divclass="section"id="sub-flows">
<h2>Sub-flows<aclass="headerlink"href="#sub-flows"title="Permalink to this headline">¶</a></h2>
<p>Flows can be composed via nesting. Invoking a sub-flow looks similar to an ordinary function call:</p>
<p>In this code snippet we are using the <codeclass="docutils literal"><spanclass="pre">NotaryFlow.Client</span></code> to request notarisation of the transaction.
We simply create the flow object via its constructor, and then pass it to the <codeclass="docutils literal"><spanclass="pre">subFlow</span></code> method which
returns the result of the flow’s execution directly. Behind the scenes all this is doing is wiring up progress
tracking (discussed more below) and then running the objects <codeclass="docutils literal"><spanclass="pre">call</span></code> method. Because this little helper method can
be on the stack when network IO takes place, we mark it as <codeclass="docutils literal"><spanclass="pre">@Suspendable</span></code>.</p>
<p>Going back to the previous code snippet, we use a sub-flow called <codeclass="docutils literal"><spanclass="pre">ResolveTransactionsFlow</span></code>. This is
responsible for downloading and checking all the dependencies of a transaction, which in Corda are always retrievable
from the party that sent you a transaction that uses them. This flow returns a list of <codeclass="docutils literal"><spanclass="pre">LedgerTransaction</span></code>
objects, but we don’t need them here so we just ignore the return value.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Transaction dependency resolution assumes that the peer you got the transaction from has all of the
dependencies itself. It must do, otherwise it could not have convinced itself that the dependencies were themselves
valid. It’s important to realise that requesting only the transactions we require is a privacy leak, because if
we don’t download a transaction from the peer, they know we must have already seen it before. Fixing this privacy
leak will come later.</p>
</div>
<p>After the dependencies, we check the proposed trading transaction for validity by running the contracts for that as
well (but having handled the fact that some signatures are missing ourselves).</p>
<spanclass="n">logger</span><spanclass="p">.</span><spanclass="n">trace</span><spanclass="p">{</span><spanclass="s">"Built finished transaction, sending back to secondary!"</span><spanclass="p">}</span>
<p>It’s all pretty straightforward from now on. Here <codeclass="docutils literal"><spanclass="pre">id</span></code> is the secure hash representing the serialised
transaction, and we just use our private key to calculate a signature over it. As a reminder, in Corda signatures do
not cover other signatures: just the core of the transaction data.</p>
<p>In <codeclass="docutils literal"><spanclass="pre">sendSignatures</span></code>, we take the two signatures we obtained and add them to the partial transaction we were sent.
There is an overload for the + operator so signatures can be added to a SignedTransaction easily. Finally, we wrap the
two signatures in a simple wrapper message class and send it back. The send won’t block waiting for an acknowledgement,
but the underlying message queue software will retry delivery if the other side has gone away temporarily.</p>
<p>You can also see that every flow instance has a logger (using the SLF4J API) which you can use to log progress
messages.</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">This sample code is <strong>not secure</strong>. Other than not checking for all possible invalid constructions, if the
seller stops before sending the finalised transaction to the buyer, the seller is left with a valid transaction
but the buyer isn’t, so they can’t spend the asset they just purchased! This sort of thing will be fixed in a
future version of the code.</p>
</div>
</div>
<divclass="section"id="implementing-the-buyer">
<h2>Implementing the buyer<aclass="headerlink"href="#implementing-the-buyer"title="Permalink to this headline">¶</a></h2>
<p>OK, let’s do the same for the buyer side:</p>
<li>We create a cash spend in the normal way, by using <codeclass="docutils literal"><spanclass="pre">VaultService.generateSpend</span></code>. See the vault documentation if this
<li>We access the <em>service hub</em> when we need it to access things that are transient and may change or be recreated
whilst a flow is suspended, things like the wallet or the network map.</li>
<li>Finally, we send the unfinished, invalid transaction to the seller so they can sign it. They are expected to send
back to us a <codeclass="docutils literal"><spanclass="pre">SignaturesFromSeller</span></code>, which once we verify it, should be the final outcome of the trade.</li>
</ol>
<p>As you can see, the flow logic is straightforward and does not contain any callbacks or network glue code, despite
the fact that it takes minimal resources and can survive node restarts.</p>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">In the current version of the platform, exceptions thrown during flow execution are not propagated
back to the sender. A thorough error handling and exceptions framework will be in a future version of the platform.</p>
</div>
</div>
<divclass="section"id="progress-tracking">
<h2>Progress tracking<aclass="headerlink"href="#progress-tracking"title="Permalink to this headline">¶</a></h2>
<p>Not shown in the code snippets above is the usage of the <codeclass="docutils literal"><spanclass="pre">ProgressTracker</span></code> API. Progress tracking exports information
from a flow about where it’s got up to in such a way that observers can render it in a useful manner to humans who
may need to be informed. It may be rendered via an API, in a GUI, onto a terminal window, etc.</p>
<p>A <codeclass="docutils literal"><spanclass="pre">ProgressTracker</span></code> is constructed with a series of <codeclass="docutils literal"><spanclass="pre">Step</span></code> objects, where each step is an object representing a
stage in a piece of work. It is therefore typical to use singletons that subclass <codeclass="docutils literal"><spanclass="pre">Step</span></code>, which may be defined easily
in one line when using Kotlin. Typical steps might be “Waiting for response from peer”, “Waiting for signature to be
approved”, “Downloading and verifying data” etc.</p>
<spanclass="k">object</span><spanclass="nc">RECEIVING</span><spanclass="p">:</span><spanclass="n">ProgressTracker</span><spanclass="p">.</span><spanclass="n">Step</span><spanclass="p">(</span><spanclass="s">"Waiting for seller trading info"</span><spanclass="p">)</span>
<spanclass="k">object</span><spanclass="nc">SIGNING</span><spanclass="p">:</span><spanclass="n">ProgressTracker</span><spanclass="p">.</span><spanclass="n">Step</span><spanclass="p">(</span><spanclass="s">"Generating and signing transaction proposal"</span><spanclass="p">)</span>
<spanclass="k">object</span><spanclass="nc">SWAPPING_SIGNATURES</span><spanclass="p">:</span><spanclass="n">ProgressTracker</span><spanclass="p">.</span><spanclass="n">Step</span><spanclass="p">(</span><spanclass="s">"Swapping signatures with the seller"</span><spanclass="p">)</span>
<spanclass="s">"Sending purchase order to seller for review, and receiving partially signed transaction from seller in return."</span><spanclass="o">);</span>
<p>Each step exposes a label. By default labels are fixed, but by subclassing <codeclass="docutils literal"><spanclass="pre">RelabelableStep</span></code>
you can make a step that can update its label on the fly. That’s useful for steps that want to expose non-structured
progress information like the current file being downloaded. By defining your own step types, you can export progress
in a way that’s both human readable and machine readable.</p>
<p>Progress trackers are hierarchical. Each step can be the parent for another tracker. By altering the
<codeclass="docutils literal"><spanclass="pre">ProgressTracker.childrenFor</span></code> map, a tree of steps can be created. It’s allowed to alter the hierarchy
<divclass="highlight-java"><divclass="highlight"><pre><span></span><spanclass="kd">private</span><spanclass="kd">static</span><spanclass="kd">final</span><spanclass="n">ProgressTracker</span><spanclass="o">.</span><spanclass="na">Step</span><spanclass="n">COMMITTING</span><spanclass="o">=</span><spanclass="k">new</span><spanclass="n">ProgressTracker</span><spanclass="o">.</span><spanclass="na">Step</span><spanclass="o">(</span><spanclass="s">"Committing to the ledger."</span><spanclass="o">)</span><spanclass="o">{</span>
<p>Every tracker has not only the steps given to it at construction time, but also the singleton
<codeclass="docutils literal"><spanclass="pre">ProgressTracker.UNSTARTED</span></code> step and the <codeclass="docutils literal"><spanclass="pre">ProgressTracker.DONE</span></code> step. Once a tracker has become <codeclass="docutils literal"><spanclass="pre">DONE</span></code> its
position may not be modified again (because e.g. the UI may have been removed/cleaned up), but until that point, the
position can be set to any arbitrary set both forwards and backwards. Steps may be skipped, repeated, etc. Note that
rolling the current step backwards will delete any progress trackers that are children of the steps being reversed, on
the assumption that those subtasks will have to be repeated.</p>
<p>Trackers provide an <aclass="reference external"href="http://reactivex.io/">Rx observable</a> which streams changes to the hierarchy. The top level
observable exposes all the events generated by its children as well. The changes are represented by objects indicating
whether the change is one of position (i.e. progress), structure (i.e. new subtasks being added/removed) or some other
aspect of rendering (i.e. a step has changed in some way and is requesting a re-render).</p>
<p>The flow framework is somewhat integrated with this API. Each <codeclass="docutils literal"><spanclass="pre">FlowLogic</span></code> may optionally provide a tracker by
overriding the <codeclass="docutils literal"><spanclass="pre">flowTracker</span></code> property (<codeclass="docutils literal"><spanclass="pre">getFlowTracker</span></code> method in Java). If the
<codeclass="docutils literal"><spanclass="pre">FlowLogic.subFlow</span></code> method is used, then the tracker of the sub-flow will be made a child of the current
step in the parent flow automatically, if the parent is using tracking in the first place. The framework will also
automatically set the current step to <codeclass="docutils literal"><spanclass="pre">DONE</span></code> for you, when the flow is finished.</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
