ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-02-04 10:11:14 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Documentation regen

Browse Source
This commit is contained in:
Richard Green 2016-04-13 10:29:54 +01:00
parent 19ecbcd863
commit e1bcfd197b
29 changed files with 568 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/build/html/.buildinfo vendored
View File

@ -1,4 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: b08dca817adc75e78b383039f097775b
config: ea2b50e74e4f198a7f0eac80af818dde
tags: 645f666f9bcd5a90fca523b33c5a78b7

BIN
docs/build/html/_images/irs.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 100 KiB

2
docs/build/html/_sources/data-model.txt vendored
View File

@ -56,7 +56,7 @@ factors are:
* Improved contract flexibility vs Bitcoin
* Improved scalability vs Ethereum, as well as ability to keep parts of the transaction graph private (yet still uniquely addressable)
* No reliance on proof of work
* Re-us of existing sandboxing virtual machines
* Re-use of existing sandboxing virtual machines
* Use of type safe GCd implementation languages.
* Simplified auditing

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

@ -54,6 +54,9 @@ the issuing party after a certain time. Commercial paper states define the face
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.
``InterestRateSwap`` implements a vanilla OTC same currency bilateral fixed / floating leg swap. For further details,
see :doc:`irs`
Each contract comes with unit tests.
Kotlin

108
docs/build/html/_sources/irs.txt vendored Normal file
View File

@ -0,0 +1,108 @@
The Interest Rate Swap Contract
===============================
The Interest Rate Swap (IRS) Contract (source: IRS.kt, IRSUtils.kt, IRSExport.kt) is a bilateral contract to implement a
vanilla fixed / floating same currency IRS.
In general, an IRS allows two counterparties to modify their exposure from changes in the underlying interest rate. They
are often used as a hedging instrument, convert a fixed rate loan to a floating rate loan, vice versa etc.
The IRS contract exists over a period of time (normally measurable in years). It starts on its value date
(although this is not the agreement date), and is considered to be no longer active after its maturity date. During that
time, there is an exchange of cash flows which are calculated by looking at the economics of each leg. These are based
upon an amount that is not actually exchanged but notionally used for the calculation (and is hence known as the notional
amount), and a rate that is either fixed at the creation of the swap (for the fixed leg), or based upon a reference rate
that is retrieved during the swap (for the floating leg). An example reference rate might be something such as 'LIBOR 3M'.
The fixed leg has its rate computed and set in advance, where as the floating leg has a fixing process whereas the rate
for the next period is fixed with relation to a reference rate. Then, a calculation is performed such that the interest
due over that period multiplied by the notional is paid (normally at the end of the period). If these two legs have the
same payment date, then these flows can be offset against each other (in reality there are normally a number of these
swaps that are live between two counterparties, so that further netting is performed at counterparty level).
The fixed leg and floating leg do not have to have the same period frequency. In fact, conventional swaps do not have
the same period.
Currently, there is no notion of an actual payment or obligation being performed in the contract code we have written;
it merely represents that the payment needs to be made.
Consider the diagram below; the x-axis represents time and the y-axis the size of the leg payments (not to scale), from
the view of the floating leg receiver / fixed leg payer. The enumerated documents represent the versions of the IRS as
it progresses (note that, the first version exists before the value date), the dots on the "y=0" represent an interest
rate value becoming available and then the curved arrow indicates to which period the fixing applies.
.. image:: irs.png
Two days (by convention, although this can be modified), before the value date (ie the start of the swap) in the red
period the reference rate is observed from an oracle and fixed in the instance at 1.1%. At the end of the accrual period,
there is an obligation from the floating leg payer of 1.1% * notional amount * days in the accrual period / 360.
(Also note that the result of "days in the accrual period / 360" is also known as the day count factor, although other
conventions are allowed and will be supported). This amount is then paid at a determined time at the end of the accrual period.
Again, two working days before the blue period, the rate is fixed (this time at 0.5% - however in reality, the rates
would not be so significantly different), and the same calculation is performed to evaluate the payment that will be due
at the end of this period.
This process continues until the swap reaches maturity and the final payments are calculated.
Creating an instance and lifecycle
----------------------------------
There are two valid operations on an IRS. The first is to generate via the ``Agree`` command (signed by both parties)
and the second (and repeated operation) is ``Fix`` to apply a rate fixing.
To see the minimum dataset required for the creation of an IRS, refer to ``IRSTests.kt`` which has two examples in the
function ``IRSTests.createDummyIRS()``. Implicitly, when the agree function is called, the floating leg and fixed
leg payment schedules are created (more details below) and can be queried.
Once an IRS hase been agreed, then the the only valid operation is to apply a fixing on one of the entries in the
``Calculation.floatingLegPaymentSchedule`` map. Fixes do not have to be applied in order (although it does make most
sense to do them so).
Examples of applying fixings to rates can been seen in ``IRSTests.generateIRSandFixSome()`` which loops through the next
fixing date of an IRS that is created with the above example function and then applies a fixing of 0.052% to each floating
event.
Currently, there are no matured, termination or dispute operations.
Technical Details
-----------------
The contract itself comprises of 4 data state classes, ``FixedLeg``, ``FloatingLeg``, ``Common`` and ``Calculation``.
Recall that the platform model is strictly immutable. To further that, between states, the only class that is modified
is the ``Calculation`` class.
The ``Common`` data class contains all data that is general to the entire swap, e.g. data like trade identifier,
valuation date, etc.
The Fixed and Floating leg classes derive from a common base class ``CommonLeg``. This is due to the simple reason that
they share a lot of common fields.
The ``CommonLeg`` class contains the notional amount, a payment frequency, the effective date (as well as an adjustment
option), a termination date (and optional adjustment), the day count basis for day factor calculation, the payment delay
and calendar for the payment as well as the accrual adjustment options.
The ``FixedLeg`` contains all the details for the ``CommonLeg`` as well as payer details, the rate the leg is fixed at
and the date roll convention (ie what to do if the calculated date lands on a bank holiday or weekend).
The ``FloatingLeg`` contains all the details for the CommonLeg and payer details, roll convention, the fixing roll
convention, which day of the month the reset is calculated, the frequency period of the fixing, the fixing calendar and
the details for the reference index (source and tenor).
The ``Calculation`` class contains an expression (that can be evaluated via the ledger using variables provided and also
any members of the contract) and two schedules - a ``floatingLegPaymentSchedule`` and a ``fixedLegPaymentSchedule``.
The fixed leg schedule is obviously pre-ordained, however, during the lifetime of the swap, the floating leg schedule is
regenerated upon each fixing being presented.
For this reason, there are two helper functions on the floating leg. ``Calculation.getFixing`` returns the date of the
earliest unset fixing, and ``Calculation.applyFixing`` returns a new Calculation object with the revised fixing in place.
Note that both schedules are, for consistency, indexed by payment dates, but the fixing is (due to the convention of
taking place two days previously) not going to be on that date.
.. note:: Payment events in the ``floatingLegPaymentSchedule`` that start as a ``FloatingRatePaymentEvent`` (which is a
representation of a payment for a rate that has not yet been finalised) are replaced in their entirety with an
equivalent ``FixedRatePaymentEvent`` (which is the same type that is on the ``FixedLeg``).

8
docs/build/html/_sources/node-administration.txt vendored
View File

@ -77,10 +77,10 @@ The file looks like this::
# Some pretend noddy rate fixes, for the interest rate oracles.
LIBOR 2016-03-16 30 = 0.678
LIBOR 2016-03-16 60 = 0.655
EURIBOR 2016-03-15 30 = 0.123
EURIBOR 2016-03-15 60 = 0.111
LIBOR 2016-03-16 1M = 0.678
LIBOR 2016-03-16 2M = 0.655
EURIBOR 2016-03-15 1M = 0.123
EURIBOR 2016-03-15 2M = 0.111
The columns are:

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

@ -611,7 +611,7 @@ In this example we see some new features of the DSL:
* The ``transaction`` function can also be given a time, to override the default timestamp on a transaction.
The ``trade`` function is not itself a unit test. Instead it builds up a trade/transaction group, with some slight
differences depending on the parameters provided (Kotlin allows parameters to have default valus). Then it returns
differences depending on the parameters provided (Kotlin allows parameters to have default values). Then it returns
it, unexecuted.
We use it like this:

