ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-20 05:28:21 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Docs: regen HTML + reorganise left hand menu a bit.

Browse Source
This commit is contained in:
Mike Hearn 2015-12-22 15:15:38 +00:00
parent c217702606
commit 89b1a5648b
22 changed files with 384 additions and 283 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/source/overview.rst → docs/build/html/_sources/data-model.txt vendored
View File

@ -1,13 +1,13 @@
Overview
========
Data model
==========
Description
-----------
This article covers the data model: how *states*, *transactions* and *code contracts* 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.
Data model
----------
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.
@ -55,7 +55,7 @@ factors are:
* Simplified auditing
Comparison with Bitcoin
^^^^^^^^^^^^^^^^^^^^^^^
-----------------------
Similarities:
@ -88,7 +88,7 @@ Differences:
(this is often called "wallet code" in Bitcoin).
Comparison with Ethereum
^^^^^^^^^^^^^^^^^^^^^^^^
------------------------
Similarities:
@ -108,49 +108,3 @@ Differences:
* 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.
Contracts
---------
The primary goal of this prototype is to implement various kinds of contracts and verify that useful business logic
can be expressed with the data model, developing and refining an API along the way. To that end there are currently
two contracts in the repository:
1. Cash
2. Commercial paper
``Cash`` implements the idea of a claim on some quantity of deposits at some institutional party, denominated in some currency,
identified by some *deposit reference*. A deposit reference is an opaque byte array which is usable by
the issuing party for internal bookkeeping purposes.
Cash states are *fungible* with each other (can be merged and split arbitrarily) if they use the same currency,
party and deposit reference.
``CommercialPaper`` implements an asset with a *face value* denominated in a certain currency, which may be redeemed at
the issuing party after a certain time. Commercial paper states define the face value (e.g. $1000) and the time
at which they may be redeemed. The contract allows the paper to be issued, traded and redeemed. The commercial paper
contract is implemented twice, once in Java and once in a language called Kotlin.
Each contract comes with unit tests.
Kotlin
------
The prototype is written in a language called `Kotlin <https://kotlinlang.org/>`_. Kotlin is a language that targets the JVM
and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support
from JetBrains, the makers of the IntelliJ IDE and other popular developer tools.
As Kotlin is very new, without a doubt you have not encountered it before. Don't worry: it is designed as a better
Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don't know
the language, after only a few minutes of introduction.
Due to the seamless Java interop the use of Kotlin to extend the platform is *not* required and the tutorial shows how
to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here <https://medium.com/@octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3>`_.
Kotlin programs use the regular Java standard library and ordinary Java frameworks. Frameworks used at this time are:
* JUnit for unit testing
* Kryo for serialisation (this is not intended to be permanent)
* Gradle for the build
* Guava for a few utility functions

4
docs/build/html/_sources/getting-set-up.txt vendored
View File

@ -7,12 +7,12 @@ Then install IntelliJ version 15 community edition:
https://www.jetbrains.com/idea/download/
Upgrade the Kotlin plugin to the latest version (1.0-beta-2423) by clicking "Configure > Plugins" in the opening screen,
Upgrade the Kotlin plugin to the latest version (1.0-beta-3595) by clicking "Configure > Plugins" in the opening screen,
then clicking "Install JetBrains plugin", then searching for Kotlin, then hitting "Upgrade" and then "Restart".
Choose "Check out from version control" and use this git URL
https://your_username@bitbucket.org/R3-CEV/playground.git
https://your_username@bitbucket.org/R3-CEV/r3repository.git
Agree to the defaults for importing a Gradle project. Wait for it to think and download the dependencies.

15
docs/build/html/_sources/index.txt vendored
View File

@ -21,13 +21,24 @@ Read on to learn:
.. toctree::
:maxdepth: 2
:caption: Overview
inthebox
overview
getting-set-up
tutorial
data-model
messaging
.. toctree::
:maxdepth: 2
:caption: Tutorials
tutorial
protocol-state-machines
.. toctree::
:maxdepth: 2
:caption: Appendix
visualiser
roadmap

47
docs/build/html/_sources/inthebox.txt vendored
View File

@ -25,4 +25,49 @@ The prototype's goal is rapid exploration of ideas. Therefore in places it takes
would not in order to boost productivity:
* It uses a serialization framework instead of a well specified, vendor neutral protocol.
* It uses secp256r1, an obsolete elliptic curve.
* It uses secp256r1, an obsolete elliptic curve.
Contracts
---------
The primary goal of this prototype is to implement various kinds of contracts and verify that useful business logic
can be expressed with the data model, developing and refining an API along the way. To that end there are currently
two contracts in the repository:
1. Cash
2. Commercial paper
``Cash`` implements the idea of a claim on some quantity of deposits at some institutional party, denominated in some currency,
identified by some *deposit reference*. A deposit reference is an opaque byte array which is usable by
the issuing party for internal bookkeeping purposes.
Cash states are *fungible* with each other (can be merged and split arbitrarily) if they use the same currency,
party and deposit reference.
``CommercialPaper`` implements an asset with a *face value* denominated in a certain currency, which may be redeemed at
the issuing party after a certain time. Commercial paper states define the face value (e.g. $1000) and the time
at which they may be redeemed. The contract allows the paper to be issued, traded and redeemed. The commercial paper
contract is implemented twice, once in Java and once in a language called Kotlin.
Each contract comes with unit tests.
Kotlin
------
The prototype is written in a language called `Kotlin <https://kotlinlang.org/>`_. Kotlin is a language that targets the JVM
and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support
from JetBrains, the makers of the IntelliJ IDE and other popular developer tools.
As Kotlin is very new, without a doubt you have not encountered it before. Don't worry: it is designed as a better
Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don't know
the language, after only a few minutes of introduction.
Due to the seamless Java interop the use of Kotlin to extend the platform is *not* required and the tutorial shows how
to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here <https://medium.com/@octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3>`_.
Kotlin programs use the regular Java standard library and ordinary Java frameworks. Frameworks used at this time are:
* JUnit for unit testing
* Kryo for serialisation (this is not intended to be permanent)
* Gradle for the build
* Guava for a few utility functions

4
docs/build/html/_sources/tutorial.txt vendored
View File

@ -4,8 +4,8 @@
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Tutorial
========
Writing a contract
==================
This tutorial will take you through how the commercial paper contract works.

121
docs/build/html/overview.html → docs/build/html/data-model.html vendored
View File

