x 3 vuotta sitten
vanhempi
sitoutus
bd0aa50ed5

+ 36 - 39
doc/src/SUMMARY.md

@@ -5,9 +5,9 @@
   - [Ideology](philosophy/ideology.md)
   - [Ideology](philosophy/ideology.md)
   - [Recommended Books](philosophy/recommended-books.md)
   - [Recommended Books](philosophy/recommended-books.md)
   - [Reading Maths Books](philosophy/reading-maths-books.md)
   - [Reading Maths Books](philosophy/reading-maths-books.md)
+- [Start Here: Testnet Guide](testnet/guide.md)
 - [Development](development/development.md)
 - [Development](development/development.md)
   - [Maintenance](development/maintenance.md)
   - [Maintenance](development/maintenance.md)
-- [Port ranges](portranges.md)
 - [Architecture](architecture/architecture.md)
 - [Architecture](architecture/architecture.md)
   - [Overview](architecture/overview.md)
   - [Overview](architecture/overview.md)
   - [Anonymous Assets](architecture/anonymous_assets.md)
   - [Anonymous Assets](architecture/anonymous_assets.md)
@@ -16,15 +16,46 @@
   - [Transactions](architecture/tx_lifetime.md)
   - [Transactions](architecture/tx_lifetime.md)
   - [Smart Contracts](architecture/smart_contracts.md)
   - [Smart Contracts](architecture/smart_contracts.md)
   - [Tooling](architecture/tooling.md)
   - [Tooling](architecture/tooling.md)
-- [Client](clients/clients.md)
-  - [darkfid JSON-RPC API](clients/darkfid_jsonrpc.md)
-  - [cashierd JSON-RPC API](clients/cashierd_jsonrpc.md)
-  - [faucetd JSON-RPC API](clients/faucetd_jsonrpc.md)
 - [zkas](zkas/index.md)
 - [zkas](zkas/index.md)
   - [Bincode](zkas/bincode.md)
   - [Bincode](zkas/bincode.md)
   - [Examples](zkas/examples.md)
   - [Examples](zkas/examples.md)
     - [Sapling scheme](zkas/examples/sapling.md)
     - [Sapling scheme](zkas/examples/sapling.md)
     - [Anonymous voting](zkas/examples/voting.md)
     - [Anonymous voting](zkas/examples/voting.md)
+- [Crypto](crypto/crypto.md)
+  - [FFT](crypto/fft.md)
+  - [ZK explainer](crypto/zk_explainer.md)
+  - [Research](crypto/research.md)
+- [p2p Api Tutorial](learn/dchat/dchat.md)
+  - [Deployment](learn/dchat/deployment/part-1.md)
+    - [Getting started](learn/dchat/deployment/getting-started.md)
+    - [Writing a daemon](learn/dchat/deployment/writing-a-daemon.md)
+    - [Sessions](learn/dchat/deployment/sessions.md)
+    - [Settings](learn/dchat/deployment/settings.md)
+    - [Error handling](learn/dchat/deployment/error-handling.md)
+    - [Start-Run-Stop](learn/dchat/deployment/start-run-stop.md)
+    - [Seed](learn/dchat/deployment/seed-node.md)
+    - [Deploy](learn/dchat/deployment/deploy.md)
+  - [Creating dchat](learn/dchat/creating-dchat/part-2.md)
+    - [Message](learn/dchat/creating-dchat/message.md)
+    - [Protocols](learn/dchat/creating-dchat/protocols.md)
+    - [ProtocolDchat](learn/dchat/creating-dchat/protocol-dchat.md)
+    - [Register protocol](learn/dchat/creating-dchat/register-protocol.md)
+    - [Sending messages](learn/dchat/creating-dchat/sending-messages.md)
+    - [Slap on a UI](learn/dchat/creating-dchat/ui.md)
+    - [Using dchat](learn/dchat/creating-dchat/using-dchat.md)
+  - [Net tools](learn/dchat/network-tools/part-3.md)
+    - [RPC interface](learn/dchat/network-tools/rpc.md)
+    - [Accept addr](learn/dchat/network-tools/accept-addr.md)
+    - [Adding methods](learn/dchat/network-tools/pong.md)
+    - [RPC server](learn/dchat/network-tools/server.md)
+    - [get_info](learn/dchat/network-tools/get-info.md)
+    - [Using dnetview](learn/dchat/network-tools/using-dnetview.md)
+    - [Debugging](learn/dchat/network-tools/debug.md)
+- [Client](clients/clients.md)
+  - [darkfid JSON-RPC API](clients/darkfid_jsonrpc.md)
+  - [cashierd JSON-RPC API](clients/cashierd_jsonrpc.md)
+  - [faucetd JSON-RPC API](clients/faucetd_jsonrpc.md)
+  - [Port ranges](clients/portranges.md)
 - [Miscellaneous tools](misc/misc.md)
 - [Miscellaneous tools](misc/misc.md)
   - [vanityaddr](misc/vanityaddr.md)
   - [vanityaddr](misc/vanityaddr.md)
   - [ircd](misc/ircd/ircd.md)
   - [ircd](misc/ircd/ircd.md)
@@ -33,40 +64,6 @@
   - [tau](misc/tau.md)
   - [tau](misc/tau.md)
   - [event_graph](misc/event_graph/event_graph.md)
   - [event_graph](misc/event_graph/event_graph.md)
     - [Network Protocol](misc/event_graph/network_protocol.md)
     - [Network Protocol](misc/event_graph/network_protocol.md)
-  - [HashChain](misc/hashchain/hashchain.md)
-  	- [Network Protocol](misc/hashchain/network_protocol.md)
   - [darkwiki](misc/darkwiki.md)
   - [darkwiki](misc/darkwiki.md)
   - [dnetview](misc/dnetview.md)
   - [dnetview](misc/dnetview.md)
-- [Crypto](crypto/crypto.md)
-  - [FFT](crypto/fft.md)
-- [Testnet Guide](testnet/guide.md)
-- [Learn](learn/learn.md)
-  - [Research](learn/research.md)
-  - [ZK explainer](learn/zk_explainer.md)
-  - [Dchat](learn/dchat/dchat.md)
-    - [Deployment](learn/dchat/deployment/part-1.md)
-      - [Getting started](learn/dchat/deployment/getting-started.md)
-      - [Writing a daemon](learn/dchat/deployment/writing-a-daemon.md)
-      - [Sessions](learn/dchat/deployment/sessions.md)
-      - [Settings](learn/dchat/deployment/settings.md)
-      - [Error handling](learn/dchat/deployment/error-handling.md)
-      - [Start-Run-Stop](learn/dchat/deployment/start-run-stop.md)
-      - [Seed](learn/dchat/deployment/seed-node.md)
-      - [Deploy](learn/dchat/deployment/deploy.md)
-    - [Creating dchat](learn/dchat/creating-dchat/part-2.md)
-      - [Message](learn/dchat/creating-dchat/message.md)
-      - [Protocols](learn/dchat/creating-dchat/protocols.md)
-      - [ProtocolDchat](learn/dchat/creating-dchat/protocol-dchat.md)
-      - [Register protocol](learn/dchat/creating-dchat/register-protocol.md)
-      - [Sending messages](learn/dchat/creating-dchat/sending-messages.md)
-      - [Slap on a UI](learn/dchat/creating-dchat/ui.md)
-      - [Using dchat](learn/dchat/creating-dchat/using-dchat.md)
-    - [Net tools](learn/dchat/network-tools/part-3.md)
-      - [RPC interface](learn/dchat/network-tools/rpc.md)
-      - [Accept addr](learn/dchat/network-tools/accept-addr.md)
-      - [Adding methods](learn/dchat/network-tools/pong.md)
-      - [RPC server](learn/dchat/network-tools/server.md)
-      - [get_info](learn/dchat/network-tools/get-info.md)
-      - [Using dnetview](learn/dchat/network-tools/using-dnetview.md)
-      - [Debugging](learn/dchat/network-tools/debug.md)
 
 

+ 0 - 0
doc/src/portranges.md → doc/src/clients/portranges.md


+ 0 - 0
doc/src/learn/research.md → doc/src/crypto/research.md


