ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-01-31 16:35:43 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merged in rg_doc_updates_3a (pull request #582)

Browse Source 
Starting new pull request - previous one had conflict errors
This commit is contained in:
Richard Green 2016-11-29 17:21:35 +00:00
commit d5ba8a2382
7 changed files with 134 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/source/CLI-vs-IDE.rst
View File

@ -25,8 +25,8 @@ Windows vs Mac / Unix
*********************
Due to the nature of their respective command interfaces, gradle is typically ran in windows with the command ``gradle.bat``
(or ``gradlew.bat`` if using the wrapper) and in Mac / Unix environments it is ran via ``./gradlew``. For brevity, the
simple windows syntax ``gradle`` is used for the majority of the documentation.
(or ``gradlew.bat`` if using the wrapper) and in Mac / Unix environments it is ran via ``./gradlew``. For brevity, the
simple windows syntax ``gradle`` is used for the majority of the documentation.
As well as including the most significant run and build configurations in the IDE, we also provide gradle tasks to build, install
and run significant parts of Corda demos and tools. Gradle is highly extensible and we use it for downloading required resources,

117
docs/source/running-the-demos.rst
View File

@ -16,15 +16,21 @@ so far. We have:
.. note:: If any demos don't work please jump on our mailing list and let us know.
Important : Common Instructions for all demos
---------------------------------------------
The demos can be run either from the command line, or from inside IntelliJ. Running from the command line is
recommended if you are just wanting to see them run, using IntelliJ can be helpful if you want to debug or
develop the demos themselves. For more details about running via the command line or within IntelliJ - see :doc:`CLI-vs-IDE`.
*For all demos:* The ``install`` gradle task is automatically ran if required; this no longer needs to be run independently.
Trader demo
-----------
This demo brings up three nodes: Bank A, Bank B and a notary/network map node that they both use. Bank A will
be the buyer, and self-issues some cash in order to acquire the commercial paper from Bank B, the seller.
be the buyer, and self-issues some cash in order to acquire commercial paper from Bank B, the seller.
To run from the command line:
@ -54,7 +60,7 @@ on a simulated clock passes.
To run from the command line:
1. Run ``./gradlew samples:irs-demo:deployNodes samples:irs-demo:installDist`` to install configs and a command line tool under ``samples/irs-demo/build``.
1. Run ``./gradlew samples:irs-demo:deployNodes`` to install configs and a command line tool under ``samples/irs-demo/build``.
2. Change to the ``samples/irs-demo/build`` directory.
3. Run ``./nodes/runnodes`` (or ``runnodes.bat`` on Windows) to open up three new terminals with the three nodes.
4. Run ``./install/irs-demo/bin/irs-demo --role UploadRates`` (or use ``irs-demo.bat`` on Windows). You should see a
@ -104,19 +110,6 @@ Or you can run them from inside IntelliJ, but when done this way, all the node o
In the "Attachment Demo: Run Nodes" window you should see some log lines scroll past, and within a few seconds the
message "File received - we're happy!" should be printed.
SIMM and Portfolio demo
-----------------------
.. note:: Read more about this demo at :doc:`initial-margin-agreement`.
To run the demo run:
1. Open the Corda project in IntelliJ and run the "Install" configuration
2. Open the Corda samples project in IntelliJ and run the "Simm Valuation Demo" configuration
Now open http://localhost:10005/web/simmvaluationdemo and http://localhost:10007/web/simmvaluationdemo to view the two nodes that this
will have started respectively. You can now use the demo by creating trades and agreeing the valuations.
.. _notary-demo:
Distributed Notary demo
@ -161,4 +154,96 @@ by using the H2 web console:
You can use the string on the right to connect to the h2 database: just paste it in to the `JDBC URL` field and click *Connect*.
You will be presented with a web application that enumerates all the available tables and provides an interface for you to query them using SQL.
- The committed states are stored in the ``NOTARY_COMMITTED_STATES`` table. Note that the raw data is not human-readable,
but we're only interested in the row count for this demo.
but we're only interested in the row count for this demo.
SIMM and Portfolio Demo - aka the Initial Margin Agreement Demo
---------------------------------------------------------------
Background and SIMM Introduction
********************************
This app is a demonstration of how Corda can be used for the real world requirement of initial margin calculation and
agreement; featuring the integration of complex and industry proven third party libraries into Corda nodes.
SIMM is an acronym for "Standard Initial Margin Model". It is effectively the calculation of a "margin" that is paid
by one party to another when they agree a trade on certain types of transaction. This margin is
paid such that, in the event of one of the counterparties suffering a credit event
(a financial term and a polite way to say defaulting, not paying the debts that are due, or potentially even bankruptcy),
then the party that is owed any sum already has some of the amount that it should have been paid. This payment to the
receiving party is a preventative measure in order to reduce the risk of a potentially catastrophic default domino
effect that caused the `Great Financial Crisis <https://en.wikipedia.org/wiki/Financial_crisis_of_2007%E2%80%932008>`_,
as it means that they can be assured that if they need to pay another party, they will have a proportion of the funds
that they have been relying on.
To enact this, in September 2016, the ISDA committee - with full backing from various governing bodies -
`issued a ruling on what is known as the ISDA SIMM ™ model <http://www2.isda.org/news/isda-simm-deployed-today-new-industry-standard-for-calculating-initial-margin-widely-adopted-by-market-participants>`_,
a way of fairly and consistently calculating this margin. Any parties wishing to trade a financial product that is
covered under this ruling would, independently, use this model and calculate their margin payment requirement,
agree it with their trading counterparty and then pay (or receive, depending on the results of this calculation)
this amount. In the case of disagreement that is not resolved in a timely fashion, this payment would increase
and so therefore it is in the parties' interest to reach agreement in as short as time frame as possible.
To be more accurate, the SIMM calculation is not performed on just one trade - it is calculated on an aggregate of
intermediary values (which in this model are sensitivities to risk factors) from a portfolio of trades; therefore
the input to a SIMM is actually this data, not the individual trades themselves.
Also note that implementations of the SIMM are actually protected and subject to license restrictions by ISDA
(this is due to the model itself being protected). We were fortunate enough to technically partner with
`OpenGamma <http://www.opengamma.com>`_ who allowed us to demonstrate the SIMM process using their proprietary model.
In the source code released, we have replaced their analytics engine with very simple stub functions that allow
the process to run without actually calculating correct values, and can easily be swapped out in place for their real libraries.
Open the Corda samples project in IntelliJ and run the "Simm Valuation Demo" configuration
Now open http://localhost:10005/web/simmvaluationdemo and http://localhost:10007/web/simmvaluationdemo to view the two
nodes that this will have started respectively. You can now use the demo by creating trades and agreeing the valuations.
Also see the README located in samples/simm-valuation-demo.
What happens in the demo (notionally)
*************************************
Preliminaries
- Ensure that there are a number of live trades with another party financial products that are covered under the
ISDA SIMM agreement (if none, then use the demo to enter some simple trades as described below).
Initial Margin Agreement Process
- Agree that one will be performing the margining calculation against a portfolio of trades with another party, and agree the trades in that portfolio. In practice, one node will start the flow but it does not matter which node does.
- Individually (at the node level), identify the data (static, reference etc) one will need in order to be able to calculate the metrics on those trades
- Confirm with the other counterparty the dataset from the above set
- Calculate any intermediary steps and values needed for the margin calculation (ie sensitivities to risk factors)
- Agree on the results of these steps
- Calculate the initial margin
- Agree on the calculation of the above with the other party
- In practice, pay (or receive) this margin (omitted for the sake of complexity for this example)
Demo execution (step by step)
*****************************
The demonstration can be run in two ways - via IntelliJ (which will allow you to add breakpoints, debug, etc), or via gradle and the command line.
Run with IntelliJ
1. Open the ``corda`` project with IntelliJ
2. Run the shared run configuration "SIMM Valuation Demo"
Run via CLI
1. Navigate to the ``samples/simm-valuation-demo`` directory in your shell
2. Run the gradle target ``deployNodes`` (ie; ``./gradlew deployNodes`` for Unix or ``gradlew.bat`` on Windows)
a. Unix: ``cd simm-valuation-demo/build/nodes && ./runnodes``
b. Windows: ``cd simm-valuation-demo/build/nodes & runnodes.bat``
Then (for both)
3. Browse to http://localhost:10005/web/simmvaluationdemo
4. Select the other counterparty (ie Bank B)
5. Enter at least 3 trades - via the "Create New Trade" tab.
6. On the "Agree Valuations" tab, click the "Start Calculations" button.
Additionally, you can confirm that these trades are not visible from `Bank C's node<http://localhost:10009/web/simmvaluationdemo/>`_.
Please note that any URL text after `simmvaluationdemo` should not be bookmarked or navigated directly to as they are only for aesthetics.

14
samples/attachment-demo/README.md
View File

@ -1,6 +1,14 @@
# Attachment Demo
Please see docs/build/html/running-the-demos.html and docs/build/html/tutorial-attachments.html
This code demonstrates sending a transaction with an attachment from one to node to another, and the receiving node accessing the attachment.
This program is a simple demonstration of sending a transaction with an attachment from one node to another, and
then accessing the attachment on the remote node.
Please see the either the [online documentation](https://docs.corda.net/running-the-demos.html#attachment-demo) for more info on the attachment demo, or the [included offline version](../../docs/build/html/running-the-demos.html#attachment-demo).
From the root directory of the repository, run the following commands (on mac / unix, replace `gradle` with `./gradlew`)
gradle samples:attachment-demo:deployNodes
./samples/attachment-demo/build/nodes/runnodes
gradle samples:attachment-demo:runRecipient # (in one window)
gradle samples:attachment-demo:runSender # (in another window)

6
samples/irs-demo/README.md
View File

@ -1 +1,7 @@
# IRS Demo
This code demonstrates an Interest Rate Swap agreement between two banks, confirming the transaction utilising the services
of a notary and then retrieving and applying interest rates from an oracle service.
Please see the either the [online documentation](https://docs.corda.net/running-the-demos.html#irs-demo) for more info on the attachment demo, or the [included offline version](../../docs/build/html/running-the-demos.html#irs-demo).

13
samples/network-visualiser/README.md
View File

@ -1,8 +1,13 @@
# Network Visualiser
This package contains a network visualiser that uses a simulation to visualise the interaction and messages between
nodes on the Corda network.
This package contains a network visualiser that uses a simulation to visualise the interaction and messages between nodes on the Corda network.
Please see the documentation site for more info on the simulator tool. You can run it like this:
Please see the either the [online documentation](https://docs.corda.net/network-simulator.html) for more info on the network visualiser, or the [included offline version](../../docs/build/html/network-simulator.html).
gradle samples:network-visualiser:run
From the root directory of the repository, run it like this (Windows):
gradle samples:network-visualiser:run
or (Mac / Unix)
./gradlew samples:network-visualiser:run

43
samples/simm-valuation-demo/README.md
View File

@ -1,50 +1,14 @@
# SIMM Valuation Demo
## Introduction and Background
See our [main documentation site](https://docs.corda.net/initial-margin-agreement.html) regarding the SIMM valuation and agreement on a distributed ledger.
See our documentation regarding the SIMM valuation and agreement on a distributed ledger
.. TODO: main_doc_site_link
This demo allows you to trade swaps - a type of financial product - with another counterparty. Once several swaps have been traded, the demo shows how a process can be run in order to generate what is known as the Standard Initial Margin. This is a payment made from one counterparty to the other so that in the event of a default (ie non payment of the overall value of the contract), the receiving counterparty has received sufficient cash to purchase replacement contracts in the market (hopefully preventing a domino effect associated with the global financial crisis of 2007 and 2008)
This demo does not, however, include real SIMM valuation code but a stub for the OpenGamma set of libraries (see below), so please do not base any financial decisions on results generated by this demo.
## Preparation / Building
You will need to build the core Corda component libraries and ensure they have been installed into your local maven repository. Do this by following the instructions if you haven't done this already.
.. TODO: Link Instructions when finalised
Once they are available, you will need to run (in the directory containing the samples repo)
./gradle deployNodes
which will compile all of the demos in this project, create the web framework and generate test nodes for this demonstration
## Startup
This demo is best run via the command line and a web browser, although it can be run via IntelliJ for debugging purposes.
Change directory to `simm-valuation-demo/build/nodes` and execute the `runnodes` script. This will start four nodes - a notary node and three bank nodes. Wait until the message TODO: _when logging output changes completed_ appears and then all of the nodes will be ready for interaction.
## Interacting
The demo shows a simple web front end with both a trade entry and a portfolio view. The simple portfolio view is filtered by the counterparty selected.
Start by browsing [here](http://localhost:10005/web/simmvaluationdemo/) . This is the home page for Bank A (as determined in the top right corner). In the dropdown titled "Select a counterparty", choose the party you wish to transact with, in our case "Bank B". Click the "Create New Trade" function in the top menu bar. Choose any convention for the swap (the top one - EUR fixed 1Y EURIBOR 3M - works well). Feel free to amend any of the new deal parameters. Lastly, click the Submit bar to send your completed trade to the other counterparty. Once you are taken to the "view-trade" page, then that trade has been sent across the network to the other node, signed and sent back and then signed by your node, committing it to the Corda ledger. At this stage, you can optionally verify that the trade exists on the other node by visiting [Bank B's node](http://localhost:10007/web/simmvaluationdemo/). Additionally, you can confirm that these trades are not visible from [Bank C's node](http://localhost:10009/web/simmvaluationdemo/).
Once the portfolio has some trades, you can start the valuation and agreement flow. Do this by clicking the "Agree Valuations" tab and then the "Start Calculations" button. The flow will execute and then the web page will demonstrate a simulation of the agreement as it proceeds. Eventually, the flow will complete with the Initial Margin figures being agreed by and then signed by both nodes. For more details on exactly what is happening here, please see the link in the Introduction and Background section.
Please note that any URL text after `simmvaluationdemo` should not be bookmarked or navigated directly to as they are only for aesthetics.
### Shutting down
The script to start the nodes has been written such that when you press a key in the window the script is running, the nodes will close down.
## SIMM Library Licensing
This demo does not, however, include real SIMM valuation code but a stub for the OpenGamma set of libraries, so please do not base any financial decisions on results generated by this demo.
This demo was built in partnership with OpenGamma and used their SIMM library. However, due to licensing constraints we cannot distribute their library with this code. For this reason, we have stubbed out the relevant parts and replaced it with a very simplistic template that returns fake (but correctly structured) data. However, if you wish to use a realistic library, then please do get in touch with OpenGamma directly for access to their libraries and we will be happy to demonstrate how to replace the stub code.
@ -55,7 +19,6 @@ This demo was built in partnership with OpenGamma and used their SIMM library. H
| Could not find net.corda.(...):(...):0.6-SNAPSHOT | The corda libraries have not been installed into your local maven directory. View the instructions for doing this in the core corda repository |
| Execution failed for task ':simm-valuation-demo:buildWeb' : A problem occurred starting process 'command 'ng'' | You need to have `node packet manager` installed in order to build out some of the web resources. This is not a necessary step as we include pre-built web resources but if you do modify the web source, you will need to rebuild this area |
.. TODO: expand upon how the the web site is built

4
samples/trader-demo/README.md
View File

@ -1,5 +1,5 @@
# Trader Demo
This demo shows a couple of nodes doing an atomic asset swap: cash for commercial paper.
This code demonstrates two nodes exchanging cash for a commercial paper.
Please see docs/build/html/running-the-demos.html to learn how to use this demo.
Please see the either the [online documentation](https://docs.corda.net/running-the-demos.html#trader-demo) for more info on the attachment demo, or the [included offline version](../../docs/build/html/running-the-demos.html#trader-demo).