@ -8,7 +8,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Overview &mdash; R3 Prototyping 0.1 documentation</title>
<title>Data model &mdash; R3 Prototyping 0.1 documentation</title>
@ -31,8 +31,8 @@
<link rel="top" title="R3 Prototyping 0.1 documentation" href="index.html"/>
<link rel="next" title="Getting set up" href="getting-set-up.html"/>
<link rel="prev" title="What’s included?" href="inthebox.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>
@ -81,22 +81,25 @@
<ul class="current">
<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&#8217;s included?</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Overview</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#data-model">Data model</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#comparison-with-bitcoin">Comparison with Bitcoin</a></li>
<li class="toctree-l3"><a class="reference internal" href="#comparison-with-ethereum">Comparison with Ethereum</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#contracts">Contracts</a></li>
<li class="toctree-l2"><a class="reference internal" href="#kotlin">Kotlin</a></li>
</ul>
</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="tutorial.html">Tutorial</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>
</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>
</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="roadmap.html">Roadmap</a></li>
</ul>
@ -129,11 +132,11 @@
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Overview</li>
<li>Data model</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/overview.txt" rel="nofollow"> View page source</a>
<a href="_sources/data-model.txt" rel="nofollow"> View page source</a>
</li>
@ -143,13 +146,13 @@
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="overview">
<h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline"></a></h1>
<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&#8217;t attempt to give detailed design rationales or information on future
design elements: please refer to the R3 wiki for background information.</p>
<div class="section" id="data-model">
<h2>Data model<a class="headerlink" href="#data-model" title="Permalink to this headline"></a></h2>
<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>
@ -158,32 +161,26 @@ heavily on secure hashes like SHA-256 to identify things. The ledger is defined
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 pointer to the bytecode of a
<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 &#8220;contracts&#8221; 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.</p>
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>Note that there is nothing that explicitly binds together specific inputs, outputs or commands. Instead it&#8217;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>A transaction has one or more <strong>signatures</strong> attached to it. The signatures do not mean anything by themselves, rather,
their existence is given as input to the contract which can then decide which set of signatures it demands (if any).
Signatures may be from an arbitrary, random <strong>public key</strong> that has no identity attached. A public key may be
well known, that is, appears in some sort of public identity registry. In this case we say the key is owned by a
<strong>party</strong>, which is defined (for now) as being merely a (public key, name) pair.</p>
<p>A transaction may also be <strong>timestamped</strong>. A timestamp is a (hash, datetime, signature) triple from a
<em>timestamping authority</em> (TSA). The notion of a TSA is not ledger specific and is defined by
<a class="reference external" href="https://www.ietf.org/rfc/rfc3161.txt">IETF RFC 3161</a> which defines the internet standard Timestamping Protocol (TSP).
The purpose of the TSA is to attach a single, globally agreed upon time which a contract may use to enforce certain
types of time-based logic. The TSA&#8217;s do not need to know about the contents of the transaction in order to provide a
timestamp, and they are therefore never exposed to private data.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In the current code, use of TSAs is not implemented.</p>
</div>
<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. 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 &#8220;true
time&#8221; (i.e. GPS time as calibrated to the US Naval Observatory).</p>
<p>As the same terminology often crops up in different distributed ledger designs, let&#8217;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
@ -196,8 +193,9 @@ factors are:</p>
<li>Use of type safe GCd implementation languages.</li>
<li>Simplified auditing</li>
</ul>
</div>
<div class="section" id="comparison-with-bitcoin">
<h3>Comparison with Bitcoin<a class="headerlink" href="#comparison-with-bitcoin" title="Permalink to this headline"></a></h3>
<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>
@ -230,7 +228,7 @@ transaction verification. For instance, currently our contracts also include cod
</ul>
</div>
<div class="section" id="comparison-with-ethereum">
<h3>Comparison with Ethereum<a class="headerlink" href="#comparison-with-ethereum" title="Permalink to this headline"></a></h3>
<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
@ -250,45 +248,6 @@ stateless i.e. it may not interact with any other part of the system whilst exec
platform considers non-financial applications to be out of scope.</li>
</ul>
</div>
</div>
<div class="section" id="contracts">
<h2>Contracts<a class="headerlink" href="#contracts" title="Permalink to this headline"></a></h2>
<p>The primary goal of this prototype is to implement various kinds of contracts and verify that useful business logic
can be expressed with the data model, developing and refining an API along the way. To that end there are currently
two contracts in the repository:</p>
<ol class="arabic simple">
<li>Cash</li>
<li>Commercial paper</li>
</ol>
<p><code class="docutils literal"><span class="pre">Cash</span></code> implements the idea of a claim on some quantity of deposits at some institutional party, denominated in some currency,
identified by some <em>deposit reference</em>. A deposit reference is an opaque byte array which is usable by
the issuing party for internal bookkeeping purposes.</p>
<p>Cash states are <em>fungible</em> with each other (can be merged and split arbitrarily) if they use the same currency,
party and deposit reference.</p>
<p><code class="docutils literal"><span class="pre">CommercialPaper</span></code> implements an asset with a <em>face value</em> denominated in a certain currency, which may be redeemed at
the issuing party after a certain time. Commercial paper states define the face value (e.g. $1000) and the time
at which they may be redeemed. The contract allows the paper to be issued, traded and redeemed. The commercial paper
contract is implemented twice, once in Java and once in a language called Kotlin.</p>
<p>Each contract comes with unit tests.</p>
</div>
<div class="section" id="kotlin">
<h2>Kotlin<a class="headerlink" href="#kotlin" title="Permalink to this headline"></a></h2>
<p>The prototype is written in a language called <a class="reference external" href="https://kotlinlang.org/">Kotlin</a>. Kotlin is a language that targets the JVM
and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support
from JetBrains, the makers of the IntelliJ IDE and other popular developer tools.</p>
<p>As Kotlin is very new, without a doubt you have not encountered it before. Don&#8217;t worry: it is designed as a better
Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don&#8217;t know
the language, after only a few minutes of introduction.</p>
<p>Due to the seamless Java interop the use of Kotlin to extend the platform is <em>not</em> required and the tutorial shows how
to write contracts in both Kotlin and Java. You can <a class="reference external" href="https://medium.com/&#64;octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3">read more about why Kotlin is a potentially strong successor to Java here</a>.</p>
<p>Kotlin programs use the regular Java standard library and ordinary Java frameworks. Frameworks used at this time are:</p>
<ul class="simple">
<li>JUnit for unit testing</li>
<li>Kryo for serialisation (this is not intended to be permanent)</li>
<li>Gradle for the build</li>
<li>Guava for a few utility functions</li>
</ul>
</div>
</div>
@ -298,10 +257,10 @@ to write contracts in both Kotlin and Java. You can <a class="reference external
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="getting-set-up.html" class="btn btn-neutral float-right" title="Getting set up" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<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="inthebox.html" class="btn btn-neutral" title="What’s included?" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</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>

13
docs/build/html/genindex.html vendored
View File

@ -80,13 +80,20 @@
<ul>
<p class="caption"><span class="caption-text">Overview</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="overview.html">Overview</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="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</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>
</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="roadmap.html">Roadmap</a></li>
</ul>

25
docs/build/html/getting-set-up.html vendored
View File

