diff --git a/README.md b/README.md index 6a24af8..c0129a4 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Agora is a set of Plutus scripts that compose together to form a governance syst Goals: -- Agora aims to reduce duplication in Liqwid and LiqwidX and to serve as a one-size-fits-all governance library for projects on the Cardano blockchain. +- Agora aims to reduce duplication in Liqwid and XplorerDAO and to serve as a one-size-fits-all governance library for projects on the Cardano blockchain. - Agora aims to be modular and flexible for specific needs but presents an opinionated architecture. Non-goals: @@ -36,8 +36,6 @@ cabal run agora-scripts -- --enable-cors-middleware Documentation for Agora is hosted on Notion. You can find the specs [here](https://liqwid.notion.site/e85c09d2c9a542b19aac8dd3d6caa98b?v=d863219cd6a14082a661c4959cabd6e7). -Haddock is deployed on GitHub Pages [here](https://liqwid-labs.github.io/agora/). - ### Using Agora for your protocol If you are a protocol wanting to use Agora, read [Using Agora](https://liqwid.notion.site/Using-Agora-74ceb4a70d024992abd9ff07087013e6). @@ -64,8 +62,8 @@ Please read [CONTRIBUTING.md](./CONTRIBUTING.md). Additionally, please follow th ### v2 -- [ ] Rewards distribution -- [ ] Escrow staking pool solution +- [ ] Flexible scripts using TxT pattern integrated with governance +- [ ] Different voting mechanisms ### Available support channels info diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index f14ce0f..0000000 --- a/docs/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Agora specification and documentation - -This folder contains documents explaining the conceptual background and technical implementation of Agora components. - -## Technical design - -The `tech-design/` subdirectory contains high level descriptions of the architecture of Agora's governance solution. - -## Plutarch - -Agora makes extensive use of [Plutarch](https://github.com/plutonomicon/plutarch). One unfamiliar with the library will be unable to suitably understand the technical parts of this documentation. The maintainers provide an extensive [guide](https://github.com/Plutonomicon/plutarch/blob/master/docs/GUIDE.md) that will familiarise the developer with the language and thereby this set of documentation. - -## Glossary - -The following is a list of terms that are used frequently throughout the documentation: - -- **DAO**: decentralised autonomous organisation. -- **Proposal**: a set of changes to a Cardano protocol, suggested by a community member. Will be enacted, if passed by the community. -- **Governance token (GT)**: the token that confers the right to vote on proposals within the protocol. May affect the user's eligibility for rewards. Examples include Liqwid's LQ. -- **Governance authority token (GAT)**: A token that grants the effects of a proposal the authority to alter the system. More information can be read [here](https://liqwid.notion.site/Authority-Tokens-b25d2011c8114e04ac9e73514e6b9421). -- **Effect**: A script for implementing changes suggested by a proposal. An effect can make numerous changes and a proposal may have multiple effects. diff --git a/docs/diagrams/GovernanceAuthorityToken.dot b/docs/diagrams/GovernanceAuthorityToken.dot deleted file mode 100644 index a4be5c4..0000000 --- a/docs/diagrams/GovernanceAuthorityToken.dot +++ /dev/null @@ -1,238 +0,0 @@ -digraph GovernanceAuthorityToken { - - rankdir = LR; - // Inputs: - - ////////////////////////////////////////////////////////////////////////////// - // governance in - governance_datum - [ shape = record - , label = - "{{ GovernanceState - }}" - ]; - - governance_addr - [ shape = record - , label = "{{ Script | Governance }}" - , style = "bold" - ]; - - ////////////////////////////////////////////////////////////////////////////// - // proposal in - proposal_datum - [ shape = record - , label = "{{ ProposalState }}" - ]; - - proposal_addr - -> proposal_redeemer - [style = "dashed", dir="none"]; - - proposal_addr - [ shape = record - , label = "{{ Script | Proposal }}" - , style = "bold" - ]; - - governance_datum - -> governance_addr [style = "dashed"]; - - governance_redeemer - [ shape = record - , label = "{{ GovernanceAction | MintAuthorityTokens }}" - ]; - - governance_addr - -> governance_redeemer - [style = "dashed", dir="none"]; - - proposal_datum -> proposal_addr [style = "dashed"]; - - ////////////////////////////////////////////////////////////////////////////// - // user wallet in - user_wallet_min_ada_in - [ shape = ellipse - , label = min utxo> - ]; - - user_wallet_in - [ shape = box - , label = "User Inputs" - , style = "bold" - , peripheries = 2 - ]; - - user_wallet_min_ada_in - -> user_wallet_in - [ style = "dashed" - ]; - - - tx1 - [ shape = diamond - , label = "Tx1" - , style = "bold" - ]; - - user_wallet_in -> tx1; - governance_addr -> tx1; - proposal_addr -> tx1; - - ////////////////////////////////////////////////////////////////////////////// - // governance out - governance_datum_out - [ shape = record - , label = - "{{ GovernanceState - }}" - ]; - - governance_addr_out - [ shape = record - , label = "{{ Script | Governance }}" - , style = "bold" - ]; - - - governance_datum_out - -> governance_addr_out - [ style = "dashed" - ]; - - ////////////////////////////////////////////////////////////////////////////// - // proposal out - proposal_datum_out - -> proposal_addr_out - [ style = "dashed" - ]; - - proposal_redeemer - [ shape = record - , label = - "{{ ProposalAction | FinishVoting }}" - ]; - - - proposal_datum_out - [ shape = record - , label = - "{{ ProposalState }}" - ]; - - proposal_addr_out - [ shape = record - , label = "{{ Script | Proposal }}" - , style = "bold" - ]; - - - ////////////////////////////////////////////////////////////////////////////// - // effect out - effect_governance_token_out - [ shape = ellipse - , label = - ]; - - effect_addr_out - [ shape = record - , label = "{{ Script | Effect }}" - , style = "bold" - ]; - - effect_governance_token_out - -> effect_addr_out - [ style = "dashed" - ]; - - effect_min_ada_out - -> effect_addr_out - [ style = "dashed" - ]; - - effect_min_ada_out - [ shape = ellipse - , label = min utxo> - ]; - - tx1 -> governance_addr_out; - tx1 -> proposal_addr_out; - tx1 -> effect_addr_out; - - ////////////////////////////////////////////////////////////////////////////// - ////////////////////////////////////////////////////////////////////////////// - - ////////////////////////////////////////////////////////////////////////////// - // effect in - effect_addr_out2 - [ shape = record - , label = "{{ Script | Effect }}" - , style = "bold" - ]; - - ////////////////////////////////////////////////////////////////////////////// - // market in - market_addr_in - [ shape = record - , label = "{{ Script | Market }}" - , style = "bold" - ]; - - market_datum_in - [ shape = record - , label = "{{ MarketState | params: A }}" - ]; - - market_datum_in - -> market_addr_in - [ style = "dashed" - ]; - - ////////////////////////////////////////////////////////////////////////////// - // market out - market_addr_out - [ shape = record - , label = "{{ Script | Market }}" - , style = "bold" - ]; - - market_datum_out - [ shape = record - , label = "{{ MarketState | params: f(A) }}" - ]; - - market_datum_out - -> market_addr_out - [ style = "dashed" - ]; - - tx2 - [ shape = diamond - , label = "Tx2" - , style = "bold" - ]; - - user_wallet_min_ada_out - [ shape = ellipse - , label = min utxo> - ]; - - user_wallet_out - [ shape = box - , label = "User Outputs" - , style = "bold" - , peripheries = 2 - ]; - - user_wallet_min_ada_out - -> user_wallet_out - [ style = "dashed" - ]; - - effect_addr_out -> tx2; - market_addr_in -> tx2; - tx2 -> user_wallet_out; - tx2 -> effect_addr_out2; - tx2 -> market_addr_out; - -} diff --git a/docs/diagrams/GovernanceAuthorityToken.png b/docs/diagrams/GovernanceAuthorityToken.png deleted file mode 100644 index 60878f1..0000000 Binary files a/docs/diagrams/GovernanceAuthorityToken.png and /dev/null differ diff --git a/docs/diagrams/GovernanceAuthorityToken.svg b/docs/diagrams/GovernanceAuthorityToken.svg deleted file mode 100644 index fcaee17..0000000 --- a/docs/diagrams/GovernanceAuthorityToken.svg +++ /dev/null @@ -1,322 +0,0 @@ - - - - - - -GovernanceAuthorityToken - - - -governance_datum - -GovernanceState - - - -governance_addr - -Script - -Governance - - - -governance_datum->governance_addr - - - - - -governance_redeemer - -GovernanceAction - -MintAuthorityTokens - - - -governance_addr->governance_redeemer - - - - -tx1 - -Tx1 - - - -governance_addr->tx1 - - - - - -proposal_datum - -ProposalState - - - -proposal_addr - -Script - -Proposal - - - -proposal_datum->proposal_addr - - - - - -proposal_redeemer - -ProposalAction - -FinishVoting - - - -proposal_addr->proposal_redeemer - - - - -proposal_addr->tx1 - - - - - -user_wallet_min_ada_in - -ADA: -min utxo - - - -user_wallet_in - - -User Inputs - - - -user_wallet_min_ada_in->user_wallet_in - - - - - -user_wallet_in->tx1 - - - - - -governance_addr_out - -Script - -Governance - - - -tx1->governance_addr_out - - - - - -proposal_addr_out - -Script - -Proposal - - - -tx1->proposal_addr_out - - - - - -effect_addr_out - -Script - -Effect - - - -tx1->effect_addr_out - - - - - -governance_datum_out - -GovernanceState - - - -governance_datum_out->governance_addr_out - - - - - -proposal_datum_out - -ProposalState - - - -proposal_datum_out->proposal_addr_out - - - - - -effect_governance_token_out - -GovernanceAuthorityToken: 1 - - - -effect_governance_token_out->effect_addr_out - - - - - -tx2 - -Tx2 - - - -effect_addr_out->tx2 - - - - - -effect_min_ada_out - -ADA: -min utxo - - - -effect_min_ada_out->effect_addr_out - - - - - -effect_addr_out2 - -Script - -Effect - - - -market_addr_in - -Script - -Market - - - -market_addr_in->tx2 - - - - - -market_datum_in - -MarketState - -params: A - - - -market_datum_in->market_addr_in - - - - - -market_addr_out - -Script - -Market - - - -market_datum_out - -MarketState - -params: f(A) - - - -market_datum_out->market_addr_out - - - - - -tx2->effect_addr_out2 - - - - - -tx2->market_addr_out - - - - - -user_wallet_out - - -User Outputs - - - -tx2->user_wallet_out - - - - - -user_wallet_min_ada_out - -ADA: -min utxo - - - -user_wallet_min_ada_out->user_wallet_out - - - - - diff --git a/docs/diagrams/ProposalStateMachine.png b/docs/diagrams/ProposalStateMachine.png new file mode 100644 index 0000000..0c0f915 Binary files /dev/null and b/docs/diagrams/ProposalStateMachine.png differ diff --git a/docs/diagrams/UsingAgora.dot b/docs/diagrams/UsingAgora.dot deleted file mode 100644 index 29bc58b..0000000 --- a/docs/diagrams/UsingAgora.dot +++ /dev/null @@ -1,6 +0,0 @@ -digraph { - rankdir=LR - Users -> Proposals [label="vote on"] - Proposals -> Effects [label="have one or many"] - Effects -> Components [label="alter"] -} diff --git a/docs/diagrams/UsingAgora.svg b/docs/diagrams/UsingAgora.svg deleted file mode 100644 index 7ed833d..0000000 --- a/docs/diagrams/UsingAgora.svg +++ /dev/null @@ -1,57 +0,0 @@ - - - - - - - - - -Users - -Users - - - -Proposals - -Proposals - - - -Users->Proposals - - -vote on - - - -Effects - -Effects - - - -Proposals->Effects - - -have one or many - - - -Components - -Components - - - -Effects->Components - - -alter - - - diff --git a/docs/diagrams/gov-overview.dot b/docs/diagrams/gov-overview.dot index 0ee05d6..2b78923 100644 --- a/docs/diagrams/gov-overview.dot +++ b/docs/diagrams/gov-overview.dot @@ -1,7 +1,9 @@ digraph { - Stakes -> Proposals [label="vote on"] + Stakes -> Proposals [label="create and vote on"] Proposals -> Effects [label="have"] + Admin-> Governor [label="initializes"] Governor -> Effects [label="issues GATs to"] Users -> Stakes [label="lock GT in"] Effects -> Treasury [label="release GT from"] + Effects -> Components [label="alter"] } diff --git a/docs/diagrams/gov-overview.png b/docs/diagrams/gov-overview.png new file mode 100644 index 0000000..1125d5c Binary files /dev/null and b/docs/diagrams/gov-overview.png differ diff --git a/docs/diagrams/gov-overview.svg b/docs/diagrams/gov-overview.svg index b52362d..94175ed 100644 --- a/docs/diagrams/gov-overview.svg +++ b/docs/diagrams/gov-overview.svg @@ -4,80 +4,106 @@ - + - + Stakes - -Stakes + +Stakes Proposals - -Proposals + +Proposals Stakes->Proposals - - -vote on + + +create and vote on Effects - -Effects + +Effects Proposals->Effects - - -have + + +have - + Treasury - -Treasury + +Treasury - + Effects->Treasury - - -release GT from + + +release GT from + + + +Components + +Components + + + +Effects->Components + + +alter + + + +Admin + +Admin - + Governor - -Governor + +Governor + + + +Admin->Governor + + +initializes - + Governor->Effects - - -issues GATs to + + +issues GATs to - + Users - -Users + +Users - + Users->Stakes - - -lock GT in + + +lock GT in diff --git a/docs/meta/README.md b/docs/meta/README.md deleted file mode 100644 index c762e15..0000000 --- a/docs/meta/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Docs meta - -This folder includes notes to assist in the writing of documentation. Those not involved with spec writing have no need for these files. diff --git a/docs/meta/status-format.md b/docs/meta/status-format.md deleted file mode 100644 index c10e71a..0000000 --- a/docs/meta/status-format.md +++ /dev/null @@ -1,119 +0,0 @@ -# Spec status format - -This document specifies a format used to denote the 'status' of a spec document. - -## Overview - -Each specification document should be headed by a simple table outlining aspects of its status in relation to: - -- Authorship: who has contributed to it? -- Ownership: who is responsible for it? -- Implementation(s): where is it used? -- Completeness: is it done yet? - -This format should be used at the start of any documentation that may be considered a _technical specification_, with a related implementation. - -## Format - -The format is as follows, with {substitutions} in curly braces. - -| Specification | Implementation | Last revision | -|:-------------:|:--------------:|:-------------:| -| {status} | {status} | {version} {date} | - --------------------- - -**Specification ownership:** {[Spec owner]} - -**Authors**: - - {[Spec owner]} - - {[Author]} - -**Implementation ownership:** {[Impl owner]} - -**Current status**: - -{Short description of status regarding __both__ specification and implementation}. - -[Spec owner]: https://genrandom.com/cats/ -[Author]: https://genrandom.com/cats/ -[Impl owner]: https://genrandom.com/cats/ - -```markdown -| Specification | Implementation | Last Revision | -|:-------------:|:--------------:|:-------------:| -| {status} | {status} | {version}, {date} | - --------------------- - -**Specification ownership:** [{owner name}] - -**Authors**: - - [{owner name}] - - [{author name}] - - -**Implementation ownership:** [{impl owner name}] - -**Current status**: - -{Short description of status} - -[{owner name}]: {github url} -[{author name}]: {github url} -[{impl owner name}]: {github url} - --------------------- -``` - -### Specification/Implementation status - -The 'Specification' and 'Implementation' status should be one of the following: - -- `WIP`: Work In Progress, currently incomplete, pending current or future work by the current owner or a future owner. -- `Draft`: Complete but pending further evaluation or changes to be accounted for in the future. -- `Final`: Complete and finalised to some degree of certainty. - -### Last revision - -- version - An optional version/revision number for the spec document. -- date - date the document was last updated in [ISO 8601 format](https://www.wikiwand.com/en/ISO_8601#/Calendar_dates) (YYYY-MM-DD). - -### Authors - -The authors and contributors of the spec document. - -### Specification ownership - -The person currently, or most recently tasked with writing and maintaining the spec document. - -### Implementation ownership - -The person currently or most recently tasked with the implementation of the features described in the document. - -- For individual features, this will be the person most recently assigned to related GitHub issues. -- For broader sections, this will be a person leading the implementation efforts for the particular system. - -## Example - -| Specification | Implementation | Last Revision | -|:-------------:|:--------------:|:-------------:| -| WIP | Draft | 0.1 2022-01-31 | - --------------------- - -**Specification ownership:** [Jack Hodgkinson] - -**Authors**: - - [Jack Hodgkinson] - - [Emily Martins] - -**Implementation ownership:** [Emily Martins] - -**Current status**: - -Draft completed in project repo. Spec needs revisiting to address issues outlined in #42. Section on staking pool behaviour is out-dated. - -[Jack Hodgkinson]: https://github.com/jhodgdev -[Emily Martins]: https://github.com/emiflake -*** diff --git a/docs/meta/style-guide.md b/docs/meta/style-guide.md deleted file mode 100644 index 664549c..0000000 --- a/docs/meta/style-guide.md +++ /dev/null @@ -1,52 +0,0 @@ -# Agora docs style guide - -This document includes a couple of notes on how Agora documentation should be written and formatted. - -## British/American spelling and grammatical differences - -The difference between British and American English is wider than a lot of people presume. Authors are permitted to use whichever of the two they learned and therefore feel more comfortable with. The only exception to this is when writing changes that would result in a 'mixing' of styles e.g. having 'color' in a sentence and 'colour' in the next. In this instance please alter your use of the language to maintain consistency. - -## Capitalised words - -The following words should always in the forms below: - -- Agora -- Liqwid -- LiqwidX -- Nix -- NixOS -- Plutus -- Plutarch - -Sensible exceptions naturally exist, including referencing shell commands (`nix-shell`) or code: - -```haskell -plutarchTerm :: Term s a -plutarchTerm = ... -``` - -## Upper-case terms - -The following terms should always be rendered in all capital letters: - -- UTXO -- EUTXO - -## Lower-case words - -The following words should always be rendered lower-case (unless used at the beginning of a sentence): - -- governance - -## ADA, Ada, ada - -Cardano's native token suffers from a frustrating variety of acceptable forms. Reputable sources can be found using all three variants listed in the header. As such, no usage shall be mandated with two caveats: - -1. Whilst the name of the currency is subject to variance, its 'symbol' is unambiguously 'ADA'. Therefore when talking about amounts e.g. 'Trillian deposits 100ADA', use 'ADA'. -2. Exercise _reasonable consistency_. The use of an 'Ada' at the beginning of the document and an 'ada' 3000 words later is not something worth losing sleep over. Inconsistency within paragraphs or (gasp!) _sentences_ should always be avoided. - -## Avoid - -The following practices should be avoided: - -- The use of '&' apart from in proper nouns such as AT\&T.