<h1>Event scheduling<aclass="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>
<divclass="section"id="introduction">
<h2>Introduction<aclass="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>
<ulclass="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 <aclass="reference internal"href="protocol-state-machines.html"><spanclass="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
<h2>How to implement scheduled events<aclass="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>
<ulclass="simple">
<li>Have your <codeclass="docutils literal"><spanclass="pre">ContractState</span></code> implementation also implement <codeclass="docutils literal"><spanclass="pre">SchedulableState</span></code>. This requires a method named
<codeclass="docutils literal"><spanclass="pre">nextScheduledActivity</span></code> to be implemented which returns an optional <codeclass="docutils literal"><spanclass="pre">ScheduledActivity</span></code> instance.
<codeclass="docutils literal"><spanclass="pre">ScheduledActivity</span></code> captures what <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> instance each node will run, to perform the activity, and when it
will run is described by a <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="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>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">The scheduler’s clock always operates in the UTC time zone for uniformity, so any time zone logic must be
performed by the contract, using <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">nextScheduledActivity</span></code>
method and if they do not return <codeclass="docutils literal"><spanclass="pre">null</span></code> then that activity is scheduled based on the content of the
<codeclass="docutils literal"><spanclass="pre">ScheduledActivity</span></code> object returned. Be aware that this <em>only</em> happens if the wallet considers the state
“relevant”, for instance, because the owner of the node also owns that state. States that your node happens to
encounter but which aren’t related to yourself will not have any activities scheduled.</p>
</div>
<divclass="section"id="an-example">
<h2>An example<aclass="headerlink"href="#an-example"title="Permalink to this headline">¶</a></h2>
<p>Let’s take an example of the interest rate swap fixings for our scheduled events. The first task is to implement the
<codeclass="docutils literal"><spanclass="pre">nextScheduledActivity</span></code> method on the <codeclass="docutils literal"><spanclass="pre">State</span></code>.</p>
<divclass="codeset container">
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span>override fun nextScheduledActivity(thisStateRef: StateRef,
<p>The first thing this does is establish if there are any remaining fixings. If there are none, then it returns <codeclass="docutils literal"><spanclass="pre">null</span></code>
to indicate that there is no activity to schedule. Otherwise it calculates the <codeclass="docutils literal"><spanclass="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 <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> will be handed the <codeclass="docutils literal"><spanclass="pre">StateRef</span></code> for the interest
rate swap <codeclass="docutils literal"><spanclass="pre">State</span></code> in question, as well as a tolerance <codeclass="docutils literal"><spanclass="pre">Duration</span></code> of how long to wait after the activity is triggered
for the interest rate before indicating an error.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="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 <codeclass="docutils literal"><spanclass="pre">FixingSessionInitiationHandler</span></code> which
is responsible for starting a <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> to perform one role in the fixing protocol with the <codeclass="docutils literal"><spanclass="pre">sessionID</span></code> sent
by the <codeclass="docutils literal"><spanclass="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>
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>.