@ -31,8 +31,8 @@
<link rel="top" title="R3 Prototyping 0.1 documentation" href="index.html"/>
<link rel="next" title="Tutorial" href="tutorial.html"/>
<link rel="prev" title="Overview" href="overview.html"/>
<link rel="next" title="Data model" href="data-model.html"/>
<link rel="prev" title="What’s included?" href="inthebox.html"/>
<script src="_static/js/modernizr.min.js"></script>
@ -81,17 +81,24 @@
<ul class="current">
<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&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Getting set up</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#if-intellij-complains-about-lack-of-an-sdk">If IntelliJ complains about lack of an SDK</a></li>
<li class="toctree-l2"><a class="reference internal" href="#doing-it-without-intellij">Doing it without IntelliJ</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</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>
</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="roadmap.html">Roadmap</a></li>
</ul>
@ -144,11 +151,11 @@
<p>Then install IntelliJ version 15 community edition:</p>
<blockquote>
<div><a class="reference external" href="https://www.jetbrains.com/idea/download/">https://www.jetbrains.com/idea/download/</a></div></blockquote>
<p>Upgrade the Kotlin plugin to the latest version (1.0-beta-2423) by clicking &#8220;Configure &gt; Plugins&#8221; in the opening screen,
<p>Upgrade the Kotlin plugin to the latest version (1.0-beta-3595) by clicking &#8220;Configure &gt; Plugins&#8221; in the opening screen,
then clicking &#8220;Install JetBrains plugin&#8221;, then searching for Kotlin, then hitting &#8220;Upgrade&#8221; and then &#8220;Restart&#8221;.</p>
<p>Choose &#8220;Check out from version control&#8221; and use this git URL</p>
<blockquote>
<div><a class="reference external" href="https://your_username&#64;bitbucket.org/R3-CEV/playground.git">https://your_username&#64;bitbucket.org/R3-CEV/playground.git</a></div></blockquote>
<div><a class="reference external" href="https://your_username&#64;bitbucket.org/R3-CEV/r3repository.git">https://your_username&#64;bitbucket.org/R3-CEV/r3repository.git</a></div></blockquote>
<p>Agree to the defaults for importing a Gradle project. Wait for it to think and download the dependencies.</p>
<p>Right click on the tests directory, click &#8220;Run -&gt; All Tests&#8221; (note: NOT the first item in the submenu that has the
gradle logo next to it).</p>
@ -185,10 +192,10 @@ found at something like</p>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="tutorial.html" class="btn btn-neutral float-right" title="Tutorial" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="data-model.html" class="btn btn-neutral float-right" title="Data model" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="overview.html" class="btn btn-neutral" title="Overview" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
<a href="inthebox.html" class="btn btn-neutral" title="What’s included?" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>

54
docs/build/html/index.html vendored
View File

@ -80,13 +80,20 @@
<ul>
<p class="caption"><span class="caption-text">Overview</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="overview.html">Overview</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="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</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>
</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="roadmap.html">Roadmap</a></li>
</ul>
@ -148,13 +155,12 @@ prove or disprove the following hypothesis:</p>
</ul>
<p><em>is sufficiently powerful to justify the creation of a new platform implementation.</em></p>
<p>Read on to learn:</p>
<div class="toctree-wrapper compound">
<div class="toctree-wrapper compound" id="overview">
<p class="caption"><span class="caption-text">Overview</span><a class="headerlink" href="#overview" title="Permalink to this toctree"></a></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="overview.html">Overview</a><ul>
<li class="toctree-l2"><a class="reference internal" href="overview.html#data-model">Data model</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#contracts">Contracts</a></li>
<li class="toctree-l2"><a class="reference internal" href="overview.html#kotlin">Kotlin</a></li>
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What&#8217;s included?</a><ul>
<li class="toctree-l2"><a class="reference internal" href="inthebox.html#contracts">Contracts</a></li>
<li class="toctree-l2"><a class="reference internal" href="inthebox.html#kotlin">Kotlin</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a><ul>
@ -162,7 +168,24 @@ prove or disprove the following hypothesis:</p>
<li class="toctree-l2"><a class="reference internal" href="getting-set-up.html#doing-it-without-intellij">Doing it without IntelliJ</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a><ul>
<li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a><ul>
<li class="toctree-l2"><a class="reference internal" href="data-model.html#description">Description</a></li>
<li class="toctree-l2"><a class="reference internal" href="data-model.html#comparison-with-bitcoin">Comparison with Bitcoin</a></li>
<li class="toctree-l2"><a class="reference internal" href="data-model.html#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><ul>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#messaging-vs-networking">Messaging vs networking</a></li>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#interfaces">Interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#in-memory-implementation">In memory implementation</a></li>
</ul>
</li>
</ul>
</div>
<div class="toctree-wrapper compound" id="tutorials">
<p class="caption"><span class="caption-text">Tutorials</span><a class="headerlink" href="#tutorials" title="Permalink to this toctree"></a></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Writing a contract</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#starting-the-commercial-paper-class">Starting the commercial paper class</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#states">States</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#commands">Commands</a></li>
@ -174,12 +197,6 @@ prove or disprove the following hypothesis:</p>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html#non-asset-oriented-based-smart-contracts">Non-asset-oriented based smart contracts</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a><ul>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#messaging-vs-networking">Messaging vs networking</a></li>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#interfaces">Interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="messaging.html#in-memory-implementation">In memory implementation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="protocol-state-machines.html">Protocol state machines</a><ul>
<li class="toctree-l2"><a class="reference internal" href="protocol-state-machines.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="protocol-state-machines.html#theory">Theory</a></li>
@ -189,6 +206,11 @@ prove or disprove the following hypothesis:</p>
<li class="toctree-l2"><a class="reference internal" href="protocol-state-machines.html#implementing-the-buyer">Implementing the buyer</a></li>
</ul>
</li>
</ul>
</div>
<div class="toctree-wrapper compound" id="appendix">
<p class="caption"><span class="caption-text">Appendix</span><a class="headerlink" href="#appendix" title="Permalink to this toctree"></a></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="roadmap.html">Roadmap</a></li>
</ul>

