corda/docs/build/html/event-scheduling.html
2016-11-11 12:52:29 +01:00

346 lines
18 KiB
HTML

<!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>Event scheduling &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="Contract catalogue" href="contract-catalogue.html"/>
<link rel="prev" title="Using attachments" href="tutorial-attachments.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"><a class="reference internal" href="protocol-state-machines.html">Protocol state machines</a></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 current"><a class="current reference internal" href="#">Event scheduling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#how-to-implement-scheduled-events">How to implement scheduled events</a></li>
<li class="toctree-l2"><a class="reference internal" href="#an-example">An example</a></li>
</ul>
</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>Event scheduling</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/event-scheduling.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="event-scheduling">
<h1>Event scheduling<a class="headerlink" href="#event-scheduling" title="Permalink to this headline"></a></h1>
<p>This article explains our approach to modelling time based events in code. It explains how a contract
state can expose an upcoming event and what action to take if the scheduled time for that event is reached.</p>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>Many financial instruments have time sensitive components to them. For example, an Interest Rate Swap has a schedule
for when:</p>
<ul class="simple">
<li>Interest rate fixings should take place for floating legs, so that the interest rate used as the basis for payments
can be agreed.</li>
<li>Any payments between the parties are expected to take place.</li>
<li>Any payments between the parties become overdue.</li>
</ul>
<p>Each of these is dependent on the current state of the financial instrument. What payments and interest rate fixings
have already happened should already be recorded in the state, for example. This means that the <em>next</em> time sensitive
event is thus a property of the current contract state. By next, we mean earliest in chronological terms, that is still
due. If a contract state is consumed in the UTXO model, then what <em>was</em> the next event becomes irrelevant and obsolete
and the next time sensitive event is determined by any successor contract state.</p>
<p>Knowing when the next time sensitive event is due to occur is useful, but typically some <em>activity</em> is expected to take
place when this event occurs. We already have a model for business processes in the form of <a class="reference internal" href="protocol-state-machines.html"><span class="doc">protocols</span></a>,
so in the platform we have introduced the concept of <em>scheduled activities</em> that can invoke protocol state machines
at a scheduled time. A contract state can optionally described the next scheduled activity for itself. If it omits
to do so, then nothing will be scheduled.</p>
</div>
<div class="section" id="how-to-implement-scheduled-events">
<h2>How to implement scheduled events<a class="headerlink" href="#how-to-implement-scheduled-events" title="Permalink to this headline"></a></h2>
<p>There are two main steps to implementing scheduled events:</p>
<ul class="simple">
<li>Have your <code class="docutils literal"><span class="pre">ContractState</span></code> implementation also implement <code class="docutils literal"><span class="pre">SchedulableState</span></code>. This requires a method named
<code class="docutils literal"><span class="pre">nextScheduledActivity</span></code> to be implemented which returns an optional <code class="docutils literal"><span class="pre">ScheduledActivity</span></code> instance.
<code class="docutils literal"><span class="pre">ScheduledActivity</span></code> captures what <code class="docutils literal"><span class="pre">ProtocolLogic</span></code> instance each node will run, to perform the activity, and when it
will run is described by a <code class="docutils literal"><span class="pre">java.time.Instant</span></code>. Once your state implements this interface and is tracked by the
wallet, it can expect to be queried for the next activity when committed to the wallet.</li>
<li>If nothing suitable exists, implement a <code class="docutils literal"><span class="pre">ProtocolLogic</span></code> to be executed by each node as the activity itself.
The important thing to remember is that in the current implementation, each node that is party to the transaction
will execute the same <code class="docutils literal"><span class="pre">ProtocolLogic</span></code>, so it needs to establish roles in the business process based on the contract
state and the node it is running on. Each side will follow different but complementary paths through the business logic.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The scheduler&#8217;s clock always operates in the UTC time zone for uniformity, so any time zone logic must be
performed by the contract, using <code class="docutils literal"><span class="pre">ZonedDateTime</span></code>.</p>
</div>
<p>In the short term, until we have automatic protocol session set up, you will also likely need to install a network
handler to help with obtaining a unqiue and secure random session. An example is described below.</p>
<p>The production and consumption of <code class="docutils literal"><span class="pre">ContractStates</span></code> is observed by the scheduler and the activities associated with
any consumed states are unscheduled. Any newly produced states are then queried via the <code class="docutils literal"><span class="pre">nextScheduledActivity</span></code>
method and if they do not return <code class="docutils literal"><span class="pre">null</span></code> then that activity is scheduled based on the content of the
<code class="docutils literal"><span class="pre">ScheduledActivity</span></code> object returned. Be aware that this <em>only</em> happens if the wallet considers the state
&#8220;relevant&#8221;, for instance, because the owner of the node also owns that state. States that your node happens to
encounter but which aren&#8217;t related to yourself will not have any activities scheduled.</p>
</div>
<div class="section" id="an-example">
<h2>An example<a class="headerlink" href="#an-example" title="Permalink to this headline"></a></h2>
<p>Let&#8217;s take an example of the interest rate swap fixings for our scheduled events. The first task is to implement the
<code class="docutils literal"><span class="pre">nextScheduledActivity</span></code> method on the <code class="docutils literal"><span class="pre">State</span></code>.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>override fun nextScheduledActivity(thisStateRef: StateRef,
protocolLogicRefFactory: ProtocolLogicRefFactory): ScheduledActivity? {
val nextFixingOf = nextFixingOf() ?: return null
val (instant, duration) = suggestInterestRateAnnouncementTimeWindow(index = nextFixingOf.name,
source = floatingLeg.indexSource,
date = nextFixingOf.forDay)
return ScheduledActivity(protocolLogicRefFactory.create(TwoPartyDealProtocol.FixingRoleDecider::class.java,
thisStateRef, duration), instant)
}
</pre></div>
</div>
</div>
<p>The first thing this does is establish if there are any remaining fixings. If there are none, then it returns <code class="docutils literal"><span class="pre">null</span></code>
to indicate that there is no activity to schedule. Otherwise it calculates the <code class="docutils literal"><span class="pre">Instant</span></code> at which the interest rate
should become available and schedules an activity at that time to work out what roles each node will take in the fixing
business process and to take on those roles. That <code class="docutils literal"><span class="pre">ProtocolLogic</span></code> will be handed the <code class="docutils literal"><span class="pre">StateRef</span></code> for the interest
rate swap <code class="docutils literal"><span class="pre">State</span></code> in question, as well as a tolerance <code class="docutils literal"><span class="pre">Duration</span></code> of how long to wait after the activity is triggered
for the interest rate before indicating an error.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This is a way to create a reference to the ProtocolLogic class and its constructor parameters to
instantiate. The reference can be checked against a per-node whitelist of approved and allowable types as
part of our overall security sandboxing.</p>
</div>
<p>As previously mentioned, we currently need a small network handler to assist with session setup until the work to
automate that is complete. See the interest rate swap specific implementation <code class="docutils literal"><span class="pre">FixingSessionInitiationHandler</span></code> which
is responsible for starting a <code class="docutils literal"><span class="pre">ProtocolLogic</span></code> to perform one role in the fixing protocol with the <code class="docutils literal"><span class="pre">sessionID</span></code> sent
by the <code class="docutils literal"><span class="pre">FixingRoleDecider</span></code> on the other node which then launches the other role in the fixing protocol. Currently
the handler needs to be manually installed in the node.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="contract-catalogue.html" class="btn btn-neutral float-right" title="Contract catalogue" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tutorial-attachments.html" class="btn btn-neutral" title="Using attachments" 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>