Merge pull request #81 from gnosis/edit-docs

Edit docs

README.rst

@@ -1,12 +1,5 @@
-.. figure:: https://raw.githubusercontent.com/gnosis/conditional-tokens-contracts/master/assets/logo.png
-   :target: https://gnosis.pm
-   :alt: Gnosis Logo
-
-
-Gnosis Conditional Tokens Contracts
-===================================
-Prediction Market Contracts
----------------------------
+Conditional Tokens Contracts
+============================
 
 .. image:: https://travis-ci.org/gnosis/conditional-tokens-contracts.svg?branch=master
    :target: https://travis-ci.org/gnosis/conditional-tokens-contracts
@@ -16,12 +9,11 @@ Prediction Market Contracts
    :target: https://greenkeeper.io/
    :alt: Greenkeeper badge
 
-Experimental smart contracts for conditional prediction markets.
+Smart contracts for conditional tokens.
 
 `→ Online Documentation`_
 
-.. _→ Online Documentation: https://gnosis-conditional-tokens.readthedocs.io/en/latest/
-.. _Gnosis: https://gnosis.pm
+.. _→ Online Documentation: https://conditional-tokens.readthedocs.io/en/latest/
 
 
 License

docs/Makefile

@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SPHINXAUTOB   = sphinx-autobuild
-SPHINXPROJ    = GnosisPredictionMarketContracts
+SPHINXPROJ    = ConditionalTokens
 SOURCEDIR     = .
 BUILDDIR      = _build
 

docs/conf.py

@@ -19,7 +19,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Gnosis Conditional Tokens'
+project = 'Conditional Tokens'
 copyright = '2018, Gnosis Ltd'
 author = 'Gnosis'
 
@@ -106,7 +106,7 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'GnosisConditionalTokensdoc'
+htmlhelp_basename = 'ConditionalTokensdoc'
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -134,8 +134,8 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc,
-     'GnosisConditionalTokens.tex',
-     'Gnosis Conditional Tokens Documentation',
+     'ConditionalTokens.tex',
+     'Conditional Tokens Documentation',
      'Gnosis', 'manual'),
 ]
 
@@ -145,8 +145,8 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'gnosisconditionaltokens',
-     'Gnosis Conditional Tokens Documentation',
+    (master_doc, 'conditionaltokens',
+     'Conditional Tokens Documentation',
      [author], 1)
 ]
 
@@ -157,9 +157,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'GnosisConditionalTokens',
-     'Gnosis Conditional Tokens Documentation',
-     author, 'GnosisConditionalTokens',
+    (master_doc, 'ConditionalTokens',
+     'Conditional Tokens Documentation',
+     author, 'ConditionalTokens',
      'One line description of project.',
      'Miscellaneous'),
 ]

docs/developer-guide.rst

@@ -1,10 +1,6 @@
 Developer Guide
 ===============
 
-.. warning::
-
-    This document refers to an experimental prediction market framework under active development. Some things may change. You may also be interested in the predecessor of this work: the original `Gnosis prediction market contracts <https://gnosis-pm-contracts.readthedocs.io>`_.
-
 Prerequisites
 -------------
 
@@ -334,7 +330,7 @@ The effect of this transaction is to transfer ``amount`` DollaCoin from the mess
 * ``$:(B)``
 * ``$:(C)``
 
-.. note:: The previous example, where collateral was split into shallow positions containing collections with one slot each, is similar to ``Event.buyAllOutcomes`` from v1.
+.. note:: The previous example, where collateral was split into shallow positions containing collections with one slot each, is similar to ``Event.buyAllOutcomes`` from Gnosis' first prediction market contracts.
 
 The set of ``(A)``, ``(B)``, and ``(C)`` is not the only nontrivial partition of outcome slots for the example categorical condition. For example, the set ``(B)`` (with index set ``0b010``) and ``(A|C)`` (with index set ``0b101``) also partitions these outcome slots, and consequently, splitting from ``$`` to ``$:(B)`` and ``$:(A|C)`` is also valid and can be done with the following code:
 
@@ -449,7 +445,7 @@ If successful, the function will emit this event:
 
 .. autosolevent:: ConditionalTokens.PositionsMerge
 
-.. note:: This generalizes ``sellAllOutcomes`` from v1 like ``splitPosition`` generalizes ``buyAllOutcomes``.
+.. note:: This generalizes ``sellAllOutcomes`` from Gnosis' first prediction market contracts like ``splitPosition`` generalizes ``buyAllOutcomes``.
 
 
 Querying and Transferring Stake

docs/glossary.rst

@@ -4,7 +4,7 @@ Glossary
 *********
 Condition
 *********
-    A question that a specific oracle reports on with a preset number of outcome slots. Analogous to events from PM contracts v1.
+    A question that a specific oracle reports on with a preset number of outcome slots. Analogous to events from Gnosis' first prediction market contracts.
 
     For example, a condition with a categorical outcome, that is, one of N outcomes, may have N outcome slots, where the resolution of the condition sets one of the outcome slots to receive the full payout.
 