61
docs/build/html/inthebox.html vendored
View File

@ -31,7 +31,7 @@
<link rel="top" title="R3 Prototyping 0.1 documentation" href="index.html"/>
<link rel="next" title="Overview" href="overview.html"/>
<link rel="next" title="Getting set up" href="getting-set-up.html"/>
<link rel="prev" title="Welcome to the R3 prototyping repository!" href="index.html"/>
@ -81,13 +81,24 @@
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="">What&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
<p class="caption"><span class="caption-text">Overview</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="">What&#8217;s included?</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#contracts">Contracts</a></li>
<li class="toctree-l2"><a class="reference internal" href="#kotlin">Kotlin</a></li>
</ul>
</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="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</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>
</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="roadmap.html">Roadmap</a></li>
</ul>
@ -161,6 +172,44 @@ would not in order to boost productivity:</p>
<li>It uses a serialization framework instead of a well specified, vendor neutral protocol.</li>
<li>It uses secp256r1, an obsolete elliptic curve.</li>
</ul>
<div class="section" id="contracts">
<h2>Contracts<a class="headerlink" href="#contracts" title="Permalink to this headline"></a></h2>
<p>The primary goal of this prototype is to implement various kinds of contracts and verify that useful business logic
can be expressed with the data model, developing and refining an API along the way. To that end there are currently
two contracts in the repository:</p>
<ol class="arabic simple">
<li>Cash</li>
<li>Commercial paper</li>
</ol>
<p><code class="docutils literal"><span class="pre">Cash</span></code> implements the idea of a claim on some quantity of deposits at some institutional party, denominated in some currency,
identified by some <em>deposit reference</em>. A deposit reference is an opaque byte array which is usable by
the issuing party for internal bookkeeping purposes.</p>
<p>Cash states are <em>fungible</em> with each other (can be merged and split arbitrarily) if they use the same currency,
party and deposit reference.</p>
<p><code class="docutils literal"><span class="pre">CommercialPaper</span></code> implements an asset with a <em>face value</em> denominated in a certain currency, which may be redeemed at
the issuing party after a certain time. Commercial paper states define the face value (e.g. $1000) and the time
at which they may be redeemed. The contract allows the paper to be issued, traded and redeemed. The commercial paper
contract is implemented twice, once in Java and once in a language called Kotlin.</p>
<p>Each contract comes with unit tests.</p>
</div>
<div class="section" id="kotlin">
<h2>Kotlin<a class="headerlink" href="#kotlin" title="Permalink to this headline"></a></h2>
<p>The prototype is written in a language called <a class="reference external" href="https://kotlinlang.org/">Kotlin</a>. Kotlin is a language that targets the JVM
and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support
from JetBrains, the makers of the IntelliJ IDE and other popular developer tools.</p>
<p>As Kotlin is very new, without a doubt you have not encountered it before. Don&#8217;t worry: it is designed as a better
Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don&#8217;t know
the language, after only a few minutes of introduction.</p>
<p>Due to the seamless Java interop the use of Kotlin to extend the platform is <em>not</em> required and the tutorial shows how
to write contracts in both Kotlin and Java. You can <a class="reference external" href="https://medium.com/&#64;octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3">read more about why Kotlin is a potentially strong successor to Java here</a>.</p>
<p>Kotlin programs use the regular Java standard library and ordinary Java frameworks. Frameworks used at this time are:</p>
<ul class="simple">
<li>JUnit for unit testing</li>
<li>Kryo for serialisation (this is not intended to be permanent)</li>
<li>Gradle for the build</li>
<li>Guava for a few utility functions</li>
</ul>
</div>
</div>
@ -170,7 +219,7 @@ would not in order to boost productivity:</p>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="overview.html" class="btn btn-neutral float-right" title="Overview" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="getting-set-up.html" class="btn btn-neutral float-right" title="Getting set up" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="index.html" class="btn btn-neutral" title="Welcome to the R3 prototyping repository!" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>

