add rollup docs

README.md

@@ -22,6 +22,81 @@ flowchart TD
     API <-- matrix-bot-sdk --> Matrix
 ```
 
+## Rollup
+
+Instead of calling `DAO.initiateValidationPool()`, a contract can call `Rollup.addItem()`.
+
+We demonstrate this by extending our base `Work` contract as `RollableWork`.
+
+Our work contract normally triggeres a validation pool when the customer submits work approval. Instead, the fee and worker availability stakes are transferred to the `Rollup` contract.
+
+The `Rollup` contract itself uses the `Availability` contract to assign a batch worker. This worker is responsible for making sure off-chain pools are conducted.
+
+When ready, the worker submits the current batch on-chain by creating a batch post and a validation pool targeting the batch post.
+```mermaid
+sequenceDiagram
+    participant client as Staking client
+    participant matrix as Matrix room
+    box Blockchain
+    participant worker as Worker
+    participant customer as Customer
+    participant work as Work contract
+    participant rollup as Rollup contract
+    participant vp as Validation pool
+    participant forum as Forum
+    end
+
+
+    worker ->> work : Availability stake<br />(REP)
+    activate worker
+    activate work
+    customer ->> work : Request work<br />(fee)
+    activate customer
+    worker ->> work : Submit work evidence<br />(postId)
+    deactivate worker
+    customer ->> work : Submit work approval
+    deactivate customer
+    work ->> rollup : Add item<br />(fee, REP, postId)
+    activate rollup
+    deactivate work
+
+    rollup ->> client : Event: BatchItemAdded
+    activate client
+    client ->> matrix : io.dgov.pool.start<br />(postId)
+    activate matrix
+    matrix -->> client : 
+    client ->> matrix : io.dgov.pool.stake<br />(postId, REP, inFavor)
+    matrix -->> client : 
+    client ->> matrix : io.dgov.pool.result<br />(postId, votePasses, quorumMet)
+    matrix -->> client : 
+
+    note right of matrix : All staking clients<br/>record each other's stakes
+
+    client ->> forum : Add post<br />(batchPostId)
+    activate forum
+    client ->> rollup : Submit batch<br />(batchPostId)
+    client ->> matrix : io.dgov.rollup.submit
+    matrix -->> client : 
+    deactivate matrix
+    rollup ->> vp : Initiate validation pool<br />(fee, REP, batchPostId)
+    activate vp
+    note right of vp : Mints REP in<br />proportion to fee
+    deactivate rollup
+
+    vp ->> client : Event: ValidationPoolInitiated
+
+    note right of client : Each staking client <br />verifies the rollup post
+
+    client ->> vp : Stake for/against
+    client ->> vp : Evaluate outcome
+    
+    vp ->> client : REP rewards for policin
+    deactivate client
+    vp ->> forum : Minted REP
+    deactivate vp
+    forum ->> worker : REP rewards for batch post authors
+    deactivate forum
+```
 
 ## Local development setup