diff --git a/docs/README.md b/docs/README.md index 6f4d199..51650fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,4 +15,5 @@ Agora makes extensive use of plutarch. So it's prerequisite for understanding th The following is a list of words/shorthands that are frequently used: - **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-token.md) +- **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. diff --git a/docs/diagrams/ProposalStateMachine.dot b/docs/diagrams/ProposalStateMachine.dot new file mode 100644 index 0000000..bf75340 --- /dev/null +++ b/docs/diagrams/ProposalStateMachine.dot @@ -0,0 +1,64 @@ +digraph "ProposalStateMachine" { + +rankdir=LR; +node [shape=circle, width=1.5]; + +subgraph cluster_0 { + style=filled; + color=white; + + "Draft phase (duration = D)" [shape=plaintext]; + + Draft [shape=doublecircle]; +} + +subgraph cluster_1 { + style=filled; + color=white; + + "Voting phase (duration = V)" [shape=plaintext]; + + Voting; +} + +subgraph cluster_2 { + style=filled; + color=white; + + "Lock phase (duration = L)" [shape=plaintext]; + + Lock; +} + +subgraph cluster_3 { + style=filled; + color=white; + + "Execution phase (duration = E)" [shape=plaintext]; + + Execution; +} + +node [shape = circle]; + +subgraph cluster_4 { + style=filled; + color=white; + + Executed [shape=doublecircle]; +} + + +Draft -> Voting [label="enough LQ cosigned"]; + +Voting -> Lock [label="proposal passed"]; +Voting -> Failed [label="quorum not reached"]; + +Lock -> Execution [label="lock time finished"]; + +Execution -> Failed [label="execution not on time"]; +Execution -> Executed []; + +Failed [shape=doublecircle]; + +} diff --git a/docs/diagrams/ProposalStateMachine.svg b/docs/diagrams/ProposalStateMachine.svg new file mode 100644 index 0000000..d7ee346 --- /dev/null +++ b/docs/diagrams/ProposalStateMachine.svg @@ -0,0 +1,133 @@ + + + + + + +ProposalStateMachine + + +cluster_0 + + + +cluster_1 + + + +cluster_2 + + + +cluster_3 + + + +cluster_4 + + + + +Draft phase (duration = D) +Draft phase (duration = D) + + + +Draft + + +Draft + + + +Voting + +Voting + + + +Draft->Voting + + +enough LQ cosigned + + + +Voting phase (duration = V) +Voting phase (duration = V) + + + +Lock + +Lock + + + +Voting->Lock + + +proposal passed + + + +Failed + + +Failed + + + +Voting->Failed + + +quorum not reached + + + +Lock phase (duration = L) +Lock phase (duration = L) + + + +Execution + +Execution + + + +Lock->Execution + + +lock time finished + + + +Execution phase (duration = E) +Execution phase (duration = E) + + + +Executed + + +Executed + + + +Execution->Executed + + + + + +Execution->Failed + + +execution not on time + + + diff --git a/docs/tech-design/authority-tokens.md b/docs/tech-design/authority-tokens.md index f6e3d94..584d2f9 100644 --- a/docs/tech-design/authority-tokens.md +++ b/docs/tech-design/authority-tokens.md @@ -34,7 +34,7 @@ The components that need to be adjustable at a later point, will need to allow t ![](../diagrams/GovernanceAuthorityToken.svg) -As a result of this approach, there's a number of benefits, but also details we need to watch out for. +As a result of this approach, there's a number of benefits, but also details we need to watch out for: #### Handling multiple effects in a single Proposal diff --git a/docs/tech-design/proposals.md b/docs/tech-design/proposals.md new file mode 100644 index 0000000..3750bc7 --- /dev/null +++ b/docs/tech-design/proposals.md @@ -0,0 +1,81 @@ +# Proposals Technical Design + +This document gives an overview of technical design aspects of the Proposals system for introducing, voting on and executing Governance Proposals. + +| Spec Status | Impl Status | Last Revision | +|-------------|-------------|---------------| +| WIP | WIP | 2022-01-19 | + +-------------------- + +**Spec Ownership:** [@Emily Martins] + +**Authors**: [@Emily Martins] + +**Impl Owner:** [@Emily Martins] + +[@Emily Martins]: https://github.com/emiflake + +-------------------- + +## 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. + +### Proposal voting + +##### 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. + +![](../diagrams/ProposalStateMachine.svg) + +##### When is each interaction valid? + +- `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 | + +```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? +``` + +#### 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. + +#### 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. + +##### What determines a successful proposal? + +When initializing a proposal, the governance's thresholds are passed along, one of the thresholds is the `quorum`. + +#### 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 seem fit. This is also a security mechanism, should the system be at risk of hostile takeover. + +#### 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. + +In the case of a successful proposal, anyone can execute the effects, as it can only be done in a lawful way. + +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 diff --git a/docs/tech-design/vesting.md b/docs/tech-design/vesting.md new file mode 100644 index 0000000..de8cf87 --- /dev/null +++ b/docs/tech-design/vesting.md @@ -0,0 +1,37 @@ +# Vesting contract technical design + +| Spec Status | Impl Status | Last Revision | +|-------------|-------------|---------------| +| WIP | WIP | 2022-01-18 | + +-------------------- + +**Spec Ownership:** [@Emily Martins] + +**Authors**: [@Emily Martins] + +**Impl Owner:** [@Emily Martins] + +[@Emily Martins]: https://github.com/emiflake + +-------------------- + +## 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.