docs: add documentation about depinject and app wiring (#13683)
This commit is contained in:
Julien Robert
GitHub
parent
5af7b5993c
commit
c85447cdb9
9
.gitignore
vendored
9
.gitignore
vendored
@ -14,11 +14,12 @@ private
|
||||
# Build
|
||||
vendor
|
||||
build
|
||||
docs/_build
|
||||
docs/tutorial
|
||||
docs/node_modules
|
||||
docs/modules
|
||||
docs/tools/cosmovisor.md
|
||||
docs/docs/modules
|
||||
docs/docs/spec
|
||||
docs/docs/architecture
|
||||
docs/docs/tooling/01-cosmovisor.md
|
||||
docs/docs/tooling/02-depinject.md
|
||||
docs/run-node/04-rosetta.md
|
||||
dist
|
||||
tools-stamp
|
||||
|
||||
@ -26,7 +26,7 @@ The `simapp` package **should not be imported in your own app**. Instead, you sh
|
||||
|
||||
#### App Wiring
|
||||
|
||||
SimApp's `app.go` is now using [App Wiring](https://docs.cosmos.network/main/building-chain/depinject.html), the dependency injection framework of the Cosmos SDK.
|
||||
SimApp's `app.go` is now using [App Wiring](https://docs.cosmos.network/main/building-apps/app-go), the dependency injection framework of the Cosmos SDK.
|
||||
This means that modules are injected directly into SimApp thanks to a [configuration file](https://github.com/cosmos/cosmos-sdk/blob/main/simapp/app_config.go).
|
||||
The old behavior is preserved and can still be used, without the dependency injection framework, as shows [`app_legacy.go`](https://github.com/cosmos/cosmos-sdk/blob/main/simapp/app_legacy.go).
|
||||
|
||||
|
||||
@ -2,17 +2,21 @@
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Cosmos SDK Dependency Injection `depinject` Module
|
||||
# Depinject
|
||||
|
||||
> **DISCLAIMER**: This is a **beta** package. The SDK team is actively working on this feature and we are looking for feedback from the community. Please try it out and let us know what you think.
|
||||
|
||||
## Overview
|
||||
|
||||
`depinject` is a dependency injection framework for the Cosmos SDK. This module together with `core/appconfig` are meant
|
||||
to simplify the definition of a blockchain by replacing most of app.go's boilerplate code with a configuration file (YAML or JSON).
|
||||
`depinject` is a dependency injection framework for the Cosmos SDK. This module together with `core/appconfig` are meant to simplify the definition of a blockchain by replacing most of `app.go`'s boilerplate code with a configuration file (Go, YAML or JSON).
|
||||
|
||||
* [Go Doc](https://pkg.go.dev/cosmossdk.io/depinject)
|
||||
|
||||
## Usage
|
||||
|
||||
`depinject` includes an expressive and composable [Configuration API](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/depinject#Config).
|
||||
A core configuration is `Provide`, for example this code snippet
|
||||
A core configuration function is `Provide`. The example below demonstrates the registration of free **provider functions** via the `Provide` API.
|
||||
|
||||
|
||||
```go
|
||||
package main
|
||||
@ -44,17 +48,16 @@ func main() {
|
||||
}
|
||||
```
|
||||
|
||||
demonstrates the registration of free **provider functions** via the `Provide` API. Provider functions form the basis of the
|
||||
dependency tree, they are introspected then their inputs identified as dependencies and outputs as dependants, either for
|
||||
another provider function or state stored outside the DI container, as is the case of `&x` and `&y` above.
|
||||
Provider functions form the basis of the dependency tree, they are introspected then their inputs identified as dependencies and outputs as dependants, either for another provider function or state stored outside the DI container, as is the case of `&x` and `&y` above.
|
||||
|
||||
### Interface type resolution
|
||||
|
||||
`depinject` supports interface types as inputs to provider functions. In the SDK's case this pattern is used to decouple
|
||||
`Keeper` dependencies between modules. For example `x/bank` expects an [AccountKeeper](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/x/bank/types#AccountKeeper) interface as [input to provideModule](https://github.com/cosmos/cosmos-sdk/blob/de343d458aa68c19630177807d6f0e2e6deaf7a9/x/bank/module.go#L224).
|
||||
|
||||
Concretely `SimApp` uses the implementation in `x/auth`, but this design allows for this loose coupling to change.
|
||||
|
||||
Given the following types
|
||||
Given the following types:
|
||||
|
||||
```go
|
||||
package duck
|
||||
@ -92,8 +95,8 @@ depinject.Inject(
|
||||
&pond)
|
||||
```
|
||||
|
||||
results in an *implicit* binding of `Duck` to `Mallard`. This works because there is only one implementation of `Duck`
|
||||
in the container. However, adding a second provider of `Duck` will result in an error:
|
||||
results in an *implicit* binding of `Duck` to `Mallard`. This works because there is only one implementation of `Duck` in the container.
|
||||
However, adding a second provider of `Duck` will result in an error:
|
||||
|
||||
```go
|
||||
var pond Pond
|
||||
@ -133,49 +136,18 @@ Now `depinject` has enough information to provide `Mallard` as an input to `APon
|
||||
|
||||
### Full example in real app
|
||||
|
||||
```go
|
||||
//go:embed app.yaml
|
||||
var appConfigYaml []byte
|
||||
:::warning
|
||||
When using `depinject.Inject`, the injected types must be pointers.
|
||||
:::
|
||||
|
||||
var appConfig = appconfig.LoadYAML(appConfigYaml)
|
||||
|
||||
func NewSimApp(
|
||||
logger log.Logger,
|
||||
db dbm.DB,
|
||||
traceStore io.Writer,
|
||||
loadLatest bool,
|
||||
appOpts servertypes.AppOptions,
|
||||
baseAppOptions ...func(*baseapp.BaseApp),
|
||||
) *SimApp {
|
||||
var (
|
||||
app = &SimApp{}
|
||||
appBuilder *runtime.AppBuilder
|
||||
)
|
||||
|
||||
err := depinject.Inject(AppConfig,
|
||||
&appBuilder,
|
||||
&app.ParamsKeeper,
|
||||
&app.CapabilityKeeper,
|
||||
&app.appCodec,
|
||||
&app.legacyAmino,
|
||||
&app.interfaceRegistry,
|
||||
&app.AccountKeeper,
|
||||
&app.BankKeeper,
|
||||
&app.FeeGrantKeeper,
|
||||
&app.StakingKeeper,
|
||||
)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
...
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app.go#L227-L254
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
Issues with resolving dependencies in the container can be done with logs
|
||||
and [Graphviz](https://graphviz.org) renderings of the container tree. By default, whenever there is an error, logs will
|
||||
be printed to stderr and a rendering of the dependency graph in Graphviz DOT format will be saved to
|
||||
`debug_container.dot`.
|
||||
Issues with resolving dependencies in the container can be done with logs and [Graphviz](https://graphviz.org) renderings of the container tree.
|
||||
By default, whenever there is an error, logs will be printed to stderr and a rendering of the dependency graph in Graphviz DOT format will be saved to `debug_container.dot`.
|
||||
|
||||
Here is an example Graphviz rendering of a successful build of a dependency graph:
|
||||
|
||||
@ -191,7 +163,7 @@ Here is an example Graphviz rendering of a dependency graph build which failed:
|
||||
Graphviz DOT files can be converted into SVG's for viewing in a web browser using the `dot` command-line tool, ex:
|
||||
|
||||
```txt
|
||||
> dot -Tsvg debug_container.dot > debug_container.svg
|
||||
dot -Tsvg debug_container.dot > debug_container.svg
|
||||
```
|
||||
|
||||
Many other tools including some IDEs support working with DOT files.
|
||||
|
||||
@ -78,7 +78,7 @@ When writing ADRs, follow the same best practices for writing RFCs. When writing
|
||||
* [ADR 039: Epoched Staking](./adr-039-epoched-staking.md)
|
||||
* [ADR 040: Storage and SMT State Commitments](./adr-040-storage-and-smt-state-commitments.md)
|
||||
* [ADR 046: Module Params](./adr-046-module-params.md)
|
||||
* [ADR 057: App Wiring Part I](./adr-057-app-wiring-1.md)
|
||||
* [ADR 057: App Wiring](./adr-057-app-wiring.md)
|
||||
* [ADR 059: Test Scopes](./adr-059-test-scopes.md)
|
||||
* [ADR 060: ABCI 1.0](adr-060-abci-1.0.md)
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ language for talking about test scopes and proposes an ideal state of tests at e
|
||||
## Context
|
||||
|
||||
[ADR-053: Go Module Refactoring](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-053-go-module-refactoring.md) expresses our desire for an SDK composed of many
|
||||
independently versioned Go modules, and [ADR-057: App Wiring Part I](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-057-app-wiring-1.md) offers a methodology
|
||||
independently versioned Go modules, and [ADR-057: App Wiring](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-057-app-wiring.md) offers a methodology
|
||||
for breaking apart inter-module dependencies through the use of dependency injection. As
|
||||
described in [EPIC: Separate all SDK modules into standalone go modules](https://github.com/cosmos/cosmos-sdk/issues/11899), module
|
||||
dependencies are particularly complected in the test phase, where simapp is used as
|
||||
|
||||
@ -2,25 +2,129 @@
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Overview of `app.go` and how to wire it up
|
||||
# Overview of `app.go`
|
||||
|
||||
This section is intended to provide an overview of the `app.go` file and is still a work in progress.
|
||||
For now we invite you to read the [tutorials](https://tutorials.cosmos.network) for a deep dive on how to build a chain.
|
||||
:::note Synopsis
|
||||
|
||||
Since `v0.47.0`, the Cosmos SDK allows much easier wiring an `app.go` with App Wiring and the tool [`depinject`](../tooling/02-depinject.md).
|
||||
Learn more about the rationale of App Wiring in [ADR-057](../architecture/adr-057-app-wiring.md).
|
||||
|
||||
:::
|
||||
|
||||
:::note
|
||||
|
||||
### Pre-requisite Readings
|
||||
|
||||
* [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md)
|
||||
* [Depinject Documentation](../tooling/02-depinject.md)
|
||||
|
||||
:::
|
||||
|
||||
This section is intended to provide an overview of the `SimApp` `app.go` file with App Wiring.
|
||||
|
||||
## `app_config.go`
|
||||
|
||||
The `app_config.go` file is the single place to configure all modules parameters.
|
||||
|
||||
1. Create the `AppConfig` variable:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app_config.go#L77-L78
|
||||
```
|
||||
|
||||
2. Configure the `runtime` module:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app_config.go#L79-L137
|
||||
```
|
||||
|
||||
3. Configure the modules defined in the `BeginBlocker` and `EndBlocker` and the `tx` module:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app_config.go#L138-L156
|
||||
```
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app_config.go#L170-L173
|
||||
```
|
||||
|
||||
### Complete `app_config.go`
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app_config.go#L52-L233
|
||||
```
|
||||
|
||||
### Alternative formats
|
||||
|
||||
:::tip
|
||||
The example above shows how to create an `AppConfig` using Go. However, it is also possible to create an `AppConfig` using YAML, or JSON.
|
||||
The configuration can then be embed with `go:embed` and read with [`appconfig.LoadYAML`](https://pkg.go.dev/cosmossdk.io/core/appconfig#LoadYAML), or [`appconfig.LoadJSON`](https://pkg.go.dev/cosmossdk.io/core/appconfig#LoadJSON), in `app.go`.
|
||||
|
||||
```go
|
||||
//go:embed app_config.yaml
|
||||
var (
|
||||
appConfigYaml []byte
|
||||
appConfig = appconfig.LoadYAML(appConfigYaml)
|
||||
)
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
```yaml
|
||||
modules:
|
||||
- name: runtime
|
||||
config:
|
||||
"@type": cosmos.app.runtime.v1alpha1.Module
|
||||
app_name: SimApp
|
||||
begin_blockers: [staking, auth, bank]
|
||||
end_blockers: [bank, auth, staking]
|
||||
init_genesis: [bank, auth, staking]
|
||||
- name: auth
|
||||
config:
|
||||
"@type": cosmos.auth.module.v1.Module
|
||||
bech32_prefix: cosmos
|
||||
- name: bank
|
||||
config:
|
||||
"@type": cosmos.bank.module.v1.Module
|
||||
- name: staking
|
||||
config:
|
||||
"@type": cosmos.staking.module.v1.Module
|
||||
- name: tx
|
||||
config:
|
||||
"@type": cosmos.tx.module.v1.Module
|
||||
```
|
||||
|
||||
A more complete example of `app.yaml` can be found [here](https://github.com/cosmos/cosmos-sdk/blob/91b1d83f1339e235a1dfa929ecc00084101a19e3/simapp/app.yaml).
|
||||
|
||||
## `app.go`
|
||||
|
||||
Since `v0.47.0` the Cosmos SDK have made easier wiring an `app.go` thanks to dependency injection:
|
||||
`app.go` is the place where `SimApp` is constructed. `depinject.Inject` facilitates that by automatically wiring the app modules and keepers, provided an application configuration `AppConfig` is provided. `SimApp` is constructed, when calling the injected `*runtime.AppBuilder`, with `appBuilder.Build(...)`.
|
||||
In short `depinject` and the [`runtime` package](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/runtime) abstract the wiring of the app, and the `AppBuilder` is the place where the app is constructed. [`runtime`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/runtime) takes care of registering the codecs, KV store, subspaces and instantiating `baseapp`.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/simapp/app_config.go
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app.go#L227-L254
|
||||
```
|
||||
|
||||
:::warning
|
||||
When using `depinject.Inject`, the injected types must be pointers.
|
||||
:::
|
||||
|
||||
### Advanced Configuration
|
||||
|
||||
In advanced cases, it is possible to inject extra (module) configuration in a way that is not (yet) supported by `AppConfig`.
|
||||
In this case, use `depinject.Configs` for combining the extra configuration and `AppConfig`, and `depinject.Supply` to providing that extra configuration.
|
||||
More information on how work `depinject.Configs` and `depinject.Supply` can be found in the [`depinject` documentation](https://pkg.go.dev/cosmossdk.io/depinject).
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/simapp/app.go
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app.go#L193-L224
|
||||
```
|
||||
|
||||
## `app_legacy.go`
|
||||
### Complete `app.go`
|
||||
|
||||
:::tip
|
||||
Note that in the complete `SimApp` `app.go` file, testing utilities are also defined, but they could as well be defined in a separate file.
|
||||
:::
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/simapp/app_legacy.go
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app.go#L94-L427
|
||||
```
|
||||
|
||||
14
docs/docs/building-apps/01-app-legacy-go.md
Normal file
14
docs/docs/building-apps/01-app-legacy-go.md
Normal file
@ -0,0 +1,14 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Overview of `app_legacy.go`
|
||||
|
||||
This section is intended to provide an overview of the `SimApp` `app_legacy.go` (or `app.go` pre-`v0.47.0`) file and is still a work in progress.
|
||||
For now please instead read the [tutorials](https://tutorials.cosmos.network) for a deep dive on how to build a chain.
|
||||
|
||||
## Complete `app_legacy.go`
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app_legacy.go#L103-L716
|
||||
```
|
||||
125
docs/docs/building-modules/14-depinject.md
Normal file
125
docs/docs/building-modules/14-depinject.md
Normal file
@ -0,0 +1,125 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Dependency Injection
|
||||
|
||||
:::note
|
||||
|
||||
### Pre-requisite Readings
|
||||
|
||||
* [Cosmos SDK Dependency Injection Framework](../tooling/02-depinject.md)
|
||||
|
||||
:::
|
||||
|
||||
[`depinject`](../tooling/02-depinject.md) is used to wire any module in `app.go`.
|
||||
All core modules are already configured to support dependency injection.
|
||||
|
||||
To work with `depinject` a module must define its configuration and requirements so that `depinject` can provide the right dependencies.
|
||||
|
||||
In brief, as a module developer, the following steps are required:
|
||||
|
||||
1. Define the module configuration using Protobuf
|
||||
2. Define the module dependencies in `x/{moduleName}/module.go`
|
||||
|
||||
A chain developer can then use the module by following these two steps:
|
||||
|
||||
1. Configure the module in `app_config.go` or `app.yaml`
|
||||
2. Inject the module in `app.go`
|
||||
|
||||
## Module Configuration
|
||||
|
||||
The module available configuration is defined in a Protobuf file, located at `{moduleName}/module/v1/module.proto`.
|
||||
|
||||
```protobuf reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/group/module/v1/module.proto
|
||||
```
|
||||
|
||||
* `go_import` must point to the Go package of the custom module.
|
||||
* Message fields define the module configuration.
|
||||
That configuration can be set in the `app_config.go` / `app.yaml` file for a chain developer to configure the module.
|
||||
Taking `group` as example, a chain developer is able to decide, thanks to `uint64 max_metadata_len`, what the maximum metatada length allowed for a group porposal is.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/simapp/app_config.go#L202-L206
|
||||
```
|
||||
|
||||
That message is generated using [`pulsar`](https://github.com/cosmos/cosmos-sdk/blob/main/scripts/protocgen-pulsar.sh) (by running `make proto-gen`).
|
||||
In the case of the `group` module, this file is generated here: https://github.com/cosmos/cosmos-sdk/blob/main/api/cosmos/group/module/v1/module.pulsar.go.
|
||||
|
||||
The part that is relevant for the module configuration is:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/api/cosmos/group/module/v1/module.pulsar.go#L514-L526
|
||||
```
|
||||
|
||||
:::note
|
||||
Pulsar is totally optional. The official [`protoc-gen-go`](https://developers.google.com/protocol-buffers/docs/reference/go-generated) can be used as well.
|
||||
:::
|
||||
|
||||
## Dependency Definition
|
||||
|
||||
Once the configuration proto is defined, the module's `module.go` must define what dependencies are required by the module.
|
||||
The boilerplate is similar for all modules.
|
||||
|
||||
:::warning
|
||||
|
||||
All methods, structs and their fields must be public for `depinject`.
|
||||
|
||||
:::
|
||||
|
||||
1. Import the module configuration generated package:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/x/group/module/module.go#L14-L15
|
||||
```
|
||||
|
||||
Define an `init()` function for defining the `providers` of the module configuration:
|
||||
This registers the module configuration message and the wiring of the module.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/x/group/module/module.go#L184-L192
|
||||
```
|
||||
|
||||
2. `ProvideModuleBasic` is calls `WrapAppModuleBasic` for wrapping the module `AppModuleBasic`, so that it can be injected and used by the runtime module.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/x/group/module/module.go#L194-L196
|
||||
```
|
||||
|
||||
3. Define a struct that inherits `depinject.In` and define the module inputs (i.e. module dependencies):
|
||||
* `depinject` provides the right dependencies to the module.
|
||||
* `depinject` also checks that all dependencies are provided.
|
||||
|
||||
:::tip
|
||||
For making a dependency optional, add the `optional:"true"` struct tag.
|
||||
:::
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/x/group/module/module.go#L198-L208
|
||||
```
|
||||
|
||||
4. Define the module outputs with a public struct that inherits `depinject.Out`:
|
||||
The module outputs are the dependencies that the module provides to other modules. It is usually the module itself and its keeper.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/x/group/module/module.go#L210-L215
|
||||
```
|
||||
|
||||
5. Create a function named `ProvideModule` (as called in 1.) and use the inputs for instantitating the module outputs.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/main/x/group/module/module.go#L217-L227
|
||||
```
|
||||
|
||||
Following is the complete app wiring configuration for `group`:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/0d8787c/x/group/module/module.go#L180-L227
|
||||
```
|
||||
|
||||
The module is now ready to be used with `depinject` by a chain developer.
|
||||
|
||||
## App Wiring
|
||||
|
||||
The App Wiring is done in `app_config.go` / `app.yaml` and `app.go` and is explained in detail in the [overview of `app.go`](../building-apps/00-app-go.md).
|
||||
@ -2,7 +2,7 @@
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Module & App Testing
|
||||
# Testing
|
||||
|
||||
The Cosmos SDK contains different types of [tests](https://martinfowler.com/articles/practical-test-pyramid.html).
|
||||
These tests have different goals and are used at different stages of the development cycle.
|
||||
@ -57,13 +57,13 @@ https://github.com/cosmos/cosmos-sdk/blob/a92c291880eb6240b7221173282fee0c5f2adb
|
||||
Integration tests are at the second level of the [test pyramid](https://martinfowler.com/articles/practical-test-pyramid.html).
|
||||
In the SDK, we locate our integration tests under [`/tests/integrations`](https://github.com/cosmos/cosmos-sdk/tree/main/tests/integration).
|
||||
|
||||
The goal of these integration tests is to test a component with a minimal application (i.e. not `simapp`). The minimal application is defined with the help of [`depinject`](../building-apps/01-depinject.md) – the SDK dependency injection framework, and includes all necessary modules to test the component. With the helps of the SDK testing package, we can easily create a minimal application and start the application with a set of genesis transactions: <https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go>.
|
||||
The goal of these integration tests is to test a component with a minimal application (i.e. not `simapp`). The minimal application is defined with the help of [`depinject`](../tooling/02-depinject.md) – the SDK dependency injection framework, and includes all necessary modules to test the component. With the helps of the SDK testing package, we can easily create a minimal application and start the application with a set of genesis transactions: <https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go>.
|
||||
|
||||
### Example
|
||||
|
||||
Here, we will walkthrough the integration tests of the `x/distribution` module. The `x/distribution` module has, in addition to keeper unit tests, integration tests that test the `x/distribution` module with a minimal application. This is expected as you may want to test the `x/distribution` module with actual application logic, instead of only mocked dependencies.
|
||||
|
||||
For creating a minimal application, we use [`simtestutil.Setup`](https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go#L98-L102) and an [`AppConfig`](../building-apps/01-depinject.md) of the `x/distribution` minimal dependencies.
|
||||
For creating a minimal application, we use [`simtestutil.Setup`](https://github.com/cosmos/cosmos-sdk/blob/main/testutil/sims/app_helpers.go#L98-L102) and an [`AppConfig`](../tooling/02-depinject.md) of the `x/distribution` minimal dependencies.
|
||||
|
||||
For instance, the `AppConfig` of `x/distribution` is defined as:
|
||||
|
||||
@ -102,7 +102,7 @@ https://github.com/cosmos/cosmos-sdk/blob/9f3575a10f1a6f1315b94a9be783df5156ce22
|
||||
|
||||
## Simulations
|
||||
|
||||
Simulations uses as well a minimal application, built with [`depinject`](../building-apps/01-depinject.md):
|
||||
Simulations uses as well a minimal application, built with [`depinject`](../tooling/02-depinject.md):
|
||||
|
||||
Following is an example for `x/gov/` simulations:
|
||||
|
||||
@ -24,7 +24,7 @@ securely. Typically, an operating system's credential sub-system handles passwor
|
||||
private keys storage, and user sessions according to the user's password policies. Here
|
||||
is a list of the most popular operating systems and their respective passwords manager:
|
||||
|
||||
* macOS (since Mac OS 8.6): [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
|
||||
* macOS: [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
|
||||
* Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management)
|
||||
* GNU/Linux:
|
||||
* [libsecret](https://gitlab.gnome.org/GNOME/libsecret)
|
||||
@ -116,10 +116,6 @@ Applications developed using the Cosmos SDK come with the `keys` subcommand. For
|
||||
|
||||
You can use `simd keys` for help about the keys command and `simd keys [command] --help` for more information about a particular subcommand.
|
||||
|
||||
:::tip
|
||||
You can also enable auto-completion with the `simd completion` command. For example, at the start of a bash session, run `. <(simd completion)`, and all `simd` subcommands will be auto-completed.
|
||||
:::
|
||||
|
||||
To create a new key in the keyring, run the `add` subcommand with a `<key_name>` argument. For the purpose of this tutorial, we will solely use the `test` backend, and call our new key `my_validator`. This key will be used in the next section.
|
||||
|
||||
```bash
|
||||
@ -131,4 +127,4 @@ MY_VALIDATOR_ADDRESS=$(simd keys show my_validator -a --keyring-backend test)
|
||||
|
||||
This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe!
|
||||
|
||||
By default, the keyring generates a `secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module (in particular its [middlewares](../core/00-baseapp.md#middleware)) supports natively these two public key algorithms.
|
||||
By default, the keyring generates a `secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module supports natively these two public key algorithms.
|
||||
|
||||
@ -7,4 +7,5 @@ sidebar_position: 0
|
||||
This section provides documentation on various tooling used in development of a Cosmos SDK chain, operating a node and testing.
|
||||
|
||||
* [Protocol Buffers](./00-protobuf.md)
|
||||
* [Cosmovisor](./01-cosmovisor.md)
|
||||
* [Cosmovisor](./01-cosmovisor.md)
|
||||
* [Depinject](./02-depinject.md)
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
rm -rf docs/modules
|
||||
rm -rf docs/tooling/01-cosmovisor.md
|
||||
rm -rf docs/building-apps/01-depinject.md
|
||||
rm -rf docs/tooling/02-depinject.md
|
||||
rm -rf docs/run-node/04-rosetta.md
|
||||
rm -rf docs/architecture
|
||||
rm -rf docs/spec
|
||||
|
||||
@ -20,13 +20,13 @@ cp -r ../x/auth/vesting/README.md ./docs/modules/vesting/README.md
|
||||
## Add modules page list
|
||||
cat ../x/README.md | sed 's/\.\.\/docs\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./docs/modules/README.md
|
||||
|
||||
## Add Cosmovisor documentation
|
||||
## Add cosmovisor documentation
|
||||
cp ../tools/cosmovisor/README.md ./docs/tooling/01-cosmovisor.md
|
||||
|
||||
## Add Depinject documentation
|
||||
cp ../depinject/README.md ./docs/building-apps/01-depinject.md
|
||||
## Add depinject documentation
|
||||
cp ../depinject/README.md ./docs/tooling/02-depinject.md
|
||||
|
||||
## Add Rosetta documentation
|
||||
## Add rosetta documentation
|
||||
cp ../tools/rosetta/README.md ./docs/run-node/04-rosetta.md
|
||||
|
||||
## Add architecture documentation
|
||||
|
||||
@ -426,7 +426,7 @@ html {
|
||||
|
||||
/* MARKDOWN */
|
||||
.theme-code-block {
|
||||
@apply font-jetbrain;
|
||||
@apply font-jetbrain mt-3;
|
||||
}
|
||||
|
||||
.markdown {
|
||||
@ -509,9 +509,6 @@ html {
|
||||
& > ol {
|
||||
@apply my-5;
|
||||
}
|
||||
& > p + .theme-code-block {
|
||||
@apply mt-3;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -239,7 +239,7 @@ The auth module contains the following parameters:
|
||||
|
||||
A user can query and interact with the `auth` module using the CLI.
|
||||
|
||||
#### Query
|
||||
### Query
|
||||
|
||||
The `query` commands allow users to query `auth` state.
|
||||
|
||||
@ -247,7 +247,7 @@ The `query` commands allow users to query `auth` state.
|
||||
simd query auth --help
|
||||
```
|
||||
|
||||
##### account
|
||||
#### account
|
||||
|
||||
The `account` command allow users to query for an account by it's address.
|
||||
|
||||
@ -273,7 +273,7 @@ pub_key:
|
||||
sequence: "1"
|
||||
```
|
||||
|
||||
##### accounts
|
||||
#### accounts
|
||||
|
||||
The `accounts` command allow users to query all the available accounts.
|
||||
|
||||
@ -372,7 +372,7 @@ pagination:
|
||||
total: "0"
|
||||
```
|
||||
|
||||
##### params
|
||||
#### params
|
||||
|
||||
The `params` command allow users to query the current auth parameters.
|
||||
|
||||
@ -396,7 +396,7 @@ tx_sig_limit: "7"
|
||||
tx_size_cost_per_byte: "10"
|
||||
```
|
||||
|
||||
#### Transactions
|
||||
### Transactions
|
||||
|
||||
The `auth` module supports transactions commands to help you with signing and more. Compared to other modules you can access directly the `auth` module transactions commands using the only `tx` command.
|
||||
|
||||
@ -406,7 +406,7 @@ Use directly the `--help` flag to get more information about the `tx` command.
|
||||
simd tx --help
|
||||
```
|
||||
|
||||
##### `sign`
|
||||
#### `sign`
|
||||
|
||||
The `sign` command allows users to sign transactions that was generated offline.
|
||||
|
||||
@ -418,7 +418,7 @@ The result is a signed transaction that can be broadcasted to the network thanks
|
||||
|
||||
More information about the `sign` command can be found running `simd tx sign --help`.
|
||||
|
||||
##### `sign-batch`
|
||||
#### `sign-batch`
|
||||
|
||||
The `sign-batch` command allows users to sign multiples offline generated transactions.
|
||||
The transactions can be in one file, with one tx per line, or in multiple files.
|
||||
@ -437,7 +437,7 @@ The result is multiples signed transactions. For combining the signed transactio
|
||||
|
||||
More information about the `sign-batch` command can be found running `simd tx sign-batch --help`.
|
||||
|
||||
##### `multi-sign`
|
||||
#### `multi-sign`
|
||||
|
||||
The `multi-sign` command allows users to sign transactions that was generated offline by a multisig account.
|
||||
|
||||
@ -449,14 +449,14 @@ Where `k1k2k3` is the multisig account address, `k1sig.json` is the signature of
|
||||
|
||||
More information about the `multi-sign` command can be found running `simd tx multi-sign --help`.
|
||||
|
||||
##### `multisign-batch`
|
||||
#### `multisign-batch`
|
||||
|
||||
The `multisign-batch` works the same way as `sign-batch`, but for multisig accounts.
|
||||
With the difference that the `multisign-batch` command requires all transactions to be in one file, and the `--append` flag does not exist.
|
||||
|
||||
More information about the `multisign-batch` command can be found running `simd tx multisign-batch --help`.
|
||||
|
||||
##### `validate-signatures`
|
||||
#### `validate-signatures`
|
||||
|
||||
The `validate-signatures` command allows users to validate the signatures of a signed transaction.
|
||||
|
||||
@ -471,7 +471,7 @@ Signatures:
|
||||
|
||||
More information about the `validate-signatures` command can be found running `simd tx validate-signatures --help`.
|
||||
|
||||
##### `broadcast`
|
||||
#### `broadcast`
|
||||
|
||||
The `broadcast` command allows users to broadcast a signed transaction to the network.
|
||||
|
||||
@ -481,7 +481,7 @@ simd tx broadcast tx.signed.json
|
||||
|
||||
More information about the `broadcast` command can be found running `simd tx broadcast --help`.
|
||||
|
||||
##### `encode`
|
||||
#### `encode`
|
||||
|
||||
The `encode` command encodes a transaction created with the `--generate-only` flag or signed with the sign command.
|
||||
The transaction is seralized it to Protobuf and returned as base64.
|
||||
@ -494,7 +494,7 @@ $ simd tx encode tx.signed.json
|
||||
|
||||
More information about the `encode` command can be found running `simd tx encode --help`.
|
||||
|
||||
##### `decode`
|
||||
#### `decode`
|
||||
|
||||
The `decode` commands decodes a transaction encoded with the `encode` command.
|
||||
|
||||
@ -505,7 +505,7 @@ simd tx decode Co8BCowBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEmwKLWNvc21vczFsN
|
||||
|
||||
More information about the `decode` command can be found running `simd tx decode --help`.
|
||||
|
||||
##### `aux-to-fee`
|
||||
#### `aux-to-fee`
|
||||
|
||||
The `aux-to-fee` comamnds includes the aux signer data in the tx, broadcast the tx, and sends the tip amount to the broadcaster.
|
||||
[Learn more about tip transaction](https://docs.cosmos.network/main/core/tips).
|
||||
|
||||
@ -1,194 +0,0 @@
|
||||
# x/auth
|
||||
|
||||
The `x/auth` module is responsible for specifying the base transaction and
|
||||
account types for an application, as well as AnteHandler and authentication logic.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Import the module.
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/cosmos/cosmos-sdk/x/auth"
|
||||
)
|
||||
```
|
||||
|
||||
2. Add `AppModuleBasic` to your `ModuleBasics`.
|
||||
|
||||
```go
|
||||
var (
|
||||
ModuleBasics = module.NewBasicManager(
|
||||
// ...
|
||||
auth.AppModuleBasic{},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
3. Create the module's parameter subspace in your application constructor.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.subspaces[auth.ModuleName] = app.ParamsKeeper.Subspace(auth.DefaultParamspace)
|
||||
}
|
||||
```
|
||||
|
||||
4. Create the keeper.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.AccountKeeper = auth.NewAccountKeeper(
|
||||
app.cdc, keys[auth.StoreKey], app.subspaces[auth.ModuleName], auth.ProtoBaseAccount,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
5. Add the `x/auth` module to the app's `ModuleManager`.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.mm = module.NewManager(
|
||||
// ...
|
||||
auth.NewAppModule(app.AccountKeeper),
|
||||
// ...
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
6. Set the `x/auth` module genesis order.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.mm.SetOrderInitGenesis(..., auth.ModuleName, ...)
|
||||
}
|
||||
```
|
||||
|
||||
7. Add the `x/auth` module to the simulation manager (if you have one set).
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.sm = module.NewSimulationManager(
|
||||
// ...
|
||||
auth.NewAppModule(app.AccountKeeper),
|
||||
// ...
|
||||
)
|
||||
}
|
||||
|
||||
8. Set the `AnteHandler` if you're using the default provided by `x/auth`. Note,
|
||||
the default `AnteHandler` provided by the `x/auth` module depends on the `x/supply`
|
||||
module.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
app.SetAnteHandler(ante.NewAnteHandler(
|
||||
app.AccountKeeper,
|
||||
app.SupplyKeeper,
|
||||
auth.DefaultSigVerificationGasConsumer,
|
||||
))
|
||||
}
|
||||
```
|
||||
|
||||
### Vesting Accounts
|
||||
|
||||
The `x/auth` modules also defines a few standard vesting account types under the
|
||||
`vesting` sub-package. In order to get your application to automatically support
|
||||
these in terms of encoding and decoding, you must register the types with your
|
||||
application Amino codec.
|
||||
|
||||
Where ever you define the application `Codec`, be sure to register types via:
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/cosmos/cosmos-sdk/x/auth/vesting"
|
||||
)
|
||||
|
||||
func MakeCodec() *codec.Codec {
|
||||
var cdc = codec.New()
|
||||
|
||||
// ...
|
||||
vesting.RegisterCodec(cdc)
|
||||
// ...
|
||||
|
||||
return cdc
|
||||
}
|
||||
```
|
||||
|
||||
## Genesis
|
||||
|
||||
The `x/auth` module defines its genesis state as follows:
|
||||
|
||||
```go
|
||||
type GenesisState struct {
|
||||
Params Params `json:"params" yaml:"params"`
|
||||
Accounts exported.GenesisAccounts `json:"accounts" yaml:"accounts"`
|
||||
}
|
||||
```
|
||||
|
||||
Which relies on the following types:
|
||||
|
||||
```go
|
||||
type Account interface {
|
||||
GetAddress() sdk.AccAddress
|
||||
SetAddress(sdk.AccAddress) error
|
||||
GetPubKey() crypto.PubKey
|
||||
SetPubKey(crypto.PubKey) error
|
||||
GetAccountNumber() uint64
|
||||
SetAccountNumber(uint64) error
|
||||
GetSequence() uint64
|
||||
SetSequence(uint64) error
|
||||
GetCoins() sdk.Coins
|
||||
SetCoins(sdk.Coins) error
|
||||
SpendableCoins(blockTime time.Time) sdk.Coins
|
||||
String() string
|
||||
}
|
||||
|
||||
type Params struct {
|
||||
MaxMemoCharacters uint64 `json:"max_memo_characters" yaml:"max_memo_characters"`
|
||||
TxSigLimit uint64 `json:"tx_sig_limit" yaml:"tx_sig_limit"`
|
||||
TxSizeCostPerByte uint64 `json:"tx_size_cost_per_byte" yaml:"tx_size_cost_per_byte"`
|
||||
SigVerifyCostED25519 uint64 `json:"sig_verify_cost_ed25519" yaml:"sig_verify_cost_ed25519"`
|
||||
SigVerifyCostSecp256k1 uint64 `json:"sig_verify_cost_secp256k1" yaml:"sig_verify_cost_secp256k1"`
|
||||
}
|
||||
```
|
||||
|
||||
## Client
|
||||
|
||||
### CLI
|
||||
|
||||
The `x/auth` module provides various auxiliary CLI commands and a few that are
|
||||
part of the module itself via the `ModuleManager`. The commands that are part of
|
||||
the module itself are defined below:
|
||||
|
||||
1. Query an account.
|
||||
|
||||
```shell
|
||||
app q auth account [address] [...flags]
|
||||
```
|
||||
|
||||
2. Sign an unsigned transaction using a single signature.
|
||||
|
||||
```shell
|
||||
app tx auth sign [file]
|
||||
```
|
||||
|
||||
3. Sign an unsigned transaction using a multisig.
|
||||
|
||||
```shell
|
||||
app tx auth multisign [file] [name] [[signature]...]
|
||||
```
|
||||
|
||||
### REST
|
||||
|
||||
The `x/auth` module provides various auxiliary REST handlers and a few that are
|
||||
part of the module itself via the `ModuleManager`. The endpoints that are part of
|
||||
the module itself are defined below:
|
||||
|
||||
1. Query an account.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :----------------------- |
|
||||
| `GET` | `/auth/accounts/{address}` |
|
||||
@ -1,33 +0,0 @@
|
||||
[module]
|
||||
description = "The auth module is responsible for specifying the base transaction and account types for an application, as well as AnteHandler and authentication logic."
|
||||
homepage = "https://github.com/cosmos/cosmos-sdk"
|
||||
keywords = [
|
||||
"authentication",
|
||||
"signatures",
|
||||
"ante",
|
||||
"transactions",
|
||||
"accounts",
|
||||
]
|
||||
|
||||
name = "x/auth"
|
||||
|
||||
[bug_tracker]
|
||||
url = "https://github.com/cosmos/cosmos-sdk/issues"
|
||||
|
||||
[[authors]]
|
||||
name = "alexanderbez"
|
||||
|
||||
[[authors]]
|
||||
name = "fedekunze"
|
||||
|
||||
[[authors]]
|
||||
name = "cwgoes"
|
||||
|
||||
[[authors]]
|
||||
name = "alessio"
|
||||
|
||||
[version]
|
||||
documentation = "https://raw.githubusercontent.com/cosmos/cosmos-sdk/master/x/auth/atlas/atlas-v0.39.1.md"
|
||||
repo = "https://github.com/cosmos/cosmos-sdk/releases/tag/v0.39.2"
|
||||
sdk_compat = "v0.39.x"
|
||||
version = "v0.39.2"
|
||||
@ -1,208 +0,0 @@
|
||||
# x/bank
|
||||
|
||||
The `x/bank` module is responsible for handling multi-asset coin transfers between
|
||||
accounts and tracking special-case pseudo-transfers which must work differently
|
||||
with particular kinds of accounts.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Import the module.
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/cosmos/cosmos-sdk/x/bank"
|
||||
)
|
||||
```
|
||||
|
||||
2. Add `AppModuleBasic` to your `ModuleBasics`.
|
||||
|
||||
```go
|
||||
var (
|
||||
ModuleBasics = module.NewBasicManager(
|
||||
// ...
|
||||
bank.AppModuleBasic{},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
3. Create the module's parameter subspace in your application constructor.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.subspaces[bank.ModuleName] = app.ParamsKeeper.Subspace(bank.DefaultParamspace)
|
||||
}
|
||||
```
|
||||
|
||||
4. Create the keeper. Note, the `x/bank` module depends on the `x/auth` module
|
||||
and a list of blocklisted account addresses which funds are not allowed to be
|
||||
sent to. Your application will need to define this method based your needs.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.BankKeeper = bank.NewBaseKeeper(
|
||||
app.AccountKeeper, app.subspaces[bank.ModuleName], app.BlocklistedAccAddrs(),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
5. Add the `x/bank` module to the app's `ModuleManager`.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.mm = module.NewManager(
|
||||
// ...
|
||||
bank.NewAppModule(app.BankKeeper, app.AccountKeeper),
|
||||
// ...
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
6. Set the `x/bank` module genesis order.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.mm.SetOrderInitGenesis(..., bank.ModuleName, ...)
|
||||
}
|
||||
```
|
||||
|
||||
7. Add the `x/bank` module to the simulation manager (if you have one set).
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.sm = module.NewSimulationManager(
|
||||
// ...
|
||||
bank.NewAppModule(app.BankKeeper, app.AccountKeeper),
|
||||
// ...
|
||||
)
|
||||
}
|
||||
|
||||
## Genesis
|
||||
|
||||
The `x/bank` module defines its genesis state as follows:
|
||||
|
||||
```go
|
||||
type GenesisState struct {
|
||||
SendEnabled bool `json:"send_enabled" yaml:"send_enabled"`
|
||||
}
|
||||
```
|
||||
|
||||
The `SendEnabled` parameter determines if transfers are enabled or disabled
|
||||
entirely on the chain. This can be used to start a network without enabling
|
||||
transfers while ensuring critical network functionality is operating as expected.
|
||||
|
||||
## Messages
|
||||
|
||||
### `MsgSend`
|
||||
|
||||
The `x/bank` module allows for transfer of funds from a source account to a
|
||||
destination account.
|
||||
|
||||
```go
|
||||
type MsgSend struct {
|
||||
FromAddress sdk.AccAddress `json:"from_address" yaml:"from_address"`
|
||||
ToAddress sdk.AccAddress `json:"to_address" yaml:"to_address"`
|
||||
Amount sdk.Coins `json:"amount" yaml:"amount"`
|
||||
}
|
||||
```
|
||||
|
||||
### `MsgMultiSend`
|
||||
|
||||
The `x/bank` module also allows for multiple inputs and outputs. The sum of all
|
||||
inputs must be equivalent to the sum of all outputs.
|
||||
|
||||
```go
|
||||
type Input struct {
|
||||
Address sdk.AccAddress `json:"address" yaml:"address"`
|
||||
Coins sdk.Coins `json:"coins" yaml:"coins"`
|
||||
}
|
||||
|
||||
type Output struct {
|
||||
Address sdk.AccAddress `json:"address" yaml:"address"`
|
||||
Coins sdk.Coins `json:"coins" yaml:"coins"`
|
||||
}
|
||||
|
||||
type MsgMultiSend struct {
|
||||
Inputs []Input `json:"inputs" yaml:"inputs"`
|
||||
Outputs []Output `json:"outputs" yaml:"outputs"`
|
||||
}
|
||||
```
|
||||
|
||||
## Client
|
||||
|
||||
### CLI
|
||||
|
||||
The `x/bank` supports the following transactional commands.
|
||||
|
||||
1. Send tokens via a `MsgSend` message.
|
||||
|
||||
```sh
|
||||
app tx send [from_key_or_address] [to_address] [amount] [...flags]
|
||||
```
|
||||
|
||||
Note, the `x/bank` module does not natively support constructing a `MsgMultiSend`
|
||||
message. This type of message must be constructed manually, but it may be signed
|
||||
and broadcasted via the CLI.
|
||||
|
||||
### REST
|
||||
|
||||
The `x/bank` supports various query API endpoints and a `MsgSend` construction
|
||||
endpoint.
|
||||
|
||||
1. Construct an unsigned `MsgSend` transaction.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :----------------------------------- |
|
||||
| `POST` | `/bank/accounts/{address}/transfers` |
|
||||
|
||||
Sample payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"base_req": {
|
||||
"chain_id": "chain-foo",
|
||||
"from": "cosmos1u3fneykx9carelvurc6av22vpjvptytj9wklk0",
|
||||
"memo": "memo",
|
||||
"fees": [
|
||||
{
|
||||
"denom": "stake",
|
||||
"amount": "25000"
|
||||
}
|
||||
]
|
||||
},
|
||||
"amount": [
|
||||
{
|
||||
"denom": "stake",
|
||||
"amount": "400000000"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. Query for an account's balance.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :------------------------- |
|
||||
| `GET` | `/bank/balances/{address}` |
|
||||
|
||||
Sample response:
|
||||
|
||||
```json
|
||||
{
|
||||
"height": "0",
|
||||
"result": [
|
||||
{
|
||||
"denom": "node0token",
|
||||
"amount": "1000000000"
|
||||
},
|
||||
{
|
||||
"denom": "stake",
|
||||
"amount": "400000000"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@ -1,34 +0,0 @@
|
||||
[module]
|
||||
description = "The bank module is responsible for handling multi-asset coin transfers between accounts and tracking special-case pseudo-transfers which must work differently with particular kinds of accounts."
|
||||
homepage = "https://github.com/cosmos/cosmos-sdk"
|
||||
keywords = [
|
||||
"tokens",
|
||||
"bank",
|
||||
"transfer",
|
||||
"asset",
|
||||
"fungible",
|
||||
"coins",
|
||||
]
|
||||
|
||||
name = "x/bank"
|
||||
|
||||
[bug_tracker]
|
||||
url = "https://github.com/cosmos/cosmos-sdk/issues"
|
||||
|
||||
[[authors]]
|
||||
name = "alexanderbez"
|
||||
|
||||
[[authors]]
|
||||
name = "fedekunze"
|
||||
|
||||
[[authors]]
|
||||
name = "cwgoes"
|
||||
|
||||
[[authors]]
|
||||
name = "alessio"
|
||||
|
||||
[version]
|
||||
documentation = "https://raw.githubusercontent.com/cosmos/cosmos-sdk/master/x/bank/atlas/atlas-v0.39.1.md"
|
||||
repo = "https://github.com/cosmos/cosmos-sdk/releases/tag/v0.39.2"
|
||||
sdk_compat = "v0.39.x"
|
||||
version = "v0.39.2"
|
||||
@ -1,167 +0,0 @@
|
||||
# x/evidence
|
||||
|
||||
The `x/evidence` module is responsible for handling multi-asset coin transfers between
|
||||
accounts and tracking special-case pseudo-transfers which must work differently
|
||||
with particular kinds of accounts.
|
||||
|
||||
## Usage
|
||||
|
||||
1. Import the module.
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/cosmos/cosmos-sdk/x/evidence"
|
||||
evidencekeeper "github.com/cosmos/cosmos-sdk/x/evidence/keeper"
|
||||
evidencetypes "github.com/cosmos/cosmos-sdk/x/evidence/types"
|
||||
)
|
||||
```
|
||||
|
||||
2. Add `AppModuleBasic` to your `ModuleBasics`.
|
||||
|
||||
```go
|
||||
var (
|
||||
ModuleBasics = module.NewBasicManager(
|
||||
// ...
|
||||
evidence.AppModuleBasic{},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
3. Add the evidence keeper to your apps struct.
|
||||
|
||||
```go
|
||||
type app struct {
|
||||
// ...
|
||||
EvidenceKeeper evidencekeeper.Keeper
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
4. Add the evidence store key to the group of store keys.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
keys := sdk.NewKVStoreKeys(
|
||||
evidencetypes.StoreKey,
|
||||
)
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
5. Create the keeper. Note, the `x/evidence` module depends on the `x/staking` and `x/slashing` modules. Evidence has expected interfaces, these interfaces are linked to slashing and staking. You can find these interfaces [here](https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/x/evidence/types/expected_keepers.go)
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
// create evidence keeper with router
|
||||
evidenceKeeper := evidencekeeper.NewKeeper(
|
||||
appCodec, keys[evidencetypes.StoreKey], &app.StakingKeeper, app.SlashingKeeper,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
6. Add the `x/evidence` module to the app's `ModuleManager`.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.mm = module.NewManager(
|
||||
// ...
|
||||
evidence.NewAppModule(app.EvidenceKeeper),
|
||||
// ...
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
7. Set the `x/evidence` module begin blocker order.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.mm.SetOrderBeginBlockers(
|
||||
// ...
|
||||
evidencetypes.ModuleName,
|
||||
// ...
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
8. Set the `x/evidence` module genesis order.
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.mm.SetOrderInitGenesis(..., evidencetypes.ModuleName, ...)
|
||||
}
|
||||
```
|
||||
|
||||
9. Add the `x/evidence` module to the simulation manager (if you have one set).
|
||||
|
||||
```go
|
||||
func NewApp(...) *App {
|
||||
// ...
|
||||
app.sm = module.NewSimulationManager(
|
||||
// ...
|
||||
evidence.NewAppModule(app.EvidenceKeeper),
|
||||
// ...
|
||||
)
|
||||
}
|
||||
|
||||
## Genesis
|
||||
|
||||
The `x/evidence` module defines its genesis state as follows:
|
||||
|
||||
```proto
|
||||
type GenesisState struct {
|
||||
// evidence defines all the evidence at genesis.
|
||||
Evidence []*types.Any `protobuf:"bytes,1,rep,name=evidence,proto3" json:"evidence,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
## Messages
|
||||
<!-- todo: change to v0.41 when its available -->
|
||||
|
||||
View supported messages at [docs.cosmos.network/v0.40/modules/evidence](https://docs.cosmos.network/v0.40/modules/evidence/03_messages.html)
|
||||
|
||||
## Client
|
||||
|
||||
Evidence supports querying of old evidence and submission of new evidence. There are two queries. One for all the evidence, and one for a specific piece of evidence.
|
||||
|
||||
### CLI
|
||||
|
||||
The evidence module supports the blow command to query evidence.
|
||||
|
||||
```sh
|
||||
Usage:
|
||||
app query evidence [flags]
|
||||
|
||||
Flags:
|
||||
--count-total count total number of records in evidence to query for
|
||||
--height int Use a specific height to query state at (this can error if the node is pruning state)
|
||||
-h, --help help for evidence
|
||||
--limit uint pagination limit of evidence to query for (default 100)
|
||||
--node string <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
|
||||
--offset uint pagination offset of evidence to query for
|
||||
-o, --output string Output format (text|json) (default "text")
|
||||
--page uint pagination page of evidence to query for. This sets offset to a multiple of limit (default 1)
|
||||
--page-key string pagination page-key of evidence to query for
|
||||
```
|
||||
|
||||
### REST
|
||||
|
||||
Evidence REST API supports only queries of evidence. To submit evidence please use gRPC or the cli.
|
||||
|
||||
### gRPC
|
||||
|
||||
Evidence supports both querying and submitting transactions via gRPC
|
||||
|
||||
#### Query
|
||||
|
||||
[gRPC query](https://docs.cosmos.network/master/core/proto-docs.html#cosmos/evidence/v1beta1/query.proto)
|
||||
|
||||
#### Tx
|
||||
|
||||
[gRPC Tx](https://docs.cosmos.network/master/core/proto-docs.html#cosmos-evidence-v1beta1-tx-proto)
|
||||
|
||||
View supported messages at [docs.cosmos.network/v0.40/modules/evidence](https://docs.cosmos.network/v0.40/modules/evidence/03_messages.html)
|
||||
@ -1,48 +0,0 @@
|
||||
[module]
|
||||
# Name of the module. (Required)
|
||||
name = "x/evidence"
|
||||
|
||||
# Description of the module. (Optional)
|
||||
description = "The evidence module is responsible for storing and handling evidence of misbeaviour."
|
||||
|
||||
# Link to where the module is located, it can also be a link to your project. (Optional)
|
||||
homepage = "https://github.com/cosmos/cosmos-sdk"
|
||||
|
||||
#List of key words describing your module (Optional)
|
||||
keywords = [
|
||||
"evidence",
|
||||
"misbeaviour",
|
||||
"accountability"
|
||||
]
|
||||
|
||||
|
||||
[bug_tracker]
|
||||
# A URL to a site that provides information or guidance on how to submit or deal
|
||||
# with security vulnerabilities and bug reports.
|
||||
url = "https://github.com/cosmos/cosmos-sdk/issues"
|
||||
|
||||
# To list multiple authors, multiple [[authors]] need to be created
|
||||
[[authors]]
|
||||
# Name of one of the authors. Typically their Github name. (Required)
|
||||
name = "alexanderbez"
|
||||
|
||||
[[authors]]
|
||||
name = "fedekunze"
|
||||
|
||||
[[authors]]
|
||||
name = "aaronc"
|
||||
|
||||
[version]
|
||||
# The repository field should be a URL to the source repository for your module.
|
||||
# Typically, this will point to the specific GitHub repository release/tag for the
|
||||
# module, although this is not enforced or required. (Required)
|
||||
repo = "https://github.com/cosmos/cosmos-sdk"
|
||||
|
||||
# The documentation field specifies a URL to a website hosting the module's documentation. (Optional)
|
||||
documentation = "https://raw.githubusercontent.com/cosmos/cosmos-sdk/master/x/evidence/atlas/atlas-v0.41.x.md"
|
||||
|
||||
# The module version to be published. (Required)
|
||||
version = "v0.41"
|
||||
|
||||
# An optional Cosmos SDK version compatibility may be provided. (Optional)
|
||||
sdk_compat = "v0.41"
|
||||
@ -23,6 +23,8 @@ network.
|
||||
* [State](#state)
|
||||
* [Pool](#pool)
|
||||
* [LastTotalPower](#lasttotalpower)
|
||||
* [ValidatorUpdates](#validatorupdates)
|
||||
* [UnbondingID](#unbondingid)
|
||||
* [Params](#params)
|
||||
* [Validator](#validator)
|
||||
* [Delegation](#delegation)
|
||||
@ -47,6 +49,7 @@ network.
|
||||
* [Historical Info Tracking](#historical-info-tracking)
|
||||
* [End-Block](#end-block)
|
||||
* [Validator Set Changes](#validator-set-changes)
|
||||
* [Queues](#queues-1)
|
||||
* [Hooks](#hooks)
|
||||
* [Events](#events)
|
||||
* [EndBlocker](#endblocker)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user