docs (governance): update interactions and overview #1145

sarasorici · 2025-09-01T07:57:01Z

Description of the pull request (what is new / what has changed)

Did you test the changes locally ?

yes
no

Which category (categories) does this pull request belong to?

document new feature
update documentation that is not relevant anymore
add examples or more information about a component
fix grammar issues
other

Development to main

Merge dev in main

Development into main

…ig references

into governance-update

Development into main

…ig references

into governance-update

spelling error

raduchis · 2025-09-08T07:14:57Z

docs/governance/governance-interaction.md

 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 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 starting & ending epochs should be an even-length hex string containing the starting epoch and the ending epoch. During this time frame, lasting 10 days, the votes can be cast.


During this time frame, lasting 10 days, the votes can be cast. -> lasting at most 10 days,

raduchis · 2025-09-08T07:27:05Z

docs/governance/governance-interaction.md

+- `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
+


can we please add an example here how the encoding looks like?
similar to line 197 from this file: https://github.com/multiversx/mx-docs/pull/1145/files#diff-07f3478f0433c88d1671159679aeaa7019d72cb78c63c302d45db6cc13fe1afeR197

I took this example: https://devnet-explorer.multiversx.com/transactions/2cd33ee164881dd273a3568ed6cb272e3d7f05b7b46fd8f4a64d28dc30e1fe48/logs

WQ== -> hex 59 -> 89 eWVz -> hex 79657 -> "yes" BxRA1dqcrTxyQw== -> hex 071440d5da9cad3c7243 -> 33430172142116630458947 (~33430 EGLD) BxRA1dqcrTxyQw== -> hex 071440d5da9cad3c7243 -> 33430172142116630458947 (~33430 EGLD)

raduchis · 2025-09-08T07:32:57Z

docs/governance/governance-interaction.md

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


providing the value -> providing the corresponding voting power.

raduchis · 2025-09-08T07:34:40Z

docs/governance/governance-interaction.md


+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 


also here please have an example of the encoding.

raduchis · 2025-09-08T07:40:46Z

docs/governance/governance-interaction.md

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


before the GovernanceVoteThroughDelegationTransaction we need a short explanation like this:

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 users transaction inputs to forward the vote and the computed voting power to the governance contract.

There's a typo in Thourgh -> Through

raduchis · 2025-09-08T08:01:13Z

docs/governance/governance-interaction.md

-    "AA==", (number of direct nonces: 0)
+    "AA==", (used power: 0)
+    "AA==", (used stake: 0)
+    "A+g=", (total power: 1000)


also here please make last 2 values equal.

raduchis · 2025-09-08T08:03:49Z

docs/governance/overview.md


-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.
+After a proposal is created, the following rules will apply: 
+- If the proposal passes or fails normally, the fee is refunded to the issuer.  


if the proposal fails, we currently refund the 500 from the proposal fee without the LostProposalFee so only if the proposal passes, the entire fee is refunded.

raduchis · 2025-09-08T08:05:11Z

docs/governance/overview.md


-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.
+### Voting
+- The voting starts from the provided starting epoch and lasts exactly *10 days*.


lasts at most 10 days

it should have been exactly, but it was implement with 1-10 days.

raduchis · 2025-09-08T08:07:56Z

docs/governance/overview.md

+- 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 cast votes on behalf of users.


do we need the () ?
can cast votes on behalf of users -> can forward user votes.

can cast votes on behalf sounds like the users can't/don't have to to anything.

raduchis · 2025-09-08T08:09:48Z

docs/governance/overview.md


-The quorum in this case will be a value `(2000+3000+4000+1500) * 10^18 = 10500 * 10^18`.
+### Closing and cleanup
+- Proposals can only be closed after the end epoch has passed.  


Can be closed also before the voting period has started, but only by the issuer.
Anyone can close them after the voting period ended.

popenta · 2025-09-08T07:24:29Z

docs/governance/overview.md

+- 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 cast votes on behalf of users.


the parentheses can be removed

popenta · 2025-09-08T07:33:28Z

docs/governance/governance-interaction.md

+    Value: 500 EGLD
    GasLimit: 51000000
    Data: "proposal" +
          "@<identifier>" +


i think a better name would be commit_hash.

and also specify than length is mandatory to be exactly 40 chars

popenta · 2025-09-08T07:34:33Z

docs/governance/governance-interaction.md


+The value parameter represents the mandatory proposal submission deposit of 500 EGLD.
+
 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.  


I think something like this is a bit more accurate:

The proposal identifier is a hex string containing exactly 40 characters. This is the git commit hash on which the proposal is made.

popenta · 2025-09-08T07:39:45Z

docs/governance/governance-interaction.md

+>**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:



replace identifier with commit hash bellow

popenta · 2025-09-08T08:08:40Z

docs/governance/governance-interaction.md

 ```json
 {
  "returnData": [
    "NjXJrcXeoAAA", (proposal locked amount: 1000 EGLD denominated = 1000 * 10^18)


let's change the example to use 500 EGLD

btc-fan · 2025-09-08T08:19:30Z

docs/governance/governance-interaction.md

+    Value: 500 EGLD
    GasLimit: 51000000
    Data: "proposal" +
          "@<identifier>" +


and also specify than length is mandatory to be exactly 40 chars

btc-fan · 2025-09-08T08:26:52Z

docs/governance/overview.md

+- `delta`: staked value **1500 EGLD** that vote **No**
+
+The totals are:
+- Quorum = `(2000+3000+4000+1500) = 10,500 EGLD`  


Regarding the quorum: it would be nice to clarify that it is calculated as 33% of the total staked EGLD, where total means the sum of Direct stake + Staking Providers + Legacy Staking.

cc: @raduchis

btc-fan · 2025-09-08T08:28:35Z

docs/governance/governance-interaction.md

 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 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 starting & ending epochs should be an even-length hex string containing the starting epoch and the ending epoch. During this time frame, lasting 10 days, the votes can be cast.


Can we rename days to Unbound Period duration, which is 10 Epochs on Mainnet

elvisboghiu

The following view methods are nnot documented: viewVotingPower, viewConfig.
You can find more information in governance contract.
https://github.com/multiversx/mx-chain-go/blob/master/vm/systemSmartContracts/governance.go

popenta · 2025-09-09T10:36:01Z

Merged the PR to governance-update where I'll do the fixes after review and then it will be merged in development.

LE: This is the PR: #1148.

danielailie and others added 7 commits July 29, 2025 13:19

Merge pull request multiversx#1138 from multiversx/development

2bdfe1b

Development to main

Merge pull request multiversx#1140 from multiversx/merge-dev-in-main

ea3c9ee

Merge dev in main

Merge pull request multiversx#1142 from multiversx/development

a257ff9

Development into main

docs(governance): update proposal close/query interaction and overview

f74892b

Merge branch 'multiversx:main' into governance-update

4f2ab22

chore(docs): remove duplicate governance files

dda38d8

WIP: save local changes

a90f711

sarasorici marked this pull request as draft September 1, 2025 08:26

sarasorici and others added 20 commits September 2, 2025 10:13

Update governance docs: clarified querying voting status

65ddd1e

Update governance docs: clarified older viewUserVoteHistory function

749d2b7

Update governance overview: clarified quorum and thresholds with conf…

bbcd78d

…ig references

update - governance creation of proposal and voting

1b33881

Merge branch 'governance-update' of https://github.com/LaraTifui/mx-docs

24a6491

into governance-update

update - gov interaction

2f6f6a0

Merge pull request multiversx#1142 from multiversx/development

20581df

Development into main

docs(governance): update proposal close/query interaction and overview

eb77ec4

Merge branch 'multiversx:main' into governance-update

21a2cbf

chore(docs): remove duplicate governance files

37ebcdb

WIP: save local changes

17d787b

Update governance docs: clarified querying voting status

283e1b7

Update governance docs: clarified older viewUserVoteHistory function

d63b7ff

Update governance overview: clarified quorum and thresholds with conf…

4208eaf

…ig references

Merge branch 'governance-update' of https://github.com/LaraTifui/mx-docs

c0ed157

into governance-update

update - gov interaction

c0e65eb

Merge branch 'governance-update' of https://github.com/LaraTifui/mx-docs

9893040

into governance-update

your message for docs/governance/overview.md

20d57a6

update - gov overview - alignment

ac32312

update - gov overview - fix alignment issue

cc97305

sarasorici marked this pull request as ready for review September 4, 2025 10:24

AdoAdoAdo changed the base branch from main to development September 4, 2025 10:39

AdoAdoAdo changed the base branch from development to master September 4, 2025 10:40

AdoAdoAdo changed the base branch from master to main September 4, 2025 10:41

popenta changed the base branch from main to development September 4, 2025 10:45

Update overview.md

d64eff3

spelling error

raduchis requested changes Sep 8, 2025

View reviewed changes

popenta reviewed Sep 8, 2025

View reviewed changes

btc-fan requested changes Sep 8, 2025

View reviewed changes

elvisboghiu requested changes Sep 8, 2025

View reviewed changes

popenta changed the base branch from development to governance-update September 9, 2025 10:34

popenta merged commit c2d4b87 into multiversx:governance-update Sep 9, 2025
3 checks passed


		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.


		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


		The value parameter represents the mandatory proposal submission deposit of 500 EGLD.

		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.

		>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:

docs (governance): update interactions and overview #1145

docs (governance): update interactions and overview #1145

Uh oh!

Conversation

sarasorici commented Sep 1, 2025

Description of the pull request (what is new / what has changed)

Did you test the changes locally ?

Which category (categories) does this pull request belong to?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elvisboghiu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

popenta commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

popenta commented Sep 9, 2025 •

edited

Loading