docs: rewrite README for public release
This commit is contained in:
Sulkta
parent
1b0c3cfc91
commit
d8dd5a0cb9
1 changed files with 99 additions and 44 deletions
143
README.md
143
README.md
|
|
@ -1,74 +1,129 @@
|
|||
# Agora :classical_building:
|
||||
# Agora 🏛️
|
||||
|
||||
Agora is a set of Plutus scripts that compose together to form a governance system.
|
||||
Agora is a set of [Plutus](https://github.com/input-output-hk/plutus) scripts,
|
||||
written in [Plutarch](https://github.com/Plutonomicon/plutarch), that compose
|
||||
together to form an on-chain governance system for the
|
||||
[Cardano](https://cardano.org) blockchain.
|
||||
|
||||
### What is Agora
|
||||
It is a reusable, modular library — not a finished application. You import the
|
||||
components you need (a governor, a treasury, stake positions, proposals, and
|
||||
effects) and wire them into your own protocol.
|
||||
|
||||
Goals:
|
||||
## What Agora is
|
||||
|
||||
- Agora aims to reduce duplication in Liqwid and LiqwidX and to serve as a one-size-fits-all governance library for projects on the Cardano blockchain.
|
||||
- Agora aims to be modular and flexible for specific needs but presents an opinionated architecture.
|
||||
**Goals**
|
||||
|
||||
Non-goals:
|
||||
- Provide a one-size-fits-all governance library for protocols on Cardano,
|
||||
reducing the duplication of governance logic across projects.
|
||||
- Be modular and flexible enough for specific needs while presenting an
|
||||
opinionated, well-tested architecture.
|
||||
|
||||
- Agora is not a DAO. It doesn't have tokenomics or even a token. It is simply a library for governance.
|
||||
- Agora doesn't aim to provide any primitive tools for Plutus that are not governance-specific. For this, see [liqwid-plutarch-extra](https://github.com/Liqwid-Labs/liqwid-plutarch-extra/).
|
||||
**Non-goals**
|
||||
|
||||
## Project setup
|
||||
- Agora is **not** a DAO. It has no tokenomics and ships no token of its own —
|
||||
it is purely a library for governance.
|
||||
- Agora does not try to provide general-purpose Plutus primitives that aren't
|
||||
governance-specific. For those, see
|
||||
[liqwid-plutarch-extra](https://github.com/Liqwid-Labs/liqwid-plutarch-extra/).
|
||||
|
||||
An up to date version of the [Nix package manager](nixos.org) (>=2.3) is required to build this project. For information on how to install, see the [NixOS website](https://nixos.org/download.html). Important: see also [this section](https://github.com/input-output-hk/plutus#nix-advice) on binary caches.
|
||||
## Components
|
||||
|
||||
Open a development shell with `nix develop` and build the project with `cabal build`. Those pained by the need to remember to enter a Nix shell may consider using [nix-direnv](https://github.com/nix-community/nix-direnv).
|
||||
The repository is a Cabal multi-package project. The most important pieces are:
|
||||
|
||||
## `agora-scripts` HTTP export server
|
||||
| Component | Kind | Description |
|
||||
| ------------------------- | ----------- | --------------------------------------------------------------------------------------- |
|
||||
| `agora` | library | The governance scripts: Governor, Treasury, Stake, Proposal, Effects, and Authority Token. |
|
||||
| `agora-scripts` | executable | An HTTP server that exports the compiled scripts on demand for off-chain use. |
|
||||
| `agora-purescript-bridge` | executable | Generates PureScript type bindings for the on-chain types. |
|
||||
| `agora-specs` | library | Property-based and golden test specifications for the scripts. |
|
||||
| `agora-test` | test-suite | Runs the specifications. |
|
||||
| `agora-bench` | benchmark | Script-size and execution-budget benchmarks. |
|
||||
|
||||
To use scripts in a frontend, you can use the `agora-scripts` executable which allows you to query them on-demand.
|
||||
## Building
|
||||
|
||||
The CTL repo [`agora-offchain`](https://github.com/mlabs-haskell/agora-offchain) already has the setup prepared for this feature.
|
||||
An up-to-date [Nix](https://nixos.org) (>= 2.3) with flakes enabled is required.
|
||||
See the [NixOS download page](https://nixos.org/download.html) for installation,
|
||||
and the [Plutus binary-cache notes](https://github.com/input-output-hk/plutus#nix-advice)
|
||||
so you don't rebuild the world.
|
||||
|
||||
In order to run the server, simply run the following command:
|
||||
```sh
|
||||
# Enter the development shell
|
||||
nix develop
|
||||
|
||||
# Build everything
|
||||
cabal build all
|
||||
```
|
||||
|
||||
If you would rather not enter the Nix shell by hand each time, consider
|
||||
[nix-direnv](https://github.com/nix-community/nix-direnv).
|
||||
|
||||
Common workflows are wrapped in the `Makefile` (all targets assume you are
|
||||
inside `nix develop`):
|
||||
|
||||
```sh
|
||||
make build # cabal build all
|
||||
make test # run the test-suite
|
||||
make bench # run benchmarks
|
||||
make scripts # export the compiled scripts
|
||||
make haddock # build API documentation
|
||||
make format # format Haskell + Nix sources
|
||||
make lint # hlint
|
||||
make ci # format-check, lint, build, bench-check, test, haddock
|
||||
```
|
||||
|
||||
## Using the script export server
|
||||
|
||||
To consume the compiled scripts from a frontend or off-chain stack, run the
|
||||
`agora-scripts` executable, which serves the scripts on demand:
|
||||
|
||||
```sh
|
||||
cabal run agora-scripts -- --enable-cors-middleware
|
||||
```
|
||||
|
||||
A Cardano Transaction Library (CTL) integration that already wires this up is
|
||||
available in [agora-offchain](https://github.com/mlabs-haskell/agora-offchain).
|
||||
|
||||
## Documentation
|
||||
|
||||
Documentation for Agora is hosted on Notion. You can find the specs [here](https://liqwid.notion.site/e85c09d2c9a542b19aac8dd3d6caa98b?v=d863219cd6a14082a661c4959cabd6e7).
|
||||
In-repository design documents live under [`docs/`](./docs), including a
|
||||
glossary, the Governance Authority Token model, and the proposal state-machine
|
||||
diagrams under [`docs/diagrams/`](./docs/diagrams).
|
||||
|
||||
Haddock is deployed on GitHub Pages [here](https://liqwid-labs.github.io/agora/).
|
||||
```
|
||||
docs/
|
||||
├── README.md overview + glossary
|
||||
├── diagrams/ architecture & state-machine diagrams
|
||||
└── meta/ documentation status format & style guide
|
||||
```
|
||||
|
||||
### Using Agora for your protocol
|
||||
## Roadmap
|
||||
|
||||
If you are a protocol wanting to use Agora, read [Using Agora](https://liqwid.notion.site/Using-Agora-74ceb4a70d024992abd9ff07087013e6).
|
||||
**v1**
|
||||
|
||||
- [x] Governor
|
||||
- [x] Treasury
|
||||
- [x] Stakes
|
||||
- [x] Proposals
|
||||
- [x] Effects
|
||||
|
||||
**v2**
|
||||
|
||||
- [ ] Rewards distribution
|
||||
- [ ] Escrow staking pool solution
|
||||
|
||||
## Contributing
|
||||
|
||||
Please read [CONTRIBUTING.md](./CONTRIBUTING.md). Additionally, please follow the [Git policy](https://liqwid.notion.site/Git-Policy-9a7979b2fd5d4604b6d042b084e7e14f) when contributing to this project.
|
||||
Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md)
|
||||
before opening an issue or a pull request.
|
||||
|
||||
## Overview of components
|
||||
## License
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/diagrams/gov-overview.svg"/>
|
||||
</p>
|
||||
Agora is licensed under the [Apache License 2.0](./LICENSE).
|
||||
|
||||
## Road-map
|
||||
## Acknowledgements
|
||||
|
||||
### v1
|
||||
|
||||
- [x] Governor
|
||||
- [x] Treasury
|
||||
- [x] Stakes
|
||||
- [x] Proposals
|
||||
- [x] Effects
|
||||
|
||||
### v2
|
||||
|
||||
- [ ] Rewards distribution
|
||||
- [ ] Escrow staking pool solution
|
||||
|
||||
### Available support channels info
|
||||
|
||||
You can find help, more information and ongoing discusion about the project here:
|
||||
|
||||
- The [Agora & Liqwid Libs Discord](https://discord.gg/yGkjxrYueB) - Most Agora discussion happens here.
|
||||
Agora was originally created by the [Liqwid Labs](https://github.com/Liqwid-Labs)
|
||||
and [MLabs](https://github.com/mlabs-haskell) teams. This repository is a
|
||||
maintained fork that builds on their work; the original authors retain
|
||||
authorship of their commits, and their contributions are gratefully
|
||||
acknowledged.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue