add user stories section

specification/docs/implementation-solidity.md

@@ -13,5 +13,11 @@ flowchart TD
 
 ## Contracts
 
+### DAO
+
+We introduce a DAO contract which estabishs the public interface of the DAO core, and provides a context within which the core contracts may securely call each other.
+
+Each of the core contracts must first be deployed. Then the DAO contract is deployed, and for each core contract, makes the first and only call to `registerDAO` to set the address of the DAO contract. All calls are then mediated by the DAO contract's public interface. This enables us to enforce the security of the core contracts.
+
 ### Bench
 

specification/docs/system-design.md

@@ -217,9 +217,14 @@ To achieve the Rollup requirements, the contract must do the following:
 
 ## Off-chain Operations
 
-As outlined in the Rollup section above, we need to define processes for handling off-chain Posts and Validation Pools. On-chain, Posts are represented by a unique identifier, but the Post content is always stored off-chain. So, every on-chain Post must have a corresponding off-chain Post. These off-chain posts should be visible to the public. To achieve this, we introduce a Forum API, that supports writing and reading off-chain Posts. Moreover, each Forum API instance must also function as a Matrix client to send, receive, and query for messages.
+As outlined in the Rollup section above, we need to define processes for handling off-chain Posts and Validation Pools. Posts are represented by a unique identifier on-chain, but the Post content is stored off-chain. So, every on-chain Post must have a corresponding off-chain Post. These off-chain posts should be visible to the public. To achieve this, we introduce a Forum API, for supporting web clients in reading and writing posts. We use Matrix as the off-chain forum database. Each Forum API instance will read the history and receive new posts using the Matrix client-server protocol.
 
-### Write
+Matrix implements a layer of encryption and identity management. We define an identity registration process, whereby a Matrix user may send a signed message asserting their wallet address. Messages from this Matrix user can then be attributed to their wallet address, and their on-chain REP can be verified as needed.
+
+As mentioned above, Matrix serves as the Forum database. For this we use `io.dgov.forum.post` events. We can also use Matrix to conduct off-chain Validation Pools. For this we use `io.dgov.pool.start`, `io.dgov.pool.stake`, and `io.dgov.pool.result` events.
+
+### Forum API
+#### Write
 
 Parameters
 
@@ -246,18 +251,29 @@ When a Post is written, the Forum API should send an `io.dgov.forum.post` event
 
 Each Forum API node should keep track of the most recent `io.dgov.forum.post` event received. On startup, each Forum API node should query the Matrix Homeserver for any newer `io.dgov.forum.post` events.
 
-### Read
+#### Read
 
 The `read` endpoint should accept a Post ID argument, and retrieve the corresponding Post from storage. Before sending the Post to the caller, the Forum API should verify the hash and signature, to ensure the integrity of the record.
 
+### Register Identity
+
+### Chat REP
+
+### Matrix Pools
+
+
+
+
 ## Automated Staking
 
 To achieve the Autonomy requirement for the DAO, Validation Pools targeting Work Evidence Posts or Rollup Posts should be automatically validated, without human intervention. This means the rules for validating a given VP and its target Post must be represented in code.
 
-Our prototype demonstrates the simplest possible type of rule that can be applied: a Work Evidence Post is considered valid if it starts with a specific string, "This is a work evidence post".
+Our prototype demonstrates the simplest possible type of rule that can be applied: a Work Evidence Post is considered valid if it starts with a specific string, "This is a work evidence post". Another type of evidence we can consider is signatures from the customer, from the worker, or from reviewers. 
  
 ### Validation Pool
 
+The client that each worker operates should be prepared to render a decision on each Executive Validation Pool within its specified duration. An example of such a VP is a work contract which submits a VP for each work request once completed. The client must be able to execute 
+
 ### Rollup
 
 ## User Interface
@@ -266,9 +282,12 @@ Our prototype demonstrates the simplest possible type of rule that can be applie
 
 ### Widget
 
+
+
+
+
 ## Other
 
-- Register Matrix Identity
 - Imprt from Semantic Scholar
 - Import from Matrix
 - Bot Commands

specification/docs/user-stories.md

@@ -0,0 +1,14 @@
+## Experts start a new DAO
+
+## New member joins a DAO
+
+## DAO member defines a new Work Contract
+
+## Customer engages a Work Contract
+
+## Contract triggers a dispute resolution process
+
+## DAO changes the price of a Work Contract
+
+## DAO upgrades the soft protocol
+

specification/mkdocs.yml

@@ -19,6 +19,7 @@ nav:
   - Terminology: terminology.md
   - Requirements: requirements.md
   - System Design: system-design.md
+  - User Stories: user-stories.md
   - Implementation: 
     - Ethereum Prototype: implementation-solidity.md
     - Casper Production: implementation-casper.md