corda/docs/source/event-scheduling.rst

.. highlight:: kotlin
.. raw:: html

   <script type="text/javascript" src="_static/jquery.js"></script>
   <script type="text/javascript" src="_static/codesets.js"></script>

Event scheduling
================

This article explains our experimental 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.

Introduction
------------

Many financial instruments have time sensitive components to them.  For example, an Interest Rate Swap has a schedule
for when:

* Interest rate fixings should take place for floating legs, so that the interest rate used as the basis for payments
  can be agreed.
* Any payments between the parties are expected to take place.
* Any payments between the parties become overdue.

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 *next* 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 *was* the next event becomes irrelevant and obsolete
and the next time sensitive event is determined by any successor contract state.

Knowing when the next time sensitive event is due to occur is useful, but typically some *activity* is expected to take
place when this event occurs.  We already have a model for business processes in the form of the protocol state machines,
so in the platform we have introduced the concept of *scheduled activities* 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.

How to implement scheduled events
---------------------------------

There are two main steps to implementing scheduled events:

* Have your ``ContractState`` implementation also implement ``SchedulableState``.  This requires a method named
  ``nextScheduledActivity`` to be implemented which returns an optional ``ScheduledActivity`` instance.
  ``ScheduledActivity`` captures what ``ProtocolLogic`` instance each node will run, to perform the activity, and when it
  will run is described by a ``java.time.Instant``.  Once your state implements this interface and is tracked by the
  wallet, it can expect to be queried for the next activity when recorded via the ``ServiceHub.recordTransactions``
  method during protocols execution.
* If nothing suitable exists, implement a ``ProtocolLogic`` to be executed by each node as the activity itself.
  The important thing to remember is that each node that is party to the transaction, in the current implementation,
  will execute the same ``ProtocolLogic`` so that needs to establish roles in the business process based on the contract
  state and the node it is running on, and follow different but complementary paths through the business logic.

.. note:: 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 ``ZonedDateTime``.

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.

The production and consumption of ``ContractStates`` is observed by the scheduler and the activities associated with
any consumed states are unscheduled.  Any newly produced states are then queried via the ``nextScheduledActivity``
method and if they do not return ``null`` then that activity is scheduled based on the content of the
``ScheduledActivity`` object returned.

An example
----------

Let's take an example of the Interest Rate Swap fixings for our scheduled events.  The first task is to implement the
``nextScheduledActivity`` method on the ``State``.


.. container:: codeset

   .. sourcecode:: kotlin

        override fun nextScheduledActivity(thisStateRef: StateRef,
                                           protocolLogicRefFactory: ProtocolLogicRefFactory): ScheduledActivity? {
            val nextFixingOf = nextFixingOf() ?: return null

            // This is perhaps not how we should determine the time point in the business day, but instead expect the
            // schedule to detail some of these aspects.
            val (instant, duration) = suggestInterestRateAnnouncementTimeWindow(index = nextFixingOf.name,
                                                                                source = floatingLeg.indexSource,
                                                                                date = nextFixingOf.forDay)
            return ScheduledActivity(protocolLogicRefFactory.create(TwoPartyDealProtocol.FixingRoleDecider::class.java,
                                                                    thisStateRef, duration), instant)
        }

The first thing this does is establish if there are any remaining fixings.  If there are none, then it returns ``null``
to indicate that there is no activity to schedule.  Otherwise it calculates the ``Instant`` 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 ``ProtocolLogic`` will be handed the ``StateRef`` for the interest
rate swap ``State`` in question, as well as a tolerance ``Duration`` of how long to wait after the activity is triggered
for the interest rate before indicating an error.

.. note:: The use of the factory to create a ``ProtocolLogicRef`` instance to embed in the ``ScheduledActivity``.  This is a
   way to create a reference to the ``ProtocolLogic`` class and it's constructor parameters to instantiate that can be
   checked against a per node whitelist of approved and allowable types as part of our overall security sandboxing.

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 ``FixingSessionInitiationHandler`` which
is responsible for starting a ``ProtocolLogic`` to perform one role in the fixing protocol with the ``sessionID`` sent
by the ``FixingRoleDecider`` 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.