chore: rename develop to learn (#17821)
This commit is contained in:
Marko
@@ -0,0 +1,277 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Anatomy of a Cosmos SDK Application
|
||||
|
||||
:::note Synopsis
|
||||
This document describes the core parts of a Cosmos SDK application, represented throughout the document as a placeholder application named `app`.
|
||||
:::
|
||||
|
||||
## Node Client
|
||||
|
||||
The Daemon, or [Full-Node Client](../advanced/03-node.md), is the core process of a Cosmos SDK-based blockchain. Participants in the network run this process to initialize their state-machine, connect with other full-nodes, and update their state-machine as new blocks come in.
|
||||
|
||||
```text
|
||||
^ +-------------------------------+ ^
|
||||
| | | |
|
||||
| | State-machine = Application | |
|
||||
| | | | Built with Cosmos SDK
|
||||
| | ^ + | |
|
||||
| +----------- | ABCI | ----------+ v
|
||||
| | + v | ^
|
||||
| | | |
|
||||
Blockchain Node | | Consensus | |
|
||||
| | | |
|
||||
| +-------------------------------+ | CometBFT
|
||||
| | | |
|
||||
| | Networking | |
|
||||
| | | |
|
||||
v +-------------------------------+ v
|
||||
```
|
||||
|
||||
The blockchain full-node presents itself as a binary, generally suffixed by `-d` for "daemon" (e.g. `appd` for `app` or `gaiad` for `gaia`). This binary is built by running a simple [`main.go`](../advanced/03-node.md#main-function) function placed in `./cmd/appd/`. This operation usually happens through the [Makefile](#dependencies-and-makefile).
|
||||
|
||||
Once the main binary is built, the node can be started by running the [`start` command](../advanced/03-node.md#start-command). This command function primarily does three things:
|
||||
|
||||
1. Create an instance of the state-machine defined in [`app.go`](#core-application-file).
|
||||
2. Initialize the state-machine with the latest known state, extracted from the `db` stored in the `~/.app/data` folder. At this point, the state-machine is at height `appBlockHeight`.
|
||||
3. Create and start a new CometBFT instance. Among other things, the node performs a handshake with its peers. It gets the latest `blockHeight` from them and replays blocks to sync to this height if it is greater than the local `appBlockHeight`. The node starts from genesis and CometBFT sends an `InitChain` message via the ABCI to the `app`, which triggers the [`InitChainer`](#initchainer).
|
||||
|
||||
:::note
|
||||
When starting a CometBFT instance, the genesis file is the `0` height and the state within the genesis file is committed at block height `1`. When querying the state of the node, querying block height 0 will return an error.
|
||||
:::
|
||||
|
||||
## Core Application File
|
||||
|
||||
In general, the core of the state-machine is defined in a file called `app.go`. This file mainly contains the **type definition of the application** and functions to **create and initialize it**.
|
||||
|
||||
### Type Definition of the Application
|
||||
|
||||
The first thing defined in `app.go` is the `type` of the application. It is generally comprised of the following parts:
|
||||
|
||||
* **A reference to [`baseapp`](../advanced/00-baseapp.md).** The custom application defined in `app.go` is an extension of `baseapp`. When a transaction is relayed by CometBFT to the application, `app` uses `baseapp`'s methods to route them to the appropriate module. `baseapp` implements most of the core logic for the application, including all the [ABCI methods](https://docs.cometbft.com/v0.37/spec/abci/) and the [routing logic](../advanced/00-baseapp.md#routing).
|
||||
* **A list of store keys**. The [store](../advanced/04-store.md), which contains the entire state, is implemented as a [`multistore`](../advanced/04-store.md#multistore) (i.e. a store of stores) in the Cosmos SDK. Each module uses one or multiple stores in the multistore to persist their part of the state. These stores can be accessed with specific keys that are declared in the `app` type. These keys, along with the `keepers`, are at the heart of the [object-capabilities model](../advanced/10-ocap.md) of the Cosmos SDK.
|
||||
* **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../../build/building-modules/06-keeper.md), which handles reads and writes for this module's store(s). The `keeper`'s methods of one module can be called from other modules (if authorized), which is why they are declared in the application's type and exported as interfaces to other modules so that the latter can only access the authorized functions.
|
||||
* **A reference to an [`appCodec`](../advanced/05-encoding.md).** The application's `appCodec` is used to serialize and deserialize data structures in order to store them, as stores can only persist `[]bytes`. The default codec is [Protocol Buffers](../advanced/05-encoding.md).
|
||||
* **A reference to a [`legacyAmino`](../advanced/05-encoding.md) codec.** Some parts of the Cosmos SDK have not been migrated to use the `appCodec` above, and are still hardcoded to use Amino. Other parts explicitly use Amino for backwards compatibility. For these reasons, the application still holds a reference to the legacy Amino codec. Please note that the Amino codec will be removed from the SDK in the upcoming releases.
|
||||
* **A reference to a [module manager](../../build/building-modules/01-module-manager.md#manager)** and a [basic module manager](../../build/building-modules/01-module-manager.md#basicmanager). The module manager is an object that contains a list of the application's modules. It facilitates operations related to these modules, like registering their [`Msg` service](../advanced/00-baseapp.md#msg-services) and [gRPC `Query` service](../advanced/00-baseapp.md#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`PreBlocker`](#preblocker) and [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker).
|
||||
|
||||
See an example of application type definition from `simapp`, the Cosmos SDK's own app used for demo and testing purposes:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L173-L212
|
||||
```
|
||||
|
||||
### Constructor Function
|
||||
|
||||
Also defined in `app.go` is the constructor function, which constructs a new application of the type defined in the preceding section. The function must fulfill the `AppCreator` signature in order to be used in the [`start` command](../advanced/03-node.md#start-command) of the application's daemon command.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L66-L68
|
||||
```
|
||||
|
||||
Here are the main actions performed by this function:
|
||||
|
||||
* Instantiate a new [`codec`](../advanced/05-encoding.md) and initialize the `codec` of each of the application's modules using the [basic manager](../../build/building-modules/01-module-manager.md#basicmanager).
|
||||
* Instantiate a new application with a reference to a `baseapp` instance, a codec, and all the appropriate store keys.
|
||||
* Instantiate all the [`keeper`](#keeper) objects defined in the application's `type` using the `NewKeeper` function of each of the application's modules. Note that keepers must be instantiated in the correct order, as the `NewKeeper` of one module might require a reference to another module's `keeper`.
|
||||
* Instantiate the application's [module manager](../../build/building-modules/01-module-manager.md#manager) with the [`AppModule`](#application-module-interface) object of each of the application's modules.
|
||||
* With the module manager, initialize the application's [`Msg` services](../advanced/00-baseapp.md#msg-services), [gRPC `Query` services](../advanced/00-baseapp.md#grpc-query-services), [legacy `Msg` routes](../advanced/00-baseapp.md#routing), and [legacy query routes](../advanced/00-baseapp.md#query-routing). When a transaction is relayed to the application by CometBFT via the ABCI, it is routed to the appropriate module's [`Msg` service](#msg-services) using the routes defined here. Likewise, when a gRPC query request is received by the application, it is routed to the appropriate module's [`gRPC query service`](#grpc-query-services) using the gRPC routes defined here. The Cosmos SDK still supports legacy `Msg`s and legacy CometBFT queries, which are routed using the legacy `Msg` routes and the legacy query routes, respectively.
|
||||
* With the module manager, register the [application's modules' invariants](../../build/building-modules/07-invariants.md). Invariants are variables (e.g. total supply of a token) that are evaluated at the end of each block. The process of checking invariants is done via a special module called the [`InvariantsRegistry`](../../build/building-modules/07-invariants.md#invariant-registry). The value of the invariant should be equal to a predicted value defined in the module. Should the value be different than the predicted one, special logic defined in the invariant registry is triggered (usually the chain is halted). This is useful to make sure that no critical bug goes unnoticed, producing long-lasting effects that are hard to fix.
|
||||
* With the module manager, set the order of execution between the `InitGenesis`, `PreBlocker`, `BeginBlocker`, and `EndBlocker` functions of each of the [application's modules](#application-module-interface). Note that not all modules implement these functions.
|
||||
* Set the remaining application parameters:
|
||||
* [`InitChainer`](#initchainer): used to initialize the application when it is first started.
|
||||
* [`PreBlocker`](#preblocker): called before BeginBlock.
|
||||
* [`BeginBlocker`, `EndBlocker`](#beginblocker-and-endblocker): called at the beginning and at the end of every block.
|
||||
* [`anteHandler`](../advanced/00-baseapp.md#antehandler): used to handle fees and signature verification.
|
||||
* Mount the stores.
|
||||
* Return the application.
|
||||
|
||||
Note that the constructor function only creates an instance of the app, while the actual state is either carried over from the `~/.app/data` folder if the node is restarted, or generated from the genesis file if the node is started for the first time.
|
||||
|
||||
See an example of application constructor from `simapp`:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L223-L575
|
||||
```
|
||||
|
||||
### InitChainer
|
||||
|
||||
The `InitChainer` is a function that initializes the state of the application from a genesis file (i.e. token balances of genesis accounts). It is called when the application receives the `InitChain` message from the CometBFT engine, which happens when the node is started at `appBlockHeight == 0` (i.e. on genesis). The application must set the `InitChainer` in its [constructor](#constructor-function) via the [`SetInitChainer`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetInitChainer) method.
|
||||
|
||||
In general, the `InitChainer` is mostly composed of the [`InitGenesis`](../../build/building-modules/08-genesis.md#initgenesis) function of each of the application's modules. This is done by calling the `InitGenesis` function of the module manager, which in turn calls the `InitGenesis` function of each of the modules it contains. Note that the order in which the modules' `InitGenesis` functions must be called has to be set in the module manager using the [module manager's](../../build/building-modules/01-module-manager.md) `SetOrderInitGenesis` method. This is done in the [application's constructor](#application-constructor), and the `SetOrderInitGenesis` has to be called before the `SetInitChainer`.
|
||||
|
||||
See an example of an `InitChainer` from `simapp`:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L626-L634
|
||||
```
|
||||
|
||||
### PreBlocker
|
||||
|
||||
There are two semantics around the new lifecycle method:
|
||||
|
||||
- It runs before the `BeginBlocker` of all modules
|
||||
- It can modify consensus parameters in storage, and signal the caller through the return value.
|
||||
|
||||
When it returns `ConsensusParamsChanged=true`, the caller must refresh the consensus parameter in the finalize context:
|
||||
```
|
||||
app.finalizeBlockState.ctx = app.finalizeBlockState.ctx.WithConsensusParams(app.GetConsensusParams())
|
||||
```
|
||||
The new ctx must be passed to all the other lifecycle methods.
|
||||
|
||||
### BeginBlocker and EndBlocker
|
||||
|
||||
The Cosmos SDK offers developers the possibility to implement automatic execution of code as part of their application. This is implemented through two functions called `BeginBlocker` and `EndBlocker`. They are called when the application receives the `FinalizeBlock` messages from the CometBFT consensus engine, which happens respectively at the beginning and at the end of each block. The application must set the `BeginBlocker` and `EndBlocker` in its [constructor](#constructor-function) via the [`SetBeginBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetBeginBlocker) and [`SetEndBlocker`](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetEndBlocker) methods.
|
||||
|
||||
In general, the `BeginBlocker` and `EndBlocker` functions are mostly composed of the [`BeginBlock` and `EndBlock`](../../build/building-modules/06-beginblock-endblock.md) functions of each of the application's modules. This is done by calling the `BeginBlock` and `EndBlock` functions of the module manager, which in turn calls the `BeginBlock` and `EndBlock` functions of each of the modules it contains. Note that the order in which the modules' `BeginBlock` and `EndBlock` functions must be called has to be set in the module manager using the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods, respectively. This is done via the [module manager](../../build/building-modules/01-module-manager.md) in the [application's constructor](#application-constructor), and the `SetOrderBeginBlockers` and `SetOrderEndBlockers` methods have to be called before the `SetBeginBlocker` and `SetEndBlocker` functions.
|
||||
|
||||
As a sidenote, it is important to remember that application-specific blockchains are deterministic. Developers must be careful not to introduce non-determinism in `BeginBlocker` or `EndBlocker`, and must also be careful not to make them too computationally expensive, as [gas](./04-gas-fees.md) does not constrain the cost of `BeginBlocker` and `EndBlocker` execution.
|
||||
|
||||
See an example of `BeginBlocker` and `EndBlocker` functions from `simapp`
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L613-L620
|
||||
```
|
||||
|
||||
### Register Codec
|
||||
|
||||
The `EncodingConfig` structure is the last important part of the `app.go` file. The goal of this structure is to define the codecs that will be used throughout the app.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/params/encoding.go#L9-L16
|
||||
```
|
||||
|
||||
Here are descriptions of what each of the four fields means:
|
||||
|
||||
* `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces that are encoded and decoded (we also say "unpacked") using [`google.protobuf.Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto). `Any` could be thought as a struct that contains a `type_url` (name of a concrete type implementing the interface) and a `value` (its encoded bytes). `InterfaceRegistry` provides a mechanism for registering interfaces and implementations that can be safely unpacked from `Any`. Each application module implements the `RegisterInterfaces` method that can be used to register the module's own interfaces and implementations.
|
||||
* You can read more about `Any` in [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md).
|
||||
* To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/cosmos/gogoproto). By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/cosmos/gogoproto/types) uses [global type registration](https://github.com/cosmos/gogoproto/blob/master/proto/properties.go#L540) to decode values packed in `Any` into concrete Go types. This introduces a vulnerability where any malicious module in the dependency tree could register a type with the global protobuf registry and cause it to be loaded and unmarshaled by a transaction that referenced it in the `type_url` field. For more information, please refer to [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md).
|
||||
* `Codec`: The default codec used throughout the Cosmos SDK. It is composed of a `BinaryCodec` used to encode and decode state, and a `JSONCodec` used to output data to the users (for example, in the [CLI](#cli)). By default, the SDK uses Protobuf as `Codec`.
|
||||
* `TxConfig`: `TxConfig` defines an interface a client can utilize to generate an application-defined concrete transaction type. Currently, the SDK handles two transaction types: `SIGN_MODE_DIRECT` (which uses Protobuf binary as over-the-wire encoding) and `SIGN_MODE_LEGACY_AMINO_JSON` (which depends on Amino). Read more about transactions [here](../advanced/01-transactions.md).
|
||||
* `Amino`: Some legacy parts of the Cosmos SDK still use Amino for backwards-compatibility. Each module exposes a `RegisterLegacyAmino` method to register the module's specific types within Amino. This `Amino` codec should not be used by app developers anymore, and will be removed in future releases.
|
||||
|
||||
An application should create its own encoding config.
|
||||
See an example of a `simappparams.EncodingConfig` from `simapp`:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/params/encoding.go#L11-L16
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
[Modules](../../build/building-modules/00-intro.md) are the heart and soul of Cosmos SDK applications. They can be considered as state-machines nested within the state-machine. When a transaction is relayed from the underlying CometBFT engine via the ABCI to the application, it is routed by [`baseapp`](../advanced/00-baseapp.md) to the appropriate module in order to be processed. This paradigm enables developers to easily build complex state-machines, as most of the modules they need often already exist. **For developers, most of the work involved in building a Cosmos SDK application revolves around building custom modules required by their application that do not exist yet, and integrating them with modules that do already exist into one coherent application**. In the application directory, the standard practice is to store modules in the `x/` folder (not to be confused with the Cosmos SDK's `x/` folder, which contains already-built modules).
|
||||
|
||||
### Application Module Interface
|
||||
|
||||
Modules must implement [interfaces](../../build/building-modules/01-module-manager.md#application-module-interfaces) defined in the Cosmos SDK, [`AppModuleBasic`](../../build/building-modules/01-module-manager.md#appmodulebasic) and [`AppModule`](../../build/building-modules/01-module-manager.md#appmodule). The former implements basic non-dependent elements of the module, such as the `codec`, while the latter handles the bulk of the module methods (including methods that require references to other modules' `keeper`s). Both the `AppModule` and `AppModuleBasic` types are, by convention, defined in a file called `module.go`.
|
||||
|
||||
`AppModule` exposes a collection of useful methods on the module that facilitates the composition of modules into a coherent application. These methods are called from the [`module manager`](../../build/building-modules/01-module-manager.md#manager), which manages the application's collection of modules.
|
||||
|
||||
### `Msg` Services
|
||||
|
||||
Each application module defines two [Protobuf services](https://developers.google.com/protocol-buffers/docs/proto#services): one `Msg` service to handle messages, and one gRPC `Query` service to handle queries. If we consider the module as a state-machine, then a `Msg` service is a set of state transition RPC methods.
|
||||
Each Protobuf `Msg` service method is 1:1 related to a Protobuf request type, which must implement `sdk.Msg` interface.
|
||||
Note that `sdk.Msg`s are bundled in [transactions](../advanced/01-transactions.md), and each transaction contains one or multiple messages.
|
||||
|
||||
When a valid block of transactions is received by the full-node, CometBFT relays each one to the application via [`DeliverTx`](https://docs.cometbft.com/v0.37/spec/abci/abci++_app_requirements#specifics-of-responsedelivertx). Then, the application handles the transaction:
|
||||
|
||||
1. Upon receiving the transaction, the application first unmarshalls it from `[]byte`.
|
||||
2. Then, it verifies a few things about the transaction like [fee payment and signatures](./04-gas-fees.md#antehandler) before extracting the `Msg`(s) contained in the transaction.
|
||||
3. `sdk.Msg`s are encoded using Protobuf [`Any`s](#register-codec). By analyzing each `Any`'s `type_url`, baseapp's `msgServiceRouter` routes the `sdk.Msg` to the corresponding module's `Msg` service.
|
||||
4. If the message is successfully processed, the state is updated.
|
||||
|
||||
For more details, see [transaction lifecycle](./01-tx-lifecycle.md).
|
||||
|
||||
Module developers create custom `Msg` services when they build their own module. The general practice is to define the `Msg` Protobuf service in a `tx.proto` file. For example, the `x/bank` module defines a service with two methods to transfer tokens:
|
||||
|
||||
```protobuf reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/bank/v1beta1/tx.proto#L13-L36
|
||||
```
|
||||
|
||||
Service methods use `keeper` in order to update the module state.
|
||||
|
||||
Each module should also implement the `RegisterServices` method as part of the [`AppModule` interface](#application-module-interface). This method should call the `RegisterMsgServer` function provided by the generated Protobuf code.
|
||||
|
||||
### gRPC `Query` Services
|
||||
|
||||
gRPC `Query` services allow users to query the state using [gRPC](https://grpc.io). They are enabled by default, and can be configured under the `grpc.enable` and `grpc.address` fields inside [`app.toml`](../../user/run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml).
|
||||
|
||||
gRPC `Query` services are defined in the module's Protobuf definition files, specifically inside `query.proto`. The `query.proto` definition file exposes a single `Query` [Protobuf service](https://developers.google.com/protocol-buffers/docs/proto#services). Each gRPC query endpoint corresponds to a service method, starting with the `rpc` keyword, inside the `Query` service.
|
||||
|
||||
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 `RegisterServices` method as part of the [`AppModule` interface](#application-module-interface). This method should call the `RegisterQueryServer` function provided by the generated Protobuf code.
|
||||
|
||||
### Keeper
|
||||
|
||||
[`Keepers`](../../build/building-modules/06-keeper.md) are the gatekeepers of their module's store(s). To read or write in a module's store, it is mandatory to go through one of its `keeper`'s methods. This is ensured by the [object-capabilities](../advanced/10-ocap.md) model of the Cosmos SDK. Only objects that hold the key to a store can access it, and only the module's `keeper` should hold the key(s) to the module's store(s).
|
||||
|
||||
`Keepers` are generally defined in a file called `keeper.go`. It contains the `keeper`'s type definition and methods.
|
||||
|
||||
The `keeper` type definition generally consists of the following:
|
||||
|
||||
* **Key(s)** to the module's store(s) in the multistore.
|
||||
* Reference to **other module's `keepers`**. Only needed if the `keeper` needs to access other module's store(s) (either to read or write from them).
|
||||
* A reference to the application's **codec**. The `keeper` needs it to marshal structs before storing them, or to unmarshal them when it retrieves them, because stores only accept `[]bytes` as value.
|
||||
|
||||
Along with the type definition, the next important component of the `keeper.go` file is the `keeper`'s constructor function, `NewKeeper`. This function instantiates a new `keeper` of the type defined above with a `codec`, stores `keys` and potentially references other modules' `keeper`s as parameters. The `NewKeeper` function is called from the [application's constructor](#constructor-function). The rest of the file defines the `keeper`'s methods, which are primarily getters and setters.
|
||||
|
||||
### Command-Line, gRPC Services and REST Interfaces
|
||||
|
||||
Each module defines command-line commands, gRPC services, and REST routes to be exposed to the end-user via the [application's interfaces](#application-interfaces). This enables end-users to create messages of the types defined in the module, or to query the subset of the state managed by the module.
|
||||
|
||||
#### CLI
|
||||
|
||||
Generally, the [commands related to a module](../../build/building-modules/09-module-interfaces.md#cli) are defined in a folder called `client/cli` in the module's folder. The CLI divides commands into two categories, transactions and queries, defined in `client/cli/tx.go` and `client/cli/query.go`, respectively. Both commands are built on top of the [Cobra Library](https://github.com/spf13/cobra):
|
||||
|
||||
* Transactions commands let users generate new transactions so that they can be included in a block and eventually update the state. One command should be created for each [message type](#message-types) defined in the module. The command calls the constructor of the message with the parameters provided by the end-user, and wraps it into a transaction. The Cosmos SDK handles signing and the addition of other transaction metadata.
|
||||
* Queries let users query the subset of the state defined by the module. Query commands forward queries to the [application's query router](../advanced/00-baseapp.md#query-routing), which routes them to the appropriate [querier](#querier) the `queryRoute` parameter supplied.
|
||||
|
||||
#### gRPC
|
||||
|
||||
[gRPC](https://grpc.io) is a modern open-source high performance RPC framework that has support in multiple languages. It is the recommended way for external clients (such as wallets, browsers and other backend services) to interact with a node.
|
||||
|
||||
Each module can expose gRPC endpoints called [service methods](https://grpc.io/docs/what-is-grpc/core-concepts/#service-definition), which are defined in the [module's Protobuf `query.proto` file](#grpc-query-services). A service method is defined by its name, input arguments, and output response. The module then needs to perform the following actions:
|
||||
|
||||
* Define a `RegisterGRPCGatewayRoutes` method on `AppModuleBasic` to wire the client gRPC requests to the correct handler inside the module.
|
||||
* For each service method, define a corresponding handler. The handler implements the core logic necessary to serve the gRPC request, and is located in the `keeper/grpc_query.go` file.
|
||||
|
||||
#### gRPC-gateway REST Endpoints
|
||||
|
||||
Some external clients may not wish to use gRPC. In this case, the Cosmos SDK provides a gRPC gateway service, which exposes each gRPC service as a corresponding REST endpoint. Please refer to the [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) documentation to learn more.
|
||||
|
||||
The REST endpoints are defined in the Protobuf files, along with the gRPC services, using Protobuf annotations. Modules that want to expose REST queries should add `google.api.http` annotations to their `rpc` methods. By default, all REST endpoints defined in the SDK have a URL starting with the `/cosmos/` prefix.
|
||||
|
||||
The Cosmos SDK also provides a development endpoint to generate [Swagger](https://swagger.io/) definition files for these REST endpoints. This endpoint can be enabled inside the [`app.toml`](../../user/run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml) config file, under the `api.swagger` key.
|
||||
|
||||
## Application Interface
|
||||
|
||||
[Interfaces](#command-line-grpc-services-and-rest-interfaces) let end-users interact with full-node clients. This means querying data from the full-node or creating and sending new transactions to be relayed by the full-node and eventually included in a block.
|
||||
|
||||
The main interface is the [Command-Line Interface](../advanced/07-cli.md). The CLI of a Cosmos SDK application is built by aggregating [CLI commands](#cli) defined in each of the modules used by the application. The CLI of an application is the same as the daemon (e.g. `appd`), and is defined in a file called `appd/main.go`. The file contains the following:
|
||||
|
||||
* **A `main()` function**, which is executed to build the `appd` interface client. This function prepares each command and adds them to the `rootCmd` before building them. At the root of `appd`, the function adds generic commands like `status`, `keys`, and `config`, query commands, tx commands, and `rest-server`.
|
||||
* **Query commands**, which are added by calling the `queryCmd` function. This function returns a Cobra command that contains the query commands defined in each of the application's modules (passed as an array of `sdk.ModuleClients` from the `main()` function), as well as some other lower level query commands such as block or validator queries. Query command are called by using the command `appd query [query]` of the CLI.
|
||||
* **Transaction commands**, which are added by calling the `txCmd` function. Similar to `queryCmd`, the function returns a Cobra command that contains the tx commands defined in each of the application's modules, as well as lower level tx commands like transaction signing or broadcasting. Tx commands are called by using the command `appd tx [tx]` of the CLI.
|
||||
|
||||
See an example of an application's main command-line file from the [Cosmos Hub](https://github.com/cosmos/gaia).
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/gaia/blob/26ae7c2/cmd/gaiad/cmd/root.go#L39-L80
|
||||
```
|
||||
|
||||
## Dependencies and Makefile
|
||||
|
||||
This section is optional, as developers are free to choose their dependency manager and project building method. That said, the current most used framework for versioning control is [`go.mod`](https://github.com/golang/go/wiki/Modules). It ensures each of the libraries used throughout the application are imported with the correct version.
|
||||
|
||||
The following is the `go.mod` of the [Cosmos Hub](https://github.com/cosmos/gaia), provided as an example.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/gaia/blob/26ae7c2/go.mod#L1-L28
|
||||
```
|
||||
|
||||
For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`appd`](#node-client) and [`appd`](#application-interface).
|
||||
|
||||
Here is an example of the [Cosmos Hub Makefile](https://github.com/cosmos/gaia/blob/main/Makefile).
|
||||
@@ -0,0 +1,264 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Transaction Lifecycle
|
||||
|
||||
:::note Synopsis
|
||||
This document describes the lifecycle of a transaction from creation to committed state changes. Transaction definition is described in a [different doc](../advanced/01-transactions.md). The transaction is referred to as `Tx`.
|
||||
:::
|
||||
|
||||
:::note Pre-requisite Readings
|
||||
|
||||
* [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md)
|
||||
:::
|
||||
|
||||
## Creation
|
||||
|
||||
### Transaction Creation
|
||||
|
||||
One of the main application interfaces is the command-line interface. The transaction `Tx` can be created by the user inputting a command in the following format from the [command-line](../advanced/07-cli.md), providing the type of transaction in `[command]`, arguments in `[args]`, and configurations such as gas prices in `[flags]`:
|
||||
|
||||
```bash
|
||||
[appname] tx [command] [args] [flags]
|
||||
```
|
||||
|
||||
This command automatically **creates** the transaction, **signs** it using the account's private key, and **broadcasts** it to the specified peer node.
|
||||
|
||||
There are several required and optional flags for transaction creation. The `--from` flag specifies which [account](./03-accounts.md) the transaction is originating from. For example, if the transaction is sending coins, the funds are drawn from the specified `from` address.
|
||||
|
||||
#### Gas and Fees
|
||||
|
||||
Additionally, there are several [flags](../advanced/07-cli.md) users can use to indicate how much they are willing to pay in [fees](./04-gas-fees.md):
|
||||
|
||||
* `--gas` refers to how much [gas](./04-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`.
|
||||
* `--gas-adjustment` (optional) 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.
|
||||
* `--gas-prices` specifies how much the user is willing to 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 the user is willing to pay in total.
|
||||
* `--timeout-height` specifies a block timeout height to prevent the tx from being committed past a certain height.
|
||||
|
||||
The ultimate value of the fees paid is equal to the gas multiplied by the gas prices. In other words, `fees = ceil(gas * gasPrices)`. Thus, since fees can be calculated using gas prices and vice versa, the users specify only one of the two.
|
||||
|
||||
Later, validators decide whether or not to include the transaction in their block by comparing the given or calculated `gas-prices` to their local `min-gas-prices`. `Tx` is rejected if its `gas-prices` is not high enough, so users are incentivized to pay more.
|
||||
|
||||
#### CLI Example
|
||||
|
||||
Users of the application `app` can enter the following command into their CLI to generate a transaction to send 1000uatom from a `senderAddress` to a `recipientAddress`. The command specifies how much gas they are willing to pay: an automatic estimate scaled up by 1.5 times, with a gas price of 0.025uatom per unit gas.
|
||||
|
||||
```bash
|
||||
appd tx send <recipientAddress> 1000uatom --from <senderAddress> --gas auto --gas-adjustment 1.5 --gas-prices 0.025uatom
|
||||
```
|
||||
|
||||
#### Other Transaction Creation Methods
|
||||
|
||||
The command-line is an easy way to interact with an application, but `Tx` can also be created using a [gRPC or REST interface](../advanced/06-grpc_rest.md) or some other entry point defined by the application developer. From the user's perspective, the interaction depends on the web interface or wallet they are using (e.g. creating `Tx` using [Lunie.io](https://lunie.io/#/) and signing it with a Ledger Nano S).
|
||||
|
||||
## Addition to Mempool
|
||||
|
||||
Each full-node (running CometBFT) that receives a `Tx` sends an [ABCI message](https://docs.cometbft.com/v0.37/spec/p2p/messages/),
|
||||
`CheckTx`, to the application layer to check for validity, and receives an `abci.ResponseCheckTx`. If the `Tx` passes the checks, it is held in the node's
|
||||
[**Mempool**](https://docs.cometbft.com/v0.37/spec/p2p/messages/mempool/), an in-memory pool of transactions unique to each node, pending inclusion in a block - honest nodes discard a `Tx` if it is found to be invalid. Prior to consensus, nodes continuously check incoming transactions and gossip them to their peers.
|
||||
|
||||
### Types of Checks
|
||||
|
||||
The full-nodes perform stateless, then stateful checks on `Tx` during `CheckTx`, with the goal to
|
||||
identify and reject an invalid transaction as early on as possible to avoid wasted computation.
|
||||
|
||||
**_Stateless_** checks do not require nodes to access state - light clients or offline nodes can do
|
||||
them - and are thus less computationally expensive. Stateless checks include making sure addresses
|
||||
are not empty, enforcing nonnegative numbers, and other logic specified in the definitions.
|
||||
|
||||
**_Stateful_** checks validate transactions and messages based on a committed state. Examples
|
||||
include checking that the relevant values exist and can be transacted with, the address
|
||||
has sufficient funds, and the sender is authorized or has the correct ownership to transact.
|
||||
At any given moment, full-nodes typically have [multiple versions](../advanced/00-baseapp.md#state-updates)
|
||||
of the application's internal state for different purposes. For example, nodes execute state
|
||||
changes while in the process of verifying transactions, but still need a copy of the last committed
|
||||
state in order to answer queries - they should not respond using state with uncommitted changes.
|
||||
|
||||
In order to verify a `Tx`, full-nodes call `CheckTx`, which includes both _stateless_ and _stateful_
|
||||
checks. Further validation happens later in the [`DeliverTx`](#delivertx) stage. `CheckTx` goes
|
||||
through several steps, beginning with decoding `Tx`.
|
||||
|
||||
### Decoding
|
||||
|
||||
When `Tx` is received by the application from the underlying consensus engine (e.g. CometBFT ), it is still in its [encoded](../advanced/05-encoding.md) `[]byte` form and needs to be unmarshaled in order to be processed. Then, the [`runTx`](../advanced/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) function is called to run in `runTxModeCheck` mode, meaning the function runs all checks but exits before executing messages and writing state changes.
|
||||
|
||||
### ValidateBasic (deprecated)
|
||||
|
||||
Messages ([`sdk.Msg`](../advanced/01-transactions.md#messages)) are extracted from transactions (`Tx`). The `ValidateBasic` method of the `sdk.Msg` interface implemented by the module developer is run for each transaction.
|
||||
To discard obviously invalid messages, the `BaseApp` type calls the `ValidateBasic` method very early in the processing of the message in the [`CheckTx`](../advanced/00-baseapp.md#checktx) and [`DeliverTx`](../advanced/00-baseapp.md#delivertx) transactions.
|
||||
`ValidateBasic` can include only **stateless** checks (the checks that do not require access to the state).
|
||||
|
||||
:::warning
|
||||
The `ValidateBasic` method on messages has been deprecated in favor of validating messages directly in their respective [`Msg` services](../../build/building-modules/03-msg-services.md#Validation).
|
||||
|
||||
Read [RFC 001](https://docs.cosmos.network/main/rfc/rfc-001-tx-validation) for more details.
|
||||
:::
|
||||
|
||||
:::note
|
||||
`BaseApp` still calls `ValidateBasic` on messages that implements that method for backwards compatibility.
|
||||
:::
|
||||
|
||||
#### Guideline
|
||||
|
||||
`ValidateBasic` should not be used anymore. Message validation should be performed in the `Msg` service when [handling a message](../../build/building-modules/msg-services#Validation) in a module Msg Server.
|
||||
|
||||
### AnteHandler
|
||||
|
||||
`AnteHandler`s even though optional, are in practice very often used to perform signature verification, gas calculation, fee deduction, and other core operations related to blockchain transactions.
|
||||
|
||||
A copy of the cached context is provided to the `AnteHandler`, which performs limited checks specified for the transaction type. Using a copy allows the `AnteHandler` to do stateful checks for `Tx` without modifying the last committed state, and revert back to the original if the execution fails.
|
||||
|
||||
For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module `AnteHandler` checks and increments sequence numbers, checks signatures and account numbers, and deducts fees from the first signer of the transaction - all state changes are made using the `checkState`.
|
||||
|
||||
### Gas
|
||||
|
||||
The [`Context`](../advanced/02-context.md), which keeps a `GasMeter` that tracks how much gas is used during the execution of `Tx`, is initialized. The user-provided amount of gas for `Tx` is known as `GasWanted`. If `GasConsumed`, the amount of gas consumed during execution, ever exceeds `GasWanted`, the execution stops and the changes made to the cached copy of the state are not committed. Otherwise, `CheckTx` sets `GasUsed` equal to `GasConsumed` and returns it in the result. After calculating the gas and fee values, validator-nodes check that the user-specified `gas-prices` is greater than their locally defined `min-gas-prices`.
|
||||
|
||||
### Discard or Addition to Mempool
|
||||
|
||||
If at any point during `CheckTx` the `Tx` fails, it is discarded and the transaction lifecycle ends
|
||||
there. Otherwise, if it passes `CheckTx` successfully, the default protocol is to relay it to peer
|
||||
nodes and add it to the Mempool so that the `Tx` becomes a candidate to be included in the next block.
|
||||
|
||||
The **mempool** serves the purpose of keeping track of transactions seen by all full-nodes.
|
||||
Full-nodes keep a **mempool cache** of the last `mempool.cache_size` transactions they have seen, as a first line of
|
||||
defense to prevent replay attacks. Ideally, `mempool.cache_size` is large enough to encompass all
|
||||
of the transactions in the full mempool. If the mempool cache is too small to keep track of all
|
||||
the transactions, `CheckTx` is responsible for identifying and rejecting replayed transactions.
|
||||
|
||||
Currently existing preventative measures include fees and a `sequence` (nonce) counter to distinguish
|
||||
replayed transactions from identical but valid ones. If an attacker tries to spam nodes with many
|
||||
copies of a `Tx`, full-nodes keeping a mempool cache reject all identical copies instead of running
|
||||
`CheckTx` on them. Even if the copies have incremented `sequence` numbers, attackers are
|
||||
disincentivized by the need to pay fees.
|
||||
|
||||
Validator nodes keep a mempool to prevent replay attacks, just as full-nodes do, but also use it as
|
||||
a pool of unconfirmed transactions in preparation of block inclusion. Note that even if a `Tx`
|
||||
passes all checks at this stage, it is still possible to be found invalid later on, because
|
||||
`CheckTx` does not fully validate the transaction (that is, it does not actually execute the messages).
|
||||
|
||||
## Inclusion in a Block
|
||||
|
||||
Consensus, the process through which validator nodes come to agreement on which transactions to
|
||||
accept, happens in **rounds**. Each round begins with a proposer creating a block of the most
|
||||
recent transactions and ends with **validators**, special full-nodes with voting power responsible
|
||||
for consensus, agreeing to accept the block or go with a `nil` block instead. Validator nodes
|
||||
execute the consensus algorithm, such as [CometBFT](https://docs.cometbft.com/v0.37/spec/consensus/),
|
||||
confirming the transactions using ABCI requests to the application, in order to come to this agreement.
|
||||
|
||||
The first step of consensus is the **block proposal**. One proposer amongst the validators is chosen
|
||||
by the consensus algorithm to create and propose a block - in order for a `Tx` to be included, it
|
||||
must be in this proposer's mempool.
|
||||
|
||||
## State Changes
|
||||
|
||||
The next step of consensus is to execute the transactions to fully validate them. All full-nodes
|
||||
that receive a block proposal from the correct proposer execute the transactions by calling the ABCI function `FinalizeBlock`.
|
||||
As mentioned throughout the documentation `BeginBlock`, `ExecuteTx` and `EndBlock` are called within FinalizeBlock.
|
||||
Although every full-node operates individually and locally, the outcome is always consistent and unequivocal. This is because the state changes brought about by the messages are predictable, and the transactions are specifically sequenced in the proposed block.
|
||||
|
||||
```text
|
||||
-----------------------
|
||||
|Receive Block Proposal|
|
||||
-----------------------
|
||||
|
|
||||
v
|
||||
-------------------------
|
||||
| FinalizeBlock |
|
||||
|
|
||||
v
|
||||
-------------------
|
||||
| BeginBlock |
|
||||
-------------------
|
||||
|
|
||||
v
|
||||
--------------------
|
||||
| ExecuteTx(tx0) |
|
||||
| ExecuteTx(tx1) |
|
||||
| ExecuteTx(tx2) |
|
||||
| ExecuteTx(tx3) |
|
||||
| . |
|
||||
| . |
|
||||
| . |
|
||||
-------------------
|
||||
|
|
||||
v
|
||||
--------------------
|
||||
| EndBlock |
|
||||
--------------------
|
||||
-------------------------
|
||||
|
|
||||
v
|
||||
-----------------------
|
||||
| Consensus |
|
||||
-----------------------
|
||||
|
|
||||
v
|
||||
-----------------------
|
||||
| Commit |
|
||||
-----------------------
|
||||
```
|
||||
|
||||
### Transaction Execution
|
||||
|
||||
The `FinalizeBlock` ABCI function defined in [`BaseApp`](../advanced/00-baseapp.md) does the bulk of the
|
||||
state transitions: it is run for each transaction in the block in sequential order as committed
|
||||
to during consensus. Under the hood, transaction execution is almost identical to `CheckTx` but calls the
|
||||
[`runTx`](../advanced/00-baseapp.md#runtx) function in deliver mode instead of check mode.
|
||||
Instead of using their `checkState`, full-nodes use `finalizeblock`:
|
||||
|
||||
* **Decoding:** Since `FinalizeBlock` is an ABCI call, `Tx` is received in the encoded `[]byte` form.
|
||||
Nodes first unmarshal the transaction, using the [`TxConfig`](./app-anatomy#register-codec) defined in the app, then call `runTx` in `execModeFinalize`, which is very similar to `CheckTx` but also executes and writes state changes.
|
||||
|
||||
* **Checks and `AnteHandler`:** Full-nodes call `validateBasicMsgs` and `AnteHandler` again. This second check
|
||||
happens because they may not have seen the same transactions during the addition to Mempool stage
|
||||
and a malicious proposer may have included invalid ones. One difference here is that the
|
||||
`AnteHandler` does not compare `gas-prices` to the node's `min-gas-prices` since that value is local
|
||||
to each node - differing values across nodes yield nondeterministic results.
|
||||
|
||||
* **`MsgServiceRouter`:** After `CheckTx` exits, `FinalizeBlock` continues to run
|
||||
[`runMsgs`](../advanced/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) to fully execute each `Msg` within the transaction.
|
||||
Since the transaction may have messages from different modules, `BaseApp` needs to know which module
|
||||
to find the appropriate handler. This is achieved using `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md).
|
||||
For `LegacyMsg` routing, the `Route` function is called via the [module manager](../../build/building-modules/01-module-manager.md) to retrieve the route name and find the legacy [`Handler`](../../build/building-modules/03-msg-services.md#handler-type) within the module.
|
||||
|
||||
* **`Msg` service:** Protobuf `Msg` service is responsible for executing each message in the `Tx` and causes state transitions to persist in `finalizeBlockState`.
|
||||
|
||||
* **PostHandlers:** [`PostHandler`](../advanced/00-baseapp.md#posthandler)s run after the execution of the message. If they fail, the state change of `runMsgs`, as well of `PostHandlers`, are both reverted.
|
||||
|
||||
* **Gas:** While a `Tx` is being delivered, a `GasMeter` is used to keep track of how much
|
||||
gas is being used; if execution completes, `GasUsed` is set and returned in the
|
||||
`abci.ExecTxResult`. If execution halts because `BlockGasMeter` or `GasMeter` has run out or something else goes
|
||||
wrong, a deferred function at the end appropriately errors or panics.
|
||||
|
||||
If there are any failed state changes resulting from a `Tx` being invalid or `GasMeter` running out,
|
||||
the transaction processing terminates and any state changes are reverted. Invalid transactions in a
|
||||
block proposal cause validator nodes to reject the block and vote for a `nil` block instead.
|
||||
|
||||
### Commit
|
||||
|
||||
The final step is for nodes to commit the block and state changes. Validator nodes
|
||||
perform the previous step of executing state transitions in order to validate the transactions,
|
||||
then sign the block to confirm it. Full nodes that are not validators do not
|
||||
participate in consensus - i.e. they cannot vote - but listen for votes to understand whether or
|
||||
not they should commit the state changes.
|
||||
|
||||
When they receive enough validator votes (2/3+ _precommits_ weighted by voting power), full nodes commit to a new block to be added to the blockchain and
|
||||
finalize the state transitions in the application layer. A new state root is generated to serve as
|
||||
a merkle proof for the state transitions. Applications use the [`Commit`](../advanced/00-baseapp.md#commit)
|
||||
ABCI method inherited from [Baseapp](../advanced/00-baseapp.md); it syncs all the state transitions by
|
||||
writing the `deliverState` into the application's internal state. As soon as the state changes are
|
||||
committed, `checkState` starts afresh from the most recently committed state and `deliverState`
|
||||
resets to `nil` in order to be consistent and reflect the changes.
|
||||
|
||||
Note that not all blocks have the same number of transactions and it is possible for consensus to
|
||||
result in a `nil` block or one with none at all. In a public blockchain network, it is also possible
|
||||
for validators to be **byzantine**, or malicious, which may prevent a `Tx` from being committed in
|
||||
the blockchain. Possible malicious behaviors include the proposer deciding to censor a `Tx` by
|
||||
excluding it from the block or a validator voting against the block.
|
||||
|
||||
At this point, the transaction lifecycle of a `Tx` is over: nodes have verified its validity,
|
||||
delivered it by executing its state changes, and committed those changes. The `Tx` itself,
|
||||
in `[]byte` form, is stored in a block and appended to the blockchain.
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Query Lifecycle
|
||||
|
||||
:::note Synopsis
|
||||
This document describes the lifecycle of a query in a Cosmos SDK application, from the user interface to application stores and back. The query is referred to as `MyQuery`.
|
||||
:::
|
||||
|
||||
:::note Pre-requisite Readings
|
||||
|
||||
* [Transaction Lifecycle](./01-tx-lifecycle.md)
|
||||
:::
|
||||
|
||||
## Query Creation
|
||||
|
||||
A [**query**](../../build/building-modules/02-messages-and-queries.md#queries) is a request for information made by end-users of applications through an interface and processed by a full-node. Users can query information about the network, the application itself, and application state directly from the application's stores or modules. Note that queries are different from [transactions](../advanced/01-transactions.md) (view the lifecycle [here](./01-tx-lifecycle.md)), particularly in that they do not require consensus to be processed (as they do not trigger state-transitions); they can be fully handled by one full-node.
|
||||
|
||||
For the purpose of explaining the query lifecycle, let's say the query, `MyQuery`, is requesting a list of delegations made by a certain delegator address in the application called `simapp`. As is to be expected, the [`staking`](../../build/modules/staking/README.md) module handles this query. But first, there are a few ways `MyQuery` can be created by users.
|
||||
|
||||
### CLI
|
||||
|
||||
The main interface for an application is the command-line interface. Users connect to a full-node and run the CLI directly from their machines - the CLI interacts directly with the full-node. To create `MyQuery` from their terminal, users type the following command:
|
||||
|
||||
```bash
|
||||
simd query staking delegations <delegatorAddress>
|
||||
```
|
||||
|
||||
This query command was defined by the [`staking`](../../build/modules/staking/README.md) module developer and added to the list of subcommands by the application developer when creating the CLI.
|
||||
|
||||
Note that the general format is as follows:
|
||||
|
||||
```bash
|
||||
simd query [moduleName] [command] <arguments> --flag <flagArg>
|
||||
```
|
||||
|
||||
To provide values such as `--node` (the full-node the CLI connects to), the user can use the [`app.toml`](../../user/run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml) config file to set them or provide them as flags.
|
||||
|
||||
The CLI understands a specific set of commands, defined in a hierarchical structure by the application developer: from the [root command](../advanced/07-cli.md#root-command) (`simd`), the type of command (`Myquery`), the module that contains the command (`staking`), and command itself (`delegations`). Thus, the CLI knows exactly which module handles this command and directly passes the call there.
|
||||
|
||||
### gRPC
|
||||
|
||||
Another interface through which users can make queries is [gRPC](https://grpc.io) requests to a [gRPC server](../advanced/06-grpc_rest.md#grpc-server). The endpoints are defined as [Protocol Buffers](https://developers.google.com/protocol-buffers) service methods inside `.proto` files, written in Protobuf's own language-agnostic interface definition language (IDL). The Protobuf ecosystem developed tools for code-generation from `*.proto` files into various languages. These tools allow to build gRPC clients easily.
|
||||
|
||||
One such tool is [grpcurl](https://github.com/fullstorydev/grpcurl), and a gRPC request for `MyQuery` using this client looks like:
|
||||
|
||||
```bash
|
||||
grpcurl \
|
||||
-plaintext # We want results in plain test
|
||||
-import-path ./proto \ # Import these .proto files
|
||||
-proto ./proto/cosmos/staking/v1beta1/query.proto \ # Look into this .proto file for the Query protobuf service
|
||||
-d '{"address":"$MY_DELEGATOR"}' \ # Query arguments
|
||||
localhost:9090 \ # gRPC server endpoint
|
||||
cosmos.staking.v1beta1.Query/Delegations # Fully-qualified service method name
|
||||
```
|
||||
|
||||
### REST
|
||||
|
||||
Another interface through which users can make queries is through HTTP Requests to a [REST server](../advanced/06-grpc_rest.md#rest-server). The REST server is fully auto-generated from Protobuf services, using [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway).
|
||||
|
||||
An example HTTP request for `MyQuery` looks like:
|
||||
|
||||
```bash
|
||||
GET http://localhost:1317/cosmos/staking/v1beta1/delegators/{delegatorAddr}/delegations
|
||||
```
|
||||
|
||||
## How Queries are Handled by the CLI
|
||||
|
||||
The preceding examples show how an external user can interact with a node by querying its state. To understand in more detail the exact lifecycle of a query, let's dig into how the CLI prepares the query, and how the node handles it. The interactions from the users' perspective are a bit different, but the underlying functions are almost identical because they are implementations of the same command defined by the module developer. This step of processing happens within the CLI, gRPC, or REST server, and heavily involves a `client.Context`.
|
||||
|
||||
### Context
|
||||
|
||||
The first thing that is created in the execution of a CLI command is a `client.Context`. A `client.Context` is an object that stores all the data needed to process a request on the user side. In particular, a `client.Context` stores the following:
|
||||
|
||||
* **Codec**: The [encoder/decoder](../advanced/05-encoding.md) used by the application, used to marshal the parameters and query before making the CometBFT RPC request and unmarshal the returned response into a JSON object. The default codec used by the CLI is Protobuf.
|
||||
* **Account Decoder**: The account decoder from the [`auth`](../../build/modules/auth/README.md) module, which translates `[]byte`s into accounts.
|
||||
* **RPC Client**: The CometBFT RPC Client, or node, to which requests are relayed.
|
||||
* **Keyring**: A [Key Manager]../beginner/03-accounts.md#keyring) used to sign transactions and handle other operations with keys.
|
||||
* **Output Writer**: A [Writer](https://pkg.go.dev/io/#Writer) used to output the response.
|
||||
* **Configurations**: The flags configured by the user for this command, including `--height`, specifying the height of the blockchain to query, and `--indent`, which indicates to add an indent to the JSON response.
|
||||
|
||||
The `client.Context` also contains various functions such as `Query()`, which retrieves the RPC Client and makes an ABCI call to relay a query to a full-node.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/context.go#L25-L68
|
||||
```
|
||||
|
||||
The `client.Context`'s primary role is to store data used during interactions with the end-user and provide methods to interact with this data - it is used before and after the query is processed by the full-node. Specifically, in handling `MyQuery`, the `client.Context` is utilized to encode the query parameters, retrieve the full-node, and write the output. Prior to being relayed to a full-node, the query needs to be encoded into a `[]byte` form, as full-nodes are application-agnostic and do not understand specific types. The full-node (RPC Client) itself is retrieved using the `client.Context`, which knows which node the user CLI is connected to. The query is relayed to this full-node to be processed. Finally, the `client.Context` contains a `Writer` to write output when the response is returned. These steps are further described in later sections.
|
||||
|
||||
### Arguments and Route Creation
|
||||
|
||||
At this point in the lifecycle, the user has created a CLI command with all of the data they wish to include in their query. A `client.Context` exists to assist in the rest of the `MyQuery`'s journey. Now, the next step is to parse the command or request, extract the arguments, and encode everything. These steps all happen on the user side within the interface they are interacting with.
|
||||
|
||||
#### Encoding
|
||||
|
||||
In our case (querying an address's delegations), `MyQuery` contains an [address](./03-accounts.md#addresses) `delegatorAddress` as its only argument. However, the request can only contain `[]byte`s, as it is ultimately relayed to a consensus engine (e.g. CometBFT) of a full-node that has no inherent knowledge of the application types. Thus, the `codec` of `client.Context` is used to marshal the address.
|
||||
|
||||
Here is what the code looks like for the CLI command:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/client/cli/query.go#L315-L318
|
||||
```
|
||||
|
||||
#### gRPC Query Client Creation
|
||||
|
||||
The Cosmos SDK leverages code generated from Protobuf services to make queries. The `staking` module's `MyQuery` service generates a `queryClient`, which the CLI uses to make queries. Here is the relevant code:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/client/cli/query.go#L308-L343
|
||||
```
|
||||
|
||||
Under the hood, the `client.Context` has a `Query()` function used to retrieve the pre-configured node and relay a query to it; the function takes the query fully-qualified service method name as path (in our case: `/cosmos.staking.v1beta1.Query/Delegations`), and arguments as parameters. It first retrieves the RPC Client (called the [**node**](../advanced/03-node.md)) configured by the user to relay this query to, and creates the `ABCIQueryOptions` (parameters formatted for the ABCI call). The node is then used to make the ABCI call, `ABCIQueryWithOptions()`.
|
||||
|
||||
Here is what the code looks like:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/query.go#L79-L113
|
||||
```
|
||||
|
||||
## RPC
|
||||
|
||||
With a call to `ABCIQueryWithOptions()`, `MyQuery` is received by a [full-node](../advanced/05-encoding.md) which then processes the request. Note that, while the RPC is made to the consensus engine (e.g. CometBFT) of a full-node, queries are not part of consensus and so are not broadcasted to the rest of the network, as they do not require anything the network needs to agree upon.
|
||||
|
||||
Read more about ABCI Clients and CometBFT RPC in the [CometBFT documentation](https://docs.cometbft.com/v0.37/spec/rpc/).
|
||||
|
||||
## Application Query Handling
|
||||
|
||||
When a query is received by the full-node after it has been relayed from the underlying consensus engine, it is at that point being handled within an environment that understands application-specific types and has a copy of the state. [`baseapp`](../advanced/00-baseapp.md) implements the ABCI [`Query()`](../advanced/00-baseapp.md#query) function and handles gRPC queries. The query route is parsed, and it matches the fully-qualified service method name of an existing service method (most likely in one of the modules), then `baseapp` relays the request to the relevant module.
|
||||
|
||||
Since `MyQuery` has a Protobuf fully-qualified service method name from the `staking` module (recall `/cosmos.staking.v1beta1.Query/Delegations`), `baseapp` first parses the path, then uses its own internal `GRPCQueryRouter` to retrieve the corresponding gRPC handler, and routes the query to the module. The gRPC handler is responsible for recognizing this query, retrieving the appropriate values from the application's stores, and returning a response. Read more about query services [here](../../build/building-modules/04-query-services.md).
|
||||
|
||||
Once a result is received from the querier, `baseapp` begins the process of returning a response to the user.
|
||||
|
||||
## Response
|
||||
|
||||
Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci.ResponseQuery`](https://docs.cometbft.com/master/spec/abci/abci.html#query-2) type. The `client.Context` `Query()` routine receives the response and.
|
||||
|
||||
### CLI Response
|
||||
|
||||
The application [`codec`](../advanced/05-encoding.md) is used to unmarshal the response to a JSON and the `client.Context` prints the output to the command line, applying any configurations such as the output type (text, JSON or YAML).
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/context.go#L341-L349
|
||||
```
|
||||
|
||||
And that's a wrap! The result of the query is outputted to the console by the CLI.
|
||||
@@ -0,0 +1,281 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Accounts
|
||||
|
||||
:::note Synopsis
|
||||
This document describes the in-built account and public key system of the Cosmos SDK.
|
||||
:::
|
||||
|
||||
:::note Pre-requisite Readings
|
||||
|
||||
|
||||
* [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md)
|
||||
|
||||
:::
|
||||
|
||||
## Account Definition
|
||||
|
||||
In the Cosmos SDK, an _account_ designates a pair of _public key_ `PubKey` and _private key_ `PrivKey`. The `PubKey` can be derived to generate various `Addresses`, which are used to identify users (among other parties) in the application. `Addresses` are also associated with [`message`s](../../build/building-modules/02-messages-and-queries.md#messages) to identify the sender of the `message`. The `PrivKey` is used to generate [digital signatures](#signatures) to prove that an `Address` associated with the `PrivKey` approved of a given `message`.
|
||||
|
||||
For HD key derivation the Cosmos SDK uses a standard called [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki). The BIP32 allows users to create an HD wallet (as specified in [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)) - a set of accounts derived from an initial secret seed. A seed is usually created from a 12- or 24-word mnemonic. A single seed can derive any number of `PrivKey`s using a one-way cryptographic function. Then, a `PubKey` can be derived from the `PrivKey`. Naturally, the mnemonic is the most sensitive information, as private keys can always be re-generated if the mnemonic is preserved.
|
||||
|
||||
```text
|
||||
Account 0 Account 1 Account 2
|
||||
|
||||
+------------------+ +------------------+ +------------------+
|
||||
| | | | | |
|
||||
| Address 0 | | Address 1 | | Address 2 |
|
||||
| ^ | | ^ | | ^ |
|
||||
| | | | | | | | |
|
||||
| | | | | | | | |
|
||||
| | | | | | | | |
|
||||
| + | | + | | + |
|
||||
| Public key 0 | | Public key 1 | | Public key 2 |
|
||||
| ^ | | ^ | | ^ |
|
||||
| | | | | | | | |
|
||||
| | | | | | | | |
|
||||
| | | | | | | | |
|
||||
| + | | + | | + |
|
||||
| Private key 0 | | Private key 1 | | Private key 2 |
|
||||
| ^ | | ^ | | ^ |
|
||||
+------------------+ +------------------+ +------------------+
|
||||
| | |
|
||||
| | |
|
||||
| | |
|
||||
+--------------------------------------------------------------------+
|
||||
|
|
||||
|
|
||||
+---------+---------+
|
||||
| |
|
||||
| Master PrivKey |
|
||||
| |
|
||||
+-------------------+
|
||||
|
|
||||
|
|
||||
+---------+---------+
|
||||
| |
|
||||
| Mnemonic (Seed) |
|
||||
| |
|
||||
+-------------------+
|
||||
```
|
||||
|
||||
In the Cosmos SDK, keys are stored and managed by using an object called a [`Keyring`](#keyring).
|
||||
|
||||
## Keys, accounts, addresses, and signatures
|
||||
|
||||
The principal way of authenticating a user is done using [digital signatures](https://en.wikipedia.org/wiki/Digital_signature). Users sign transactions using their own private key. Signature verification is done with the associated public key. For on-chain signature verification purposes, we store the public key in an `Account` object (alongside other data required for a proper transaction validation).
|
||||
|
||||
In the node, all data is stored using Protocol Buffers serialization.
|
||||
|
||||
The Cosmos SDK supports the following digital key schemes for creating digital signatures:
|
||||
|
||||
* `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/keys/secp256k1/secp256k1.go).
|
||||
* `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/keys/secp256r1/pubkey.go),
|
||||
* `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation.
|
||||
|
||||
| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (cometbft) |
|
||||
| :----------: | :---------------------: | :------------------------: | :---------------------------------: | :-----------------------------: |
|
||||
| `secp256k1` | 20 | 33 | yes | no |
|
||||
| `secp256r1` | 32 | 33 | yes | no |
|
||||
| `tm-ed25519` | -- not used -- | 32 | no | yes |
|
||||
|
||||
## Addresses
|
||||
|
||||
`Addresses` and `PubKey`s are both public information that identifies actors in the application. `Account` is used to store authentication information. The basic account implementation is provided by a `BaseAccount` object.
|
||||
|
||||
Each account is identified using `Address` which is a sequence of bytes derived from a public key. In the Cosmos SDK, we define 3 types of addresses that specify a context where an account is used:
|
||||
|
||||
* `AccAddress` identifies users (the sender of a `message`).
|
||||
* `ValAddress` identifies validator operators.
|
||||
* `ConsAddress` identifies validator nodes that are participating in consensus. Validator nodes are derived using the **`ed25519`** curve.
|
||||
|
||||
These types implement the `Address` interface:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/address.go#L126-L134
|
||||
```
|
||||
|
||||
Address construction algorithm is defined in [ADR-28](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-028-public-key-addresses.md).
|
||||
Here is the standard way to obtain an account address from a `pub` public key:
|
||||
|
||||
```go
|
||||
sdk.AccAddress(pub.Address().Bytes())
|
||||
```
|
||||
|
||||
Of note, the `Marshal()` and `Bytes()` method both return the same raw `[]byte` form of the address. `Marshal()` is required for Protobuf compatibility.
|
||||
|
||||
For user interaction, addresses are formatted using [Bech32](https://en.bitcoin.it/wiki/Bech32) and implemented by the `String` method. The Bech32 method is the only supported format to use when interacting with a blockchain. The Bech32 human-readable part (Bech32 prefix) is used to denote an address type. Example:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/address.go#L299-L316
|
||||
```
|
||||
|
||||
| | Address Bech32 Prefix |
|
||||
| ------------------ | --------------------- |
|
||||
| Accounts | cosmos |
|
||||
| Validator Operator | cosmosvaloper |
|
||||
| Consensus Nodes | cosmosvalcons |
|
||||
|
||||
### Public Keys
|
||||
|
||||
Public keys in Cosmos SDK are defined by `cryptotypes.PubKey` interface. Since public keys are saved in a store, `cryptotypes.PubKey` extends the `proto.Message` interface:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/types/types.go#L8-L17
|
||||
```
|
||||
|
||||
A compressed format is used for `secp256k1` and `secp256r1` serialization.
|
||||
|
||||
* The first byte is a `0x02` byte if the `y`-coordinate is the lexicographically largest of the two associated with the `x`-coordinate.
|
||||
* Otherwise the first byte is a `0x03`.
|
||||
|
||||
This prefix is followed by the `x`-coordinate.
|
||||
|
||||
Public Keys are not used to reference accounts (or users) and in general are not used when composing transaction messages (with few exceptions: `MsgCreateValidator`, `Validator` and `Multisig` messages).
|
||||
For user interactions, `PubKey` is formatted using Protobufs JSON ([ProtoMarshalJSON](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/codec/json.go#L14-L34) function). Example:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/keys/output.go#L23-L39
|
||||
```
|
||||
|
||||
## Keyring
|
||||
|
||||
A `Keyring` is an object that stores and manages accounts. In the Cosmos SDK, a `Keyring` implementation follows the `Keyring` interface:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/keyring/keyring.go#L57-L105
|
||||
```
|
||||
|
||||
The default implementation of `Keyring` comes from the third-party [`99designs/keyring`](https://github.com/99designs/keyring) library.
|
||||
|
||||
A few notes on the `Keyring` methods:
|
||||
|
||||
* `Sign(uid string, msg []byte) ([]byte, types.PubKey, error)` strictly deals with the signature of the `msg` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../../build/architecture/adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../advanced/00-baseapp.md#antehandler).
|
||||
|
||||
```protobuf reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L50-L66
|
||||
```
|
||||
|
||||
* `NewAccount(uid, mnemonic, bip39Passphrase, hdPath string, algo SignatureAlgo) (*Record, error)` creates a new account based on the [`bip44 path`](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) and persists it on disk. The `PrivKey` is **never stored unencrypted**, instead it is [encrypted with a passphrase](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/armor.go) before being persisted. In the context of this method, the key type and sequence number refer to the segment of the BIP44 derivation path (for example, `0`, `1`, `2`, ...) that is used to derive a private and a public key from the mnemonic. Using the same mnemonic and derivation path, the same `PrivKey`, `PubKey` and `Address` is generated. The following keys are supported by the keyring:
|
||||
|
||||
* `secp256k1`
|
||||
* `ed25519`
|
||||
|
||||
* `ExportPrivKeyArmor(uid, encryptPassphrase string) (armor string, err error)` exports a private key in ASCII-armored encrypted format using the given passphrase. You can then either import the private key again into the keyring using the `ImportPrivKey(uid, armor, passphrase string)` function or decrypt it into a raw private key using the `UnarmorDecryptPrivKey(armorStr string, passphrase string)` function.
|
||||
|
||||
### Create New Key Type
|
||||
|
||||
To create a new key type for using in keyring, `keyring.SignatureAlgo` interface must be fulfilled.
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/keyring/signing_algorithms.go#L10-L15
|
||||
```
|
||||
|
||||
The interface consists in three methods where `Name()` returns the name of the algorithm as a `hd.PubKeyType` and `Derive()` and `Generate()` must return the following functions respectively:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/hd/algo.go#L28-L31
|
||||
```
|
||||
|
||||
Once the `keyring.SignatureAlgo` has been implemented it must be added to the [list of supported algos](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/keyring/keyring.go#L217) of the keyring.
|
||||
|
||||
For simplicity the implementation of a new key type should be done inside the `crypto/hd` package.
|
||||
There is an example of a working `secp256k1` implementation in [algo.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/hd/algo.go#L38).
|
||||
|
||||
|
||||
#### Implementing secp256r1 algo
|
||||
|
||||
Here is an example of how secp256r1 could be implemented.
|
||||
|
||||
First a new function to create a private key from a secret number is needed in the secp256r1 package. This function could look like this:
|
||||
|
||||
```go
|
||||
// cosmos-sdk/crypto/keys/secp256r1/privkey.go
|
||||
|
||||
// NewPrivKeyFromSecret creates a private key derived for the secret number
|
||||
// represented in big-endian. The `secret` must be a valid ECDSA field element.
|
||||
func NewPrivKeyFromSecret(secret []byte) (*PrivKey, error) {
|
||||
var d = new(big.Int).SetBytes(secret)
|
||||
if d.Cmp(secp256r1.Params().N) >= 1 {
|
||||
return nil, errorsmod.Wrap(errors.ErrInvalidRequest, "secret not in the curve base field")
|
||||
}
|
||||
sk := new(ecdsa.PrivKey)
|
||||
return &PrivKey{&ecdsaSK{*sk}}, nil
|
||||
}
|
||||
```
|
||||
|
||||
After that `secp256r1Algo` can be implemented.
|
||||
|
||||
```go
|
||||
// cosmos-sdk/crypto/hd/secp256r1Algo.go
|
||||
|
||||
package hd
|
||||
|
||||
import (
|
||||
"github.com/cosmos/go-bip39"
|
||||
|
||||
"github.com/cosmos/cosmos-sdk/crypto/keys/secp256r1"
|
||||
"github.com/cosmos/cosmos-sdk/crypto/types"
|
||||
)
|
||||
|
||||
// Secp256r1Type uses the secp256r1 ECDSA parameters.
|
||||
const Secp256r1Type = PubKeyType("secp256r1")
|
||||
|
||||
var Secp256r1 = secp256r1Algo{}
|
||||
|
||||
type secp256r1Algo struct{}
|
||||
|
||||
func (s secp256r1Algo) Name() PubKeyType {
|
||||
return Secp256r1Type
|
||||
}
|
||||
|
||||
// Derive derives and returns the secp256r1 private key for the given seed and HD path.
|
||||
func (s secp256r1Algo) Derive() DeriveFn {
|
||||
return func(mnemonic string, bip39Passphrase, hdPath string) ([]byte, error) {
|
||||
seed, err := bip39.NewSeedWithErrorChecking(mnemonic, bip39Passphrase)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
masterPriv, ch := ComputeMastersFromSeed(seed)
|
||||
if len(hdPath) == 0 {
|
||||
return masterPriv[:], nil
|
||||
}
|
||||
derivedKey, err := DerivePrivateKeyForPath(masterPriv, ch, hdPath)
|
||||
|
||||
return derivedKey, err
|
||||
}
|
||||
}
|
||||
|
||||
// Generate generates a secp256r1 private key from the given bytes.
|
||||
func (s secp256r1Algo) Generate() GenerateFn {
|
||||
return func(bz []byte) types.PrivKey {
|
||||
key, err := secp256r1.NewPrivKeyFromSecret(bz)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
return key
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Finally, the algo must be added to the list of [supported algos](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/crypto/keyring/keyring.go#L217) by the keyring.
|
||||
|
||||
```go
|
||||
// cosmos-sdk/crypto/keyring/keyring.go
|
||||
|
||||
func newKeystore(kr keyring.Keyring, cdc codec.Codec, backend string, opts ...Option) keystore {
|
||||
// Default options for keybase, these can be overwritten using the
|
||||
// Option function
|
||||
options := Options{
|
||||
SupportedAlgos: SigningAlgoList{hd.Secp256k1, hd.Secp256r1}, // added here
|
||||
SupportedAlgosLedger: SigningAlgoList{hd.Secp256k1},
|
||||
}
|
||||
...
|
||||
```
|
||||
|
||||
Hereafter to create new keys using your algo, you must specify it with the flag `--algo` :
|
||||
|
||||
`simd keys add myKey --algo secp256r1`
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Gas and Fees
|
||||
|
||||
:::note Synopsis
|
||||
This document describes the default strategies to handle gas and fees within a Cosmos SDK application.
|
||||
:::
|
||||
|
||||
:::note Pre-requisite Readings
|
||||
|
||||
* [Anatomy of a Cosmos SDK Application](./00-app-anatomy.md)
|
||||
|
||||
:::
|
||||
|
||||
## Introduction to `Gas` and `Fees`
|
||||
|
||||
In the Cosmos SDK, `gas` is a special unit that is used to track the consumption of resources during execution. `gas` is typically consumed whenever read and writes are made to the store, but it can also be consumed if expensive computation needs to be done. It serves two main purposes:
|
||||
|
||||
* Make sure blocks are not consuming too many resources and are finalized. This is implemented by default in the Cosmos SDK via the [block gas meter](#block-gas-meter).
|
||||
* Prevent spam and abuse from end-user. To this end, `gas` consumed during [`message`](../../build/building-modules/02-messages-and-queries.md#messages) execution is typically priced, resulting in a `fee` (`fees = gas * gas-prices`). `fees` generally have to be paid by the sender of the `message`. Note that the Cosmos SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications implement `fee` mechanisms to prevent spam by using the [`AnteHandler`](#antehandler).
|
||||
|
||||
## Gas Meter
|
||||
|
||||
In the Cosmos SDK, `gas` is a simple alias for `uint64`, and is managed by an object called a _gas meter_. Gas meters implement the `GasMeter` interface
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/types/gas.go#L40-L51
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
* `GasConsumed()` returns the amount of gas that was consumed by the gas meter instance.
|
||||
* `GasConsumedToLimit()` returns the amount of gas that was consumed by gas meter instance, or the limit if it is reached.
|
||||
* `GasRemaining()` returns the gas left in the GasMeter.
|
||||
* `Limit()` returns the limit of the gas meter instance. `0` if the gas meter is infinite.
|
||||
* `ConsumeGas(amount Gas, descriptor string)` consumes the amount of `gas` provided. If the `gas` overflows, it panics with the `descriptor` message. If the gas meter is not infinite, it panics if `gas` consumed goes above the limit.
|
||||
* `RefundGas()` deducts the given amount from the gas consumed. This functionality enables refunding gas to the transaction or block gas pools so that EVM-compatible chains can fully support the go-ethereum StateDB interface.
|
||||
* `IsPastLimit()` returns `true` if the amount of gas consumed by the gas meter instance is strictly above the limit, `false` otherwise.
|
||||
* `IsOutOfGas()` returns `true` if the amount of gas consumed by the gas meter instance is above or equal to the limit, `false` otherwise.
|
||||
|
||||
The gas meter is generally held in [`ctx`](../advanced/02-context.md), and consuming gas is done with the following pattern:
|
||||
|
||||
```go
|
||||
ctx.GasMeter().ConsumeGas(amount, "description")
|
||||
```
|
||||
|
||||
By default, the Cosmos SDK makes use of two different gas meters, the [main gas meter](#main-gas-metter) and the [block gas meter](#block-gas-meter).
|
||||
|
||||
### Main Gas Meter
|
||||
|
||||
`ctx.GasMeter()` is the main gas meter of the application. The main gas meter is initialized in `FinalizeBlock` via `setFinalizeBlockState`, and then tracks gas consumption during execution sequences that lead to state-transitions, i.e. those originally triggered by [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock). At the beginning of each transaction execution, the main gas meter **must be set to 0** in the [`AnteHandler`](#antehandler), so that it can track gas consumption per-transaction.
|
||||
|
||||
Gas consumption can be done manually, generally by the module developer in the [`BeginBlocker`, `EndBlocker`](../../build/building-modules/06-beginblock-endblock.md) or [`Msg` service](../../build/building-modules/03-msg-services.md), but most of the time it is done automatically whenever there is a read or write to the store. This automatic gas consumption logic is implemented in a special store called [`GasKv`](../advanced/04-store.md#gaskv-store).
|
||||
|
||||
### Block Gas Meter
|
||||
|
||||
`ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. By default, Cosmos SDK applications use the default consensus parameters provided by CometBFT:
|
||||
|
||||
```go reference
|
||||
https://github.com/cometbft/cometbft/blob/v0.37.0/types/params.go#L66-L105
|
||||
```
|
||||
|
||||
When a new [transaction](../advanced/01-transactions.md) is being processed via `FinalizeBlock`, the current value of `BlockGasMeter` is checked to see if it is above the limit. If it is, the transaction fails and returned to the consensus engine as a failed transaction. This can happen even with the first transaction in a block, as `FinalizeBlock` itself can consume gas. If not, the transaction is processed normally. At the end of `FinalizeBlock`, the gas tracked by `ctx.BlockGasMeter()` is increased by the amount consumed to process the transaction:
|
||||
|
||||
```go
|
||||
ctx.BlockGasMeter().ConsumeGas(
|
||||
ctx.GasMeter().GasConsumedToLimit(),
|
||||
"block gas meter",
|
||||
)
|
||||
```
|
||||
|
||||
## AnteHandler
|
||||
|
||||
The `AnteHandler` is run for every transaction during `CheckTx` and `FinalizeBlock`, before a Protobuf `Msg` service method for each `sdk.Msg` in the transaction.
|
||||
|
||||
The anteHandler is not implemented in the core Cosmos SDK but in a module. That said, most applications today use the default implementation defined in the [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth). Here is what the `anteHandler` is intended to do in a normal Cosmos SDK application:
|
||||
|
||||
* Verify that the transactions are of the correct type. Transaction types are defined in the module that implements the `anteHandler`, and they follow the transaction interface:
|
||||
|
||||
```go reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L51-L56
|
||||
```
|
||||
|
||||
This enables developers to play with various types for the transaction of their application. In the default `auth` module, the default transaction type is `Tx`:
|
||||
|
||||
```protobuf reference
|
||||
https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L14-L27
|
||||
```
|
||||
|
||||
* Verify signatures for each [`message`](../../build/building-modules/02-messages-and-queries.md#messages) contained in the transaction. Each `message` should be signed by one or multiple sender(s), and these signatures must be verified in the `anteHandler`.
|
||||
* During `CheckTx`, verify that the gas prices provided with the transaction is greater than the local `min-gas-prices` (as a reminder, gas-prices can be deducted from the following equation: `fees = gas * gas-prices`). `min-gas-prices` is a parameter local to each full-node and used during `CheckTx` to discard transactions that do not provide a minimum amount of fees. This ensures that the mempool cannot be spammed with garbage transactions.
|
||||
* Verify that the sender of the transaction has enough funds to cover for the `fees`. When the end-user generates a transaction, they must indicate 2 of the 3 following parameters (the third one being implicit): `fees`, `gas` and `gas-prices`. This signals how much they are willing to pay for nodes to execute their transaction. The provided `gas` value is stored in a parameter called `GasWanted` for later use.
|
||||
* Set `newCtx.GasMeter` to 0, with a limit of `GasWanted`. **This step is crucial**, as it not only makes sure the transaction cannot consume infinite gas, but also that `ctx.GasMeter` is reset in-between each transaction (`ctx` is set to `newCtx` after `anteHandler` is run, and the `anteHandler` is run each time a transactions executes).
|
||||
|
||||
As explained above, the `anteHandler` returns a maximum limit of `gas` the transaction can consume during execution called `GasWanted`. The actual amount consumed in the end is denominated `GasUsed`, and we must therefore have `GasUsed =< GasWanted`. Both `GasWanted` and `GasUsed` are relayed to the underlying consensus engine when [`FinalizeBlock`](../advanced/00-baseapp.md#finalizeblock) returns.
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"label": "Beginner",
|
||||
"position": 1,
|
||||
"link": null
|
||||
}
|
||||
Reference in New Issue
Block a user