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

initial review

Browse source
This commit is contained in:
Jack Hodgkinson 2022-04-08 09:07:56 +01:00
parent ba48fe33fd
commit 9a8a87b4fb
3 changed files with 100 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/diagrams/UsingAgora.dot Normal file
View file

@ -0,0 +1,6 @@
digraph {
rankdir=LR
Users -> Proposals [label="vote on"]
Proposals -> Effects [label="have one or many"]
Effects -> Components [label="alter"]
}

57
docs/diagrams/UsingAgora.svg Normal file
View file

@ -0,0 +1,57 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.49.3 (0)
-->
<!-- Pages: 1 -->
<svg width="742pt" height="44pt"
viewBox="0.00 0.00 742.06 44.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 40)">
<polygon fill="white" stroke="transparent" points="-4,4 -4,-40 738.06,-40 738.06,4 -4,4"/>
<!-- Users -->
<g id="node1" class="node">
<title>Users</title>
<ellipse fill="none" stroke="black" cx="38.35" cy="-18" rx="38.19" ry="18"/>
<text text-anchor="middle" x="38.35" y="-14.3" font-family="Times,serif" font-size="14.00">Users</text>
</g>
<!-- Proposals -->
<g id="node2" class="node">
<title>Proposals</title>
<ellipse fill="none" stroke="black" cx="221.59" cy="-18" rx="55.79" ry="18"/>
<text text-anchor="middle" x="221.59" y="-14.3" font-family="Times,serif" font-size="14.00">Proposals</text>
</g>
<!-- Users&#45;&gt;Proposals -->
<g id="edge1" class="edge">
<title>Users&#45;&gt;Proposals</title>
<path fill="none" stroke="black" d="M76.9,-18C99.51,-18 128.92,-18 155.24,-18"/>
<polygon fill="black" stroke="black" points="155.54,-21.5 165.54,-18 155.54,-14.5 155.54,-21.5"/>
<text text-anchor="middle" x="121.19" y="-21.8" font-family="Times,serif" font-size="14.00">vote on</text>
</g>
<!-- Effects -->
<g id="node3" class="node">
<title>Effects</title>
<ellipse fill="none" stroke="black" cx="483.38" cy="-18" rx="42.79" ry="18"/>
<text text-anchor="middle" x="483.38" y="-14.3" font-family="Times,serif" font-size="14.00">Effects</text>
</g>
<!-- Proposals&#45;&gt;Effects -->
<g id="edge2" class="edge">
<title>Proposals&#45;&gt;Effects</title>
<path fill="none" stroke="black" d="M277.68,-18C322.64,-18 385.72,-18 429.94,-18"/>
<polygon fill="black" stroke="black" points="430.19,-21.5 440.19,-18 430.19,-14.5 430.19,-21.5"/>
<text text-anchor="middle" x="358.98" y="-21.8" font-family="Times,serif" font-size="14.00">have one or many</text>
</g>
<!-- Components -->
<g id="node4" class="node">
<title>Components</title>
<ellipse fill="none" stroke="black" cx="665.17" cy="-18" rx="68.79" ry="18"/>
<text text-anchor="middle" x="665.17" y="-14.3" font-family="Times,serif" font-size="14.00">Components</text>
</g>
<!-- Effects&#45;&gt;Components -->
<g id="edge3" class="edge">
<title>Effects&#45;&gt;Components</title>
<path fill="none" stroke="black" d="M526.53,-18C544.29,-18 565.55,-18 585.99,-18"/>
<polygon fill="black" stroke="black" points="586.25,-21.5 596.25,-18 586.25,-14.5 586.25,-21.5"/>
<text text-anchor="middle" x="561.28" y="-21.8" font-family="Times,serif" font-size="14.00">alter</text>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 2.7 KiB

53
docs/using-agora.md
View file

