<h2>A two party trading protocol<aclass="headerlink"href="#a-two-party-trading-protocol"title="Permalink to this headline">¶</a></h2>
<p>We would like to implement the “hello world” 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’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>
<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
<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
<p>You can find the implementation of this protocol in the file <codeclass="docutils literal"><spanclass="pre">contracts/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’s the <em>seller</em> who initiates contact with the buyer, not vice-versa as you might imagine.</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>
<li>It defines a several classes nested inside the main <codeclass="docutils literal"><spanclass="pre">TwoPartyTradeProtocol</span></code> singleton, and a couple of methods, one
<li>It defines the “trade topic”, which is just a string that namespaces this protocol. The prefix “platform.” is reserved
by the DLG, but you can define your own protocols using standard Java-style reverse DNS notation.</li>
<li>The <codeclass="docutils literal"><spanclass="pre">runBuyer</span></code> and <codeclass="docutils literal"><spanclass="pre">runSeller</span></code> methods take a number of parameters that specialise the protocol for this run,
use them to construct a <codeclass="docutils literal"><spanclass="pre">Buyer</span></code> or <codeclass="docutils literal"><spanclass="pre">Seller</span></code> object respectively, and then add the new instances to the
<codeclass="docutils literal"><spanclass="pre">StateMachineManager</span></code>. The purpose of this class is described below. The <codeclass="docutils literal"><spanclass="pre">smm.add</span></code> method takes a logger name as
the first parameter, this is just a standard JDK logging identifier string, and the instance to add.</li>
</ul>
<p>Going through the data needed to become a seller, we have:</p>
<ulclass="simple">
<li><codeclass="docutils literal"><spanclass="pre">timestampingAuthority:</span><spanclass="pre">LegallyIdentifiableNode</span></code> - a reference to a node on the P2P network that acts as a trusted
timestamper. The use of timestamping is described in <aclass="reference internal"href="data-model.html"><em>Data model</em></a>.</li>
<li><codeclass="docutils literal"><spanclass="pre">otherSide:</span><spanclass="pre">SingleMessageRecipient</span></code> - the network address of the node with which you are trading.</li>
<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</span></code> - the agreed on price that the asset is being sold for.</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>
<li><codeclass="docutils literal"><spanclass="pre">buyerSessionID:</span><spanclass="pre">Long</span></code> - a unique number that identifies this trade to the buyer. It is expected that the buyer
knows that the trade is going to take place and has sent you such a number already. (This field may go away in a future
<li><codeclass="docutils literal"><spanclass="pre">acceptablePrice:</span><spanclass="pre">Amount</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 protocol isn’t trying to sell us the wrong thing, whether by accident or on purpose.</li>
<li><codeclass="docutils literal"><spanclass="pre">sessionID:</span><spanclass="pre">Long</span></code> - the session ID that was handed to the seller in order to start the protocol.</li>
</ul>
<p>The run methods return a <codeclass="docutils literal"><spanclass="pre">ListenableFuture</span></code> that will complete when the protocol has finished.</p>
to either runBuyer or runSeller, depending on who we are, and then call <codeclass="docutils literal"><spanclass="pre">.get()</span></code> on resulting object to
<p>Finally, we define a couple of exceptions, and two classes that will be used as a protocol message called
<codeclass="docutils literal"><spanclass="pre">SellerTradeInfo</span></code> and <codeclass="docutils literal"><spanclass="pre">SignaturesFromSeller</span></code>.</p>
<h2>Suspendable methods<aclass="headerlink"href="#suspendable-methods"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal"><spanclass="pre">call</span></code> method 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 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 <codeclass="docutils literal"><spanclass="pre">@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 <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">A future version of Java is likely to remove this pre-marking requirement completely.</p>
with a <codeclass="docutils literal"><spanclass="pre">MessagingService</span></code> 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 store a serialised copy of
each state machine before it’s suspended to wait for the network.</p>
<p>To get a <codeclass="docutils literal"><spanclass="pre">StateMachineManager</span></code>, you currently have to build one by passing in a <codeclass="docutils literal"><spanclass="pre">ServiceHub</span></code> and a thread or thread
pool which it can use. This will change in future so don’t worry about the details of this too much: just check the
unit tests to see how it’s done.</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 invoked by the platform when the protocol is started by the
<p>Here we see the outline of the procedure. We receive a proposed trade transaction from the buyer and check that it’s
valid. Then we sign with our own key, request a timestamping authority to assert with another signature that the
timestamp in the transaction (if any) is valid, and finally we send back both our signature and the TSA’s signature.
Finally, we hand back to the code that invoked the protocol the finished transaction in a couple of different forms.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last"><codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> classes can be composed together. Here, we see the use of the <codeclass="docutils literal"><spanclass="pre">subProtocol</span></code> method, which
is given an instance of <codeclass="docutils literal"><spanclass="pre">TimestampingProtocol</span></code>. This protocol will run to completion and yield a result, almost
as if it’s a regular method call. In fact, under the hood, all the <codeclass="docutils literal"><spanclass="pre">subProtocol</span></code> method does is pass the current
fiber object into the newly created object and then run <codeclass="docutils literal"><spanclass="pre">call()</span></code> on it ... so it basically _is_ just a method call.
This is where we can see the benefits of using continuations/fibers as a programming model.</p>
</div>
<p>Let’s fill out the <codeclass="docutils literal"><spanclass="pre">receiveAndCheckProposedTransaction()</span></code> method.</p>
<spanclass="k">throw</span><spanclass="n">SignatureException</span><spanclass="p">(</span><spanclass="s">"The set of missing signatures is not as expected: $missingSigs"</span><spanclass="p">)</span>
<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="k">throw</span><spanclass="n">IllegalArgumentException</span><spanclass="p">(</span><spanclass="s">"Transaction is not sending us the right amounnt of cash"</span><spanclass="p">)</span>
<spanclass="c1">// There are all sorts of funny games a malicious secondary might play here, we should fix them:</span>
<spanclass="c1">//</span>
<spanclass="c1">// - This tx may attempt to send some assets we aren't intending to sell to the secondary, if</span>
<spanclass="c1">// we're reusing keys! So don't reuse keys!</span>
<spanclass="c1">// - This tx may include output states that impose odd conditions on the movement of the cash,</span>
<spanclass="c1">// once we implement state pairing.</span>
<spanclass="c1">//</span>
<spanclass="c1">// but the goal of this code is not to be fully secure (yet), but rather, just to find good ways to</span>
<spanclass="c1">// express protocol state machines on top of the messaging layer.</span>
the initial protocol message, and then call <codeclass="docutils literal"><spanclass="pre">sendAndReceive</span></code>. This function takes a few arguments:</p>
<ulclass="simple">
<li>The topic string that ensures the message is routed to the right bit of code in the other side’s node.</li>
<li>The session IDs that ensure the messages don’t get mixed up with other simultaneous trades.</li>
<p>Once <codeclass="docutils literal"><spanclass="pre">sendAndReceive</span></code> is called, the call method will be suspended into a continuation. When it gets back we’ll do a log
<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. Here, our scrubbing
simply involves checking the signatures on it. Then we go ahead and check all the dependencies of this partial
transaction for validity. Here’s the code to do that:</p>
<p>This is simple enough: we mark the method as <codeclass="docutils literal"><spanclass="pre">@Suspendable</span></code> because we’re going to invoke a sub-protocol, extract the
IDs of the transactions the proposed transaction depends on, and then uses a protocol provided by the system to download
and check them all. This protocol does a breadth-first search over the dependency graph, bottoming out at issuance
transactions that don’t have any inputs themselves. Once the node has audited the transaction history, all the dependencies
are committed to the node’s local database so they won’t be checked again next time.</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 should be all pretty straightforward: here, <codeclass="docutils literal"><spanclass="pre">txBits</span></code> is the raw byte array representing the transaction.</p>
<p>In <codeclass="docutils literal"><spanclass="pre">sendSignatures</span></code>, we take the two signatures we calculated, then add them to the partial transaction we were sent.
We provide 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>
<li>We create a cash spend in the normal way, by using <codeclass="docutils literal"><spanclass="pre">Cash().generateSpend</span></code>. See the contracts tutorial if this isn’t
<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>
<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>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="last">When accessing things via the <codeclass="docutils literal"><spanclass="pre">serviceHub</span></code> field, avoid the temptation to stuff a reference into a local variable.
If you do this then next time your protocol waits to receive an object, the system will try and serialise all your
local variables and end up trying to serialise, e.g. the timestamping service, which doesn’t make any conceptual
sense. The <codeclass="docutils literal"><spanclass="pre">serviceHub</span></code> field is defined by the <codeclass="docutils literal"><spanclass="pre">ProtocolStateMachine</span></code> superclass and is marked transient so
<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 protocol 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>
<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[step]</span><spanclass="pre">=</span><spanclass="pre">tracker</span></code> map, a tree of steps can be created. It’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’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
<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 protocol framework is somewhat integrated with this API. Each <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> may optionally provide a tracker by
overriding the <codeclass="docutils literal"><spanclass="pre">protocolTracker</span></code> property (<codeclass="docutils literal"><spanclass="pre">getProtocolTracker</span></code> method in Java). If the
<codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="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’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>
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>.
