2016-03-14 15:57:36 +00:00
<!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" >
2016-05-09 16:13:23 +00:00
< title > Writing oracle services — R3 Corda latest documentation< / title >
2016-03-14 15:57:36 +00:00
< link rel = "stylesheet" href = "_static/css/custom.css" type = "text/css" / >
2016-05-09 16:13:23 +00:00
< link rel = "top" title = "R3 Corda latest documentation" href = "index.html" / >
2016-06-30 12:49:28 +00:00
< link rel = "next" title = "Event scheduling" href = "event-scheduling.html" / >
2016-03-14 15:57:36 +00:00
< link rel = "prev" title = "Protocol state machines" href = "protocol-state-machines.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" >
2016-05-09 16:13:23 +00:00
< a href = "index.html" class = "icon icon-home" > R3 Corda
2016-03-14 15:57:36 +00:00
< / 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’ 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 >
2016-06-30 12:49:28 +00:00
< 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 = "consensus.html" > Consensus model< / a > < / li >
2016-03-14 15:57:36 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "messaging.html" > Networking and messaging< / a > < / li >
2016-08-30 11:05:32 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "creating-a-cordapp.html" > Creating a Cordapp< / a > < / li >
2016-05-09 16:13:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "running-the-demos.html" > Running the demos< / a > < / li >
2016-03-14 15:57:36 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "node-administration.html" > Node administration< / a > < / li >
2016-08-09 10:21:07 +00:00
< / ul >
< p class = "caption" > < span class = "caption-text" > Contracts< / span > < / p >
< ul >
2016-08-30 11:05:32 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "contract-catalogue.html" > Contract catalogue< / a > < / li >
2016-08-09 10:21:07 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "contract-irs.html" > Interest Rate Swaps< / a > < / li >
2016-03-14 15:57:36 +00:00
< / ul >
< p class = "caption" > < span class = "caption-text" > Tutorials< / span > < / p >
< ul class = "current" >
2016-05-24 11:27:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "where-to-start.html" > Where to start< / a > < / li >
2016-05-23 16:05:37 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "tutorial-contract.html" > Writing a contract< / a > < / li >
2016-07-12 16:52:52 +00:00
< 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 >
2016-03-14 15:57:36 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "protocol-state-machines.html" > Protocol state machines< / a > < / li >
2016-04-13 09:29:54 +00:00
< li class = "toctree-l1 current" > < a class = "current reference internal" href = "#" > Writing oracle services< / a > < ul >
2016-03-14 15:57:36 +00:00
< li class = "toctree-l2" > < a class = "reference internal" href = "#introduction" > Introduction< / a > < / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "#the-two-basic-approaches" > The two basic approaches< / a > < / li >
2016-08-30 11:05:32 +00:00
< li class = "toctree-l2" > < a class = "reference internal" href = "#asserting-continuously-varying-data" > Asserting continuously varying data< / a > < / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "#pay-per-play-oracles" > Pay-per-play oracles< / a > < / li >
2016-03-14 15:57:36 +00:00
< / ul >
< / li >
2016-06-30 12:49:28 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "event-scheduling.html" > Event scheduling< / a > < / li >
2016-03-14 15:57:36 +00:00
< / ul >
< p class = "caption" > < span class = "caption-text" > Appendix< / span > < / p >
< ul >
2016-05-23 16:05:37 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "release-process.html" > Release process< / a > < / li >
2016-06-13 17:27:53 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "release-process.html#steps-to-cut-a-release" > Steps to cut a release< / a > < / li >
2016-05-24 11:27:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "release-notes.html" > Release notes< / a > < / li >
2016-03-14 15:57:36 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "visualiser.html" > Using the visualiser< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "codestyle.html" > Code style guide< / a > < / li >
2016-05-09 16:13:23 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "building-the-docs.html" > Building the documentation< / a > < / li >
2016-03-14 15:57:36 +00:00
< / 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 >
2016-05-09 16:13:23 +00:00
< a href = "index.html" > R3 Corda< / a >
2016-03-14 15:57:36 +00:00
< / nav >
< div class = "wy-nav-content" >
< div class = "rst-content" >
2016-04-13 09:29:54 +00:00
2016-03-14 15:57:36 +00:00
< div role = "navigation" aria-label = "breadcrumbs navigation" >
< ul class = "wy-breadcrumbs" >
< li > < a href = "index.html" > Docs< / a > » < / li >
< li > Writing oracle services< / li >
< li class = "wy-breadcrumbs-aside" >
< a href = "_sources/oracles.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 = "writing-oracle-services" >
< h1 > Writing oracle services< a class = "headerlink" href = "#writing-oracle-services" title = "Permalink to this headline" > ¶< / a > < / h1 >
< p > This article covers < em > oracles< / em > : network services that link the ledger to the outside world by providing facts that
affect the validity of transactions.< / p >
2016-08-30 11:05:32 +00:00
< p > The current prototype includes an example oracle that provides an interest rate fixing service. It is used by the
IRS trading demo app.< / p >
2016-03-14 15:57:36 +00:00
< div class = "section" id = "introduction" >
< h2 > Introduction< a class = "headerlink" href = "#introduction" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > Oracles are a key concept in the block chain/decentralised ledger space. They can be essential for many kinds of
application, because we often wish to condition a transaction on some fact being true or false, but the ledger itself
has a design that is essentially functional: all transactions are < em > pure< / em > and < em > immutable< / em > . Phrased another way, a
smart contract cannot perform any input/output or depend on any state outside of the transaction itself. There is no
way to download a web page or interact with the user, in a smart contract. It must be this way because everyone must
be able to independently check a transaction and arrive at an identical conclusion for the ledger to maintan its
integrity: if a transaction could evaluate to “ valid” on one computer and then “ invalid” a few minutes later on a
different computer, the entire shared ledger concept wouldn’ t work.< / p >
< p > But it is often essential that transactions do depend on data from the outside world, for example, verifying that an
interest rate swap is paying out correctly may require data on interest rates, verifying that a loan has reached
maturity requires knowledge about the current time, knowing which side of a bet receives the payment may require
arbitrary facts about the real world (e.g. the bankruptcy or solvency of a company or country) ... and so on.< / p >
< p > We can solve this problem by introducing services that create digitally signed data structures which assert facts.
These structures can then be used as an input to a transaction and distributed with the transaction data itself. Because
the statements are themselves immutable and signed, it is impossible for an oracle to change its mind later and
invalidate transactions that were previously found to be valid. In contrast, consider what would happen if a contract
could do an HTTP request: it’ s possible that an answer would change after being downloaded, resulting in loss of
consensus (breaks).< / p >
< / div >
< div class = "section" id = "the-two-basic-approaches" >
< h2 > The two basic approaches< a class = "headerlink" href = "#the-two-basic-approaches" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > The architecture provides two ways of implementing oracles with different tradeoffs:< / p >
< ol class = "arabic simple" >
< li > Using commands< / li >
< li > Using attachments< / li >
< / ol >
< p > When a fact is encoded in a command, it is embedded in the transaction itself. The oracle then acts as a co-signer to
the entire transaction. The oracle’ s signature is valid only for that transaction, and thus even if a fact (like a
stock price) does not change, every transaction that incorporates that fact must go back to the oracle for signing.< / p >
2016-08-30 11:05:32 +00:00
< p > When a fact is encoded as an attachment, it is a separate object to the transaction and is referred to by hash.
2016-03-14 15:57:36 +00:00
Nodes download attachments from peers at the same time as they download transactions, unless of course the node has
already seen that attachment, in which case it won’ t fetch it again. Contracts have access to the contents of
2016-08-30 11:05:32 +00:00
attachments when they run.< / p >
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
< p class = "last" > Currently attachments do not support digital signing, but this is a planned feature.< / p >
< / div >
2016-03-14 15:57:36 +00:00
< p > As you can see, both approaches share a few things: they both allow arbitrary binary data to be provided to transactions
(and thus contracts). The primary difference is whether the data is a freely reusable, standalone object or whether it’ s
integrated with a transaction.< / p >
< p > Here’ s a quick way to decide which approach makes more sense for your data source:< / p >
< ul class = "simple" >
< li > Is your data < em > continuously changing< / em > , like a stock price, the current time, etc? If yes, use a command.< / li >
< li > Is your data < em > commercially valuable< / em > , like a feed which you are not allowed to resell unless it’ s incorporated into
a business deal? If yes, use a command, so you can charge money for signing the same fact in each unique business
context.< / li >
< li > Is your data < em > very small< / em > , like a single number? If yes, use a command.< / li >
< li > Is your data < em > large< / em > , < em > static< / em > and < em > commercially worthless< / em > , for instance, a holiday calendar? If yes, use an
attachment.< / li >
< li > Is your data < em > intended for human consumption< / em > , like a PDF of legal prose, or an Excel spreadsheet? If yes, use an
attachment.< / li >
< / ul >
< / div >
2016-08-30 11:05:32 +00:00
< div class = "section" id = "asserting-continuously-varying-data" >
< h2 > Asserting continuously varying data< a class = "headerlink" href = "#asserting-continuously-varying-data" title = "Permalink to this headline" > ¶< / a > < / h2 >
2016-03-14 15:57:36 +00:00
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
2016-08-30 11:05:32 +00:00
< p class = "last" > A future version of the platform will include a complete tutorial on implementing this type of oracle.< / p >
2016-03-14 15:57:36 +00:00
< / div >
2016-08-30 11:05:32 +00:00
< p > Let’ s look at the interest rates oracle that can be found in the < code class = "docutils literal" > < span class = "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 >
< ol class = "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 >
< ol class = "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 >
< li > They then send it to the oracle for signing, along with everyone else in parallel. The oracle checks that the command
has correct data for the asserted time, and signs if so.< / li >
< / ol >
2016-03-14 15:57:36 +00:00
< p > This same technique can be adapted to other types of oracle.< / p >
2016-08-30 11:05:32 +00:00
< p > The oracle consists of a core class that implements the query/sign operations (for easy unit testing), and then a separate
class that binds it to the network layer.< / p >
2016-03-14 15:57:36 +00:00
< p > Here is an extract from the < code class = "docutils literal" > < span class = "pre" > NodeService.Oracle< / span > < / code > class and supporting types:< / p >
2016-04-13 09:29:54 +00:00
< div class = "highlight-kotlin" > < div class = "highlight" > < pre > < span > < / span > < span class = "cm" > /** A [FixOf] identifies the question side of a fix: what day, tenor and type of fix (" LIBOR" , " EURIBOR" etc) */< / span >
< span class = "k" > data< / span > < span class = "k" > class< / span > < span class = "nc" > FixOf< / span > < span class = "p" > (< / span > < span class = "k" > val< / span > < span class = "py" > name< / span > < span class = "p" > :< / span > < span class = "n" > String< / span > < span class = "p" > ,< / span > < span class = "k" > val< / span > < span class = "py" > forDay< / span > < span class = "p" > :< / span > < span class = "n" > LocalDate< / span > < span class = "p" > ,< / span > < span class = "k" > val< / span > < span class = "py" > ofTenor< / span > < span class = "p" > :< / span > < span class = "n" > Duration< / span > < span class = "p" > )< / span >
2016-03-14 15:57:36 +00:00
< span class = "cm" > /** A [Fix] represents a named interest rate, on a given day, for a given duration. It can be embedded in a tx. */< / span >
2016-04-13 09:29:54 +00:00
< span class = "k" > data< / span > < span class = "k" > class< / span > < span class = "nc" > Fix< / span > < span class = "p" > (< / span > < span class = "k" > val< / span > < span class = "py" > of< / span > < span class = "p" > :< / span > < span class = "n" > FixOf< / span > < span class = "p" > ,< / span > < span class = "k" > val< / span > < span class = "py" > value< / span > < span class = "p" > :< / span > < span class = "n" > BigDecimal< / span > < span class = "p" > )< / span > < span class = "p" > :< / span > < span class = "n" > CommandData< / span >
2016-03-14 15:57:36 +00:00
< span class = "k" > class< / span > < span class = "nc" > Oracle< / span > < span class = "p" > {< / span >
< span class = "k" > fun< / span > < span class = "nf" > query< / span > < span class = "p" > (< / span > < span class = "n" > queries< / span > < span class = "p" > :< / span > < span class = "n" > List< / span > < span class = "p" > < < / span > < span class = "n" > FixOf< / span > < span class = "p" > > ):< / span > < span class = "n" > List< / span > < span class = "p" > < < / span > < span class = "n" > Fix< / span > < span class = "p" > > < / span >
< span class = "k" > fun< / span > < span class = "nf" > sign< / span > < span class = "p" > (< / span > < span class = "n" > wtx< / span > < span class = "p" > :< / span > < span class = "n" > WireTransaction< / span > < span class = "p" > ):< / span > < span class = "n" > DigitalSignature< / span > < span class = "p" > .< / span > < span class = "n" > LegallyIdentifiable< / span >
< span class = "p" > }< / span >
< / pre > < / div >
< / div >
< p > Because the fix contains a timestamp (the < code class = "docutils literal" > < span class = "pre" > forDay< / span > < / code > field), there can be an arbitrary delay between a fix being
requested via < code class = "docutils literal" > < span class = "pre" > query< / span > < / code > and the signature being requested via < code class = "docutils literal" > < span class = "pre" > sign< / span > < / code > .< / p >
< / div >
2016-08-30 11:05:32 +00:00
< div class = "section" id = "pay-per-play-oracles" >
< h2 > Pay-per-play oracles< a class = "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
< code class = "docutils literal" > < span class = "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 >
2016-03-14 15:57:36 +00:00
< / div >
< / div >
< / div >
< / div >
< footer >
< div class = "rst-footer-buttons" role = "navigation" aria-label = "footer navigation" >
2016-06-30 12:49:28 +00:00
< a href = "event-scheduling.html" class = "btn btn-neutral float-right" title = "Event scheduling" accesskey = "n" > Next < span class = "fa fa-arrow-circle-right" > < / span > < / a >
2016-03-14 15:57:36 +00:00
< a href = "protocol-state-machines.html" class = "btn btn-neutral" title = "Protocol state machines" accesskey = "p" > < span class = "fa fa-arrow-circle-left" > < / span > Previous< / a >
< / div >
< hr / >
< div role = "contentinfo" >
< p >
2016-05-09 16:13:23 +00:00
© Copyright 2016, Distributed Ledger Group, LLC.
2016-03-14 15:57:36 +00:00
< / 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 >
