diff --git a/docs/governance/governance-interaction.md b/docs/governance/governance-interaction.md index fb838278e..27a01e3ac 100644 --- a/docs/governance/governance-interaction.md +++ b/docs/governance/governance-interaction.md @@ -7,7 +7,7 @@ title: Governance interaction ### Introduction -The interaction with the governance system smartcontract is done through correctly formatted transactions to submit actions and through the usage of the vm-query REST API calls for reading the proposal(s) status. +The interaction with the governance system smart contract is done through correctly formatted transactions to submit actions and through the usage of the vm-query REST API calls for reading the proposal(s) status. [comment]: # (mx-context-auto) @@ -19,7 +19,7 @@ The proposal creation transaction has the following parameters: GovernanceProposalTransaction { Sender: Receiver: erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqrlllsrujgla - Value: 1000 EGLD + Value: 500 EGLD GasLimit: 51000000 Data: "proposal" + "@" + @@ -28,14 +28,18 @@ GovernanceProposalTransaction { } ``` -The proposal identifier is a hex string containing exactly 40 characters. Usually, this can be a git commit hash on which the proposal is made but can be any other identifier string. +The value parameter represents the mandatory proposal submission deposit of 500 EGLD. -The starting & ending epochs should be an even-length hex string containing the starting epoch and the ending epoch. During this time frame the votes can be cast. +The proposal identifier is a hex string containing exactly 40 characters. This is the git commit hash on which the proposal is made. + +The starting & ending epochs should be an even-length hex string containing the starting epoch and the ending epoch. During this time frame, lasting at most 10 days, the votes can be cast. + +>**Note:** When providing the starting epoch, it should be taken into consideration that the governance contract enforcing a configured maximum gap of 30 epochs between the current epoch and the proposal’s starting epoch. After issuing the proposal, there is a log event generated having the `proposal` identifier that will contain the following encoded topics: -- `nonce` as encoded integer which uniquely identifies the proposals -- `identifier` the provided 40 hex characters longs identifier +- `nonce` as encoded integer which uniquely identifies the proposals +- `identifier` is the provided 40 hex characters long identifier - `start epoch` as encoded integer for the starting epoch - `end epoch` as encoded integer for the ending epoch @@ -44,6 +48,7 @@ After issuing the proposal, there is a log event generated having the `proposal` ### Voting a proposal using the direct staked or delegation-system amount Any wallet that has staked EGLD (either direct staked or through the delegation sub-system) can cast a vote for a proposal. + ```rust GovernanceVoteTransaction { Sender: @@ -56,28 +61,54 @@ GovernanceVoteTransaction { } ``` +The value parameter for the voting transaction must be set to 0, since the function is non-payable. + The `nonce` is the hex encoded value of the proposal's unique nonce and the `vote_type` can be one of the following values: - for **Yes**: `796573`; - for **No**: `6e6f`; - for **Abstain**: `6162737461696e`; - for **Veto**: `7665746f`. -The vote value for the account that will vote a proposal is the sum of all staked values along with the sum of all delegated values in the delegation sub-system. +The vote value for the account that will vote a proposal is the sum of all staked values along with the sum of all delegated values in the delegation sub-system. + +After issuing the vote, a log event is generated containing the `proposal` identifier and the following encoded topics: + +- `nonce` as encoded integer which uniquely identifies the proposals +- `vote_type` as encoded string representing the vote +- `total_stake` total staked EGLD for the sender address +- `total_voting_power` total available voting power for the sender address + +Example response: + +```json +{ + "returnData": [ + "WQ==", (nonce: hex = 59 -> decimal = 89) + "eWVz", (vote_type: hex = "79657" -> "yes") + "BxRA1dqcrTxyQw==", (total_stake: hex = "071440d5da9cad3c7243" -> 33430172142116630458947 -> ~33430 EGLD) + "BxRA1dqcrTxyQw==", (total_voting_power: hex = "071440d5da9cad3c7243" -> 33430172142116630458947 -> ~33430 EGLD) + ] +} +``` [comment]: # (mx-context-auto) ### Voting a proposal through smart contracts (delegation voting) Whenever we deal with a smart contract that delegated through the delegation sub-system or owns staked nodes it is the out of scope of the metachain's governance contract to track each address that sent EGLD how much is really staked (if any EGLD is staked). + That is why we offered an endpoint to the governance smart contact that can be called **only by a shard smart contract** and the governance contract will record the address provided, the vote type and vote value. -This is very useful whenever implementing liquid-staking-like smart contracts. The liquid-staking contract knows the balance for each user, so it will delegate the call to the governance contract providing the value. + +This is very useful whenever implementing liquid-staking-like smart contracts. The liquid-staking contract knows the balance for each user, so it will delegate the call to the governance contract providing the corresponding voting power. :::important The maximum value for the staked value & the voting power for the liquid-staking contract is known by the governance contract, so it can not counterfeit the voting. If, due to a bug the liquid-staking contract allows, for example, for a user to vote with a larger quota, the liquid-staking contract will deplete its maximum allowance making other voting transactions (on his behalf) to fail. ::: +The user that delegated through a liquid-staking-like contract in order to vote on a proposal, sends a transaction to the liquid-staking-like contract. The smart contract then creates the GovernanceVoteThroughDelegationTransaction based on the user’s transaction inputs, forwarding the vote and the computed voting power to the governance contract. + ```rust -GovernanceVoteThourghDelegationTransaction { +GovernanceVoteThroughDelegationTransaction { Sender: Receiver: erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqrlllsrujgla Value: 0 EGLD @@ -85,11 +116,13 @@ GovernanceVoteThourghDelegationTransaction { Data: "delegateVote" + "@" + "@" + - "@" + - "@" + "@" + + "@" } ``` +The value parameter for the voting transaction must be set to 0, since the function is non-payable. + The `nonce` is the hex encoded value of the proposal's unique nonce and the `vote_type` can be one of the following values: - for **Yes**: `796573`; - for **No**: `6e6f`; @@ -97,32 +130,60 @@ The `nonce` is the hex encoded value of the proposal's unique nonce and the `vot - for **Veto**: `7665746f`. The `account address handled by the smart contract` is the address handled by the smart contract that will delegate the vote towards the governance smart contract. This address will be recorded for casting the vote. -The `vote_balance` is the amount of stake the address has in the smart contract. The governance contract will "believe" that this is the right amount as it impossible to verify the information. The balance will diminish the total voting power the smart contract has. + +The `vote_balance` is the amount of stake the address has in the smart contract. The governance contract will "believe" that this is the right amount as it impossible to verify the information. The balance will diminish the total voting power the smart contract has. + +After issuing the vote, a log event is generated containing the `proposal` identifier and the following encoded topics: + +- `nonce` as encoded integer which uniquely identifies the proposals +- `vote_type` as encoded string representing the vote +- `voter` account address handled by the smart contract +- `total_stake` total staked EGLD for the sender address +- `total_voting_power` total available voting power for the sender address + +Example response: + +```json +{ + "returnData": [ + "WQ==", (nonce: hex = 59 -> decimal = 89) + "eWVz", (vote_type: hex = "79657" -> "yes") + "ATlHLv9ohncamC8wg9pdQh8kwpGB5jiIIo3IHKYNaeE=", (voter: hex = "0139472eff6886771a982f3083da5d421f24c29181e63888228dc81ca60d69e1" -> erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th) + "BxRA1dqcrTxyQw==", (total_stake: hex = "071440d5da9cad3c7243" -> 33430172142116630458947 -> ~33430 EGLD) + "BxRA1dqcrTxyQw==", (total_voting_power: hex = "071440d5da9cad3c7243" -> 33430172142116630458947 -> ~33430 EGLD) + ] +} +``` [comment]: # (mx-context-auto) ### Closing a proposal -A proposal can be closed only in an epoch that is strictly higher than the end epoch value provided when the proposal was open. +A proposal can be closed by the issuer before the voting period starts but with an early closing fee equal to `LostProposalFee`. A proposal can also be closed by anyone in an epoch that is strictly higher than the end epoch value provided when the proposal was opened. ```rust CloseProposalTransaction { - Sender: + Sender: Receiver: erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqrlllsrujgla - Value: 0 EGLD + Value: 0 EGLD GasLimit: 51000000 - Data: "closeProposal" + - "@" + Data: "closeProposal" + + "@" } ``` -Only the address that created the proposal can call the `closeProposal` function that will also trigger the funds unlocking. As stated in the overview page, if the proposal does not pass, the amount returned will be less with 10 EGLD. +#### Rules for closing +- The proposal can be closed by the issuer before the voting starts or by anyone after voting ended. +- If the proposal **passes** → the full proposal fee is refunded. +- If the proposal **fails** or is **vetoed** → the refund is reduced by the `LostProposalFee`. +- Once a proposal is closed, it cannot be reopened. +- Closing also finalizes the vote tally (the proposal is marked as `Passed` or not, based on the results). [comment]: # (mx-context-auto) ### Querying the status of a proposal -The status of a certain proposal can be queried at any time by using the `vm-values/query` REST API endpoints provided by the gateway/API. +The status of any proposal can be queried at any time through `vm-values/query` REST API endpoints provided by the gateway/API. ```bash https://.multiversx.com/vm-values/query @@ -132,53 +193,55 @@ https://.multiversx.com/vm-values/query { "scAddress": "erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqrlllsrujgla", "funcName": "viewProposal", - "args": [""] + "args": [""] } ``` -the `nonce` represents the proposal nonce in hex format. The response will contain the following json definition where all fields are base64-encoded: +- The argument `nonce` is the proposal nonce in hex format. +- The response will contain the following json definition where all fields are base64-encoded: ```json { "returnData": [ - "", - "", - "", - "", - "", - "", - "", - "", - "", - "", - "", + "", (amount locked by proposer) + "", (unique identifier of the proposal) + "", (proposal number) + "", (address of the proposer) + "", (epoch when voting starts) + "", (epoch when voting ends) + "", (current quorum stake: sum of stake that participated) + "", (total stake voting YES) + "", (total stake voting NO) + "", (total stake vetoing the proposal) + "", (total stake abstaining) "", "" ] } ``` -Example: +Example response: ```json { "returnData": [ - "NjXJrcXeoAAA", (proposal locked amount: 1000 EGLD denominated = 1000 * 10^18) + "Gxrk1uLvUAAA", (proposal locked amount: 500 EGLD denominated = 500 * 10^18) "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABg==", (commit hash: 0x0000...006) "AQ==", (nonce: 1) - "aj88GtqHy9ibm5ePPQlG4aqLhpgqsQWygoTppckLa4M=", (address: erd1dglncxk6sl9a3xumj78n6z2xux4ghp5c92cstv5zsn56tjgtdwpsk46qrs) + "aj88GtqHy9ibm5ePPQlG4aqLhpgqsQWygoTppckLa4M=", (proposer address) "bQ==", (starting epoch: 109) "bg==", (ending epoch: 110) - "ntGU2xmyOMAAAA==", (quorum: 750000 EGLD = 7500000 * 10^18) - "", (yes value: 0) - "", (no value: 0) - "ntGU2xmyOMAAAA==", (veto value: 7500000 * 10^18) - "", (abstain value: 0) + "ntGU2xmyOMAAAA==", (quorum: 750000 EGLD denominated) + "", (yes votes: 0) + "", (no votes: 0) + "ntGU2xmyOMAAAA==", (veto votes: 750000 EGLD denominated) + "", (abstain votes: 0) "dHJ1ZQ==", (proposal closed: true) "ZmFsc2U=" (proposal passed: false) ] } ``` + [comment]: # (mx-context-auto) ### Querying an address voting status (direct staking or system delegation) @@ -186,57 +249,136 @@ Example: The voting status of a certain address can be queried at any time by using the `vm-values/query` REST API endpoints provided by the gateway/API. ```bash -https://.multiversx.com/vm-values/query +https://gateway.multiversx.com/vm-values/query ``` +With the following payload: + ```json { "scAddress": "erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqrlllsrujgla", - "funcName": "viewUserVoteHistory", - "args": ["
"] + "funcName": "viewDelegatedVoteInfo", + "args": ["", "
"] } ``` -the `address` represents the address in hex format. The response will contain the following json definition where all fields are base64-encoded: +- `proposal_nonce` → the proposal identifier (nonce, hex-encoded). +- `address` → the bech32 address of the account to check. + +> **Note:** The older function `viewUserVoteHistory` (which returned lists of proposal nonces) is now considered legacy. +> Use `viewDelegatedVoteInfo` for detailed voting power and stake information. + +The response will contain the following json definition where all fields are base64-encoded: ```json { "returnData": [ - "", - "", - "", - ... - "", - "", - "", - "", - ... - "" + "", (voting power used by this address on the proposal) + "", (stake associated with the used power) + "", (total available voting power for the address) + "" (total stake considered in governance for the address) ] } ``` -Example for an address that cast votes on 5 proposals: +Example for an address that voted: ```json { "returnData": [ - "Aw==", (number of delegated nonces: 3) - "AQ==", (nonce: 1) - "Ag==", (nonce: 2) - "Aw==", (nonce: 3) - "Ag==", (number of direct nonces: 2) - "BA==", (nonce: 4) - "BQ==", (nonce: 5) + "Cg==", (used power: 100) + "ZAA=", (used stake: 100) + "A+g=", (total power: 1000) + "Gg4M=", (total stake: 1000) + ] +} +``` + +In this example, the queried address voted on this proposal with **100 stake**, which translated into **100 voting power**. The proposal overall had **1000 total stake** and **1000 total voting power** recorded. + +Example for an address that did not vote: + +```json +{ + "returnData": [ + "AA==", (used power: 0) + "AA==", (used stake: 0) + "A+g=", (total power: 1000) + "A+g=", (total stake: 1000) + ] +} +``` + +### Querying the voting power of an address + +The voting power of a certain address can be queried at any time by using the `vm-values/query` REST API endpoints provided by the gateway/API. + +```bash +https://gateway.multiversx.com/vm-values/query +``` + +With the following payload: + +```json +{ + "scAddress": "erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqrlllsrujgla", + "funcName": "viewVotingPower", + "args": [""] +} +``` + +Here's an example of the response: + +```json +{ + "returnData": [ + "Q8M8GTdWSAAA" (1250000000000000000000 -> 1250 EGLD) ] } ``` -Example for an address that did not cast votes on any proposals: +### Querying the configuration of the Governance contract + +The configuration of the Governance System Smart Contract can be queried at any time by using the `vm-values/query` REST API endpoints provided by the gateway/API. + +```bash +https://gateway.multiversx.com/vm-values/query +``` + +With the following payload: + +```json +{ + "scAddress": "erd1qqqqqqqqqqqqqqqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqrlllsrujgla", + "funcName": "viewConfig", + "args": [] +} +``` + +The response will contain the following json definition where all fields are base64-encoded: + ```json { "returnData": [ - "AA==", (number of delegated nonces: 0) - "AA==", (number of direct nonces: 0) + "", (the amount of EGLD required to issue a new proposal) + "", (the amount of EGLD that the issuer loses if the proposal fails) + "", (the minimum percentage of total voting power required for a proposal to be considered valid) + "", (the minimum percentage of veto votes needed to reject a proposal and slash its fee) + "", (the minimum percentage of YES votes required for a proposal to pass) + "" (the nonce of the last created proposal) ] } ``` + +Here's how a response might look like: +```json +{ + "returnData": [ + "NTAwMDAwMDAwMDAwMDAwMDAwMDAw", ("500000000000000000000" -> 500 EGLD) + "MTAwMDAwMDAwMDAwMDAwMDAwMDA=", ("10000000000000000000" -> 10 EGLD) + "MC4yMDAw", ("0.2000" -> 20%) + "MC4zMzAw", ("0.3300" -> 33%) + "MC42NjY3", ("0.6667" -> 66.67%) + "MA==", ("0" -> 0) + ], +} +``` diff --git a/docs/governance/overview.md b/docs/governance/overview.md index a8c7d2994..df76e7e4f 100644 --- a/docs/governance/overview.md +++ b/docs/governance/overview.md @@ -19,54 +19,103 @@ This page provides an overview of the On-chain Governance module that will be av ## Overview -The MultiversX network is able to handle on-chain governance proposes by issuing special types of transactions. This was implemented as a mean for further increasing the decentralization of the decision-making process. +The MultiversX network enables on-chain governance by issuing special types of transactions. This mechanism increases decentralization by allowing community members to directly propose and vote on changes, such as protocol upgrades or configuration adjustments. -Anyone can create a proposal using their wallet and issuing a special type of transaction specifying an identifier, a starting epoch and an end epoch. - -Users that staked EGLD will be able to cast votes upon opened proposals. The voting power is proportional with the staked value and is computed as `voting_power = staked_value` (linear voting). +- **Anyone** can create a proposal by paying the proposal fee and specifying: + - a **commit hash** (unique identifier, usually a GitHub commit or spec reference) + - a **start epoch** and an **end epoch** (the voting window). +- **Any staked user** (direct or delegated) can vote during the active period. +- Voting power is proportional to stake: + `voting_power = staked_value` (linear voting). [comment]: # (mx-context-auto) ## Implementation details -Each proposal costs 1000 EGLD that will be locked during the voting of the proposal. If the proposal is either rejected or accepted, the entire locked sum can be unlocked & withdrawn. If the proposal do not pass, 10 EGLD will remain locked in the governance smart contract as a penalty fee. The proposal costs around 51 million of gas units. +### Proposals + +In order for a proposal to be submitted, the following requirements need to be met: +- For a period of at least 15 days, the proposal needs to be published on Agora for public debate and analysis; +- Each proposal requires paying a `ProposalFee` (currently **500 EGLD**); +- Each proposal costs around 51 million of gas units to be submitted. +- The starting epoch of the proposal's voting period needs to be set inside an interval of 30 epochs from the epoch in which the proposal was submitted; + +After a proposal is created, the following rules will apply: +- If the proposal passes, the fee is refunded to the issuer. +- If the proposal fails, a penalty fee (called `LostProposalFee`) is deducted from the initial proposal fee, and the remaining amount is returned to the proposer. +- If the proposal is vetoed, the fee is slashed (transferred to the **Community Governance Pool**) or reduced by the configured `LostProposalFee`. +- Proposals cannot be duplicated: the same commit hash cannot be submitted twice. +- Proposals can be **cancelled** by the issuer **before the voting period starts**. (introduced in v1.10.0 Barnard release) +- Lost proposal fees may either be accumulated in the governance contract (retrievable by the contract owner) or redirected to a **Community Governance Pool**, depending on configuration. + + +### Voting +- The voting starts from the provided starting epoch and lasts at most *10 days*. +- There are four vote types: **Yes**, **No**, **Abstain**, and **Veto**. +- Voting consumes gas (approx. 6 million units). +- Voting power is derived from staked and delegated EGLD. +- Delegation and liquid staking contracts can forward user votes. +- Voting power is **linear** with stake: the more EGLD staked or delegated, the higher the voting power. +- The contract tracks both **used voting power/stake** (applied in a proposal) and **total available voting power/stake** for each address. + +### Quorum and thresholds +A proposal can pass only if all conditions are met: -There are 4 types of votes: **Yes**, **No**, **Abstain** and **Veto**. Each of the vote costs around 6 million of gas units. +- **Quorum**: at least `MinQuorum%` of the total voting power must participate. (currently at least **20%** of total voting power) +- **Acceptance threshold**: YES / (YES + NO + VETO) ≥ **66.67%** (`MinPassThreshold`) +- **Veto threshold**: if VETO votes exceed **33%** of total participating voting power, the proposal is rejected and the proposal fee is slashed. -A user can create any number of proposals as long as it pays the locking fee & the gas used for the transaction. The proposal can be closed in any epoch following the provided end epoch. +### Closing and cleanup +**Proposal closing permissions:** +- **Before voting starts:** Only the proposal issuer can close the proposal. +- **After voting ends:** Any user can close the proposal. -The quorum is computed as the sum of the staked EGLD for all addresses that cast votes. +**Effects of closing:** +1. Finalizes the proposal outcome (passed/failed/vetoed). +2. Unlocks any locked funds. +3. Updates the proposal status in the governance system. -The votes will be added for each category (**Yes**, **No**, **Abstain** and **Veto**). The vote is computed as `vote = total_staked_value` for each address that cast a vote. +**Cleanup options:** +- The `clearEndedProposals` function can be called to clean up expired but unclosed proposals. +- This helps maintain system efficiency by removing inactive proposals. -A proposal can pass only if all conditions are met: -- the quorum value is at least the minimumQuorumThresholdPercentage * total staked value held by the staking contracts; -- the **Yes** value > **No** value (simple majority); -- the **Yes** value is at least the minimumPassThresholdPercentage * sum of votes on all 4 categories. -- the **Veto** value did not reach the minimumVetoThresholdPercentage * sum of votes on all 4 categories; +### Governance configuration +All thresholds and fees are defined in `GovernanceConfigV2`: +- `MinQuorum` +- `MinPassThreshold` +- `MinVetoThreshold` +- `ProposalFee` +- `LostProposalFee` +- `LastProposalNonce` + +These values are set by the system and can be updated by contract owner calls. [comment]: # (mx-context-auto) ### Example Let's suppose we have the following addresses that cast the following votes: -- `alice`: staked value 2000 EGLD that vote **Yes** -- `bob`: staked value 3000 EGLD that vote **Yes** -- `charlie`: staked value 4000 EGLD that vote **Yes** -- `delta`: staked value 1500 EGLD that vote **No** - -The quorum in this case will be a value `(2000+3000+4000+1500) * 10^18 = 10500 * 10^18`. - -The **Yes** category will hold the value `2000 * 10^18 + 3000 * 10^18 + 4000 * 10^18 = 9000 * 10^18` -The **No** category will hold the value `1500 * 10^18` -The **Abstain** and **Veto** categories will both hold 0. -The total voted value is `9000 * 10^18 + 1500 * 10^18 + 0 + 0 = 10500 * 10^18` - -Supposing the total staked value in the system is `20000 EGLD` and the minimum quorum threshold percentage is `20%`, then the minimum quorum value is `20% * 20000 = 4000 EGLD`. - -The following list contains true sentences: -- the quorum value (`10500 EGLD`) is larger than the minimum quorum (`4000 EGLD`) -- **Yes** value (`9000 * 10^18`) is larger than the **No** value (`1500 * 10^18`) -- **Yes** value (`9000 * 10^18`) is larger than the pass threshold (`50%`) \* total voted value (`10500 * 10^18`) which is `5250 * 10^18` -- the **Veto** did not reach `33%` of the total vote value because it was `0` - -To sum it all, **the proposal passed**. +- `alice`: staked value **2000 EGLD** that vote **Yes** +- `bob`: staked value **3000 EGLD** that vote **Yes** +- `charlie`: staked value **4000 EGLD** that vote **Yes** +- `delta`: staked value **1500 EGLD** that vote **No** + +The totals are: +- Quorum = `(2000+3000+4000+1500) = 10,500 EGLD` +- **Yes** = `9000 EGLD` +- **No** = `1500 EGLD` +- **Abstain** = `0` +- **Veto** = `0` + +Assume: +- total staked in the system = `20,000 EGLD` +- `MinQuorum` = 20% +- `MinPassThreshold` = 50% +- `MinVetoThreshold` = 33% + +Evaluation: +- Quorum is satisfied: `10,500 > 4000` +- Yes > No: `9000 > 1500` +- Yes is ≥ 50% of votes: `9000 / 10,500 = 85.7%` +- Veto is below 33%: `0 < 3465` + +To sum it all, the proposal **passes**.