Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Building Modules documentation #7473

Merged
merged 49 commits into from
Oct 14, 2020
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
cb87c4f
Update module-manager.md
blushi Oct 7, 2020
49bdfa0
Merge branch 'master' of github.com:cosmos/cosmos-sdk
blushi Oct 7, 2020
0bc40be
Update modules #messages doc
blushi Oct 7, 2020
916a80b
Fix typo
blushi Oct 7, 2020
340babe
Update message implementation example link
blushi Oct 8, 2020
844401d
Update messages-and-queries.md#queries doc
blushi Oct 8, 2020
0a8fa86
Update querier.md
blushi Oct 8, 2020
25bc998
Update handler.md
blushi Oct 8, 2020
2c7010b
Update links in beginblock-endblock.md
blushi Oct 8, 2020
201d442
Update keeper.md
blushi Oct 8, 2020
546aefc
Update invariants.md
blushi Oct 8, 2020
3918392
Update genesis.md
blushi Oct 8, 2020
d0bac01
Update module-interfaces.md#transaction-commands
blushi Oct 8, 2020
0686e5e
Update module-interfaces.md#query-commands
blushi Oct 8, 2020
e76bdaf
Merge branch 'master' into marie/6953-building-modules
blushi Oct 8, 2020
6dac9b2
Update module-interfaces.md#flags
blushi Oct 8, 2020
fadd8c1
Update module-interfaces.md#rest
blushi Oct 8, 2020
8b58c43
Update structure.md
blushi Oct 8, 2020
bcb17dd
Merge branch 'master' into marie/6953-building-modules
blushi Oct 9, 2020
2fed130
Update module-interfaces.md#grpc
blushi Oct 9, 2020
289e10e
Update errors.md
blushi Oct 9, 2020
d0d4b34
Update module-interfaces.md#grpc-gateway-rest
blushi Oct 9, 2020
757b711
Merge branch 'master' into marie/6953-building-modules
blushi Oct 9, 2020
0d26688
Add more info on swagger
blushi Oct 9, 2020
7e9db05
Merge branch 'marie/6953-building-modules' of github.com:cosmos/cosmo…
blushi Oct 9, 2020
fa8a9cf
Address comments
blushi Oct 13, 2020
9d1cc7f
Merge branch 'master' into marie/6953-building-modules
blushi Oct 13, 2020
84a520d
Fix go.sum
blushi Oct 13, 2020
cf8d497
Merge branch 'marie/6953-building-modules' of github.com:cosmos/cosmo…
blushi Oct 13, 2020
d86adc2
Fix app-anatomy.md
blushi Oct 13, 2020
5a69a8c
Update docs/building-modules/module-interfaces.md
blushi Oct 13, 2020
cd56931
Update docs/building-modules/querier.md
blushi Oct 13, 2020
5e02309
Update docs/building-modules/querier.md
blushi Oct 13, 2020
7bbc9b8
Update docs/building-modules/module-interfaces.md
blushi Oct 13, 2020
0635919
Update docs/building-modules/module-interfaces.md
blushi Oct 13, 2020
b19c8e1
Address part of review comments
blushi Oct 14, 2020
1ea1ea8
Update old ref of RegisterQueryService
blushi Oct 14, 2020
56f9e10
Add example code for Manager
blushi Oct 14, 2020
bbd52c1
Update queriers.md to query-services.md and refs
blushi Oct 14, 2020
447ebb7
Add new query-services.md
blushi Oct 14, 2020
03e4c56
Revert "Update old ref of RegisterQueryService"
blushi Oct 14, 2020
5ad70f4
Update keeper.md
blushi Oct 14, 2020
9201a1a
Update handler.md
blushi Oct 14, 2020
9d156fa
Update handler.md
blushi Oct 14, 2020
e8d6858
Update messages-and-queries.md
blushi Oct 14, 2020
6ef1db3
Update docs/basics/app-anatomy.md
blushi Oct 14, 2020
bd20a72
Update docs/building-modules/intro.md
blushi Oct 14, 2020
1d02539
Fix typo
blushi Oct 14, 2020
4288915
Merge branch 'master' into marie/6953-building-modules
fedekunze Oct 14, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/basics/app-anatomy.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ gRPC query services are defined in the module's Protobuf definition, specificall

Protobuf generates a `QueryServer` interface for each module, containing all the service methods. A module's [`keeper`](#keeper) then needs to implement this `QueryServer` interface, by providing the concrete implementation of each service method. This concrete implementation is the handler of the corresponding gRPC query endpoint.

