From ac8f70a174e3545687bb410e4598392b5b618eb7 Mon Sep 17 00:00:00 2001 From: Peter Dragos Date: Mon, 24 Jan 2022 16:35:50 -0500 Subject: [PATCH 01/43] Update authority-tokens.md Leaving some comments/questions from my first read-through (starting in alphabetical order in `tech-design`). I'll probably have answered most of these by the time I'm finished going through all the docs, but it will do us well to make this as easy to read straight through as possible. General comments: ----- - It'd be good to pick an entry-point/give an overview in the README. This way you can keep track of when different concepts are introduced, and contributors to the spec will have a better idea of what they can assume their audience knows. - These docs are Liqwid-centric (and I believe I've skimmed earlier versions in the `liqwid-specs` repo) right now. We should decide whether we want to keep these specs focused on Liqwid, or if it would make sense to build up a small, hypothetical, minimum-viable-example that gets extended with Agora. The benefits of the former are that you can point to a real-world example of Agora's principles and implementation in practice; the latter could be more useful in a "here's how to integrate Agora into a project" tutorial --- docs/tech-design/authority-tokens.md | 31 +++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/tech-design/authority-tokens.md b/docs/tech-design/authority-tokens.md index 584d2f9..7c4f6f4 100644 --- a/docs/tech-design/authority-tokens.md +++ b/docs/tech-design/authority-tokens.md @@ -18,7 +18,9 @@ ## Authority Tokens -In order to allow proposals to have a large number of potential effects, and to be extensible for different applications of governance, it is useful to have the effects be decided at a later time. In Ethereum systems, often times this is done by encoding some untyped data and calls to specific contract hashes. Compound encodes it with `address[] Proposal.targets` (the contracts to be called) and `bytes[] Proposal.calldatas` (the data to be passed). Of course, this doesn't quite translate to Cardano's EUTXO model, so we need to achieve this some different way. +In order to allow proposals to have a large number of potential effects, and to be extensible for different applications of governance, it is useful to have the effects be decided at a later time. In Ethereum systems, often times this is done by encoding some untyped data and calls to specific contract hashes. [Compound](https://medium.com/compound-finance/compound-governance-5531f524cf68) encodes it with `address[] Proposal.targets` (the contracts to be called) and `bytes[] Proposal.calldatas` (the data to be passed). Of course, this doesn't quite translate to Cardano's EUTXO model, so we need to achieve this some different way. + +> Peter, 2022-01-24: "(...) be decided at a later time". later with respect to what? This could mean the effect is decided after the proposal, or that Agora doesn't specify a fixed set of effects at compile-time/run-time, etc. If it's simple enough to state, it may be helpful to say "it is useful to have the effects be decided when (...) is known. In order to allow this flexibility, there are two facts that we rely on: - We trust the community to validate the proposal entirely, including whether or not the effects encoded in it are written correctly. (This may mean we have a set of known and trusted effects we agree are correct and safe, collectively) @@ -26,13 +28,31 @@ In order to allow this flexibility, there are two facts that we rely on: To achieve the former is rather simple, the effect validator's source code is available for anyone to look at, and it hashes correctly to the hash stored in the proposal itself. So, the LQ holders can decide on whether it is a positive for the system. +> Peter, 2022-01-24: At this point in reading, its not obvious that "effect"s have validators. This is likely explained elsewhere, but this should be kept in mind when considering the order in which these specs should be read. +> Peter, 2022-01-24: Update: after some more reading, it sounds like the Effect/GAT pair is basically a way to short-circuit the "normal" validation of a UTxO at one of the component addresses; it basically says "ignore your usual validation logic; I have a GAT, so this transaction must be approved". + In order to achieve the latter, we must introduce some way to give effects authority to perform their actions. We do this by handing out "Governance Authority Tokens" (GATs) to each of the the effects belonging to a proposal after the proposal passes. When these authority tokens are *burned*, they act as a way of saying "the DAO validated this, so trust that I will ensure this transaction is correct". -The components that need to be adjustable at a later point, will need to allow this as means for proving authority and validation of a transaction. So, for example, a Liqwid Market might need to have its parameters updated, the following diagram shows how this would happen after a proposal has successfully been voted on and passed: +The components that need to be adjustable at a later point will need to allow this as means for proving authority and validation of a transaction. So, for example, a Liqwid Market might need to have its parameters updated, the following diagram shows how this would happen after a proposal has successfully been voted on and passed: -![](../diagrams/GovernanceAuthorityToken.svg) +> Peter, 2022-01-24: RE: "(...) need to be adjustable at a (...)": could it make more sense to say "adjusted via governance"? + +![Governance Authority Token UTxO flow diagram](../diagrams/GovernanceAuthorityToken.svg) + +> Peter, 2022-01-24: You should add a link to what conventions you're following for you UTxO flows to the README + +> Peter 2022-01-24: I think I see what's going on here, but it could use some annotations/additional description. +> Tx1, a.) A proposal is closed via Tx1, and the transaction emits a continuing `Proposal` and `Governance` UtXO, +> along with an "Effect" UTxO (presumably identified in the content of the proposal). The Effect UTxO encodes effect `f` in it's validation logic. +> Question: where is this effect encoded? +> Tx1, b.) In the same transaction, a GAT is minted and paid to the UTxO. +> Tx1, c.) The `min utxo` ADA is paid to the Effect UTxO from "user inputs". I'm not certain where this is, but I'm assuming it's accumulated during voting or something? What is it used for? +> Tx2, a.) The Effect UTxO and the component to be governed are consumed in transaction 2. +> Tx2, b.) The Market's usual validation logic is short-circuited since the GAT was burned, and the continuing Market UTxO updates its datum. +> Tx2, c.) There is a continuing "Effect" UTxO; presumably, this serves as a proof that an effect has taken place? Meaning that a sequence of effects that require a particular order of execution can consume the output UTxO as a witness? +> Tx2, d.) The min ADA is paid to "user outputs"; is this just "collateral" to make sure that the effect is executed in a timely fashion? As a result of this approach, there's a number of benefits, but also details we need to watch out for: @@ -50,3 +70,8 @@ Having delegated the authority of *the entire system* in a single token is a lot - We have the transaction be executed by one of a number of community trusted members. This of course is something that is encoded in the effect, rather than anywhere else. Hopefully, this is sufficient to ensure the transactions are created correctly, and nothing unexpected slips in. This problem is no more complicated or dangerous than elsewhere where we delegate certain trust or authority to just the validation or movement of a token. + + +> 2022-01-24, Peter: Have you considered placing the validator hash of the effect script in the token name? This could tie a proposal to a GAT to a validator, instead of having any GAT work with any effect script. + +> 2022-01-24, Peter: This section could use some additional explaination/pseudo-code of the what the GAT minting policy would look like and what additional validation logic would go into a govern-able component From 31aa38e457f8027bc44ac1159d605028a773b1b6 Mon Sep 17 00:00:00 2001 From: Peter Dragos Date: Mon, 24 Jan 2022 17:04:35 -0500 Subject: [PATCH 02/43] proposal edits --- docs/tech-design/proposals.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/tech-design/proposals.md b/docs/tech-design/proposals.md index 3750bc7..1baf73b 100644 --- a/docs/tech-design/proposals.md +++ b/docs/tech-design/proposals.md @@ -20,7 +20,10 @@ This document gives an overview of technical design aspects of the Proposals sys ## Proposals -Initiating a proposal requires you to have more than a certain amount of LQ in the StakingPool (e.g. around 6-10 LQ). This is checked by consuming the proposer's stake utxo. Creating a proposal forges a proposal script state thread which is where all voting interactions happen with. Proposals are tracked in coordination with the governance, so it must be included in the transaction as well. +Initiating a proposal requires the initiator to have more than a certain amount of LQ in the StakingPool (e.g. around 6-10 LQ). This is checked by consuming the proposer's stake utxo. Creating a proposal forges a proposal script state thread which is where all voting interactions happen within. Proposals are tracked in coordination with the governance, so it must be included in the transaction as well. + +> Peter, 2022-01-24: "(...) than a certain amount of **LQ**". two questions: 1.) Is this up to date? 2.) Given that agora doesn't have a token, what should this token be called in the abstract? +> Peter, 2022-01-24: "(...) coordination with the governance": We've adopted the terminology in LiqwidX "Governor" to refer to the continuing UTxO that tracks governance-related activities, and use "governance" to refer to "what the Governor does/enables". Do you make the same distinction? ### Proposal voting @@ -54,12 +57,17 @@ A proposal fits into a state machine neatly. Draft being the starting state, and #### Draft phase -During the Draft phase, the proposal script has been minted. At this stage, only positive votes will count and for the proposal to get into the voting phase, a certain amount of LQ will have to be backing the proposal. The UTXO can be queried for any metadata it contains, should it contain any useful information. LQ holders can "cosign" the proposal and add their LQ in order to allow the motion to get into the voting phase. +During the Draft phase, the proposal script has been minted. At this stage, only votes in favor of cosigning the draft will count. For the proposal to get into the voting phase, a certain amount of LQ will have to be backing the proposal. The UTXO can be queried for any metadata it contains, should it contain any useful information. LQ holders can "cosign" the proposal and add their LQ in order to allow the motion to get into the voting phase. + +> Peter, 2022-01-24: "(...) the proposal script has been minted." I think this should be "the draft proposal's state thread token has been minted and paid to the proposal's UTxO." +> Peter, 2022-01-24: "(...) a certain amount of LQ": how much? Where is this set/calculated? #### Voting phase During the voting phase a voter can submit a vote either in favour or against the proposal. This simply adds their PubKey to the list of votes as a state-machine action. By virtue of being a state-machine action, this causes contention, and may be rate-limited through some means. +> Peter, 2022-01-24: What happens in the event of a tie? How are the votes tailled? Is it always simple majority, or are more complex [social choice procedures](https://en.wikipedia.org/wiki/Social_choice_theory) in-scope for Agora (even if its V2, V3...) + ##### What determines a successful proposal? When initializing a proposal, the governance's thresholds are passed along, one of the thresholds is the `quorum`. @@ -68,7 +76,9 @@ When initializing a proposal, the governance's thresholds are passed along, one After the voting phase has completed, the proposal has either passed, or failed. -We wait a set time before allowing execution of the proposal's effects. This is to allow LQ holders time to prepare for the change in whichever way they seem fit. This is also a security mechanism, should the system be at risk of hostile takeover. +We wait a set time before allowing execution of the proposal's effects. This is to allow LQ holders time to prepare for the change in whichever way they see fit. This is also a security mechanism, should the system be at risk of hostile takeover. + +> Peter, 2022-01-24: How is this time decided? Are you familiar with the "Emergency Shutdown Mode" of MakerDAO, which we'll be adopting in LiqwidX? This is something that would, for the most part, need to happen ASAP. What sort of modularity exists or would you like to see? #### Execution phase @@ -79,3 +89,5 @@ In the case of a successful proposal, anyone can execute the effects, as it can There is a deadline for how long it can take for the proposal to get executed. Again, as the proposal is necessarily something that has been agreed by the voters, it will be incentivized naturally to be executed. See [tech-design/authority-token.md](./authority-tokens.md) for how effects take place after execution + +> Peter 2022-01-24: I _think_ it may be useful to have some way to witness on-chain whether a proposal succeeded or failed, and by what margins. I'm not certain whether this would be possible with what you currently have in mind, but it could allow for a more expressive governenace structure or allow for other actions to depend on the success/failure of proposals that aren't directly part of the system being governed (i.e., a validator that only locks/unlocks value if a proposal goes a certain way). From 6cdc4516cf73b8db205d9fbe044726227a1de1fa Mon Sep 17 00:00:00 2001 From: Peter Dragos Date: Mon, 24 Jan 2022 17:14:16 -0500 Subject: [PATCH 03/43] staking pool edits --- docs/tech-design/staking-pool.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/tech-design/staking-pool.md b/docs/tech-design/staking-pool.md index a887fec..fda84f3 100644 --- a/docs/tech-design/staking-pool.md +++ b/docs/tech-design/staking-pool.md @@ -20,6 +20,8 @@ In order to be able to count votes at all, some means of proving a user's skin in the game on-chain must exist. We propose having a central StakingPool contract which mints separate per-user UTXOs in which the governance token can be deposited. The MintingPolicy of the state threads ensures that it is paid to the script and with valid initial state. This circumvents the need for a central token, and makes the minting of such tokens concurrently possible. +> Peter, 2022-01-24: "(...) mints separate per-user UTxOs (...)": I think this should read something like "locks per-user continuing UTxOs carrying unique state-thread tokens in which the governance token can be deposited." What do you think? + ### Stake UTXOs A stake UTXO stores the information to allow accessing your staked GT as if it was a safe. @@ -35,6 +37,8 @@ data Stake = Stake } ``` +> Peter, 2022-01-24: What happens is `lockedByProposals` grows too large? I know its unlikely, but have you considered devising a way circumvent this from being a possibility? + When voting for a proposal, the Stake UTXO is used to witness the user's staked amount. As a result, the two following state transitions take place (pseudocode): ```haskell @@ -46,6 +50,8 @@ A sort of mutual binding between the proposal and the stake is created and undoi Depositing and withdrawing is made illegal when `stake.lockedByProposals` isn't empty. Withdrawing is illegal so that you can't have GT in a vote, without having it anymore, whereas Depositing is illegal so that you can't deposit after a vote and unvote it again in order to retract more than you originally voted. Thus preserving that +> Peter, 2022-01-24: "Thus preserving that..." (incomplete sentence) + #### Delegating stake Most things like Cosigning sort of work trivially by just witnessing Stake, but delegation requires an extra step. We add a field to what `Stake` stores. From b4a40a56ea72a25cec5dca6adcdf022f34e9a52b Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 26 Jan 2022 12:25:11 +0000 Subject: [PATCH 04/43] first commit --- README.md | 21 +++++- docs/concepts/README.md | 37 ++++++++++ docs/diagrams/gov-overview.dot | 12 +++ docs/diagrams/gov-overview.svg | 130 +++++++++++++++++++++++++++++++++ docs/diagrams/staking-pool.dot | 6 ++ docs/diagrams/staking-pool.svg | 57 +++++++++++++++ docs/style-guide.md | 18 +++++ 7 files changed, 279 insertions(+), 2 deletions(-) create mode 100644 docs/concepts/README.md create mode 100644 docs/diagrams/gov-overview.dot create mode 100644 docs/diagrams/gov-overview.svg create mode 100644 docs/diagrams/staking-pool.dot create mode 100644 docs/diagrams/staking-pool.svg create mode 100644 docs/style-guide.md diff --git a/README.md b/README.md index a8e8e57..38eab4b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# `agora` +# Agora Agora is a set of Plutus scripts that compose together to form a Governance system. @@ -20,4 +20,21 @@ Open a dev-shell with `nix develop`, and build with `cabal build`. ## Documentation -See documentation of the agora architecture in [docs](./docs). +See documentation of the Agora architecture in [docs](./docs). + +## Road-map + +### v1 +- [ ] Governor +- [ ] Treasury +- [ ] Staking pool +- [ ] Proposals +- [ ] Effects + +### v2 +- [ ] Rewards distribution + +### Beyond + + + diff --git a/docs/concepts/README.md b/docs/concepts/README.md new file mode 100644 index 0000000..596b634 --- /dev/null +++ b/docs/concepts/README.md @@ -0,0 +1,37 @@ +# Governance concepts + +This document seeks to introduce to the reader the concept of governance systems on Cardano and acquaint them with the core components of a generic governance system. + +## Simple questions, simple answers + +### Q: What's a 'governance'? + +A: A _governance system_ is a component of a Cardano system, that allows for its community to issue and vote on proposals. + +### Q: What can be proposed? + +A: That depends on the Cardano protocol in-question. An example for a proposal could suggest that funds be released from a community treasury. Another might propose an alteration to some parameter in the wider-system. + +### Q: Who can vote? + +A: The right to vote is conferred by the _staking_ of some designated _governance token_. If one owns the relevant token, they may 'stake' some of it to vote in favour of, or opposition to, some proposal. The 'weight' of their vote will be directly proportional to the amount they stake on it. + +## Overview of components + +More-detailed information on individual components will be included in their own, specific documentation. This section provides brief descriptions on the purpose of each component. + +### Proposal + +A proposal suggests for some specified changes to be made to a Cardano system. It is voted upon by the community and, if passed, its effects are applied to the system. + +### Governor + +The governor may be conceived of as the 'centre' of a given 'governance system'. Users submit proposals to the governor, which creates them on-chain and keeps track of them. Furthermore, it holds parameters which affect the behaviour of the governance system e.g. the duration of a proposal's voting phase. Finally, it issues 'governance authority tokens', which are used to permit changes to the system. + +### Governance tokens + +Governance tokens (GTs) are a currency, which confer the right to vote on proposals. The more GTs one stakes, the more their vote counts on proposals. + +### Staking pool + +A staking pool is required, so that the system knows how much diff --git a/docs/diagrams/gov-overview.dot b/docs/diagrams/gov-overview.dot new file mode 100644 index 0000000..325ab27 --- /dev/null +++ b/docs/diagrams/gov-overview.dot @@ -0,0 +1,12 @@ +digraph { + Proposals -> Governor [label="submitted to"] + Users -> StakingPool [label="pay GT to"] + StakingPool -> Stakes [label="creates"] + Stakes -> Proposals [label="are locked by"] + Proposals -> Effects [label="have"] + Governor -> Effects [label="issues GATs to"] + Treasury -> Governor [label="releases GT to"] + "Vesting contract" -> Users [label="distributes GT amongst"] + Users -> Stakes [label="own"] + Governor -> "Vesting contract" [label="invokes"] +} diff --git a/docs/diagrams/gov-overview.svg b/docs/diagrams/gov-overview.svg new file mode 100644 index 0000000..15fe1c1 --- /dev/null +++ b/docs/diagrams/gov-overview.svg @@ -0,0 +1,130 @@ + + + + + + + + + +Proposals + +Proposals + + + +Governor + +Governor + + + +Proposals->Governor + + +submitted to + + + +Effects + +Effects + + + +Proposals->Effects + + +have + + + +Governor->Effects + + +issues GATs to + + + +Vesting contract + +Vesting contract + + + +Governor->Vesting contract + + +invokes + + + +Users + +Users + + + +StakingPool + +StakingPool + + + +Users->StakingPool + + +pay GT to + + + +Stakes + +Stakes + + + +Users->Stakes + + +own + + + +StakingPool->Stakes + + +creates + + + +Stakes->Proposals + + +are locked by + + + +Treasury + +Treasury + + + +Treasury->Governor + + +releases GT to + + + +Vesting contract->Users + + +distributes GT amongst + + + diff --git a/docs/diagrams/staking-pool.dot b/docs/diagrams/staking-pool.dot new file mode 100644 index 0000000..57f6039 --- /dev/null +++ b/docs/diagrams/staking-pool.dot @@ -0,0 +1,6 @@ +digraph { + rankdir="LR" + {User} -> StakingPool [label="pays LQ to"] + StakingPool -> Stake [label="creates"] + Stake -> Proposal [label="is locked by"] +} diff --git a/docs/diagrams/staking-pool.svg b/docs/diagrams/staking-pool.svg new file mode 100644 index 0000000..9ddbf3b --- /dev/null +++ b/docs/diagrams/staking-pool.svg @@ -0,0 +1,57 @@ + + + + + + + + + +User + +User + + + +StakingPool + +StakingPool + + + +User->StakingPool + + +pays LQ to + + + +Stake + +Stake + + + +StakingPool->Stake + + +creates + + + +Proposal + +Proposal + + + +Stake->Proposal + + +is locked by + + + diff --git a/docs/style-guide.md b/docs/style-guide.md new file mode 100644 index 0000000..92a5ea2 --- /dev/null +++ b/docs/style-guide.md @@ -0,0 +1,18 @@ +# Agora docs style guide + +This document includes a couple of notes on how Agora documentation should be written and formatted. + +## Capitalised words +The following words should always be render capitalised: + +- Agora +- Plutus +- Plutarch +- Liqwid +- LiqwidX + +## Lower-case words +The following words should always be rendered lower-case: + +- governance + From cb7356e7755dbdaca822bfa942cc33b09f1cd745 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 26 Jan 2022 14:27:23 +0000 Subject: [PATCH 05/43] Introduced meta folder --- docs/diagrams/README.md | 3 ++ docs/meta/status-format.md | 99 ++++++++++++++++++++++++++++++++++ docs/{ => meta}/style-guide.md | 0 3 files changed, 102 insertions(+) create mode 100644 docs/diagrams/README.md create mode 100644 docs/meta/status-format.md rename docs/{ => meta}/style-guide.md (100%) diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md new file mode 100644 index 0000000..9b628a0 --- /dev/null +++ b/docs/diagrams/README.md @@ -0,0 +1,3 @@ +# Diagrams + +This directory is for diagram source files (.dot) and output files (.svg, .png), which will be referenced throughout the documentation. diff --git a/docs/meta/status-format.md b/docs/meta/status-format.md new file mode 100644 index 0000000..5707e24 --- /dev/null +++ b/docs/meta/status-format.md @@ -0,0 +1,99 @@ +# Spec Status Format + +This document specifies a format used to denote the 'status' of a document. + +## Overview + +Each specification document should be headed by a simple table outlining aspects of its status in relation to: + +- Authorship +- Ownership +- Implementation(s) +- Specification Completeness + +This format should be used at the start of any documentation that may be considered a _technical specification_, with a related implementation. + +## Format + +In Markdown, the format is as follows, with {substitutions} in curly braces. + +```markdown +| Spec Status | Impl Status | Last Revision | +|-------------|-------------|---------------| +| {status} | {status} | {version}, {date} | + +-------------------- + +**Spec Ownership:** [@{owner name}] + +**Authors**: [@{author name}], [@{owner name}] + +**Impl Owner:** [@{impl owner name}] + +**Current Status**: + +{Short description of status} + +[@{owner name}]: {github url} +[@{author name}]: {github url} +[@{impl owner name]: {github url} + +-------------------- +``` + +### Spec/Impl Status + +The Spec and Impl 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. (ISO 8601 format) + +### Authors + +The authors/contributors of the spec document. + +### Spec Ownership + +The person currently, or most recently tasked with writing/maintaining the spec document. + +### Impl Owner + +The person currently or most recently tasked with the implementation of the feature/s described in the document. + +- For individual features, this will be the person currently/previously assigned to related GitHub Issues. +- For broader sections, this will be a person leading the implementation efforts for the particular system. + +## Example + +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | Draft | 1.0, 2021-10-20 | + +*** + +**Spec Ownership:** [@owner] + +**Authors**: [@author1], [@author2] + +**Impl Owner:** [@developer] + +**Current Status**: + +Draft completed in project repo. +Spec needs revisiting to address issues outlined in [#100](etc). + +[@owner]: URL + +[@author1]: URL + +[@author2]: URL + +[@developer]: URL + +*** diff --git a/docs/style-guide.md b/docs/meta/style-guide.md similarity index 100% rename from docs/style-guide.md rename to docs/meta/style-guide.md From f895a1673130b34e00bbac1de29fe07a29407941 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 26 Jan 2022 14:45:49 +0000 Subject: [PATCH 06/43] minor changes --- docs/README.md | 23 ++++++++++++++++++----- docs/meta/style-guide.md | 19 +++++++++++++------ 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/docs/README.md b/docs/README.md index 51650fa..2140611 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,31 @@ -# Agora specification & documentation +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | -This folder contains all of the specification and architecture documentation of agora. +-------------------- + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: + +-------------------- +# Agora specification and documentation + +This folder contains all of the specification and architecture documentation of Agora. ## Technical design -The `tech-design/` subdirectory contains high level description of architecture involved in building agora's governance system. +The `tech-design/` subdirectory contains high level descriptions of architecture involved in building Agora's governance system. ## Implementation -Agora makes extensive use of plutarch. So it's prerequisite for understanding the implementation. Plutarch features an [_extensive_ guide](https://github.com/Plutonomicon/plutarch/blob/master/docs/GUIDE.md), which explains many intricacies of plutarch and its use. +Agora makes extensive use of Plutarch. So it's prerequisite for understanding the implementation. Plutarch features an [_extensive_ guide](https://github.com/Plutonomicon/plutarch/blob/master/docs/GUIDE.md), which explains many intricacies of Plutarch and its use. ## Glossary -The following is a list of words/shorthands that are frequently used: +The following is a list of terms that are used frequently: - **Governance Token (GT)**: The token that holds value within the protocol and is used for voting, rewards, etc. _Examples: Liqwid's LQ_. - **Authority Token (GAT)**: A token that delegates authority of a particular script / token. See [tech-design/authority-token.md](./tech-design/authority-tokens.md) diff --git a/docs/meta/style-guide.md b/docs/meta/style-guide.md index 92a5ea2..ae99b7c 100644 --- a/docs/meta/style-guide.md +++ b/docs/meta/style-guide.md @@ -3,16 +3,23 @@ This document includes a couple of notes on how Agora documentation should be written and formatted. ## Capitalised words + The following words should always be render capitalised: -- Agora -- Plutus -- Plutarch -- Liqwid -- LiqwidX +- Agora +- Plutus +- Plutarch +- Liqwid +- LiqwidX ## Lower-case words + The following words should always be rendered lower-case: -- governance +- governance +## Avoid + +The following practices should be avoided: + +- The use of '&' e.g. 'specification and documentation' vs 'specification & documentation'. From fa1c2fa538e3b3a4ad9c025f6d09299a2dd6ff15 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 26 Jan 2022 15:17:45 +0000 Subject: [PATCH 07/43] minor tweaks to README.md --- README.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 38eab4b..70dde1c 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,43 @@ # Agora -Agora is a set of Plutus scripts that compose together to form a Governance system. +Agora is a set of Plutus scripts that compose together to form a governance system. ### What is Agora 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 Network. -- Agora aims to be modular and allow customizing specific needs, but presents an opinionated architecture. + +- 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 be modular and flexible for specific needs but presents an opinionated architecture. Non-goals: -- Agora is not a DAO. It doesn't have tokenomics or even a token. It is simply a library for governance. -- Agora doesn't aim to provide any primitive tools for plutus that are not governance-specific. For this, see [plutus-extra](https://github.com/Liqwid-Labs/plutus-extra/). + +- Agora is not a DAO. It doesn't have tokenomics or even a token. It is simply a library for governance. +- Agora doesn't aim to provide any primitive tools for Plutus that are not governance-specific. For this, see [plutus-extra](https://github.com/Liqwid-Labs/plutus-extra/). ## Project setup -An up to date `nix` (>=2.3) is required to build this project. For information on how to install, see the [nixos website](https://nixos.org/download.html). Important: See also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. +An up to date version of the [`nix` package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [nixos website](https://nixos.org/download.html). Important: See also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. -Open a dev-shell with `nix develop`, and build with `cabal build`. +Open a dev-shell with `nix develop` and build with `cabal build`. ## Documentation -See documentation of the Agora architecture in [docs](./docs). +Documentation for Agora may be found in [docs](./docs). ## Road-map ### v1 -- [ ] Governor -- [ ] Treasury -- [ ] Staking pool -- [ ] Proposals -- [ ] Effects + +- [ ] Governor +- [ ] Treasury +- [ ] Staking pool +- [ ] Proposals +- [ ] Effects ### v2 -- [ ] Rewards distribution + +- [ ] Rewards distribution ### Beyond - - +- [ ] ... From 78f8f300d535139835e3993ba248034d28539faa Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 26 Jan 2022 15:29:55 +0000 Subject: [PATCH 08/43] Added skeleton files --- docs/concepts/effects.md | 11 +++++++++++ docs/concepts/governor.md | 12 ++++++++++++ docs/concepts/proposal.md | 11 +++++++++++ docs/concepts/staking-pool.md | 11 +++++++++++ docs/concepts/treasury.md | 11 +++++++++++ docs/meta/README.md | 3 +++ docs/tech-design/effects.md | 13 +++++++++++++ docs/tech-design/governor.md | 13 +++++++++++++ docs/tech-design/treasury.md | 13 +++++++++++++ 9 files changed, 98 insertions(+) create mode 100644 docs/concepts/effects.md create mode 100644 docs/concepts/governor.md create mode 100644 docs/concepts/proposal.md create mode 100644 docs/concepts/staking-pool.md create mode 100644 docs/concepts/treasury.md create mode 100644 docs/meta/README.md create mode 100644 docs/tech-design/effects.md create mode 100644 docs/tech-design/governor.md create mode 100644 docs/tech-design/treasury.md diff --git a/docs/concepts/effects.md b/docs/concepts/effects.md new file mode 100644 index 0000000..83e961c --- /dev/null +++ b/docs/concepts/effects.md @@ -0,0 +1,11 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +*** + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: diff --git a/docs/concepts/governor.md b/docs/concepts/governor.md new file mode 100644 index 0000000..a4f307b --- /dev/null +++ b/docs/concepts/governor.md @@ -0,0 +1,12 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +-------------------- + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: + diff --git a/docs/concepts/proposal.md b/docs/concepts/proposal.md new file mode 100644 index 0000000..83e961c --- /dev/null +++ b/docs/concepts/proposal.md @@ -0,0 +1,11 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +*** + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: diff --git a/docs/concepts/staking-pool.md b/docs/concepts/staking-pool.md new file mode 100644 index 0000000..83e961c --- /dev/null +++ b/docs/concepts/staking-pool.md @@ -0,0 +1,11 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +*** + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: diff --git a/docs/concepts/treasury.md b/docs/concepts/treasury.md new file mode 100644 index 0000000..83e961c --- /dev/null +++ b/docs/concepts/treasury.md @@ -0,0 +1,11 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +*** + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: diff --git a/docs/meta/README.md b/docs/meta/README.md new file mode 100644 index 0000000..c762e15 --- /dev/null +++ b/docs/meta/README.md @@ -0,0 +1,3 @@ +# 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/tech-design/effects.md b/docs/tech-design/effects.md new file mode 100644 index 0000000..4ebef20 --- /dev/null +++ b/docs/tech-design/effects.md @@ -0,0 +1,13 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +*** + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Impl Ownership:** _unassigned_ + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: diff --git a/docs/tech-design/governor.md b/docs/tech-design/governor.md new file mode 100644 index 0000000..4ebef20 --- /dev/null +++ b/docs/tech-design/governor.md @@ -0,0 +1,13 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +*** + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Impl Ownership:** _unassigned_ + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: diff --git a/docs/tech-design/treasury.md b/docs/tech-design/treasury.md new file mode 100644 index 0000000..4ebef20 --- /dev/null +++ b/docs/tech-design/treasury.md @@ -0,0 +1,13 @@ +| Spec Status | Impl Status | Last Revision | +|-------------|----------------|---------------| +| WIP | WIP | v0.1 22/01/26 | + +*** + +**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) + +**Impl Ownership:** _unassigned_ + +**Authors**: [Jack Hodgkinson](github.com/jhodgdev) + +**Current Status**: From bd4817d25dbef9c2b43d100cc77789e39938605c Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 26 Jan 2022 16:31:58 +0000 Subject: [PATCH 09/43] began rewriting authority-tokens.md --- docs/meta/style-guide.md | 15 +++++--- docs/tech-design/authority-tokens.md | 54 +++++++++++++++------------- 2 files changed, 41 insertions(+), 28 deletions(-) diff --git a/docs/meta/style-guide.md b/docs/meta/style-guide.md index ae99b7c..c9e7265 100644 --- a/docs/meta/style-guide.md +++ b/docs/meta/style-guide.md @@ -7,14 +7,21 @@ This document includes a couple of notes on how Agora documentation should be wr The following words should always be render capitalised: - Agora -- Plutus -- Plutarch - Liqwid - LiqwidX +- Plutus +- Plutarch + +## 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: +The following words should always be rendered lower-case (unless used at the beginning of a sentence): - governance @@ -22,4 +29,4 @@ The following words should always be rendered lower-case: The following practices should be avoided: -- The use of '&' e.g. 'specification and documentation' vs 'specification & documentation'. +- The use of '&' apart from in proper nouns such as AT&T or commonly-understood abbreviations such as 'R&D'. diff --git a/docs/tech-design/authority-tokens.md b/docs/tech-design/authority-tokens.md index 7c4f6f4..c9afc36 100644 --- a/docs/tech-design/authority-tokens.md +++ b/docs/tech-design/authority-tokens.md @@ -1,39 +1,46 @@ # Authority token technical design -| Spec Status | Impl Status | Last Revision | +| Spec status | Impl status | Last revision | |-------------|-------------|---------------| | WIP | WIP | 2022-01-18 | --------------------- +*** -**Spec Ownership:** [@Emily Martins] +**Specification owner:** [Emily Martins] -**Authors**: [@Emily Martins] +**Authors**: [Emily Martins] -**Impl Owner:** [@Emily Martins] +**Implementation owner:** [Emily Martins] -[@Emily Martins]: https://github.com/emiflake +[Emily Martins]: https://github.com/emiflake --------------------- +*** ## Authority Tokens -In order to allow proposals to have a large number of potential effects, and to be extensible for different applications of governance, it is useful to have the effects be decided at a later time. In Ethereum systems, often times this is done by encoding some untyped data and calls to specific contract hashes. [Compound](https://medium.com/compound-finance/compound-governance-5531f524cf68) encodes it with `address[] Proposal.targets` (the contracts to be called) and `bytes[] Proposal.calldatas` (the data to be passed). Of course, this doesn't quite translate to Cardano's EUTXO model, so we need to achieve this some different way. +In the spirit of extensibility, a governance system should be able to readily expand the effects proposals can have on their protocol. With Ethereum systems, this is often done with untyped data and references to specific contract hashes. [Compound](https://medium.com/compound-finance/compound-governance-5531f524cf68) encodes an array of the contracts' addresses (`address[] Proposal.targets`) and the data to be passed to them (`bytes[] Proposal.calldatas`). This does not translate to Cardano's EUTXO model, so we require an alternative approach. -> Peter, 2022-01-24: "(...) be decided at a later time". later with respect to what? This could mean the effect is decided after the proposal, or that Agora doesn't specify a fixed set of effects at compile-time/run-time, etc. If it's simple enough to state, it may be helpful to say "it is useful to have the effects be decided when (...) is known. -In order to allow this flexibility, there are two facts that we rely on: -- We trust the community to validate the proposal entirely, including whether or not the effects encoded in it are written correctly. (This may mean we have a set of known and trusted effects we agree are correct and safe, collectively) -- The effects are given authority only after the proposal that promises them succeeds. +> In order to allow this flexibility, there are two facts that we rely on: + +- We trust the community to validate the proposal entirely, including whether or not the effects encoded in it are written correctly. (This may mean we have a set of known and trusted effects we agree are correct and safe, collectively) +- The effects are given authority only after the proposal that promises them succeeds. + +Our approach relies on two core assumptions: + +- We trust the community to thoroughly assess the effects of a proposal. This ensures that the effects are safe and will work as intended. + +- The effects of a proposal may only alter the system, after their associated proposal has been passed by the community. To achieve the former is rather simple, the effect validator's source code is available for anyone to look at, and it hashes correctly to the hash stored in the proposal itself. So, the LQ holders can decide on whether it is a positive for the system. > Peter, 2022-01-24: At this point in reading, its not obvious that "effect"s have validators. This is likely explained elsewhere, but this should be kept in mind when considering the order in which these specs should be read. + > Peter, 2022-01-24: Update: after some more reading, it sounds like the Effect/GAT pair is basically a way to short-circuit the "normal" validation of a UTxO at one of the component addresses; it basically says "ignore your usual validation logic; I have a GAT, so this transaction must be approved". In order to achieve the latter, we must introduce some way to give effects authority to perform their actions. -We do this by handing out "Governance Authority Tokens" (GATs) to each of the the effects belonging to a proposal after the proposal passes. When these authority tokens are *burned*, they act as a way of saying "the DAO validated this, so trust that I will ensure this transaction is correct". +We do this by handing out "Governance Authority Tokens" (GATs) to each of the the effects belonging to a proposal after the proposal passes. When these authority tokens are _burned_, they act as a way of saying "the DAO validated this, so trust that I will ensure this transaction is correct". The components that need to be adjustable at a later point will need to allow this as means for proving authority and validation of a transaction. So, for example, a Liqwid Market might need to have its parameters updated, the following diagram shows how this would happen after a proposal has successfully been voted on and passed: @@ -45,11 +52,11 @@ The components that need to be adjustable at a later point will need to allow th > Peter 2022-01-24: I think I see what's going on here, but it could use some annotations/additional description. > Tx1, a.) A proposal is closed via Tx1, and the transaction emits a continuing `Proposal` and `Governance` UtXO, -> along with an "Effect" UTxO (presumably identified in the content of the proposal). The Effect UTxO encodes effect `f` in it's validation logic. -> Question: where is this effect encoded? -> Tx1, b.) In the same transaction, a GAT is minted and paid to the UTxO. -> Tx1, c.) The `min utxo` ADA is paid to the Effect UTxO from "user inputs". I'm not certain where this is, but I'm assuming it's accumulated during voting or something? What is it used for? -> Tx2, a.) The Effect UTxO and the component to be governed are consumed in transaction 2. +> along with an "Effect" UTxO (presumably identified in the content of the proposal). The Effect UTxO encodes effect `f` in it's validation logic. +> Question: where is this effect encoded? +> Tx1, b.) In the same transaction, a GAT is minted and paid to the UTxO. +> Tx1, c.) The `min utxo` ADA is paid to the Effect UTxO from "user inputs". I'm not certain where this is, but I'm assuming it's accumulated during voting or something? What is it used for?\ +> Tx2, a.) The Effect UTxO and the component to be governed are consumed in transaction 2.\ > Tx2, b.) The Market's usual validation logic is short-circuited since the GAT was burned, and the continuing Market UTxO updates its datum. > Tx2, c.) There is a continuing "Effect" UTxO; presumably, this serves as a proof that an effect has taken place? Meaning that a sequence of effects that require a particular order of execution can consume the output UTxO as a witness? > Tx2, d.) The min ADA is paid to "user outputs"; is this just "collateral" to make sure that the effect is executed in a timely fashion? @@ -58,20 +65,19 @@ As a result of this approach, there's a number of benefits, but also details we #### Handling multiple effects in a single Proposal -Handling multile effects this way is very doable. For one, a single effect can do multiple things at once, if the script sizes allow it. But another point is that a proposal can have a *list* of hashes that it distributes GATs to. And this is all without growing size almost at all, because the actual effects are encoded in their scripts. +Handling multile effects this way is very doable. For one, a single effect can do multiple things at once, if the script sizes allow it. But another point is that a proposal can have a _list_ of hashes that it distributes GATs to. And this is all without growing size almost at all, because the actual effects are encoded in their scripts. There is the concern of expiration date of effects and incomplete execution now, however. But the customizability allows for failsafes (like retrying) and encoding expiration correctly. Due to the nature of these effects being handled by the DAO, it's assumed no conflicting effects will be executed in short succession. This is essentially impossible to encode in the system itself, so this tradeoff must be taken. -#### Writing effect code needs a *lot* of care +#### Writing effect code needs a _lot_ of care -Having delegated the authority of *the entire system* in a single token is a lot of power for one tiny script. And with great power comes great responsibility. It is important that this token doesn't fall into the wrong hands or is executed in a way that was unexpected (by the community). There's a few things we can do to help mitigate this: +Having delegated the authority of _the entire system_ in a single token is a lot of power for one tiny script. And with great power comes great responsibility. It is important that this token doesn't fall into the wrong hands or is executed in a way that was unexpected (by the community). There's a few things we can do to help mitigate this: -- We write the validator with the transaction in mind specified out in fullest. No extra inputs, no extra outputs, no extra mints, etc. Essentially this is the opposite of what we do in other places, where we try to be only as specific as we need. -- We have the transaction be executed by one of a number of community trusted members. This of course is something that is encoded in the effect, rather than anywhere else. +- We write the validator with the transaction in mind specified out in fullest. No extra inputs, no extra outputs, no extra mints, etc. Essentially this is the opposite of what we do in other places, where we try to be only as specific as we need. +- We have the transaction be executed by one of a number of community trusted members. This of course is something that is encoded in the effect, rather than anywhere else. Hopefully, this is sufficient to ensure the transactions are created correctly, and nothing unexpected slips in. This problem is no more complicated or dangerous than elsewhere where we delegate certain trust or authority to just the validation or movement of a token. - > 2022-01-24, Peter: Have you considered placing the validator hash of the effect script in the token name? This could tie a proposal to a GAT to a validator, instead of having any GAT work with any effect script. > 2022-01-24, Peter: This section could use some additional explaination/pseudo-code of the what the GAT minting policy would look like and what additional validation logic would go into a govern-able component From 5101fb8e1f51d0032a94d58ba225ef390b41baca Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Fri, 28 Jan 2022 13:38:20 +0000 Subject: [PATCH 10/43] fixed missing brace in meta status document --- docs/meta/status-format.md | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/meta/status-format.md b/docs/meta/status-format.md index 5707e24..627fce1 100644 --- a/docs/meta/status-format.md +++ b/docs/meta/status-format.md @@ -1,6 +1,6 @@ # Spec Status Format -This document specifies a format used to denote the 'status' of a document. +This document specifies a format used to denote the 'status' of a spec document. ## Overview @@ -17,6 +17,26 @@ This format should be used at the start of any documentation that may be conside In Markdown, the format is as follows, with {substitutions} in curly braces. +| Spec Status | Impl Status | Last Revision | +|-------------|-------------|---------------| +| {status} | {status} | {version}, {date} | + +-------------------- + +**Spec Ownership:** [{owner name}] + +**Authors**: [{author name}], [{owner name}] + +**Impl Owner:** [{impl owner name}] + +**Current Status**: + +{Short description of status} + +[{owner name}]: {github url} +[{author name}]: {github url} +[{impl owner name}]: {github url} + ```markdown | Spec Status | Impl Status | Last Revision | |-------------|-------------|---------------| @@ -24,19 +44,19 @@ In Markdown, the format is as follows, with {substitutions} in curly braces. -------------------- -**Spec Ownership:** [@{owner name}] +**Spec Ownership:** [{owner name}] -**Authors**: [@{author name}], [@{owner name}] +**Authors**: [{author name}], [{owner name}] -**Impl Owner:** [@{impl owner name}] +**Impl Owner:** [{impl owner name}] **Current Status**: {Short description of status} -[@{owner name}]: {github url} -[@{author name}]: {github url} -[@{impl owner name]: {github url} +[{owner name}]: {github url} +[{author name}]: {github url} +[{impl owner name}]: {github url} -------------------- ``` From bd0b81251d5a6f45e0bfe3709614e5713f3618db Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 31 Jan 2022 12:09:59 +0000 Subject: [PATCH 11/43] began rework on meta status doc --- docs/meta/status-format.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/meta/status-format.md b/docs/meta/status-format.md index 627fce1..0b74365 100644 --- a/docs/meta/status-format.md +++ b/docs/meta/status-format.md @@ -6,12 +6,12 @@ This document specifies a format used to denote the 'status' of a spec document. Each specification document should be headed by a simple table outlining aspects of its status in relation to: -- Authorship -- Ownership -- Implementation(s) -- Specification Completeness +- 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. +This format should be used at the start of any documentation that may be considered a _technical specification_, with a related implementation. For anything conceptual, information regarding implementations and completeness may be omitted. ## Format From 2e05890d15132f6d2a64acd0469d55c6f4f12a9f Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 31 Jan 2022 12:41:41 +0000 Subject: [PATCH 12/43] Update status-format.md --- docs/meta/status-format.md | 114 ++++++++++++++++++------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/meta/status-format.md b/docs/meta/status-format.md index 0b74365..2a71ee8 100644 --- a/docs/meta/status-format.md +++ b/docs/meta/status-format.md @@ -1,4 +1,4 @@ -# Spec Status Format +# Spec status format This document specifies a format used to denote the 'status' of a spec document. @@ -11,46 +11,51 @@ Each specification document should be headed by a simple table outlining aspects - 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. For anything conceptual, information regarding implementations and completeness may be omitted. +This format should be used at the start of any documentation that may be considered a _technical specification_, with a related implementation. ## Format -In Markdown, the format is as follows, with {substitutions} in curly braces. +The format is as follows, with {substitutions} in curly braces. -| Spec Status | Impl Status | Last Revision | -|-------------|-------------|---------------| -| {status} | {status} | {version}, {date} | +| Specification | Implementation | Last Revision | +|:-------------:|:--------------:|:-------------:| +| {status} | {status} | {version}, {date} | -------------------- -**Spec Ownership:** [{owner name}] +**Specification ownership:** {[Spec owner]} -**Authors**: [{author name}], [{owner name}] +**Authors**: + - {[Spec owner]} + - {[Author]} -**Impl Owner:** [{impl owner name}] +**Implementation ownership:** {[Impl owner]} -**Current Status**: +**Current status**: -{Short description of status} +{Short description of status regarding __both__ specification and implementation}. -[{owner name}]: {github url} -[{author name}]: {github url} -[{impl owner name}]: {github url} +[Spec owner]: https://genrandom.com/cats/ +[Author]: https://genrandom.com/cats/ +[Impl owner]: https://genrandom.com/cats/ ```markdown -| Spec Status | Impl Status | Last Revision | -|-------------|-------------|---------------| -| {status} | {status} | {version}, {date} | +| Specification | Implementation | Last Revision | +|:-------------:|:--------------:|:-------------:| +| {status} | {status} | {version}, {date} | -------------------- -**Spec Ownership:** [{owner name}] +**Specification ownership:** [{owner name}] -**Authors**: [{author name}], [{owner name}] +**Authors**: + - [{owner name}] + - [{author name}] -**Impl Owner:** [{impl owner name}] + +**Implementation ownership:** [{impl owner name}] -**Current Status**: +**Current status**: {Short description of status} @@ -61,59 +66,54 @@ In Markdown, the format is as follows, with {substitutions} in curly braces. -------------------- ``` -### Spec/Impl Status +### Specification/Implementation status -The Spec and Impl status should be one of the following: +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. +- `Final`: Complete and finalised to some degree of certainty. -### Last Revision +### Last revision -- version - An (optional) version/revision number for the spec document. -- date - date the document was last updated. (ISO 8601 format) +- 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/contributors of the spec document. +The authors and contributors of the spec document. -### Spec Ownership +### Specificiation ownership -The person currently, or most recently tasked with writing/maintaining the spec document. +The person currently, or most recently tasked with writing and maintaining the spec document. -### Impl Owner +### Implementation ownership -The person currently or most recently tasked with the implementation of the feature/s described in the document. +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 currently/previously assigned to related GitHub Issues. +- 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 -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | Draft | 1.0, 2021-10-20 | - -*** - -**Spec Ownership:** [@owner] - -**Authors**: [@author1], [@author2] - -**Impl Owner:** [@developer] - -**Current Status**: - -Draft completed in project repo. -Spec needs revisiting to address issues outlined in [#100](etc). - -[@owner]: URL - -[@author1]: URL - -[@author2]: URL - -[@developer]: URL +| 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 *** From 84508a448259aa802c9924145ab12f119e81adfc Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 31 Jan 2022 15:55:04 +0000 Subject: [PATCH 13/43] updated gov overview diagram --- docs/diagrams/gov-overview.dot | 12 +-- docs/diagrams/gov-overview.svg | 180 +++++++++++++-------------------- 2 files changed, 77 insertions(+), 115 deletions(-) diff --git a/docs/diagrams/gov-overview.dot b/docs/diagrams/gov-overview.dot index 325ab27..5b1ab3c 100644 --- a/docs/diagrams/gov-overview.dot +++ b/docs/diagrams/gov-overview.dot @@ -1,12 +1,8 @@ digraph { - Proposals -> Governor [label="submitted to"] - Users -> StakingPool [label="pay GT to"] - StakingPool -> Stakes [label="creates"] - Stakes -> Proposals [label="are locked by"] + "Staking pool" -> Stakes [label="tracks"] + Stakes -> Proposals [label="are put on"] Proposals -> Effects [label="have"] Governor -> Effects [label="issues GATs to"] - Treasury -> Governor [label="releases GT to"] - "Vesting contract" -> Users [label="distributes GT amongst"] - Users -> Stakes [label="own"] - Governor -> "Vesting contract" [label="invokes"] + Users -> Stakes [label="lock GT in"] + Users -> Treasury [label="claim GT from"] } diff --git a/docs/diagrams/gov-overview.svg b/docs/diagrams/gov-overview.svg index 15fe1c1..008d286 100644 --- a/docs/diagrams/gov-overview.svg +++ b/docs/diagrams/gov-overview.svg @@ -4,127 +4,93 @@ - - - - + + + + -Proposals - -Proposals - - - -Governor - -Governor - - - -Proposals->Governor - - -submitted to - - - -Effects - -Effects - - - -Proposals->Effects - - -have - - - -Governor->Effects - - -issues GATs to - - - -Vesting contract - -Vesting contract - - - -Governor->Vesting contract - - -invokes - - - -Users - -Users - - - -StakingPool - -StakingPool - - - -Users->StakingPool - - -pay GT to +Staking pool + +Staking pool - + Stakes - -Stakes + +Stakes - - -Users->Stakes - - -own + + +Staking pool->Stakes + + +tracks - - -StakingPool->Stakes - - -creates + + +Proposals + +Proposals - + Stakes->Proposals - - -are locked by + + +are put on + + + +Effects + +Effects + + + +Proposals->Effects + + +have + + + +Governor + +Governor + + + +Governor->Effects + + +issues GATs to + + + +Users + +Users + + + +Users->Stakes + + +lock GT in Treasury - -Treasury + +Treasury - - -Treasury->Governor - - -releases GT to - - - -Vesting contract->Users - - -distributes GT amongst + + +Users->Treasury + + +claim GT from From bc60a3a959d6dce2ec7ceff50066f547df91560d Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Tue, 1 Feb 2022 10:37:08 +0000 Subject: [PATCH 14/43] expanded concepts README --- docs/concepts/README.md | 63 ++++++++++++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 10 deletions(-) diff --git a/docs/concepts/README.md b/docs/concepts/README.md index 596b634..8245165 100644 --- a/docs/concepts/README.md +++ b/docs/concepts/README.md @@ -1,3 +1,26 @@ +| Specification | Last Revision | +|:-------------:|:-------------:| +| Draft | v0.1, 2022-02-01 | + +*** + +**Specification ownership:** [Jack Hodgkinson] + +**Authors**: + +- [Jack Hodgkinson] +- [Emily Martins] + +**Current status**: + +Considering potential expansion of 'Simple questions, simple answers' section. Awaiting review from @emiflake. + +[Jack Hodgkinson]: https://github.com/jhodgdev + +[Emily Martins]: https://github.com/emiflake + +*** + # Governance concepts This document seeks to introduce to the reader the concept of governance systems on Cardano and acquaint them with the core components of a generic governance system. @@ -14,24 +37,44 @@ A: That depends on the Cardano protocol in-question. An example for a proposal c ### Q: Who can vote? -A: The right to vote is conferred by the _staking_ of some designated _governance token_. If one owns the relevant token, they may 'stake' some of it to vote in favour of, or opposition to, some proposal. The 'weight' of their vote will be directly proportional to the amount they stake on it. +A: The right to vote is conferred by the _staking_ of some designated _governance token_ (GT). If one owns the relevant token, they may 'stake' some of it to vote in favour of, or opposition to, some proposal. ## Overview of components +![Governance overview diagram](/docs/diagrams/gov-overview.svg "Governance overview diagram") + More-detailed information on individual components will be included in their own, specific documentation. This section provides brief descriptions on the purpose of each component. +### Users + +A user is a member of the DAO (decentralised autonomous organisation), who +may choose to redeem governance tokens (GT) from the treasury and stake those GT +to vote in favour of, or opposition to, proposals. + +### Governance tokens + +Governance tokens (GTs) are a currency, which confer the right to vote on proposals. + +### Treasury + +The treasury of a governance system is responsible for determining which users are entitled to what GT rewards and when. If a user is eligible for a reward, it they must claim it from the treasury. A treasury can also serve as a form of 'DAO wallet', storing and saving funds that can be later spent by the community. + +### Stakes + +Users are required to 'lock' their GT in stakes, so that the system has some idea of their eligibility to vote on proposal. + +### Staking pool + +A staking pool can be introduced, for the purpose of tracking the aggregate status of all stakes in the system. Some systems may not require a staking pool. + ### Proposal A proposal suggests for some specified changes to be made to a Cardano system. It is voted upon by the community and, if passed, its effects are applied to the system. +### Effects + +Proposals may have one or many 'effects', which represent the concrete, individual changes the proposal would make to the system. If their corresponding proposals have been passed, each effect is granted a _governance authority token_ (GAT) by the governor. This token permits the effect to alter the system. + ### Governor -The governor may be conceived of as the 'centre' of a given 'governance system'. Users submit proposals to the governor, which creates them on-chain and keeps track of them. Furthermore, it holds parameters which affect the behaviour of the governance system e.g. the duration of a proposal's voting phase. Finally, it issues 'governance authority tokens', which are used to permit changes to the system. - -### Governance tokens - -Governance tokens (GTs) are a currency, which confer the right to vote on proposals. The more GTs one stakes, the more their vote counts on proposals. - -### Staking pool - -A staking pool is required, so that the system knows how much +The governor is responsible for validating whether proposals have passed. If they have, it issues GATs to the proposals effects. From b963a83f4149969933b227e35c489dd49ff00112 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Tue, 1 Feb 2022 10:45:47 +0000 Subject: [PATCH 15/43] fixed single typo --- docs/concepts/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/README.md b/docs/concepts/README.md index 8245165..5c6c0a9 100644 --- a/docs/concepts/README.md +++ b/docs/concepts/README.md @@ -77,4 +77,4 @@ Proposals may have one or many 'effects', which represent the concrete, individu ### Governor -The governor is responsible for validating whether proposals have passed. If they have, it issues GATs to the proposals effects. +The governor is responsible for validating whether proposals have passed. If they have, it issues GATs to the proposals' effects. From 1bf2fa1a3301bdebaa8f918cd98279daa2881202 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 11:10:23 +0000 Subject: [PATCH 16/43] Implemented changes to authority token docs --- docs/tech-design/authority-tokens.md | 63 +++++++++++++--------------- 1 file changed, 29 insertions(+), 34 deletions(-) diff --git a/docs/tech-design/authority-tokens.md b/docs/tech-design/authority-tokens.md index c9afc36..9cafa3e 100644 --- a/docs/tech-design/authority-tokens.md +++ b/docs/tech-design/authority-tokens.md @@ -1,50 +1,43 @@ # Authority token technical design -| Spec status | Impl status | Last revision | -|-------------|-------------|---------------| -| WIP | WIP | 2022-01-18 | +| Specification | Implementation | Last revision | +|:-----------:|:-----------:|:-------------:| +| WIP | WIP | 2022-02-02 | *** **Specification owner:** [Emily Martins] -**Authors**: [Emily Martins] +**Authors**: + +- [Emily Martins] +- [Jack Hodgkinson] **Implementation owner:** [Emily Martins] [Emily Martins]: https://github.com/emiflake +[Jack Hodgkinson]: https://github.com/jhodgdev + *** -## Authority Tokens +## Authority tokens In the spirit of extensibility, a governance system should be able to readily expand the effects proposals can have on their protocol. With Ethereum systems, this is often done with untyped data and references to specific contract hashes. [Compound](https://medium.com/compound-finance/compound-governance-5531f524cf68) encodes an array of the contracts' addresses (`address[] Proposal.targets`) and the data to be passed to them (`bytes[] Proposal.calldatas`). This does not translate to Cardano's EUTXO model, so we require an alternative approach. +Our approach relies on two core assumptions: -> In order to allow this flexibility, there are two facts that we rely on: +- We trust the community to thoroughly assess the effects of a proposal. This ensures that the effects are safe and will work as intended. -- We trust the community to validate the proposal entirely, including whether or not the effects encoded in it are written correctly. (This may mean we have a set of known and trusted effects we agree are correct and safe, collectively) -- The effects are given authority only after the proposal that promises them succeeds. +- The effects of a proposal may only alter the system, after their associated proposal has been passed by the community. -Our approach relies on two core assumptions: +The first assumption is justified by the fact that any proposal stores the hash of its effects' codes, and these effects are available for any user to inspect. The community of GT-holders will be able to verify a proposal's purported benefits. -- We trust the community to thoroughly assess the effects of a proposal. This ensures that the effects are safe and will work as intended. +To ensure the latter assumption holds true, we introduce 'governance authority tokens' (GATs). Any effect that wishes to alter the system will be required to _burn_ a GAT, when it is enacted. These GATs will be issued to a proposal's effects via the governor component, which has the responsibility of ensuring that a proposal passed in a correct and valid manner. Conceptually, the ownership of a GAT by an effect is a way of demonstrating to a component: 'the DAO (decentralised autonomous organisation) has granted me permission to alter your parameters'. -- The effects of a proposal may only alter the system, after their associated proposal has been passed by the community. +> The components that need to be adjustable at a later point will need to allow this as means for proving authority and validation of a transaction. So, for example, a Liqwid market might need to have its parameters updated, the following diagram shows how this would happen after a proposal has successfully been voted on and passed: -To achieve the former is rather simple, the effect validator's source code is available for anyone to look at, and it hashes correctly to the hash stored in the proposal itself. So, the LQ holders can decide on whether it is a positive for the system. - -> Peter, 2022-01-24: At this point in reading, its not obvious that "effect"s have validators. This is likely explained elsewhere, but this should be kept in mind when considering the order in which these specs should be read. - -> Peter, 2022-01-24: Update: after some more reading, it sounds like the Effect/GAT pair is basically a way to short-circuit the "normal" validation of a UTxO at one of the component addresses; it basically says "ignore your usual validation logic; I have a GAT, so this transaction must be approved". - -In order to achieve the latter, we must introduce some way to give effects authority to perform their actions. - -We do this by handing out "Governance Authority Tokens" (GATs) to each of the the effects belonging to a proposal after the proposal passes. When these authority tokens are _burned_, they act as a way of saying "the DAO validated this, so trust that I will ensure this transaction is correct". - -The components that need to be adjustable at a later point will need to allow this as means for proving authority and validation of a transaction. So, for example, a Liqwid Market might need to have its parameters updated, the following diagram shows how this would happen after a proposal has successfully been voted on and passed: - -> Peter, 2022-01-24: RE: "(...) need to be adjustable at a (...)": could it make more sense to say "adjusted via governance"? +This model naturally requires that any component of the system, desired to be adjustable via governance is aware of the existence and significance of GATs. For example, a [Liqwid](https://github.com/mlabs-haskell/liqwid-contracts/) market may be subject to the effects of a successful proposal to alter its parameters. The following diagram shows how such an update would occur: ![Governance Authority Token UTxO flow diagram](../diagrams/GovernanceAuthorityToken.svg) @@ -61,23 +54,25 @@ The components that need to be adjustable at a later point will need to allow th > Tx2, c.) There is a continuing "Effect" UTxO; presumably, this serves as a proof that an effect has taken place? Meaning that a sequence of effects that require a particular order of execution can consume the output UTxO as a witness? > Tx2, d.) The min ADA is paid to "user outputs"; is this just "collateral" to make sure that the effect is executed in a timely fashion? -As a result of this approach, there's a number of benefits, but also details we need to watch out for: +This approach has a number of benefits but some important details must be kept in mind: -#### Handling multiple effects in a single Proposal +#### Handling multiple effects in a single proposal -Handling multile effects this way is very doable. For one, a single effect can do multiple things at once, if the script sizes allow it. But another point is that a proposal can have a _list_ of hashes that it distributes GATs to. And this is all without growing size almost at all, because the actual effects are encoded in their scripts. +Cardano script sizes are restricted to 16KB and previous proposal/effect models have had difficulties generating scripts which keep under this limit. By decoupling proposals and their effects, a proposal can have a far greater number of effects, as all it contains is a list of hashes for said effects. Effects themselves can make any number of changes to the system, as long as the resulting script is kept to an allowable size. -There is the concern of expiration date of effects and incomplete execution now, however. But the customizability allows for failsafes (like retrying) and encoding expiration correctly. Due to the nature of these effects being handled by the DAO, it's assumed no conflicting effects will be executed in short succession. This is essentially impossible to encode in the system itself, so this tradeoff must be taken. +It is essentially impossible for the system to prevent from conflicting effects taking place in short order and harming the system but the likelihood of this occurring is sufficiently reduced by all effects first having be passed by the DAO. There is scope for adding a notion of 'expiration', after which effects will no longer be able to enact their changes. -#### Writing effect code needs a _lot_ of care +#### Writing effect code requires a _lot_ of care -Having delegated the authority of _the entire system_ in a single token is a lot of power for one tiny script. And with great power comes great responsibility. It is important that this token doesn't fall into the wrong hands or is executed in a way that was unexpected (by the community). There's a few things we can do to help mitigate this: +The ability to alter large swathes of the system being conferred by the ownership of a single token poses the risk of (purposeful or inadvertent) harm. There are steps one can take to lessen this risk: -- We write the validator with the transaction in mind specified out in fullest. No extra inputs, no extra outputs, no extra mints, etc. Essentially this is the opposite of what we do in other places, where we try to be only as specific as we need. -- We have the transaction be executed by one of a number of community trusted members. This of course is something that is encoded in the effect, rather than anywhere else. +> Jack 2022-02-02: Is there any scope for 'domain specific' GATs? Effects could be limited to altering a single component of the system and therefore be issued with GATs that only permit the altering of that component. -Hopefully, this is sufficient to ensure the transactions are created correctly, and nothing unexpected slips in. This problem is no more complicated or dangerous than elsewhere where we delegate certain trust or authority to just the validation or movement of a token. +- All validators for an effect transaction are specified **in full**. In comparison to the normal writing of validators, where one only specifies what they must, one must do all they can to avoid undesired behaviour being permitted by the validator. +- All transactions are only executed by one of a few 'trusted' DAO members. This would necessarily have to be encoded in the effect. + +This should be sufficient to prevent loopholes. Delegating authority through validation or movement of tokens is often a necessary risk in blockchain systems and this problem is no more complex than others of its kind. > 2022-01-24, Peter: Have you considered placing the validator hash of the effect script in the token name? This could tie a proposal to a GAT to a validator, instead of having any GAT work with any effect script. -> 2022-01-24, Peter: This section could use some additional explaination/pseudo-code of the what the GAT minting policy would look like and what additional validation logic would go into a govern-able component +> 2022-01-24, Peter: This section could use some additional explanation/pseudo-code of the what the GAT minting policy would look like and what additional validation logic would go into a governable component From 2387055b5c21b97e3cf6d672029fe4bc1c01073e Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 12:12:14 +0000 Subject: [PATCH 17/43] Posted updates on proposals technical design --- docs/tech-design/authority-tokens.md | 8 ++- docs/tech-design/proposals.md | 101 +++++++++++++-------------- 2 files changed, 54 insertions(+), 55 deletions(-) diff --git a/docs/tech-design/authority-tokens.md b/docs/tech-design/authority-tokens.md index 9cafa3e..e8a55ab 100644 --- a/docs/tech-design/authority-tokens.md +++ b/docs/tech-design/authority-tokens.md @@ -19,6 +19,12 @@ [Jack Hodgkinson]: https://github.com/jhodgdev +[Peter Dragos]: https://github.com/peter-mlabs + +**Current status:** + +Initially written up by [Emily Martins] for Liqwid. Transferred across to Agora. Rewritten by [Jack Hodgkinson]. Outstanding suggestions from [Peter Dragos] that require addressing. + *** ## Authority tokens @@ -66,8 +72,6 @@ It is essentially impossible for the system to prevent from conflicting effects The ability to alter large swathes of the system being conferred by the ownership of a single token poses the risk of (purposeful or inadvertent) harm. There are steps one can take to lessen this risk: -> Jack 2022-02-02: Is there any scope for 'domain specific' GATs? Effects could be limited to altering a single component of the system and therefore be issued with GATs that only permit the altering of that component. - - All validators for an effect transaction are specified **in full**. In comparison to the normal writing of validators, where one only specifies what they must, one must do all they can to avoid undesired behaviour being permitted by the validator. - All transactions are only executed by one of a few 'trusted' DAO members. This would necessarily have to be encoded in the effect. diff --git a/docs/tech-design/proposals.md b/docs/tech-design/proposals.md index 1baf73b..44f6f40 100644 --- a/docs/tech-design/proposals.md +++ b/docs/tech-design/proposals.md @@ -1,93 +1,88 @@ -# Proposals Technical Design +# Proposals technical design -This document gives an overview of technical design aspects of the Proposals system for introducing, voting on and executing Governance Proposals. +This document gives an overview of the technical design of the proposals system for introducing, voting on and executing governance proposals. -| Spec Status | Impl Status | Last Revision | -|-------------|-------------|---------------| -| WIP | WIP | 2022-01-19 | +| Specification | Implementation | Last revision | +|:-----------:|:-----------:|:-------------:| +| WIP | WIP | v0.1 2022-02-02 | --------------------- +*** -**Spec Ownership:** [@Emily Martins] +**Specification ownership:** [Emily Martins] -**Authors**: [@Emily Martins] +**Authors**: -**Impl Owner:** [@Emily Martins] +- [Emily Martins] +- [Jack Hodgkinson] -[@Emily Martins]: https://github.com/emiflake +**Implementation ownership:** [Emily Martins] --------------------- +[Emily Martins]: https://github.com/emiflake + +[Jack Hodgkinson]: https://github.com/jhodgdev + +**Current status**: + +Imported from Liqwid by [Emily Martins]. Underwent rewrite by [Jack Hodgkinson].Further amendments to the 'period table' should be considered. Outstanding remarks from Peter Dragos that require attention. + +*** ## Proposals -Initiating a proposal requires the initiator to have more than a certain amount of LQ in the StakingPool (e.g. around 6-10 LQ). This is checked by consuming the proposer's stake utxo. Creating a proposal forges a proposal script state thread which is where all voting interactions happen within. Proposals are tracked in coordination with the governance, so it must be included in the transaction as well. +Initiating a proposal requires the proposer to have more than a certain amount of GT staked in the system e.g. 5GT. This is checked by consuming the UTXO representing the user's stake. Initiating a proposal creates a script, which will handle all voting interactions. -> Peter, 2022-01-24: "(...) than a certain amount of **LQ**". two questions: 1.) Is this up to date? 2.) Given that agora doesn't have a token, what should this token be called in the abstract? -> Peter, 2022-01-24: "(...) coordination with the governance": We've adopted the terminology in LiqwidX "Governor" to refer to the continuing UTxO that tracks governance-related activities, and use "governance" to refer to "what the Governor does/enables". Do you make the same distinction? +## Voting -### Proposal voting +### Voting stages -##### Overview of stages - -A proposal fits into a state machine neatly. Draft being the starting state, and Executed or Failed being the final states. It should be noted that, for optimization reasons, not all states are exactly physical, instead, the current state is a product of the current time as well. For instance, after the voting has ended, no state transition on-chain occurs. +The life-cycle of a proposal is neatly represented by a state machine, with the 'draft' phase being the initial state, and 'executed' and 'failed' being the terminating states. Please note that this state-machine representation is purely conceptual and should not be expected to reflect technical implementation. ![](../diagrams/ProposalStateMachine.svg) -##### When is each interaction valid? +#### When may interactions occur? -- `S`: When the proposal was created -- `D`: The length of the draft period -- `V`: The length of the voting period -- `L`: The length of the locking period -- `E`: The length of the execution period +Consider the following 'stages' of a proposal: -| Action | Valid POSIXTimeRange | Valid *stored* state(s) | +- `S`: when the proposal was created. +- `D`: the length of the draft period. +- `V`: the length of the voting period. +- `L`: the length of the locking period. +- `E`: the length of the execution period. + +| Action | Valid POSIXTimeRange | Valid _stored_ state(s) | |-------------------------------------|------------------------------------|-------------------------| -| Witness | [S, ∞) | * | -| Cosign | [S, S + D) | Draft | -| AdvanceProposal | [S, S + D) | Draft | -| Vote | [S + D, S + D + V) | Voting | -| Unlock | [S + D, ∞) | * | -| CountVotes (? see spec comment) | [S + D + V, S + D + V + L) | Voting | -| ExecuteProposal (if quorum reached) | [S + D + V + L, S + D + V + L + E) | Voting | +| Witness | \[S, ∞] | \* | +| Cosign | \[S, S + D] | Draft | +| AdvanceProposal | \[S, S + D] | Draft | +| Vote | \[S + D, S + D + V] | Voting | +| Unlock | \[S + D, ∞] | \* | +| CountVotes (? see spec comment) | \[S + D + V, S + D + V + L] | Voting | +| ExecuteProposal (if quorum reached) | \[S + D + V + L, S + D + V + L + E] | Voting | ```diff - CountVotes takes a snapshot after voting has ended, it allows users to unlock their stake without affecting votes, after the lock period has ended. This is an optional feature of locking, do we want this? ``` +> Jack 2022-02-02: I will consider revising this table further at a later time. + #### Draft phase -During the Draft phase, the proposal script has been minted. At this stage, only votes in favor of cosigning the draft will count. For the proposal to get into the voting phase, a certain amount of LQ will have to be backing the proposal. The UTXO can be queried for any metadata it contains, should it contain any useful information. LQ holders can "cosign" the proposal and add their LQ in order to allow the motion to get into the voting phase. - -> Peter, 2022-01-24: "(...) the proposal script has been minted." I think this should be "the draft proposal's state thread token has been minted and paid to the proposal's UTxO." -> Peter, 2022-01-24: "(...) a certain amount of LQ": how much? Where is this set/calculated? +During the draft phase, the proposal script has been minted. At this stage, only votes in favor of co-signing the draft are counted. For the proposal to transition to the voting phase, a threshold of GT will have to be staked backing the proposal. This threshold will be determined on a per-system basis and could itself be a 'governable' parameter. #### Voting phase -During the voting phase a voter can submit a vote either in favour or against the proposal. This simply adds their PubKey to the list of votes as a state-machine action. By virtue of being a state-machine action, this causes contention, and may be rate-limited through some means. - -> Peter, 2022-01-24: What happens in the event of a tie? How are the votes tailled? Is it always simple majority, or are more complex [social choice procedures](https://en.wikipedia.org/wiki/Social_choice_theory) in-scope for Agora (even if its V2, V3...) - -##### What determines a successful proposal? - -When initializing a proposal, the governance's thresholds are passed along, one of the thresholds is the `quorum`. +In the voting phase, users may utilise their stakes to vote in-favour or in-opposition to a proposal. This adds their public key to the proposal. There is potential for contention within the system and therefore may have to be rate-limited. The method by which a user's stakes are weighted and the thresholds required for proposals to pass are determined on a per-protocol basis. #### Lock phase -After the voting phase has completed, the proposal has either passed, or failed. - -We wait a set time before allowing execution of the proposal's effects. This is to allow LQ holders time to prepare for the change in whichever way they see fit. This is also a security mechanism, should the system be at risk of hostile takeover. +Upon completion of the voting phase, a proposal will either have been passed or failed. A delay between the passing of a proposal and execution of its effects will be enforced, to allow users to prepare for incoming changes to the system. It'll further give the system maintainers opportunity to intervene, in the case of a hostile action. > Peter, 2022-01-24: How is this time decided? Are you familiar with the "Emergency Shutdown Mode" of MakerDAO, which we'll be adopting in LiqwidX? This is something that would, for the most part, need to happen ASAP. What sort of modularity exists or would you like to see? #### Execution phase -In the case of a failed proposal, the proposal will simply be frozen in time and never interacted with anymore. There is no value locked behind a proposal, besides the state thread itself, so nothing is lost. +Failed proposals will not be interacted with further. The only value they will contain is their state thread tokens, so nothing of worth is lost. -In the case of a successful proposal, anyone can execute the effects, as it can only be done in a lawful way. +Successful proposals will be verified by the governor component, which will issue ['governance authority tokens'](/docs/tech-design/authority-tokens.md) (GATs) to a proposal's separate 'effects'. The burning of these tokens will be a pre-requisite for system changes to be made, therefore the possession of one will serve as a form of 'licence' for making the changes. -There is a deadline for how long it can take for the proposal to get executed. Again, as the proposal is necessarily something that has been agreed by the voters, it will be incentivized naturally to be executed. - -See [tech-design/authority-token.md](./authority-tokens.md) for how effects take place after execution - -> Peter 2022-01-24: I _think_ it may be useful to have some way to witness on-chain whether a proposal succeeded or failed, and by what margins. I'm not certain whether this would be possible with what you currently have in mind, but it could allow for a more expressive governenace structure or allow for other actions to depend on the success/failure of proposals that aren't directly part of the system being governed (i.e., a validator that only locks/unlocks value if a proposal goes a certain way). +There will be a deadline before which a proposal's effects will have to be executed. As any passed proposal's effects will necessarily have been supported by the community, it can be presumed that community members will have be incentivised to ensure the effects are enacted soon after the proposal has been passed. From 9d11bb1fe8954d1adf98d792b50934b9614ce5e2 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 13:59:26 +0000 Subject: [PATCH 18/43] removed concepts subdir --- docs/governance-concepts.md | 80 +++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/governance-concepts.md diff --git a/docs/governance-concepts.md b/docs/governance-concepts.md new file mode 100644 index 0000000..5c6c0a9 --- /dev/null +++ b/docs/governance-concepts.md @@ -0,0 +1,80 @@ +| Specification | Last Revision | +|:-------------:|:-------------:| +| Draft | v0.1, 2022-02-01 | + +*** + +**Specification ownership:** [Jack Hodgkinson] + +**Authors**: + +- [Jack Hodgkinson] +- [Emily Martins] + +**Current status**: + +Considering potential expansion of 'Simple questions, simple answers' section. Awaiting review from @emiflake. + +[Jack Hodgkinson]: https://github.com/jhodgdev + +[Emily Martins]: https://github.com/emiflake + +*** + +# Governance concepts + +This document seeks to introduce to the reader the concept of governance systems on Cardano and acquaint them with the core components of a generic governance system. + +## Simple questions, simple answers + +### Q: What's a 'governance'? + +A: A _governance system_ is a component of a Cardano system, that allows for its community to issue and vote on proposals. + +### Q: What can be proposed? + +A: That depends on the Cardano protocol in-question. An example for a proposal could suggest that funds be released from a community treasury. Another might propose an alteration to some parameter in the wider-system. + +### Q: Who can vote? + +A: The right to vote is conferred by the _staking_ of some designated _governance token_ (GT). If one owns the relevant token, they may 'stake' some of it to vote in favour of, or opposition to, some proposal. + +## Overview of components + +![Governance overview diagram](/docs/diagrams/gov-overview.svg "Governance overview diagram") + +More-detailed information on individual components will be included in their own, specific documentation. This section provides brief descriptions on the purpose of each component. + +### Users + +A user is a member of the DAO (decentralised autonomous organisation), who +may choose to redeem governance tokens (GT) from the treasury and stake those GT +to vote in favour of, or opposition to, proposals. + +### Governance tokens + +Governance tokens (GTs) are a currency, which confer the right to vote on proposals. + +### Treasury + +The treasury of a governance system is responsible for determining which users are entitled to what GT rewards and when. If a user is eligible for a reward, it they must claim it from the treasury. A treasury can also serve as a form of 'DAO wallet', storing and saving funds that can be later spent by the community. + +### Stakes + +Users are required to 'lock' their GT in stakes, so that the system has some idea of their eligibility to vote on proposal. + +### Staking pool + +A staking pool can be introduced, for the purpose of tracking the aggregate status of all stakes in the system. Some systems may not require a staking pool. + +### Proposal + +A proposal suggests for some specified changes to be made to a Cardano system. It is voted upon by the community and, if passed, its effects are applied to the system. + +### Effects + +Proposals may have one or many 'effects', which represent the concrete, individual changes the proposal would make to the system. If their corresponding proposals have been passed, each effect is granted a _governance authority token_ (GAT) by the governor. This token permits the effect to alter the system. + +### Governor + +The governor is responsible for validating whether proposals have passed. If they have, it issues GATs to the proposals' effects. From c299c87c8f909a323b5ab0220ffe3edbc8470eb1 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 13:59:34 +0000 Subject: [PATCH 19/43] removed concepts subdir --- docs/concepts/README.md | 80 -------------------------------- docs/concepts/effects.md | 11 ----- docs/concepts/governor.md | 12 ----- docs/concepts/proposal.md | 11 ----- docs/concepts/staking-pool.md | 11 ----- docs/concepts/treasury.md | 11 ----- docs/tech-design/staking-pool.md | 24 ++++++---- 7 files changed, 14 insertions(+), 146 deletions(-) delete mode 100644 docs/concepts/README.md delete mode 100644 docs/concepts/effects.md delete mode 100644 docs/concepts/governor.md delete mode 100644 docs/concepts/proposal.md delete mode 100644 docs/concepts/staking-pool.md delete mode 100644 docs/concepts/treasury.md diff --git a/docs/concepts/README.md b/docs/concepts/README.md deleted file mode 100644 index 5c6c0a9..0000000 --- a/docs/concepts/README.md +++ /dev/null @@ -1,80 +0,0 @@ -| Specification | Last Revision | -|:-------------:|:-------------:| -| Draft | v0.1, 2022-02-01 | - -*** - -**Specification ownership:** [Jack Hodgkinson] - -**Authors**: - -- [Jack Hodgkinson] -- [Emily Martins] - -**Current status**: - -Considering potential expansion of 'Simple questions, simple answers' section. Awaiting review from @emiflake. - -[Jack Hodgkinson]: https://github.com/jhodgdev - -[Emily Martins]: https://github.com/emiflake - -*** - -# Governance concepts - -This document seeks to introduce to the reader the concept of governance systems on Cardano and acquaint them with the core components of a generic governance system. - -## Simple questions, simple answers - -### Q: What's a 'governance'? - -A: A _governance system_ is a component of a Cardano system, that allows for its community to issue and vote on proposals. - -### Q: What can be proposed? - -A: That depends on the Cardano protocol in-question. An example for a proposal could suggest that funds be released from a community treasury. Another might propose an alteration to some parameter in the wider-system. - -### Q: Who can vote? - -A: The right to vote is conferred by the _staking_ of some designated _governance token_ (GT). If one owns the relevant token, they may 'stake' some of it to vote in favour of, or opposition to, some proposal. - -## Overview of components - -![Governance overview diagram](/docs/diagrams/gov-overview.svg "Governance overview diagram") - -More-detailed information on individual components will be included in their own, specific documentation. This section provides brief descriptions on the purpose of each component. - -### Users - -A user is a member of the DAO (decentralised autonomous organisation), who -may choose to redeem governance tokens (GT) from the treasury and stake those GT -to vote in favour of, or opposition to, proposals. - -### Governance tokens - -Governance tokens (GTs) are a currency, which confer the right to vote on proposals. - -### Treasury - -The treasury of a governance system is responsible for determining which users are entitled to what GT rewards and when. If a user is eligible for a reward, it they must claim it from the treasury. A treasury can also serve as a form of 'DAO wallet', storing and saving funds that can be later spent by the community. - -### Stakes - -Users are required to 'lock' their GT in stakes, so that the system has some idea of their eligibility to vote on proposal. - -### Staking pool - -A staking pool can be introduced, for the purpose of tracking the aggregate status of all stakes in the system. Some systems may not require a staking pool. - -### Proposal - -A proposal suggests for some specified changes to be made to a Cardano system. It is voted upon by the community and, if passed, its effects are applied to the system. - -### Effects - -Proposals may have one or many 'effects', which represent the concrete, individual changes the proposal would make to the system. If their corresponding proposals have been passed, each effect is granted a _governance authority token_ (GAT) by the governor. This token permits the effect to alter the system. - -### Governor - -The governor is responsible for validating whether proposals have passed. If they have, it issues GATs to the proposals' effects. diff --git a/docs/concepts/effects.md b/docs/concepts/effects.md deleted file mode 100644 index 83e961c..0000000 --- a/docs/concepts/effects.md +++ /dev/null @@ -1,11 +0,0 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | - -*** - -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) - -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) - -**Current Status**: diff --git a/docs/concepts/governor.md b/docs/concepts/governor.md deleted file mode 100644 index a4f307b..0000000 --- a/docs/concepts/governor.md +++ /dev/null @@ -1,12 +0,0 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | - --------------------- - -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) - -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) - -**Current Status**: - diff --git a/docs/concepts/proposal.md b/docs/concepts/proposal.md deleted file mode 100644 index 83e961c..0000000 --- a/docs/concepts/proposal.md +++ /dev/null @@ -1,11 +0,0 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | - -*** - -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) - -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) - -**Current Status**: diff --git a/docs/concepts/staking-pool.md b/docs/concepts/staking-pool.md deleted file mode 100644 index 83e961c..0000000 --- a/docs/concepts/staking-pool.md +++ /dev/null @@ -1,11 +0,0 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | - -*** - -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) - -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) - -**Current Status**: diff --git a/docs/concepts/treasury.md b/docs/concepts/treasury.md deleted file mode 100644 index 83e961c..0000000 --- a/docs/concepts/treasury.md +++ /dev/null @@ -1,11 +0,0 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | - -*** - -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) - -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) - -**Current Status**: diff --git a/docs/tech-design/staking-pool.md b/docs/tech-design/staking-pool.md index fda84f3..6ada426 100644 --- a/docs/tech-design/staking-pool.md +++ b/docs/tech-design/staking-pool.md @@ -1,20 +1,24 @@ -# StakingPool technical design +# Staking pool technical design -| Spec Status | Impl Status | Last Revision | -|-------------|-------------|---------------| -| WIP | WIP | 2022-01-18 | +| Specification Status | Implementation status | Last revision | +|:-----------:|:-----------:|:-------------:| +| WIP | WIP | 2022-02-2022 | --------------------- +*** -**Spec Ownership:** [@Emily Martins] +**Specification ownership:** [Emily Martins] -**Authors**: [@Emily Martins] +**Authors**: + - [Emily Martins] + - [Jack Hodgkinson] -**Impl Owner:** [@Emily Martins] +**Implementation ownership:** [Emily Martins] -[@Emily Martins]: https://github.com/emiflake +[Emily Martins]: https://github.com/emiflake --------------------- +[Jack Hodgkinson]: https://github.com/jhodgdev + +*** ## The StakingPool From d484803d9aeffef2c5481d521589a850de2b6b92 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 14:09:09 +0000 Subject: [PATCH 20/43] coordination of technical docs --- docs/meta/status-format.md | 4 ++-- docs/tech-design/effects.md | 18 ++++++++++++------ docs/tech-design/governor.md | 18 ++++++++++++------ docs/tech-design/treasury.md | 18 ++++++++++++------ docs/tech-design/vesting.md | 25 ++++++++++++++++--------- 5 files changed, 54 insertions(+), 29 deletions(-) diff --git a/docs/meta/status-format.md b/docs/meta/status-format.md index 2a71ee8..9daddb1 100644 --- a/docs/meta/status-format.md +++ b/docs/meta/status-format.md @@ -17,9 +17,9 @@ This format should be used at the start of any documentation that may be conside The format is as follows, with {substitutions} in curly braces. -| Specification | Implementation | Last Revision | +| Specification | Implementation | Last revision | |:-------------:|:--------------:|:-------------:| -| {status} | {status} | {version}, {date} | +| {status} | {status} | {version} {date} | -------------------- diff --git a/docs/tech-design/effects.md b/docs/tech-design/effects.md index 4ebef20..aa88ba8 100644 --- a/docs/tech-design/effects.md +++ b/docs/tech-design/effects.md @@ -1,13 +1,19 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | +# Effects technical design + +| Specification | Implementation | Last revision | +|:-----------:|:--------------:|:-------------:| +| WIP | WIP | v0.1 2022-01-26 | *** -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) +**Specification ownership:** [Jack Hodgkinson] -**Impl Ownership:** _unassigned_ +**Authors**: -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) +- [Jack Hodgkinson] + +**Implementation ownership:** _unassigned_ + +[Jack Hodgkinson]: https://github.com/jhodgdev **Current Status**: diff --git a/docs/tech-design/governor.md b/docs/tech-design/governor.md index 4ebef20..85bf7e6 100644 --- a/docs/tech-design/governor.md +++ b/docs/tech-design/governor.md @@ -1,13 +1,19 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | +# Governor technical design + +| Specification | Implementation | Last revision | +|:-----------:|:--------------:|:-------------:| +| WIP | WIP | v0.1 2022-01-26 | *** -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) +**Specification ownership:** [Jack Hodgkinson] -**Impl Ownership:** _unassigned_ +**Authors**: -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) +- [Jack Hodgkinson] + +**Implementation ownership:** _unassigned_ + +[Jack Hodgkinson]: https://github.com/jhodgdev **Current Status**: diff --git a/docs/tech-design/treasury.md b/docs/tech-design/treasury.md index 4ebef20..719ff58 100644 --- a/docs/tech-design/treasury.md +++ b/docs/tech-design/treasury.md @@ -1,13 +1,19 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | +# Treasury technical design + +| Specification | Implementation | Last revision | +|:-----------:|:--------------:|:-------------:| +| WIP | WIP | v0.1 2022-01-26 | *** -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) +**Specification ownership:** [Jack Hodgkinson] -**Impl Ownership:** _unassigned_ +**Authors**: -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) +- [Jack Hodgkinson] + +**Implementation ownership:** _unassigned_ + +[Jack Hodgkinson]: https://github.com/jhodgdev **Current Status**: diff --git a/docs/tech-design/vesting.md b/docs/tech-design/vesting.md index de8cf87..f10ad04 100644 --- a/docs/tech-design/vesting.md +++ b/docs/tech-design/vesting.md @@ -1,20 +1,27 @@ # Vesting contract technical design -| Spec Status | Impl Status | Last Revision | -|-------------|-------------|---------------| -| WIP | WIP | 2022-01-18 | +| Specification | Implementation | Last revision | +|:-----------:|:--------------:|:-------------:| +| WIP | WIP | v0.1 2022-01-26 | --------------------- +*** -**Spec Ownership:** [@Emily Martins] +**Specification ownership:** [Emily Martins] -**Authors**: [@Emily Martins] +**Authors**: -**Impl Owner:** [@Emily Martins] +- [Emily Martins] +- [Jack Hodgkinson] -[@Emily Martins]: https://github.com/emiflake +**Implementation ownership:** [Emily Martins] --------------------- +[Jack Hodgkinson]: https://github.com/jhodgdev + +[Emily Martins]: https://github.com/emiflake + +**Current Status**: + +*** ## Vesting contract From 027053a2332be4bb0a5d37f9409dc0e46f82a54a Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 15:04:48 +0000 Subject: [PATCH 21/43] Added current status to staking pool --- docs/meta/status-format.md | 4 +-- docs/tech-design/staking-pool.md | 58 ++++++++++++++++---------------- 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/meta/status-format.md b/docs/meta/status-format.md index 9daddb1..c10e71a 100644 --- a/docs/meta/status-format.md +++ b/docs/meta/status-format.md @@ -83,7 +83,7 @@ The 'Specification' and 'Implementation' status should be one of the following: The authors and contributors of the spec document. -### Specificiation ownership +### Specification ownership The person currently, or most recently tasked with writing and maintaining the spec document. @@ -98,7 +98,7 @@ The person currently or most recently tasked with the implementation of the feat | Specification | Implementation | Last Revision | |:-------------:|:--------------:|:-------------:| -| WIP | Draft | 0.1, 2022-01-31 | +| WIP | Draft | 0.1 2022-01-31 | -------------------- diff --git a/docs/tech-design/staking-pool.md b/docs/tech-design/staking-pool.md index 6ada426..8e429ad 100644 --- a/docs/tech-design/staking-pool.md +++ b/docs/tech-design/staking-pool.md @@ -2,15 +2,16 @@ | Specification Status | Implementation status | Last revision | |:-----------:|:-----------:|:-------------:| -| WIP | WIP | 2022-02-2022 | +| WIP | WIP | 2022-02-02 | *** **Specification ownership:** [Emily Martins] -**Authors**: - - [Emily Martins] - - [Jack Hodgkinson] +**Authors**: + +- [Emily Martins] +- [Jack Hodgkinson] **Implementation ownership:** [Emily Martins] @@ -18,59 +19,58 @@ [Jack Hodgkinson]: https://github.com/jhodgdev +**Current status:** Originally written for Liqwid by [Emily Martins]. Rewritten by [Jack Hodgkinson]. Will be subject to changes, when a final implementation for the staking pool has been decided. + *** -## The StakingPool +## Stake UTXOs -In order to be able to count votes at all, some means of proving a user's skin in the game on-chain must exist. We propose having a central StakingPool contract which mints separate per-user UTXOs in which the governance token can be deposited. The MintingPolicy of the state threads ensures that it is paid to the script and with valid initial state. This circumvents the need for a central token, and makes the minting of such tokens concurrently possible. - -> Peter, 2022-01-24: "(...) mints separate per-user UTxOs (...)": I think this should read something like "locks per-user continuing UTxOs carrying unique state-thread tokens in which the governance token can be deposited." What do you think? - -### Stake UTXOs - -A stake UTXO stores the information to allow accessing your staked GT as if it was a safe. +A 'stake' records how much GT has been staked by a user, and on which proposals it has been locked against. ```haskell data Stake = Stake - { -- | Which proposals has this Stake been used to vote on? + { -- | Which proposals has this stake been used to vote on? lockedByProposals :: [(DatumHash, ProposalVote)] - , -- | The amount staked by this utxo + , -- | The amount of GT in the stake. stakedAmount :: GT - , -- | Who owns this Stake + , -- | The owner of the stake. owner :: PubKeyHash } ``` -> Peter, 2022-01-24: What happens is `lockedByProposals` grows too large? I know its unlikely, but have you considered devising a way circumvent this from being a possibility? - -When voting for a proposal, the Stake UTXO is used to witness the user's staked amount. As a result, the two following state transitions take place (pseudocode): +When voting for a proposal, the stake UTXO is used to witness the user's staked amount. As a result, the two following state transitions take place: ```haskell proposal.votes += (stake.stakedAmount, vote) stake.lockedByProposals += (hash proposal.settings, vote) ``` -A sort of mutual binding between the proposal and the stake is created and undoing one undoes the other, which is exactly what we want! +This forms a mutual binding between the proposal and the stake. -Depositing and withdrawing is made illegal when `stake.lockedByProposals` isn't empty. Withdrawing is illegal so that you can't have GT in a vote, without having it anymore, whereas Depositing is illegal so that you can't deposit after a vote and unvote it again in order to retract more than you originally voted. Thus preserving that +A stake may be used to vote on an unlimited number of proposals. Consider a user staking 50GT. They may pledge that 50GT against a proposal `p` _and_ another proposal `p'`. -> Peter, 2022-01-24: "Thus preserving that..." (incomplete sentence) +Altering the amount positioned in a stake is not possible, for as long as that stake is locked against any proposals. This is to prevent two potential malpractices: -#### Delegating stake +1. A user stakes `n` GT and votes on a proposal. They then withdraw their stake and sell it on a DEX. They no own zero GT but have `n` GT staked on a proposal. +2. A user stakes `n` GT and votes on a proposal. They further deposit `k` into their stake. They revoke their vote and redeem `n + k` GT, leaving them with a `k` GT profit. -Most things like Cosigning sort of work trivially by just witnessing Stake, but delegation requires an extra step. We add a field to what `Stake` stores. +Preventing alteration of GT in stakes ensures that there is never a discrepancy between the amount of GT a user holds and the amount the system believes that they hold. + +## Delegating stake + +Aspects of delegation, such as co-signing work through the trivial witnessing of a stake UTXO, however allowing a user to delegate their stakes requires an extra field: ```haskell data Stake = Stake - { -- | Which proposals has this Stake been used to vote on? + { -- | Which proposals has this stake been used to vote on? lockedByProposals :: [(DatumHash, ProposalVote)] - , -- | The amount staked by this utxo + , -- | The amount of GT in the stake. stakedAmount :: GT - , -- | Who can spend our utxo for us when voting - delegatedTo :: Maybe ValidatorHash - , -- | Who owns this Stake + , -- | The owner of the stake. owner :: PubKeyHash + , -- | To whom this stake has been delegated. + delegatedTo :: Maybe ValidatorHash } ``` -We simply link one stake to another. When voting now the voter can check which Stake utxos are delegated to them off-chain, and include them in the transaction for voting. **This will lock the delegators' utxos**, but that's no big deal because they can themselves unlock it just like usual. The validity of the hash provided to the Stake is irrelevant. It simply delegates its _authentication_ to the particular hash. Note, it only delegates authentication for _voting_ but not for example for withdrawing. +When voting on a proposal, a user can check which stakes have delegated to them off-chain and include them in the voting transaction. _This will lock the delegator's stake_, however they will be themselves be able to unlock it as usual. It should be noted that delegation of stakes only extends to voting on proposals and not, for example, withdrawing GT from a stake. From 7ec8f731d417181e2b9a2fcc3699f5461a43f93d Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 15:28:59 +0000 Subject: [PATCH 22/43] made changes to authoirty-tokens and proposals.ms --- docs/tech-design/authority-tokens.md | 6 ++---- docs/tech-design/proposals.md | 6 ++---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/tech-design/authority-tokens.md b/docs/tech-design/authority-tokens.md index e8a55ab..5b9e194 100644 --- a/docs/tech-design/authority-tokens.md +++ b/docs/tech-design/authority-tokens.md @@ -47,7 +47,7 @@ This model naturally requires that any component of the system, desired to be ad ![Governance Authority Token UTxO flow diagram](../diagrams/GovernanceAuthorityToken.svg) -> Peter, 2022-01-24: You should add a link to what conventions you're following for you UTxO flows to the README +> Peter, 2022-01-24: You should add a link to what conventions you're following for you UTXO flows to the README > Peter 2022-01-24: I think I see what's going on here, but it could use some annotations/additional description. > Tx1, a.) A proposal is closed via Tx1, and the transaction emits a continuing `Proposal` and `Governance` UtXO, @@ -77,6 +77,4 @@ The ability to alter large swathes of the system being conferred by the ownershi This should be sufficient to prevent loopholes. Delegating authority through validation or movement of tokens is often a necessary risk in blockchain systems and this problem is no more complex than others of its kind. -> 2022-01-24, Peter: Have you considered placing the validator hash of the effect script in the token name? This could tie a proposal to a GAT to a validator, instead of having any GAT work with any effect script. - -> 2022-01-24, Peter: This section could use some additional explanation/pseudo-code of the what the GAT minting policy would look like and what additional validation logic would go into a governable component +There is scope for expanding GATs to make them more restrictive and therefore less dangerous. One proposal is to store the hash of the effect script within the GAT, thus allowing for the minting of 'bespoke GATs', which are only authorised to make changes allowed for in the effect hash. diff --git a/docs/tech-design/proposals.md b/docs/tech-design/proposals.md index 44f6f40..5287798 100644 --- a/docs/tech-design/proposals.md +++ b/docs/tech-design/proposals.md @@ -23,7 +23,7 @@ This document gives an overview of the technical design of the proposals system **Current status**: -Imported from Liqwid by [Emily Martins]. Underwent rewrite by [Jack Hodgkinson].Further amendments to the 'period table' should be considered. Outstanding remarks from Peter Dragos that require attention. +Imported from Liqwid by [Emily Martins]. Underwent rewrite by [Jack Hodgkinson].Further amendments to the 'period table' should be considered. *** @@ -67,7 +67,7 @@ Consider the following 'stages' of a proposal: #### Draft phase -During the draft phase, the proposal script has been minted. At this stage, only votes in favor of co-signing the draft are counted. For the proposal to transition to the voting phase, a threshold of GT will have to be staked backing the proposal. This threshold will be determined on a per-system basis and could itself be a 'governable' parameter. +During the draft phase, the proposal script has been created. At this stage, only votes in favor of co-signing the draft are counted. For the proposal to transition to the voting phase, a threshold of GT will have to be staked backing the proposal. This threshold will be determined on a per-system basis and could itself be a 'governable' parameter. #### Voting phase @@ -77,8 +77,6 @@ In the voting phase, users may utilise their stakes to vote in-favour or in-oppo Upon completion of the voting phase, a proposal will either have been passed or failed. A delay between the passing of a proposal and execution of its effects will be enforced, to allow users to prepare for incoming changes to the system. It'll further give the system maintainers opportunity to intervene, in the case of a hostile action. -> Peter, 2022-01-24: How is this time decided? Are you familiar with the "Emergency Shutdown Mode" of MakerDAO, which we'll be adopting in LiqwidX? This is something that would, for the most part, need to happen ASAP. What sort of modularity exists or would you like to see? - #### Execution phase Failed proposals will not be interacted with further. The only value they will contain is their state thread tokens, so nothing of worth is lost. From a4d399c1686a1c84221146e346aa050386b6d3cc Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Wed, 2 Feb 2022 15:33:56 +0000 Subject: [PATCH 23/43] removed redundant staking pool diagrams --- docs/diagrams/staking-pool.dot | 6 ---- docs/diagrams/staking-pool.svg | 57 ---------------------------------- 2 files changed, 63 deletions(-) delete mode 100644 docs/diagrams/staking-pool.dot delete mode 100644 docs/diagrams/staking-pool.svg diff --git a/docs/diagrams/staking-pool.dot b/docs/diagrams/staking-pool.dot deleted file mode 100644 index 57f6039..0000000 --- a/docs/diagrams/staking-pool.dot +++ /dev/null @@ -1,6 +0,0 @@ -digraph { - rankdir="LR" - {User} -> StakingPool [label="pays LQ to"] - StakingPool -> Stake [label="creates"] - Stake -> Proposal [label="is locked by"] -} diff --git a/docs/diagrams/staking-pool.svg b/docs/diagrams/staking-pool.svg deleted file mode 100644 index 9ddbf3b..0000000 --- a/docs/diagrams/staking-pool.svg +++ /dev/null @@ -1,57 +0,0 @@ - - - - - - - - - -User - -User - - - -StakingPool - -StakingPool - - - -User->StakingPool - - -pays LQ to - - - -Stake - -Stake - - - -StakingPool->Stake - - -creates - - - -Proposal - -Proposal - - - -Stake->Proposal - - -is locked by - - - From 345a93d963e07613ec982b29d8402eee0c244910 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Thu, 3 Feb 2022 10:56:26 +0000 Subject: [PATCH 24/43] moved governance-concepts into main project README --- README.md | 59 +++++++++++++++++++++++++++ docs/governance-concepts.md | 80 ------------------------------------- 2 files changed, 59 insertions(+), 80 deletions(-) delete mode 100644 docs/governance-concepts.md diff --git a/README.md b/README.md index 70dde1c..4770abd 100644 --- a/README.md +++ b/README.md @@ -41,3 +41,62 @@ Documentation for Agora may be found in [docs](./docs). ### Beyond - [ ] ... + + +# Governance concepts + +This section seeks to introduce to the reader the concept of governance systems on Cardano and acquaint them with the core components of a generic governance system. + +## Simple questions, simple answers + +### Q: What's a 'governance'? + +A: A _governance system_ is a component of a Cardano system, that allows for its community to issue and vote on proposals. + +### Q: What can be proposed? + +A: That depends on the Cardano protocol in-question. An example for a proposal could suggest that funds be released from a community treasury. Another might propose an alteration to some parameter in the wider-system. + +### Q: Who can vote? + +A: The right to vote is conferred by the _staking_ of some designated _governance token_ (GT). If one owns the relevant token, they may 'stake' some of it to vote in favour of, or opposition to, some proposal. + +## Overview of components + +![Governance overview diagram](/docs/diagrams/gov-overview.svg "Governance overview diagram") + +More-detailed information on individual components will be included in their own, specific documentation. This section provides brief descriptions on the purpose of each component. + +### Users + +A user is a member of the DAO (decentralised autonomous organisation), who +may choose to redeem governance tokens (GT) from the treasury and stake those GT +to vote in favour of, or opposition to, proposals. + +### Governance tokens + +Governance tokens (GTs) are a currency, which confer the right to vote on proposals. + +### Treasury + +The treasury of a governance system is responsible for determining which users are entitled to what GT rewards and when. If a user is eligible for a reward, it they must claim it from the treasury. A treasury can also serve as a form of 'DAO wallet', storing and saving funds that can be later spent by the community. + +### Stakes + +Users are required to 'lock' their GT in stakes, so that the system has some idea of their eligibility to vote on proposal. + +### Staking pool + +A staking pool can be introduced, for the purpose of tracking the aggregate status of all stakes in the system. Some systems may not require a staking pool. + +### Proposal + +A proposal suggests for some specified changes to be made to a Cardano system. It is voted upon by the community and, if passed, its effects are applied to the system. + +### Effects + +Proposals may have one or many 'effects', which represent the concrete, individual changes the proposal would make to the system. If their corresponding proposals have been passed, each effect is granted a _governance authority token_ (GAT) by the governor. This token permits the effect to alter the system. + +### Governor + +The governor is responsible for validating whether proposals have passed. If they have, it issues GATs to the proposals' effects. diff --git a/docs/governance-concepts.md b/docs/governance-concepts.md deleted file mode 100644 index 5c6c0a9..0000000 --- a/docs/governance-concepts.md +++ /dev/null @@ -1,80 +0,0 @@ -| Specification | Last Revision | -|:-------------:|:-------------:| -| Draft | v0.1, 2022-02-01 | - -*** - -**Specification ownership:** [Jack Hodgkinson] - -**Authors**: - -- [Jack Hodgkinson] -- [Emily Martins] - -**Current status**: - -Considering potential expansion of 'Simple questions, simple answers' section. Awaiting review from @emiflake. - -[Jack Hodgkinson]: https://github.com/jhodgdev - -[Emily Martins]: https://github.com/emiflake - -*** - -# Governance concepts - -This document seeks to introduce to the reader the concept of governance systems on Cardano and acquaint them with the core components of a generic governance system. - -## Simple questions, simple answers - -### Q: What's a 'governance'? - -A: A _governance system_ is a component of a Cardano system, that allows for its community to issue and vote on proposals. - -### Q: What can be proposed? - -A: That depends on the Cardano protocol in-question. An example for a proposal could suggest that funds be released from a community treasury. Another might propose an alteration to some parameter in the wider-system. - -### Q: Who can vote? - -A: The right to vote is conferred by the _staking_ of some designated _governance token_ (GT). If one owns the relevant token, they may 'stake' some of it to vote in favour of, or opposition to, some proposal. - -## Overview of components - -![Governance overview diagram](/docs/diagrams/gov-overview.svg "Governance overview diagram") - -More-detailed information on individual components will be included in their own, specific documentation. This section provides brief descriptions on the purpose of each component. - -### Users - -A user is a member of the DAO (decentralised autonomous organisation), who -may choose to redeem governance tokens (GT) from the treasury and stake those GT -to vote in favour of, or opposition to, proposals. - -### Governance tokens - -Governance tokens (GTs) are a currency, which confer the right to vote on proposals. - -### Treasury - -The treasury of a governance system is responsible for determining which users are entitled to what GT rewards and when. If a user is eligible for a reward, it they must claim it from the treasury. A treasury can also serve as a form of 'DAO wallet', storing and saving funds that can be later spent by the community. - -### Stakes - -Users are required to 'lock' their GT in stakes, so that the system has some idea of their eligibility to vote on proposal. - -### Staking pool - -A staking pool can be introduced, for the purpose of tracking the aggregate status of all stakes in the system. Some systems may not require a staking pool. - -### Proposal - -A proposal suggests for some specified changes to be made to a Cardano system. It is voted upon by the community and, if passed, its effects are applied to the system. - -### Effects - -Proposals may have one or many 'effects', which represent the concrete, individual changes the proposal would make to the system. If their corresponding proposals have been passed, each effect is granted a _governance authority token_ (GAT) by the governor. This token permits the effect to alter the system. - -### Governor - -The governor is responsible for validating whether proposals have passed. If they have, it issues GATs to the proposals' effects. From 9a16e677c010bbc0d09ebe2de2c2b4d46d3b172b Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Thu, 3 Feb 2022 11:00:06 +0000 Subject: [PATCH 25/43] Centre governance diagram on README --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4770abd..fea7c52 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,9 @@ A: The right to vote is conferred by the _staking_ of some designated _governanc ## Overview of components -![Governance overview diagram](/docs/diagrams/gov-overview.svg "Governance overview diagram") +