21
docs/build/html/messaging.html vendored
View File

@ -31,8 +31,8 @@
<link rel="top" title="R3 Prototyping 0.1 documentation" href="index.html"/>
<link rel="next" title="Protocol state machines" href="protocol-state-machines.html"/>
<link rel="prev" title="Tutorial" href="tutorial.html"/>
<link rel="next" title="Writing a contract" href="tutorial.html"/>
<link rel="prev" title="Data model" href="data-model.html"/>
<script src="_static/js/modernizr.min.js"></script>
@ -81,18 +81,25 @@
<ul class="current">
<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&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</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="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Networking and messaging</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#messaging-vs-networking">Messaging vs networking</a></li>
<li class="toctree-l2"><a class="reference internal" href="#interfaces">Interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="#in-memory-implementation">In memory implementation</a></li>
</ul>
</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>
</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="roadmap.html">Roadmap</a></li>
</ul>
@ -231,10 +238,10 @@ nodes run in parallel, just as they would on a real network spread over multiple
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="protocol-state-machines.html" class="btn btn-neutral float-right" title="Protocol state machines" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tutorial.html" class="btn btn-neutral float-right" title="Writing a contract" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tutorial.html" class="btn btn-neutral" title="Tutorial" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
<a href="data-model.html" class="btn btn-neutral" title="Data model" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>

BIN
docs/build/html/objects.inv vendored
View File

Binary file not shown.

17
docs/build/html/protocol-state-machines.html vendored
View File

@ -32,7 +32,7 @@
<link rel="top" title="R3 Prototyping 0.1 documentation" href="index.html"/>
<link rel="next" title="Using the visualiser" href="visualiser.html"/>
<link rel="prev" title="Networking and messaging" href="messaging.html"/>
<link rel="prev" title="Writing a contract" href="tutorial.html"/>
<script src="_static/js/modernizr.min.js"></script>
@ -81,12 +81,16 @@
<ul class="current">
<p class="caption"><span class="caption-text">Overview</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="overview.html">Overview</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="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Writing a contract</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Protocol state machines</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#theory">Theory</a></li>
@ -96,6 +100,9 @@
<li class="toctree-l2"><a class="reference internal" href="#implementing-the-buyer">Implementing the buyer</a></li>
</ul>
</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="roadmap.html">Roadmap</a></li>
</ul>
@ -543,7 +550,7 @@ restart.</p>
<a href="visualiser.html" class="btn btn-neutral float-right" title="Using the visualiser" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="messaging.html" class="btn btn-neutral" title="Networking and messaging" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
<a href="tutorial.html" class="btn btn-neutral" title="Writing a contract" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>

13
docs/build/html/roadmap.html vendored
View File

@ -80,13 +80,20 @@
<ul class="current">
<p class="caption"><span class="caption-text">Overview</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="overview.html">Overview</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="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</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>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="visualiser.html">Using the visualiser</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Roadmap</a></li>
</ul>

13
docs/build/html/search.html vendored
View File

@ -79,13 +79,20 @@
<ul>
<p class="caption"><span class="caption-text">Overview</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="overview.html">Overview</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="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</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>
</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="roadmap.html">Roadmap</a></li>
</ul>

2
docs/build/html/searchindex.js vendored
View File

File diff suppressed because one or more lines are too long

31
docs/build/html/tutorial.html vendored
View File