Finally, each module should also implement the `RegisterQueryService` method as part of the [`AppModule` interface](#application-module-interface). This method should call the `RegisterQueryServer` function provided by the generated Protobuf code.
Finally, each module should also implement the `RegisterServices` method as part of the [`AppModule` interface](#application-module-interface). This method should call the `RegisterQueryServer` function provided by the generated Protobuf code.

### Legacy Querier

Expand Down
2 changes: 1 addition & 1 deletion docs/building-modules/messages-and-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Here's an example of such a `Query` service definition:

As `proto.Message`s, generated `Response` types implement by default `String()` method of [`fmt.Stringer`](https://golang.org/pkg/fmt/#Stringer).

A `RegisterQueryServer` method is also generated and should be used to register the module's query server in `RegisterQueryService` method from the [`AppModule` interface](./module-manager.md#appmodule).
A `RegisterQueryServer` method is also generated and should be used to register the module's query server in `RegisterServices` method from the [`AppModule` interface](./module-manager.md#appmodule).

### Legacy Queries

Expand Down
4 changes: 2 additions & 2 deletions docs/building-modules/module-manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Let us go through the methods of `AppModule`:
- `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).
blushi marked this conversation as resolved.
Show resolved Hide resolved
- `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`](./querier.md) given the query `path`, in order to process the `query`.
- `RegisterQueryService(grpc.Server)`: Allows a module to register a gRPC query service.
- `RegisterServices(Configurator)`: Allows a module to register services.
- `BeginBlock(sdk.Context, abci.RequestBeginBlock)`: This method gives module developers the option to implement logic that is automatically triggered at the beginning of each block. Implement empty if no logic needs to be triggered at the beginning of each block for this module.
- `EndBlock(sdk.Context, abci.RequestEndBlock)`: This method gives module developers the option to implement logic that is automatically triggered at the beginning of each block. This is also where the module can inform the underlying consensus engine of validator set changes (e.g. the `staking` module). Implement empty if no logic needs to be triggered at the beginning of each block for this module.

Expand Down Expand Up @@ -135,7 +135,7 @@ The module manager is used throughout the application whenever an action on a co
- `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../basics/app-anatomy.md#constructor-function).
- `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./invariants.md) of each module.
- `RegisterRoutes(router sdk.Router, queryRouter sdk.QueryRouter, legacyQuerierCdc *codec.LegacyAmino)`: Registers module routes to the application's `router`, in order to route [`message`s](./messages-and-queries.md#messages) to the appropriate [`handler`](./handler.md), and module query routes to the application's `queryRouter`, in order to route [`queries`](./messages-and-queries.md#queries) to the appropriate [`querier`](./querier.md).
- `RegisterQueryServices(grpcRouter grpc.Server)`: Registers all module gRPC query services.
blushi marked this conversation as resolved.
Show resolved Hide resolved
- `RegisterServices(cfg Configurator)`: Registers all module gRPC query services.
- `InitGenesis(ctx sdk.Context, cdc codec.JSONMarshaler, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.ResponseInitChain` to the underlying consensus engine, which can contain validator updates.
- `ExportGenesis(ctx sdk.Context, cdc codec.JSONMarshaler)`: Calls the [`ExportGenesis`](./genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required.
- `BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock)`: At the beginning of each block, this function is called from [`baseapp`](../core/baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./beginblock-endblock.md) function of each module, in the order defined in `OrderBeginBlockers`. It creates a child [context](../core/context.md) with an event manager to aggregate [events](../core/events.md) emitted from all modules. The function returns an `abci.ResponseBeginBlock` which contains the aforementioned events.
Expand Down
4 changes: 2 additions & 2 deletions types/module/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -166,10 +166,10 @@ type AppModule interface {
// routes
Route() sdk.Route

// Deprecated: use RegisterQueryService
blushi marked this conversation as resolved.
Show resolved Hide resolved
// Deprecated: use RegisterServices
QuerierRoute() string

// Deprecated: use RegisterQueryService
// Deprecated: use RegisterServices
LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier

// RegisterServices allows a module to register services
Expand Down
2 changes: 1 addition & 1 deletion x/auth/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.accountKeeper, legacyQuerierCdc)
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.accountKeeper)
Expand Down
2 changes: 1 addition & 1 deletion x/auth/vesting/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ func (am AppModule) Route() sdk.Route {
// functionality.
func (AppModule) QuerierRoute() string { return "" }

// RegisterQueryService performs a no-op.
// RegisterServices performs a no-op.
func (am AppModule) RegisterServices(_ module.Configurator) {}

// LegacyQuerierHandler performs a no-op.
Expand Down
2 changes: 1 addition & 1 deletion x/bank/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ type AppModule struct {
accountKeeper types.AccountKeeper
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/capability/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ func (AppModule) QuerierRoute() string { return "" }
// LegacyQuerierHandler returns the capability module's Querier.
func (am AppModule) LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier { return nil }

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(module.Configurator) {}

Expand Down
2 changes: 1 addition & 1 deletion x/crisis/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ func (AppModule) QuerierRoute() string { return "" }
// LegacyQuerierHandler returns no sdk.Querier.
func (AppModule) LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier { return nil }

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(module.Configurator) {}

Expand Down
2 changes: 1 addition & 1 deletion x/distribution/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/evidence/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/gov/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/ibc/applications/transfer/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ func (am AppModule) LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier {
return nil
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/ibc/core/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return nil
}

// RegisterQueryService registers the gRPC query service for the ibc module.
// RegisterServices registers the gRPC query service for the ibc module.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryService(cfg.QueryServer(), am.keeper)
}
Expand Down
2 changes: 1 addition & 1 deletion x/ibc/testing/mock/mock.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ func (am AppModule) LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier {
return nil
}

// RegisterQueryService implements the AppModule interface.
// RegisterServices implements the AppModule interface.
func (am AppModule) RegisterServices(module.Configurator) {}

// InitGenesis implements the AppModule interface.
Expand Down
2 changes: 1 addition & 1 deletion x/mint/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a gRPC query service to respond to the
// RegisterServices registers a gRPC query service to respond to the
// module-specific gRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/params/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a gRPC query service to respond to the
// RegisterServices registers a gRPC query service to respond to the
// module-specific gRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
proposal.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/slashing/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down
2 changes: 1 addition & 1 deletion x/staking/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
querier := keeper.Querier{Keeper: am.keeper}
Expand Down
2 changes: 1 addition & 1 deletion x/upgrade/module.go
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sd
return keeper.NewQuerier(am.keeper, legacyQuerierCdc)
}

// RegisterQueryService registers a GRPC query service to respond to the
// RegisterServices registers a GRPC query service to respond to the
// module-specific GRPC queries.
func (am AppModule) RegisterServices(cfg module.Configurator) {
types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
Expand Down