+ +

More-detailed information on individual components will be included in their own, specific documentation. This section provides brief descriptions on the purpose of each component. From e65b2b98b14f39f45ae979d1e00fb225017ffe21 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Thu, 3 Feb 2022 11:03:34 +0000 Subject: [PATCH 26/43] Update staking-pool.md --- docs/tech-design/staking-pool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tech-design/staking-pool.md b/docs/tech-design/staking-pool.md index 8e429ad..048d767 100644 --- a/docs/tech-design/staking-pool.md +++ b/docs/tech-design/staking-pool.md @@ -1,6 +1,6 @@ # Staking pool technical design -| Specification Status | Implementation status | Last revision | +| Specification | Implementation | Last revision | |:-----------:|:-----------:|:-------------:| | WIP | WIP | 2022-02-02 | From 4537ecc4da035515db83377f3d3a061a77d45cb3 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Thu, 3 Feb 2022 12:31:59 +0000 Subject: [PATCH 27/43] written first draft of effect technical design --- docs/tech-design/effects.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/tech-design/effects.md b/docs/tech-design/effects.md index aa88ba8..75174ee 100644 --- a/docs/tech-design/effects.md +++ b/docs/tech-design/effects.md @@ -2,9 +2,9 @@ | Specification | Implementation | Last revision | |:-----------:|:--------------:|:-------------:| -| WIP | WIP | v0.1 2022-01-26 | +| WIP | WIP | v0.1 2022-02-03 | -*** +--- **Specification ownership:** [Jack Hodgkinson] @@ -17,3 +17,35 @@ [Jack Hodgkinson]: https://github.com/jhodgdev **Current Status**: + +First draft of effect article. Subject to review from @emiflake. + +--- + +[Proposals](proposals.md) in a governance system are necessarily going to perform some actions or alter some parameters (otherwise, what's the point?). Due to script size limitations on Cardano, it is difficult to encapsulate all of a proposal's effects alongside other necessary information, such as vote counts. Rather than be constrained by such limitations, Agora _decouples_ proposals from their effects. + +Effects will exist as their own scripts on the blockchain and proposals will simply include a list of an effect's hashes. This way, users are still able to identify the changes a given proposal would make to the system and thereby assess the proposal's desirability. + +A proposal's effects will be initiated by the community, whom we assume will have sufficient incentive to pay the required transaction fee. However, if these effects are independent scripts, sitting there waiting to be initiated, how can we trust community members to only activate the effects of _passed_ proposals? + +We don't. Effects will be _unable_ to alter the system without burning [_governance authority tokens_ (GATs)](authority-tokens.md). These are bestowed upon an effect, via the [governor](governor.md), if their associated proposal has been passed by the community. + +All 'governable' components of a system must be able to interface with effects and allow them to make necessary changes, so long as they are in possession of a GAT. + +## What can an effect _be_? + +The range of powers an effect may have is at the discretion of the protocol maker. For usability and security purposes though, Agora will initially offer a _buffet approach_ to proposals and effects. + +

