From d8dd5a0cb94b124912aa9cc36aac8b024407a103 Mon Sep 17 00:00:00 2001 From: Sulkta Date: Sun, 28 Jun 2026 11:59:27 -0700 Subject: [PATCH] docs: rewrite README for public release --- README.md | 143 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 99 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 6a24af8..27536c3 100644 --- a/README.md +++ b/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 -

- -

+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.