docs: 10180 Fix SDK (#10237)
* docs: Fix Cosmos-sdk references in md files * Fix SDK to Cosmos SDK in all found places and adjust grammar in turn * Add changelog entry * Update docs/core/context.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/architecture/adr-010-modular-antehandler.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/basics/README.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/architecture/adr-040-storage-and-smt-state-commitments.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/core/baseapp.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/basics/accounts.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * docs 10180 fix 'an Cosmos SDK' where used Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch>
This commit is contained in:
Brenn Hill
co-authored by
Barrie Byron
Amaury
Robert Zaremba
Barrie Byron
Amaury
Robert Zaremba
parent
f757c90f61
commit
a47bd592e9
@@ -4,22 +4,22 @@ order: 1
|
||||
|
||||
# BaseApp
|
||||
|
||||
This document describes `BaseApp`, the abstraction that implements the core functionalities of an SDK application. {synopsis}
|
||||
This document describes `BaseApp`, the abstraction that implements the core functionalities of a Cosmos SDK application. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
|
||||
- [Lifecycle of an SDK transaction](../basics/tx-lifecycle.md) {prereq}
|
||||
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
|
||||
- [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq}
|
||||
|
||||
## Introduction
|
||||
|
||||
`BaseApp` is a base type that implements the core of an SDK application, namely:
|
||||
`BaseApp` is a base type that implements the core of a Cosmos SDK application, namely:
|
||||
|
||||
- The [Application Blockchain Interface](#abci), for the state-machine to communicate with the underlying consensus engine (e.g. Tendermint).
|
||||
- [Service Routers](#service-routers), to route messages and queries to the appropriate module.
|
||||
- Different [states](#states), as the state-machine can have different volatile states updated based on the ABCI message received.
|
||||
|
||||
The goal of `BaseApp` is to provide the fundamental layer of an SDK application
|
||||
The goal of `BaseApp` is to provide the fundamental layer of a Cosmos SDK application
|
||||
that developers can easily extend to build their own custom application. Usually,
|
||||
developers will create a custom type for their application, like so:
|
||||
|
||||
|
||||
+11
-11
@@ -4,13 +4,13 @@ order: 8
|
||||
|
||||
# Command-Line Interface
|
||||
|
||||
This document describes how commmand-line interface (CLI) works on a high-level, for an [**application**](../basics/app-anatomy.md). A separate document for implementing a CLI for an SDK [**module**](../building-modules/intro.md) can be found [here](../building-modules/module-interfaces.md#cli). {synopsis}
|
||||
This document describes how commmand-line interface (CLI) works on a high-level, for an [**application**](../basics/app-anatomy.md). A separate document for implementing a CLI for a Cosmos SDK [**module**](../building-modules/intro.md) can be found [here](../building-modules/module-interfaces.md#cli). {synopsis}
|
||||
|
||||
## Command-Line Interface
|
||||
|
||||
### Example Command
|
||||
|
||||
There is no set way to create a CLI, but SDK modules typically use the [Cobra Library](https://github.com/spf13/cobra). Building a CLI with Cobra entails defining commands, arguments, and flags. [**Commands**](#commands) understand the actions users wish to take, such as `tx` for creating a transaction and `query` for querying the application. Each command can also have nested subcommands, necessary for naming the specific transaction type. Users also supply **Arguments**, such as account numbers to send coins to, and [**Flags**](#flags) to modify various aspects of the commands, such as gas prices or which node to broadcast to.
|
||||
There is no set way to create a CLI, but Cosmos SDK modules typically use the [Cobra Library](https://github.com/spf13/cobra). Building a CLI with Cobra entails defining commands, arguments, and flags. [**Commands**](#commands) understand the actions users wish to take, such as `tx` for creating a transaction and `query` for querying the application. Each command can also have nested subcommands, necessary for naming the specific transaction type. Users also supply **Arguments**, such as account numbers to send coins to, and [**Flags**](#flags) to modify various aspects of the commands, such as gas prices or which node to broadcast to.
|
||||
|
||||
Here is an example of a command a user might enter to interact with the simapp CLI `simd` in order to send some tokens:
|
||||
|
||||
@@ -33,7 +33,7 @@ The CLI interacts with a [node](../core/node.md) to handle this command. The int
|
||||
|
||||
The `main.go` file needs to have a `main()` function that creates a root command, to which all the application commands will be added as subcommands. The root command additionally handles:
|
||||
|
||||
- **setting configurations** by reading in configuration files (e.g. the sdk config file).
|
||||
- **setting configurations** by reading in configuration files (e.g. the Cosmos SDK config file).
|
||||
- **adding any flags** to it, such as `--chain-id`.
|
||||
- **instantiating the `codec`** by calling the application's `MakeCodec()` function (called `MakeTestEncodingConfig` in `simapp`). The [`codec`](../core/encoding.md) is used to encode and decode data structures for the application - stores can only persist `[]byte`s so the developer must define a serialization format for their data structures or use the default, Protobuf.
|
||||
- **adding subcommand** for all the possible user interactions, including [transaction commands](#transaction-commands) and [query commands](#query-commands).
|
||||
@@ -52,9 +52,9 @@ Every application CLI first constructs a root command, then adds functionality b
|
||||
|
||||
The root command (called `rootCmd`) is what the user first types into the command line to indicate which application they wish to interact with. The string used to invoke the command (the "Use" field) is typically the name of the application suffixed with `-d`, e.g. `simd` or `gaiad`. The root command typically includes the following commands to support basic functionality in the application.
|
||||
|
||||
- **Status** command from the SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`.
|
||||
- **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys) from the SDK client tools, which includes a collection of subcommands for using the key functions in the SDK crypto tools, including adding a new key and saving it to the keyring, listing all public keys stored in the keyring, and deleting a key. For example, users can type `simd keys add <name>` to add a new key and save an encrypted copy to the keyring, using the flag `--recover` to recover a private key from a seed phrase or the flag `--multisig` to group multiple keys together to create a multisig key. For full details on the `add` key command, see the code [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../run-node/keyring.md).
|
||||
- **Server** commands from the SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on [cobra](github.com/spf13/cobra)) necessary to fully bootstrap an application. The package exposes two core functions: `StartCmd` and `ExportCmd` which creates commands to start the application and export state respectively. Click [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/server) to learn more.
|
||||
- **Status** command from the Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`.
|
||||
- **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys) from the Cosmos SDK client tools, which includes a collection of subcommands for using the key functions in the Cosmos SDK crypto tools, including adding a new key and saving it to the keyring, listing all public keys stored in the keyring, and deleting a key. For example, users can type `simd keys add <name>` to add a new key and save an encrypted copy to the keyring, using the flag `--recover` to recover a private key from a seed phrase or the flag `--multisig` to group multiple keys together to create a multisig key. For full details on the `add` key command, see the code [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../run-node/keyring.md).
|
||||
- **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on [cobra](github.com/spf13/cobra)) necessary to fully bootstrap an application. The package exposes two core functions: `StartCmd` and `ExportCmd` which creates commands to start the application and export state respectively. Click [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/server) to learn more.
|
||||
- [**Transaction**](#transaction-commands) commands.
|
||||
- [**Query**](#query-commands) commands.
|
||||
|
||||
@@ -63,12 +63,12 @@ Next is an example `rootCmd` function from the `simapp` application. It instanti
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L37-L150
|
||||
|
||||
`rootCmd` has a function called `initAppConfig()` which is useful for setting the application's custom configs.
|
||||
By default app uses Tendermint app config template from SDK, which can be over-written via `initAppConfig()`.
|
||||
By default app uses Tendermint app config template from Cosmos SDK, which can be over-written via `initAppConfig()`.
|
||||
Here's an example code to override default `app.toml` template.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L84-L117
|
||||
|
||||
The `initAppConfig()` also allows overriding the default SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/server/config/config.go#L199). One example is the `min-gas-prices` config, which defines the minimum gas prices a validator is willing to accept for processing a transaction. By default, the SDK sets this parameter to `""` (empty string), which forces all validators to tweak their own `app.toml` and set a non-empty value, or else the node will halt on startup. This might not be the best UX for validators, so the chain developer can set a default `app.toml` value for validators inside this `initAppConfig()` function.
|
||||
The `initAppConfig()` also allows overriding the default Cosmos SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/server/config/config.go#L199). One example is the `min-gas-prices` config, which defines the minimum gas prices a validator is willing to accept for processing a transaction. By default, the Cosmos SDK sets this parameter to `""` (empty string), which forces all validators to tweak their own `app.toml` and set a non-empty value, or else the node will halt on startup. This might not be the best UX for validators, so the chain developer can set a default `app.toml` value for validators inside this `initAppConfig()` function.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/aa9b055ddb46aacd4737335a92d0b8a82d577341/simapp/simd/cmd/root.go#L101-L116
|
||||
|
||||
@@ -83,7 +83,7 @@ The root-level `status` and `keys` subcommands are common across most applicatio
|
||||
This `txCmd` function adds all the transaction available to end-users for the application. This typically includes:
|
||||
|
||||
- **Sign command** from the [`auth`](../../x/auth/spec/README.md) module that signs messages in a transaction. To enable multisig, add the `auth` module's `MultiSign` command. Since every transaction requires some sort of signature in order to be valid, the signing command is necessary for every application.
|
||||
- **Broadcast command** from the SDK client tools, to broadcast transactions.
|
||||
- **Broadcast command** from the Cosmos SDK client tools, to broadcast transactions.
|
||||
- **All [module transaction commands](../building-modules/module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddTxCommands()` function.
|
||||
|
||||
Here is an example of a `txCmd` aggregating these subcommands from the `simapp` application:
|
||||
@@ -100,8 +100,8 @@ This `queryCmd` function adds all the queries available to end-users for the app
|
||||
|
||||
- **QueryTx** and/or other transaction query commands] from the `auth` module which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block.
|
||||
- **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address.
|
||||
- **Validator command** from the SDK rpc client tools, which displays the validator set of a given height.
|
||||
- **Block command** from the SDK rpc client tools, which displays the block data for a given height.
|
||||
- **Validator command** from the Cosmos SDK rpc client tools, which displays the validator set of a given height.
|
||||
- **Block command** from the Cosmos SDK rpc client tools, which displays the block data for a given height.
|
||||
- **All [module query commands](../building-modules/module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/module-manager.md#basic-manager) `AddQueryCommands()` function.
|
||||
|
||||
Here is an example of a `queryCmd` aggregating subcommands from the `simapp` application:
|
||||
|
||||
@@ -8,12 +8,12 @@ The `context` is a data structure intended to be passed from function to functio
|
||||
|
||||
## Pre-requisites Readings
|
||||
|
||||
- [Anatomy of an SDK Application](../basics/app-anatomy.md) {prereq}
|
||||
- [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
|
||||
- [Lifecycle of a Transaction](../basics/tx-lifecycle.md) {prereq}
|
||||
|
||||
## Context Definition
|
||||
|
||||
The SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://golang.org/pkg/context) as its base, and has many additional types within its definition that are specific to the Cosmos SDK. The `Context` is integral to transaction processing in that it allows modules to easily access their respective [store](./store.md#base-layer-kvstores) in the [`multistore`](./store.md#multistore) and retrieve transactional context such as the block header and gas meter.
|
||||
The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://golang.org/pkg/context) as its base, and has many additional types within its definition that are specific to the Cosmos SDK. The `Context` is integral to transaction processing in that it allows modules to easily access their respective [store](./store.md#base-layer-kvstores) in the [`multistore`](./store.md#multistore) and retrieve transactional context such as the block header and gas meter.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/context.go#L16-L39
|
||||
|
||||
@@ -21,7 +21,7 @@ The SDK `Context` is a custom data structure that contains Go's stdlib [`context
|
||||
- **Multistore:** Every application's `BaseApp` contains a [`CommitMultiStore`](./store.md#multistore) which is provided when a `Context` is created. Calling the `KVStore()` and `TransientStore()` methods allows modules to fetch their respective [`KVStore`](./store.md#base-layer-kvstores) using their unique `StoreKey`.
|
||||
- **ABCI Header:** The [header](https://tendermint.com/docs/spec/abci/abci.html#header) is an ABCI type. It carries important information about the state of the blockchain, such as block height and proposer of the current block.
|
||||
- **Chain ID:** The unique identification number of the blockchain a block pertains to.
|
||||
- **Transaction Bytes:** The `[]byte` representation of a transaction being processed using the context. Every transaction is processed by various parts of the SDK and consensus engine (e.g. Tendermint) throughout its [lifecycle](../basics/tx-lifecycle.md), some of which to not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./encoding.md) such as [Amino](./encoding.md).
|
||||
- **Transaction Bytes:** The `[]byte` representation of a transaction being processed using the context. Every transaction is processed by various parts of the Cosmos SDK and consensus engine (e.g. Tendermint) throughout its [lifecycle](../basics/tx-lifecycle.md), some of which to not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./encoding.md) such as [Amino](./encoding.md).
|
||||
- **Logger:** A `logger` from the Tendermint libraries. Learn more about logs [here](https://tendermint.com/docs/tendermint-core/how-to-read-logs.html#how-to-read-logs). Modules call this method to create their own unique module-specific logger.
|
||||
- **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://tendermint.com/docs/spec/abci/abci.html#voteinfo), which includes the name of a validator and a boolean indicating whether they have signed the block.
|
||||
- **Gas Meters:** Specifically, a [`gasMeter`](../basics/gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../basics/gas-fees.md#block-gas-meter) for the entire block it belongs to. Users specify how much in fees they wish to pay for the execution of their transaction; these gas meters keep track of how much [gas](../basics/gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts.
|
||||
|
||||
@@ -4,11 +4,11 @@ order: 6
|
||||
|
||||
# Encoding
|
||||
|
||||
While encoding in the SDK used to be mainly handled by `go-amino` codec, the SDK is moving towards using `gogoprotobuf` for both state and client-side encoding. {synopsis}
|
||||
While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, the Cosmos SDK is moving towards using `gogoprotobuf` for both state and client-side encoding. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
|
||||
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
|
||||
|
||||
## Encoding
|
||||
|
||||
@@ -69,7 +69,7 @@ typically used for when the data needs to be streamed or grouped together
|
||||
|
||||
### Gogoproto
|
||||
|
||||
Modules are encouraged to utilize Protobuf encoding for their respective types. In the SDK, we use the [Gogoproto](https://github.com/gogo/protobuf) specific implementation of the Protobuf spec that offers speed and DX improvements compared to the official [Google protobuf implementation](https://github.com/protocolbuffers/protobuf).
|
||||
Modules are encouraged to utilize Protobuf encoding for their respective types. In the Cosmos SDK, we use the [Gogoproto](https://github.com/gogo/protobuf) specific implementation of the Protobuf spec that offers speed and DX improvements compared to the official [Google protobuf implementation](https://github.com/protocolbuffers/protobuf).
|
||||
|
||||
### Guidelines for protobuf message definitions
|
||||
|
||||
@@ -84,7 +84,7 @@ In addition to [following official Protocol Buffer guidelines](https://developer
|
||||
|
||||
Another important use of Protobuf is the encoding and decoding of
|
||||
[transactions](./transactions.md). Transactions are defined by the application or
|
||||
the SDK but are then passed to the underlying consensus engine to be relayed to
|
||||
the Cosmos SDK but are then passed to the underlying consensus engine to be relayed to
|
||||
other peers. Since the underlying consensus engine is agnostic to the application,
|
||||
the consensus engine accepts only transactions in the form of raw bytes.
|
||||
|
||||
@@ -154,7 +154,7 @@ bz, err := cdc.Marshal(profile)
|
||||
jsonBz, err := cdc.MarshalJSON(profile)
|
||||
```
|
||||
|
||||
To summarize, to encode an interface, you must 1/ pack the interface into an `Any` and 2/ marshal the `Any`. For convenience, the SDK provides a `MarshalInterface` method to bundle these two steps. Have a look at [a real-life example in the x/auth module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/keeper/keeper.go#L218-L221).
|
||||
To summarize, to encode an interface, you must 1/ pack the interface into an `Any` and 2/ marshal the `Any`. For convenience, the Cosmos SDK provides a `MarshalInterface` method to bundle these two steps. Have a look at [a real-life example in the x/auth module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/keeper/keeper.go#L218-L221).
|
||||
|
||||
The reverse operation of retrieving the concrete Go type from inside an `Any`, called "unpacking", is done with the `GetCachedValue()` on `Any`.
|
||||
|
||||
@@ -189,9 +189,9 @@ The `UnpackInterfaces` gets called recursively on all structs implementing this
|
||||
|
||||
For more information about interface encoding, and especially on `UnpackInterfaces` and how the `Any`'s `type_url` gets resolved using the `InterfaceRegistry`, please refer to [ADR-019](../architecture/adr-019-protobuf-state-encoding.md).
|
||||
|
||||
#### `Any` Encoding in the SDK
|
||||
#### `Any` Encoding in the Cosmos SDK
|
||||
|
||||
The above `Profile` example is a fictive example used for educational purposes. In the SDK, we use `Any` encoding in several places (non-exhaustive list):
|
||||
The above `Profile` example is a fictive example used for educational purposes. In the Cosmos SDK, we use `Any` encoding in several places (non-exhaustive list):
|
||||
|
||||
- the `cryptotypes.PubKey` interface for encoding different types of public keys,
|
||||
- the `sdk.Msg` interface for encoding different `Msg`s in a transaction,
|
||||
@@ -242,7 +242,7 @@ message MsgSubmitEvidence {
|
||||
}
|
||||
```
|
||||
|
||||
The SDK `codec.Codec` interface provides support methods `MarshalInterface` and `UnmarshalInterface` to easy encoding of state to `Any`.
|
||||
The Cosmos SDK `codec.Codec` interface provides support methods `MarshalInterface` and `UnmarshalInterface` to easy encoding of state to `Any`.
|
||||
|
||||
Module should register interfaces using `InterfaceRegistry` which provides a mechanism for registering interfaces: `RegisterInterface(protoName string, iface interface{})` and implementations: `RegisterImplementations(iface interface{}, impls ...proto.Message)` that can be safely unpacked from Any, similarly to type registration with Amino:
|
||||
|
||||
|
||||
+5
-5
@@ -8,7 +8,7 @@ order: 9
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
|
||||
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
|
||||
- [Tendermint Documentation on Events](https://docs.tendermint.com/master/spec/abci/abci.html#events) {prereq}
|
||||
|
||||
## Events
|
||||
@@ -20,7 +20,7 @@ take the form of: `{eventType}.{attributeKey}={attributeValue}`.
|
||||
|
||||
An Event contains:
|
||||
|
||||
- A `type` to categorize the Event at a high-level; for example, the SDK uses the `"message"` type to filter Events by `Msg`s.
|
||||
- A `type` to categorize the Event at a high-level; for example, the Cosmos SDK uses the `"message"` type to filter Events by `Msg`s.
|
||||
- A list of `attributes` are key-value pairs that give more information about the categorized Event. For example, for the `"message"` type, we can filter Events by key-value pairs using `message.action={some_action}`, `message.module={some_module}` or `message.sender={some_sender}`.
|
||||
|
||||
::: tip
|
||||
@@ -41,7 +41,7 @@ Events are returned to the underlying consensus engine in the response of the fo
|
||||
|
||||
### Examples
|
||||
|
||||
The following examples show how to query Events using the SDK.
|
||||
The following examples show how to query Events using the Cosmos SDK.
|
||||
|
||||
| Event | Description |
|
||||
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -128,10 +128,10 @@ where `senderAddress` is an address following the [`AccAddress`](../basics/accou
|
||||
|
||||
## Typed Events (coming soon)
|
||||
|
||||
As previously described, Events are defined on a per-module basis. It is the responsibility of the module developer to define Event types and Event attributes. Except in the `spec/XX_events.md` file, these Event types and attributes are unfortunately not easily discoverable, so the SDK proposes to use Protobuf-defined [Typed Events](../architecture/adr-032-typed-events.md) for emitting and querying Events.
|
||||
As previously described, Events are defined on a per-module basis. It is the responsibility of the module developer to define Event types and Event attributes. Except in the `spec/XX_events.md` file, these Event types and attributes are unfortunately not easily discoverable, so the Cosmos SDK proposes to use Protobuf-defined [Typed Events](../architecture/adr-032-typed-events.md) for emitting and querying Events.
|
||||
|
||||
The Typed Events proposal has not yet been fully implemented. Documentation is not yet available.
|
||||
|
||||
## Next {hide}
|
||||
|
||||
Learn about SDK [telemetry](./telemetry.md) {hide}
|
||||
Learn about Cosmos SDK [telemetry](./telemetry.md) {hide}
|
||||
|
||||
@@ -21,7 +21,7 @@ The node also exposes some other endpoints, such as the Tendermint P2P endpoint,
|
||||
## gRPC Server
|
||||
|
||||
::: warning
|
||||
A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`.
|
||||
A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the Cosmos SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`.
|
||||
|
||||
To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`:
|
||||
|
||||
@@ -32,7 +32,7 @@ replace google.golang.org/grpc => google.golang.org/grpc v1.33.2
|
||||
Please see [issue #8392](https://github.com/cosmos/cosmos-sdk/issues/8392) for more info.
|
||||
:::
|
||||
|
||||
Cosmos SDK v0.40 introduced Protobuf as the main [encoding](./encoding) library, and this brings a wide range of Protobuf-based tools that can be plugged into the SDK. One such tool is [gRPC](https://grpc.io), a modern open source high performance RPC framework that has decent client support in several languages.
|
||||
Cosmos SDK v0.40 introduced Protobuf as the main [encoding](./encoding) library, and this brings a wide range of Protobuf-based tools that can be plugged into the Cosmos SDK. One such tool is [gRPC](https://grpc.io), a modern open source high performance RPC framework that has decent client support in several languages.
|
||||
|
||||
Each module exposes a [Protobuf `Query` service](../building-modules/messages-and-queries.md#queries) that defines state queries. The `Query` services and a transaction service used to broadcast transactions are hooked up to the gRPC server via the following function inside the application:
|
||||
|
||||
@@ -65,9 +65,9 @@ All routes are configured under the following fields in `~/.simapp/config/app.to
|
||||
|
||||
### gRPC-gateway REST Routes
|
||||
|
||||
If, for various reasons, you cannot use gRPC (for example, you are building a web application, and browsers don't support HTTP2 on which gRPC is built), then the SDK offers REST routes via gRPC-gateway.
|
||||
If, for various reasons, you cannot use gRPC (for example, you are building a web application, and browsers don't support HTTP2 on which gRPC is built), then the Cosmos SDK offers REST routes via gRPC-gateway.
|
||||
|
||||
[gRPC-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) is a tool to expose gRPC endpoints as REST endpoints. For each gRPC endpoint defined in a Protobuf `Query` service, the SDK offers a REST equivalent. For instance, querying a balance could be done via the `/cosmos.bank.v1beta1.QueryAllBalances` gRPC endpoint, or alternatively via the gRPC-gateway `"/cosmos/bank/v1beta1/balances/{address}"` REST endpoint: both will return the same result. For each RPC method defined in a Protobuf `Query` service, the corresponding REST endpoint is defined as an option:
|
||||
[gRPC-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) is a tool to expose gRPC endpoints as REST endpoints. For each gRPC endpoint defined in a Protobuf `Query` service, the Cosmos SDK offers a REST equivalent. For instance, querying a balance could be done via the `/cosmos.bank.v1beta1.QueryAllBalances` gRPC endpoint, or alternatively via the gRPC-gateway `"/cosmos/bank/v1beta1/balances/{address}"` REST endpoint: both will return the same result. For each RPC method defined in a Protobuf `Query` service, the corresponding REST endpoint is defined as an option:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/proto/cosmos/bank/v1beta1/query.proto#L19-L22
|
||||
|
||||
@@ -79,7 +79,7 @@ A [Swagger](https://swagger.io/) (or OpenAPIv2) specification file is exposed un
|
||||
|
||||
Enabling the `/swagger` endpoint is configurable inside `~/.simapp/config/app.toml` via the `api.swagger` field, which is set to true by default.
|
||||
|
||||
For application developers, you may want to generate your own Swagger definitions based on your custom modules. The SDK's [Swagger generation script](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/scripts/protoc-swagger-gen.sh) is a good place to start.
|
||||
For application developers, you may want to generate your own Swagger definitions based on your custom modules. The Cosmos SDK's [Swagger generation script](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/scripts/protoc-swagger-gen.sh) is a good place to start.
|
||||
|
||||
## Tendermint RPC
|
||||
|
||||
|
||||
+5
-5
@@ -4,7 +4,7 @@ order: 4
|
||||
|
||||
# Node Client (Daemon)
|
||||
|
||||
The main endpoint of an SDK application is the daemon client, otherwise known as the full-node client. The full-node runs the state-machine, starting from a genesis file. It connects to peers running the same client in order to receive and relay transactions, block proposals and signatures. The full-node is constituted of the application, defined with the Cosmos SDK, and of a consensus engine connected to the application via the ABCI. {synopsis}
|
||||
The main endpoint of a Cosmos SDK application is the daemon client, otherwise known as the full-node client. The full-node runs the state-machine, starting from a genesis file. It connects to peers running the same client in order to receive and relay transactions, block proposals and signatures. The full-node is constituted of the application, defined with the Cosmos SDK, and of a consensus engine connected to the application via the ABCI. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
@@ -12,7 +12,7 @@ The main endpoint of an SDK application is the daemon client, otherwise known as
|
||||
|
||||
## `main` function
|
||||
|
||||
The full-node client of any SDK application is built by running a `main` function. The client is generally named by appending the `-d` suffix to the application name (e.g. `appd` for an application named `app`), and the `main` function is defined in a `./appd/cmd/main.go` file. Running this function creates an executable `appd` that comes with a set of commands. For an app named `app`, the main command is [`appd start`](#start-command), which starts the full-node.
|
||||
The full-node client of any Cosmos SDK application is built by running a `main` function. The client is generally named by appending the `-d` suffix to the application name (e.g. `appd` for an application named `app`), and the `main` function is defined in a `./appd/cmd/main.go` file. Running this function creates an executable `appd` that comes with a set of commands. For an app named `app`, the main command is [`appd start`](#start-command), which starts the full-node.
|
||||
|
||||
In general, developers will implement the `main.go` function with the following structure:
|
||||
|
||||
@@ -20,11 +20,11 @@ In general, developers will implement the `main.go` function with the following
|
||||
- Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../basics/accounts.md#addresses).
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/config.go#L13-L24
|
||||
- Using [cobra](https://github.com/spf13/cobra), the root command of the full-node client is created. After that, all the custom commands of the application are added using the `AddCommand()` method of `rootCmd`.
|
||||
- Add default server commands to `rootCmd` using the `server.AddCommands()` method. These commands are separated from the ones added above since they are standard and defined at SDK level. They should be shared by all SDK-based applications. They include the most important command: the [`start` command](#start-command).
|
||||
- Add default server commands to `rootCmd` using the `server.AddCommands()` method. These commands are separated from the ones added above since they are standard and defined at Cosmos SDK level. They should be shared by all Cosmos SDK-based applications. They include the most important command: the [`start` command](#start-command).
|
||||
- Prepare and execute the `executor`.
|
||||
+++ https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/libs/cli/setup.go#L74-L78
|
||||
|
||||
See an example of `main` function from the `simapp` application, the SDK's application for demo purposes:
|
||||
See an example of `main` function from the `simapp` application, the Cosmos SDK's application for demo purposes:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/main.go
|
||||
|
||||
@@ -36,7 +36,7 @@ The `start` command is defined in the `/server` folder of the Cosmos SDK. It is
|
||||
# For an example app named "app", the following command starts the full-node.
|
||||
appd start
|
||||
|
||||
# Using the SDK's own simapp, the following commands start the simapp node.
|
||||
# Using the Cosmos SDK's own simapp, the following commands start the simapp node.
|
||||
simd start
|
||||
```
|
||||
|
||||
|
||||
+1
-1
@@ -8,7 +8,7 @@ order: 11
|
||||
|
||||
When thinking about security, it is good to start with a specific threat model. Our threat model is the following:
|
||||
|
||||
> We assume that a thriving ecosystem of Cosmos-SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules.
|
||||
> We assume that a thriving ecosystem of Cosmos SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules.
|
||||
|
||||
The Cosmos SDK is designed to address this threat by being the
|
||||
foundation of an object capability system.
|
||||
|
||||
+16
-16
@@ -2469,7 +2469,7 @@ ReflectionService defines a service for interface reflection.
|
||||
<a name="cosmos.base.reflection.v2alpha1.AppDescriptor"></a>
|
||||
|
||||
### AppDescriptor
|
||||
AppDescriptor describes a cosmos-sdk based application
|
||||
AppDescriptor describes a Cosmos SDK based application
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
@@ -2750,7 +2750,7 @@ InterfaceImplementerDescriptor describes an interface implementer
|
||||
<a name="cosmos.base.reflection.v2alpha1.MsgDescriptor"></a>
|
||||
|
||||
### MsgDescriptor
|
||||
MsgDescriptor describes a cosmos-sdk message that can be delivered with a transaction
|
||||
MsgDescriptor describes a Cosmos SDK message that can be delivered with a transaction
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
@@ -2783,7 +2783,7 @@ because it would be redundant with the grpc reflection service
|
||||
<a name="cosmos.base.reflection.v2alpha1.QueryServiceDescriptor"></a>
|
||||
|
||||
### QueryServiceDescriptor
|
||||
QueryServiceDescriptor describes a cosmos-sdk queryable service
|
||||
QueryServiceDescriptor describes a Cosmos SDK queryable service
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
@@ -2800,12 +2800,12 @@ QueryServiceDescriptor describes a cosmos-sdk queryable service
|
||||
<a name="cosmos.base.reflection.v2alpha1.QueryServicesDescriptor"></a>
|
||||
|
||||
### QueryServicesDescriptor
|
||||
QueryServicesDescriptor contains the list of cosmos-sdk queriable services
|
||||
QueryServicesDescriptor contains the list of Cosmos SDK queriable services
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
| ----- | ---- | ----- | ----------- |
|
||||
| `query_services` | [QueryServiceDescriptor](#cosmos.base.reflection.v2alpha1.QueryServiceDescriptor) | repeated | query_services is a list of cosmos-sdk QueryServiceDescriptor |
|
||||
| `query_services` | [QueryServiceDescriptor](#cosmos.base.reflection.v2alpha1.QueryServiceDescriptor) | repeated | query_services is a list of Cosmos SDK QueryServiceDescriptor |
|
||||
|
||||
|
||||
|
||||
@@ -2861,7 +2861,7 @@ ReflectionService defines a service for application reflection.
|
||||
|
||||
| Method Name | Request Type | Response Type | Description | HTTP Verb | Endpoint |
|
||||
| ----------- | ------------ | ------------- | ------------| ------- | -------- |
|
||||
| `GetAuthnDescriptor` | [GetAuthnDescriptorRequest](#cosmos.base.reflection.v2alpha1.GetAuthnDescriptorRequest) | [GetAuthnDescriptorResponse](#cosmos.base.reflection.v2alpha1.GetAuthnDescriptorResponse) | GetAuthnDescriptor returns information on how to authenticate transactions in the application NOTE: this RPC is still experimental and might be subject to breaking changes or removal in future releases of the cosmos-sdk. | GET|/cosmos/base/reflection/v1beta1/app_descriptor/authn|
|
||||
| `GetAuthnDescriptor` | [GetAuthnDescriptorRequest](#cosmos.base.reflection.v2alpha1.GetAuthnDescriptorRequest) | [GetAuthnDescriptorResponse](#cosmos.base.reflection.v2alpha1.GetAuthnDescriptorResponse) | GetAuthnDescriptor returns information on how to authenticate transactions in the application NOTE: this RPC is still experimental and might be subject to breaking changes or removal in future releases of the Cosmos SDK. | GET|/cosmos/base/reflection/v1beta1/app_descriptor/authn|
|
||||
| `GetChainDescriptor` | [GetChainDescriptorRequest](#cosmos.base.reflection.v2alpha1.GetChainDescriptorRequest) | [GetChainDescriptorResponse](#cosmos.base.reflection.v2alpha1.GetChainDescriptorResponse) | GetChainDescriptor returns the description of the chain | GET|/cosmos/base/reflection/v1beta1/app_descriptor/chain|
|
||||
| `GetCodecDescriptor` | [GetCodecDescriptorRequest](#cosmos.base.reflection.v2alpha1.GetCodecDescriptorRequest) | [GetCodecDescriptorResponse](#cosmos.base.reflection.v2alpha1.GetCodecDescriptorResponse) | GetCodecDescriptor returns the descriptor of the codec of the application | GET|/cosmos/base/reflection/v1beta1/app_descriptor/codec|
|
||||
| `GetConfigurationDescriptor` | [GetConfigurationDescriptorRequest](#cosmos.base.reflection.v2alpha1.GetConfigurationDescriptorRequest) | [GetConfigurationDescriptorResponse](#cosmos.base.reflection.v2alpha1.GetConfigurationDescriptorResponse) | GetConfigurationDescriptor returns the descriptor for the sdk.Config of the application | GET|/cosmos/base/reflection/v1beta1/app_descriptor/configuration|
|
||||
@@ -2882,7 +2882,7 @@ ReflectionService defines a service for application reflection.
|
||||
<a name="cosmos.base.snapshots.v1beta1.Metadata"></a>
|
||||
|
||||
### Metadata
|
||||
Metadata contains SDK-specific snapshot metadata.
|
||||
Metadata contains Cosmos SDK-specific snapshot metadata.
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
@@ -3559,7 +3559,7 @@ Msg defines the bank Msg service.
|
||||
|
||||
### PrivKey
|
||||
Deprecated: PrivKey defines a ed25519 private key.
|
||||
NOTE: ed25519 keys must not be used in SDK apps except in a tendermint validator context.
|
||||
NOTE: ed25519 keys must not be used in Cosmos SDK apps except in a tendermint validator context.
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
@@ -3574,8 +3574,8 @@ NOTE: ed25519 keys must not be used in SDK apps except in a tendermint validator
|
||||
<a name="cosmos.crypto.ed25519.PubKey"></a>
|
||||
|
||||
### PubKey
|
||||
PubKey is an ed25519 public key for handling Tendermint keys in SDK.
|
||||
It's needed for Any serialization and SDK compatibility.
|
||||
PubKey is an ed25519 public key for handling Tendermint keys in the Cosmos SDK.
|
||||
It's needed for Any serialization and Cosmos SDK compatibility.
|
||||
It must not be used in a non Tendermint key context because it doesn't implement
|
||||
ADR-28. Nevertheless, you will like to use ed25519 in app user level
|
||||
then you must create a new proto message and follow ADR-28 for Address construction.
|
||||
@@ -9089,7 +9089,7 @@ Query defines the gRPC querier service.
|
||||
<a name="cosmos.staking.v1beta1.MsgBeginRedelegate"></a>
|
||||
|
||||
### MsgBeginRedelegate
|
||||
MsgBeginRedelegate defines a SDK message for performing a redelegation
|
||||
MsgBeginRedelegate defines a Cosmos SDK message for performing a redelegation
|
||||
of coins from a delegator and source validator to a destination validator.
|
||||
|
||||
|
||||
@@ -9123,7 +9123,7 @@ MsgBeginRedelegateResponse defines the Msg/BeginRedelegate response type.
|
||||
<a name="cosmos.staking.v1beta1.MsgCreateValidator"></a>
|
||||
|
||||
### MsgCreateValidator
|
||||
MsgCreateValidator defines a SDK message for creating a new validator.
|
||||
MsgCreateValidator defines a Cosmos SDK message for creating a new validator.
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
@@ -9154,7 +9154,7 @@ MsgCreateValidatorResponse defines the Msg/CreateValidator response type.
|
||||
<a name="cosmos.staking.v1beta1.MsgDelegate"></a>
|
||||
|
||||
### MsgDelegate
|
||||
MsgDelegate defines a SDK message for performing a delegation of coins
|
||||
MsgDelegate defines a Cosmos SDK message for performing a delegation of coins
|
||||
from a delegator to a validator.
|
||||
|
||||
|
||||
@@ -9182,7 +9182,7 @@ MsgDelegateResponse defines the Msg/Delegate response type.
|
||||
<a name="cosmos.staking.v1beta1.MsgEditValidator"></a>
|
||||
|
||||
### MsgEditValidator
|
||||
MsgEditValidator defines a SDK message for editing an existing validator.
|
||||
MsgEditValidator defines a Cosmos SDK message for editing an existing validator.
|
||||
|
||||
|
||||
| Field | Type | Label | Description |
|
||||
@@ -9210,7 +9210,7 @@ MsgEditValidatorResponse defines the Msg/EditValidator response type.
|
||||
<a name="cosmos.staking.v1beta1.MsgUndelegate"></a>
|
||||
|
||||
### MsgUndelegate
|
||||
MsgUndelegate defines a SDK message for performing an undelegation from a
|
||||
MsgUndelegate defines a Cosmos SDK message for performing an undelegation from a
|
||||
delegate and a validator.
|
||||
|
||||
|
||||
@@ -9873,7 +9873,7 @@ Plan specifies information about a planned upgrade and when it should occur.
|
||||
| Field | Type | Label | Description |
|
||||
| ----- | ---- | ----- | ----------- |
|
||||
| `name` | [string](#string) | | Sets the name for the upgrade. This name will be used by the upgraded version of the software to apply any special "on-upgrade" commands during the first BeginBlock method after the upgrade is applied. It is also used to detect whether a software version can handle a given upgrade. If no upgrade handler with this name has been set in the software, it will be assumed that the software is out-of-date when the upgrade Time or Height is reached and the software will exit. |
|
||||
| `time` | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | **Deprecated.** Deprecated: Time based upgrades have been deprecated. Time based upgrade logic has been removed from the SDK. If this field is not empty, an error will be thrown. |
|
||||
| `time` | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | **Deprecated.** Deprecated: Time based upgrades have been deprecated. Time based upgrade logic has been removed from the Cosmos SDK. If this field is not empty, an error will be thrown. |
|
||||
| `height` | [int64](#int64) | | The height at which the upgrade must be performed. Only used if Time is not set. |
|
||||
| `info` | [string](#string) | | Any application specific upgrade info to be included on-chain such as a git commit that validators could automatically upgrade to |
|
||||
| `upgraded_client_state` | [google.protobuf.Any](#google.protobuf.Any) | | **Deprecated.** Deprecated: UpgradedClientState field has been deprecated. IBC upgrade logic has been moved to the IBC module in the sub module 02-client. If this field is not empty, an error will be thrown. |
|
||||
|
||||
@@ -6,7 +6,7 @@ order: 12
|
||||
|
||||
`BaseApp.runTx()` function handles Golang panics that might occur during transactions execution, for example, keeper has faced an invalid state and paniced.
|
||||
Depending on the panic type different handler is used, for instance the default one prints an error log message.
|
||||
Recovery middleware is used to add custom panic recovery for SDK application developers.
|
||||
Recovery middleware is used to add custom panic recovery for Cosmos SDK application developers.
|
||||
|
||||
More context could be found in the corresponding [ADR-022](../architecture/adr-022-custom-panic-handling.md).
|
||||
|
||||
@@ -50,7 +50,7 @@ func (k FooKeeper) Do(obj interface{}) {
|
||||
By default that panic would be recovered and an error message will be printed to log. To override that behaviour we should register a custom RecoveryHandler:
|
||||
|
||||
```go
|
||||
// SDK application constructor
|
||||
// Cosmos SDK application constructor
|
||||
customHandler := func(recoveryObj interface{}) error {
|
||||
err, ok := recoveryObj.(error)
|
||||
if !ok {
|
||||
|
||||
@@ -7,7 +7,7 @@ order: 13
|
||||
The Cosmos SDK offers a full fledged simulation framework to fuzz test every
|
||||
message defined by a module.
|
||||
|
||||
On the SDK, this functionality is provided by the[`SimApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/app.go), which is a
|
||||
On the Cosmos SDK, this functionality is provided by the[`SimApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/app.go), which is a
|
||||
`Baseapp` application that is used for running the [`simulation`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/simulation) module.
|
||||
This module defines all the simulation logic as well as the operations for
|
||||
randomized parameters like accounts, balances etc.
|
||||
@@ -63,7 +63,7 @@ generated genesis state (`1`) with manually generated simulation params (`3`).
|
||||
## Usage
|
||||
|
||||
This is a general example of how simulations are run. For more specific examples
|
||||
check the SDK [Makefile](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/Makefile#L251-L287).
|
||||
check the Cosmos SDK [Makefile](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/Makefile#L251-L287).
|
||||
|
||||
```bash
|
||||
$ go test -mod=readonly github.com/cosmos/cosmos-sdk/simapp \
|
||||
@@ -92,9 +92,9 @@ Here are some suggestions when encountering a simulation failure:
|
||||
- Try adding logs to operations that are not logged. You will have to define a
|
||||
[Logger](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/keeper/keeper.go#L66-L69) on your `Keeper`.
|
||||
|
||||
## Use simulation in your SDK-based application
|
||||
## Use simulation in your Cosmos SDK-based application
|
||||
|
||||
Learn how you can integrate the simulation into your SDK-based application:
|
||||
Learn how you can integrate the simulation into your Cosmos SDK-based application:
|
||||
|
||||
- Application Simulation Manager
|
||||
- [Building modules: Simulator](../building-modules/simulator.md)
|
||||
|
||||
+3
-3
@@ -8,11 +8,11 @@ A store is a data structure that holds the state of the application. {synopsis}
|
||||
|
||||
### Pre-requisite Readings
|
||||
|
||||
- [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq}
|
||||
- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq}
|
||||
|
||||
## Introduction to SDK Stores
|
||||
## Introduction to Cosmos SDK Stores
|
||||
|
||||
The Cosmos SDK comes with a large set of stores to persist the state of applications. By default, the main store of SDK applications is a `multistore`, i.e. a store of stores. Developers can add any number of key-value stores to the multistore, depending on their application needs. The multistore exists to support the modularity of the Cosmos SDK, as it lets each module declare and manage their own subset of the state. Key-value stores in the multistore can only be accessed with a specific capability `key`, which is typically held in the [`keeper`](../building-modules/keeper.md) of the module that declared the store.
|
||||
The Cosmos SDK comes with a large set of stores to persist the state of applications. By default, the main store of Cosmos SDK applications is a `multistore`, i.e. a store of stores. Developers can add any number of key-value stores to the multistore, depending on their application needs. The multistore exists to support the modularity of the Cosmos SDK, as it lets each module declare and manage their own subset of the state. Key-value stores in the multistore can only be accessed with a specific capability `key`, which is typically held in the [`keeper`](../building-modules/keeper.md) of the module that declared the store.
|
||||
|
||||
```
|
||||
+-----------------------------------------------------+
|
||||
|
||||
@@ -8,7 +8,7 @@ order: 2
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Anatomy of an SDK Application](../basics/app-anatomy.md) {prereq}
|
||||
- [Anatomy of a Cosmos SDK Application](../basics/app-anatomy.md) {prereq}
|
||||
|
||||
## Transactions
|
||||
|
||||
@@ -18,7 +18,7 @@ When users want to interact with an application and make state changes (e.g. sen
|
||||
|
||||
## Type Definition
|
||||
|
||||
Transaction objects are SDK types that implement the `Tx` interface
|
||||
Transaction objects are Cosmos SDK types that implement the `Tx` interface
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57
|
||||
|
||||
@@ -31,7 +31,7 @@ As a developer, you should rarely manipulate `Tx` directly, as `Tx` is really an
|
||||
|
||||
### Signing Transactions
|
||||
|
||||
Every message in a transaction must be signed by the addresses specified by its `GetSigners`. The SDK currently allows signing transactions in two different ways.
|
||||
Every message in a transaction must be signed by the addresses specified by its `GetSigners`. The Cosmos SDK currently allows signing transactions in two different ways.
|
||||
|
||||
#### `SIGN_MODE_DIRECT` (preferred)
|
||||
|
||||
@@ -39,7 +39,7 @@ The most used implementation of the `Tx` interface is the Protobuf `Tx` message,
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25
|
||||
|
||||
Because Protobuf serialization is not deterministic, the SDK uses an additional `TxRaw` type to denote the pinned bytes over which a transaction is signed. Any user can generate a valid `body` and `auth_info` for a transaction, and serialize these two messages using Protobuf. `TxRaw` then pins the user's exact binary representation of `body` and `auth_info`, called respectively `body_bytes` and `auth_info_bytes`. The document that is signed by all signers of the transaction is `SignDoc` (deterministically serialized using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md)):
|
||||
Because Protobuf serialization is not deterministic, the Cosmos SDK uses an additional `TxRaw` type to denote the pinned bytes over which a transaction is signed. Any user can generate a valid `body` and `auth_info` for a transaction, and serialize these two messages using Protobuf. `TxRaw` then pins the user's exact binary representation of `body` and `auth_info`, called respectively `body_bytes` and `auth_info_bytes`. The document that is signed by all signers of the transaction is `SignDoc` (deterministically serialized using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md)):
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L47-L64
|
||||
|
||||
@@ -66,7 +66,7 @@ Other sign modes, most notably `SIGN_MODE_TEXTUAL`, are being discussed. If you
|
||||
The process of an end-user sending a transaction is:
|
||||
|
||||
- decide on the messages to put into the transaction,
|
||||
- generate the transaction using the SDK's `TxBuilder`,
|
||||
- generate the transaction using the Cosmos SDK's `TxBuilder`,
|
||||
- broadcast the transaction using one of the available interfaces.
|
||||
|
||||
The next paragraphs will describe each of these components, in this order.
|
||||
@@ -136,7 +136,7 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake
|
||||
|
||||
#### gRPC
|
||||
|
||||
[gRPC](https://grpc.io) is introduced in Cosmos SDK 0.40 as the main component for the SDK's RPC layer. The principal usage of gRPC is in the context of modules' [`Query` services](../building-modules). However, the SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service:
|
||||
[gRPC](https://grpc.io) is introduced in Cosmos SDK 0.40 as the main component for the Cosmos SDK's RPC layer. The principal usage of gRPC is in the context of modules' [`Query` services](../building-modules). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/service.proto
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ This document provides steps to use the In-Place Store Migrations upgrade method
|
||||
|
||||
## Tracking Module Versions
|
||||
|
||||
Each module gets assigned a consensus version by the module developer. The consensus version serves as the breaking change version of the module. The SDK keeps track of all module consensus versions in the x/upgrade `VersionMap` store. During an upgrade, the difference between the old `VersionMap` stored in state and the new `VersionMap` is calculated by the Cosmos SDK. For each identified difference, the module-specific migrations are run and the respective consensus version of each upgraded module is incremented.
|
||||
Each module gets assigned a consensus version by the module developer. The consensus version serves as the breaking change version of the module. The Cosmos SDK keeps track of all module consensus versions in the x/upgrade `VersionMap` store. During an upgrade, the difference between the old `VersionMap` stored in state and the new `VersionMap` is calculated by the Cosmos SDK. For each identified difference, the module-specific migrations are run and the respective consensus version of each upgraded module is incremented.
|
||||
|
||||
## Genesis State
|
||||
|
||||
@@ -38,7 +38,7 @@ This information is used by the Cosmos SDK to detect when modules with newer ver
|
||||
|
||||
### Consensus Version
|
||||
|
||||
The consensus version is defined on each app module by the module developer and serves as the breaking change version of the module. The consensus version informs the SDK on which modules need to be upgraded. For example, if the bank module was version 2 and an upgrade introduces bank module 3, the SDK upgrades the bank module and runs the "version 2 to 3" migration script.
|
||||
The consensus version is defined on each app module by the module developer and serves as the breaking change version of the module. The consensus version informs the Cosmos SDK on which modules need to be upgraded. For example, if the bank module was version 2 and an upgrade introduces bank module 3, the Cosmos SDK upgrades the bank module and runs the "version 2 to 3" migration script.
|
||||
|
||||
### Version Map
|
||||
|
||||
|
||||
Reference in New Issue
Block a user