Fleshed out consensus plugin docs

docs/source/consensus.md

@@ -1,7 +1,50 @@
 # BigchainDB Consensus Plugins
-TODO: Write this section
 
-A quick example of a plugin that adds nonsense rules:
+BigchainDB has a pluggable block/transaction validation architecture. The default consensus rules can be extended or replaced entirely.
+
+
+## Installing a plugin
+
+Plugins can be installed via pip!
+
+```bash
+$ pip install bigchaindb-plugin-demo
+```
+
+Or using setuptools:
+
+```bash
+$ cd bigchaindb-plugin-demo/
+$ python setup.py install # (or develop)
+```
+
+To activate your plugin, you can either set the `consensus_plugin` field in your config file (usually `~/.bigchaindb`) or by setting the `BIGCHAIN_CONSENSUS_PLUGIN` environement variable to the name of your plugin (see the section on [Packaging a plugin](#packaging-a-plugin) for more about plugin names).
+
+
+## Plugin API
+
+BigchainDB's [current plugin API](../../bigchaindb/consensus.py) exposes five functions in an `AbstractConsensusRules` class:
+
+```python
+validate_transaction(bigchain, transaction)
+validate_block(bigchain, block)
+create_transaction(*args, **kwargs)
+sign_transaction(transaction, *args, **kwargs)
+verify_signature(transaction)
+```
+
+Together, these functions are sufficient for most customizations. For example:
+- Replace the crypto-system with one your hardware can accelerate
+- Re-implement an existing protocol
+- Delegate validation to another application
+- etc...
+
+
+## Extending BigchainDB behavior
+
+A default installation of BigchainDB will use the rules in the `BaseConsensusRules` class. If you only need to modify this behavior slightly, you can inherit from that class and call `super()` in any methods you change, so long as the return values remain the same.
+
+Here's a quick example of a plugin that adds nonsense rules:
 
 ```python
 from bigchaindb.consensus import BaseConsensusRules
@@ -22,6 +65,18 @@ class SillyConsensusRules(BaseConsensusRules):
         # I don't trust Alice, I think she's shady.
         if block['block']['node_pubkey'] == '<ALICE_PUBKEY>':
             raise StandardError("Alice is shady, everybody ignore her blocks!")
-
        return block
 ```
+
+
+## Packaging a plugin
+
+BigchainDB uses [setuptool's entry_point](https://pythonhosted.org/setuptools/setuptools.html) system to provide the plugin functionality. Any custom plugin needs to add this section to the `setup()` call in their `setup.py`:
+
+```python
+entry_points={
+    'bigchaindb.consensus': [
+        'PLUGIN_NAME=package.module:ConsensusRulesClass'
+    ]
+},
+```