ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-25 23:51:10 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
deb628281a
corda/docs/build/html/protocol-state-machines.html

897 lines
73 KiB
HTML
Raw Normal View History

Regen docsite
2016-11-11 11:52:29 +00:00
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Protocol state machines &mdash; R3 Corda latest documentation</title>
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
<link rel="top" title="R3 Corda latest documentation" href="index.html"/>
<link rel="next" title="Writing oracle services" href="oracles.html"/>
<link rel="prev" title="Client RPC API" href="tutorial-clientrpc-api.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> R3 Corda
</a>
<div class="version">
latest
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<br>
<a href="api/index.html">API reference</a>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Overview</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
<li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="transaction-data-types.html">Data types</a></li>
<li class="toctree-l1"><a class="reference internal" href="merkle-trees.html">Transaction Tear-offs</a></li>
<li class="toctree-l1"><a class="reference internal" href="consensus.html">Consensus model</a></li>
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
<li class="toctree-l1"><a class="reference internal" href="persistence.html">Persistence</a></li>
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html">Creating a Cordapp</a></li>
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html#gradle-plugins-for-cordapps">Gradle Plugins for Cordapps</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="corda-configuration-files.html">The Corda Configuration File</a></li>
<li class="toctree-l1"><a class="reference internal" href="corda-configuration-files.html#rpc-users-file">RPC Users File</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="where-to-start.html">Where to start</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract.html">Writing a contract</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract-clauses.html">Writing a contract using clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-test-dsl.html">Writing a contract test</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-clientrpc-api.html">Client RPC API</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Protocol state machines</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#theory">Theory</a></li>
<li class="toctree-l2"><a class="reference internal" href="#a-two-party-trading-protocol">A two party trading protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="#suspendable-functions">Suspendable functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#starting-your-protocol">Starting your protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="#implementing-the-seller">Implementing the seller</a></li>
<li class="toctree-l2"><a class="reference internal" href="#subprotocols">Subprotocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="#implementing-the-buyer">Implementing the buyer</a></li>
<li class="toctree-l2"><a class="reference internal" href="#progress-tracking">Progress tracking</a></li>
<li class="toctree-l2"><a class="reference internal" href="#unit-testing">Unit testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="#versioning">Versioning</a></li>
<li class="toctree-l2"><a class="reference internal" href="#future-features">Future features</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-attachments.html">Using attachments</a></li>
<li class="toctree-l1"><a class="reference internal" href="event-scheduling.html">Event scheduling</a></li>
</ul>
<p class="caption"><span class="caption-text">Contracts</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="contract-catalogue.html">Contract catalogue</a></li>
<li class="toctree-l1"><a class="reference internal" href="contract-irs.html">Interest Rate Swaps</a></li>
<li class="toctree-l1"><a class="reference internal" href="initialmarginagreement.html">Initial Margin Agreements</a></li>
</ul>
<p class="caption"><span class="caption-text">Node API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="clientrpc.html">Client RPC</a></li>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="secure-coding-guidelines.html">Secure coding guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-process.html">Release process</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-process.html#steps-to-cut-a-release">Steps to cut a release</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-explorer.html">Node Explorer</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">R3 Corda</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Protocol state machines</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/protocol-state-machines.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script><div class="section" id="protocol-state-machines">
<h1>Protocol state machines<a class="headerlink" href="#protocol-state-machines" title="Permalink to this headline"></a></h1>
<p>This article explains our experimental approach to modelling financial protocols in code. It explains how the
platform&#8217;s state machine framework is used, and takes you through the code for a simple 2-party asset trading protocol
which is included in the source.</p>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>Shared distributed ledgers are interesting because they allow many different, mutually distrusting parties to
share a single source of truth about the ownership of assets. Digitally signed transactions are used to update that
shared ledger, and transactions may alter many states simultaneously and atomically.</p>
<p>Blockchain systems such as Bitcoin support the idea of building up a finished, signed transaction by passing around
partially signed invalid transactions outside of the main network, and by doing this you can implement
<em>delivery versus payment</em> such that there is no chance of settlement failure, because the movement of cash and the
traded asset are performed atomically by the same transaction. To perform such a trade involves a multi-step protocol
in which messages are passed back and forth privately between parties, checked, signed and so on.</p>
<p>Despite how useful these protocols are, platforms such as Bitcoin and Ethereum do not assist the developer with the rather
tricky task of actually building them. That is unfortunate. There are many awkward problems in their implementation
that a good platform would take care of for you, problems like:</p>
<ul class="simple">
<li>Avoiding &#8220;callback hell&#8221; in which code that should ideally be sequential is turned into an unreadable mess due to the
desire to avoid using up a thread for every protocol instantiation.</li>
<li>Surviving node shutdowns/restarts that may occur in the middle of the protocol without complicating things. This
implies that the state of the protocol must be persisted to disk.</li>
<li>Error handling.</li>
<li>Message routing.</li>
<li>Serialisation.</li>
<li>Catching type errors, in which the developer gets temporarily confused and expects to receive/send one type of message
when actually they need to receive/send another.</li>
<li>Unit testing of the finished protocol.</li>
</ul>
<p>Actor frameworks can solve some of the above but they are often tightly bound to a particular messaging layer, and
we would like to keep a clean separation. Additionally, they are typically not type safe, and don&#8217;t make persistence or
writing sequential code much easier.</p>
<p>To put these problems in perspective, the <em>payment channel protocol</em> in the bitcoinj library, which allows bitcoins to
be temporarily moved off-chain and traded at high speed between two parties in private, consists of about 7000 lines of
Java and took over a month of full time work to develop. Most of that code is concerned with the details of persistence,
message passing, lifecycle management, error handling and callback management. Because the business logic is quite
spread out the code can be difficult to read and debug.</p>
<p>As small contract-specific trading protocols are a common occurence in finance, we provide a framework for the
construction of them that automatically handles many of the concerns outlined above.</p>
</div>
<div class="section" id="theory">
<h2>Theory<a class="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 &#8220;fibers&#8221;. This may
sound abstract but don&#8217;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&#8217;t have to know how this works to benefit from it, however.</p>
<p>We use continuations for the following reasons:</p>
<ul class="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 protocol. Typically writing a state machine would require the use of a big switch statement and some
explicit variables to keep track of where you&#8217;re up to. The use of continuations avoids this hassle.</p>
</div>
<div class="section" id="a-two-party-trading-protocol">
<h2>A two party trading protocol<a class="headerlink" href="#a-two-party-trading-protocol" title="Permalink to this headline"></a></h2>
<p>We would like to implement the &#8220;hello world&#8221; of shared transaction building protocols: 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&#8217;t covered in this article.</p>
<p>Our protocol has two parties (B and S for buyer and seller) and will proceed as follows:</p>
<ol class="arabic simple">
<li>S sends a <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">SignedTransaction</span></code> that includes the state as input, B&#8217;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&#8217;t valid because
it lacks a signature from S authorising movement of the asset.</li>
<li>S signs it and hands the now finalised <code class="docutils literal"><span class="pre">SignedTransaction</span></code> back to B.</li>
</ol>
<p>You can find the implementation of this protocol in the file <code class="docutils literal"><span class="pre">finance/src/main/kotlin/net.corda.protocols/TwoPartyTradeProtocol.kt</span></code>.</p>
<p>Assuming no malicious termination, they both end the protocol being in posession of a valid, signed transaction that
represents an atomic asset swap.</p>
<p>Note that it&#8217;s the <em>seller</em> who initiates contact with the buyer, not vice-versa as you might imagine.</p>
<p>We start by defining a wrapper that namespaces the protocol code, two functions to start either the buy or sell side
of the protocol, and two classes that will contain the protocol definition. We also pick what data will be used by
each side.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The code samples in this tutorial are only available in Kotlin, but you can use any JVM language to
write them and the approach is the same.</p>
</div>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">object</span> <span class="nc">TwoPartyTradeProtocol</span> <span class="p">{</span>
<span class="k">class</span> <span class="nc">UnacceptablePriceException</span><span class="p">(</span><span class="k">val</span> <span class="py">givenPrice</span><span class="p">:</span> <span class="n">Amount</span><span class="p">&lt;</span><span class="n">Currency</span><span class="p">&gt;)</span> <span class="p">:</span> <span class="n">Exception</span><span class="p">(</span><span class="s">&quot;Unacceptable price: $givenPrice&quot;</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">AssetMismatchException</span><span class="p">(</span><span class="k">val</span> <span class="py">expectedTypeName</span><span class="p">:</span> <span class="n">String</span><span class="p">,</span> <span class="k">val</span> <span class="py">typeName</span><span class="p">:</span> <span class="n">String</span><span class="p">)</span> <span class="p">:</span> <span class="n">Exception</span><span class="p">()</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">toString</span><span class="p">()</span> <span class="p">=</span> <span class="s">&quot;The submitted asset didn&#39;t match the expected type: $expectedTypeName vs $typeName&quot;</span>
<span class="p">}</span>
<span class="c1">// This object is serialised to the network and is the first protocol message the seller sends to the buyer.</span>
<span class="k">data</span> <span class="k">class</span> <span class="nc">SellerTradeInfo</span><span class="p">(</span>
<span class="k">val</span> <span class="py">assetForSale</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">OwnableState</span><span class="p">&gt;,</span>
<span class="k">val</span> <span class="py">price</span><span class="p">:</span> <span class="n">Amount</span><span class="p">&lt;</span><span class="n">Currency</span><span class="p">&gt;,</span>
<span class="k">val</span> <span class="py">sellerOwnerKey</span><span class="p">:</span> <span class="n">PublicKey</span>
<span class="p">)</span>
<span class="k">data</span> <span class="k">class</span> <span class="nc">SignaturesFromSeller</span><span class="p">(</span><span class="k">val</span> <span class="py">sellerSig</span><span class="p">:</span> <span class="n">DigitalSignature</span><span class="p">.</span><span class="n">WithKey</span><span class="p">,</span>
<span class="k">val</span> <span class="py">notarySig</span><span class="p">:</span> <span class="n">DigitalSignature</span><span class="p">.</span><span class="n">LegallyIdentifiable</span><span class="p">)</span>
<span class="k">open</span> <span class="k">class</span> <span class="nc">Seller</span><span class="p">(</span><span class="k">val</span> <span class="py">otherSide</span><span class="p">:</span> <span class="n">Party</span><span class="p">,</span>
<span class="k">val</span> <span class="py">notaryNode</span><span class="p">:</span> <span class="n">NodeInfo</span><span class="p">,</span>
<span class="k">val</span> <span class="py">assetToSell</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">OwnableState</span><span class="p">&gt;,</span>
<span class="k">val</span> <span class="py">price</span><span class="p">:</span> <span class="n">Amount</span><span class="p">&lt;</span><span class="n">Currency</span><span class="p">&gt;,</span>
<span class="k">val</span> <span class="py">myKeyPair</span><span class="p">:</span> <span class="n">KeyPair</span><span class="p">,</span>
<span class="k">override</span> <span class="k">val</span> <span class="py">progressTracker</span><span class="p">:</span> <span class="n">ProgressTracker</span> <span class="p">=</span> <span class="n">Seller</span><span class="p">.</span><span class="n">tracker</span><span class="p">())</span> <span class="p">:</span> <span class="n">ProtocolLogic</span><span class="p">&lt;</span><span class="n">SignedTransaction</span><span class="p">&gt;()</span> <span class="p">{</span>
<span class="n">@Suspendable</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">call</span><span class="p">():</span> <span class="n">SignedTransaction</span> <span class="p">{</span>
<span class="n">TODO</span><span class="p">()</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">open</span> <span class="k">class</span> <span class="nc">Buyer</span><span class="p">(</span><span class="k">val</span> <span class="py">otherSide</span><span class="p">:</span> <span class="n">Party</span><span class="p">,</span>
<span class="k">val</span> <span class="py">notary</span><span class="p">:</span> <span class="n">Party</span><span class="p">,</span>
<span class="k">val</span> <span class="py">acceptablePrice</span><span class="p">:</span> <span class="n">Amount</span><span class="p">&lt;</span><span class="n">Currency</span><span class="p">&gt;,</span>
<span class="k">val</span> <span class="py">typeToBuy</span><span class="p">:</span> <span class="n">Class</span><span class="p">&lt;</span><span class="k">out</span> <span class="n">OwnableState</span><span class="p">&gt;)</span> <span class="p">:</span> <span class="n">ProtocolLogic</span><span class="p">&lt;</span><span class="n">SignedTransaction</span><span class="p">&gt;()</span> <span class="p">{</span>
<span class="n">@Suspendable</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">call</span><span class="p">():</span> <span class="n">SignedTransaction</span> <span class="p">{</span>
<span class="n">TODO</span><span class="p">()</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>This code defines several classes nested inside the main <code class="docutils literal"><span class="pre">TwoPartyTradeProtocol</span></code> singleton. Some of the classes are
simply protocol messages or exceptions. The other two represent the buyer and seller side of the protocol.</p>
<p>Going through the data needed to become a seller, we have:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">otherSide:</span> <span class="pre">Party</span></code> - the party with which you are trading.</li>
<li><code class="docutils literal"><span class="pre">notaryNode:</span> <span class="pre">NodeInfo</span></code> - the entry in the network map for the chosen notary. See &#8220;<a class="reference internal" href="consensus.html"><span class="doc">Consensus model</span></a>&#8221; for more
information on notaries.</li>
<li><code class="docutils literal"><span class="pre">assetToSell:</span> <span class="pre">StateAndRef&lt;OwnableState&gt;</span></code> - a pointer to the ledger entry that represents the thing being sold.</li>
<li><code class="docutils literal"><span class="pre">price:</span> <span class="pre">Amount&lt;Currency&gt;</span></code> - the agreed on price that the asset is being sold for (without an issuer constraint).</li>
<li><code class="docutils literal"><span class="pre">myKeyPair:</span> <span class="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>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">acceptablePrice:</span> <span class="pre">Amount&lt;Currency&gt;</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><code class="docutils literal"><span class="pre">typeToBuy:</span> <span class="pre">Class&lt;out</span> <span class="pre">OwnableState&gt;</span></code> - the type of state that is being purchased. This is used to check that the
sell side of the protocol isn&#8217;t trying to sell us the wrong thing, whether by accident or on purpose.</li>
</ul>
<p>Alright, so using this protocol shouldn&#8217;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 protocol in some way. Just
calling the <code class="docutils literal"><span class="pre">call</span></code> function ourselves won&#8217;t work: instead we need to ask the framework to start the protocol for
us. More on that in a moment.</p>
</div>
<div class="section" id="suspendable-functions">
<h2>Suspendable functions<a class="headerlink" href="#suspendable-functions" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal"><span class="pre">call</span></code> function of the buyer/seller classes is marked with the <code class="docutils literal"><span class="pre">&#64;Suspendable</span></code> annotation. What does this mean?</p>
<p>As mentioned above, our protocol 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 <code class="docutils literal"><span class="pre">&#64;Suspendable</span></code> so the bytecode rewriter knows to modify
the underlying code to support this new feature. A protocol is suspended when calling either <code class="docutils literal"><span class="pre">receive</span></code>, <code class="docutils literal"><span class="pre">send</span></code> or
<code class="docutils literal"><span class="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&#8217;t mark. The fix is simple enough: just add the annotation
and try again.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Java 9 is likely to remove this pre-marking requirement completely.</p>
</div>
</div>
<div class="section" id="starting-your-protocol">
<h2>Starting your protocol<a class="headerlink" href="#starting-your-protocol" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal"><span class="pre">StateMachineManager</span></code> is the class responsible for taking care of all running protocols in a node. It knows
how to register handlers with the messaging system (see &#8220;<a class="reference internal" href="messaging.html"><span class="doc">Networking and messaging</span></a>&#8221;) 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>Protocols can be invoked in several ways. For instance, they can be triggered by scheduled events,
see &#8220;<a class="reference internal" href="event-scheduling.html"><span class="doc">Event scheduling</span></a>&#8221; to learn more about this. Or they can be triggered via the HTTP API. Or they can
be triggered directly via the Java-level node APIs from your app code.</p>
<p>You request a protocol to be invoked by using the <code class="docutils literal"><span class="pre">ServiceHub.invokeProtocolAsync</span></code> method. This takes a
Java reflection <code class="docutils literal"><span class="pre">Class</span></code> object that describes the protocol class to use (in this case, either <code class="docutils literal"><span class="pre">Buyer</span></code> or <code class="docutils literal"><span class="pre">Seller</span></code>).
It also takes a set of arguments to pass to the constructor. Because it&#8217;s possible for protocol invocations to
be requested by untrusted code (e.g. a state that you have been sent), the types that can be passed into the
protocol are checked against a whitelist, which can be extended by apps themselves at load time.</p>
<p>The process of starting a protocol returns a <code class="docutils literal"><span class="pre">ListenableFuture</span></code> that you can use to either block waiting for
the result, or register a callback that will be invoked when the result is ready.</p>
<p>In a two party protocol only one side is to be manually started using <code class="docutils literal"><span class="pre">ServiceHub.invokeProtocolAsync</span></code>. The other side
has to be registered by its node to respond to the initiating protocol via <code class="docutils literal"><span class="pre">ServiceHubInternal.registerProtocolInitiator</span></code>.
In our example it doesn&#8217;t matter which protocol is the initiator and which is the initiated. For example, if we are to
take the seller as the initiator then we would register the buyer as such:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">val</span> <span class="py">services</span><span class="p">:</span> <span class="n">ServiceHubInternal</span> <span class="p">=</span> <span class="n">TODO</span><span class="p">()</span>
<span class="n">services</span><span class="p">.</span><span class="n">registerProtocolInitiator</span><span class="p">(</span><span class="n">Seller</span><span class="o">::</span><span class="k">class</span><span class="p">)</span> <span class="p">{</span> <span class="n">otherParty</span> <span class="p">-&gt;</span>
<span class="k">val</span> <span class="py">notary</span> <span class="p">=</span> <span class="n">services</span><span class="p">.</span><span class="n">networkMapCache</span><span class="p">.</span><span class="n">notaryNodes</span><span class="p">[</span><span class="m">0</span><span class="p">]</span>
<span class="k">val</span> <span class="py">acceptablePrice</span> <span class="p">=</span> <span class="n">TODO</span><span class="p">()</span>
<span class="k">val</span> <span class="py">typeToBuy</span> <span class="p">=</span> <span class="n">TODO</span><span class="p">()</span>
<span class="n">Buyer</span><span class="p">(</span><span class="n">otherParty</span><span class="p">,</span> <span class="n">notary</span><span class="p">,</span> <span class="n">acceptablePrice</span><span class="p">,</span> <span class="n">typeToBuy</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>This is telling the buyer node to fire up an instance of <code class="docutils literal"><span class="pre">Buyer</span></code> (the code in the lambda) when the initiating protocol
is a seller (<code class="docutils literal"><span class="pre">Seller::class</span></code>).</p>
</div>
<div class="section" id="implementing-the-seller">
<h2>Implementing the seller<a class="headerlink" href="#implementing-the-seller" title="Permalink to this headline"></a></h2>
<p>Let&#8217;s implement the <code class="docutils literal"><span class="pre">Seller.call</span></code> method. This will be run when the protocol is invoked.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Suspendable</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">call</span><span class="p">():</span> <span class="n">SignedTransaction</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">partialTX</span><span class="p">:</span> <span class="n">SignedTransaction</span> <span class="p">=</span> <span class="n">receiveAndCheckProposedTransaction</span><span class="p">()</span>
<span class="k">val</span> <span class="py">ourSignature</span><span class="p">:</span> <span class="n">DigitalSignature</span><span class="p">.</span><span class="n">WithKey</span> <span class="p">=</span> <span class="n">computeOurSignature</span><span class="p">(</span><span class="n">partialTX</span><span class="p">)</span>
<span class="k">val</span> <span class="py">allPartySignedTx</span> <span class="p">=</span> <span class="n">partialTX</span> <span class="p">+</span> <span class="n">ourSignature</span>
<span class="k">val</span> <span class="py">notarySignature</span> <span class="p">=</span> <span class="n">getNotarySignature</span><span class="p">(</span><span class="n">allPartySignedTx</span><span class="p">)</span>
<span class="k">val</span> <span class="py">result</span><span class="p">:</span> <span class="n">SignedTransaction</span> <span class="p">=</span> <span class="n">sendSignatures</span><span class="p">(</span><span class="n">allPartySignedTx</span><span class="p">,</span> <span class="n">ourSignature</span><span class="p">,</span> <span class="n">notarySignature</span><span class="p">)</span>
<span class="k">return</span> <span class="n">result</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>Here we see the outline of the procedure. We receive a proposed trade transaction from the buyer and check that it&#8217;s
valid. The buyer has already attached their signature before sending it. Then we calculate and attach our own signature so that the transaction is
now signed by both the buyer and the seller. We then send this request to a notary to assert with another signature that the
timestamp in the transaction (if any) is valid and there are no double spends, and send back both
our signature and the notaries signature. Note we should not send to the notary until all other required signatures have been appended
as the notary may validate the signatures as well as verifying for itself the transactional integrity.
Finally, we hand back to the code that invoked the protocol the finished transaction.</p>
<p>Let&#8217;s fill out the <code class="docutils literal"><span class="pre">receiveAndCheckProposedTransaction()</span></code> method.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Suspendable</span>
<span class="k">private</span> <span class="k">fun</span> <span class="nf">receiveAndCheckProposedTransaction</span><span class="p">():</span> <span class="n">SignedTransaction</span> <span class="p">{</span>
<span class="c1">// Make the first message we&#39;ll send to kick off the protocol.</span>
<span class="k">val</span> <span class="py">hello</span> <span class="p">=</span> <span class="n">SellerTradeInfo</span><span class="p">(</span><span class="n">assetToSell</span><span class="p">,</span> <span class="n">price</span><span class="p">,</span> <span class="n">myKeyPair</span><span class="p">.</span><span class="k">public</span><span class="p">)</span>
<span class="k">val</span> <span class="py">maybeSTX</span> <span class="p">=</span> <span class="n">sendAndReceive</span><span class="p">&lt;</span><span class="n">SignedTransaction</span><span class="p">&gt;(</span><span class="n">otherSide</span><span class="p">,</span> <span class="n">hello</span><span class="p">)</span>
<span class="n">maybeSTX</span><span class="p">.</span><span class="n">unwrap</span> <span class="p">{</span>
<span class="c1">// Check that the tx proposed by the buyer is valid.</span>
<span class="k">val</span> <span class="py">missingSigs</span><span class="p">:</span> <span class="n">Set</span><span class="p">&lt;</span><span class="n">PublicKey</span><span class="p">&gt;</span> <span class="p">=</span> <span class="n">it</span><span class="p">.</span><span class="n">verifySignatures</span><span class="p">(</span><span class="n">throwIfSignaturesAreMissing</span> <span class="p">=</span> <span class="k">false</span><span class="p">)</span>
<span class="k">val</span> <span class="py">expected</span> <span class="p">=</span> <span class="n">setOf</span><span class="p">(</span><span class="n">myKeyPair</span><span class="p">.</span><span class="k">public</span><span class="p">,</span> <span class="n">notaryNode</span><span class="p">.</span><span class="n">identity</span><span class="p">.</span><span class="n">owningKey</span><span class="p">)</span>
<span class="k">if</span> <span class="p">(</span><span class="n">missingSigs</span> <span class="p">!=</span> <span class="n">expected</span><span class="p">)</span>
<span class="k">throw</span> <span class="n">SignatureException</span><span class="p">(</span><span class="s">&quot;The set of missing signatures is not as expected: ${missingSigs.toStringsShort()} vs ${expected.toStringsShort()}&quot;</span><span class="p">)</span>
<span class="k">val</span> <span class="py">wtx</span><span class="p">:</span> <span class="n">WireTransaction</span> <span class="p">=</span> <span class="n">it</span><span class="p">.</span><span class="n">tx</span>
<span class="n">logger</span><span class="p">.</span><span class="n">trace</span> <span class="p">{</span> <span class="s">&quot;Received partially signed transaction: ${it.id}&quot;</span> <span class="p">}</span>
<span class="c1">// Download and check all the things that this transaction depends on and verify it is contract-valid,</span>
<span class="c1">// even though it is missing signatures.</span>
<span class="n">subProtocol</span><span class="p">(</span><span class="n">ResolveTransactionsProtocol</span><span class="p">(</span><span class="n">wtx</span><span class="p">,</span> <span class="n">otherSide</span><span class="p">))</span>
<span class="k">if</span> <span class="p">(</span><span class="n">wtx</span><span class="p">.</span><span class="n">outputs</span><span class="p">.</span><span class="n">map</span> <span class="p">{</span> <span class="n">it</span><span class="p">.</span><span class="k">data</span> <span class="p">}.</span><span class="n">sumCashBy</span><span class="p">(</span><span class="n">myKeyPair</span><span class="p">.</span><span class="k">public</span><span class="p">).</span><span class="n">withoutIssuer</span><span class="p">()</span> <span class="p">!=</span> <span class="n">price</span><span class="p">)</span>
<span class="k">throw</span> <span class="n">IllegalArgumentException</span><span class="p">(</span><span class="s">&quot;Transaction is not sending us the right amount of cash&quot;</span><span class="p">)</span>
<span class="k">return</span> <span class="n">it</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>Let&#8217;s break this down. We fill out the initial protocol message with the trade info, and then call <code class="docutils literal"><span class="pre">sendAndReceive</span></code>.
This function takes a few arguments:</p>
<ul class="simple">
<li>The party on the other side.</li>
<li>The thing to send. It&#8217;ll be serialised and sent automatically.</li>
<li>Finally a type argument, which is the kind of object we&#8217;re expecting to receive from the other side. If we get
back something else an exception is thrown.</li>
</ul>
<p>Once <code class="docutils literal"><span class="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 protocol 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 protocol that
needs human interaction!</p>
<div class="admonition note">
<p class="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
the garbage collector. So try to avoid keeping enormous data structures alive unless you really have to.</p>
<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&#8217;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 protocol framework.</p>
<p class="last">It&#8217;s OK to keep references around to many large internal node services though: these will be serialised using a
special token that&#8217;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, <code class="docutils literal"><span class="pre">UntrustworthyData&lt;SignedTransaction&gt;</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&#8217;t add any functionality, but acts as a reminder to &#8220;scrub&#8221; the data before use.</p>
<p>Our &#8220;scrubbing&#8221; has three parts:</p>
<ol class="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&#8217;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>
<div class="section" id="subprotocols">
<h2>Subprotocols<a class="headerlink" href="#subprotocols" title="Permalink to this headline"></a></h2>
<p>Protocols can be composed via nesting. Invoking a sub-protocol looks similar to an ordinary function call:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Suspendable</span>
<span class="k">private</span> <span class="k">fun</span> <span class="nf">getNotarySignature</span><span class="p">(</span><span class="n">stx</span><span class="p">:</span> <span class="n">SignedTransaction</span><span class="p">):</span> <span class="n">DigitalSignature</span><span class="p">.</span><span class="n">LegallyIdentifiable</span> <span class="p">{</span>
<span class="n">progressTracker</span><span class="p">.</span><span class="n">currentStep</span> <span class="p">=</span> <span class="n">NOTARY</span>
<span class="k">return</span> <span class="n">subProtocol</span><span class="p">(</span><span class="n">NotaryProtocol</span><span class="p">.</span><span class="n">Client</span><span class="p">(</span><span class="n">stx</span><span class="p">))</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>In this code snippet we are using the <code class="docutils literal"><span class="pre">NotaryProtocol.Client</span></code> to request notarisation of the transaction.
We simply create the protocol object via its constructor, and then pass it to the <code class="docutils literal"><span class="pre">subProtocol</span></code> method which
returns the result of the protocol&#8217;s execution directly. Behind the scenes all this is doing is wiring up progress
tracking (discussed more below) and then running the objects <code class="docutils literal"><span class="pre">call</span></code> method. Because this little helper method can
be on the stack when network IO takes place, we mark it as <code class="docutils literal"><span class="pre">&#64;Suspendable</span></code>.</p>
<p>Going back to the previous code snippet, we use a subprotocol called <code class="docutils literal"><span class="pre">ResolveTransactionsProtocol</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 protocol returns a list of <code class="docutils literal"><span class="pre">LedgerTransaction</span></code>
objects, but we don&#8217;t need them here so we just ignore the return value.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="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&#8217;s important to realise that requesting only the transactions we require is a privacy leak, because if
we don&#8217;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>
<p>Here&#8217;s the rest of the code:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">open</span> <span class="k">fun</span> <span class="nf">computeOurSignature</span><span class="p">(</span><span class="n">partialTX</span><span class="p">:</span> <span class="n">SignedTransaction</span><span class="p">)</span> <span class="p">=</span> <span class="n">myKeyPair</span><span class="p">.</span><span class="n">signWithECDSA</span><span class="p">(</span><span class="n">partialTX</span><span class="p">.</span><span class="n">txBits</span><span class="p">)</span>
<span class="n">@Suspendable</span>
<span class="k">private</span> <span class="k">fun</span> <span class="nf">sendSignatures</span><span class="p">(</span><span class="n">allPartySignedTX</span><span class="p">:</span> <span class="n">SignedTransaction</span><span class="p">,</span> <span class="n">ourSignature</span><span class="p">:</span> <span class="n">DigitalSignature</span><span class="p">.</span><span class="n">WithKey</span><span class="p">,</span>
<span class="n">notarySignature</span><span class="p">:</span> <span class="n">DigitalSignature</span><span class="p">.</span><span class="n">LegallyIdentifiable</span><span class="p">):</span> <span class="n">SignedTransaction</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">fullySigned</span> <span class="p">=</span> <span class="n">allPartySignedTX</span> <span class="p">+</span> <span class="n">notarySignature</span>
<span class="n">logger</span><span class="p">.</span><span class="n">trace</span> <span class="p">{</span> <span class="s">&quot;Built finished transaction, sending back to secondary!&quot;</span> <span class="p">}</span>
<span class="n">send</span><span class="p">(</span><span class="n">otherSide</span><span class="p">,</span> <span class="n">SignaturesFromSeller</span><span class="p">(</span><span class="n">ourSignature</span><span class="p">,</span> <span class="n">notarySignature</span><span class="p">))</span>
<span class="k">return</span> <span class="n">fullySigned</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>It&#8217;s all pretty straightforward from now on. Here <code class="docutils literal"><span class="pre">txBits</span></code> is the raw byte array 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 <code class="docutils literal"><span class="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&#8217;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 protocol instance has a logger (using the SLF4J API) which you can use to log progress
messages.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="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&#8217;t, so they can&#8217;t spend the asset they just purchased! This sort of thing will be fixed in a
future version of the code.</p>
</div>
</div>
<div class="section" id="implementing-the-buyer">
<h2>Implementing the buyer<a class="headerlink" href="#implementing-the-buyer" title="Permalink to this headline"></a></h2>
<p>OK, let&#8217;s do the same for the buyer side:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>@Suspendable
override fun call(): SignedTransaction {
val tradeRequest = receiveAndValidateTradeRequest()
val (ptx, cashSigningPubKeys) = assembleSharedTX(tradeRequest)
val stx = signWithOurKeys(cashSigningPubKeys, ptx)
val signatures = swapSignaturesWithSeller(stx)
logger.trace { &quot;Got signatures from seller, verifying ... &quot; }
val fullySigned = stx + signatures.sellerSig + signatures.notarySig
fullySigned.verifySignatures()
logger.trace { &quot;Signatures received are valid. Trade complete! :-)&quot; }
return fullySigned
}
@Suspendable
private fun receiveAndValidateTradeRequest(): SellerTradeInfo {
// Wait for a trade request to come in from the other side
val maybeTradeRequest = receive&lt;SellerTradeInfo&gt;(otherParty)
maybeTradeRequest.unwrap {
// What is the seller trying to sell us?
val asset = it.assetForSale.state.data
val assetTypeName = asset.javaClass.name
logger.trace { &quot;Got trade request for a $assetTypeName: ${it.assetForSale}&quot; }
if (it.price &gt; acceptablePrice)
throw UnacceptablePriceException(it.price)
if (!typeToBuy.isInstance(asset))
throw AssetMismatchException(typeToBuy.name, assetTypeName)
// Check the transaction that contains the state which is being resolved.
// We only have a hash here, so if we don&#39;t know it already, we have to ask for it.
subProtocol(ResolveTransactionsProtocol(setOf(it.assetForSale.ref.txhash), otherSide))
return it
}
}
@Suspendable
private fun swapSignaturesWithSeller(stx: SignedTransaction): SignaturesFromSeller {
progressTracker.currentStep = SWAPPING_SIGNATURES
logger.trace { &quot;Sending partially signed transaction to seller&quot; }
// TODO: Protect against the seller terminating here and leaving us in the lurch without the final tx.
return sendAndReceive&lt;SignaturesFromSeller&gt;(otherSide, stx).unwrap { it }
}
private fun signWithOurKeys(cashSigningPubKeys: List&lt;PublicKey&gt;, ptx: TransactionBuilder): SignedTransaction {
// Now sign the transaction with whatever keys we need to move the cash.
for (k in cashSigningPubKeys) {
val priv = serviceHub.keyManagementService.toPrivate(k)
ptx.signWith(KeyPair(k, priv))
}
return ptx.toSignedTransaction(checkSufficientSignatures = false)
}
private fun assembleSharedTX(tradeRequest: SellerTradeInfo): Pair&lt;TransactionBuilder, List&lt;PublicKey&gt;&gt; {
val ptx = TransactionType.General.Builder(notary)
// Add input and output states for the movement of cash, by using the Cash contract to generate the states.
val wallet = serviceHub.walletService.currentWallet
val cashStates = wallet.statesOfType&lt;Cash.State&gt;()
val cashSigningPubKeys = Cash().generateSpend(ptx, tradeRequest.price, tradeRequest.sellerOwnerKey, cashStates)
// Add inputs/outputs/a command for the movement of the asset.
ptx.addInputState(tradeRequest.assetForSale)
// Just pick some new public key for now. This won&#39;t be linked with our identity in any way, which is what
// we want for privacy reasons: the key is here ONLY to manage and control ownership, it is not intended to
// reveal who the owner actually is. The key management service is expected to derive a unique key from some
// initial seed in order to provide privacy protection.
val freshKey = serviceHub.keyManagementService.freshKey()
val (command, state) = tradeRequest.assetForSale.state.data.withNewOwner(freshKey.public)
ptx.addOutputState(state, tradeRequest.assetForSale.state.notary)
ptx.addCommand(command, tradeRequest.assetForSale.state.data.owner)
// And add a request for timestamping: it may be that none of the contracts need this! But it can&#39;t hurt
// to have one.
val currentTime = serviceHub.clock.instant()
ptx.setTime(currentTime, 30.seconds)
return Pair(ptx, cashSigningPubKeys)
}
</pre></div>
</div>
</div>
<p>This code is longer but no more complicated. Here are some things to pay attention to:</p>
<ol class="arabic simple">
<li>We do some sanity checking on the received message to ensure we&#8217;re being offered what we expected to be offered.</li>
<li>We create a cash spend in the normal way, by using <code class="docutils literal"><span class="pre">Cash().generateSpend</span></code>. See the contracts tutorial if this
part isn&#8217;t clear.</li>
<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 protocol 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 <code class="docutils literal"><span class="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 protocol 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>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">In the current version of the platform, exceptions thrown during protocol 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>
<div class="section" id="progress-tracking">
<h2>Progress tracking<a class="headerlink" href="#progress-tracking" title="Permalink to this headline"></a></h2>
<p>Not shown in the code snippets above is the usage of the <code class="docutils literal"><span class="pre">ProgressTracker</span></code> API. Progress tracking exports information
from a protocol about where it&#8217;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 <code class="docutils literal"><span class="pre">ProgressTracker</span></code> is constructed with a series of <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">Step</span></code>, which may be defined easily
in one line when using Kotlin. Typical steps might be &#8220;Waiting for response from peer&#8221;, &#8220;Waiting for signature to be
approved&#8221;, &#8220;Downloading and verifying data&#8221; etc.</p>
<p>Each step exposes a label. By default labels are fixed, but by subclassing <code class="docutils literal"><span class="pre">RelabelableStep</span></code>
you can make a step that can update its label on the fly. That&#8217;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&#8217;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
<code class="docutils literal"><span class="pre">ProgressTracker.childrenFor[step]</span> <span class="pre">=</span> <span class="pre">tracker</span></code> map, a tree of steps can be created. It&#8217;s allowed to alter the hierarchy
at runtime, on the fly, and the progress renderers will adapt to that properly. This can be helpful when you don&#8217;t
fully know ahead of time what steps will be required. If you _do_ know what is required, configuring as much of the
hierarchy ahead of time is a good idea, as that will help the users see what is coming up.</p>
<p>Every tracker has not only the steps given to it at construction time, but also the singleton
<code class="docutils literal"><span class="pre">ProgressTracker.UNSTARTED</span></code> step and the <code class="docutils literal"><span class="pre">ProgressTracker.DONE</span></code> step. Once a tracker has become <code class="docutils literal"><span class="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 <a class="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 protocol framework is somewhat integrated with this API. Each <code class="docutils literal"><span class="pre">ProtocolLogic</span></code> may optionally provide a tracker by
overriding the <code class="docutils literal"><span class="pre">protocolTracker</span></code> property (<code class="docutils literal"><span class="pre">getProtocolTracker</span></code> method in Java). If the
<code class="docutils literal"><span class="pre">ProtocolLogic.subProtocol</span></code> method is used, then the tracker of the sub-protocol will be made a child of the current
step in the parent protocol automatically, if the parent is using tracking in the first place. The framework will also
automatically set the current step to <code class="docutils literal"><span class="pre">DONE</span></code> for you, when the protocol is finished.</p>
<p>Because a protocol may sometimes wish to configure the children in its progress hierarchy _before_ the sub-protocol
is constructed, for sub-protocols that always follow the same outline regardless of their parameters it&#8217;s conventional
to define a companion object/static method (for Kotlin/Java respectively) that constructs a tracker, and then allow
the sub-protocol to have the tracker it will use be passed in as a parameter. This allows all trackers to be built
and linked ahead of time.</p>
<p>In future, the progress tracking framework will become a vital part of how exceptions, errors, and other faults are
surfaced to human operators for investigation and resolution.</p>
</div>
<div class="section" id="unit-testing">
<h2>Unit testing<a class="headerlink" href="#unit-testing" title="Permalink to this headline"></a></h2>
<p>A protocol can be a fairly complex thing that interacts with many services and other parties over the network. That
means unit testing one requires some infrastructure to provide lightweight mock implementations. The MockNetwork
provides this testing infrastructure layer; you can find this class in the node module</p>
<p>A good example to examine for learning how to unit test protocols is the <code class="docutils literal"><span class="pre">ResolveTransactionsProtocol</span></code> tests. This
protocol takes care of downloading and verifying transaction graphs, with all the needed dependencies. We start
with this basic skeleton:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ResolveTransactionsProtocolTest</span> <span class="p">{</span>
<span class="k">lateinit</span> <span class="k">var</span> <span class="py">net</span><span class="p">:</span> <span class="n">MockNetwork</span>
<span class="k">lateinit</span> <span class="k">var</span> <span class="py">a</span><span class="p">:</span> <span class="n">MockNetwork</span><span class="p">.</span><span class="n">MockNode</span>
<span class="k">lateinit</span> <span class="k">var</span> <span class="py">b</span><span class="p">:</span> <span class="n">MockNetwork</span><span class="p">.</span><span class="n">MockNode</span>
<span class="k">lateinit</span> <span class="k">var</span> <span class="py">notary</span><span class="p">:</span> <span class="n">Party</span>
<span class="n">@Before</span>
<span class="k">fun</span> <span class="nf">setup</span><span class="p">()</span> <span class="p">{</span>
<span class="n">net</span> <span class="p">=</span> <span class="n">MockNetwork</span><span class="p">()</span>
<span class="k">val</span> <span class="py">nodes</span> <span class="p">=</span> <span class="n">net</span><span class="p">.</span><span class="n">createSomeNodes</span><span class="p">()</span>
<span class="n">a</span> <span class="p">=</span> <span class="n">nodes</span><span class="p">.</span><span class="n">partyNodes</span><span class="p">[</span><span class="m">0</span><span class="p">]</span>
<span class="n">b</span> <span class="p">=</span> <span class="n">nodes</span><span class="p">.</span><span class="n">partyNodes</span><span class="p">[</span><span class="m">1</span><span class="p">]</span>
<span class="n">notary</span> <span class="p">=</span> <span class="n">nodes</span><span class="p">.</span><span class="n">notaryNode</span><span class="p">.</span><span class="n">info</span><span class="p">.</span><span class="n">identity</span>
<span class="n">net</span><span class="p">.</span><span class="n">runNetwork</span><span class="p">()</span>
<span class="p">}</span>
<span class="n">@After</span>
<span class="k">fun</span> <span class="nf">tearDown</span><span class="p">()</span> <span class="p">{</span>
<span class="n">net</span><span class="p">.</span><span class="n">stopNodes</span><span class="p">()</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>We create a mock network in our <code class="docutils literal"><span class="pre">&#64;Before</span></code> setup method and create a couple of nodes. We also record the identity
of the notary in our test network, which will come in handy later. We also tidy up when we&#8217;re done.</p>
<p>Next, we write a test case:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>@Test
fun resolveFromTwoHashes() {
val (stx1, stx2) = makeTransactions()
val p = ResolveTransactionsProtocol(setOf(stx2.id), a.info.identity)
val future = b.services.startProtocol(&quot;resolve&quot;, p)
net.runNetwork()
val results = future.get()
assertEquals(listOf(stx1.id, stx2.id), results.map { it.id })
assertEquals(stx1, b.storage.validatedTransactions.getTransaction(stx1.id))
assertEquals(stx2, b.storage.validatedTransactions.getTransaction(stx2.id))
}
</pre></div>
</div>
</div>
<p>We&#8217;ll take a look at the <code class="docutils literal"><span class="pre">makeTransactions</span></code> function in a moment. For now, it&#8217;s enough to know that it returns two
<code class="docutils literal"><span class="pre">SignedTransaction</span></code> objects, the second of which spends the first. Both transactions are known by node A
but not node B.</p>
<p>The test logic is simple enough: we create the protocol, giving it node A&#8217;s identity as the target to talk to.
Then we start it on node B and use the <code class="docutils literal"><span class="pre">net.runNetwork()</span></code> method to bounce messages around until things have
settled (i.e. there are no more messages waiting to be delivered). All this is done using an in memory message
routing implementation that is fast to initialise and use. Finally, we obtain the result of the protocol and do
some tests on it. We also check the contents of node B&#8217;s database to see that the protocol had the intended effect
on the node&#8217;s persistent state.</p>
<p>Here&#8217;s what <code class="docutils literal"><span class="pre">makeTransactions</span></code> looks like:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">private</span> <span class="k">fun</span> <span class="nf">makeTransactions</span><span class="p">():</span> <span class="n">Pair</span><span class="p">&lt;</span><span class="n">SignedTransaction</span><span class="p">,</span> <span class="n">SignedTransaction</span><span class="p">&gt;</span> <span class="p">{</span>
<span class="c1">// Make a chain of custody of dummy states and insert into node A.</span>
<span class="k">val</span> <span class="py">dummy1</span><span class="p">:</span> <span class="n">SignedTransaction</span> <span class="p">=</span> <span class="n">DummyContract</span><span class="p">.</span><span class="n">generateInitial</span><span class="p">(</span><span class="n">MEGA_CORP</span><span class="p">.</span><span class="n">ref</span><span class="p">(</span><span class="m">1</span><span class="p">),</span> <span class="m">0</span><span class="p">,</span> <span class="n">notary</span><span class="p">).</span><span class="n">let</span> <span class="p">{</span>
<span class="n">it</span><span class="p">.</span><span class="n">signWith</span><span class="p">(</span><span class="n">MEGA_CORP_KEY</span><span class="p">)</span>
<span class="n">it</span><span class="p">.</span><span class="n">signWith</span><span class="p">(</span><span class="n">DUMMY_NOTARY_KEY</span><span class="p">)</span>
<span class="n">it</span><span class="p">.</span><span class="n">toSignedTransaction</span><span class="p">(</span><span class="k">false</span><span class="p">)</span>
<span class="p">}</span>
<span class="k">val</span> <span class="py">dummy2</span><span class="p">:</span> <span class="n">SignedTransaction</span> <span class="p">=</span> <span class="n">DummyContract</span><span class="p">.</span><span class="n">move</span><span class="p">(</span><span class="n">dummy1</span><span class="p">.</span><span class="n">tx</span><span class="p">.</span><span class="n">outRef</span><span class="p">(</span><span class="m">0</span><span class="p">),</span> <span class="n">MINI_CORP_PUBKEY</span><span class="p">).</span><span class="n">let</span> <span class="p">{</span>
<span class="n">it</span><span class="p">.</span><span class="n">signWith</span><span class="p">(</span><span class="n">MEGA_CORP_KEY</span><span class="p">)</span>
<span class="n">it</span><span class="p">.</span><span class="n">signWith</span><span class="p">(</span><span class="n">DUMMY_NOTARY_KEY</span><span class="p">)</span>
<span class="n">it</span><span class="p">.</span><span class="n">toSignedTransaction</span><span class="p">()</span>
<span class="p">}</span>
<span class="n">a</span><span class="p">.</span><span class="n">services</span><span class="p">.</span><span class="n">recordTransactions</span><span class="p">(</span><span class="n">dummy1</span><span class="p">,</span> <span class="n">dummy2</span><span class="p">)</span>
<span class="k">return</span> <span class="n">Pair</span><span class="p">(</span><span class="n">dummy1</span><span class="p">,</span> <span class="n">dummy2</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<p>We&#8217;re using the <code class="docutils literal"><span class="pre">DummyContract</span></code>, a simple test smart contract which stores a single number in its states, along
with ownership and issuer information. You can issue such states, exit them and re-assign ownership (move them).
It doesn&#8217;t do anything else. This code simply creates a transaction that issues a dummy state (the issuer is
<code class="docutils literal"><span class="pre">MEGA_CORP</span></code>, a pre-defined unit test identity), signs it with the test notary and MegaCorp keys and then
converts the builder to the final <code class="docutils literal"><span class="pre">SignedTransaction</span></code>. It then does so again, but this time instead of issuing
it re-assigns ownership instead. The chain of two transactions is finally committed to node A by sending them
directly to the <code class="docutils literal"><span class="pre">a.services.recordTransaction</span></code> method (note that this method doesn&#8217;t check the transactions are
valid).</p>
<p>And that&#8217;s it: you can explore the documentation for the <a class="reference external" href="api/net.corda.node.internal.testing/-mock-network/index.html">MockNode API</a> here.</p>
</div>
<div class="section" id="versioning">
<h2>Versioning<a class="headerlink" href="#versioning" title="Permalink to this headline"></a></h2>
<p>Fibers involve persisting object-serialised stack frames to disk. Although we may do some R&amp;D into in-place upgrades
in future, for now the upgrade process for protocols is simple: you duplicate the code and rename it so it has a
new set of class names. Old versions of the protocol can then drain out of the system whilst new versions are
initiated. When enough time has passed that no old versions are still waiting for anything to happen, the previous
copy of the code can be deleted.</p>
<p>Whilst kind of ugly, this is a very simple approach that should suffice for now.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Protocols are not meant to live for months or years, and by implication they are not meant to implement entire deal
lifecycles. For instance, implementing the entire life cycle of an interest rate swap as a single protocol - whilst
technically possible - would not be a good idea. The platform provides a job scheduler tool that can invoke
protocols for this reason (see &#8220;<a class="reference internal" href="event-scheduling.html"><span class="doc">Event scheduling</span></a>&#8221;)</p>
</div>
</div>
<div class="section" id="future-features">
<h2>Future features<a class="headerlink" href="#future-features" title="Permalink to this headline"></a></h2>
<p>The protocol framework is a key part of the platform and will be extended in major ways in future. Here are some of
the features we have planned:</p>
<ul class="simple">
<li>Identity based addressing</li>
<li>Exposing progress trackers to local (inside the firewall) clients using message queues and/or WebSockets</li>
<li>Exception propagation and management, with a &#8220;protocol hospital&#8221; tool to manually provide solutions to unavoidable
problems (e.g. the other side doesn&#8217;t know the trade)</li>
<li>Being able to interact with internal apps and tools via HTTP and similar</li>
<li>Being able to interact with people, either via some sort of external ticketing system, or email, or a custom UI.
For example to implement human transaction authorisations.</li>
<li>A standard library of protocols that can be easily sub-classed by local developers in order to integrate internal
reporting logic, or anything else that might be required as part of a communications lifecycle.</li>
</ul>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="oracles.html" class="btn btn-neutral float-right" title="Writing oracle services" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tutorial-clientrpc-api.html" class="btn btn-neutral" title="Client RPC API" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2016, Distributed Ledger Group, LLC.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'latest',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
Reference in New Issue Copy Permalink