sys design: matrix pools

specification/docs/future-work.md

@@ -8,4 +8,7 @@ The process defined by the Proposal contract could be used to govern features of
 
 ### Ratio of Minted REP Staked For/Against
 
-The ratio of minted REP staked for and against a VP could be taken as a parameter or governed by a Proposal to increase the flexibility of the DAO.
+The ratio of minted REP staked for and against a VP could be taken as a parameter or governed by a Proposal to increase the flexibility of the DAO.
+
+## Chat REP
+

specification/docs/system-design.md

@@ -305,7 +305,7 @@ To achieve the Rollup requirements, the contract must do the following:
 | Name | Type |
 | --- | --- |
 | `batchPostId` | string |
-| `batchItems` | Array<string> |
+| `batchItems` | Array<`string`> |
 | `poolDuration` | integer |
 
 **`SubmitBatch`** Logic
@@ -330,6 +330,20 @@ To achieve the Rollup requirements, the contract must do the following:
 
 1. A new batch worker should be assigned.
 
+## 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". 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. For example, if a Work contract submits a VP targeting a particular Work Evidence Post, the Worker client must evaluate this post and determine if it qualifies as valid Work Evidence according to the rules of the DAO.
+
+### Rollup
+
+Each Worker client should compute the expected values for the Batch Post's authors and references, based on the outcomes of the Matrix Pools corresponding to each item in the batch. If the submitted Batch Post matches the expectation, the Worker client should stake in favor of the Batch Post VP. Otherwise, it should stake against the VP.
+
 ## Off-chain Operations
 
 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.
@@ -339,6 +353,7 @@ Matrix implements a layer of encryption and identity management. We define an id
 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
@@ -370,26 +385,91 @@ Each Forum API node should keep track of the most recent `io.dgov.forum.post` ev
 
 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
 
+We can use Matrix events to carry out a variation of a Validation Pool, which we call a Matrix Pool. The main difference is that we don't have a native fungible currency in Matrix. Therefore Matrix Pools do not require a fee, and do not mint Reputation.
 
+In principle, we could define rules governing a Chat REP, that is distinct from our on-chain REP. However, the rules for governing such a Chat REP are not obvious. It would have the fundamental challenge that there is nothing truly at stake, since Chat REP would not be backed by fungible currency. Therefor we defer Chat REP for [future work](./future-work.md).
 
+Since Matrix Pools have no direct power over on-chain Reputation, Matrix Pools are always non-binding, meaning that Members who stake on the losing side of a Matrix Pool do not lose the staked REP. This is in contrast to on-chain Validation Pools, which may be anywhere from 0 to 100% binding.
 
-## Automated Staking
+The main use case for Matrix Pools is in the context of the Rollup process. Rather than initiate an on-chain VP, a contract may add an item to the Rollup batch queue. The Rollup batch worker initiates a Matrix Pool for each of these items. Then, when the batch interval has elapsed, the Batch Worker submits a Batch Post whose authorship is determined by the outcomes of the corresponding Matrix Pools for the included batch items.
 
-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.
+Like on-chain VPs, Matrix Pools have three operations: Initiate Pool, Stake, and Evaluate Outcome. All Worker clients which intend to participate in the on-chain VP targeting the next Batch Post should listen for and handle these messages.
 
-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
+#### Initiate
 
-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 
+To initiate a Matrix Pool, a Member may send an `io.dgov.pool.start` event.
 
-### Rollup
+**`io.dgov.pool.start`** Properties
+
+| Name | Type |
+| --- | --- |
+| `postId` | string |
+| `sender` | contract address |
+| `fee` | integer |
+| `duration` | integer |
+| `quorum` | [integer numerator, integer denominator] |
+| `winRatio` | [integer numerator, integer denominator] |
+
+#### Stake
+
+To register a stake, a Member may send an `io.dgov.pool.stake` event.
+
+**`io.dgov.pool.stake`** Properties
+
+| Name | Type |
+| --- | --- |
+| `postId` | string |
+| `amount` | integer |
+| `inFavor` | boolean |
+
+The stake should be accepted only if the following conditions are met:
+
+1. It is sent before the Matrix Pool duration has elapsed.
+
+1. The Member who sends the stake has an on-chain REP balance greater than or equal to the staked amount.
+
+#### Evaluate Outcome
+
+When the Matrix Pool duration has elapsed, the current Batch Worker should evaluate the outcome and send an `io.dgov.pool.result` event.
+
+**`io.dgov.pool.result`** Properties
+
+| Name | Type |
+| --- | --- |
+| `postId` | string |
+| `result` | `Result` object |
+
+**`Result`** Properties
+
+| Name | Type |
+| --- | --- |
+| `stakedFor` | integer |
+| `stakedAgainst` | integer |
+| `totalSupply` | integer |
+| `votePasses` | integer |
+| `quorumMet` | integer |
+
+This message provides an opportunity for other Workers to compute their own expected result for the Matrix Pool and verify the result provided by the Batch Worker. If there is a discrepancy, it can be logged and reported for investigation.
+
+### Register Identity
+
+A client may send an `io.dgov.identity.register` event via Matrix. 
+
+1. This event should include a message signed by the sender's wallet. 
+
+    1. To prevent replay attacks, the signed message should include the Matrix user ID of the sender.
+
+1. All Forum nodes should receive this message and do the following:
+
+    1. Verify the signature, extracting the sender's wallet address
+
+    1. Verify that the signed message contains the sender's Matrix user ID
+
+    1. Store a record associating the given Matrix user ID with the given wallet address
+
+Once this has been performed, messages from the given Matrix user can be attributed to the given wallet address.
 
 ## User Interface