Merge PR #5604: docs: minor doc formatting & touchup of the scaffold section
This commit is contained in:
Marko
GitHub
parent
5412725b35
commit
e1517e7a1d
|
|
@ -1,16 +1,16 @@
|
|||
# Quick Start
|
||||
|
||||
This guide serves as a practical introduction to building blockchains with the Cosmos SDK. It shows how to scaffold the code for a basic blockchain node, build and run it. Several important concepts of the Cosmos SDK are introduced along the way.
|
||||
This guide serves as a practical introduction to building blockchains with the Cosmos SDK. It shows how to scaffold the code for a basic blockchain node, build and run it. Several important concepts of the Cosmos SDK are introduced along the way.
|
||||
|
||||
## Setup
|
||||
|
||||
::: tip
|
||||
To follow this guide, you need to [install golang](https://golang.org/doc/install) and set [your $GOPATH environment variable](https://golang.org/doc/code.html#GOPATH)
|
||||
To follow this guide, you need to [install golang](https://golang.org/doc/install) and set [your \$GOPATH environment variable](https://golang.org/doc/code.html#GOPATH)
|
||||
:::
|
||||
|
||||
::: warning
|
||||
Make sure you are using the latest stable version of golang available on https://golang.org/dl/
|
||||
:::
|
||||
:::
|
||||
|
||||
First, download the [`scaffold`](https://github.com/cosmos/scaffold) tool:
|
||||
|
||||
|
|
@ -30,50 +30,27 @@ make
|
|||
To create a basic Cosmos SDK application, simply type in the following command:
|
||||
|
||||
```bash
|
||||
scaffold app lvl-1 <username|org> <repo>
|
||||
scaffold app <lvl> <username|org> <repo>
|
||||
```
|
||||
|
||||
where `username|org` is the name of your github/gitlab/atlassian username or organisation, and `repo` the name of the distant repository you would push your application too. These arguments are used to configure the imports so that people can easily download and install your application once (if) you upload it.
|
||||
There are multiple levels of apps to choose from, they can be found [here](https://github.com/cosmos/scaffold/blob/master/docs/app.md).
|
||||
|
||||
The command above creates a starter application in a new folder named after the `repo` argument. This application contains the [basic logic most SDK applications](../intro/sdk-app-architecture.md) need as well as a set of standard [modules](../building-modules/intro.md) already hooked up. These include:
|
||||
where `username|org` is the name of your github/gitlab/atlassian username or organisation, and `repo` the name of the distant repository you would push your application too. These arguments are used to configure the imports so that people can easily download and install your application once (if) you upload it.
|
||||
|
||||
- [`auth`](../../x/auth/spec/): Accounts, signatures and fees.
|
||||
- [`bank`](../../x/bank/spec/): Token transfers.
|
||||
- [`staking`](../../x/staking/spec/): Proof-of-Stake logic, which is a way of managing validator set changes in public decentralised networks. Also includes delegation logic.
|
||||
- [`slashing`](../../x/slashing/spec/): Slash validators that misebehave. Complementary to the `staking` module.
|
||||
- [`distribution`](../../x/distribution/spec/): Distribution of rewards and fees earned by participants in the Proof-of-Stake system (delegators and validators).
|
||||
- [`params`](../../x/params/spec/): Global parameter store of the application.
|
||||
- [`supply`](../../x/supply/spec/): Handles global token supply of the application. Enables modules to hold tokens.
|
||||
- [`genutil`](../../x/genutil) and [`genaccounts`](../../x/genaccounts): Utility modules to facilitate creation of genesis file.
|
||||
The command above creates a starter application in a new folder named after the `repo` argument. This application contains the [basic logic most SDK applications](../intro/sdk-app-architecture.md) need as well as a set of standard [modules](../building-modules/intro.md) already hooked up. You can find which level consists of which modules [here](https://github.com/cosmos/scaffold/blob/master/docs/app.md)
|
||||
|
||||
Now, go into the application's folder. The structure should look like the following:
|
||||
The structure of the generated app will look like similar to the [recommended folder structure](../building-modules/structure.md). Below you will find a simple break down of some of the files.
|
||||
|
||||
```
|
||||
├── app/
|
||||
│ ├── app.go
|
||||
│ └── export.go
|
||||
├── cmd/
|
||||
│ ├── acli/
|
||||
│ │ └── main.go
|
||||
│ ├── aud/
|
||||
│ │ └── main.go
|
||||
├── Makefile
|
||||
├── go.mod
|
||||
└── x/
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
- `app.go` is the [main file](../basics/app-anatomy.md#core-application-file) defining the application logic. This is where the state is intantiated and modules are declared. This is also where the Cosmos SDK is imported as a dependency to help build the application.
|
||||
- `export.go` is a helper file used to export the state of the application into a new genesis file. It is helpful when you want to upgrade your chain to a new (breaking) version.
|
||||
- `acli/main.go` builds the command-line interface for your blockchain application. It enables end-users to create transactions and query the chain for information.
|
||||
- `aud/main.go` builds the main [daemon client](../basics/app-anatomy.md#node-client) of the chain. It is used to run a full-node that will connect to peers and sync its local application state with the latest state of the network.
|
||||
- `go.mod` helps manage dependencies. The two main dependencies used are the Cosmos SDK to help build the application, and Tendermint to replicate it.
|
||||
- `x/` is the folder to place all the custom modules built specifically for the application. In general, most of the modules used in an application have already been built by third-party developers and only need to be imported in `app.go`. These modules do not need to be cloned into the application's `x/` folder. This is why the basic application shown above, which uses several modules, works despite having an empty `x/` folder.
|
||||
- `app.go` is the [main file](../basics/app-anatomy.md#core-application-file) defining the application logic. This is where the state is instantiated and modules are declared. This is also where the Cosmos SDK is imported as a dependency to help build the application.
|
||||
- `export.go` is a helper file used to export the state of the application into a new genesis file. It is helpful when you want to upgrade your chain to a new (breaking) version.
|
||||
- `acli/main.go` builds the command-line interface for your blockchain application. It enables end-users to create transactions and query the chain for information.
|
||||
- `aud/main.go` builds the main [daemon client](../basics/app-anatomy.md#node-client) of the chain. It is used to run a full-node that will connect to peers and sync its local application state with the latest state of the network.
|
||||
- `go.mod` helps manage dependencies. The two main dependencies used are the Cosmos SDK to help build the application, and Tendermint to replicate it.
|
||||
- `x/` is the folder to place all the custom modules built specifically for the application. In general, most of the modules used in an application have already been built by third-party developers and only need to be imported in `app.go`. These modules do not need to be cloned into the application's `x/` folder. This is why the basic application shown above, which uses several modules, works despite having an empty `x/` folder.
|
||||
|
||||
## Run your Blockchain
|
||||
|
||||
First, install the two main entrypoints of your blockchain, `aud` and `acli`:
|
||||
First, install the two main entry points of your blockchain, `aud` and `acli`:
|
||||
|
||||
```bash
|
||||
go mod tidy
|
||||
|
|
@ -93,17 +70,17 @@ Now that you have your daemon client `aud` and your command-line interface `acli
|
|||
aud init <node-moniker> --chain-id test
|
||||
```
|
||||
|
||||
The command above creates all the configuration files needed for your node to run, as well as a default genesis file, which defines the initial state of the network. Before starting the chain, you need to populate the state with at least one account. To do so, first create a new [account](../basics/accounts.md) named `validator` (feel free to choose another name):
|
||||
The command above creates all the configuration files needed for your node to run, as well as a default genesis file, which defines the initial state of the network. Before starting the chain, you need to populate the state with at least one account. To do so, first create a new [account](../basics/accounts.md) named `validator` (feel free to choose another name):
|
||||
|
||||
```bash
|
||||
acli keys add validator
|
||||
```
|
||||
```
|
||||
|
||||
Now that you have created a local account, go ahead and grant it `stake` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence:
|
||||
|
||||
```bash
|
||||
aud add-genesis-account $(acli keys show validator -a) 100000000stake
|
||||
```
|
||||
```
|
||||
|
||||
Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../intro/sdk-app-architecture.md#tendermint)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`:
|
||||
|
||||
|
|
@ -115,11 +92,11 @@ aud gentx --name validator --amount 100000stake
|
|||
aud collect-gentxs
|
||||
```
|
||||
|
||||
A `gentx` does three things:
|
||||
A `gentx` does three things:
|
||||
|
||||
1. Makes the `validator` account you created into a validator operator account (i.e. the account that controls the validator).
|
||||
2. Self-delegates the provided `amount` of staking tokens.
|
||||
3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `aud init` command above.
|
||||
2. Self-delegates the provided `amount` of staking tokens.
|
||||
3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `aud init` command above.
|
||||
|
||||
For more on `gentx`, use the following command:
|
||||
|
||||
|
|
@ -127,13 +104,13 @@ For more on `gentx`, use the following command:
|
|||
aud gentx --help
|
||||
```
|
||||
|
||||
Now that everyting is set up, you can finally start your node:
|
||||
Now that everything is set up, you can finally start your node:
|
||||
|
||||
```bash
|
||||
aud start
|
||||
```
|
||||
|
||||
You should see blocks come in.
|
||||
You should see blocks come in.
|
||||
|
||||
## Send Tokens and Increase Delegation
|
||||
|
||||
|
|
@ -149,7 +126,7 @@ You should see the current balance of the account you created, equal to the orig
|
|||
acli keys add receiver
|
||||
```
|
||||
|
||||
The command above creates a local key-pair that is not yet registered on the chain. An account is registered the first time it receives tokens from another account. Now, run the following command to send tokens to the second account:
|
||||
The command above creates a local key-pair that is not yet registered on the chain. An account is registered the first time it receives tokens from another account. Now, run the following command to send tokens to the second account:
|
||||
|
||||
```bash
|
||||
acli tx send $(acli keys show validator -a) $(acli keys show receiver -a) 1000stake --chain-id test
|
||||
|
|
@ -165,7 +142,7 @@ Finally, delegate some of the stake tokens sent to the `receiver` account to the
|
|||
|
||||
```bash
|
||||
acli tx staking delegate $(acli keys show validator --bech val -a) 500stake --from receiver --chain-id test
|
||||
```
|
||||
```
|
||||
|
||||
Try to query the total delegations to `validator`:
|
||||
|
||||
|
|
@ -173,12 +150,11 @@ Try to query the total delegations to `validator`:
|
|||
acli query staking delegations-to $(acli keys show validator --bech val -a) --chain-id test
|
||||
```
|
||||
|
||||
You should see two delegations, the first one made from the `gentx`, and the second one you just performed from the `receiver` account.
|
||||
You should see two delegations, the first one made from the `gentx`, and the second one you just performed from the `receiver` account.
|
||||
|
||||
## Next
|
||||
|
||||
Congratulations on making it to the end of this short introduction guide! If you want to learn more, check out the following resources:
|
||||
|
||||
- [How to build a full SDK application from scratch](https://tutorials.cosmos.network/nameservice/tutorial/00-intro.html).
|
||||
- [Read the Cosmos SDK Documentation](../intro/overview.md).
|
||||
|
||||
- [Read the Cosmos SDK Documentation](../intro/overview.md).
|
||||
|
|
|
|||
|
|
@ -4,41 +4,42 @@ order: 1
|
|||
|
||||
# Concepts
|
||||
|
||||
*Disclaimer: This is work in progress. Mechanisms are susceptible to change.*
|
||||
_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
|
||||
- **Proposal submission:** Proposal is submitted to the blockchain with a
|
||||
deposit.
|
||||
* **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is
|
||||
confirmed and vote opens. Bonded Atom holders can then send `TxGovVote`
|
||||
- **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is
|
||||
confirmed and vote opens. Bonded Atom holders can then send `TxGovVote`
|
||||
transactions to vote on the proposal.
|
||||
* If the proposal involves a software upgrade:
|
||||
* **Signal:** Validators start signaling that they are ready to switch to the
|
||||
- If the proposal involves a software upgrade:
|
||||
- **Signal:** Validators start signaling that they are ready to switch to the
|
||||
new version.
|
||||
* **Switch:** Once more than 75% of validators have signaled that they are
|
||||
- **Switch:** Once more than 75% of validators have signaled that they are
|
||||
ready to switch, their software automatically flips to the new version.
|
||||
|
||||
## Proposal submission
|
||||
|
||||
### Right to submit a proposal
|
||||
|
||||
Any Atom holder, whether bonded or unbonded, can submit proposals by sending a
|
||||
`TxGovProposal` transaction. Once a proposal is submitted, it is identified by
|
||||
Any Atom holder, whether bonded or unbonded, can submit proposals by sending a
|
||||
`TxGovProposal` transaction. Once a proposal is submitted, it is identified by
|
||||
its unique `proposalID`.
|
||||
|
||||
### Proposal types
|
||||
|
||||
In the initial version of the governance module, there are two types of
|
||||
In the initial version of the governance module, there are two types of
|
||||
proposal:
|
||||
* `PlainTextProposal` All the proposals that do not involve a modification of
|
||||
the source code go under this type. For example, an opinion poll would use a
|
||||
|
||||
- `PlainTextProposal` All the proposals that do not involve a modification of
|
||||
the source code go under this type. For example, an opinion poll would use a
|
||||
proposal of type `PlainTextProposal`.
|
||||
* `SoftwareUpgradeProposal`. If accepted, validators are expected to update
|
||||
their software in accordance with the proposal. They must do so by following
|
||||
a 2-steps process described in the [Software Upgrade](#software-upgrade)
|
||||
section below. Software upgrade roadmap may be discussed and agreed on via
|
||||
`PlainTextProposals`, but actual software upgrades must be performed via
|
||||
- `SoftwareUpgradeProposal`. If accepted, validators are expected to update
|
||||
their software in accordance with the proposal. They must do so by following
|
||||
a 2-steps process described in the [Software Upgrade](#software-upgrade)
|
||||
section below. Software upgrade roadmap may be discussed and agreed on via
|
||||
`PlainTextProposals`, but actual software upgrades must be performed via
|
||||
`SoftwareUpgradeProposals`.
|
||||
|
||||
Other modules may expand upon the governance module by implementing their own
|
||||
|
|
@ -59,85 +60,87 @@ Once the proposal's deposit reaches `MinDeposit`, it enters voting period. If pr
|
|||
|
||||
When a the a proposal 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 if it's rejected but _not_ vetoed, deposits will automatically be refunded to their respective depositor (transferred from the governance `ModuleAccount`).
|
||||
* When the proposal is vetoed with a supermajority, deposits be burned from the governance `ModuleAccount`.
|
||||
- If the proposal is approved or if it's rejected but _not_ vetoed, deposits will automatically be refunded to their respective depositor (transferred from the governance `ModuleAccount`).
|
||||
- When the proposal is vetoed with a supermajority, deposits be burned from the governance `ModuleAccount`.
|
||||
|
||||
## Vote
|
||||
|
||||
### Participants
|
||||
|
||||
*Participants* are users that have the right to vote on proposals. On the
|
||||
Cosmos Hub, participants are bonded Atom holders. Unbonded Atom holders and
|
||||
other users do not get the right to participate in governance. However, they
|
||||
_Participants_ are users that have the right to vote on proposals. On the
|
||||
Cosmos Hub, participants are bonded Atom holders. Unbonded Atom holders and
|
||||
other users do not get the right to participate in governance. However, they
|
||||
can submit and deposit on proposals.
|
||||
|
||||
Note that some *participants* can be forbidden to vote on a proposal under a
|
||||
Note that some _participants_ can be forbidden to vote on a proposal under a
|
||||
certain validator if:
|
||||
* *participant* bonded or unbonded Atoms to said validator after proposal
|
||||
entered voting period.
|
||||
* *participant* became validator after proposal entered voting period.
|
||||
|
||||
This does not prevent *participant* to vote with Atoms bonded to other
|
||||
validators. For example, if a *participant* bonded some Atoms to validator A
|
||||
before a proposal entered voting period and other Atoms to validator B after
|
||||
proposal entered voting period, only the vote under validator B will be
|
||||
- _participant_ bonded or unbonded Atoms to said validator after proposal
|
||||
entered voting period.
|
||||
- _participant_ became validator after proposal entered voting period.
|
||||
|
||||
This does not prevent _participant_ to vote with Atoms bonded to other
|
||||
validators. For example, if a _participant_ bonded some Atoms to validator A
|
||||
before a proposal entered voting period and other Atoms to validator B after
|
||||
proposal entered voting period, only the vote under validator B will be
|
||||
forbidden.
|
||||
|
||||
### Voting period
|
||||
|
||||
Once a proposal reaches `MinDeposit`, 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
|
||||
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.
|
||||
|
||||
### Option set
|
||||
|
||||
The option set of a proposal refers to the set of choices a participant can
|
||||
The option set of a proposal refers to the set of choices a participant can
|
||||
choose from when casting its vote.
|
||||
|
||||
The initial option set includes the following options:
|
||||
The initial option set includes the following options:
|
||||
|
||||
- `Yes`
|
||||
- `No`
|
||||
- `NoWithVeto`
|
||||
- `Abstain`
|
||||
- `NoWithVeto`
|
||||
- `Abstain`
|
||||
|
||||
`NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option
|
||||
`NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option
|
||||
allows voters to signal that they do not intend to vote in favor or against the
|
||||
proposal but accept the result of the vote.
|
||||
proposal but accept the result of the vote.
|
||||
|
||||
*Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’
|
||||
option that casts a `NoWithVeto` vote.*
|
||||
_Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’
|
||||
option that casts a `NoWithVeto` vote._
|
||||
|
||||
### Quorum
|
||||
### Quorum
|
||||
|
||||
Quorum is defined as the minimum percentage of voting power that needs to be
|
||||
casted on a proposal for the result to be valid.
|
||||
Quorum is defined as the minimum percentage of voting power that needs to be
|
||||
casted on a proposal for the result to be valid.
|
||||
|
||||
### Threshold
|
||||
|
||||
Threshold is defined as the minimum proportion of `Yes` votes (excluding
|
||||
Threshold is defined as the minimum proportion of `Yes` votes (excluding
|
||||
`Abstain` votes) for the proposal to be accepted.
|
||||
|
||||
Initially, the threshold is set at 50% with a possibility to veto if more than
|
||||
1/3rd of votes (excluding `Abstain` votes) are `NoWithVeto` votes. This means
|
||||
that proposals are accepted if the proportion of `Yes` votes (excluding
|
||||
`Abstain` votes) at the end of the voting period is superior to 50% and if the
|
||||
proportion of `NoWithVeto` votes is inferior to 1/3 (excluding `Abstain`
|
||||
1/3rd of votes (excluding `Abstain` votes) are `NoWithVeto` votes. This means
|
||||
that proposals are accepted if the proportion of `Yes` votes (excluding
|
||||
`Abstain` votes) at the end of the voting period is superior to 50% and if the
|
||||
proportion of `NoWithVeto` votes is inferior to 1/3 (excluding `Abstain`
|
||||
votes).
|
||||
|
||||
Proposals can be accepted before the end of the voting period if they meet a special condition. Namely, if the ratio of `Yes` votes to `InitTotalVotingPower`exceeds 2:3, the proposal will be immediately accepted, even if the `Voting period` is not finished. `InitTotalVotingPower` is the total voting power of all bonded Atom holders at the moment when the vote opens.
|
||||
Proposals can be accepted before the end of the voting period if they meet a special condition. Namely, if the ratio of `Yes` votes to `InitTotalVotingPower`exceeds 2:3, the proposal will be immediately accepted, even if the `Voting period` is not finished. `InitTotalVotingPower` is the total voting power of all bonded Atom holders at the moment when the vote opens.
|
||||
This condition exists so that the network can react quickly in case of urgency.
|
||||
|
||||
### Inheritance
|
||||
|
||||
If a delegator does not vote, it will inherit its validator vote.
|
||||
|
||||
* If the delegator votes before its validator, it will not inherit from the
|
||||
- If the delegator votes before its validator, it will not inherit from the
|
||||
validator's vote.
|
||||
* If the delegator votes after its validator, it will override its validator
|
||||
vote with its own. If the proposal is urgent, it is possible
|
||||
that the vote will close before delegators have a chance to react and
|
||||
- If the delegator votes after its validator, it will override its validator
|
||||
vote with its own. If the proposal is urgent, it is possible
|
||||
that the vote will close before delegators have a chance to react and
|
||||
override their validator's vote. This is not a problem, as proposals require more than 2/3rd of the total voting power to pass before the end of the voting period. If more than 2/3rd of validators collude, they can censor the votes of delegators anyway.
|
||||
|
||||
### Validator’s punishment for non-voting
|
||||
|
|
@ -150,29 +153,29 @@ Later, we may add permissioned keys that could only sign txs from certain module
|
|||
|
||||
## Software Upgrade
|
||||
|
||||
If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade
|
||||
their software to the new version that was voted. This process is divided in
|
||||
If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade
|
||||
their software to the new version that was voted. This process is divided in
|
||||
two steps.
|
||||
|
||||
### Signal
|
||||
|
||||
After a `SoftwareUpgradeProposal` is accepted, validators are expected to
|
||||
download and install the new version of the software while continuing to run
|
||||
the previous version. Once a validator has downloaded and installed the
|
||||
upgrade, it will start signaling to the network that it is ready to switch by
|
||||
including the proposal's `proposalID` in its *precommits*.(*Note: Confirmation
|
||||
that we want it in the precommit?*)
|
||||
After a `SoftwareUpgradeProposal` is accepted, validators are expected to
|
||||
download and install the new version of the software while continuing to run
|
||||
the previous version. Once a validator has downloaded and installed the
|
||||
upgrade, it will start signaling to the network that it is ready to switch by
|
||||
including the proposal's `proposalID` in its _precommits_.(_Note: Confirmation
|
||||
that we want it in the precommit?_)
|
||||
|
||||
Note: There is only one signal slot per *precommit*. If several
|
||||
`SoftwareUpgradeProposals` are accepted in a short timeframe, a pipeline will
|
||||
form and they will be implemented one after the other in the order that they
|
||||
Note: There is only one signal slot per _precommit_. If several
|
||||
`SoftwareUpgradeProposals` are accepted in a short timeframe, a pipeline will
|
||||
form and they will be implemented one after the other in the order that they
|
||||
were accepted.
|
||||
|
||||
### Switch
|
||||
|
||||
Once a block contains more than 2/3rd *precommits* where a common
|
||||
`SoftwareUpgradeProposal` is signaled, all the nodes (including validator
|
||||
Once a block contains more than 2/3rd _precommits_ where a common
|
||||
`SoftwareUpgradeProposal` is signaled, all the nodes (including validator
|
||||
nodes, non-validating full nodes and light-nodes) are expected to switch to the
|
||||
new version of the software.
|
||||
new version of the software.
|
||||
|
||||
*Note: Not clear how the flip is handled programmatically*
|
||||
_Note: Not clear how the flip is handled programmatically_
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ the governance process.
|
|||
type Proposal struct {
|
||||
Content // Proposal content interface
|
||||
|
||||
ProposalID uint64
|
||||
ProposalID uint64
|
||||
Status ProposalStatus // Status of the Proposal {Pending, Active, Passed, Rejected}
|
||||
FinalTallyResult TallyResult // Result of Tallies
|
||||
|
||||
|
|
@ -145,26 +145,26 @@ We also mention a method to update the tally for a given proposal:
|
|||
|
||||
## Stores
|
||||
|
||||
*Stores are KVStores in the multi-store. The key to find the store is the first
|
||||
parameter in the list*`
|
||||
_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 two 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 `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`.
|
||||
|
||||
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
|
||||
- `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
|
||||
|
||||
## Proposal Processing Queue
|
||||
|
||||
**Store:**
|
||||
* `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the
|
||||
|
||||
- `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the
|
||||
`ProposalIDs` of proposals that reached `MinDeposit`. During each `EndBlock`,
|
||||
all the proposals that have reached the end of their voting period are processed.
|
||||
To process a finished proposal, the application tallies the votes, computes the
|
||||
|
|
|
|||
|
|
@ -21,13 +21,14 @@ The `Content` of a `TxGovSubmitProposal` message must have an appropriate router
|
|||
set in the governance module.
|
||||
|
||||
**State modifications:**
|
||||
* Generate new `proposalID`
|
||||
* Create new `Proposal`
|
||||
* Initialise `Proposals` attributes
|
||||
* Decrease balance of sender by `InitialDeposit`
|
||||
* If `MinDeposit` is reached:
|
||||
* Push `proposalID` in `ProposalProcessingQueue`
|
||||
* Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount`
|
||||
|
||||
- Generate new `proposalID`
|
||||
- Create new `Proposal`
|
||||
- Initialise `Proposals` attributes
|
||||
- Decrease balance of sender by `InitialDeposit`
|
||||
- If `MinDeposit` is reached:
|
||||
- Push `proposalID` in `ProposalProcessingQueue`
|
||||
- Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount`
|
||||
|
||||
A `TxGovSubmitProposal` transaction can be handled according to the following
|
||||
pseudocode.
|
||||
|
|
@ -88,12 +89,13 @@ type TxGovDeposit struct {
|
|||
```
|
||||
|
||||
**State modifications:**
|
||||
* Decrease balance of sender by `deposit`
|
||||
* Add `deposit` of sender in `proposal.Deposits`
|
||||
* Increase `proposal.TotalDeposit` by sender's `deposit`
|
||||
* If `MinDeposit` is reached:
|
||||
* Push `proposalID` in `ProposalProcessingQueueEnd`
|
||||
* Transfer `Deposit` from the `proposer` to the governance `ModuleAccount`
|
||||
|
||||
- Decrease balance of sender by `deposit`
|
||||
- Add `deposit` of sender in `proposal.Deposits`
|
||||
- Increase `proposal.TotalDeposit` by sender's `deposit`
|
||||
- If `MinDeposit` is reached:
|
||||
- Push `proposalID` in `ProposalProcessingQueueEnd`
|
||||
- Transfer `Deposit` from the `proposer` to the governance `ModuleAccount`
|
||||
|
||||
A `TxGovDeposit` transaction has to go through a number of checks to be valid.
|
||||
These checks are outlined in the following pseudocode.
|
||||
|
|
@ -158,10 +160,10 @@ vote on the proposal.
|
|||
```
|
||||
|
||||
**State modifications:**
|
||||
* Record `Vote` of sender
|
||||
|
||||
*Note: Gas cost for this message has to take into account the future tallying of the vote in EndBlocker*
|
||||
- Record `Vote` of sender
|
||||
|
||||
_Note: Gas cost for this message has to take into account the future tallying of the vote in EndBlocker_
|
||||
|
||||
Next is a pseudocode proposal of the way `TxGovVote` transactions are
|
||||
handled:
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ The governance module emits the following events:
|
|||
## EndBlocker
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
|-------------------|-----------------|------------------|
|
||||
| ----------------- | --------------- | ---------------- |
|
||||
| inactive_proposal | proposal_id | {proposalID} |
|
||||
| inactive_proposal | proposal_result | {proposalResult} |
|
||||
| active_proposal | proposal_id | {proposalID} |
|
||||
|
|
@ -20,7 +20,7 @@ The governance module emits the following events:
|
|||
### MsgSubmitProposal
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
|---------------------|---------------------|-----------------|
|
||||
| ------------------- | ------------------- | --------------- |
|
||||
| submit_proposal | proposal_id | {proposalID} |
|
||||
| submit_proposal [0] | voting_period_start | {proposalID} |
|
||||
| proposal_deposit | amount | {depositAmount} |
|
||||
|
|
@ -29,12 +29,12 @@ The governance module emits the following events:
|
|||
| message | action | submit_proposal |
|
||||
| message | sender | {senderAddress} |
|
||||
|
||||
* [0] Event only emitted if the voting period starts during the submission.
|
||||
- [0] Event only emitted if the voting period starts during the submission.
|
||||
|
||||
### MsgVote
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
|---------------|---------------|-----------------|
|
||||
| ------------- | ------------- | --------------- |
|
||||
| proposal_vote | option | {voteOption} |
|
||||
| proposal_vote | proposal_id | {proposalID} |
|
||||
| message | module | governance |
|
||||
|
|
@ -44,7 +44,7 @@ The governance module emits the following events:
|
|||
### MsgDeposit
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
|----------------------|---------------------|-----------------|
|
||||
| -------------------- | ------------------- | --------------- |
|
||||
| proposal_deposit | amount | {depositAmount} |
|
||||
| proposal_deposit | proposal_id | {proposalID} |
|
||||
| proposal_deposit [0] | voting_period_start | {proposalID} |
|
||||
|
|
@ -52,4 +52,4 @@ The governance module emits the following events:
|
|||
| message | action | deposit |
|
||||
| message | sender | {senderAddress} |
|
||||
|
||||
* [0] Event only emitted if the voting period starts during the submission.
|
||||
- [0] Event only emitted if the voting period starts during the submission.
|
||||
|
|
|
|||
Loading…
Reference in New Issue