@ -1,37 +1,58 @@
# Using Agora
### Motivation
## Motivation
If you are building a project on Cardano that involves decentralized interaction between users you may want to create a DAO (Decentralized Autonomous Organization). A DAO will allow users to come to consensus on various matters relevant to your project. For instance managing of treasury assets, changing of protocol parameters, replacing of scripts, deprecation of the protocol in favour of a new version, emergency actions protecting the users, etc. In order to do this on-chain, users will have to be able to voice their opinion contractually, and only those with skin in the game ought to be able to interact, so they interact in favour of the protocol at large. Furthermore, a balance must be struck when it comes to the various features of governance and your particular protocol. Various flavours of governance exist, each with their own trade-offs.
If you are building a project on Cardano that involves decentralized interaction between users you may want to create a DAO (Decentralized Autonomous Organization).
Building such a system is quite a complex process and requires a lot of care; ensuring fairness (with regard to user interactions), efficiency (with regard to contention and throughput) and simplicity (with regard to script size, tx costs). Agora is a curated set of scripts, types and design patterns that are designed from the ground up to solve this problem in a way that is flexible enough to suit essentially any protocol while also ensuring a balance is struck in trade-offs by default. Hopefully this will save time.
> Consider linking an article here? Maybe the [Wikipedia one](https://www.wikiwand.com/en/Decentralized_autonomous_organization) or a better one you know of?
### Agora and your protocol
A DAO will allow users to come to a consensus on a variety of matters relevant to your project. These could include: managing of treasury assets, changing of protocol parameters, replacing of scripts, deprecation of the protocol in favour of a new version, emergency actions to protect users, and so forth. In order to do this on-chain, users will have to be able to express their opinion contractually, and only those with a vested interest ought to be able to interact with relevant proposals. This should ensure that voters have the best interests of the protocol at-heart. Governance systems can take varied forms, and not all of them will be suitable for your project.
Agora’s staking model relies on the existence of a governance token. The entire system essentially is “parameterized” by your governance token. The Agora staking pools will lock user’s governance tokens in order to allow them to vote. However, the majority of Agora components can live on their own after that fact. One could for instance technically create a DAO that works with ADA as its governance token.
Building such a system is a complex process and requires a lot of care; ensuring fairness (with regard to user interactions), efficiency (with regard to contention and throughput) and simplicity (with regard to script size and transaction costs). Agora is a curated set of scripts, types and design patterns that are designed from the ground-up to solve this problem in a way that is flexible enough to suit essentially any protocol.
In order to wire up your protocol’s DAO actions:
### A quick note on terms
- All relevant and affected parts of your protocol will need to enable authority token burns to act as full authority:
This article will include common English words that have specific meanings in Agora. To help you disambiguate, here are some definitions:
In the case of, say, a datum that stores parameters of your protocol, there ought to be a redeemer that delegates the validation of the entire transaction to a single check for the burning of the authority token. This allows flexibility of proposal outcomes, and is the core building block for Agora’s effects.
- proposal: A collection of changes to the protocol, which are voted on as a block.
- effect: An on-chain representation of a proposed change to the protocol. A 'proposal' will hold references to one or many 'effects'. If an effect's proposal is passed by the community, effects are granted special 'authority tokens' which permit them to enact their encoded changes to the relevant protocol components.
- Write effects that perform desired actions within your protocol.
![Proposals have effects, which alter components.](/docs/diagrams/UsingAgora.svg)
Writing an effect is as simple as writing any other script, but this script has only a single transaction in mind. Let’s say you’re building an NFT project, and you want to leave all mints up to the community to decide on. In this scenario you could make a `MintNFTs` effect which will mint the NFTs after a proposal passes. This is where the authority token burn “master key” comes into play: The policy of the NFTs can check for an authority token burn, proving it was “authorized” by the DAO.
## Agora and your protocol
Agora’s staking model relies on the existence of a governance token. In a sense, this governance token _parameterizes_ the entire system. Agora staking pools will lock users' governance tokens in order to permit them to vote.
> However, the majority of Agora components can live on their own after that fact.
>
> Jack: I am unsure what you mean here. Please rewrite for clarity.
One could for instance technically create a DAO that works with ADA as its governance token.
In order to set-up your protocol’s DAO actions, all affected components of your protocol will need to interpret the burning of an _authority token_ as a licence to alter _any_ aspect of that component.
To put this in slightly more concrete terms: for any datum which holds a subset of your protocol's parameters, there _should_ exist a redeemer for that datum and validation for this datum/redeemer pair should do _no more_ than verify that one of these authority tokens has been burned. Without this flexibility, the effects of Agora's proposals would be markedly less powerful.
### Writing effects
One writes a proposal effect, as one would write any Plutus script with the caveat that the effect script will only be permitted to run _once_.
Consider an example NFT project, wherein the minting of each NFT is a community action. For this scenario, one would require a template `MintNFT` effect, which mints its corresponding NFT upon the passing of the relevant proposal. The proposal being passed will issue an authority token to the effect. Each NFT's policy will verify that such an authority token was burned upon minting, which demonstrates that the minting of the NFT was indeed authorized by the DAO.
These two are the only required chores of using Agora in practice. The former is the only one that involves adapting your own scripts. Effect scripts can be written after your protocol and its governance has deployed, provided the authority tokens are respected by the components.
> Which two, sorry?
### What Agora leaves up to you
## What Agora leaves up to you
Agora’s bread and butter is the on-chain components and scripts. So, the frontend is a concern of the consumer of the library. Hopefully the documentation and design will be enough for you to figure out the best way to design your frontends. In the future, an off-chain library may exist for Agora, which would contain various functions for creating transactions.
Agora’s concern is the on-chain components and scripts. Any front-ends are the concern of the protocol's developers. In the best case, our documentation and program design will inspire you in developing a front-end solution. There is scope for Agora containing some off-chain functionality in-future. This would allow the user to create and experiment with transactions.
It’s worth noting that, while the actual functionality of the *frontends* isn’t a concern, documentation on standardization of off-chain metadata *is*. For example, off-chain metadata tagging of proposal descriptions, tags, dates, etc. These are all important features that Agora aims to standardize, in hopes of helping the interoperability between various protocols, and DAOs for DAOs.
> It’s worth noting that, while the actual functionality of the _frontends_ isn’t a concern, documentation on standardization of off-chain metadata _is_. For example, off-chain metadata tagging of proposal descriptions, tags, dates, etc. These are all important features that Agora aims to standardize, in hopes of helping the interoperability between various protocols, and DAOs for DAOs.
>
> Jack: 'documentation on standardization of off-chain metadata'?
Writing new effects that are protocol specific is up to you too. Although, if your protocol is general in nature, and you believe that an effect can be beneficial to other users of Agora, then you can contribute it. Agora ships with a number of meta-effects out of the box, and intends to add more as time goes on.
You're welcome to write any new effects you require for your protocol. If you believe any effects you write are sufficiently general and could serve as a benefit to our community, we would encourage you to up-stream them. Guidelines for doing so may be found in our [contribution guide](/CONTRIBUTING.md). Agora provides a number of effects out-of-the-box and intends to add more with time.
### What to do if something is missing
## What to do if something is missing
If you find that one of your use cases isn’t covered by Agora, or there is a hole in the spec with regards to potentially critical importance to your project. Then feel free to create an issue for it and we will open discussion on that matter. See [CONTRIBUTING.md](../CONTRIBUTING.md) before doing so.
In the event Agora does not provide for one of your use cases, feel free to raise an issue and we can begin a discussion on implementing the desired functionality. Our [contribution guide](/CONTRIBUTING.md) has guidelines for registering issues.