Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add governance docs for atlantic #214

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Add governance docs for atlantic #214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
363ac5e
Add governance docs for atlantic
Dengjianping Jan 5, 2024
5a15700
Fix governance docs
Dengjianping Jan 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
107 changes: 107 additions & 0 deletions docs/manta-atlantic/Governance.md
View file
Open in desktop
@@ -0,0 +1,107 @@
# 🎙 Governance Overview

_Note: Manta is just beginning to implement Governance features, so a lot
of the planned features aren't available yet. This document describes what is
currently available, and will be updated as features are released._

Welcome to our Governance docs! Here you'll find a high level overview of
how token holders make decisions about how the Manta system is updated.
As a decentralized system, it's crucial that the Manta Network core development
can't implement or remove any features without community consent. The roadmap
of planned feature development lives [here](https://emphasized-seed-161.notion.site/3b1b61e0aee8484396d674f4653e0813?v=451a4ad2105d4f9cb35fb74680359c1d).

The [Manta Governance Deep Dive doc](GovernanceDeepdive.md)
is a great resource if you're looking for more of the technical details about
show Manta governance works.

## Intro

At a high level, changes to Manta follow three steps:

- **Launch Period**: Token holders submit proposals that turn into referendums.
- **Voting Period**: Token holders vote on referendums.
- **Enactment Period**: Successful referendums are automatically enacted.

There are three key actors in this system:

- **Public token holders**: This is you!
- **The Council**: Represents passive token holders.
- **Technical Committee**: Handles emergencies.

## 1) Launch Period

Changes to the Manta system start out as a **proposal**. Token holders
or the Council submit the [preimage hash of a proposal](https://wiki.polkadot.network/docs/maintain-guides-democracy#proposing-an-action)
to the proposal queue. Other token holders can then second the proposal with
their stake, and at the end of a Launch Period the proposal with the most
backing stake is promoted to a **referendum**. We only promote one proposal
at a time to avoid the situation where two opposing proposals pass simultaneously.

Right now, only the council can submit new proposals. The method they use
is called `democracy.externalProposeDefault`, and it will be available to
all token holders in upcoming releases.

## 2) Voting Period

All token holders get to vote aye or nay on referendums. The percent of ayes required
for a referendum to pass changes based on turnout. The method `democracy.externalProposeDefault`
has a "negative turnout bias", meaning if there's low turnout, the
threshold to pass is lower, and as turnout increases, the threshold increases.
For example, if the turnout is 25%, then 34% ayes are needed to pass. But if the
turnout is 100%, then 51% of ayes are needed (a simple majority).

This approach to voting is called [Adaptive Quorum Biasing](https://wiki.polkadot.network/docs/learn-governance#adaptive-quorum-biasing).
The idea behind it is to anticipate that voter turnout in practice is
never going to be 100%, and that different proposals will have varying levels of
contentiousness and trustworthiness. For example, we assume that a proposal
submitted by the Council is more trust worthy than a proposal from any public
token holder, so we want to apply a negative turnout bias to the vote.

## 3) Enactment Period

Once a referendum passes, it is automatically implemented by the chain according to
the referendum code. There's a delay before the implementation starts so that
stake holders can prepare for the change.

### A note on the responsibilities of the Council and Technical Committee

The Technical Committee can fast-track the launch period, voting period, and enactment
period in the case of an emergency. How much the periods are shortened depends
on how many committee members believe the action is necessary, with unanimous
agreement required for instantaneous changes. Similarly, the Council can cancel
a referendum during the voting period.

Clearly the Council and the Technical Committee have a lot of influence over
what proposals and referendums get passed! The Council offsets the usual low
voter turnout in democratic systems, and is expected to submit proposals for
regular operations and maintenance of the system. The Technical Committee exists
to handle emergency situations where fast technical updates are needed.

## How To: Vote on a Referendum

The actions you can take as a public token holder can all be executed by connecting
to a Manta node using the [Polkadot.JS apps interface](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fws.manta.systems#/democracy).
You can find our tutorial on how to vote in a referendum below:

<div style={{textAlign: 'center'}}>
<a href="https://www.youtube.com/watch?v=0MN9TbRlvhk">
<img alt="governance video" src="https://img.youtube.com/vi/0MN9TbRlvhk/0.jpg" width="70%"/>
</a>
</div>

**Note** that voting with the default amount from polkadot-js front end will fail,
due to the fact that the transaction fee is more than the existential deposit of accounts.
Please reduce that amount slightly to avoid this error.

## More Resources

If you'd like to learn more about governance in the Polkadot ecosystem, these links
are a great place to start:

- [Manta Governance Deep Dive](GovernanceDeepdive.md)
- [Polkadot docs](https://wiki.polkadot.network/docs/learn-governance)
- [Polkadot video tutorials](https://wiki.polkadot.network/docs/learn-video-tutorials#getting-started)
- [Polkadot blog on governance systems](https://polkadot.network/blog/polkadot-governance/)
- [Polkadot blog on the governance of the Kusama rollout](https://polkadot.network/blog/kusama-rollout-and-governance/)
- [Polkadot wiki "Participate in Democracy"](https://wiki.polkadot.network/docs/maintain-guides-democracy)

171 changes: 171 additions & 0 deletions docs/manta-atlantic/GovernanceDeepdive.md
View file
Open in desktop
@@ -0,0 +1,171 @@
# Governance Deep Dive

This doc is a more technical dive into how governance on Manta operates.
Manta is built on Polkadot and Substrate; the governance system is
directly inspired by what Polkadot uses. One of the main differences is that
our Council manages its own membership.

_Note: not everything documented here is released yet. Check our
[roadmap](https://emphasized-seed-161.notion.site/3b1b61e0aee8484396d674f4653e0813?v=451a4ad2105d4f9cb35fb74680359c1d)
for the up to date status of features._

## Concepts to know

If you're reading this doc we're assuming you know what an
[extrinsic](https://docs.substrate.io/v3/concepts/extrinsics/) is, and that
you're generally familiar with
[how Substrate runtimes work](https://docs.substrate.io/v3/concepts/runtime/).

## System Actors

There are three kinds of actors that can participate in governance
on Manta: _Public Token Holders, the _Council_, and the _Technical Committee_.
They all have a different set of extrinsics they are allowed to submit to the chain.

The **Public Token Holders** are everyone who owns a Manta token. They can use
their stake to second proposals that are trying to become referendums, and
vote on referendums, proportional to the amount of stake they have.

The **Council** represents passive token holders and exists because democratic
systems usually have issues with low voter turnout. There are three council
members, and their responsibility is to submit common sense proposals for the
regular development and maintenance of the system. In our case, the Council is
also responsible for bootstrapping the Manta Network and is thus made up of
members of the Manta Core Development Team. The Council manages the membership
of the Technical Committee.

The **Technical Committee** is responsible for handling emergencies. They
have the ability to fast track all three periods, and how much the periods
are shortened depends on how many committee members believe the action is necessary.
Unanimous agreement is required for instantaneous changes. There are three
technical committee members, and they are also part of the Manta Core
Development Team.

## Launch Phase

The process of submitting a proposal starts out by getting the preimage hash
of the proposal, in order to verify that it doesn't change at any point during
the process.

There are two ways to submit a proposal, and the launch periods alternate
between the two methods.

### 1. Public token holder proposals

Public token holders can submit a preimage hash using the
`democracy.externalProposeDefault()` extrinsic. These proposals all go
into the `public proposal queue`. Then stakeholders can second proposals,
and the proposal with the most stake backing it at the end of the period
is promoted to a referendum.

### 2. Council motions

The council can create "council motions" also called "external proposals".
They can submit the preimage hash using three methods,

* `democracy.externalPropose()`
* `democracy.externalProposeMajority()`
* `democracy.externalProposeDefault()`

which have differences in voting thresholds that we'll cover in the [Voting Phase](#voting-phase)
section below. The council votes on the proposal internally, with one vote per
council member, and if it passes, the proposal moves to the `external propose queue`
where it waits for the end of the period and is automatically promoted to a referendum.

We only promote one proposal at a time to avoid the situation where two opposing
proposals pass simultaneously.

During this period, the Technical Committee has the ability to cancel any proposal
and fast track proposals made using the `democracy.externalPropose()` or
`democracy.externalProposeDefault()` extrinsics.

## Voting Phase

At the start of the Voting Period a referendum has been tabled either from the
external proposal queue or the public proposal queue. Now token holders have
the opportunity to vote on the referendum with an `aye` to pass or `nay` to
reject.

The percent of ayes needed for a referendum to pass depends on the extrinsic
used to submit the proposal, and varies based on voter turnout using a method
called **Adaptive Quorum Biasing**. The idea is to anticipate that in practice
voter turnout is not `100%`, and that different proposals will have varying
levels of contentiousness and trustworthiness.

If a **positive turnout bias** is applied, then a super-majority threshold is
required to _pass_ at low levels of turnout, and the threshold decreases as
turnout increases. On the other hand applying a **negative turnout bias** means
that a super majority is needed to _reject_ at low levels of turnout, and the
threshold increases as turnout increases. In all cases these biasings work out
so that if `51%` of the total stake votes in one direction (a simple majority),
then that choice is executed.

Now let's look at the different biases that are applied to the different extrinsics:

| Extrinsic | Vote Bias | Low turnout behavior |
|---------------------------|-------------------------|---------------------------------|
| `externalPropose` | `no` bias | always simple `50% + 1` |
| public proposal | `positive` turnout bias | threshold to pass starts `high` |
| `externalProposeMajority` | `positive` turnout bias | threshold to pass starts `high` |
| `externalProposeDefault` | `negative` turnout bias | threshold to pass starts `low` |

Let's consider an example of an external proposal generated by `democracy.externalProposeDefault()`.
Consulting the table above we see that this extrinsic has a negative turnout bias applied.
In other words, the threshold for passing starts low and increases as turnout increases.
For example, at `25%` turnout it needs `34%` ayes to pass, at `75%` turnout it needs `46%` ayes to pass.
As turnout increases, it becomes harder to pass approaching simple-majority of `50% + 1` of the turnout.

During the Voting Period the Technical Committee can fast-track external proposals created using
the `democracy.externalPropose()` or `democracy.externalProposeDefault()` extrinsics.
The Council also has the ability to cancel a referendum.

## Enactment Phase

Once a referendum passes, the chain automatically implements the referendum code
using the `pallet_scheduler`. There's a delay before the implementation starts so that
stake holders can prepare for the change.

As with the previous periods, the Technical Committee can fast-track the delay on
external proposals created using the `democracy.externalPropose()` or
`democracy.externalProposeDefault()`.

## The Treasury

The Treasury is a reserve of tokens that is controlled by the Council and
used to fund community projects. The goal of the Treasury is to have a source of funds
that can incentivize projects on the network. Anyone can submit a treasury
spend proposal with a `1%` deposit of the total spend amount, and the proposal
will be approved or denied by the council.

The funds in the treasury are collected through:

1. **Transaction fees**: `90%` of on-chain transaction fees are transferred to the Treasury.
2. **Treasury slashing**: when a treasury spend proposal doesn't pass, the
deposit amount (`1%` of the total proposed amount) is "slashed", which means
that it is transferred to the Treasury.
3. **Democracy slashing**: when any democracy proposal is canceled the
preimage deposit fee is transferred to the Treasury instead of being returned.

## API Reference

The naming of functions here follows the Substrate invocation method, `[pallet].[extrinsic]`.

| Extrinsic | Who can invoke | Unfiltered* |
|---------------------------------------------------|----------------------|----------------------|
| `democracy.notePreimage(call)` | Public Token Holders | Yes |
| `democracy.propose(preImageHash)` | Public Token Holders | No |
| `democracy.externalPropose(preImageHash)` | Council | No |
| `democracy.externalProposeDefault(preImageHash)` | Council | Yes |
| `democracy.externalProposeMajority(preImageHash)` | Council | No |
| `democracy.emergencyCancel(index)` | Technical Committee | Yes |
| `democracy.fastTrack(proposalHash)` | Technical Committee | Yes |
| `democracy.vetoExternal(proposalHash)` | Technical Committee | Yes |
| `democracy.cancelProposal(index)` | Technical Committee | Yes |
| `treasury.approveSpend(index)` | Council | No |
| `treasury.rejectSpend(index)` | Council | No |
| `treasury.proposeSpend()` | Treasury | No |
| `councilMembership.add()` | Council | Yes |
| `councilMembership.remove()` | Council | Yes |
| `councilMembership.swap()` | Council | Yes |

* In order to reduce the system's complexity during the initial rollout, some extrinsics are filtered out, and will be enabled in future updates.
8 changes: 8 additions & 0 deletions sidebars.js
View file
Open in desktop
Expand Up @@ -194,6 +194,14 @@ module.exports = {
},
],
},
{
type: "category",
label: "Governance",
items: [
"manta-atlantic/Governance",
"manta-atlantic/GovernanceDeepdive",
]
}
],
},
{
Expand Down