docs/index.rst

@@ -1,11 +1,39 @@
-.. include:: ../README.rst
+Conditional Tokens Contracts
+============================
+
+.. image:: https://travis-ci.org/gnosis/conditional-tokens-contracts.svg?branch=master
+   :target: https://travis-ci.org/gnosis/conditional-tokens-contracts
+   :alt: Build Status
+
+.. image:: https://badges.greenkeeper.io/gnosis/conditional-tokens-contracts.svg
+   :target: https://greenkeeper.io/
+   :alt: Greenkeeper badge
+
+Smart contracts for conditional tokens.
+
+`→ Github source repository`_
+
+.. _→ Github source repository: https://github.com/gnosis/conditional-tokens-contracts
+
+
+License
+-------
+
+All smart contracts are released under the `LGPL 3.0`_ license.
+
+Security and Liability
+~~~~~~~~~~~~~~~~~~~~~~
+
+All contracts are **WITHOUT ANY WARRANTY**; *without even* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+.. _LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.en.html
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   motivation
    developer-guide
-   changes-from-v1
    contributing
    glossary
 

docs/make.bat

@@ -9,7 +9,7 @@ if "%SPHINXBUILD%" == "" (
 )
 set SOURCEDIR=.
 set BUILDDIR=_build
-set SPHINXPROJ=GnosisPredictionMarketContracts
+set SPHINXPROJ=ConditionalTokens
 
 if "%1" == "" goto help
 

docs/motivation.rst

@@ -0,0 +1,53 @@
+Motivation
+==========
+
+Conditional tokens were originally designed to enable combinatorial prediction markets more fully. These sorts of markets enable deeper information discovery with respect to conditional probabilities of events and conditional expected values. Prediction markets like this may be represented by nesting traditional prediction markets in systems like Augur or the first version of Gnosis prediction market contracts. However, they weren't designed to maximize fungibility in deeper combinatorial markets. 
+
+Existing Approach to Combinatorial Markets
+------------------------------------------
+
+For example, let's suppose there are two oracles which report on the following questions:
+
+1. Which **choice** out of Alice, Bob, and Carol will be made?
+2. Will the **score** be high or low?
+
+There are two ways to create conditional tokens backed by a collateral token denoted as ``$``, where the value of these conditional tokens depend on *both* of the reports of these oracles on their respective assigned questions:
+
+.. figure:: /_static/v1-cond-market-abc-hilo.png
+    :alt: Markets where events depending on the outcome of the "score" question use outcome tokens from an event depending on the "choice" question as collateral
+    :align: center
+
+    **Choice**, then **Score**
+
+.. figure:: /_static/v1-cond-market-hilo-abc.png
+    :alt: Another setup where instead events depending on the outcome of the "choice" question use outcome tokens from an event depending on the "score" question as collateral
+    :align: center
+
+    **Score**, then **Choice**
+
+Although the outcome tokens in the second layer should represent value in collateral under the same conditions irrespective of the order in which the conditions are specified, they are in reality separate entities. Users may hold separate balances of each even though that balance should theoretically be redeemable under the same conditions.
+
+.. figure:: /_static/v1-cond-market-ot-compare.png
+    :alt: The two different conditional tokens which resolves to collateral if Alice gets chosen and the score is high.
+    :align: center
+
+    These tokens should be the same, but aren't.
+
+The order in which operations are done on these "deeper" tokens matters as well. For example, partial redemptions to the first layer are only possible if that specific outcome token's second layer condition has been resolved.
+
+Combinatorial Markets with Conditional Tokens
+---------------------------------------------
+
+For conditional tokens, because all conditions are held in a single contract and are not tied to a specific collateral token, fungibility in deeper layers may be preserved. Referring to the example, the situation using conditional tokens looks more like this:
+
+.. figure:: /_static/v2-cond-market-slots-only.png
+    :alt: The second layer of conditional tokens may resolve to conditional tokens of either condition.
+    :align: center
+
+It can be seen that the deeper outcome tokens which were different tokens in older systems are now the same token:
+
+.. figure:: /_static/v2-cond-market-ot-compare.png
+    :alt: There is a single class of conditional tokens which resolves to collateral if Alice gets chosen and the score is high.
+    :align: center
+
+    Contrast this with the older approach.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gnosis.pm/conditional-tokens-contracts",
   "version": "0.5.3",
-  "description": "Collection of smart contracts for the Gnosis prediction market platform",
+  "description": "Collection of smart contracts for the conditional tokens",
   "scripts": {
     "lint": "eslint .",
     "develop": "truffle develop",
@@ -22,7 +22,7 @@
     "Solidity",
     "Truffle"
   ],
-  "author": "Gnosis (https://gnosis.pm)",
+  "author": "Gnosis (https://gnosis.io)",
   "license": "LGPL-3.0",
   "dependencies": {
     "openzeppelin-solidity": "^2.3.0"