Development

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

docs/sdk-and-tools/mxpy/mxpy-cli.md

@@ -305,6 +305,26 @@ We can remove an address from the config using the alias of the address and the
 mxpy config-wallet remove --alias alice
 ```
 
+## Estimating the Gas Limit for transactions
+
+mxpy (version 11.1.0 and later) can automatically estimate the required gas limit for transactions when a proxy URL is provided. The estimation works by simulating the transaction before sending it.
+
+While the estimation is generally accurate, it's recommended to add a safety margin to account for potential state changes. This can be done in two ways:
+
+1. Per transaction, using the `--gas-limit-multiplier` flag:
+
+```sh
+mxpy tx new --gas-limit-multiplier 1.1 ...
+```
+
+2. As a global default setting in the config:
+
+```sh
+mxpy config set gas_limit_multiplier 1.1
+```
+
+A multiplier of 1.1 (10% increase) is typically sufficient for most transactions.
+
 [comment]: # (mx-context-auto)
 
 ## Creating wallets

docs/utils.mdx

@@ -273,7 +273,7 @@ $$
 
 Image path should include `#gh-light-mode-only` for the Light Theme and `#gh-dark-mode-only` for the Dark Theme
 
-![Docusaurus themed image](/img/logo.svg#gh-light-mode-only)![Docusaurus themed image](/img/logo_dark.svg#gh-dark-mode-only)
+![Docusaurus themed image](/img/logo_dark.svg#gh-light-mode-only)![Docusaurus themed image](/img/logo.svg#gh-dark-mode-only)
 
 ### Second Version
 
@@ -287,8 +287,8 @@ import ThemedImage from "@theme/ThemedImage";
 <ThemedImage
   alt="Docusaurus themed image"
   sources={{
-    light: useBaseUrl("/img/logo.svg"),
-    dark: useBaseUrl("/img/logo_dark.svg"),
+    light: useBaseUrl("/img/logo_dark.svg"),
+    dark: useBaseUrl("/img/logo.svg"),
   }}
 />