corda/docs/build/html/key-concepts-consensus-notaries.html
Clinton Alexander 9a2963bca9 Docs regen.
2017-02-22 10:59:02 +00:00

451 lines
26 KiB
HTML

<!-- If you edit this, then please make the same changes to layout_for_doc_website.html, as that is used for the web
doc site generation which we put analytics tracking on to identify any potential problem pages -->
<!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">
<title>Consensus and notaries &mdash; R3 Corda latest documentation</title>
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
<link rel="top" title="R3 Corda latest documentation" href="index.html"/>
<link rel="next" title="Vault" href="key-concepts-vault.html"/>
<link rel="prev" title="Flow framework" href="key-concepts-flow-framework.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">
<a href="index.html" class="icon icon-home"> R3 Corda
</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>
API reference: <a href="api/kotlin/corda/index.html">Kotlin</a>/ <a href="api/javadoc/index.html">JavaDoc</a>
<br>
<a href="https://discourse.corda.net">Discourse Forums</a>
<br>
<a href="http://slack.corda.net">Slack</a>
<br>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Getting started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What&#8217;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="getting-set-up-fault-finding.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
<li class="toctree-l1"><a class="reference internal" href="CLI-vs-IDE.html">CLI vs IDE</a></li>
</ul>
<p class="caption"><span class="caption-text">Key concepts</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="key-concepts.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-ecosystem.html">Corda ecosystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-data-model.html">Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-core-types.html">Core types</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-financial-model.html">Financial model</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-flow-framework.html">Flow framework</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Consensus and notaries</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#consensus-model">Consensus model</a></li>
<li class="toctree-l2"><a class="reference internal" href="#notary">Notary</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#multiple-notaries">Multiple notaries</a></li>
<li class="toctree-l3"><a class="reference internal" href="#changing-notaries">Changing notaries</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#validation">Validation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#timestamping">Timestamping</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-vault.html">Vault</a></li>
<li class="toctree-l1"><a class="reference internal" href="key-concepts-security-model.html">Security model</a></li>
</ul>
<p class="caption"><span class="caption-text">CorDapps</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html">CorDapp basics</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html">The example CorDapp</a></li>
</ul>
<p class="caption"><span class="caption-text">The Corda node</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="clientrpc.html">Client RPC</a></li>
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
<li class="toctree-l1"><a class="reference internal" href="persistence.html">Persistence</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="corda-configuration-file.html">Node configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="corda-plugins.html">The Corda plugin framework</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-services.html">Brief introduction to the node services</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-explorer.html">Node Explorer</a></li>
<li class="toctree-l1"><a class="reference internal" href="permissioning.html">Network permissioning</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract.html">Writing a contract</a></li>
<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>
<li class="toctree-l1"><a class="reference internal" href="contract-upgrade.html">Upgrading Contracts</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-integration-testing.html">Integration testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-clientrpc-api.html">Client RPC API tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-building-transactions.html">Building transactions</a></li>
<li class="toctree-l1"><a class="reference internal" href="flow-state-machines.html">Writing flows</a></li>
<li class="toctree-l1"><a class="reference internal" href="flow-testing.html">Writing flow tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="running-a-notary.html">Running a notary service</a></li>
<li class="toctree-l1"><a class="reference internal" href="using-a-notary.html">Using a notary service</a></li>
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-attachments.html">Using attachments</a></li>
<li class="toctree-l1"><a class="reference internal" href="event-scheduling.html">Event scheduling</a></li>
</ul>
<p class="caption"><span class="caption-text">Other</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
<li class="toctree-l1"><a class="reference internal" href="clauses.html">Clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="merkle-trees.html">Transaction tear-offs</a></li>
</ul>
<p class="caption"><span class="caption-text">Component library</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="contract-catalogue.html">Contract catalogue</a></li>
<li class="toctree-l1"><a class="reference internal" href="contract-irs.html">Interest rate swaps</a></li>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="loadtesting.html">Load testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="setting-up-a-corda-network.html">What is a corda network?</a></li>
<li class="toctree-l1"><a class="reference internal" href="secure-coding-guidelines.html">Secure coding guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-process.html">Release process</a></li>
<li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="further-notes-on-kotlin.html">Further notes on Kotlin</a></li>
<li class="toctree-l1"><a class="reference internal" href="publishing-corda.html">Publishing Corda</a></li>
<li class="toctree-l1"><a class="reference internal" href="azure-vm.html">Working with the Corda Demo on Azure Marketplace</a></li>
</ul>
<p class="caption"><span class="caption-text">Glossary</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
</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>
<a href="index.html">R3 Corda</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Consensus and notaries</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/key-concepts-consensus-notaries.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">
<div class="section" id="consensus-and-notaries">
<h1>Consensus and notaries<a class="headerlink" href="#consensus-and-notaries" title="Permalink to this headline"></a></h1>
<p>A notary is a service that provides transaction ordering and timestamping.</p>
<p>Notaries are expected to be composed of multiple mutually distrusting parties who use a standard consensus algorithm.
Notaries are identified by and sign with <a class="reference internal" href="key-concepts-core-types.html#composite-keys"><span class="std std-ref">Composite Keys</span></a>. Notaries accept transactions submitted to them for processing
and either return a signature over the transaction, or a rejection error that states that a double spend attempt has occurred.</p>
<p>Corda has &#8220;pluggable&#8221; notary services to improve privacy, scalability, legal-system compatibility and algorithmic agility.
The platform currently provides validating and non-validating notaries, and a distributed RAFT implementation.</p>
<div class="section" id="consensus-model">
<h2>Consensus model<a class="headerlink" href="#consensus-model" title="Permalink to this headline"></a></h2>
<p>The fundamental unit of consensus in Corda is the <strong>state</strong>. Consensus can be divided into two parts:</p>
<ol class="arabic simple">
<li>Consensus over state <strong>validity</strong> &#8211; parties can reach certainty that a transaction is accepted by the contracts pointed
to by the input and output states, and has all the required signatures. This is achieved by parties independently running
the same contract code and validation logic (as described in <span class="xref doc">data model</span>)</li>
<li>Consensus over state <strong>uniqueness</strong> &#8211; parties can reach certainty the output states created in a transaction are the
unique successors to the input states consumed by that transaction (in other words &#8211; an input state has not been previously
consumed)</li>
</ol>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The current model is still a <strong>work in progress</strong> and everything described in this article can and is likely to change</p>
</div>
</div>
<div class="section" id="notary">
<h2>Notary<a class="headerlink" href="#notary" title="Permalink to this headline"></a></h2>
<p>A <strong>notary</strong> is an authority responsible for attesting that for a given transaction, it has not signed another transaction
consuming any of the same input states. Every <strong>state</strong> has an appointed notary:</p>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="cm">/**</span>
<span class="cm"> * A wrapper for [ContractState] containing additional platform-level state information.</span>
<span class="cm"> * This is the definitive state that is stored on the ledger and used in transaction outputs</span>
<span class="cm"> */</span>
<span class="k">data</span> <span class="k">class</span> <span class="nc">TransactionState</span><span class="p">&lt;</span><span class="k">out</span> <span class="n">T</span> <span class="p">:</span> <span class="n">ContractState</span><span class="p">&gt;(</span>
<span class="cm">/** The custom contract state */</span>
<span class="k">val</span> <span class="py">data</span><span class="p">:</span> <span class="n">T</span><span class="p">,</span>
<span class="cm">/** Identity of the notary that ensures the state is not used as an input to a transaction more than once */</span>
<span class="k">val</span> <span class="py">notary</span><span class="p">:</span> <span class="n">Party</span><span class="p">)</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Transactions are signed by a notary to ensure their input states are <strong>valid</strong> (apart from <em>issue</em> transactions, containing no input states).
Furthermore, when using a validating notary, a transaction is only valid if all its dependencies are also valid.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The notary is a logical concept and can itself be a distributed entity, potentially a cluster maintained by mutually distrusting parties</p>
</div>
<p>When the notary is requested to sign a transaction, it either signs it, attesting that the outputs are the <strong>unique</strong>
successors of the inputs, or provides conflict information for any input state that has been consumed by another transaction
it has already signed. In doing so, the notary provides the point of finality in the system. Until the notary signature
is obtained, parties cannot be sure that an equally valid, but conflicting, transaction will not be regarded as confirmed.
After the signature is obtained, the parties know that the inputs to this transaction have been uniquely consumed by this transaction.
Hence, it is the point at which we can say finality has occurred.</p>
<div class="section" id="multiple-notaries">
<h3>Multiple notaries<a class="headerlink" href="#multiple-notaries" title="Permalink to this headline"></a></h3>
<p>More than one notary can exist in a network. This gives the following benefits:</p>
<ul class="simple">
<li><strong>Custom behaviour</strong>. We can have both validating and privacy preserving Notaries &#8211; parties can make a choice based
on their specific requirements.</li>
<li><strong>Load balancing</strong>. Spreading the transaction load over multiple notaries will allow higher transaction throughput in
the platform overall</li>
<li><strong>Low latency</strong>. Latency could be minimised by choosing a notary physically closer the transacting parties</li>
</ul>
</div>
<div class="section" id="changing-notaries">
<h3>Changing notaries<a class="headerlink" href="#changing-notaries" title="Permalink to this headline"></a></h3>
<p>A transaction should only be signed by a notary if all of its input states point to the same notary.
In cases where a transaction involves states controlled by multiple notaries, the states first have to be repointed to the same notary.
This is achieved by using a special type of transaction whose sole output state is identical to its sole input state except for its designated notary.
Ensuring that all input states point to the same notary is the responsibility of each involved party
(it is another condition for an output state of the transaction to be <strong>valid</strong>)</p>
<p>To change the notary for an input state, use the <code class="docutils literal"><span class="pre">NotaryChangeFlow</span></code>. For example:</p>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Suspendable</span>
<span class="k">fun</span> <span class="nf">changeNotary</span><span class="p">(</span><span class="n">originalState</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">ContractState</span><span class="p">&gt;,</span>
<span class="n">newNotary</span><span class="p">:</span> <span class="n">Party</span><span class="p">):</span> <span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">ContractState</span><span class="p">&gt;</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">flow</span> <span class="p">=</span> <span class="n">NotaryChangeFlow</span><span class="p">.</span><span class="n">Instigator</span><span class="p">(</span><span class="n">originalState</span><span class="p">,</span> <span class="n">newNotary</span><span class="p">)</span>
<span class="k">return</span> <span class="n">subFlow</span><span class="p">(</span><span class="n">flow</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The flow will:</p>
<ol class="arabic simple">
<li>Construct a transaction with the old state as the input and the new state as the output</li>
<li>Obtain signatures from all <em>participants</em> (a participant is any party that is able to consume this state in a valid transaction, as defined by the state itself)</li>
<li>Obtain the <em>old</em> notary signature</li>
<li>Record and distribute the final transaction to the participants so that everyone possesses the new state</li>
</ol>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Eventually, changing notaries will be handled automatically on demand.</p>
</div>
</div>
</div>
<div class="section" id="validation">
<h2>Validation<a class="headerlink" href="#validation" title="Permalink to this headline"></a></h2>
<p>One of the design decisions for a notary is whether or not to <strong>validate</strong> a transaction before accepting it.</p>
<p>If a transaction is not checked for validity, it opens the platform to &#8220;denial of state&#8221; attacks, where anyone can build an invalid transaction consuming someone else&#8217;s states and submit it to the notary to get the states &#8220;blocked&#8221;.
However, if the transaction is validated, this requires the notary to be able to see the full contents of the transaction in question and its dependencies.
This is an obvious privacy leak.</p>
<p>The platform is flexible and currently supports both validating and non-validating notary implementations &#8211; a party can select which one to use based on its own privacy requirements.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In the non-validating model, the &#8220;denial of state&#8221; attack is partially alleviated by requiring the calling
party to authenticate and storing its identity for the request. The conflict information returned by the notary
specifies the consuming transaction ID along with the identity of the party that had created the transaction. If the
conflicting transaction is valid, the current one is aborted; if not, a dispute can be raised and the input states
of the conflicting invalid transaction are &#8220;un-committed&#8221; (via a legal process).</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">At present, all notaries can see the entire contents of a submitted transaction. A future piece of work
will enable the processing of <a class="reference internal" href="merkle-trees.html"><span class="doc">Transaction tear-offs</span></a>, thus providing data hiding of sensitive information.</p>
</div>
</div>
<div class="section" id="timestamping">
<h2>Timestamping<a class="headerlink" href="#timestamping" title="Permalink to this headline"></a></h2>
<p>A notary can also act as a <em>timestamping authority</em>, verifying the transaction timestamp command.</p>
<p>For a timestamp to be meaningful, its implications must be binding on the party requesting it.
A party can obtain a timestamp signature in order to prove that some event happened <em>before</em>, <em>on</em>, or <em>after</em> a particular point in time.
However, if the party is not also compelled to commit to the associated transaction, it has a choice of whether or not to reveal this fact until some point in the future.
As a result, we need to ensure that the notary either has to also sign the transaction within some time tolerance,
or perform timestamping <em>and</em> notarisation at the same time, which is the chosen behaviour for this model.</p>
<p>There will never be exact clock synchronisation between the party creating the transaction and the notary.
This is not only due to physics, network latencies, etc. but also because between inserting the command and getting the
notary to sign there may be many other steps, like sending the transaction to other parties involved in the trade, or
even requesting human sign-off. Thus the time observed by the notary may be quite different to the time observed by the
party creating the transaction.</p>
<p>For this reason, times in transactions are specified as time <em>windows</em>, not absolute times.
In a distributed system there can never be &#8220;true time&#8221;, only an approximation of it. Time windows can be
open-ended (i.e. specify only one of &#8220;before&#8221; and &#8220;after&#8221;) or they can be fully bounded. If a time window needs to
be converted to an absolute time (e.g. for display purposes), there is a utility method on <code class="docutils literal"><span class="pre">Timestamp</span></code> to
calculate the mid point.</p>
<p>In this way, we express the idea that the <em>true value</em> of the fact &#8220;the current time&#8221; is actually unknowable. Even when both before and
after times are included, the transaction could have occurred at any point between those two timestamps. Here,
&#8220;occurrence&#8221; could mean the execution date, the value date, the trade date etc ... The notary doesn&#8217;t care what precise
meaning the timestamp has to the contract.</p>
<p>By creating a range that can be either closed or open at one end, we allow all of the following facts to be modelled:</p>
<ul class="simple">
<li>This transaction occurred at some point after the given time (e.g. after a maturity event)</li>
<li>This transaction occurred at any time before the given time (e.g. before a bankruptcy event)</li>
<li>This transaction occurred at some point roughly around the given time (e.g. on a specific day)</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is assumed that the time feed for a notary is 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>Also see section 7 of the <a class="reference external" href="_static/corda-technical-whitepaper.pdf">Technical white paper</a> which covers this topic in significantly more depth.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="key-concepts-vault.html" class="btn btn-neutral float-right" title="Vault" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="key-concepts-flow-framework.html" class="btn btn-neutral" title="Flow framework" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2016, R3 Limited.
</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>