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

apply suggestions

Browse source
This commit is contained in:
Emily Martins 2022-04-11 19:48:12 +02:00
parent f29cfe0716
commit d30feaf198
3 changed files with 9 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/tech-design/effects.md
View file

@ -32,7 +32,7 @@ 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.
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 on their datum. This allows for effects to be given names, be audited, and to be tracked. The datums are more easily inspected because of human-readable representations of their underlying encoding in [CBOR](https://en.wikipedia.org/wiki/CBOR) (See [`plutus_data` in alonzo.cddl](https://github.com/input-output-hk/cardano-ledger/blob/master/eras/alonzo/test-suite/cddl-files/alonzo.cddl#L274-L279))
## What can an effect _be_?
@ -56,6 +56,6 @@ This should not be a major limitation in the system, as community members _shoul
## 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.
The primary safety consideration for handling GATs with proposal effects should be that an effect's transaction should only be valid when it burns 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).

6
docs/tech-design/governor.md
View file

@ -21,7 +21,7 @@
**Current Status**:
First draft. Subject to review by @emiflake.
First draft.
---
@ -39,6 +39,6 @@ The main responsibility for the governor is allowing the minting of [authority t
The governor is also responsible for allowing the _creation_ of proposals. There are a few rules for the creation of a proposal, and the governor ensures these rules are followed.
In order for proposals to have sequential IDs, the governor keeps track of a counter which it uses to ensure the ID has not been taken yet. The governor also needs to keep global settings that influence how proposals behave: thresholds for state transitions, how long each phase lasts, etc.
In order for proposals to have sequential IDs, the governor keeps track of a counter which it uses to ensure an ID has not been taken yet. The governor also needs to keep global settings that influence how proposals behave: thresholds for state transitions, how long each phase lasts, etc.
The governor itself is sensitive to authority token burning in order to allow all of this to be able to mutate.
The governor, in-line with other Agora components, allows its state to be mutated, subject to the burning of an authority token.

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

@ -63,7 +63,7 @@ Consider the following 'stages' of a proposal:
#### 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. 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.
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 into a single transaction to witness their size.
#### Voting phase
@ -83,7 +83,7 @@ There will be a deadline before which a proposal's effects will have to be execu
#### Encoding of results
Most proposals are simply looking for approval for a particular transaction to take place. We encode the potential outcomes of the proposal in the following way (calling it "effects"):
Most proposals are simply looking for approval for a particular transaction to take place. We encode the potential outcomes of the proposal in the following way (calling them "effects"):
```haskell
type Effect =
@ -120,6 +120,6 @@ Encoding multiple different outcomes is possible by adding more pairs to the map
#### Proposal metadata
Proposals carry very little metadata in their datums. They carry only the id, which identifies them in a convenient incremental number; and their original cosigners. The rest is all very functional information required for their functioning. It may however be useful to carry some extra metadata on-chain in order for frontends to be able to identify and display relevant information to the users.
Proposals carry very little metadata in their datums. They carry only their id -- which identifies them in a convenient incremental number -- and their original cosigners. The rest is data required for their functioning. It may however be useful to carry some extra metadata on-chain in order for the front-end to be able to identify and display relevant information to the users.
In order to achieve this, we can, upon the creation of a proposal, pass along the relevant information in the metadata field. Establishing a standard for how this should be laid out is yet to be done, but it could look as simple as a number of fields indicating the title, description, tags, etc. Since this metadata is only present in the creation of the proposal, it won't weigh the future transactions belonging to the proposal. The information can still be looked up by looking at the mint transaction of that particulara proposal state thread.
In order to achieve this, we can, upon the creation of a proposal, pass along the relevant information in the metadata field. Establishing a standard for how this should be laid out is yet to be done, but it could look as simple as a number of fields indicating the title, description, tags, etc. Since this metadata is only present in the creation of the proposal, it won't add to the transaction size for future transactions belonging to the proposal. The information can still be looked up by looking at the mint transaction of that particular proposal state thread.