corda/docs/build/html/merkle-trees.html

381 lines
22 KiB
HTML
Raw Normal View History

2017-01-03 13:07:48 +00:00
<!-- 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 -->
2016-11-11 11:52:29 +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-11-29 11:38:52 +00:00
<title>Transaction tear-offs &mdash; R3 Corda latest documentation</title>
2016-11-11 11:52:29 +00:00
<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="Consensus model" href="consensus.html"/>
<link rel="prev" title="Data types" href="transaction-data-types.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>
2017-01-03 13:07:48 +00:00
<br>
<a href="https://discourse.corda.net">Discourse Forums</a>
<br>
<a href="http://slack.corda.net">Slack</a>
<br>
2016-11-11 11:52:29 +00:00
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
2016-11-23 12:50:02 +00:00
<p class="caption"><span class="caption-text">Getting started</span></p>
<ul>
2016-11-11 11:52:29 +00:00
<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>
2017-01-06 17:38:23 +00:00
<li class="toctree-l1"><a class="reference internal" href="getting-set-up-fault-finding.html">Troubleshooting</a></li>
2016-11-23 12:50:02 +00:00
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
2016-11-29 18:44:59 +00:00
<li class="toctree-l1"><a class="reference internal" href="CLI-vs-IDE.html">CLI vs IDE</a></li>
2016-11-23 12:50:02 +00:00
</ul>
<p class="caption"><span class="caption-text">Key concepts</span></p>
<ul class="current">
2016-11-11 11:52:29 +00:00
<li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="transaction-data-types.html">Data types</a></li>
2016-11-29 11:38:52 +00:00
<li class="toctree-l1 current"><a class="current reference internal" href="#">Transaction tear-offs</a><ul>
2016-11-11 11:52:29 +00:00
<li class="toctree-l2"><a class="reference internal" href="#merkle-trees-in-corda">Merkle trees in Corda</a></li>
<li class="toctree-l2"><a class="reference internal" href="#hiding-data">Hiding data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#example-of-usage">Example of usage</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="consensus.html">Consensus model</a></li>
2017-01-06 17:38:23 +00:00
<li class="toctree-l1"><a class="reference internal" href="clauses.html">Clauses</a></li>
2016-11-29 18:44:59 +00:00
</ul>
<p class="caption"><span class="caption-text">CorDapps</span></p>
<ul>
2017-01-06 17:38:23 +00:00
<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 CorDapp template</a></li>
2016-11-23 12:50:02 +00:00
</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>
2016-11-11 11:52:29 +00:00
<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>
2016-11-29 11:38:52 +00:00
<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>
2016-11-23 12:50:02 +00:00
</ul>
2016-11-11 11:52:29 +00:00
<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>
2017-01-06 17:38:23 +00:00
<li class="toctree-l1"><a class="reference internal" href="tutorial-integration-testing.html">Integration testing</a></li>
2016-11-29 11:38:52 +00:00
<li class="toctree-l1"><a class="reference internal" href="tutorial-clientrpc-api.html">Client RPC API tutorial</a></li>
2017-01-06 17:38:23 +00:00
<li class="toctree-l1"><a class="reference internal" href="tutorial-building-transactions.html">Building transactions</a></li>
2016-11-25 12:10:21 +00:00
<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>
2016-11-29 11:38:52 +00:00
<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>
2016-11-11 11:52:29 +00:00
<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>
2016-11-23 12:50:02 +00:00
<p class="caption"><span class="caption-text">Other</span></p>
2016-11-11 11:52:29 +00:00
<ul>
2016-11-23 12:50:02 +00:00
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
2016-11-11 11:52:29 +00:00
</ul>
2016-11-23 12:50:02 +00:00
<p class="caption"><span class="caption-text">Component library</span></p>
2016-11-11 11:52:29 +00:00
<ul>
2016-11-23 12:50:02 +00:00
<li class="toctree-l1"><a class="reference internal" href="contract-catalogue.html">Contract catalogue</a></li>
2016-11-29 11:38:52 +00:00
<li class="toctree-l1"><a class="reference internal" href="contract-irs.html">Interest rate swaps</a></li>
2016-11-11 11:52:29 +00:00
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul>
2016-11-18 12:57:39 +00:00
<li class="toctree-l1"><a class="reference internal" href="loadtesting.html">Load testing</a></li>
2017-01-06 17:38:23 +00:00
<li class="toctree-l1"><a class="reference internal" href="setting-up-a-corda-network.html">What is a corda network?</a></li>
2016-11-11 11:52:29 +00:00
<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>
2017-01-03 13:07:48 +00:00
<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>
2016-11-11 11:52:29 +00:00
</ul>
2016-11-23 12:50:02 +00:00
<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>
2016-11-11 11:52:29 +00:00
</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>
2016-11-29 11:38:52 +00:00
<li>Transaction tear-offs</li>
2016-11-11 11:52:29 +00:00
<li class="wy-breadcrumbs-aside">
<a href="_sources/merkle-trees.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="transaction-tear-offs">
2016-11-29 11:38:52 +00:00
<h1>Transaction tear-offs<a class="headerlink" href="#transaction-tear-offs" title="Permalink to this headline"></a></h1>
2016-11-11 11:52:29 +00:00
<p>One of the basic data structures in our platform is a transaction. It can be passed around to be signed and verified,
also by third parties. The construction of transactions assumes that they form a whole entity with input and output states,
commands and attachments inside. However all sensitive data shouldnt be revealed to other nodes that take part in
the creation of transaction on validation level (a good example of this situation is the Oracle which validates only
2017-01-06 17:38:23 +00:00
embedded commands). How to achieve it in a way that convinces the other party the data they got for signing really did form
2016-11-11 11:52:29 +00:00
a part of the transaction?</p>
<p>We decided to use well known and described cryptographic scheme to provide proofs of inclusion and data integrity.
Merkle trees are widely used in peer-to-peer networks, blockchain systems and git.
You can read more on the concept <a class="reference external" href="https://en.wikipedia.org/wiki/Merkle_tree">here</a>.</p>
<div class="section" id="merkle-trees-in-corda">
<h2>Merkle trees in Corda<a class="headerlink" href="#merkle-trees-in-corda" title="Permalink to this headline"></a></h2>
<p>Transactions are split into leaves, each of them contains either input, output, command or attachment. Other fields like
timestamp or signers are not used in the calculation.
Next, the Merkle tree is built in the normal way by hashing the concatenation
of nodes hashes below the current one together. Its visible on the example image below, where <code class="docutils literal"><span class="pre">H</span></code> denotes sha256 function,
&#8220;+&#8221; - concatenation.</p>
<img alt="_images/merkleTree.png" src="_images/merkleTree.png" />
<p>The transaction has one input state, one output and three commands. If a tree is not a full binary tree, the rightmost nodes are
duplicated in hash calculation (dotted lines).</p>
<p>Finally, the hash of the root is the identifier of the transaction, it&#8217;s also used for signing and verification of data integrity.
Every change in transaction on a leaf level will change its identifier.</p>
</div>
<div class="section" id="hiding-data">
<h2>Hiding data<a class="headerlink" href="#hiding-data" title="Permalink to this headline"></a></h2>
<p>Hiding data and providing the proof that it formed a part of a transaction is done by constructing Partial Merkle Trees
(or Merkle branches). A Merkle branch is a set of hashes, that given the leaves data, is used to calculate the roots hash.
Then that hash is compared with the hash of a whole transaction and if they match it means that data we obtained belongs
to that particular transaction.</p>
<img alt="_images/partialMerkle.png" src="_images/partialMerkle.png" />
<p>In the example above, the red node is the one holding data for signing Oracle service. Blue nodes&#8217; hashes form the Partial Merkle
Tree, dotted ones are not included. Having the command that should be in a red node place and branch we are able to calculate
root of this tree and compare it with original transaction identifier - we have a proof that this command belongs to this transaction.</p>
</div>
<div class="section" id="example-of-usage">
<h2>Example of usage<a class="headerlink" href="#example-of-usage" title="Permalink to this headline"></a></h2>
<p>Lets focus on a code example. We want to construct a transaction with commands containing interest rate fix data as in:
<a class="reference internal" href="oracles.html"><span class="doc">Writing oracle services</span></a>.
After construction of a partial transaction, with included <code class="docutils literal"><span class="pre">Fix</span></code> commands in it, we want to send it to the Oracle for checking
and signing. To do so we need to specify which parts of the transaction are going to be revealed. That can be done by constructing
filtering functions for inputs, outputs, attachments and commands separately. If a function is not provided by default none
of the elements from this group will be included in a Partial Merkle Tree.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">val</span> <span class="py">partialTx</span> <span class="p">=</span> <span class="p">...</span>
<span class="k">val</span> <span class="py">oracle</span><span class="p">:</span> <span class="n">Party</span> <span class="p">=</span> <span class="p">...</span>
<span class="k">fun</span> <span class="nf">filterCommands</span><span class="p">(</span><span class="n">c</span><span class="p">:</span> <span class="n">Command</span><span class="p">)</span> <span class="p">=</span> <span class="n">oracle</span><span class="p">.</span><span class="n">owningKey</span> <span class="k">in</span> <span class="n">c</span><span class="p">.</span><span class="n">signers</span> <span class="p">&amp;&amp;</span> <span class="n">c</span><span class="p">.</span><span class="n">value</span> <span class="k">is</span> <span class="n">Fix</span>
<span class="k">val</span> <span class="py">filterFuns</span> <span class="p">=</span> <span class="n">FilterFuns</span><span class="p">(</span><span class="n">filterCommands</span> <span class="p">=</span> <span class="o">::</span><span class="n">filterCommands</span><span class="p">)</span>
</pre></div>
</div>
</div>
<p>Assuming that we already assembled partialTx with some commands and know the identity of Oracle service,
we pass filtering function over commands - <code class="docutils literal"><span class="pre">filterCommands</span></code> to <code class="docutils literal"><span class="pre">FilterFuns</span></code>. It filters only
commands of type <code class="docutils literal"><span class="pre">Fix</span></code> as in IRSDemo example. Then we can construct <code class="docutils literal"><span class="pre">FilteredTransaction</span></code>:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">val</span> <span class="py">wtx</span><span class="p">:</span> <span class="n">WireTransaction</span> <span class="p">=</span> <span class="n">partialTx</span><span class="p">.</span><span class="n">toWireTransaction</span><span class="p">()</span>
<span class="k">val</span> <span class="py">ftx</span> <span class="p">=</span> <span class="n">FilteredTransaction</span><span class="p">.</span><span class="n">buildMerkleTransaction</span><span class="p">(</span><span class="n">wtx</span><span class="p">,</span> <span class="n">filterFuns</span><span class="p">)</span>
</pre></div>
</div>
</div>
2016-11-23 12:50:02 +00:00
<p>In the Oracle example this step takes place in <code class="docutils literal"><span class="pre">RatesFixFlow</span></code>:</p>
2016-11-11 11:52:29 +00:00
<div class="codeset container">
2016-11-23 12:50:02 +00:00
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">val</span> <span class="py">flow</span> <span class="p">=</span> <span class="n">RatesFixFlow</span><span class="p">(</span><span class="n">partialTx</span><span class="p">,</span> <span class="n">filterFuns</span><span class="p">,</span> <span class="n">oracle</span><span class="p">,</span> <span class="n">fixOf</span><span class="p">,</span> <span class="s">&quot;0.675&quot;</span><span class="p">.</span><span class="n">bd</span><span class="p">,</span> <span class="s">&quot;0.1&quot;</span><span class="p">.</span><span class="n">bd</span><span class="p">)</span>
2016-11-11 11:52:29 +00:00
</pre></div>
</div>
</div>
<p><code class="docutils literal"><span class="pre">FilteredTransaction</span></code> holds <code class="docutils literal"><span class="pre">filteredLeaves</span></code> (data that we wanted to reveal) and Merkle branch for them.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="c1">// Getting included commands, inputs, outputs, attachments.</span>
<span class="k">val</span> <span class="py">cmds</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">Command</span><span class="p">&gt;</span> <span class="p">=</span> <span class="n">ftx</span><span class="p">.</span><span class="n">filteredLeaves</span><span class="p">.</span><span class="n">commands</span>
<span class="k">val</span> <span class="py">ins</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">StateRef</span><span class="p">&gt;</span> <span class="p">=</span> <span class="n">ftx</span><span class="p">.</span><span class="n">filteredLeaves</span><span class="p">.</span><span class="n">inputs</span>
<span class="k">val</span> <span class="py">outs</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">TransactionState</span><span class="p">&lt;</span><span class="n">ContractState</span><span class="p">&gt;&gt;</span> <span class="p">=</span> <span class="n">ftx</span><span class="p">.</span><span class="n">filteredLeaves</span><span class="p">.</span><span class="n">outputs</span>
<span class="k">val</span> <span class="py">attchs</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">SecureHash</span><span class="p">&gt;</span> <span class="p">=</span> <span class="n">ftx</span><span class="p">.</span><span class="n">filteredLeaves</span><span class="p">.</span><span class="n">attachments</span>
</pre></div>
</div>
</div>
<p>If you want to verify obtained <code class="docutils literal"><span class="pre">FilteredTransaction</span></code> all you need is the root hash of the full transaction:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(!</span><span class="n">ftx</span><span class="p">.</span><span class="n">verify</span><span class="p">(</span><span class="n">merkleRoot</span><span class="p">)){</span>
<span class="k">throw</span> <span class="n">MerkleTreeException</span><span class="p">(</span><span class="s">&quot;Rate Fix Oracle: Couldn&#39;t verify partial Merkle tree.&quot;</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The way the <code class="docutils literal"><span class="pre">FilteredTransaction</span></code> is constructed ensures that after signing of the root hash it&#8217;s impossible to add or remove
leaves. However, it can happen that having transaction with multiple commands one party reveals only subset of them to the Oracle.
2017-01-06 17:38:23 +00:00
As signing is done now over the Merkle root hash, the service signs all commands of given type, even though it didn&#8217;t see
2016-11-11 11:52:29 +00:00
all of them. This issue will be handled after implementing partial signatures.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="consensus.html" class="btn btn-neutral float-right" title="Consensus model" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="transaction-data-types.html" class="btn btn-neutral" title="Data types" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
2016-11-29 18:44:59 +00:00
&copy; Copyright 2016, R3 Limited.
2016-11-11 11:52:29 +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>