Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

Update docs #8751

Merged
merged 11 commits into from
Mar 16, 2021
4 changes: 2 additions & 2 deletions docs/basics/accounts.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,11 +125,11 @@ aa := sdk.AccAddress(pub.Address().Bytes())

These addresses implement the `Address` interface:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/address.go#L73-L82
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/address.go#L76-L85

Of note, the `Marshal()` and `Bytes()` method both return the same raw `[]byte` form of the address, the former being needed for Protobuf compatibility. Also, the `String()` method is used to return the `bech32` encoded form of the address, which should be the only address format with which end-user interract. Here is an example:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/address.go#L232-L246
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/address.go#L235-L249

## Next {hide}

Expand Down
12 changes: 6 additions & 6 deletions docs/basics/app-anatomy.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,13 +53,13 @@ The first thing defined in `app.go` is the `type` of the application. It is gene

See an example of application type definition from `simapp`, the SDK's own app used for demo and testing purposes:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L139-L181
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L145-L187

### Constructor Function

This function constructs a new application of the type defined in the section above. It must fulfill the `AppCreator` signature in order to be used in the [`start` command](../core/node.md#start-command) of the application's daemon command.

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L42-L44
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50

Here are the main actions performed by this function:

Expand All @@ -81,7 +81,7 @@ Note that this function only creates an instance of the app, while the actual st

See an example of application constructor from `simapp`:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L192-L429
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L198-L441

### InitChainer

Expand All @@ -91,7 +91,7 @@ In general, the `InitChainer` is mostly composed of the [`InitGenesis`](../build

See an example of an `InitChainer` from `simapp`:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L452-L459
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L464-L471

### BeginBlocker and EndBlocker

Expand All @@ -103,7 +103,7 @@ As a sidenote, it is important to remember that application-specific blockchains

See an example of `BeginBlocker` and `EndBlocker` functions from `simapp`

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L442-L450
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L454-L462

### Register Codec

Expand All @@ -125,7 +125,7 @@ NOTE: this function is marked deprecated and should only be used to create an ap

See an example of a `MakeTestEncodingConfig` from `simapp`:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/cmd/root.go#L179-196
+++ https://github.com/cosmos/cosmos-sdk/blob/590358652cc1cbc13872ea1659187e073ea38e75/simapp/encoding.go#L8-L19

## Modules

Expand Down
6 changes: 3 additions & 3 deletions docs/building-modules/msg-services.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ When possible, the existing module's [`Keeper`](keeper.md) should implement `Msg

`msgServer` methods can retrieve the `sdk.Context` from the `context.Context` parameter method using the `sdk.UnwrapSDKContext`:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L27
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L27-L28

`Msg` processing usually follows these 2 steps:

Expand All @@ -48,7 +48,7 @@ These events are relayed back to the underlying consensus engine and can be used

The invoked `msgServer` method returns a `proto.Message` response and an `error`. These return values are then wrapped into an `*sdk.Result` or an `error` using `sdk.WrapServiceResult(ctx sdk.Context, res proto.Message, err error)`:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/baseapp/msg_service_router.go#L104
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/baseapp/msg_service_router.go#L104-L104

This method takes care of marshaling the `res` parameter to protobuf and attaching any events on the `ctx.EventManager()` to the `sdk.Result`.

Expand All @@ -62,7 +62,7 @@ The `handler` type defined in the Cosmos SDK will be deprecated in favor of [`Ms

Here is the typical structure of a `handler` function:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/types/handler.go#L4
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/types/handler.go#L4-L4

Let us break it down:

Expand Down
2 changes: 1 addition & 1 deletion docs/building-modules/simulator.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Operations on the simulation are simulated using the full [transaction cycle](..

Shown below is how weights are set:

+++ https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/simulation/operations.go#L18
+++ https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/simulation/operations.go#L18-L68

As you can see the weights are predefined in this case but there are options on how to override this behavior with different weights. One is allowing `*rand.Rand` to define a random weight for the operation, or you can inject your own predefined weights.

Expand Down
4 changes: 2 additions & 2 deletions docs/core/baseapp.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,7 @@ The response contains:
- `Info (string):` Additional information. May be non-deterministic.
- `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction.
- `GasUsed (int64)`: Amount of gas consumed by transaction. During `CheckTx`, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction. Next is an example:
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/ante/basic.go#L104
+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/ante/basic.go#L104-L105
- `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more.
- `Codespace (string)`: Namespace for the Code.

Expand All @@ -288,7 +288,7 @@ Before the first transaction of a given block is processed, a [volatile state](#

During the additional fifth step outlined in (2), each read/write to the store increases the value of `GasConsumed`. You can find the default cost of each operation:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L153-L162
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L164-L175

At any point, if `GasConsumed > GasWanted`, the function returns with `Code != 0` and `DeliverTx` fails.

Expand Down
4 changes: 2 additions & 2 deletions docs/core/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,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, thithe signing command is necessary for every application.
- **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.
- **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.

Expand Down Expand Up @@ -106,7 +106,7 @@ A _persistent_ flag (as opposed to a _local_ flag) added to a command transcends

Flags are added to commands directly (generally in the [module's CLI file](../building-modules/module-interfaces.md#flags) where module commands are defined) and no flag except for the `rootCmd` persistent flags has to be added at application level. It is common to add a _persistent_ flag for `--chain-id`, the unique identifier of the blockchain the application pertains to, to the root command. Adding this flag can be done in the `main()` function. Adding this flag makes sense as the chain ID should not be changing across commands in this application CLI. Here is an example from the `simapp` application:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L118
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L118-L119

## Environment variables

Expand Down
6 changes: 3 additions & 3 deletions docs/core/grpc_rest.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,9 @@ The `grpc.Server` is a concrete gRPC server, which spawns and serves any gRPC re
- `grpc.enable = true|false` field defines if the gRPC server should be enabled. Defaults to `true`.
- `grpc.address = {string}` field defines the address (really, the port, since the host should be kept at `0.0.0.0`) the server should bind to. Defaults to `0.0.0.0:9090`.

::tip
:::tip
`~/.simapp` is the directory where the node's configuration and databases are stored. By default, it's set to `~/.{app_name}`.
::
:::

Once the gRPC server is started, you can send requests to it using a gRPC client. Some examples are given in our [Interact with the Node](../run-node/interact-node.md#using-grpc) tutorial.

Expand All @@ -67,7 +67,7 @@ If, for various reasons, you cannot use gRPC (for example, you are building a we

[gRPC-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) is a tool to expose gRPC endpoints as REST endpoints. For each RPC endpoint defined in a Protobuf service, the SDK offers a REST equivalent. For instance, querying a balance could be done via the `/cosmos.bank.v1beta1.Query/AllBalances` 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 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>
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/proto/cosmos/bank/v1beta1/query.proto#L19-L22

For application developers, gRPC-gateway REST routes needs to be wired up to the REST server, this is done by calling the `RegisterGRPCGatewayRoutes` function on the ModuleManager.

Expand Down
4 changes: 2 additions & 2 deletions docs/core/node.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,10 +46,10 @@ The flow of the `start` command is pretty straightforward. First, it retrieves t

With the `db`, the `start` command creates a new instance of the application using an `appCreator` function:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L227
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L227-L228

Note that an `appCreator` is a function that fulfills the `AppCreator` signature:
+++https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50

In practice, the [constructor of the application](../basics/app-anatomy.md#constructor-function) is passed as the `appCreator`.

Expand Down
2 changes: 1 addition & 1 deletion docs/core/ocap.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ sumValue := externalModule.ComputeSumValue(*account)
In the Cosmos SDK, you can see the application of this principle in the
gaia app.

+++ https://github.com/cosmos/gaia/blob/master/app/app.go#L197-L209
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.4/simapp/app.go#L249-L273

## Next {hide}

Expand Down
4 changes: 2 additions & 2 deletions docs/core/store.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](http

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachemulti/store.go#L17-L28

`cachemulti.Store` branches all substores (creates a virtual store for each substore) in its constructor and hold them in `Store.stores`. Moreover cachese all read queries. `Store.GetKVStore()` returns the store from `Store.stores`, and `Store.Write()` recursively calls `CacheWrap.Write()` on all the substores.
`cachemulti.Store` branches all substores (creates a virtual store for each substore) in its constructor and hold them in `Store.stores`. Moreover caches all read queries. `Store.GetKVStore()` returns the store from `Store.stores`, and `Store.Write()` recursively calls `CacheWrap.Write()` on all the substores.

## Base-layer KVStores

Expand Down Expand Up @@ -180,7 +180,7 @@ This is the type used whenever an IAVL Store needs to be branched to create an i

#### `Set`

`Store.Set()` sets the key-value pair to the `Store.cache`. `cValue` has the field dirty bool which indicates whether the cached value is different from the underlying value. When `Store.Set()` cachees a new pair, the `cValue.dirty` is set `true` so when `Store.Write()` is called it can be written to the underlying store.
`Store.Set()` sets the key-value pair to the `Store.cache`. `cValue` has the field dirty bool which indicates whether the cached value is different from the underlying value. When `Store.Set()` caches a new pair, the `cValue.dirty` is set `true` so when `Store.Write()` is called it can be written to the underlying store.

#### `Iterator`

Expand Down