corda/samples/simm-valuation-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.

The SIMM was introduced to standardise the calculation of how much margin counterparties charge each other on their bilateral transactions. Before SIMM, each counterparty computed margins according to its own model and it was made it very difficult to agree the exact margin with the counterparty that faces the same trade on the other side.

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 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 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.

What happens in the demo (notionally)

Preliminaries - Ensure that there are a number of live trades with another party based on 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)

Requirements

This document assumes you have cURL (curl) installed and ready to use. It is usually installed by default in many Linux distributions and MacOS. On Windows, there are numerous ways of installation, including Cygwin, official distribution, package managers like Chocolatey, NuGet, or Windows Linux subsystem. Please refer to installation documents of your chosen source.

Demo execution (step by step)

Setting up the Corda infrastructure

To run from the command line in Unix:

1. Deploy the nodes using ./gradlew samples:simm-valuation-demo:deployNodes
2. Run the nodes using ./samples/simm-valuation-demo/build/nodes/runnodes

To run from the command line in Windows:

1. Deploy the nodes using gradlew samples:simm-valuation-demo:deployNodes
2. Run the nodes using samples\simm-valuation-demo\build\nodes\runnodes

Getting Bank A's details

From the command line run

curl http://localhost:10005/api/simmvaluationdemo/whoami

The response should be something like

{
    "self" : {
        "id" : "8Kqd4oWdx4KQGHGQW3FwXHQpjiv7cHaSsaAWMwRrK25bBJj792Z4rag7EtA",
        "text" : "C=GB,L=London,O=Bank A"
    },
    "counterparties" : [
        {
            "id" : "8Kqd4oWdx4KQGHGL1DzULumUmZyyokeSGJDY1n5M6neUfAj2sjbf65wYwQM",
            "text" : "C=JP,L=Tokyo,O=Bank C"
        },
        {
            "id" : "8Kqd4oWdx4KQGHGTBm34eCM2nrpcWKeM1ZG3DUYat3JTFUQTwB3Lv2WbPM8",
            "text" : "C=US,L=New York,O=Bank B"
        }
    ]
}

Now, if we ask the same question of Bank C we will see that it's id matches the id for Bank C as a counter party to Bank A and Bank A will appear as a counterparty

curl -i -H "Content-Type: application/json" -X GET http://localhost:10011/api/simmvaluationdemo/whoami

Creating a trade with Bank C

In what follows, we assume we are Bank A (which is listening on port 10005)

Notice the id field in the output of the whoami command. We are going to use the id associated with Bank C, one of our counterparties, to create a trade. The general command for this is:

curl -i -H "Content-Type: application/json" -X PUT -d <<<JSON representation of the trade>>>  http://localhost:10005/api/simmvaluationdemo/<<<counterparty id>>>/trades

where the representation of the trade is

{
  "id"          : "trade1",
  "description" : "desc",
  "tradeDate"   : [ 2016, 6, 6 ],
  "convention"  : "EUR_FIXED_1Y_EURIBOR_3M",
  "startDate"   : [ 2016, 6, 6 ],
  "endDate"     : [ 2020, 1, 2 ],
  "buySell"     : "BUY",
  "notional"    : "1000",
  "fixedRate"   : "0.1"
}

Continuing our example, the specific command would look as follows

curl -i -H "Content-Type: application/json" \
  -X PUT \
  -d '{"id":"trade1","description" : "desc","tradeDate" : [ 2016, 6, 6 ],  "convention" : "EUR_FIXED_1Y_EURIBOR_3M",  "startDate" : [ 2016, 6, 6 ],  "endDate" : [ 2020, 1, 2 ],  "buySell" : "BUY",  "notional" : "1000",  "fixedRate" : "0.1"}' \
  http://localhost:10005/api/simmvaluationdemo/8Kqd4oWdx4KQGHGL1DzULumUmZyyokeSGJDY1n5M6neUfAj2sjbf65wYwQM/trades

Note: you should replace the node id 8Kqd4oWdx4KQGHGL1DzULumUmZyyokeSGJDY1n5M6neUfAj2sjbf65wYwQM with the node id returned by the whoami call above for one of the counterparties. In our worked example we selected "Bank C" and used the generated id for that node. Thus, the actual command would be:

curl -i -H "Content-Type: application/json" \
  -X PUT \
  -d '{"id":"trade1","description" : "desc","tradeDate" : [ 2016, 6, 6 ],  "convention" : "EUR_FIXED_1Y_EURIBOR_3M",  "startDate" : [ 2016, 6, 6 ],  "endDate" : [ 2020, 1, 2 ],  "buySell" : "BUY",  "notional" : "1000",  "fixedRate" : "0.1"}' \
  http://localhost:10005/api/simmvaluationdemo/<<<INSERT BANK C ID HERE>>/trades

Once executed, the expected response is:

HTTP/1.1 202 Accepted
Date: Thu, 28 Sep 2017 17:19:39 GMT
Content-Type: text/plain
    Access-Control-Allow-Origin: *
Content-Length: 2
Server: Jetty(9.3.9.v20160517)

Verifying trade completion

With the trade completed and stored by both parties, the complete list of trades with our counterparty can be seen with the following command

curl -X GET http://localhost:10005/api/simmvaluationdemo/<<<counterparty id>>>/trades

The command for our example, using Bank A, would thus be

curl -X GET http://localhost:10005/api/simmvaluationdemo/8Kqd4oWdx4KQGHGL1DzULumUmZyyokeSGJDY1n5M6neUfAj2sjbf65wYwQM/trades

whilst a specific trade can be seen with

curl  -X GET http://localhost:10005/api/simmvaluationdemo/<<<counterparty id>>>/trades/<<<trade id>>>

If we look at the trade we created above, we assigned it the id "trade1", the complete command in this case would be

curl  -X GET http://localhost:10005/api/simmvaluationdemo/8Kqd4oWdx4KQGHGL1DzULumUmZyyokeSGJDY1n5M6neUfAj2sjbf65wYwQM/trades/trade1

Generating a valuation

curl -i -H "Content-Type: application/json" \
  -X POST \
  -d <<<JSON representation>>>
  http://localhost:10005/api/simmvaluationdemo/<<<counterparty id>>>/portfolio/valuations/calculate

Again, the specific command to continue our example would be

curl -i -H "Content-Type: application/json" \
  -X POST \
  -d '{"valuationDate":[2016,6,6]}' \
  http://localhost:10005/api/simmvaluationdemo/8Kqd4oWdx4KQGHGL1DzLumUmZyyokeSGJDY1n5M6neUfAj2sjbf65wYwQM/portfolio/valuations/calculate

Viewing a valuation

In the same way we can ask for specific instances of trades with a counterparty, we can request details of valuations

curl -i -H "Content-Type: application/json" -X GET http://localhost:10005/api/simmvaluationdemo/<<<counterparty id>>>/portfolio/valuations

The specific command for out Bank A example is

curl -i -H "Content-Type: application/json" \
  -X GET http://localhost:10005/api/simmvaluationdemo/8Kqd4oWdx4KQGHGL1DzULumUmZyyokeSGJDY1n5M6neUfAj2sjbf65YwQM/portfolio/valuations

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.

Troubleshooting

Error	Fix
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