diff --git a/docs/manta-atlantic/Governance.md b/docs/manta-atlantic/Governance.md new file mode 100644 index 00000000..91bc0fed --- /dev/null +++ b/docs/manta-atlantic/Governance.md @@ -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: + +
+ + governance video + +
+ +**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) + diff --git a/docs/manta-atlantic/GovernanceDeepdive.md b/docs/manta-atlantic/GovernanceDeepdive.md new file mode 100644 index 00000000..d5654048 --- /dev/null +++ b/docs/manta-atlantic/GovernanceDeepdive.md @@ -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. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index c0469871..fe66b79f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -194,6 +194,14 @@ module.exports = { }, ], }, + { + type: "category", + label: "Governance", + items: [ + "manta-atlantic/Governance", + "manta-atlantic/GovernanceDeepdive", + ] + } ], }, {