@ -8,7 +8,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Tutorial &mdash; R3 Prototyping 0.1 documentation</title>
<title>Writing a contract &mdash; R3 Prototyping 0.1 documentation</title>
@ -31,8 +31,8 @@
<link rel="top" title="R3 Prototyping 0.1 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"/>
<link rel="next" title="Protocol state machines" href="protocol-state-machines.html"/>
<link rel="prev" title="Networking and messaging" href="messaging.html"/>
<script src="_static/js/modernizr.min.js"></script>
@ -81,11 +81,16 @@
<ul class="current">
<p class="caption"><span class="caption-text">Overview</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="overview.html">Overview</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="">Tutorial</a><ul>
<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="messaging.html">Networking and messaging</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="">Writing a contract</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#starting-the-commercial-paper-class">Starting the commercial paper class</a></li>
<li class="toctree-l2"><a class="reference internal" href="#states">States</a></li>
<li class="toctree-l2"><a class="reference internal" href="#commands">Commands</a></li>
@ -97,8 +102,10 @@
<li class="toctree-l2"><a class="reference internal" href="#non-asset-oriented-based-smart-contracts">Non-asset-oriented based smart contracts</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="protocol-state-machines.html">Protocol state machines</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="roadmap.html">Roadmap</a></li>
</ul>
@ -131,7 +138,7 @@
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Tutorial</li>
<li>Writing a contract</li>
<li class="wy-breadcrumbs-aside">
@ -146,8 +153,8 @@
<div itemprop="articleBody">
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script><div class="section" id="tutorial">
<h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline"></a></h1>
<script type="text/javascript" src="_static/codesets.js"></script><div class="section" id="writing-a-contract">
<h1>Writing a contract<a class="headerlink" href="#writing-a-contract" title="Permalink to this headline"></a></h1>
<p>This tutorial will take you through how the commercial paper contract works.</p>
<p>The code in this tutorial is available in both Kotlin and Java. You can quickly switch between them to get a feeling
for how Kotlin syntax works.</p>
@ -859,10 +866,10 @@ be implemented once in a separate contract, with the controlling data being held
<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="protocol-state-machines.html" class="btn btn-neutral float-right" title="Protocol state machines" 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>
<a href="messaging.html" class="btn btn-neutral" title="Networking and messaging" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>

13
docs/build/html/visualiser.html vendored
View File

@ -81,13 +81,20 @@
<ul class="current">
<p class="caption"><span class="caption-text">Overview</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="overview.html">Overview</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="tutorial.html">Tutorial</a></li>
<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="messaging.html">Networking and messaging</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>
</ul>
<p class="caption"><span class="caption-text">Appendix</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="roadmap.html">Roadmap</a></li>
</ul>

87
docs/build/html/_sources/overview.txt → docs/source/data-model.rst
View File

@ -1,13 +1,13 @@
Overview
========
Data model
==========
Description
-----------
This article covers the data model: how *states*, *transactions* and *code contracts* 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.
Data model
----------
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.
@ -18,7 +18,7 @@ are created and destroyed by digitally signed **transactions**. Each transaction
consume/destroy, these are called **inputs**, and contains a set of new states that it will create, these are called
**outputs**.
States contain arbitrary data, but they always contain at minimum a pointer to the bytecode of a
States contain arbitrary data, but they always contain at minimum a hash of the bytecode of a
**code contract**, 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 **verify function**, which is a pure function given the entire transaction as input.
@ -26,26 +26,21 @@ define a **verify function**, which is a pure function given the entire transact
To be considered valid, the transaction must be **accepted** by the verify function of every contract pointed to by the
input and output states. Beyond inputs and outputs, transactions may also contain **commands**, 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.
arguments to the verify function. Each command has a list of **public keys** 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 *public key infrastructure* (PKI).
Note that there is nothing that explicitly binds together specific inputs, outputs or commands. 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.
A transaction has one or more **signatures** attached to it. The signatures do not mean anything by themselves, rather,
their existence is given as input to the contract which can then decide which set of signatures it demands (if any).
Signatures may be from an arbitrary, random **public key** that has no identity attached. A public key may be
well known, that is, appears in some sort of public identity registry. In this case we say the key is owned by a
**party**, which is defined (for now) as being merely a (public key, name) pair.
A transaction may also be **timestamped**. A timestamp is a (hash, datetime, signature) triple from a
*timestamping authority* (TSA). The notion of a TSA is not ledger specific and is defined by
`IETF RFC 3161 <https://www.ietf.org/rfc/rfc3161.txt>`_ which defines the internet standard Timestamping Protocol (TSP).
The purpose of the TSA is to attach a single, globally agreed upon time which a contract may use to enforce certain
types of time-based logic. The TSA's do not need to know about the contents of the transaction in order to provide a
timestamp, and they are therefore never exposed to private data.
.. note:: In the current code, use of TSAs is not implemented.
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 **oracles** and they provide facts to the ledger by signing transactions that contain commands they
recognise. 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 **timestamping authority** (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).
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
@ -60,7 +55,7 @@ factors are:
* Simplified auditing
Comparison with Bitcoin
^^^^^^^^^^^^^^^^^^^^^^^
-----------------------
Similarities:
@ -93,7 +88,7 @@ Differences:
(this is often called "wallet code" in Bitcoin).
Comparison with Ethereum
^^^^^^^^^^^^^^^^^^^^^^^^
------------------------
Similarities:
@ -113,49 +108,3 @@ Differences:
* 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.
Contracts
---------
The primary goal of this prototype is to implement various kinds of contracts and verify that useful business logic
can be expressed with the data model, developing and refining an API along the way. To that end there are currently
two contracts in the repository:
1. Cash
2. Commercial paper
``Cash`` implements the idea of a claim on some quantity of deposits at some institutional party, denominated in some currency,
identified by some *deposit reference*. A deposit reference is an opaque byte array which is usable by
the issuing party for internal bookkeeping purposes.
Cash states are *fungible* with each other (can be merged and split arbitrarily) if they use the same currency,
party and deposit reference.
``CommercialPaper`` implements an asset with a *face value* denominated in a certain currency, which may be redeemed at
the issuing party after a certain time. Commercial paper states define the face value (e.g. $1000) and the time
at which they may be redeemed. The contract allows the paper to be issued, traded and redeemed. The commercial paper
contract is implemented twice, once in Java and once in a language called Kotlin.
Each contract comes with unit tests.
Kotlin
------
The prototype is written in a language called `Kotlin <https://kotlinlang.org/>`_. Kotlin is a language that targets the JVM
and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support
from JetBrains, the makers of the IntelliJ IDE and other popular developer tools.
As Kotlin is very new, without a doubt you have not encountered it before. Don't worry: it is designed as a better
Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don't know
the language, after only a few minutes of introduction.
Due to the seamless Java interop the use of Kotlin to extend the platform is *not* required and the tutorial shows how
to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here <https://medium.com/@octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3>`_.
Kotlin programs use the regular Java standard library and ordinary Java frameworks. Frameworks used at this time are:
* JUnit for unit testing
* Kryo for serialisation (this is not intended to be permanent)
* Gradle for the build
* Guava for a few utility functions

