Merge branch 'development' into website/addPySRA

* development: (141 commits)
  Add missing CHANGELOG entry for OrderWatcher WS interface
  Bump up stale to close to 30 days
  Move onMessageAsync outside of tests and add comments
  Fix WS tests to remove race-condition and be more specific about the message expected
  Add temporary console.log to test failing on CI
  Make @0x/contracts-test-utils a dependency instead of a devDependency
  Fix test-publish failure in contracts packages
  Fixed solhint errors
  Added documentation to `LibAddressArray.append` and switched `if` to `require` smt
  Updated changelogs for new contracts
  Added `gas` field so tests pass on Geth;
  Added Changelog for new Extensions
  Updated comment `Execute fillOrder` -> `Execute exchange function`
  Explicit returns
  Prettier / Linter on contracts + TS
  Refactoring balance threshold filter
  Moved exchange calldata functions to separate mixin
  Less Assembly. More Solidity. Less Efficiency. More Readability.
  Run all tests for extensions
  Cleaned up tests for balance threshold filter
  ...

1 files changed, 88 insertions, 0 deletions

diff --git a/packages/order-watcher/README.md b/packages/order-watcher/README.md
index c0b99b272..385fe4715 100644
--- a/packages/order-watcher/README.md
+++ b/packages/order-watcher/README.md
@@ -4,6 +4,9 @@ An order watcher daemon that watches for order validity.
 
 #### Read the wiki [article](https://0xproject.com/wiki#0x-OrderWatcher).
 
+OrderWatcher also comes with a WebSocket server to provide language-agnostic access
+to order watching functionality. We used the [WebSocket Client and Server Implementation for Node](https://www.npmjs.com/package/websocket). The server sends and receives messages that conform to the [JSON RPC specifications](https://www.jsonrpc.org/specification).
+
 ## Installation
 
 **Install**
@@ -26,6 +29,91 @@ If your project is in [TypeScript](https://www.typescriptlang.org/), add the fol
 }
 ```
 
+## Using the WebSocket Server
+
+**Setup**
+
+**Environmental Variables**
+Several environmental variables can be set to configure the server:
+
+*   `ORDER_WATCHER_HTTP_PORT` specifies the port that the http server will listen on
+    and accept connections from. When this is not set, we default to 8080.
+
+**Requests**
+The server accepts three types of requests: `ADD_ORDER`, `REMOVE_ORDER` and `GET_STATS`. These mirror what the underlying OrderWatcher does. You can read more in the [wiki](https://0xproject.com/wiki#0x-OrderWatcher). Unlike the OrderWatcher, it does not expose any `subscribe` or `unsubscribe` functionality because the WebSocket server keeps a single subscription open for all clients.
+
+The first step for making a request is establishing a connection with the server. In Javascript:
+
+```
+var W3CWebSocket = require('websocket').w3cwebsocket;
+wsClient = new W3CWebSocket('ws://127.0.0.1:8080');
+```
+
+In Python, you could use the [websocket-client library](http://pypi.python.org/pypi/websocket-client/) and run:
+
+```
+from websocket import create_connection
+wsClient = create_connection("ws://127.0.0.1:8080")
+```
+
+With the connection established, you prepare the payload for your request. The payload is a json object with a format established by the [JSON RPC specification](https://www.jsonrpc.org/specification):
+
+*   `id`: All requests require you to specify a numerical `id`. When the server responds to the request, the response will have the same `id` as the one supplied with your request.
+*   `jsonrpc`: This is always the string `'2.0'`.
+*   `method`: This specifies the OrderWatcher method you want to call. I.e., `'ADD_ORDER'`, `'REMOVE_ORDER'` or `'GET_STATS'`.
+*   `params`: These contain the parameters needed by OrderWatcher to execute the method you called. For `ADD_ORDER`, provide `{ signedOrder: <your signedOrder> }`. For `REMOVE_ORDER`, provide `{ orderHash: <your orderHash> }`. For `GET_STATS`, no parameters are needed, so you may leave this empty.
+
+Next, convert the payload to a string and send it through the connection.
+In Javascript:
+
+```
+const addOrderPayload = {
+    id: 1,
+    jsonrpc: '2.0',
+    method: 'ADD_ORDER',
+    params: { signedOrder: <your signedOrder> },
+};
+wsClient.send(JSON.stringify(addOrderPayload));
+```
+
+In Python:
+
+```
+import json
+remove_order_payload = {
+    'id': 1,
+    'jsonrpc': '2.0',
+    'method': 'REMOVE_ORDER',
+    'params': {'orderHash': '0x6edc16bf37fde79f5012088c33784c730e2f103d9ab1caf73060c386ad107b7e'},
+}
+wsClient.send(json.dumps(remove_order_payload));
+```
+
+**Response**
+The server responds to all requests in a similar format. In the data field, you'll find another object containing the following fields:
+
+*   `id`: The id corresponding to the request that the server is responding to. `UPDATE` responses are not based on any requests so the `id` field is omitted`.
+*   `jsonrpc`: Always `'2.0'`.
+*   `method`: The method the server is responding to. Eg. `ADD_ORDER`. When order states change the server may also initiate a response. In this case, method will be listed as `UPDATE`.
+*   `result`: This field varies based on the method. `UPDATE` responses contain the new order state. `GET_STATS` responses contain the current order count. When there are errors, this field is omitted.
+*   `error`: When there is an error executing a request, the [JSON RPC](https://www.jsonrpc.org/specification) error object is listed here. When the server responds successfully, this field is omitted.
+
+In Javascript, the responses can be parsed using the `onmessage` callback:
+
+```
+wsClient.onmessage = (msg) => {
+    const responseData = JSON.parse(msg.data);
+    const method = responseData.method
+};
+```
+
+In Python, `recv` is a lightweight way to receive a response:
+
+```
+result = wsClient.recv()
+method = result.method
+```
+
 ## Contributing
 
 We strongly recommend that the community help us make improvements and determine the future direction of the protocol. To report bugs within this package, please create an issue in this repository.