From c2a10e8fae0dd3ee53d8a5a2eb13107f9903fa44 Mon Sep 17 00:00:00 2001
From: Mike Hearn <mike@r3cev.com>
Date: Wed, 3 Feb 2016 16:56:21 +0100
Subject: [PATCH] Add a page to the docsite about the trading demo.

---
 docs/source/index.rst                    |  1 +
 docs/source/inthebox.rst                 |  3 +++
 docs/source/running-the-trading-demo.rst | 34 ++++++++++++++++++++++++
 3 files changed, 38 insertions(+)
 create mode 100644 docs/source/running-the-trading-demo.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index d0e75160f0..66ce77d925 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -27,6 +27,7 @@ Read on to learn:
    getting-set-up
    data-model
    messaging
+   running-the-trading-demo
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source/inthebox.rst b/docs/source/inthebox.rst
index 9a98be3524..30be0a9db8 100644
--- a/docs/source/inthebox.rst
+++ b/docs/source/inthebox.rst
@@ -9,6 +9,9 @@ The current prototype consists of a small amount of code that defines:
   These are simplified versions of the real things.
 * Unit tests that check the algorithms do what is expected, and which verify the behaviour of the smart contracts.
 * API documentation and tutorials (what you're reading)
+* A simple standalone node that uses an embedded message queue broker as its P2P messaging layer
+* A trading demo that runs the node in either a listening/buying mode, or a connecting/selling mode, and swaps some
+  fake commercial paper assets for some self-issued IOU cash.
 
 Some things it does not currently include but should gain later are:
 
diff --git a/docs/source/running-the-trading-demo.rst b/docs/source/running-the-trading-demo.rst
new file mode 100644
index 0000000000..af971cf7ca
--- /dev/null
+++ b/docs/source/running-the-trading-demo.rst
@@ -0,0 +1,34 @@
+Running the trading demo
+========================
+
+The repository contains a program that implements a demo of two nodes running the two-party trading protocol, which you
+can learn about in :doc:`protocol-state-machines`.
+
+The node has only currently been tested on MacOS X. If you have success on other platforms, please let us know.
+
+To run the demo, firstly edit your /etc/hosts file or Windows equivalent to add two aliases for localhost: alpha and
+beta. This is necessary for now because parts of the code use the DNS hostname to identify nodes and thus defining two
+nodes both called localhost won't work. We might fix this in future to include the port number everywhere, so making
+this easier.
+
+You should now be able to run ``ping alpha`` and ``ping beta`` and not see errors.
+
+Now, open two terminals, and in the first run:::
+
+    ./gradlew runDemoBuyer
+
+It will create a directory named "alpha" and ask you to edit the configuration file inside. Open up ``alpha/config``
+in your favourite text editor and give the node a legal identity of "Alpha Corp, Inc" or whatever else you feel like.
+The actual text string is not important. Now run the gradle command again, and it should start up and wait for
+a seller to connect.
+
+In the second terminal, run::
+
+    ./gradlew runDemoSeller
+
+and repeat the process, this time calling the node ... something else.
+
+You should see some log lines scroll past, and within a few seconds the messages "Purchase complete - we are a
+happy customer!" and "Sale completed - we have a happy customer!" should be printed.
+
+If it doesn't work, jump on the mailing list and let us know.
\ No newline at end of file