<liclass="toctree-l2"><aclass="reference internal"href="#the-two-basic-approaches">The two basic approaches</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#asserting-continuously-varying-data-that-is-publicly-known">Asserting continuously varying data that is publicly known</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#asserting-occasionally-varying-data-that-is-not-publicly-known">Asserting occasionally varying data that is not publicly known</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#implementing-oracles-in-the-framework">Implementing oracles in the framework</a></li>
<h2>Asserting continuously varying data that is publicly known<aclass="headerlink"href="#asserting-continuously-varying-data-that-is-publicly-known"title="Permalink to this headline">¶</a></h2>
<p>Let’s look at the timestamping oracle that can be found in the <codeclass="docutils literal"><spanclass="pre">TimestamperService</span></code> class. This is an example of
an oracle that uses a command because the current time is a constantly changing fact that everybody knows.</p>
<p>The most obvious way to implement such a service would be:</p>
<olclass="arabic simple">
<li>The creator of the transaction that depends on the time reads their local clock</li>
<li>They insert a command with that time into the transaction</li>
<li>They then send it to the oracle for signing.</li>
</ol>
<p>But this approach has a problem. There will never be exact clock synchronisation between the party creating the
transaction and the oracle. This is not only due to physics, network latencies etc but because between inserting the
command and getting the oracle to sign there may be many other steps, like sending the transaction to other parties
involved in the trade as well, or even requesting human signoff. Thus the time observed by the oracle may be quite
different to the time observed in step 1. This problem can occur any time an oracle attests to a constantly changing
value.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">It is assumed that “true time” for a timestamping oracle means GPS/NaviStar time as defined by the atomic
clocks at the US Naval Observatory. This time feed is extremely accurate and available globally for free.</p>
</div>
<p>We fix it by including explicit tolerances in the command, which is defined like this:</p>
<spanclass="k">throw</span><spanclass="n">IllegalArgumentException</span><spanclass="p">(</span><spanclass="s">"At least one of before/after must be specified"</span><spanclass="p">)</span>
<h2>Asserting occasionally varying data that is not publicly known<aclass="headerlink"href="#asserting-occasionally-varying-data-that-is-not-publicly-known"title="Permalink to this headline">¶</a></h2>
<p>Sometimes you may want a fact that changes, but is not entirely continuous. Additionally the exact value may not be
public, or may only be semi-public (e.g. easily available to some entities on the network but not all). An example of
this would be a LIBOR interest rate fix.</p>
<p>In this case, the following design can be used. The oracle service provides a query API which returns the current value,
and a signing service that signs a transaction if the data in the command matches the answer being returned by the
query API. Probably the query response contains some sort of timestamp as well, so the service can recognise values
that were true in the past but no longer are (this is arguably a part of the fact being asserted).</p>
<p>Because the signature covers the transaction, and transactions may end up being forwarded anywhere, the fact itself
is independently checkable. However, this approach can be useful when the data itself costs money, because the act
of issuing the signature in the first place can be charged for (e.g. by requiring the submission of a fresh
<codeclass="docutils literal"><spanclass="pre">Cash.State</span></code> that has been re-assigned to a key owned by the oracle service). Because the signature covers the
<em>transaction</em> and not only the <em>fact</em>, this allows for a kind of weak pseudo-DRM over data feeds. Whilst a smart
contract could in theory include a transaction parsing and signature checking library, writing a contract in this way
would be conclusive evidence of intent to disobey the rules of the service (<em>res ipsa loquitur</em>). In an environment
where parties are legally identifiable, usage of such a contract would by itself be sufficient to trigger some sort of
punishment.</p>
<p>Here is an extract from the <codeclass="docutils literal"><spanclass="pre">NodeService.Oracle</span></code> class and supporting types:</p>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span><spanclass="cm">/** A [FixOf] identifies the question side of a fix: what day, tenor and type of fix ("LIBOR", "EURIBOR" etc) */</span>
<p>Because the fix contains a timestamp (the <codeclass="docutils literal"><spanclass="pre">forDay</span></code> field), there can be an arbitrary delay between a fix being
requested via <codeclass="docutils literal"><spanclass="pre">query</span></code> and the signature being requested via <codeclass="docutils literal"><spanclass="pre">sign</span></code>.</p>
<h2>Implementing oracles in the framework<aclass="headerlink"href="#implementing-oracles-in-the-framework"title="Permalink to this headline">¶</a></h2>
<p>Implementation involves the following steps:</p>
<olclass="arabic simple">
<li>Defining a high level oracle class, that exposes the basic API operations.</li>
<li>Defining a lower level service class, that binds network messages to the API.</li>
<li>Defining a protocol using the <aclass="reference internal"href="protocol-state-machines.html"><spanclass="doc">Protocol state machines</span></a> framework to make it easy for a client to interact
<p>An example of how to do this can be found in the <codeclass="docutils literal"><spanclass="pre">NodeInterestRates.Oracle</span></code>, <codeclass="docutils literal"><spanclass="pre">NodeInterestRates.Service</span></code> and
<codeclass="docutils literal"><spanclass="pre">RateFixProtocol</span></code> classes. The exact details of how this code works will change in future, so for now consulting
the protocols tutorial and the code for the server-side oracles implementation will have to suffice. There will be more
detail added once the platform APIs have settled down.</p>
<p>Currently, there’s no network map service, so the location and identity keys of an oracle must be distributed out of
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>.
