Sulkta-Coop/agora
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Posted updates on proposals technical design

Browse source
This commit is contained in:
Jack Hodgkinson 2022-02-02 12:12:14 +00:00
parent 1bf2fa1a33
commit 2387055b5c
2 changed files with 54 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/tech-design/authority-tokens.md
View file

@ -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.

101
docs/tech-design/proposals.md
View file

@ -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.