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