+ Get the effects, whilst they're hot! +

+ +In this model, a proposal is defined by the _combination_ of _effect templates_, in much the same way a diner's meal at a buffet is defined by which dishes they choose. + +Conceiving of proposals this way makes them no less powerful, as they will be able to combine effects in such a way as to render the desired effect. It does however prevent a user wishing to issue a proposal from having to construct their effects from whole cloth and it allows the maintainers of the system a better insight into changes to the protocol a proposal might make. + +## The issue of partial execution + +An anticipated problem with this model is the danger of 'partial execution'. The model relies on the assumption that desired effects will be processed by community members, as they are seen as desirable.There could however be an issue, if users deem some effects as more desirable than others. If the effects of a proposal are not executed __in their entirety__, this may lead to unanticipated and undesirable outcomes. + +This should not be a major limitation in the system, as community members _should_ recognise the necessity to implement the proposal in its entirety. However, one might consider _incentivising effect execution_ to prevent such an occurrence. From 4d84c73a4094f2b939f993725d02d101d7331ed5 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Thu, 3 Feb 2022 14:59:47 +0000 Subject: [PATCH 28/43] initiated effects --- docs/tech-design/governor.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/tech-design/governor.md b/docs/tech-design/governor.md index 85bf7e6..914db13 100644 --- a/docs/tech-design/governor.md +++ b/docs/tech-design/governor.md @@ -2,7 +2,7 @@ | Specification | Implementation | Last revision | |:-----------:|:--------------:|:-------------:| -| WIP | WIP | v0.1 2022-01-26 | +| WIP | WIP | v0.1 2022-02-03 | *** @@ -17,3 +17,11 @@ [Jack Hodgkinson]: https://github.com/jhodgdev **Current Status**: + +First draft. Subject to review by @emiflake. + +--- + +The governor is a simpler component than others in the system but +still provides an invaluable role. Firstly, it acts as a repository for all the governance parameters e.g. the duration of proposal phases or GT thresholds. Secondly, and perhaps most importantly, it verifies whether proposals have passed legally and, if they have, grants their [effects](effects.md) powerful [governance authority tokens](authority-tokens.md). + From cb8ee1e3d2437b6db876467e4b22728502c7f609 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 08:55:11 +0000 Subject: [PATCH 29/43] Added section on staking pool to stakes technical design --- docs/tech-design/staking-pool.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/tech-design/staking-pool.md b/docs/tech-design/staking-pool.md index 048d767..9a46978 100644 --- a/docs/tech-design/staking-pool.md +++ b/docs/tech-design/staking-pool.md @@ -1,10 +1,10 @@ -# Staking pool technical design +# Stakes and staking pool technical design | Specification | Implementation | Last revision | |:-----------:|:-----------:|:-------------:| -| WIP | WIP | 2022-02-02 | +| WIP | WIP | 2022-02-07 | -*** +--- **Specification ownership:** [Emily Martins] @@ -19,9 +19,9 @@ [Jack Hodgkinson]: https://github.com/jhodgdev -**Current status:** Originally written for Liqwid by [Emily Martins]. Rewritten by [Jack Hodgkinson]. Will be subject to changes, when a final implementation for the staking pool has been decided. +**Current status:** Originally written for Liqwid by [Emily Martins]. Rewritten by [Jack Hodgkinson]. Required review from [Emily Martins], especially wrt the section on tracking global state. -*** +--- ## Stake UTXOs @@ -56,6 +56,8 @@ Altering the amount positioned in a stake is not possible, for as long as that s Preventing alteration of GT in stakes ensures that there is never a discrepancy between the amount of GT a user holds and the amount the system believes that they hold. +If a user wished to stake _more_ GT, they could always create a new stake that they would be free to lock on proposals. For this reason, it may be useful to include a method of 'merging' stakes, when they are not being locked against any proposals, to allow users to 'streamline' their GT portfolio. + ## Delegating stake Aspects of delegation, such as co-signing work through the trivial witnessing of a stake UTXO, however allowing a user to delegate their stakes requires an extra field: @@ -74,3 +76,13 @@ data Stake = Stake ``` When voting on a proposal, a user can check which stakes have delegated to them off-chain and include them in the voting transaction. _This will lock the delegator's stake_, however they will be themselves be able to unlock it as usual. It should be noted that delegation of stakes only extends to voting on proposals and not, for example, withdrawing GT from a stake. + +## Staking pool + +There are a number of reasons that a protocol would wish to track the global state of stakes in its system. For example, a protocol may wish to implement a proposal system where a certain proportion of the globally available GT must be staked in-favour of a proposal, in order to allow it to pass. This is the equivalent of mandating a certain voter turnout be met in a national referendum. The ability to do such a thing is conferred by the creation of a _staking pool_. + +Whilst the ability to track stakes is a useful one, it is a complicated concept to implement on Cardano. A particular issue is _throughput and contention_: any purely on-chain solution is unlikely to be able to process data rapidly enough that the process of users creating stakes _and_ updating the staking pool is as seamless as desired. + +One potential solution for this is an _escrow_ system, which implements a queueing solution by which users issue their stake and the system takes responsibility for updating the staking pool accordingly, with no further action required from the staker. + +Another implementation takes the burden of calculating the global state of user stakes _off-chain_. This allows the developers much more freedom in how they approach the solution, as they are no longer restricted by the complications of programming on a blockchain. What issue this solution _does_ have is one of **trust**. Any off-chain solution utilised by the protocol developers must demonstrate its fairness and accuracy to its users. From d4b62fe6f42d05a20ef5976449194af2fa6c69aa Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 09:16:01 +0000 Subject: [PATCH 30/43] small change to staking pool document --- docs/tech-design/staking-pool.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tech-design/staking-pool.md b/docs/tech-design/staking-pool.md index 9a46978..4d5d533 100644 --- a/docs/tech-design/staking-pool.md +++ b/docs/tech-design/staking-pool.md @@ -19,7 +19,7 @@ [Jack Hodgkinson]: https://github.com/jhodgdev -**Current status:** Originally written for Liqwid by [Emily Martins]. Rewritten by [Jack Hodgkinson]. Required review from [Emily Martins], especially wrt the section on tracking global state. +**Current status:** Originally written for Liqwid by [Emily Martins]. Rewritten by [Jack Hodgkinson]. Required review from [Emily Martins], especially the section on staking pools. --- From 8d30f12f3cf5bbec12c0227e0806f2fc64f9bfa6 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 09:47:21 +0000 Subject: [PATCH 31/43] Replaced vesting contract docs with new treasury docs --- docs/tech-design/treasury.md | 33 +++++++++++++++++++++++++-- docs/tech-design/vesting.md | 44 ------------------------------------ 2 files changed, 31 insertions(+), 46 deletions(-) delete mode 100644 docs/tech-design/vesting.md diff --git a/docs/tech-design/treasury.md b/docs/tech-design/treasury.md index 719ff58..abd977a 100644 --- a/docs/tech-design/treasury.md +++ b/docs/tech-design/treasury.md @@ -2,9 +2,9 @@ | Specification | Implementation | Last revision | |:-----------:|:--------------:|:-------------:| -| WIP | WIP | v0.1 2022-01-26 | +| WIP | WIP | v0.1 2022-02-07 | -*** +--- **Specification ownership:** [Jack Hodgkinson] @@ -16,4 +16,33 @@ [Jack Hodgkinson]: https://github.com/jhodgdev +[Emily Martins]: https://github.com/emiflake + **Current Status**: + +Initial conceptual draft. Requires review from [Emily Martins]. + +--- + +Treasuries in Cardano governance systems serve two functions: + +1. To serve as a community reserve or wallet. +2. To allow users to redeem their allocated share of rewards. + +## Community reserve + +A decentralised autonomous organisation (DAO) may wish to source funds from its members to save for use at a later date. A treasury therefore serves as a form of 'community wallet', where members can contribute funds, knowing that they may only be released at the behest of the community. + +Treasuries are not, by default, limited to the reserve of a single token and are indeed able to hold any supported Cardano tokens. + +A treasury, as a community's reserves, will naturally need to interact with governance proposals. Indeed, the primary mechanism by which funds are able to be released by the treasury, will be the passing of an appropriate proposal. + +## Reward holder + +The treasury will further be the initial holder of all a governance system's GT. It is likely that any governance system will desire a method to distribute these GT through the community _over time_. The amount of GT a DAO member is eligible for at a given time can be termed that user's 'reward'. The specifics of any 'reward structure', namely: + +1. Who is eligible for rewards? +2. When may they receive those rewards? +3. How much do they receive in their reward? + +are all, naturally, protocol-specific. A simple method for creating such a bespoke reward structure is **not** considered in-scope for Agora v1. Agora v1 will offer a simple, prescribed reward structure, that allows the treasury to determine the reward eligibility of a user and allow them to redeem said amount. diff --git a/docs/tech-design/vesting.md b/docs/tech-design/vesting.md deleted file mode 100644 index f10ad04..0000000 --- a/docs/tech-design/vesting.md +++ /dev/null @@ -1,44 +0,0 @@ -# Vesting contract technical design - -| Specification | Implementation | Last revision | -|:-----------:|:--------------:|:-------------:| -| WIP | WIP | v0.1 2022-01-26 | - -*** - -**Specification ownership:** [Emily Martins] - -**Authors**: - -- [Emily Martins] -- [Jack Hodgkinson] - -**Implementation ownership:** [Emily Martins] - -[Jack Hodgkinson]: https://github.com/jhodgdev - -[Emily Martins]: https://github.com/emiflake - -**Current Status**: - -*** - -## Vesting contract - -In order to distribute governance tokens, one or more vesting contracts may be deployed. - -First and foremost, there is a _schedule_ for the distribution of said tokens. Alongside this schedule, we keep track of how much we've distributed so far. This allows us to calculate how much is "due" at any particular time. - -To gain intuition, you can think of it being implemented this way: - -```haskell -distributed :: Schedule -> Time -> Value -distributed schedule time = scanl (+) mempty schedule !! time - -due :: Schedule -> Value -> Time -> Value -due schedule alreadyDistributed time = distributed schedule time - alreadyDistributed -``` - -The vesting contract may require that only an address in a particular set can withdraw from it. - -The vesting contract may have an optional escape hatch for trusted authority to recover from a potential DAO operation. From f00dc7b91d703081c7c3f9c6ad36c75c07d2240f Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 10:26:43 +0000 Subject: [PATCH 32/43] general neatening --- README.md | 2 +- docs/README.md | 31 ++++++++++--------------------- docs/meta/style-guide.md | 11 ++++++++++- 3 files changed, 21 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index fea7c52..5209f3c 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Non-goals: ## Project setup -An up to date version of the [`nix` package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [nixos website](https://nixos.org/download.html). Important: See also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. +An up to date version of the [`nix` package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [NixOS website](https://nixos.org/download.html). Important: See also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. Open a dev-shell with `nix develop` and build with `cabal build`. diff --git a/docs/README.md b/docs/README.md index 2140611..6829bb8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,32 +1,21 @@ -| Spec Status | Impl Status | Last Revision | -|-------------|----------------|---------------| -| WIP | WIP | v0.1 22/01/26 | - --------------------- - -**Spec Ownership:** [Jack Hodgkinson](github.com/jhodgdev) - -**Authors**: [Jack Hodgkinson](github.com/jhodgdev) - -**Current Status**: - --------------------- # Agora specification and documentation -This folder contains all of the specification and architecture documentation of Agora. +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 architecture involved in building Agora's governance system. +The `tech-design/` subdirectory contains high level descriptions of the architecture of Agora's governance solution. -## Implementation +## Plutarch -Agora makes extensive use of Plutarch. So it's prerequisite for understanding the implementation. Plutarch features an [_extensive_ guide](https://github.com/Plutonomicon/plutarch/blob/master/docs/GUIDE.md), which explains many intricacies of Plutarch and its use. +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: +The following is a list of terms that are used frequently throughout the documentation: -- **Governance Token (GT)**: The token that holds value within the protocol and is used for voting, rewards, etc. _Examples: Liqwid's LQ_. -- **Authority Token (GAT)**: A token that delegates authority of a particular script / token. See [tech-design/authority-token.md](./tech-design/authority-tokens.md) -- **Effect**: The result of a proposal, enforced by an effect script. +- **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 grant's the effects of a proposal the authority to alter the system. More information can be read [here](./tech-design/authority-tokens.md). +- **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/meta/style-guide.md b/docs/meta/style-guide.md index c9e7265..3a129c5 100644 --- a/docs/meta/style-guide.md +++ b/docs/meta/style-guide.md @@ -9,9 +9,18 @@ The following words should always be render capitalised: - 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: @@ -29,4 +38,4 @@ The following words should always be rendered lower-case (unless used at the beg The following practices should be avoided: -- The use of '&' apart from in proper nouns such as AT&T or commonly-understood abbreviations such as 'R&D'. +- The use of '&' apart from in proper nouns such as AT\&T. From 0e575ad6482060cf1c6c5cda8f9e47fa9aa99eef Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 10:27:54 +0000 Subject: [PATCH 33/43] capitalised Nix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5209f3c..5491fe9 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Non-goals: ## Project setup -An up to date version of the [`nix` package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [NixOS website](https://nixos.org/download.html). Important: See also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. +An up to date version of the [Nix package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [NixOS website](https://nixos.org/download.html). Important: see also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. Open a dev-shell with `nix develop` and build with `cabal build`. From ce8c0a8e7a38a9a472ef1bf7d2be55742ffcdebe Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 13:36:16 +0000 Subject: [PATCH 34/43] removed unnecessary newline from governor --- docs/tech-design/governor.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/tech-design/governor.md b/docs/tech-design/governor.md index 914db13..d5675d8 100644 --- a/docs/tech-design/governor.md +++ b/docs/tech-design/governor.md @@ -4,7 +4,7 @@ |:-----------:|:--------------:|:-------------:| | WIP | WIP | v0.1 2022-02-03 | -*** +--- **Specification ownership:** [Jack Hodgkinson] @@ -20,8 +20,6 @@ First draft. Subject to review by @emiflake. ---- - -The governor is a simpler component than others in the system but -still provides an invaluable role. Firstly, it acts as a repository for all the governance parameters e.g. the duration of proposal phases or GT thresholds. Secondly, and perhaps most importantly, it verifies whether proposals have passed legally and, if they have, grants their [effects](effects.md) powerful [governance authority tokens](authority-tokens.md). +--- +The governor is a simpler component than others in the system but still provides an invaluable role. Firstly, it acts as a repository for all the governance parameters e.g. the duration of proposal phases or GT thresholds. Secondly, and perhaps most importantly, it verifies whether proposals have passed legally and, if they have, grants their [effects](effects.md) powerful [governance authority tokens](authority-tokens.md). From c6c87b4b11ca84b5b783aac9618edae80bde339b Mon Sep 17 00:00:00 2001 From: Emily Martins Date: Mon, 7 Feb 2022 15:34:45 +0100 Subject: [PATCH 35/43] add plutus-extra dependency --- agora.cabal | 1 + flake.lock | 66 +++++++++++++++++++++++-------------- flake.nix | 44 +++++++++++++++++++++---- src/Agora/AuthorityToken.hs | 26 --------------- 4 files changed, 80 insertions(+), 57 deletions(-) diff --git a/agora.cabal b/agora.cabal index 0208378..bc8e01d 100644 --- a/agora.cabal +++ b/agora.cabal @@ -78,6 +78,7 @@ common deps , serialise , template-haskell , text + , plutus-extra common test-deps build-depends: diff --git a/flake.lock b/flake.lock index cb2c99d..231f12c 100644 --- a/flake.lock +++ b/flake.lock @@ -187,17 +187,17 @@ "cardano-base": { "flake": false, "locked": { - "lastModified": 1633939430, - "narHash": "sha256-zbjq43Bnhv1/LhJCFlI8gdd61dGvVlkEa6wkCvLqEFg=", + "lastModified": 1633088283, + "narHash": "sha256-JKpOlruMX5sr9eaQ3AuOppCbBjQIRKwF4ny20tdPnUg=", "owner": "input-output-hk", "repo": "cardano-base", - "rev": "4ea7e2d927c9a7f78ddc69738409a5827ab66b98", + "rev": "654f5b7c76f7cc57900b4ddc664a82fc3b925fb0", "type": "github" }, "original": { "owner": "input-output-hk", "repo": "cardano-base", - "rev": "4ea7e2d927c9a7f78ddc69738409a5827ab66b98", + "rev": "654f5b7c76f7cc57900b4ddc664a82fc3b925fb0", "type": "github" } }, @@ -220,17 +220,17 @@ "cardano-crypto": { "flake": false, "locked": { - "lastModified": 1621376239, - "narHash": "sha256-oxIOVlgm07FAEmgGRF1C2me9TXqVxQulEOcJ22zpTRs=", + "lastModified": 1604244485, + "narHash": "sha256-2Fipex/WjIRMrvx6F3hjJoAeMtFd2wGnZECT0kuIB9k=", "owner": "input-output-hk", "repo": "cardano-crypto", - "rev": "07397f0e50da97eaa0575d93bee7ac4b2b2576ec", + "rev": "f73079303f663e028288f9f4a9e08bcca39a923e", "type": "github" }, "original": { "owner": "input-output-hk", "repo": "cardano-crypto", - "rev": "07397f0e50da97eaa0575d93bee7ac4b2b2576ec", + "rev": "f73079303f663e028288f9f4a9e08bcca39a923e", "type": "github" } }, @@ -386,17 +386,17 @@ "cardano-wallet": { "flake": false, "locked": { - "lastModified": 1635781445, - "narHash": "sha256-5IZuqlE/4aGH3TEuGYQsZwOpI/Q7DYzJ4q3stuqGpWc=", + "lastModified": 1639607349, + "narHash": "sha256-JuYH5pAF7gOsliES0Beo86PinoBmmKXWShXT3NqVlgQ=", "owner": "j-mueller", "repo": "cardano-wallet", - "rev": "6be73ab852c0592713dfe78218856d4a8a0ee69e", + "rev": "760140e238a5fbca61d1b286d7a80ece058dc729", "type": "github" }, "original": { "owner": "j-mueller", "repo": "cardano-wallet", - "rev": "6be73ab852c0592713dfe78218856d4a8a0ee69e", + "rev": "760140e238a5fbca61d1b286d7a80ece058dc729", "type": "github" } }, @@ -1353,17 +1353,17 @@ "ouroboros-network": { "flake": false, "locked": { - "lastModified": 1634917006, - "narHash": "sha256-lwTgyoZBQAaU6Sh7BouGJGUvK1tSVrWhJP63v7MpwKA=", + "lastModified": 1637082154, + "narHash": "sha256-FNYcUjoy0ZpletEXUIAMbag2Hwb9K3bDRl793NyNy1E=", "owner": "input-output-hk", "repo": "ouroboros-network", - "rev": "1f4973f36f689d6da75b5d351fb124d66ef1057d", + "rev": "d613de3d872ec8b4a5da0c98afb443f322dc4dab", "type": "github" }, "original": { "owner": "input-output-hk", "repo": "ouroboros-network", - "rev": "1f4973f36f689d6da75b5d351fb124d66ef1057d", + "rev": "d613de3d872ec8b4a5da0c98afb443f322dc4dab", "type": "github" } }, @@ -1393,17 +1393,17 @@ "th-extras": "th-extras" }, "locked": { - "lastModified": 1643303963, - "narHash": "sha256-Ta3PLyLX209Dj1LWljkp9ynlA+QPJyaI2g6oQgBeueM=", + "lastModified": 1643799364, + "narHash": "sha256-ud/YkMtBKcx0yrHOboA7uTPtGCt5LCOipF0m2W6LqxU=", "owner": "Plutonomicon", "repo": "plutarch", - "rev": "d753dc34dfc30b144e94d6493c837ebd0c99b588", + "rev": "1fd4db27152625184e559cfb465d225a0995a56b", "type": "github" }, "original": { "owner": "Plutonomicon", "repo": "plutarch", - "rev": "d753dc34dfc30b144e94d6493c837ebd0c99b588", + "rev": "1fd4db27152625184e559cfb465d225a0995a56b", "type": "github" } }, @@ -1438,17 +1438,34 @@ "plutus-apps": { "flake": false, "locked": { - "lastModified": 1636122782, - "narHash": "sha256-+T9TGzHEzyfixBysxLwy5VWVrL5xqKF5pcbRlHQr+wI=", + "lastModified": 1642502716, + "narHash": "sha256-UULYQppoNjj+EOcV75UT3DOwJF+d609FOYsZZFeAQcM=", "owner": "input-output-hk", "repo": "plutus-apps", - "rev": "404af7ac3e27ebcb218c05f79d9a70ca966407c9", + "rev": "34fe6eeff441166fee0cd0ceba68c1439f0e93d2", "type": "github" }, "original": { "owner": "input-output-hk", "repo": "plutus-apps", - "rev": "404af7ac3e27ebcb218c05f79d9a70ca966407c9", + "rev": "34fe6eeff441166fee0cd0ceba68c1439f0e93d2", + "type": "github" + } + }, + "plutus-extra": { + "flake": false, + "locked": { + "lastModified": 1643739251, + "narHash": "sha256-L7WSXvGWxfuqSP4ZNdbuT2AdW89mAJsE6+3mxO+1dx8=", + "owner": "Liqwid-Labs", + "repo": "plutus-extra", + "rev": "bfeb0d2bb1bc18f147e58c200db2022f5c75eb60", + "type": "github" + }, + "original": { + "owner": "Liqwid-Labs", + "repo": "plutus-extra", + "rev": "bfeb0d2bb1bc18f147e58c200db2022f5c75eb60", "type": "github" } }, @@ -1585,6 +1602,7 @@ "plutarch": "plutarch", "plutus": "plutus_2", "plutus-apps": "plutus-apps", + "plutus-extra": "plutus-extra", "purescript-bridge": "purescript-bridge", "servant-purescript": "servant-purescript" } diff --git a/flake.nix b/flake.nix index ae7ec49..1316ec4 100644 --- a/flake.nix +++ b/flake.nix @@ -10,18 +10,22 @@ "github:input-output-hk/plutus?rev=65bad0fd53e432974c3c203b1b1999161b6c2dce"; inputs.plutarch.url = - "github:Plutonomicon/plutarch?rev=d753dc34dfc30b144e94d6493c837ebd0c99b588"; + "github:Plutonomicon/plutarch?rev=1fd4db27152625184e559cfb465d225a0995a56b"; inputs.goblins.url = "github:input-output-hk/goblins?rev=cde90a2b27f79187ca8310b6549331e59595e7ba"; inputs.goblins.flake = false; + inputs.plutus-extra.url = + "github:Liqwid-Labs/plutus-extra?rev=bfeb0d2bb1bc18f147e58c200db2022f5c75eb60"; + inputs.plutus-extra.flake = false; # Could we set this to true? + inputs.cardano-node.url = "github:input-output-hk/cardano-node?rev=b6ca519f97a0e795611a63174687e6bb70c9f752"; inputs.cardano-node.flake = false; inputs.cardano-wallet.url = - "github:j-mueller/cardano-wallet?rev=6be73ab852c0592713dfe78218856d4a8a0ee69e"; + "github:j-mueller/cardano-wallet?rev=760140e238a5fbca61d1b286d7a80ece058dc729"; inputs.cardano-wallet.flake = false; inputs.purescript-bridge.url = @@ -33,7 +37,7 @@ inputs.servant-purescript.flake = false; inputs.plutus-apps.url = - "github:input-output-hk/plutus-apps?rev=404af7ac3e27ebcb218c05f79d9a70ca966407c9"; + "github:input-output-hk/plutus-apps?rev=34fe6eeff441166fee0cd0ceba68c1439f0e93d2"; inputs.plutus-apps.flake = false; inputs.cardano-addresses.url = @@ -45,7 +49,7 @@ inputs.optparse-applicative.flake = false; inputs.ouroboros-network.url = - "github:input-output-hk/ouroboros-network?rev=1f4973f36f689d6da75b5d351fb124d66ef1057d"; + "github:input-output-hk/ouroboros-network?rev=d613de3d872ec8b4a5da0c98afb443f322dc4dab"; inputs.ouroboros-network.flake = false; inputs.cardano-ledger-specs.url = @@ -61,11 +65,11 @@ inputs.cardano-prelude.flake = false; inputs.cardano-base.url = - "github:input-output-hk/cardano-base?rev=4ea7e2d927c9a7f78ddc69738409a5827ab66b98"; + "github:input-output-hk/cardano-base?rev=654f5b7c76f7cc57900b4ddc664a82fc3b925fb0"; inputs.cardano-base.flake = false; inputs.cardano-crypto.url = - "github:input-output-hk/cardano-crypto?rev=07397f0e50da97eaa0575d93bee7ac4b2b2576ec"; + "github:input-output-hk/cardano-crypto?rev=f73079303f663e028288f9f4a9e08bcca39a923e"; inputs.cardano-crypto.flake = false; inputs.flat.url = @@ -91,6 +95,7 @@ }; deferPluginErrors = true; + plutarch-development = true; projectFor = system: let pkgs = nixpkgsFor system; @@ -224,6 +229,7 @@ "lib/launcher" "lib/core-integration" "lib/cli" + "lib/dbvar" "lib/shelley" ]; } @@ -238,6 +244,7 @@ "plutus-chain-index-core" "plutus-contract" "plutus-ledger" + "plutus-ledger-constraints" "plutus-pab" "plutus-playground-server" "plutus-use-cases" @@ -250,6 +257,19 @@ subdirs = [ "cardano-api" "cardano-node" "cardano-cli" "cardano-config" ]; } + { + src = inputs.plutus-extra; + subdirs = [ + "tasty-plutus" + "plutus-pretty" + "plutus-numeric" + "plutus-extra" + "plutus-golden" + "plutus-laws" + "quickcheck-plutus-instances" + + ]; + } { src = inputs.plutus; subdirs = [ @@ -268,7 +288,12 @@ ]; modules = [{ packages = { + + plutarch.flags.development = plutarch-development; + marlowe.flags.defer-plugin-errors = deferPluginErrors; + plutus-use-cases.flags.defer-plugin-errors = deferPluginErrors; plutus-ledger.flags.defer-plugin-errors = deferPluginErrors; + plutus-contract.flags.defer-plugin-errors = deferPluginErrors; cardano-crypto-praos.components.library.pkgconfig = nixpkgs.lib.mkForce [ [ (import plutus { inherit system; }).pkgs.libsodium-vrf ] ]; @@ -296,7 +321,12 @@ graphviz ]; - additional = ps: [ ps.plutarch ps.plutus-ledger ]; + additional = ps: [ + ps.plutarch + ps.plutus-ledger + ps.plutus-extra + + ]; }; }; in { diff --git a/src/Agora/AuthorityToken.hs b/src/Agora/AuthorityToken.hs index 22d43f3..bbd2849 100644 --- a/src/Agora/AuthorityToken.hs +++ b/src/Agora/AuthorityToken.hs @@ -1,7 +1,6 @@ module Agora.AuthorityToken ( authorityTokenPolicy, AuthorityToken (..), - serialisedScriptSize, ) where -------------------------------------------------------------------------------- @@ -9,20 +8,6 @@ module Agora.AuthorityToken ( import Prelude -------------------------------------------------------------------------------- - -import Codec.Serialise (serialise) -import Data.ByteString qualified as BSS -import Data.ByteString.Lazy qualified as BS -import Data.ByteString.Short qualified as SBS - --------------------------------------------------------------------------------- - -import Cardano.Api.Shelley ( - PlutusScript (PlutusScriptSerialised), - PlutusScriptV1, - serialiseToCBOR, - ) -import Plutus.V1.Ledger.Scripts (Script) import Plutus.V1.Ledger.Value (AssetClass (..)) -------------------------------------------------------------------------------- @@ -86,17 +71,6 @@ passetClassValueOf = PNothing -> 0 PJust v -> pfromData v --- TODO: We should rely on plutus-extra instead of rolling our own, --- this is just quick and hacky. -serialisedScriptSize :: Script -> Int -serialisedScriptSize = - BSS.length - . serialiseToCBOR - . PlutusScriptSerialised @PlutusScriptV1 - . SBS.toShort - . BS.toStrict - . serialise - authorityTokenPolicy :: AuthorityToken -> Term s (PData :--> PData :--> PScriptContext :--> PUnit) From 17332e43f73d5ac5503cf573780be2fde19a0603 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 14:47:52 +0000 Subject: [PATCH 36/43] implemented changes from review --- README.md | 1 + docs/tech-design/effects.md | 10 ++++++---- docs/tech-design/proposals.md | 26 +++++++++++++------------- docs/tech-design/staking-pool.md | 11 ++++++----- 4 files changed, 26 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 5491fe9..16a2512 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ Documentation for Agora may be found in [docs](./docs). ### v2 - [ ] Rewards distribution +- [ ] Escrow staking pool solution ### Beyond diff --git a/docs/tech-design/effects.md b/docs/tech-design/effects.md index 75174ee..d6e2659 100644 --- a/docs/tech-design/effects.md +++ b/docs/tech-design/effects.md @@ -34,18 +34,20 @@ All 'governable' components of a system must be able to interface with effects a ## What can an effect _be_? -The range of powers an effect may have is at the discretion of the protocol maker. For usability and security purposes though, Agora will initially offer a _buffet approach_ to proposals and effects. +The range of powers an effect may have is at the discretion of the protocol maker. For usability purposes, Agora might offer a _buffet approach_ as an option for proposals and effects.

