New docs page re contents of a condition

docs/server/source/data-models/conditions.rst

@@ -0,0 +1,102 @@
+Conditions
+==========
+
+At a high level, a condition is like a lock on an output.
+If can you satisfy the condition, you can unlock the output and transfer/spend it.
+BigchainDB Server supports a subset of the ILP Crypto-Conditions
+(`version 02 of Crypto-Conditions <https://tools.ietf.org/html/draft-thomas-crypto-conditions-02>`_).
+
+A condition object can be quite elaborate,
+with many nested levels,
+but the simplest case is actually quite simple.
+Here's an example signature condition:
+
+.. code-block:: json
+
+   {
+       "details": {
+           "type": "ed25519-sha-256",
+           "public_key": "HFp773FH21sPFrn4y8wX3Ddrkzhqy4La4cQLfePT2vz7"
+       },
+       "uri": "ni:///sha-256;at0MY6Ye8yvidsgL9FrnKmsVzX0XrNNXFmuAPF4bQeU?fpt=ed25519-sha-256&cost=131072"
+   }
+
+If someone wants to spend the output where this condition is found, then they must create a TRANSFER transaction with an input that fulfills it (this condition). Because it's a ed25519-sha-256 signature condition, that means they must sign the TRANSFER transaction with the private key corresponding to the public key HFp773…
+
+
+Supported Crypto-Conditions
+---------------------------
+
+BigchainDB Server v1.0 supports two of the Crypto-Conditions:
+
+1. ED25519-SHA-256 signature conditions
+2. THRESHOLD-SHA-256 threshold conditions
+
+We saw an example signature condition above.
+For more information about how BigchainDB handles keys and signatures,
+see the page titled :ref:`Signature Algorithm and Keys`.
+
+A more complex condition can be composed by using n signature conditions as inputs to an m-of-n threshold condition: a logic gate which outputs TRUE if and only if m or more inputs are TRUE. If there are n inputs to a threshold condition:
+
+* 1-of-n is the same as a logical OR of all the inputs
+* n-of-n is the same as a logical AND of all the inputs
+
+For example, you could create a condition requiring m (of n) signatures.
+Here's an example 2-of-2 condition:
+
+.. code-block:: json
+
+   {
+       "details": {
+           "type": "threshold-sha-256",
+           "threshold": 2,
+           "subconditions": [
+               {
+                   "public_key": "5ycPMinRx7D7e6wYXLNLa3TCtQrMQfjkap4ih7JVJy3h",
+                   "type": "ed25519-sha-256"
+               },
+               {
+                   "public_key": "9RSas2uCxR5sx1rJoUgcd2PB3tBK7KXuCHbUMbnH3X1M",
+                   "type": "ed25519-sha-256"
+                }
+            ]       
+        },
+        "uri": "ni:///sha-256;zr5oThl2kk6613WKGFDg-JGu00Fv88nXcDcp6Cyr0Vw?fpt=threshold-sha-256&cost=264192&subtypes=ed25519-sha-256"
+   }
+
+The (single) output of a threshold condition can be used as one of the inputs to another threshold condition. That means you can combine threshold conditions to build complex expressions such as ``(x OR y) AND (2 of {a, b, c})``.
+
+.. image:: /_static/Conditions_Circuit_Diagram.png
+
+When you create a condition, you can calculate its
+`cost <https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-7.2.2>`_,
+an estimate of the resources that would be required to validate the fulfillment.
+For example, the cost of one signature condition is 131072.
+A BigchainDB federation can put an upper limit on the complexity of each
+condition, either directly by setting a maximum allowed cost,
+or
+`indirectly <https://github.com/bigchaindb/bigchaindb/issues/356#issuecomment-288085251>`_
+by :ref:`setting a maximum allowed transaction size <Enforcing a Max Transaction Size>`
+which would limit
+the overall complexity accross all inputs and outputs of a transaction.
+Note: At the time of writing, there was no configuration setting
+to set a maximum allowed cost,
+so the only real option was to
+:ref:`set a maximum allowed transaction size <Enforcing a Max Transaction Size>`.
+
+
+Constructing a Condition
+------------------------
+
+The above examples should make it clear how to construct
+a condition object, but they didn't say how to generate the ``uri``.
+If you want to generate a correct condition URI,
+then you should consult the Crypto-Conditions spec
+or use one of the existing Crypto-Conditions packages/libraries
+(which are used by the BigchainDB Drivers).
+
+* `Crypto-Conditions Spec (Version 02) <https://tools.ietf.org/html/draft-thomas-crypto-conditions-02>`_
+* BigchainDB :ref:`Drivers & Tools`
+
+The `Handcrafting Transactions <https://docs.bigchaindb.com/projects/py-driver/en/latest/handcraft.html>`_
+page may also be of interest.

