system design for contracts

specification/docs/requirements.md

@@ -84,12 +84,18 @@ The day to day operations of a DAO are centered around Work Smart Contracts (WSC
 
 1. A Customer may submit a request for work to the WSC, including a fee and any necessary request details.
 
+    1. The work must be assigned to an available worker
+    
+    1. The worker may be chosen by random weighted selection, weighted by the amount of REP each worker staked toward their availability.
+
 1. The assigned Worker must submit a Work Evidence Post to the WSC, providing any necessary supporting information to verify that the work was performed correctly.
 
 1. The Customer must submit approval/disapproval of the work to the WSC.
 
 1. The Staking Clients must verify the work evidence, and stake for/against a Validation Pool targeting the Work Evidence Post.
 
+    1. This Validation Pool may target a single WEV Post, or multile WEV Posts (see Rollup section, below).
+
 ### Legislative
 
 The DAO will need to be able to update the rules by which it operates, in order to respond to changing circumstances or goals. There will not always be unanimous consensus regarding what changes to make. Therefore, we need a legislative governance process that a DAO can use in order to progress from disagreement to agreement.

specification/docs/system-design.md

@@ -21,10 +21,11 @@ Proposal
 Rollup
 end
 Bench --> Reputation
+Proposal --> Bench
+Proposal --> Reputation
 Work --> Reputation
 Work --> Bench
-Proposal --> Reputation
-Proposal --> Bench
+Work --> Proposal
 Forum --> Reputation
 Bench --> Forum
 Rollup --> Bench
@@ -48,21 +49,87 @@ We can achieve the requirements of the Reputation contract as follows:
 
 To achieve the Bench requirements, the contract must do the following:
 
-1. Keep a record of Validation Pools
-
-1. Implement a method for initiating a Validation Pool (VP)
-
-1. Implement a method for evaluating the outcome of a Validation Pool
-
 1. Define a minimum quorum
 
 1. Define a minimum and maximum VP duration
 
-### Work
+1. Keep a record of Validation Pools
+
+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
+
+### Forum
+
+To achieve the Forum requirements, the contract must do the following:
+
+1. Keep a record of Posts, indexed by Post ID
+
+1. Implement a method to add a Post
+
+1. Implement a recursive method to distribute Reputation to a Post's references and authors.
+
+    1. This method must be called only by the Bench, when a Validation Pool is accepted.
 
 ### Proposal
 
-### Forum
+To achieve the Proposals requirements, the contract must do the following:
+
+1. Define an attestation threshold
+
+1. Keep a record of Proposals
+
+1. Implement a method to initiate a Proposal
+
+    1. The caller should be able to provide an optional callback to be executed when and if the Proposal is accepted
+
+1. Implement a method for a DAO member to attest to a Proposal
+
+1. Implement a method to evaluate the attestation for a given Proposal
+
+    1. If the attestation threshold is met, begin the referendum process
+
+1. Implement the referendum process
+
+    1. Initiate the VP for the current stage referendum
+
+    1. Provide a callback to be executed when each referendum VP concludes, that advances the Proposal through the referenda stages according to the requirements.
+
+    1. If the Proposal passes all referenda stages, and a callback was provided, the callback should be executed.
+
+### Availability
+
+For convenience, we can define an Availability contract, as a base contract that other contracts may extend. Work contracts as well as the Rollup contract need to use this Availability mechanism.
+
+To achieve the requirements, the Availability contract must do the following:
+
+1. Keep a record of Worker availability stakes
+
+1. Implement a method to accept Worker availability stakes
+
+1. Implement a method to select a Worker by random weighted selection, weighted by the amount each Worker staked.
+
+### Work
+
+To achieve the Work Smart Contract requirements, a work contract must do the following:
+
+1. Inherit from the Availability contract
+
+1. Define a price for the work
+
+    1. Optionally, implement a method to initate a Proposal to change the price
+
+1. Implement a method for a Customer to request work
+
+1. Implement a method for a Worker to submit Work Evidence (WEV)
+
+1. Implement a method for a Customer to submit work approval/disapproval
+
+    1. Once approval/disapproval is submitted, either initiate a Validation Pool tarageting the WEV, or submit the fee and worker's REP stakes to the Rollup contract instead (explained below).
 
 ### Rollup
 
@@ -72,6 +139,22 @@ With this Rollup Post, we have the opportunity to attribute credit to multiple a
 
 The Rollup Post can weight authorship in accordance with the off-chain Validation Pools that have taken place. The off-chain system can fully model the Forum and Bench outlined in the [Requirements](../requirements.md) section. For demonstration purposes, our prototype makes some simplifying assumptions. Work Evidence Posts (WEV) are assumed to contain no references to prior Posts. In reality, we want WEV to be able to reference prior Posts, such as those representing policies of the DAO, prior work by other DAO members, prior art outside the DAO, and so on. So, a proper implementation of this system should account for these references, just as the Forum contract must.
 
+To achieve the Rollup requirements, the contract must do the following:
+
+1. Inherit from the Availability contract
+
+1. Keep a queue of items to be batched
+
+1. Implement a method to add an item to the queue of items to be batched
+
+1. Implement a method for the current batch worker to initiate a Validation Pool targeting a Rollup Post that represents items from the batch queue.
+
+    1. Items must be submitted in order without skipping any items
+
+1. Implement a method to select a new batch worker
+
+    1. If this method is called to replace a batch worker who has failed to submit the next batch, a Validation Pool should be initiated and the batch worker's stakes submitted in favor of the VP. The DAO members may then stake against this VP, punishing the worker who failed to submit the batch.
+
 ## Automated Staking
  
 - On-chain Direct Pool