129 lines
4.6 KiB
Markdown
129 lines
4.6 KiB
Markdown
# Agora 🏛️
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## What Agora is
|
|
|
|
**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.
|
|
|
|
**Non-goals**
|
|
|
|
- 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/).
|
|
|
|
## Components
|
|
|
|
The repository is a Cabal multi-package project. The most important pieces are:
|
|
|
|
| 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. |
|
|
|
|
## Building
|
|
|
|
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.
|
|
|
|
```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
|
|
|
|
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).
|
|
|
|
```
|
|
docs/
|
|
├── README.md overview + glossary
|
|
├── diagrams/ architecture & state-machine diagrams
|
|
└── meta/ documentation status format & style guide
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
**v1**
|
|
|
|
- [x] Governor
|
|
- [x] Treasury
|
|
- [x] Stakes
|
|
- [x] Proposals
|
|
- [x] Effects
|
|
|
|
**v2**
|
|
|
|
- [ ] Rewards distribution
|
|
- [ ] Escrow staking pool solution
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md)
|
|
before opening an issue or a pull request.
|
|
|
|
## License
|
|
|
|
Agora is licensed under the [Apache License 2.0](./LICENSE).
|
|
|
|
## Acknowledgements
|
|
|
|
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.
|