+ 19 - 25
doc/src/development/maintenance.md

@@ -2,28 +2,22 @@
 There are several areas of work that are either undergoing maintenance 
 There are several areas of work that are either undergoing maintenance 
 or need to be maintained:
 or need to be maintained:
 
 
-**Documentation:** general documentation and code docs (cargo doc). this is a very 
-important work for example [overview](https://darkrenaissance.github.io/darkfi/architecture/overview.html) 
-page is out of date.
-
-**Tooling:** Such as the `drk` tool. right now 
-we're adding [DAO functionality](https://github.com/darkrenaissance/darkfi/blob/master/src/contract/dao/wallet.sql) 
-to it.
-
-**Tests:** Throughout the project there are either broken or commented out unit tests, they need to be fixed.
-
-**Cleanup:** General code cleanup. for example flattening headers and improving things like in 
-[this commit](https://github.com/darkrenaissance/darkfi/commit/9cd9c3113eed1b5f0bcad2ee449ef926d0908d55).
-
-**ZK Debugger:** The ZKVM needs a debugger so we can interactively inspect values 
-at each step to see where problems go wrong.
-
-**ZK Special Tool:** We need a special tool to run zk contracts, where you can create 
-a json file with the input values and public values, then run the zk 
-contract without having to write any rust code. so you can write .zk 
-files and try them out without having to write rust code. It will tell 
-you the time to create and verify the proof, as well as the byte size of 
-the proof.
-
-**Events System:** We need to fix IRCD, we will need to implement the 
-[events](https://darkrenaissance.github.io/darkfi/misc/event_graph/event_graph.html) system.
+* **Documentation:** general documentation and code docs (cargo doc). this is a very 
+  important work for example [overview](https://darkrenaissance.github.io/darkfi/architecture/overview.html) 
+  page is out of date.
+* **Tooling:** Such as the `drk` tool. right now 
+  we're adding [DAO functionality](https://github.com/darkrenaissance/darkfi/blob/master/src/contract/dao/wallet.sql) 
+  to it.
+* **Tests:** Throughout the project there are either broken or commented out unit tests, they need to be fixed.
+* **Cleanup:** General code cleanup. for example flattening headers and improving things like in 
+  [this commit](https://github.com/darkrenaissance/darkfi/commit/9cd9c3113eed1b5f0bcad2ee449ef926d0908d55).
+* **ZK Debugger:** The ZKVM needs a debugger so we can interactively inspect values 
+  at each step to see where problems go wrong.
+* **ZK Special Tool:** We need a special tool to run zk contracts, where you can create 
+  a json file with the input values and public values, then run the zk 
+  contract without having to write any rust code. so you can write .zk 
+  files and try them out without having to write rust code. It will tell 
+  you the time to create and verify the proof, as well as the byte size of 
+  the proof.
+* **Events System:** We need to fix IRCD, we will need to implement the 
+  [events](https://darkrenaissance.github.io/darkfi/misc/event_graph/event_graph.html) system.

+ 0 - 112
doc/src/learn/zk_explainer.md

@@ -1,112 +0,0 @@
-# Zero-knowledge explainer
-
-We start with this algorithm as an example:
-
-```python
-def foo(w, a, b):
-    if w:
-        return a * b
-    else:
-        return a + b
-```
-
-ZK code consists of lines of constraints. It has no concept of
-branching conditionals or loops.
-
-So our first task is to flatten (convert) the above code to a linear
-equation that can be evaluated in ZK.
-
-Consider an interesting fact. For any value $\mathbb{x}$, then
-$(1 - w) = 0$ if and only if $x = 1$.
-
-In our code above $w$ is a binary value. It's value is either $1$
-or $0$. We make use of this fact by the following:
-
-1. $w = 1$ when $w = 1$
-2. $(1 - w) = 1$ when $w = 0$. If $w = 1$ then the expression is $0$.
-
-So we can rewrite `foo(w, a, b)` as the mathematical function
-
-$$f(w, a, b) = w(ab) + (1 - w)(a + b)$$
-
-We now can convert this expression to a constraint system.
-
-ZK statements take the form of:
-$$(c_{l,1} \cdot v_{l,1} + c_{a,2} \cdot v_{l,2} + \dots) \times (c_{b,1} \cdot v_{r,1} + c_{b,2} \cdot v_{r,2} + \dots) = (c_{o,1} \cdot v_{o,1} + c_{o,2} v_{o,2} + \dots)$$
-
-More succinctly as:
-$$\sum_{i = 1}^n c_{l,i} \cdot v_{l,i} \times \sum_{i = 1}^n c_{r,i} v_{r, i} = \sum_{i = 1}^n c_{o, i} v_{o, i}$$
-
-These statements are converted into polynomials of the form:
-$$L(x) \times R(x) - O(x) = t(x)h(x)$$
-
-$t(x)$ is the target polynomial and in our case will be
-$(x - 1)(x - 2)(x - 3)$. $h(x)$ is the cofactor polynomial. The
-statement says that the polynomial $L(x) \times R(x) - O(x)$ has roots
-(is equal to zero) at the points when $x \in {1, 2, 3}$.
-
-Earlier we wrote our mathematical statement which we will now convert
-to constraints.
-
-$$f(w, a, b) = w(ab) + (1 - w)(a + b)$$
-
-Rearranging the equation, we note that:
-
-$$ v = w(ab) + (1 - w)(a + b) $$
-$$   = w(ab) + a + b - w(a + b) $$
-
-Swapping and rearranging, our final statement becomes
-$w(ab - a - b) = v - a - b$. Represented in ZK as:
-
-$$ ab = m $$
-$$ w(m - a - b) = v - a - b $$
-$$ w^2 = w $$
-
-The last line is a boolean constraint that $w$ is either $0$ or $1$ by
-enforcing that $w(w - 1) = 0$ (re-arranged this is $w \cdot w = w$).
-
-| Line      | L(x)               | R(x)                                        | O(x)                                        |
-|-----------|--------------------|---------------------------------------------|---------------------------------------------|
-| 1         | $(1\cdot a)$       | $(1 \cdot b)$                               | $(1 \cdot m)$                               |
-| 2         | $(1 \cdot w)$      | $(1 \cdot m + (-1) \cdot a + (-1) \cdot b)$ | $(1 \cdot v + (-1) \cdot a + (-1) \cdot b)$ |
-| 3         | $(1 \cdot w)$      | $(1 \cdot w)$                               | $(1 \cdot w)$                               |
-
-Because of how the polynomials are created during the setup phase, you
-must supply them with the correct variables that satisfy these
-constraints, so that $L(1) \times R(1) - O(1) = 0$ (line 1),
-$L(2) \times R(2) - O(2) = 0$ (line 2) and
-$L(3) \times R(3) - O(3) = 0$ (line 3).
-
-Each one of $L(x)$, $R(x)$ and $O(x)$ is supplied a list of
-(constant coefficient, variable value) pairs.
-
-In bellman library, the constant is a fixed value of type `Scalar`.
-The variable is a type called `Variable`. These are the values fed
-into `lc0` (the 'left' polynomial), `lc1` (the 'right' polynomial),
-and `lc2` (the 'out' polynomial).
-
-In our example we had a function $f(w, a, b)$ where for example $f(1, 4, 2) = 8$.
-The verifier does not know the variables $w = 1$, $a = 4$
-and $b = 2$ which are *allocated* by the prover as *variables*. However
-the verifier does know the coefficients (which are of the `Scalar`
-type) shown in the table above. In our example they only either $1$
-or $-1$, but can also be other constant values.
-
-```rust
-pub struct LinearCombination<Scalar: PrimeField>(Vec<(Variable, Scalar)>);
-```
-
-It is important to note that each one of the left, right and out
-registers is simply a list of tuples of (constant coefficient,
-variable value).
-
-When we wish to add a constant value, we use the variable called
-`~one` (which is always the first automatically allocated variable in
-bellman at index 0). Therefore we end up adding our constant $c$ to
-the `LinearCombination` as `(c, ~one)`.
-
-Any other non-constant value, we wish to add to our constraint system
-*must* be allocated as a variable. Then the variable is added to the
-`LinearCombination`. So in our example, we will allocate
-$w, a, b, m, v$, getting back `Variable` objects which we then add to
-the left lc, right lc or output lc.

+ 0 - 5
doc/src/misc/dnetview.md

@@ -8,11 +8,6 @@ dnetview displays:
 2. outgoing, incoming and manual sessions
 2. outgoing, incoming and manual sessions
 3. each associated connection and recent messages.
 3. each associated connection and recent messages.
 
 
-dnetview is based on the design-pattern Model, View, Controller. We
-create a logical separation between the underlying data structure or
-Model; the ui rendering aspect which is the View; and the Controller or
-game engine that makes everything run.
-
 ## Install 
 ## Install 
 
 
 ```shell
 ```shell

+ 0 - 106
doc/src/misc/hashchain/hashchain.md

@@ -1,106 +0,0 @@
-# Structures
-
-## EventId
-
-Hash of `Event`
-
-```rust
-type EventId = [u8; 32];
-```
-
-## EventAction
-
-The `Event` could have many actions according to the underlying data.
-
-```rust
-enum EventAction { ... };
-```
-
-## Event
-
-| Description            | Data Type      | Comments                    |
-| ---------------------- | -------------- | --------------------------- |
-| previous_event_hash    | `EventId`      | Hash of the previous `Event`|
-| action                 | `EventAction`  | `Event`'s action            |
-| timestamp              | u64            | `Event`'s timestamp         |
-
-## EventNode
-
-| Description    | Data Type              | Comments                                              |
-| -------------- | ---------------------- | ----------------------------------------------------- |
-| parent         | Option<`EventId`>      | Only current root has this set to None                |
-| event          | `Event`                | The `Event` itself                                    |
-| children       | Vec<`EventId`>         | The `Event`s which has parent as this `Event` hash    |
-
-## Model
-
-The `Model` consists of chains (`EventNodes`) structured as a tree;
-whereby, each chain has an `Event`-based list. To maintain a strict
-order of chains, each `Event` depends on the hash of the previous
-`Event`. All of the chains share a root `Event` to preserve the tree
-structure.
-
-| Description   | Data Type                        | Comments                      |
-| ------------- | -------------------------------- | ----------------------------- |
-| current_root  | `EventId`                        | The root `Event` for the tree |
-| orphans       | HashMap<`EventId`, `Event`>      | Recently added `Event`s       |
-| event_map     | HashMap<`EventId`, `EventNode`>  | The actual tree               |
-| events_queue  | `EventsQueue`                    | Communication channel         |
-
-## View
-
-The `View` checks the `Model` for new `Event`s and then dispatches
-these `Event`s to the clients.
-
-`Event`s are sorted according to the timestamp attached to each
-`Event`.
-
-| Description   | Data Type                     | Comments               |
-| ------------- | ----------------------------- | ---------------------- |
-| seen          | HashMap<`EventId`, `Event`>   | A list of `Event`s     |
-
-## EventsQueue
-
-The `EventsQueue` used to transport the event from `Model` to `View`.
-
-The `Model` fills the `EventsQueue` with the new `Event`, while the
-`View` continuously fetches `Event`s from queue.
-
-# Architecture
-
-Tau uses Model–view software architecture. All of the operations, main
-data structures, and message handling from the network protocol happen
-on the `Model` side. Further, this keeps the `View` independent of the
-`Model` and allows the `View` to focus on receiving continuous updates
-from it.
-
-## Add new `Event`
-
-Upon receiving a new `Event` from the network protocol, the `Event`
-will be added to the orphans list.
-
-After the ancestor of the new orphan is found, the orphan `Event` will
-be added to the chain according to its ancestor.
-
-For example: in [Example1](#example1) below, an `Event` is added to the
-first chain if its previous hash is Event-A1.
-
-## Remove old leaves
-
-Remove leaves which are too far from the head leaf (the leaf in the
-longest chain).
-
-The depth difference from the common ancestor between a leaf to be
-removed and a head leaf must be greater than `MAX_DEPTH`.
-
-## Update the root
-
-Finding the highest common ancestor for the leaves and assign it as the
-root for the tree.
-
-The highest common ancestor must have a height greater than
-`MAX_HEIGHT`.
-
-## Example1
-
-![data structure](../../assets/mv_event.png)

+ 0 - 134
doc/src/misc/hashchain/network_protocol.md

@@ -1,134 +0,0 @@
-# Network Protocol
-
-The protocol checks that `Event`s properly broadcast through the
-network before adding `Event`s to the `Model`.
-
-The read_confirms inside each `Event` indicate how many times the
-`Event` has been read from other nodes in the network.
-
-The protocol classifies the `Event`s by their state:
-
-```text
-Unread: read_confirms < MAX_CONFIRMS
-Read:	read_confirms >= MAX_CONFIRMS
-```
-
-## Inv
-
-Inventory vectors notify other nodes about objects they have or data
-which is being requested.
-
-| Description   | Data Type            | Comments                   |
-| ------------- | -------------------- | -------------------------- |
-| invs          | `Vec<[u8; 32]>`      | Inventory items            |
-
-### Receiving an `Inv` message
-
-Allows a node to advertise its knowledge of one or more objects. It can
-be received unsolicited or in reply to `getevents`.
-
-An `Inv` message is a confirmation from a node in the network that the
-`Event` has been read.
-
-Confirmation for an `Event` does not exist in the `UnreadEvents` list.
-Instead, the protocol sends a `GetData` message to request the missing
-`Event`.
-
-The protocol updates the `Event` in the `UnreadEvents` list by
-increasing the read_confirms by one.
-
-The updated `Event` state changes to read when the read_confirms exceed
-`MAX_CONFIRMS`. Then, the `UnreadEvents` list removes the `Event` and
-adds it to the `Model`.
-
-The protocol rebroadcasts the received `Inv` to the network.
-
-### Sending an `Inv` message
-
-Upon receiving an `Event` with unread status from the network, the
-protocol sends back an `Inv` message to confirm that the `Event` has
-been read.
-
-## GetData
-
-| Description   | Data Type            | Comments                   |
-| ------------- | -------------------- | -------------------------- |
-| events        | Vec<`EventId`>       | A list of `EventId`s       |
-
-### Receiving a `GetData` message
-
-The protocol searches in both `Model` and `UnreadEvents` for the
-requested `Event`s in `GetData` message.
-
-## UnreadEvents
-
-| Description | Data Type                   | Comments                                                                             |
-| ------------| --------------------------- | ------------------------------------------------------------------------------------ |
-| Messages    | HashMap<`EventId`, `Event`> | Hold all the `Event`s that have broadcasted to other nodes but haven't confirmed yet |
-
-### Add new `Event` to `UnreadEvents`
-
-To add an `Event` to `UnreadEvents`, the protocol first must check the
- validity of `Event`.
-
-The `Event` is not valid in the network if it's either too far in the
-future or in the past.
-
-### Updating `UnreadEvents` list
-
-The protocol continuously broadcasts unread `Event`s to the network,
-after a certain period of time (`SEND_UNREAD_EVENTS_INTERVAL`),
-until the state of `Event` updates to read.
-
-## SyncEvent
-
-| Description | Data Type       | Comments                      |
-| ------------| --------------- | ----------------------------- |
-| Leaves      | Vec<`EventId`>  | Hash of `Event`s              |
-
-### Synchronization
-
-To achieve complete synchronization between nodes, the protocol sends a
-`SyncEvent` message every 2 seconds to other nodes in the network.
-
-The `SyncEvent` contains the hashes of `Event`s set in the leaves of
-`Model`'s tree.
-
-On receiving `SyncEvent` message, the leaves in `SyncEvent` should
-match the leaves in the `Model`'s tree; otherwise, the protocol sends
-`Event`s which are the children of `Event`s in `SyncEvent`.
-
-## Seen
-
-This prevents receiving duplicate objects.
-The list contains only 2^16 ids.
-
-| Description | Data Type       | Comments                      |
-| ----------- | --------------- | ----------------------------- |
-| Ids         | Vec<`ObjectId`> | Contains objects ids          |
-
-## Receiving a new `Event`
-
-The new received `Event` with unread status is added to the
-`UnreadEvents` buffer after increasing the read_confirms by one.
-
-The `Event` with read status is added to the `Model`.
-
-The protocol broadcasts the received `Event` to the network, again.
-This ensures all nodes in the network get the Event.
-
-## Sending an `Event`
-
-A new created `Event` has unread status with read_confirms equal to 0.
-
-The protocol broadcasts the `Event` to the network after adding it to
-the `UnreadEvents`.
-
-## Add new `Event` to `Model`
-
-For the `Event` to be successfully added to the `Model`, the protocol
-checks if the previous `Event`'s hash inside the `Event` exists in the
-`Model`.
-
-In case the previous `Event` check fails, the protocol
-sends a `GetData` message requesting the previous `Event`.

+ 28 - 31
doc/src/misc/tau.md

@@ -59,18 +59,22 @@ To run your own instance check [Local Deployment](#local-deployment)
 
 
 #### Add tasks
 #### Add tasks
 
 
-```shell
-% tau add Review tau usage desc:description	# will add a new task named
-%						# "Review tau usage" with
-%						# "description" in its desc filed
-% tau add Second task assign:dave 	# will add a new task and assign it
-%					# to "dave".
-%					# Note: not having "desc:" key
-% 					# will pop up your OS editor
-%					# configured in \$EDITOR env var,
-%					# this is recommended for
-%					# formatting reasons and
-%					# will be used through this demo.
+Add a new task with the title "review tau usage" with the description text
+"description" set to "review tau".
+
+```bash
+tau add review tau usage "desc:review tau"
+```
+
+Add another task with the title "second task" assigned to dave.
+Because no description is set, it will open your EDITOR and prompt you
+for a description which allows entering multiline text.
+
+```bash
+tau add second task @dave
+```
+
+```
 % tau add Third task project:tau rank:1.1
 % tau add Third task project:tau rank:1.1
 % tau add Fourth task assign:dave project:tau due:1509 rank:2.5
 % tau add Fourth task assign:dave project:tau due:1509 rank:2.5
 % tau add Five
 % tau add Five
@@ -144,10 +148,8 @@ connect to when they first connect to the network. The `seed_session` simply
 connects to a seed node and runs `protocol_seed`, which requests a list of
 connects to a seed node and runs `protocol_seed`, which requests a list of
 addresses from the seed node and disconnects straight after receiving them.
 addresses from the seed node and disconnects straight after receiving them.
 
 
-	in config file:
-
-		## P2P accept addresses
-		inbound=["127.0.0.1:11001"] 
+    # P2P accept addresses
+    inbound=["127.0.0.1:11001"] 
 
 
 Note that the above config doesn't specify an external address since the
 Note that the above config doesn't specify an external address since the
 seed node shouldn't be advertised in the list of connectable nodes. The seed
 seed node shouldn't be advertised in the list of connectable nodes. The seed
@@ -161,16 +163,14 @@ making any outbound connections.
 
 
 The external addresses are important and must be correct.
 The external addresses are important and must be correct.
 
 
-	in config file:
-		
-		## P2P accept addresses
-		inbound=["127.0.0.1:11002"]
-		
-		## P2P external addresses
-		external_addr=["127.0.0.1:11002"]
+    # P2P accept addresses
+    inbound=["127.0.0.1:11002"]
+    
+    # P2P external addresses
+    external_addr=["127.0.0.1:11002"]
 
 
-		## Seed nodes to connect to 
-		seeds=["127.0.0.1:11001"]
+    # Seed nodes to connect to 
+    seeds=["127.0.0.1:11001"]
 
 
 ### Outbound Node
 ### Outbound Node
 
 
@@ -178,11 +178,8 @@ This is a node which has 8 outbound connection slots and no inbound connections.
 This means the node has 8 slots which will actively search for unique nodes to
 This means the node has 8 slots which will actively search for unique nodes to
 connect to in the p2p network.
 connect to in the p2p network.
 
 
-	in config file:
-
-		## Connection slots
-		outbound_connections=8
-
-		## Seed nodes to connect to 
+    # Connection slots
+    outbound_connections=8
 
 
+    # Seed nodes to connect to