From c55ebff9fb6e23abc2ebc09ec75f2bade204bb0c Mon Sep 17 00:00:00 2001 From: samricotta <37125168+samricotta@users.noreply.github.com> Date: Tue, 5 Sep 2023 10:56:01 +0300 Subject: [PATCH 1/4] refactor: docs path updates (#17459) Co-authored-by: Julien Robert Co-authored-by: Marko Co-authored-by: marbar3778 (cherry picked from commit f198ea9445fe1c3a6355eabf90242f26382550a4) # Conflicts: # .github/workflows/deploy-docs.yml # UPGRADING.md # docs/docs/build/building-modules/01-module-manager.md # docs/docs/build/building-modules/06-keeper.md # docs/docs/develop/advanced/00-baseapp.md # docs/rfc/README.md --- .github/workflows/deploy-docs.yml | 47 ++ UPGRADING.md | 413 ++++++++++++++++++ docs/.gitignore | 8 +- .../adr-033-protobuf-inter-module-comm.md | 2 +- docs/architecture/adr-063-core-module-api.md | 2 +- docs/docs/{README.md => Introduction.md} | 14 +- .../{ => build}/building-apps/00-app-go.md | 0 .../{ => build}/building-apps/01-app-go-v2.md | 0 .../building-apps/02-app-mempool.md | 2 +- .../building-apps/03-app-upgrade.md | 0 .../building-apps/04-vote-extensions.md | 0 .../{ => build}/building-apps/_category_.json | 0 .../{ => build}/building-modules/01-intro.md | 14 +- .../building-modules/01-module-manager.md | 39 +- .../02-messages-and-queries.md | 14 +- .../building-modules/03-msg-services.md | 8 +- .../building-modules/04-query-services.md | 2 +- .../05-beginblock-endblock.md | 6 +- .../{ => build}/building-modules/06-keeper.md | 14 +- .../building-modules/07-invariants.md | 2 +- .../building-modules/08-genesis.md | 6 +- .../building-modules/09-module-interfaces.md | 6 +- .../building-modules/11-structure.md | 0 .../{ => build}/building-modules/12-errors.md | 0 .../building-modules/13-upgrade.md | 4 +- .../building-modules/14-simulator.md | 4 +- .../building-modules/15-depinject.md | 0 .../building-modules/16-testing.md | 0 .../building-modules/_category_.json | 0 docs/docs/{ => build}/migrations/01-intro.md | 0 .../{ => build}/migrations/_category_.json | 0 docs/docs/{ => build}/modules/_category_.json | 0 .../docs/{ => build}/packages/_category_.json | 0 docs/docs/{ => build}/tooling/_category_.json | 0 .../{core => develop/advanced}/00-baseapp.md | 49 ++- .../advanced}/01-transactions.md | 28 +- .../{core => develop/advanced}/02-context.md | 10 +- .../{core => develop/advanced}/03-node.md | 8 +- .../{core => develop/advanced}/04-store.md | 10 +- .../{core => develop/advanced}/05-encoding.md | 22 +- .../advanced}/06-grpc_rest.md | 6 +- .../docs/{core => develop/advanced}/07-cli.md | 26 +- .../{core => develop/advanced}/08-events.md | 14 +- .../advanced}/09-telemetry.md | 0 .../{core => develop/advanced}/10-ocap.md | 0 .../advanced}/11-runtx_middleware.md | 2 +- .../advanced}/12-simulation.md | 4 +- .../advanced}/13-proto-docs.md | 0 .../{core => develop/advanced}/14-tips.md | 0 .../{core => develop/advanced}/15-upgrade.md | 4 +- .../{core => develop/advanced}/16-config.md | 0 .../advanced}/_category_.json | 0 .../advanced}/baseapp_state-begin_block.png | Bin .../advanced}/baseapp_state-checktx.png | Bin .../advanced}/baseapp_state-commit.png | Bin .../advanced}/baseapp_state-deliver_tx.png | Bin .../advanced}/baseapp_state-initchain.png | Bin .../baseapp_state-prepareproposal.png | Bin .../baseapp_state-processproposal.png | Bin .../advanced}/baseapp_state.png | Bin .../beginner}/00-app-anatomy.md | 60 +-- .../beginner}/01-tx-lifecycle.md | 38 +- .../beginner}/02-query-lifecycle.md | 30 +- .../beginner}/03-accounts.md | 4 +- .../beginner}/04-gas-fees.md | 16 +- .../beginner}/_category_.json | 0 docs/docs/{ => develop}/intro/00-overview.md | 2 +- .../intro/01-why-app-specific.md | 0 .../intro/02-sdk-app-architecture.md | 4 +- .../docs/{ => develop}/intro/03-sdk-design.md | 12 +- docs/docs/{ => develop}/intro/_category_.json | 0 docs/docs/packages/README.md | 39 -- docs/docs/tooling/README.md | 19 - docs/docs/{ => user}/run-node/00-keyring.md | 2 +- docs/docs/{ => user}/run-node/01-run-node.md | 4 +- .../{ => user}/run-node/02-interact-node.md | 6 +- docs/docs/{ => user}/run-node/03-txs.md | 2 +- .../{ => user}/run-node/05-run-testnet.md | 0 .../{ => user}/run-node/06-run-production.md | 0 docs/docs/{ => user}/run-node/_category_.json | 0 docs/docusaurus.config.js | 64 ++- docs/post.sh | 27 +- docs/pre.sh | 32 +- docs/rfc/README.md | 6 +- docs/rfc/_category_.json | 5 - 85 files changed, 802 insertions(+), 360 deletions(-) create mode 100644 .github/workflows/deploy-docs.yml rename docs/docs/{README.md => Introduction.md} (59%) rename docs/docs/{ => build}/building-apps/00-app-go.md (100%) rename docs/docs/{ => build}/building-apps/01-app-go-v2.md (100%) rename docs/docs/{ => build}/building-apps/02-app-mempool.md (99%) rename docs/docs/{ => build}/building-apps/03-app-upgrade.md (100%) rename docs/docs/{ => build}/building-apps/04-vote-extensions.md (100%) rename docs/docs/{ => build}/building-apps/_category_.json (100%) rename docs/docs/{ => build}/building-modules/01-intro.md (86%) rename docs/docs/{ => build}/building-modules/01-module-manager.md (77%) rename docs/docs/{ => build}/building-modules/02-messages-and-queries.md (86%) rename docs/docs/{ => build}/building-modules/03-msg-services.md (91%) rename docs/docs/{ => build}/building-modules/04-query-services.md (98%) rename docs/docs/{ => build}/building-modules/05-beginblock-endblock.md (87%) rename docs/docs/{ => build}/building-modules/06-keeper.md (70%) rename docs/docs/{ => build}/building-modules/07-invariants.md (97%) rename docs/docs/{ => build}/building-modules/08-genesis.md (81%) rename docs/docs/{ => build}/building-modules/09-module-interfaces.md (93%) rename docs/docs/{ => build}/building-modules/11-structure.md (100%) rename docs/docs/{ => build}/building-modules/12-errors.md (100%) rename docs/docs/{ => build}/building-modules/13-upgrade.md (90%) rename docs/docs/{ => build}/building-modules/14-simulator.md (97%) rename docs/docs/{ => build}/building-modules/15-depinject.md (100%) rename docs/docs/{ => build}/building-modules/16-testing.md (100%) rename docs/docs/{ => build}/building-modules/_category_.json (100%) rename docs/docs/{ => build}/migrations/01-intro.md (100%) rename docs/docs/{ => build}/migrations/_category_.json (100%) rename docs/docs/{ => build}/modules/_category_.json (100%) rename docs/docs/{ => build}/packages/_category_.json (100%) rename docs/docs/{ => build}/tooling/_category_.json (100%) rename docs/docs/{core => develop/advanced}/00-baseapp.md (88%) rename docs/docs/{core => develop/advanced}/01-transactions.md (78%) rename docs/docs/{core => develop/advanced}/02-context.md (85%) rename docs/docs/{core => develop/advanced}/03-node.md (94%) rename docs/docs/{core => develop/advanced}/04-store.md (94%) rename docs/docs/{core => develop/advanced}/05-encoding.md (91%) rename docs/docs/{core => develop/advanced}/06-grpc_rest.md (91%) rename docs/docs/{core => develop/advanced}/07-cli.md (80%) rename docs/docs/{core => develop/advanced}/08-events.md (91%) rename docs/docs/{core => develop/advanced}/09-telemetry.md (100%) rename docs/docs/{core => develop/advanced}/10-ocap.md (100%) rename docs/docs/{core => develop/advanced}/11-runtx_middleware.md (89%) rename docs/docs/{core => develop/advanced}/12-simulation.md (97%) rename docs/docs/{core => develop/advanced}/13-proto-docs.md (100%) rename docs/docs/{core => develop/advanced}/14-tips.md (100%) rename docs/docs/{core => develop/advanced}/15-upgrade.md (97%) rename docs/docs/{core => develop/advanced}/16-config.md (100%) rename docs/docs/{core => develop/advanced}/_category_.json (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-begin_block.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-checktx.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-commit.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-deliver_tx.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-initchain.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-prepareproposal.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-processproposal.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state.png (100%) rename docs/docs/{basics => develop/beginner}/00-app-anatomy.md (65%) rename docs/docs/{basics => develop/beginner}/01-tx-lifecycle.md (82%) rename docs/docs/{basics => develop/beginner}/02-query-lifecycle.md (67%) rename docs/docs/{basics => develop/beginner}/03-accounts.md (95%) rename docs/docs/{basics => develop/beginner}/04-gas-fees.md (70%) rename docs/docs/{basics => develop/beginner}/_category_.json (100%) rename docs/docs/{ => develop}/intro/00-overview.md (86%) rename docs/docs/{ => develop}/intro/01-why-app-specific.md (100%) rename docs/docs/{ => develop}/intro/02-sdk-app-architecture.md (91%) rename docs/docs/{ => develop}/intro/03-sdk-design.md (85%) rename docs/docs/{ => develop}/intro/_category_.json (100%) delete mode 100644 docs/docs/packages/README.md delete mode 100644 docs/docs/tooling/README.md rename docs/docs/{ => user}/run-node/00-keyring.md (98%) rename docs/docs/{ => user}/run-node/01-run-node.md (93%) rename docs/docs/{ => user}/run-node/02-interact-node.md (94%) rename docs/docs/{ => user}/run-node/03-txs.md (99%) rename docs/docs/{ => user}/run-node/05-run-testnet.md (100%) rename docs/docs/{ => user}/run-node/06-run-production.md (100%) rename docs/docs/{ => user}/run-node/_category_.json (100%) delete mode 100644 docs/rfc/_category_.json diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000000..da885a75ebe2 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,47 @@ +name: Deploy docs +# This job builds and deploys documenation to github pages. +# It runs on every push to main with a change in the docs folder. +on: + workflow_dispatch: + push: + branches: + - main + - "release/**" + paths: + - "docs/**" + - "x/**/*.md" + - .github/workflows/deploy-docs.yml + +permissions: + contents: read + +jobs: + build-and-deploy: + permissions: + contents: write # for JamesIves/github-pages-deploy-action to push changes in repo + runs-on: ubuntu-latest + steps: + - name: Checkout πŸ›ŽοΈ + uses: actions/checkout@v4 + with: + persist-credentials: false + fetch-depth: 0 + path: "." + + - name: Setup Node.js πŸ”§ + uses: actions/setup-node@v3 + with: + node-version: "16.x" + + # npm install npm should be removed when https://github.com/npm/cli/issues/4942 is fixed + - name: Build πŸ”§ + run: | + npm install -g npm@8.5.5 + make build-docs + + # - name: Deploy πŸš€ + # uses: JamesIves/github-pages-deploy-action@v4.4.3 + # with: + # branch: gh-pages + # folder: ~/output + # single-commit: true diff --git a/UPGRADING.md b/UPGRADING.md index 67ce37d03fe1..30999296bef7 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -369,4 +369,417 @@ All the upgrade imports are now renamed to use `cosmossdk.io/x/upgrade` instead Rosetta has moved to it's own [repo](https://github.com/cosmos/rosetta) and not imported by the Cosmos SDK SimApp by default. Any user who is interested on using the tool can connect it standalone to any node without the need to add it as part of the node binary. +<<<<<<< HEAD The rosetta tool also allows multi chain connections. +======= +The rosetta tool also allows multi chain connections. + +## [v0.47.x](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.47.0) + +### Migration to CometBFT (Part 1) + +The Cosmos SDK has migrated to CometBFT, as its default consensus engine. +CometBFT is an implementation of the Tendermint consensus algorithm, and the successor of Tendermint Core. +Due to the import changes, this is a breaking change. Chains need to remove **entirely** their imports of Tendermint Core in their codebase, from direct and indirects imports in their `go.mod`. + +* Replace `github.com/tendermint/tendermint` by `github.com/cometbft/cometbft` +* Replace `github.com/tendermint/tm-db` by `github.com/cometbft/cometbft-db` +* Verify `github.com/tendermint/tendermint` is not an indirect or direct dependency +* Run `make proto-gen` + +Other than that, the migration should be seamless. +On the SDK side, clean-up of variables, functions to reflect the new name will only happen from v0.50 (part 2). + +Note: It is possible that these steps must first be performed by your dependencies before you can perform them on your own codebase. + +### Simulation + +Remove `RandomizedParams` from `AppModuleSimulation` interface. Previously, it used to generate random parameter changes during simulations, however, it does so through ParamChangeProposal which is now legacy. Since all modules were migrated, we can now safely remove this from `AppModuleSimulation` interface. + +Moreover, to support the `MsgUpdateParams` governance proposals for each modules, `AppModuleSimulation` now defines a `AppModule.ProposalMsgs` method in addition to `AppModule.ProposalContents`. That method defines the messages that can be used to submit a proposal and that should be tested in simulation. + +When a module has no proposal messages or proposal content to be tested by simulation, the `AppModule.ProposalMsgs` and `AppModule.ProposalContents` methods can be deleted. + +### gRPC + +A new gRPC service, `proto/cosmos/base/node/v1beta1/query.proto`, has been introduced +which exposes various operator configuration. App developers should be sure to +register the service with the gRPC-gateway service via +`nodeservice.RegisterGRPCGatewayRoutes` in their application construction, which +is typically found in `RegisterAPIRoutes`. + +### AppModule Interface + +Support for the `AppModule` `Querier`, `Route` and `LegacyQuerier` methods has been entirely removed from the `AppModule` +interface. This removes and fully deprecates all legacy queriers. All modules no longer support the REST API previously +known as the LCD, and the `sdk.Msg#Route` method won't be used anymore. + +Most other existing `AppModule` methods have been moved to extension interfaces in preparation for the migration +to the `cosmossdk.io/core/appmodule` API in the next release. Most `AppModule` implementations should not be broken +by this change. + +### SimApp + +The `simapp` package **should not be imported in your own app**. Instead, you should import the `runtime.AppI` interface, that defines an `App`, and use the [`simtestutil` package](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/testutil/sims) for application testing. + +#### App Wiring + +SimApp's `app_v2.go` is using [App Wiring](https://docs.cosmos.network/main/building-apps/app-go-v2), the dependency injection framework of the Cosmos SDK. +This means that modules are injected directly into SimApp thanks to a [configuration file](https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/simapp/app_config.go). +The previous behavior, without the dependency injection framework, is still present in [`app.go`](https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/simapp/app.go) and is not going anywhere. + +If you are using a `app.go` without dependency injection, add the following lines to your `app.go` in order to provide newer gRPC services: + +```go +autocliv1.RegisterQueryServer(app.GRPCQueryRouter(), runtimeservices.NewAutoCLIQueryService(app.ModuleManager.Modules)) + +reflectionSvc, err := runtimeservices.NewReflectionService() +if err != nil { + panic(err) +} +reflectionv1.RegisterReflectionServiceServer(app.GRPCQueryRouter(), reflectionSvc) +``` + +#### Constructor + +The constructor, `NewSimApp` has been simplified: + +* `NewSimApp` does not take encoding parameters (`encodingConfig`) as input, instead the encoding parameters are injected (when using app wiring), or directly created in the constructor. Instead, we can instantiate `SimApp` for getting the encoding configuration. +* `NewSimApp` now uses `AppOptions` for getting the home path (`homePath`) and the invariant checks period (`invCheckPeriod`). These were unnecessary given as arguments as they were already present in the `AppOptions`. + +#### Encoding + +`simapp.MakeTestEncodingConfig()` was deprecated and has been removed. Instead you can use the `TestEncodingConfig` from the `types/module/testutil` package. +This means you can replace your usage of `simapp.MakeTestEncodingConfig` in tests to `moduletestutil.MakeTestEncodingConfig`, which takes a series of relevant `AppModuleBasic` as input (the module being tested and any potential dependencies). + +#### Export + +`ExportAppStateAndValidators` takes an extra argument, `modulesToExport`, which is a list of module names to export. +That argument should be passed to the module maanager `ExportGenesisFromModules` method. + +#### Replaces + +The `GoLevelDB` version must pinned to `v1.0.1-0.20210819022825-2ae1ddf74ef7` in the application, following versions might cause unexpected behavior. +This can be done adding `replace github.com/syndtr/goleveldb => github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7` to the `go.mod` file. + +* [issue #14949 on cosmos-sdk](https://github.com/cosmos/cosmos-sdk/issues/14949) +* [issue #25413 on go-ethereum](https://github.com/ethereum/go-ethereum/pull/25413) + +### Protobuf + +The SDK has migrated from `gogo/protobuf` (which is currently unmaintained), to our own maintained fork, [`cosmos/gogoproto`](https://github.com/cosmos/gogoproto). + +This means you should replace all imports of `github.com/gogo/protobuf` to `github.com/cosmos/gogoproto`. +This allows you to remove the replace directive `replace github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1` from your `go.mod` file. + +Please use the `ghcr.io/cosmos/proto-builder` image (version >= `0.11.5`) for generating protobuf files. + +See which buf commit for `cosmos/cosmos-sdk` to pin in your `buf.yaml` file [here](https://github.com/cosmos/cosmos-sdk/blob/main/proto/README.md). + +#### Gogoproto Import Paths + +The SDK made a [patch fix](https://github.com/cosmos/gogoproto/pull/32) on its gogoproto repository to require that each proto file's package name matches its OS import path (relatively to a protobuf root import path, usually the root `proto/` folder, set by the `protoc -I` flag). + +For example, assuming you put all your proto files in subfolders inside your root `proto/` folder, then a proto file with package name `myapp.mymodule.v1` should be found in the `proto/myapp/mymodule/v1/` folder. If it is in another folder, the proto generation command will throw an error. + +If you are using a custom folder structure for your proto files, please reorganize them so that their OS path matches their proto package name. + +This is to allow the proto FileDescriptSets to be correctly registered, and this standardized OS import paths allows [Hubl](https://github.com/cosmos/cosmos-sdk/tree/main/tools/hubl) to reflectively talk to any chain. + +#### `{accepts,implements}_interface` proto annotations + +The SDK is normalizing the strings inside the Protobuf `accepts_interface` and `implements_interface` annotations. We require them to be fully-scoped names. They will soon be used by code generators like Pulsar and Telescope to match which messages can or cannot be packed inside `Any`s. + +Here are the following replacements that you need to perform on your proto files: + +```diff +- "Content" ++ "cosmos.gov.v1beta1.Content" +- "Authorization" ++ "cosmos.authz.v1beta1.Authorization" +- "sdk.Msg" ++ "cosmos.base.v1beta1.Msg" +- "AccountI" ++ "cosmos.auth.v1beta1.AccountI" +- "ModuleAccountI" ++ "cosmos.auth.v1beta1.ModuleAccountI" +- "FeeAllowanceI" ++ "cosmos.feegrant.v1beta1.FeeAllowanceI" +``` + +Please also check that in your own app's proto files that there are no single-word names for those two proto annotations. If so, then replace them with fully-qualified names, even though those names don't actually resolve to an actual protobuf entity. + +For more information, see the [encoding guide](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/develop/advanced/05-encoding.md). + +### Transactions + +#### Broadcast Mode + +Broadcast mode `block` was deprecated and has been removed. Please use `sync` mode +instead. When upgrading your tests from `block` to `sync` and checking for a +transaction code, you need to query the transaction first (with its hash) to get +the correct code. + +### Modules + +#### `**all**` + +`EventTypeMessage` events, with `sdk.AttributeKeyModule` and `sdk.AttributeKeySender` are now emitted directly at message excecution (in `baseapp`). +This means that the following boilerplate should be removed from all your custom modules: + +```go +ctx.EventManager().EmitEvent( + sdk.NewEvent( + sdk.EventTypeMessage, + sdk.NewAttribute(sdk.AttributeKeyModule, types.AttributeValueCategory), + sdk.NewAttribute(sdk.AttributeKeySender, `signer/sender`), + ), +) +``` + +The module name is assumed by `baseapp` to be the second element of the message route: `"cosmos.bank.v1beta1.MsgSend" -> "bank"`. +In case a module does not follow the standard message path, (e.g. IBC), it is advised to keep emitting the module name event. +`Baseapp` only emits that event if the module has not already done so. + +#### `x/params` + +The `params` module was deprecated since v0.46. The Cosmos SDK has migrated away from `x/params` for its own modules. +Cosmos SDK modules now store their parameters directly in its repective modules. +The `params` module will be removed in `v0.50`, as mentioned [in v0.46 release](https://github.com/cosmos/cosmos-sdk/blob/v0.46.1/UPGRADING.md#xparams). It is strongly encouraged to migrate away from `x/params` before `v0.50`. + +When performing a chain migration, the params table must be initizalied manually. This was done in the modules keepers in previous versions. +Have a look at `simapp.RegisterUpgradeHandlers()` for an example. + +#### `x/crisis` + +With the migrations of all modules away from `x/params`, the crisis module now has a store. +The store must be created during a chain upgrade to v0.47.x. + +```go +storetypes.StoreUpgrades{ + Added: []string{ + crisistypes.ModuleName, + }, +} +``` + +#### `x/gov` + +##### Minimum Proposal Deposit At Time of Submission + +The `gov` module has been updated to support a minimum proposal deposit at submission time. It is determined by a new +parameter called `MinInitialDepositRatio`. When multiplied by the existing `MinDeposit` parameter, it produces +the necessary proportion of coins needed at the proposal submission time. The motivation for this change is to prevent proposal spamming. + +By default, the new `MinInitialDepositRatio` parameter is set to zero during migration. The value of zero signifies that this +feature is disabled. If chains wish to utilize the minimum proposal deposits at time of submission, the migration logic needs to be +modified to set the new parameter to the desired value. + +##### New `Proposal.Proposer` field + +The `Proposal` proto has been updated with proposer field. For proposal state migraton developers can call `v4.AddProposerAddressToProposal` in their upgrade handler to update all existing proposal and make them compatible and **this migration is optional**. + +```go +import ( + sdk "github.com/cosmos/cosmos-sdk/types" + "github.com/cosmos/cosmos-sdk/types/module" + v4 "github.com/cosmos/cosmos-sdk/x/gov/migrations/v4" + upgradetypes "github.com/cosmos/cosmos-sdk/x/upgrade/types" +) + +func (app SimApp) RegisterUpgradeHandlers() { + app.UpgradeKeeper.SetUpgradeHandler(UpgradeName, + func(ctx sdk.Context, plan upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) { + // this migration is optional + // add proposal ids with proposers which are active (deposit or voting period) + proposals := make(map[uint64]string) + proposals[1] = "cosmos1luyncewxk4lm24k6gqy8y5dxkj0klr4tu0lmnj" ... + v4.AddProposerAddressToProposal(ctx, sdk.NewKVStoreKey(v4.ModuleName), app.appCodec, proposals) + return app.ModuleManager.RunMigrations(ctx, app.Configurator(), fromVM) + }) +} + +``` + +#### `x/consensus` + +Introducing a new `x/consensus` module to handle managing Tendermint consensus +parameters. For migration it is required to call a specific migration to migrate +existing parameters from the deprecated `x/params` to `x/consensus` module. App +developers should ensure to call `baseapp.MigrateParams` in their upgrade handler. + +Example: + +```go +func (app SimApp) RegisterUpgradeHandlers() { + ----> baseAppLegacySS := app.ParamsKeeper.Subspace(baseapp.Paramspace).WithKeyTable(paramstypes.ConsensusParamsKeyTable()) <---- + + app.UpgradeKeeper.SetUpgradeHandler( + UpgradeName, + func(ctx sdk.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) { + // Migrate Tendermint consensus parameters from x/params module to a + // dedicated x/consensus module. + ----> baseapp.MigrateParams(ctx, baseAppLegacySS, &app.ConsensusParamsKeeper) <---- + + // ... + + return app.ModuleManager.RunMigrations(ctx, app.Configurator(), fromVM) + }, + ) + + // ... +} +``` + +The `x/params` module should still be imported in your app.go in order to handle this migration. + +Because the `x/consensus` module is a new module, its store must be added while upgrading to v0.47.x: + +```go +storetypes.StoreUpgrades{ + Added: []string{ + consensustypes.ModuleName, + }, +} +``` + +##### `app.go` changes + +When using an `app.go` without App Wiring, the following changes are required: + +```diff +- bApp.SetParamStore(app.ParamsKeeper.Subspace(baseapp.Paramspace).WithKeyTable(paramstypes.ConsensusParamsKeyTable())) ++ app.ConsensusParamsKeeper = consensusparamkeeper.NewKeeper(appCodec, keys[consensusparamstypes.StoreKey], authtypes.NewModuleAddress(govtypes.ModuleName).String()) ++ bApp.SetParamStore(&app.ConsensusParamsKeeper) +``` + +When using App Wiring, the paramater store is automatically set for you. + +#### `x/nft` + +The SDK does not validate anymore the `classID` and `nftID` of an NFT, for extra flexibility in your NFT implementation. +This means chain developers need to validate the `classID` and `nftID` of an NFT. + +### Ledger + +Ledger support has been generalized to enable use of different apps and keytypes that use `secp256k1`. The Ledger interface remains the same, but it can now be provided through the Keyring `Options`, allowing higher-level chains to connect to different Ledger apps or use custom implementations. In addition, higher-level chains can provide custom key implementations around the Ledger public key, to enable greater flexibility with address generation and signing. + +This is not a breaking change, as all values will default to use the standard Cosmos app implementation unless specified otherwise. + +## [v0.46.x](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.46.0) + +### Go API Changes + +The `replace google.golang.org/grpc` directive can be removed from the `go.mod`, it is no more required to block the version. + +A few packages that were deprecated in the previous version are now removed. + +For instance, the REST API, deprecated in v0.45, is now removed. If you have not migrated yet, please follow the [instructions](https://docs.cosmos.network/v0.45/migrations/rest.html). + +To improve clarity of the API, some renaming and improvements has been done: + +| Package | Previous | Current | +| --------- | ---------------------------------- | ------------------------------------ | +| `simapp` | `encodingConfig.Marshaler` | `encodingConfig.Codec` | +| `simapp` | `FundAccount`, `FundModuleAccount` | Functions moved to `x/bank/testutil` | +| `types` | `AccAddressFromHex` | `AccAddressFromHexUnsafe` | +| `x/auth` | `MempoolFeeDecorator` | Use `DeductFeeDecorator` instead | +| `x/bank` | `AddressFromBalancesStore` | `AddressAndDenomFromBalancesStore` | +| `x/gov` | `keeper.DeleteDeposits` | `keeper.DeleteAndBurnDeposits` | +| `x/gov` | `keeper.RefundDeposits` | `keeper.RefundAndDeleteDeposits` | +| `x/{mod}` | package `legacy` | package `migrations` | + +For the exhaustive list of API renaming, please refer to the [CHANGELOG](https://github.com/cosmos/cosmos-sdk/blob/main/CHANGELOG.md). + +#### new packages + +Additionally, new packages have been introduced in order to further split the codebase. Aliases are available for a new API breaking migration, but it is encouraged to migrate to this new packages: + +* `errors` should replace `types/errors` when registering errors or wrapping SDK errors. +* `math` contains the `Int` or `Uint` types that are used in the SDK. +* `x/nft` an NFT base module. +* `x/group` a group module allowing to create DAOs, multisig and policies. Greatly composes with `x/authz`. + +#### `x/authz` + +* `authz.NewMsgGrant` `expiration` is now a pointer. When `nil` is used, then no expiration will be set (grant won't expire). +* `authz.NewGrant` takes a new argument: block time, to correctly validate expire time. + +### Keyring + +The keyring has been refactored in v0.46. + +* The `Unsafe*` interfaces have been removed from the keyring package. Please use interface casting if you wish to access those unsafe functions. +* The keys' implementation has been refactored to be serialized as proto. +* `keyring.NewInMemory` and `keyring.New` takes now a `codec.Codec`. +* Take `keyring.Record` instead of `Info` as first argument in: + _ `MkConsKeyOutput` + _ `MkValKeyOutput` \* `MkAccKeyOutput` +* Rename: + _ `SavePubKey` to `SaveOfflineKey` and remove the `algo` argument. + _ `NewMultiInfo`, `NewLedgerInfo` to `NewLegacyMultiInfo`, `newLegacyLedgerInfo` respectively. \* `NewOfflineInfo` to `newLegacyOfflineInfo` and move it to `migration_test.go`. + +### PostHandler + +A `postHandler` is like an `antehandler`, but is run _after_ the `runMsgs` execution. It is in the same store branch that `runMsgs`, meaning that both `runMsgs` and `postHandler`. This allows to run a custom logic after the execution of the messages. + +### IAVL + +v0.19.0 IAVL introduces a new "fast" index. This index represents the latest state of the +IAVL laid out in a format that preserves data locality by key. As a result, it allows for faster queries and iterations +since data can now be read in lexicographical order that is frequent for Cosmos-SDK chains. + +The first time the chain is started after the upgrade, the aforementioned index is created. The creation process +might take time and depends on the size of the latest state of the chain. For example, Osmosis takes around 15 minutes to rebuild the index. + +While the index is being created, node operators can observe the following in the logs: +"Upgrading IAVL storage for faster queries + execution on the live state. This may take a while". The store +key is appended to the message. The message is printed for every module that has a non-transient store. +As a result, it gives a good indication of the progress of the upgrade. + +There is also downgrade and re-upgrade protection. If a node operator chooses to downgrade to IAVL pre-fast index, and then upgrade again, the index is rebuilt from scratch. This implementation detail should not be relevant in most cases. It was added as a safeguard against operator +mistakes. + +### Modules + +#### `x/params` + +* The `x/params` module has been depreacted in favour of each module housing and providing way to modify their parameters. Each module that has parameters that are changable during runtime have an authority, the authority can be a module or user account. The Cosmos SDK team recommends migrating modules away from using the param module. An example of how this could look like can be found [here](https://github.com/cosmos/cosmos-sdk/pull/12363). +* The Param module will be maintained until April 18, 2023. At this point the module will reach end of life and be removed from the Cosmos SDK. + +#### `x/gov` + +The `gov` module has been greatly improved. The previous API has been moved to `v1beta1` while the new implementation is called `v1`. + +In order to submit a proposal with `submit-proposal` you now need to pass a `proposal.json` file. +You can still use the old way by using `submit-legacy-proposal`. This is not recommended. +More information can be found in the gov module [client documentation](https://docs.cosmos.network/v0.46/modules/gov/07_client.html). + +#### `x/staking` + +The `staking module` added a new message type to cancel unbonding delegations. Users that have unbonded by accident or wish to cancel a undelegation can now specify the amount and valdiator they would like to cancel the unbond from + +### Protobuf + +The `third_party/proto` folder that existed in [previous version](https://github.com/cosmos/cosmos-sdk/tree/v0.45.3/third_party/proto) now does not contains directly the [proto files](https://github.com/cosmos/cosmos-sdk/tree/release/v0.46.x/third_party/proto). + +Instead, the SDK uses [`buf`](https://buf.build). Clients should have their own [`buf.yaml`](https://docs.buf.build/configuration/v1/buf-yaml) with `buf.build/cosmos/cosmos-sdk` as dependency, in order to avoid having to copy paste these files. + +The protos can as well be downloaded using `buf export buf.build/cosmos/cosmos-sdk:8cb30a2c4de74dc9bd8d260b1e75e176 --output `. + +Cosmos message protobufs should be extended with `cosmos.msg.v1.signer`: + +```protobuf +message MsgSetWithdrawAddress { + option (cosmos.msg.v1.signer) = "delegator_address"; ++ + + option (gogoproto.equal) = false; + option (gogoproto.goproto_getters) = false; + + string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; + string withdraw_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; +} +``` + +When clients interract with a node they are required to set a codec in in the grpc.Dial. More information can be found in this [doc](https://docs.cosmos.network/v0.46/run-node/interact-node.html#programmatically-via-go). +>>>>>>> f198ea944 (refactor: docs path updates (#17459)) diff --git a/docs/.gitignore b/docs/.gitignore index 6613ce192ef7..ded365d1f8c7 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,7 +2,8 @@ /node_modules # Production -/build +build +!docs/build # Generated files .docusaurus @@ -21,8 +22,9 @@ docs/docs/core/17-autocli.md docs/docs/packages/01-depinject.md docs/docs/packages/02-collections.md docs/docs/packages/03-orm.md -docs/run-node/04-rosetta.md -docs/migrations/02-upgrading.md +docs/user/run-node/04-rosetta.md +docs/build/migrations/02-upgrading.md +docs/develop/advanced/17-autocli.md # Misc .DS_Store diff --git a/docs/architecture/adr-033-protobuf-inter-module-comm.md b/docs/architecture/adr-033-protobuf-inter-module-comm.md index ea634dac9748..672c906d755e 100644 --- a/docs/architecture/adr-033-protobuf-inter-module-comm.md +++ b/docs/architecture/adr-033-protobuf-inter-module-comm.md @@ -20,7 +20,7 @@ service definitions defined in [ADR 021](./adr-021-protobuf-query-encoding.md) a ## Context -In the current Cosmos SDK documentation on the [Object-Capability Model](../core/10-ocap.md), it is stated that: +In the current Cosmos SDK documentation on the [Object-Capability Model](../../develop/advanced/10-ocap.md), it is stated that: > 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. diff --git a/docs/architecture/adr-063-core-module-api.md b/docs/architecture/adr-063-core-module-api.md index d5e0d06b7cbd..622e294352b8 100644 --- a/docs/architecture/adr-063-core-module-api.md +++ b/docs/architecture/adr-063-core-module-api.md @@ -90,7 +90,7 @@ slower than more fast moving projects. ### Core Services The following "core services" are defined by the core API. All valid runtime module implementations should provide -implementations of these services to modules via both [dependency injection](./adr-057-app-wiring-1.md) and +implementations of these services to modules via both [dependency injection](./adr-057-app-wiring.md) and manual wiring. The individual services described below are all bundled in a convenient `appmodule.Service` "bundle service" so that for simplicity modules can declare a dependency on a single service. diff --git a/docs/docs/README.md b/docs/docs/Introduction.md similarity index 59% rename from docs/docs/README.md rename to docs/docs/Introduction.md index 451a0bc1942e..7ada53c8fc4e 100644 --- a/docs/docs/README.md +++ b/docs/docs/Introduction.md @@ -9,19 +9,19 @@ Cosmos SDK is the world’s most popular framework for building application-spec Read all about the SDK or dive straight into the code with tutorials. -* [**Introductions to the Cosmos SDK**](./intro/00-overview.md) - Learn about all the parts of the Cosmos SDK. +* [**Introductions to the Cosmos SDK**](develop/intro/00-overview.md) - Learn about all the parts of the Cosmos SDK. * [**SDK Tutorials**](https://tutorials.cosmos.network) - Build a complete blockchain application from scratch. ## Explore the SDK Get familiar with the SDK and explore its main concepts. -* [**Introduction**](./intro/00-overview.md) - High-level overview of the Cosmos SDK. -* [**Basics**](./basics/00-app-anatomy.md) - Anatomy of a blockchain, transaction lifecycle, accounts and more. -* [**Core Concepts**](./core/00-baseapp.md) - Read about the core concepts like baseapp, the store, or the server. -* [**Building Modules**](./building-modules/01-intro.md) - Discover how to build modules for the Cosmos SDK. -* [**Running a Node**](./run-node/00-keyring.md) - Running and interacting with nodes using the CLI and API. -* [**Modules**](./modules/README.md) - Explore existing modules to build your application with. +* [**Introduction**](develop/intro/00-overview.md) - High-level overview of the Cosmos SDK. +* [**Basics**](develop/beginner/00-app-anatomy.md) - Anatomy of a blockchain, transaction lifecycle, accounts and more. +* [**Core Concepts**](develop/advanced/00-baseapp.md) - Read about the core concepts like baseapp, the store, or the server. +* [**Building Modules**](build/building-modules/01-intro.md) - Discover how to build modules for the Cosmos SDK. +* [**Running a Node**](user/run-node/00-keyring.md) - Running and interacting with nodes using the CLI and API. +* [**Modules**](./build/modules/README.md) - Explore existing modules to build your application with. ## Explore the Stack diff --git a/docs/docs/building-apps/00-app-go.md b/docs/docs/build/building-apps/00-app-go.md similarity index 100% rename from docs/docs/building-apps/00-app-go.md rename to docs/docs/build/building-apps/00-app-go.md diff --git a/docs/docs/building-apps/01-app-go-v2.md b/docs/docs/build/building-apps/01-app-go-v2.md similarity index 100% rename from docs/docs/building-apps/01-app-go-v2.md rename to docs/docs/build/building-apps/01-app-go-v2.md diff --git a/docs/docs/building-apps/02-app-mempool.md b/docs/docs/build/building-apps/02-app-mempool.md similarity index 99% rename from docs/docs/building-apps/02-app-mempool.md rename to docs/docs/build/building-apps/02-app-mempool.md index ca754a85dde8..1f591fc6de12 100644 --- a/docs/docs/building-apps/02-app-mempool.md +++ b/docs/docs/build/building-apps/02-app-mempool.md @@ -15,7 +15,7 @@ Notably it introduces the `PrepareProposal` and `ProcessProposal` steps of ABCI+ :::note Pre-requisite Readings -* [BaseApp](../core/00-baseapp.md) +* [BaseApp](../../develop/advanced/00-baseapp.md) ::: diff --git a/docs/docs/building-apps/03-app-upgrade.md b/docs/docs/build/building-apps/03-app-upgrade.md similarity index 100% rename from docs/docs/building-apps/03-app-upgrade.md rename to docs/docs/build/building-apps/03-app-upgrade.md diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/build/building-apps/04-vote-extensions.md similarity index 100% rename from docs/docs/building-apps/04-vote-extensions.md rename to docs/docs/build/building-apps/04-vote-extensions.md diff --git a/docs/docs/building-apps/_category_.json b/docs/docs/build/building-apps/_category_.json similarity index 100% rename from docs/docs/building-apps/_category_.json rename to docs/docs/build/building-apps/_category_.json diff --git a/docs/docs/building-modules/01-intro.md b/docs/docs/build/building-modules/01-intro.md similarity index 86% rename from docs/docs/building-modules/01-intro.md rename to docs/docs/build/building-modules/01-intro.md index 71dbd56bd537..7bfaf8e980ac 100644 --- a/docs/docs/building-modules/01-intro.md +++ b/docs/docs/build/building-modules/01-intro.md @@ -10,18 +10,18 @@ Modules define most of the logic of Cosmos SDK applications. Developers compose :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) -* [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md) +* [Anatomy of a Cosmos SDK application](../../develop/beginner/00-app-anatomy.md) +* [Lifecycle of a Cosmos SDK transaction](../../develop/beginner/01-tx-lifecycle.md) ::: ## Role of Modules in a Cosmos SDK Application -The Cosmos SDK can be thought of as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../core/00-baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../core/04-store.md#multistore) to persist state, a [server](../core/03-node.md) to form a full-node and [interfaces](./09-module-interfaces.md) to handle queries. +The Cosmos SDK can be thought of as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../../develop/advanced/00-baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../../develop/advanced/04-store.md#multistore) to persist state, a [server](../../develop/advanced/03-node.md) to form a full-node and [interfaces](./09-module-interfaces.md) to handle queries. On top of this core, the Cosmos SDK enables developers to build modules that implement the business logic of their application. In other words, SDK modules implement the bulk of the logic of applications, while the core does the wiring and enables modules to be composed together. The end goal is to build a robust ecosystem of open-source Cosmos SDK modules, making it increasingly easier to build complex blockchain applications. -Cosmos SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../core/04-store.md), as well as a subset of [message types](./02-messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../core/00-baseapp.md), to a module Protobuf [`Msg` service](./03-msg-services.md) that defines them. +Cosmos SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../../develop/advanced/04-store.md), as well as a subset of [message types](./02-messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../../develop/advanced/00-baseapp.md), to a module Protobuf [`Msg` service](./03-msg-services.md) that defines them. ```text + @@ -75,7 +75,7 @@ As a result of this architecture, building a Cosmos SDK application usually revo While there are no definitive guidelines for writing modules, here are some important design principles developers should keep in mind when building them: * **Composability**: Cosmos SDK applications are almost always composed of multiple modules. This means developers need to carefully consider the integration of their module not only with the core of the Cosmos SDK, but also with other modules. The former is achieved by following standard design patterns outlined [here](#main-components-of-sdk-modules), while the latter is achieved by properly exposing the store(s) of the module via the [`keeper`](./06-keeper.md). -* **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../core/10-ocap.md) of the Cosmos SDK. +* **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../../develop/advanced/10-ocap.md) of the Cosmos SDK. * **Capabilities**: Most modules need to read and/or write to the store(s) of other modules. However, in an open-source environment, it is possible for some modules to be malicious. That is why module developers need to carefully think not only about how their module interacts with other modules, but also about how to give access to the module's store(s). The Cosmos SDK takes a capabilities-oriented approach to inter-module security. This means that each store defined by a module is accessed by a `key`, which is held by the module's [`keeper`](./06-keeper.md). This `keeper` defines how to access the store(s) and under what conditions. Access to the module's store(s) is done by passing a reference to the module's `keeper`. ## Main Components of Cosmos SDK Modules @@ -83,8 +83,8 @@ While there are no definitive guidelines for writing modules, here are some impo Modules are by convention defined in the `./x/` subfolder (e.g. the `bank` module will be defined in the `./x/bank` folder). They generally share the same core components: * A [`keeper`](./06-keeper.md), used to access the module's store(s) and update the state. -* A [`Msg` service](./02-messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../core/00-baseapp.md#message-routing) and trigger state-transitions. -* A [query service](./04-query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../core/00-baseapp.md#query-routing). +* A [`Msg` service](./02-messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../../develop/advanced/00-baseapp.md#message-routing) and trigger state-transitions. +* A [query service](./04-query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../../develop/advanced/00-baseapp.md#query-routing). * Interfaces, for end users to query the subset of the state defined by the module and create `message`s of the custom types defined in the module. In addition to these components, modules implement the `AppModule` interface in order to be managed by the [`module manager`](./01-module-manager.md). diff --git a/docs/docs/building-modules/01-module-manager.md b/docs/docs/build/building-modules/01-module-manager.md similarity index 77% rename from docs/docs/building-modules/01-module-manager.md rename to docs/docs/build/building-modules/01-module-manager.md index dc9a9b5ebe14..00924c4d2c46 100644 --- a/docs/docs/building-modules/01-module-manager.md +++ b/docs/docs/build/building-modules/01-module-manager.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Module Manager :::note Synopsis -Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../core/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../basics/00-app-anatomy.md#begingblocker-and-endblocker). +Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../../develop/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../../develop/beginner/00-app-anatomy.md#begingblocker-and-endblocker). ::: :::note Pre-requisite Readings @@ -45,7 +45,7 @@ The above interfaces are mostly embedding smaller interfaces (extension interfac * (legacy) [`module.HasInvariants`](#hasinvariants): The extension interface for registering invariants. * (legacy) [`module.HasConsensusVersion`](#hasconsensusversion): The extension interface for declaring a module consensus version. -The `AppModuleBasic` interface exists to define independent methods of the module, i.e. those that do not depend on other modules in the application. This allows for the construction of the basic application structure early in the application definition, generally in the `init()` function of the [main application file](../basics/00-app-anatomy.md#core-application-file). +The `AppModuleBasic` interface exists to define independent methods of the module, i.e. those that do not depend on other modules in the application. This allows for the construction of the basic application structure early in the application definition, generally in the `init()` function of the [main application file](../../develop/beginner/00-app-anatomy.md#core-application-file). The `AppModule` interface exists to define inter-dependent module methods. Many modules need to interact with other modules, typically through [`keeper`s](./06-keeper.md), which means there is a need for an interface where modules list their `keeper`s and other methods that require a reference to another module's object. `AppModule` interface extension, such as `HasBeginBlocker` and `HasEndBlocker`, also enables the module manager to set the order of execution between module's methods like `BeginBlock` and `EndBlock`, which is important in cases where the order of execution between modules matters in the context of the application. @@ -219,7 +219,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/core/appmodule/module.go#L49-L52 ``` -* `Precommit(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../core/00-baseapp.md#commit) of each block using the [`finalizeblockstate`](../core/00-baseapp.md#state-updates) of the block to be committed. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. +* `Precommit(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../../develop/advanced/00-baseapp.md#commit) of each block using the [`finalizeblockstate`](../../develop/advanced/00-baseapp.md#state-updates) of the block to be committed. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. ### `HasPrepareCheckState` @@ -229,7 +229,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/core/appmodule/module. https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/core/appmodule/module.go#L49-L52 ``` -* `PrepareCheckState(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../core/00-baseapp.md#commit) of each block using the [`checkState`](../core/00-baseapp.md#state-updates) of the next block. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. +* `PrepareCheckState(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../../develop/advanced/00-baseapp.md#commit) of each block using the [`checkState`](../../develop/advanced/00-baseapp.md#state-updates) of the next block. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. ### Implementing the Application Module Interfaces @@ -267,15 +267,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go It implements the following methods: -* `NewBasicManager(modules ...AppModuleBasic)`: Constructor function. It takes a list of the application's `AppModuleBasic` and builds a new `BasicManager`. This function is generally called in the `init()` function of [`app.go`](../basics/00-app-anatomy.md#core-application-file) to quickly initialize the independent elements of the application's modules (click [here](https://github.com/cosmos/gaia/blob/main/app/app.go#L59-L74) to see an example). +* `NewBasicManager(modules ...AppModuleBasic)`: Constructor function. It takes a list of the application's `AppModuleBasic` and builds a new `BasicManager`. This function is generally called in the `init()` function of [`app.go`](../../develop/beginner/00-app-anatomy.md#core-application-file) to quickly initialize the independent elements of the application's modules (click [here](https://github.com/cosmos/gaia/blob/main/app/app.go#L59-L74) to see an example). * `NewBasicManagerFromManager(manager *Manager, customModuleBasics map[string]AppModuleBasic)`: Contructor function. It creates a new `BasicManager` from a `Manager`. The `BasicManager` will contain all `AppModuleBasic` from the `AppModule` manager using `CoreAppModuleBasicAdaptor` whenever possible. Module's `AppModuleBasic` can be overridden by passing a custom AppModuleBasic map -* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../core/05-encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../basics/00-app-anatomy.md#constructor). +* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../../develop/advanced/05-encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../../develop/beginner/00-app-anatomy.md#constructor). * `RegisterInterfaces(registry codectypes.InterfaceRegistry)`: Registers interface types and implementations of each of the application's `AppModuleBasic`. * `DefaultGenesis(cdc codec.JSONCodec)`: Provides default genesis information for modules in the application by calling the [`DefaultGenesis(cdc codec.JSONCodec)`](./08-genesis.md#defaultgenesis) function of each module. It only calls the modules that implements the `HasGenesisBasics` interfaces. * `ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage)`: Validates the genesis information modules by calling the [`ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`](./08-genesis.md#validategenesis) function of modules implementing the `HasGenesisBasics` interface. * `RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)`: Registers gRPC routes for modules. -* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands (defined as `GetTxCmd() *cobra.Command`) to the application's [`rootTxCommand`](../core/07-cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/07-cli.md). -* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands (defined as `GetQueryCmd() *cobra.Command`) to the application's [`rootQueryCommand`](../core/07-cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/07-cli.md). +* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands (defined as `GetTxCmd() *cobra.Command`) to the application's [`rootTxCommand`](../../develop/advanced/07-cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../develop/advanced/07-cli.md). +* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands (defined as `GetQueryCmd() *cobra.Command`) to the application's [`rootQueryCommand`](../../develop/advanced/07-cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../develop/advanced/07-cli.md). ### `Manager` @@ -287,25 +287,34 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go The module manager is used throughout the application whenever an action on a collection of modules is required. It implements the following methods: -* `NewManager(modules ...AppModule)`: Constructor function. It takes a list of the application's `AppModule`s and builds a new `Manager`. It is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). +* `NewManager(modules ...AppModule)`: Constructor function. It takes a list of the application's `AppModule`s and builds a new `Manager`. It is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). To initialize modules successfully, module dependencies should be considered. For example, the `genutil` module must occur after `staking` module so that the pools are properly initialized with tokens from genesis accounts, the `genutils` module must also occur after `auth` so that it can access the params from auth, IBC's `capability` module should be initialized before all other modules so that it can initialize any capabilities. -* `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderPrecommiters(moduleNames ...string)`: Sets the order in which the `Precommit()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderPrepareCheckStaters(moduleNames ...string)`: Sets the order in which the `PrepareCheckState()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). +* `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderPrecommiters(moduleNames ...string)`: Sets the order in which the `Precommit()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderPrepareCheckStaters(moduleNames ...string)`: Sets the order in which the `PrepareCheckState()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). * `SetOrderMigrations(moduleNames ...string)`: Sets the order of migrations to be run. If not set then migrations will be run with an order defined in `DefaultMigrationsOrder`. * `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./07-invariants.md) of module implementing the `HasInvariants` interface. * `RegisterServices(cfg Configurator)`: Registers the services of modules implementing the `HasServices` interface. * `InitGenesis(ctx context.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.ResponseInitChain` to the underlying consensus engine, which can contain validator updates. * `ExportGenesis(ctx context.Context, cdc codec.JSONCodec)`: Calls the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required. * `ExportGenesisForModules(ctx context.Context, cdc codec.JSONCodec, modulesToExport []string)`: Behaves the same as `ExportGenesis`, except takes a list of modules to export. +<<<<<<< HEAD:docs/docs/building-modules/01-module-manager.md * `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of all modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from modules. * `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `Precommit(ctx context.Context)`: During [`Commit`](../core/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../core/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../core/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../core/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../core/00-baseapp.md#state-updates). * `PrepareCheckState(ctx context.Context)`: During [`Commit`](../core/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../core/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../core/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../core/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../core/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../core/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block. +======= +* `RunMigrationBeginBlock(ctx sdk.Context) (bool, error)`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of the upgrade module implementing the `HasBeginBlocker` interface. The function returns a boolean value indicating whether the migration was executed or not and an error if fails. +* `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of each non-upgrade modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from non-upgrade modules. +* `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). +* `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). +* `Precommit(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../../develop/advanced/00-baseapp.md#state-updates). +* `PrepareCheckState(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../../develop/advanced/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../../develop/advanced/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block. +>>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/build/building-modules/01-module-manager.md Here's an example of a concrete integration within an `simapp`: diff --git a/docs/docs/building-modules/02-messages-and-queries.md b/docs/docs/build/building-modules/02-messages-and-queries.md similarity index 86% rename from docs/docs/building-modules/02-messages-and-queries.md rename to docs/docs/build/building-modules/02-messages-and-queries.md index a175216c3488..69465ab5e576 100644 --- a/docs/docs/building-modules/02-messages-and-queries.md +++ b/docs/docs/build/building-modules/02-messages-and-queries.md @@ -16,13 +16,13 @@ sidebar_position: 1 ## Messages -`Msg`s are objects whose end-goal is to trigger state-transitions. They are wrapped in [transactions](../core/01-transactions.md), which may contain one or more of them. +`Msg`s are objects whose end-goal is to trigger state-transitions. They are wrapped in [transactions](../../develop/advanced/01-transactions.md), which may contain one or more of them. -When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../core/00-baseapp.md). Then, each message contained in the transaction is extracted and routed to the appropriate module via `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's [`Msg` service](./03-msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../basics/01-tx-lifecycle.md). +When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../../develop/advanced/00-baseapp.md). Then, each message contained in the transaction is extracted and routed to the appropriate module via `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's [`Msg` service](./03-msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../../develop/beginner/01-tx-lifecycle.md). ### `Msg` Services -Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../core/05-encoding.md#faq)). It must have an RPC service method defined for each message in the module. +Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../../develop/advanced/05-encoding.md#faq)). It must have an RPC service method defined for each message in the module. Each `Msg` service method must have exactly one argument, which must implement the `sdk.Msg` interface, and a Protobuf response. The naming convention is to call the RPC argument `Msg` and the RPC response `MsgResponse`. For example: @@ -89,7 +89,7 @@ In order for clients (CLI and grpc-gateway) to have these URLs registered, the C ## Queries -A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `QueryRouter` so that it can be processed by the module's query service (./04-query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../basics/02-query-lifecycle.md). +A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `QueryRouter` so that it can be processed by the module's query service (./04-query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../../develop/beginner/02-query-lifecycle.md). ### gRPC Queries @@ -115,14 +115,14 @@ queryCategory/queryRoute/queryType/arg1/arg2/... where: -* `queryCategory` is the category of the `query`, typically `custom` for module queries. It is used to differentiate between different kinds of queries within `BaseApp`'s [`Query` method](../core/00-baseapp.md#query). -* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../core/00-baseapp.md#query-routing) to map the `query` to its module. Usually, `queryRoute` should be the name of the module. +* `queryCategory` is the category of the `query`, typically `custom` for module queries. It is used to differentiate between different kinds of queries within `BaseApp`'s [`Query` method](../../develop/advanced/00-baseapp.md#query). +* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../../develop/advanced/00-baseapp.md#query-routing) to map the `query` to its module. Usually, `queryRoute` should be the name of the module. * `queryType` is used by the module's [`querier`](./04-query-services.md#legacy-queriers) to map the `query` to the appropriate `querier function` within the module. * `args` are the actual arguments needed to process the `query`. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in the `Data` field of the request `req` instead of the `path`. The `path` for each `query` must be defined by the module developer in the module's [command-line interface file](./09-module-interfaces.md#query-commands).Overall, there are 3 mains components module developers need to implement in order to make the subset of the state defined by their module queryable: -* A [`querier`](./04-query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../core/00-baseapp.md#query-routing). +* A [`querier`](./04-query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../../develop/advanced/00-baseapp.md#query-routing). * [Query commands](./09-module-interfaces.md#query-commands) in the module's CLI file, where the `path` for each `query` is specified. * `query` return types. Typically defined in a file `types/querier.go`, they specify the result type of each of the module's `queries`. These custom types must implement the `String()` method of [`fmt.Stringer`](https://pkg.go.dev/fmt#Stringer). diff --git a/docs/docs/building-modules/03-msg-services.md b/docs/docs/build/building-modules/03-msg-services.md similarity index 91% rename from docs/docs/building-modules/03-msg-services.md rename to docs/docs/build/building-modules/03-msg-services.md index 918a5d45a4a0..ead334108a74 100644 --- a/docs/docs/building-modules/03-msg-services.md +++ b/docs/docs/build/building-modules/03-msg-services.md @@ -5,7 +5,7 @@ sidebar_position: 1 # `Msg` Services :::note Synopsis -A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messages). Protobuf `Msg` services are specific to the module in which they are defined, and only process messages defined within the said module. They are called from `BaseApp` during [`DeliverTx`](../core/00-baseapp.md#delivertx). +A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messages). Protobuf `Msg` services are specific to the module in which they are defined, and only process messages defined within the said module. They are called from `BaseApp` during [`DeliverTx`](../../develop/advanced/00-baseapp.md#delivertx). ::: :::note Pre-requisite Readings @@ -71,7 +71,7 @@ After the validation is successful, the `msgServer` method uses the [`keeper`](. ### Events -Before returning, `msgServer` methods generally emit one or more [events](../core/08-events.md) by using the `EventManager` held in the `ctx`. Use the new `EmitTypedEvent` function that uses protobuf-based event types: +Before returning, `msgServer` methods generally emit one or more [events](../../develop/advanced/08-events.md) by using the `EventManager` held in the `ctx`. Use the new `EmitTypedEvent` function that uses protobuf-based event types: ```go ctx.EventManager().EmitTypedEvent( @@ -90,7 +90,7 @@ ctx.EventManager().EmitEvent( ) ``` -These events are relayed back to the underlying consensus engine and can be used by service providers to implement services around the application. Click [here](../core/08-events.md) to learn more about events. +These events are relayed back to the underlying consensus engine and can be used by service providers to implement services around the application. Click [here](../../develop/advanced/08-events.md) to learn more about events. 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 context.Context, res proto.Message, err error)`: @@ -110,7 +110,7 @@ This diagram shows a typical structure of a Protobuf `Msg` service, and how the ## Telemetry -New [telemetry metrics](../core/09-telemetry.md) can be created from `msgServer` methods when handling messages. +New [telemetry metrics](../../develop/advanced/09-telemetry.md) can be created from `msgServer` methods when handling messages. This is an example from the `x/auth/vesting` module: diff --git a/docs/docs/building-modules/04-query-services.md b/docs/docs/build/building-modules/04-query-services.md similarity index 98% rename from docs/docs/building-modules/04-query-services.md rename to docs/docs/build/building-modules/04-query-services.md index 657557f89859..29542d86cc3c 100644 --- a/docs/docs/building-modules/04-query-services.md +++ b/docs/docs/build/building-modules/04-query-services.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Query Services :::note Synopsis -A Protobuf Query service processes [`queries`](./02-messages-and-queries.md#queries). Query services are specific to the module in which they are defined, and only process `queries` defined within said module. They are called from `BaseApp`'s [`Query` method](../core/00-baseapp.md#query). +A Protobuf Query service processes [`queries`](./02-messages-and-queries.md#queries). Query services are specific to the module in which they are defined, and only process `queries` defined within said module. They are called from `BaseApp`'s [`Query` method](../../develop/advanced/00-baseapp.md#query). ::: :::note Pre-requisite Readings diff --git a/docs/docs/building-modules/05-beginblock-endblock.md b/docs/docs/build/building-modules/05-beginblock-endblock.md similarity index 87% rename from docs/docs/building-modules/05-beginblock-endblock.md rename to docs/docs/build/building-modules/05-beginblock-endblock.md index ff9a35a847c1..9472b0b759eb 100644 --- a/docs/docs/building-modules/05-beginblock-endblock.md +++ b/docs/docs/build/building-modules/05-beginblock-endblock.md @@ -5,7 +5,7 @@ sidebar_position: 1 # BeginBlocker and EndBlocker :::note Synopsis -`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the [`BeginBlock`](../core/00-baseapp.md#beginblock) and [`EndBlock`](../core/00-baseapp.md#endblock) ABCI messages are received from the underlying consensus engine. +`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the [`BeginBlock`](../../develop/advanced/00-baseapp.md#beginblock) and [`EndBlock`](../../develop/advanced/00-baseapp.md#endblock) ABCI messages are received from the underlying consensus engine. ::: :::note Pre-requisite Readings @@ -24,9 +24,9 @@ When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`Ha The actual implementation of `BeginBlocker` and `EndBlocker` in `abci.go` are very similar to that of a [`Msg` service](./03-msg-services.md): -* They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../core/02-context.md) to retrieve information about the latest state. +* They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../../develop/advanced/02-context.md) to retrieve information about the latest state. * If needed, they use the `keeper` and `ctx` to trigger state-transitions. -* If needed, they can emit [`events`](../core/08-events.md) via the `ctx`'s `EventManager`. +* If needed, they can emit [`events`](../../develop/advanced/08-events.md) via the `ctx`'s `EventManager`. A specific type of `EndBlocker` is available to return validator updates to the underlying consensus engine in the form of an [`[]abci.ValidatorUpdates`](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#endblock). This is the preferred way to implement custom validator changes. diff --git a/docs/docs/building-modules/06-keeper.md b/docs/docs/build/building-modules/06-keeper.md similarity index 70% rename from docs/docs/building-modules/06-keeper.md rename to docs/docs/build/building-modules/06-keeper.md index b9a11f87b4ec..400c79bf2185 100644 --- a/docs/docs/building-modules/06-keeper.md +++ b/docs/docs/build/building-modules/06-keeper.md @@ -18,9 +18,9 @@ sidebar_position: 1 The Cosmos SDK is a framework that makes it easy for developers to build complex decentralized applications from scratch, mainly by composing modules together. As the ecosystem of open-source modules for the Cosmos SDK expands, it will become increasingly likely that some of these modules contain vulnerabilities, as a result of the negligence or malice of their developer. -The Cosmos SDK adopts an [object-capabilities-based approach](../core/10-ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../core/04-store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s). +The Cosmos SDK adopts an [object-capabilities-based approach](../../develop/advanced/10-ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../../develop/advanced/04-store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s). -The core idea behind the object-capabilities approach is to only reveal what is necessary to get the work done. In practice, this means that instead of handling permissions of modules through access-control lists, module `keeper`s are passed a reference to the specific instance of the other modules' `keeper`s that they need to access (this is done in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function)). As a consequence, a module can only interact with the subset of state defined in another module via the methods exposed by the instance of the other module's `keeper`. This is a great way for developers to control the interactions that their own module can have with modules developed by external developers. +The core idea behind the object-capabilities approach is to only reveal what is necessary to get the work done. In practice, this means that instead of handling permissions of modules through access-control lists, module `keeper`s are passed a reference to the specific instance of the other modules' `keeper`s that they need to access (this is done in the [application's constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function)). As a consequence, a module can only interact with the subset of state defined in another module via the methods exposed by the instance of the other module's `keeper`. This is a great way for developers to control the interactions that their own module can have with modules developed by external developers. ## Type Definition @@ -47,10 +47,16 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/keepe Let us go through the different parameters: * An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in an `expected_keepers.go` file in the root of the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself. +<<<<<<< HEAD:docs/docs/building-modules/06-keeper.md * `storeKey`s grant access to the store(s) of the [multistore](../core/04-store.md) managed by the module. They should always remain unexposed to external modules. * `cdc` is the [codec](../core/05-encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces. The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated. +======= +* `storeKey`s grant access to the store(s) of the [multistore](../../develop/advanced/04-store.md) managed by the module. They should always remain unexposed to external modules. +* `cdc` is the [codec](../../develop/advanced/05-encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces. +* The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated. +>>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/build/building-modules/06-keeper.md -Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../basics/00-app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them. +Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../../develop/beginner/00-app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them. ## Implementing Methods @@ -82,7 +88,7 @@ and the method will go through the following steps: For more, see an example of `keeper`'s [methods implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/keeper.go). -The [module `KVStore`](../core/04-store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys. +The [module `KVStore`](../../develop/advanced/04-store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys. This is an example from the `auth` module to iterate accounts: diff --git a/docs/docs/building-modules/07-invariants.md b/docs/docs/build/building-modules/07-invariants.md similarity index 97% rename from docs/docs/building-modules/07-invariants.md rename to docs/docs/build/building-modules/07-invariants.md index f1bcd801f827..cd85864bfa3b 100644 --- a/docs/docs/building-modules/07-invariants.md +++ b/docs/docs/build/building-modules/07-invariants.md @@ -79,7 +79,7 @@ Typically, this interface is implemented in the `keeper` of a specific module. T https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/crisis/keeper/keeper.go#L48-L50 ``` -The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function). +The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). `Invariant`s can be checked manually via [`message`s](./02-messages-and-queries.md), but most often they are checked automatically at the end of each block. Here is an example from the `crisis` module: diff --git a/docs/docs/building-modules/08-genesis.md b/docs/docs/build/building-modules/08-genesis.md similarity index 81% rename from docs/docs/building-modules/08-genesis.md rename to docs/docs/build/building-modules/08-genesis.md index 2e400353742d..546eb5fb9263 100644 --- a/docs/docs/building-modules/08-genesis.md +++ b/docs/docs/build/building-modules/08-genesis.md @@ -17,7 +17,7 @@ Modules generally handle a subset of the state and, as such, they need to define ## Type Definition -The subset of the genesis state defined from a given module is generally defined in a `genesis.proto` file ([more info](../core/05-encoding.md#gogoproto) on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called `GenesisState` and contains all the module-related values that need to be initialized during the genesis process. +The subset of the genesis state defined from a given module is generally defined in a `genesis.proto` file ([more info](../../develop/advanced/05-encoding.md#gogoproto) on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called `GenesisState` and contains all the module-related values that need to be initialized during the genesis process. See an example of `GenesisState` protobuf message definition from the `auth` module: @@ -49,9 +49,9 @@ Other than the methods related directly to `GenesisState`, module developers are ### `InitGenesis` -The `InitGenesis` method is executed during [`InitChain`](../core/00-baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./06-keeper.md) setter function on each parameter within the `GenesisState`. +The `InitGenesis` method is executed during [`InitChain`](../../develop/advanced/00-baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./06-keeper.md) setter function on each parameter within the `GenesisState`. -The [module manager](./01-module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function). +The [module manager](./01-module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). See an example of `InitGenesis` from the `auth` module: diff --git a/docs/docs/building-modules/09-module-interfaces.md b/docs/docs/build/building-modules/09-module-interfaces.md similarity index 93% rename from docs/docs/building-modules/09-module-interfaces.md rename to docs/docs/build/building-modules/09-module-interfaces.md index 81831f90da80..27707bd344a7 100644 --- a/docs/docs/building-modules/09-module-interfaces.md +++ b/docs/docs/build/building-modules/09-module-interfaces.md @@ -16,11 +16,11 @@ This document details how to build CLI and REST interfaces for a module. Example ## CLI -One of the main interfaces for an application is the [command-line interface](../core/07-cli.md). This entrypoint adds commands from the application's modules enabling end-users to create [**messages**](./02-messages-and-queries.md#messages) wrapped in transactions and [**queries**](./02-messages-and-queries.md#queries). The CLI files are typically found in the module's `./client/cli` folder. +One of the main interfaces for an application is the [command-line interface](../../develop/advanced/07-cli.md). This entrypoint adds commands from the application's modules enabling end-users to create [**messages**](./02-messages-and-queries.md#messages) wrapped in transactions and [**queries**](./02-messages-and-queries.md#queries). The CLI files are typically found in the module's `./client/cli` folder. ### Transaction Commands -In order to create messages that trigger state changes, end-users must create [transactions](../core/01-transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages. +In order to create messages that trigger state changes, end-users must create [transactions](../../develop/advanced/01-transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages. Transaction commands typically have their own `tx.go` file that lives within the module's `./client/cli` folder. The commands are specified in getter functions and the name of the function should include the name of the command. @@ -101,7 +101,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/module.go#L84-L ### Flags -[Flags](../core/07-cli.md#flags) allow users to customize commands. `--fees` and `--gas-prices` are examples of flags that allow users to set the [fees](../basics/04-gas-fees.md) and gas prices for their transactions. +[Flags](../../develop/advanced/07-cli.md#flags) allow users to customize commands. `--fees` and `--gas-prices` are examples of flags that allow users to set the [fees](../../develop/beginner/04-gas-fees.md) and gas prices for their transactions. Flags that are specific to a module are typically created in a `flags.go` file in the module's `./client/cli` folder. When creating a flag, developers set the value type, the name of the flag, the default value, and a description about the flag. Developers also have the option to mark flags as _required_ so that an error is thrown if the user does not include a value for the flag. diff --git a/docs/docs/building-modules/11-structure.md b/docs/docs/build/building-modules/11-structure.md similarity index 100% rename from docs/docs/building-modules/11-structure.md rename to docs/docs/build/building-modules/11-structure.md diff --git a/docs/docs/building-modules/12-errors.md b/docs/docs/build/building-modules/12-errors.md similarity index 100% rename from docs/docs/building-modules/12-errors.md rename to docs/docs/build/building-modules/12-errors.md diff --git a/docs/docs/building-modules/13-upgrade.md b/docs/docs/build/building-modules/13-upgrade.md similarity index 90% rename from docs/docs/building-modules/13-upgrade.md rename to docs/docs/build/building-modules/13-upgrade.md index 3a6515707643..703b4cd28082 100644 --- a/docs/docs/building-modules/13-upgrade.md +++ b/docs/docs/build/building-modules/13-upgrade.md @@ -5,12 +5,12 @@ sidebar_position: 1 # Upgrading Modules :::note Synopsis -[In-Place Store Migrations](../core/15-upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. +[In-Place Store Migrations](../../develop/advanced/15-upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. ::: :::note Pre-requisite Readings -* [In-Place Store Migration](../core/15-upgrade.md) +* [In-Place Store Migration](../../develop/advanced/15-upgrade.md) ::: diff --git a/docs/docs/building-modules/14-simulator.md b/docs/docs/build/building-modules/14-simulator.md similarity index 97% rename from docs/docs/building-modules/14-simulator.md rename to docs/docs/build/building-modules/14-simulator.md index 3065e3c60ec4..5360709f6d58 100644 --- a/docs/docs/building-modules/14-simulator.md +++ b/docs/docs/build/building-modules/14-simulator.md @@ -6,7 +6,7 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Cosmos Blockchain Simulator](../core/12-simulation.md) +* [Cosmos Blockchain Simulator](../../develop/advanced/12-simulation.md) ::: ## Synopsis @@ -62,7 +62,7 @@ Operations are one of the crucial parts of the Cosmos SDK simulation. They are t (`Msg`) that are simulated with random field values. The sender of the operation is also assigned randomly. -Operations on the simulation are simulated using the full [transaction cycle](../core/01-transactions.md) of a +Operations on the simulation are simulated using the full [transaction cycle](../../develop/advanced/01-transactions.md) of a `ABCI` application that exposes the `BaseApp`. Shown below is how weights are set: diff --git a/docs/docs/building-modules/15-depinject.md b/docs/docs/build/building-modules/15-depinject.md similarity index 100% rename from docs/docs/building-modules/15-depinject.md rename to docs/docs/build/building-modules/15-depinject.md diff --git a/docs/docs/building-modules/16-testing.md b/docs/docs/build/building-modules/16-testing.md similarity index 100% rename from docs/docs/building-modules/16-testing.md rename to docs/docs/build/building-modules/16-testing.md diff --git a/docs/docs/building-modules/_category_.json b/docs/docs/build/building-modules/_category_.json similarity index 100% rename from docs/docs/building-modules/_category_.json rename to docs/docs/build/building-modules/_category_.json diff --git a/docs/docs/migrations/01-intro.md b/docs/docs/build/migrations/01-intro.md similarity index 100% rename from docs/docs/migrations/01-intro.md rename to docs/docs/build/migrations/01-intro.md diff --git a/docs/docs/migrations/_category_.json b/docs/docs/build/migrations/_category_.json similarity index 100% rename from docs/docs/migrations/_category_.json rename to docs/docs/build/migrations/_category_.json diff --git a/docs/docs/modules/_category_.json b/docs/docs/build/modules/_category_.json similarity index 100% rename from docs/docs/modules/_category_.json rename to docs/docs/build/modules/_category_.json diff --git a/docs/docs/packages/_category_.json b/docs/docs/build/packages/_category_.json similarity index 100% rename from docs/docs/packages/_category_.json rename to docs/docs/build/packages/_category_.json diff --git a/docs/docs/tooling/_category_.json b/docs/docs/build/tooling/_category_.json similarity index 100% rename from docs/docs/tooling/_category_.json rename to docs/docs/build/tooling/_category_.json diff --git a/docs/docs/core/00-baseapp.md b/docs/docs/develop/advanced/00-baseapp.md similarity index 88% rename from docs/docs/core/00-baseapp.md rename to docs/docs/develop/advanced/00-baseapp.md index 3a0aa2651d5b..dd35bccbfc7d 100644 --- a/docs/docs/core/00-baseapp.md +++ b/docs/docs/develop/advanced/00-baseapp.md @@ -10,8 +10,8 @@ This document describes `BaseApp`, the abstraction that implements the core func :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) -* [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) +* [Lifecycle of a Cosmos SDK transaction](../beginner/01-tx-lifecycle.md) ::: @@ -78,8 +78,8 @@ First, the important parameters that are initialized during the bootstrapping of * [`AnteHandler`](#antehandler): This handler is used to handle signature verification, fee payment, and other pre-message execution checks when a transaction is received. It's executed during [`CheckTx/RecheckTx`](#checktx) and [`FinalizeBlock`](#finalizeblock). -* [`InitChainer`](../basics/00-app-anatomy.md#initchainer), - [`BeginBlocker` and `EndBlocker`](../basics/00-app-anatomy.md#beginblocker-and-endblocker): These are +* [`InitChainer`](../beginner/00-app-anatomy.md#initchainer), + [`BeginBlocker` and `EndBlocker`](../beginner/00-app-anatomy.md#beginblocker-and-endblocker): These are the functions executed when the application receives the `InitChain` and `FinalizeBlock` ABCI messages from the underlying CometBFT engine. @@ -105,7 +105,7 @@ Finally, a few more important parameters: `minGasPrices` (e.g. if `minGasPrices == 1uatom,1photon`, the `gas-price` of the transaction must be greater than `1uatom` OR `1photon`). * `appVersion`: Version of the application. It is set in the - [application's constructor function](../basics/00-app-anatomy.md#constructor-function). + [application's constructor function](../beginner/00-app-anatomy.md#constructor-function). ## Constructor @@ -217,17 +217,17 @@ When messages and queries are received by the application, they must be routed t ### `Msg` Service Router -[`sdk.Msg`s](../building-modules/02-messages-and-queries.md#messages) need to be routed after they are extracted from transactions, which are sent from the underlying CometBFT engine via the [`CheckTx`](#checktx) and [`FinalizeBlock`](#finalizeblock) ABCI messages. To do so, `BaseApp` holds a `msgServiceRouter` which maps fully-qualified service methods (`string`, defined in each module's Protobuf `Msg` service) to the appropriate module's `MsgServer` implementation. +[`sdk.Msg`s](../../build/building-modules/02-messages-and-queries.md#messages) need to be routed after they are extracted from transactions, which are sent from the underlying CometBFT engine via the [`CheckTx`](#checktx) and [`FinalizeBlock`](#finalizeblock) ABCI messages. To do so, `BaseApp` holds a `msgServiceRouter` which maps fully-qualified service methods (`string`, defined in each module's Protobuf `Msg` service) to the appropriate module's `MsgServer` implementation. The [default `msgServiceRouter` included in `BaseApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/msg_service_router.go) is stateless. However, some applications may want to make use of more stateful routing mechanisms such as allowing governance to disable certain routes or point them to new modules for upgrade purposes. For this reason, the `sdk.Context` is also passed into each [route handler inside `msgServiceRouter`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/msg_service_router.go#L31-L32). For a stateless router that doesn't want to make use of this, you can just ignore the `ctx`. -The application's `msgServiceRouter` is initialized with all the routes using the application's [module manager](../building-modules/01-module-manager.md#manager) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/00-app-anatomy.md#constructor-function). +The application's `msgServiceRouter` is initialized with all the routes using the application's [module manager](../../build/building-modules/01-module-manager.md#manager) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../beginner/00-app-anatomy.md#constructor-function). ### gRPC Query Router -Similar to `sdk.Msg`s, [`queries`](../building-modules/02-messages-and-queries.md#queries) need to be routed to the appropriate module's [`Query` service](../building-modules/04-query-services.md). To do so, `BaseApp` holds a `grpcQueryRouter`, which maps modules' fully-qualified service methods (`string`, defined in their Protobuf `Query` gRPC) to their `QueryServer` implementation. The `grpcQueryRouter` is called during the initial stages of query processing, which can be either by directly sending a gRPC query to the gRPC endpoint, or via the [`Query` ABCI message](#query) on the CometBFT RPC endpoint. +Similar to `sdk.Msg`s, [`queries`](../../build/building-modules/02-messages-and-queries.md#queries) need to be routed to the appropriate module's [`Query` service](../../build/building-modules/04-query-services.md). To do so, `BaseApp` holds a `grpcQueryRouter`, which maps modules' fully-qualified service methods (`string`, defined in their Protobuf `Query` gRPC) to their `QueryServer` implementation. The `grpcQueryRouter` is called during the initial stages of query processing, which can be either by directly sending a gRPC query to the gRPC endpoint, or via the [`Query` ABCI message](#query) on the CometBFT RPC endpoint. -Just like the `msgServiceRouter`, the `grpcQueryRouter` is initialized with all the query routes using the application's [module manager](../building-modules/01-module-manager.md) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/00-app-anatomy.md#app-constructor). +Just like the `msgServiceRouter`, the `grpcQueryRouter` is initialized with all the query routes using the application's [module manager](../../build/building-modules/01-module-manager.md) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../beginner/00-app-anatomy.md#app-constructor). ## Main ABCI 2.0 Messages @@ -318,16 +318,16 @@ to do the following checks: first, as _stateless_ checks are less computationally expensive than _stateful_ checks. If `ValidateBasic()` fail, `CheckTx` returns before running _stateful_ checks, which saves resources. This check is still performed for messages that have not yet migrated to the new message validation mechanism defined in [RFC 001](https://docs.cosmos.network/main/rfc/rfc-001-tx-validation) and still have a `ValidateBasic()` method. -3. Perform non-module related _stateful_ checks on the [account](../basics/03-accounts.md). This step is mainly about checking +3. Perform non-module related _stateful_ checks on the [account](../beginner/03-accounts.md). This step is mainly about checking that the `sdk.Msg` signatures are valid, that enough fees are provided and that the sending account - has enough funds to pay for said fees. Note that no precise [`gas`](../basics/04-gas-fees.md) counting occurs here, - as `sdk.Msg`s are not processed. Usually, the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) will check that the `gas` provided + has enough funds to pay for said fees. Note that no precise [`gas`](../beginner/04-gas-fees.md) counting occurs here, + as `sdk.Msg`s are not processed. Usually, the [`AnteHandler`](../beginner/04-gas-fees.md#antehandler) will check that the `gas` provided with the transaction is superior to a minimum reference gas amount based on the raw transaction size, in order to avoid spam with transactions that provide 0 gas. `CheckTx` does **not** process `sdk.Msg`s - they only need to be processed when the canonical state need to be updated, which happens during `FinalizeBlock`. -Steps 2. and 3. are performed by the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) in the [`RunTx()`](#runtx-antehandler-and-runmsgs) +Steps 2. and 3. are performed by the [`AnteHandler`](../beginner/04-gas-fees.md#antehandler) in the [`RunTx()`](#runtx-antehandler-and-runmsgs) function, which `CheckTx()` calls with the `runTxModeCheck` mode. During each step of `CheckTx()`, a special [volatile state](#state-updates) called `checkState` is updated. This state is used to keep track of the temporary changes triggered by the `CheckTx()` calls of each transaction without modifying @@ -371,7 +371,7 @@ This allows certain checks like signature verification can be skipped during `Ch `RunTx` is called from `CheckTx`/`Finalizeblock` to handle the transaction, with `execModeCheck` or `execModeFinalize` as parameter to differentiate between the two modes of execution. Note that when `RunTx` receives a transaction, it has already been decoded. -The first thing `RunTx` does upon being called is to retrieve the `context`'s `CacheMultiStore` by calling the `getContextForTx()` function with the appropriate mode (either `runTxModeCheck` or `execModeFinalize`). This `CacheMultiStore` is a branch of the main store, with cache functionality (for query requests), instantiated during `FinalizeBlock` for transaction execution and during the `Commit` of the previous block for `CheckTx`. After that, two `defer func()` are called for [`gas`](../basics/04-gas-fees.md) management. They are executed when `runTx` returns and make sure `gas` is actually consumed, and will throw errors, if any. +The first thing `RunTx` does upon being called is to retrieve the `context`'s `CacheMultiStore` by calling the `getContextForTx()` function with the appropriate mode (either `runTxModeCheck` or `execModeFinalize`). This `CacheMultiStore` is a branch of the main store, with cache functionality (for query requests), instantiated during `FinalizeBlock` for transaction execution and during the `Commit` of the previous block for `CheckTx`. After that, two `defer func()` are called for [`gas`](../beginner/04-gas-fees.md) management. They are executed when `runTx` returns and make sure `gas` is actually consumed, and will throw errors, if any. After that, `RunTx()` calls `ValidateBasic()`, when available and for backward compatibility, on each `sdk.Msg`in the `Tx`, which runs preliminary _stateless_ validity checks. If any `sdk.Msg` fails to pass `ValidateBasic()`, `RunTx()` returns with an error. @@ -399,15 +399,15 @@ The `AnteHandler` is theoretically optional, but still a very important componen * Perform preliminary _stateful_ validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees. * Play a role in the incentivisation of stakeholders via the collection of transaction fees. -`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../basics/00-app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/ante/ante.go). +`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../beginner/00-app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/ante/ante.go). -Click [here](../basics/04-gas-fees.md#antehandler) for more on the `anteHandler`. +Click [here](../beginner/04-gas-fees.md#antehandler) for more on the `anteHandler`. ### RunMsgs `RunMsgs` is called from `RunTx` with `runTxModeCheck` as parameter to check the existence of a route for each message the transaction, and with `execModeFinalize` to actually process the `sdk.Msg`s. -First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `type_url` of the Protobuf `Any` representing the `sdk.Msg`. Then, using the application's [`msgServiceRouter`](#msg-service-router), it checks for the existence of `Msg` service method related to that `type_url`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. Otherwise, if `mode == execModeFinalize`, the [`Msg` service](../building-modules/03-msg-services.md) RPC is executed, before `RunMsgs` returns. +First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `type_url` of the Protobuf `Any` representing the `sdk.Msg`. Then, using the application's [`msgServiceRouter`](#msg-service-router), it checks for the existence of `Msg` service method related to that `type_url`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. Otherwise, if `mode == execModeFinalize`, the [`Msg` service](../../build/building-modules/03-msg-services.md) RPC is executed, before `RunMsgs` returns. ### PostHandler @@ -430,9 +430,9 @@ The [`InitChain` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x * [Consensus Parameters](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#consensus-parameters) via `setConsensusParams`. * [`checkState` and `finalizeBlockState`](#state-updates) via `setState`. -* The [block gas meter](../basics/04-gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions. +* The [block gas meter](../beginner/04-gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions. -Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls the [`initChainer()`](../basics/00-app-anatomy.md#initchainer) of the application in order to initialize the main state of the application from the `genesis file` and, if defined, call the [`InitGenesis`](../building-modules/08-genesis.md#initgenesis) function of each of the application's modules. +Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls the [`initChainer()`](../beginner/00-app-anatomy.md#initchainer) of the application in order to initialize the main state of the application from the `genesis file` and, if defined, call the [`InitGenesis`](../../build/building-modules/08-genesis.md#initgenesis) function of each of the application's modules. ### FinalizeBlock @@ -452,10 +452,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci.go#L623 https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/baseapp.go#L682-L706 ``` - This function also resets the [main gas meter](../basics/04-gas-fees.md#main-gas-meter). + This function also resets the [main gas meter](../beginner/04-gas-fees.md#main-gas-meter). +<<<<<<< HEAD:docs/docs/core/00-baseapp.md * Initialize the [block gas meter](../basics/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. * Run the application's [`beginBlocker()`](../basics/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/05-beginblock-endblock.md#beginblock) method of each of the application's modules. +======= +* Initialize the [block gas meter](../beginner/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. +* Run the application's [`beginBlocker()`](../beginner/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../../build/building-modules/05-beginblock-endblock.md#beginblock) method of each of the non-upgrade modules. +>>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/develop/advanced/00-baseapp.md * Set the [`VoteInfos`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./02-context.md) so that it can be used during transaction execution and EndBlock. #### Transaction Execution @@ -471,7 +476,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/baseapp.go#LL7 Transaction execution within `FinalizeBlock` performs the **exact same steps as `CheckTx`**, with a little caveat at step 3 and the addition of a fifth step: 1. The `AnteHandler` does **not** check that the transaction's `gas-prices` is sufficient. That is because the `min-gas-prices` value `gas-prices` is checked against is local to the node, and therefore what is enough for one full-node might not be for another. This means that the proposer can potentially include transactions for free, although they are not incentivised to do so, as they earn a bonus on the total fee of the block they propose. -2. For each `sdk.Msg` in the transaction, route to the appropriate module's Protobuf [`Msg` service](../building-modules/03-msg-services.md). Additional _stateful_ checks are performed, and the branched multistore held in `finalizeBlockState`'s `context` is updated by the module's `keeper`. If the `Msg` service returns successfully, the branched multistore held in `context` is written to `finalizeBlockState` `CacheMultiStore`. +2. For each `sdk.Msg` in the transaction, route to the appropriate module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md). Additional _stateful_ checks are performed, and the branched multistore held in `finalizeBlockState`'s `context` is updated by the module's `keeper`. If the `Msg` service returns successfully, the branched multistore held in `context` is written to `finalizeBlockState` `CacheMultiStore`. 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: @@ -514,7 +519,7 @@ The [`Info` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec ### Query -The [`Query` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#info-methods) is used to serve queries received from the underlying consensus engine, including queries received via RPC like CometBFT RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../building-modules/04-query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#query). +The [`Query` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#info-methods) is used to serve queries received from the underlying consensus engine, including queries received via RPC like CometBFT RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../../build/building-modules/04-query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#query). Each CometBFT `query` comes with a `path`, which is a `string` which denotes what to query. If the `path` matches a gRPC fully-qualified service method, then `BaseApp` will defer the query to the `grpcQueryRouter` and let it handle it like explained [above](#grpc-query-router). Otherwise, the `path` represents a query that is not (yet) handled by the gRPC router. `BaseApp` splits the `path` string with the `/` delimiter. By convention, the first element of the split string (`split[0]`) contains the category of `query` (`app`, `p2p`, `store` or `custom` ). The `BaseApp` implementation of the `Query(req abci.RequestQuery)` method is a simple dispatcher serving these 4 main categories of queries: diff --git a/docs/docs/core/01-transactions.md b/docs/docs/develop/advanced/01-transactions.md similarity index 78% rename from docs/docs/core/01-transactions.md rename to docs/docs/develop/advanced/01-transactions.md index dd29c472b250..eee4fae37976 100644 --- a/docs/docs/core/01-transactions.md +++ b/docs/docs/develop/advanced/01-transactions.md @@ -10,15 +10,15 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK Application](../beginner/00-app-anatomy.md) ::: ## Transactions -Transactions are comprised of metadata held in [contexts](./02-context.md) and [`sdk.Msg`s](../building-modules/02-messages-and-queries.md) that trigger state changes within a module through the module's Protobuf [`Msg` service](../building-modules/03-msg-services.md). +Transactions are comprised of metadata held in [contexts](./02-context.md) and [`sdk.Msg`s](../../build/building-modules/02-messages-and-queries.md) that trigger state changes within a module through the module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md). -When users want to interact with an application and make state changes (e.g. sending coins), they create transactions. Each of a transaction's `sdk.Msg` must be signed using the private key associated with the appropriate account(s), before the transaction is broadcasted to the network. A transaction must then be included in a block, validated, and approved by the network through the consensus process. To read more about the lifecycle of a transaction, click [here](../basics/01-tx-lifecycle.md). +When users want to interact with an application and make state changes (e.g. sending coins), they create transactions. Each of a transaction's `sdk.Msg` must be signed using the private key associated with the appropriate account(s), before the transaction is broadcasted to the network. A transaction must then be included in a block, validated, and approved by the network through the consensus process. To read more about the lifecycle of a transaction, click [here](../beginner/01-tx-lifecycle.md). ## Type Definition @@ -31,10 +31,10 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L51-L5 It contains the following methods: * **GetMsgs:** unwraps the transaction and returns a list of contained `sdk.Msg`s - one transaction may have one or multiple messages, which are defined by module developers. -* **ValidateBasic:** lightweight, [_stateless_](../basics/01-tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./00-baseapp.md#checktx) and [`DeliverTx`](./00-baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth) module's `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. When [`runTx`](./00-baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself. +* **ValidateBasic:** lightweight, [_stateless_](../beginner/01-tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./00-baseapp.md#checktx) and [`DeliverTx`](./00-baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth) module's `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. When [`runTx`](./00-baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself. :::note - This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../basics/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. + This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../beginner/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. ::: As a developer, you should rarely manipulate `Tx` directly, as `Tx` is really an intermediate type used for transaction generation. Instead, developers should prefer the `TxBuilder` interface, which you can learn more about [below](#transaction-generation). @@ -51,7 +51,7 @@ The most used implementation of the `Tx` interface is the Protobuf `Tx` message, https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L13-L26 ``` -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)): +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](../../build/architecture/adr-027-deterministic-protobuf-serialization.md)): ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L48-L65 @@ -117,12 +117,12 @@ The next paragraphs will describe each of these components, in this order. Module `sdk.Msg`s are not to be confused with [ABCI Messages](https://docs.cometbft.com/v0.37/spec/abci/) which define interactions between the CometBFT and application layers. ::: -**Messages** (or `sdk.Msg`s) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the messages for their module by adding methods to the Protobuf [`Msg` service](../building-modules/03-msg-services.md), and also implement the corresponding `MsgServer`. +**Messages** (or `sdk.Msg`s) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the messages for their module by adding methods to the Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md), and also implement the corresponding `MsgServer`. -Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../building-modules/03-msg-services.md) RPC, defined inside each module's `tx.proto` file. A SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface. +Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) RPC, defined inside each module's `tx.proto` file. A SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface. This design puts more responsibility on module developers, allowing application developers to reuse common functionalities without having to implement state transition logic repetitively. -To learn more about Protobuf `Msg` services and how to implement `MsgServer`, click [here](../building-modules/03-msg-services.md). +To learn more about Protobuf `Msg` services and how to implement `MsgServer`, click [here](../../build/building-modules/03-msg-services.md). While messages contain the information for state transition logic, a transaction's other metadata and relevant information are stored in the `TxBuilder` and `Context`. @@ -170,9 +170,9 @@ Once the transaction bytes are generated, there are currently three ways of broa #### CLI -Application developers create entry points to the application by creating a [command-line interface](../core/07-cli.md), [gRPC and/or REST interface](../core/06-grpc_rest.md), typically found in the application's `./cmd` folder. These interfaces allow users to interact with the application through command-line. +Application developers create entry points to the application by creating a [command-line interface](./07-cli.md), [gRPC and/or REST interface](./06-grpc_rest.md), typically found in the application's `./cmd` folder. These interfaces allow users to interact with the application through command-line. -For the [command-line interface](../building-modules/09-module-interfaces.md#cli), module developers create subcommands to add as children to the application top-level transaction command `TxCmd`. CLI commands actually bundle all the steps of transaction processing into one simple command: creating messages, generating transactions and broadcasting. For concrete examples, see the [Interacting with a Node](../run-node/02-interact-node.md) section. An example transaction made using CLI looks like: +For the [command-line interface](../../build/building-modules/09-module-interfaces.md#cli), module developers create subcommands to add as children to the application top-level transaction command `TxCmd`. CLI commands actually bundle all the steps of transaction processing into one simple command: creating messages, generating transactions and broadcasting. For concrete examples, see the [Interacting with a Node](../../user/run-node/02-interact-node.md) section. An example transaction made using CLI looks like: ```bash simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake @@ -180,7 +180,7 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake #### gRPC -[gRPC](https://grpc.io) is the main component for the Cosmos SDK's RPC layer. Its principal usage is in the context of modules' [`Query` services](../building-modules/04-query-services.md). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service: +[gRPC](https://grpc.io) is the main component for the Cosmos SDK's RPC layer. Its principal usage is in the context of modules' [`Query` services](../../build/building-modules/04-query-services.md). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/service.proto @@ -188,13 +188,13 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta The `Tx` service exposes a handful of utility functions, such as simulating a transaction or querying a transaction, and also one method to broadcast transactions. -Examples of broadcasting and simulating a transaction are shown [here](../run-node/03-txs.md#programmatically-with-go). +Examples of broadcasting and simulating a transaction are shown [here](../../user/run-node/03-txs.md#programmatically-with-go). #### REST Each gRPC method has its corresponding REST endpoint, generated using [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway). Therefore, instead of using gRPC, you can also use HTTP to broadcast the same transaction, on the `POST /cosmos/tx/v1beta1/txs` endpoint. -An example can be seen [here](../run-node/03-txs.md#using-rest) +An example can be seen [here](../../user/run-node/03-txs.md#using-rest) #### CometBFT RPC diff --git a/docs/docs/core/02-context.md b/docs/docs/develop/advanced/02-context.md similarity index 85% rename from docs/docs/core/02-context.md rename to docs/docs/develop/advanced/02-context.md index 77397b0df452..4d9ecdf690ff 100644 --- a/docs/docs/core/02-context.md +++ b/docs/docs/develop/advanced/02-context.md @@ -10,8 +10,8 @@ The `context` is a data structure intended to be passed from function to functio :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) -* [Lifecycle of a Transaction](../basics/01-tx-lifecycle.md) +* [Anatomy of a Cosmos SDK Application](../beginner/00-app-anatomy.md) +* [Lifecycle of a Transaction](../beginner/01-tx-lifecycle.md) ::: @@ -28,12 +28,12 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/context.go#L41-L * **Header:** The [header](https://docs.cometbft.com/v0.37/spec/core/data_structures#header) is a Blockchain type. It carries important information about the state of the blockchain, such as block height and proposer of the current block. * **Header Hash:** The current block header hash, obtained during `abci.FinalizeBlock`. * **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 Cosmos SDK and consensus engine (e.g. CometBFT) throughout its [lifecycle](../basics/01-tx-lifecycle.md), some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./05-encoding.md) such as [Amino](./05-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. CometBFT) throughout its [lifecycle](../beginner/01-tx-lifecycle.md), some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./05-encoding.md) such as [Amino](./05-encoding.md). * **Logger:** A `logger` from the CometBFT libraries. Learn more about logs [here](https://docs.cometbft.com/v0.37/core/configuration). Modules call this method to create their own unique module-specific logger. * **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://docs.cometbft.com/master/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/04-gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../basics/04-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/04-gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts. +* **Gas Meters:** Specifically, a [`gasMeter`](../beginner/04-gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../beginner/04-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](../beginner/04-gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts. * **CheckTx Mode:** A boolean value indicating whether a transaction should be processed in `CheckTx` or `DeliverTx` mode. -* **Min Gas Price:** The minimum [gas](../basics/04-gas-fees.md) price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore **not be used in any functions used in sequences leading to state-transitions**. +* **Min Gas Price:** The minimum [gas](../beginner/04-gas-fees.md) price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore **not be used in any functions used in sequences leading to state-transitions**. * **Consensus Params:** The ABCI type [Consensus Parameters](https://docs.cometbft.com/master/spec/abci/apps.html#consensus-parameters), which specify certain limits for the blockchain, such as maximum gas for a block. * **Event Manager:** The event manager allows any caller with access to a `Context` to emit [`Events`](./08-events.md). Modules may define module specific `Events` by defining various `Types` and `Attributes` or use the common definitions found in `types/`. Clients can subscribe or query for these `Events`. These `Events` are collected throughout `FinalizeBlock` and are returned to CometBFT for indexing. diff --git a/docs/docs/core/03-node.md b/docs/docs/develop/advanced/03-node.md similarity index 94% rename from docs/docs/core/03-node.md rename to docs/docs/develop/advanced/03-node.md index 5ac391b25370..47b691b32c6b 100644 --- a/docs/docs/core/03-node.md +++ b/docs/docs/develop/advanced/03-node.md @@ -10,7 +10,7 @@ The main endpoint of a Cosmos SDK application is the daemon client, otherwise kn :::note Pre-requisite Readings -* [Anatomy of an SDK application](../basics/00-app-anatomy.md) +* [Anatomy of an SDK application](../beginner/00-app-anatomy.md) ::: @@ -21,7 +21,7 @@ The full-node client of any Cosmos SDK application is built by running a `main` In general, developers will implement the `main.go` function with the following structure: * First, an [`encodingCodec`](./05-encoding.md) is instantiated for the application. -* Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../basics/03-accounts.md#addresses). +* Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../beginner/03-accounts.md#addresses). ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/config.go#L14-L29 @@ -69,7 +69,7 @@ Note that an `appCreator` is a function that fulfills the `AppCreator` signature https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L68 ``` -In practice, the [constructor of the application](../basics/00-app-anatomy.md#constructor-function) is passed as the `appCreator`. +In practice, the [constructor of the application](../beginner/00-app-anatomy.md#constructor-function) is passed as the `appCreator`. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L294-L308 @@ -93,4 +93,4 @@ Upon starting, the node will bootstrap its RPC and P2P server and start dialing ## Other commands -To discover how to concretely run a node and interact with it, please refer to our [Running a Node, API and CLI](../run-node/01-run-node.md) guide. +To discover how to concretely run a node and interact with it, please refer to our [Running a Node, API and CLI](../../user/run-node/01-run-node.md) guide. diff --git a/docs/docs/core/04-store.md b/docs/docs/develop/advanced/04-store.md similarity index 94% rename from docs/docs/core/04-store.md rename to docs/docs/develop/advanced/04-store.md index bc979b6ba085..35f67665752a 100644 --- a/docs/docs/core/04-store.md +++ b/docs/docs/develop/advanced/04-store.md @@ -10,13 +10,13 @@ A store is a data structure that holds the state of the application. :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) ::: ## 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 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/06-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`](../../build/building-modules/06-keeper.md) of the module that declared the store. ```text +-----------------------------------------------------+ @@ -136,9 +136,9 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/cachemulti/store A `KVStore` is a simple key-value store used to store and retrieve data. A `CommitKVStore` is a `KVStore` that also implements a `Committer`. By default, stores mounted in `baseapp`'s main `CommitMultiStore` are `CommitKVStore`s. The `KVStore` interface is primarily used to restrict modules from accessing the committer. -Individual `KVStore`s are used by modules to manage a subset of the global state. `KVStores` can be accessed by objects that hold a specific key. This `key` should only be exposed to the [`keeper`](../building-modules/06-keeper.md) of the module that defines the store. +Individual `KVStore`s are used by modules to manage a subset of the global state. `KVStores` can be accessed by objects that hold a specific key. This `key` should only be exposed to the [`keeper`](../../build/building-modules/06-keeper.md) of the module that defines the store. -`CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../basics/00-app-anatomy.md#core-application-file). In the same file, the `key` is also passed to the module's `keeper` that is responsible for managing the store. +`CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../beginner/00-app-anatomy.md#core-application-file). In the same file, the `key` is also passed to the module's `keeper` that is responsible for managing the store. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/types/store.go#L229-L266 @@ -224,7 +224,7 @@ This is the type used whenever an IAVL Store needs to be branched to create an i ### `GasKv` Store -Cosmos SDK applications use [`gas`](../basics/04-gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications. +Cosmos SDK applications use [`gas`](../beginner/04-gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/gaskv/store.go#L11-L17 diff --git a/docs/docs/core/05-encoding.md b/docs/docs/develop/advanced/05-encoding.md similarity index 91% rename from docs/docs/core/05-encoding.md rename to docs/docs/develop/advanced/05-encoding.md index 202609420ac6..6253ba166a11 100644 --- a/docs/docs/core/05-encoding.md +++ b/docs/docs/develop/advanced/05-encoding.md @@ -10,7 +10,7 @@ While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) ::: @@ -127,7 +127,7 @@ the consensus engine accepts only transactions in the form of raw bytes. https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L91-L95 ``` -A standard implementation of both these objects can be found in the [`auth/tx` module](../modules/auth/tx/README.md): +A standard implementation of both these objects can be found in the [`auth/tx` module](../../build/modules/auth/2-tx.md): ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/decoder.go @@ -137,11 +137,11 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/decoder.go https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/encoder.go ``` -See [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. +See [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. ### Interface Encoding and Usage of `Any` -The Protobuf DSL is strongly typed, which can make inserting variable-typed fields difficult. Imagine we want to create a `Profile` protobuf message that serves as a wrapper over [an account](../basics/03-accounts.md): +The Protobuf DSL is strongly typed, which can make inserting variable-typed fields difficult. Imagine we want to create a `Profile` protobuf message that serves as a wrapper over [an account](../beginner/03-accounts.md): ```protobuf message Profile { @@ -152,13 +152,13 @@ message Profile { } ``` -In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../modules/auth/1-vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface? +In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../../build/modules/auth/1-vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface? ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/account.go#L15-L32 ``` -In [ADR-019](../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: +In [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: ```protobuf message Profile { @@ -227,7 +227,7 @@ func (p *Profile) UnpackInterfaces(unpacker codectypes.AnyUnpacker) error { The `UnpackInterfaces` gets called recursively on all structs implementing this method, to allow all `Any`s to have their `GetCachedValue()` correctly populated. -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). +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](../../build/architecture/adr-019-protobuf-state-encoding.md). #### `Any` Encoding in the Cosmos SDK @@ -285,14 +285,14 @@ import ( Protobuf types can be defined to encode: * state -* [`Msg`s](../building-modules/02-messages-and-queries.md#messages) -* [Query services](../building-modules/04-query-services.md) -* [genesis](../building-modules/08-genesis.md) +* [`Msg`s](../../build/building-modules/02-messages-and-queries.md#messages) +* [Query services](../../build/building-modules/04-query-services.md) +* [genesis](../../build/building-modules/08-genesis.md) #### Naming and conventions We encourage developers to follow industry guidelines: [Protocol Buffers style guide](https://developers.google.com/protocol-buffers/docs/style) -and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../architecture/adr-023-protobuf-naming.md) +and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../../build/architecture/adr-023-protobuf-naming.md) ### How to update modules to protobuf encoding diff --git a/docs/docs/core/06-grpc_rest.md b/docs/docs/develop/advanced/06-grpc_rest.md similarity index 91% rename from docs/docs/core/06-grpc_rest.md rename to docs/docs/develop/advanced/06-grpc_rest.md index f78bfa62b346..da44796c8912 100644 --- a/docs/docs/core/06-grpc_rest.md +++ b/docs/docs/develop/advanced/06-grpc_rest.md @@ -24,13 +24,13 @@ The node also exposes some other endpoints, such as the CometBFT P2P endpoint, o In the Cosmos SDK, Protobuf is the main [encoding](./encoding) library. 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/02-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: +Each module exposes a [Protobuf `Query` service](../../build/building-modules/02-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: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L46-L48 ``` -Note: It is not possible to expose any [Protobuf `Msg` service](../building-modules/02-messages-and-queries.md#messages) endpoints via gRPC. Transactions must be generated and signed using the CLI or programmatically before they can be broadcasted using gRPC. See [Generating, Signing, and Broadcasting Transactions](../run-node/03-txs.md) for more information. +Note: It is not possible to expose any [Protobuf `Msg` service](../../build/building-modules/02-messages-and-queries.md#messages) endpoints via gRPC. Transactions must be generated and signed using the CLI or programmatically before they can be broadcasted using gRPC. See [Generating, Signing, and Broadcasting Transactions](../../user/run-node/03-txs.md) for more information. The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC query requests and a broadcast transaction request. This server can be configured inside `~/.simapp/config/app.toml`: @@ -41,7 +41,7 @@ The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC qu `~/.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/02-interact-node.md#using-grpc) tutorial. +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](../../user/run-node/02-interact-node.md#using-grpc) tutorial. An overview of all available gRPC endpoints shipped with the Cosmos SDK is [Protobuf documentation](https://buf.build/cosmos/cosmos-sdk). diff --git a/docs/docs/core/07-cli.md b/docs/docs/develop/advanced/07-cli.md similarity index 80% rename from docs/docs/core/07-cli.md rename to docs/docs/develop/advanced/07-cli.md index 5d2be5c03cb9..bbe2ca4ef8f2 100644 --- a/docs/docs/core/07-cli.md +++ b/docs/docs/develop/advanced/07-cli.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Command-Line Interface :::note Synopsis -This document describes how command-line interface (CLI) works on a high-level, for an [**application**](../basics/00-app-anatomy.md). A separate document for implementing a CLI for a Cosmos SDK [**module**](../building-modules/01-intro.md) can be found [here](../building-modules/09-module-interfaces.md#cli). +This document describes how command-line interface (CLI) works on a high-level, for an [**application**](../beginner/00-app-anatomy.md). A separate document for implementing a CLI for a Cosmos SDK [**module**](../../build/building-modules/01-intro.md) can be found [here](../../build/building-modules/09-module-interfaces.md#cli). ::: ## Command-Line Interface @@ -24,12 +24,12 @@ The first four strings specify the command: * The root command for the entire application `simd`. * The subcommand `tx`, which contains all commands that let users create transactions. -* The subcommand `bank` to indicate which module to route the command to ([`x/bank`](../modules/bank/README.md) module in this case). +* The subcommand `bank` to indicate which module to route the command to ([`x/bank`](../../build/modules/bank/README.md) module in this case). * The type of transaction `send`. The next two strings are arguments: the `from_address` the user wishes to send from, the `to_address` of the recipient, and the `amount` they want to send. Finally, the last few strings of the command are optional flags to indicate how much the user is willing to pay in fees (calculated using the amount of gas used to execute the transaction and the gas prices provided by the user). -The CLI interacts with a [node](../core/03-node.md) to handle this command. The interface itself is defined in a `main.go` file. +The CLI interacts with a [node](./03-node.md) to handle this command. The interface itself is defined in a `main.go` file. ### Building the CLI @@ -37,7 +37,7 @@ The `main.go` file needs to have a `main()` function that creates a root command * **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 injecting the application codecs. The [`codec`](../core/05-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. +* **instantiating the `codec`** by injecting the application codecs. The [`codec`](./05-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). The `main()` function finally creates an executor and [execute](https://pkg.go.dev/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application: @@ -56,8 +56,8 @@ 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 Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/03-node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`. -* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.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 ` 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.50.0-alpha.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/00-keyring.md). +* **Status** command from the Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](./03-node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`. +* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.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 ` 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.50.0-alpha.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../../user/run-node/00-keyring.md). * **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI CometBFT application and provides the CLI framework (based on [cobra](https://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. Learn more [here](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server). * [**Transaction**](#transaction-commands) commands. @@ -93,7 +93,7 @@ The root-level `status` and `keys` subcommands are common across most applicatio ### Transaction Commands -[Transactions](./01-transactions.md) are objects wrapping [`Msg`s](../building-modules/02-messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCommand` is generally added to the `rootCmd`: +[Transactions](./01-transactions.md) are objects wrapping [`Msg`s](../../build/building-modules/02-messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCommand` is generally added to the `rootCmd`: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L222-L229 @@ -101,9 +101,9 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v This `txCommand` function adds all the transaction available to end-users for the application. This typically includes: -* **Sign command** from the [`auth`](../modules/auth/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. +* **Sign command** from the [`auth`](../../build/modules/auth/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 Cosmos SDK client tools, to broadcast transactions. -* **All [module transaction commands](../building-modules/09-module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/01-module-manager.md#basic-manager) `AddTxCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). +* **All [module transaction commands](../../build/building-modules/09-module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#basic-manager) `AddTxCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). Here is an example of a `txCommand` aggregating these subcommands from the `simapp` application: @@ -118,7 +118,7 @@ Read more about [AutoCLI](https://docs.cosmos.network/main/core/autocli) in its ### Query Commands -[**Queries**](../building-modules/02-messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of queries using the CLI interface, a function `queryCommand` is generally added to the `rootCmd`: +[**Queries**](../../build/building-modules/02-messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of queries using the CLI interface, a function `queryCommand` is generally added to the `rootCmd`: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L222-L229 @@ -130,7 +130,7 @@ This `queryCommand` function adds all the queries available to end-users for the * **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address. * **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/09-module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/01-module-manager.md#basic-manager) `AddQueryCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). +* **All [module query commands](../../build/building-modules/09-module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#basic-manager) `AddQueryCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). Here is an example of a `queryCommand` aggregating subcommands from the `simapp` application: @@ -145,11 +145,11 @@ Read more about [AutoCLI](https://docs.cosmos.network/main/core/autocli) in its ## Flags -Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with. +Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their [`app.toml`](../../user/run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with. A *persistent* flag (as opposed to a *local* flag) added to a command transcends all of its children: subcommands will inherit the configured values for these flags. Additionally, all flags have default values when they are added to commands; some toggle an option off but others are empty values that the user needs to override to create valid commands. A flag can be explicitly marked as *required* so that an error is automatically thrown if the user does not provide a value, but it is also acceptable to handle unexpected missing flags differently. -Flags are added to commands directly (generally in the [module's CLI file](../building-modules/09-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. +Flags are added to commands directly (generally in the [module's CLI file](../../build/building-modules/09-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. ## Environment variables diff --git a/docs/docs/core/08-events.md b/docs/docs/develop/advanced/08-events.md similarity index 91% rename from docs/docs/core/08-events.md rename to docs/docs/develop/advanced/08-events.md index e063a991cdaa..410e20ade09d 100644 --- a/docs/docs/core/08-events.md +++ b/docs/docs/develop/advanced/08-events.md @@ -9,7 +9,7 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) * [CometBFT Documentation on Events](https://docs.cometbft.com/v0.37/spec/abci/abci++_basic_concepts#events) ::: @@ -33,10 +33,10 @@ An Event contains: To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value. ::: -_Typed Events_ are Protobuf-defined [messages](../architecture/adr-032-typed-events.md) used by the Cosmos SDK +_Typed Events_ are Protobuf-defined [messages](../../build/architecture/adr-032-typed-events.md) used by the Cosmos SDK for emitting and querying Events. They are defined in a `event.proto` file, on a **per-module basis** and are read as `proto.Message`. _Legacy Events_ are defined on a **per-module basis** in the module's `/types/events.go` file. -They are triggered from the module's Protobuf [`Msg` service](../building-modules/03-msg-services.md) +They are triggered from the module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) by using the [`EventManager`](#eventmanager). In addition, each module documents its events under in the `Events` sections of its specs (x/{moduleName}/`README.md`). @@ -55,9 +55,9 @@ The following examples show how to query Events using the Cosmos SDK. | Event | Description | | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tx.height=23` | Query all transactions at height 23 | -| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../building-modules/03-msg-services.md). Note the `'`s around the value. | +| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../../build/building-modules/03-msg-services.md). Note the `'`s around the value. | | `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | -| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../modules/staking/README.md). | +| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../build/modules/staking/README.md). | ## EventManager @@ -98,7 +98,7 @@ ctx.EventManager().EmitEvent( Where the `EventManager` is accessed via the [`Context`](./02-context.md). -See the [`Msg` services](../building-modules/03-msg-services.md) concept doc for a more detailed +See the [`Msg` services](../../build/building-modules/03-msg-services.md) concept doc for a more detailed view on how to typically implement Events and use the `EventManager` in modules. ## Subscribing to Events @@ -140,7 +140,7 @@ Subscribing to this Event would be done like so: } ``` -where `ownerAddress` is an address following the [`AccAddress`](../basics/03-accounts.md#addresses) format. +where `ownerAddress` is an address following the [`AccAddress`](../beginner/03-accounts.md#addresses) format. The same way can be used to subscribe to [legacy events](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/types/events.go). diff --git a/docs/docs/core/09-telemetry.md b/docs/docs/develop/advanced/09-telemetry.md similarity index 100% rename from docs/docs/core/09-telemetry.md rename to docs/docs/develop/advanced/09-telemetry.md diff --git a/docs/docs/core/10-ocap.md b/docs/docs/develop/advanced/10-ocap.md similarity index 100% rename from docs/docs/core/10-ocap.md rename to docs/docs/develop/advanced/10-ocap.md diff --git a/docs/docs/core/11-runtx_middleware.md b/docs/docs/develop/advanced/11-runtx_middleware.md similarity index 89% rename from docs/docs/core/11-runtx_middleware.md rename to docs/docs/develop/advanced/11-runtx_middleware.md index 76700fd959ba..f083a77888e5 100644 --- a/docs/docs/core/11-runtx_middleware.md +++ b/docs/docs/develop/advanced/11-runtx_middleware.md @@ -8,7 +8,7 @@ sidebar_position: 1 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 Cosmos SDK application developers. -More context can found in the corresponding [ADR-022](../architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go). +More context can found in the corresponding [ADR-022](../../build/architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go). ## Interface diff --git a/docs/docs/core/12-simulation.md b/docs/docs/develop/advanced/12-simulation.md similarity index 97% rename from docs/docs/core/12-simulation.md rename to docs/docs/develop/advanced/12-simulation.md index ff65f33052e0..dfbcddd0d29f 100644 --- a/docs/docs/core/12-simulation.md +++ b/docs/docs/develop/advanced/12-simulation.md @@ -94,8 +94,8 @@ Here are some suggestions when encountering a simulation failure: ## Use simulation in your Cosmos SDK-based application -Learn how you can integrate the simulation into your Cosmos SDK-based application: +Learn how you can build the simulation into your Cosmos SDK-based application: * Application Simulation Manager -* [Building modules: Simulator](../building-modules/14-simulator.md) +* [Building modules: Simulator](../../build/building-modules/14-simulator.md) * Simulator tests diff --git a/docs/docs/core/13-proto-docs.md b/docs/docs/develop/advanced/13-proto-docs.md similarity index 100% rename from docs/docs/core/13-proto-docs.md rename to docs/docs/develop/advanced/13-proto-docs.md diff --git a/docs/docs/core/14-tips.md b/docs/docs/develop/advanced/14-tips.md similarity index 100% rename from docs/docs/core/14-tips.md rename to docs/docs/develop/advanced/14-tips.md diff --git a/docs/docs/core/15-upgrade.md b/docs/docs/develop/advanced/15-upgrade.md similarity index 97% rename from docs/docs/core/15-upgrade.md rename to docs/docs/develop/advanced/15-upgrade.md index b5db25589658..e926bc5dffab 100644 --- a/docs/docs/core/15-upgrade.md +++ b/docs/docs/develop/advanced/15-upgrade.md @@ -16,7 +16,7 @@ The Cosmos SDK uses two methods to perform upgrades: * Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. -* Perform upgrades in place, which significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/13-upgrade.md) to set up your application modules to take advantage of in-place upgrades. +* Perform upgrades in place, which significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../../build/building-modules/13-upgrade.md) to set up your application modules to take advantage of in-place upgrades. This document provides steps to use the In-Place Store Migrations upgrade method. @@ -63,7 +63,7 @@ app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgrad }) ``` -To learn more about configuring migration scripts for your modules, see the [Module Upgrade Guide](../building-modules/13-upgrade.md). +To learn more about configuring migration scripts for your modules, see the [Module Upgrade Guide](../../build/building-modules/13-upgrade.md). ### Order Of Migrations diff --git a/docs/docs/core/16-config.md b/docs/docs/develop/advanced/16-config.md similarity index 100% rename from docs/docs/core/16-config.md rename to docs/docs/develop/advanced/16-config.md diff --git a/docs/docs/core/_category_.json b/docs/docs/develop/advanced/_category_.json similarity index 100% rename from docs/docs/core/_category_.json rename to docs/docs/develop/advanced/_category_.json diff --git a/docs/docs/core/baseapp_state-begin_block.png b/docs/docs/develop/advanced/baseapp_state-begin_block.png similarity index 100% rename from docs/docs/core/baseapp_state-begin_block.png rename to docs/docs/develop/advanced/baseapp_state-begin_block.png diff --git a/docs/docs/core/baseapp_state-checktx.png b/docs/docs/develop/advanced/baseapp_state-checktx.png similarity index 100% rename from docs/docs/core/baseapp_state-checktx.png rename to docs/docs/develop/advanced/baseapp_state-checktx.png diff --git a/docs/docs/core/baseapp_state-commit.png b/docs/docs/develop/advanced/baseapp_state-commit.png similarity index 100% rename from docs/docs/core/baseapp_state-commit.png rename to docs/docs/develop/advanced/baseapp_state-commit.png diff --git a/docs/docs/core/baseapp_state-deliver_tx.png b/docs/docs/develop/advanced/baseapp_state-deliver_tx.png similarity index 100% rename from docs/docs/core/baseapp_state-deliver_tx.png rename to docs/docs/develop/advanced/baseapp_state-deliver_tx.png diff --git a/docs/docs/core/baseapp_state-initchain.png b/docs/docs/develop/advanced/baseapp_state-initchain.png similarity index 100% rename from docs/docs/core/baseapp_state-initchain.png rename to docs/docs/develop/advanced/baseapp_state-initchain.png diff --git a/docs/docs/core/baseapp_state-prepareproposal.png b/docs/docs/develop/advanced/baseapp_state-prepareproposal.png similarity index 100% rename from docs/docs/core/baseapp_state-prepareproposal.png rename to docs/docs/develop/advanced/baseapp_state-prepareproposal.png diff --git a/docs/docs/core/baseapp_state-processproposal.png b/docs/docs/develop/advanced/baseapp_state-processproposal.png similarity index 100% rename from docs/docs/core/baseapp_state-processproposal.png rename to docs/docs/develop/advanced/baseapp_state-processproposal.png diff --git a/docs/docs/core/baseapp_state.png b/docs/docs/develop/advanced/baseapp_state.png similarity index 100% rename from docs/docs/core/baseapp_state.png rename to docs/docs/develop/advanced/baseapp_state.png diff --git a/docs/docs/basics/00-app-anatomy.md b/docs/docs/develop/beginner/00-app-anatomy.md similarity index 65% rename from docs/docs/basics/00-app-anatomy.md rename to docs/docs/develop/beginner/00-app-anatomy.md index 005bbafb0ece..4d924ba05da9 100644 --- a/docs/docs/basics/00-app-anatomy.md +++ b/docs/docs/develop/beginner/00-app-anatomy.md @@ -10,7 +10,7 @@ This document describes the core parts of a Cosmos SDK application, represented ## Node Client -The Daemon, or [Full-Node Client](../core/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. +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 ^ +-------------------------------+ ^ @@ -30,9 +30,9 @@ Blockchain Node | | Consensus | | 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`](../core/03-node.md#main-function) function placed in `./cmd/appd/`. This operation usually happens through the [Makefile](#dependencies-and-makefile). +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](../core/03-node.md#start-command). This command function primarily does three things: +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`. @@ -50,12 +50,12 @@ In general, the core of the state-machine is defined in a file called `app.go`. 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`](../core/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](../core/00-baseapp.md#routing). -* **A list of store keys**. The [store](../core/04-store.md), which contains the entire state, is implemented as a [`multistore`](../core/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](../core/10-ocap.md) of the Cosmos SDK. -* **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../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`](../core/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](../core/05-encoding.md). -* **A reference to a [`legacyAmino`](../core/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](../building-modules/01-module-manager.md#manager)** and a [basic module manager](../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](../core/00-baseapp.md#msg-services) and [gRPC `Query` service](../core/00-baseapp.md#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker). +* **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), [`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: @@ -65,7 +65,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L173-L21 ### 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](../core/03-node.md#start-command) of the application's daemon command. +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 @@ -73,17 +73,17 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L6 Here are the main actions performed by this function: -* Instantiate a new [`codec`](../core/05-encoding.md) and initialize the `codec` of each of the application's modules using the [basic manager](../building-modules/01-module-manager.md#basicmanager). +* 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](../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](../core/00-baseapp.md#msg-services), [gRPC `Query` services](../core/00-baseapp.md#grpc-query-services), [legacy `Msg` routes](../core/00-baseapp.md#routing), and [legacy query routes](../core/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](../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`](../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. +* 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`, `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. * [`BeginBlocker`, `EndBlocker`](#beginblocker-and-endlbocker): called at the beginning and at the end of every block. - * [`anteHandler`](../core/00-baseapp.md#antehandler): used to handle fees and signature verification. + * [`anteHandler`](../advanced/00-baseapp.md#antehandler): used to handle fees and signature verification. * Mount the stores. * Return the application. @@ -99,7 +99,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L223-L57 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`](../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](../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`. +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`: @@ -111,7 +111,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L626-L63 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`](../building-modules/05-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](../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. +In general, the `BeginBlocker` and `EndBlocker` functions are mostly composed of the [`BeginBlock` and `EndBlock`](../../build/building-modules/05-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. @@ -132,10 +132,10 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/params/encoding 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](../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](../architecture/adr-019-protobuf-state-encoding.md). + * 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](../core/01-transactions.md). +* `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. @@ -147,19 +147,19 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/params/encoding ## Modules -[Modules](../building-modules/01-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`](../core/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). +[Modules](../../build/building-modules/01-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](../building-modules/01-module-manager.md#application-module-interfaces) defined in the Cosmos SDK, [`AppModuleBasic`](../building-modules/01-module-manager.md#appmodulebasic) and [`AppModule`](../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`. +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`](../building-modules/01-module-manager.md#manager), which manages the application's collection of modules. +`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](../core/01-transactions.md), and each transaction contains one or multiple messages. +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: @@ -182,7 +182,7 @@ Each module should also implement the `RegisterServices` method as part of the [ ### 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`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). +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. @@ -192,7 +192,7 @@ Finally, each module should also implement the `RegisterServices` method as part ### Keeper -[`Keepers`](../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](../core/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`](../../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. @@ -210,10 +210,10 @@ Each module defines command-line commands, gRPC services, and REST routes to be #### CLI -Generally, the [commands related to a module](../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): +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](../core/00-baseapp.md#query-routing), which routes them to the appropriate [querier](#querier) the `queryRoute` parameter supplied. +* 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 @@ -230,13 +230,13 @@ Some external clients may not wish to use gRPC. In this case, the Cosmos SDK pro 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`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml) config file, under the `api.swagger` key. +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](../core/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: +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. diff --git a/docs/docs/basics/01-tx-lifecycle.md b/docs/docs/develop/beginner/01-tx-lifecycle.md similarity index 82% rename from docs/docs/basics/01-tx-lifecycle.md rename to docs/docs/develop/beginner/01-tx-lifecycle.md index d6c703dacc42..e3831ae3b45c 100644 --- a/docs/docs/basics/01-tx-lifecycle.md +++ b/docs/docs/develop/beginner/01-tx-lifecycle.md @@ -5,7 +5,7 @@ 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](../core/01-transactions.md). The transaction is referred to as `Tx`. +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 @@ -17,7 +17,7 @@ This document describes the lifecycle of a transaction from creation to committe ### 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](../core/07-cli.md), providing the type of transaction in `[command]`, arguments in `[args]`, and configurations such as gas prices in `[flags]`: +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] @@ -29,7 +29,7 @@ There are several required and optional flags for transaction creation. The `--f #### Gas and Fees -Additionally, there are several [flags](../core/07-cli.md) users can use to indicate how much they are willing to pay in [fees](./04-gas-fees.md): +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. @@ -51,7 +51,7 @@ appd tx send 1000uatom --from --gas auto --ga #### 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](../core/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). +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 @@ -71,7 +71,7 @@ are not empty, enforcing nonnegative numbers, and other logic specified in the d **_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](../core/00-baseapp.md#state-updates) +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. @@ -82,16 +82,16 @@ 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](../core/05-encoding.md) `[]byte` form and needs to be unmarshaled in order to be processed. Then, the [`runTx`](../core/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. +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`](../core/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`](../core/00-baseapp.md#checktx) and [`DeliverTx`](../core/00-baseapp.md#delivertx) transactions. +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](../building-modules/03-msg-services.md#Validation). +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. ::: @@ -102,7 +102,7 @@ Read [RFC 001](https://docs.cosmos.network/main/rfc/rfc-001-tx-validation) for m #### Guideline -`ValidateBasic` should not be used anymore. Message validation should be performed in the `Msg` service when [handling a message](../building-modules/msg-services#Validation) in a module Msg Server. +`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 @@ -114,7 +114,7 @@ For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/ ### Gas -The [`Context`](../core/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`. +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 @@ -203,10 +203,10 @@ Although every full-node operates individually and locally, the outcome is alway ### Transaction Execution -The `FinalizeBlock` ABCI function defined in [`BaseApp`](../core/00-baseapp.md) does the bulk of the +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`](../core/00-baseapp.md#runtx) function in deliver mode instead of check mode. +[`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. @@ -219,14 +219,14 @@ Instead of using their `checkState`, full-nodes use `finalizeblock`: to each node - differing values across nodes yield nondeterministic results. * **`MsgServiceRouter`:** After `CheckTx` exits, `FinalizeBlock` continues to run - [`runMsgs`](../core/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) to fully execute each `Msg` within the transaction. + [`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](../building-modules/03-msg-services.md). - For `LegacyMsg` routing, the `Route` function is called via the [module manager](../building-modules/01-module-manager.md) to retrieve the route name and find the legacy [`Handler`](../building-modules/03-msg-services.md#handler-type) within the 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`](../core/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. +* **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 @@ -247,8 +247,8 @@ 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`](../core/00-baseapp.md#commit) -ABCI method inherited from [Baseapp](../core/00-baseapp.md); it syncs all the state transitions by +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. diff --git a/docs/docs/basics/02-query-lifecycle.md b/docs/docs/develop/beginner/02-query-lifecycle.md similarity index 67% rename from docs/docs/basics/02-query-lifecycle.md rename to docs/docs/develop/beginner/02-query-lifecycle.md index 29332d802eff..04e4fc9ed644 100644 --- a/docs/docs/basics/02-query-lifecycle.md +++ b/docs/docs/develop/beginner/02-query-lifecycle.md @@ -15,9 +15,9 @@ This document describes the lifecycle of a query in a Cosmos SDK application, fr ## Query Creation -A [**query**](../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](../core/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. +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`](../modules/staking/README.md) module handles this query. But first, there are a few ways `MyQuery` can be created by users. +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 @@ -27,7 +27,7 @@ The main interface for an application is the command-line interface. Users conne simd query staking delegations ``` -This query command was defined by the [`staking`](../modules/staking/README.md) module developer and added to the list of subcommands by the application developer when creating the CLI. +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: @@ -35,13 +35,13 @@ Note that the general format is as follows: simd query [moduleName] [command] --flag ``` -To provide values such as `--node` (the full-node the CLI connects to), the user can use the [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml) config file to set them or provide them as flags. +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](../core/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. +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](../core/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. +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: @@ -57,7 +57,7 @@ grpcurl \ ### REST -Another interface through which users can make queries is through HTTP Requests to a [REST server](../core/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). +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: @@ -73,10 +73,10 @@ The preceding examples show how an external user can interact with a node by que 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](../core/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`](../modules/auth/README.md) module, which translates `[]byte`s into accounts. +* **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](../basics/03-accounts.md#keyring) used to sign transactions and handle other operations with keys. +* **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. @@ -110,7 +110,7 @@ The Cosmos SDK leverages code generated from Protobuf services to make queries. 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**](../core/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()`. +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: @@ -120,15 +120,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/query.go#L79-L1 ## RPC -With a call to `ABCIQueryWithOptions()`, `MyQuery` is received by a [full-node](../core/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. +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`](../core/00-baseapp.md) implements the ABCI [`Query()`](../core/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. +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](../building-modules/04-query-services.md). +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. @@ -138,7 +138,7 @@ Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci ### CLI Response -The application [`codec`](../core/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). +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 diff --git a/docs/docs/basics/03-accounts.md b/docs/docs/develop/beginner/03-accounts.md similarity index 95% rename from docs/docs/basics/03-accounts.md rename to docs/docs/develop/beginner/03-accounts.md index 45a1e6e302a1..7280108ac744 100644 --- a/docs/docs/basics/03-accounts.md +++ b/docs/docs/develop/beginner/03-accounts.md @@ -17,7 +17,7 @@ This document describes the in-built account and public key system of the Cosmos ## 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](../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`. +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. @@ -152,7 +152,7 @@ The default implementation of `Keyring` comes from the third-party [`99designs/k 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](../architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../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`](../core/00-baseapp.md#antehandler). +* `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 diff --git a/docs/docs/basics/04-gas-fees.md b/docs/docs/develop/beginner/04-gas-fees.md similarity index 70% rename from docs/docs/basics/04-gas-fees.md rename to docs/docs/develop/beginner/04-gas-fees.md index c20231a117ad..11b7efdf5f1e 100644 --- a/docs/docs/basics/04-gas-fees.md +++ b/docs/docs/develop/beginner/04-gas-fees.md @@ -19,7 +19,7 @@ This document describes the default strategies to handle gas and fees within a C 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`](../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). +* 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 @@ -40,7 +40,7 @@ where: * `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`](../core/02-context.md), and consuming gas is done with the following pattern: +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") @@ -50,19 +50,19 @@ By default, the Cosmos SDK makes use of two different gas meters, the [main gas ### 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`](../core/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. +`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`](../building-modules/05-beginblock-endblock.md) or [`Msg` service](../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`](../core/04-store.md#gaskv-store). +Gas consumption can be done manually, generally by the module developer in the [`BeginBlocker`, `EndBlocker`](../../build/building-modules/05-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`](../core/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: +`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](../core/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: +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( @@ -89,9 +89,9 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L51-L5 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`](../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`. +* 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`](../core/00-baseapp.md#finalizeblock) returns. +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. diff --git a/docs/docs/basics/_category_.json b/docs/docs/develop/beginner/_category_.json similarity index 100% rename from docs/docs/basics/_category_.json rename to docs/docs/develop/beginner/_category_.json diff --git a/docs/docs/intro/00-overview.md b/docs/docs/develop/intro/00-overview.md similarity index 86% rename from docs/docs/intro/00-overview.md rename to docs/docs/develop/intro/00-overview.md index 31301657727a..58b743688a81 100644 --- a/docs/docs/intro/00-overview.md +++ b/docs/docs/develop/intro/00-overview.md @@ -8,7 +8,7 @@ sidebar_position: 1 The [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is an open-source framework for building multi-asset public Proof-of-Stake (PoS) blockchains, like the Cosmos Hub, as well as permissioned Proof-of-Authority (PoA) blockchains. Blockchains built with the Cosmos SDK are generally referred to as **application-specific blockchains**. -The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. We envision the Cosmos SDK as the npm-like framework to build secure blockchain applications on top of [CometBFT](https://github.com/cometbft/cometbft). SDK-based blockchains are built out of composable [modules](../building-modules/01-intro.md), most of which are open-source and readily available for any developers to use. Anyone can create a module for the Cosmos SDK, and integrating already-built modules is as simple as importing them into your blockchain application. What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../core/10-ocap.md). +The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. We envision the Cosmos SDK as the npm-like framework to build secure blockchain applications on top of [CometBFT](https://github.com/cometbft/cometbft). SDK-based blockchains are built out of composable [modules](../../build/building-modules/01-intro.md), most of which are open-source and readily available for any developers to use. Anyone can create a module for the Cosmos SDK, and integrating already-built modules is as simple as importing them into your blockchain application. What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../advanced/10-ocap.md). ## What are Application-Specific Blockchains diff --git a/docs/docs/intro/01-why-app-specific.md b/docs/docs/develop/intro/01-why-app-specific.md similarity index 100% rename from docs/docs/intro/01-why-app-specific.md rename to docs/docs/develop/intro/01-why-app-specific.md diff --git a/docs/docs/intro/02-sdk-app-architecture.md b/docs/docs/develop/intro/02-sdk-app-architecture.md similarity index 91% rename from docs/docs/intro/02-sdk-app-architecture.md rename to docs/docs/develop/intro/02-sdk-app-architecture.md index 465948bacac5..475326903ea7 100644 --- a/docs/docs/intro/02-sdk-app-architecture.md +++ b/docs/docs/develop/intro/02-sdk-app-architecture.md @@ -84,8 +84,8 @@ Note that **CometBFT only handles transaction bytes**. It has no knowledge of wh Here are the most important messages of the ABCI: -* `CheckTx`: When a transaction is received by CometBFT, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.cometbft.com/v0.37/spec/p2p/messages/mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. -* `DeliverTx`: When a [valid block](https://docs.cometbft.com/v0.37/spec/core/data_structures#block) is received by CometBFT, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../building-modules/03-msg-services.md) RPC for each message in the transaction. +* `CheckTx`: When a transaction is received by CometBFT, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`]../beginner/04-gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.cometbft.com/v0.37/spec/p2p/messages/mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. +* `DeliverTx`: When a [valid block](https://docs.cometbft.com/v0.37/spec/core/data_structures#block) is received by CometBFT, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../../build/building-modules/03-msg-services.md) RPC for each message in the transaction. * `BeginBlock`/`EndBlock`: These messages are executed at the beginning and the end of each block, whether the block contains transactions or not. It is useful to trigger automatic execution of logic. Proceed with caution though, as computationally expensive loops could slow down your blockchain, or even freeze it if the loop is infinite. Find a more detailed view of the ABCI methods from the [CometBFT docs](https://docs.cometbft.com/v0.37/spec/abci/). diff --git a/docs/docs/intro/03-sdk-design.md b/docs/docs/develop/intro/03-sdk-design.md similarity index 85% rename from docs/docs/intro/03-sdk-design.md rename to docs/docs/develop/intro/03-sdk-design.md index eea12fd4dcbb..78afb12989cc 100644 --- a/docs/docs/intro/03-sdk-design.md +++ b/docs/docs/develop/intro/03-sdk-design.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Main Components of the Cosmos SDK -The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of CometBFT. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./02-sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../core/04-store.md#multistore) to persist data and a [`router`](../core/00-baseapp.md#routing) to handle transactions. +The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of CometBFT. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./02-sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../advanced/04-store.md#multistore) to persist data and a [`router`](../advanced/00-baseapp.md#routing) to handle transactions. Here is a simplified view of how transactions are handled by an application built on top of the Cosmos SDK when transferred from CometBFT via `DeliverTx`: @@ -15,7 +15,7 @@ Here is a simplified view of how transactions are handled by an application buil ## `baseapp` -`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`](../basics/00-app-anatomy.md#core-application-file). +`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`]../beginner/00-app-anatomy.md#core-application-file). Here is an example of this from `simapp`, the Cosmos SDK demonstration app: @@ -25,13 +25,13 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L170-L21 The goal of `baseapp` is to provide a secure interface between the store and the extensible state machine while defining as little about the state machine as possible (staying true to the ABCI). -For more on `baseapp`, please click [here](../core/00-baseapp.md). +For more on `baseapp`, please click [here](../advanced/00-baseapp.md). ## Multistore -The Cosmos SDK provides a [`multistore`](../core/04-store.md#multistore) for persisting state. The multistore allows developers to declare any number of [`KVStores`](../core/04-store.md#base-layer-kvstores). These `KVStores` only accept the `[]byte` type as value and therefore any custom structure needs to be marshalled using [a codec](../core/05-encoding.md) before being stored. +The Cosmos SDK provides a [`multistore`](../advanced/04-store.md#multistore) for persisting state. The multistore allows developers to declare any number of [`KVStores`](../advanced/04-store.md#base-layer-kvstores). These `KVStores` only accept the `[]byte` type as value and therefore any custom structure needs to be marshalled using [a codec](../advanced/05-encoding.md) before being stored. -The multistore abstraction is used to divide the state in distinct compartments, each managed by its own module. For more on the multistore, click [here](../core/04-store.md#multistore) +The multistore abstraction is used to divide the state in distinct compartments, each managed by its own module. For more on the multistore, click [here](../advanced/04-store.md#multistore) ## Modules @@ -84,7 +84,7 @@ Here is a simplified view of how a transaction is processed by the application o v ``` -Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` by `baseapp`). In general, each module declares its own `KVStore` in the `multistore` to persist the subset of the state it defines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on [object-capabilities](../core/10-ocap.md). In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called `keepers` that can be passed to other modules to grant a pre-defined set of capabilities. +Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` by `baseapp`). In general, each module declares its own `KVStore` in the `multistore` to persist the subset of the state it defines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on [object-capabilities](../advanced/10-ocap.md). In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called `keepers` that can be passed to other modules to grant a pre-defined set of capabilities. Cosmos SDK modules are defined in the `x/` folder of the Cosmos SDK. Some core modules include: diff --git a/docs/docs/intro/_category_.json b/docs/docs/develop/intro/_category_.json similarity index 100% rename from docs/docs/intro/_category_.json rename to docs/docs/develop/intro/_category_.json diff --git a/docs/docs/packages/README.md b/docs/docs/packages/README.md deleted file mode 100644 index d7a115b263de..000000000000 --- a/docs/docs/packages/README.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_position: 0 ---- - -# Packages - -The Cosmos SDK is a collection of Go modules. This section provides documentation on various packages that can used when developing a Cosmos SDK chain. -It lists all standalone Go modules that are part of the Cosmos SDK. - -:::tip -For more information on SDK modules, see the [SDK Modules](https://docs.cosmos.network/main/modules) section. -For more information on SDK tooling, see the [Tooling](https://docs.cosmos.network/main/tooling) section. -::: - -## Core - -* [Core](https://pkg.go.dev/cosmossdk.io/core) - Core library defining SDK interfaces ([ADR-063](https://docs.cosmos.network/main/architecture/adr-063-core-module-api)) -* [API](https://pkg.go.dev/cosmossdk.io/api) - API library containing generated SDK Pulsar API -* [Store](https://pkg.go.dev/cosmossdk.io/store) - Implementation of the Cosmos SDK store - -## State Management - -* [Collections](./02-collections.md) - State management library -* [ORM](./03-orm.md) - State management library - -## Automation - -* [Depinject](./01-depinject.md) - Dependency injection framework -* [Client/v2](https://pkg.go.dev/cosmossdk.io/client/v2) - Library powering [AutoCLI](https://docs.cosmos.network/main/core/autocli) - -## Utilities - -* [Log](https://pkg.go.dev/cosmossdk.io/log) - Logging library -* [Errors](https://pkg.go.dev/cosmossdk.io/errors) - Error handling library -* [Math](https://pkg.go.dev/cosmossdk.io/math) - Math library for SDK arithmetic operations - -## Example - -* [SimApp](https://pkg.go.dev/cosmossdk.io/simapp) - SimApp is **the** sample Cosmos SDK chain. This package should not be imported in your application. diff --git a/docs/docs/tooling/README.md b/docs/docs/tooling/README.md deleted file mode 100644 index 27bc94e24f34..000000000000 --- a/docs/docs/tooling/README.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_position: 0 ---- - -# Tools - -This section provides documentation on various tooling maintained by the SDK team. -This includes tools for development, operating a node, and ease of use of a Cosmos SDK chain. - -## CLI Tools - -* [Cosmovisor](./01-cosmovisor.md) -* [Confix](./02-confix.md) -* [Hubl](./03-hubl.md) -* [Rosetta](https://docs.cosmos.network/main/run-node/rosetta) - -## Other Tools - -* [Protocol Buffers](./00-protobuf.md) diff --git a/docs/docs/run-node/00-keyring.md b/docs/docs/user/run-node/00-keyring.md similarity index 98% rename from docs/docs/run-node/00-keyring.md rename to docs/docs/user/run-node/00-keyring.md index 2cb15b115cfd..09d8b07422d2 100644 --- a/docs/docs/run-node/00-keyring.md +++ b/docs/docs/user/run-node/00-keyring.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Setting up the keyring :::note Synopsis -This document describes how to configure and use the keyring and its various backends for an [**application**](../basics/00-app-anatomy.md). +This document describes how to configure and use the keyring and its various backends for an [**application**](../../develop/beginner/00-app-anatomy.md). ::: The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage. diff --git a/docs/docs/run-node/01-run-node.md b/docs/docs/user/run-node/01-run-node.md similarity index 93% rename from docs/docs/run-node/01-run-node.md rename to docs/docs/user/run-node/01-run-node.md index 0c24117e3b39..fc539989b93e 100644 --- a/docs/docs/run-node/01-run-node.md +++ b/docs/docs/user/run-node/01-run-node.md @@ -10,7 +10,7 @@ Now that the application is ready and the keyring populated, it's time to see ho :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK Application](../../develop/beginner/00-app-anatomy.md) * [Setting up the keyring](./00-keyring.md) ::: @@ -87,7 +87,7 @@ simd genesis add-genesis-account $MY_VALIDATOR_ADDRESS 100000000000stake Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./00-keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is is a 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). For your own chain with its own staking denom, that token identifier should be used instead. -Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../intro/02-sdk-app-architecture.md#cometbft)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`: +Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../../develop/intro/02-sdk-app-architecture.md#cometbft)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`: ```bash # Create a gentx. diff --git a/docs/docs/run-node/02-interact-node.md b/docs/docs/user/run-node/02-interact-node.md similarity index 94% rename from docs/docs/run-node/02-interact-node.md rename to docs/docs/user/run-node/02-interact-node.md index 90977a61d6ef..48193504a603 100644 --- a/docs/docs/run-node/02-interact-node.md +++ b/docs/docs/user/run-node/02-interact-node.md @@ -10,7 +10,7 @@ There are multiple ways to interact with a node: using the CLI, using gRPC or us :::note Pre-requisite Readings -* [gRPC, REST and CometBFT Endpoints](../core/06-grpc_rest.md) +* [gRPC, REST and CometBFT Endpoints](../../develop/advanced/06-grpc_rest.md) * [Running a Node](./01-run-node.md) ::: @@ -54,7 +54,7 @@ You should see two delegations, the first one made from the `gentx`, and the sec ## Using gRPC -The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../core/06-grpc_rest.md). +The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../../develop/advanced/06-grpc_rest.md). Since the code generation library largely depends on your own tech stack, we will only present three alternatives: @@ -248,7 +248,7 @@ CosmJS documentation can be found at [https://cosmos.github.io/cosmjs](https://c ## Using the REST Endpoints -As described in the [gRPC guide](../core/06-grpc_rest.md), all gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters. +As described in the [gRPC guide](../../develop/advanced/06-grpc_rest.md), all gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters. Note that the REST endpoints are not enabled by default. To enable them, edit the `api` section of your `~/.simapp/config/app.toml` file: diff --git a/docs/docs/run-node/03-txs.md b/docs/docs/user/run-node/03-txs.md similarity index 99% rename from docs/docs/run-node/03-txs.md rename to docs/docs/user/run-node/03-txs.md index 16c1d966bf3e..faf1d8b65def 100644 --- a/docs/docs/run-node/03-txs.md +++ b/docs/docs/user/run-node/03-txs.md @@ -269,7 +269,7 @@ func sendTx() error { ### Broadcasting a Transaction -The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the CometBFT RPC is also posible. An overview of the differences between these methods is exposed [here](../core/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. +The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the CometBFT RPC is also posible. An overview of the differences between these methods is exposed [here](../../develop/advanced/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. ```go import ( diff --git a/docs/docs/run-node/05-run-testnet.md b/docs/docs/user/run-node/05-run-testnet.md similarity index 100% rename from docs/docs/run-node/05-run-testnet.md rename to docs/docs/user/run-node/05-run-testnet.md diff --git a/docs/docs/run-node/06-run-production.md b/docs/docs/user/run-node/06-run-production.md similarity index 100% rename from docs/docs/run-node/06-run-production.md rename to docs/docs/user/run-node/06-run-production.md diff --git a/docs/docs/run-node/_category_.json b/docs/docs/user/run-node/_category_.json similarity index 100% rename from docs/docs/run-node/_category_.json rename to docs/docs/user/run-node/_category_.json diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index d331c6c94339..19e52494a462 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -215,6 +215,24 @@ const config = { { fromExtensions: ["html"], toExtensions: ["html"], + createRedirects(existingPath) { + return [ + existingPath.replace('/core', '/develop/advanced'), + existingPath.replace('/basics', '/develop/beginner'), + existingPath.replace('/intro', '/develop/intro'), + existingPath.replace('/architecture', '/build/architecture/'), + existingPath.replace('/building-apps', '/build/building-apps'), + existingPath.replace('/building-modules', '/build/building-modules'), + existingPath.replace('/tooling', '/build/tooling'), + existingPath.replace('/migrations', '/build/migrations'), + existingPath.replace('/modules', '/build/modules'), + existingPath.replace('/rfc', '/build/rfc'), + existingPath.replace('/spec', '/build/spec'), + existingPath.replace('/tooling', '/build/tooling'), + existingPath.replace('/run-node', '/user/run-node'), + existingPath.replace('/validate', '/user/validate') + ]; + }, redirects: [ { from: ["/", "/master", "/v0.43", "/v0.44"], @@ -229,11 +247,11 @@ const config = { "/main/modules/auth/06_params", "/main/modules/auth/07_client", ], - to: "/main/modules/auth", + to: "/main/build/modules/auth", }, { from: "/main/modules/auth/05_vesting", - to: "/main/modules/auth/vesting", + to: "/main/build/modules/auth/vesting", }, { from: [ @@ -243,7 +261,7 @@ const config = { "/main/modules/authz/04_events", "/main/modules/authz/05_client", ], - to: "/main/modules/authz", + to: "/main/build/modules/authz", }, { from: [ @@ -253,7 +271,7 @@ const config = { "/main/modules/bank/05_params", "/main/modules/bank/06_client", ], - to: "/main/modules/bank", + to: "/main/build/modules/bank", }, { from: [ @@ -263,7 +281,7 @@ const config = { "/main/modules/crisis/04_params", "/main/modules/crisis/05_client", ], - to: "/main/modules/crisis", + to: "/main/build/modules/crisis", }, { from: [ @@ -276,7 +294,7 @@ const config = { "/main/modules/distribution/07_params", "/main/modules/distribution/08_client", ], - to: "/main/modules/distribution", + to: "/main/build/modules/distribution", }, { from: [ @@ -288,7 +306,7 @@ const config = { "/main/modules/evidence/06_begin_block", "/main/modules/evidence/07_client", ], - to: "/main/modules/evidence", + to: "/main/build/modules/evidence", }, { from: [ @@ -298,7 +316,7 @@ const config = { "/main/modules/feegrant/04_events", "/main/modules/feegrant/05_client", ], - to: "/main/modules/feegrant", + to: "/main/build/modules/feegrant", }, { from: [ @@ -311,7 +329,7 @@ const config = { "/main/modules/gov/07_client", "/main/modules/gov/08_metadata", ], - to: "/main/modules/gov", + to: "/main/build/modules/gov", }, { from: [ @@ -322,7 +340,7 @@ const config = { "/main/modules/group/05_client", "/main/modules/group/06_metadata", ], - to: "/main/modules/group/", + to: "/main/build/modules/group/", }, { from: [ @@ -333,7 +351,7 @@ const config = { "/main/modules/mint/05_events", "/main/modules/mint/06_client", ], - to: "/main/modules/mint/", + to: "/main/build/modules/mint/", }, { from: [ @@ -342,14 +360,14 @@ const config = { "/main/modules/nft/03_messages", "/main/modules/nft/04_events", ], - to: "/main/modules/nft/", + to: "/main/build/modules/nft/", }, { from: [ "/main/modules/params/01_keeper", "/main/modules/params/02_subspace", ], - to: "/main/modules/params/", + to: "/main/build/modules/params/", }, { from: [ @@ -363,7 +381,7 @@ const config = { "/main/modules/slashing/08_params", "/main/modules/slashing/09_client", ], - to: "/main/modules/slashing/", + to: "/main/build/modules/slashing/", }, { from: [ @@ -377,7 +395,7 @@ const config = { "/main/modules/staking/08_params", "/main/modules/staking/09_client", ], - to: "/main/modules/staking/", + to: "/main/build/modules/staking/", }, { from: [ @@ -386,35 +404,35 @@ const config = { "/main/modules/upgrade/03_events", "/main/modules/upgrade/04_client", ], - to: "/main/modules/upgrade/", + to: "/main/build/modules/upgrade/", }, { from: ["/main/modules/capability", "/main/ecosystem"], - to: "/main/modules", + to: "/main/build/modules/auth", }, { from: ["/main/spec/circuit-breaker"], - to: "/main/modules/circuit", + to: "/main/build/modules/circuit", }, { from: ["/main/spec/reserve-pool"], - to: "/main/modules/distribution", + to: "/main/build/modules/distribution", }, { from: ["/main/run-node/cosmovisor"], - to: "/main/tooling/cosmovisor", + to: "/main/build/tooling/cosmovisor", }, { from: ["/main/migrations/pre-upgrade"], - to: "/main/building-apps/app-upgrade", + to: "/main/build/building-apps/app-upgrade", }, { from: ["/main/tooling/depinject"], - to: "/main/packages/depinject", + to: "/main/build/packages/depinject", }, { from: ["/main/building-modules/autocli"], - to: "/main/core/autocli", + to: "/main/develop/advanced/autocli", }, ], }, diff --git a/docs/post.sh b/docs/post.sh index 816a7779bf7a..0e9b23bb67b6 100755 --- a/docs/post.sh +++ b/docs/post.sh @@ -1,16 +1,17 @@ #!/usr/bin/env bash -find docs/modules ! -name '_category_.json' -type f -exec rm -rf {} + -rm -rf docs/tooling/01-cosmovisor.md -rm -rf docs/tooling/02-confix.md -rm -rf docs/tooling/03-hubl.md -rm -rf docs/packages/01-depinject.md -rm -rf docs/packages/02-collections.md -rm -rf docs/packages/03-orm.md -rm -rf docs/core/17-autocli.md -rm -rf docs/run-node/04-rosetta.md -rm -rf docs/architecture -rm -rf docs/spec -rm -rf docs/rfc -rm -rf docs/migrations/02-upgrading.md +find docs/build/modules ! -name '_category_.json' -type f -exec rm -rf {} + +rm -rf docs/build/tooling/01-cosmovisor.md +rm -rf docs/build/tooling/02-confix.md +rm -rf docs/build/tooling/03-hubl.md +rm -rf docs/build/packages/01-depinject.md +rm -rf docs/build/packages/02-collections.md +rm -rf docs/build/packages/03-orm.md +rm -rf docs/develop/advaced-concepts/17-autocli.md +rm -rf docs/user/run-node/04-rosetta.md +rm -rf docs/build/architecture +rm -rf docs/build/spec +rm -rf docs/build/rfc +rm -rf docs/develop/advanced/17-autocli.md +rm -rf docs/build/migrations/02-upgrading.md rm -rf versioned_docs versioned_sidebars versions.json \ No newline at end of file diff --git a/docs/pre.sh b/docs/pre.sh index f45982651a42..93939e419a84 100755 --- a/docs/pre.sh +++ b/docs/pre.sh @@ -3,7 +3,7 @@ ## Create modules pages for D in ../x/*; do if [ -d "${D}" ]; then - MODDOC=docs/modules/$(echo $D | awk -F/ '{print $NF}') + MODDOC=docs/build/modules/$(echo $D | awk -F/ '{print $NF}') rm -rf $MODDOC mkdir -p $MODDOC && cp -r $D/README.md "$_" fi @@ -11,32 +11,32 @@ done ## Vesting is a submodule of auth, but we still want to display it in docs ## TODO to be removed in https://github.com/cosmos/cosmos-sdk/issues/9958 -cp ../x/auth/vesting/README.md ./docs/modules/auth/1-vesting.md -cp ../x/auth/tx/README.md ./docs/modules/auth/2-tx.md +cp ../x/auth/vesting/README.md ./docs/build/modules/auth/1-vesting.md +cp ../x/auth/tx/README.md ./docs/build/modules/auth/2-tx.md ## Add modules page list -cat ../x/README.md | sed 's/\.\.\/docs\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./docs/modules/README.md +cat ../x/README.md | sed 's/\.\.\/docs\/build\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./docs/modules/README.md ## Add tooling documentation -cp ../tools/cosmovisor/README.md ./docs/tooling/01-cosmovisor.md -cp ../tools/confix/README.md ./docs/tooling/02-confix.md -cp ../tools/hubl/README.md ./docs/tooling/03-hubl.md -wget -O docs/run-node/04-rosetta.md https://raw.githubusercontent.com/cosmos/rosetta/main/README.md +cp ../tools/cosmovisor/README.md ./docs/build/tooling/01-cosmovisor.md +cp ../tools/confix/README.md ./docs/build/tooling/02-confix.md +cp ../tools/hubl/README.md ./docs/build/tooling/03-hubl.md +wget -O docs/user/run-node/04-rosetta.md https://raw.githubusercontent.com/cosmos/rosetta/main/README.md ## Add package documentation -cp ../client/v2/README.md ./docs/core/17-autocli.md -cp ../depinject/README.md ./docs/packages/01-depinject.md -cp ../collections/README.md ./docs/packages/02-collections.md -cp ../orm/README.md ./docs/packages/03-orm.md +cp ../client/v2/README.md ./docs/develop/advanced/17-autocli.md +cp ../depinject/README.md ./docs/build/packages/01-depinject.md +cp ../collections/README.md ./docs/build/packages/02-collections.md +cp ../orm/README.md ./docs/build/packages/03-orm.md ## Add architecture documentation -cp -r ./architecture ./docs +cp -r ./architecture ./docs/build ## Add spec documentation -cp -r ./spec ./docs +cp -r ./spec ./docs/build ## Add rfc documentation -cp -r ./rfc ./docs +cp -r ./rfc ./docs/build/rfc ## Add SDK migration documentation -cp -r ../UPGRADING.md ./docs/migrations/02-upgrading.md \ No newline at end of file +cp -r ../UPGRADING.md ./docs/build/migrations/02-upgrading.md \ No newline at end of file diff --git a/docs/rfc/README.md b/docs/rfc/README.md index 24887ac3f668..0c75501e1623 100644 --- a/docs/rfc/README.md +++ b/docs/rfc/README.md @@ -13,7 +13,7 @@ discussion that might otherwise only be recorded in an ad-hoc way (for example, via gists or Google docs) that are difficult to discover for someone after the fact. An RFC _may_ give rise to more specific architectural _decisions_ for the Cosmos SDK, but those decisions must be recorded separately in -[Architecture Decision Records (ADR)](../architecture/). +[Architecture Decision Records (ADR)](../architecture). As a rule of thumb, if you can articulate a specific question that needs to be answered, write an ADR. If you need to explore the topic and get input from @@ -36,3 +36,7 @@ sections. ## Table of Contents +<<<<<<< HEAD +======= +* [RFC-002: Zero Copy Encoding](./rfc-002-zero-copy-encoding.md) +>>>>>>> f198ea944 (refactor: docs path updates (#17459)) diff --git a/docs/rfc/_category_.json b/docs/rfc/_category_.json deleted file mode 100644 index 40fac9822465..000000000000 --- a/docs/rfc/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "RFCs", - "position": 12, - "link": null -} \ No newline at end of file From 0428c483397c2953aacb4cf4aff54550a93db0b3 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Tue, 5 Sep 2023 10:31:40 +0200 Subject: [PATCH 2/4] chore: correct api docs (backport #17622) (#17625) Co-authored-by: Marko --- docs/docs/core/06-grpc_rest.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docs/core/06-grpc_rest.md b/docs/docs/core/06-grpc_rest.md index f78bfa62b346..7f5923ca8922 100644 --- a/docs/docs/core/06-grpc_rest.md +++ b/docs/docs/core/06-grpc_rest.md @@ -20,6 +20,10 @@ Each node exposes the following endpoints for users to interact with a node, eac The node also exposes some other endpoints, such as the CometBFT P2P endpoint, or the [Prometheus endpoint](https://docs.cometbft.com/v0.37/core/metrics), which are not directly related to the Cosmos SDK. Please refer to the [CometBFT documentation](https://docs.cometbft.com/v0.37/core/configuration) for more information about these endpoints. ::: +:::note +All endpoints are defaulted to localhost and must be modified to be exposed to the public internet. +::: + ## gRPC Server In the Cosmos SDK, Protobuf is the main [encoding](./encoding) library. 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. @@ -71,7 +75,7 @@ For application developers, gRPC-gateway REST routes needs to be wired up to the A [Swagger](https://swagger.io/) (or OpenAPIv2) specification file is exposed under the `/swagger` route on the API server. Swagger is an open specification describing the API endpoints a server serves, including description, input arguments, return types and much more about each endpoint. -Enabling the `/swagger` endpoint is configurable inside `~/.simapp/config/app.toml` via the `api.swagger` field, which is set to true by default. +Enabling the `/swagger` endpoint is configurable inside `~/.simapp/config/app.toml` via the `api.swagger` field, which is set to false by default. 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.50.0-alpha.0/scripts/protoc-swagger-gen.sh) is a good place to start. From 92b1dbcd23d59a45317ba2ab60889593946cb78e Mon Sep 17 00:00:00 2001 From: samricotta <37125168+samricotta@users.noreply.github.com> Date: Tue, 5 Sep 2023 10:56:01 +0300 Subject: [PATCH 3/4] refactor: docs path updates (#17459) Co-authored-by: Julien Robert Co-authored-by: Marko Co-authored-by: marbar3778 (cherry picked from commit f198ea9445fe1c3a6355eabf90242f26382550a4) # Conflicts: # .github/workflows/deploy-docs.yml # UPGRADING.md # docs/docs/build/building-modules/01-module-manager.md # docs/docs/build/building-modules/06-keeper.md # docs/docs/develop/advanced/00-baseapp.md # docs/rfc/README.md --- .github/workflows/deploy-docs.yml | 47 ++ UPGRADING.md | 413 ++++++++++++++++++ docs/.gitignore | 8 +- .../adr-033-protobuf-inter-module-comm.md | 2 +- docs/architecture/adr-063-core-module-api.md | 2 +- docs/docs/{README.md => Introduction.md} | 14 +- .../{ => build}/building-apps/00-app-go.md | 0 .../{ => build}/building-apps/01-app-go-v2.md | 0 .../building-apps/02-app-mempool.md | 2 +- .../building-apps/03-app-upgrade.md | 0 .../building-apps/04-vote-extensions.md | 0 .../{ => build}/building-apps/_category_.json | 0 .../{ => build}/building-modules/01-intro.md | 14 +- .../building-modules/01-module-manager.md | 39 +- .../02-messages-and-queries.md | 14 +- .../building-modules/03-msg-services.md | 8 +- .../building-modules/04-query-services.md | 2 +- .../05-beginblock-endblock.md | 6 +- .../{ => build}/building-modules/06-keeper.md | 14 +- .../building-modules/07-invariants.md | 2 +- .../building-modules/08-genesis.md | 6 +- .../building-modules/09-module-interfaces.md | 6 +- .../building-modules/11-structure.md | 0 .../{ => build}/building-modules/12-errors.md | 0 .../building-modules/13-upgrade.md | 4 +- .../building-modules/14-simulator.md | 4 +- .../building-modules/15-depinject.md | 0 .../building-modules/16-testing.md | 0 .../building-modules/_category_.json | 0 docs/docs/{ => build}/migrations/01-intro.md | 0 .../{ => build}/migrations/_category_.json | 0 docs/docs/{ => build}/modules/_category_.json | 0 .../docs/{ => build}/packages/_category_.json | 0 docs/docs/{ => build}/tooling/_category_.json | 0 .../{core => develop/advanced}/00-baseapp.md | 49 ++- .../advanced}/01-transactions.md | 28 +- .../{core => develop/advanced}/02-context.md | 10 +- .../{core => develop/advanced}/03-node.md | 8 +- .../{core => develop/advanced}/04-store.md | 10 +- .../{core => develop/advanced}/05-encoding.md | 22 +- .../advanced}/06-grpc_rest.md | 6 +- .../docs/{core => develop/advanced}/07-cli.md | 26 +- .../{core => develop/advanced}/08-events.md | 14 +- .../advanced}/09-telemetry.md | 0 .../{core => develop/advanced}/10-ocap.md | 0 .../advanced}/11-runtx_middleware.md | 2 +- .../advanced}/12-simulation.md | 4 +- .../advanced}/13-proto-docs.md | 0 .../{core => develop/advanced}/14-tips.md | 0 .../{core => develop/advanced}/15-upgrade.md | 4 +- .../{core => develop/advanced}/16-config.md | 0 .../advanced}/_category_.json | 0 .../advanced}/baseapp_state-begin_block.png | Bin .../advanced}/baseapp_state-checktx.png | Bin .../advanced}/baseapp_state-commit.png | Bin .../advanced}/baseapp_state-deliver_tx.png | Bin .../advanced}/baseapp_state-initchain.png | Bin .../baseapp_state-prepareproposal.png | Bin .../baseapp_state-processproposal.png | Bin .../advanced}/baseapp_state.png | Bin .../beginner}/00-app-anatomy.md | 60 +-- .../beginner}/01-tx-lifecycle.md | 38 +- .../beginner}/02-query-lifecycle.md | 30 +- .../beginner}/03-accounts.md | 4 +- .../beginner}/04-gas-fees.md | 16 +- .../beginner}/_category_.json | 0 docs/docs/{ => develop}/intro/00-overview.md | 2 +- .../intro/01-why-app-specific.md | 0 .../intro/02-sdk-app-architecture.md | 4 +- .../docs/{ => develop}/intro/03-sdk-design.md | 12 +- docs/docs/{ => develop}/intro/_category_.json | 0 docs/docs/packages/README.md | 39 -- docs/docs/tooling/README.md | 19 - docs/docs/{ => user}/run-node/00-keyring.md | 2 +- docs/docs/{ => user}/run-node/01-run-node.md | 4 +- .../{ => user}/run-node/02-interact-node.md | 6 +- docs/docs/{ => user}/run-node/03-txs.md | 2 +- .../{ => user}/run-node/05-run-testnet.md | 0 .../{ => user}/run-node/06-run-production.md | 0 docs/docs/{ => user}/run-node/_category_.json | 0 docs/docusaurus.config.js | 64 ++- docs/post.sh | 27 +- docs/pre.sh | 32 +- docs/rfc/README.md | 6 +- docs/rfc/_category_.json | 5 - 85 files changed, 802 insertions(+), 360 deletions(-) create mode 100644 .github/workflows/deploy-docs.yml rename docs/docs/{README.md => Introduction.md} (59%) rename docs/docs/{ => build}/building-apps/00-app-go.md (100%) rename docs/docs/{ => build}/building-apps/01-app-go-v2.md (100%) rename docs/docs/{ => build}/building-apps/02-app-mempool.md (99%) rename docs/docs/{ => build}/building-apps/03-app-upgrade.md (100%) rename docs/docs/{ => build}/building-apps/04-vote-extensions.md (100%) rename docs/docs/{ => build}/building-apps/_category_.json (100%) rename docs/docs/{ => build}/building-modules/01-intro.md (86%) rename docs/docs/{ => build}/building-modules/01-module-manager.md (77%) rename docs/docs/{ => build}/building-modules/02-messages-and-queries.md (86%) rename docs/docs/{ => build}/building-modules/03-msg-services.md (91%) rename docs/docs/{ => build}/building-modules/04-query-services.md (98%) rename docs/docs/{ => build}/building-modules/05-beginblock-endblock.md (87%) rename docs/docs/{ => build}/building-modules/06-keeper.md (70%) rename docs/docs/{ => build}/building-modules/07-invariants.md (97%) rename docs/docs/{ => build}/building-modules/08-genesis.md (81%) rename docs/docs/{ => build}/building-modules/09-module-interfaces.md (93%) rename docs/docs/{ => build}/building-modules/11-structure.md (100%) rename docs/docs/{ => build}/building-modules/12-errors.md (100%) rename docs/docs/{ => build}/building-modules/13-upgrade.md (90%) rename docs/docs/{ => build}/building-modules/14-simulator.md (97%) rename docs/docs/{ => build}/building-modules/15-depinject.md (100%) rename docs/docs/{ => build}/building-modules/16-testing.md (100%) rename docs/docs/{ => build}/building-modules/_category_.json (100%) rename docs/docs/{ => build}/migrations/01-intro.md (100%) rename docs/docs/{ => build}/migrations/_category_.json (100%) rename docs/docs/{ => build}/modules/_category_.json (100%) rename docs/docs/{ => build}/packages/_category_.json (100%) rename docs/docs/{ => build}/tooling/_category_.json (100%) rename docs/docs/{core => develop/advanced}/00-baseapp.md (88%) rename docs/docs/{core => develop/advanced}/01-transactions.md (78%) rename docs/docs/{core => develop/advanced}/02-context.md (85%) rename docs/docs/{core => develop/advanced}/03-node.md (94%) rename docs/docs/{core => develop/advanced}/04-store.md (94%) rename docs/docs/{core => develop/advanced}/05-encoding.md (91%) rename docs/docs/{core => develop/advanced}/06-grpc_rest.md (92%) rename docs/docs/{core => develop/advanced}/07-cli.md (80%) rename docs/docs/{core => develop/advanced}/08-events.md (91%) rename docs/docs/{core => develop/advanced}/09-telemetry.md (100%) rename docs/docs/{core => develop/advanced}/10-ocap.md (100%) rename docs/docs/{core => develop/advanced}/11-runtx_middleware.md (89%) rename docs/docs/{core => develop/advanced}/12-simulation.md (97%) rename docs/docs/{core => develop/advanced}/13-proto-docs.md (100%) rename docs/docs/{core => develop/advanced}/14-tips.md (100%) rename docs/docs/{core => develop/advanced}/15-upgrade.md (97%) rename docs/docs/{core => develop/advanced}/16-config.md (100%) rename docs/docs/{core => develop/advanced}/_category_.json (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-begin_block.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-checktx.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-commit.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-deliver_tx.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-initchain.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-prepareproposal.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state-processproposal.png (100%) rename docs/docs/{core => develop/advanced}/baseapp_state.png (100%) rename docs/docs/{basics => develop/beginner}/00-app-anatomy.md (65%) rename docs/docs/{basics => develop/beginner}/01-tx-lifecycle.md (82%) rename docs/docs/{basics => develop/beginner}/02-query-lifecycle.md (67%) rename docs/docs/{basics => develop/beginner}/03-accounts.md (95%) rename docs/docs/{basics => develop/beginner}/04-gas-fees.md (70%) rename docs/docs/{basics => develop/beginner}/_category_.json (100%) rename docs/docs/{ => develop}/intro/00-overview.md (86%) rename docs/docs/{ => develop}/intro/01-why-app-specific.md (100%) rename docs/docs/{ => develop}/intro/02-sdk-app-architecture.md (91%) rename docs/docs/{ => develop}/intro/03-sdk-design.md (85%) rename docs/docs/{ => develop}/intro/_category_.json (100%) delete mode 100644 docs/docs/packages/README.md delete mode 100644 docs/docs/tooling/README.md rename docs/docs/{ => user}/run-node/00-keyring.md (98%) rename docs/docs/{ => user}/run-node/01-run-node.md (93%) rename docs/docs/{ => user}/run-node/02-interact-node.md (94%) rename docs/docs/{ => user}/run-node/03-txs.md (99%) rename docs/docs/{ => user}/run-node/05-run-testnet.md (100%) rename docs/docs/{ => user}/run-node/06-run-production.md (100%) rename docs/docs/{ => user}/run-node/_category_.json (100%) delete mode 100644 docs/rfc/_category_.json diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 000000000000..da885a75ebe2 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,47 @@ +name: Deploy docs +# This job builds and deploys documenation to github pages. +# It runs on every push to main with a change in the docs folder. +on: + workflow_dispatch: + push: + branches: + - main + - "release/**" + paths: + - "docs/**" + - "x/**/*.md" + - .github/workflows/deploy-docs.yml + +permissions: + contents: read + +jobs: + build-and-deploy: + permissions: + contents: write # for JamesIves/github-pages-deploy-action to push changes in repo + runs-on: ubuntu-latest + steps: + - name: Checkout πŸ›ŽοΈ + uses: actions/checkout@v4 + with: + persist-credentials: false + fetch-depth: 0 + path: "." + + - name: Setup Node.js πŸ”§ + uses: actions/setup-node@v3 + with: + node-version: "16.x" + + # npm install npm should be removed when https://github.com/npm/cli/issues/4942 is fixed + - name: Build πŸ”§ + run: | + npm install -g npm@8.5.5 + make build-docs + + # - name: Deploy πŸš€ + # uses: JamesIves/github-pages-deploy-action@v4.4.3 + # with: + # branch: gh-pages + # folder: ~/output + # single-commit: true diff --git a/UPGRADING.md b/UPGRADING.md index 67ce37d03fe1..30999296bef7 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -369,4 +369,417 @@ All the upgrade imports are now renamed to use `cosmossdk.io/x/upgrade` instead Rosetta has moved to it's own [repo](https://github.com/cosmos/rosetta) and not imported by the Cosmos SDK SimApp by default. Any user who is interested on using the tool can connect it standalone to any node without the need to add it as part of the node binary. +<<<<<<< HEAD The rosetta tool also allows multi chain connections. +======= +The rosetta tool also allows multi chain connections. + +## [v0.47.x](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.47.0) + +### Migration to CometBFT (Part 1) + +The Cosmos SDK has migrated to CometBFT, as its default consensus engine. +CometBFT is an implementation of the Tendermint consensus algorithm, and the successor of Tendermint Core. +Due to the import changes, this is a breaking change. Chains need to remove **entirely** their imports of Tendermint Core in their codebase, from direct and indirects imports in their `go.mod`. + +* Replace `github.com/tendermint/tendermint` by `github.com/cometbft/cometbft` +* Replace `github.com/tendermint/tm-db` by `github.com/cometbft/cometbft-db` +* Verify `github.com/tendermint/tendermint` is not an indirect or direct dependency +* Run `make proto-gen` + +Other than that, the migration should be seamless. +On the SDK side, clean-up of variables, functions to reflect the new name will only happen from v0.50 (part 2). + +Note: It is possible that these steps must first be performed by your dependencies before you can perform them on your own codebase. + +### Simulation + +Remove `RandomizedParams` from `AppModuleSimulation` interface. Previously, it used to generate random parameter changes during simulations, however, it does so through ParamChangeProposal which is now legacy. Since all modules were migrated, we can now safely remove this from `AppModuleSimulation` interface. + +Moreover, to support the `MsgUpdateParams` governance proposals for each modules, `AppModuleSimulation` now defines a `AppModule.ProposalMsgs` method in addition to `AppModule.ProposalContents`. That method defines the messages that can be used to submit a proposal and that should be tested in simulation. + +When a module has no proposal messages or proposal content to be tested by simulation, the `AppModule.ProposalMsgs` and `AppModule.ProposalContents` methods can be deleted. + +### gRPC + +A new gRPC service, `proto/cosmos/base/node/v1beta1/query.proto`, has been introduced +which exposes various operator configuration. App developers should be sure to +register the service with the gRPC-gateway service via +`nodeservice.RegisterGRPCGatewayRoutes` in their application construction, which +is typically found in `RegisterAPIRoutes`. + +### AppModule Interface + +Support for the `AppModule` `Querier`, `Route` and `LegacyQuerier` methods has been entirely removed from the `AppModule` +interface. This removes and fully deprecates all legacy queriers. All modules no longer support the REST API previously +known as the LCD, and the `sdk.Msg#Route` method won't be used anymore. + +Most other existing `AppModule` methods have been moved to extension interfaces in preparation for the migration +to the `cosmossdk.io/core/appmodule` API in the next release. Most `AppModule` implementations should not be broken +by this change. + +### SimApp + +The `simapp` package **should not be imported in your own app**. Instead, you should import the `runtime.AppI` interface, that defines an `App`, and use the [`simtestutil` package](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/testutil/sims) for application testing. + +#### App Wiring + +SimApp's `app_v2.go` is using [App Wiring](https://docs.cosmos.network/main/building-apps/app-go-v2), the dependency injection framework of the Cosmos SDK. +This means that modules are injected directly into SimApp thanks to a [configuration file](https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/simapp/app_config.go). +The previous behavior, without the dependency injection framework, is still present in [`app.go`](https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/simapp/app.go) and is not going anywhere. + +If you are using a `app.go` without dependency injection, add the following lines to your `app.go` in order to provide newer gRPC services: + +```go +autocliv1.RegisterQueryServer(app.GRPCQueryRouter(), runtimeservices.NewAutoCLIQueryService(app.ModuleManager.Modules)) + +reflectionSvc, err := runtimeservices.NewReflectionService() +if err != nil { + panic(err) +} +reflectionv1.RegisterReflectionServiceServer(app.GRPCQueryRouter(), reflectionSvc) +``` + +#### Constructor + +The constructor, `NewSimApp` has been simplified: + +* `NewSimApp` does not take encoding parameters (`encodingConfig`) as input, instead the encoding parameters are injected (when using app wiring), or directly created in the constructor. Instead, we can instantiate `SimApp` for getting the encoding configuration. +* `NewSimApp` now uses `AppOptions` for getting the home path (`homePath`) and the invariant checks period (`invCheckPeriod`). These were unnecessary given as arguments as they were already present in the `AppOptions`. + +#### Encoding + +`simapp.MakeTestEncodingConfig()` was deprecated and has been removed. Instead you can use the `TestEncodingConfig` from the `types/module/testutil` package. +This means you can replace your usage of `simapp.MakeTestEncodingConfig` in tests to `moduletestutil.MakeTestEncodingConfig`, which takes a series of relevant `AppModuleBasic` as input (the module being tested and any potential dependencies). + +#### Export + +`ExportAppStateAndValidators` takes an extra argument, `modulesToExport`, which is a list of module names to export. +That argument should be passed to the module maanager `ExportGenesisFromModules` method. + +#### Replaces + +The `GoLevelDB` version must pinned to `v1.0.1-0.20210819022825-2ae1ddf74ef7` in the application, following versions might cause unexpected behavior. +This can be done adding `replace github.com/syndtr/goleveldb => github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7` to the `go.mod` file. + +* [issue #14949 on cosmos-sdk](https://github.com/cosmos/cosmos-sdk/issues/14949) +* [issue #25413 on go-ethereum](https://github.com/ethereum/go-ethereum/pull/25413) + +### Protobuf + +The SDK has migrated from `gogo/protobuf` (which is currently unmaintained), to our own maintained fork, [`cosmos/gogoproto`](https://github.com/cosmos/gogoproto). + +This means you should replace all imports of `github.com/gogo/protobuf` to `github.com/cosmos/gogoproto`. +This allows you to remove the replace directive `replace github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1` from your `go.mod` file. + +Please use the `ghcr.io/cosmos/proto-builder` image (version >= `0.11.5`) for generating protobuf files. + +See which buf commit for `cosmos/cosmos-sdk` to pin in your `buf.yaml` file [here](https://github.com/cosmos/cosmos-sdk/blob/main/proto/README.md). + +#### Gogoproto Import Paths + +The SDK made a [patch fix](https://github.com/cosmos/gogoproto/pull/32) on its gogoproto repository to require that each proto file's package name matches its OS import path (relatively to a protobuf root import path, usually the root `proto/` folder, set by the `protoc -I` flag). + +For example, assuming you put all your proto files in subfolders inside your root `proto/` folder, then a proto file with package name `myapp.mymodule.v1` should be found in the `proto/myapp/mymodule/v1/` folder. If it is in another folder, the proto generation command will throw an error. + +If you are using a custom folder structure for your proto files, please reorganize them so that their OS path matches their proto package name. + +This is to allow the proto FileDescriptSets to be correctly registered, and this standardized OS import paths allows [Hubl](https://github.com/cosmos/cosmos-sdk/tree/main/tools/hubl) to reflectively talk to any chain. + +#### `{accepts,implements}_interface` proto annotations + +The SDK is normalizing the strings inside the Protobuf `accepts_interface` and `implements_interface` annotations. We require them to be fully-scoped names. They will soon be used by code generators like Pulsar and Telescope to match which messages can or cannot be packed inside `Any`s. + +Here are the following replacements that you need to perform on your proto files: + +```diff +- "Content" ++ "cosmos.gov.v1beta1.Content" +- "Authorization" ++ "cosmos.authz.v1beta1.Authorization" +- "sdk.Msg" ++ "cosmos.base.v1beta1.Msg" +- "AccountI" ++ "cosmos.auth.v1beta1.AccountI" +- "ModuleAccountI" ++ "cosmos.auth.v1beta1.ModuleAccountI" +- "FeeAllowanceI" ++ "cosmos.feegrant.v1beta1.FeeAllowanceI" +``` + +Please also check that in your own app's proto files that there are no single-word names for those two proto annotations. If so, then replace them with fully-qualified names, even though those names don't actually resolve to an actual protobuf entity. + +For more information, see the [encoding guide](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/develop/advanced/05-encoding.md). + +### Transactions + +#### Broadcast Mode + +Broadcast mode `block` was deprecated and has been removed. Please use `sync` mode +instead. When upgrading your tests from `block` to `sync` and checking for a +transaction code, you need to query the transaction first (with its hash) to get +the correct code. + +### Modules + +#### `**all**` + +`EventTypeMessage` events, with `sdk.AttributeKeyModule` and `sdk.AttributeKeySender` are now emitted directly at message excecution (in `baseapp`). +This means that the following boilerplate should be removed from all your custom modules: + +```go +ctx.EventManager().EmitEvent( + sdk.NewEvent( + sdk.EventTypeMessage, + sdk.NewAttribute(sdk.AttributeKeyModule, types.AttributeValueCategory), + sdk.NewAttribute(sdk.AttributeKeySender, `signer/sender`), + ), +) +``` + +The module name is assumed by `baseapp` to be the second element of the message route: `"cosmos.bank.v1beta1.MsgSend" -> "bank"`. +In case a module does not follow the standard message path, (e.g. IBC), it is advised to keep emitting the module name event. +`Baseapp` only emits that event if the module has not already done so. + +#### `x/params` + +The `params` module was deprecated since v0.46. The Cosmos SDK has migrated away from `x/params` for its own modules. +Cosmos SDK modules now store their parameters directly in its repective modules. +The `params` module will be removed in `v0.50`, as mentioned [in v0.46 release](https://github.com/cosmos/cosmos-sdk/blob/v0.46.1/UPGRADING.md#xparams). It is strongly encouraged to migrate away from `x/params` before `v0.50`. + +When performing a chain migration, the params table must be initizalied manually. This was done in the modules keepers in previous versions. +Have a look at `simapp.RegisterUpgradeHandlers()` for an example. + +#### `x/crisis` + +With the migrations of all modules away from `x/params`, the crisis module now has a store. +The store must be created during a chain upgrade to v0.47.x. + +```go +storetypes.StoreUpgrades{ + Added: []string{ + crisistypes.ModuleName, + }, +} +``` + +#### `x/gov` + +##### Minimum Proposal Deposit At Time of Submission + +The `gov` module has been updated to support a minimum proposal deposit at submission time. It is determined by a new +parameter called `MinInitialDepositRatio`. When multiplied by the existing `MinDeposit` parameter, it produces +the necessary proportion of coins needed at the proposal submission time. The motivation for this change is to prevent proposal spamming. + +By default, the new `MinInitialDepositRatio` parameter is set to zero during migration. The value of zero signifies that this +feature is disabled. If chains wish to utilize the minimum proposal deposits at time of submission, the migration logic needs to be +modified to set the new parameter to the desired value. + +##### New `Proposal.Proposer` field + +The `Proposal` proto has been updated with proposer field. For proposal state migraton developers can call `v4.AddProposerAddressToProposal` in their upgrade handler to update all existing proposal and make them compatible and **this migration is optional**. + +```go +import ( + sdk "github.com/cosmos/cosmos-sdk/types" + "github.com/cosmos/cosmos-sdk/types/module" + v4 "github.com/cosmos/cosmos-sdk/x/gov/migrations/v4" + upgradetypes "github.com/cosmos/cosmos-sdk/x/upgrade/types" +) + +func (app SimApp) RegisterUpgradeHandlers() { + app.UpgradeKeeper.SetUpgradeHandler(UpgradeName, + func(ctx sdk.Context, plan upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) { + // this migration is optional + // add proposal ids with proposers which are active (deposit or voting period) + proposals := make(map[uint64]string) + proposals[1] = "cosmos1luyncewxk4lm24k6gqy8y5dxkj0klr4tu0lmnj" ... + v4.AddProposerAddressToProposal(ctx, sdk.NewKVStoreKey(v4.ModuleName), app.appCodec, proposals) + return app.ModuleManager.RunMigrations(ctx, app.Configurator(), fromVM) + }) +} + +``` + +#### `x/consensus` + +Introducing a new `x/consensus` module to handle managing Tendermint consensus +parameters. For migration it is required to call a specific migration to migrate +existing parameters from the deprecated `x/params` to `x/consensus` module. App +developers should ensure to call `baseapp.MigrateParams` in their upgrade handler. + +Example: + +```go +func (app SimApp) RegisterUpgradeHandlers() { + ----> baseAppLegacySS := app.ParamsKeeper.Subspace(baseapp.Paramspace).WithKeyTable(paramstypes.ConsensusParamsKeyTable()) <---- + + app.UpgradeKeeper.SetUpgradeHandler( + UpgradeName, + func(ctx sdk.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) { + // Migrate Tendermint consensus parameters from x/params module to a + // dedicated x/consensus module. + ----> baseapp.MigrateParams(ctx, baseAppLegacySS, &app.ConsensusParamsKeeper) <---- + + // ... + + return app.ModuleManager.RunMigrations(ctx, app.Configurator(), fromVM) + }, + ) + + // ... +} +``` + +The `x/params` module should still be imported in your app.go in order to handle this migration. + +Because the `x/consensus` module is a new module, its store must be added while upgrading to v0.47.x: + +```go +storetypes.StoreUpgrades{ + Added: []string{ + consensustypes.ModuleName, + }, +} +``` + +##### `app.go` changes + +When using an `app.go` without App Wiring, the following changes are required: + +```diff +- bApp.SetParamStore(app.ParamsKeeper.Subspace(baseapp.Paramspace).WithKeyTable(paramstypes.ConsensusParamsKeyTable())) ++ app.ConsensusParamsKeeper = consensusparamkeeper.NewKeeper(appCodec, keys[consensusparamstypes.StoreKey], authtypes.NewModuleAddress(govtypes.ModuleName).String()) ++ bApp.SetParamStore(&app.ConsensusParamsKeeper) +``` + +When using App Wiring, the paramater store is automatically set for you. + +#### `x/nft` + +The SDK does not validate anymore the `classID` and `nftID` of an NFT, for extra flexibility in your NFT implementation. +This means chain developers need to validate the `classID` and `nftID` of an NFT. + +### Ledger + +Ledger support has been generalized to enable use of different apps and keytypes that use `secp256k1`. The Ledger interface remains the same, but it can now be provided through the Keyring `Options`, allowing higher-level chains to connect to different Ledger apps or use custom implementations. In addition, higher-level chains can provide custom key implementations around the Ledger public key, to enable greater flexibility with address generation and signing. + +This is not a breaking change, as all values will default to use the standard Cosmos app implementation unless specified otherwise. + +## [v0.46.x](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.46.0) + +### Go API Changes + +The `replace google.golang.org/grpc` directive can be removed from the `go.mod`, it is no more required to block the version. + +A few packages that were deprecated in the previous version are now removed. + +For instance, the REST API, deprecated in v0.45, is now removed. If you have not migrated yet, please follow the [instructions](https://docs.cosmos.network/v0.45/migrations/rest.html). + +To improve clarity of the API, some renaming and improvements has been done: + +| Package | Previous | Current | +| --------- | ---------------------------------- | ------------------------------------ | +| `simapp` | `encodingConfig.Marshaler` | `encodingConfig.Codec` | +| `simapp` | `FundAccount`, `FundModuleAccount` | Functions moved to `x/bank/testutil` | +| `types` | `AccAddressFromHex` | `AccAddressFromHexUnsafe` | +| `x/auth` | `MempoolFeeDecorator` | Use `DeductFeeDecorator` instead | +| `x/bank` | `AddressFromBalancesStore` | `AddressAndDenomFromBalancesStore` | +| `x/gov` | `keeper.DeleteDeposits` | `keeper.DeleteAndBurnDeposits` | +| `x/gov` | `keeper.RefundDeposits` | `keeper.RefundAndDeleteDeposits` | +| `x/{mod}` | package `legacy` | package `migrations` | + +For the exhaustive list of API renaming, please refer to the [CHANGELOG](https://github.com/cosmos/cosmos-sdk/blob/main/CHANGELOG.md). + +#### new packages + +Additionally, new packages have been introduced in order to further split the codebase. Aliases are available for a new API breaking migration, but it is encouraged to migrate to this new packages: + +* `errors` should replace `types/errors` when registering errors or wrapping SDK errors. +* `math` contains the `Int` or `Uint` types that are used in the SDK. +* `x/nft` an NFT base module. +* `x/group` a group module allowing to create DAOs, multisig and policies. Greatly composes with `x/authz`. + +#### `x/authz` + +* `authz.NewMsgGrant` `expiration` is now a pointer. When `nil` is used, then no expiration will be set (grant won't expire). +* `authz.NewGrant` takes a new argument: block time, to correctly validate expire time. + +### Keyring + +The keyring has been refactored in v0.46. + +* The `Unsafe*` interfaces have been removed from the keyring package. Please use interface casting if you wish to access those unsafe functions. +* The keys' implementation has been refactored to be serialized as proto. +* `keyring.NewInMemory` and `keyring.New` takes now a `codec.Codec`. +* Take `keyring.Record` instead of `Info` as first argument in: + _ `MkConsKeyOutput` + _ `MkValKeyOutput` \* `MkAccKeyOutput` +* Rename: + _ `SavePubKey` to `SaveOfflineKey` and remove the `algo` argument. + _ `NewMultiInfo`, `NewLedgerInfo` to `NewLegacyMultiInfo`, `newLegacyLedgerInfo` respectively. \* `NewOfflineInfo` to `newLegacyOfflineInfo` and move it to `migration_test.go`. + +### PostHandler + +A `postHandler` is like an `antehandler`, but is run _after_ the `runMsgs` execution. It is in the same store branch that `runMsgs`, meaning that both `runMsgs` and `postHandler`. This allows to run a custom logic after the execution of the messages. + +### IAVL + +v0.19.0 IAVL introduces a new "fast" index. This index represents the latest state of the +IAVL laid out in a format that preserves data locality by key. As a result, it allows for faster queries and iterations +since data can now be read in lexicographical order that is frequent for Cosmos-SDK chains. + +The first time the chain is started after the upgrade, the aforementioned index is created. The creation process +might take time and depends on the size of the latest state of the chain. For example, Osmosis takes around 15 minutes to rebuild the index. + +While the index is being created, node operators can observe the following in the logs: +"Upgrading IAVL storage for faster queries + execution on the live state. This may take a while". The store +key is appended to the message. The message is printed for every module that has a non-transient store. +As a result, it gives a good indication of the progress of the upgrade. + +There is also downgrade and re-upgrade protection. If a node operator chooses to downgrade to IAVL pre-fast index, and then upgrade again, the index is rebuilt from scratch. This implementation detail should not be relevant in most cases. It was added as a safeguard against operator +mistakes. + +### Modules + +#### `x/params` + +* The `x/params` module has been depreacted in favour of each module housing and providing way to modify their parameters. Each module that has parameters that are changable during runtime have an authority, the authority can be a module or user account. The Cosmos SDK team recommends migrating modules away from using the param module. An example of how this could look like can be found [here](https://github.com/cosmos/cosmos-sdk/pull/12363). +* The Param module will be maintained until April 18, 2023. At this point the module will reach end of life and be removed from the Cosmos SDK. + +#### `x/gov` + +The `gov` module has been greatly improved. The previous API has been moved to `v1beta1` while the new implementation is called `v1`. + +In order to submit a proposal with `submit-proposal` you now need to pass a `proposal.json` file. +You can still use the old way by using `submit-legacy-proposal`. This is not recommended. +More information can be found in the gov module [client documentation](https://docs.cosmos.network/v0.46/modules/gov/07_client.html). + +#### `x/staking` + +The `staking module` added a new message type to cancel unbonding delegations. Users that have unbonded by accident or wish to cancel a undelegation can now specify the amount and valdiator they would like to cancel the unbond from + +### Protobuf + +The `third_party/proto` folder that existed in [previous version](https://github.com/cosmos/cosmos-sdk/tree/v0.45.3/third_party/proto) now does not contains directly the [proto files](https://github.com/cosmos/cosmos-sdk/tree/release/v0.46.x/third_party/proto). + +Instead, the SDK uses [`buf`](https://buf.build). Clients should have their own [`buf.yaml`](https://docs.buf.build/configuration/v1/buf-yaml) with `buf.build/cosmos/cosmos-sdk` as dependency, in order to avoid having to copy paste these files. + +The protos can as well be downloaded using `buf export buf.build/cosmos/cosmos-sdk:8cb30a2c4de74dc9bd8d260b1e75e176 --output `. + +Cosmos message protobufs should be extended with `cosmos.msg.v1.signer`: + +```protobuf +message MsgSetWithdrawAddress { + option (cosmos.msg.v1.signer) = "delegator_address"; ++ + + option (gogoproto.equal) = false; + option (gogoproto.goproto_getters) = false; + + string delegator_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; + string withdraw_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; +} +``` + +When clients interract with a node they are required to set a codec in in the grpc.Dial. More information can be found in this [doc](https://docs.cosmos.network/v0.46/run-node/interact-node.html#programmatically-via-go). +>>>>>>> f198ea944 (refactor: docs path updates (#17459)) diff --git a/docs/.gitignore b/docs/.gitignore index 6613ce192ef7..ded365d1f8c7 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,7 +2,8 @@ /node_modules # Production -/build +build +!docs/build # Generated files .docusaurus @@ -21,8 +22,9 @@ docs/docs/core/17-autocli.md docs/docs/packages/01-depinject.md docs/docs/packages/02-collections.md docs/docs/packages/03-orm.md -docs/run-node/04-rosetta.md -docs/migrations/02-upgrading.md +docs/user/run-node/04-rosetta.md +docs/build/migrations/02-upgrading.md +docs/develop/advanced/17-autocli.md # Misc .DS_Store diff --git a/docs/architecture/adr-033-protobuf-inter-module-comm.md b/docs/architecture/adr-033-protobuf-inter-module-comm.md index ea634dac9748..672c906d755e 100644 --- a/docs/architecture/adr-033-protobuf-inter-module-comm.md +++ b/docs/architecture/adr-033-protobuf-inter-module-comm.md @@ -20,7 +20,7 @@ service definitions defined in [ADR 021](./adr-021-protobuf-query-encoding.md) a ## Context -In the current Cosmos SDK documentation on the [Object-Capability Model](../core/10-ocap.md), it is stated that: +In the current Cosmos SDK documentation on the [Object-Capability Model](../../develop/advanced/10-ocap.md), it is stated that: > 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. diff --git a/docs/architecture/adr-063-core-module-api.md b/docs/architecture/adr-063-core-module-api.md index d5e0d06b7cbd..622e294352b8 100644 --- a/docs/architecture/adr-063-core-module-api.md +++ b/docs/architecture/adr-063-core-module-api.md @@ -90,7 +90,7 @@ slower than more fast moving projects. ### Core Services The following "core services" are defined by the core API. All valid runtime module implementations should provide -implementations of these services to modules via both [dependency injection](./adr-057-app-wiring-1.md) and +implementations of these services to modules via both [dependency injection](./adr-057-app-wiring.md) and manual wiring. The individual services described below are all bundled in a convenient `appmodule.Service` "bundle service" so that for simplicity modules can declare a dependency on a single service. diff --git a/docs/docs/README.md b/docs/docs/Introduction.md similarity index 59% rename from docs/docs/README.md rename to docs/docs/Introduction.md index 451a0bc1942e..7ada53c8fc4e 100644 --- a/docs/docs/README.md +++ b/docs/docs/Introduction.md @@ -9,19 +9,19 @@ Cosmos SDK is the world’s most popular framework for building application-spec Read all about the SDK or dive straight into the code with tutorials. -* [**Introductions to the Cosmos SDK**](./intro/00-overview.md) - Learn about all the parts of the Cosmos SDK. +* [**Introductions to the Cosmos SDK**](develop/intro/00-overview.md) - Learn about all the parts of the Cosmos SDK. * [**SDK Tutorials**](https://tutorials.cosmos.network) - Build a complete blockchain application from scratch. ## Explore the SDK Get familiar with the SDK and explore its main concepts. -* [**Introduction**](./intro/00-overview.md) - High-level overview of the Cosmos SDK. -* [**Basics**](./basics/00-app-anatomy.md) - Anatomy of a blockchain, transaction lifecycle, accounts and more. -* [**Core Concepts**](./core/00-baseapp.md) - Read about the core concepts like baseapp, the store, or the server. -* [**Building Modules**](./building-modules/01-intro.md) - Discover how to build modules for the Cosmos SDK. -* [**Running a Node**](./run-node/00-keyring.md) - Running and interacting with nodes using the CLI and API. -* [**Modules**](./modules/README.md) - Explore existing modules to build your application with. +* [**Introduction**](develop/intro/00-overview.md) - High-level overview of the Cosmos SDK. +* [**Basics**](develop/beginner/00-app-anatomy.md) - Anatomy of a blockchain, transaction lifecycle, accounts and more. +* [**Core Concepts**](develop/advanced/00-baseapp.md) - Read about the core concepts like baseapp, the store, or the server. +* [**Building Modules**](build/building-modules/01-intro.md) - Discover how to build modules for the Cosmos SDK. +* [**Running a Node**](user/run-node/00-keyring.md) - Running and interacting with nodes using the CLI and API. +* [**Modules**](./build/modules/README.md) - Explore existing modules to build your application with. ## Explore the Stack diff --git a/docs/docs/building-apps/00-app-go.md b/docs/docs/build/building-apps/00-app-go.md similarity index 100% rename from docs/docs/building-apps/00-app-go.md rename to docs/docs/build/building-apps/00-app-go.md diff --git a/docs/docs/building-apps/01-app-go-v2.md b/docs/docs/build/building-apps/01-app-go-v2.md similarity index 100% rename from docs/docs/building-apps/01-app-go-v2.md rename to docs/docs/build/building-apps/01-app-go-v2.md diff --git a/docs/docs/building-apps/02-app-mempool.md b/docs/docs/build/building-apps/02-app-mempool.md similarity index 99% rename from docs/docs/building-apps/02-app-mempool.md rename to docs/docs/build/building-apps/02-app-mempool.md index ca754a85dde8..1f591fc6de12 100644 --- a/docs/docs/building-apps/02-app-mempool.md +++ b/docs/docs/build/building-apps/02-app-mempool.md @@ -15,7 +15,7 @@ Notably it introduces the `PrepareProposal` and `ProcessProposal` steps of ABCI+ :::note Pre-requisite Readings -* [BaseApp](../core/00-baseapp.md) +* [BaseApp](../../develop/advanced/00-baseapp.md) ::: diff --git a/docs/docs/building-apps/03-app-upgrade.md b/docs/docs/build/building-apps/03-app-upgrade.md similarity index 100% rename from docs/docs/building-apps/03-app-upgrade.md rename to docs/docs/build/building-apps/03-app-upgrade.md diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/build/building-apps/04-vote-extensions.md similarity index 100% rename from docs/docs/building-apps/04-vote-extensions.md rename to docs/docs/build/building-apps/04-vote-extensions.md diff --git a/docs/docs/building-apps/_category_.json b/docs/docs/build/building-apps/_category_.json similarity index 100% rename from docs/docs/building-apps/_category_.json rename to docs/docs/build/building-apps/_category_.json diff --git a/docs/docs/building-modules/01-intro.md b/docs/docs/build/building-modules/01-intro.md similarity index 86% rename from docs/docs/building-modules/01-intro.md rename to docs/docs/build/building-modules/01-intro.md index 71dbd56bd537..7bfaf8e980ac 100644 --- a/docs/docs/building-modules/01-intro.md +++ b/docs/docs/build/building-modules/01-intro.md @@ -10,18 +10,18 @@ Modules define most of the logic of Cosmos SDK applications. Developers compose :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) -* [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md) +* [Anatomy of a Cosmos SDK application](../../develop/beginner/00-app-anatomy.md) +* [Lifecycle of a Cosmos SDK transaction](../../develop/beginner/01-tx-lifecycle.md) ::: ## Role of Modules in a Cosmos SDK Application -The Cosmos SDK can be thought of as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../core/00-baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../core/04-store.md#multistore) to persist state, a [server](../core/03-node.md) to form a full-node and [interfaces](./09-module-interfaces.md) to handle queries. +The Cosmos SDK can be thought of as the Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a [boilerplate implementation of the ABCI](../../develop/advanced/00-baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../../develop/advanced/04-store.md#multistore) to persist state, a [server](../../develop/advanced/03-node.md) to form a full-node and [interfaces](./09-module-interfaces.md) to handle queries. On top of this core, the Cosmos SDK enables developers to build modules that implement the business logic of their application. In other words, SDK modules implement the bulk of the logic of applications, while the core does the wiring and enables modules to be composed together. The end goal is to build a robust ecosystem of open-source Cosmos SDK modules, making it increasingly easier to build complex blockchain applications. -Cosmos SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../core/04-store.md), as well as a subset of [message types](./02-messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../core/00-baseapp.md), to a module Protobuf [`Msg` service](./03-msg-services.md) that defines them. +Cosmos SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../../develop/advanced/04-store.md), as well as a subset of [message types](./02-messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../../develop/advanced/00-baseapp.md), to a module Protobuf [`Msg` service](./03-msg-services.md) that defines them. ```text + @@ -75,7 +75,7 @@ As a result of this architecture, building a Cosmos SDK application usually revo While there are no definitive guidelines for writing modules, here are some important design principles developers should keep in mind when building them: * **Composability**: Cosmos SDK applications are almost always composed of multiple modules. This means developers need to carefully consider the integration of their module not only with the core of the Cosmos SDK, but also with other modules. The former is achieved by following standard design patterns outlined [here](#main-components-of-sdk-modules), while the latter is achieved by properly exposing the store(s) of the module via the [`keeper`](./06-keeper.md). -* **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../core/10-ocap.md) of the Cosmos SDK. +* **Specialization**: A direct consequence of the **composability** feature is that modules should be **specialized**. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. **Specialization** also plays an important role in the [object-capabilities model](../../develop/advanced/10-ocap.md) of the Cosmos SDK. * **Capabilities**: Most modules need to read and/or write to the store(s) of other modules. However, in an open-source environment, it is possible for some modules to be malicious. That is why module developers need to carefully think not only about how their module interacts with other modules, but also about how to give access to the module's store(s). The Cosmos SDK takes a capabilities-oriented approach to inter-module security. This means that each store defined by a module is accessed by a `key`, which is held by the module's [`keeper`](./06-keeper.md). This `keeper` defines how to access the store(s) and under what conditions. Access to the module's store(s) is done by passing a reference to the module's `keeper`. ## Main Components of Cosmos SDK Modules @@ -83,8 +83,8 @@ While there are no definitive guidelines for writing modules, here are some impo Modules are by convention defined in the `./x/` subfolder (e.g. the `bank` module will be defined in the `./x/bank` folder). They generally share the same core components: * A [`keeper`](./06-keeper.md), used to access the module's store(s) and update the state. -* A [`Msg` service](./02-messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../core/00-baseapp.md#message-routing) and trigger state-transitions. -* A [query service](./04-query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../core/00-baseapp.md#query-routing). +* A [`Msg` service](./02-messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../../develop/advanced/00-baseapp.md#message-routing) and trigger state-transitions. +* A [query service](./04-query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../../develop/advanced/00-baseapp.md#query-routing). * Interfaces, for end users to query the subset of the state defined by the module and create `message`s of the custom types defined in the module. In addition to these components, modules implement the `AppModule` interface in order to be managed by the [`module manager`](./01-module-manager.md). diff --git a/docs/docs/building-modules/01-module-manager.md b/docs/docs/build/building-modules/01-module-manager.md similarity index 77% rename from docs/docs/building-modules/01-module-manager.md rename to docs/docs/build/building-modules/01-module-manager.md index dc9a9b5ebe14..00924c4d2c46 100644 --- a/docs/docs/building-modules/01-module-manager.md +++ b/docs/docs/build/building-modules/01-module-manager.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Module Manager :::note Synopsis -Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../core/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../basics/00-app-anatomy.md#begingblocker-and-endblocker). +Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-module-interfaces), in order to be managed by the application's [module manager](#module-manager). The module manager plays an important role in [`message` and `query` routing](../../develop/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`BeginBlocker` and `EndBlocker`](../../develop/beginner/00-app-anatomy.md#begingblocker-and-endblocker). ::: :::note Pre-requisite Readings @@ -45,7 +45,7 @@ The above interfaces are mostly embedding smaller interfaces (extension interfac * (legacy) [`module.HasInvariants`](#hasinvariants): The extension interface for registering invariants. * (legacy) [`module.HasConsensusVersion`](#hasconsensusversion): The extension interface for declaring a module consensus version. -The `AppModuleBasic` interface exists to define independent methods of the module, i.e. those that do not depend on other modules in the application. This allows for the construction of the basic application structure early in the application definition, generally in the `init()` function of the [main application file](../basics/00-app-anatomy.md#core-application-file). +The `AppModuleBasic` interface exists to define independent methods of the module, i.e. those that do not depend on other modules in the application. This allows for the construction of the basic application structure early in the application definition, generally in the `init()` function of the [main application file](../../develop/beginner/00-app-anatomy.md#core-application-file). The `AppModule` interface exists to define inter-dependent module methods. Many modules need to interact with other modules, typically through [`keeper`s](./06-keeper.md), which means there is a need for an interface where modules list their `keeper`s and other methods that require a reference to another module's object. `AppModule` interface extension, such as `HasBeginBlocker` and `HasEndBlocker`, also enables the module manager to set the order of execution between module's methods like `BeginBlock` and `EndBlock`, which is important in cases where the order of execution between modules matters in the context of the application. @@ -219,7 +219,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/core/appmodule/module.go#L49-L52 ``` -* `Precommit(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../core/00-baseapp.md#commit) of each block using the [`finalizeblockstate`](../core/00-baseapp.md#state-updates) of the block to be committed. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. +* `Precommit(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../../develop/advanced/00-baseapp.md#commit) of each block using the [`finalizeblockstate`](../../develop/advanced/00-baseapp.md#state-updates) of the block to be committed. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. ### `HasPrepareCheckState` @@ -229,7 +229,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/core/appmodule/module. https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/core/appmodule/module.go#L49-L52 ``` -* `PrepareCheckState(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../core/00-baseapp.md#commit) of each block using the [`checkState`](../core/00-baseapp.md#state-updates) of the next block. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. +* `PrepareCheckState(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../../develop/advanced/00-baseapp.md#commit) of each block using the [`checkState`](../../develop/advanced/00-baseapp.md#state-updates) of the next block. Implement empty if no logic needs to be triggered during `Commit` of each block for this module. ### Implementing the Application Module Interfaces @@ -267,15 +267,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go It implements the following methods: -* `NewBasicManager(modules ...AppModuleBasic)`: Constructor function. It takes a list of the application's `AppModuleBasic` and builds a new `BasicManager`. This function is generally called in the `init()` function of [`app.go`](../basics/00-app-anatomy.md#core-application-file) to quickly initialize the independent elements of the application's modules (click [here](https://github.com/cosmos/gaia/blob/main/app/app.go#L59-L74) to see an example). +* `NewBasicManager(modules ...AppModuleBasic)`: Constructor function. It takes a list of the application's `AppModuleBasic` and builds a new `BasicManager`. This function is generally called in the `init()` function of [`app.go`](../../develop/beginner/00-app-anatomy.md#core-application-file) to quickly initialize the independent elements of the application's modules (click [here](https://github.com/cosmos/gaia/blob/main/app/app.go#L59-L74) to see an example). * `NewBasicManagerFromManager(manager *Manager, customModuleBasics map[string]AppModuleBasic)`: Contructor function. It creates a new `BasicManager` from a `Manager`. The `BasicManager` will contain all `AppModuleBasic` from the `AppModule` manager using `CoreAppModuleBasicAdaptor` whenever possible. Module's `AppModuleBasic` can be overridden by passing a custom AppModuleBasic map -* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../core/05-encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../basics/00-app-anatomy.md#constructor). +* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../../develop/advanced/05-encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../../develop/beginner/00-app-anatomy.md#constructor). * `RegisterInterfaces(registry codectypes.InterfaceRegistry)`: Registers interface types and implementations of each of the application's `AppModuleBasic`. * `DefaultGenesis(cdc codec.JSONCodec)`: Provides default genesis information for modules in the application by calling the [`DefaultGenesis(cdc codec.JSONCodec)`](./08-genesis.md#defaultgenesis) function of each module. It only calls the modules that implements the `HasGenesisBasics` interfaces. * `ValidateGenesis(cdc codec.JSONCodec, txEncCfg client.TxEncodingConfig, genesis map[string]json.RawMessage)`: Validates the genesis information modules by calling the [`ValidateGenesis(codec.JSONCodec, client.TxEncodingConfig, json.RawMessage)`](./08-genesis.md#validategenesis) function of modules implementing the `HasGenesisBasics` interface. * `RegisterGRPCGatewayRoutes(clientCtx client.Context, rtr *runtime.ServeMux)`: Registers gRPC routes for modules. -* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands (defined as `GetTxCmd() *cobra.Command`) to the application's [`rootTxCommand`](../core/07-cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/07-cli.md). -* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands (defined as `GetQueryCmd() *cobra.Command`) to the application's [`rootQueryCommand`](../core/07-cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../core/07-cli.md). +* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands (defined as `GetTxCmd() *cobra.Command`) to the application's [`rootTxCommand`](../../develop/advanced/07-cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../develop/advanced/07-cli.md). +* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands (defined as `GetQueryCmd() *cobra.Command`) to the application's [`rootQueryCommand`](../../develop/advanced/07-cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../develop/advanced/07-cli.md). ### `Manager` @@ -287,25 +287,34 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/module/module.go The module manager is used throughout the application whenever an action on a collection of modules is required. It implements the following methods: -* `NewManager(modules ...AppModule)`: Constructor function. It takes a list of the application's `AppModule`s and builds a new `Manager`. It is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). +* `NewManager(modules ...AppModule)`: Constructor function. It takes a list of the application's `AppModule`s and builds a new `Manager`. It is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderInitGenesis(moduleNames ...string)`: Sets the order in which the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module will be called when the application is first started. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). To initialize modules successfully, module dependencies should be considered. For example, the `genutil` module must occur after `staking` module so that the pools are properly initialized with tokens from genesis accounts, the `genutils` module must also occur after `auth` so that it can access the params from auth, IBC's `capability` module should be initialized before all other modules so that it can initialize any capabilities. -* `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderPrecommiters(moduleNames ...string)`: Sets the order in which the `Precommit()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). -* `SetOrderPrepareCheckStaters(moduleNames ...string)`: Sets the order in which the `PrepareCheckState()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../basics/00-app-anatomy.md#constructor-function). +* `SetOrderExportGenesis(moduleNames ...string)`: Sets the order in which the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module will be called in case of an export. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderBeginBlockers(moduleNames ...string)`: Sets the order in which the `BeginBlock()` function of each module will be called at the beginning of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderEndBlockers(moduleNames ...string)`: Sets the order in which the `EndBlock()` function of each module will be called at the end of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderPrecommiters(moduleNames ...string)`: Sets the order in which the `Precommit()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderPrepareCheckStaters(moduleNames ...string)`: Sets the order in which the `PrepareCheckState()` function of each module will be called during commit of each block. This function is generally called from the application's main [constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). * `SetOrderMigrations(moduleNames ...string)`: Sets the order of migrations to be run. If not set then migrations will be run with an order defined in `DefaultMigrationsOrder`. * `RegisterInvariants(ir sdk.InvariantRegistry)`: Registers the [invariants](./07-invariants.md) of module implementing the `HasInvariants` interface. * `RegisterServices(cfg Configurator)`: Registers the services of modules implementing the `HasServices` interface. * `InitGenesis(ctx context.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.ResponseInitChain` to the underlying consensus engine, which can contain validator updates. * `ExportGenesis(ctx context.Context, cdc codec.JSONCodec)`: Calls the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required. * `ExportGenesisForModules(ctx context.Context, cdc codec.JSONCodec, modulesToExport []string)`: Behaves the same as `ExportGenesis`, except takes a list of modules to export. +<<<<<<< HEAD:docs/docs/building-modules/01-module-manager.md * `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of all modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from modules. * `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `Precommit(ctx context.Context)`: During [`Commit`](../core/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../core/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../core/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../core/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../core/00-baseapp.md#state-updates). * `PrepareCheckState(ctx context.Context)`: During [`Commit`](../core/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../core/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../core/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../core/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../core/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../core/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block. +======= +* `RunMigrationBeginBlock(ctx sdk.Context) (bool, error)`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of the upgrade module implementing the `HasBeginBlocker` interface. The function returns a boolean value indicating whether the migration was executed or not and an error if fails. +* `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of each non-upgrade modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from non-upgrade modules. +* `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). +* `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). +* `Precommit(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../../develop/advanced/00-baseapp.md#state-updates). +* `PrepareCheckState(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../../develop/advanced/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../../develop/advanced/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block. +>>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/build/building-modules/01-module-manager.md Here's an example of a concrete integration within an `simapp`: diff --git a/docs/docs/building-modules/02-messages-and-queries.md b/docs/docs/build/building-modules/02-messages-and-queries.md similarity index 86% rename from docs/docs/building-modules/02-messages-and-queries.md rename to docs/docs/build/building-modules/02-messages-and-queries.md index a175216c3488..69465ab5e576 100644 --- a/docs/docs/building-modules/02-messages-and-queries.md +++ b/docs/docs/build/building-modules/02-messages-and-queries.md @@ -16,13 +16,13 @@ sidebar_position: 1 ## Messages -`Msg`s are objects whose end-goal is to trigger state-transitions. They are wrapped in [transactions](../core/01-transactions.md), which may contain one or more of them. +`Msg`s are objects whose end-goal is to trigger state-transitions. They are wrapped in [transactions](../../develop/advanced/01-transactions.md), which may contain one or more of them. -When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../core/00-baseapp.md). Then, each message contained in the transaction is extracted and routed to the appropriate module via `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's [`Msg` service](./03-msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../basics/01-tx-lifecycle.md). +When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../../develop/advanced/00-baseapp.md). Then, each message contained in the transaction is extracted and routed to the appropriate module via `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's [`Msg` service](./03-msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../../develop/beginner/01-tx-lifecycle.md). ### `Msg` Services -Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../core/05-encoding.md#faq)). It must have an RPC service method defined for each message in the module. +Defining Protobuf `Msg` services is the recommended way to handle messages. A Protobuf `Msg` service should be created for each module, typically in `tx.proto` (see more info about [conventions and naming](../../develop/advanced/05-encoding.md#faq)). It must have an RPC service method defined for each message in the module. Each `Msg` service method must have exactly one argument, which must implement the `sdk.Msg` interface, and a Protobuf response. The naming convention is to call the RPC argument `Msg` and the RPC response `MsgResponse`. For example: @@ -89,7 +89,7 @@ In order for clients (CLI and grpc-gateway) to have these URLs registered, the C ## Queries -A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `QueryRouter` so that it can be processed by the module's query service (./04-query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../basics/02-query-lifecycle.md). +A `query` is a request for information made by end-users of applications through an interface and processed by a full-node. A `query` is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via `BaseApp`'s `QueryRouter` so that it can be processed by the module's query service (./04-query-services.md). For a deeper look at the lifecycle of a `query`, click [here](../../develop/beginner/02-query-lifecycle.md). ### gRPC Queries @@ -115,14 +115,14 @@ queryCategory/queryRoute/queryType/arg1/arg2/... where: -* `queryCategory` is the category of the `query`, typically `custom` for module queries. It is used to differentiate between different kinds of queries within `BaseApp`'s [`Query` method](../core/00-baseapp.md#query). -* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../core/00-baseapp.md#query-routing) to map the `query` to its module. Usually, `queryRoute` should be the name of the module. +* `queryCategory` is the category of the `query`, typically `custom` for module queries. It is used to differentiate between different kinds of queries within `BaseApp`'s [`Query` method](../../develop/advanced/00-baseapp.md#query). +* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../../develop/advanced/00-baseapp.md#query-routing) to map the `query` to its module. Usually, `queryRoute` should be the name of the module. * `queryType` is used by the module's [`querier`](./04-query-services.md#legacy-queriers) to map the `query` to the appropriate `querier function` within the module. * `args` are the actual arguments needed to process the `query`. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in the `Data` field of the request `req` instead of the `path`. The `path` for each `query` must be defined by the module developer in the module's [command-line interface file](./09-module-interfaces.md#query-commands).Overall, there are 3 mains components module developers need to implement in order to make the subset of the state defined by their module queryable: -* A [`querier`](./04-query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../core/00-baseapp.md#query-routing). +* A [`querier`](./04-query-services.md#legacy-queriers), to process the `query` once it has been [routed to the module](../../develop/advanced/00-baseapp.md#query-routing). * [Query commands](./09-module-interfaces.md#query-commands) in the module's CLI file, where the `path` for each `query` is specified. * `query` return types. Typically defined in a file `types/querier.go`, they specify the result type of each of the module's `queries`. These custom types must implement the `String()` method of [`fmt.Stringer`](https://pkg.go.dev/fmt#Stringer). diff --git a/docs/docs/building-modules/03-msg-services.md b/docs/docs/build/building-modules/03-msg-services.md similarity index 91% rename from docs/docs/building-modules/03-msg-services.md rename to docs/docs/build/building-modules/03-msg-services.md index 918a5d45a4a0..ead334108a74 100644 --- a/docs/docs/building-modules/03-msg-services.md +++ b/docs/docs/build/building-modules/03-msg-services.md @@ -5,7 +5,7 @@ sidebar_position: 1 # `Msg` Services :::note Synopsis -A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messages). Protobuf `Msg` services are specific to the module in which they are defined, and only process messages defined within the said module. They are called from `BaseApp` during [`DeliverTx`](../core/00-baseapp.md#delivertx). +A Protobuf `Msg` service processes [messages](./02-messages-and-queries.md#messages). Protobuf `Msg` services are specific to the module in which they are defined, and only process messages defined within the said module. They are called from `BaseApp` during [`DeliverTx`](../../develop/advanced/00-baseapp.md#delivertx). ::: :::note Pre-requisite Readings @@ -71,7 +71,7 @@ After the validation is successful, the `msgServer` method uses the [`keeper`](. ### Events -Before returning, `msgServer` methods generally emit one or more [events](../core/08-events.md) by using the `EventManager` held in the `ctx`. Use the new `EmitTypedEvent` function that uses protobuf-based event types: +Before returning, `msgServer` methods generally emit one or more [events](../../develop/advanced/08-events.md) by using the `EventManager` held in the `ctx`. Use the new `EmitTypedEvent` function that uses protobuf-based event types: ```go ctx.EventManager().EmitTypedEvent( @@ -90,7 +90,7 @@ ctx.EventManager().EmitEvent( ) ``` -These events are relayed back to the underlying consensus engine and can be used by service providers to implement services around the application. Click [here](../core/08-events.md) to learn more about events. +These events are relayed back to the underlying consensus engine and can be used by service providers to implement services around the application. Click [here](../../develop/advanced/08-events.md) to learn more about events. 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 context.Context, res proto.Message, err error)`: @@ -110,7 +110,7 @@ This diagram shows a typical structure of a Protobuf `Msg` service, and how the ## Telemetry -New [telemetry metrics](../core/09-telemetry.md) can be created from `msgServer` methods when handling messages. +New [telemetry metrics](../../develop/advanced/09-telemetry.md) can be created from `msgServer` methods when handling messages. This is an example from the `x/auth/vesting` module: diff --git a/docs/docs/building-modules/04-query-services.md b/docs/docs/build/building-modules/04-query-services.md similarity index 98% rename from docs/docs/building-modules/04-query-services.md rename to docs/docs/build/building-modules/04-query-services.md index 657557f89859..29542d86cc3c 100644 --- a/docs/docs/building-modules/04-query-services.md +++ b/docs/docs/build/building-modules/04-query-services.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Query Services :::note Synopsis -A Protobuf Query service processes [`queries`](./02-messages-and-queries.md#queries). Query services are specific to the module in which they are defined, and only process `queries` defined within said module. They are called from `BaseApp`'s [`Query` method](../core/00-baseapp.md#query). +A Protobuf Query service processes [`queries`](./02-messages-and-queries.md#queries). Query services are specific to the module in which they are defined, and only process `queries` defined within said module. They are called from `BaseApp`'s [`Query` method](../../develop/advanced/00-baseapp.md#query). ::: :::note Pre-requisite Readings diff --git a/docs/docs/building-modules/05-beginblock-endblock.md b/docs/docs/build/building-modules/05-beginblock-endblock.md similarity index 87% rename from docs/docs/building-modules/05-beginblock-endblock.md rename to docs/docs/build/building-modules/05-beginblock-endblock.md index ff9a35a847c1..9472b0b759eb 100644 --- a/docs/docs/building-modules/05-beginblock-endblock.md +++ b/docs/docs/build/building-modules/05-beginblock-endblock.md @@ -5,7 +5,7 @@ sidebar_position: 1 # BeginBlocker and EndBlocker :::note Synopsis -`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the [`BeginBlock`](../core/00-baseapp.md#beginblock) and [`EndBlock`](../core/00-baseapp.md#endblock) ABCI messages are received from the underlying consensus engine. +`BeginBlocker` and `EndBlocker` are optional methods module developers can implement in their module. They will be triggered at the beginning and at the end of each block respectively, when the [`BeginBlock`](../../develop/advanced/00-baseapp.md#beginblock) and [`EndBlock`](../../develop/advanced/00-baseapp.md#endblock) ABCI messages are received from the underlying consensus engine. ::: :::note Pre-requisite Readings @@ -24,9 +24,9 @@ When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`Ha The actual implementation of `BeginBlocker` and `EndBlocker` in `abci.go` are very similar to that of a [`Msg` service](./03-msg-services.md): -* They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../core/02-context.md) to retrieve information about the latest state. +* They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../../develop/advanced/02-context.md) to retrieve information about the latest state. * If needed, they use the `keeper` and `ctx` to trigger state-transitions. -* If needed, they can emit [`events`](../core/08-events.md) via the `ctx`'s `EventManager`. +* If needed, they can emit [`events`](../../develop/advanced/08-events.md) via the `ctx`'s `EventManager`. A specific type of `EndBlocker` is available to return validator updates to the underlying consensus engine in the form of an [`[]abci.ValidatorUpdates`](https://docs.cometbft.com/v0.37/spec/abci/abci++_methods#endblock). This is the preferred way to implement custom validator changes. diff --git a/docs/docs/building-modules/06-keeper.md b/docs/docs/build/building-modules/06-keeper.md similarity index 70% rename from docs/docs/building-modules/06-keeper.md rename to docs/docs/build/building-modules/06-keeper.md index b9a11f87b4ec..400c79bf2185 100644 --- a/docs/docs/building-modules/06-keeper.md +++ b/docs/docs/build/building-modules/06-keeper.md @@ -18,9 +18,9 @@ sidebar_position: 1 The Cosmos SDK is a framework that makes it easy for developers to build complex decentralized applications from scratch, mainly by composing modules together. As the ecosystem of open-source modules for the Cosmos SDK expands, it will become increasingly likely that some of these modules contain vulnerabilities, as a result of the negligence or malice of their developer. -The Cosmos SDK adopts an [object-capabilities-based approach](../core/10-ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../core/04-store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s). +The Cosmos SDK adopts an [object-capabilities-based approach](../../develop/advanced/10-ocap.md) to help developers better protect their application from unwanted inter-module interactions, and `keeper`s are at the core of this approach. A `keeper` can be considered quite literally to be the gatekeeper of a module's store(s). Each store (typically an [`IAVL` Store](../../develop/advanced/04-store.md#iavl-store)) defined within a module comes with a `storeKey`, which grants unlimited access to it. The module's `keeper` holds this `storeKey` (which should otherwise remain unexposed), and defines [methods](#implementing-methods) for reading and writing to the store(s). -The core idea behind the object-capabilities approach is to only reveal what is necessary to get the work done. In practice, this means that instead of handling permissions of modules through access-control lists, module `keeper`s are passed a reference to the specific instance of the other modules' `keeper`s that they need to access (this is done in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function)). As a consequence, a module can only interact with the subset of state defined in another module via the methods exposed by the instance of the other module's `keeper`. This is a great way for developers to control the interactions that their own module can have with modules developed by external developers. +The core idea behind the object-capabilities approach is to only reveal what is necessary to get the work done. In practice, this means that instead of handling permissions of modules through access-control lists, module `keeper`s are passed a reference to the specific instance of the other modules' `keeper`s that they need to access (this is done in the [application's constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function)). As a consequence, a module can only interact with the subset of state defined in another module via the methods exposed by the instance of the other module's `keeper`. This is a great way for developers to control the interactions that their own module can have with modules developed by external developers. ## Type Definition @@ -47,10 +47,16 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/keepe Let us go through the different parameters: * An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in an `expected_keepers.go` file in the root of the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself. +<<<<<<< HEAD:docs/docs/building-modules/06-keeper.md * `storeKey`s grant access to the store(s) of the [multistore](../core/04-store.md) managed by the module. They should always remain unexposed to external modules. * `cdc` is the [codec](../core/05-encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces. The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated. +======= +* `storeKey`s grant access to the store(s) of the [multistore](../../develop/advanced/04-store.md) managed by the module. They should always remain unexposed to external modules. +* `cdc` is the [codec](../../develop/advanced/05-encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces. +* The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated. +>>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/build/building-modules/06-keeper.md -Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../basics/00-app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them. +Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../../develop/beginner/00-app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them. ## Implementing Methods @@ -82,7 +88,7 @@ and the method will go through the following steps: For more, see an example of `keeper`'s [methods implementation from the `staking` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/keeper.go). -The [module `KVStore`](../core/04-store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys. +The [module `KVStore`](../../develop/advanced/04-store.md#kvstore-and-commitkvstore-interfaces) also provides an `Iterator()` method which returns an `Iterator` object to iterate over a domain of keys. This is an example from the `auth` module to iterate accounts: diff --git a/docs/docs/building-modules/07-invariants.md b/docs/docs/build/building-modules/07-invariants.md similarity index 97% rename from docs/docs/building-modules/07-invariants.md rename to docs/docs/build/building-modules/07-invariants.md index f1bcd801f827..cd85864bfa3b 100644 --- a/docs/docs/building-modules/07-invariants.md +++ b/docs/docs/build/building-modules/07-invariants.md @@ -79,7 +79,7 @@ Typically, this interface is implemented in the `keeper` of a specific module. T https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/crisis/keeper/keeper.go#L48-L50 ``` -The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function). +The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). `Invariant`s can be checked manually via [`message`s](./02-messages-and-queries.md), but most often they are checked automatically at the end of each block. Here is an example from the `crisis` module: diff --git a/docs/docs/building-modules/08-genesis.md b/docs/docs/build/building-modules/08-genesis.md similarity index 81% rename from docs/docs/building-modules/08-genesis.md rename to docs/docs/build/building-modules/08-genesis.md index 2e400353742d..546eb5fb9263 100644 --- a/docs/docs/building-modules/08-genesis.md +++ b/docs/docs/build/building-modules/08-genesis.md @@ -17,7 +17,7 @@ Modules generally handle a subset of the state and, as such, they need to define ## Type Definition -The subset of the genesis state defined from a given module is generally defined in a `genesis.proto` file ([more info](../core/05-encoding.md#gogoproto) on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called `GenesisState` and contains all the module-related values that need to be initialized during the genesis process. +The subset of the genesis state defined from a given module is generally defined in a `genesis.proto` file ([more info](../../develop/advanced/05-encoding.md#gogoproto) on how to define protobuf messages). The struct defining the module's subset of the genesis state is usually called `GenesisState` and contains all the module-related values that need to be initialized during the genesis process. See an example of `GenesisState` protobuf message definition from the `auth` module: @@ -49,9 +49,9 @@ Other than the methods related directly to `GenesisState`, module developers are ### `InitGenesis` -The `InitGenesis` method is executed during [`InitChain`](../core/00-baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./06-keeper.md) setter function on each parameter within the `GenesisState`. +The `InitGenesis` method is executed during [`InitChain`](../../develop/advanced/00-baseapp.md#initchain) when the application is first started. Given a `GenesisState`, it initializes the subset of the state managed by the module by using the module's [`keeper`](./06-keeper.md) setter function on each parameter within the `GenesisState`. -The [module manager](./01-module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../basics/00-app-anatomy.md#constructor-function). +The [module manager](./01-module-manager.md#manager) of the application is responsible for calling the `InitGenesis` method of each of the application's modules in order. This order is set by the application developer via the manager's `SetOrderGenesisMethod`, which is called in the [application's constructor function](../../develop/beginner/00-app-anatomy.md#constructor-function). See an example of `InitGenesis` from the `auth` module: diff --git a/docs/docs/building-modules/09-module-interfaces.md b/docs/docs/build/building-modules/09-module-interfaces.md similarity index 93% rename from docs/docs/building-modules/09-module-interfaces.md rename to docs/docs/build/building-modules/09-module-interfaces.md index 81831f90da80..27707bd344a7 100644 --- a/docs/docs/building-modules/09-module-interfaces.md +++ b/docs/docs/build/building-modules/09-module-interfaces.md @@ -16,11 +16,11 @@ This document details how to build CLI and REST interfaces for a module. Example ## CLI -One of the main interfaces for an application is the [command-line interface](../core/07-cli.md). This entrypoint adds commands from the application's modules enabling end-users to create [**messages**](./02-messages-and-queries.md#messages) wrapped in transactions and [**queries**](./02-messages-and-queries.md#queries). The CLI files are typically found in the module's `./client/cli` folder. +One of the main interfaces for an application is the [command-line interface](../../develop/advanced/07-cli.md). This entrypoint adds commands from the application's modules enabling end-users to create [**messages**](./02-messages-and-queries.md#messages) wrapped in transactions and [**queries**](./02-messages-and-queries.md#queries). The CLI files are typically found in the module's `./client/cli` folder. ### Transaction Commands -In order to create messages that trigger state changes, end-users must create [transactions](../core/01-transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages. +In order to create messages that trigger state changes, end-users must create [transactions](../../develop/advanced/01-transactions.md) that wrap and deliver the messages. A transaction command creates a transaction that includes one or more messages. Transaction commands typically have their own `tx.go` file that lives within the module's `./client/cli` folder. The commands are specified in getter functions and the name of the function should include the name of the command. @@ -101,7 +101,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/module.go#L84-L ### Flags -[Flags](../core/07-cli.md#flags) allow users to customize commands. `--fees` and `--gas-prices` are examples of flags that allow users to set the [fees](../basics/04-gas-fees.md) and gas prices for their transactions. +[Flags](../../develop/advanced/07-cli.md#flags) allow users to customize commands. `--fees` and `--gas-prices` are examples of flags that allow users to set the [fees](../../develop/beginner/04-gas-fees.md) and gas prices for their transactions. Flags that are specific to a module are typically created in a `flags.go` file in the module's `./client/cli` folder. When creating a flag, developers set the value type, the name of the flag, the default value, and a description about the flag. Developers also have the option to mark flags as _required_ so that an error is thrown if the user does not include a value for the flag. diff --git a/docs/docs/building-modules/11-structure.md b/docs/docs/build/building-modules/11-structure.md similarity index 100% rename from docs/docs/building-modules/11-structure.md rename to docs/docs/build/building-modules/11-structure.md diff --git a/docs/docs/building-modules/12-errors.md b/docs/docs/build/building-modules/12-errors.md similarity index 100% rename from docs/docs/building-modules/12-errors.md rename to docs/docs/build/building-modules/12-errors.md diff --git a/docs/docs/building-modules/13-upgrade.md b/docs/docs/build/building-modules/13-upgrade.md similarity index 90% rename from docs/docs/building-modules/13-upgrade.md rename to docs/docs/build/building-modules/13-upgrade.md index 3a6515707643..703b4cd28082 100644 --- a/docs/docs/building-modules/13-upgrade.md +++ b/docs/docs/build/building-modules/13-upgrade.md @@ -5,12 +5,12 @@ sidebar_position: 1 # Upgrading Modules :::note Synopsis -[In-Place Store Migrations](../core/15-upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. +[In-Place Store Migrations](../../develop/advanced/15-upgrade.md) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. ::: :::note Pre-requisite Readings -* [In-Place Store Migration](../core/15-upgrade.md) +* [In-Place Store Migration](../../develop/advanced/15-upgrade.md) ::: diff --git a/docs/docs/building-modules/14-simulator.md b/docs/docs/build/building-modules/14-simulator.md similarity index 97% rename from docs/docs/building-modules/14-simulator.md rename to docs/docs/build/building-modules/14-simulator.md index 3065e3c60ec4..5360709f6d58 100644 --- a/docs/docs/building-modules/14-simulator.md +++ b/docs/docs/build/building-modules/14-simulator.md @@ -6,7 +6,7 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Cosmos Blockchain Simulator](../core/12-simulation.md) +* [Cosmos Blockchain Simulator](../../develop/advanced/12-simulation.md) ::: ## Synopsis @@ -62,7 +62,7 @@ Operations are one of the crucial parts of the Cosmos SDK simulation. They are t (`Msg`) that are simulated with random field values. The sender of the operation is also assigned randomly. -Operations on the simulation are simulated using the full [transaction cycle](../core/01-transactions.md) of a +Operations on the simulation are simulated using the full [transaction cycle](../../develop/advanced/01-transactions.md) of a `ABCI` application that exposes the `BaseApp`. Shown below is how weights are set: diff --git a/docs/docs/building-modules/15-depinject.md b/docs/docs/build/building-modules/15-depinject.md similarity index 100% rename from docs/docs/building-modules/15-depinject.md rename to docs/docs/build/building-modules/15-depinject.md diff --git a/docs/docs/building-modules/16-testing.md b/docs/docs/build/building-modules/16-testing.md similarity index 100% rename from docs/docs/building-modules/16-testing.md rename to docs/docs/build/building-modules/16-testing.md diff --git a/docs/docs/building-modules/_category_.json b/docs/docs/build/building-modules/_category_.json similarity index 100% rename from docs/docs/building-modules/_category_.json rename to docs/docs/build/building-modules/_category_.json diff --git a/docs/docs/migrations/01-intro.md b/docs/docs/build/migrations/01-intro.md similarity index 100% rename from docs/docs/migrations/01-intro.md rename to docs/docs/build/migrations/01-intro.md diff --git a/docs/docs/migrations/_category_.json b/docs/docs/build/migrations/_category_.json similarity index 100% rename from docs/docs/migrations/_category_.json rename to docs/docs/build/migrations/_category_.json diff --git a/docs/docs/modules/_category_.json b/docs/docs/build/modules/_category_.json similarity index 100% rename from docs/docs/modules/_category_.json rename to docs/docs/build/modules/_category_.json diff --git a/docs/docs/packages/_category_.json b/docs/docs/build/packages/_category_.json similarity index 100% rename from docs/docs/packages/_category_.json rename to docs/docs/build/packages/_category_.json diff --git a/docs/docs/tooling/_category_.json b/docs/docs/build/tooling/_category_.json similarity index 100% rename from docs/docs/tooling/_category_.json rename to docs/docs/build/tooling/_category_.json diff --git a/docs/docs/core/00-baseapp.md b/docs/docs/develop/advanced/00-baseapp.md similarity index 88% rename from docs/docs/core/00-baseapp.md rename to docs/docs/develop/advanced/00-baseapp.md index 3a0aa2651d5b..dd35bccbfc7d 100644 --- a/docs/docs/core/00-baseapp.md +++ b/docs/docs/develop/advanced/00-baseapp.md @@ -10,8 +10,8 @@ This document describes `BaseApp`, the abstraction that implements the core func :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) -* [Lifecycle of a Cosmos SDK transaction](../basics/01-tx-lifecycle.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) +* [Lifecycle of a Cosmos SDK transaction](../beginner/01-tx-lifecycle.md) ::: @@ -78,8 +78,8 @@ First, the important parameters that are initialized during the bootstrapping of * [`AnteHandler`](#antehandler): This handler is used to handle signature verification, fee payment, and other pre-message execution checks when a transaction is received. It's executed during [`CheckTx/RecheckTx`](#checktx) and [`FinalizeBlock`](#finalizeblock). -* [`InitChainer`](../basics/00-app-anatomy.md#initchainer), - [`BeginBlocker` and `EndBlocker`](../basics/00-app-anatomy.md#beginblocker-and-endblocker): These are +* [`InitChainer`](../beginner/00-app-anatomy.md#initchainer), + [`BeginBlocker` and `EndBlocker`](../beginner/00-app-anatomy.md#beginblocker-and-endblocker): These are the functions executed when the application receives the `InitChain` and `FinalizeBlock` ABCI messages from the underlying CometBFT engine. @@ -105,7 +105,7 @@ Finally, a few more important parameters: `minGasPrices` (e.g. if `minGasPrices == 1uatom,1photon`, the `gas-price` of the transaction must be greater than `1uatom` OR `1photon`). * `appVersion`: Version of the application. It is set in the - [application's constructor function](../basics/00-app-anatomy.md#constructor-function). + [application's constructor function](../beginner/00-app-anatomy.md#constructor-function). ## Constructor @@ -217,17 +217,17 @@ When messages and queries are received by the application, they must be routed t ### `Msg` Service Router -[`sdk.Msg`s](../building-modules/02-messages-and-queries.md#messages) need to be routed after they are extracted from transactions, which are sent from the underlying CometBFT engine via the [`CheckTx`](#checktx) and [`FinalizeBlock`](#finalizeblock) ABCI messages. To do so, `BaseApp` holds a `msgServiceRouter` which maps fully-qualified service methods (`string`, defined in each module's Protobuf `Msg` service) to the appropriate module's `MsgServer` implementation. +[`sdk.Msg`s](../../build/building-modules/02-messages-and-queries.md#messages) need to be routed after they are extracted from transactions, which are sent from the underlying CometBFT engine via the [`CheckTx`](#checktx) and [`FinalizeBlock`](#finalizeblock) ABCI messages. To do so, `BaseApp` holds a `msgServiceRouter` which maps fully-qualified service methods (`string`, defined in each module's Protobuf `Msg` service) to the appropriate module's `MsgServer` implementation. The [default `msgServiceRouter` included in `BaseApp`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/msg_service_router.go) is stateless. However, some applications may want to make use of more stateful routing mechanisms such as allowing governance to disable certain routes or point them to new modules for upgrade purposes. For this reason, the `sdk.Context` is also passed into each [route handler inside `msgServiceRouter`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/msg_service_router.go#L31-L32). For a stateless router that doesn't want to make use of this, you can just ignore the `ctx`. -The application's `msgServiceRouter` is initialized with all the routes using the application's [module manager](../building-modules/01-module-manager.md#manager) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/00-app-anatomy.md#constructor-function). +The application's `msgServiceRouter` is initialized with all the routes using the application's [module manager](../../build/building-modules/01-module-manager.md#manager) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../beginner/00-app-anatomy.md#constructor-function). ### gRPC Query Router -Similar to `sdk.Msg`s, [`queries`](../building-modules/02-messages-and-queries.md#queries) need to be routed to the appropriate module's [`Query` service](../building-modules/04-query-services.md). To do so, `BaseApp` holds a `grpcQueryRouter`, which maps modules' fully-qualified service methods (`string`, defined in their Protobuf `Query` gRPC) to their `QueryServer` implementation. The `grpcQueryRouter` is called during the initial stages of query processing, which can be either by directly sending a gRPC query to the gRPC endpoint, or via the [`Query` ABCI message](#query) on the CometBFT RPC endpoint. +Similar to `sdk.Msg`s, [`queries`](../../build/building-modules/02-messages-and-queries.md#queries) need to be routed to the appropriate module's [`Query` service](../../build/building-modules/04-query-services.md). To do so, `BaseApp` holds a `grpcQueryRouter`, which maps modules' fully-qualified service methods (`string`, defined in their Protobuf `Query` gRPC) to their `QueryServer` implementation. The `grpcQueryRouter` is called during the initial stages of query processing, which can be either by directly sending a gRPC query to the gRPC endpoint, or via the [`Query` ABCI message](#query) on the CometBFT RPC endpoint. -Just like the `msgServiceRouter`, the `grpcQueryRouter` is initialized with all the query routes using the application's [module manager](../building-modules/01-module-manager.md) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../basics/00-app-anatomy.md#app-constructor). +Just like the `msgServiceRouter`, the `grpcQueryRouter` is initialized with all the query routes using the application's [module manager](../../build/building-modules/01-module-manager.md) (via the `RegisterServices` method), which itself is initialized with all the application's modules in the application's [constructor](../beginner/00-app-anatomy.md#app-constructor). ## Main ABCI 2.0 Messages @@ -318,16 +318,16 @@ to do the following checks: first, as _stateless_ checks are less computationally expensive than _stateful_ checks. If `ValidateBasic()` fail, `CheckTx` returns before running _stateful_ checks, which saves resources. This check is still performed for messages that have not yet migrated to the new message validation mechanism defined in [RFC 001](https://docs.cosmos.network/main/rfc/rfc-001-tx-validation) and still have a `ValidateBasic()` method. -3. Perform non-module related _stateful_ checks on the [account](../basics/03-accounts.md). This step is mainly about checking +3. Perform non-module related _stateful_ checks on the [account](../beginner/03-accounts.md). This step is mainly about checking that the `sdk.Msg` signatures are valid, that enough fees are provided and that the sending account - has enough funds to pay for said fees. Note that no precise [`gas`](../basics/04-gas-fees.md) counting occurs here, - as `sdk.Msg`s are not processed. Usually, the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) will check that the `gas` provided + has enough funds to pay for said fees. Note that no precise [`gas`](../beginner/04-gas-fees.md) counting occurs here, + as `sdk.Msg`s are not processed. Usually, the [`AnteHandler`](../beginner/04-gas-fees.md#antehandler) will check that the `gas` provided with the transaction is superior to a minimum reference gas amount based on the raw transaction size, in order to avoid spam with transactions that provide 0 gas. `CheckTx` does **not** process `sdk.Msg`s - they only need to be processed when the canonical state need to be updated, which happens during `FinalizeBlock`. -Steps 2. and 3. are performed by the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) in the [`RunTx()`](#runtx-antehandler-and-runmsgs) +Steps 2. and 3. are performed by the [`AnteHandler`](../beginner/04-gas-fees.md#antehandler) in the [`RunTx()`](#runtx-antehandler-and-runmsgs) function, which `CheckTx()` calls with the `runTxModeCheck` mode. During each step of `CheckTx()`, a special [volatile state](#state-updates) called `checkState` is updated. This state is used to keep track of the temporary changes triggered by the `CheckTx()` calls of each transaction without modifying @@ -371,7 +371,7 @@ This allows certain checks like signature verification can be skipped during `Ch `RunTx` is called from `CheckTx`/`Finalizeblock` to handle the transaction, with `execModeCheck` or `execModeFinalize` as parameter to differentiate between the two modes of execution. Note that when `RunTx` receives a transaction, it has already been decoded. -The first thing `RunTx` does upon being called is to retrieve the `context`'s `CacheMultiStore` by calling the `getContextForTx()` function with the appropriate mode (either `runTxModeCheck` or `execModeFinalize`). This `CacheMultiStore` is a branch of the main store, with cache functionality (for query requests), instantiated during `FinalizeBlock` for transaction execution and during the `Commit` of the previous block for `CheckTx`. After that, two `defer func()` are called for [`gas`](../basics/04-gas-fees.md) management. They are executed when `runTx` returns and make sure `gas` is actually consumed, and will throw errors, if any. +The first thing `RunTx` does upon being called is to retrieve the `context`'s `CacheMultiStore` by calling the `getContextForTx()` function with the appropriate mode (either `runTxModeCheck` or `execModeFinalize`). This `CacheMultiStore` is a branch of the main store, with cache functionality (for query requests), instantiated during `FinalizeBlock` for transaction execution and during the `Commit` of the previous block for `CheckTx`. After that, two `defer func()` are called for [`gas`](../beginner/04-gas-fees.md) management. They are executed when `runTx` returns and make sure `gas` is actually consumed, and will throw errors, if any. After that, `RunTx()` calls `ValidateBasic()`, when available and for backward compatibility, on each `sdk.Msg`in the `Tx`, which runs preliminary _stateless_ validity checks. If any `sdk.Msg` fails to pass `ValidateBasic()`, `RunTx()` returns with an error. @@ -399,15 +399,15 @@ The `AnteHandler` is theoretically optional, but still a very important componen * Perform preliminary _stateful_ validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees. * Play a role in the incentivisation of stakeholders via the collection of transaction fees. -`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../basics/00-app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/ante/ante.go). +`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../beginner/00-app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/ante/ante.go). -Click [here](../basics/04-gas-fees.md#antehandler) for more on the `anteHandler`. +Click [here](../beginner/04-gas-fees.md#antehandler) for more on the `anteHandler`. ### RunMsgs `RunMsgs` is called from `RunTx` with `runTxModeCheck` as parameter to check the existence of a route for each message the transaction, and with `execModeFinalize` to actually process the `sdk.Msg`s. -First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `type_url` of the Protobuf `Any` representing the `sdk.Msg`. Then, using the application's [`msgServiceRouter`](#msg-service-router), it checks for the existence of `Msg` service method related to that `type_url`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. Otherwise, if `mode == execModeFinalize`, the [`Msg` service](../building-modules/03-msg-services.md) RPC is executed, before `RunMsgs` returns. +First, it retrieves the `sdk.Msg`'s fully-qualified type name, by checking the `type_url` of the Protobuf `Any` representing the `sdk.Msg`. Then, using the application's [`msgServiceRouter`](#msg-service-router), it checks for the existence of `Msg` service method related to that `type_url`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. Otherwise, if `mode == execModeFinalize`, the [`Msg` service](../../build/building-modules/03-msg-services.md) RPC is executed, before `RunMsgs` returns. ### PostHandler @@ -430,9 +430,9 @@ The [`InitChain` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x * [Consensus Parameters](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#consensus-parameters) via `setConsensusParams`. * [`checkState` and `finalizeBlockState`](#state-updates) via `setState`. -* The [block gas meter](../basics/04-gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions. +* The [block gas meter](../beginner/04-gas-fees.md#block-gas-meter), with infinite gas to process genesis transactions. -Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls the [`initChainer()`](../basics/00-app-anatomy.md#initchainer) of the application in order to initialize the main state of the application from the `genesis file` and, if defined, call the [`InitGenesis`](../building-modules/08-genesis.md#initgenesis) function of each of the application's modules. +Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls the [`initChainer()`](../beginner/00-app-anatomy.md#initchainer) of the application in order to initialize the main state of the application from the `genesis file` and, if defined, call the [`InitGenesis`](../../build/building-modules/08-genesis.md#initgenesis) function of each of the application's modules. ### FinalizeBlock @@ -452,10 +452,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci.go#L623 https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/baseapp.go#L682-L706 ``` - This function also resets the [main gas meter](../basics/04-gas-fees.md#main-gas-meter). + This function also resets the [main gas meter](../beginner/04-gas-fees.md#main-gas-meter). +<<<<<<< HEAD:docs/docs/core/00-baseapp.md * Initialize the [block gas meter](../basics/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. * Run the application's [`beginBlocker()`](../basics/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/05-beginblock-endblock.md#beginblock) method of each of the application's modules. +======= +* Initialize the [block gas meter](../beginner/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. +* Run the application's [`beginBlocker()`](../beginner/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../../build/building-modules/05-beginblock-endblock.md#beginblock) method of each of the non-upgrade modules. +>>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/develop/advanced/00-baseapp.md * Set the [`VoteInfos`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./02-context.md) so that it can be used during transaction execution and EndBlock. #### Transaction Execution @@ -471,7 +476,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/baseapp.go#LL7 Transaction execution within `FinalizeBlock` performs the **exact same steps as `CheckTx`**, with a little caveat at step 3 and the addition of a fifth step: 1. The `AnteHandler` does **not** check that the transaction's `gas-prices` is sufficient. That is because the `min-gas-prices` value `gas-prices` is checked against is local to the node, and therefore what is enough for one full-node might not be for another. This means that the proposer can potentially include transactions for free, although they are not incentivised to do so, as they earn a bonus on the total fee of the block they propose. -2. For each `sdk.Msg` in the transaction, route to the appropriate module's Protobuf [`Msg` service](../building-modules/03-msg-services.md). Additional _stateful_ checks are performed, and the branched multistore held in `finalizeBlockState`'s `context` is updated by the module's `keeper`. If the `Msg` service returns successfully, the branched multistore held in `context` is written to `finalizeBlockState` `CacheMultiStore`. +2. For each `sdk.Msg` in the transaction, route to the appropriate module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md). Additional _stateful_ checks are performed, and the branched multistore held in `finalizeBlockState`'s `context` is updated by the module's `keeper`. If the `Msg` service returns successfully, the branched multistore held in `context` is written to `finalizeBlockState` `CacheMultiStore`. 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: @@ -514,7 +519,7 @@ The [`Info` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec ### Query -The [`Query` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#info-methods) is used to serve queries received from the underlying consensus engine, including queries received via RPC like CometBFT RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../building-modules/04-query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#query). +The [`Query` ABCI message](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#info-methods) is used to serve queries received from the underlying consensus engine, including queries received via RPC like CometBFT RPC. It used to be the main entrypoint to build interfaces with the application, but with the introduction of [gRPC queries](../../build/building-modules/04-query-services.md) in Cosmos SDK v0.40, its usage is more limited. The application must respect a few rules when implementing the `Query` method, which are outlined [here](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_app_requirements.md#query). Each CometBFT `query` comes with a `path`, which is a `string` which denotes what to query. If the `path` matches a gRPC fully-qualified service method, then `BaseApp` will defer the query to the `grpcQueryRouter` and let it handle it like explained [above](#grpc-query-router). Otherwise, the `path` represents a query that is not (yet) handled by the gRPC router. `BaseApp` splits the `path` string with the `/` delimiter. By convention, the first element of the split string (`split[0]`) contains the category of `query` (`app`, `p2p`, `store` or `custom` ). The `BaseApp` implementation of the `Query(req abci.RequestQuery)` method is a simple dispatcher serving these 4 main categories of queries: diff --git a/docs/docs/core/01-transactions.md b/docs/docs/develop/advanced/01-transactions.md similarity index 78% rename from docs/docs/core/01-transactions.md rename to docs/docs/develop/advanced/01-transactions.md index dd29c472b250..eee4fae37976 100644 --- a/docs/docs/core/01-transactions.md +++ b/docs/docs/develop/advanced/01-transactions.md @@ -10,15 +10,15 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK Application](../beginner/00-app-anatomy.md) ::: ## Transactions -Transactions are comprised of metadata held in [contexts](./02-context.md) and [`sdk.Msg`s](../building-modules/02-messages-and-queries.md) that trigger state changes within a module through the module's Protobuf [`Msg` service](../building-modules/03-msg-services.md). +Transactions are comprised of metadata held in [contexts](./02-context.md) and [`sdk.Msg`s](../../build/building-modules/02-messages-and-queries.md) that trigger state changes within a module through the module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md). -When users want to interact with an application and make state changes (e.g. sending coins), they create transactions. Each of a transaction's `sdk.Msg` must be signed using the private key associated with the appropriate account(s), before the transaction is broadcasted to the network. A transaction must then be included in a block, validated, and approved by the network through the consensus process. To read more about the lifecycle of a transaction, click [here](../basics/01-tx-lifecycle.md). +When users want to interact with an application and make state changes (e.g. sending coins), they create transactions. Each of a transaction's `sdk.Msg` must be signed using the private key associated with the appropriate account(s), before the transaction is broadcasted to the network. A transaction must then be included in a block, validated, and approved by the network through the consensus process. To read more about the lifecycle of a transaction, click [here](../beginner/01-tx-lifecycle.md). ## Type Definition @@ -31,10 +31,10 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L51-L5 It contains the following methods: * **GetMsgs:** unwraps the transaction and returns a list of contained `sdk.Msg`s - one transaction may have one or multiple messages, which are defined by module developers. -* **ValidateBasic:** lightweight, [_stateless_](../basics/01-tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./00-baseapp.md#checktx) and [`DeliverTx`](./00-baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth) module's `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. When [`runTx`](./00-baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself. +* **ValidateBasic:** lightweight, [_stateless_](../beginner/01-tx-lifecycle.md#types-of-checks) checks used by ABCI messages [`CheckTx`](./00-baseapp.md#checktx) and [`DeliverTx`](./00-baseapp.md#delivertx) to make sure transactions are not invalid. For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth) module's `ValidateBasic` function checks that its transactions are signed by the correct number of signers and that the fees do not exceed what the user's maximum. When [`runTx`](./00-baseapp.md#runtx) is checking a transaction created from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/spec) module, it first runs `ValidateBasic` on each message, then runs the `auth` module AnteHandler which calls `ValidateBasic` for the transaction itself. :::note - This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../basics/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. + This function is different from the deprecated `sdk.Msg` [`ValidateBasic`](../beginner/01-tx-lifecycle.md#ValidateBasic) methods, which was performing basic validity checks on messages only. ::: As a developer, you should rarely manipulate `Tx` directly, as `Tx` is really an intermediate type used for transaction generation. Instead, developers should prefer the `TxBuilder` interface, which you can learn more about [below](#transaction-generation). @@ -51,7 +51,7 @@ The most used implementation of the `Tx` interface is the Protobuf `Tx` message, https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L13-L26 ``` -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)): +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](../../build/architecture/adr-027-deterministic-protobuf-serialization.md)): ```protobuf reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/tx.proto#L48-L65 @@ -117,12 +117,12 @@ The next paragraphs will describe each of these components, in this order. Module `sdk.Msg`s are not to be confused with [ABCI Messages](https://docs.cometbft.com/v0.37/spec/abci/) which define interactions between the CometBFT and application layers. ::: -**Messages** (or `sdk.Msg`s) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the messages for their module by adding methods to the Protobuf [`Msg` service](../building-modules/03-msg-services.md), and also implement the corresponding `MsgServer`. +**Messages** (or `sdk.Msg`s) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define the messages for their module by adding methods to the Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md), and also implement the corresponding `MsgServer`. -Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../building-modules/03-msg-services.md) RPC, defined inside each module's `tx.proto` file. A SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface. +Each `sdk.Msg`s is related to exactly one Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) RPC, defined inside each module's `tx.proto` file. A SDK app router automatically maps every `sdk.Msg` to a corresponding RPC. Protobuf generates a `MsgServer` interface for each module `Msg` service, and the module developer needs to implement this interface. This design puts more responsibility on module developers, allowing application developers to reuse common functionalities without having to implement state transition logic repetitively. -To learn more about Protobuf `Msg` services and how to implement `MsgServer`, click [here](../building-modules/03-msg-services.md). +To learn more about Protobuf `Msg` services and how to implement `MsgServer`, click [here](../../build/building-modules/03-msg-services.md). While messages contain the information for state transition logic, a transaction's other metadata and relevant information are stored in the `TxBuilder` and `Context`. @@ -170,9 +170,9 @@ Once the transaction bytes are generated, there are currently three ways of broa #### CLI -Application developers create entry points to the application by creating a [command-line interface](../core/07-cli.md), [gRPC and/or REST interface](../core/06-grpc_rest.md), typically found in the application's `./cmd` folder. These interfaces allow users to interact with the application through command-line. +Application developers create entry points to the application by creating a [command-line interface](./07-cli.md), [gRPC and/or REST interface](./06-grpc_rest.md), typically found in the application's `./cmd` folder. These interfaces allow users to interact with the application through command-line. -For the [command-line interface](../building-modules/09-module-interfaces.md#cli), module developers create subcommands to add as children to the application top-level transaction command `TxCmd`. CLI commands actually bundle all the steps of transaction processing into one simple command: creating messages, generating transactions and broadcasting. For concrete examples, see the [Interacting with a Node](../run-node/02-interact-node.md) section. An example transaction made using CLI looks like: +For the [command-line interface](../../build/building-modules/09-module-interfaces.md#cli), module developers create subcommands to add as children to the application top-level transaction command `TxCmd`. CLI commands actually bundle all the steps of transaction processing into one simple command: creating messages, generating transactions and broadcasting. For concrete examples, see the [Interacting with a Node](../../user/run-node/02-interact-node.md) section. An example transaction made using CLI looks like: ```bash simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake @@ -180,7 +180,7 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake #### gRPC -[gRPC](https://grpc.io) is the main component for the Cosmos SDK's RPC layer. Its principal usage is in the context of modules' [`Query` services](../building-modules/04-query-services.md). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service: +[gRPC](https://grpc.io) is the main component for the Cosmos SDK's RPC layer. Its principal usage is in the context of modules' [`Query` services](../../build/building-modules/04-query-services.md). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta1/service.proto @@ -188,13 +188,13 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/tx/v1beta The `Tx` service exposes a handful of utility functions, such as simulating a transaction or querying a transaction, and also one method to broadcast transactions. -Examples of broadcasting and simulating a transaction are shown [here](../run-node/03-txs.md#programmatically-with-go). +Examples of broadcasting and simulating a transaction are shown [here](../../user/run-node/03-txs.md#programmatically-with-go). #### REST Each gRPC method has its corresponding REST endpoint, generated using [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway). Therefore, instead of using gRPC, you can also use HTTP to broadcast the same transaction, on the `POST /cosmos/tx/v1beta1/txs` endpoint. -An example can be seen [here](../run-node/03-txs.md#using-rest) +An example can be seen [here](../../user/run-node/03-txs.md#using-rest) #### CometBFT RPC diff --git a/docs/docs/core/02-context.md b/docs/docs/develop/advanced/02-context.md similarity index 85% rename from docs/docs/core/02-context.md rename to docs/docs/develop/advanced/02-context.md index 77397b0df452..4d9ecdf690ff 100644 --- a/docs/docs/core/02-context.md +++ b/docs/docs/develop/advanced/02-context.md @@ -10,8 +10,8 @@ The `context` is a data structure intended to be passed from function to functio :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) -* [Lifecycle of a Transaction](../basics/01-tx-lifecycle.md) +* [Anatomy of a Cosmos SDK Application](../beginner/00-app-anatomy.md) +* [Lifecycle of a Transaction](../beginner/01-tx-lifecycle.md) ::: @@ -28,12 +28,12 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/context.go#L41-L * **Header:** The [header](https://docs.cometbft.com/v0.37/spec/core/data_structures#header) is a Blockchain type. It carries important information about the state of the blockchain, such as block height and proposer of the current block. * **Header Hash:** The current block header hash, obtained during `abci.FinalizeBlock`. * **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 Cosmos SDK and consensus engine (e.g. CometBFT) throughout its [lifecycle](../basics/01-tx-lifecycle.md), some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./05-encoding.md) such as [Amino](./05-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. CometBFT) throughout its [lifecycle](../beginner/01-tx-lifecycle.md), some of which do not have any understanding of transaction types. Thus, transactions are marshaled into the generic `[]byte` type using some kind of [encoding format](./05-encoding.md) such as [Amino](./05-encoding.md). * **Logger:** A `logger` from the CometBFT libraries. Learn more about logs [here](https://docs.cometbft.com/v0.37/core/configuration). Modules call this method to create their own unique module-specific logger. * **VoteInfo:** A list of the ABCI type [`VoteInfo`](https://docs.cometbft.com/master/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/04-gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../basics/04-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/04-gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts. +* **Gas Meters:** Specifically, a [`gasMeter`](../beginner/04-gas-fees.md#main-gas-meter) for the transaction currently being processed using the context and a [`blockGasMeter`](../beginner/04-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](../beginner/04-gas-fees.md) has been used in the transaction or block so far. If the gas meter runs out, execution halts. * **CheckTx Mode:** A boolean value indicating whether a transaction should be processed in `CheckTx` or `DeliverTx` mode. -* **Min Gas Price:** The minimum [gas](../basics/04-gas-fees.md) price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore **not be used in any functions used in sequences leading to state-transitions**. +* **Min Gas Price:** The minimum [gas](../beginner/04-gas-fees.md) price a node is willing to take in order to include a transaction in its block. This price is a local value configured by each node individually, and should therefore **not be used in any functions used in sequences leading to state-transitions**. * **Consensus Params:** The ABCI type [Consensus Parameters](https://docs.cometbft.com/master/spec/abci/apps.html#consensus-parameters), which specify certain limits for the blockchain, such as maximum gas for a block. * **Event Manager:** The event manager allows any caller with access to a `Context` to emit [`Events`](./08-events.md). Modules may define module specific `Events` by defining various `Types` and `Attributes` or use the common definitions found in `types/`. Clients can subscribe or query for these `Events`. These `Events` are collected throughout `FinalizeBlock` and are returned to CometBFT for indexing. diff --git a/docs/docs/core/03-node.md b/docs/docs/develop/advanced/03-node.md similarity index 94% rename from docs/docs/core/03-node.md rename to docs/docs/develop/advanced/03-node.md index 5ac391b25370..47b691b32c6b 100644 --- a/docs/docs/core/03-node.md +++ b/docs/docs/develop/advanced/03-node.md @@ -10,7 +10,7 @@ The main endpoint of a Cosmos SDK application is the daemon client, otherwise kn :::note Pre-requisite Readings -* [Anatomy of an SDK application](../basics/00-app-anatomy.md) +* [Anatomy of an SDK application](../beginner/00-app-anatomy.md) ::: @@ -21,7 +21,7 @@ The full-node client of any Cosmos SDK application is built by running a `main` In general, developers will implement the `main.go` function with the following structure: * First, an [`encodingCodec`](./05-encoding.md) is instantiated for the application. -* Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../basics/03-accounts.md#addresses). +* Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../beginner/03-accounts.md#addresses). ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/config.go#L14-L29 @@ -69,7 +69,7 @@ Note that an `appCreator` is a function that fulfills the `AppCreator` signature https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L68 ``` -In practice, the [constructor of the application](../basics/00-app-anatomy.md#constructor-function) is passed as the `appCreator`. +In practice, the [constructor of the application](../beginner/00-app-anatomy.md#constructor-function) is passed as the `appCreator`. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L294-L308 @@ -93,4 +93,4 @@ Upon starting, the node will bootstrap its RPC and P2P server and start dialing ## Other commands -To discover how to concretely run a node and interact with it, please refer to our [Running a Node, API and CLI](../run-node/01-run-node.md) guide. +To discover how to concretely run a node and interact with it, please refer to our [Running a Node, API and CLI](../../user/run-node/01-run-node.md) guide. diff --git a/docs/docs/core/04-store.md b/docs/docs/develop/advanced/04-store.md similarity index 94% rename from docs/docs/core/04-store.md rename to docs/docs/develop/advanced/04-store.md index bc979b6ba085..35f67665752a 100644 --- a/docs/docs/core/04-store.md +++ b/docs/docs/develop/advanced/04-store.md @@ -10,13 +10,13 @@ A store is a data structure that holds the state of the application. :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) ::: ## 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 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/06-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`](../../build/building-modules/06-keeper.md) of the module that declared the store. ```text +-----------------------------------------------------+ @@ -136,9 +136,9 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/cachemulti/store A `KVStore` is a simple key-value store used to store and retrieve data. A `CommitKVStore` is a `KVStore` that also implements a `Committer`. By default, stores mounted in `baseapp`'s main `CommitMultiStore` are `CommitKVStore`s. The `KVStore` interface is primarily used to restrict modules from accessing the committer. -Individual `KVStore`s are used by modules to manage a subset of the global state. `KVStores` can be accessed by objects that hold a specific key. This `key` should only be exposed to the [`keeper`](../building-modules/06-keeper.md) of the module that defines the store. +Individual `KVStore`s are used by modules to manage a subset of the global state. `KVStores` can be accessed by objects that hold a specific key. This `key` should only be exposed to the [`keeper`](../../build/building-modules/06-keeper.md) of the module that defines the store. -`CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../basics/00-app-anatomy.md#core-application-file). In the same file, the `key` is also passed to the module's `keeper` that is responsible for managing the store. +`CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../beginner/00-app-anatomy.md#core-application-file). In the same file, the `key` is also passed to the module's `keeper` that is responsible for managing the store. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/types/store.go#L229-L266 @@ -224,7 +224,7 @@ This is the type used whenever an IAVL Store needs to be branched to create an i ### `GasKv` Store -Cosmos SDK applications use [`gas`](../basics/04-gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications. +Cosmos SDK applications use [`gas`](../beginner/04-gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications. ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/store/gaskv/store.go#L11-L17 diff --git a/docs/docs/core/05-encoding.md b/docs/docs/develop/advanced/05-encoding.md similarity index 91% rename from docs/docs/core/05-encoding.md rename to docs/docs/develop/advanced/05-encoding.md index 202609420ac6..6253ba166a11 100644 --- a/docs/docs/core/05-encoding.md +++ b/docs/docs/develop/advanced/05-encoding.md @@ -10,7 +10,7 @@ While encoding in the Cosmos SDK used to be mainly handled by `go-amino` codec, :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) ::: @@ -127,7 +127,7 @@ the consensus engine accepts only transactions in the form of raw bytes. https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L91-L95 ``` -A standard implementation of both these objects can be found in the [`auth/tx` module](../modules/auth/tx/README.md): +A standard implementation of both these objects can be found in the [`auth/tx` module](../../build/modules/auth/2-tx.md): ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/decoder.go @@ -137,11 +137,11 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/decoder.go https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/auth/tx/encoder.go ``` -See [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. +See [ADR-020](../../build/architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. ### Interface Encoding and Usage of `Any` -The Protobuf DSL is strongly typed, which can make inserting variable-typed fields difficult. Imagine we want to create a `Profile` protobuf message that serves as a wrapper over [an account](../basics/03-accounts.md): +The Protobuf DSL is strongly typed, which can make inserting variable-typed fields difficult. Imagine we want to create a `Profile` protobuf message that serves as a wrapper over [an account](../beginner/03-accounts.md): ```protobuf message Profile { @@ -152,13 +152,13 @@ message Profile { } ``` -In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../modules/auth/1-vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface? +In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../../build/modules/auth/1-vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface? ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/account.go#L15-L32 ``` -In [ADR-019](../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: +In [ADR-019](../../build/architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: ```protobuf message Profile { @@ -227,7 +227,7 @@ func (p *Profile) UnpackInterfaces(unpacker codectypes.AnyUnpacker) error { The `UnpackInterfaces` gets called recursively on all structs implementing this method, to allow all `Any`s to have their `GetCachedValue()` correctly populated. -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). +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](../../build/architecture/adr-019-protobuf-state-encoding.md). #### `Any` Encoding in the Cosmos SDK @@ -285,14 +285,14 @@ import ( Protobuf types can be defined to encode: * state -* [`Msg`s](../building-modules/02-messages-and-queries.md#messages) -* [Query services](../building-modules/04-query-services.md) -* [genesis](../building-modules/08-genesis.md) +* [`Msg`s](../../build/building-modules/02-messages-and-queries.md#messages) +* [Query services](../../build/building-modules/04-query-services.md) +* [genesis](../../build/building-modules/08-genesis.md) #### Naming and conventions We encourage developers to follow industry guidelines: [Protocol Buffers style guide](https://developers.google.com/protocol-buffers/docs/style) -and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../architecture/adr-023-protobuf-naming.md) +and [Buf](https://buf.build/docs/style-guide), see more details in [ADR 023](../../build/architecture/adr-023-protobuf-naming.md) ### How to update modules to protobuf encoding diff --git a/docs/docs/core/06-grpc_rest.md b/docs/docs/develop/advanced/06-grpc_rest.md similarity index 92% rename from docs/docs/core/06-grpc_rest.md rename to docs/docs/develop/advanced/06-grpc_rest.md index 7f5923ca8922..f9ef118a3979 100644 --- a/docs/docs/core/06-grpc_rest.md +++ b/docs/docs/develop/advanced/06-grpc_rest.md @@ -28,13 +28,13 @@ All endpoints are defaulted to localhost and must be modified to be exposed to t In the Cosmos SDK, Protobuf is the main [encoding](./encoding) library. 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/02-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: +Each module exposes a [Protobuf `Query` service](../../build/building-modules/02-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: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L46-L48 ``` -Note: It is not possible to expose any [Protobuf `Msg` service](../building-modules/02-messages-and-queries.md#messages) endpoints via gRPC. Transactions must be generated and signed using the CLI or programmatically before they can be broadcasted using gRPC. See [Generating, Signing, and Broadcasting Transactions](../run-node/03-txs.md) for more information. +Note: It is not possible to expose any [Protobuf `Msg` service](../../build/building-modules/02-messages-and-queries.md#messages) endpoints via gRPC. Transactions must be generated and signed using the CLI or programmatically before they can be broadcasted using gRPC. See [Generating, Signing, and Broadcasting Transactions](../../user/run-node/03-txs.md) for more information. The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC query requests and a broadcast transaction request. This server can be configured inside `~/.simapp/config/app.toml`: @@ -45,7 +45,7 @@ The `grpc.Server` is a concrete gRPC server, which spawns and serves all gRPC qu `~/.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/02-interact-node.md#using-grpc) tutorial. +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](../../user/run-node/02-interact-node.md#using-grpc) tutorial. An overview of all available gRPC endpoints shipped with the Cosmos SDK is [Protobuf documentation](https://buf.build/cosmos/cosmos-sdk). diff --git a/docs/docs/core/07-cli.md b/docs/docs/develop/advanced/07-cli.md similarity index 80% rename from docs/docs/core/07-cli.md rename to docs/docs/develop/advanced/07-cli.md index 5d2be5c03cb9..bbe2ca4ef8f2 100644 --- a/docs/docs/core/07-cli.md +++ b/docs/docs/develop/advanced/07-cli.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Command-Line Interface :::note Synopsis -This document describes how command-line interface (CLI) works on a high-level, for an [**application**](../basics/00-app-anatomy.md). A separate document for implementing a CLI for a Cosmos SDK [**module**](../building-modules/01-intro.md) can be found [here](../building-modules/09-module-interfaces.md#cli). +This document describes how command-line interface (CLI) works on a high-level, for an [**application**](../beginner/00-app-anatomy.md). A separate document for implementing a CLI for a Cosmos SDK [**module**](../../build/building-modules/01-intro.md) can be found [here](../../build/building-modules/09-module-interfaces.md#cli). ::: ## Command-Line Interface @@ -24,12 +24,12 @@ The first four strings specify the command: * The root command for the entire application `simd`. * The subcommand `tx`, which contains all commands that let users create transactions. -* The subcommand `bank` to indicate which module to route the command to ([`x/bank`](../modules/bank/README.md) module in this case). +* The subcommand `bank` to indicate which module to route the command to ([`x/bank`](../../build/modules/bank/README.md) module in this case). * The type of transaction `send`. The next two strings are arguments: the `from_address` the user wishes to send from, the `to_address` of the recipient, and the `amount` they want to send. Finally, the last few strings of the command are optional flags to indicate how much the user is willing to pay in fees (calculated using the amount of gas used to execute the transaction and the gas prices provided by the user). -The CLI interacts with a [node](../core/03-node.md) to handle this command. The interface itself is defined in a `main.go` file. +The CLI interacts with a [node](./03-node.md) to handle this command. The interface itself is defined in a `main.go` file. ### Building the CLI @@ -37,7 +37,7 @@ The `main.go` file needs to have a `main()` function that creates a root command * **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 injecting the application codecs. The [`codec`](../core/05-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. +* **instantiating the `codec`** by injecting the application codecs. The [`codec`](./05-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). The `main()` function finally creates an executor and [execute](https://pkg.go.dev/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application: @@ -56,8 +56,8 @@ 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 Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](../core/03-node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`. -* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.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 ` 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.50.0-alpha.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/00-keyring.md). +* **Status** command from the Cosmos SDK rpc client tools, which prints information about the status of the connected [`Node`](./03-node.md). The Status of a node includes `NodeInfo`,`SyncInfo` and `ValidatorInfo`. +* **Keys** [commands](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.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 ` 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.50.0-alpha.0/client/keys/add.go). For more details about usage of `--keyring-backend` for storage of key credentials look at the [keyring docs](../../user/run-node/00-keyring.md). * **Server** commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI CometBFT application and provides the CLI framework (based on [cobra](https://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. Learn more [here](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server). * [**Transaction**](#transaction-commands) commands. @@ -93,7 +93,7 @@ The root-level `status` and `keys` subcommands are common across most applicatio ### Transaction Commands -[Transactions](./01-transactions.md) are objects wrapping [`Msg`s](../building-modules/02-messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCommand` is generally added to the `rootCmd`: +[Transactions](./01-transactions.md) are objects wrapping [`Msg`s](../../build/building-modules/02-messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCommand` is generally added to the `rootCmd`: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L222-L229 @@ -101,9 +101,9 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v This `txCommand` function adds all the transaction available to end-users for the application. This typically includes: -* **Sign command** from the [`auth`](../modules/auth/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. +* **Sign command** from the [`auth`](../../build/modules/auth/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 Cosmos SDK client tools, to broadcast transactions. -* **All [module transaction commands](../building-modules/09-module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/01-module-manager.md#basic-manager) `AddTxCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). +* **All [module transaction commands](../../build/building-modules/09-module-interfaces.md#transaction-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#basic-manager) `AddTxCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). Here is an example of a `txCommand` aggregating these subcommands from the `simapp` application: @@ -118,7 +118,7 @@ Read more about [AutoCLI](https://docs.cosmos.network/main/core/autocli) in its ### Query Commands -[**Queries**](../building-modules/02-messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of queries using the CLI interface, a function `queryCommand` is generally added to the `rootCmd`: +[**Queries**](../../build/building-modules/02-messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of queries using the CLI interface, a function `queryCommand` is generally added to the `rootCmd`: ```go reference https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/simd/cmd/root_v2.go#L222-L229 @@ -130,7 +130,7 @@ This `queryCommand` function adds all the queries available to end-users for the * **Account command** from the `auth` module, which displays the state (e.g. account balance) of an account given an address. * **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/09-module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../building-modules/01-module-manager.md#basic-manager) `AddQueryCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). +* **All [module query commands](../../build/building-modules/09-module-interfaces.md#query-commands)** the application is dependent on, retrieved by using the [basic module manager's](../../build/building-modules/01-module-manager.md#basic-manager) `AddQueryCommands()` function, or enhanced by [AutoCLI](https://docs.cosmos.network/main/core/autocli). Here is an example of a `queryCommand` aggregating subcommands from the `simapp` application: @@ -145,11 +145,11 @@ Read more about [AutoCLI](https://docs.cosmos.network/main/core/autocli) in its ## Flags -Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with. +Flags are used to modify commands; developers can include them in a `flags.go` file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their [`app.toml`](../../user/run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). Commonly pre-configured flags include the `--node` to connect to and `--chain-id` of the blockchain the user wishes to interact with. A *persistent* flag (as opposed to a *local* flag) added to a command transcends all of its children: subcommands will inherit the configured values for these flags. Additionally, all flags have default values when they are added to commands; some toggle an option off but others are empty values that the user needs to override to create valid commands. A flag can be explicitly marked as *required* so that an error is automatically thrown if the user does not provide a value, but it is also acceptable to handle unexpected missing flags differently. -Flags are added to commands directly (generally in the [module's CLI file](../building-modules/09-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. +Flags are added to commands directly (generally in the [module's CLI file](../../build/building-modules/09-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. ## Environment variables diff --git a/docs/docs/core/08-events.md b/docs/docs/develop/advanced/08-events.md similarity index 91% rename from docs/docs/core/08-events.md rename to docs/docs/develop/advanced/08-events.md index e063a991cdaa..410e20ade09d 100644 --- a/docs/docs/core/08-events.md +++ b/docs/docs/develop/advanced/08-events.md @@ -9,7 +9,7 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK application](../beginner/00-app-anatomy.md) * [CometBFT Documentation on Events](https://docs.cometbft.com/v0.37/spec/abci/abci++_basic_concepts#events) ::: @@ -33,10 +33,10 @@ An Event contains: To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value. ::: -_Typed Events_ are Protobuf-defined [messages](../architecture/adr-032-typed-events.md) used by the Cosmos SDK +_Typed Events_ are Protobuf-defined [messages](../../build/architecture/adr-032-typed-events.md) used by the Cosmos SDK for emitting and querying Events. They are defined in a `event.proto` file, on a **per-module basis** and are read as `proto.Message`. _Legacy Events_ are defined on a **per-module basis** in the module's `/types/events.go` file. -They are triggered from the module's Protobuf [`Msg` service](../building-modules/03-msg-services.md) +They are triggered from the module's Protobuf [`Msg` service](../../build/building-modules/03-msg-services.md) by using the [`EventManager`](#eventmanager). In addition, each module documents its events under in the `Events` sections of its specs (x/{moduleName}/`README.md`). @@ -55,9 +55,9 @@ The following examples show how to query Events using the Cosmos SDK. | Event | Description | | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tx.height=23` | Query all transactions at height 23 | -| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../building-modules/03-msg-services.md). Note the `'`s around the value. | +| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../../build/building-modules/03-msg-services.md). Note the `'`s around the value. | | `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | -| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../modules/staking/README.md). | +| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../build/modules/staking/README.md). | ## EventManager @@ -98,7 +98,7 @@ ctx.EventManager().EmitEvent( Where the `EventManager` is accessed via the [`Context`](./02-context.md). -See the [`Msg` services](../building-modules/03-msg-services.md) concept doc for a more detailed +See the [`Msg` services](../../build/building-modules/03-msg-services.md) concept doc for a more detailed view on how to typically implement Events and use the `EventManager` in modules. ## Subscribing to Events @@ -140,7 +140,7 @@ Subscribing to this Event would be done like so: } ``` -where `ownerAddress` is an address following the [`AccAddress`](../basics/03-accounts.md#addresses) format. +where `ownerAddress` is an address following the [`AccAddress`](../beginner/03-accounts.md#addresses) format. The same way can be used to subscribe to [legacy events](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/bank/types/events.go). diff --git a/docs/docs/core/09-telemetry.md b/docs/docs/develop/advanced/09-telemetry.md similarity index 100% rename from docs/docs/core/09-telemetry.md rename to docs/docs/develop/advanced/09-telemetry.md diff --git a/docs/docs/core/10-ocap.md b/docs/docs/develop/advanced/10-ocap.md similarity index 100% rename from docs/docs/core/10-ocap.md rename to docs/docs/develop/advanced/10-ocap.md diff --git a/docs/docs/core/11-runtx_middleware.md b/docs/docs/develop/advanced/11-runtx_middleware.md similarity index 89% rename from docs/docs/core/11-runtx_middleware.md rename to docs/docs/develop/advanced/11-runtx_middleware.md index 76700fd959ba..f083a77888e5 100644 --- a/docs/docs/core/11-runtx_middleware.md +++ b/docs/docs/develop/advanced/11-runtx_middleware.md @@ -8,7 +8,7 @@ sidebar_position: 1 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 Cosmos SDK application developers. -More context can found in the corresponding [ADR-022](../architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go). +More context can found in the corresponding [ADR-022](../../build/architecture/adr-022-custom-panic-handling.md) and the implementation in [recovery.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/recovery.go). ## Interface diff --git a/docs/docs/core/12-simulation.md b/docs/docs/develop/advanced/12-simulation.md similarity index 97% rename from docs/docs/core/12-simulation.md rename to docs/docs/develop/advanced/12-simulation.md index ff65f33052e0..dfbcddd0d29f 100644 --- a/docs/docs/core/12-simulation.md +++ b/docs/docs/develop/advanced/12-simulation.md @@ -94,8 +94,8 @@ Here are some suggestions when encountering a simulation failure: ## Use simulation in your Cosmos SDK-based application -Learn how you can integrate the simulation into your Cosmos SDK-based application: +Learn how you can build the simulation into your Cosmos SDK-based application: * Application Simulation Manager -* [Building modules: Simulator](../building-modules/14-simulator.md) +* [Building modules: Simulator](../../build/building-modules/14-simulator.md) * Simulator tests diff --git a/docs/docs/core/13-proto-docs.md b/docs/docs/develop/advanced/13-proto-docs.md similarity index 100% rename from docs/docs/core/13-proto-docs.md rename to docs/docs/develop/advanced/13-proto-docs.md diff --git a/docs/docs/core/14-tips.md b/docs/docs/develop/advanced/14-tips.md similarity index 100% rename from docs/docs/core/14-tips.md rename to docs/docs/develop/advanced/14-tips.md diff --git a/docs/docs/core/15-upgrade.md b/docs/docs/develop/advanced/15-upgrade.md similarity index 97% rename from docs/docs/core/15-upgrade.md rename to docs/docs/develop/advanced/15-upgrade.md index b5db25589658..e926bc5dffab 100644 --- a/docs/docs/core/15-upgrade.md +++ b/docs/docs/develop/advanced/15-upgrade.md @@ -16,7 +16,7 @@ The Cosmos SDK uses two methods to perform upgrades: * Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. -* Perform upgrades in place, which significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/13-upgrade.md) to set up your application modules to take advantage of in-place upgrades. +* Perform upgrades in place, which significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../../build/building-modules/13-upgrade.md) to set up your application modules to take advantage of in-place upgrades. This document provides steps to use the In-Place Store Migrations upgrade method. @@ -63,7 +63,7 @@ app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgrad }) ``` -To learn more about configuring migration scripts for your modules, see the [Module Upgrade Guide](../building-modules/13-upgrade.md). +To learn more about configuring migration scripts for your modules, see the [Module Upgrade Guide](../../build/building-modules/13-upgrade.md). ### Order Of Migrations diff --git a/docs/docs/core/16-config.md b/docs/docs/develop/advanced/16-config.md similarity index 100% rename from docs/docs/core/16-config.md rename to docs/docs/develop/advanced/16-config.md diff --git a/docs/docs/core/_category_.json b/docs/docs/develop/advanced/_category_.json similarity index 100% rename from docs/docs/core/_category_.json rename to docs/docs/develop/advanced/_category_.json diff --git a/docs/docs/core/baseapp_state-begin_block.png b/docs/docs/develop/advanced/baseapp_state-begin_block.png similarity index 100% rename from docs/docs/core/baseapp_state-begin_block.png rename to docs/docs/develop/advanced/baseapp_state-begin_block.png diff --git a/docs/docs/core/baseapp_state-checktx.png b/docs/docs/develop/advanced/baseapp_state-checktx.png similarity index 100% rename from docs/docs/core/baseapp_state-checktx.png rename to docs/docs/develop/advanced/baseapp_state-checktx.png diff --git a/docs/docs/core/baseapp_state-commit.png b/docs/docs/develop/advanced/baseapp_state-commit.png similarity index 100% rename from docs/docs/core/baseapp_state-commit.png rename to docs/docs/develop/advanced/baseapp_state-commit.png diff --git a/docs/docs/core/baseapp_state-deliver_tx.png b/docs/docs/develop/advanced/baseapp_state-deliver_tx.png similarity index 100% rename from docs/docs/core/baseapp_state-deliver_tx.png rename to docs/docs/develop/advanced/baseapp_state-deliver_tx.png diff --git a/docs/docs/core/baseapp_state-initchain.png b/docs/docs/develop/advanced/baseapp_state-initchain.png similarity index 100% rename from docs/docs/core/baseapp_state-initchain.png rename to docs/docs/develop/advanced/baseapp_state-initchain.png diff --git a/docs/docs/core/baseapp_state-prepareproposal.png b/docs/docs/develop/advanced/baseapp_state-prepareproposal.png similarity index 100% rename from docs/docs/core/baseapp_state-prepareproposal.png rename to docs/docs/develop/advanced/baseapp_state-prepareproposal.png diff --git a/docs/docs/core/baseapp_state-processproposal.png b/docs/docs/develop/advanced/baseapp_state-processproposal.png similarity index 100% rename from docs/docs/core/baseapp_state-processproposal.png rename to docs/docs/develop/advanced/baseapp_state-processproposal.png diff --git a/docs/docs/core/baseapp_state.png b/docs/docs/develop/advanced/baseapp_state.png similarity index 100% rename from docs/docs/core/baseapp_state.png rename to docs/docs/develop/advanced/baseapp_state.png diff --git a/docs/docs/basics/00-app-anatomy.md b/docs/docs/develop/beginner/00-app-anatomy.md similarity index 65% rename from docs/docs/basics/00-app-anatomy.md rename to docs/docs/develop/beginner/00-app-anatomy.md index 005bbafb0ece..4d924ba05da9 100644 --- a/docs/docs/basics/00-app-anatomy.md +++ b/docs/docs/develop/beginner/00-app-anatomy.md @@ -10,7 +10,7 @@ This document describes the core parts of a Cosmos SDK application, represented ## Node Client -The Daemon, or [Full-Node Client](../core/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. +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 ^ +-------------------------------+ ^ @@ -30,9 +30,9 @@ Blockchain Node | | Consensus | | 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`](../core/03-node.md#main-function) function placed in `./cmd/appd/`. This operation usually happens through the [Makefile](#dependencies-and-makefile). +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](../core/03-node.md#start-command). This command function primarily does three things: +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`. @@ -50,12 +50,12 @@ In general, the core of the state-machine is defined in a file called `app.go`. 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`](../core/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](../core/00-baseapp.md#routing). -* **A list of store keys**. The [store](../core/04-store.md), which contains the entire state, is implemented as a [`multistore`](../core/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](../core/10-ocap.md) of the Cosmos SDK. -* **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../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`](../core/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](../core/05-encoding.md). -* **A reference to a [`legacyAmino`](../core/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](../building-modules/01-module-manager.md#manager)** and a [basic module manager](../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](../core/00-baseapp.md#msg-services) and [gRPC `Query` service](../core/00-baseapp.md#grpc-query-services), or setting the order of execution between modules for various functions like [`InitChainer`](#initchainer), [`BeginBlocker` and `EndBlocker`](#beginblocker-and-endblocker). +* **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), [`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: @@ -65,7 +65,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L173-L21 ### 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](../core/03-node.md#start-command) of the application's daemon command. +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 @@ -73,17 +73,17 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/server/types/app.go#L6 Here are the main actions performed by this function: -* Instantiate a new [`codec`](../core/05-encoding.md) and initialize the `codec` of each of the application's modules using the [basic manager](../building-modules/01-module-manager.md#basicmanager). +* 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](../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](../core/00-baseapp.md#msg-services), [gRPC `Query` services](../core/00-baseapp.md#grpc-query-services), [legacy `Msg` routes](../core/00-baseapp.md#routing), and [legacy query routes](../core/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](../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`](../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. +* 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`, `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. * [`BeginBlocker`, `EndBlocker`](#beginblocker-and-endlbocker): called at the beginning and at the end of every block. - * [`anteHandler`](../core/00-baseapp.md#antehandler): used to handle fees and signature verification. + * [`anteHandler`](../advanced/00-baseapp.md#antehandler): used to handle fees and signature verification. * Mount the stores. * Return the application. @@ -99,7 +99,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L223-L57 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`](../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](../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`. +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`: @@ -111,7 +111,7 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L626-L63 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`](../building-modules/05-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](../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. +In general, the `BeginBlocker` and `EndBlocker` functions are mostly composed of the [`BeginBlock` and `EndBlock`](../../build/building-modules/05-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. @@ -132,10 +132,10 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/params/encoding 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](../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](../architecture/adr-019-protobuf-state-encoding.md). + * 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](../core/01-transactions.md). +* `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. @@ -147,19 +147,19 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/params/encoding ## Modules -[Modules](../building-modules/01-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`](../core/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). +[Modules](../../build/building-modules/01-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](../building-modules/01-module-manager.md#application-module-interfaces) defined in the Cosmos SDK, [`AppModuleBasic`](../building-modules/01-module-manager.md#appmodulebasic) and [`AppModule`](../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`. +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`](../building-modules/01-module-manager.md#manager), which manages the application's collection of modules. +`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](../core/01-transactions.md), and each transaction contains one or multiple messages. +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: @@ -182,7 +182,7 @@ Each module should also implement the `RegisterServices` method as part of the [ ### 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`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). +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. @@ -192,7 +192,7 @@ Finally, each module should also implement the `RegisterServices` method as part ### Keeper -[`Keepers`](../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](../core/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`](../../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. @@ -210,10 +210,10 @@ Each module defines command-line commands, gRPC services, and REST routes to be #### CLI -Generally, the [commands related to a module](../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): +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](../core/00-baseapp.md#query-routing), which routes them to the appropriate [querier](#querier) the `queryRoute` parameter supplied. +* 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 @@ -230,13 +230,13 @@ Some external clients may not wish to use gRPC. In this case, the Cosmos SDK pro 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`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml) config file, under the `api.swagger` key. +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](../core/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: +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. diff --git a/docs/docs/basics/01-tx-lifecycle.md b/docs/docs/develop/beginner/01-tx-lifecycle.md similarity index 82% rename from docs/docs/basics/01-tx-lifecycle.md rename to docs/docs/develop/beginner/01-tx-lifecycle.md index d6c703dacc42..e3831ae3b45c 100644 --- a/docs/docs/basics/01-tx-lifecycle.md +++ b/docs/docs/develop/beginner/01-tx-lifecycle.md @@ -5,7 +5,7 @@ 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](../core/01-transactions.md). The transaction is referred to as `Tx`. +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 @@ -17,7 +17,7 @@ This document describes the lifecycle of a transaction from creation to committe ### 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](../core/07-cli.md), providing the type of transaction in `[command]`, arguments in `[args]`, and configurations such as gas prices in `[flags]`: +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] @@ -29,7 +29,7 @@ There are several required and optional flags for transaction creation. The `--f #### Gas and Fees -Additionally, there are several [flags](../core/07-cli.md) users can use to indicate how much they are willing to pay in [fees](./04-gas-fees.md): +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. @@ -51,7 +51,7 @@ appd tx send 1000uatom --from --gas auto --ga #### 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](../core/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). +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 @@ -71,7 +71,7 @@ are not empty, enforcing nonnegative numbers, and other logic specified in the d **_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](../core/00-baseapp.md#state-updates) +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. @@ -82,16 +82,16 @@ 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](../core/05-encoding.md) `[]byte` form and needs to be unmarshaled in order to be processed. Then, the [`runTx`](../core/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. +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`](../core/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`](../core/00-baseapp.md#checktx) and [`DeliverTx`](../core/00-baseapp.md#delivertx) transactions. +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](../building-modules/03-msg-services.md#Validation). +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. ::: @@ -102,7 +102,7 @@ Read [RFC 001](https://docs.cosmos.network/main/rfc/rfc-001-tx-validation) for m #### Guideline -`ValidateBasic` should not be used anymore. Message validation should be performed in the `Msg` service when [handling a message](../building-modules/msg-services#Validation) in a module Msg Server. +`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 @@ -114,7 +114,7 @@ For example, the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/main/x/auth/ ### Gas -The [`Context`](../core/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`. +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 @@ -203,10 +203,10 @@ Although every full-node operates individually and locally, the outcome is alway ### Transaction Execution -The `FinalizeBlock` ABCI function defined in [`BaseApp`](../core/00-baseapp.md) does the bulk of the +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`](../core/00-baseapp.md#runtx) function in deliver mode instead of check mode. +[`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. @@ -219,14 +219,14 @@ Instead of using their `checkState`, full-nodes use `finalizeblock`: to each node - differing values across nodes yield nondeterministic results. * **`MsgServiceRouter`:** After `CheckTx` exits, `FinalizeBlock` continues to run - [`runMsgs`](../core/00-baseapp.md#runtx-antehandler-runmsgs-posthandler) to fully execute each `Msg` within the transaction. + [`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](../building-modules/03-msg-services.md). - For `LegacyMsg` routing, the `Route` function is called via the [module manager](../building-modules/01-module-manager.md) to retrieve the route name and find the legacy [`Handler`](../building-modules/03-msg-services.md#handler-type) within the 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`](../core/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. +* **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 @@ -247,8 +247,8 @@ 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`](../core/00-baseapp.md#commit) -ABCI method inherited from [Baseapp](../core/00-baseapp.md); it syncs all the state transitions by +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. diff --git a/docs/docs/basics/02-query-lifecycle.md b/docs/docs/develop/beginner/02-query-lifecycle.md similarity index 67% rename from docs/docs/basics/02-query-lifecycle.md rename to docs/docs/develop/beginner/02-query-lifecycle.md index 29332d802eff..04e4fc9ed644 100644 --- a/docs/docs/basics/02-query-lifecycle.md +++ b/docs/docs/develop/beginner/02-query-lifecycle.md @@ -15,9 +15,9 @@ This document describes the lifecycle of a query in a Cosmos SDK application, fr ## Query Creation -A [**query**](../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](../core/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. +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`](../modules/staking/README.md) module handles this query. But first, there are a few ways `MyQuery` can be created by users. +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 @@ -27,7 +27,7 @@ The main interface for an application is the command-line interface. Users conne simd query staking delegations ``` -This query command was defined by the [`staking`](../modules/staking/README.md) module developer and added to the list of subcommands by the application developer when creating the CLI. +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: @@ -35,13 +35,13 @@ Note that the general format is as follows: simd query [moduleName] [command] --flag ``` -To provide values such as `--node` (the full-node the CLI connects to), the user can use the [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml) config file to set them or provide them as flags. +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](../core/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. +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](../core/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. +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: @@ -57,7 +57,7 @@ grpcurl \ ### REST -Another interface through which users can make queries is through HTTP Requests to a [REST server](../core/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). +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: @@ -73,10 +73,10 @@ The preceding examples show how an external user can interact with a node by que 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](../core/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`](../modules/auth/README.md) module, which translates `[]byte`s into accounts. +* **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](../basics/03-accounts.md#keyring) used to sign transactions and handle other operations with keys. +* **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. @@ -110,7 +110,7 @@ The Cosmos SDK leverages code generated from Protobuf services to make queries. 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**](../core/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()`. +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: @@ -120,15 +120,15 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/query.go#L79-L1 ## RPC -With a call to `ABCIQueryWithOptions()`, `MyQuery` is received by a [full-node](../core/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. +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`](../core/00-baseapp.md) implements the ABCI [`Query()`](../core/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. +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](../building-modules/04-query-services.md). +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. @@ -138,7 +138,7 @@ Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci ### CLI Response -The application [`codec`](../core/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). +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 diff --git a/docs/docs/basics/03-accounts.md b/docs/docs/develop/beginner/03-accounts.md similarity index 95% rename from docs/docs/basics/03-accounts.md rename to docs/docs/develop/beginner/03-accounts.md index 45a1e6e302a1..7280108ac744 100644 --- a/docs/docs/basics/03-accounts.md +++ b/docs/docs/develop/beginner/03-accounts.md @@ -17,7 +17,7 @@ This document describes the in-built account and public key system of the Cosmos ## 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](../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`. +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. @@ -152,7 +152,7 @@ The default implementation of `Keyring` comes from the third-party [`99designs/k 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](../architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../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`](../core/00-baseapp.md#antehandler). +* `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 diff --git a/docs/docs/basics/04-gas-fees.md b/docs/docs/develop/beginner/04-gas-fees.md similarity index 70% rename from docs/docs/basics/04-gas-fees.md rename to docs/docs/develop/beginner/04-gas-fees.md index c20231a117ad..11b7efdf5f1e 100644 --- a/docs/docs/basics/04-gas-fees.md +++ b/docs/docs/develop/beginner/04-gas-fees.md @@ -19,7 +19,7 @@ This document describes the default strategies to handle gas and fees within a C 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`](../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). +* 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 @@ -40,7 +40,7 @@ where: * `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`](../core/02-context.md), and consuming gas is done with the following pattern: +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") @@ -50,19 +50,19 @@ By default, the Cosmos SDK makes use of two different gas meters, the [main gas ### 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`](../core/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. +`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`](../building-modules/05-beginblock-endblock.md) or [`Msg` service](../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`](../core/04-store.md#gaskv-store). +Gas consumption can be done manually, generally by the module developer in the [`BeginBlocker`, `EndBlocker`](../../build/building-modules/05-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`](../core/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: +`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](../core/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: +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( @@ -89,9 +89,9 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/tx_msg.go#L51-L5 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`](../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`. +* 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`](../core/00-baseapp.md#finalizeblock) returns. +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. diff --git a/docs/docs/basics/_category_.json b/docs/docs/develop/beginner/_category_.json similarity index 100% rename from docs/docs/basics/_category_.json rename to docs/docs/develop/beginner/_category_.json diff --git a/docs/docs/intro/00-overview.md b/docs/docs/develop/intro/00-overview.md similarity index 86% rename from docs/docs/intro/00-overview.md rename to docs/docs/develop/intro/00-overview.md index 31301657727a..58b743688a81 100644 --- a/docs/docs/intro/00-overview.md +++ b/docs/docs/develop/intro/00-overview.md @@ -8,7 +8,7 @@ sidebar_position: 1 The [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is an open-source framework for building multi-asset public Proof-of-Stake (PoS) blockchains, like the Cosmos Hub, as well as permissioned Proof-of-Authority (PoA) blockchains. Blockchains built with the Cosmos SDK are generally referred to as **application-specific blockchains**. -The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. We envision the Cosmos SDK as the npm-like framework to build secure blockchain applications on top of [CometBFT](https://github.com/cometbft/cometbft). SDK-based blockchains are built out of composable [modules](../building-modules/01-intro.md), most of which are open-source and readily available for any developers to use. Anyone can create a module for the Cosmos SDK, and integrating already-built modules is as simple as importing them into your blockchain application. What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../core/10-ocap.md). +The goal of the Cosmos SDK is to allow developers to easily create custom blockchains from scratch that can natively interoperate with other blockchains. We envision the Cosmos SDK as the npm-like framework to build secure blockchain applications on top of [CometBFT](https://github.com/cometbft/cometbft). SDK-based blockchains are built out of composable [modules](../../build/building-modules/01-intro.md), most of which are open-source and readily available for any developers to use. Anyone can create a module for the Cosmos SDK, and integrating already-built modules is as simple as importing them into your blockchain application. What's more, the Cosmos SDK is a capabilities-based system that allows developers to better reason about the security of interactions between modules. For a deeper look at capabilities, jump to [Object-Capability Model](../advanced/10-ocap.md). ## What are Application-Specific Blockchains diff --git a/docs/docs/intro/01-why-app-specific.md b/docs/docs/develop/intro/01-why-app-specific.md similarity index 100% rename from docs/docs/intro/01-why-app-specific.md rename to docs/docs/develop/intro/01-why-app-specific.md diff --git a/docs/docs/intro/02-sdk-app-architecture.md b/docs/docs/develop/intro/02-sdk-app-architecture.md similarity index 91% rename from docs/docs/intro/02-sdk-app-architecture.md rename to docs/docs/develop/intro/02-sdk-app-architecture.md index 465948bacac5..475326903ea7 100644 --- a/docs/docs/intro/02-sdk-app-architecture.md +++ b/docs/docs/develop/intro/02-sdk-app-architecture.md @@ -84,8 +84,8 @@ Note that **CometBFT only handles transaction bytes**. It has no knowledge of wh Here are the most important messages of the ABCI: -* `CheckTx`: When a transaction is received by CometBFT, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`](../basics/04-gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.cometbft.com/v0.37/spec/p2p/messages/mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. -* `DeliverTx`: When a [valid block](https://docs.cometbft.com/v0.37/spec/core/data_structures#block) is received by CometBFT, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../building-modules/03-msg-services.md) RPC for each message in the transaction. +* `CheckTx`: When a transaction is received by CometBFT, it is passed to the application to check if a few basic requirements are met. `CheckTx` is used to protect the mempool of full-nodes against spam transactions. . A special handler called the [`AnteHandler`]../beginner/04-gas-fees.md#antehandler) is used to execute a series of validation steps such as checking for sufficient fees and validating the signatures. If the checks are valid, the transaction is added to the [mempool](https://docs.cometbft.com/v0.37/spec/p2p/messages/mempool) and relayed to peer nodes. Note that transactions are not processed (i.e. no modification of the state occurs) with `CheckTx` since they have not been included in a block yet. +* `DeliverTx`: When a [valid block](https://docs.cometbft.com/v0.37/spec/core/data_structures#block) is received by CometBFT, each transaction in the block is passed to the application via `DeliverTx` in order to be processed. It is during this stage that the state transitions occur. The `AnteHandler` executes again, along with the actual [`Msg` service](../../build/building-modules/03-msg-services.md) RPC for each message in the transaction. * `BeginBlock`/`EndBlock`: These messages are executed at the beginning and the end of each block, whether the block contains transactions or not. It is useful to trigger automatic execution of logic. Proceed with caution though, as computationally expensive loops could slow down your blockchain, or even freeze it if the loop is infinite. Find a more detailed view of the ABCI methods from the [CometBFT docs](https://docs.cometbft.com/v0.37/spec/abci/). diff --git a/docs/docs/intro/03-sdk-design.md b/docs/docs/develop/intro/03-sdk-design.md similarity index 85% rename from docs/docs/intro/03-sdk-design.md rename to docs/docs/develop/intro/03-sdk-design.md index eea12fd4dcbb..78afb12989cc 100644 --- a/docs/docs/intro/03-sdk-design.md +++ b/docs/docs/develop/intro/03-sdk-design.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Main Components of the Cosmos SDK -The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of CometBFT. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./02-sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../core/04-store.md#multistore) to persist data and a [`router`](../core/00-baseapp.md#routing) to handle transactions. +The Cosmos SDK is a framework that facilitates the development of secure state-machines on top of CometBFT. At its core, the Cosmos SDK is a boilerplate implementation of the [ABCI](./02-sdk-app-architecture.md#abci) in Golang. It comes with a [`multistore`](../advanced/04-store.md#multistore) to persist data and a [`router`](../advanced/00-baseapp.md#routing) to handle transactions. Here is a simplified view of how transactions are handled by an application built on top of the Cosmos SDK when transferred from CometBFT via `DeliverTx`: @@ -15,7 +15,7 @@ Here is a simplified view of how transactions are handled by an application buil ## `baseapp` -`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`](../basics/00-app-anatomy.md#core-application-file). +`baseapp` is the boilerplate implementation of a Cosmos SDK application. It comes with an implementation of the ABCI to handle the connection with the underlying consensus engine. Typically, a Cosmos SDK application extends `baseapp` by embedding it in [`app.go`]../beginner/00-app-anatomy.md#core-application-file). Here is an example of this from `simapp`, the Cosmos SDK demonstration app: @@ -25,13 +25,13 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app.go#L170-L21 The goal of `baseapp` is to provide a secure interface between the store and the extensible state machine while defining as little about the state machine as possible (staying true to the ABCI). -For more on `baseapp`, please click [here](../core/00-baseapp.md). +For more on `baseapp`, please click [here](../advanced/00-baseapp.md). ## Multistore -The Cosmos SDK provides a [`multistore`](../core/04-store.md#multistore) for persisting state. The multistore allows developers to declare any number of [`KVStores`](../core/04-store.md#base-layer-kvstores). These `KVStores` only accept the `[]byte` type as value and therefore any custom structure needs to be marshalled using [a codec](../core/05-encoding.md) before being stored. +The Cosmos SDK provides a [`multistore`](../advanced/04-store.md#multistore) for persisting state. The multistore allows developers to declare any number of [`KVStores`](../advanced/04-store.md#base-layer-kvstores). These `KVStores` only accept the `[]byte` type as value and therefore any custom structure needs to be marshalled using [a codec](../advanced/05-encoding.md) before being stored. -The multistore abstraction is used to divide the state in distinct compartments, each managed by its own module. For more on the multistore, click [here](../core/04-store.md#multistore) +The multistore abstraction is used to divide the state in distinct compartments, each managed by its own module. For more on the multistore, click [here](../advanced/04-store.md#multistore) ## Modules @@ -84,7 +84,7 @@ Here is a simplified view of how a transaction is processed by the application o v ``` -Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` by `baseapp`). In general, each module declares its own `KVStore` in the `multistore` to persist the subset of the state it defines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on [object-capabilities](../core/10-ocap.md). In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called `keepers` that can be passed to other modules to grant a pre-defined set of capabilities. +Each module can be seen as a little state-machine. Developers need to define the subset of the state handled by the module, as well as custom message types that modify the state (*Note:* `messages` are extracted from `transactions` by `baseapp`). In general, each module declares its own `KVStore` in the `multistore` to persist the subset of the state it defines. Most developers will need to access other 3rd party modules when building their own modules. Given that the Cosmos SDK is an open framework, some of the modules may be malicious, which means there is a need for security principles to reason about inter-module interactions. These principles are based on [object-capabilities](../advanced/10-ocap.md). In practice, this means that instead of having each module keep an access control list for other modules, each module implements special objects called `keepers` that can be passed to other modules to grant a pre-defined set of capabilities. Cosmos SDK modules are defined in the `x/` folder of the Cosmos SDK. Some core modules include: diff --git a/docs/docs/intro/_category_.json b/docs/docs/develop/intro/_category_.json similarity index 100% rename from docs/docs/intro/_category_.json rename to docs/docs/develop/intro/_category_.json diff --git a/docs/docs/packages/README.md b/docs/docs/packages/README.md deleted file mode 100644 index d7a115b263de..000000000000 --- a/docs/docs/packages/README.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_position: 0 ---- - -# Packages - -The Cosmos SDK is a collection of Go modules. This section provides documentation on various packages that can used when developing a Cosmos SDK chain. -It lists all standalone Go modules that are part of the Cosmos SDK. - -:::tip -For more information on SDK modules, see the [SDK Modules](https://docs.cosmos.network/main/modules) section. -For more information on SDK tooling, see the [Tooling](https://docs.cosmos.network/main/tooling) section. -::: - -## Core - -* [Core](https://pkg.go.dev/cosmossdk.io/core) - Core library defining SDK interfaces ([ADR-063](https://docs.cosmos.network/main/architecture/adr-063-core-module-api)) -* [API](https://pkg.go.dev/cosmossdk.io/api) - API library containing generated SDK Pulsar API -* [Store](https://pkg.go.dev/cosmossdk.io/store) - Implementation of the Cosmos SDK store - -## State Management - -* [Collections](./02-collections.md) - State management library -* [ORM](./03-orm.md) - State management library - -## Automation - -* [Depinject](./01-depinject.md) - Dependency injection framework -* [Client/v2](https://pkg.go.dev/cosmossdk.io/client/v2) - Library powering [AutoCLI](https://docs.cosmos.network/main/core/autocli) - -## Utilities - -* [Log](https://pkg.go.dev/cosmossdk.io/log) - Logging library -* [Errors](https://pkg.go.dev/cosmossdk.io/errors) - Error handling library -* [Math](https://pkg.go.dev/cosmossdk.io/math) - Math library for SDK arithmetic operations - -## Example - -* [SimApp](https://pkg.go.dev/cosmossdk.io/simapp) - SimApp is **the** sample Cosmos SDK chain. This package should not be imported in your application. diff --git a/docs/docs/tooling/README.md b/docs/docs/tooling/README.md deleted file mode 100644 index 27bc94e24f34..000000000000 --- a/docs/docs/tooling/README.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_position: 0 ---- - -# Tools - -This section provides documentation on various tooling maintained by the SDK team. -This includes tools for development, operating a node, and ease of use of a Cosmos SDK chain. - -## CLI Tools - -* [Cosmovisor](./01-cosmovisor.md) -* [Confix](./02-confix.md) -* [Hubl](./03-hubl.md) -* [Rosetta](https://docs.cosmos.network/main/run-node/rosetta) - -## Other Tools - -* [Protocol Buffers](./00-protobuf.md) diff --git a/docs/docs/run-node/00-keyring.md b/docs/docs/user/run-node/00-keyring.md similarity index 98% rename from docs/docs/run-node/00-keyring.md rename to docs/docs/user/run-node/00-keyring.md index 2cb15b115cfd..09d8b07422d2 100644 --- a/docs/docs/run-node/00-keyring.md +++ b/docs/docs/user/run-node/00-keyring.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Setting up the keyring :::note Synopsis -This document describes how to configure and use the keyring and its various backends for an [**application**](../basics/00-app-anatomy.md). +This document describes how to configure and use the keyring and its various backends for an [**application**](../../develop/beginner/00-app-anatomy.md). ::: The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage. diff --git a/docs/docs/run-node/01-run-node.md b/docs/docs/user/run-node/01-run-node.md similarity index 93% rename from docs/docs/run-node/01-run-node.md rename to docs/docs/user/run-node/01-run-node.md index 0c24117e3b39..fc539989b93e 100644 --- a/docs/docs/run-node/01-run-node.md +++ b/docs/docs/user/run-node/01-run-node.md @@ -10,7 +10,7 @@ Now that the application is ready and the keyring populated, it's time to see ho :::note Pre-requisite Readings -* [Anatomy of a Cosmos SDK Application](../basics/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK Application](../../develop/beginner/00-app-anatomy.md) * [Setting up the keyring](./00-keyring.md) ::: @@ -87,7 +87,7 @@ simd genesis add-genesis-account $MY_VALIDATOR_ADDRESS 100000000000stake Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./00-keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is is a 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). For your own chain with its own staking denom, that token identifier should be used instead. -Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../intro/02-sdk-app-architecture.md#cometbft)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`: +Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../../develop/intro/02-sdk-app-architecture.md#cometbft)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`: ```bash # Create a gentx. diff --git a/docs/docs/run-node/02-interact-node.md b/docs/docs/user/run-node/02-interact-node.md similarity index 94% rename from docs/docs/run-node/02-interact-node.md rename to docs/docs/user/run-node/02-interact-node.md index 90977a61d6ef..48193504a603 100644 --- a/docs/docs/run-node/02-interact-node.md +++ b/docs/docs/user/run-node/02-interact-node.md @@ -10,7 +10,7 @@ There are multiple ways to interact with a node: using the CLI, using gRPC or us :::note Pre-requisite Readings -* [gRPC, REST and CometBFT Endpoints](../core/06-grpc_rest.md) +* [gRPC, REST and CometBFT Endpoints](../../develop/advanced/06-grpc_rest.md) * [Running a Node](./01-run-node.md) ::: @@ -54,7 +54,7 @@ You should see two delegations, the first one made from the `gentx`, and the sec ## Using gRPC -The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../core/06-grpc_rest.md). +The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../../develop/advanced/06-grpc_rest.md). Since the code generation library largely depends on your own tech stack, we will only present three alternatives: @@ -248,7 +248,7 @@ CosmJS documentation can be found at [https://cosmos.github.io/cosmjs](https://c ## Using the REST Endpoints -As described in the [gRPC guide](../core/06-grpc_rest.md), all gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters. +As described in the [gRPC guide](../../develop/advanced/06-grpc_rest.md), all gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters. Note that the REST endpoints are not enabled by default. To enable them, edit the `api` section of your `~/.simapp/config/app.toml` file: diff --git a/docs/docs/run-node/03-txs.md b/docs/docs/user/run-node/03-txs.md similarity index 99% rename from docs/docs/run-node/03-txs.md rename to docs/docs/user/run-node/03-txs.md index 16c1d966bf3e..faf1d8b65def 100644 --- a/docs/docs/run-node/03-txs.md +++ b/docs/docs/user/run-node/03-txs.md @@ -269,7 +269,7 @@ func sendTx() error { ### Broadcasting a Transaction -The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the CometBFT RPC is also posible. An overview of the differences between these methods is exposed [here](../core/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. +The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the CometBFT RPC is also posible. An overview of the differences between these methods is exposed [here](../../develop/advanced/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. ```go import ( diff --git a/docs/docs/run-node/05-run-testnet.md b/docs/docs/user/run-node/05-run-testnet.md similarity index 100% rename from docs/docs/run-node/05-run-testnet.md rename to docs/docs/user/run-node/05-run-testnet.md diff --git a/docs/docs/run-node/06-run-production.md b/docs/docs/user/run-node/06-run-production.md similarity index 100% rename from docs/docs/run-node/06-run-production.md rename to docs/docs/user/run-node/06-run-production.md diff --git a/docs/docs/run-node/_category_.json b/docs/docs/user/run-node/_category_.json similarity index 100% rename from docs/docs/run-node/_category_.json rename to docs/docs/user/run-node/_category_.json diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index d331c6c94339..19e52494a462 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -215,6 +215,24 @@ const config = { { fromExtensions: ["html"], toExtensions: ["html"], + createRedirects(existingPath) { + return [ + existingPath.replace('/core', '/develop/advanced'), + existingPath.replace('/basics', '/develop/beginner'), + existingPath.replace('/intro', '/develop/intro'), + existingPath.replace('/architecture', '/build/architecture/'), + existingPath.replace('/building-apps', '/build/building-apps'), + existingPath.replace('/building-modules', '/build/building-modules'), + existingPath.replace('/tooling', '/build/tooling'), + existingPath.replace('/migrations', '/build/migrations'), + existingPath.replace('/modules', '/build/modules'), + existingPath.replace('/rfc', '/build/rfc'), + existingPath.replace('/spec', '/build/spec'), + existingPath.replace('/tooling', '/build/tooling'), + existingPath.replace('/run-node', '/user/run-node'), + existingPath.replace('/validate', '/user/validate') + ]; + }, redirects: [ { from: ["/", "/master", "/v0.43", "/v0.44"], @@ -229,11 +247,11 @@ const config = { "/main/modules/auth/06_params", "/main/modules/auth/07_client", ], - to: "/main/modules/auth", + to: "/main/build/modules/auth", }, { from: "/main/modules/auth/05_vesting", - to: "/main/modules/auth/vesting", + to: "/main/build/modules/auth/vesting", }, { from: [ @@ -243,7 +261,7 @@ const config = { "/main/modules/authz/04_events", "/main/modules/authz/05_client", ], - to: "/main/modules/authz", + to: "/main/build/modules/authz", }, { from: [ @@ -253,7 +271,7 @@ const config = { "/main/modules/bank/05_params", "/main/modules/bank/06_client", ], - to: "/main/modules/bank", + to: "/main/build/modules/bank", }, { from: [ @@ -263,7 +281,7 @@ const config = { "/main/modules/crisis/04_params", "/main/modules/crisis/05_client", ], - to: "/main/modules/crisis", + to: "/main/build/modules/crisis", }, { from: [ @@ -276,7 +294,7 @@ const config = { "/main/modules/distribution/07_params", "/main/modules/distribution/08_client", ], - to: "/main/modules/distribution", + to: "/main/build/modules/distribution", }, { from: [ @@ -288,7 +306,7 @@ const config = { "/main/modules/evidence/06_begin_block", "/main/modules/evidence/07_client", ], - to: "/main/modules/evidence", + to: "/main/build/modules/evidence", }, { from: [ @@ -298,7 +316,7 @@ const config = { "/main/modules/feegrant/04_events", "/main/modules/feegrant/05_client", ], - to: "/main/modules/feegrant", + to: "/main/build/modules/feegrant", }, { from: [ @@ -311,7 +329,7 @@ const config = { "/main/modules/gov/07_client", "/main/modules/gov/08_metadata", ], - to: "/main/modules/gov", + to: "/main/build/modules/gov", }, { from: [ @@ -322,7 +340,7 @@ const config = { "/main/modules/group/05_client", "/main/modules/group/06_metadata", ], - to: "/main/modules/group/", + to: "/main/build/modules/group/", }, { from: [ @@ -333,7 +351,7 @@ const config = { "/main/modules/mint/05_events", "/main/modules/mint/06_client", ], - to: "/main/modules/mint/", + to: "/main/build/modules/mint/", }, { from: [ @@ -342,14 +360,14 @@ const config = { "/main/modules/nft/03_messages", "/main/modules/nft/04_events", ], - to: "/main/modules/nft/", + to: "/main/build/modules/nft/", }, { from: [ "/main/modules/params/01_keeper", "/main/modules/params/02_subspace", ], - to: "/main/modules/params/", + to: "/main/build/modules/params/", }, { from: [ @@ -363,7 +381,7 @@ const config = { "/main/modules/slashing/08_params", "/main/modules/slashing/09_client", ], - to: "/main/modules/slashing/", + to: "/main/build/modules/slashing/", }, { from: [ @@ -377,7 +395,7 @@ const config = { "/main/modules/staking/08_params", "/main/modules/staking/09_client", ], - to: "/main/modules/staking/", + to: "/main/build/modules/staking/", }, { from: [ @@ -386,35 +404,35 @@ const config = { "/main/modules/upgrade/03_events", "/main/modules/upgrade/04_client", ], - to: "/main/modules/upgrade/", + to: "/main/build/modules/upgrade/", }, { from: ["/main/modules/capability", "/main/ecosystem"], - to: "/main/modules", + to: "/main/build/modules/auth", }, { from: ["/main/spec/circuit-breaker"], - to: "/main/modules/circuit", + to: "/main/build/modules/circuit", }, { from: ["/main/spec/reserve-pool"], - to: "/main/modules/distribution", + to: "/main/build/modules/distribution", }, { from: ["/main/run-node/cosmovisor"], - to: "/main/tooling/cosmovisor", + to: "/main/build/tooling/cosmovisor", }, { from: ["/main/migrations/pre-upgrade"], - to: "/main/building-apps/app-upgrade", + to: "/main/build/building-apps/app-upgrade", }, { from: ["/main/tooling/depinject"], - to: "/main/packages/depinject", + to: "/main/build/packages/depinject", }, { from: ["/main/building-modules/autocli"], - to: "/main/core/autocli", + to: "/main/develop/advanced/autocli", }, ], }, diff --git a/docs/post.sh b/docs/post.sh index 816a7779bf7a..0e9b23bb67b6 100755 --- a/docs/post.sh +++ b/docs/post.sh @@ -1,16 +1,17 @@ #!/usr/bin/env bash -find docs/modules ! -name '_category_.json' -type f -exec rm -rf {} + -rm -rf docs/tooling/01-cosmovisor.md -rm -rf docs/tooling/02-confix.md -rm -rf docs/tooling/03-hubl.md -rm -rf docs/packages/01-depinject.md -rm -rf docs/packages/02-collections.md -rm -rf docs/packages/03-orm.md -rm -rf docs/core/17-autocli.md -rm -rf docs/run-node/04-rosetta.md -rm -rf docs/architecture -rm -rf docs/spec -rm -rf docs/rfc -rm -rf docs/migrations/02-upgrading.md +find docs/build/modules ! -name '_category_.json' -type f -exec rm -rf {} + +rm -rf docs/build/tooling/01-cosmovisor.md +rm -rf docs/build/tooling/02-confix.md +rm -rf docs/build/tooling/03-hubl.md +rm -rf docs/build/packages/01-depinject.md +rm -rf docs/build/packages/02-collections.md +rm -rf docs/build/packages/03-orm.md +rm -rf docs/develop/advaced-concepts/17-autocli.md +rm -rf docs/user/run-node/04-rosetta.md +rm -rf docs/build/architecture +rm -rf docs/build/spec +rm -rf docs/build/rfc +rm -rf docs/develop/advanced/17-autocli.md +rm -rf docs/build/migrations/02-upgrading.md rm -rf versioned_docs versioned_sidebars versions.json \ No newline at end of file diff --git a/docs/pre.sh b/docs/pre.sh index f45982651a42..93939e419a84 100755 --- a/docs/pre.sh +++ b/docs/pre.sh @@ -3,7 +3,7 @@ ## Create modules pages for D in ../x/*; do if [ -d "${D}" ]; then - MODDOC=docs/modules/$(echo $D | awk -F/ '{print $NF}') + MODDOC=docs/build/modules/$(echo $D | awk -F/ '{print $NF}') rm -rf $MODDOC mkdir -p $MODDOC && cp -r $D/README.md "$_" fi @@ -11,32 +11,32 @@ done ## Vesting is a submodule of auth, but we still want to display it in docs ## TODO to be removed in https://github.com/cosmos/cosmos-sdk/issues/9958 -cp ../x/auth/vesting/README.md ./docs/modules/auth/1-vesting.md -cp ../x/auth/tx/README.md ./docs/modules/auth/2-tx.md +cp ../x/auth/vesting/README.md ./docs/build/modules/auth/1-vesting.md +cp ../x/auth/tx/README.md ./docs/build/modules/auth/2-tx.md ## Add modules page list -cat ../x/README.md | sed 's/\.\.\/docs\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./docs/modules/README.md +cat ../x/README.md | sed 's/\.\.\/docs\/build\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./docs/modules/README.md ## Add tooling documentation -cp ../tools/cosmovisor/README.md ./docs/tooling/01-cosmovisor.md -cp ../tools/confix/README.md ./docs/tooling/02-confix.md -cp ../tools/hubl/README.md ./docs/tooling/03-hubl.md -wget -O docs/run-node/04-rosetta.md https://raw.githubusercontent.com/cosmos/rosetta/main/README.md +cp ../tools/cosmovisor/README.md ./docs/build/tooling/01-cosmovisor.md +cp ../tools/confix/README.md ./docs/build/tooling/02-confix.md +cp ../tools/hubl/README.md ./docs/build/tooling/03-hubl.md +wget -O docs/user/run-node/04-rosetta.md https://raw.githubusercontent.com/cosmos/rosetta/main/README.md ## Add package documentation -cp ../client/v2/README.md ./docs/core/17-autocli.md -cp ../depinject/README.md ./docs/packages/01-depinject.md -cp ../collections/README.md ./docs/packages/02-collections.md -cp ../orm/README.md ./docs/packages/03-orm.md +cp ../client/v2/README.md ./docs/develop/advanced/17-autocli.md +cp ../depinject/README.md ./docs/build/packages/01-depinject.md +cp ../collections/README.md ./docs/build/packages/02-collections.md +cp ../orm/README.md ./docs/build/packages/03-orm.md ## Add architecture documentation -cp -r ./architecture ./docs +cp -r ./architecture ./docs/build ## Add spec documentation -cp -r ./spec ./docs +cp -r ./spec ./docs/build ## Add rfc documentation -cp -r ./rfc ./docs +cp -r ./rfc ./docs/build/rfc ## Add SDK migration documentation -cp -r ../UPGRADING.md ./docs/migrations/02-upgrading.md \ No newline at end of file +cp -r ../UPGRADING.md ./docs/build/migrations/02-upgrading.md \ No newline at end of file diff --git a/docs/rfc/README.md b/docs/rfc/README.md index 24887ac3f668..0c75501e1623 100644 --- a/docs/rfc/README.md +++ b/docs/rfc/README.md @@ -13,7 +13,7 @@ discussion that might otherwise only be recorded in an ad-hoc way (for example, via gists or Google docs) that are difficult to discover for someone after the fact. An RFC _may_ give rise to more specific architectural _decisions_ for the Cosmos SDK, but those decisions must be recorded separately in -[Architecture Decision Records (ADR)](../architecture/). +[Architecture Decision Records (ADR)](../architecture). As a rule of thumb, if you can articulate a specific question that needs to be answered, write an ADR. If you need to explore the topic and get input from @@ -36,3 +36,7 @@ sections. ## Table of Contents +<<<<<<< HEAD +======= +* [RFC-002: Zero Copy Encoding](./rfc-002-zero-copy-encoding.md) +>>>>>>> f198ea944 (refactor: docs path updates (#17459)) diff --git a/docs/rfc/_category_.json b/docs/rfc/_category_.json deleted file mode 100644 index 40fac9822465..000000000000 --- a/docs/rfc/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "RFCs", - "position": 12, - "link": null -} \ No newline at end of file From 79a91b69c9e59bc872405fcd9d69182c691b8fee Mon Sep 17 00:00:00 2001 From: samricotta Date: Tue, 5 Sep 2023 16:55:04 +0300 Subject: [PATCH 4/4] conflicts --- .github/workflows/deploy-docs.yml | 47 ------------------- UPGRADING.md | 1 - .../building-modules/01-module-manager.md | 8 ---- docs/docs/build/building-modules/06-keeper.md | 6 --- docs/docs/develop/advanced/00-baseapp.md | 5 -- docs/rfc/README.md | 5 +- 6 files changed, 2 insertions(+), 70 deletions(-) delete mode 100644 .github/workflows/deploy-docs.yml diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml deleted file mode 100644 index da885a75ebe2..000000000000 --- a/.github/workflows/deploy-docs.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: Deploy docs -# This job builds and deploys documenation to github pages. -# It runs on every push to main with a change in the docs folder. -on: - workflow_dispatch: - push: - branches: - - main - - "release/**" - paths: - - "docs/**" - - "x/**/*.md" - - .github/workflows/deploy-docs.yml - -permissions: - contents: read - -jobs: - build-and-deploy: - permissions: - contents: write # for JamesIves/github-pages-deploy-action to push changes in repo - runs-on: ubuntu-latest - steps: - - name: Checkout πŸ›ŽοΈ - uses: actions/checkout@v4 - with: - persist-credentials: false - fetch-depth: 0 - path: "." - - - name: Setup Node.js πŸ”§ - uses: actions/setup-node@v3 - with: - node-version: "16.x" - - # npm install npm should be removed when https://github.com/npm/cli/issues/4942 is fixed - - name: Build πŸ”§ - run: | - npm install -g npm@8.5.5 - make build-docs - - # - name: Deploy πŸš€ - # uses: JamesIves/github-pages-deploy-action@v4.4.3 - # with: - # branch: gh-pages - # folder: ~/output - # single-commit: true diff --git a/UPGRADING.md b/UPGRADING.md index 30999296bef7..43afbf309bde 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -782,4 +782,3 @@ message MsgSetWithdrawAddress { ``` When clients interract with a node they are required to set a codec in in the grpc.Dial. More information can be found in this [doc](https://docs.cosmos.network/v0.46/run-node/interact-node.html#programmatically-via-go). ->>>>>>> f198ea944 (refactor: docs path updates (#17459)) diff --git a/docs/docs/build/building-modules/01-module-manager.md b/docs/docs/build/building-modules/01-module-manager.md index 00924c4d2c46..92e3f838dea7 100644 --- a/docs/docs/build/building-modules/01-module-manager.md +++ b/docs/docs/build/building-modules/01-module-manager.md @@ -301,20 +301,12 @@ The module manager is used throughout the application whenever an action on a co * `InitGenesis(ctx context.Context, cdc codec.JSONCodec, genesisData map[string]json.RawMessage)`: Calls the [`InitGenesis`](./08-genesis.md#initgenesis) function of each module when the application is first started, in the order defined in `OrderInitGenesis`. Returns an `abci.ResponseInitChain` to the underlying consensus engine, which can contain validator updates. * `ExportGenesis(ctx context.Context, cdc codec.JSONCodec)`: Calls the [`ExportGenesis`](./08-genesis.md#exportgenesis) function of each module, in the order defined in `OrderExportGenesis`. The export constructs a genesis file from a previously existing state, and is mainly used when a hard-fork upgrade of the chain is required. * `ExportGenesisForModules(ctx context.Context, cdc codec.JSONCodec, modulesToExport []string)`: Behaves the same as `ExportGenesis`, except takes a list of modules to export. -<<<<<<< HEAD:docs/docs/building-modules/01-module-manager.md * `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of all modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from modules. * `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../core/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../core/02-context.md) with an event manager to aggregate [events](../core/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). * `Precommit(ctx context.Context)`: During [`Commit`](../core/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../core/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../core/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../core/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../core/00-baseapp.md#state-updates). * `PrepareCheckState(ctx context.Context)`: During [`Commit`](../core/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../core/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../core/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../core/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../core/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../core/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block. -======= * `RunMigrationBeginBlock(ctx sdk.Context) (bool, error)`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of the upgrade module implementing the `HasBeginBlocker` interface. The function returns a boolean value indicating whether the migration was executed or not and an error if fails. -* `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./05-beginblock-endblock.md) function of each non-upgrade modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from non-upgrade modules. -* `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). -* `EndBlock(context.Context) ([]abci.ValidatorUpdate, error)`: At the end of each block, this function is called from [`BaseApp`](../../develop/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./05-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndblock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../develop/advanced/02-context.md) with an event manager to aggregate [events](../../develop/advanced/08-events.md) emitted from all modules. The function returns an `abci` which contains the aforementioned events, as well as validator set updates (if any). -* `Precommit(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `Precommit` function of each modules implementing the `HasPrecommit` interface, in the order defined in `OrderPrecommiters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../../develop/advanced/00-baseapp.md#state-updates). -* `PrepareCheckState(ctx context.Context)`: During [`Commit`](../../develop/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../../develop/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../develop/advanced/04-store.md#commitmultistore) and, in turn calls the `PrepareCheckState` function of each module implementing the `HasPrepareCheckState` interface, in the order defined in `OrderPrepareCheckStaters`. It creates a child [context](../../develop/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../../develop/advanced/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../../develop/advanced/00-baseapp.md#state-updates) of the next block, and therefore this method can be used to prepare the `checkState` for the next block. ->>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/build/building-modules/01-module-manager.md Here's an example of a concrete integration within an `simapp`: diff --git a/docs/docs/build/building-modules/06-keeper.md b/docs/docs/build/building-modules/06-keeper.md index 400c79bf2185..d5426a7263ea 100644 --- a/docs/docs/build/building-modules/06-keeper.md +++ b/docs/docs/build/building-modules/06-keeper.md @@ -47,14 +47,8 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/staking/keeper/keepe Let us go through the different parameters: * An expected `keeper` is a `keeper` external to a module that is required by the internal `keeper` of said module. External `keeper`s are listed in the internal `keeper`'s type definition as interfaces. These interfaces are themselves defined in an `expected_keepers.go` file in the root of the module's folder. In this context, interfaces are used to reduce the number of dependencies, as well as to facilitate the maintenance of the module itself. -<<<<<<< HEAD:docs/docs/building-modules/06-keeper.md * `storeKey`s grant access to the store(s) of the [multistore](../core/04-store.md) managed by the module. They should always remain unexposed to external modules. * `cdc` is the [codec](../core/05-encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces. The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated. -======= -* `storeKey`s grant access to the store(s) of the [multistore](../../develop/advanced/04-store.md) managed by the module. They should always remain unexposed to external modules. -* `cdc` is the [codec](../../develop/advanced/05-encoding.md) used to marshall and unmarshall structs to/from `[]byte`. The `cdc` can be any of `codec.BinaryCodec`, `codec.JSONCodec` or `codec.Codec` based on your requirements. It can be either a proto or amino codec as long as they implement these interfaces. -* The authority listed is a module account or user account that has the right to change module level parameters. Previously this was handled by the param module, which has been deprecated. ->>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/build/building-modules/06-keeper.md Of course, it is possible to define different types of internal `keeper`s for the same module (e.g. a read-only `keeper`). Each type of `keeper` comes with its own constructor function, which is called from the [application's constructor function](../../develop/beginner/00-app-anatomy.md). This is where `keeper`s are instantiated, and where developers make sure to pass correct instances of modules' `keeper`s to other modules that require them. diff --git a/docs/docs/develop/advanced/00-baseapp.md b/docs/docs/develop/advanced/00-baseapp.md index dd35bccbfc7d..3476606ee552 100644 --- a/docs/docs/develop/advanced/00-baseapp.md +++ b/docs/docs/develop/advanced/00-baseapp.md @@ -454,13 +454,8 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci.go#L623 This function also resets the [main gas meter](../beginner/04-gas-fees.md#main-gas-meter). -<<<<<<< HEAD:docs/docs/core/00-baseapp.md * Initialize the [block gas meter](../basics/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. * Run the application's [`beginBlocker()`](../basics/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../building-modules/05-beginblock-endblock.md#beginblock) method of each of the application's modules. -======= -* Initialize the [block gas meter](../beginner/04-gas-fees.md#block-gas-meter) with the `maxGas` limit. The `gas` consumed within the block cannot go above `maxGas`. This parameter is defined in the application's consensus parameters. -* Run the application's [`beginBlocker()`](../beginner/00-app-anatomy.md#beginblocker-and-endblock), which mainly runs the [`BeginBlocker()`](../../build/building-modules/05-beginblock-endblock.md#beginblock) method of each of the non-upgrade modules. ->>>>>>> f198ea944 (refactor: docs path updates (#17459)):docs/docs/develop/advanced/00-baseapp.md * Set the [`VoteInfos`](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_methods.md#voteinfo) of the application, i.e. the list of validators whose _precommit_ for the previous block was included by the proposer of the current block. This information is carried into the [`Context`](./02-context.md) so that it can be used during transaction execution and EndBlock. #### Transaction Execution diff --git a/docs/rfc/README.md b/docs/rfc/README.md index 0c75501e1623..c4254e7af6e6 100644 --- a/docs/rfc/README.md +++ b/docs/rfc/README.md @@ -36,7 +36,6 @@ sections. ## Table of Contents -<<<<<<< HEAD -======= + * [RFC-002: Zero Copy Encoding](./rfc-002-zero-copy-encoding.md) ->>>>>>> f198ea944 (refactor: docs path updates (#17459)) +