Get the effects, whilst they're hot!

-In this model, a proposal is defined by the _combination_ of _effect templates_, in much the same way a diner's meal at a buffet is defined by which dishes they choose. +In this model, a proposal is defined by the _combination_ of _effect templates_, in much the same way a diner's meal at a buffet is defined by which dishes they choose. -Conceiving of proposals this way makes them no less powerful, as they will be able to combine effects in such a way as to render the desired effect. It does however prevent a user wishing to issue a proposal from having to construct their effects from whole cloth and it allows the maintainers of the system a better insight into changes to the protocol a proposal might make. +Conceiving of proposals this way makes them only marginally less powerful, as users will be able to combine effects in such a way as to render the desired effect. It does however prevent a user wishing to issue a proposal from having to construct their effects from whole cloth. + +Whilst Agora may offer this functionality, there is nothing stopping DAO members from writing their own effect code. ## The issue of partial execution -An anticipated problem with this model is the danger of 'partial execution'. The model relies on the assumption that desired effects will be processed by community members, as they are seen as desirable.There could however be an issue, if users deem some effects as more desirable than others. If the effects of a proposal are not executed __in their entirety__, this may lead to unanticipated and undesirable outcomes. +An anticipated problem with this model is the danger of 'partial execution'. The model relies on the assumption that desired effects will be processed by community members, as they are seen as desirable.There could however be an issue, if users deem some effects as more desirable than others. If the effects of a proposal are not executed **in their entirety**, this may lead to unanticipated and undesirable outcomes. This should not be a major limitation in the system, as community members _should_ recognise the necessity to implement the proposal in its entirety. However, one might consider _incentivising effect execution_ to prevent such an occurrence. diff --git a/docs/tech-design/proposals.md b/docs/tech-design/proposals.md index 5287798..6509069 100644 --- a/docs/tech-design/proposals.md +++ b/docs/tech-design/proposals.md @@ -6,7 +6,7 @@ This document gives an overview of the technical design of the proposals system |:-----------:|:-----------:|:-------------:| | WIP | WIP | v0.1 2022-02-02 | -*** +--- **Specification ownership:** [Emily Martins] @@ -23,9 +23,9 @@ This document gives an overview of the technical design of the proposals system **Current status**: -Imported from Liqwid by [Emily Martins]. Underwent rewrite by [Jack Hodgkinson].Further amendments to the 'period table' should be considered. +Imported from Liqwid by [Emily Martins]. Underwent rewrite by [Jack Hodgkinson].Further amendments to the 'period table' should be considered. -*** +--- ## Proposals @@ -51,13 +51,13 @@ Consider the following 'stages' of a proposal: | Action | Valid POSIXTimeRange | Valid _stored_ state(s) | |-------------------------------------|------------------------------------|-------------------------| -| Witness | \[S, ∞] | \* | -| Cosign | \[S, S + D] | Draft | -| AdvanceProposal | \[S, S + D] | Draft | -| Vote | \[S + D, S + D + V] | Voting | -| Unlock | \[S + D, ∞] | \* | -| CountVotes (? see spec comment) | \[S + D + V, S + D + V + L] | Voting | -| ExecuteProposal (if quorum reached) | \[S + D + V + L, S + D + V + L + E] | Voting | +| Witness | \[S, ∞) | \* | +| Cosign | \[S, S + D) | Draft | +| AdvanceProposal | \[S, S + D) | Draft | +| Vote | \[S + D, S + D + V) | Voting | +| Unlock | \[S + D, ∞) | \* | +| CountVotes (? see spec comment) | \[S + D + V, S + D + V + L) | Voting | +| ExecuteProposal (if quorum reached) | \[S + D + V + L, S + D + V + L + E) | Voting | ```diff - CountVotes takes a snapshot after voting has ended, it allows users to unlock their stake without affecting votes, after the lock period has ended. This is an optional feature of locking, do we want this? @@ -67,11 +67,11 @@ Consider the following 'stages' of a proposal: #### Draft phase -During the draft phase, the proposal script has been created. At this stage, only votes in favor of co-signing the draft are counted. For the proposal to transition to the voting phase, a threshold of GT will have to be staked backing the proposal. This threshold will be determined on a per-system basis and could itself be a 'governable' parameter. +During the draft phase, a new UTXO at the proposal script has been created. At this stage, only votes in favor of co-signing the draft are counted. For the proposal to transition to the voting phase, a threshold of GT will have to be staked backing the proposal. This threshold will be determined on a per-system basis and could itself be a 'governable' parameter. #### Voting phase -In the voting phase, users may utilise their stakes to vote in-favour or in-opposition to a proposal. This adds their public key to the proposal. There is potential for contention within the system and therefore may have to be rate-limited. The method by which a user's stakes are weighted and the thresholds required for proposals to pass are determined on a per-protocol basis. +In the voting phase, users may utilise their stakes to vote in-favour or in-opposition to a proposal. This will add their vote to the relevant count. There is potential for contention within the system and therefore voting on proposals may have to be rate-limited. The method by which a user's stakes are weighted and the thresholds required for proposals to pass are determined on a per-protocol basis. #### Lock phase @@ -79,7 +79,7 @@ Upon completion of the voting phase, a proposal will either have been passed or #### Execution phase -Failed proposals will not be interacted with further. The only value they will contain is their state thread tokens, so nothing of worth is lost. +Failed proposals will not be interacted with further. The only value they will contain is their state thread tokens and the minimum ADA requirement, so little of worth is lost. Successful proposals will be verified by the governor component, which will issue ['governance authority tokens'](/docs/tech-design/authority-tokens.md) (GATs) to a proposal's separate 'effects'. The burning of these tokens will be a pre-requisite for system changes to be made, therefore the possession of one will serve as a form of 'licence' for making the changes. diff --git a/docs/tech-design/staking-pool.md b/docs/tech-design/staking-pool.md index 4d5d533..2262bbb 100644 --- a/docs/tech-design/staking-pool.md +++ b/docs/tech-design/staking-pool.md @@ -49,12 +49,13 @@ This forms a mutual binding between the proposal and the stake. A stake may be used to vote on an unlimited number of proposals. Consider a user staking 50GT. They may pledge that 50GT against a proposal `p` _and_ another proposal `p'`. -Altering the amount positioned in a stake is not possible, for as long as that stake is locked against any proposals. This is to prevent two potential malpractices: +Altering the amount positioned in a stake is not possible, for as long as that stake is locked against any proposals. This is to prevent vote manipulation. Consider: -1. A user stakes `n` GT and votes on a proposal. They then withdraw their stake and sell it on a DEX. They no own zero GT but have `n` GT staked on a proposal. -2. A user stakes `n` GT and votes on a proposal. They further deposit `k` into their stake. They revoke their vote and redeem `n + k` GT, leaving them with a `k` GT profit. +- Ford stakes 100GT and votes in-favour of a proposal `p`. `p` now has +100GT in-favour. +- Ford _increases_ his stake by 50GT to 150GT. +- Ford retracts his vote from `p`. As his stake is 150GT, `p` deducts 150GT and `p` now has -50GT in-favour. -Preventing alteration of GT in stakes ensures that there is never a discrepancy between the amount of GT a user holds and the amount the system believes that they hold. +It should be clear how users could alter their stakes to reduce and manipulate the vote count. Preventing alteration of GT in stakes ensures that there is never a discrepancy between the amount of GT a user holds and the amount the system believes that they hold. If a user wished to stake _more_ GT, they could always create a new stake that they would be free to lock on proposals. For this reason, it may be useful to include a method of 'merging' stakes, when they are not being locked against any proposals, to allow users to 'streamline' their GT portfolio. @@ -83,6 +84,6 @@ There are a number of reasons that a protocol would wish to track the global sta Whilst the ability to track stakes is a useful one, it is a complicated concept to implement on Cardano. A particular issue is _throughput and contention_: any purely on-chain solution is unlikely to be able to process data rapidly enough that the process of users creating stakes _and_ updating the staking pool is as seamless as desired. -One potential solution for this is an _escrow_ system, which implements a queueing solution by which users issue their stake and the system takes responsibility for updating the staking pool accordingly, with no further action required from the staker. +One potential solution for this is an _escrow_ system, which implements a queueing solution by which users issue their stake and the system takes responsibility for updating the staking pool accordingly, with no further action required from the staker. This is a feature that is being considered for Agora v2. Another implementation takes the burden of calculating the global state of user stakes _off-chain_. This allows the developers much more freedom in how they approach the solution, as they are no longer restricted by the complications of programming on a blockchain. What issue this solution _does_ have is one of **trust**. Any off-chain solution utilised by the protocol developers must demonstrate its fairness and accuracy to its users. From 0e44aea051e1d21713d92a222f2c73fbd28908d7 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Mon, 7 Feb 2022 16:07:22 +0000 Subject: [PATCH 37/43] Small changes to style guide --- docs/meta/style-guide.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/meta/style-guide.md b/docs/meta/style-guide.md index 3a129c5..664549c 100644 --- a/docs/meta/style-guide.md +++ b/docs/meta/style-guide.md @@ -2,9 +2,13 @@ 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 be render capitalised: +The following words should always in the forms below: - Agora - Liqwid @@ -34,6 +38,13 @@ The following words should always be rendered lower-case (unless used at the beg - 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: From 4113c7ff8647609c451508291ea62501c7efa2e3 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Tue, 8 Feb 2022 08:57:20 +0000 Subject: [PATCH 38/43] Updated .gitignore to reflect nix-direnv support --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index b6ea349..9699888 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ tags # direnv files .envrc +.direnv/ From 1cca3251101d7cf53c1ac3a5f178e860007abdd0 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Tue, 8 Feb 2022 09:26:10 +0000 Subject: [PATCH 39/43] Removed nix.shell, as no longer required --- shell.nix | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 shell.nix diff --git a/shell.nix b/shell.nix deleted file mode 100644 index 3dc01ba..0000000 --- a/shell.nix +++ /dev/null @@ -1,6 +0,0 @@ -# This file is no longer useful for normal nix-shell, as it has -# been superseded by flake.nix However, this is still useful for -# lorri to use automatically. -{ system ? builtins.currentSystem }: - -(builtins.getFlake (toString ./.)).devShell.${system} From 9350dcfd7f156ff1906bedcc83cb8de7f436cee3 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Tue, 8 Feb 2022 09:43:32 +0000 Subject: [PATCH 40/43] updated gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index b6ea349..9699888 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ tags # direnv files .envrc +.direnv/ From 38fb5470a299162d9f3e1b81f9411bf6e12949a7 Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Tue, 8 Feb 2022 09:52:22 +0000 Subject: [PATCH 41/43] fixed grammatical error --- docs/tech-design/authority-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tech-design/authority-tokens.md b/docs/tech-design/authority-tokens.md index 5b9e194..5420775 100644 --- a/docs/tech-design/authority-tokens.md +++ b/docs/tech-design/authority-tokens.md @@ -66,7 +66,7 @@ This approach has a number of benefits but some important details must be kept i Cardano script sizes are restricted to 16KB and previous proposal/effect models have had difficulties generating scripts which keep under this limit. By decoupling proposals and their effects, a proposal can have a far greater number of effects, as all it contains is a list of hashes for said effects. Effects themselves can make any number of changes to the system, as long as the resulting script is kept to an allowable size. -It is essentially impossible for the system to prevent from conflicting effects taking place in short order and harming the system but the likelihood of this occurring is sufficiently reduced by all effects first having be passed by the DAO. There is scope for adding a notion of 'expiration', after which effects will no longer be able to enact their changes. +It is essentially impossible for the system to prevent conflicting effects taking place in short order and harming the system but the likelihood of this occurring is sufficiently reduced by all effects first having be passed by the DAO. There is scope for adding a notion of 'expiration', after which effects will no longer be able to enact their changes. #### Writing effect code requires a _lot_ of care From 6738707b56447b88a285dc1bf7e2ba2bd269e7ef Mon Sep 17 00:00:00 2001 From: Jack Hodgkinson <30505104+jhodgdev@users.noreply.github.com> Date: Tue, 8 Feb 2022 10:02:16 +0000 Subject: [PATCH 42/43] Update README.md Added reference to `nix-direnv`. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 16a2512..35870f8 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Non-goals: An up to date version of the [Nix package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [NixOS website](https://nixos.org/download.html). Important: see also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches. -Open a dev-shell with `nix develop` and build with `cabal build`. +Open a development shell with `nix develop` and build the project with `cabal build`. Those pained by the need to remember to enter a Nix shell may consider using [nix-direnv](https://github.com/nix-community/nix-direnv). ## Documentation From db15a05521614350330b80e6a2927202a8f3a1fc Mon Sep 17 00:00:00 2001 From: Emily Martins Date: Wed, 9 Feb 2022 12:46:20 +0100 Subject: [PATCH 43/43] simply add `haskell-language-server` to tools --- flake.lock | 6 +++--- flake.nix | 7 ++----- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/flake.lock b/flake.lock index 231f12c..f8466b2 100644 --- a/flake.lock +++ b/flake.lock @@ -1139,11 +1139,11 @@ }, "nixpkgs-2009": { "locked": { - "lastModified": 1624271064, - "narHash": "sha256-qns/uRW7MR2EfVf6VEeLgCsCp7pIOjDeR44JzTF09MA=", + "lastModified": 1635350005, + "narHash": "sha256-tAMJnUwfaDEB2aa31jGcu7R7bzGELM9noc91L2PbVjg=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "46d1c3f28ca991601a53e9a14fdd53fcd3dd8416", + "rev": "1c1f5649bb9c1b0d98637c8c365228f57126f361", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index 1316ec4..6b9f7a5 100644 --- a/flake.nix +++ b/flake.nix @@ -321,12 +321,9 @@ graphviz ]; - additional = ps: [ - ps.plutarch - ps.plutus-ledger - ps.plutus-extra + additional = ps: [ ps.plutarch ps.plutus-ledger ps.plutus-extra ]; - ]; + tools.haskell-language-server = { }; }; }; in {