15
docs/source/index.rst
View File

@ -21,13 +21,24 @@ Read on to learn:
.. toctree::
:maxdepth: 2
:caption: Overview
inthebox
overview
getting-set-up
tutorial
data-model
messaging
.. toctree::
:maxdepth: 2
:caption: Tutorials
tutorial
protocol-state-machines
.. toctree::
:maxdepth: 2
:caption: Appendix
visualiser
roadmap

47
docs/source/inthebox.rst
View File

@ -25,4 +25,49 @@ The prototype's goal is rapid exploration of ideas. Therefore in places it takes
would not in order to boost productivity:
* It uses a serialization framework instead of a well specified, vendor neutral protocol.
* It uses secp256r1, an obsolete elliptic curve.
* It uses secp256r1, an obsolete elliptic curve.
Contracts
---------
The primary goal of this prototype is to implement various kinds of contracts and verify that useful business logic
can be expressed with the data model, developing and refining an API along the way. To that end there are currently
two contracts in the repository:
1. Cash
2. Commercial paper
``Cash`` implements the idea of a claim on some quantity of deposits at some institutional party, denominated in some currency,
identified by some *deposit reference*. A deposit reference is an opaque byte array which is usable by
the issuing party for internal bookkeeping purposes.
Cash states are *fungible* with each other (can be merged and split arbitrarily) if they use the same currency,
party and deposit reference.
``CommercialPaper`` implements an asset with a *face value* denominated in a certain currency, which may be redeemed at
the issuing party after a certain time. Commercial paper states define the face value (e.g. $1000) and the time
at which they may be redeemed. The contract allows the paper to be issued, traded and redeemed. The commercial paper
contract is implemented twice, once in Java and once in a language called Kotlin.
Each contract comes with unit tests.
Kotlin
------
The prototype is written in a language called `Kotlin <https://kotlinlang.org/>`_. Kotlin is a language that targets the JVM
and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support
from JetBrains, the makers of the IntelliJ IDE and other popular developer tools.
As Kotlin is very new, without a doubt you have not encountered it before. Don't worry: it is designed as a better
Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don't know
the language, after only a few minutes of introduction.
Due to the seamless Java interop the use of Kotlin to extend the platform is *not* required and the tutorial shows how
to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here <https://medium.com/@octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3>`_.
Kotlin programs use the regular Java standard library and ordinary Java frameworks. Frameworks used at this time are:
* JUnit for unit testing
* Kryo for serialisation (this is not intended to be permanent)
* Gradle for the build
* Guava for a few utility functions

4
docs/source/tutorial.rst
View File

@ -4,8 +4,8 @@
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Tutorial
========
Writing a contract
==================
This tutorial will take you through how the commercial paper contract works.