mirror of
https://github.com/corda/corda.git
synced 2024-12-29 17:28:56 +00:00
334 lines
16 KiB
HTML
334 lines
16 KiB
HTML
|
|
|
|
<!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>Data model — R3 Prototyping latest documentation</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="top" title="R3 Prototyping latest documentation" href="index.html"/>
|
|
<link rel="next" title="Networking and messaging" href="messaging.html"/>
|
|
<link rel="prev" title="Getting set up" href="getting-set-up.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 Prototyping
|
|
|
|
|
|
|
|
</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 class="current">
|
|
<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 current"><a class="current reference internal" href="#">Data model</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#description">Description</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#comparison-with-bitcoin">Comparison with Bitcoin</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#comparison-with-ethereum">Comparison with Ethereum</a></li>
|
|
</ul>
|
|
</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="running-the-demos.html">Running the demos</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="irs.html">The Interest Rate Swap Contract</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Writing a contract</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="protocol-state-machines.html">Protocol state machines</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Appendix</span></p>
|
|
<ul>
|
|
<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>
|
|
</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 Prototyping</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> »</li>
|
|
|
|
<li>Data model</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
<a href="_sources/data-model.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="data-model">
|
|
<h1>Data model<a class="headerlink" href="#data-model" title="Permalink to this headline">¶</a></h1>
|
|
<div class="section" id="description">
|
|
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
|
|
<p>This article covers the data model: how <em>states</em>, <em>transactions</em> and <em>code contracts</em> interact with each other and
|
|
how they are represented in the code. It doesn’t attempt to give detailed design rationales or information on future
|
|
design elements: please refer to the R3 wiki for background information.</p>
|
|
<p>We begin with the idea of a global ledger. In our model, although the ledger is shared, it is not always the case that
|
|
transactions and ledger entries are globally visible. In cases where a set of transactions stays within a small subgroup of
|
|
users it should be possible to keep the relevant data purely within that group.</p>
|
|
<p>To ensure consistency in a global, shared system where not all data may be visible to all participants, we rely
|
|
heavily on secure hashes like SHA-256 to identify things. The ledger is defined as a set of immutable <strong>states</strong>, which
|
|
are created and destroyed by digitally signed <strong>transactions</strong>. Each transaction points to a set of states that it will
|
|
consume/destroy, these are called <strong>inputs</strong>, and contains a set of new states that it will create, these are called
|
|
<strong>outputs</strong>.</p>
|
|
<p>States contain arbitrary data, but they always contain at minimum a hash of the bytecode of a
|
|
<strong>code contract</strong>, which is a program expressed in some byte code that runs sandboxed inside a virtual machine. Code
|
|
contracts (or just “contracts” in the rest of this document) are globally shared pieces of business logic. Contracts
|
|
define a <strong>verify function</strong>, which is a pure function given the entire transaction as input.</p>
|
|
<p>To be considered valid, the transaction must be <strong>accepted</strong> by the verify function of every contract pointed to by the
|
|
input and output states. Beyond inputs and outputs, transactions may also contain <strong>commands</strong>, small data packets that
|
|
the platform does not interpret itself, but which can parameterise execution of the contracts. They can be thought of as
|
|
arguments to the verify function. Each command has a list of <strong>public keys</strong> associated with it. The platform ensures
|
|
that the transaction is signed by every key listed in the commands before the contracts start to execute. Public keys
|
|
may be random/identityless for privacy, or linked to a well known legal identity via a <em>public key infrastructure</em> (PKI).</p>
|
|
<p>Commands are always embedded inside a transaction. Sometimes, there’s a larger piece of data that can be reused across
|
|
many different transactions. For this use case, we have <strong>attachments</strong>. Every transaction can refer to zero or more
|
|
attachments by hash. Attachments are always ZIP/JAR files, which may contain arbitrary content. Contract code can then
|
|
access the attachments by opening them as a JarInputStream (this is temporary and will change later).</p>
|
|
<p>Note that there is nothing that explicitly binds together specific inputs, outputs, commands or attachments. Instead
|
|
it’s up to the contract code to interpret the pieces inside the transaction and ensure they fit together correctly. This
|
|
is done to maximise flexibility for the contract developer.</p>
|
|
<p>Transactions may sometimes need to provide a contract with data from the outside world. Examples may include stock
|
|
prices, facts about events or the statuses of legal entities (e.g. bankruptcy), and so on. The providers of such
|
|
facts are called <strong>oracles</strong> and they provide facts to the ledger by signing transactions that contain commands they
|
|
recognise, or by creating signed attachments. The commands contain the fact and the signature shows agreement to that fact.
|
|
Time is also modelled as a fact, with the signature of a special kind of oracle called a <strong>timestamping authority</strong> (TSA).
|
|
A TSA signs a transaction if a pre-defined timestamping command in it defines a after/before time window that includes
|
|
“true time” (i.e. GPS time as calibrated to the US Naval Observatory). An oracle may prefer to generate a signed
|
|
attachment if the fact it’s creating is relatively static and may be referred to over and over again.</p>
|
|
<p>As the same terminology often crops up in different distributed ledger designs, let’s compare this to other
|
|
distributed ledger systems you may be familiar with. You can find more detailed design rationales for why the platform
|
|
differs from existing systems in <a class="reference external" href="https://r3-cev.atlassian.net/wiki/">the R3 wiki</a>, but to summarise, the driving
|
|
factors are:</p>
|
|
<ul class="simple">
|
|
<li>Improved contract flexibility vs Bitcoin</li>
|
|
<li>Improved scalability vs Ethereum, as well as ability to keep parts of the transaction graph private (yet still uniquely addressable)</li>
|
|
<li>No reliance on proof of work</li>
|
|
<li>Re-use of existing sandboxing virtual machines</li>
|
|
<li>Use of type safe GCd implementation languages.</li>
|
|
<li>Simplified auditing</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="comparison-with-bitcoin">
|
|
<h2>Comparison with Bitcoin<a class="headerlink" href="#comparison-with-bitcoin" title="Permalink to this headline">¶</a></h2>
|
|
<p>Similarities:</p>
|
|
<ul class="simple">
|
|
<li>The basic notion of immutable states that are consumed and created by transactions is the same.</li>
|
|
<li>The notion of transactions having multiple inputs and outputs is the same. Bitcoin sometimes refers to the ledger
|
|
as the unspent transaction output set (UTXO set) as a result.</li>
|
|
<li>Like in Bitcoin, a contract is pure function. Contracts do not have storage or the ability to interact with anything.
|
|
Given the same transaction, a contract’s accept function always yields exactly the same result.</li>
|
|
<li>Bitcoin output scripts are parameterised by the input scripts in the spending transaction. This is somewhat similar
|
|
to our notion of a <em>command</em>.</li>
|
|
<li>Bitcoin transactions, like ours, refer to the states they consume by using a (txhash, index) pair. The Bitcoin
|
|
protocol calls these “outpoints”. In our prototype code they are known as <code class="docutils literal"><span class="pre">StateRefs</span></code> but the concept is identical.</li>
|
|
<li>Bitcoin transactions have an associated timestamp (the time at which they are mined).</li>
|
|
</ul>
|
|
<p>Differences:</p>
|
|
<ul class="simple">
|
|
<li>A Bitcoin transaction has a single, rigid data format. A “state” in Bitcoin is always a (quantity of bitcoin, script)
|
|
pair and cannot hold any other data. Some people have been known to try and hack around this limitation by embedding
|
|
data in semi-standardised places in the contract code so the data can be extracted through pattern matching, but this
|
|
is a poor approach. Our states can include arbitrary typed data.</li>
|
|
<li>A Bitcoin transaction’s acceptance is controlled only by the contract code in the consumed input states. In practice
|
|
this has proved limiting. Our transactions invoke not only input contracts but also the contracts of the outputs.</li>
|
|
<li>A Bitcoin script can only be given a fixed set of byte arrays as the input. This means there’s no way for a contract
|
|
to examine the structure of the entire transaction, which severely limits what contracts can do.</li>
|
|
<li>Our contracts are Turing-complete and can be written in any ordinary programming language that targets the JVM.</li>
|
|
<li>Our transactions and contracts have to get their time from an attached timestamp rather than a block chain. This is
|
|
important given that we are currently considering block-free conflict resolution algorithms.</li>
|
|
<li>We use the term “contract” to refer to a bundle of business logic that may handle various different tasks, beyond
|
|
transaction verification. For instance, currently our contracts also include code for creating valid transactions
|
|
(this is often called “wallet code” in Bitcoin).</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="comparison-with-ethereum">
|
|
<h2>Comparison with Ethereum<a class="headerlink" href="#comparison-with-ethereum" title="Permalink to this headline">¶</a></h2>
|
|
<p>Similarities:</p>
|
|
<ul class="simple">
|
|
<li>Like Ethereum, code runs inside a relatively powerful virtual machine and can contain complex logic. Non-assembly
|
|
based programming languages can be used for contract programming.</li>
|
|
<li>They are both intended for the modelling of many different kinds of financial contract.</li>
|
|
</ul>
|
|
<p>Differences:</p>
|
|
<ul class="simple">
|
|
<li>The term “contract” in Ethereum refers to an <em>instantiation</em> of a program that is replicated and maintained by
|
|
every participating node. This instantiation is very much like an object in an OO program: it can receive and send
|
|
messages, update local storage and so on. In contrast, we use the term “contract” to refer to a set of functions, only
|
|
one of which is a part of keeping the system synchronised (the verify function). That function is pure and
|
|
stateless i.e. it may not interact with any other part of the system whilst executing.</li>
|
|
<li>There is no notion of an “account”, as there is in Ethereum.</li>
|
|
<li>As contracts don’t have any kind of mutable storage, there is no notion of a “message” as in Ethereum.</li>
|
|
<li>Ethereum claims to be a platform not only for financial logic, but literally any kind of application at all. Our
|
|
platform considers non-financial applications to be out of scope.</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="messaging.html" class="btn btn-neutral float-right" title="Networking and messaging" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="getting-set-up.html" class="btn btn-neutral" title="Getting set up" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
© Copyright 2015, R3 CEV.
|
|
|
|
</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> |