Update docs for building modules (#9272)
* update example structure * update example structure * update module errors path * update paths and fix typos * update paths and fix typos * update example structure * address review comments
This commit is contained in:
Ryan Christoffersen
GitHub
parent
3e4d81c3d3
commit
b635ae2090
@ -14,9 +14,9 @@ order: 6
|
||||
|
||||
`BeginBlocker` and `EndBlocker` are a way for module developers to add automatic execution of logic to their module. This is a powerful tool that should be used carefully, as complex automatic functions can slow down or even halt the chain.
|
||||
|
||||
When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`AppModule` interface](./module-manager.md#appmodule). The `BeginBlock` and `EndBlock` methods of the interface implemented in `module.go` generally defer to `BeginBlocker` and `EndBlocker` methods respectively, which are usually implemented in a **`abci.go`** file.
|
||||
When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`AppModule` interface](./module-manager.md#appmodule). The `BeginBlock` and `EndBlock` methods of the interface implemented in `module.go` generally defer to `BeginBlocker` and `EndBlocker` methods respectively, which are usually implemented in `abci.go`.
|
||||
|
||||
The actual implementation of `BeginBlocker` and `EndBlocker` in `./abci.go` are very similar to that of a [`Msg` service](./msg-services.md):
|
||||
The actual implementation of `BeginBlocker` and `EndBlocker` in `abci.go` are very similar to that of a [`Msg` service](./msg-services.md):
|
||||
|
||||
- They generally use the [`keeper`](./keeper.md) and [`ctx`](../core/context.md) to retrieve information about the latest state.
|
||||
- If needed, they use the `keeper` and `ctx` to trigger state-transitions.
|
||||
|
||||
@ -13,7 +13,7 @@ execution context.
|
||||
|
||||
## Registration
|
||||
|
||||
Modules should define and register their custom errors in `x/{module}/types/errors.go`. Registration
|
||||
Modules should define and register their custom errors in `x/{module}/errors.go`. Registration
|
||||
of errors is handled via the `types/errors` package.
|
||||
|
||||
Example:
|
||||
|
||||
@ -29,7 +29,7 @@ The `DefaultGenesis()` method is a simple method that calls the constructor func
|
||||
|
||||
### `ValidateGenesis`
|
||||
|
||||
The `ValidateGenesis(genesisState GenesisState)` method is called to verify that the provided `genesisState` is correct. It should perform validity checks on each of the parameter listed in `GenesisState`. See an example from the `auth` module:
|
||||
The `ValidateGenesis(genesisState GenesisState)` method is called to verify that the provided `genesisState` is correct. It should perform validity checks on each of the parameters listed in `GenesisState`. See an example from the `auth` module:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/types/genesis.go#L57-L70
|
||||
|
||||
@ -41,9 +41,9 @@ Other than the methods related directly to `GenesisState`, module developers are
|
||||
|
||||
The `InitGenesis` method is executed during [`InitChain`](../core/baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./keeper.md) setter function on each parameter within the `GenesisState`.
|
||||
|
||||
The [module manager](./module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules, in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../basics/app-anatomy.md#constructor-function)
|
||||
The [module manager](./module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../basics/app-anatomy.md#constructor-function).
|
||||
|
||||
See an example of `InitGenesis` from the `auth` module
|
||||
See an example of `InitGenesis` from the `auth` module:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L13-L28
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ order: 1
|
||||
|
||||
# Introduction to SDK Modules
|
||||
|
||||
Modules define most of the logic of SDK applications. Developers compose module together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management. {synopsis}
|
||||
Modules define most of the logic of SDK applications. Developers compose modules together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
@ -13,11 +13,11 @@ Modules define most of the logic of SDK applications. Developers compose module
|
||||
|
||||
## Role of Modules in an SDK Application
|
||||
|
||||
The Cosmos SDK can be thought as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../core/baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../core/store.md#multistore) to persist state, a [server](../core/node.md) to form a full-node and [interfaces](./module-interfaces.md) to handle queries.
|
||||
The Cosmos SDK can be thought of as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../core/baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../core/store.md#multistore) to persist state, a [server](../core/node.md) to form a full-node and [interfaces](./module-interfaces.md) to handle queries.
|
||||
|
||||
On top of this core, the Cosmos SDK enables developers to build modules that implement the business logic of their application. In other words, SDK modules implement the bulk of the logic of applications, while the core does the wiring and enables modules to be composed together. The end goal is to build a robust ecosystem of open-source SDK modules, making it increasingly easier to build complex blockchain applications.
|
||||
|
||||
SDK Modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../core/store.md), as well as a subset of [message types](./messages-and-queries.md#messages). These messages are routed by one of the main component of SDK core, [`BaseApp`](../core/baseapp.md), to the [`Msg` service](./msg-services.md) of the module that define them.
|
||||
SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../core/store.md), as well as a subset of [message types](./messages-and-queries.md#messages). These messages are routed by one of the main components of SDK core, [`BaseApp`](../core/baseapp.md), to the [`Msg` service](./msg-services.md) of the module that defines them.
|
||||
|
||||
```
|
||||
+
|
||||
@ -71,8 +71,8 @@ As a result of this architecture, building an SDK application usually revolves a
|
||||
While there are no definitive guidelines for writing modules, here are some important design principles developers should keep in mind when building them:
|
||||
|
||||
- **Composability**: SDK applications are almost always composed of multiple modules. This means developers need to carefully consider the integration of their module not only with the core of the Cosmos SDK, but also with other modules. The former is achieved by following standard design patterns outlined [here](#main-components-of-sdk-modules), while the latter is achieved by properly exposing the store(s) of the module via the [`keeper`](./keeper.md).
|
||||
- **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concern enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../core/ocap.md) of the Cosmos SDK.
|
||||
- **Capabilities**: Most modules need to read and/or write to the store(s) of other modules. However, in an open-source environment, it is possible for some module to be malicious. That is why module developers need to carefully think not only about how their module interacts with other modules, but also about how to give access to the module's store(s). The Cosmos SDK takes a capabilities-oriented approach to inter-module security. This means that each store defined by a module is accessed by a `key`, which is held by the module's [`keeper`](./keeper.md). This `keeper` defines how to access the store(s) and under what conditions. Access to the module's store(s) is done by passing a reference to the module's `keeper`.
|
||||
- **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../core/ocap.md) of the Cosmos SDK.
|
||||
- **Capabilities**: Most modules need to read and/or write to the store(s) of other modules. However, in an open-source environment, it is possible for some modules to be malicious. That is why module developers need to carefully think not only about how their module interacts with other modules, but also about how to give access to the module's store(s). The Cosmos SDK takes a capabilities-oriented approach to inter-module security. This means that each store defined by a module is accessed by a `key`, which is held by the module's [`keeper`](./keeper.md). This `keeper` defines how to access the store(s) and under what conditions. Access to the module's store(s) is done by passing a reference to the module's `keeper`.
|
||||
|
||||
## Main Components of SDK Modules
|
||||
|
||||
|
||||
@ -12,11 +12,11 @@ An invariant is a property of the application that should always be true. In the
|
||||
|
||||
## Implementing `Invariant`s
|
||||
|
||||
An `Invariant` is a function that checks for a particular invariant within a module. Module `Invariant`s must follow the `Invariant`s type:
|
||||
An `Invariant` is a function that checks for a particular invariant within a module. Module `Invariant`s must follow the `Invariant` type:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L9
|
||||
|
||||
where the `string` return value is the invariant message, which can be used when printing logs, and the `bool` return value is the actual result of the invariant check.
|
||||
The `string` return value is the invariant message, which can be used when printing logs, and the `bool` return value is the actual result of the invariant check.
|
||||
|
||||
In practice, each module implements `Invariant`s in a `./keeper/invariants.go` file within the module's folder. The standard is to implement one `Invariant` function per logical grouping of invariants with the following model:
|
||||
|
||||
@ -49,7 +49,7 @@ func AllInvariants(k Keeper) sdk.Invariant {
|
||||
}
|
||||
```
|
||||
|
||||
Finally, module developers need to implement the `RegisterInvariants` method as part of the [`AppModule` interface](./module-manager.md#appmodule). Indeed, the `RegisterInvariants` method of the module, implemented in the `module.go` file, typically only defers the call to a `RegisterInvariants` method implemented in `internal/keeper/invariants.go`. The `RegisterInvariants` method registers a route for each `Invariant` function in the [`InvariantRegistry`](#invariant-registry):
|
||||
Finally, module developers need to implement the `RegisterInvariants` method as part of the [`AppModule` interface](./module-manager.md#appmodule). Indeed, the `RegisterInvariants` method of the module, implemented in the `module/module.go` file, typically only defers the call to a `RegisterInvariants` method implemented in the `keeper/invariants.go` file. The `RegisterInvariants` method registers a route for each `Invariant` function in the [`InvariantRegistry`](#invariant-registry):
|
||||
|
||||
|
||||
```go
|
||||
|
||||
@ -38,37 +38,37 @@ For example, here is the type definition of the `keeper` from the `staking` modu
|
||||
|
||||
Let us go through the different parameters:
|
||||
|
||||
- An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in a `types/expected_keepers.go` file within the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself.
|
||||
- An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in an `expected_keepers.go` file in the root of the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself.
|
||||
- `storeKey`s grant access to the store(s) of the [multistore](../core/store.md) managed by the module. They should always remain unexposed to external modules.
|
||||
- A [codec `cdc`](../core/encoding.md), used to marshall and unmarshall struct to/from `[]byte`, that can be any of `codec.BinaryCodec`,`codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces.
|
||||
- `cdc` is the [codec](../core/encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces.
|
||||
|
||||
Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../basics/app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require it.
|
||||
Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../basics/app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them.
|
||||
|
||||
## Implementing Methods
|
||||
|
||||
`Keeper`s primarily expose getter and setter methods for the store(s) managed by their module. These methods should remain as simple as possible and strictly be limited to getting or setting the requested value, as validity checks should have already been performed via the `ValidateBasic()` method of the [`message`](./messages-and-queries.md#messages) and the [`Msg` server](./msg-services.md) when `keeper`s' methods are called.
|
||||
|
||||
Typically, a *getter* method will present with the following signature
|
||||
Typically, a *getter* method will have the following signature
|
||||
|
||||
```go
|
||||
func (k Keeper) Get(ctx sdk.Context, key string) returnType
|
||||
```
|
||||
|
||||
and go through the following steps:
|
||||
and the method will go through the following steps:
|
||||
|
||||
1. Retrieve the appropriate store from the `ctx` using the `storeKey`. This is done through the `KVStore(storeKey sdk.StoreKey)` method of the `ctx`. Then it's prefered to use the `prefix.Store` to access only the desired limited subset of the store for convenience and safety.
|
||||
2. If it exists, get the `[]byte` value stored at location `[]byte(key)` using the `Get(key []byte)` method of the store.
|
||||
3. Unmarshall the retrieved value from `[]byte` to `returnType` using the codec `cdc`. Return the value.
|
||||
|
||||
Similarly, a *setter* method will present with the following signature
|
||||
Similarly, a *setter* method will have the following signature
|
||||
|
||||
```go
|
||||
func (k Keeper) Set(ctx sdk.Context, key string, value valueType)
|
||||
```
|
||||
|
||||
and go through the following steps:
|
||||
and the method will go through the following steps:
|
||||
|
||||
1. Retrieve the appropriate store from the `ctx` using the `storeKey`. This is done through the `KVStore(storeKey sdk.StoreKey)` method of the `ctx`. Then it's prefered to use the `prefix.Store` to access only the desired limited subset of the store for convenience and safety.
|
||||
1. Retrieve the appropriate store from the `ctx` using the `storeKey`. This is done through the `KVStore(storeKey sdk.StoreKey)` method of the `ctx`. It's preferred to use the `prefix.Store` to access only the desired limited subset of the store for convenience and safety.
|
||||
2. Marshal `value` to `[]byte` using the codec `cdc`.
|
||||
3. Set the encoded value in the store at location `key` using the `Set(key []byte, value []byte)` method of the store.
|
||||
|
||||
|
||||
@ -43,7 +43,7 @@ This way of defining messages is deprecated and using [`Msg` services](#msg-serv
|
||||
|
||||
Legacy `Msg`s can be defined as protobuf messages. The messages definition usually includes a list of parameters needed to process the message that will be provided by end-users when they want to create a new transaction containing said message.
|
||||
|
||||
The `Msg` is typically accompanied by a standard constructor function, that is called from one of the [module's interface](./module-interfaces.md). `message`s also need to implement the [`Msg`] interface:
|
||||
The `Msg` is typically accompanied by a standard constructor function, that is called from one of the [module's interface](./module-interfaces.md). `message`s also need to implement the `Msg` interface:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/4a1b2fba43b1052ca162b3a1e0b6db6db9c26656/types/tx_msg.go#L10-L33
|
||||
|
||||
|
||||
@ -12,11 +12,11 @@ This document details how to build CLI and REST interfaces for a module. Example
|
||||
|
||||
## CLI
|
||||
|
||||
One of the main interfaces for an application is the [command-line interface](../interfaces/cli.md). This entrypoint adds commands from the application's modules to let end-users create [**messages**](./messages-and-queries.md#messages) and [**queries**](./messages-and-queries.md#queries). The CLI files are typically found in the `./x/moduleName/client/cli` folder.
|
||||
One of the main interfaces for an application is the [command-line interface](../interfaces/cli.md). This entrypoint adds commands from the application's modules to let end-users create [**messages**](./messages-and-queries.md#messages) and [**queries**](./messages-and-queries.md#queries). The CLI files are typically found in the module's `./client/cli` folder.
|
||||
|
||||
### Transaction Commands
|
||||
|
||||
[Transactions](../core/transactions.md) are created by users to wrap messages that trigger state changes when they get included in a valid block. Transaction commands typically have their own `tx.go` file in the module `./x/moduleName/client/cli` folder. The commands are specified in getter functions and include the name of the command.
|
||||
[Transactions](../core/transactions.md) are created by users to wrap messages that trigger state changes when they get included in a valid block. Transaction commands typically have their own `tx.go` file in the module's `./client/cli` folder. The commands are specified in getter functions and include the name of the command.
|
||||
|
||||
Here is an example from the `auth` module:
|
||||
|
||||
@ -45,7 +45,7 @@ An application using this module likely adds `auth` module commands to its root
|
||||
|
||||
### Query Commands
|
||||
|
||||
[Queries](./messages-and-queries.md#queries) allow users to gather information about the application or network state; they are routed by the application and processed by the module in which they are defined. Query commands typically have their own `query.go` file in the module `x/moduleName/client/cli` folder. Like transaction commands, they are specified in getter functions. Here is an example of a query command from the `auth` module:
|
||||
[Queries](./messages-and-queries.md#queries) allow users to gather information about the application or network state; they are routed by the application and processed by the module in which they are defined. Query commands typically have their own `query.go` file in the module's `./client/cli` folder. Like transaction commands, they are specified in getter functions. Here is an example of a query command from the `auth` module:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/auth/client/cli/query.go#L76-L108
|
||||
|
||||
@ -53,7 +53,7 @@ This query returns the account at a given address. The getter function does the
|
||||
|
||||
- **Construct the command.** Read the [Cobra Documentation](https://godoc.org/github.com/spf13/cobra) and the [transaction command](#transaction-commands) example above for more information. The user must type `account` and provide the `address` they are querying for as the only argument.
|
||||
- **`RunE`.** The function should be specified as a `RunE` to allow for errors to be returned. This function encapsulates all of the logic to create a new query that is ready to be relayed to nodes.
|
||||
- The function should first initialize a new client [`Context`](../interfaces/query-lifecycle.md#context) as described in the [previous section](#transaction-commands)
|
||||
- The function should first initialize a new client [`Context`](../interfaces/query-lifecycle.md#context) as described in the [previous section](#transaction-commands).
|
||||
- If applicable, the `Context` is used to retrieve any parameters (e.g. the query originator's address to be used in the query) and marshal them with the query parameter type, in preparation to be relayed to a node. There are no `Context` parameters in this case because the query does not involve any information about the user.
|
||||
- A new `queryClient` should be initialized using `NewQueryClient(clientCtx)`, this method being generated from `query.proto`. Then it can be used to call the appropriate [query](./messages-and-queries.md#grpc-queries).
|
||||
- The `clientCtx.PrintProto` method is used to format a `proto.Message` object and print it back to the user.
|
||||
@ -65,7 +65,7 @@ Finally, the module also needs a `GetQueryCmd`, which aggregates all of the quer
|
||||
|
||||
[Flags](../interfaces/cli.md#flags) are entered by the user and allow for command customizations. Examples include the [fees](../basics/gas-fees.md) or gas prices users are willing to pay for their transactions.
|
||||
|
||||
The flags for a module are typically found in a `flags.go` file in the `./x/moduleName/client/cli` folder. Module developers can create a list of possible flags including the value type, default value, and a description displayed if the user uses a `help` command. In each transaction getter function, they can add flags to the commands and, optionally, mark flags as _required_ so that an error is thrown if the user does not provide values for them.
|
||||
The flags for a module are typically found in a `flags.go` file in the module's `./client/cli` folder. Module developers can create a list of possible flags including the value type, default value, and a description displayed if the user uses a `help` command. In each transaction getter function, they can add flags to the commands and, optionally, mark flags as _required_ so that an error is thrown if the user does not provide values for them.
|
||||
|
||||
For full details on flags, visit the [Cobra Documentation](https://github.com/spf13/cobra).
|
||||
|
||||
@ -97,7 +97,7 @@ Similarly, there is a `AddQueryFlagsToCmd(cmd *cobra.Command)` to add common fla
|
||||
|
||||
In addition to providing an ABCI query pathway, modules [custom queries](./messages-and-queries.md#grpc-queries) can provide a GRPC proxy server that routes requests in the GRPC protocol to ABCI query requests under the hood.
|
||||
|
||||
In order to do that, module should implement `RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)` on `AppModuleBasic` to wire the client gRPC requests to the correct handler inside the module.
|
||||
In order to do that, modules should implement `RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)` on `AppModuleBasic` to wire the client gRPC requests to the correct handler inside the module.
|
||||
|
||||
Here's an example from the `auth` module:
|
||||
|
||||
@ -105,7 +105,7 @@ Here's an example from the `auth` module:
|
||||
|
||||
## gRPC-gateway REST
|
||||
|
||||
Applications typically support web services that use HTTP requests (e.g. a web wallet like [Lunie.io](https://lunie.io). Thus, application developers can also use REST Routes to route HTTP requests to the application's modules; these routes will be used by service providers.
|
||||
Applications typically support web services that use HTTP requests (e.g. a web wallet like [Lunie.io](https://lunie.io)). Thus, application developers can also use REST Routes to route HTTP requests to the application's modules; these routes will be used by service providers.
|
||||
|
||||
[grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) translates REST calls into gRPC calls, which might be useful for clients that do not use gRPC.
|
||||
|
||||
@ -134,7 +134,7 @@ The SDK provides a command for generating [Swagger](https://swagger.io/) documen
|
||||
|
||||
Legacy REST endpoints will be deprecated. But developers may choose to keep using legacy REST endpoints for backward compatibility, although the recommended way is to use [gRPC](#grpc) and [gRPC-gateway](#grpc-gateway-rest).
|
||||
|
||||
With this implementation, module developers need to define the REST client by defining [routes](#register-routes) for all possible [requests](#request-types) and [handlers](#request-handlers) for each of them. It's up to the module developer how to organize the REST interface files; there is typically a `rest.go` file found in the module's `./x/moduleName/client/rest` folder.
|
||||
With this implementation, module developers need to define the REST client by defining [routes](#register-routes) for all possible [requests](#request-types) and [handlers](#request-handlers) for each of them. It's up to the module developer how to organize the REST interface files; there is typically a `rest.go` file found in the module's `./client/rest` folder.
|
||||
|
||||
To support HTTP requests, the module developer needs to define possible request types, how to handle them, and provide a way to register them with a provided router.
|
||||
|
||||
@ -158,9 +158,9 @@ The `BaseReq` includes basic information that every request needs to have, simil
|
||||
- `AccountNumber` is an identifier for the account.
|
||||
- `Sequence`is the value of a counter measuring how many transactions have been sent from the account. It is used to prevent replay attacks.
|
||||
- `TimeoutHeight` allows a transaction to be rejected if it's committed at a height greater than the timeout.
|
||||
- `Gas` refers to how much [gas](../basics/gas-fees.md), which represents computational resources, Tx consumes. Gas is dependent on the transaction and is not precisely calculated until execution, but can be estimated by providing auto as the value for `Gas`.
|
||||
- `GasAdjustment` can be used to scale gas up in order to avoid underestimating. For example, users can specify their gas adjustment as 1.5 to use 1.5 times the estimated gas.
|
||||
- `GasPrices` specifies how much the user is willing pay per unit of gas, which can be one or multiple denominations of tokens. For example, --gas-prices=0.025uatom, 0.025upho means the user is willing to pay 0.025uatom AND 0.025upho per unit of gas.
|
||||
- `Gas` refers to how much [gas](../basics/gas-fees.md), which represents computational resources, a transaction consumes. Gas is dependent on the transaction and is not precisely calculated until execution, but can be estimated by providing `auto` as the value for `Gas`.
|
||||
- `GasAdjustment` can be used to scale gas up in order to avoid underestimating. For example, users can specify their gas adjustment as `1.5` to use 1.5 times the estimated gas.
|
||||
- `GasPrices` specifies how much the user is willing pay per unit of gas, which can be one or multiple denominations of tokens. For example, `--gas-prices=0.025uatom, 0.025upho` means the user is willing to pay 0.025uatom AND 0.025upho per unit of gas.
|
||||
- `Fees` specifies how much in [fees](../basics/gas-fees.md) the user is willing to pay in total. Note that the user only needs to provide either `gas-prices` or `fees`, but not both, because they can be derived from each other.
|
||||
- `Simulate` instructs the application to ignore gas and simulate the transaction running without broadcasting.
|
||||
|
||||
@ -174,9 +174,9 @@ Here is an example of a request handler for the `bank` module `SendReq` request
|
||||
|
||||
The request handler can be broken down as follows:
|
||||
|
||||
- **Parse Request:** First, it tries to parse the argument `address` into a `AccountAddress`. Then, the request handler attempts to parse the request, and then run `Sanitize` and `ValidateBasic` on the underlying `BaseReq` to check the validity of the request. Finally, it attempts to parse `BaseReq.From` to the type `AccountAddress`.
|
||||
- **Message:** Then, a [message](./messages-and-queries.md#messages) of the type `MsgSend` (defined by the module developer to trigger the state changes for this transaction) is created from the values.
|
||||
- **Generate Transaction:** Finally, the HTTP `ResponseWriter`, client `Context`, request [`BaseReq`](../interfaces/rest.md#basereq), and message is passed to `WriteGeneratedTxResponse` to further process the request.
|
||||
- **Parse Request:** First, the request handler tries to parse the argument `address` into a `AccountAddress`. The request handler then attempts to parse the request, followed by running `Sanitize` and `ValidateBasic` on the underlying `BaseReq` to check the validity of the request. Finally, the request handler attempts to parse `BaseReq.From` to the type `AccountAddress`.
|
||||
- **Message:** After parsing the request, a [message](./messages-and-queries.md#messages) of type `MsgSend` is created from the values, which is defined by the module developer to trigger the state changes for this transaction.
|
||||
- **Generate Transaction:** Finally, the client `Context`, the HTTP `ResponseWriter`, the request's [`BaseReq`](../interfaces/rest.md#basereq), and the message are all passed to `WriteGeneratedTxResponse` to further process the request.
|
||||
|
||||
To read more about how a transaction is generated, visit the transactions documentation [here](../core/transactions.md#transaction-generation).
|
||||
|
||||
@ -184,7 +184,7 @@ To read more about how a transaction is generated, visit the transactions docume
|
||||
|
||||
The application CLI entrypoint will have a `RegisterRoutes` function in its `main.go` file, which calls the `registerRoutes` functions of each module utilized by the application. Module developers need to implement `registerRoutes` for their modules so that applications are able to route messages and queries to their corresponding handlers and queriers.
|
||||
|
||||
The router used by the SDK is [Gorilla Mux](https://github.com/gorilla/mux). The router is initialized with the Gorilla Mux `NewRouter()` function. Then, the router's `HandleFunc` function can then be used to route urls with the defined request handlers and the HTTP method (e.g. "POST", "GET") as a route matcher. It is recommended to prefix every route with the name of the module to avoid collisions with other modules that have the same query or transaction names.
|
||||
The router used by the SDK is [Gorilla Mux](https://github.com/gorilla/mux). The router is initialized with the Gorilla Mux `NewRouter()` function. The router's `HandleFunc` function can then be used to route urls with the defined request handlers and the HTTP method (e.g. "POST", "GET") as a route matcher. It is recommended to prefix every route with the name of the module to avoid collisions with other modules that have the same query or transaction names.
|
||||
|
||||
Here is a `registerRoutes` function with one query route example from the [nameservice tutorial](https://cosmos.network/docs/tutorial/rest.html):
|
||||
|
||||
|
||||
@ -56,11 +56,11 @@ Let us go through the two added methods:
|
||||
- `InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage)`: Initializes the subset of the state managed by the module. It is called at genesis (i.e. when the chain is first started).
|
||||
- `ExportGenesis(sdk.Context, codec.JSONCodec)`: Exports the latest subset of the state managed by the module to be used in a new genesis file. `ExportGenesis` is called for each module when a new chain is started from the state of an existing chain.
|
||||
|
||||
It does not have its own manager, and exists separately from [`AppModule`](#appmodule) only for modules that exist only to implement genesis functionalities, so that they can be managed without having to implement all of `AppModule`'s methods. If the module is not only used during genesis, `InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage)` and `ExportGenesis(sdk.Context, codec.JSONCodec)` will generally be defined as methods of the concrete type implementing hte `AppModule` interface.
|
||||
It does not have its own manager, and exists separately from [`AppModule`](#appmodule) only for modules that exist only to implement genesis functionalities, so that they can be managed without having to implement all of `AppModule`'s methods. If the module is not only used during genesis, `InitGenesis(sdk.Context, codec.JSONCodec, json.RawMessage)` and `ExportGenesis(sdk.Context, codec.JSONCodec)` will generally be defined as methods of the concrete type implementing the `AppModule` interface.
|
||||
|
||||
### `AppModule`
|
||||
|
||||
The `AppModule` interface defines the inter-dependent methods modules need to implement.
|
||||
The `AppModule` interface defines the inter-dependent methods that modules need to implement.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/b4cce159bcc6a32ac78245c6866dd87c73f3720d/types/module/module.go#L160-L182
|
||||
|
||||
@ -68,7 +68,7 @@ The `AppModule` interface defines the inter-dependent methods modules need to im
|
||||
|
||||
Let us go through the methods of `AppModule`:
|
||||
|
||||
- `RegisterInvariants(sdk.InvariantRegistry)`: Registers the [`invariants`](./invariants.md) of the module. If the invariants deviates from its predicted value, the [`InvariantRegistry`](./invariants.md#registry) triggers appropriate logic (most often the chain will be halted).
|
||||
- `RegisterInvariants(sdk.InvariantRegistry)`: Registers the [`invariants`](./invariants.md) of the module. If an invariant deviates from its predicted value, the [`InvariantRegistry`](./invariants.md#registry) triggers appropriate logic (most often the chain will be halted).
|
||||
- `Route()`: Returns the route for [`message`s](./messages-and-queries.md#messages) to be routed to the module by [`BaseApp`](../core/baseapp.md#message-routing).
|
||||
- `QuerierRoute()` (deprecated): Returns the name of the module's query route, for [`queries`](./messages-and-queries.md#queries) to be routes to the module by [`BaseApp`](../core/baseapp.md#query-routing).
|
||||
- `LegacyQuerierHandler(*codec.LegacyAmino)` (deprecated): Returns a [`querier`](./query-services.md#legacy-queriers) given the query `path`, in order to process the `query`.
|
||||
@ -81,7 +81,7 @@ Let us go through the methods of `AppModule`:
|
||||
|
||||
Typically, the various application module interfaces are implemented in a file called `module.go`, located in the module's folder (e.g. `./x/module/module.go`).
|
||||
|
||||
Almost every module needs to implement the `AppModuleBasic` and `AppModule` interfaces. If the module is only used for genesis, it will implement `AppModuleGenesis` instead of `AppModule`. The concrete type that implements the interface can add parameters that are required for the implementation of the various methods of the interface. For example, the `Route()` function often calls a `NewHandler(k keeper)` function defined in [`handler.go`](./msg-services.md#handler-type) and therefore needs to pass the module's [`keeper`](./keeper.md) as a parameter.
|
||||
Almost every module needs to implement the `AppModuleBasic` and `AppModule` interfaces. If the module is only used for genesis, it will implement `AppModuleGenesis` instead of `AppModule`. The concrete type that implements the interface can add parameters that are required for the implementation of the various methods of the interface. For example, the `Route()` function often calls a `NewMsgServerImpl(k keeper)` function defined in `keeper/msg_server.go` and therefore needs to pass the module's [`keeper`](./keeper.md) as a parameter.
|
||||
|
||||
```go
|
||||
// example
|
||||
|
||||
@ -54,7 +54,7 @@ This method takes care of marshaling the `res` parameter to protobuf and attachi
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/base/abci/v1beta1/abci.proto#L81-L95
|
||||
|
||||
This diagram shows a typical structure of an `Msg` Service, and how the message propagates through the module.
|
||||
This diagram shows a typical structure of a `Msg` Service, and how the message propagates through the module.
|
||||
|
||||
|
||||
|
||||
@ -72,7 +72,7 @@ Let us break it down:
|
||||
|
||||
- The [`Msg`](./messages-and-queries.md#messages) is the actual object being processed.
|
||||
- The [`Context`](../core/context.md) contains all the necessary information needed to process the `msg`, as well as a branch of the latest state. If the `msg` is successfully processed, the branched version of the state contained in the `ctx` will be written to the main state (branch).
|
||||
- The [`*Result`] returned to `BaseApp` contains (among other things) information on the execution of the `handler` and [events](../core/events.md).
|
||||
- The `*Result` returned to `BaseApp` contains (among other things) information on the execution of the `handler` and [events](../core/events.md).
|
||||
|
||||
Module `handler`s are typically implemented in a `./handler.go` file inside the module's folder. The [module manager](./module-manager.md) is used to add the module's `handler`s to the
|
||||
[application's `router`](../core/baseapp.md#message-routing) via the `Route()` method. Typically,
|
||||
|
||||
@ -11,73 +11,91 @@ This document outlines the recommended structure of Cosmos SDK modules. These id
|
||||
A typical Cosmos SDK module can be structured as follows:
|
||||
|
||||
```shell
|
||||
x/{module}
|
||||
proto
|
||||
└── {project_name}
|
||||
└── {module_name}
|
||||
└── {proto_version}
|
||||
├── {module_name}.proto
|
||||
├── event.proto
|
||||
├── genesis.proto
|
||||
├── query.proto
|
||||
└── tx.proto
|
||||
```
|
||||
|
||||
- `{module_name}.proto`: The module's common message type definitions.
|
||||
- `event.proto`: The module's message type definitions related to events.
|
||||
- `genesis.proto`: The module's message type definitions related to genesis state.
|
||||
- `query.proto`: The module's service and message type definitions related to the query service.
|
||||
- `tx.proto`: The module's service and message type definitions related to the message service.
|
||||
|
||||
```shell
|
||||
x/{module_name}
|
||||
├── client
|
||||
│ ├── cli
|
||||
│ │ ├── query.go
|
||||
│ │ └── tx.go
|
||||
│ └── rest
|
||||
│ ├── query.go
|
||||
│ └── tx.go
|
||||
│ ├── rest
|
||||
│ │ ├── query.go
|
||||
│ │ └── tx.go
|
||||
│ └── testutil
|
||||
│ ├── cli_test.go
|
||||
│ └── suite.go
|
||||
├── exported
|
||||
│ └── exported.go
|
||||
├── keeper
|
||||
│ ├── invariants.go
|
||||
│ ├── genesis.go
|
||||
│ ├── grpc_query.go
|
||||
│ ├── hooks.go
|
||||
│ ├── invariants.go
|
||||
│ ├── keeper.go
|
||||
│ ├── keys.go
|
||||
│ ├── msg_server.go
|
||||
│ ├── ...
|
||||
│ └── querier.go
|
||||
│ └── grpc_query.go
|
||||
├── types
|
||||
│ ├── codec.go
|
||||
│ ├── errors.go
|
||||
│ ├── events.go
|
||||
│ ├── expected_keepers.go
|
||||
│ ├── genesis.go
|
||||
│ ├── keys.go
|
||||
│ ├── msgs.go
|
||||
│ ├── params.go
|
||||
│ ├── types.proto
|
||||
│ ├── ...
|
||||
│ └── querier.go
|
||||
│ └── {module_name}.pb.go
|
||||
│ └── query.pb.go
|
||||
│ └── genesis.pb.go
|
||||
├── module
|
||||
│ └── module.go
|
||||
├── simulation
|
||||
│ ├── decoder.go
|
||||
│ ├── genesis.go
|
||||
│ ├── operations.go
|
||||
│ ├── params.go
|
||||
│ └── proposals.go
|
||||
│ └── params.go
|
||||
├── spec
|
||||
│ ├── 01_concepts.md
|
||||
│ ├── 02_state.md
|
||||
│ ├── 03_messages.md
|
||||
│ └── 04_events.md
|
||||
├── {module_name}.pb.go
|
||||
├── abci.go
|
||||
├── handler.go
|
||||
├── ...
|
||||
└── module.go
|
||||
├── codec.go
|
||||
├── errors.go
|
||||
├── events.go
|
||||
├── events.pb.go
|
||||
├── expected_keepers.go
|
||||
├── genesis.go
|
||||
├── genesis.pb.go
|
||||
├── keys.go
|
||||
├── msgs.go
|
||||
├── params.go
|
||||
├── query.pb.go
|
||||
└── tx.pb.go
|
||||
```
|
||||
|
||||
- `abci.go`: The module's `BeginBlocker` and `EndBlocker` implementations (if any).
|
||||
- `client/`: The module's CLI and REST client functionality implementation and
|
||||
testing.
|
||||
- `exported/`: The module's exported types -- typically type interfaces. If a module
|
||||
relies on other module keepers, it is expected to receive them as interface
|
||||
contracts through the `expected_keepers.go` (which are detailed below) design to
|
||||
avoid having a direct dependency on the implementing module. However, these
|
||||
contracts can define methods that operate on and/or return types that are specific
|
||||
to the contract's implementing module and this is where `exported/` comes into play.
|
||||
Types defined here allow for `expected_keepers.go` in other modules to define
|
||||
contracts that use single canonical types. This pattern allows for code to remain
|
||||
DRY and also alleviates import cycle chaos.
|
||||
- `handler.go`: The module's message handlers.
|
||||
- `keeper/`: The module's keeper implementation along with any auxiliary
|
||||
implementations such as the querier and invariants.
|
||||
- `types/`: The module's type definitions such as messages, `KVStore` keys,
|
||||
parameter types, Protocol Buffer definitions, and `expected_keepers.go` contracts.
|
||||
- `module.go`: The module's implementation of the `AppModule` and `AppModuleBasic`
|
||||
interfaces.
|
||||
- `simulation/`: The module's simulation package defines all the required functions
|
||||
used on the blockchain simulator: randomized genesis state, parameters, weighted
|
||||
operations, proposal contents and types decoders.
|
||||
- `client/`: The module's CLI and REST client functionality implementation and the module's integration testing suite.
|
||||
- `exported/`: The module's exported types - typically interface types. If a module relies on keepers from another module, it is expected to receive the keepers as interface contracts through the `expected_keepers.go` file (see below) in order to avoid a direct dependency on the module implementing the keepers. However, these interface contracts can define methods that operate on and/or return types that are specific to the module that is implementing the keepers and this is where `exported/` comes into play. The interface types that are defined in `exported/` use canonical types, allowing for the module to receive the keepers as interface contracts through the `expected_keepers.go` file. This pattern allows for code to remain DRY and also alleviates import cycle chaos.
|
||||
- `keeper/`: The module's `Keeper` and `MsgServer` implementation.
|
||||
- `module/`: The module's `AppModule` and `AppModuleBasic` implementation.
|
||||
- `simulation/`: The module's [simulation](./simulator.html) package defines functions used by the blockchain simulator application (`simapp`).
|
||||
- `spec/`: The module's specification documents outlining important concepts, state storage structure, and message and event type definitions.
|
||||
- The root directory includes type definitions for messages, events, and genesis state, including the type definitions generated by Protocol Buffers.
|
||||
- `abci.go`: The module's `BeginBlocker` and `EndBlocker` implementations (this file is only required if `BeginBlocker` and/or `EndBlocker` need to be defined).
|
||||
- `codec.go`: The module's registry methods for interface types.
|
||||
- `errors.go`: The module's sentinel errors.
|
||||
- `events.go`: The module's event types and constructors.
|
||||
- `expected_keepers.go`: The module's [expected keeper](./keeper.html#type-definition) interfaces.
|
||||
- `genesis.go`: The module's genesis state methods and helper functions.
|
||||
- `keys.go`: The module's store keys and associated helper functions.
|
||||
- `msgs.go`: The module's message type definitions and associated methods.
|
||||
- `params.go`: The module's parameter type definitions and associated methods.
|
||||
- `*.pb.go`: The module's type definitions generated by Protocol Buffers (as defined in the respective `*.proto` files above).
|
||||
|
||||
## Next {hide}
|
||||
|
||||
|
||||
@ -5,9 +5,11 @@ order: 13
|
||||
# In-Place Store Migrations
|
||||
|
||||
In-place store migrations allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. {synopsis}
|
||||
|
||||
## Prerequisite Readings
|
||||
|
||||
- [In-Place Store Migration](../core-concepts/upgrade.md) {prereq}
|
||||
|
||||
## Consensus Version
|
||||
|
||||
Successful upgrades of existing modules require your `AppModule` to implement the function `ConsensusVersion() uint64`.
|
||||
@ -43,7 +45,7 @@ Since these migrations are functions that need access to a Keeper's store, use a
|
||||
|
||||
## Writing Migration Scripts
|
||||
|
||||
To define the functionality that takes place during an upgrade, write a migration script. Since migration scripts manipulate legacy code, place these functions in a `legacy/` directory. For example, to write migration scripts for the bank module, place the functions in `x/bank/legacy/`. Use the recommended naming convention for these functions. For example, `v043bank` is the script that migrates this legacy package `x/bank/legacy/v043:
|
||||
To define the functionality that takes place during an upgrade, write a migration script. Since migration scripts manipulate legacy code, place these functions in a `legacy/` directory. For example, to write migration scripts for the bank module, place the functions in `x/bank/legacy/`. Use the recommended naming convention for these functions. For example, `v043bank` is the script that migrates this legacy package `x/bank/legacy/v043`:
|
||||
|
||||
```golang
|
||||
// Migrating bank module from version 1 to 2
|
||||
|
||||
Loading…
Reference in New Issue
Block a user