Skip to content

Commit

Permalink
Add simple gov example
Browse files Browse the repository at this point in the history
  • Loading branch information
gamarin2 committed Jul 23, 2018
1 parent 01ba6c3 commit d41b275
Show file tree
Hide file tree
Showing 13 changed files with 63 additions and 42 deletions.
2 changes: 2 additions & 0 deletions docs/sdk/sdk-by-examples/simple-governance/app-cli.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
## 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
Expand Down
2 changes: 2 additions & 0 deletions docs/sdk/sdk-by-examples/simple-governance/app-codec.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
## 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
Expand Down
2 changes: 2 additions & 0 deletions docs/sdk/sdk-by-examples/simple-governance/app-constructor.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
## 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
Expand Down
2 changes: 2 additions & 0 deletions docs/sdk/sdk-by-examples/simple-governance/app-rest.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
##### 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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,4 @@ type SimpleGovApp struct {
- 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](#keepers_for_our_app) 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.
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.
56 changes: 28 additions & 28 deletions docs/sdk/sdk-by-examples/simple-governance/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,45 +6,45 @@ Before getting in the bulk of the code, we will start by some introductory conte

### Introduction

- [Intro to Tendermint and Cosmos](./tendermint-cosmos.md)
- [Intro to Cosmos-SDK](./sdk-intro.md)
- [Tendermint Core and ABCI](./core-abci.md)
- [Architecture of a SDK-app](./sdk-architecture.md)
- [Starting your own project](./start.md)
- [Intro to Tendermint and Cosmos](tendermint-cosmos.md)
- [Intro to Cosmos-SDK](sdk-intro.md)
- [Tendermint Core and ABCI](core-abci.md)
- [Architecture of a SDK-app](sdk-architecture.md)
- [Starting your own project](start.md)

## #Setup and design phase

- [Setup](./setup.md)
- [Application design](./app-design.md)
- [Setup](setup.md)
- [Application design](app-design.md)

### Implementation of the application

**Important note: All the code for this application can be found [here](link). Snippets will be provided throughout the tutorial, but please refer to the provided link for the full implementation details**
**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)
- [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-wire.md)
+ [Errors](./module-errors.md)
+ [Module initialization](module-init.md)
+ [Types](module-types.md)
+ [Keeper](module-keeper.md)
+ [Handler](module-handler.md)
+ [Wire](module-wire.md)
+ [Errors](module-errors.md)
+ Command-Line Interface and Rest API
* [Command-Line Interface](./module-cli.md)
* [Rest API](./module-rest.md)
* [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)
+ [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)
- [Testnet](./testnet.md)
+ [Installation](run-install.md)
+ [Submit a proposal](submit-proposal.md)
+ [Cast a vote](cast-vote.md)
- [Testnet](testnet.md)

## Useful links

Expand Down
3 changes: 2 additions & 1 deletion docs/sdk/sdk-by-examples/simple-governance/module-cli.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
## 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:
Expand Down Expand Up @@ -29,4 +31,3 @@ The CLI builds on top of [Cobra](https://github.com/spf13/cobra). Here is the sc
}
```

For a detailed implementation of the commands of the simple governance module, click [here](../client/cli/simple_governance.go).
6 changes: 4 additions & 2 deletions docs/sdk/sdk-by-examples/simple-governance/module-errors.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
## Errors (`errors.go`)
## Errors

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](./error.go) file of our simple governance module for a concrete example. The code is self-explanatory.
**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.
6 changes: 4 additions & 2 deletions docs/sdk/sdk-by-examples/simple-governance/module-handler.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
## Handler (`handler.go`)
## 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

Expand Down Expand Up @@ -56,7 +58,7 @@ func NewEndBlocker(k Keeper) sdk.EndBlocker {
}
```

Do not forget that each module need to declare its `BeginBlock` and `EndBlock` constructors at application level. See the [Application - Bridging it all together](#application_-_bridging_it_all_together).
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:

Expand Down
8 changes: 5 additions & 3 deletions docs/sdk/sdk-by-examples/simple-governance/module-keeper.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
## Keeper (`keeper.go`)
## 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`](link) for Cosmos.
`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:
Expand Down Expand Up @@ -70,7 +72,7 @@ The first function we have to create is the constructor.
func NewKeeper(SimpleGov sdk.StoreKey, ck bank.Keeper, sm stake.Keeper, codespace sdk.CodespaceType) Keeper
```

This function is called from the main `app.go` file to instanciate a new `Keeper`. A similar function exits for `KeeperRead`.
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
Expand Down
4 changes: 3 additions & 1 deletion docs/sdk/sdk-by-examples/simple-governance/module-rest.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
## 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**.

________________________________________________________
Expand Down Expand Up @@ -27,4 +29,4 @@ Now, let us define endpoints that will be available for users to query through H

It is the job of module developers to provide sensible endpoints so that front-end developers and service providers can properly interact with it.

As for the actual in-code implementation of the endpoints for our simple governance module, you can take a look at [this file](../client/rest/simple_governance.go). Additionaly, here is a [link](https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9) for REST APIs best practices.
Additionaly, here is a [link](https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9) for REST APIs best practices.
6 changes: 4 additions & 2 deletions docs/sdk/sdk-by-examples/simple-governance/module-types.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
## Types (`types.go`)
## Types

In this file, we define the custom types for our module. This includes the types from the [State](#State) section and the custom message types defined in the [Transactions](#Transactions) section.
**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.

Expand Down
6 changes: 4 additions & 2 deletions docs/sdk/sdk-by-examples/simple-governance/module-wire.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
## Wire (`wire.go`)
## Wire

**File: [`x/simple_governance/wire.go`](https://github.com/cosmos/cosmos-sdk/blob/fedekunze/module_tutorial/examples/simpleGov/x/simple_governance/wire.go)**

The `wire.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:

Expand All @@ -8,4 +10,4 @@ func RegisterWire(cdc *wire.Codec) {
cdc.RegisterConcrete(VoteMsg{}, "simple_governance/VoteMsg", nil)
}
```
Don't forget to call this function in `app.go` (see [Application - Bridging it all together](#application_-_bridging_it_all_together) for more).
Don't forget to call this function in `app.go` (see [Application - Bridging it all together](app-structure.md)) for more).

0 comments on commit d41b275

Please sign in to comment.