agora/README.md

Agora 🏛️

Agora is a set of Plutus scripts, written in Plutarch, that compose together to form an on-chain governance system for the Cardano 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.

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 (>= 2.3) with flakes enabled is required. See the NixOS download page for installation, and the Plutus binary-cache notes so you don't rebuild the world.

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

Common workflows are wrapped in the Makefile (all targets assume you are inside nix develop):

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:

cabal run agora-scripts -- --enable-cors-middleware

A Cardano Transaction Library (CTL) integration that already wires this up is available in agora-offchain.

Documentation

In-repository design documents live under docs/, including a glossary, the Governance Authority Token model, and the proposal state-machine diagrams under docs/diagrams/.

docs/
├── README.md            overview + glossary
├── diagrams/            architecture & state-machine diagrams
└── meta/                documentation status format & style guide

Roadmap

v1

• Governor
• Treasury
• Stakes
• Proposals
• Effects

v2

• Rewards distribution
• Escrow staking pool solution

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or a pull request.

License

Agora is licensed under the Apache License 2.0.

Acknowledgements

Agora was originally created by the Liqwid Labs and MLabs 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.