2015-11-25 13:29:51 +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-02-25 12:29:28 +00:00
< title > Data model — R3 Prototyping latest documentation< / title >
2015-11-25 13:29:51 +00:00
< link rel = "stylesheet" href = "_static/css/custom.css" type = "text/css" / >
2016-02-25 12:29:28 +00:00
< link rel = "top" title = "R3 Prototyping latest documentation" href = "index.html" / >
2015-12-22 15:15:38 +00:00
< link rel = "next" title = "Networking and messaging" href = "messaging.html" / >
< link rel = "prev" title = "Getting set up" href = "getting-set-up.html" / >
2015-11-25 13:29:51 +00:00
< 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-03-08 17:30:51 +00:00
2015-11-25 13:29:51 +00:00
2015-11-30 17:00:25 +00:00
< a href = "index.html" class = "icon icon-home" > R3 Prototyping
2015-11-25 13:29:51 +00:00
< / a >
< div class = "version" >
2016-02-25 12:29:28 +00:00
latest
2015-11-25 13:29:51 +00:00
< / 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 >
2016-03-08 17:30:51 +00:00
< br >
< a href = "api/index.html" > API reference< / a >
2015-11-25 13:29:51 +00:00
< / div >
< div class = "wy-menu wy-menu-vertical" data-spy = "affix" role = "navigation" aria-label = "main navigation" >
2015-12-22 15:15:38 +00:00
< p class = "caption" > < span class = "caption-text" > Overview< / span > < / p >
< ul class = "current" >
2015-11-25 13:29:51 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "inthebox.html" > What’ s included?< / a > < / li >
2015-12-22 15:15:38 +00:00
< 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 >
2015-11-25 13:29:51 +00:00
< / ul >
< / li >
2015-12-15 13:27:06 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "messaging.html" > Networking and messaging< / a > < / li >
2016-02-25 12:29:28 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "running-the-trading-demo.html" > Running the trading demo< / a > < / li >
2016-03-04 15:15:51 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "node-administration.html" > Node administration< / a > < / li >
2015-12-22 15:15:38 +00:00
< / 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 >
2015-12-15 13:27:06 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "protocol-state-machines.html" > Protocol state machines< / a > < / li >
2015-12-22 15:15:38 +00:00
< / ul >
< p class = "caption" > < span class = "caption-text" > Appendix< / span > < / p >
< ul >
2015-12-15 13:27:06 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "visualiser.html" > Using the visualiser< / a > < / li >
2015-11-25 13:29:51 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "roadmap.html" > Roadmap< / a > < / li >
2016-01-27 15:01:52 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "codestyle.html" > Code style guide< / a > < / li >
2015-11-25 13:29:51 +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 >
2015-11-30 17:00:25 +00:00
< a href = "index.html" > R3 Prototyping< / a >
2015-11-25 13:29:51 +00:00
< / 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 >
2015-12-22 15:15:38 +00:00
< li > Data model< / li >
2015-11-25 13:29:51 +00:00
< li class = "wy-breadcrumbs-aside" >
2015-12-22 15:15:38 +00:00
< a href = "_sources/data-model.txt" rel = "nofollow" > View page source< / a >
2015-11-25 13:29:51 +00:00
< / li >
< / ul >
< hr / >
< / div >
< div role = "main" class = "document" itemscope = "itemscope" itemtype = "http://schema.org/Article" >
< div itemprop = "articleBody" >
2015-12-22 15:15:38 +00:00
< 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 >
2015-11-25 13:29:51 +00:00
< 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 >
2015-12-22 15:15:38 +00:00
< p > States contain arbitrary data, but they always contain at minimum a hash of the bytecode of a
2015-11-25 13:29:51 +00:00
< 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
2015-11-25 17:49:58 +00:00
define a < strong > verify function< / strong > , which is a pure function given the entire transaction as input.< / p >
2015-11-25 13:29:51 +00:00
< 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
2015-12-22 15:15:38 +00:00
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 >
2016-03-04 15:15:51 +00:00
< 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 >
2015-12-22 15:15:38 +00:00
< 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
2016-03-04 15:15:51 +00:00
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 >
2015-11-25 13:29:51 +00:00
< p > As the same terminology often crops up in different distributed ledger designs, let’ s compare this to other
2015-11-25 17:49:58 +00:00
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-us of existing sandboxing virtual machines< / li >
< li > Use of type safe GCd implementation languages.< / li >
< li > Simplified auditing< / li >
< / ul >
2015-12-22 15:15:38 +00:00
< / div >
2015-11-25 13:29:51 +00:00
< div class = "section" id = "comparison-with-bitcoin" >
2015-12-22 15:15:38 +00:00
< h2 > Comparison with Bitcoin< a class = "headerlink" href = "#comparison-with-bitcoin" title = "Permalink to this headline" > ¶< / a > < / h2 >
2015-11-25 13:29:51 +00:00
< 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 >
2015-11-25 17:49:58 +00:00
< li > Our transactions and contracts have to get their time from an attached timestamp rather than a block chain. This is
2015-11-25 13:29:51 +00:00
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" >
2015-12-22 15:15:38 +00:00
< h2 > Comparison with Ethereum< a class = "headerlink" href = "#comparison-with-ethereum" title = "Permalink to this headline" > ¶< / a > < / h2 >
2015-11-25 13:29:51 +00:00
< 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
2015-11-25 17:49:58 +00:00
messages, update local storage and so on. In contrast, we use the term “ contract” to refer to a set of functions, only
2015-11-25 13:29:51 +00:00
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" >
2015-12-22 15:15:38 +00:00
< 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 >
2015-11-25 13:29:51 +00:00
2015-12-22 15:15:38 +00:00
< 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 >
2015-11-25 13:29:51 +00:00
< / 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:'./',
2016-02-25 12:29:28 +00:00
VERSION:'latest',
2015-11-25 13:29:51 +00:00
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 >
