From 36a1f6e7303654ec299827f7986373d11b172fc5 Mon Sep 17 00:00:00 2001 From: tusoict Date: Mon, 28 Oct 2024 07:36:19 +0700 Subject: [PATCH] added README.md for custom gov module --- blvlabs_note.md | 48 ------------- custom/gov/README.md | 160 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+), 48 deletions(-) delete mode 100644 blvlabs_note.md create mode 100644 custom/gov/README.md diff --git a/blvlabs_note.md b/blvlabs_note.md deleted file mode 100644 index 68a7ce9b..00000000 --- a/blvlabs_note.md +++ /dev/null @@ -1,48 +0,0 @@ -Proposal to improve the Gov Module Mechanism by BLV Labs (KYCed) - -Enhancing the Oracle Module to Optimize the Calculation of Minimum Deposit for Proposals in the Gov Module -Problem: -As we know, the cryptocurrency market is always very volatile with large fluctuations, and so is #lunc, the price can also fluctuate with large amplitude, falling sharply or rising sharply - -In the current gov module logic, when creating a proposal, the creator will have to deposit #lunc (5 million lunc) first to push the proposal to the voting stage. So what will happen if the lunc price drops sharply? or rises sharply? This leads to the value of the proposal is not guaranteed. When the price is too small, it can lead to bad guys being able to spam many proposals online. - -So we decided to propose an improvement to the gov module to fix this problem: - -Objective: -Use Oracle module to update and calculate the minimum deposit required to create a proposal in the Gov module. - -In the event of a sharp drop or spike in LUNC price, the system will automatically increase the minimum margin to ensure the value of the proposal is maintained. - -The proposal value is kept at $500 (as suggested by the community), which will change the required lunc amount. - -Benefit: -This ensures that the required margin amount remains stable, unaffected by market price fluctuations, thus helping the network operate stably without being affected by price changes. - -Additionally, this mechanism prevents the network from being spammed with proposals if the LUNC price drops too low, which could allow bad actors to flood the network with spam proposals. - -Updated (28/8/2024) -After a quick check of v0.50, we decided to implement the logic as v0.50’s Canceling gov Proposal logic this helps avoid any conflicts if upgrading to v0.50 - -Updated (16/9/2024) -After listening to feedback from the community and validators, we have updated our proposal: - -Focus on feature #1: Enhancing the Oracle Module to Optimize the Calculation of Minimum Deposit for Proposals in the Gov Module - -Remove features #2 & #3, as this feature has been developed on SDK v.0.50 - -In the first proposal, we want to focus on small improvements and will complete well to demonstrate the team’s capabilities, as we are a new team on the Lunc Ecosystem We will continue to propose more complex improvements and features in the next proposals after completing this first proposal - -We hope that the community will trust and support us with the common goal of Lunc blockchain continuing to develop. - -Development Plan -Phase 1: Complete Enhancement 1 (*) -Research and delve into the Oracle and Gov modules. -Add supplementary API logic to the Oracle module to determine the price of LUNC. -Use the Oracle module API to add the minimum deposit calculation mechanism in the Gov module. -Complete the feature. -Conduct testing and write documentation. -Estimated Time: 4 weeks - -Timeline: 4 weeks -Total Budget: $5,000 -NOTED: This is a text proposal, not a community spend. We will put another proposal up for funding once we complete the work listed above. \ No newline at end of file diff --git a/custom/gov/README.md b/custom/gov/README.md new file mode 100644 index 00000000..055a4bf0 --- /dev/null +++ b/custom/gov/README.md @@ -0,0 +1,160 @@ +--- +sidebar_position: 1 +--- + +# `x/gov` +# Custom Governace Module Updates + +## Concepts + +*Disclaimer: This is work in progress. Mechanisms are susceptible to change.* + +The governance process is divided in a few steps that are outlined below: +* **Proposal submission:** Proposal is submitted to the blockchain with a + deposit. +* **Vote:** When the deposit for a proposal reaches a minimum threshold equivalent to + 500 USD (`MinUusdDeposit`), proposal is confirmed and vote opens. +* **Execution** After a period of time, the votes are tallied and depending + on the result, the messages in the proposal will be executed. +### Proposal submission + +#### Right to submit a proposal + +Every account can submit proposals by sending a `MsgSubmitProposal` transaction. +Once a proposal is submitted, it is identified by its unique `proposalID`. +#### Proposal Messages + +A proposal includes an array of `sdk.Msg`s which are executed automatically if the +proposal passes. The messages are executed by the governance `ModuleAccount` itself. Modules +such as `x/upgrade`, that want to allow certain messages to be executed by governance +only should add a whitelist within the respective msg server, granting the governance +module the right to execute the message once a quorum has been reached. The governance +module uses the `MsgServiceRouter` to check that these messages are correctly constructed +and have a respective path to execute on but do not perform a full validity check. +### Deposit + +To prevent spam, proposals must be submitted with a deposit in the coins defined by the equation `luncMinDepositAmountBasedOnUusd` = `MinUusdDeposit` / real-time price of LUNC at the time of proposal submission. +```keeper reference +github.com/classic-terra/core/v3/custom/gov/keeper/proposal.go#L136-L149 +``` +The value of `luncMinDepositAmountBasedOnUusd` will be stored in KVStores, using a key defined as `UUSDMinKeyPrefix|proposalID`, where the proposal ID is appended to the prefix, represented as a single byte. +```types reference +github.com/classic-terra/core/v3/custom/gov/types/keys.go#L20-L22 +``` + +When a proposal is submitted, it has to be accompanied with a deposit that must be +strictly positive, but can be inferior to `luncMinDepositAmountBasedOnUusd`. The submitter doesn't need +to pay for the entire deposit on their own. The newly created proposal is stored in +an *inactive proposal queue* and stays there until its deposit passes the `luncMinDepositAmountBasedOnUusd`. +Other token holders can increase the proposal's deposit by sending a `Deposit` +transaction. If a proposal doesn't pass the `luncMinDepositAmountBasedOnUusd` before the deposit end time +(the time when deposits are no longer accepted), the proposal will be destroyed: the +proposal will be removed from state and the deposit will be burned (see x/gov `EndBlocker`). +When a proposal deposit passes the `luncMinDepositAmountBasedOnUusd` threshold (even during the proposal +submission) before the deposit end time, the proposal will be moved into the +*active proposal queue* and the voting period will begin. + +The deposit is kept in escrow and held by the governance `ModuleAccount` until the +proposal is finalized (passed or rejected). +#### Deposit refund and burn + +When a proposal is finalized, the coins from the deposit are either refunded or burned +according to the final tally of the proposal: + +* If the proposal is approved or rejected but *not* vetoed, each deposit will be + automatically refunded to its respective depositor (transferred from the governance + `ModuleAccount`). +* When the proposal is vetoed with greater than 1/3, deposits will be burned from the + governance `ModuleAccount` and the proposal information along with its deposit + information will be removed from state. +* All refunded or burned deposits are removed from the state. Events are issued when + burning or refunding a deposit. +### Vote + +#### Voting period + +Once a proposal reaches `luncMinDepositAmountBasedOnUusd`, it immediately enters `Voting period`. We +define `Voting period` as the interval between the moment the vote opens and +the moment the vote closes. `Voting period` should always be shorter than +`Unbonding period` to prevent double voting. The initial value of +`Voting period` is 2 weeks. + +## Stores + +:::note +Stores are KVStores in the multi-store. The key to find the store is the first parameter in the list +::: +We will use one KVStore `Governance` to store five mappings: + +* A mapping from `proposalID|'proposal'` to `Proposal`. +* A mapping from `proposalID|'addresses'|address` to `Vote`. This mapping allows + us to query all addresses that voted on the proposal along with their vote by + doing a range query on `proposalID:addresses`. +* A mapping from `ParamsKey|'Params'` to `Params`. This map allows to query all + x/gov params. +* A mapping from `VotingPeriodProposalKeyPrefix|proposalID` to a single byte. This allows + us to know if a proposal is in the voting period or not with very low gas cost. +* A mapping from `UUSDMinKeyPrefix|proposalID` to a single byte. This allows us to determine the minimum amount of LUNC that a specific proposal must deposit to pass the deposit phase. + +For pseudocode purposes, here are the two function we will use to read or write in stores: + +* `load(StoreKey, Key)`: Retrieve item stored at key `Key` in store found at key `StoreKey` in the multistore +* `store(StoreKey, Key, value)`: Write value `Value` at key `Key` in store found at key `StoreKey` in the multistore + +## Parameters + +The governance module contains the following parameters: + +| Key | Type | Example | +|-------------------------------|------------------|-----------------------------------------| +| min_deposit | array (coins) | [{"denom":"uatom","amount":"10000000"}] | +| max_deposit_period | string (time ns) | "172800000000000" (17280s) | +| voting_period | string (time ns) | "172800000000000" (17280s) | +| quorum | string (dec) | "0.334000000000000000" | +| threshold | string (dec) | "0.500000000000000000" | +| veto | string (dec) | "0.334000000000000000" | +| burn_proposal_deposit_prevote | bool | false | +| burn_vote_quorum | bool | false | +| burn_vote_veto | bool | true | +| min_uusd_deposit | coins |{"denom":"uusd","amount":"500000"} | +**NOTE**: +Aiming to establish a clearer and more consistent minimum deposit requirement for governance proposals, the default value of `min_uusd_deposit` is currently set to 500 USD. However, this value can be updated by the community in the future. This approach allows the module to adapt to fluctuations in the value of LUNC over time, ensuring a consistent threshold for proposals. + +## Client + +### CLI + +A user can query and interact with the `gov` module using the CLI. +We have added two new commands + +##### MinimalDeposit +The `MinimalDeposit` command enables users to query the minimum LUNC deposit required for a specific proposal, calculated based on the UUSD value. + + +```bash +terrad q gov min-deposit [proposal-id] +``` +Example: + +```bash +terrad q gov min-deposit 1 cosmos1.. +``` + +##### CustomParams +The `CustomParams` command allows users to query the custom parameters of the module. + + +```bash +terrad q gov custom-params +``` +Example: + +```bash +terrad q gov custom-params +``` +## Future Improvements +We have successfully upgraded the chain by increasing the consensus version to 5. Moving forward, + should the community require updates related to these matters, the BLV Team will be available to + assist with the implementation process. + +BlvLas proposal: https://commonwealth.im/terra-luna-classic-lunc/discussion/24630-proposal-to-improve-the-gov-module-mechanism-by-blv-labs