From e0b310d970a345eec01361207f710e389039e369 Mon Sep 17 00:00:00 2001 From: dongsam Date: Thu, 30 Sep 2021 20:03:30 +0900 Subject: [PATCH] docs: add signal proposal to reference and fix typo --- README.md | 2 +- docs/README.md | 1 + docs/Reference/README.md | 32 +++++++++ docs/Reference/proposals/01_proposal.md | 87 +++++++++++++++++++++++++ docs/Reference/proposals/README.md | 7 ++ 5 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 docs/Reference/README.md create mode 100644 docs/Reference/proposals/01_proposal.md create mode 100644 docs/Reference/proposals/README.md diff --git a/README.md b/README.md index fbb3ce8..f6dae0f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ A budget module is a Cosmos SDK module that implements budget functionality. It One use case is for Gravity DEX farming plan. Budget module can be used to create a budget plan that defines Cosmos Hub's FeeCollector module account where transaction gas fees and part of ATOM inflation are collected as budget source address and uses custom module account (created by budget creator) as collection address. Read [spec docs](./x/budget/spec/01_concepts.md) to get to know more about the module. -⚠ **Budger module v1 is in active development - see "master" branch for the latest update** ⚠ +⚠ **Budget module v1 is in active development - see "master" branch for the latest update** ⚠ ## Installation ### Requirements diff --git a/docs/README.md b/docs/README.md index 502fcfb..6bec7cb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ This approach outlines four specific use cases for documentation: * [Tutorials](./Tutorials/README.md) * [How-Tos](./How-To/README.md) * [Explanation](./Explanation/README.md) +* [Reference](./Reference/README.md) For further background please see [the ADR relating to the documentation structure](./Explanation/ADR/adr-002-docs-structure.md). diff --git a/docs/Reference/README.md b/docs/Reference/README.md new file mode 100644 index 0000000..a602b9d --- /dev/null +++ b/docs/Reference/README.md @@ -0,0 +1,32 @@ +# Reference Documentation + +How to use the budget module Reference documentation. + +- [Reference Documentation](#reference-documentation) + - [Introduction](#introduction) + - [Contributing](#contributing) + - [Layout](#layout) + - [Reference](#reference) + +## Introduction + +This section contains **Reference documentation** for budget module. [Reference Documentation](https://documentation.divio.com/reference/) is intended to be **information-oriented**. Content must allow the reader to easily navigate the content and use the content in conjunction with the code. + +## Contributing + +* The content must be dry, clear, and terse in style. +* All documentation should be written following [Google Documentation Best Practice](https://google.github.io/styleguide/docguide/best_practices.html) +* Generate as much documentation as possible from the code. +* Raise a PR for all documentation changes + +## Layout + +Reference Documentation will come in various forms: + +* [A record of governance proposals](./proposals) - all governance proposals reside related to budget module. + +## Reference + +- [Google Style Guide for Markdown](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md) +- [Write the Docs global community](https://www.writethedocs.org/) +- [Write the Docs Code of Conduct](https://www.writethedocs.org/code-of-conduct/#the-principles) \ No newline at end of file diff --git a/docs/Reference/proposals/01_proposal.md b/docs/Reference/proposals/01_proposal.md new file mode 100644 index 0000000..68e56f4 --- /dev/null +++ b/docs/Reference/proposals/01_proposal.md @@ -0,0 +1,87 @@ +# Signal Proposal + +Adopting the `Budget` and `Farming` Modules on Cosmos Hub + +By voting yes to this signal proposal, the voter agrees to adopt the Budget Module and Farming Module on Cosmos Hub to allow an incentivization mechanism for userbase growth on Cosmos Hub. The Tendermint team is currently building the two suggested modules, and when this signal proposal passes, the Budget Module and Farming Module will be included in a future Gaia upgrade when both modules are ready to be deployed. + +## 1. Introduction + +### 1.1 Modern Blockchain Incentivization Scheme: Farming + +Lots of modern blockchain ecosystems and decentralized applications incentivize their platform users by distributing coins based on user activities to bootstrap the growth of the userbase. Generally, the incentivization methodology is called "Farming." The source of the farming is various, but the most popular way is to utilize the native coins for current and future platform users. + +### 1.2. Cosmos Hub Context: Budget & Farming + +With pipelines of new features included on Cosmos Hub, including IBC, bridges, and Gravity DEX, Cosmos Hub needs to incentivize not only dPoS delegators but also platform users to accelerate user adoption. So we need to adopt two kinds of features as below: + +- Budget Module: To define and execute budget plans of ATOM inflation for multiple objectives + +- Farming Module: To define and distribute incentives for various utility users on Cosmos Hub + +## 2. Features + +### 2.1. Budget Module + +Budget Plan + +The Budget Module manages a list of budget plans which describe each proportional distribution of ATOM inflation to different destinations. The Budget Module distributes ATOM inflation according to the existing list of budget plans. + +Governance Process + +The list of budget plans can be added/removed/modified by a parameter governance proposal. + +### 2.2. Farming Module + +Farming Plan + +A farming plan is a definition of reward distribution plan with two types: + +- Public Farming Plan + + - Creation: A public farming plan can be created only by the governance process + + - Farming Pool Address: The source of a public farming plan is an existing module account + +- Private Farming Plan + + - Creation: A private farming plan can be created by anyone, submitting a transaction + + - Farming Pool Address: A new farming pool address is assigned to the farming plan. Anyone can fund this farming pool by sending coins to this address. + +Reward Distribution + +A farming plan defines a list of staking coin weights which are used to calculate the proportional distribution of rewards to each farmer. From the total reward distribution, each staking coin gets the weight proportion defined in the weight list. Then, each farmer who staked this coin receives the amount of corresponding rewards based on their proportion of the staked coin amount from the total staked amount. + +Reward Harvest + +A farmer can harvest (withdraw) accumulated rewards anytime he/she wants. Rewards are calculated based on a predefined epoch, therefore farmers can harvest rewards accumulated until the last epoch. + +### 2.3. Gravity DEX Liquidity Incentivization + +Staking Coins as Pool Coins + +Staking coins in a farming plan can be defined as a group of pool coins to distribute the farming plan rewards to pool coin holders. Because every liquidity provider on Gravity DEX gets pool coins as evidence of liquidity providing, this methodology naturally provides us the way to incentivize liquidity providing on Gravity DEX + +Governance Processes + +We need two kinds of governance processes to activate Gravity DEX liquidity incentivization + +- Budget: A governance process to decide + + - percentage of ATOM inflation to be used for Gravity DEX liquidity incentivization + + - time period of the budget plan created by this governance process + +- Farming: A governance process to decide + + - list and weights of staking coins (pool coins) to be incentivized + + - time period of the farming plan created by this governance process + +## 3. Detail Spec + +Detail description of the spec can be found below: + +- Budget Module: https://github.com/tendermint/budget/tree/master/x/budget/spec + +- Farming Module: https://github.com/tendermint/farming/tree/master/x/farming/spec \ No newline at end of file diff --git a/docs/Reference/proposals/README.md b/docs/Reference/proposals/README.md new file mode 100644 index 0000000..d2cfa36 --- /dev/null +++ b/docs/Reference/proposals/README.md @@ -0,0 +1,7 @@ +# Proposals Documentation + +Use this location to record all governance proposals related to budget module. + +## Contents + +- [Adopting the Budget and Farming Modules on Cosmos Hub](01_proposal.md) \ No newline at end of file