<p>The fundamental unit of consensus in Corda is the <strong>state</strong>. The concept of consensus can be divided into two parts:</p>
<olclass="arabic simple">
<li>Consensus over state <strong>validity</strong>– parties can reach certainty that a transaction defining output states is accepted by the contracts pointed to by the states and has all the required signatures. This is achieved by parties independently running the same contract code and validation logic (as described in <aclass="reference internal"href="data-model.html"><spanclass="doc">data model</span></a>)</li>
<li>Consensus over state <strong>uniqueness</strong>– 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 – a state has not been used as an input by more than one transaction)</li>
<p>This article presents an initial model for addressing the <strong>uniqueness</strong> problem.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="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>
<divclass="section"id="notary">
<h2>Notary<aclass="headerlink"href="#notary"title="Permalink to this headline">¶</a></h2>
<p>We introduce the concept of a <strong>Notary</strong>, which is an authority responsible for attesting that for a given transaction, it had not signed another transaction consuming any of its input states.
<p>All transactions have to be signed by their input state notary for the output states to be <strong>valid</strong> (apart from <em>issue</em> transactions, containing no input states).</p>
<pclass="last">The notary is a logical concept and can itself be a distributed entity, potentially a cluster maintained by mutually distrusting parties</p>
<p>When the notary is requested to sign a transaction, it either signs over it, attesting that the outputs are the <strong>unique</strong> successors of the inputs,
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>
<li><strong>Custom behaviour</strong>. We can have both validating and privacy preserving Notaries – 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>
<h2>Validation<aclass="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 committing its input states.</p>
<p>If a transaction is not checked for validity, it opens the platform to “denial of state” attacks, where anyone can build an invalid transaction consuming someone else’s states and submit it to the notary to get the states “blocked”.
However, validation of a transaction 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>Our platform is flexible and we currently support both validating and non-validating notary implementations – a party can select which one to use based on its own privacy requirements.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">In the non-validating model the “denial of state” attack is partially alleviated by requiring the calling party to authenticate and storing its identity for the request.</p>
</div>
<dlclass="docutils">
<dt>The conflict information returned by the Notary specifies the consuming transaction id along with the identity of the party that had requested the commit.</dt>
<dd>If the conflicting transaction is valid, the current one gets aborted; if not – a dispute can be raised and the input states of the conflicting invalid transaction are “un-committed” (to be covered by legal process).</dd>
</dl>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">At present all notaries can see the entire contents of a transaction, but we have a separate piece of work to replace the parts of the transaction it does not require knowing about with hashes (only input references, timestamp information, overall transaction ID and the necessary digests of the rest of the transaction to prove that the referenced inputs/timestamps really do form part of the stated transaction ID should be visible).</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 before/on/or after 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.
<h2>Running a Notary Service<aclass="headerlink"href="#running-a-notary-service"title="Permalink to this headline">¶</a></h2>
<p>At present we have two basic implementations that store committed input states in memory:</p>
<ulclass="simple">
<li><codeclass="docutils literal"><spanclass="pre">SimpleNotaryService</span></code>– commits the provided transaction without any validation</li>
<li><codeclass="docutils literal"><spanclass="pre">ValidatingNotaryService</span></code>– retrieves and validates the whole transaction history (including the given transaction) before committing</li>
</ul>
<p>To run one of these services the node has to simply specify either <codeclass="docutils literal"><spanclass="pre">SimpleNotaryService.Type</span></code> or <codeclass="docutils literal"><spanclass="pre">ValidatingNotaryService.Type</span></code> in its <codeclass="docutils literal"><spanclass="pre">advertisedServices</span></code> set, and the correct type will be initialised.</p>
</div>
<divclass="section"id="obtaining-a-signature">
<h2>Obtaining a signature<aclass="headerlink"href="#obtaining-a-signature"title="Permalink to this headline">¶</a></h2>
<p>To obtain a signature from a notary use <codeclass="docutils literal"><spanclass="pre">NotaryProtocol.Client</span></code>, passing in a <codeclass="docutils literal"><spanclass="pre">WireTransaction</span></code>.
The protocol will work out which notary needs to be called based on the input states and the timestamp command.
For example, the following snippet can be used when writing a custom protocol:</p>
<p>On conflict the <codeclass="docutils literal"><spanclass="pre">NotaryProtocol</span></code> with throw a <codeclass="docutils literal"><spanclass="pre">NotaryException</span></code> containing the conflict details:</p>
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span><spanclass="cm">/** Specifies the consuming transaction for the conflicting input state */</span>
<h2>Changing notaries<aclass="headerlink"href="#changing-notaries"title="Permalink to this headline">¶</a></h2>
<p>To change the notary for an input state, use the <codeclass="docutils literal"><spanclass="pre">NotaryChangeProtocol</span></code>. For example:</p>
<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>
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>.
