Update docs (#8751)
* docs/basics/app-anatomy.md: update code snippets * Update outdated code snippets * docs/basics/accounts.md: update code snippets * Update outdated code snippets * docs/core/baseapp.md: update code snippets * Update outdated code snippets * docs/core/node.md: update code snippets * Update outdated code snippets * docs/core/store.md: fixed typos * docs/core/grpc_rest.md: fix typos * docs/core/cli.md: fix typos * docs/core/ocap.md: fix code snippet * docs/building-modules/msg-services.md: fix snippet * Update stale code snippets * docs/building-modules/simulator.md: snippets fix * Update outdated code snippet Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
This commit is contained in:
parent
2bce1a7bae
commit
36f68eb9e0
|
@ -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}
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
||||
|
@ -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`.
|
||||
|
||||
|
@ -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:
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
|
|
@ -46,7 +46,7 @@ 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
|
||||
|
|
|
@ -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}
|
||||
|
||||
|
|
|
@ -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
|
||||
|
||||
|
@ -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`
|
||||
|
||||
|
|
Loading…
Reference in New Issue