diff --git a/.github/workflows/md-link-checker.yml b/.github/workflows/md-link-checker.yml index 29b2f9f65bff..38560ea8c80c 100644 --- a/.github/workflows/md-link-checker.yml +++ b/.github/workflows/md-link-checker.yml @@ -1,12 +1,15 @@ name: Check Markdown links on: - schedule: - - cron: '* */24 * * *' + pull_request: + paths: + - "docs/**" jobs: markdown-link-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + - run: cd docs && sh ./pre.sh - uses: gaurav-nelson/github-action-markdown-link-check@1.0.15 with: folder-path: "docs" + - run: cd docs && sh ./post.sh diff --git a/docs/.gitignore b/docs/.gitignore index 58e7dd164e4e..87f7c0101d38 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -11,4 +11,4 @@ docs/packages/02-collections.md docs/packages/03-orm.md docs/user/run-node/04-rosetta.md docs/build/migrations/02-upgrading.md -docs/develop/advanced/17-autocli.md +docs/learn/advanced/17-autocli.md diff --git a/docs/Introduction.md b/docs/Introduction.md index d2c61b263942..1b92ab6b1e11 100644 --- a/docs/Introduction.md +++ b/docs/Introduction.md @@ -9,16 +9,16 @@ 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**](develop/intro/00-overview.md) - Learn about all the parts of the Cosmos SDK. +* [**Introductions to the Cosmos SDK**](learn/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**](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. +* [**Introduction**](learn/intro/00-overview.md) - High-level overview of the Cosmos SDK. +* [**Basics**](learn/beginner/00-app-anatomy.md) - Anatomy of a blockchain, transaction lifecycle, accounts and more. +* [**Core Concepts**](learn/advanced/00-baseapp.md) - Read about the core concepts like baseapp, the store, or the server. * [**Building Modules**](build/building-modules/00-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. diff --git a/docs/architecture/adr-033-protobuf-inter-module-comm.md b/docs/architecture/adr-033-protobuf-inter-module-comm.md index 672c906d755e..28c69a910b23 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](../../develop/advanced/10-ocap.md), it is stated that: +In the current Cosmos SDK documentation on the [Object-Capability Model](../../learn/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/build/building-apps/02-app-mempool.md b/docs/build/building-apps/02-app-mempool.md index 1f591fc6de12..630b94ba70ee 100644 --- a/docs/build/building-apps/02-app-mempool.md +++ b/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](../../develop/advanced/00-baseapp.md) +* [BaseApp](../../learn/advanced/00-baseapp.md) ::: diff --git a/docs/build/building-modules/00-intro.md b/docs/build/building-modules/00-intro.md index 7bfaf8e980ac..6850f0b6740e 100644 --- a/docs/build/building-modules/00-intro.md +++ b/docs/build/building-modules/00-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](../../develop/beginner/00-app-anatomy.md) -* [Lifecycle of a Cosmos SDK transaction](../../develop/beginner/01-tx-lifecycle.md) +* [Anatomy of a Cosmos SDK application](../../learn/beginner/00-app-anatomy.md) +* [Lifecycle of a Cosmos SDK transaction](../../learn/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](../../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. +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](../../learn/advanced/00-baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../../learn/advanced/04-store.md#multistore) to persist state, a [server](../../learn/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](../../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. +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](../../learn/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`](../../learn/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](../../develop/advanced/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](../../learn/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`](../../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). +* A [`Msg` service](./02-messages-and-queries.md#messages), used to process messages when they are routed to the module by [`BaseApp`](../../learn/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`](../../learn/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/build/building-modules/01-module-manager.md b/docs/build/building-modules/01-module-manager.md index 7666cfec5262..dfd17d5f5536 100644 --- a/docs/build/building-modules/01-module-manager.md +++ b/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](../../develop/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`PreBlocker`](../../develop/beginner/00-app-anatomy#preblocker) and [`BeginBlocker` and `EndBlocker`](../../develop/beginner/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](../../learn/advanced/00-baseapp.md#routing), and allows application developers to set the order of execution of a variety of functions like [`PreBlocker`](../../learn/beginner/00-app-anatomy#preblocker) and [`BeginBlocker` and `EndBlocker`](../../learn/beginner/00-app-anatomy.md#begingblocker-and-endblocker). ::: :::note Pre-requisite Readings @@ -46,7 +46,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](../../develop/beginner/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](../../learn/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. @@ -224,7 +224,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'](../../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. +* `Precommit(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../../learn/advanced/00-baseapp.md#commit) of each block using the [`finalizeblockstate`](../../learn/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` @@ -234,7 +234,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'](../../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. +* `PrepareCheckState(context.Context)`: This method gives module developers the option to implement logic that is automatically triggered during [`Commit'](../../learn/advanced/00-baseapp.md#commit) of each block using the [`checkState`](../../learn/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 @@ -272,15 +272,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`](../../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). +* `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`](../../learn/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](../../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). +* `RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)`: Registers the [`codec.LegacyAmino`s](../../learn/advanced/05-encoding.md#amino) of each of the application's `AppModuleBasic`. This function is usually called early on in the [application's construction](../../learn/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`](../../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). +* `AddTxCommands(rootTxCmd *cobra.Command)`: Adds modules' transaction commands (defined as `GetTxCmd() *cobra.Command`) to the application's [`rootTxCommand`](../../learn/advanced/07-cli.md#transaction-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../learn/advanced/07-cli.md). +* `AddQueryCommands(rootQueryCmd *cobra.Command)`: Adds modules' query commands (defined as `GetQueryCmd() *cobra.Command`) to the application's [`rootQueryCommand`](../../learn/advanced/07-cli.md#query-commands). This function is usually called function from the `main.go` function of the [application's command-line interface](../../learn/advanced/07-cli.md). ### `Manager` @@ -292,26 +292,26 @@ 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](../../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). +* `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](../../learn/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](../../learn/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](../../develop/beginner/00-app-anatomy.md#constructor-function). -* `SetOrderPreBlockers(moduleNames ...string)`: Sets the order in which the `PreBlock()` function of each module will be called before `BeginBlock()` of all modules. 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). +* `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](../../learn/beginner/00-app-anatomy.md#constructor-function). +* `SetOrderPreBlockers(moduleNames ...string)`: Sets the order in which the `PreBlock()` function of each module will be called before `BeginBlock()` of all modules. This function is generally called from the application's main [constructor function](../../learn/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](../../learn/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](../../learn/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](../../learn/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](../../learn/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. -* `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`](./06-beginblock-endblock.md) function of each 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 each 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`](./06-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`](./06-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. +* `BeginBlock(ctx context.Context) error`: At the beginning of each block, this function is called from [`BaseApp`](../../learn/advanced/00-baseapp.md#beginblock) and, in turn, calls the [`BeginBlock`](./06-beginblock-endblock.md) function of each modules implementing the `appmodule.HasBeginBlocker` interface, in the order defined in `OrderBeginBlockers`. It creates a child [context](../../learn/advanced/02-context.md) with an event manager to aggregate [events](../../learn/advanced/08-events.md) emitted from each modules. +* `EndBlock(ctx context.Context) error`: At the end of each block, this function is called from [`BaseApp`](../../learn/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./06-beginblock-endblock.md) function of each modules implementing the `appmodule.HasEndBlocker` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../learn/advanced/02-context.md) with an event manager to aggregate [events](../../learn/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`](../../learn/advanced/00-baseapp.md#endblock) and, in turn, calls the [`EndBlock`](./06-beginblock-endblock.md) function of each modules implementing the `module.HasABCIEndBlock` interface, in the order defined in `OrderEndBlockers`. It creates a child [context](../../learn/advanced/02-context.md) with an event manager to aggregate [events](../../learn/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`](../../learn/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately before the [`deliverState`](../../learn/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../learn/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](../../learn/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the newly committed block's [`finalizeblockstate`](../../learn/advanced/00-baseapp.md#state-updates). +* `PrepareCheckState(ctx context.Context)`: During [`Commit`](../../learn/advanced/00-baseapp.md#commit), this function is called from `BaseApp` immediately after the [`deliverState`](../../learn/advanced/00-baseapp.md#state-updates) is written to the underlying [`rootMultiStore`](../../learn/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](../../learn/advanced/02-context.md) where the underlying `CacheMultiStore` is that of the next block's [`checkState`](../../learn/advanced/00-baseapp.md#state-updates). Writes to this state will be present in the [`checkState`](../../learn/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. Here's an example of a concrete integration within an `simapp`: diff --git a/docs/build/building-modules/02-messages-and-queries.md b/docs/build/building-modules/02-messages-and-queries.md index 3d92cd82a5fa..573c35cd770e 100644 --- a/docs/build/building-modules/02-messages-and-queries.md +++ b/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](../../develop/advanced/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](../../learn/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`](../../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). +When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../../learn/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](../../learn/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](../../develop/advanced/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](../../learn/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](../../develop/beginner/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](../../learn/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](../../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. +* `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](../../learn/advanced/00-baseapp.md#query). +* `queryRoute` is used by `BaseApp`'s [`queryRouter`](../../learn/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](../../develop/advanced/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](../../learn/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/build/building-modules/03-msg-services.md b/docs/build/building-modules/03-msg-services.md index b64eaa45f718..4d2bf6ee37dc 100644 --- a/docs/build/building-modules/03-msg-services.md +++ b/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`](../../develop/advanced/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`](../../learn/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](../../develop/advanced/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](../../learn/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](../../develop/advanced/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](../../learn/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`: @@ -110,7 +110,7 @@ This diagram shows a typical structure of a Protobuf `Msg` service, and how the ## Telemetry -New [telemetry metrics](../../develop/advanced/09-telemetry.md) can be created from `msgServer` methods when handling messages. +New [telemetry metrics](../../learn/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/build/building-modules/04-query-services.md b/docs/build/building-modules/04-query-services.md index 29542d86cc3c..a787a0c22b6f 100644 --- a/docs/build/building-modules/04-query-services.md +++ b/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](../../develop/advanced/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](../../learn/advanced/00-baseapp.md#query). ::: :::note Pre-requisite Readings diff --git a/docs/build/building-modules/06-beginblock-endblock.md b/docs/build/building-modules/06-beginblock-endblock.md index 35b5bb350b2e..a8eafdf67be7 100644 --- a/docs/build/building-modules/06-beginblock-endblock.md +++ b/docs/build/building-modules/06-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`](../../develop/advanced/00-baseapp.md#beginblock) and [`EndBlock`](../../develop/advanced/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`](../../learn/advanced/00-baseapp.md#beginblock) and [`EndBlock`](../../learn/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`](../../develop/advanced/02-context.md) to retrieve information about the latest state. +* They generally use the [`keeper`](./06-keeper.md) and [`ctx`](../../learn/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`](../../develop/advanced/08-events.md) via the `ctx`'s `EventManager`. +* If needed, they can emit [`events`](../../learn/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/build/building-modules/06-keeper.md b/docs/build/building-modules/06-keeper.md index 761171439fbc..399ec648cac8 100644 --- a/docs/build/building-modules/06-keeper.md +++ b/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](../../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 Cosmos SDK adopts an [object-capabilities-based approach](../../learn/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](../../learn/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](../../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. +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](../../learn/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,11 +47,11 @@ 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. -* `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. +* `storeKey`s grant access to the store(s) of the [multistore](../../learn/advanced/04-store.md) managed by the module. They should always remain unexposed to external modules. +* `cdc` is the [codec](../../learn/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. -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. +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](../../learn/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 @@ -83,7 +83,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`](../../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. +The [module `KVStore`](../../learn/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/build/building-modules/07-invariants.md b/docs/build/building-modules/07-invariants.md index cd85864bfa3b..018796f716a6 100644 --- a/docs/build/building-modules/07-invariants.md +++ b/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](../../develop/beginner/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](../../learn/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/build/building-modules/08-genesis.md b/docs/build/building-modules/08-genesis.md index 546eb5fb9263..7abb21fb6577 100644 --- a/docs/build/building-modules/08-genesis.md +++ b/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](../../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. +The subset of the genesis state defined from a given module is generally defined in a `genesis.proto` file ([more info](../../learn/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`](../../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 `InitGenesis` method is executed during [`InitChain`](../../learn/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](../../develop/beginner/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](../../learn/beginner/00-app-anatomy.md#constructor-function). See an example of `InitGenesis` from the `auth` module: diff --git a/docs/build/building-modules/09-module-interfaces.md b/docs/build/building-modules/09-module-interfaces.md index 262442661cb5..4552baef240e 100644 --- a/docs/build/building-modules/09-module-interfaces.md +++ b/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](../../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. +One of the main interfaces for an application is the [command-line interface](../../learn/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](../../develop/advanced/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](../../learn/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](../../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](../../learn/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](../../learn/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/build/building-modules/13-upgrade.md b/docs/build/building-modules/13-upgrade.md index 703b4cd28082..908a6a06eeb0 100644 --- a/docs/build/building-modules/13-upgrade.md +++ b/docs/build/building-modules/13-upgrade.md @@ -5,12 +5,12 @@ sidebar_position: 1 # Upgrading Modules :::note Synopsis -[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. +[In-Place Store Migrations](../../learn/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](../../develop/advanced/15-upgrade.md) +* [In-Place Store Migration](../../learn/advanced/15-upgrade.md) ::: diff --git a/docs/build/building-modules/14-simulator.md b/docs/build/building-modules/14-simulator.md index 5360709f6d58..8fe2d92c38bf 100644 --- a/docs/build/building-modules/14-simulator.md +++ b/docs/build/building-modules/14-simulator.md @@ -6,7 +6,7 @@ sidebar_position: 1 :::note Pre-requisite Readings -* [Cosmos Blockchain Simulator](../../develop/advanced/12-simulation.md) +* [Cosmos Blockchain Simulator](../../learn/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](../../develop/advanced/01-transactions.md) of a +Operations on the simulation are simulated using the full [transaction cycle](../../learn/advanced/01-transactions.md) of a `ABCI` application that exposes the `BaseApp`. Shown below is how weights are set: diff --git a/docs/build/building-modules/17-preblock.md b/docs/build/building-modules/17-preblock.md index 8a0f3baa9280..a79646bd4e70 100644 --- a/docs/build/building-modules/17-preblock.md +++ b/docs/build/building-modules/17-preblock.md @@ -5,7 +5,7 @@ sidebar_position: 1 # PreBlocker :::note Synopsis -`PreBlocker` is optional method module developers can implement in their module. They will be triggered before [`BeginBlock`](../../develop/advanced/00-baseapp.md#beginblock). +`PreBlocker` is optional method module developers can implement in their module. They will be triggered before [`BeginBlock`](../../learn/advanced/00-baseapp.md#beginblock). ::: :::note Pre-requisite Readings diff --git a/docs/develop/advanced/00-baseapp.md b/docs/learn/advanced/00-baseapp.md similarity index 100% rename from docs/develop/advanced/00-baseapp.md rename to docs/learn/advanced/00-baseapp.md diff --git a/docs/develop/advanced/01-transactions.md b/docs/learn/advanced/01-transactions.md similarity index 100% rename from docs/develop/advanced/01-transactions.md rename to docs/learn/advanced/01-transactions.md diff --git a/docs/develop/advanced/02-context.md b/docs/learn/advanced/02-context.md similarity index 100% rename from docs/develop/advanced/02-context.md rename to docs/learn/advanced/02-context.md diff --git a/docs/develop/advanced/03-node.md b/docs/learn/advanced/03-node.md similarity index 100% rename from docs/develop/advanced/03-node.md rename to docs/learn/advanced/03-node.md diff --git a/docs/develop/advanced/04-store.md b/docs/learn/advanced/04-store.md similarity index 100% rename from docs/develop/advanced/04-store.md rename to docs/learn/advanced/04-store.md diff --git a/docs/develop/advanced/05-encoding.md b/docs/learn/advanced/05-encoding.md similarity index 100% rename from docs/develop/advanced/05-encoding.md rename to docs/learn/advanced/05-encoding.md diff --git a/docs/develop/advanced/06-grpc_rest.md b/docs/learn/advanced/06-grpc_rest.md similarity index 100% rename from docs/develop/advanced/06-grpc_rest.md rename to docs/learn/advanced/06-grpc_rest.md diff --git a/docs/develop/advanced/07-cli.md b/docs/learn/advanced/07-cli.md similarity index 100% rename from docs/develop/advanced/07-cli.md rename to docs/learn/advanced/07-cli.md diff --git a/docs/develop/advanced/08-events.md b/docs/learn/advanced/08-events.md similarity index 100% rename from docs/develop/advanced/08-events.md rename to docs/learn/advanced/08-events.md diff --git a/docs/develop/advanced/09-telemetry.md b/docs/learn/advanced/09-telemetry.md similarity index 100% rename from docs/develop/advanced/09-telemetry.md rename to docs/learn/advanced/09-telemetry.md diff --git a/docs/develop/advanced/10-ocap.md b/docs/learn/advanced/10-ocap.md similarity index 100% rename from docs/develop/advanced/10-ocap.md rename to docs/learn/advanced/10-ocap.md diff --git a/docs/develop/advanced/11-runtx_middleware.md b/docs/learn/advanced/11-runtx_middleware.md similarity index 100% rename from docs/develop/advanced/11-runtx_middleware.md rename to docs/learn/advanced/11-runtx_middleware.md diff --git a/docs/develop/advanced/12-simulation.md b/docs/learn/advanced/12-simulation.md similarity index 100% rename from docs/develop/advanced/12-simulation.md rename to docs/learn/advanced/12-simulation.md diff --git a/docs/develop/advanced/13-proto-docs.md b/docs/learn/advanced/13-proto-docs.md similarity index 100% rename from docs/develop/advanced/13-proto-docs.md rename to docs/learn/advanced/13-proto-docs.md diff --git a/docs/develop/advanced/15-upgrade.md b/docs/learn/advanced/15-upgrade.md similarity index 100% rename from docs/develop/advanced/15-upgrade.md rename to docs/learn/advanced/15-upgrade.md diff --git a/docs/develop/advanced/16-config.md b/docs/learn/advanced/16-config.md similarity index 100% rename from docs/develop/advanced/16-config.md rename to docs/learn/advanced/16-config.md diff --git a/docs/develop/advanced/_category_.json b/docs/learn/advanced/_category_.json similarity index 100% rename from docs/develop/advanced/_category_.json rename to docs/learn/advanced/_category_.json diff --git a/docs/develop/advanced/baseapp_state-begin_block.png b/docs/learn/advanced/baseapp_state-begin_block.png similarity index 100% rename from docs/develop/advanced/baseapp_state-begin_block.png rename to docs/learn/advanced/baseapp_state-begin_block.png diff --git a/docs/develop/advanced/baseapp_state-checktx.png b/docs/learn/advanced/baseapp_state-checktx.png similarity index 100% rename from docs/develop/advanced/baseapp_state-checktx.png rename to docs/learn/advanced/baseapp_state-checktx.png diff --git a/docs/develop/advanced/baseapp_state-commit.png b/docs/learn/advanced/baseapp_state-commit.png similarity index 100% rename from docs/develop/advanced/baseapp_state-commit.png rename to docs/learn/advanced/baseapp_state-commit.png diff --git a/docs/develop/advanced/baseapp_state-deliver_tx.png b/docs/learn/advanced/baseapp_state-deliver_tx.png similarity index 100% rename from docs/develop/advanced/baseapp_state-deliver_tx.png rename to docs/learn/advanced/baseapp_state-deliver_tx.png diff --git a/docs/develop/advanced/baseapp_state-initchain.png b/docs/learn/advanced/baseapp_state-initchain.png similarity index 100% rename from docs/develop/advanced/baseapp_state-initchain.png rename to docs/learn/advanced/baseapp_state-initchain.png diff --git a/docs/develop/advanced/baseapp_state-prepareproposal.png b/docs/learn/advanced/baseapp_state-prepareproposal.png similarity index 100% rename from docs/develop/advanced/baseapp_state-prepareproposal.png rename to docs/learn/advanced/baseapp_state-prepareproposal.png diff --git a/docs/develop/advanced/baseapp_state-processproposal.png b/docs/learn/advanced/baseapp_state-processproposal.png similarity index 100% rename from docs/develop/advanced/baseapp_state-processproposal.png rename to docs/learn/advanced/baseapp_state-processproposal.png diff --git a/docs/develop/advanced/baseapp_state.png b/docs/learn/advanced/baseapp_state.png similarity index 100% rename from docs/develop/advanced/baseapp_state.png rename to docs/learn/advanced/baseapp_state.png diff --git a/docs/develop/beginner/00-app-anatomy.md b/docs/learn/beginner/00-app-anatomy.md similarity index 100% rename from docs/develop/beginner/00-app-anatomy.md rename to docs/learn/beginner/00-app-anatomy.md diff --git a/docs/develop/beginner/01-tx-lifecycle.md b/docs/learn/beginner/01-tx-lifecycle.md similarity index 100% rename from docs/develop/beginner/01-tx-lifecycle.md rename to docs/learn/beginner/01-tx-lifecycle.md diff --git a/docs/develop/beginner/02-query-lifecycle.md b/docs/learn/beginner/02-query-lifecycle.md similarity index 100% rename from docs/develop/beginner/02-query-lifecycle.md rename to docs/learn/beginner/02-query-lifecycle.md diff --git a/docs/develop/beginner/03-accounts.md b/docs/learn/beginner/03-accounts.md similarity index 100% rename from docs/develop/beginner/03-accounts.md rename to docs/learn/beginner/03-accounts.md diff --git a/docs/develop/beginner/04-gas-fees.md b/docs/learn/beginner/04-gas-fees.md similarity index 100% rename from docs/develop/beginner/04-gas-fees.md rename to docs/learn/beginner/04-gas-fees.md diff --git a/docs/develop/beginner/_category_.json b/docs/learn/beginner/_category_.json similarity index 100% rename from docs/develop/beginner/_category_.json rename to docs/learn/beginner/_category_.json diff --git a/docs/develop/intro/00-overview.md b/docs/learn/intro/00-overview.md similarity index 100% rename from docs/develop/intro/00-overview.md rename to docs/learn/intro/00-overview.md diff --git a/docs/develop/intro/01-why-app-specific.md b/docs/learn/intro/01-why-app-specific.md similarity index 100% rename from docs/develop/intro/01-why-app-specific.md rename to docs/learn/intro/01-why-app-specific.md diff --git a/docs/develop/intro/02-sdk-app-architecture.md b/docs/learn/intro/02-sdk-app-architecture.md similarity index 100% rename from docs/develop/intro/02-sdk-app-architecture.md rename to docs/learn/intro/02-sdk-app-architecture.md diff --git a/docs/develop/intro/03-sdk-design.md b/docs/learn/intro/03-sdk-design.md similarity index 100% rename from docs/develop/intro/03-sdk-design.md rename to docs/learn/intro/03-sdk-design.md diff --git a/docs/develop/intro/_category_.json b/docs/learn/intro/_category_.json similarity index 100% rename from docs/develop/intro/_category_.json rename to docs/learn/intro/_category_.json diff --git a/docs/post.sh b/docs/post.sh index 57e620b361bf..bd256eddf1ae 100755 --- a/docs/post.sh +++ b/docs/post.sh @@ -1,16 +1,16 @@ #!/usr/bin/env bash -find docs/build/modules ! -name '_category_.json' -type f -exec rm -rf {} + +find build/modules ! -name '_category_.json' -type f -exec rm -rf {} + rm -rf build/tooling/01-cosmovisor.md rm -rf build/tooling/02-confix.md rm -rf build/tooling/03-hubl.md rm -rf build/packages/01-depinject.md rm -rf build/packages/02-collections.md rm -rf build/packages/03-orm.md -rm -rf develop/advaced-concepts/17-autocli.md +rm -rf learn/advaced-concepts/17-autocli.md rm -rf user/run-node/04-rosetta.md rm -rf build/architecture rm -rf build/spec rm -rf build/rfc -rm -rf develop/advanced/17-autocli.md +rm -rf learn/advanced/17-autocli.md rm -rf build/migrations/02-upgrading.md diff --git a/docs/pre.sh b/docs/pre.sh index 6fc09224f931..f5eacdf17e89 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/build/modules/$(echo $D | awk -F/ '{print $NF}') + MODDOC=build/modules/$(echo $D | awk -F/ '{print $NF}') rm -rf $MODDOC mkdir -p $MODDOC && cp -r $D/README.md "$_" fi @@ -11,20 +11,21 @@ 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 ./build/modules/auth/1-vesting.md -cp ../x/auth/tx/README.md ./build/modules/auth/2-tx.md +cp -r ../x/auth/vesting/README.md ./build/modules/auth/1-vesting.md +cp -r ../x/auth/tx/README.md ./build/modules/auth/2-tx.md ## Add modules page list -cat ../x/README.md | sed 's/\.\.\/\/build\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./modules/README.md +cat ../x/README.md | sed 's/\.\.\/\/build\/building-modules\/README\.md/\/building-modules\/intro\.html/g' > ./build/modules/README.md ## Add tooling documentation cp ../tools/cosmovisor/README.md ./build/tooling/01-cosmovisor.md cp ../tools/confix/README.md ./build/tooling/02-confix.md cp ../tools/hubl/README.md ./build/tooling/03-hubl.md -wget -O /user/run-node/04-rosetta.md https://raw.githubusercontent.com/cosmos/rosetta/main/README.md + +wget -x -O ./user/run-node/04-rosetta.md https://raw.githubusercontent.com/cosmos/rosetta/main/README.md ## Add package documentation -cp ../client/v2/README.md ./develop/advanced/17-autocli.md +cp ../client/v2/README.md ./learn/advanced/17-autocli.md cp ../depinject/README.md ./build/packages/01-depinject.md cp ../collections/README.md ./build/packages/02-collections.md cp ../orm/README.md ./build/packages/03-orm.md diff --git a/docs/user/run-node/00-keyring.md b/docs/user/run-node/00-keyring.md index 09d8b07422d2..0ed06d412bad 100644 --- a/docs/user/run-node/00-keyring.md +++ b/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**](../../develop/beginner/00-app-anatomy.md). +This document describes how to configure and use the keyring and its various backends for an [**application**](../../learn/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/user/run-node/01-run-node.md b/docs/user/run-node/01-run-node.md index fc539989b93e..7bd1a9c79f17 100644 --- a/docs/user/run-node/01-run-node.md +++ b/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](../../develop/beginner/00-app-anatomy.md) +* [Anatomy of a Cosmos SDK Application](../../learn/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](../../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`: +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](../../learn/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/user/run-node/02-interact-node.md b/docs/user/run-node/02-interact-node.md index 48193504a603..a511aec41836 100644 --- a/docs/user/run-node/02-interact-node.md +++ b/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](../../develop/advanced/06-grpc_rest.md) +* [gRPC, REST and CometBFT Endpoints](../../learn/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](../../develop/advanced/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](../../learn/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](../../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. +As described in the [gRPC guide](../../learn/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/user/run-node/03-txs.md b/docs/user/run-node/03-txs.md index faf1d8b65def..106f02e8e8e8 100644 --- a/docs/user/run-node/03-txs.md +++ b/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](../../develop/advanced/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](../../learn/advanced/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. ```go import ( diff --git a/docs/user/run-node/04-rosetta.md b/docs/user/run-node/04-rosetta.md deleted file mode 100644 index 936666fa80f6..000000000000 --- a/docs/user/run-node/04-rosetta.md +++ /dev/null @@ -1,144 +0,0 @@ -# Rosetta - -The `rosetta` project implements Coinbase's [Rosetta API](https://www.rosetta-api.org). This document provides instructions on how to use the Rosetta API integration. For information about the motivation and design choices, refer to [ADR 035](https://docs.cosmos.network/main/architecture/adr-035-rosetta-api-support). - -## Installing Rosetta - -The Rosetta API server is a stand-alone server that connects to a node of a chain developed with Cosmos SDK. - -Rosetta can be added to any cosmos chain node. standalone or natively. - -### Standalone - -Rosetta can be executed as a standalone service, it connects to the node endpoints and expose the required endpoints. - -Install Rosetta standalone server with the following command: - -```bash -go install github.com/cosmos/rosetta -``` - -Alternatively, for building from source, simply run `make rosetta`. The binary will be located in the root folder. - -### Native - As a node command - -To enable Native Rosetta API support, it's required to add the `RosettaCommand` to your application's root command file (e.g. `simd/cmd/root.go`). - -Import the `rosettaCmd` package: - -```go -import "github.com/cosmos/rosetta/cmd" -``` - -Find the following line: - -```go -initRootCmd(rootCmd, encodingConfig) -``` - -After that line, add the following: - -```go -rootCmd.AddCommand( - rosettaCmd.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Codec) -) -``` - -The `RosettaCommand` function builds the `rosetta` root command and is defined in the `rosettaCmd` package (`github.com/cosmos/rosetta/cmd`). - -Since we’ve updated the Cosmos SDK to work with the Rosetta API, updating the application's root command file is all you need to do. - -An implementation example can be found in `simapp` package. - -## Use Rosetta Command - -To run Rosetta in your application CLI, use the following command: - -> **Note:** if using the native approach, add your node name before any rosetta comand. - -```shell -rosetta --help -``` - -To test and run Rosetta API endpoints for applications that are running and exposed, use the following command: - -```shell -rosetta - --blockchain "your application name (ex: gaia)" - --network "your chain identifier (ex: testnet-1)" - --tendermint "tendermint endpoint (ex: localhost:26657)" - --grpc "gRPC endpoint (ex: localhost:9090)" - --addr "rosetta binding address (ex: :8080)" - --grpc-types-server (optional) "gRPC endpoint for message descriptor types" -``` - -## Plugins - Multi chain connections - -Rosetta will try to reflect the node types trough reflection over the node gRPC endpoints, there may be cases were this approach is not enough. It is possible to extend or implement the required types easily trough plugins. - -To use Rosetta over any chain, it is required to set up prefixes and registering zone specific interfaces through plugins. - -Each plugin is a minimalist implementation of `InitZone` and `RegisterInterfaces` which allow Rosetta to parse chain specific data. There is an example for cosmos-hub chain under `plugins/cosmos-hun/` folder -- **InitZone**: An empty method that is executed first and defines prefixes, parameters and other settings. -- **RegisterInterfaces**: This method receives an interface registry which is were the zone specific types and interfaces will be loaded - -In order to add a new plugin: -1. Create a folder over `plugins` folder with the name of the desired zone -2. Add a `main.go` file with the mentioned methods above. -3. Build the code binary through `go build -buildmode=plugin -o main.so main.go` - -The plugin folder is selected through the cli `--plugin` flag and loaded into the Rosetta server. - -## Extensions - -There are two ways in which you can customize and extend the implementation with your custom settings. - -### Message extension - -In order to make an `sdk.Msg` understandable by rosetta the only thing which is required is adding the methods to your messages that satisfy the `rosetta.Msg` interface. Examples on how to do so can be found in the staking types such as `MsgDelegate`, or in bank types such as `MsgSend`. - -### Client interface override - -In case more customization is required, it's possible to embed the Client type and override the methods which require customizations. - -Example: - -```go -package custom_client -import ( - -"context" -"github.com/coinbase/rosetta-sdk-go/types" -"github.com/cosmos/rosetta/lib" -) - -// CustomClient embeds the standard cosmos client -// which means that it implements the cosmos-rosetta-gateway Client -// interface while at the same time allowing to customize certain methods -type CustomClient struct { - *rosetta.Client -} - -func (c *CustomClient) ConstructionPayload(_ context.Context, request *types.ConstructionPayloadsRequest) (resp *types.ConstructionPayloadsResponse, err error) { - // provide custom signature bytes - panic("implement me") -} -``` - -NOTE: when using a customized client, the command cannot be used as the constructors required **may** differ, so it's required to create a new one. We intend to provide a way to init a customized client without writing extra code in the future. - -### Error extension - -Since rosetta requires to provide 'returned' errors to network options. In order to declare a new rosetta error, we use the `errors` package in cosmos-rosetta-gateway. - -Example: - -```go -package custom_errors -import crgerrs "github.com/cosmos/rosetta/lib/errors" - -var customErrRetriable = true -var CustomError = crgerrs.RegisterError(100, "custom message", customErrRetriable, "description") -``` - -Note: errors must be registered before cosmos-rosetta-gateway's `Server`.`Start` method is called. Otherwise the registration will be ignored. Errors with same code will be ignored too.