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