docs/server/source/data-models/index.rst

@@ -15,5 +15,6 @@ This section unpacks each one in turn.
    transaction-model 
    asset-model
    inputs-outputs
+   conditions
    block-model
    vote-model

docs/server/source/data-models/inputs-outputs.rst

@@ -47,55 +47,13 @@ An output has the following structure:
        "amount": "<Number of shares of the asset (an integer in a string)>"
    }
 
+The :ref:`page about conditions <Conditions>` explains the contents of a ``condition``.
+
 The list of ``public_keys`` is always the "owners" of the asset at the time the transaction completed, but before the next transaction started.
 See the reference on :ref:`outputs <Output>` for more description about the meaning of each field.
 
-Below is a high-level description of what goes into building a ``condition`` object.
-To construct an actual ``condition`` object, you can use one of the
-:ref:`BigchainDB drivers or transaction-builders <Drivers & Tools>`,
-or use a low-level crypto-conditions library as illustrated
-in the page about `Handcrafting Transactions <https://docs.bigchaindb.com/projects/py-driver/en/latest/handcraft.html>`_.
-
-
-Conditions
-----------
-
-At a high level, a condition is like a lock on an output.
-If can you satisfy the condition, you can unlock the output and transfer/spend it.
-BigchainDB Server v1.0 supports a subset of the ILP Crypto-Conditions
-(`version 02 of Crypto-Conditions <https://tools.ietf.org/html/draft-thomas-crypto-conditions-02>`_).
-
-The simplest supported condition is a simple signature condition.
-Such a condition could be stated as,
-"You can satisfy this condition
-if you send me a message and a cryptographic signature of that message,
-produced using the private key corresponding to this public key."
-The public key is put in the output.
-BigchainDB currently only supports ED25519 signatures.
-
-A more complex condition can be composed by using n simple signature conditions as inputs to an m-of-n threshold condition (a logic gate which outputs TRUE if and only if m or more inputs are TRUE). If there are n inputs to a threshold condition:
-
-* 1-of-n is the same as a logical OR of all the inputs
-* n-of-n is the same as a logical AND of all the inputs
-
-For example, one could create a condition requiring m (of n) signatures before their asset can be transferred.
-
-The (single) output of a threshold condition can be used as one of the inputs of other threshold conditions. This means that one can combine threshold conditions to build complex logical expressions, e.g. (x OR y) AND (u OR v).
-
-When one creates a condition, one can calculate its
-`cost <https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-7.2.2>`_,
-an estimate of the resources that would be required to validate the fulfillment.
-A BigchainDB federation can put an upper limit on the complexity of each
-condition, either directly by setting a maximum allowed cost,
-or
-`indirectly <https://github.com/bigchaindb/bigchaindb/issues/356#issuecomment-288085251>`_
-by :ref:`setting a maximum allowed transaction size <Enforcing a Max Transaction Size>`
-which would limit
-the overall complexity accross all inputs and outputs of a transaction.
-Note: At the time of writing, there was no configuration setting
-to set a maximum allowed cost,
-so the only real option was to
-:ref:`set a maximum allowed transaction size <Enforcing a Max Transaction Size>`.
+Note that ``amount`` must be a string (e.g. ``"7"``).
+In a TRANSFER transaction, the sum of the output amounts must be the same as the sum of the outputs that it transfers (i.e. the sum of the input amounts). For example, if a TRANSFER transaction has two outputs, one with ``"amount": "2"`` and one with ``"amount": "3"``, then the sum of the outputs is 5 and so the sum of the outputs-being-transferred must also be 5.
 
 
 .. note::