11
docs/build/html/_static/basic.css vendored
View File

@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
@ -52,6 +52,8 @@ div.sphinxsidebar {
width: 230px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
@ -187,6 +189,13 @@ div.genindex-jumpbox {
/* -- general body styles --------------------------------------------------- */
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}

28
docs/build/html/_static/doctools.js vendored
View File

@ -4,7 +4,7 @@
*
* Sphinx JavaScript utilities for all documentation.
*
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
@ -124,6 +124,7 @@ var Documentation = {
this.fixFirefoxAnchorBug();
this.highlightSearchWords();
this.initIndexTable();
},
/**
@ -252,6 +253,29 @@ var Documentation = {
});
var url = parts.join('/');
return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
},
initOnKeyListeners: function() {
$(document).keyup(function(event) {
var activeElementType = document.activeElement.tagName;
// don't navigate when in search box or textarea
if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') {
switch (event.keyCode) {
case 37: // left
var prevHref = $('link[rel="prev"]').prop('href');
if (prevHref) {
window.location.href = prevHref;
return false;
}
case 39: // right
var nextHref = $('link[rel="next"]').prop('href');
if (nextHref) {
window.location.href = nextHref;
return false;
}
}
}
});
}
};
@ -260,4 +284,4 @@ _ = Documentation.gettext;
$(document).ready(function() {
Documentation.init();
});
});

BIN
docs/build/html/_static/irs.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

2
docs/build/html/_static/pygments.css vendored
View File

@ -4,8 +4,10 @@
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #007020; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #007020 } /* Comment.Preproc */
.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */

51
docs/build/html/_static/searchtools.js vendored
View File

@ -2,14 +2,15 @@
* searchtools.js_t
* ~~~~~~~~~~~~~~~~
*
* Sphinx JavaScript utilties for the full-text search.
* Sphinx JavaScript utilities for the full-text search.
*
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* Non-minified version JS is _stemmer.js if file is provided */
/**
* Porter Stemmer
*/
@ -373,8 +374,7 @@ var Search = {
}
// lookup as search terms in fulltext
results = results.concat(this.performTermsSearch(searchterms, excluded, terms, Scorer.term))
.concat(this.performTermsSearch(searchterms, excluded, titleterms, Scorer.title));
results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms));
// let the scorer override scores with a custom scoring function
if (Scorer.score) {
@ -538,23 +538,47 @@ var Search = {
/**
* search for full-text terms in the index
*/
performTermsSearch : function(searchterms, excluded, terms, score) {
performTermsSearch : function(searchterms, excluded, terms, titleterms) {
var filenames = this._index.filenames;
var titles = this._index.titles;
var i, j, file, files;
var i, j, file;
var fileMap = {};
var scoreMap = {};
var results = [];
// perform the search on the required terms
for (i = 0; i < searchterms.length; i++) {
var word = searchterms[i];
var files = [];
var _o = [
{files: terms[word], score: Scorer.term},
{files: titleterms[word], score: Scorer.title}
];
// no match but word was a required one
if ((files = terms[word]) === undefined)
if ($u.every(_o, function(o){return o.files === undefined;})) {
break;
if (files.length === undefined) {
files = [files];
}
// found search word in contents
$u.each(_o, function(o) {
var _files = o.files;
if (_files === undefined)
return
if (_files.length === undefined)
_files = [_files];
files = files.concat(_files);
// set score for the word in each file to Scorer.term
for (j = 0; j < _files.length; j++) {
file = _files[j];
if (!(file in scoreMap))
scoreMap[file] = {}
scoreMap[file][word] = o.score;
}
});
// create the mapping
for (j = 0; j < files.length; j++) {
file = files[j];
@ -576,7 +600,9 @@ var Search = {
// ensure that none of the excluded terms is in the search result
for (i = 0; i < excluded.length; i++) {
if (terms[excluded[i]] == file ||
$u.contains(terms[excluded[i]] || [], file)) {
titleterms[excluded[i]] == file ||
$u.contains(terms[excluded[i]] || [], file) ||
$u.contains(titleterms[excluded[i]] || [], file)) {
valid = false;
break;
}
@ -584,6 +610,9 @@ var Search = {
// if we have still a valid result we can add it to the result list
if (valid) {
// select one (max) score for the file.
// for better ranking, we should calculate ranking by using words statistics like basic tf-idf...
var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]}));
results.push([filenames[file], titles[file], '', null, score]);
}
}
@ -594,7 +623,7 @@ var Search = {
* helper function to return a node containing the
* search summary for a given text. keywords is a list
* of stemmed words, hlwords is the list of normal, unstemmed
* words. the first one is used to find the occurance, the
* words. the first one is used to find the occurrence, the
* latter for highlighting it.
*/
makeSearchSummary : function(text, keywords, hlwords) {

4
docs/build/html/_static/websupport.js vendored
View File

@ -2,9 +2,9 @@
* websupport.js
* ~~~~~~~~~~~~~
*
* sphinx.websupport utilties for all documentation.
* sphinx.websupport utilities for all documentation.
*
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/

12
docs/build/html/codestyle.html vendored
View File

@ -102,7 +102,7 @@
<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="">Code style guide</a><ul>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Code style guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#general-style">1. General style</a></li>
<li class="toctree-l2"><a class="reference internal" href="#comments">2. Comments</a></li>
<li class="toctree-l2"><a class="reference internal" href="#threading">3. Threading</a></li>
@ -131,7 +131,7 @@
<div class="rst-content">
@ -221,14 +221,14 @@ is not always right.</li>
<li>Make good use of <a class="reference external" href="mailto:{&#37;&#52;&#48;link">{<span>&#64;</span>link</a>} annotations.</li>
</ul>
<p>Bad JavaDocs look like this:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="cm">/** @return the size of the Bloom filter. */</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="cm">/** @return the size of the Bloom filter. */</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="nf">getBloomFilterSize</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">block</span><span class="o">;</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Good JavaDocs look like this:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="cm">/**</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="cm">/**</span>
<span class="cm"> * Returns the size of the current {@link BloomFilter} in bytes. Larger filters have</span>
<span class="cm"> * lower false positive rates for the same number of inserted keys and thus lower privacy,</span>
<span class="cm"> * but bandwidth usage is also correspondingly reduced.</span>
@ -279,11 +279,11 @@ and instead prefer to use the <code class="docutils literal"><span class="pre">c
<p>We define new exception types liberally. We prefer not to provide English language error messages in exceptions at
the throw site, instead we define new types with any useful information as fields, with a toString() method if
really necessary. In other words, don&#8217;t do this:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="k">throw</span> <span class="k">new</span> <span class="n">Exception</span><span class="o">(</span><span class="s">&quot;The foo broke&quot;</span><span class="o">)</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="k">throw</span> <span class="k">new</span> <span class="n">Exception</span><span class="o">(</span><span class="s">&quot;The foo broke&quot;</span><span class="o">)</span>
</pre></div>
</div>
<p>instead do this</p>
<div class="highlight-java"><div class="highlight"><pre><span class="kd">class</span> <span class="nc">FooBrokenException</span> <span class="kd">extends</span> <span class="n">Exception</span> <span class="o">{}</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">class</span> <span class="nc">FooBrokenException</span> <span class="kd">extends</span> <span class="n">Exception</span> <span class="o">{}</span>
<span class="k">throw</span> <span class="k">new</span> <span class="n">FooBrokenException</span><span class="o">()</span>
</pre></div>
</div>

6
docs/build/html/data-model.html vendored
View File

@ -89,7 +89,7 @@
<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="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-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>
@ -131,7 +131,7 @@
<div class="rst-content">
@ -201,7 +201,7 @@ factors are:</p>
<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>Re-use of existing sandboxing virtual machines</li>
<li>Use of type safe GCd implementation languages.</li>
<li>Simplified auditing</li>
</ul>

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

@ -88,7 +88,7 @@
<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="">Getting set up</a><ul>
<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>
@ -130,7 +130,7 @@
<div class="rst-content">
@ -162,7 +162,7 @@
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/r3prototyping.git">https://your_username&#64;bitbucket.org/R3-CEV/r3prototyping.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>
@ -260,4 +260,4 @@ found at something like</p>
</body>
</html>
</html>

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

@ -125,7 +125,7 @@
<div class="rst-content">

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

@ -87,7 +87,7 @@
<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-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>
@ -130,7 +130,7 @@
<div class="rst-content">
@ -202,6 +202,8 @@ party and deposit reference.</p>
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><code class="docutils literal"><span class="pre">InterestRateSwap</span></code> implements a vanilla OTC same currency bilateral fixed / floating leg swap. For further details,
see <a class="reference internal" href="irs.html"><span class="doc">The Interest Rate Swap Contract</span></a></p>
<p>Each contract comes with unit tests.</p>
</div>
<div class="section" id="kotlin">

292
docs/build/html/irs.html vendored Normal file
View File

@ -0,0 +1,292 @@
<!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>The Interest Rate Swap Contract &mdash; 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"/>
<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>
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
<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>
<li class="toctree-l1"><a class="reference internal" href="running-the-trading-demo.html">Running the trading demo</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</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> &raquo;</li>
<li>The Interest Rate Swap Contract</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/irs.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="the-interest-rate-swap-contract">
<h1>The Interest Rate Swap Contract<a class="headerlink" href="#the-interest-rate-swap-contract" title="Permalink to this headline"></a></h1>
<p>The Interest Rate Swap (IRS) Contract (source: IRS.kt, IRSUtils.kt, IRSExport.kt) is a bilateral contract to implement a
vanilla fixed / floating same currency IRS.</p>
<p>In general, an IRS allows two counterparties to modify their exposure from changes in the underlying interest rate. They
are often used as a hedging instrument, convert a fixed rate loan to a floating rate loan, vice versa etc.</p>
<p>The IRS contract exists over a period of time (normally measurable in years). It starts on its value date
(although this is not the agreement date), and is considered to be no longer active after its maturity date. During that
time, there is an exchange of cash flows which are calculated by looking at the economics of each leg. These are based
upon an amount that is not actually exchanged but notionally used for the calculation (and is hence known as the notional
amount), and a rate that is either fixed at the creation of the swap (for the fixed leg), or based upon a reference rate
that is retrieved during the swap (for the floating leg). An example reference rate might be something such as &#8216;LIBOR 3M&#8217;.</p>
<p>The fixed leg has its rate computed and set in advance, where as the floating leg has a fixing process whereas the rate
for the next period is fixed with relation to a reference rate. Then, a calculation is performed such that the interest
due over that period multiplied by the notional is paid (normally at the end of the period). If these two legs have the
same payment date, then these flows can be offset against each other (in reality there are normally a number of these
swaps that are live between two counterparties, so that further netting is performed at counterparty level).</p>
<p>The fixed leg and floating leg do not have to have the same period frequency. In fact, conventional swaps do not have
the same period.</p>
<p>Currently, there is no notion of an actual payment or obligation being performed in the contract code we have written;
it merely represents that the payment needs to be made.</p>
<p>Consider the diagram below; the x-axis represents time and the y-axis the size of the leg payments (not to scale), from
the view of the floating leg receiver / fixed leg payer. The enumerated documents represent the versions of the IRS as
it progresses (note that, the first version exists before the value date), the dots on the &#8220;y=0&#8221; represent an interest
rate value becoming available and then the curved arrow indicates to which period the fixing applies.</p>
<img alt="_images/irs.png" src="_images/irs.png" />
<p>Two days (by convention, although this can be modified), before the value date (ie the start of the swap) in the red
period the reference rate is observed from an oracle and fixed in the instance at 1.1%. At the end of the accrual period,
there is an obligation from the floating leg payer of 1.1% * notional amount * days in the accrual period / 360.
(Also note that the result of &#8220;days in the accrual period / 360&#8221; is also known as the day count factor, although other
conventions are allowed and will be supported). This amount is then paid at a determined time at the end of the accrual period.</p>
<p>Again, two working days before the blue period, the rate is fixed (this time at 0.5% - however in reality, the rates
would not be so significantly different), and the same calculation is performed to evaluate the payment that will be due
at the end of this period.</p>
<p>This process continues until the swap reaches maturity and the final payments are calculated.</p>
<div class="section" id="creating-an-instance-and-lifecycle">
<h2>Creating an instance and lifecycle<a class="headerlink" href="#creating-an-instance-and-lifecycle" title="Permalink to this headline"></a></h2>
<p>There are two valid operations on an IRS. The first is to generate via the <code class="docutils literal"><span class="pre">Agree</span></code> command (signed by both parties)
and the second (and repeated operation) is <code class="docutils literal"><span class="pre">Fix</span></code> to apply a rate fixing.
To see the minimum dataset required for the creation of an IRS, refer to <code class="docutils literal"><span class="pre">IRSTests.kt</span></code> which has two examples in the
function <code class="docutils literal"><span class="pre">IRSTests.createDummyIRS()</span></code>. Implicitly, when the agree function is called, the floating leg and fixed
leg payment schedules are created (more details below) and can be queried.</p>
<p>Once an IRS hase been agreed, then the the only valid operation is to apply a fixing on one of the entries in the
<code class="docutils literal"><span class="pre">Calculation.floatingLegPaymentSchedule</span></code> map. Fixes do not have to be applied in order (although it does make most
sense to do them so).</p>
<p>Examples of applying fixings to rates can been seen in <code class="docutils literal"><span class="pre">IRSTests.generateIRSandFixSome()</span></code> which loops through the next
fixing date of an IRS that is created with the above example function and then applies a fixing of 0.052% to each floating
event.</p>
<p>Currently, there are no matured, termination or dispute operations.</p>
</div>
<div class="section" id="technical-details">
<h2>Technical Details<a class="headerlink" href="#technical-details" title="Permalink to this headline"></a></h2>
<p>The contract itself comprises of 4 data state classes, <code class="docutils literal"><span class="pre">FixedLeg</span></code>, <code class="docutils literal"><span class="pre">FloatingLeg</span></code>, <code class="docutils literal"><span class="pre">Common</span></code> and <code class="docutils literal"><span class="pre">Calculation</span></code>.
Recall that the platform model is strictly immutable. To further that, between states, the only class that is modified
is the <code class="docutils literal"><span class="pre">Calculation</span></code> class.</p>
<p>The <code class="docutils literal"><span class="pre">Common</span></code> data class contains all data that is general to the entire swap, e.g. data like trade identifier,
valuation date, etc.</p>
<p>The Fixed and Floating leg classes derive from a common base class <code class="docutils literal"><span class="pre">CommonLeg</span></code>. This is due to the simple reason that
they share a lot of common fields.</p>
<p>The <code class="docutils literal"><span class="pre">CommonLeg</span></code> class contains the notional amount, a payment frequency, the effective date (as well as an adjustment
option), a termination date (and optional adjustment), the day count basis for day factor calculation, the payment delay
and calendar for the payment as well as the accrual adjustment options.</p>
<p>The <code class="docutils literal"><span class="pre">FixedLeg</span></code> contains all the details for the <code class="docutils literal"><span class="pre">CommonLeg</span></code> as well as payer details, the rate the leg is fixed at
and the date roll convention (ie what to do if the calculated date lands on a bank holiday or weekend).</p>
<p>The <code class="docutils literal"><span class="pre">FloatingLeg</span></code> contains all the details for the CommonLeg and payer details, roll convention, the fixing roll
convention, which day of the month the reset is calculated, the frequency period of the fixing, the fixing calendar and
the details for the reference index (source and tenor).</p>
<p>The <code class="docutils literal"><span class="pre">Calculation</span></code> class contains an expression (that can be evaluated via the ledger using variables provided and also
any members of the contract) and two schedules - a <code class="docutils literal"><span class="pre">floatingLegPaymentSchedule</span></code> and a <code class="docutils literal"><span class="pre">fixedLegPaymentSchedule</span></code>.
The fixed leg schedule is obviously pre-ordained, however, during the lifetime of the swap, the floating leg schedule is
regenerated upon each fixing being presented.</p>
<p>For this reason, there are two helper functions on the floating leg. <code class="docutils literal"><span class="pre">Calculation.getFixing</span></code> returns the date of the
earliest unset fixing, and <code class="docutils literal"><span class="pre">Calculation.applyFixing</span></code> returns a new Calculation object with the revised fixing in place.
Note that both schedules are, for consistency, indexed by payment dates, but the fixing is (due to the convention of
taking place two days previously) not going to be on that date.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Payment events in the <code class="docutils literal"><span class="pre">floatingLegPaymentSchedule</span></code> that start as a <code class="docutils literal"><span class="pre">FloatingRatePaymentEvent</span></code> (which is a
representation of a payment for a rate that has not yet been finalised) are replaced in their entirety with an
equivalent <code class="docutils literal"><span class="pre">FixedRatePaymentEvent</span></code> (which is the same type that is on the <code class="docutils literal"><span class="pre">FixedLeg</span></code>).</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; 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>

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

@ -90,7 +90,7 @@
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What&#8217;s included?</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
<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-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>
@ -131,7 +131,7 @@
<div class="rst-content">
@ -211,7 +211,7 @@ unit tests to be fast, repeatable and you want to be able to insert your own cha
message sequence. This is what the manual mode is for. In this mode, all logic runs on the same thread (the thread
running the unit tests). You can create and use a node like this:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre>val (aliceAddr, aliceNode) = makeNode(inBackground = false)
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>val (aliceAddr, aliceNode) = makeNode(inBackground = false)
val (bobAddr, bobNode) = makeNode(false)
aliceNode.send(&quot;test.topic&quot;, aliceAddr, &quot;foo&quot;)

22
docs/build/html/node-administration.html vendored
View File

@ -92,7 +92,7 @@
<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>
<li class="toctree-l1"><a class="reference internal" href="running-the-trading-demo.html">Running the trading demo</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Node administration</a><ul>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Node administration</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#monitoring-your-node">Monitoring your node</a></li>
<li class="toctree-l2"><a class="reference internal" href="#uploading-and-downloading-attachments">Uploading and downloading attachments</a></li>
<li class="toctree-l2"><a class="reference internal" href="#uploading-interest-rate-fixes">Uploading interest rate fixes</a></li>
@ -131,7 +131,7 @@
<div class="rst-content">
@ -189,22 +189,22 @@ data to their service on a regular schedule.</li>
hash and they are public, in that they propagate through the network to wherever they are needed.</p>
<p>All attachments are zip files. Thus to upload a file to the ledger you must first wrap it into a zip (or jar) file. Then
you can upload it by running this command from a UNIX terminal:</p>
<div class="highlight-shell"><div class="highlight"><pre>curl -F <span class="nv">myfile</span><span class="o">=</span>@path/to/my/file.zip http://localhost:31338/upload/attachment
<div class="highlight-shell"><div class="highlight"><pre><span></span>curl -F <span class="nv">myfile</span><span class="o">=</span>@path/to/my/file.zip http://localhost:31338/upload/attachment
</pre></div>
</div>
<p>The attachment will be identified by the SHA-256 hash of the contents, which you can get by doing:</p>
<div class="highlight-shell"><div class="highlight"><pre>shasum -a <span class="m">256</span> file.zip
<div class="highlight-shell"><div class="highlight"><pre><span></span>shasum -a <span class="m">256</span> file.zip
</pre></div>
</div>
<p>on a Mac or by using <code class="docutils literal"><span class="pre">sha256sum</span></code> on Linux. Alternatively, the hash will be returned to you when you upload the
attachment.</p>
<p>An attachment may be downloaded by fetching:</p>
<div class="highlight-shell"><div class="highlight"><pre>http://localhost:31338/attachments/DECD098666B9657314870E192CED0C3519C2C9D395507A238338F8D003929DE9
<div class="highlight-shell"><div class="highlight"><pre><span></span>http://localhost:31338/attachments/DECD098666B9657314870E192CED0C3519C2C9D395507A238338F8D003929DE9
</pre></div>
</div>
<p>where DECD... is of course replaced with the hash identifier of your own attachment. Because attachments are always
containers, you can also fetch a specific file within the attachment by appending its path, like this:</p>
<div class="highlight-shell"><div class="highlight"><pre>http://localhost:31338/attachments/DECD098666B9657314870E192CED0C3519C2C9D395507A238338F8D003929DE9/path/within/zip.txt
<div class="highlight-shell"><div class="highlight"><pre><span></span>http://localhost:31338/attachments/DECD098666B9657314870E192CED0C3519C2C9D395507A238338F8D003929DE9/path/within/zip.txt
</pre></div>
</div>
</div>
@ -213,12 +213,12 @@ containers, you can also fetch a specific file within the attachment by appendin
<p>If you would like to operate an interest rate fixing service (oracle), you can upload fix data by uploading data in
a simple text format to the <code class="docutils literal"><span class="pre">/upload/interest-rates</span></code> path on the web server.</p>
<p>The file looks like this:</p>
<div class="highlight-kotlin"><div class="highlight"><pre># Some pretend noddy rate fixes, for the interest rate oracles.
<div class="highlight-kotlin"><div class="highlight"><pre><span></span># Some pretend noddy rate fixes, for the interest rate oracles.
LIBOR 2016-03-16 30 = 0.678
LIBOR 2016-03-16 60 = 0.655
EURIBOR 2016-03-15 30 = 0.123
EURIBOR 2016-03-15 60 = 0.111
LIBOR 2016-03-16 1M = 0.678
LIBOR 2016-03-16 2M = 0.655
EURIBOR 2016-03-15 1M = 0.123
EURIBOR 2016-03-15 2M = 0.111
</pre></div>
</div>
<p>The columns are:</p>

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

Binary file not shown.

14
docs/build/html/oracles.html vendored
View File

@ -98,7 +98,7 @@
<ul class="current">
<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 current"><a class="current reference internal" href="">Writing oracle services</a><ul>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Writing oracle services</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="#the-two-basic-approaches">The two basic approaches</a></li>
<li class="toctree-l2"><a class="reference internal" href="#asserting-continuously-varying-data-that-is-publicly-known">Asserting continuously varying data that is publicly known</a></li>
@ -133,7 +133,7 @@
<div class="rst-content">
@ -239,7 +239,7 @@ value.</p>
clocks at the US Naval Observatory. This time feed is extremely accurate and available globally for free.</p>
</div>
<p>We fix it by including explicit tolerances in the command, which is defined like this:</p>
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">data</span> <span class="k">class</span> <span class="nc">TimestampCommand</span><span class="p">(</span><span class="k">val</span> <span class="py">after</span><span class="p">:</span> <span class="n">Instant</span><span class="p">?,</span> <span class="k">val</span> <span class="py">before</span><span class="p">:</span> <span class="n">Instant</span><span class="p">?)</span> <span class="p">:</span> <span class="n">CommandData</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">data</span> <span class="k">class</span> <span class="nc">TimestampCommand</span><span class="p">(</span><span class="k">val</span> <span class="py">after</span><span class="p">:</span> <span class="n">Instant</span><span class="p">?,</span> <span class="k">val</span> <span class="py">before</span><span class="p">:</span> <span class="n">Instant</span><span class="p">?)</span> <span class="p">:</span> <span class="n">CommandData</span>
<span class="n">init</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">after</span> <span class="p">==</span> <span class="k">null</span> <span class="p">&amp;&amp;</span> <span class="n">before</span> <span class="p">==</span> <span class="k">null</span><span class="p">)</span>
<span class="k">throw</span> <span class="n">IllegalArgumentException</span><span class="p">(</span><span class="s">&quot;At least one of before/after must be specified&quot;</span><span class="p">)</span>
@ -283,11 +283,11 @@ would be conclusive evidence of intent to disobey the rules of the service (<em>
where parties are legally identifiable, usage of such a contract would by itself be sufficient to trigger some sort of
punishment.</p>
<p>Here is an extract from the <code class="docutils literal"><span class="pre">NodeService.Oracle</span></code> class and supporting types:</p>
<div class="highlight-kotlin"><div class="highlight"><pre><span class="cm">/** A [FixOf] identifies the question side of a fix: what day, tenor and type of fix (&quot;LIBOR&quot;, &quot;EURIBOR&quot; etc) */</span>
<span class="n">data</span> <span class="k">class</span> <span class="nc">FixOf</span><span class="p">(</span><span class="k">val</span> <span class="py">name</span><span class="p">:</span> <span class="n">String</span><span class="p">,</span> <span class="k">val</span> <span class="py">forDay</span><span class="p">:</span> <span class="n">LocalDate</span><span class="p">,</span> <span class="k">val</span> <span class="py">ofTenor</span><span class="p">:</span> <span class="n">Duration</span><span class="p">)</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="cm">/** A [FixOf] identifies the question side of a fix: what day, tenor and type of fix (&quot;LIBOR&quot;, &quot;EURIBOR&quot; etc) */</span>
<span class="k">data</span> <span class="k">class</span> <span class="nc">FixOf</span><span class="p">(</span><span class="k">val</span> <span class="py">name</span><span class="p">:</span> <span class="n">String</span><span class="p">,</span> <span class="k">val</span> <span class="py">forDay</span><span class="p">:</span> <span class="n">LocalDate</span><span class="p">,</span> <span class="k">val</span> <span class="py">ofTenor</span><span class="p">:</span> <span class="n">Duration</span><span class="p">)</span>
<span class="cm">/** A [Fix] represents a named interest rate, on a given day, for a given duration. It can be embedded in a tx. */</span>
<span class="n">data</span> <span class="k">class</span> <span class="nc">Fix</span><span class="p">(</span><span class="k">val</span> <span class="py">of</span><span class="p">:</span> <span class="n">FixOf</span><span class="p">,</span> <span class="k">val</span> <span class="py">value</span><span class="p">:</span> <span class="n">BigDecimal</span><span class="p">)</span> <span class="p">:</span> <span class="n">CommandData</span>
<span class="k">data</span> <span class="k">class</span> <span class="nc">Fix</span><span class="p">(</span><span class="k">val</span> <span class="py">of</span><span class="p">:</span> <span class="n">FixOf</span><span class="p">,</span> <span class="k">val</span> <span class="py">value</span><span class="p">:</span> <span class="n">BigDecimal</span><span class="p">)</span> <span class="p">:</span> <span class="n">CommandData</span>
<span class="k">class</span> <span class="nc">Oracle</span> <span class="p">{</span>
<span class="k">fun</span> <span class="nf">query</span><span class="p">(</span><span class="n">queries</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">FixOf</span><span class="p">&gt;):</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">Fix</span><span class="p">&gt;</span>
@ -305,7 +305,7 @@ requested via <code class="docutils literal"><span class="pre">query</span></cod
<ol class="arabic simple">
<li>Defining a high level oracle class, that exposes the basic API operations.</li>
<li>Defining a lower level service class, that binds network messages to the API.</li>
<li>Defining a protocol using the <a class="reference internal" href="protocol-state-machines.html"><em>Protocol state machines</em></a> framework to make it easy for a client to interact
<li>Defining a protocol using the <a class="reference internal" href="protocol-state-machines.html"><span class="doc">Protocol state machines</span></a> framework to make it easy for a client to interact
with the oracle.</li>
</ol>
<p>An example of how to do this can be found in the <code class="docutils literal"><span class="pre">NodeInterestRates.Oracle</span></code>, <code class="docutils literal"><span class="pre">NodeInterestRates.Service</span></code> and

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

@ -97,7 +97,7 @@
<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-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>
<li class="toctree-l2"><a class="reference internal" href="#a-two-party-trading-protocol">A two party trading protocol</a></li>
@ -136,7 +136,7 @@
<div class="rst-content">
@ -243,7 +243,7 @@ represents an atomic asset swap.</p>
of the protocol, and two classes that will contain the protocol definition. We also pick what data will be used by
each side.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">object</span> <span class="nc">TwoPartyTradeProtocol</span> <span class="p">{</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">object</span> <span class="nc">TwoPartyTradeProtocol</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">TRADE_TOPIC</span> <span class="p">=</span> <span class="s">&quot;platform.trade&quot;</span>
<span class="k">fun</span> <span class="nf">runSeller</span><span class="p">(</span><span class="n">smm</span><span class="p">:</span> <span class="n">StateMachineManager</span><span class="p">,</span> <span class="n">timestampingAuthority</span><span class="p">:</span> <span class="n">LegallyIdentifiableNode</span><span class="p">,</span>
@ -317,7 +317,7 @@ the first parameter, this is just a standard JDK logging identifier string, and
<p>Going through the data needed to become a seller, we have:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">timestampingAuthority:</span> <span class="pre">LegallyIdentifiableNode</span></code> - a reference to a node on the P2P network that acts as a trusted
timestamper. The use of timestamping is described in <a class="reference internal" href="data-model.html"><em>Data model</em></a>.</li>
timestamper. The use of timestamping is described in <a class="reference internal" href="data-model.html"><span class="doc">Data model</span></a>.</li>
<li><code class="docutils literal"><span class="pre">otherSide:</span> <span class="pre">SingleMessageRecipient</span></code> - the network address of the node with which you are trading.</li>
<li><code class="docutils literal"><span class="pre">assetToSell:</span> <span class="pre">StateAndRef&lt;OwnableState&gt;</span></code> - a pointer to the ledger entry that represents the thing being sold.</li>
<li><code class="docutils literal"><span class="pre">price:</span> <span class="pre">Amount</span></code> - the agreed on price that the asset is being sold for.</li>
@ -377,7 +377,7 @@ unit tests to see how it&#8217;s done.</p>
<p>Let&#8217;s implement the <code class="docutils literal"><span class="pre">Seller.call</span></code> method. This will be invoked by the platform when the protocol is started by the
<code class="docutils literal"><span class="pre">StateMachineManager</span></code>.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">val</span> <span class="py">partialTX</span><span class="p">:</span> <span class="n">SignedTransaction</span> <span class="p">=</span> <span class="n">receiveAndCheckProposedTransaction</span><span class="p">()</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">val</span> <span class="py">partialTX</span><span class="p">:</span> <span class="n">SignedTransaction</span> <span class="p">=</span> <span class="n">receiveAndCheckProposedTransaction</span><span class="p">()</span>
<span class="c1">// These two steps could be done in parallel, in theory. Our framework doesn&#39;t support that yet though.</span>
<span class="k">val</span> <span class="py">ourSignature</span> <span class="p">=</span> <span class="n">signWithOurKey</span><span class="p">(</span><span class="n">partialTX</span><span class="p">)</span>
@ -403,7 +403,7 @@ This is where we can see the benefits of using continuations/fibers as a program
</div>
<p>Let&#8217;s fill out the <code class="docutils literal"><span class="pre">receiveAndCheckProposedTransaction()</span></code> method.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">@Suspendable</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Suspendable</span>
<span class="k">open</span> <span class="k">fun</span> <span class="nf">receiveAndCheckProposedTransaction</span><span class="p">():</span> <span class="n">SignedTransaction</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">sessionID</span> <span class="p">=</span> <span class="n">random63BitValue</span><span class="p">()</span>
@ -472,7 +472,7 @@ other ways. It doesn&#8217;t add any functionality, but acts as a reminder to &#
simply involves checking the signatures on it. Then we go ahead and check all the dependencies of this partial
transaction for validity. Here&#8217;s the code to do that:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">@Suspendable</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Suspendable</span>
<span class="k">private</span> <span class="k">fun</span> <span class="nf">checkDependencies</span><span class="p">(</span><span class="n">stx</span><span class="p">:</span> <span class="n">SignedTransaction</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Download and check all the transactions that this transaction depends on, but do not check this</span>
<span class="c1">// transaction itself.</span>
@ -499,7 +499,7 @@ leak will come later.</p>
well (but having handled the fact that some signatures are missing ourselves).</p>
<p>Here&#8217;s the rest of the code:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">open</span> <span class="k">fun</span> <span class="nf">signWithOurKey</span><span class="p">(</span><span class="n">partialTX</span><span class="p">:</span> <span class="n">SignedTransaction</span><span class="p">)</span> <span class="p">=</span> <span class="n">myKeyPair</span><span class="p">.</span><span class="n">signWithECDSA</span><span class="p">(</span><span class="n">partialTX</span><span class="p">.</span><span class="n">txBits</span><span class="p">)</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">open</span> <span class="k">fun</span> <span class="nf">signWithOurKey</span><span class="p">(</span><span class="n">partialTX</span><span class="p">:</span> <span class="n">SignedTransaction</span><span class="p">)</span> <span class="p">=</span> <span class="n">myKeyPair</span><span class="p">.</span><span class="n">signWithECDSA</span><span class="p">(</span><span class="n">partialTX</span><span class="p">.</span><span class="n">txBits</span><span class="p">)</span>
<span class="n">@Suspendable</span>
<span class="k">open</span> <span class="k">fun</span> <span class="nf">sendSignatures</span><span class="p">(</span><span class="n">partialTX</span><span class="p">:</span> <span class="n">SignedTransaction</span><span class="p">,</span> <span class="n">ourSignature</span><span class="p">:</span> <span class="n">DigitalSignature</span><span class="p">.</span><span class="n">WithKey</span><span class="p">,</span>
@ -531,7 +531,7 @@ future version of the code.</p>
<h2>Implementing the buyer<a class="headerlink" href="#implementing-the-buyer" title="Permalink to this headline"></a></h2>
<p>OK, let&#8217;s do the same for the buyer side:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre>@Suspendable
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>@Suspendable
override fun call(): SignedTransaction {
val tradeRequest = receiveAndValidateTradeRequest()
val (ptx, cashSigningPubKeys) = assembleSharedTX(tradeRequest)

10
docs/build/html/running-the-trading-demo.html vendored
View File

@ -91,7 +91,7 @@
<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="data-model.html">Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Running the trading demo</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Running the trading demo</a></li>
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
</ul>
<p class="caption"><span class="caption-text">Tutorials</span></p>
@ -126,7 +126,7 @@
<div class="rst-content">
@ -151,17 +151,17 @@
<div class="section" id="running-the-trading-demo">
<h1>Running the trading demo<a class="headerlink" href="#running-the-trading-demo" title="Permalink to this headline"></a></h1>
<p>The repository contains a program that implements a demo of two nodes running the two-party trading protocol, which you
can learn about in <a class="reference internal" href="protocol-state-machines.html"><em>Protocol state machines</em></a>.</p>
can learn about in <a class="reference internal" href="protocol-state-machines.html"><span class="doc">Protocol state machines</span></a>.</p>
<p>The node has only currently been tested on MacOS X and Ubuntu Linux. If you have success on other platforms, please
let us know.</p>
<p>Now, open two terminals, and in the first run::</p>
<div class="highlight-kotlin"><div class="highlight"><pre><span class="p">./</span><span class="n">scripts</span><span class="p">/</span><span class="n">trader</span><span class="p">-</span><span class="n">demo</span><span class="p">.</span><span class="n">sh</span> <span class="n">buyer</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="p">./</span><span class="n">scripts</span><span class="p">/</span><span class="n">trader</span><span class="p">-</span><span class="n">demo</span><span class="p">.</span><span class="n">sh</span> <span class="n">buyer</span>
</pre></div>
</div>
<p>It will compile things, if necessary, then create a directory named &#8220;buyer&#8221; with a bunch of files inside and start
the node. You should see it waiting for a trade to begin.</p>
<p>In the second terminal, run:</p>
<div class="highlight-kotlin"><div class="highlight"><pre><span class="p">./</span><span class="n">scripts</span><span class="p">/</span><span class="n">trader</span><span class="p">-</span><span class="n">demo</span><span class="p">.</span><span class="n">sh</span> <span class="n">seller</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="p">./</span><span class="n">scripts</span><span class="p">/</span><span class="n">trader</span><span class="p">-</span><span class="n">demo</span><span class="p">.</span><span class="n">sh</span> <span class="n">seller</span>
</pre></div>
</div>
<p>You should see some log lines scroll past, and within a few seconds the messages &#8220;Purchase complete - we are a

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

File diff suppressed because one or more lines are too long

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

@ -96,7 +96,7 @@
</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-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>
@ -137,7 +137,7 @@
<div class="rst-content">
@ -171,7 +171,7 @@ for how Kotlin syntax works.</p>
codebase, as dynamic loading of contract code is not yet implemented. Therefore, we start by creating a file named
either <code class="docutils literal"><span class="pre">CommercialPaper.kt</span></code> or <code class="docutils literal"><span class="pre">CommercialPaper.java</span></code> in the src/contracts directory with the following contents:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CommercialPaper</span> <span class="p">:</span> <span class="n">Contract</span> <span class="p">{</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">CommercialPaper</span> <span class="p">:</span> <span class="n">Contract</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">val</span> <span class="py">legalContractReference</span><span class="p">:</span> <span class="n">SecureHash</span> <span class="p">=</span> <span class="n">SecureHash</span><span class="p">.</span><span class="n">sha256</span><span class="p">(</span><span class="s">&quot;https://en.wikipedia.org/wiki/Commercial_paper&quot;</span><span class="p">);</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">verify</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForVerification</span><span class="p">)</span> <span class="p">{</span>
@ -180,7 +180,7 @@ either <code class="docutils literal"><span class="pre">CommercialPaper.kt</span
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-java"><div class="highlight"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Cash</span> <span class="kd">implements</span> <span class="n">Contract</span> <span class="o">{</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Cash</span> <span class="kd">implements</span> <span class="n">Contract</span> <span class="o">{</span>
<span class="nd">@Override</span>
<span class="kd">public</span> <span class="n">SecureHash</span> <span class="nf">getLegalContractReference</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">SecureHash</span><span class="o">.</span><span class="na">Companion</span><span class="o">.</span><span class="na">sha256</span><span class="o">(</span><span class="s">&quot;https://en.wikipedia.org/wiki/Commercial_paper&quot;</span><span class="o">);</span>
@ -209,7 +209,7 @@ piece of issued paper.</p>
<h2>States<a class="headerlink" href="#states" title="Permalink to this headline"></a></h2>
<p>A state is a class that stores data that is checked by the contract.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">data</span> <span class="k">class</span> <span class="nc">State</span><span class="p">(</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">data</span> <span class="k">class</span> <span class="nc">State</span><span class="p">(</span>
<span class="k">val</span> <span class="py">issuance</span><span class="p">:</span> <span class="n">InstitutionReference</span><span class="p">,</span>
<span class="k">val</span> <span class="py">owner</span><span class="p">:</span> <span class="n">PublicKey</span><span class="p">,</span>
<span class="k">val</span> <span class="py">faceValue</span><span class="p">:</span> <span class="n">Amount</span><span class="p">,</span>
@ -221,7 +221,7 @@ piece of issued paper.</p>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-java"><div class="highlight"><pre><span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">State</span> <span class="kd">implements</span> <span class="n">ContractState</span><span class="o">,</span> <span class="n">SerializeableWithKryo</span> <span class="o">{</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">State</span> <span class="kd">implements</span> <span class="n">ContractState</span><span class="o">,</span> <span class="n">SerializeableWithKryo</span> <span class="o">{</span>
<span class="kd">private</span> <span class="n">InstitutionReference</span> <span class="n">issuance</span><span class="o">;</span>
<span class="kd">private</span> <span class="n">PublicKey</span> <span class="n">owner</span><span class="o">;</span>
<span class="kd">private</span> <span class="n">Amount</span> <span class="n">faceValue</span><span class="o">;</span>
@ -323,14 +323,14 @@ checked, so from the contract code&#8217;s perspective, a command is simply a da
public keys. Each key had a signature proving that the corresponding private key was used to sign.</p>
<p>Let&#8217;s define a few commands now:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">interface</span> <span class="n">Commands</span> <span class="p">:</span> <span class="n">Command</span> <span class="p">{</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">interface</span> <span class="nc">Commands</span> <span class="p">:</span> <span class="n">Command</span> <span class="p">{</span>
<span class="k">object</span> <span class="nc">Move</span> <span class="p">:</span> <span class="n">Commands</span>
<span class="k">object</span> <span class="nc">Redeem</span> <span class="p">:</span> <span class="n">Commands</span>
<span class="k">object</span> <span class="nc">Issue</span> <span class="p">:</span> <span class="n">Commands</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-java"><div class="highlight"><pre><span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Commands</span> <span class="kd">implements</span> <span class="n">core</span><span class="o">.</span><span class="na">Command</span> <span class="o">{</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Commands</span> <span class="kd">implements</span> <span class="n">core</span><span class="o">.</span><span class="na">Command</span> <span class="o">{</span>
<span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">Move</span> <span class="kd">extends</span> <span class="n">Commands</span> <span class="o">{</span>
<span class="nd">@Override</span>
<span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">equals</span><span class="o">(</span><span class="n">Object</span> <span class="n">obj</span><span class="o">)</span> <span class="o">{</span>
@ -369,13 +369,13 @@ by taking the code references inside each state. Each contract is run only once.
2 cash states and 1 commercial paper state as input, and has as output 1 cash state and 1 commercial paper state, will
run two contracts one time each: Cash and CommercialPaper.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">override</span> <span class="k">fun</span> <span class="nf">verify</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForVerification</span><span class="p">)</span> <span class="p">{</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">override</span> <span class="k">fun</span> <span class="nf">verify</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionForVerification</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Group by everything except owner: any modification to the CP at all is considered changing it fundamentally.</span>
<span class="k">val</span> <span class="py">groups</span> <span class="p">=</span> <span class="n">tx</span><span class="p">.</span><span class="n">groupStates</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&gt;()</span> <span class="p">{</span> <span class="n">it</span><span class="p">.</span><span class="n">withoutOwner</span><span class="p">()</span> <span class="p">}</span>
<span class="k">val</span> <span class="py">command</span> <span class="p">=</span> <span class="n">tx</span><span class="p">.</span><span class="n">commands</span><span class="p">.</span><span class="n">requireSingleCommand</span><span class="p">&lt;</span><span class="n">CommercialPaper</span><span class="p">.</span><span class="n">Commands</span><span class="p">&gt;()</span>
</pre></div>
</div>
<div class="highlight-java"><div class="highlight"><pre><span class="nd">@Override</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="nd">@Override</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">verify</span><span class="o">(</span><span class="nd">@NotNull</span> <span class="n">TransactionForVerification</span> <span class="n">tx</span><span class="o">)</span> <span class="o">{</span>
<span class="n">List</span><span class="o">&lt;</span><span class="n">InOutGroup</span><span class="o">&lt;</span><span class="n">State</span><span class="o">&gt;&gt;</span> <span class="n">groups</span> <span class="o">=</span> <span class="n">tx</span><span class="o">.</span><span class="na">groupStates</span><span class="o">(</span><span class="n">State</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">State</span><span class="o">::</span><span class="n">withoutOwner</span><span class="o">);</span>
<span class="n">AuthenticatedObject</span><span class="o">&lt;</span><span class="n">Command</span><span class="o">&gt;</span> <span class="n">cmd</span> <span class="o">=</span> <span class="n">requireSingleCommand</span><span class="o">(</span><span class="n">tx</span><span class="o">.</span><span class="na">getCommands</span><span class="o">(),</span> <span class="n">Commands</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
@ -435,7 +435,7 @@ trade many different pieces of commercial paper in a single atomic step.</p>
<p>After extracting the command and the groups, we then iterate over each group and verify it meets the required business
logic.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">val</span> <span class="py">time</span> <span class="p">=</span> <span class="n">tx</span><span class="p">.</span><span class="n">time</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">val</span> <span class="py">time</span> <span class="p">=</span> <span class="n">tx</span><span class="p">.</span><span class="n">time</span>
<span class="k">for</span> <span class="p">(</span><span class="n">group</span> <span class="k">in</span> <span class="n">groups</span><span class="p">)</span> <span class="p">{</span>
<span class="k">when</span> <span class="p">(</span><span class="n">command</span><span class="p">.</span><span class="n">value</span><span class="p">)</span> <span class="p">{</span>
<span class="k">is</span> <span class="n">Commands</span><span class="p">.</span><span class="n">Move</span> <span class="p">-&gt;</span> <span class="p">{</span>
@ -478,7 +478,7 @@ logic.</p>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-java"><div class="highlight"><pre><span class="n">Instant</span> <span class="n">time</span> <span class="o">=</span> <span class="n">tx</span><span class="o">.</span><span class="na">getTime</span><span class="o">();</span> <span class="c1">// Can be null/missing.</span>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="n">Instant</span> <span class="n">time</span> <span class="o">=</span> <span class="n">tx</span><span class="o">.</span><span class="na">getTime</span><span class="o">();</span> <span class="c1">// Can be null/missing.</span>
<span class="k">for</span> <span class="o">(</span><span class="n">InOutGroup</span><span class="o">&lt;</span><span class="n">State</span><span class="o">&gt;</span> <span class="n">group</span> <span class="o">:</span> <span class="n">groups</span><span class="o">)</span> <span class="o">{</span>
<span class="n">List</span><span class="o">&lt;</span><span class="n">State</span><span class="o">&gt;</span> <span class="n">inputs</span> <span class="o">=</span> <span class="n">group</span><span class="o">.</span><span class="na">getInputs</span><span class="o">();</span>
<span class="n">List</span><span class="o">&lt;</span><span class="n">State</span><span class="o">&gt;</span> <span class="n">outputs</span> <span class="o">=</span> <span class="n">group</span><span class="o">.</span><span class="na">getOutputs</span><span class="o">();</span>
@ -582,7 +582,7 @@ is a Kotlin DSL, and therefore this section will not show Java equivalent code (
benefit from the DSL and would write them by hand).</p>
<p>We start by defining a new test class, with a basic CP state:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CommercialPaperTests</span> <span class="p">{</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">CommercialPaperTests</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">PAPER_1</span> <span class="p">=</span> <span class="n">CommercialPaper</span><span class="p">.</span><span class="n">State</span><span class="p">(</span>
<span class="n">issuance</span> <span class="p">=</span> <span class="n">InstitutionReference</span><span class="p">(</span><span class="n">MEGA_CORP</span><span class="p">,</span> <span class="n">OpaqueBytes</span><span class="p">.</span><span class="n">of</span><span class="p">(</span><span class="m">123</span><span class="p">)),</span>
<span class="n">owner</span> <span class="p">=</span> <span class="n">MEGA_CORP_KEY</span><span class="p">,</span>
@ -644,7 +644,7 @@ invoke all the involved contracts.</p>
Java, it&#8217;s actually not, and so you can embed arbitrary code anywhere inside any of these blocks.</p>
<p>Let&#8217;s set up a full trade and ensure it works:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre> <span class="c1">// Generate a trade lifecycle with various parameters.</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span> <span class="c1">// Generate a trade lifecycle with various parameters.</span>
<span class="k">private</span> <span class="k">fun</span> <span class="nf">trade</span><span class="p">(</span><span class="n">redemptionTime</span><span class="p">:</span> <span class="n">Instant</span> <span class="p">=</span> <span class="n">TEST_TX_TIME</span> <span class="p">+</span> <span class="m">8.</span><span class="n">days</span><span class="p">,</span>
<span class="n">aliceGetsBack</span><span class="p">:</span> <span class="n">Amount</span> <span class="p">=</span> <span class="m">1000.</span><span class="n">DOLLARS</span><span class="p">,</span>
<span class="n">destroyPaperAtRedemption</span><span class="p">:</span> <span class="n">Boolean</span> <span class="p">=</span> <span class="k">true</span><span class="p">):</span> <span class="n">TransactionGroupForTest</span> <span class="p">{</span>
@ -709,11 +709,11 @@ then, the <code class="docutils literal"><span class="pre">input</span></code> m
<li>The <code class="docutils literal"><span class="pre">transaction</span></code> function can also be given a time, to override the default timestamp on a transaction.</li>
</ul>
<p>The <code class="docutils literal"><span class="pre">trade</span></code> function is not itself a unit test. Instead it builds up a trade/transaction group, with some slight
differences depending on the parameters provided (Kotlin allows parameters to have default valus). Then it returns
differences depending on the parameters provided (Kotlin allows parameters to have default values). Then it returns
it, unexecuted.</p>
<p>We use it like this:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">@Test</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Test</span>
<span class="k">fun</span> <span class="nf">ok</span><span class="p">()</span> <span class="p">{</span>
<span class="n">trade</span><span class="p">().</span><span class="n">verify</span><span class="p">()</span>
<span class="p">}</span>
@ -748,7 +748,7 @@ like a module), the basic concept is the same: preparation of a transaction usin
<p>For our commercial paper contract however, the things that can be done with it are quite simple. Let&#8217;s start with
a method to wrap up the issuance process:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">fun</span> <span class="nf">generateIssue</span><span class="p">(</span><span class="n">issuance</span><span class="p">:</span> <span class="n">InstitutionReference</span><span class="p">,</span> <span class="n">faceValue</span><span class="p">:</span> <span class="n">Amount</span><span class="p">,</span> <span class="n">maturityDate</span><span class="p">:</span> <span class="n">Instant</span><span class="p">):</span> <span class="n">TransactionBuilder</span> <span class="p">{</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">fun</span> <span class="nf">generateIssue</span><span class="p">(</span><span class="n">issuance</span><span class="p">:</span> <span class="n">InstitutionReference</span><span class="p">,</span> <span class="n">faceValue</span><span class="p">:</span> <span class="n">Amount</span><span class="p">,</span> <span class="n">maturityDate</span><span class="p">:</span> <span class="n">Instant</span><span class="p">):</span> <span class="n">TransactionBuilder</span> <span class="p">{</span>
<span class="k">val</span> <span class="py">state</span> <span class="p">=</span> <span class="n">State</span><span class="p">(</span><span class="n">issuance</span><span class="p">,</span> <span class="n">issuance</span><span class="p">.</span><span class="n">party</span><span class="p">.</span><span class="n">owningKey</span><span class="p">,</span> <span class="n">faceValue</span><span class="p">,</span> <span class="n">maturityDate</span><span class="p">)</span>
<span class="k">return</span> <span class="n">TransactionBuilder</span><span class="p">(</span><span class="n">state</span><span class="p">,</span> <span class="n">WireCommand</span><span class="p">(</span><span class="n">Commands</span><span class="p">.</span><span class="n">Issue</span><span class="p">,</span> <span class="n">issuance</span><span class="p">.</span><span class="n">party</span><span class="p">.</span><span class="n">owningKey</span><span class="p">))</span>
<span class="p">}</span>
@ -779,7 +779,7 @@ any <code class="docutils literal"><span class="pre">ContractStateRef</span></co
for you.</p>
<p>What about moving the paper, i.e. reassigning ownership to someone else?</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="k">fun</span> <span class="nf">generateMove</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionBuilder</span><span class="p">,</span> <span class="n">paper</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&gt;,</span> <span class="n">newOwner</span><span class="p">:</span> <span class="n">PublicKey</span><span class="p">)</span> <span class="p">{</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="k">fun</span> <span class="nf">generateMove</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionBuilder</span><span class="p">,</span> <span class="n">paper</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&gt;,</span> <span class="n">newOwner</span><span class="p">:</span> <span class="n">PublicKey</span><span class="p">)</span> <span class="p">{</span>
<span class="n">tx</span><span class="p">.</span><span class="n">addInputState</span><span class="p">(</span><span class="n">paper</span><span class="p">.</span><span class="n">ref</span><span class="p">)</span>
<span class="n">tx</span><span class="p">.</span><span class="n">addOutputState</span><span class="p">(</span><span class="n">paper</span><span class="p">.</span><span class="n">state</span><span class="p">.</span><span class="n">copy</span><span class="p">(</span><span class="n">owner</span> <span class="p">=</span> <span class="n">newOwner</span><span class="p">))</span>
<span class="n">tx</span><span class="p">.</span><span class="n">addArg</span><span class="p">(</span><span class="n">WireCommand</span><span class="p">(</span><span class="n">Commands</span><span class="p">.</span><span class="n">Move</span><span class="p">,</span> <span class="n">paper</span><span class="p">.</span><span class="n">state</span><span class="p">.</span><span class="n">owner</span><span class="p">))</span>
@ -796,7 +796,7 @@ a small object that has a (copy of) a state object, and also the (txhash, index)
state on the ledger.</p>
<p>Finally, we can do redemption.</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">@Throws</span><span class="p">(</span><span class="n">InsufficientBalanceException</span><span class="o">::</span><span class="k">class</span><span class="p">)</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">@Throws</span><span class="p">(</span><span class="n">InsufficientBalanceException</span><span class="o">::</span><span class="k">class</span><span class="p">)</span>
<span class="k">fun</span> <span class="nf">generateRedeem</span><span class="p">(</span><span class="n">tx</span><span class="p">:</span> <span class="n">TransactionBuilder</span><span class="p">,</span> <span class="n">paper</span><span class="p">:</span> <span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">State</span><span class="p">&gt;,</span> <span class="n">wallet</span><span class="p">:</span> <span class="n">List</span><span class="p">&lt;</span><span class="n">StateAndRef</span><span class="p">&lt;</span><span class="n">Cash</span><span class="p">.</span><span class="n">State</span><span class="p">&gt;&gt;)</span> <span class="p">{</span>
<span class="c1">// Add the cash movement using the states in our wallet.</span>
<span class="n">Cash</span><span class="p">().</span><span class="n">generateSpend</span><span class="p">(</span><span class="n">tx</span><span class="p">,</span> <span class="n">paper</span><span class="p">.</span><span class="n">state</span><span class="p">.</span><span class="n">faceValue</span><span class="p">,</span> <span class="n">paper</span><span class="p">.</span><span class="n">state</span><span class="p">.</span><span class="n">owner</span><span class="p">,</span> <span class="n">wallet</span><span class="p">)</span>
@ -826,7 +826,7 @@ is recognised by the network. The most important next step is for the participat
signature inside the <code class="docutils literal"><span class="pre">TransactionBuilder</span></code>. Once all parties have signed, you can call <code class="docutils literal"><span class="pre">TransactionBuilder.toSignedTransaction()</span></code>
to get a <code class="docutils literal"><span class="pre">SignedTransaction</span></code> object. This is an immutable form of the transaction that&#8217;s ready for <em>timestamping</em>,
which can be done using a <code class="docutils literal"><span class="pre">TimestamperClient</span></code>. To learn more about that, please refer to the
<a class="reference internal" href="protocol-state-machines.html"><em>Protocol state machines</em></a> document.</p>
<a class="reference internal" href="protocol-state-machines.html"><span class="doc">Protocol state machines</span></a> document.</p>
<p>You can see how transactions flow through the different stages of construction by examining the commercial paper
unit tests.</p>
</div>

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

@ -102,7 +102,7 @@
</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 current"><a class="current reference internal" href="#">Using the visualiser</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
</ul>
@ -126,7 +126,7 @@
<div class="rst-content">
@ -159,7 +159,7 @@ early and the diagrams it produces are not especially beautiful. The intention i
<p>Briefly, define a set of transactions in a group using the same DSL that is used in the unit tests. Here&#8217;s an example
of a trade lifecycle using the commercial paper contract</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre>val group: TransactionGroupDSL&lt;ContractState&gt; = transactionGroupFor() {
<div class="highlight-kotlin"><div class="highlight"><pre><span></span>val group: TransactionGroupDSL&lt;ContractState&gt; = transactionGroupFor() {
roots {
transaction(900.DOLLARS.CASH `owned by` ALICE label &quot;alice&#39;s $900&quot;)
transaction(someProfits.CASH `owned by` MEGA_CORP_PUBKEY label &quot;some profits&quot;)
@ -202,7 +202,7 @@ of a trade lifecycle using the commercial paper contract</p>
</div>
<p>Now you can define a main method in your unit test class that takes the <code class="docutils literal"><span class="pre">TransactionGroupDSL</span></code> object and uses it:</p>
<div class="codeset container">
<div class="highlight-kotlin"><div class="highlight"><pre><span class="n">CommercialPaperTests</span><span class="p">().</span><span class="n">trade</span><span class="p">().</span><span class="n">visualise</span><span class="p">()</span>
<div class="highlight-kotlin"><div class="highlight"><pre><span></span><span class="n">CommercialPaperTests</span><span class="p">().</span><span class="n">trade</span><span class="p">().</span><span class="n">visualise</span><span class="p">()</span>
</pre></div>
</div>
</div>

BIN
docs/source/_static/irs.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB