From 3c05c32dffcb0f70ebd4f8b4d3fe389018f03a63 Mon Sep 17 00:00:00 2001 From: Ladd Hoffman Date: Sun, 19 May 2024 17:05:13 -0500 Subject: [PATCH] flatten sys design section --- specification/docs/implementation.md | 13 +++ specification/docs/system-design.md | 93 +++++++++++++++++++ .../docs/system-design/contracts/bench.md | 0 .../docs/system-design/contracts/forum.md | 0 .../docs/system-design/contracts/proposal.md | 0 .../system-design/contracts/reputation.md | 0 .../docs/system-design/contracts/rollup.md | 0 .../docs/system-design/contracts/work.md | 0 specification/docs/system-design/index.md | 64 ------------- specification/mkdocs.yml | 10 +- 10 files changed, 107 insertions(+), 73 deletions(-) create mode 100644 specification/docs/system-design.md delete mode 100644 specification/docs/system-design/contracts/bench.md delete mode 100644 specification/docs/system-design/contracts/forum.md delete mode 100644 specification/docs/system-design/contracts/proposal.md delete mode 100644 specification/docs/system-design/contracts/reputation.md delete mode 100644 specification/docs/system-design/contracts/rollup.md delete mode 100644 specification/docs/system-design/contracts/work.md delete mode 100644 specification/docs/system-design/index.md diff --git a/specification/docs/implementation.md b/specification/docs/implementation.md index e69de29..4e7c131 100644 --- a/specification/docs/implementation.md +++ b/specification/docs/implementation.md @@ -0,0 +1,13 @@ + +```mermaid +flowchart TD + Homeserver[Matrix\nHomeserver] + Contracts <-- Node.js blockchain\nclient library (ethers) --> API + Contracts <-- Web-based blockchain client library\n(MetaMask / Casper Wallet)--> WebApp + Contracts <-- Web-based blockchain client library\n(MetaMask / Casper Wallet)--> Widget + WebApp <-- HTTPS --> API + Widget <-- HTTPS --> API + Widget <-- Element-web Widget API\n(npm matrix-widget-api) --> Homeserver + API <-- Matrix Client-Server Protocol\n(npm matrix-bot-sdk) --> Homeserver +``` + diff --git a/specification/docs/system-design.md b/specification/docs/system-design.md new file mode 100644 index 0000000..2d7646a --- /dev/null +++ b/specification/docs/system-design.md @@ -0,0 +1,93 @@ +# System Design + +In the [Requirements](../requirements.md) section, we identified the need for the following smart contracts: Reputation, Bench, Forum, Work, Proposal, and Rollup. + +We also identified the need for a mechanism for coordinating Rollup Post validation. To address this need, we introduce [Matrix](https://matrix.org), a federated messaging protocol with multiple implementations. Our application uses the Client-Server protocol to communicate with a Matrix Homeserver. + +## Contracts + +The following is a dependency graph, where the arrows represent one contract calling another. + +```mermaid +flowchart BT +subgraph Core Contracts +Reputation +Bench +Forum +end +subgraph Business Logic +Work +Proposal +Rollup +end +Bench --> Reputation +Work --> Reputation +Work --> Bench +Proposal --> Reputation +Proposal --> Bench +Forum --> Reputation +Bench --> Forum +Rollup --> Bench +``` + +Reputation, Forum, and Bench can be considered core contracts. Together they provide the necessary primitives for a DAO to carry out its business. + +Work, Proposal, and Rollup can be considered business logic. They allow the DAO to support arbitrarily complex use cases, according to its needs. + +### Reputation + +We can achieve the requirements of the Reputation contract as follows: + +1. Reputation may be implemented as an ERC20 token contract. + +1. `transfer` and `transferFrom` methods must be disabled, so that REP may not be transferred. + +1. Reputation internal methods (`mint`, `burn`, `update`) may be called only by the Bench and Forum contracts. + +### Bench + +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 + +### Proposal + +### Forum + +### Rollup + +Rather than submit every Post on-chain and conduct every Validation Pool on-chain, it is more efficient to keep a collection of Posts off-chain, and add a single Rollup Post on-chain representing multiple off-chain Posts. + +With this Rollup Post, we have the opportunity to attribute credit to multiple authors, with a weight assigned to each author. We can express this weight as parts per million (PPM), for a balance between numerical precision, and ease of visual recognition. + +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. + +## Automated Staking + +- On-chain Direct Pool +- Rollup + +## Web App + +## API + +- Read +- Write + +## Other + +- Widget +- Register Matrix Identity +- Imprt from Semantic Scholar +- Import from Matrix +- Bot Commands diff --git a/specification/docs/system-design/contracts/bench.md b/specification/docs/system-design/contracts/bench.md deleted file mode 100644 index e69de29..0000000 diff --git a/specification/docs/system-design/contracts/forum.md b/specification/docs/system-design/contracts/forum.md deleted file mode 100644 index e69de29..0000000 diff --git a/specification/docs/system-design/contracts/proposal.md b/specification/docs/system-design/contracts/proposal.md deleted file mode 100644 index e69de29..0000000 diff --git a/specification/docs/system-design/contracts/reputation.md b/specification/docs/system-design/contracts/reputation.md deleted file mode 100644 index e69de29..0000000 diff --git a/specification/docs/system-design/contracts/rollup.md b/specification/docs/system-design/contracts/rollup.md deleted file mode 100644 index e69de29..0000000 diff --git a/specification/docs/system-design/contracts/work.md b/specification/docs/system-design/contracts/work.md deleted file mode 100644 index e69de29..0000000 diff --git a/specification/docs/system-design/index.md b/specification/docs/system-design/index.md deleted file mode 100644 index 400cdca..0000000 --- a/specification/docs/system-design/index.md +++ /dev/null @@ -1,64 +0,0 @@ -# System Design - -```mermaid -flowchart TD - Homeserver[Matrix\nHomeserver] - Contracts <-- Node.js blockchain\nclient library (ethers) --> API - Contracts <-- Web-based blockchain client library\n(MetaMask / Casper Wallet)--> WebApp - Contracts <-- Web-based blockchain client library\n(MetaMask / Casper Wallet)--> Widget - WebApp <-- HTTPS --> API - Widget <-- HTTPS --> API - Widget <-- Element-web Widget API\n(npm matrix-widget-api) --> Homeserver - API <-- Matrix Client-Server Protocol\n(npm matrix-bot-sdk) --> Homeserver -``` - - -Topics - -- Contracts -- Web Client -- Widget -- API / Staking Client - - API - - Read - - Write - - Import from Semantic Scholar - - Import from Matrix - - Event handlers - - Validation Pool - - Register Matrix Identity - - On-chain Direct Pool - - Rollup - - Bot Commands - -## Contracts - -In the [Requirements](../requirements.md) section, we identified the following smart contracts: - -1. Reputation -1. Bench -1. Work -1. Proposal -1. Forum -1. Rollup - -We also identified the need for a mechanism for coordinating Rollup Post validation. - -The following are reasons to submit a particular Post on-chain: - -- To conduct an on-chain Validation Pool tarageting that Post -- To enable other Posts to reference the given Post. - -Rather than submit every Post on-chain and conduct every Validation Pool on-chain, it is more efficient to keep a collection of Posts off-chain, and add a single Post on-chain representing multiple off-chain Posts. We call this a Rollup Post. - -With this Rollup Post, we have the opportunity to attribute credit to multiple authors, with a weight assigned to each author. We can express this weight as Parts Per Million (PPM), for a balance between numerical precision, and ease of visual recognition. - -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. - -## Matrix - -To address the need for coordination of off-chain Posts and Validation Pools, we introduce Matrix. [Matrix](https://matrix.org) is a messaging protocol, and it has multiple implementations. Our prototype uses Synapse as the Homeserver. Our system communicates with the Homeserver using the Client-Server protocol. - -## Element-web Widget - - diff --git a/specification/mkdocs.yml b/specification/mkdocs.yml index 06a3dee..bf0a846 100644 --- a/specification/mkdocs.yml +++ b/specification/mkdocs.yml @@ -18,13 +18,5 @@ nav: - Overview: index.md - Terminology: terminology.md - Requirements: requirements.md - - System Design: - - Overview: system-design/index.md - - Contracts: - - Reputation: system-design/contracts/reputation.md - - Bench: system-design/contracts/bench.md - - Work: system-design/contracts/work.md - - Proposal: system-design/contracts/proposal.md - - Forum: system-design/contracts/forum.md - - Rollup: system-design/contracts/rollup.md + - System Design: system-design.md - Implementation: implementation.md