more valdiation pool details

specification/docs/future-work.md

@@ -0,0 +1,4 @@
+## DAO Core Proposals
+
+Future work may include utilizing the process defined by the Proposal contract to govern features of the core contracts themselves. When a DAO is instantiated, a specific deployment of a Proposal contract can be designated as the official core DAO Proposal contract. DAO core contracts can utilize the designated Proposal contract to create and observe proposals. This process has not yet been demonstrated, and is currently hypothetical.
+ 

specification/docs/system-design.md

@@ -36,6 +36,8 @@ Reputation, Forum, and Bench can be considered core contracts. Together they pro
 
 Work, Proposal, and Rollup can be considered business logic. They allow the DAO to support arbitrarily complex use cases, according to its needs.
 
+[Future work](./future-work.md) may include utilizing the process defined by the Proposal contract to govern features of the core contracts themselves.
+
 ### Reputation
 
 We can achieve the requirements of the Reputation contract as follows:
@@ -58,11 +60,41 @@ To achieve the Bench requirements, the contract must do the following:
 
 1. Implement a method for initiating a Validation Pool (VP)
 
-    1. The caller should be able to provide an optional callback to be executed when the VP is concluded
-
 1. Implement a method for evaluating the outcome of a Validation Pool
 
-    1. If provided, the callback should be executed, and should be passed the results of the VP
+    1. The quorum is met if `(totalStakedFor + totalStakedAgainst) * quorum[denominator] >= totalSupply * quorum[numerator]`
+    
+    1. The vote passes if `totalStakedFor * winRatio[denominator] >= (totalStakedFor + totalStakedAgainst) * winRatio[numerator]`
+
+    1. If provided, `callbackOnValidate` should be executed, and should be passed the results of the VP.
+
+**`totalSupply`** refers to the total amount of REP held by all DAO members.
+
+**`ValdiationPoolResult`** Fields
+
+| Name | Type | 
+| --- | --- | 
+| `sender` | wallet address |
+| `votePasses` | boolean |
+| `quorumMet` | boolean |
+
+**`InitiateValidationPool`** Parameters
+
+| Name | Type | 
+| --- | --- | 
+| `postId` | string |
+| `duration` | positive integer number of seconds |
+| `quorum` | integer numerator, integer denominator |
+| `winRatio` | integer numerator, integer denominator |
+| `bindingPercent` | integer |
+| `redistributeLosingStakes` | boolean |
+| `callbackOnValidate` | function(`ValidationPoolResult`, `callbackData`) | Optional callback to be executed when the VP is concluded |
+| `callbackData` | bytes | Opaque data to be passed back to `callbackOnValidate` |
+
+    
+
+
+
 
 ### Forum
 
@@ -158,11 +190,9 @@ 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.
+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.
 
-### Forum API
-
-#### Write
+### Write
 
 Parameters
 
@@ -179,21 +209,25 @@ In order to protect the integrity of the off-chain Forum, the API should verify
 
 The API should compute a hash of all input parameters except for `references`, and use this hash as the key for storing the Post. The hash should also be returned to the caller.
 
-The reason for excluding `references` from the hash, is to support the use case of importing Posts from an existing data source. If we included the references, then to import any Posts from an existing data source, we would have to import every referenced post, starting with the earliest, in order to compute the entire tree of references made by a given Post. By omitting references from the hash, it becomes possible to precompute the hash (a.k.a. ID) of referenced Posts that have not yet been imported. 
+The reason for excluding `references` from the hash, is to support the use case of importing Posts from an existing data source. If we included the references, then to import any Posts from an existing data source, we would have to import every referenced Post, starting with the earliest, in order to compute the entire tree of references made by a given Post. By omitting references from the hash, it becomes possible to precompute the hash (a.k.a. ID) of referenced Posts that have not yet been imported. 
 
-The reason for excluding `references` from the signature, is to reduce the number of queries that must be made to an existing data source when importing a Post.
+The reason for excluding `references` from the signature, is to reduce the number of queries that must be made to an existing data source when importing a Post. (Specifically, when importing from the [Semantic Scholar API](https://api.semanticscholar.org/api-docs).) If we had to include the references in the signature, there is an "N + 1 problem" to the query pattern. For each paper, we would need to perform an additional query for each of its references. A single query can't ask for the references of the references of a paper.
 
-Note that because `references` is not included in the hash, there is a replay attack vulnerability. Someone could read an existing Post, modify the `references`, and write the modified Post back to the API. The signatures will still be valid even though the references have changed, and the new references will overwrite the previous references. Note that this would only affect the off-chain record of the Post's references. If the Post is published to the on-chain Forum, it is not subject to such modification, as a Post with a given ID can only be added once. To mitigate this vulnerabliity in the off-chain Forum, we should reject a write attempt if a Post with the given ID already exists.
+Note that because `references` is not included in the hash or signature, there is a replay attack vulnerability. Someone could read an existing Post, modify the `references`, and write the modified Post back to the API. The signatures will still be valid even though the references have changed, and the new references will overwrite the previous references. Note that this would only affect the off-chain record of the Post's references. If the Post is published to the on-chain Forum, it is not subject to such modification, as a Post with a given ID can only be added once. To mitigate this vulnerabliity in the off-chain Forum, we should reject a write attempt if a Post with the given ID already exists.
 
-When a Post is written, the Forum API should send an `io.dgov.forum.post` event to the Matrix room. Forum API nodes should listen for events of this type. When an `io.dgov.forum.post` event is received, each of the other Forum API nodes should write the Post to storage just just as they would if the `write` endpoint were called directly.
+When a Post is written, the Forum API should send an `io.dgov.forum.post` event to the Matrix room. Peer nodes should listen for events of this type from other peers. When an `io.dgov.forum.post` event is received, the recipient should write the Post to storage just as they would if the `write` endpoint were called directly.
 
 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.
 
 ## 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".
  
 ### Validation Pool
 
@@ -210,4 +244,4 @@ The `read` endpoint should accept a Post ID argument, and retrieve the correspon
 - Register Matrix Identity
 - Imprt from Semantic Scholar
 - Import from Matrix
-- Bot Commands
+- Bot Commands

specification/mkdocs.yml

@@ -19,4 +19,7 @@ nav:
   - Terminology: terminology.md
   - Requirements: requirements.md
   - System Design: system-design.md
-  - Implementation: implementation.md
+  - Implementation: 
+    - Ethereum Prototype: implementation-solidity.md
+    - Casper Production: implementation-casper.md
+  - Future Work: future-work.md