certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge PR #5604: docs: minor doc formatting & touchup of the scaffold section

This commit is contained in:
Marko 2020-02-04 19:16:56 +01:00 committed by GitHub
parent 5412725b35
commit e1517e7a1d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 132 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/using-the-sdk/quick-start.md
View File

@ -5,7 +5,7 @@ This guide serves as a practical introduction to building blockchains with the C
## 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
@ -30,41 +30,18 @@ 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>
```
There are multiple levels of apps to choose from, they can be found [here](https://github.com/cosmos/scaffold/blob/master/docs/app.md).
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.
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:
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)
- [`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 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.
Now, go into the application's folder. The structure should look like the following:
```
├── 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.
- `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.
@ -73,7 +50,7 @@ where:
## 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
@ -127,7 +104,7 @@ 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
@ -181,4 +158,3 @@ Congratulations on making it to the end of this short introduction guide! If you
- [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).

55
x/gov/spec/01_concepts.md
View File

@ -4,19 +4,19 @@ 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
- **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
@ -31,10 +31,11 @@ its unique `proposalID`.
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
- `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
- `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
@ -59,26 +60,27 @@ 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
_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
- _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.
@ -97,6 +99,7 @@ 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:
- `Yes`
- `No`
- `NoWithVeto`
@ -106,8 +109,8 @@ The initial option set includes the following options:
allows voters to signal that they do not intend to vote in favor or against the
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
@ -133,9 +136,9 @@ This condition exists so that the network can react quickly in case of urgency.
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
- 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.
@ -160,19 +163,19 @@ 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?*)
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
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
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.
*Note: Not clear how the flip is handled programmatically*
_Note: Not clear how the flip is handled programmatically_

20
x/gov/spec/02_state.md
View File

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

32
x/gov/spec/03_messages.md
View File

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

12
x/gov/spec/04_events.md
View File

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