dgf-prototype/README.md

# DGF Prototype
Decentralized Governance Framework

* [Specification](https://spec.dgov.io)

* [Demo](https://demo.dgov.io)

## Project Architecture

| directory | description |
| --------- | ----------- |
| ethereum  | Solidity smart contracts and associated deploy scripts |
| backend   | Node.js application with an HTTP API that also functions as a Matrix bot and Ethereum client |
| frontend  | React.js frontend with a WebApp route and a Matrix Widget route |

### Data Flow Diagram

```mermaid
flowchart TD
    Blockchain <-- ethers --> API
    Blockchain <-- Web3<br>+ MetaMask --> WebApp
    Blockchain <-- Web3<br>+ MetaMask --> Widget
    WebApp <-- HTTPS --> API
    Widget <-- HTTPS --> API
    Widget <-- matrix-widget-api --> Matrix
    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 calling `DAO.addPost()` to create a batch post and then calling `Rollup.submitBatch()`, which initiates 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 client : 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

Clone this repository to a directory on your machine

    git clone https://gitea.dgov.io/DGF/dgf-prototype

### Nginx

1. Install nginx

        brew install nginx


1. Install mkcert

        brew install mkcert

1. Install root CA

        mkcert -install

1. Create a certificate

        mkcert dgfprototype.dev
         
1. Create certificates directory

        sudo mkdir /etc/nginx/certs

1. Move the certificate to the certificates directory

        sudo mv dgfprototype.*.pem /etc/nginx/certs/

1. Add the following to the `http` section of `/etc/nginx/nginx.conf`

        map $http_upgrade $connection_upgrade {
            default upgrade;
            '' close;
        }

1. Add the following to a new file `/etc/nginx/sites-available/dgfprototype_dev`

        server {
                listen 443 ssl;

                server_name dgfprototype.dev;
                ssl_certificate     /etc/nginx/certs/dgfprototype.dev.pem;
                ssl_certificate_key /etc/nginx/certs/dgfprototype.dev-key.pem;

                location /api/ {
                        proxy_pass http://127.0.0.1:3003/;
                }

                location / {
                        proxy_pass http://127.0.0.1:3002/;
                        proxy_http_version 1.1;
                        proxy_set_header Upgrade $http_upgrade;
                        proxy_set_header Connection $connection_upgrade;
                        proxy_set_header Host $host;
                }
        }

1. Create a symbolic link in `sites-enabled/`

        sudo ln -s /etc/nginx/sites-available/dgfprototype_dev /etc/nginx/sites-enabled

1. Restart nginx

        sudo systemctl restart nginx

    or

        sudo brew services restart nginx

1. Edit `/etc/hosts` to add the domain alias

        127.0.0.1  dgfprototype.dev

### API

1. In a new terminal window, navigate to `dgf-prototype/backend`

1. Install the project

        npm install

1. Copy the example configuration file

        cp .env.example .env

1. Edit `.env` and set the following values

        PORT=3003

1. Create the data directory

        mkdir data

1. Run the daemon

        node src/index.js

### Hardhat

1. In a new terminal window, navigate to `dgf-prototype/ethereum`

1. Install the project

        npm install

1. Copy the example configuration file

        cp .env.example .env

1. In `.env`, set a value for `SEED_PHRASE` or `LOCAL_PRIVATE_KEY`

1. Run a hardhat node

        npx hardhat node

1. In a separate terminal window, navigate again to `dgf-prototype/ethereum`

1. Build and deploy the contracts

        npm run deploy-local

### Metamask

1. Install the Metamask extension in your browser

1. In the Metamask extension, click the list of networks in the top left, and click "Add Network"

1. At the bottom of the list of popular networks, click "Add a network manually"

    - Network name: Hardhat local
    - RPC URL: http://127.0.0.1:8545/
    - Chain ID: 1337
    - Currency symbol: ETH

### Frontend

1. In a new terminal window, navigate to `dgf-prototype/frontend`

1. Install the project

        npm install

1. Install `vite`

        npm i -g vite

1. Run the development server

        vite dev

1. Now you should be able to open the site at https://dgfprototype.dev


## To run automatic staking

1. Clone this repository to a directory on your machine

        git clone https://gitea.dgov.io/DGF/dgf-prototype

1. Change to the `ethereum` directory

        cd ethereum

1. Install the project using `npm`

        npm install

1. Copy the example configuration file

        cp .env.example .env

1. Export your Sepolia private key from MetaMask and add it to your `.env` file

        SEPOLIA_PRIVATE_KEY="YOURKEY"

1. Run the automatic staking script

        npm run automatic-staking-sepolia