<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/src/main/kotlin/com/r3corda/protocols/TwoPartyTradeProtocol.kt</span></code>.</p>
<spanclass="k">override</span><spanclass="k">fun</span><spanclass="nf">toString</span><spanclass="p">()</span><spanclass="p">=</span><spanclass="s">"The submitted asset didn't match the expected type: $expectedTypeName vs $typeName"</span>
<p>This code defines several classes nested inside the main <codeclass="docutils literal"><spanclass="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>
<li><codeclass="docutils literal"><spanclass="pre">notaryNode:</span><spanclass="pre">NodeInfo</span></code> - the entry in the network map for the chosen notary. See “<aclass="reference internal"href="consensus.html"><spanclass="doc">Consensus model</span></a>” for more
<li><codeclass="docutils literal"><spanclass="pre">assetToSell:</span><spanclass="pre">StateAndRef<OwnableState></span></code> - a pointer to the ledger entry that represents the thing being sold.</li>
<li><codeclass="docutils literal"><spanclass="pre">price:</span><spanclass="pre">Amount<Currency></span></code> - the agreed on price that the asset is being sold for (without an issuer constraint).</li>
<li><codeclass="docutils literal"><spanclass="pre">myKeyPair:</span><spanclass="pre">KeyPair</span></code> - the key pair that controls the asset being sold. It will be used to sign the transaction.</li>
<li><codeclass="docutils literal"><spanclass="pre">acceptablePrice:</span><spanclass="pre">Amount<Currency></span></code> - the price that was agreed upon out of band. If the seller specifies
a price less than or equal to this, then the trade will go ahead.</li>
<li><codeclass="docutils literal"><spanclass="pre">typeToBuy:</span><spanclass="pre">Class<out</span><spanclass="pre">OwnableState></span></code> - the type of state that is being purchased. This is used to check that the
sell side of the protocol isn’t trying to sell us the wrong thing, whether by accident or on purpose.</li>
<p>Alright, so using this protocol shouldn’t be too hard: in the simplest case we can just create a Buyer or Seller
with the details of the trade, depending on who we are. We then have to start the protocol in some way. Just
calling the <codeclass="docutils literal"><spanclass="pre">call</span></code> function ourselves won’t work: instead we need to ask the framework to start the protocol for
us. More on that in a moment.</p>
</div>
<divclass="section"id="suspendable-functions">
<h2>Suspendable functions<aclass="headerlink"href="#suspendable-functions"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal"><spanclass="pre">call</span></code> function of the buyer/seller classes is marked with the <codeclass="docutils literal"><spanclass="pre">@Suspendable</span></code> annotation. What does this mean?</p>
<p>As mentioned above, our 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
<pclass="last">Java 9 is likely to remove this pre-marking requirement completely.</p>
</div>
</div>
<divclass="section"id="starting-your-protocol">
<h2>Starting your protocol<aclass="headerlink"href="#starting-your-protocol"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal"><spanclass="pre">StateMachineManager</span></code> is the class responsible for taking care of all running protocols in a node. It knows
how to register handlers with the messaging system (see “<aclass="reference internal"href="messaging.html"><spanclass="doc">Networking and messaging</span></a>”) and iterate the right state machine
when messages arrive. It provides the send/receive/sendAndReceive calls that let the code request network
interaction and it will save/restore serialised versions of the fiber at the right times.</p>
<p>Protocols can be invoked in several ways. For instance, they can be triggered by scheduled events,
see “<aclass="reference internal"href="event-scheduling.html"><spanclass="doc">Event scheduling</span></a>” to learn more about this. Or they can be triggered 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 <codeclass="docutils literal"><spanclass="pre">ServiceHub.invokeProtocolAsync</span></code> method. This takes a
Java reflection <codeclass="docutils literal"><spanclass="pre">Class</span></code> object that describes the protocol class to use (in this case, either <codeclass="docutils literal"><spanclass="pre">Buyer</span></code> or <codeclass="docutils literal"><spanclass="pre">Seller</span></code>).
It also takes a set of arguments to pass to the constructor. Because it’s possible for 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 <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">ServiceHub.invokeProtocolAsync</span></code>. The other side
has to be registered by its node to respond to the initiating protocol via <codeclass="docutils literal"><spanclass="pre">ServiceHubInternal.registerProtocolInitiator</span></code>.
In our example it doesn’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>
<p>This is telling the buyer node to fire up an instance of <codeclass="docutils literal"><spanclass="pre">Buyer</span></code> (the code in the lambda) when the initiating protocol
is a seller (<codeclass="docutils literal"><spanclass="pre">Seller::class</span></code>).</p>
<p>Let’s implement the <codeclass="docutils literal"><spanclass="pre">Seller.call</span></code> method. This will be run when the protocol is invoked.</p>
<spanclass="k">throw</span><spanclass="n">SignatureException</span><spanclass="p">(</span><spanclass="s">"The set of missing signatures is not as expected: ${missingSigs.toStringsShort()} vs ${expected.toStringsShort()}"</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 amount of cash"</span><spanclass="p">)</span>
<p>Let’s break this down. We fill out the initial protocol message with the trade info, and then call <codeclass="docutils literal"><spanclass="pre">sendAndReceive</span></code>.
<p>Once <codeclass="docutils literal"><spanclass="pre">sendAndReceive</span></code> is called, the call method will be suspended into a continuation and saved to persistent
storage. If the node crashes or is restarted, the 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
<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
<p>In this code snippet we are using the <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">subProtocol</span></code> method which
returns the result of the protocol’s execution directly. Behind the scenes all this is doing is wiring up progress
tracking (discussed more below) and then running the objects <codeclass="docutils literal"><spanclass="pre">call</span></code> method. Because this little helper method can
be on the stack when network IO takes place, we mark it as <codeclass="docutils literal"><spanclass="pre">@Suspendable</span></code>.</p>
<p>Going back to the previous code snippet, we use a subprotocol called <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">LedgerTransaction</span></code>
objects, but we don’t need them here so we just ignore the return value.</p>
<spanclass="n">logger</span><spanclass="p">.</span><spanclass="n">trace</span><spanclass="p">{</span><spanclass="s">"Built finished transaction, sending back to secondary!"</span><spanclass="p">}</span>
<p>It’s all pretty straightforward from now on. Here <codeclass="docutils literal"><spanclass="pre">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 <codeclass="docutils literal"><spanclass="pre">sendSignatures</span></code>, we take the two signatures we obtained and add them to the partial transaction we were sent.
There is an overload for the + operator so signatures can be added to a SignedTransaction easily. Finally, we wrap the
<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
<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>
<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>
<h2>Unit testing<aclass="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 <codeclass="docutils literal"><spanclass="pre">ResolveTransactionsProtocol</span></code> tests. This
protocol takes care of downloading and verifying transaction graphs, with all the needed dependencies. We start
<p>We create a mock network in our <codeclass="docutils literal"><spanclass="pre">@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’re done.</p>
<p>We’ll take a look at the <codeclass="docutils literal"><spanclass="pre">makeTransactions</span></code> function in a moment. For now, it’s enough to know that it returns two
<codeclass="docutils literal"><spanclass="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’s identity as the target to talk to.
Then we start it on node B and use the <codeclass="docutils literal"><spanclass="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’s database to see that the protocol had the intended effect
on the node’s persistent state.</p>
<p>Here’s what <codeclass="docutils literal"><spanclass="pre">makeTransactions</span></code> looks like:</p>
<p>We’re using the <codeclass="docutils literal"><spanclass="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’t do anything else. This code simply creates a transaction that issues a dummy state (the issuer is
<codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">a.services.recordTransaction</span></code> method (note that this method doesn’t check the transactions are
valid).</p>
<p>And that’s it: you can explore the documentation for the <aclass="reference external"href="api/com.r3corda.node.internal.testing/-mock-network/index.html">MockNode API</a> here.</p>
<h2>Versioning<aclass="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&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>
<divclass="admonition warning">
<pclass="first admonition-title">Warning</p>
<pclass="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 “<aclass="reference internal"href="event-scheduling.html"><spanclass="doc">Event scheduling</span></a>”)</p>
</div>
</div>
<divclass="section"id="future-features">
<h2>Future features<aclass="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>
<ulclass="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 “protocol hospital” tool to manually provide solutions to unavoidable
problems (e.g. the other side doesn’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>
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>.
