diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5a30b442325a..32a71dd0ca27 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -15,6 +15,7 @@ module.exports = { collapsable: false, children: [ "/introduction/cosmos-hub", + "/introduction/tendermint-cosmos" "/introduction/tendermint", ] }, @@ -54,6 +55,18 @@ module.exports = { // "/specs/icts", // ] // }, + { + title: "SDK by Examples - Simple Governance", + collapsable: false, + children: [ + ["/sdk/sdk-by-examples/simple-governance/intro", "Intro"], + "/sdk/sdk-by-examples/simple-governance/setup-and-design", + "/sdk/sdk-by-examples/simple-governance/app-init", + "/sdk/sdk-by-examples/simple-governance/simple-gov-module", + "/sdk/sdk-by-examples/simple-governance/bridging-it-all", + "/sdk/sdk-by-examples/simple-governance/running-the-application" + ] + }, { title: "Lotion JS", collapsable: false, @@ -71,6 +84,13 @@ module.exports = { "/validators/validator-faq" ] }, + { + title: "Clients", + collapsable: false, + children: [ + ["/clients/service-providers", "Service Providers"] + ] + }, { title: "Resources", collapsable: false, diff --git a/docs/introduction/tendermint-cosmos.md b/docs/introduction/tendermint-cosmos.md index f48106a1d5d0..f7aeb7746ca4 100644 --- a/docs/introduction/tendermint-cosmos.md +++ b/docs/introduction/tendermint-cosmos.md @@ -1,4 +1,4 @@ -## Tendermint and Cosmos +# Tendermint and Cosmos Blockchains can be divided into three conceptual layers: diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-cli.md b/docs/sdk/sdk-by-examples/simple-governance/app-cli.md deleted file mode 100644 index 52590c62fe3f..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/app-cli.md +++ /dev/null @@ -1,23 +0,0 @@ -## Application CLI - -**File: [`cmd/simplegovcli/maing.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/cmd/simplegovcli/main.go)** - -To interact with our application, let us add the commands from the `simple_governance` module to our `simpleGov` application, as well as the pre-built SDK commands: - -```go -// cmd/simplegovcli/main.go -... - rootCmd.AddCommand( - client.GetCommands( - simplegovcmd.GetCmdQueryProposal("proposals", cdc), - simplegovcmd.GetCmdQueryProposals("proposals", cdc), - simplegovcmd.GetCmdQueryProposalVotes("proposals", cdc), - simplegovcmd.GetCmdQueryProposalVote("proposals", cdc), - )...) - rootCmd.AddCommand( - client.PostCommands( - simplegovcmd.PostCmdPropose(cdc), - simplegovcmd.PostCmdVote(cdc), - )...) -... -``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-codec.md b/docs/sdk/sdk-by-examples/simple-governance/app-codec.md deleted file mode 100644 index d994ba19c92f..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/app-codec.md +++ /dev/null @@ -1,21 +0,0 @@ -## Application codec - -**File: [`app/app.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/app/app.go)** - -Finally, we need to define the `MakeCodec()` function and register the concrete types and interface from the various modules. - -```go -func MakeCodec() *codec.Codec { - var cdc = codec.New() - codec.RegisterCrypto(cdc) // Register crypto. - sdk.RegisterCodec(cdc) // Register Msgs - bank.RegisterCodec(cdc) - simplestake.RegisterCodec(cdc) - simpleGov.RegisterCodec(cdc) - - // Register AppAccount - cdc.RegisterInterface((*auth.Account)(nil), nil) - cdc.RegisterConcrete(&types.AppAccount{}, "simpleGov/Account", nil) - return cdc -} -``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-commands.md b/docs/sdk/sdk-by-examples/simple-governance/app-commands.md deleted file mode 100644 index 4eb2f9221899..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/app-commands.md +++ /dev/null @@ -1,9 +0,0 @@ -## App commands - -We will need to add the newly created commands to our application. To do so, go to the `cmd` folder inside your root directory: - -```bash -// At root level of directory -cd cmd -``` -`simplegovd` is the folder that stores the command for running the server daemon, whereas `simplegovcli` defines the commands of your application. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-constructor.md b/docs/sdk/sdk-by-examples/simple-governance/app-constructor.md deleted file mode 100644 index 149e97277c0c..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/app-constructor.md +++ /dev/null @@ -1,61 +0,0 @@ -## Application constructor - -**File: [`app/app.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/app/app.go)** - -Now, we need to define the constructor for our application. - -```go -func NewSimpleGovApp(logger log.Logger, db dbm.DB) *SimpleGovApp -``` - -In this function, we will: - -- Create the codec - -```go -var cdc = MakeCodec() -``` - -- Instantiate our application. This includes creating the keys to access each of the substores. - -```go -// Create your application object. - var app = &SimpleGovApp{ - BaseApp: bam.NewBaseApp(appName, cdc, logger, db), - cdc: cdc, - capKeyMainStore: sdk.NewKVStoreKey("main"), - capKeyAccountStore: sdk.NewKVStoreKey("acc"), - capKeyStakingStore: sdk.NewKVStoreKey("stake"), - capKeySimpleGovStore: sdk.NewKVStoreKey("simpleGov"), - } -``` - -- Instantiate the keepers. Note that keepers generally need access to other module's keepers. In this case, make sure you only pass an instance of the keeper for the functionality that is needed. If a keeper only needs to read in another module's store, a read-only keeper should be passed to it. - -```go -app.bankKeeper = bank.NewBaseKeeper(app.accountMapper) -app.stakeKeeper = simplestake.NewKeeper(app.capKeyStakingStore, app.bankKeeper,app.RegisterCodespace(simplestake.DefaultCodespace)) -app.simpleGovKeeper = simpleGov.NewKeeper(app.capKeySimpleGovStore, app.bankKeeper, app.stakeKeeper, app.RegisterCodespace(simpleGov.DefaultCodespace)) -``` - -- Declare the handlers. - -```go -app.Router(). - AddRoute("bank", bank.NewHandler(app.bankKeeper)). - AddRoute("simplestake", simplestake.NewHandler(app.stakeKeeper)). - AddRoute("simpleGov", simpleGov.NewHandler(app.simpleGovKeeper)) -``` - -- Initialize the application. - -```go -// Initialize BaseApp. - app.MountStoresIAVL(app.capKeyMainStore, app.capKeyAccountStore, app.capKeySimpleGovStore, app.capKeyStakingStore) - app.SetAnteHandler(auth.NewAnteHandler(app.accountMapper, app.feeCollectionKeeper)) - err := app.LoadLatestVersion(app.capKeyMainStore) - if err != nil { - cmn.Exit(err.Error()) - } - return app -``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-init.md b/docs/sdk/sdk-by-examples/simple-governance/app-init.md index a71be2bed63f..2417bd88b638 100644 --- a/docs/sdk/sdk-by-examples/simple-governance/app-init.md +++ b/docs/sdk/sdk-by-examples/simple-governance/app-init.md @@ -1,4 +1,4 @@ -## Application initialization +# Application Initialization In the root of your fork of the SDK, create an `app` and `cmd` folder. In this folder, we will create the main file for our application, `app.go` and the repository to handle REST and CLI commands for our app. diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-makefile.md b/docs/sdk/sdk-by-examples/simple-governance/app-makefile.md deleted file mode 100644 index b7502d339f1e..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/app-makefile.md +++ /dev/null @@ -1,22 +0,0 @@ -## Makefile - -The [Makefile](https://en.wikipedia.org/wiki/Makefile) compiles the Go program by defining a set of rules with targets and recipes. We'll need to add our application commands to it: - -``` -// Makefile -build_examples: -ifeq ($(OS),Windows_NT) - ... - go build $(BUILD_FLAGS) -o build/simplegovd.exe ./examples/simpleGov/cmd/simplegovd - go build $(BUILD_FLAGS) -o build/simplegovcli.exe ./examples/simpleGov/cmd/simplegovcli -else - ... - go build $(BUILD_FLAGS) -o build/simplegovd ./examples/simpleGov/cmd/simplegovd - go build $(BUILD_FLAGS) -o build/simplegovcli ./examples/simpleGov/cmd/simplegovcli -endif -... -install_examples: - ... - go install $(BUILD_FLAGS) ./examples/simpleGov/cmd/simplegovd - go install $(BUILD_FLAGS) ./examples/simpleGov/cmd/simplegovcli -``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-rest.md b/docs/sdk/sdk-by-examples/simple-governance/app-rest.md deleted file mode 100644 index 828d52c858b1..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/app-rest.md +++ /dev/null @@ -1,57 +0,0 @@ -##### Rest server - -**File: [`cmd/simplegovd/main.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/cmd/simplegovd/main.go)** - -The `simplegovd` command will run the daemon server as a background process. First, let us create some `utils` functions: - -```go -// cmd/simplegovd/main.go -// SimpleGovAppInit initial parameters -var SimpleGovAppInit = server.AppInit{ - AppGenState: SimpleGovAppGenState, - AppGenTx: server.SimpleAppGenTx, -} - -// SimpleGovAppGenState sets up the app_state and appends the simpleGov app state -func SimpleGovAppGenState(cdc *codec.Codec, appGenTxs []json.RawMessage) (appState json.RawMessage, err error) { - appState, err = server.SimpleAppGenState(cdc, appGenTxs) - if err != nil { - return - } - return -} - -func newApp(logger log.Logger, db dbm.DB) abci.Application { - return app.NewSimpleGovApp(logger, db) -} - -func exportAppState(logger log.Logger, db dbm.DB) (json.RawMessage, error) { - dapp := app.NewSimpleGovApp(logger, db) - return dapp.ExportAppStateJSON() -} -``` - -Now, let us define the command for the daemon server within the `main()` function: - -```go -// cmd/simplegovd/main.go -func main() { - cdc := app.MakeCodec() - ctx := server.NewDefaultContext() - - rootCmd := &cobra.Command{ - Use: "simplegovd", - Short: "Simple Governance Daemon (server)", - PersistentPreRunE: server.PersistentPreRunEFn(ctx), - } - - server.AddCommands(ctx, cdc, rootCmd, SimpleGovAppInit, - server.ConstructAppCreator(newApp, "simplegov"), - server.ConstructAppExporter(exportAppState, "simplegov")) - - // prepare and add flags - rootDir := os.ExpandEnv("$HOME/.simplegovd") - executor := cli.PrepareBaseCmd(rootCmd, "BC", rootDir) - executor.Execute() -} -``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-structure.md b/docs/sdk/sdk-by-examples/simple-governance/app-structure.md deleted file mode 100644 index ce9ba5fef3d0..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/app-structure.md +++ /dev/null @@ -1,55 +0,0 @@ -## Application structure - -Now, that we have built all the pieces we need, it is time to integrate them into the application. Let us exit the `/x` director go back at the root of the SDK directory. - - -```bash -// At root level of directory -cd app -``` - -We are ready to create our simple governance application! - -*Note: You can check the full file (with comments!) [here](link)* - -The `app.go` file is the main file that defines your application. In it, you will declare all the modules you need, their keepers, handlers, stores, etc. Let us take a look at each section of this file to see how the application is constructed. - -Secondly, we need to define the name of our application. - -```go -const ( - appName = "SimpleGovApp" -) -``` - -Then, let us define the structure of our application. - -```go -// Extended ABCI application -type SimpleGovApp struct { - *bam.BaseApp - cdc *codec.Codec - - // keys to access the substores - capKeyMainStore *sdk.KVStoreKey - capKeyAccountStore *sdk.KVStoreKey - capKeyStakingStore *sdk.KVStoreKey - capKeySimpleGovStore *sdk.KVStoreKey - - // keepers - feeCollectionKeeper auth.FeeCollectionKeeper - bankKeeper bank.Keeper - stakeKeeper simplestake.Keeper - simpleGovKeeper simpleGov.Keeper - - // Manage getting and setting accounts - accountMapper auth.AccountMapper -} -``` - -- Each application builds on top of the `BaseApp` template, hence the pointer. -- `cdc` is the codec used in our application. -- Then come the keys to the stores we need in our application. For our simple governance app, we need 3 stores + the main store. -- Then come the keepers and mappers. - -Let us do a quick reminder so that it is clear why we need these stores and keepers. Our application is primarily based on the `simple_governance` module. However, we have established in section [Keepers for our app](module-keeper.md) that our module needs access to two other modules: the `bank` module and the `stake` module. We also need the `auth` module for basic account functionalities. Finally, we need access to the main multistore to declare the stores of each of the module we use. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/bridging-it-all.md b/docs/sdk/sdk-by-examples/simple-governance/bridging-it-all.md new file mode 100644 index 000000000000..aed6de85ef05 --- /dev/null +++ b/docs/sdk/sdk-by-examples/simple-governance/bridging-it-all.md @@ -0,0 +1,256 @@ +# From Module To Application + +## Application structure + +Now, that we have built all the pieces we need, it is time to integrate them into the application. Let us exit the `/x` director go back at the root of the SDK directory. + + +```bash +// At root level of directory +cd app +``` + +We are ready to create our simple governance application! + +*Note: You can check the full file (with comments!) [here](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/app/app.go)* + +The `app.go` file is the main file that defines your application. In it, you will declare all the modules you need, their keepers, handlers, stores, etc. Let us take a look at each section of this file to see how the application is constructed. + +Secondly, we need to define the name of our application. + +```go +const ( + appName = "SimpleGovApp" +) +``` + +Then, let us define the structure of our application. + +```go +// Extended ABCI application +type SimpleGovApp struct { + *bam.BaseApp + cdc *codec.Codec + + // keys to access the substores + capKeyMainStore *sdk.KVStoreKey + capKeyAccountStore *sdk.KVStoreKey + capKeyStakingStore *sdk.KVStoreKey + capKeySimpleGovStore *sdk.KVStoreKey + + // keepers + feeCollectionKeeper auth.FeeCollectionKeeper + bankKeeper bank.Keeper + stakeKeeper simplestake.Keeper + simpleGovKeeper simpleGov.Keeper + + // Manage getting and setting accounts + accountMapper auth.AccountMapper +} +``` + +- Each application builds on top of the `BaseApp` template, hence the pointer. +- `cdc` is the codec used in our application. +- Then come the keys to the stores we need in our application. For our simple governance app, we need 3 stores + the main store. +- Then come the keepers and mappers. + +Let us do a quick reminder so that it is clear why we need these stores and keepers. Our application is primarily based on the `simple_governance` module. However, we have established in section [Keepers for our app](module-keeper.md) that our module needs access to two other modules: the `bank` module and the `stake` module. We also need the `auth` module for basic account functionalities. Finally, we need access to the main multistore to declare the stores of each of the module we use. + +## CLI and Rest server + +We will need to add the newly created commands to our application. To do so, go to the `cmd` folder inside your root directory: + +```bash +// At root level of directory +cd cmd +``` +`simplegovd` is the folder that stores the command for running the server daemon, whereas `simplegovcli` defines the commands of your application. + +### Application CLI + +**File: [`cmd/simplegovcli/maing.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/cmd/simplegovcli/main.go)** + +To interact with our application, let us add the commands from the `simple_governance` module to our `simpleGov` application, as well as the pre-built SDK commands: + +```go +// cmd/simplegovcli/main.go +... + rootCmd.AddCommand( + client.GetCommands( + simplegovcmd.GetCmdQueryProposal("proposals", cdc), + simplegovcmd.GetCmdQueryProposals("proposals", cdc), + simplegovcmd.GetCmdQueryProposalVotes("proposals", cdc), + simplegovcmd.GetCmdQueryProposalVote("proposals", cdc), + )...) + rootCmd.AddCommand( + client.PostCommands( + simplegovcmd.PostCmdPropose(cdc), + simplegovcmd.PostCmdVote(cdc), + )...) +... +``` + +### Rest server + +**File: [`cmd/simplegovd/main.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/cmd/simplegovd/main.go)** + +The `simplegovd` command will run the daemon server as a background process. First, let us create some `utils` functions: + +```go +// cmd/simplegovd/main.go +// SimpleGovAppInit initial parameters +var SimpleGovAppInit = server.AppInit{ + AppGenState: SimpleGovAppGenState, + AppGenTx: server.SimpleAppGenTx, +} + +// SimpleGovAppGenState sets up the app_state and appends the simpleGov app state +func SimpleGovAppGenState(cdc *codec.Codec, appGenTxs []json.RawMessage) (appState json.RawMessage, err error) { + appState, err = server.SimpleAppGenState(cdc, appGenTxs) + if err != nil { + return + } + return +} + +func newApp(logger log.Logger, db dbm.DB) abci.Application { + return app.NewSimpleGovApp(logger, db) +} + +func exportAppState(logger log.Logger, db dbm.DB) (json.RawMessage, error) { + dapp := app.NewSimpleGovApp(logger, db) + return dapp.ExportAppStateJSON() +} +``` + +Now, let us define the command for the daemon server within the `main()` function: + +```go +// cmd/simplegovd/main.go +func main() { + cdc := app.MakeCodec() + ctx := server.NewDefaultContext() + + rootCmd := &cobra.Command{ + Use: "simplegovd", + Short: "Simple Governance Daemon (server)", + PersistentPreRunE: server.PersistentPreRunEFn(ctx), + } + + server.AddCommands(ctx, cdc, rootCmd, SimpleGovAppInit, + server.ConstructAppCreator(newApp, "simplegov"), + server.ConstructAppExporter(exportAppState, "simplegov")) + + // prepare and add flags + rootDir := os.ExpandEnv("$HOME/.simplegovd") + executor := cli.PrepareBaseCmd(rootCmd, "BC", rootDir) + executor.Execute() +} +``` + +## Makefile + +The [Makefile](https://en.wikipedia.org/wiki/Makefile) compiles the Go program by defining a set of rules with targets and recipes. We'll need to add our application commands to it: + +``` +// Makefile +build_examples: +ifeq ($(OS),Windows_NT) + ... + go build $(BUILD_FLAGS) -o build/simplegovd.exe ./examples/simpleGov/cmd/simplegovd + go build $(BUILD_FLAGS) -o build/simplegovcli.exe ./examples/simpleGov/cmd/simplegovcli +else + ... + go build $(BUILD_FLAGS) -o build/simplegovd ./examples/simpleGov/cmd/simplegovd + go build $(BUILD_FLAGS) -o build/simplegovcli ./examples/simpleGov/cmd/simplegovcli +endif +... +install_examples: + ... + go install $(BUILD_FLAGS) ./examples/simpleGov/cmd/simplegovd + go install $(BUILD_FLAGS) ./examples/simpleGov/cmd/simplegovcli +``` + +## Application constructor + +**File: [`app/app.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/app/app.go)** + +Now, we need to define the constructor for our application. + +```go +func NewSimpleGovApp(logger log.Logger, db dbm.DB) *SimpleGovApp +``` + +In this function, we will: + +- Create the codec + +```go +var cdc = MakeCodec() +``` + +- Instantiate our application. This includes creating the keys to access each of the substores. + +```go +// Create your application object. + var app = &SimpleGovApp{ + BaseApp: bam.NewBaseApp(appName, cdc, logger, db), + cdc: cdc, + capKeyMainStore: sdk.NewKVStoreKey("main"), + capKeyAccountStore: sdk.NewKVStoreKey("acc"), + capKeyStakingStore: sdk.NewKVStoreKey("stake"), + capKeySimpleGovStore: sdk.NewKVStoreKey("simpleGov"), + } +``` + +- Instantiate the keepers. Note that keepers generally need access to other module's keepers. In this case, make sure you only pass an instance of the keeper for the functionality that is needed. If a keeper only needs to read in another module's store, a read-only keeper should be passed to it. + +```go +app.bankKeeper = bank.NewBaseKeeper(app.accountMapper) +app.stakeKeeper = simplestake.NewKeeper(app.capKeyStakingStore, app.bankKeeper,app.RegisterCodespace(simplestake.DefaultCodespace)) +app.simpleGovKeeper = simpleGov.NewKeeper(app.capKeySimpleGovStore, app.bankKeeper, app.stakeKeeper, app.RegisterCodespace(simpleGov.DefaultCodespace)) +``` + +- Declare the handlers. + +```go +app.Router(). + AddRoute("bank", bank.NewHandler(app.bankKeeper)). + AddRoute("simplestake", simplestake.NewHandler(app.stakeKeeper)). + AddRoute("simpleGov", simpleGov.NewHandler(app.simpleGovKeeper)) +``` + +- Initialize the application. + +```go +// Initialize BaseApp. + app.MountStoresIAVL(app.capKeyMainStore, app.capKeyAccountStore, app.capKeySimpleGovStore, app.capKeyStakingStore) + app.SetAnteHandler(auth.NewAnteHandler(app.accountMapper, app.feeCollectionKeeper)) + err := app.LoadLatestVersion(app.capKeyMainStore) + if err != nil { + cmn.Exit(err.Error()) + } + return app +``` + +## Application codec + +**File: [`app/app.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/app/app.go)** + +Finally, we need to define the `MakeCodec()` function and register the concrete types and interface from the various modules. + +```go +func MakeCodec() *codec.Codec { + var cdc = codec.New() + codec.RegisterCrypto(cdc) // Register crypto. + sdk.RegisterCodec(cdc) // Register Msgs + bank.RegisterCodec(cdc) + simplestake.RegisterCodec(cdc) + simpleGov.RegisterCodec(cdc) + + // Register AppAccount + cdc.RegisterInterface((*auth.Account)(nil), nil) + cdc.RegisterConcrete(&types.AppAccount{}, "simpleGov/Account", nil) + return cdc +} +``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/cast-vote.md b/docs/sdk/sdk-by-examples/simple-governance/cast-vote.md deleted file mode 100644 index f16f2b4e6b0c..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/cast-vote.md +++ /dev/null @@ -1,19 +0,0 @@ -## Cast a vote to an existing proposal - -Let's cast a vote on the created proposal: - -```bash -simplegovcli vote --proposal-id=1 --option="No" -``` - -Get the value of the option from your casted vote : - -```bash -simplegovcli proposal-vote 1 -``` - -You can also check all the casted votes of a proposal: - -```bash -simplegovcli proposals-votes 1 -``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/intro.md b/docs/sdk/sdk-by-examples/simple-governance/intro.md index fe1c7639e945..9b3e417e04a2 100644 --- a/docs/sdk/sdk-by-examples/simple-governance/intro.md +++ b/docs/sdk/sdk-by-examples/simple-governance/intro.md @@ -6,45 +6,43 @@ Before getting in the bulk of the code, we will start by some introductory conte ## Table of contents: -### Introduction - Prerequsite reading +### Introduction - Prerequisite reading -- [Intro to Tendermint and Cosmos](../../../introduction/tendermint-cosmos.md) -- [Tendermint Core and ABCI](../../../introduction/tendermint.md) -- [Intro to Cosmos-SDK](../../overview.md) -- [Starting your own project](start.md) +- [Intro to Tendermint and Cosmos](/introduction/tendermint-cosmos.md) +- [Tendermint Core and ABCI](/introduction/tendermint.md) +- [Intro to Cosmos-SDK](/sdk/overview.md) -### Setup and design phase -- [Setup](setup.md) -- [Application design](app-design.md) +### [Setup and design](setup-and-design.md) + +- [Starting your own project](setup-and-design.md#get-started) +- [Setup](setup-and-design.md#setup) +- [Application design](setup-and-design.md#application-design) ### Implementation of the application **Important note: All the code for this application can be found [here](https://github.com/cosmos/cosmos-sdk/tree/fedekunze/module_tutorial/examples/simpleGov). Snippets will be provided throughout the tutorial, but please refer to the provided link for the full implementation details** - [Application initialization](app-init.md) -- Simple Governance module - + [Module initialization](module-init.md) - + [Types](module-types.md) - + [Keeper](module-keeper.md) - + [Handler](module-handler.md) - + [Wire](module-codec.md) - + [Errors](module-errors.md) - + Command-Line Interface and Rest API - * [Command-Line Interface](module-cli.md) - * [Rest API](module-rest.md) -- Bridging it all together - + [Application structure](app-structure.md) - + [Application CLI and Rest Server](app-commands.md) - * [Application CLI](app-cli.md) - * [Rest Server](app-rest.md) - + [Makefile](app-makefile.md) - + [Application constructor](app-constructor.md) - + [Application codec](app-codec.md) -- Running the application - + [Installation](run-install.md) - + [Submit a proposal](submit-proposal.md) - + [Cast a vote](cast-vote.md) +- [Simple Governance module](simple-gov-module.md) + + [Module initialization](simple-gov-module.md#module-initialization) + + [Types](simple-gov-module.md#types) + + [Keeper](simple-gov-module.md#keeper) + + [Handler](simple-gov-module.md#handler) + + [Wire](simple-gov-module.md#codec) + + [Errors](simple-gov-module.md#errors) + + [Command-Line Interface](simple-gov-module.md#command-line-interface) + + [Rest API](simple-gov-module.md#rest-api) +- [Bridging it all together](bridging-it-all.md) + + [Application structure](bridging-it-all.md#application-structure) + + [Application CLI and Rest Server](bridging-it-all.md#cli-and-rest-server) + + [Makefile](bridging-it-all.md#makefile) + + [Application constructor](bridging-it-all.md#application-constructor) + + [Application codec](bridging-it-all.md#application-codec) +- [Running the application](running-the-application.md) + + [Installation](running-the-application.md#installation) + + [Submit a proposal](running-the-application.md#submit-a-proposal) + + [Cast a vote](running-the-application.md#cast-a-vote) ## Useful links diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-cli.md b/docs/sdk/sdk-by-examples/simple-governance/module-cli.md deleted file mode 100644 index 4cdf331a9a04..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-cli.md +++ /dev/null @@ -1,33 +0,0 @@ -## Command-Line Interface (CLI) - -**File: [`x/simple_governance/client/cli/simple_governance.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/client/cli/simple_governance.go)** - -Go in the `cli` folder and create a `simple_governance.go` file. This is where we will define the commands for our module. - -The CLI builds on top of [Cobra](https://github.com/spf13/cobra). Here is the schema to build a command on top of Cobra: - -```go - // Declare flags - const( - Flag = "flag" - ... - ) - - // Main command function. One function for each command. - func Command(codec *codec.Codec) *cobra.Command { - // Create the command to return - command := &cobra.Command{ - Use: "actual command", - Short: "Short description", - Run: func(cmd *cobra.Command, args []string) error { - // Actual function to run when command is used - }, - } - - // Add flags to the command - command.Flags().(FlagNameConstant, , "") - - return command - } -``` - diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-codec.md b/docs/sdk/sdk-by-examples/simple-governance/module-codec.md deleted file mode 100644 index 68b03b93653b..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-codec.md +++ /dev/null @@ -1,13 +0,0 @@ -## Codec - -**File: [`x/simple_governance/codec.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/codec.go)** - -The `codec.go` file allows developers to register the concrete message types of their module into the codec. In our case, we have two messages to declare: - -```go -func RegisterCodec(cdc *codec.Codec) { - cdc.RegisterConcrete(SubmitProposalMsg{}, "simple_governance/SubmitProposalMsg", nil) - cdc.RegisterConcrete(VoteMsg{}, "simple_governance/VoteMsg", nil) -} -``` -Don't forget to call this function in `app.go` (see [Application - Bridging it all together](app-structure.md)) for more). \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-errors.md b/docs/sdk/sdk-by-examples/simple-governance/module-errors.md deleted file mode 100644 index 5597792a4259..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-errors.md +++ /dev/null @@ -1,7 +0,0 @@ -## Errors - -**File: [`x/simple_governance/errors.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/errors.go)** - -The `error.go` file allows us to define custom error messages for our module. Declaring errors should be relatively similar in all modules. You can look in the `error.go` file directly for a concrete example. The code is self-explanatory. - -Note that the errors of our module inherit from the `sdk.Error` interface and therefore possess the method `Result()`. This method is useful when there is an error in the `handler` and an error has to be returned in place of an actual result. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-handler.md b/docs/sdk/sdk-by-examples/simple-governance/module-handler.md deleted file mode 100644 index a879c31741d6..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-handler.md +++ /dev/null @@ -1,73 +0,0 @@ -## Handler - -**File: [`x/simple_governance/handler.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/handler.go)** - -### Constructor and core handlers - -Handlers implement the core logic of the state-machine. When a transaction is routed from the app to the module, it is run by the `handler` function. - -In practice, one `handler` will be implemented for each message of the module. In our case, we have two message types. We will therefore need two `handler` functions. We will also need a constructor function to route the message to the correct `handler`: - -```go -func NewHandler(k Keeper) sdk.Handler { - return func(ctx sdk.Context, msg sdk.Msg) sdk.Result { - switch msg := msg.(type) { - case SubmitProposalMsg: - return handleSubmitProposalMsg(ctx, k, msg) - case VoteMsg: - return handleVoteMsg(ctx, k, msg) - default: - errMsg := "Unrecognized gov Msg type: " + msg.Name() - return sdk.ErrUnknownRequest(errMsg).Result() - } - } -} -``` - -The messages are routed to the appropriate `handler` depending on their type. For our simple governance module, we only have two `handlers`, that correspond to our two message types. They have similar signatures: - -```go -func handleSubmitProposalMsg(ctx sdk.Context, k Keeper, msg SubmitProposalMsg) sdk.Result -``` - -Let us take a look at the parameters of this function: - -- The context `ctx` to access the stores. -- The keeper `k` allows the handler to read and write from the different stores, including the module's store (`SimpleGovernance` in our case) and all the stores from other modules that the keeper `k` has been granted an access to (`stake` and `bank` in our case). -- The message `msg` that holds all the information provided by the sender of the transaction. - -The function returns a `Result` that is returned to the application. It contains several useful information such as the amount of `Gas` for this transaction and wether the message was succesfully processed or not. At this point, we exit the boundaries of our simple governance module and go back to root application level. The `Result` will differ from application to application. You can check the `sdk.Result` type directly [here](https://github.com/cosmos/cosmos-sdk/blob/develop/types/result.go) for more info. - -### BeginBlocker and EndBlocker - -In contrast to most smart-contracts platform, it is possible to perform automatic (i.e. not triggered by a transaction sent by an end-user) execution of logic in Cosmos-SDK applications. - -This automatic execution of code takes place in the `BeginBlock` and `EndBlock` functions that are called at the beginning and at the end of every block. They are powerful tools, but it is important for application developers to be careful with them. For example, it is crutial that developers control the amount of computing that happens in these functions, as expensive computation could delay the block time, and never-ending loop freeze the chain altogether. - -`BeginBlock` and `EndBlock` are composable functions, meaning that each module can implement its own `BeginBlock` and `EndBlock` logic. When needed, `BeginBlock` and `EndBlock` logic is implemented in the module's `handler`. Here is the standard way to proceed for `EndBlock` (`BeginBlock` follows the exact same pattern): - -```go -func NewEndBlocker(k Keeper) sdk.EndBlocker { - return func(ctx sdk.Context, req abci.RequestEndBlock) (res abci.ResponseEndBlock) { - err := checkProposal(ctx, k) - if err != nil { - panic(err) - } - return - } -} -``` - -Do not forget that each module need to declare its `BeginBlock` and `EndBlock` constructors at application level. See the [Application - Bridging it all together](app-structure.md). - -For the purpose of our simple governance application, we will use `EndBlock` to automatically tally the results of the vote. Here are the different steps that will be performed: - -1. Get the oldest proposal from the `ProposalProcessingQueue` -2. Check if the `CurrentBlock` is the block at which the voting period for this proposal ends. If Yes, go to 3.. If no, exit. -3. Check if proposal is accepted or rejected. Update the proposal status. -4. Pop the proposal from the `ProposalProcessingQueue` and go back to 1. - -Let us perform a quick safety analysis on this process. -- The loop will not run forever because the number of proposals in `ProposalProcessingQueue` is finite -- The computation should not be too expensive because tallying of individual proposals is not expensive and the number of proposals is expected be relatively low. That is because proposals require a `Deposit` to be accepted. `MinDeposit` should be high enough so that we don't have too many `Proposals` in the queue. -- In the eventuality that the application becomes so successful that the `ProposalProcessingQueue` ends up containing so many proposals that the blockchain starts slowing down, the module should be modified to mitigate the situation. One clever way of doing it is to cap the number of iteration per individual `EndBlock` at `MaxIteration`. This way, tallying will be spread over many blocks if the number of proposals is too important and block time should remain stable. This would require to modify the current check `if (CurrentBlock == Proposal.SubmitBlock + VotingPeriod)` to `if (CurrentBlock > Proposal.SubmitBlock + VotingPeriod) AND (Proposal.Status == ProposalStatusActive)`. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-init.md b/docs/sdk/sdk-by-examples/simple-governance/module-init.md deleted file mode 100644 index 33bdfd5000ba..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-init.md +++ /dev/null @@ -1,31 +0,0 @@ -## Module initialization - -First, let us go into the module's folder and create a folder for our module. - -```bash -cd x/ -mkdir simple_governance -cd simple_governance -mkdir -p client/cli client/rest -touch client/cli/simple_governance.go client/rest/simple_governance.go errors.go handler.go handler_test.go keeper_keys.go keeper_test.go keeper.go test_common.go test_types.go types.go codec.go -``` - -Let us start by adding the files we will need. Your module's folder should look something like that: - -``` -x -└─── simple_governance - ├─── client - │ ├─── cli - │ │ └─── simple_governance.go - │ └─── rest - │ └─── simple_governance.go - ├─── errors.go - ├─── handler.go - ├─── keeper_keys.go - ├─── keeper.go - ├─── types.go - └─── codec.go -``` - -Let us go into the detail of each of these files. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-keeper.md b/docs/sdk/sdk-by-examples/simple-governance/module-keeper.md deleted file mode 100644 index 99c7cd566c3d..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-keeper.md +++ /dev/null @@ -1,96 +0,0 @@ -## Keeper - -**File: [`x/simple_governance/keeper.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/keeper.go)** - -### Short intro to keepers - -`Keepers` are a module abstraction that handle reading/writing to the module store. This is a practical implementation of the **Object Capability Model** for Cosmos. - - -As module developers, we have to define keepers to interact with our module's store(s) not only from within our module, but also from other modules. When another module wants to access one of our module's store(s), a keeper for this store has to be passed to it at the application level. In practice, it will look like that: - -```go -// in app.go - -// instanciate keepers -keeperA = moduleA.newKeeper(app.moduleAStoreKey) -keeperB = moduleB.newKeeper(app.moduleBStoreKey) - -// pass instance of keeperA to handler of module B -app.Router(). - AddRoute("moduleA", moduleA.NewHandler(keeperA)). - AddRoute("moduleB", moduleB.NewHandler(keeperB, keeperA)) // Here module B can access one of module A's store via the keeperA instance -``` - -`KeeperA` grants a set of capabilities to the handler of module B. When developing a module, it is good practice to think about the sensitivity of the different capabilities that can be granted through keepers. For example, some module may need to read and write to module A's main store, while others only need to read it. If a module has multiple stores, then some keepers could grant access to all of them, while others would only grant access to specific sub-stores. It is the job of the module developer to make sure it is easy for application developers to instanciate a keeper with the right capabilities. Of course, the handler of a module will most likely get an unrestricted instance of that module's keeper. - -### Store for our app - -Before we delve into the keeper itself, let us see what objects we need to store in our governance sub-store, and how to index them. - -- `Proposals` will be indexed by `'proposals'|`. -- `Votes` (`Yes`, `No`, `Abstain`) will be indexed by `'proposals'||'votes'|`. - -Notice the quote mark on `'proposals'` and `'votes'`. They indicate that these are constant keywords. So, for example, the option casted by voter with address `0x01` on proposal `0101` will be stored at index `'proposals'|0101|'votes'|0x01`. - -These keywords are used to faciliate range queries. Range queries (TODO: Link to formal spec) allow developer to query a subspace of the store, and return an iterator. They are made possible by the nice properties of the [IAVL+ tree](https://github.com/tendermint/iavl) that is used in the background. In practice, this means that it is possible to store and query a Key-Value pair in O(1), while still being able to iterate over a given subspace of Key-Value pairs. For example, we can query all the addresses that voted on a given proposal, along with their votes, by calling `rangeQuery(SimpleGovStore, )`. - -### Keepers for our app - -In our case, we only have one store to access, the `SimpleGov` store. We will need to set and get values inside this store via our keeper. However, these two actions do not have the same impact in terms of security. While there should no problem in granting read access to our store to other modules, write access is way more sensitive. So ideally application developers should be able to create either a governance mapper that can only get values from the store, or one that can both get and set values. To this end, we will introduce two keepers: `Keeper` and `KeeperRead`. When application developers create their application, they will be able to decide which of our module's keeper to use. - -Now, let us try to think about which keeper from **external** modules our module's keepers need access to. -Each proposal requires a deposit. This means our module needs to be able to both read and write to the module that handles tokens, which is the `bank` module. We also need to be able to determine the voting power of each voter based on their stake. To this end, we need read access to the store of the `staking` module. However, we don't need write access to this store. We should therefore indicate that in our module, and the application developer should be careful to only pass a read-only keeper of the `staking` module to our module's handler. - -With all that in mind, we can define the structure of our `Keeper`: - -```go - type Keeper struct { - SimpleGov sdk.StoreKey // Key to our module's store - cdc *codec.Codec // Codec to encore/decode structs - ck bank.Keeper // Needed to handle deposits. This module onlyl requires read/writes to Atom balance - sm stake.Keeper // Needed to compute voting power. This module only needs read access to the staking store. - codespace sdk.CodespaceType // Reserves space for error codes - } -``` - -And the structure of our `KeeperRead`: - -```go -type KeeperRead struct { - Keeper -} -``` - -`KeeperRead` will inherit all methods from `Keeper`, except those that we override. These will be the methods that perform writes to the store. - -### Functions and Methods - -The first function we have to create is the constructor. - -```go -func NewKeeper(SimpleGov sdk.StoreKey, ck bank.Keeper, sm stake.Keeper, codespace sdk.CodespaceType) Keeper -``` - -This function is called from the main [`app.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/app/app.go) file to instanciate a new `Keeper`. A similar function exits for `KeeperRead`. - -```go -func NewKeeperRead(SimpleGov sdk.StoreKey, ck bank.Keeper, sm stake.Keeper, codespace sdk.CodespaceType) KeeperRead -``` - -Depending on the needs of the application and its modules, either `Keeper`, `KeeperRead`, or both, will be instanciated at application level. - -*Note: Both the `Keeper` type name and `NewKeeper()` function's name are standard names used in every module. It is no requirement to follow this standard, but doing so can facilitate the life of application developers* - -Now, let us describe the methods we need for our module's `Keeper`. For the full implementation, please refer to `keeper.go`. - -- `GetProposal`: Get a `Proposal` given a `proposalID`. Proposals need to be decoded from `byte` before they can be read. -- `SetProposal`: Set a `Proposal` at index `'proposals'|`. Proposals need to be encoded to `byte` before they can be stored. -- `NewProposalID`: A function to generate a new unique `proposalID`. -- `GetVote`: Get a vote `Option` given a `proposalID` and a `voterAddress`. -- `SetVote`: Set a vote `Option` given a `proposalID` and a `voterAddress`. -- Proposal Queue methods: These methods implement a standard proposal queue to store `Proposals` on a First-In First-Out basis. It is used to tally the votes at the end of the voting period. - -The last thing that needs to be done is to override certain methods for the `KeeperRead` type. `KeeperRead` should not have write access to the stores. Therefore, we will override the methods `SetProposal()`, `SetVote()` and `NewProposalID()`, as well as `setProposalQueue()` from the Proposal Queue's methods. For `KeeperRead`, these methods will just throw an error. - -*Note: If you look at the code, you'll notice that the context `ctx` is a parameter of many of the methods. The context `ctx` provides useful information on the current state such as the current block height and allows the keeper `k` to access the `KVStore`. You can check all the methods of `ctx` [here](https://github.com/cosmos/cosmos-sdk/blob/develop/types/context.go#L144-L168)*. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-rest.md b/docs/sdk/sdk-by-examples/simple-governance/module-rest.md deleted file mode 100644 index 51758f2f41d4..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-rest.md +++ /dev/null @@ -1,32 +0,0 @@ -## Rest API - -**File: [`x/simple_governance/client/rest/simple_governance.goo`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/client/rest/simple_governance.go)** - -The Rest Server, also called [Light-Client Daemon (LCD)](https://github.com/cosmos/cosmos-sdk/tree/master/client/lcd), provides support for **HTTP queries**. - -________________________________________________________ - -USER INTERFACE <=======> REST SERVER <=======> FULL-NODE - -________________________________________________________ - -It allows end-users that do not want to run full-nodes themselves to interract with the chain. The LCD can be configured to perform **Light-Client verification** via the flag `--trust-node`, which can be set to `true` or `false`. - -- If *light-client verification* is enabled, the Rest Server acts as a light-client and needs to be run on the end-user's machine. It allows them to interract with the chain in a trustless way without having to store the whole chain locally. - -- If *light-client verification* is disabled, the Rest Server acts as a simple relayer for HTTP calls. In this setting, the Rest server needs not be run on the end-user's machine. Instead, it will probably be run by the same entity that operates the full-node the server connects to. This mode is useful if end-users trust the full-node operator and do not want to store anything locally. - -Now, let us define endpoints that will be available for users to query through HTTP requests. These endpoints will be defined in a `simple_governance.go` file stored in the `rest` folder. - -| Method | URL | Description | -|--------|---------------------------------|-------------------------------------------------------------| -| GET | /proposals | Range query to get all submitted proposals | -| POST | /proposals | Submit a new proposal | -| GET | /proposals/{id} | Returns a proposal given its ID | -| GET | /proposals/{id}/votes | Range query to get all the votes casted on a given proposal | -| POST | /proposals/{id}/votes | Cast a vote on a given proposal | -| GET | /proposals/{id}/votes/{address} | Returns the vote of a given address on a given proposal | - -It is the job of module developers to provide sensible endpoints so that front-end developers and service providers can properly interact with it. - -Additionaly, here is a [link](https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9) for REST APIs best practices. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/module-types.md b/docs/sdk/sdk-by-examples/simple-governance/module-types.md deleted file mode 100644 index 3b08448a62b1..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/module-types.md +++ /dev/null @@ -1,23 +0,0 @@ -## Types - -**File: [`x/simple_governance/types.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/types.go)** - -In this file, we define the custom types for our module. This includes the types from the [State](app-design.md#State) section and the custom message types defined in the [Messages](app-design#Messages) section. - -For each new type that is not a message, it is possible to add methods that make sense in the context of the application. In our case, we will implement an `updateTally` function to easily update the tally of a given proposal as vote messages come in. - -Messages are a bit different. They implement the `Message` interface defined in the SDK's `types` folder. Here are the methods you need to implement when you define a custom message type: - -- `Type()`: This function returns the name of our module's route. When messages are processed by the application, they are routed using the string returned by the `Type()` method. -- `GetSignBytes()`: Returns the byte representation of the message. It is used to sign the message. -- `GetSigners()`: Returns address(es) of the signer(s). -- `ValidateBasic()`: This function is used to discard obviously invalid messages. It is called at the beginning of `runTx()` in the baseapp file. If `ValidateBasic()` does not return `nil`, the app stops running the transaction. -- `Get()`: A basic getter, returns some property of the message. -- `String()`: Returns a human-readable version of the message - -For our simple governance messages, this means: - -- `Type()` will return `"simpleGov"` -- For `SubmitProposalMsg`, we need to make sure that the attributes are not empty and that the deposit is both valid and positive. Note that this is only basic validation, we will therefore not check in this method that the sender has sufficient funds to pay for the deposit -- For `VoteMsg`, we check that the address and option are valid and that the proposalID is not negative. -- As for other methods, less customization is required. You can check the code to see a standard way of implementing these. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/run-install.md b/docs/sdk/sdk-by-examples/simple-governance/run-install.md deleted file mode 100644 index dbbf203de68a..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/run-install.md +++ /dev/null @@ -1,18 +0,0 @@ -## Installation - -Once you have finallized your application, install it using `go get`. The following commands will install the pre-built modules and examples of the SDK as well as your `simpleGov` application: - -```bash -go get github.com//cosmos-sdk -cd $GOPATH/src/github.com//cosmos-sdk -make get_vendor_deps -make install -make install_examples -``` - -Check that the app is correctly installed by typing: - -```bash -simplegovcli -h -simplegovd -h -``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/running-the-application.md b/docs/sdk/sdk-by-examples/simple-governance/running-the-application.md new file mode 100644 index 000000000000..3a057054d40a --- /dev/null +++ b/docs/sdk/sdk-by-examples/simple-governance/running-the-application.md @@ -0,0 +1,77 @@ +# Running The Application + +## Installation + +Once you have finallized your application, install it using `go get`. The following commands will install the pre-built modules and examples of the SDK as well as your `simpleGov` application: + +```bash +go get github.com//cosmos-sdk +cd $GOPATH/src/github.com//cosmos-sdk +make get_vendor_deps +make install +make install_examples +``` + +Check that the app is correctly installed by typing: + +```bash +simplegovcli -h +simplegovd -h +``` + +## Submit a proposal + +Uuse the CLI to create a new proposal: + +```bash +simplegovcli propose --title="Voting Period update" --description="Should we change the proposal voting period to 3 weeks?" --deposit=300Atoms +``` + +Or, via a json file: + +```bash +simplegovcli propose --proposal="path/to/proposal.json" +``` + +Where proposal.json contains: + +```json +{ + "title": "Voting Period Update", + "description": "Should we change the proposal voting period to 3 weeks?", + "type": "Text", + "deposit": "300Atoms" +} +``` + +Get the details of your newly created proposal: + +```bash +simplegovcli proposal 1 +``` + +You can also check all the existing open proposals: + +```bash +simplegovcli proposals --active=true +``` + +## Cast a vote + +Let's cast a vote on the created proposal: + +```bash +simplegovcli vote --proposal-id=1 --option="No" +``` + +Get the value of the option from your casted vote : + +```bash +simplegovcli proposal-vote 1 +``` + +You can also check all the casted votes of a proposal: + +```bash +simplegovcli proposals-votes 1 +``` \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/app-design.md b/docs/sdk/sdk-by-examples/simple-governance/setup-and-design.md similarity index 82% rename from docs/sdk/sdk-by-examples/simple-governance/app-design.md rename to docs/sdk/sdk-by-examples/simple-governance/setup-and-design.md index fcc050979206..e979b3954e68 100644 --- a/docs/sdk/sdk-by-examples/simple-governance/app-design.md +++ b/docs/sdk/sdk-by-examples/simple-governance/setup-and-design.md @@ -1,3 +1,47 @@ +# Setup And Design + +## Get started + +To get started, you just have to follow these simple steps: + +1. Clone the [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk/tree/develop)repo +2. Code the modules needed by your application that do not already exist. +3. Create your app directory. In the app main file, import the module you need and instantiate the different stores. +4. Launch your blockchain. + +## Setup + +### Prerequisites + +- Have [go](https://golang.org/dl/) and [git](https://git-scm.com/downloads) installed +- Don't forget to set your `PATH` and `GOPATH` + +### Setup work environment + +Go to the [Cosmos-SDK repo](https://githum.com/cosmos/cosmos-sdk) and fork it. Then open a terminal and: + +```bash +cd $GOPATH/src/github.com/your_username +git clone github.com/your_username/cosmos-sdk +cd cosmos-sdk +``` + +Now we'll add the origin Cosmos-SDK as upstream in case some cool feature or module gets merged: + +```bash +git remote add upstream github.com/cosmos/cosmos-sdk +git fetch upstream +git rebase upstream/master +``` + +We will also create a branch dedicated to our module: + +```bash +git checkout -b my_new_application +``` + +We are all set! + ## Application design ### Application description diff --git a/docs/sdk/sdk-by-examples/simple-governance/setup.md b/docs/sdk/sdk-by-examples/simple-governance/setup.md deleted file mode 100644 index 963c7bf8122b..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/setup.md +++ /dev/null @@ -1,32 +0,0 @@ -## Setup - -### Prerequisites - -- Have [go](https://golang.org/dl/) and [git](https://git-scm.com/downloads) installed -- Don't forget to set your `PATH` and `GOPATH` - -### Setup work environment - -Go to the [Cosmos-SDK repo](https://githum.com/cosmos/cosmos-sdk) and fork it. Then open a terminal and: - -```bash -cd $GOPATH/src/github.com/your_username -git clone github.com/your_username/cosmos-sdk -cd cosmos-sdk -``` - -Now we'll add the origin Cosmos-SDK as upstream in case some cool feature or module gets merged: - -```bash -git remote add upstream github.com/cosmos/cosmos-sdk -git fetch upstream -git rebase upstream/master -``` - -We will also create a branch dedicated to our module: - -```bash -git checkout -b my_new_application -``` - -We are all set! \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/simple-gov-module.md b/docs/sdk/sdk-by-examples/simple-governance/simple-gov-module.md new file mode 100644 index 000000000000..92687deef5f0 --- /dev/null +++ b/docs/sdk/sdk-by-examples/simple-governance/simple-gov-module.md @@ -0,0 +1,316 @@ +# Simple Governance Module + +## Module initialization + +First, let us go into the module's folder and create a folder for our module. + +```bash +cd x/ +mkdir simple_governance +cd simple_governance +mkdir -p client/cli client/rest +touch client/cli/simple_governance.go client/rest/simple_governance.go errors.go handler.go handler_test.go keeper_keys.go keeper_test.go keeper.go test_common.go test_types.go types.go codec.go +``` + +Let us start by adding the files we will need. Your module's folder should look something like that: + +``` +x +└─── simple_governance + ├─── client + │ ├─── cli + │ │ └─── simple_governance.go + │ └─── rest + │ └─── simple_governance.go + ├─── errors.go + ├─── handler.go + ├─── keeper_keys.go + ├─── keeper.go + ├─── types.go + └─── codec.go +``` + +Let us go into the detail of each of these files. + +## Types + +**File: [`x/simple_governance/types.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/types.go)** + +In this file, we define the custom types for our module. This includes the types from the [State](app-design.md#State) section and the custom message types defined in the [Messages](app-design#Messages) section. + +For each new type that is not a message, it is possible to add methods that make sense in the context of the application. In our case, we will implement an `updateTally` function to easily update the tally of a given proposal as vote messages come in. + +Messages are a bit different. They implement the `Message` interface defined in the SDK's `types` folder. Here are the methods you need to implement when you define a custom message type: + +- `Type()`: This function returns the name of our module's route. When messages are processed by the application, they are routed using the string returned by the `Type()` method. +- `GetSignBytes()`: Returns the byte representation of the message. It is used to sign the message. +- `GetSigners()`: Returns address(es) of the signer(s). +- `ValidateBasic()`: This function is used to discard obviously invalid messages. It is called at the beginning of `runTx()` in the baseapp file. If `ValidateBasic()` does not return `nil`, the app stops running the transaction. +- `Get()`: A basic getter, returns some property of the message. +- `String()`: Returns a human-readable version of the message + +For our simple governance messages, this means: + +- `Type()` will return `"simpleGov"` +- For `SubmitProposalMsg`, we need to make sure that the attributes are not empty and that the deposit is both valid and positive. Note that this is only basic validation, we will therefore not check in this method that the sender has sufficient funds to pay for the deposit +- For `VoteMsg`, we check that the address and option are valid and that the proposalID is not negative. +- As for other methods, less customization is required. You can check the code to see a standard way of implementing these. + +## Keeper + +**File: [`x/simple_governance/keeper.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/keeper.go)** + +### Short intro to keepers + +`Keepers` are a module abstraction that handle reading/writing to the module store. This is a practical implementation of the **Object Capability Model** for Cosmos. + + +As module developers, we have to define keepers to interact with our module's store(s) not only from within our module, but also from other modules. When another module wants to access one of our module's store(s), a keeper for this store has to be passed to it at the application level. In practice, it will look like that: + +```go +// in app.go + +// instanciate keepers +keeperA = moduleA.newKeeper(app.moduleAStoreKey) +keeperB = moduleB.newKeeper(app.moduleBStoreKey) + +// pass instance of keeperA to handler of module B +app.Router(). + AddRoute("moduleA", moduleA.NewHandler(keeperA)). + AddRoute("moduleB", moduleB.NewHandler(keeperB, keeperA)) // Here module B can access one of module A's store via the keeperA instance +``` + +`KeeperA` grants a set of capabilities to the handler of module B. When developing a module, it is good practice to think about the sensitivity of the different capabilities that can be granted through keepers. For example, some module may need to read and write to module A's main store, while others only need to read it. If a module has multiple stores, then some keepers could grant access to all of them, while others would only grant access to specific sub-stores. It is the job of the module developer to make sure it is easy for application developers to instanciate a keeper with the right capabilities. Of course, the handler of a module will most likely get an unrestricted instance of that module's keeper. + +### Store for our app + +Before we delve into the keeper itself, let us see what objects we need to store in our governance sub-store, and how to index them. + +- `Proposals` will be indexed by `'proposals'|`. +- `Votes` (`Yes`, `No`, `Abstain`) will be indexed by `'proposals'||'votes'|`. + +Notice the quote mark on `'proposals'` and `'votes'`. They indicate that these are constant keywords. So, for example, the option casted by voter with address `0x01` on proposal `0101` will be stored at index `'proposals'|0101|'votes'|0x01`. + +These keywords are used to faciliate range queries. Range queries (TODO: Link to formal spec) allow developer to query a subspace of the store, and return an iterator. They are made possible by the nice properties of the [IAVL+ tree](https://github.com/tendermint/iavl) that is used in the background. In practice, this means that it is possible to store and query a Key-Value pair in O(1), while still being able to iterate over a given subspace of Key-Value pairs. For example, we can query all the addresses that voted on a given proposal, along with their votes, by calling `rangeQuery(SimpleGovStore, )`. + +### Keepers for our app + +In our case, we only have one store to access, the `SimpleGov` store. We will need to set and get values inside this store via our keeper. However, these two actions do not have the same impact in terms of security. While there should no problem in granting read access to our store to other modules, write access is way more sensitive. So ideally application developers should be able to create either a governance mapper that can only get values from the store, or one that can both get and set values. To this end, we will introduce two keepers: `Keeper` and `KeeperRead`. When application developers create their application, they will be able to decide which of our module's keeper to use. + +Now, let us try to think about which keeper from **external** modules our module's keepers need access to. +Each proposal requires a deposit. This means our module needs to be able to both read and write to the module that handles tokens, which is the `bank` module. We also need to be able to determine the voting power of each voter based on their stake. To this end, we need read access to the store of the `staking` module. However, we don't need write access to this store. We should therefore indicate that in our module, and the application developer should be careful to only pass a read-only keeper of the `staking` module to our module's handler. + +With all that in mind, we can define the structure of our `Keeper`: + +```go + type Keeper struct { + SimpleGov sdk.StoreKey // Key to our module's store + cdc *codec.Codec // Codec to encore/decode structs + ck bank.Keeper // Needed to handle deposits. This module onlyl requires read/writes to Atom balance + sm stake.Keeper // Needed to compute voting power. This module only needs read access to the staking store. + codespace sdk.CodespaceType // Reserves space for error codes + } +``` + +And the structure of our `KeeperRead`: + +```go +type KeeperRead struct { + Keeper +} +``` + +`KeeperRead` will inherit all methods from `Keeper`, except those that we override. These will be the methods that perform writes to the store. + +### Functions and Methods + +The first function we have to create is the constructor. + +```go +func NewKeeper(SimpleGov sdk.StoreKey, ck bank.Keeper, sm stake.Keeper, codespace sdk.CodespaceType) Keeper +``` + +This function is called from the main [`app.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/app/app.go) file to instanciate a new `Keeper`. A similar function exits for `KeeperRead`. + +```go +func NewKeeperRead(SimpleGov sdk.StoreKey, ck bank.Keeper, sm stake.Keeper, codespace sdk.CodespaceType) KeeperRead +``` + +Depending on the needs of the application and its modules, either `Keeper`, `KeeperRead`, or both, will be instanciated at application level. + +*Note: Both the `Keeper` type name and `NewKeeper()` function's name are standard names used in every module. It is no requirement to follow this standard, but doing so can facilitate the life of application developers* + +Now, let us describe the methods we need for our module's `Keeper`. For the full implementation, please refer to `keeper.go`. + +- `GetProposal`: Get a `Proposal` given a `proposalID`. Proposals need to be decoded from `byte` before they can be read. +- `SetProposal`: Set a `Proposal` at index `'proposals'|`. Proposals need to be encoded to `byte` before they can be stored. +- `NewProposalID`: A function to generate a new unique `proposalID`. +- `GetVote`: Get a vote `Option` given a `proposalID` and a `voterAddress`. +- `SetVote`: Set a vote `Option` given a `proposalID` and a `voterAddress`. +- Proposal Queue methods: These methods implement a standard proposal queue to store `Proposals` on a First-In First-Out basis. It is used to tally the votes at the end of the voting period. + +The last thing that needs to be done is to override certain methods for the `KeeperRead` type. `KeeperRead` should not have write access to the stores. Therefore, we will override the methods `SetProposal()`, `SetVote()` and `NewProposalID()`, as well as `setProposalQueue()` from the Proposal Queue's methods. For `KeeperRead`, these methods will just throw an error. + +*Note: If you look at the code, you'll notice that the context `ctx` is a parameter of many of the methods. The context `ctx` provides useful information on the current state such as the current block height and allows the keeper `k` to access the `KVStore`. You can check all the methods of `ctx` [here](https://github.com/cosmos/cosmos-sdk/blob/develop/types/context.go#L144-L168)*. + +## Handler + +**File: [`x/simple_governance/handler.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/handler.go)** + +### Constructor and core handlers + +Handlers implement the core logic of the state-machine. When a transaction is routed from the app to the module, it is run by the `handler` function. + +In practice, one `handler` will be implemented for each message of the module. In our case, we have two message types. We will therefore need two `handler` functions. We will also need a constructor function to route the message to the correct `handler`: + +```go +func NewHandler(k Keeper) sdk.Handler { + return func(ctx sdk.Context, msg sdk.Msg) sdk.Result { + switch msg := msg.(type) { + case SubmitProposalMsg: + return handleSubmitProposalMsg(ctx, k, msg) + case VoteMsg: + return handleVoteMsg(ctx, k, msg) + default: + errMsg := "Unrecognized gov Msg type: " + reflect.TypeOf(msg).Name() + return sdk.ErrUnknownRequest(errMsg).Result() + } + } +} +``` + +The messages are routed to the appropriate `handler` depending on their type. For our simple governance module, we only have two `handlers`, that correspond to our two message types. They have similar signatures: + +```go +func handleSubmitProposalMsg(ctx sdk.Context, k Keeper, msg SubmitProposalMsg) sdk.Result +``` + +Let us take a look at the parameters of this function: + +- The context `ctx` to access the stores. +- The keeper `k` allows the handler to read and write from the different stores, including the module's store (`SimpleGovernance` in our case) and all the stores from other modules that the keeper `k` has been granted an access to (`stake` and `bank` in our case). +- The message `msg` that holds all the information provided by the sender of the transaction. + +The function returns a `Result` that is returned to the application. It contains several useful information such as the amount of `Gas` for this transaction and wether the message was succesfully processed or not. At this point, we exit the boundaries of our simple governance module and go back to root application level. The `Result` will differ from application to application. You can check the `sdk.Result` type directly [here](https://github.com/cosmos/cosmos-sdk/blob/develop/types/result.go) for more info. + +### BeginBlocker and EndBlocker + +In contrast to most smart-contracts platform, it is possible to perform automatic (i.e. not triggered by a transaction sent by an end-user) execution of logic in Cosmos-SDK applications. + +This automatic execution of code takes place in the `BeginBlock` and `EndBlock` functions that are called at the beginning and at the end of every block. They are powerful tools, but it is important for application developers to be careful with them. For example, it is crutial that developers control the amount of computing that happens in these functions, as expensive computation could delay the block time, and never-ending loop freeze the chain altogether. + +`BeginBlock` and `EndBlock` are composable functions, meaning that each module can implement its own `BeginBlock` and `EndBlock` logic. When needed, `BeginBlock` and `EndBlock` logic is implemented in the module's `handler`. Here is the standard way to proceed for `EndBlock` (`BeginBlock` follows the exact same pattern): + +```go +func NewEndBlocker(k Keeper) sdk.EndBlocker { + return func(ctx sdk.Context, req abci.RequestEndBlock) (res abci.ResponseEndBlock) { + err := checkProposal(ctx, k) + if err != nil { + panic(err) + } + return + } +} +``` + +Do not forget that each module need to declare its `BeginBlock` and `EndBlock` constructors at application level. See the [Application - Bridging it all together](app-structure.md). + +For the purpose of our simple governance application, we will use `EndBlock` to automatically tally the results of the vote. Here are the different steps that will be performed: + +1. Get the oldest proposal from the `ProposalProcessingQueue` +2. Check if the `CurrentBlock` is the block at which the voting period for this proposal ends. If Yes, go to 3.. If no, exit. +3. Check if proposal is accepted or rejected. Update the proposal status. +4. Pop the proposal from the `ProposalProcessingQueue` and go back to 1. + +Let us perform a quick safety analysis on this process. +- The loop will not run forever because the number of proposals in `ProposalProcessingQueue` is finite +- The computation should not be too expensive because tallying of individual proposals is not expensive and the number of proposals is expected be relatively low. That is because proposals require a `Deposit` to be accepted. `MinDeposit` should be high enough so that we don't have too many `Proposals` in the queue. +- In the eventuality that the application becomes so successful that the `ProposalProcessingQueue` ends up containing so many proposals that the blockchain starts slowing down, the module should be modified to mitigate the situation. One clever way of doing it is to cap the number of iteration per individual `EndBlock` at `MaxIteration`. This way, tallying will be spread over many blocks if the number of proposals is too important and block time should remain stable. This would require to modify the current check `if (CurrentBlock == Proposal.SubmitBlock + VotingPeriod)` to `if (CurrentBlock > Proposal.SubmitBlock + VotingPeriod) AND (Proposal.Status == ProposalStatusActive)`. + +## Codec + +**File: [`x/simple_governance/codec.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/codec.go)** + +The `codec.go` file allows developers to register the concrete message types of their module into the codec. In our case, we have two messages to declare: + +```go +func RegisterCodec(cdc *codec.Codec) { + cdc.RegisterConcrete(SubmitProposalMsg{}, "simple_governance/SubmitProposalMsg", nil) + cdc.RegisterConcrete(VoteMsg{}, "simple_governance/VoteMsg", nil) +} +``` +Don't forget to call this function in `app.go` (see [Application - Bridging it all together](app-structure.md)) for more). + +## Errors + +**File: [`x/simple_governance/errors.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/errors.go)** + +The `error.go` file allows us to define custom error messages for our module. Declaring errors should be relatively similar in all modules. You can look in the `error.go` file directly for a concrete example. The code is self-explanatory. + +Note that the errors of our module inherit from the `sdk.Error` interface and therefore possess the method `Result()`. This method is useful when there is an error in the `handler` and an error has to be returned in place of an actual result. + +## Command-Line Interface + +**File: [`x/simple_governance/client/cli/simple_governance.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/client/cli/simple_governance.go)** + +Go in the `cli` folder and create a `simple_governance.go` file. This is where we will define the commands for our module. + +The CLI builds on top of [Cobra](https://github.com/spf13/cobra). Here is the schema to build a command on top of Cobra: + +```go + // Declare flags + const( + Flag = "flag" + ... + ) + + // Main command function. One function for each command. + func Command(codec *codec.Codec) *cobra.Command { + // Create the command to return + command := &cobra.Command{ + Use: "actual command", + Short: "Short description", + Run: func(cmd *cobra.Command, args []string) error { + // Actual function to run when command is used + }, + } + + // Add flags to the command + command.Flags().(FlagNameConstant, , "") + + return command + } +``` + +## Rest API + +**File: [`x/simple_governance/client/rest/simple_governance.goo`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/client/rest/simple_governance.go)** + +The Rest Server, also called [Light-Client Daemon (LCD)](https://github.com/cosmos/cosmos-sdk/tree/master/client/lcd), provides support for **HTTP queries**. + +________________________________________________________ + +USER INTERFACE <=======> REST SERVER <=======> FULL-NODE + +________________________________________________________ + +It allows end-users that do not want to run full-nodes themselves to interract with the chain. The LCD can be configured to perform **Light-Client verification** via the flag `--trust-node`, which can be set to `true` or `false`. + +- If *light-client verification* is enabled, the Rest Server acts as a light-client and needs to be run on the end-user's machine. It allows them to interract with the chain in a trustless way without having to store the whole chain locally. + +- If *light-client verification* is disabled, the Rest Server acts as a simple relayer for HTTP calls. In this setting, the Rest server needs not be run on the end-user's machine. Instead, it will probably be run by the same entity that operates the full-node the server connects to. This mode is useful if end-users trust the full-node operator and do not want to store anything locally. + +Now, let us define endpoints that will be available for users to query through HTTP requests. These endpoints will be defined in a `simple_governance.go` file stored in the `rest` folder. + +| Method | URL | Description | +|--------|---------------------------------|-------------------------------------------------------------| +| GET | /proposals | Range query to get all submitted proposals | +| POST | /proposals | Submit a new proposal | +| GET | /proposals/{id} | Returns a proposal given its ID | +| GET | /proposals/{id}/votes | Range query to get all the votes casted on a given proposal | +| POST | /proposals/{id}/votes | Cast a vote on a given proposal | +| GET | /proposals/{id}/votes/{address} | Returns the vote of a given address on a given proposal | + +It is the job of module developers to provide sensible endpoints so that front-end developers and service providers can properly interact with it. + +Additionaly, here is a [link](https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9) for REST APIs best practices. diff --git a/docs/sdk/sdk-by-examples/simple-governance/start.md b/docs/sdk/sdk-by-examples/simple-governance/start.md deleted file mode 100644 index 8461c84d98c7..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/start.md +++ /dev/null @@ -1,10 +0,0 @@ -## Starting your own project - -To get started, you just have to follow these simple steps: - -1. Clone the [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk/tree/develop)repo -2. Code the modules needed by your application that do not already exist. -3. Create your app directory. In the app main file, import the module you need and instantiate the different stores. -4. Launch your blockchain. - -Easy as pie! With the introduction over, let us delve into practice and learn how to code a SDK application with an example. \ No newline at end of file diff --git a/docs/sdk/sdk-by-examples/simple-governance/submit-proposal.md b/docs/sdk/sdk-by-examples/simple-governance/submit-proposal.md deleted file mode 100644 index 57571c151150..000000000000 --- a/docs/sdk/sdk-by-examples/simple-governance/submit-proposal.md +++ /dev/null @@ -1,36 +0,0 @@ -## Submit a proposal - -Uuse the CLI to create a new proposal: - -```bash -simplegovcli propose --title="Voting Period update" --description="Should we change the proposal voting period to 3 weeks?" --deposit=300Atoms -``` - -Or, via a json file: - -```bash -simplegovcli propose --proposal="path/to/proposal.json" -``` - -Where proposal.json contains: - -```json -{ - "title": "Voting Period Update", - "description": "Should we change the proposal voting period to 3 weeks?", - "type": "Text", - "deposit": "300Atoms" -} -``` - -Get the details of your newly created proposal: - -```bash -simplegovcli proposal 1 -``` - -You can also check all the existing open proposals: - -```bash -simplegovcli proposals --active=true -``` \ No newline at end of file