From f29cfe0716dfbb61b13c70a84caf1a29577f841a Mon Sep 17 00:00:00 2001 From: Emily Martins Date: Mon, 11 Apr 2022 13:17:23 +0200 Subject: [PATCH] some more guidelines and off-chain notes --- docs/tech-design/effects.md | 12 ++++++++++-- docs/tech-design/proposals.md | 18 +++++++----------- docs/tech-design/treasury.md | 6 +++--- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/tech-design/effects.md b/docs/tech-design/effects.md index d6e2659..3b29133 100644 --- a/docs/tech-design/effects.md +++ b/docs/tech-design/effects.md @@ -2,7 +2,7 @@ | Specification | Implementation | Last revision | |:-----------:|:--------------:|:-------------:| -| WIP | WIP | v0.1 2022-02-03 | +| WIP | WIP | v0.1 2022-04-11 | --- @@ -32,12 +32,14 @@ We don't. Effects will be _unable_ to alter the system without burning [_governa 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. +In order for effects to be identifiable through some off-chain metadata and verification of source code, it helps for effects to be reusable, their varied functionality being dependent onn their datum. This allows for effects to be given names, be audited, and to be tracked. The datums are more easily inspected because of their human-readable encoding, CBOR. + ## What can an effect _be_? 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! + 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. @@ -51,3 +53,9 @@ Whilst Agora may offer this functionality, there is nothing stopping DAO members 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. + +## Guidelines for building effects + +One of the first targets for safety regarding handling of GATs in effects is that an effect ought to only allow transactions which include the burning of exactly one GAT. This essentially prevents all of the issues of authority token leaking, multi-GAT burn issues, etc. + +Furthermore, an effect could require that no funds are sent to the effect within the spend transaction. This prevents issues with residue datums leaking into future uses of the same script (reuse of scripts is a *requirement* for correct tagging, implementation safety, etc). diff --git a/docs/tech-design/proposals.md b/docs/tech-design/proposals.md index 3978b3b..6018c7b 100644 --- a/docs/tech-design/proposals.md +++ b/docs/tech-design/proposals.md @@ -4,7 +4,7 @@ This document gives an overview of the technical design of the proposals system | Specification | Implementation | Last revision | |:-----------:|:-----------:|:-------------:| -| WIP | WIP | v0.1 2022-04-07 | +| WIP | WIP | v0.1 2022-04-11 | --- @@ -49,25 +49,21 @@ Consider the following 'stages' of a proposal: - `L`: the length of the locking period. - `E`: the length of the execution period. -| Action | Valid POSIXTimeRange | Valid _stored_ state(s) | -|-------------------------------------|------------------------------------|-------------------------| -| Witness | \[S, ∞) | \* | +| 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 | +| Unlock | \[S + D, ∞) | \* | +| CountVotes | \[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, 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. +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. It's important to note that cosignatures are not locking votes. Cosignatures are more like a delegated approval to a proposal. The sum of all cosignatures must tally to the threshold, and all cosigner stake datums must fit in a single transaction to witness their size. #### Voting phase diff --git a/docs/tech-design/treasury.md b/docs/tech-design/treasury.md index 8d3993b..8682043 100644 --- a/docs/tech-design/treasury.md +++ b/docs/tech-design/treasury.md @@ -54,7 +54,7 @@ The script for an Agora treasury is described in this section. For clarity, all ### Datum -```hs +```haskell newtype TreasuryDatum = TreasuryDatum { -- | Currency symbol of the treasury state thread. stateThread :: CurrencySymbol @@ -63,7 +63,7 @@ newtype TreasuryDatum = TreasuryDatum ### Redeemers -```hs +```haskell newtype TreasuryRedeemer = AlterTreasuryParams ``` @@ -71,7 +71,7 @@ At the current stage, it is sufficient to allow users to simply grant funds to t ### Validators -```hs +```haskell treasuryV :: CurrencySymbol -> TreasuryDatum ->