<liclass="toctree-l1"><aclass="reference internal"href="tutorial-cordapp.html#running-the-cordapp-template">Running the CorDapp template</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="tutorial-cordapp.html#interacting-with-the-cordapp-template">Interacting with the CorDapp template</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="tutorial-cordapp.html#extending-the-cordapp-template">Extending the CorDapp template</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="#implementing-an-oracle-with-continuously-varying-data">Implementing an oracle with continuously varying data</a><ul>
<liclass="toctree-l2"><aclass="reference internal"href="#implement-the-core-classes">Implement the core classes</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#binding-to-the-network-via-cordapp-plugin">Binding to the network via CorDapp plugin</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="#providing-client-sub-flows-for-querying-and-signing">Providing client sub-flows for querying and signing</a></li>
</ul>
</li>
<liclass="toctree-l1"><aclass="reference internal"href="#using-an-oracle">Using an oracle</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="setting-up-a-corda-network.html">Introduction - What is a corda network?</a></li>
<liclass="toctree-l1"><aclass="reference internal"href="setting-up-a-corda-network.html#setting-up-your-own-network">Setting up your own network</a></li>
<h2>Asserting continuously varying data<aclass="headerlink"href="#asserting-continuously-varying-data"title="Permalink to this headline">¶</a></h2>
<p>Let’s look at the interest rates oracle that can be found in the <codeclass="docutils literal"><spanclass="pre">NodeInterestRates</span></code> file. This is an example of
an oracle that uses a command because the current interest rate fix is a constantly changing fact.</p>
<p>The obvious way to implement such a service is like this:</p>
<olclass="arabic simple">
<li>The creator of the transaction that depends on the interest rate sends it to the oracle.</li>
<li>The oracle inserts a command with the rate and signs the transaction.</li>
<li>The oracle sends it back.</li>
</ol>
<p>But this has a problem - it would mean that the oracle has to be the first entity to sign the transaction, which might impose
ordering constraints we don’t want to deal with (being able to get all parties to sign in parallel is a very nice thing).
So the way we actually implement it is like this:</p>
<olclass="arabic simple">
<li>The creator of the transaction that depends on the interest rate asks for the current rate. They can abort at this point
if they want to.</li>
<li>They insert a command with that rate and the time it was obtained into the transaction.</li>
<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), that identifies the version of the data being requested,
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>
as the Oracle can know which, potentially historical, value it is being asked to sign for. This is an important
technique for continously varying data.</p>
<p>The <codeclass="docutils literal"><spanclass="pre">query</span></code> method takes a deadline, which is a point in time the requester is willing to wait until for the necessary
data to be available. Not every oracle will need this. This can be useful where data is expected to be available on a
particular schedule and we use scheduling functionality to automatically launch the processing associated with it.
We can schedule for the expected announcement (or publish) time and give a suitable deadline at which the lack of the
information being available and the delay to processing becomes significant and may need to be escalated.</p>
<h2>Hiding transaction data from the oracle<aclass="headerlink"href="#hiding-transaction-data-from-the-oracle"title="Permalink to this headline">¶</a></h2>
<p>Because the transaction is sent to the oracle for signing, ordinarily the oracle would be able to see the entire contents
of that transaction including the inputs, output contract states and all the commands, not just the one (in this case)
relevant command. This is an obvious privacy leak for the other participants. We currently solve this with
<codeclass="docutils literal"><spanclass="pre">FilteredTransaction</span></code>-s and the use of Merkle Trees. These reveal only the necessary parts of the transaction to the
oracle but still allow it to sign it by providing the Merkle hashes for the remaining parts. See <aclass="reference internal"href="merkle-trees.html"><spanclass="doc">Transaction tear-offs</span></a> for
<h2>Pay-per-play oracles<aclass="headerlink"href="#pay-per-play-oracles"title="Permalink to this headline">¶</a></h2>
<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 still 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
<h1>Implementing an oracle with continuously varying data<aclass="headerlink"href="#implementing-an-oracle-with-continuously-varying-data"title="Permalink to this headline">¶</a></h1>
<h2>Implement the core classes<aclass="headerlink"href="#implement-the-core-classes"title="Permalink to this headline">¶</a></h2>
<p>The key is to implement your oracle in a similar way to the <codeclass="docutils literal"><spanclass="pre">NodeInterestRates.Oracle</span></code> outline we gave above with
both <codeclass="docutils literal"><spanclass="pre">query</span></code> and <codeclass="docutils literal"><spanclass="pre">sign</span></code> methods. Typically you would want one class that encapsulates the parameters to the <codeclass="docutils literal"><spanclass="pre">query</span></code>
method (<codeclass="docutils literal"><spanclass="pre">FixOf</span></code> above), and a <codeclass="docutils literal"><spanclass="pre">CommandData</span></code> implementation (<codeclass="docutils literal"><spanclass="pre">Fix</span></code> above) that encapsulates both an instance of
that parameter class and an instance of whatever the result of the <codeclass="docutils literal"><spanclass="pre">query</span></code> is (<codeclass="docutils literal"><spanclass="pre">BigDecimal</span></code> above).</p>
<p>The <codeclass="docutils literal"><spanclass="pre">NodeInterestRates.Oracle</span></code> allows querying for multiple <codeclass="docutils literal"><spanclass="pre">Fix</span></code>-es but that is not necessary and is
provided for the convenience of callers who might need multiple and can do it all in one query request. Likewise
the <em>deadline</em> functionality is optional and can be avoided initially.</p>
<p>Let’s see what parameters we pass to the constructor of this oracle.</p>
<p>Here we see the oracle needs to have its own identity, so it can check which transaction commands it is expected to
sign for, and also needs a pair of signing keys with which it signs transactions. The clock is used for the deadline
functionality which we will not discuss further here.</p>
<p>Assuming you have a data source and can query it, it should be very easy to implement your <codeclass="docutils literal"><spanclass="pre">query</span></code> method and the
parameter and <codeclass="docutils literal"><spanclass="pre">CommandData</span></code> classes.</p>
<p>Let’s see how the <codeclass="docutils literal"><spanclass="pre">sign</span></code> method for <codeclass="docutils literal"><spanclass="pre">NodeInterestRates.Oracle</span></code> is written:</p>
<h2>Binding to the network via CorDapp plugin<aclass="headerlink"href="#binding-to-the-network-via-cordapp-plugin"title="Permalink to this headline">¶</a></h2>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Before reading any further, we advise that you understand the concept of flows and how to write them and use
them. See <aclass="reference internal"href="flow-state-machines.html"><spanclass="doc">Writing flows</span></a>. Likewise some understanding of Cordapps, plugins and services will be helpful.
See <aclass="reference internal"href="creating-a-cordapp.html"><spanclass="doc">CorDapps Background</span></a>.</p>
</div>
<p>The first step is to create a service to host the oracle on the network. Let’s see how that’s implemented:</p>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span> class Service(val services: PluginServiceHub) : AcceptsFileUpload, SingletonSerializeAsToken() {
val oracle: Oracle by lazy {
val myNodeInfo = services.myInfo
val myIdentity = myNodeInfo.serviceIdentities(type).first()
val mySigningKey = services.keyManagementService.toKeyPair(myIdentity.owningKey.keys)
Oracle(myIdentity, mySigningKey, services.clock)
}
init {
// Note: access to the singleton oracle property is via the registered SingletonSerializeAsToken Service.
// Otherwise the Kryo serialisation of the call stack in the Quasar Fiber extends to include
override val progressTracker = ProgressTracker(RECEIVED, SENDING)
init {
progressTracker.currentStep = RECEIVED
}
@Suspendable
override fun call(): Unit {
val request = receive<RatesFixFlow.QueryRequest>(otherParty).unwrap { it }
val answers = service.oracle.query(request.queries, request.deadline)
progressTracker.currentStep = SENDING
send(otherParty, answers)
}
}
</pre></div>
</div>
<p>This may look complicated, but really it’s made up of some relatively simple elements (in the order they appear in the code):</p>
<olclass="arabic simple">
<li>Accept a <codeclass="docutils literal"><spanclass="pre">PluginServiceHub</span></code> in the constructor. This is your interface to the Corda node.</li>
<li>Ensure you extend the abstract class <codeclass="docutils literal"><spanclass="pre">SingletonSerializeAsToken</span></code> (see <aclass="reference internal"href="corda-plugins.html"><spanclass="doc">The Corda plugin framework</span></a>).</li>
<li>Create an instance of your core oracle class that has the <codeclass="docutils literal"><spanclass="pre">query</span></code> and <codeclass="docutils literal"><spanclass="pre">sign</span></code> methods as discussed above.</li>
<li>Register your client sub-flows (in this case both in <codeclass="docutils literal"><spanclass="pre">RatesFixFlow</span></code>. See the next section) for querying and
signing as initiating your service flows that actually do the querying and signing using your core oracle class instance.</li>
<li>Implement your service flows that call your core oracle class instance.</li>
</ol>
<p>The final step is to register your service with the node via the plugin mechanism. Do this by
implementing a plugin. Don’t forget the resources file to register it with the <codeclass="docutils literal"><spanclass="pre">ServiceLoader</span></code> framework
(see <aclass="reference internal"href="corda-plugins.html"><spanclass="doc">The Corda plugin framework</span></a>).</p>
<h2>Providing client sub-flows for querying and signing<aclass="headerlink"href="#providing-client-sub-flows-for-querying-and-signing"title="Permalink to this headline">¶</a></h2>
<p>We mentioned the client sub-flow briefly above. They are the mechanism that clients, in the form of other flows, will
interact with your oracle. Typically there will be one for querying and one for signing. Let’s take a look at
those for <codeclass="docutils literal"><spanclass="pre">NodeInterestRates.Oracle</span></code>.</p>
<p>You’ll note that the <codeclass="docutils literal"><spanclass="pre">FixSignFlow</span></code> requires a <codeclass="docutils literal"><spanclass="pre">FilterFuns</span></code> instance with the appropriate filter to include only
the <codeclass="docutils literal"><spanclass="pre">Fix</span></code> commands. You can find a further explanation of this in <aclass="reference internal"href="merkle-trees.html"><spanclass="doc">Transaction tear-offs</span></a>.</p>
</div>
</div>
<divclass="section"id="using-an-oracle">
<h1>Using an oracle<aclass="headerlink"href="#using-an-oracle"title="Permalink to this headline">¶</a></h1>
<p>The oracle is invoked through sub-flows to query for values, add them to the transaction as commands and then get
the transaction signed by the the oracle. Following on from the above examples, this is all encapsulated in a sub-flow
called <codeclass="docutils literal"><spanclass="pre">RatesFixFlow</span></code>. Here’s the <codeclass="docutils literal"><spanclass="pre">call</span></code> method of that flow.</p>
<li>Queries the oracle for the fact using the client sub-flow for querying from above.</li>
<li>Does some quick validation.</li>
<li>Adds the command to the transaction containing the fact to be signed for by the oracle.</li>
<li>Calls an extension point that allows clients to generate output states based on the fact from the oracle.</li>
<li>Requests the signature from the oracle using the client sub-flow for signing from above.</li>
<li>Adds the signature returned from the oracle.</li>
</ol>
<p>Here’s an example of it in action from <codeclass="docutils literal"><spanclass="pre">FixingFlow.Fixer</span></code>.</p>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span> fun filterCommands(c: Command) = oracleParty.owningKey in c.signers && c.value is Fix
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>.
