From a47bd592e951d34ebbffca03f85ca98d65b61be8 Mon Sep 17 00:00:00 2001 From: Brenn Hill Date: Wed, 29 Sep 2021 00:33:58 +0700 Subject: [PATCH] docs: 10180 Fix SDK (#10237) * docs: Fix Cosmos-sdk references in md files * Fix SDK to Cosmos SDK in all found places and adjust grammar in turn * Add changelog entry * Update docs/core/context.md Co-authored-by: Barrie Byron * Update docs/architecture/adr-010-modular-antehandler.md Co-authored-by: Barrie Byron * Update docs/basics/README.md Co-authored-by: Barrie Byron * Update docs/architecture/adr-040-storage-and-smt-state-commitments.md Co-authored-by: Barrie Byron * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron * Update docs/core/baseapp.md Co-authored-by: Barrie Byron * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron * Update docs/basics/accounts.md Co-authored-by: Barrie Byron * docs 10180 fix 'an Cosmos SDK' where used Co-authored-by: Barrie Byron Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com> Co-authored-by: Robert Zaremba --- CHANGELOG.md | 2 +- CONTRIBUTING.md | 4 +-- LICENSE | 2 +- docs/README.md | 2 +- docs/architecture/adr-002-docs-structure.md | 14 ++++---- .../adr-003-dynamic-capability-store.md | 2 +- .../adr-006-secret-store-replacement.md | 4 +-- .../adr-010-modular-antehandler.md | 12 +++---- .../adr-011-generalize-genesis-accounts.md | 2 +- docs/architecture/adr-012-state-accessors.md | 2 +- ...dr-016-validator-consensus-key-rotation.md | 4 +-- .../adr-017-historical-header-module.md | 6 ++-- .../adr-019-protobuf-state-encoding.md | 8 ++--- .../adr-020-protobuf-transaction-encoding.md | 2 +- .../adr-021-protobuf-query-encoding.md | 4 +-- .../adr-022-custom-panic-handling.md | 2 +- docs/architecture/adr-023-protobuf-naming.md | 4 +-- ...27-deterministic-protobuf-serialization.md | 2 +- .../adr-028-public-key-addresses.md | 10 +++--- docs/architecture/adr-030-authz-module.md | 2 +- docs/architecture/adr-031-msg-service.md | 2 +- docs/architecture/adr-032-typed-events.md | 14 ++++---- .../adr-033-protobuf-inter-module-comm.md | 6 ++-- .../adr-035-rosetta-api-support.md | 8 ++--- .../adr-036-arbitrary-signature.md | 2 +- ...r-040-storage-and-smt-state-commitments.md | 18 +++++------ .../adr-041-in-place-store-migrations.md | 8 ++--- docs/architecture/adr-042-group-module.md | 2 +- .../adr-044-protobuf-updates-guidelines.md | 22 ++++++------- .../adr-045-check-delivertx-middlewares.md | 12 +++---- docs/basics/README.md | 2 +- docs/basics/accounts.md | 12 +++---- docs/basics/app-anatomy.md | 32 +++++++++---------- docs/basics/gas-fees.md | 8 ++--- docs/basics/query-lifecycle.md | 6 ++-- docs/basics/tx-lifecycle.md | 2 +- docs/building-modules/errors.md | 8 ++--- docs/building-modules/intro.md | 20 ++++++------ docs/building-modules/invariants.md | 2 +- docs/building-modules/keeper.md | 2 +- docs/building-modules/messages-and-queries.md | 12 +++---- docs/building-modules/module-interfaces.md | 6 ++-- docs/building-modules/module-manager.md | 4 +-- docs/building-modules/query-services.md | 2 +- docs/building-modules/simulator.md | 6 ++-- docs/core/baseapp.md | 10 +++--- docs/core/cli.md | 22 ++++++------- docs/core/context.md | 6 ++-- docs/core/encoding.md | 16 +++++----- docs/core/events.md | 10 +++--- docs/core/grpc_rest.md | 10 +++--- docs/core/node.md | 10 +++--- docs/core/ocap.md | 2 +- docs/core/proto-docs.md | 32 +++++++++---------- docs/core/runtx_middleware.md | 4 +-- docs/core/simulation.md | 8 ++--- docs/core/store.md | 6 ++-- docs/core/transactions.md | 12 +++---- docs/core/upgrade.md | 4 +-- docs/ibc/integration.md | 4 +-- docs/ibc/relayer.md | 2 +- docs/ibc/upgrades/README.md | 2 +- docs/ibc/upgrades/quick-guide.md | 4 +-- docs/intro/README.md | 2 +- docs/intro/overview.md | 12 +++---- docs/intro/sdk-app-architecture.md | 4 +-- docs/intro/sdk-design.md | 14 ++++---- docs/intro/why-app-specific.md | 2 +- docs/migrations/rest.md | 2 +- docs/run-node/interact-node.md | 2 +- docs/run-node/run-node.md | 6 ++-- docs/run-node/txs.md | 4 +-- docs/spec/README.md | 4 +-- docs/spec/reserve-pool/TODO.md | 2 +- docs/using-the-sdk/README.md | 2 +- 75 files changed, 264 insertions(+), 264 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b05cc98fbe4..32c849b6de53 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -121,7 +121,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ * [\#9699](https://github.com/cosmos/cosmos-sdk/pull/9699) Add `:`, `.`, `-`, and `_` as allowed characters in the default denom regular expression. ### Bug Fixes - +* [#10180](https://github.com/cosmos/cosmos-sdk/issues/10180) Documentation: make references to Cosmos SDK consistent * (store) [#10218](https://github.com/cosmos/cosmos-sdk/pull/10218) Charge gas even when there are no entries while seeking. * (x/genutil) [#10104](https://github.com/cosmos/cosmos-sdk/pull/10104) Ensure the `init` command reads the `--home` flag value correctly. * [\#9651](https://github.com/cosmos/cosmos-sdk/pull/9651) Change inconsistent limit of `0` to `MaxUint64` on InfiniteGasMeter and add GasRemaining func to GasMeter. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fb782070f40..7d07145fd0a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ - [Point Release Procedure](#point-release-procedure) - [Code Owner Membership](#code-owner-membership) -Thank you for considering making contributions to Cosmos-SDK and related +Thank you for considering making contributions to the Cosmos SDK and related repositories! Contributing to this repo can mean many things such as participating in @@ -65,7 +65,7 @@ Other notes: ## Architecture Decision Records (ADR) -When proposing an architecture decision for the SDK, please start by opening an [issue](https://github.com/cosmos/cosmos-sdk/issues/new/choose) or a [discussion](https://github.com/cosmos/cosmos-sdk/discussions/new) with a summary of the proposal. Once the proposal has been discussed and there is rough alignment on a high-level approach to the design, the [ADR creation process](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/PROCESS.md) can begin. We are following this process to ensure all involved parties are in agreement before any party begins coding the proposed implementation. If you would like to see examples of how these are written, please refer to the current [ADRs](https://github.com/cosmos/cosmos-sdk/tree/master/docs/architecture). +When proposing an architecture decision for the Cosmos SDK, please start by opening an [issue](https://github.com/cosmos/cosmos-sdk/issues/new/choose) or a [discussion](https://github.com/cosmos/cosmos-sdk/discussions/new) with a summary of the proposal. Once the proposal has been discussed and there is rough alignment on a high-level approach to the design, the [ADR creation process](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/PROCESS.md) can begin. We are following this process to ensure all involved parties are in agreement before any party begins coding the proposed implementation. If you would like to see examples of how these are written, please refer to the current [ADRs](https://github.com/cosmos/cosmos-sdk/tree/master/docs/architecture). ## Pull Requests diff --git a/LICENSE b/LICENSE index 4e31b6cf9ffc..1931c12a2b33 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Cosmos-SDK +Cosmos SDK License: Apache2.0 Apache License diff --git a/docs/README.md b/docs/README.md index 5ddfacfbe6e2..9c5acc729eef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -64,7 +64,7 @@ aside: false - **[Module Directory](../x/)**: Cosmos SDK module implementations and their respective documentation. - **[Specifications](./spec/)**: Specifications of modules and other parts of the Cosmos SDK. -- **[SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK. +- **[Cosmos SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK. - **[REST and RPC Endpoints](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node. - **[Rosetta API](./run-node/rosetta.md)**: Rosetta API integration. diff --git a/docs/architecture/adr-002-docs-structure.md b/docs/architecture/adr-002-docs-structure.md index 1c8201890c22..dd104acd7714 100644 --- a/docs/architecture/adr-002-docs-structure.md +++ b/docs/architecture/adr-002-docs-structure.md @@ -2,7 +2,7 @@ ## Context -There is a need for a scalable structure of the SDK documentation. Current documentation includes a lot of non-related SDK material, is difficult to maintain and hard to follow as a user. +There is a need for a scalable structure of the Cosmos SDK documentation. Current documentation includes a lot of non-related Cosmos SDK material, is difficult to maintain and hard to follow as a user. Ideally, we would have: @@ -11,7 +11,7 @@ Ideally, we would have: ## Decision -Re-structure the `/docs` folder of the SDK github repo as follows: +Re-structure the `/docs` folder of the Cosmos SDK github repo as follows: ``` docs/ @@ -40,9 +40,9 @@ docs/ The files in each sub-folders do not matter and will likely change. What matters is the sectioning: - `README`: Landing page of the docs. -- `intro`: Introductory material. Goal is to have a short explainer of the SDK and then channel people to the resource they need. The [sdk-tutorial](https://github.com/cosmos/sdk-application-tutorial/) will be highlighted, as well as the `godocs`. -- `concepts`: Contains high-level explanations of the abstractions of the SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. -- `clients`: Contains specs and info about the various SDK clients. +- `intro`: Introductory material. Goal is to have a short explainer of the Cosmos SDK and then channel people to the resource they need. The [Cosmos SDK tutorial](https://github.com/cosmos/sdk-application-tutorial/) will be highlighted, as well as the `godocs`. +- `concepts`: Contains high-level explanations of the abstractions of the Cosmos SDK. It does not contain specific code implementation and does not need to be updated often. **It is not an API specification of the interfaces**. API spec is the `godoc`. +- `clients`: Contains specs and info about the various Cosmos SDK clients. - `spec`: Contains specs of modules, and others. - `modules`: Contains links to `godocs` and the spec of the modules. - `architecture`: Contains architecture-related docs like the present one. @@ -65,8 +65,8 @@ Accepted ### Positive -- Much clearer organisation of the SDK docs. -- The `/docs` folder now only contains SDK and gaia related material. Later, it will only contain SDK related material. +- Much clearer organisation of the Cosmos SDK docs. +- The `/docs` folder now only contains Cosmos SDK and gaia related material. Later, it will only contain Cosmos SDK related material. - Developers only have to update `/docs` folder when they open a PR (and not `/examples` for example). - Easier for developers to find what they need to update in the docs thanks to reworked architecture. - Cleaner vuepress build for website docs. diff --git a/docs/architecture/adr-003-dynamic-capability-store.md b/docs/architecture/adr-003-dynamic-capability-store.md index 3f5c9387c6ae..b392404e0eba 100644 --- a/docs/architecture/adr-003-dynamic-capability-store.md +++ b/docs/architecture/adr-003-dynamic-capability-store.md @@ -21,7 +21,7 @@ This ADR proposes such an interface & mechanism. ## Decision -The SDK will include a new `CapabilityKeeper` abstraction, which is responsible for provisioning, +The Cosmos SDK will include a new `CapabilityKeeper` abstraction, which is responsible for provisioning, tracking, and authenticating capabilities at runtime. During application initialisation in `app.go`, the `CapabilityKeeper` will be hooked up to modules through unique function references (by calling `ScopeToModule`, defined below) so that it can identify the calling module when later diff --git a/docs/architecture/adr-006-secret-store-replacement.md b/docs/architecture/adr-006-secret-store-replacement.md index 8be4077272f8..0b1d88d9e397 100644 --- a/docs/architecture/adr-006-secret-store-replacement.md +++ b/docs/architecture/adr-006-secret-store-replacement.md @@ -4,12 +4,12 @@ - July 29th, 2019: Initial draft - September 11th, 2019: Work has started -- November 4th: SDK changes merged in +- November 4th: Cosmos SDK changes merged in - November 18th: Gaia changes merged in ## Context -Currently, an SDK application's CLI directory stores key material and metadata in a plain text database in the user’s home directory. Key material is encrypted by a passphrase, protected by bcrypt hashing algorithm. Metadata (e.g. addresses, public keys, key storage details) is available in plain text. +Currently, a Cosmos SDK application's CLI directory stores key material and metadata in a plain text database in the user’s home directory. Key material is encrypted by a passphrase, protected by bcrypt hashing algorithm. Metadata (e.g. addresses, public keys, key storage details) is available in plain text. This is not desirable for a number of reasons. Perhaps the biggest reason is insufficient security protection of key material and metadata. Leaking the plain text allows an attacker to surveil what keys a given computer controls via a number of techniques, like compromised dependencies without any privilege execution. This could be followed by a more targeted attack on a particular user/computer. diff --git a/docs/architecture/adr-010-modular-antehandler.md b/docs/architecture/adr-010-modular-antehandler.md index 4fdd2ebdfc6b..d4ad05241867 100644 --- a/docs/architecture/adr-010-modular-antehandler.md +++ b/docs/architecture/adr-010-modular-antehandler.md @@ -44,7 +44,7 @@ type Decorator interface { } ``` -Each decorator works like a modularized SDK antehandler function, but it can take in a `next` argument that may be another decorator or a Handler (which does not take in a next argument). These decorators can be chained together, one decorator being passed in as the `next` argument of the previous decorator in the chain. The chain ends in a Router which can take a tx and route to the appropriate msg handler. +Each decorator works like a modularized Cosmos SDK antehandler function, but it can take in a `next` argument that may be another decorator or a Handler (which does not take in a next argument). These decorators can be chained together, one decorator being passed in as the `next` argument of the previous decorator in the chain. The chain ends in a Router which can take a tx and route to the appropriate msg handler. A key benefit of this approach is that one Decorator can wrap its internal logic around the next Checker/Deliverer. A weave Decorator may do the following: @@ -84,7 +84,7 @@ If however, users wish to change the order or add, modify, or delete ante micro- This is an example of a user's AnteHandler if they choose not to make any custom micro-functions. -##### SDK code +##### Cosmos SDK code ```go // Chains together a list of AnteHandler micro-functions that get run one after the other. @@ -186,13 +186,13 @@ Cons: ### Simple Decorators -This approach takes inspiration from Weave's decorator design while trying to minimize the number of breaking changes to the SDK and maximizing simplicity. Like Weave decorators, this approach allows one `AnteDecorator` to wrap the next AnteHandler to do pre- and post-processing on the result. This is useful since decorators can do defer/cleanups after an AnteHandler returns as well as perform some setup beforehand. Unlike Weave decorators, these `AnteDecorator` functions can only wrap over the AnteHandler rather than the entire handler execution path. This is deliberate as we want decorators from different modules to perform authentication/validation on a `tx`. However, we do not want decorators being capable of wrapping and modifying the results of a `MsgHandler`. +This approach takes inspiration from Weave's decorator design while trying to minimize the number of breaking changes to the Cosmos SDK and maximizing simplicity. Like Weave decorators, this approach allows one `AnteDecorator` to wrap the next AnteHandler to do pre- and post-processing on the result. This is useful since decorators can do defer/cleanups after an AnteHandler returns as well as perform some setup beforehand. Unlike Weave decorators, these `AnteDecorator` functions can only wrap over the AnteHandler rather than the entire handler execution path. This is deliberate as we want decorators from different modules to perform authentication/validation on a `tx`. However, we do not want decorators being capable of wrapping and modifying the results of a `MsgHandler`. -In addition, this approach will not break any core SDK API's. Since we preserve the notion of an AnteHandler and still set a single AnteHandler in baseapp, the decorator is simply an additional approach available for users that desire more customization. The API of modules (namely `x/auth`) may break with this approach, but the core API remains untouched. +In addition, this approach will not break any core Cosmos SDK API's. Since we preserve the notion of an AnteHandler and still set a single AnteHandler in baseapp, the decorator is simply an additional approach available for users that desire more customization. The API of modules (namely `x/auth`) may break with this approach, but the core API remains untouched. -Allow Decorator interface that can be chained together to create an SDK AnteHandler. +Allow Decorator interface that can be chained together to create a Cosmos SDK AnteHandler. -This allows users to choose between implementing an AnteHandler by themselves and setting it in the baseapp, or use the decorator pattern to chain their custom decorators with SDK provided decorators in the order they wish. +This allows users to choose between implementing an AnteHandler by themselves and setting it in the baseapp, or use the decorator pattern to chain their custom decorators with the Cosmos SDK provided decorators in the order they wish. ```go // An AnteDecorator wraps an AnteHandler, and can do pre- and post-processing on the next AnteHandler diff --git a/docs/architecture/adr-011-generalize-genesis-accounts.md b/docs/architecture/adr-011-generalize-genesis-accounts.md index db323966e1f0..60964f95b90c 100644 --- a/docs/architecture/adr-011-generalize-genesis-accounts.md +++ b/docs/architecture/adr-011-generalize-genesis-accounts.md @@ -6,7 +6,7 @@ ## Context -Currently, the SDK allows for custom account types; the `auth` keeper stores any type fulfilling its `Account` interface. However `auth` does not handle exporting or loading accounts to/from a genesis file, this is done by `genaccounts`, which only handles one of 4 concrete account types (`BaseAccount`, `ContinuousVestingAccount`, `DelayedVestingAccount` and `ModuleAccount`). +Currently, the Cosmos SDK allows for custom account types; the `auth` keeper stores any type fulfilling its `Account` interface. However `auth` does not handle exporting or loading accounts to/from a genesis file, this is done by `genaccounts`, which only handles one of 4 concrete account types (`BaseAccount`, `ContinuousVestingAccount`, `DelayedVestingAccount` and `ModuleAccount`). Projects desiring to use custom accounts (say custom vesting accounts) need to fork and modify `genaccounts`. diff --git a/docs/architecture/adr-012-state-accessors.md b/docs/architecture/adr-012-state-accessors.md index b66e23eb67b2..79deb6a9df8d 100644 --- a/docs/architecture/adr-012-state-accessors.md +++ b/docs/architecture/adr-012-state-accessors.md @@ -6,7 +6,7 @@ ## Context -SDK modules currently use the `KVStore` interface and `Codec` to access their respective state. While +Cosmos SDK modules currently use the `KVStore` interface and `Codec` to access their respective state. While this provides a large degree of freedom to module developers, it is hard to modularize and the UX is mediocre. diff --git a/docs/architecture/adr-016-validator-consensus-key-rotation.md b/docs/architecture/adr-016-validator-consensus-key-rotation.md index 9b5d77e7d750..6cc1e5ce7a20 100644 --- a/docs/architecture/adr-016-validator-consensus-key-rotation.md +++ b/docs/architecture/adr-016-validator-consensus-key-rotation.md @@ -7,11 +7,11 @@ ## Context -Validator consensus key rotation feature has been discussed and requested for a long time, for the sake of safer validator key management policy (e.g. https://github.com/tendermint/tendermint/issues/1136). So, we suggest one of the simplest form of validator consensus key rotation implementation mostly onto Cosmos-SDK. +Validator consensus key rotation feature has been discussed and requested for a long time, for the sake of safer validator key management policy (e.g. https://github.com/tendermint/tendermint/issues/1136). So, we suggest one of the simplest form of validator consensus key rotation implementation mostly onto Cosmos SDK. We don't need to make any update on consensus logic in Tendermint because Tendermint does not have any mapping information of consensus key and validator operator key, meaning that from Tendermint point of view, a consensus key rotation of a validator is simply a replacement of a consensus key to another. -Also, it should be noted that this ADR includes only the simplest form of consensus key rotation without considering multiple consensus keys concept. Such multiple consensus keys concept shall remain a long term goal of Tendermint and Cosmos-SDK. +Also, it should be noted that this ADR includes only the simplest form of consensus key rotation without considering multiple consensus keys concept. Such multiple consensus keys concept shall remain a long term goal of Tendermint and Cosmos SDK. ## Decision diff --git a/docs/architecture/adr-017-historical-header-module.md b/docs/architecture/adr-017-historical-header-module.md index f0cdf4c07d66..8c5a1f6cd65e 100644 --- a/docs/architecture/adr-017-historical-header-module.md +++ b/docs/architecture/adr-017-historical-header-module.md @@ -7,7 +7,7 @@ ## Context -In order for the Cosmos SDK to implement the [IBC specification](https://github.com/cosmos/ics), modules within the SDK must have the ability to introspect recent consensus states (validator sets & commitment roots) as proofs of these values on other chains must be checked during the handshakes. +In order for the Cosmos SDK to implement the [IBC specification](https://github.com/cosmos/ics), modules within the Cosmos SDK must have the ability to introspect recent consensus states (validator sets & commitment roots) as proofs of these values on other chains must be checked during the handshakes. ## Decision @@ -30,7 +30,7 @@ func BeginBlock(ctx sdk.Context, keeper HistoricalHeaderKeeper, req abci.Request Alternatively, the application MAY store only the hash of the validator set. -The application MUST make these past `n` committed headers available for querying by SDK modules through the `Keeper`'s `GetHistoricalInfo` function. This MAY be implemented in a new module, or it MAY also be integrated into an existing one (likely `x/staking` or `x/ibc`). +The application MUST make these past `n` committed headers available for querying by Cosmos SDK modules through the `Keeper`'s `GetHistoricalInfo` function. This MAY be implemented in a new module, or it MAY also be integrated into an existing one (likely `x/staking` or `x/ibc`). `n` MAY be configured as a parameter store parameter, in which case it could be changed by `ParameterChangeProposal`s, although it will take some blocks for the stored information to catch up if `n` is increased. @@ -44,7 +44,7 @@ Implementation of this ADR will require changes to the Cosmos SDK. It will not r ### Positive -- Easy retrieval of headers & state roots for recent past heights by modules anywhere in the SDK. +- Easy retrieval of headers & state roots for recent past heights by modules anywhere in the Cosmos SDK. - No RPC calls to Tendermint required. - No ABCI alterations required. diff --git a/docs/architecture/adr-019-protobuf-state-encoding.md b/docs/architecture/adr-019-protobuf-state-encoding.md index cddf7092fb98..657e5b386e12 100644 --- a/docs/architecture/adr-019-protobuf-state-encoding.md +++ b/docs/architecture/adr-019-protobuf-state-encoding.md @@ -65,13 +65,13 @@ will provide two concrete implementations of the `Marshaler` interface: `AminoCo - `AminoCodec`: Uses Amino for both binary and JSON encoding. - `ProtoCodec`: Uses Protobuf for both binary and JSON encoding. -Modules will use whichever codec that is instantiated in the app. By default, the SDK's `simapp` +Modules will use whichever codec that is instantiated in the app. By default, the Cosmos SDK's `simapp` instantiates a `ProtoCodec` as the concrete implementation of `Marshaler`, inside the `MakeTestEncodingConfig` function. This can be easily overwritten by app developers if they so desire. The ultimate goal will be to replace Amino JSON encoding with Protobuf encoding and thus have modules accept and/or extend `ProtoCodec`. Until then, Amino JSON is still provided for legacy use-cases. -A handful of places in the SDK still have Amino JSON hardcoded, such as the Legacy API REST endpoints +A handful of places in the Cosmos SDK still have Amino JSON hardcoded, such as the Legacy API REST endpoints and the `x/params` store. They are planned to be converted to Protobuf in a gradual manner. ### Module Codecs @@ -139,7 +139,7 @@ compression at the persistence layer in the future and the performance impact is likely to be small. Thus, not using `Any` is seem as a pre-mature optimization, with user experience as the higher order concern. -Note, that given the SDK's decision to adopt the `Codec` interfaces described +Note, that given the Cosmos SDK's decision to adopt the `Codec` interfaces described above, apps can still choose to use `oneof` to encode state and transactions but it is not the recommended approach. If apps do choose to use `oneof`s instead of `Any` they will likely lose compatibility with client apps that @@ -226,7 +226,7 @@ every module that implements it in order to populate the `InterfaceRegistry`. ### Using `Any` to encode state -The SDK will provide support methods `MarshalInterface` and `UnmarshalInterface` to hide a complexity of wrapping interface types into `Any` and allow easy serialization. +The Cosmos SDK will provide support methods `MarshalInterface` and `UnmarshalInterface` to hide a complexity of wrapping interface types into `Any` and allow easy serialization. ```go import "github.com/cosmos/cosmos-sdk/codec" diff --git a/docs/architecture/adr-020-protobuf-transaction-encoding.md b/docs/architecture/adr-020-protobuf-transaction-encoding.md index 2efe583cf590..e50fe6704fa9 100644 --- a/docs/architecture/adr-020-protobuf-transaction-encoding.md +++ b/docs/architecture/adr-020-protobuf-transaction-encoding.md @@ -12,7 +12,7 @@ - 2020 August 19: Move sequence field from `SignDoc` to `SignerInfo`, as discussed in [#6966](https://github.com/cosmos/cosmos-sdk/issues/6966). - 2020 September 25: Remove `PublicKey` type in favor of `secp256k1.PubKey`, `ed25519.PubKey` and `multisig.LegacyAminoPubKey`. - 2020 October 15: Add `GetAccount` and `GetAccountWithHeight` methods to the `AccountRetriever` interface. -- 2021 Feb 24: The SDK does not use Tendermint's `PubKey` interface anymore, but its own `cryptotypes.PubKey`. Updates to reflect this. +- 2021 Feb 24: The Cosmos SDK does not use Tendermint's `PubKey` interface anymore, but its own `cryptotypes.PubKey`. Updates to reflect this. - 2021 May 3: Rename `clientCtx.JSONMarshaler` to `clientCtx.JSONCodec`. - 2021 June 10: Add `clientCtx.Codec: codec.Codec`. diff --git a/docs/architecture/adr-021-protobuf-query-encoding.md b/docs/architecture/adr-021-protobuf-query-encoding.md index 60830de3ce16..443b506101f1 100644 --- a/docs/architecture/adr-021-protobuf-query-encoding.md +++ b/docs/architecture/adr-021-protobuf-query-encoding.md @@ -87,7 +87,7 @@ The custom queries for our module are implemented by implementing this interface The first parameter in this generated interface is a generic `context.Context`, whereas querier methods generally need an instance of `sdk.Context` to read from the store. Since arbitrary values can be attached to `context.Context` -using the `WithValue` and `Value` methods, the SDK should provide a function +using the `WithValue` and `Value` methods, the Cosmos SDK should provide a function `sdk.UnwrapSDKContext` to retrieve the `sdk.Context` from the provided `context.Context`. @@ -186,7 +186,7 @@ approach, there will be no need to generate separate REST query handlers, just query servers as described above as grpc-gateway handles the translation of protobuf to REST as well as Swagger definitions. -The SDK should provide CLI commands for apps to start GRPC gateway either in +The Cosmos SDK should provide CLI commands for apps to start GRPC gateway either in a separate process or the same process as the ABCI app, as well as provide a command for generating grpc-gateway proxy `.proto` files and the `swagger.json` file. diff --git a/docs/architecture/adr-022-custom-panic-handling.md b/docs/architecture/adr-022-custom-panic-handling.md index 22dad4447df4..eea066bcd1e5 100644 --- a/docs/architecture/adr-022-custom-panic-handling.md +++ b/docs/architecture/adr-022-custom-panic-handling.md @@ -13,7 +13,7 @@ SUPERSEDED by ADR-045 The current implementation of BaseApp does not allow developers to write custom error handlers during panic recovery [runTx()](https://github.com/cosmos/cosmos-sdk/blob/bad4ca75f58b182f600396ca350ad844c18fc80b/baseapp/baseapp.go#L539) -method. We think that this method can be more flexible and can give SDK users more options for customizations without +method. We think that this method can be more flexible and can give Cosmos SDK users more options for customizations without the need to rewrite whole BaseApp. Also there's one special case for `sdk.ErrorOutOfGas` error handling, that case might be handled in a "standard" way (middleware) alongside the others. diff --git a/docs/architecture/adr-023-protobuf-naming.md b/docs/architecture/adr-023-protobuf-naming.md index 6e9ead13c829..f4425243e158 100644 --- a/docs/architecture/adr-023-protobuf-naming.md +++ b/docs/architecture/adr-023-protobuf-naming.md @@ -51,7 +51,7 @@ The goal of this ADR is to provide thoughtful naming conventions that: names too short and cryptic) or under-optimizing (just accepting bloated names with lots of redundant information) -These guidelines are meant to act as a style guide for both the SDK and +These guidelines are meant to act as a style guide for both the Cosmos SDK and third-party modules. As a starting point, we should adopt all of the [DEFAULT](https://buf.build/docs/lint-checkers#default) @@ -251,7 +251,7 @@ community-based governance. the path) * code generation will be easier for clients because .proto files will be in a single `proto/` directory which can be copied rather than scattered -throughout the SDK +throughout the Cosmos SDK ### Negative diff --git a/docs/architecture/adr-027-deterministic-protobuf-serialization.md b/docs/architecture/adr-027-deterministic-protobuf-serialization.md index ab303e8d007a..41c8d2fc10f6 100644 --- a/docs/architecture/adr-027-deterministic-protobuf-serialization.md +++ b/docs/architecture/adr-027-deterministic-protobuf-serialization.md @@ -274,7 +274,7 @@ for all protobuf documents we need in the context of Cosmos SDK signing. ### Neutral -### Usage in SDK +### Usage in Cosmos SDK For the reasons mentioned above ("Negative" section) we prefer to keep workarounds for shared data structure. Example: the aforementioned `TxRaw` is using raw bytes diff --git a/docs/architecture/adr-028-public-key-addresses.md b/docs/architecture/adr-028-public-key-addresses.md index d86a0426f83e..51ccc4390d75 100644 --- a/docs/architecture/adr-028-public-key-addresses.md +++ b/docs/architecture/adr-028-public-key-addresses.md @@ -11,7 +11,7 @@ Proposed ## Abstract -This ADR defines an address format for all addressable SDK accounts. That includes: new public key algorithms, multisig public keys, and module accounts. +This ADR defines an address format for all addressable Cosmos SDK accounts. That includes: new public key algorithms, multisig public keys, and module accounts. ## Context @@ -79,7 +79,7 @@ We define the following account types, for which we define the address function: ### Legacy Public Key Addresses Don't Change -Currently (Jan 2021), the only officially supported SDK user accounts are `secp256k1` basic accounts and legacy amino multisig. +Currently (Jan 2021), the only officially supported Cosmos SDK user accounts are `secp256k1` basic accounts and legacy amino multisig. They are used in existing Cosmos SDK zones. They use the following address formats: - secp256k1: `ripemd160(sha256(pk_bytes))[:20]` @@ -186,7 +186,7 @@ address.Hash("module", moduleName) ``` We use `"module"` as a schema type for all module derived addresses. Module accounts can have sub accounts. The derivation process has a defined order: module name, submodule key, subsubmodule key. -Module account addresses are heavily used in the SDK so it makes sense to optimize the derivation process: instead of using of using `LengthPrefix` for the module name, we use a null byte (`'\x00'`) as a separator. This works, because null byte is not a part of a valid module name. +Module account addresses are heavily used in the Cosmos SDK so it makes sense to optimize the derivation process: instead of using of using `LengthPrefix` for the module name, we use a null byte (`'\x00'`) as a separator. This works, because null byte is not a part of a valid module name. ```go func Module(moduleName string, key []byte) []byte{ @@ -227,7 +227,7 @@ smartContractAddr := Derived(Module("cosmwasm", smartContractsNamespace), []{sma ### Schema Types A `typ` parameter used in `Hash` function SHOULD be unique for each account type. -Since all SDK account types are serialized in the state, we propose to use the protobuf message name string. +Since all Cosmos SDK account types are serialized in the state, we propose to use the protobuf message name string. Example: all public key types have a unique protobuf message type similar to: @@ -248,7 +248,7 @@ in other places such as the type URL in `Any`s. We can easily obtain the name us ### Backwards Compatibility -This ADR is compatible with what was committed and directly supported in the SDK repository. +This ADR is compatible with what was committed and directly supported in the Cosmos SDK repository. ### Positive diff --git a/docs/architecture/adr-030-authz-module.md b/docs/architecture/adr-030-authz-module.md index eccbabf16bbf..ff6286c2d888 100644 --- a/docs/architecture/adr-030-authz-module.md +++ b/docs/architecture/adr-030-authz-module.md @@ -5,7 +5,7 @@ - 2019-11-06: Initial Draft - 2020-10-12: Updated Draft - 2020-11-13: Accepted -- 2020-05-06: proto API updates, use `sdk.Msg` instead of `sdk.ServiceMsg` (the latter concept was removed from SDK) +- 2020-05-06: proto API updates, use `sdk.Msg` instead of `sdk.ServiceMsg` (the latter concept was removed from Cosmos SDK) ## Status diff --git a/docs/architecture/adr-031-msg-service.md b/docs/architecture/adr-031-msg-service.md index e11813c735be..ff92c617bb5a 100644 --- a/docs/architecture/adr-031-msg-service.md +++ b/docs/architecture/adr-031-msg-service.md @@ -38,7 +38,7 @@ This was never adopted, however. Having a well-specified return value for `Msg`s would improve client UX. For instance, in `x/gov`, `MsgSubmitProposal` returns the proposal ID as a big-endian `uint64`. This isn’t really documented anywhere and clients would need to know the internals -of the SDK to parse that value and return it to users. +of the Cosmos SDK to parse that value and return it to users. Also, there may be cases where we want to use these return values programatically. For instance, https://github.com/cosmos/cosmos-sdk/issues/7093 proposes a method for diff --git a/docs/architecture/adr-032-typed-events.md b/docs/architecture/adr-032-typed-events.md index a85126b728b0..0d96054f51c6 100644 --- a/docs/architecture/adr-032-typed-events.md +++ b/docs/architecture/adr-032-typed-events.md @@ -16,17 +16,17 @@ Proposed ## Abstract -Currently in the SDK, events are defined in the handlers for each message as well as `BeginBlock` and `EndBlock`. Each module doesn't have types defined for each event, they are implemented as `map[string]string`. Above all else this makes these events difficult to consume as it requires a great deal of raw string matching and parsing. This proposal focuses on updating the events to use **typed events** defined in each module such that emiting and subscribing to events will be much easier. This workflow comes from the experience of the Akash Network team. +Currently in the Cosmos SDK, events are defined in the handlers for each message as well as `BeginBlock` and `EndBlock`. Each module doesn't have types defined for each event, they are implemented as `map[string]string`. Above all else this makes these events difficult to consume as it requires a great deal of raw string matching and parsing. This proposal focuses on updating the events to use **typed events** defined in each module such that emiting and subscribing to events will be much easier. This workflow comes from the experience of the Akash Network team. ## Context -Currently in the SDK, events are defined in the handlers for each message, meaning each module doesn't have a cannonical set of types for each event. Above all else this makes these events difficult to consume as it requires a great deal of raw string matching and parsing. This proposal focuses on updating the events to use **typed events** defined in each module such that emiting and subscribing to events will be much easier. This workflow comes from the experience of the Akash Network team. +Currently in the Cosmos SDK, events are defined in the handlers for each message, meaning each module doesn't have a cannonical set of types for each event. Above all else this makes these events difficult to consume as it requires a great deal of raw string matching and parsing. This proposal focuses on updating the events to use **typed events** defined in each module such that emiting and subscribing to events will be much easier. This workflow comes from the experience of the Akash Network team. -[Our platform](http://github.com/ovrclk/akash) requires a number of programatic on chain interactions both on the provider (datacenter - to bid on new orders and listen for leases created) and user (application developer - to send the app manifest to the provider) side. In addition the Akash team is now maintaining the IBC [`relayer`](https://github.com/ovrclk/relayer), another very event driven process. In working on these core pieces of infrastructure, and integrating lessons learned from Kubernetes developement, our team has developed a standard method for defining and consuming typed events in SDK modules. We have found that it is extremely useful in building this type of event driven application. +[Our platform](http://github.com/ovrclk/akash) requires a number of programatic on chain interactions both on the provider (datacenter - to bid on new orders and listen for leases created) and user (application developer - to send the app manifest to the provider) side. In addition the Akash team is now maintaining the IBC [`relayer`](https://github.com/ovrclk/relayer), another very event driven process. In working on these core pieces of infrastructure, and integrating lessons learned from Kubernetes developement, our team has developed a standard method for defining and consuming typed events in Cosmos SDK modules. We have found that it is extremely useful in building this type of event driven application. -As the SDK gets used more extensively for apps like `peggy`, other peg zones, IBC, DeFi, etc... there will be an exploding demand for event driven applications to support new features desired by users. We propose upstreaming our findings into the SDK to enable all SDK applications to quickly and easily build event driven apps to aid their core application. Wallets, exchanges, explorers, and defi protocols all stand to benefit from this work. +As the Cosmos SDK gets used more extensively for apps like `peggy`, other peg zones, IBC, DeFi, etc... there will be an exploding demand for event driven applications to support new features desired by users. We propose upstreaming our findings into the Cosmos SDK to enable all Cosmos SDK applications to quickly and easily build event driven apps to aid their core application. Wallets, exchanges, explorers, and defi protocols all stand to benefit from this work. -If this proposal is accepted, users will be able to build event driven SDK apps in go by just writing `EventHandler`s for their specific event types and passing them to `EventEmitters` that are defined in the SDK. +If this proposal is accepted, users will be able to build event driven Cosmos SDK apps in go by just writing `EventHandler`s for their specific event types and passing them to `EventEmitters` that are defined in the Cosmos SDK. The end of this proposal contains a detailed example of how to consume events after this refactor. @@ -159,7 +159,7 @@ Please see the below code sample for more detail on this flow looks for clients. ### Positive -* Improves consistency of implementation for the events currently in the sdk +* Improves consistency of implementation for the events currently in the Cosmos SDK * Provides a much more ergonomic way to handle events and facilitates writing event driven applications * This implementation will support a middleware ecosystem of `EventHandler`s @@ -206,7 +206,7 @@ func SubmitProposalEventHandler(ev proto.Message) (err error) { } // TxEmitter is an example of an event emitter that emits just transaction events. This can and -// should be implemented somewhere in the SDK. The SDK can include an EventEmitters for tm.event='Tx' +// should be implemented somewhere in the Cosmos SDK. The Cosmos SDK can include an EventEmitters for tm.event='Tx' // and/or tm.event='NewBlock' (the new block events may contain typed events) func TxEmitter(ctx context.Context, cliCtx client.Context, ehs ...EventHandler) (err error) { // Instantiate and start tendermint RPC client diff --git a/docs/architecture/adr-033-protobuf-inter-module-comm.md b/docs/architecture/adr-033-protobuf-inter-module-comm.md index 6234c3d10b34..9d8d752692ce 100644 --- a/docs/architecture/adr-033-protobuf-inter-module-comm.md +++ b/docs/architecture/adr-033-protobuf-inter-module-comm.md @@ -22,7 +22,7 @@ service definitions defined in [ADR 021](./adr-021-protobuf-query-encoding.md) a In the current Cosmos SDK documentation on the [Object-Capability Model](../core/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. +> 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. There is currently not a thriving ecosystem of Cosmos SDK modules. We hypothesize that this is in part due to: @@ -352,9 +352,9 @@ Other future improvements may include: ### MsgServices vs `x/capability` The `x/capability` module does provide a proper object-capability implementation that can be used by any module in the -SDK and could even be used for inter-module OCAPs as described in [\#5931](https://github.com/cosmos/cosmos-sdk/issues/5931). +Cosmos SDK and could even be used for inter-module OCAPs as described in [\#5931](https://github.com/cosmos/cosmos-sdk/issues/5931). -The advantages of the approach described in this ADR are mostly around how it integrates with other parts of the SDK, +The advantages of the approach described in this ADR are mostly around how it integrates with other parts of the Cosmos SDK, specifically: * protobuf so that: diff --git a/docs/architecture/adr-035-rosetta-api-support.md b/docs/architecture/adr-035-rosetta-api-support.md index fe85405a5ed0..7a10a59b0d42 100644 --- a/docs/architecture/adr-035-rosetta-api-support.md +++ b/docs/architecture/adr-035-rosetta-api-support.md @@ -9,7 +9,7 @@ ## Changelog -- 2021-05-12: the external library [cosmos-rosetta-gateway](https://github.com/tendermint/cosmos-rosetta-gateway) has been moved within the SDK. +- 2021-05-12: the external library [cosmos-rosetta-gateway](https://github.com/tendermint/cosmos-rosetta-gateway) has been moved within the Cosmos SDK. ## Context @@ -164,8 +164,8 @@ type OfflineClient interface { ### 2. Cosmos SDK Implementation -The cosmos sdk implementation, based on version, takes care of satisfying the `Client` interface. -In Stargate, Launchpad and 0.37, we have introduced the concept of rosetta.Msg, this message is not in the shared repository as the sdk.Msg type differs between cosmos-sdk versions. +The Cosmos SDK implementation, based on version, takes care of satisfying the `Client` interface. +In Stargate, Launchpad and 0.37, we have introduced the concept of rosetta.Msg, this message is not in the shared repository as the sdk.Msg type differs between Cosmos SDK versions. The rosetta.Msg interface follows: @@ -193,7 +193,7 @@ Rosetta API service could run within the same execution process as the applicati #### Separate API service -Client application developers can write a new command to launch a Rosetta API server as a separate process too, using the rosetta command contained in the `/server/rosetta` package. Construction of the command depends on cosmos sdk version. Examples can be found inside `simd` for stargate, and `contrib/rosetta/simapp` for other release series. +Client application developers can write a new command to launch a Rosetta API server as a separate process too, using the rosetta command contained in the `/server/rosetta` package. Construction of the command depends on Cosmos SDK version. Examples can be found inside `simd` for stargate, and `contrib/rosetta/simapp` for other release series. ## Status diff --git a/docs/architecture/adr-036-arbitrary-signature.md b/docs/architecture/adr-036-arbitrary-signature.md index 0d0737bfff71..c175d25ec42f 100644 --- a/docs/architecture/adr-036-arbitrary-signature.md +++ b/docs/architecture/adr-036-arbitrary-signature.md @@ -17,7 +17,7 @@ Draft ## Abstract -Currently, in the SDK, there is no convention to sign arbitrary message like on Ethereum. We propose with this specification, for Cosmos SDK ecosystem, a way to sign and validate off-chain arbitrary messages. +Currently, in the Cosmos SDK, there is no convention to sign arbitrary message like on Ethereum. We propose with this specification, for Cosmos SDK ecosystem, a way to sign and validate off-chain arbitrary messages. This specification serves the purpose of covering every use case, this means that cosmos-sdk applications developers decide how to serialize and represent `Data` to users. diff --git a/docs/architecture/adr-040-storage-and-smt-state-commitments.md b/docs/architecture/adr-040-storage-and-smt-state-commitments.md index 0daf873485c6..4ee109b6c4df 100644 --- a/docs/architecture/adr-040-storage-and-smt-state-commitments.md +++ b/docs/architecture/adr-040-storage-and-smt-state-commitments.md @@ -10,7 +10,7 @@ DRAFT Not Implemented ## Abstract -Sparse Merkle Tree ([SMT](https://osf.io/8mcnh/)) is a version of a Merkle Tree with various storage and performance optimizations. This ADR defines a separation of state commitments from data storage and the SDK transition from IAVL to SMT. +Sparse Merkle Tree ([SMT](https://osf.io/8mcnh/)) is a version of a Merkle Tree with various storage and performance optimizations. This ADR defines a separation of state commitments from data storage and the Cosmos SDK transition from IAVL to SMT. ## Context @@ -19,11 +19,11 @@ Currently, Cosmos SDK uses IAVL for both state [commitments](https://cryptograph IAVL has effectively become an orphaned project within the Cosmos ecosystem and it's proven to be an inefficient state commitment data structure. In the current design, IAVL is used for both data storage and as a Merkle Tree for state commitments. IAVL is meant to be a standalone Merkelized key/value database, however it's using a KV DB engine to store all tree nodes. So, each node is stored in a separate record in the KV DB. This causes many inefficiencies and problems: -+ Each object query requires a tree traversal from the root. Subsequent queries for the same object are cached on the SDK level. ++ Each object query requires a tree traversal from the root. Subsequent queries for the same object are cached on the Cosmos SDK level. + Each edge traversal requires a DB query. + Creating snapshots is [expensive](https://github.com/cosmos/cosmos-sdk/issues/7215#issuecomment-684804950). It takes about 30 seconds to export less than 100 MB of state (as of March 2020). + Updates in IAVL may trigger tree reorganization and possible O(log(n)) hashes re-computation, which can become a CPU bottleneck. -+ The node structure is pretty expensive - it contains a standard tree node elements (key, value, left and right element) and additional metadata such as height, version (which is not required by the SDK). The entire node is hashed, and that hash is used as the key in the underlying database, [ref](https://github.com/cosmos/iavl/blob/master/docs/node/node.md ++ The node structure is pretty expensive - it contains a standard tree node elements (key, value, left and right element) and additional metadata such as height, version (which is not required by the Cosmos SDK). The entire node is hashed, and that hash is used as the key in the underlying database, [ref](https://github.com/cosmos/iavl/blob/master/docs/node/node.md ). Moreover, the IAVL project lacks support and a maintainer and we already see better and well-established alternatives. Instead of optimizing the IAVL, we are looking into other solutions for both storage and state commitments. @@ -44,7 +44,7 @@ SMT is a merkle tree structure: we don't store keys directly. For every `(key, v For data access we propose 2 additional KV buckets (implemented as namespaces for the key-value pairs, sometimes called [column family](https://github.com/facebook/rocksdb/wiki/Terminology)): -1. B1: `key → value`: the principal object storage, used by a state machine, behind the SDK `KVStore` interface: provides direct access by key and allows prefix iteration (KV DB backend must support it). +1. B1: `key → value`: the principal object storage, used by a state machine, behind the Cosmos SDK `KVStore` interface: provides direct access by key and allows prefix iteration (KV DB backend must support it). 2. B2: `hash(key) → key`: a reverse index to get a key from an SMT path. Internally the SMT will store `(key, value)` as `prefix || hash(key) || hash(value)`. So, we can get an object value by composing `hash(key) → B2 → B1`. 3. We could use more buckets to optimize the app usage if needed. @@ -85,11 +85,11 @@ Below, with simple _snapshot_ we refer to a database snapshot mechanism, not to Database snapshot is a view of DB state at a certain time or transaction. It's not a full copy of a database (it would be too big), usually a snapshot mechanism is based on a _copy on write_ and it allows to efficiently deliver DB state at a certain stage. Some DB engines support snapshotting. Hence, we propose to reuse that functionality for the state sync and versioning (described below). It will the supported DB engines to ones which efficiently implement snapshots. In a final section we will discuss evaluated DBs. -One of the Stargate core features is a _snapshot sync_ delivered in the `/snapshot` package. It provides a way to trustlessly sync a blockchain without repeating all transactions from the genesis. This feature is implemented in SDK and requires storage support. Currently IAVL is the only supported backend. It works by streaming to a client a snapshot of a `SS` at a certain version together with a header chain. +One of the Stargate core features is a _snapshot sync_ delivered in the `/snapshot` package. It provides a way to trustlessly sync a blockchain without repeating all transactions from the genesis. This feature is implemented in Cosmos SDK and requires storage support. Currently IAVL is the only supported backend. It works by streaming to a client a snapshot of a `SS` at a certain version together with a header chain. A new `SS` snapshot will be created in every `EndBlocker` and identified by a block height. The `rootmulti.Store` keeps track of the available snapshots to offer `SS` at a certain version. The `rootmulti.Store` implements the `CommitMultiStore` interface, which encapsulates a `Committer` interface. `Committer` has a `Commit`, `SetPruning`, `GetPruning` functions which will be used for creating and removing snapshots. The `rootStore.Commit` function creates a new snapshot and increments the version on each call, and checks if it needs to remove old versions. We will need to update the SMT interface to implement the `Committer` interface. NOTE: `Commit` must be called exactly once per block. Otherwise we risk going out of sync for the version number and block height. -NOTE: For the SDK storage, we may consider splitting that interface into `Committer` and `PruningCommitter` - only the multiroot should implement `PruningCommitter` (cache and prefix store don't need pruning). +NOTE: For the Cosmos SDK storage, we may consider splitting that interface into `Committer` and `PruningCommitter` - only the multiroot should implement `PruningCommitter` (cache and prefix store don't need pruning). Number of historical versions for `abci.Query` and state sync snapshots is part of a node configuration, not a chain configuration (configuration implied by the blockchain consensus). A configuration should allow to specify number of past blocks and number of past blocks modulo some number (eg: 100 past blocks and one snapshot every 100 blocks for past 2000 blocks). Archival nodes can keep all past versions. @@ -102,7 +102,7 @@ To manage the active snapshots we will either us a DB _max number of snapshots_ One of the functional requirements is to access old state. This is done through `abci.Query` structure. The version is specified by a block height (so we query for an object by a key `K` at block height `H`). The number of old versions supported for `abci.Query` is configurable. Accessing an old state is done by using available snapshots. `abci.Query` doesn't need old state of `SC`. So, for efficiency, we should keep `SC` and `SS` in different databases (however using the same DB engine). -Moreover, SDK could provide a way to directly access the state. However, a state machine shouldn't do that - since the number of snapshots is configurable, it would lead to nondeterministic execution. +Moreover, Cosmos SDK could provide a way to directly access the state. However, a state machine shouldn't do that - since the number of snapshots is configurable, it would lead to nondeterministic execution. We positively [validated](https://github.com/cosmos/cosmos-sdk/discussions/8297) a versioning and snapshot mechanism for querying old state with regards to the database we evaluated. @@ -122,7 +122,7 @@ We identified use-cases, where modules will need to save an object commitment wi ### Backwards Compatibility -This ADR doesn't introduce any SDK level API changes. +This ADR doesn't introduce any Cosmos SDK level API changes. We change the storage layout of the state machine, a storage hard fork and network upgrade is required to incorporate these changes. SMT provides a merkle proof functionality, however it is not compatible with ICS23. Updating the proofs for ICS23 compatibility is required. @@ -155,7 +155,7 @@ We verified existing databases KV databases for evaluating snapshot support. The ### RDBMS -Use of RDBMS instead of simple KV store for state. Use of RDBMS will require an SDK API breaking change (`KVStore` interface), will allow better data extraction and indexing solutions. Instead of saving an object as a single blob of bytes, we could save it as record in a table in the state storage layer, and as a `hash(key, protobuf(object))` in the SMT as outlined above. To verify that an object registered in RDBMS is same as the one committed to SMT, one will need to load it from RDBMS, marshal using protobuf, hash and do SMT search. +Use of RDBMS instead of simple KV store for state. Use of RDBMS will require a Cosmos SDK API breaking change (`KVStore` interface) and will allow better data extraction and indexing solutions. Instead of saving an object as a single blob of bytes, we could save it as record in a table in the state storage layer, and as a `hash(key, protobuf(object))` in the SMT as outlined above. To verify that an object registered in RDBMS is same as the one committed to SMT, one will need to load it from RDBMS, marshal using protobuf, hash and do SMT search. ### Off Chain Store diff --git a/docs/architecture/adr-041-in-place-store-migrations.md b/docs/architecture/adr-041-in-place-store-migrations.md index 6e0fce90c504..3eb8a078ccac 100644 --- a/docs/architecture/adr-041-in-place-store-migrations.md +++ b/docs/architecture/adr-041-in-place-store-migrations.md @@ -36,7 +36,7 @@ type AppModule interface { } ``` -This methods returns an `uint64` which serves as state-breaking version of the module. It MUST be incremented on each consensus-breaking change introduced by the module. To avoid potential errors with default values, the initial version of a module MUST be set to 1. In the SDK, version 1 corresponds to the modules in the v0.41 series. +This methods returns an `uint64` which serves as state-breaking version of the module. It MUST be incremented on each consensus-breaking change introduced by the module. To avoid potential errors with default values, the initial version of a module MUST be set to 1. In the Cosmos SDK, version 1 corresponds to the modules in the v0.41 series. ### Module-Specific Migration Functions @@ -57,7 +57,7 @@ func (am AppModule) RegisterServices(cfg module.Configurator) { For example, if the new ConsensusVersion of a module is `N` , then `N-1` migration functions MUST be registered in the configurator. -In the SDK, the migration functions are handled by each module's keeper, because the keeper holds the `sdk.StoreKey` used to perform in-place store migrations. To not overload the keeper, a `Migrator` wrapper is used by each module to handle the migration functions: +In the Cosmos SDK, the migration functions are handled by each module's keeper, because the keeper holds the `sdk.StoreKey` used to perform in-place store migrations. To not overload the keeper, a `Migrator` wrapper is used by each module to handle the migration functions: ```go // Migrator is a struct for handling in-place store migrations. @@ -155,8 +155,8 @@ While modules MUST register their migration functions when bumping ConsensusVers ### Neutral -- The SDK will continue to support JSON migrations via the existing `simd export` and `simd migrate` commands. -- The current ADR does not allow creating, renaming or deleting stores, only modifying existing store keys and values. The SDK already has the `StoreLoader` for those operations. +- The Cosmos SDK will continue to support JSON migrations via the existing `simd export` and `simd migrate` commands. +- The current ADR does not allow creating, renaming or deleting stores, only modifying existing store keys and values. The Cosmos SDK already has the `StoreLoader` for those operations. ## Further Discussions diff --git a/docs/architecture/adr-042-group-module.md b/docs/architecture/adr-042-group-module.md index 7d863f958f32..2907c7305aa8 100644 --- a/docs/architecture/adr-042-group-module.md +++ b/docs/architecture/adr-042-group-module.md @@ -276,4 +276,4 @@ Inter-module communication introduced by [ADR-033](adr-033-protobuf-inter-module - Initial specification: - https://gist.github.com/aaronc/b60628017352df5983791cad30babe56#group-module - [#5236](https://github.com/cosmos/cosmos-sdk/pull/5236) -- Proposal to add `x/group` into the SDK: [#7633](https://github.com/cosmos/cosmos-sdk/issues/7633) +- Proposal to add `x/group` into the Cosmos SDK: [#7633](https://github.com/cosmos/cosmos-sdk/issues/7633) diff --git a/docs/architecture/adr-044-protobuf-updates-guidelines.md b/docs/architecture/adr-044-protobuf-updates-guidelines.md index bc92feb88b9f..68265f83076d 100644 --- a/docs/architecture/adr-044-protobuf-updates-guidelines.md +++ b/docs/architecture/adr-044-protobuf-updates-guidelines.md @@ -14,9 +14,9 @@ This ADR provides guidelines and recommended practices when updating Protobuf de ## Context -The SDK maintains a set of [Protobuf definitions](https://github.com/cosmos/cosmos-sdk/tree/master/proto/cosmos). It is important to correctly design Protobuf definitions to avoid any breaking changes within the same version. The reasons are to not break tooling (including indexers and explorers), wallets and other third-party integrations. +The Cosmos SDK maintains a set of [Protobuf definitions](https://github.com/cosmos/cosmos-sdk/tree/master/proto/cosmos). It is important to correctly design Protobuf definitions to avoid any breaking changes within the same version. The reasons are to not break tooling (including indexers and explorers), wallets and other third-party integrations. -When making changes to these Protobuf definitions, the SDK currently only follows [Buf's](https://docs.buf.build/) recommendations. We noticed however that Buf's recommendations might still result in breaking changes in the SDK in some cases. For example: +When making changes to these Protobuf definitions, the Cosmos SDK currently only follows [Buf's](https://docs.buf.build/) recommendations. We noticed however that Buf's recommendations might still result in breaking changes in the SDK in some cases. For example: - Adding fields to `Msg`s. Adding fields is a not a Protobuf spec-breaking operation. However, when adding new fields to `Msg`s, the unknown field rejection will throw an error when sending the new `Msg` to an older node. - Marking fields as `reserved`. Protobuf proposes the `reserved` keyword for removing fields without the need to bump the package version. However, by doing so, client backwards compatibility is broken as Protobuf doesn't generate anything for `reserved` fields. See [#9446](https://github.com/cosmos/cosmos-sdk/issues/9446) for more details on this issue. @@ -27,19 +27,19 @@ Moreover, module developers often face other questions around Protobuf definitio We decide to keep [Buf's](https://docs.buf.build/) recommendations with the following exceptions: -- `UNARY_RPC`: the SDK currently does not support streaming RPCs. -- `COMMENT_FIELD`: the SDK allows fields with no comments. +- `UNARY_RPC`: the Cosmos SDK currently does not support streaming RPCs. +- `COMMENT_FIELD`: the Cosmos SDK allows fields with no comments. - `SERVICE_SUFFIX`: we use the `Query` and `Msg` service naming convention, which doesn't use the `-Service` suffix. - `PACKAGE_VERSION_SUFFIX`: some packages, such as `cosmos.crypto.ed25519`, don't use a version suffix. - `RPC_REQUEST_STANDARD_NAME`: Requests for the `Msg` service don't have the `-Request` suffix to keep backwards compatibility. -On top of Buf's recommendations we add the following guidelines that are specific to the SDK. +On top of Buf's recommendations we add the following guidelines that are specific to the Cosmos SDK. ### Updating Protobuf Definition Without Bumping Version #### 1. `Msg`s MUST NOT have new fields. -When processing `Msg`s, the SDK's antehandlers are strict and don't allow unknown fields in `Msg`s. This is checked by the unknown field rejection in the [`codec/unknownproto` package](https://github.com/cosmos/cosmos-sdk/blob/master/codec/unknownproto). +When processing `Msg`s, the Cosmos SDK's antehandlers are strict and don't allow unknown fields in `Msg`s. This is checked by the unknown field rejection in the [`codec/unknownproto` package](https://github.com/cosmos/cosmos-sdk/blob/master/codec/unknownproto). Now imagine a v0.43 node accepting a `MsgExample` transaction, and in v0.44 the chain developer decides to add a field to `MsgExample`. A client developer, which only manipulates Protobuf definitions, would see that `MsgExample` has a new field, and will populate it. However, sending the new `MsgExample` to an old v0.43 node would cause the v0.43 node to reject the `MsgExample` because of the unknown field. The expectation that the same Protobuf version can be used across multiple node versions MUST be guaranteed. @@ -55,10 +55,10 @@ On the other hand, module developers MAY add new fields to Protobuf definitions Protobuf supports the [`deprecated` field option](https://developers.google.com/protocol-buffers/docs/proto#options), and this option MAY be used on any field, including `Msg` fields. If a node handles a Protobuf message with a non-empty deprecated field, the node MAY change its behavior upon processing it, even in a protocol-breaking way. When possible, the node MUST handle backwards compatibility without breaking the consensus (unless we increment the proto version). -As an example, the SDK v0.42 to v0.43 update contained two Protobuf-breaking changes, listed below. Instead of bumping the package versions from `v1beta1` to `v1`, the SDK team decided to follow this guideline, by reverting the breaking changes, marking those changes as deprecated, and modifying the node implementation when processing messages with deprecated fields. More specifically: +As an example, the Cosmos SDK v0.42 to v0.43 update contained two Protobuf-breaking changes, listed below. Instead of bumping the package versions from `v1beta1` to `v1`, the SDK team decided to follow this guideline, by reverting the breaking changes, marking those changes as deprecated, and modifying the node implementation when processing messages with deprecated fields. More specifically: -- The SDK recently removed support for [time-based software upgrades](https://github.com/cosmos/cosmos-sdk/pull/8849). As such, the `time` field has been marked as deprecated in `cosmos.upgrade.v1beta1.Plan`. Moreover, the node will reject any proposal containing an upgrade Plan whose `time` field is non-empty. -- The SDK now supports [governance split votes](./adr-037-gov-split-vote.md). When querying for votes, the returned `cosmos.gov.v1beta1.Vote` message has its `option` field (used for 1 vote option) deprecated in favor of its `options` field (allowing multiple vote options). Whenever possible, the SDK still populates the deprecated `option` field, that is, if and only if the `len(options) == 1` and `options[0].Weight == 1.0`. +- The Cosmos SDK recently removed support for [time-based software upgrades](https://github.com/cosmos/cosmos-sdk/pull/8849). As such, the `time` field has been marked as deprecated in `cosmos.upgrade.v1beta1.Plan`. Moreover, the node will reject any proposal containing an upgrade Plan whose `time` field is non-empty. +- The Cosmos SDK now supports [governance split votes](./adr-037-gov-split-vote.md). When querying for votes, the returned `cosmos.gov.v1beta1.Vote` message has its `option` field (used for 1 vote option) deprecated in favor of its `options` field (allowing multiple vote options). Whenever possible, the SDK still populates the deprecated `option` field, that is, if and only if the `len(options) == 1` and `options[0].Weight == 1.0`. #### 4. Fields MUST NOT be renamed. @@ -69,8 +69,8 @@ Whereas the official Protobuf recommendations do not prohibit renaming fields, a TODO, needs architecture review. Some topics: - Bumping versions frequency -- When bumping versions, should the SDK support both versions? - - i.e. v1beta1 -> v1, should we have two folders in the SDK, and handlers for both versions? +- When bumping versions, should the Cosmos SDK support both versions? + - i.e. v1beta1 -> v1, should we have two folders in the Cosmos SDK, and handlers for both versions? - mention ADR-023 Protobuf naming ## Consequences diff --git a/docs/architecture/adr-045-check-delivertx-middlewares.md b/docs/architecture/adr-045-check-delivertx-middlewares.md index b66f410fec52..29e874c7c6eb 100644 --- a/docs/architecture/adr-045-check-delivertx-middlewares.md +++ b/docs/architecture/adr-045-check-delivertx-middlewares.md @@ -16,7 +16,7 @@ This ADR replaces the current BaseApp `runTx` and antehandlers design with a mid BaseApp's implementation of ABCI `{Check,Deliver}Tx()` and its own `Simulate()` method call the `runTx` method under the hood, which first runs antehandlers, then executes `Msg`s. However, the [transaction Tips](https://github.com/cosmos/cosmos-sdk/issues/9406) and [refunding unused gas](https://github.com/cosmos/cosmos-sdk/issues/2150) use cases require custom logic to be run after the `Msg`s execution. There is currently no way to achieve this. -An naive solution would be to add post-`Msg` hooks to BaseApp. However, the SDK team thinks in parallel about the bigger picture of making app wiring simpler ([#9181](https://github.com/cosmos/cosmos-sdk/discussions/9182)), which includes making BaseApp more lightweight and modular. +An naive solution would be to add post-`Msg` hooks to BaseApp. However, the Cosmos SDK team thinks in parallel about the bigger picture of making app wiring simpler ([#9181](https://github.com/cosmos/cosmos-sdk/discussions/9182)), which includes making BaseApp more lightweight and modular. ## Decision @@ -130,7 +130,7 @@ func (txh myTxHandler) SimulateTx(ctx context.Context, tx sdk.Tx, req tx.Request ### Composing Middlewares -While BaseApp simply holds a reference to a `tx.Handler`, this `tx.Handler` itself is defined using a middleware stack. The SDK exposes a base (i.e. innermost) `tx.Handler` called `RunMsgsTxHandler`, which executes messages. +While BaseApp simply holds a reference to a `tx.Handler`, this `tx.Handler` itself is defined using a middleware stack. The Cosmos SDK exposes a base (i.e. innermost) `tx.Handler` called `RunMsgsTxHandler`, which executes messages. Then, the app developer can compose multiple middlewares on top on the base `tx.Handler`. Each middleware can run pre-and-post-processing logic around its next middleware, as described in the section above. Conceptually, as an example, given the middlewares `A`, `B`, and `C` and the base `tx.Handler` `H` the stack looks like: @@ -159,11 +159,11 @@ txHandler := middleware.ComposeMiddlewares(...) app.SetTxHandler(txHandler) ``` -The app developer can define their own middlewares, or use the SDK's pre-defined middlewares from `middleware.NewDefaultTxHandler()`. +The app developer can define their own middlewares, or use the Cosmos SDK's pre-defined middlewares from `middleware.NewDefaultTxHandler()`. -### Middlewares Maintained by the SDK +### Middlewares Maintained by the Cosmos SDK -While the app developer can define and compose the middlewares of their choice, the SDK provides a set of middlewares that caters for the ecosystem's most common use cases. These middlewares are: +While the app developer can define and compose the middlewares of their choice, the Cosmos SDK provides a set of middlewares that caters for the ecosystem's most common use cases. These middlewares are: | Middleware | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -220,7 +220,7 @@ if err != nil { + app.SetTxHandler(txHandler) ``` -Other more minor API breaking changes will also be provided in the CHANGELOG. As usual, the SDK will provide a release migration document for app developers. +Other more minor API breaking changes will also be provided in the CHANGELOG. As usual, the Cosmos SDK will provide a release migration document for app developers. This ADR does not introduce any state-machine-, client- or CLI-breaking changes. diff --git a/docs/basics/README.md b/docs/basics/README.md index 03934dcd5112..3907f6e60bd9 100644 --- a/docs/basics/README.md +++ b/docs/basics/README.md @@ -8,7 +8,7 @@ parent: This repository contains reference documentation on the basic concepts of the Cosmos SDK. -1. [Anatomy of an SDK Application](./app-anatomy.md) +1. [Anatomy of a Cosmos SDK Application](./app-anatomy.md) 2. [Lifecycle of a transaction](./tx-lifecycle.md) 3. [Lifecycle of a query](./query-lifecycle.md) 4. [Accounts](./accounts.md) diff --git a/docs/basics/accounts.md b/docs/basics/accounts.md index d57f80955cd1..b01c124ab722 100644 --- a/docs/basics/accounts.md +++ b/docs/basics/accounts.md @@ -8,7 +8,7 @@ This document describes the in-built account and public key system of the Cosmos ### Pre-requisite Readings -- [Anatomy of an SDK Application](./app-anatomy.md) {prereq} +- [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq} ## Account Definition @@ -66,9 +66,9 @@ In the node, all data is stored using Protocol Buffers serialization. The Cosmos SDK supports the following digital key schemes for creating digital signatures: -- `secp256k1`, as implemented in the [SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/secp256k1/secp256k1.go). -- `secp256r1`, as implemented in the [SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/secp256r1/pubkey.go), -- `tm-ed25519`, as implemented in the [SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation. +- `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/secp256k1/secp256k1.go). +- `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/secp256r1/pubkey.go), +- `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation. | | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) | |:------------:|:-----------------------:|:--------------------------:|:-----------------------------------:|:-------------------------------:| @@ -80,7 +80,7 @@ The Cosmos SDK supports the following digital key schemes for creating digital s `Addresses` and `PubKey`s are both public information that identifies actors in the application. `Account` is used to store authentication information. The basic account implementation is provided by a `BaseAccount` object. -Each account is identified using `Address` which is a sequence of bytes derived from a public key. In SDK, we define 3 types of addresses that specify a context where an account is used: +Each account is identified using `Address` which is a sequence of bytes derived from a public key. In the Cosmos SDK, we define 3 types of addresses that specify a context where an account is used: - `AccAddress` identifies users (the sender of a `message`). - `ValAddress` identifies validator operators. @@ -137,7 +137,7 @@ The default implementation of `Keyring` comes from the third-party [`99designs/k A few notes on the `Keyring` methods: -- `Sign(uid string, payload []byte) ([]byte, sdkcrypto.PubKey, error)` strictly deals with the signature of the `payload` 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](adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the SDK by default, it is deferred to the [`anteHandler`](../core/baseapp.md#antehandler). +- `Sign(uid string, payload []byte) ([]byte, sdkcrypto.PubKey, error)` strictly deals with the signature of the `payload` 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](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/baseapp.md#antehandler). +++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/proto/cosmos/tx/v1beta1/tx.proto#L47-L64 - `NewAccount(uid, mnemonic, bip39Passwd, hdPath string, algo SignatureAlgo) (Info, error)` creates a new account based on the [`bip44 path`](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) and persists it on disk. The `PrivKey` is **never stored unencrypted**, instead it is [encrypted with a passphrase](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/crypto/armor.go) before being persisted. In the context of this method, the key type and sequence number refer to the segment of the BIP44 derivation path (for example, `0`, `1`, `2`, ...) that is used to derive a private and a public key from the mnemonic. Using the same mnemonic and derivation path, the same `PrivKey`, `PubKey` and `Address` is generated. The following keys are supported by the keyring: diff --git a/docs/basics/app-anatomy.md b/docs/basics/app-anatomy.md index 233b7e1b4503..c72cd3f7c702 100644 --- a/docs/basics/app-anatomy.md +++ b/docs/basics/app-anatomy.md @@ -2,13 +2,13 @@ order: 1 --> -# Anatomy of an SDK Application +# Anatomy of a Cosmos SDK Application This document describes the core parts of a Cosmos SDK application. Throughout the document, a placeholder application named `app` will be used. {synopsis} ## Node Client -The Daemon, or [Full-Node Client](../core/node.md), is the core process of an 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](../core/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. ``` ^ +-------------------------------+ ^ @@ -48,10 +48,10 @@ The first thing defined in `app.go` is the `type` of the application. It is gene - **A list of store keys**. The [store](../core/store.md), which contains the entire state, is implemented as a [`multistore`](../core/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/ocap.md) of the Cosmos SDK. - **A list of module's `keeper`s.** Each module defines an abstraction called [`keeper`](../building-modules/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/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/encoding.md). -- **A reference to a [`legacyAmino`](../core/encoding.md) codec.** Some parts of the SDK have not been migrated to use the `appCodec` above, and are still hardcoded to use Amino. Other parts explicity 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 [`legacyAmino`](../core/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 explicity 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/module-manager.md#manager)** and a [basic module manager](../building-modules/module-manager.md#basicmanager). The module manager is an object that contains a list of the application's module. It facilitates operations related to these modules, like registering their [`Msg` service](../core/baseapp.md#msg-services) and [gRPC `Query` service](../core/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 SDK's own app used for demo and testing purposes: +See an example of application type definition from `simapp`, the Cosmos SDK's own app used for demo and testing purposes: +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L145-L187 @@ -67,7 +67,7 @@ Here are the main actions performed by this function: - Instantiate a new application with a reference to a `baseapp` instance, a codec and all the appropriate store keys. - Instantiate all the [`keeper`s](#keeper) 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/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/baseapp.md#msg-services), [gRPC `Query` services](../core/baseapp.md#grpc-query-services), [legacy `Msg` routes](../core/baseapp.md#routing) and [legacy query routes](../core/baseapp.md#query-routing). When a transaction is relayed to the application by Tendermint 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 SDK still supports legacy `Msg`s and legacy Tendermint queries, which are routed using respectively the legacy `Msg` routes and the legacy query routes. +- With the module manager, initialize the application's [`Msg` services](../core/baseapp.md#msg-services), [gRPC `Query` services](../core/baseapp.md#grpc-query-services), [legacy `Msg` routes](../core/baseapp.md#routing) and [legacy query routes](../core/baseapp.md#query-routing). When a transaction is relayed to the application by Tendermint 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 Tendermint queries, which are routed using respectively the legacy `Msg` routes and the legacy query routes. - With the module manager, register the [application's modules' invariants](../building-modules/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/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 will be triggered (usually the chain is halted). This is useful to make sure no critical bug goes unnoticed and produces long-lasting effects that would be 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 remainer of application's parameters: @@ -95,7 +95,7 @@ See an example of an `InitChainer` from `simapp`: ### BeginBlocker and EndBlocker -The SDK offers developers the possibility to implement automatic execution of code as part of their application. This is implemented through two function called `BeginBlocker` and `EndBlocker`. They are called when the application receives respectively the `BeginBlock` and `EndBlock` messages from the Tendermint engine, which happens 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://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetBeginBlocker) and [`SetEndBlocker`](https://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetEndBlocker) methods. +The Cosmos SDK offers developers the possibility to implement automatic execution of code as part of their application. This is implemented through two function called `BeginBlocker` and `EndBlocker`. They are called when the application receives respectively the `BeginBlock` and `EndBlock` messages from the Tendermint engine, which happens 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://godoc.org/github.com/cosmos/cosmos-sdk/baseapp#BaseApp.SetBeginBlocker) and [`SetEndBlocker`](https://godoc.org/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/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 will call the `BeginBLock` and `EndBlock` functions of each of the modules it contains. Note that the order in which the modules' `BegingBlock` and `EndBlock` functions must be called has to be set in the module manager using the `SetOrderBeginBlock` and `SetOrderEndBlock` methods respectively. This is done via the [module manager](../building-modules/module-manager.md) in the [application's constructor](#application-constructor), and the `SetOrderBeginBlock` and `SetOrderEndBlock` methods have to be called before the `SetBeginBlocker` and `SetEndBlocker` functions. @@ -115,12 +115,12 @@ 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 of the application's modules 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-19](../architecture/adr-019-protobuf-state-encoding.md#usage-of-any-to-encode-interfaces). - - To go more into details, the SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/gogo/protobuf). By default, the [gogo protobuf implementation of `Any`](https://godoc.org/github.com/gogo/protobuf/types) uses [global type registration](https://github.com/gogo/protobuf/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 registry 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). -- `Marshaler`: the default codec used throughout the 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 `Marshaler`. + - To go more into details, the Cosmos SDK uses an implementation of the Protobuf specification called [`gogoprotobuf`](https://github.com/gogo/protobuf). By default, the [gogo protobuf implementation of `Any`](https://godoc.org/github.com/gogo/protobuf/types) uses [global type registration](https://github.com/gogo/protobuf/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 registry 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). +- `Marshaler`: 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 `Marshaler`. - `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/transactions.md). -- `Amino`: Some legacy parts of the 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. +- `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. -The SDK exposes a `MakeTestEncodingConfig` function used to create a `EncodingConfig` for the app constructor (`NewApp`). It uses Protobuf as a default `Marshaler`. +The Cosmos SDK exposes a `MakeTestEncodingConfig` function used to create a `EncodingConfig` for the app constructor (`NewApp`). It uses Protobuf as a default `Marshaler`. NOTE: this function is marked deprecated and should only be used to create an app or in tests. We are working on refactoring codec management in a post Stargate release. See an example of a `MakeTestEncodingConfig` from `simapp`: @@ -129,7 +129,7 @@ See an example of a `MakeTestEncodingConfig` from `simapp`: ## Modules -[Modules](../building-modules/intro.md) are the heart and soul of SDK applications. They can be considered as state-machines within the state-machine. When a transaction is relayed from the underlying Tendermint engine via the ABCI to the application, it is routed by [`baseapp`](../core/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 an 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 SDK's `x/` folder, which contains already-built modules). +[Modules](../building-modules/intro.md) are the heart and soul of Cosmos SDK applications. They can be considered as state-machines within the state-machine. When a transaction is relayed from the underlying Tendermint engine via the ABCI to the application, it is routed by [`baseapp`](../core/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 @@ -192,7 +192,7 @@ Each module defines command-line commands, gRPC services and REST routes to be e Generally, the [commands related to a module](../building-modules/module-interfaces.md#cli) are defined in a folder called `client/cli` in the module's folder. The CLI divides commands in two category, 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 SDK handles signing and the addition of other transaction metadata. +- 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/baseapp.md#query-routing), which routes them to the appropriate [querier](#querier) the `queryRoute` parameter supplied. #### gRPC @@ -206,17 +206,17 @@ Each module can expose gRPC endpoints, called [service methods](https://grpc.io/ #### gRPC-gateway REST Endpoints -Some external clients may not wish to use gRPC. The SDK provides in this case a gRPC gateway service, which exposes each gRPC service as a correspoding REST endpoint. Please refer to the [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) documentation to learn more. +Some external clients may not wish to use gRPC. The Cosmos SDK provides in this case a gRPC gateway service, which exposes each gRPC service as a correspoding REST endpoint. Please refer to the [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) documentation to learn more. 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 an URL starting with the `/cosmos/` prefix. -The 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/run-node.md#configuring-the-node-using-apptoml) 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`](../run-node/run-node.md#configuring-the-node-using-apptoml) 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/cli.md). The CLI of an 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 defined in a file called `appd/main.go`. The file contains: +The main interface is the [Command-Line Interface](../core/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 defined in a file called `appd/main.go`. The file contains: - **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** 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. @@ -229,7 +229,7 @@ See an example of an application's main command-line file from the [nameservice ## Dependencies and Makefile ::: warning -A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`. +A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the Cosmos SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`. To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`: diff --git a/docs/basics/gas-fees.md b/docs/basics/gas-fees.md index 0a93c133580f..c9a9cc77ffa3 100644 --- a/docs/basics/gas-fees.md +++ b/docs/basics/gas-fees.md @@ -8,14 +8,14 @@ This document describes the default strategies to handle gas and fees within a C ### Pre-requisite Readings -- [Anatomy of an SDK Application](./app-anatomy.md) {prereq} +- [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq} ## Introduction to `Gas` and `Fees` 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 will be finalized. This is implemented by default in the 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/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 SDK does not enforce `gas` pricing by default, as there may be other ways to prevent spam (e.g. bandwidth schemes). Still, most applications will implement `fee` mechanisms to prevent spam. This is done via the [`AnteHandler`](#antehandler). +- Make sure blocks are not consuming too many resources and will be 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/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 will implement `fee` mechanisms to prevent spam. This is done via the [`AnteHandler`](#antehandler). ## Gas Meter @@ -71,7 +71,7 @@ The `AnteHandler` is run for every transaction during `CheckTx` and `DeliverTx`, type AnteHandler func(ctx Context, tx Tx, simulate bool) (newCtx Context, result Result, abort bool) ``` -The `anteHandler` is not implemented in the core SDK but in a module. This gives the possibility to developers to choose which version of `AnteHandler` fits their application's needs. That said, most applications today use the default implementation defined in the [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth). Here is what the `anteHandler` is intended to do in a normal Cosmos SDK application: +The `anteHandler` is not implemented in the core Cosmos SDK but in a module. This gives the possibility to developers to choose which version of `AnteHandler` fits their application's needs. That said, most applications today use the default implementation defined in the [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth). Here is what the `anteHandler` is intended to do in a normal Cosmos SDK application: - Verify that the transaction are of the correct type. Transaction types are defined in the module that implements the `anteHandler`, and they follow the transaction interface: +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57 diff --git a/docs/basics/query-lifecycle.md b/docs/basics/query-lifecycle.md index 55902e698d3c..a71faac0c0d4 100644 --- a/docs/basics/query-lifecycle.md +++ b/docs/basics/query-lifecycle.md @@ -4,7 +4,7 @@ order: 3 # Query Lifecycle -This document describes the lifecycle of a query in a SDK application, from the user interface to application stores and back. {synopsis} +This document describes the lifecycle of a query in a Cosmos SDK application, from the user interface to application stores and back. {synopsis} ## Pre-requisite Readings @@ -39,7 +39,7 @@ The CLI understands a specific set of commands, defined in a hierarchical struct ### gRPC ::: warning -A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`. +A patch introduced in `go-grpc v1.34.0` made gRPC incompatible with the `gogoproto` library, making some [gRPC queries](https://github.com/cosmos/cosmos-sdk/issues/8426) panic. As such, the Cosmos SDK requires that `go-grpc <=v1.33.2` is installed in your `go.mod`. To make sure that gRPC is working properly, it is **highly recommended** to add the following line in your application's `go.mod`: @@ -109,7 +109,7 @@ Here is what the code looks like for the CLI command: #### gRPC Query Client Creation -The SDK leverages code generated from Protobuf services to make queries. The `staking` module's `MyQuery` service generates a `queryClient`, which the CLI will use to make queries. Here is the relevant code: +The Cosmos SDK leverages code generated from Protobuf services to make queries. The `staking` module's `MyQuery` service generates a `queryClient`, which the CLI will use to make queries. Here is the relevant code: +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L318-L342 diff --git a/docs/basics/tx-lifecycle.md b/docs/basics/tx-lifecycle.md index a070aafda42c..9139988af1aa 100644 --- a/docs/basics/tx-lifecycle.md +++ b/docs/basics/tx-lifecycle.md @@ -8,7 +8,7 @@ This document describes the lifecycle of a transaction from creation to committe ### Pre-requisite Readings -- [Anatomy of an SDK Application](./app-anatomy.md) {prereq} +- [Anatomy of a Cosmos SDK Application](./app-anatomy.md) {prereq} ## Creation diff --git a/docs/building-modules/errors.md b/docs/building-modules/errors.md index 0eb3728a5e72..0a7990b7686c 100644 --- a/docs/building-modules/errors.md +++ b/docs/building-modules/errors.md @@ -22,13 +22,13 @@ Example: Each custom module error must provide the codespace, which is typically the module name (e.g. "distribution") and is unique per module, and a uint32 code. Together, the codespace and code -provide a globally unique SDK error. Typically, the code is monotonically increasing but does not +provide a globally unique Cosmos SDK error. Typically, the code is monotonically increasing but does not necessarily have to be. The only restrictions on error codes are the following: * Must be greater than one, as a code value of one is reserved for internal errors. * Must be unique within the module. -Note, the SDK provides a core set of *common* errors. These errors are defined in `types/errors/errors.go`. +Note, the Cosmos SDK provides a core set of *common* errors. These errors are defined in `types/errors/errors.go`. ## Wrapping @@ -40,11 +40,11 @@ Example: +++ https://github.com/cosmos/cosmos-sdk/blob/b2d48a9e815fe534a7faeec6ca2adb0874252b81/x/bank/keeper/keeper.go#L85-L122 -Regardless if an error is wrapped or not, the SDK's `errors` package provides an API to determine if +Regardless if an error is wrapped or not, the Cosmos SDK's `errors` package provides an API to determine if an error is of a particular kind via `Is`. ## ABCI -If a module error is registered, the SDK `errors` package allows ABCI information to be extracted +If a module error is registered, the Cosmos SDK `errors` package allows ABCI information to be extracted through the `ABCIInfo` API. The package also provides `ResponseCheckTx` and `ResponseDeliverTx` as auxiliary APIs to automatically get `CheckTx` and `DeliverTx` responses from an error. diff --git a/docs/building-modules/intro.md b/docs/building-modules/intro.md index b486176bcb6b..ffe37217160d 100644 --- a/docs/building-modules/intro.md +++ b/docs/building-modules/intro.md @@ -2,22 +2,22 @@ order: 1 --> -# Introduction to SDK Modules +# Introduction to Cosmos SDK Modules -Modules define most of the logic of SDK applications. Developers compose modules together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management. {synopsis} +Modules define most of the logic of Cosmos SDK applications. Developers compose modules together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management. {synopsis} ## Pre-requisite Readings -- [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq} -- [Lifecycle of an SDK transaction](../basics/tx-lifecycle.md) {prereq} +- [Anatomy of a Cosmos SDK application](../basics/app-anatomy.md) {prereq} +- [Lifecycle of a Cosmos SDK transaction](../basics/tx-lifecycle.md) {prereq} -## Role of Modules in an SDK Application +## 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/baseapp.md) to communicate with the underlying consensus engine, a [`multistore`](../core/store.md#multistore) to persist state, a [server](../core/node.md) to form a full-node and [interfaces](./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 SDK modules, making it increasingly easier to build complex blockchain applications. +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. -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/store.md), as well as a subset of [message types](./messages-and-queries.md#messages). These messages are routed by one of the main components of SDK core, [`BaseApp`](../core/baseapp.md), to a module Protobuf [`Msg` service](./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](../core/store.md), as well as a subset of [message types](./messages-and-queries.md#messages). These messages are routed by one of the main components of Cosmos SDK core, [`BaseApp`](../core/baseapp.md), to a module Protobuf [`Msg` service](./msg-services.md) that defines them. ``` + @@ -64,17 +64,17 @@ SDK modules can be seen as little state-machines within the state-machine. They v ``` -As a result of this architecture, building an SDK application usually revolves around writing modules to implement the specialized logic of the application, and composing them with existing modules to complete the application. Developers will generally work on modules that implement logic needed for their specific use case that do not exist yet, and will use existing modules for more generic functionalities like staking, accounts or token management. +As a result of this architecture, building a Cosmos SDK application usually revolves around writing modules to implement the specialized logic of the application and composing them with existing modules to complete the application. Developers will generally work on modules that implement logic needed for their specific use case that do not exist yet, and will use existing modules for more generic functionalities like staking, accounts, or token management. ## How to Approach Building Modules as a Developer While there are no definitive guidelines for writing modules, here are some important design principles developers should keep in mind when building them: -- **Composability**: 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`](./keeper.md). +- **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`](./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/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`](./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 SDK Modules +## Main Components of Cosmos SDK Modules 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: diff --git a/docs/building-modules/invariants.md b/docs/building-modules/invariants.md index 0adce4dc1f9e..a5272f25a512 100644 --- a/docs/building-modules/invariants.md +++ b/docs/building-modules/invariants.md @@ -67,7 +67,7 @@ For more, see an example of [`Invariant`s implementation from the `staking` modu The `InvariantRegistry` is a registry where the `Invariant`s of all the modules of an application are registered. There is only one `InvariantRegistry` per **application**, meaning module developers need not implement their own `InvariantRegistry` when building a module. **All module developers need to do is to register their modules' invariants in the `InvariantRegistry`, as explained in the section above**. The rest of this section gives more information on the `InvariantRegistry` itself, and does not contain anything directly relevant to module developers. -At its core, the `InvariantRegistry` is defined in the SDK as an interface: +At its core, the `InvariantRegistry` is defined in the Cosmos SDK as an interface: +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L14-L17 diff --git a/docs/building-modules/keeper.md b/docs/building-modules/keeper.md index 0f82ccd2e8fa..e2e91312d907 100644 --- a/docs/building-modules/keeper.md +++ b/docs/building-modules/keeper.md @@ -8,7 +8,7 @@ order: 7 ## Pre-requisite Readings -- [Introduction to SDK Modules](./intro.md) {prereq} +- [Introduction to Cosmos SDK Modules](./intro.md) {prereq} ## Motivation diff --git a/docs/building-modules/messages-and-queries.md b/docs/building-modules/messages-and-queries.md index 3481939673b6..21e5bec15f7a 100644 --- a/docs/building-modules/messages-and-queries.md +++ b/docs/building-modules/messages-and-queries.md @@ -8,13 +8,13 @@ order: 3 ## Pre-requisite Readings -- [Introduction to SDK Modules](./intro.md) {prereq} +- [Introduction to Cosmos SDK Modules](./intro.md) {prereq} ## Messages `Msg`s are objects whose end-goal is to trigger state-transitions. They are wrapped in [transactions](../core/transactions.md), which may contain one or more of them. -When a transaction is relayed from the underlying consensus engine to the SDK application, it is first decoded by [`BaseApp`](../core/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](./msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../basics/tx-lifecycle.md). +When a transaction is relayed from the underlying consensus engine to the Cosmos SDK application, it is first decoded by [`BaseApp`](../core/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](./msg-services.md). For a more detailed explanation of the lifecycle of a transaction, click [here](../basics/tx-lifecycle.md). ### `Msg` Services @@ -32,14 +32,14 @@ Each `Msg` service method must have exactly one argument, which must implement t `sdk.Msg` interface is a simplified version of the Amino `LegacyMsg` interface described [below](#legacy-amino-msgs) with only `ValidateBasic()` and `GetSigners()` methods. For backwards compatibility with [Amino `LegacyMsg`s](#legacy-amino-msgs), existing `LegacyMsg` types should be used as the request parameter for `service` RPC definitions. Newer `sdk.Msg` types, which only support `service` definitions, should use canonical `Msg...` name. -Cosmos SDK uses Protobuf definitions to generate client and server code: +The Cosmos SDK uses Protobuf definitions to generate client and server code: * `MsgServer` interface defines the server API for the `Msg` service and its implementation is described as part of the [`Msg` services](./msg-services.md) documentation. * Structures are generated for all RPC request and response types. A `RegisterMsgServer` method is also generated and should be used to register the module's `MsgServer` implementation in `RegisterServices` method from the [`AppModule` interface](./module-manager.md#appmodule). -In order for clients (CLI and grpc-gateway) to have these URLs registered, the SDK provides the function `RegisterMsgServiceDesc(registry codectypes.InterfaceRegistry, sd *grpc.ServiceDesc)` that should be called inside module's [`RegisterInterfaces`](module-manager.md#appmodulebasic) method, using the proto-generated `&_Msg_serviceDesc` as `*grpc.ServiceDesc` argument. +In order for clients (CLI and grpc-gateway) to have these URLs registered, the Cosmos SDK provides the function `RegisterMsgServiceDesc(registry codectypes.InterfaceRegistry, sd *grpc.ServiceDesc)` that should be called inside module's [`RegisterInterfaces`](module-manager.md#appmodulebasic) method, using the proto-generated `&_Msg_serviceDesc` as `*grpc.ServiceDesc` argument. ### Legacy Amino `LegacyMsg`s @@ -57,7 +57,7 @@ It extends `proto.Message` and contains the following methods: - `Type() string`: Type of the message, used primarly in [events](../core/events.md). This should return a message-specific `string`, typically the denomination of the message itself. - `ValidateBasic() error`: This method is called by `BaseApp` very early in the processing of the `message` (in both [`CheckTx`](../core/baseapp.md#checktx) and [`DeliverTx`](../core/baseapp.md#delivertx)), in order to discard obviously invalid messages. `ValidateBasic` should only include *stateless* checks, i.e. checks that do not require access to the state. This usually consists in checking that the message's parameters are correctly formatted and valid (i.e. that the `amount` is strictly positive for a transfer). - `GetSignBytes() []byte`: Return the canonical byte representation of the message. Used to generate a signature. -- `GetSigners() []AccAddress`: Return the list of signers. The SDK will make sure that each `message` contained in a transaction is signed by all the signers listed in the list returned by this method. +- `GetSigners() []AccAddress`: Return the list of signers. The Cosmos SDK will make sure that each `message` contained in a transaction is signed by all the signers listed in the list returned by this method. See an example implementation of a `message` from the `gov` module: @@ -81,7 +81,7 @@ A `RegisterQueryServer` method is also generated and should be used to register ### Legacy Queries -Before the introduction of Protobuf and gRPC in the SDK, there was usually no specific `query` object defined by module developers, contrary to `message`s. Instead, the SDK took the simpler approach of using a simple `path` to define each `query`. The `path` contains the `query` type and all the arguments needed in order to process it. For most module queries, the `path` should look like the following: +Before the introduction of Protobuf and gRPC in the Cosmos SDK, there was usually no specific `query` object defined by module developers, contrary to `message`s. Instead, the Cosmos SDK took the simpler approach of using a simple `path` to define each `query`. The `path` contains the `query` type and all the arguments needed in order to process it. For most module queries, the `path` should look like the following: ``` queryCategory/queryRoute/queryType/arg1/arg2/... diff --git a/docs/building-modules/module-interfaces.md b/docs/building-modules/module-interfaces.md index c033db6635a5..98b480aa3177 100644 --- a/docs/building-modules/module-interfaces.md +++ b/docs/building-modules/module-interfaces.md @@ -4,7 +4,7 @@ order: 11 # Module Interfaces -This document details how to build CLI and REST interfaces for a module. Examples from various SDK modules are included. {synopsis} +This document details how to build CLI and REST interfaces for a module. Examples from various Cosmos SDK modules are included. {synopsis} ## Prerequisite Readings @@ -100,7 +100,7 @@ cmd.MarkFlagRequired(FlagFrom) For more detailed information on creating flags, visit the [Cobra Documentation](https://github.com/spf13/cobra). -As mentioned in [transaction commands](#transaction-commands), there is a set of flags that all transaction commands must add. This is done with the `AddTxFlagsToCmd` method defined in the SDK's `./client/flags` package. +As mentioned in [transaction commands](#transaction-commands), there is a set of flags that all transaction commands must add. This is done with the `AddTxFlagsToCmd` method defined in the Cosmos SDK's `./client/flags` package. +++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L94-L120 @@ -132,7 +132,7 @@ Modules that want to expose REST queries should add `google.api.http` annotation gRPC gateway is started in-process along with the application and Tendermint. It can be enabled or disabled by setting gRPC Configuration `enable` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml). -The SDK provides a command for generating [Swagger](https://swagger.io/) documentation (`protoc-gen-swagger`). Setting `swagger` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) defines if swagger documentation should be automatically registered. +The Cosmos SDK provides a command for generating [Swagger](https://swagger.io/) documentation (`protoc-gen-swagger`). Setting `swagger` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) defines if swagger documentation should be automatically registered. ## Next {hide} diff --git a/docs/building-modules/module-manager.md b/docs/building-modules/module-manager.md index 334d252e6188..92941112edac 100644 --- a/docs/building-modules/module-manager.md +++ b/docs/building-modules/module-manager.md @@ -8,11 +8,11 @@ Cosmos SDK modules need to implement the [`AppModule` interfaces](#application-m ## Pre-requisite Readings -- [Introduction to SDK Modules](./intro.md) {prereq} +- [Introduction to Cosmos SDK Modules](./intro.md) {prereq} ## Application Module Interfaces -Application module interfaces exist to facilitate the composition of modules together to form a functional SDK application. There are 3 main application module interfaces: +Application module interfaces exist to facilitate the composition of modules together to form a functional Cosmos SDK application. There are 3 main application module interfaces: - [`AppModuleBasic`](#appmodulebasic) for independent module functionalities. - [`AppModule`](#appmodule) for inter-dependent module functionalities (except genesis-related functionalities). diff --git a/docs/building-modules/query-services.md b/docs/building-modules/query-services.md index 4113e099efe0..df1e05dfa045 100644 --- a/docs/building-modules/query-services.md +++ b/docs/building-modules/query-services.md @@ -38,7 +38,7 @@ type QueryServer interface { ``` These custom queries methods should be implemented by a module's keeper, typically in `./keeper/grpc_query.go`. The first parameter of these methods is a generic `context.Context`, whereas querier methods generally need an instance of `sdk.Context` to read -from the store. Therefore, the SDK provides a function `sdk.UnwrapSDKContext` to retrieve the `sdk.Context` from the provided +from the store. Therefore, the Cosmos SDK provides a function `sdk.UnwrapSDKContext` to retrieve the `sdk.Context` from the provided `context.Context`. Here's an example implementation for the bank module: diff --git a/docs/building-modules/simulator.md b/docs/building-modules/simulator.md index e6f07fbb6231..479d6141ced9 100644 --- a/docs/building-modules/simulator.md +++ b/docs/building-modules/simulator.md @@ -21,7 +21,7 @@ integrated with the application `SimulationManager`. ## Simulation package -Every module that implements the SDK simulator needs to have a `x//simulation` +Every module that implements the Cosmos SDK simulator needs to have a `x//simulation` package which contains the primary functions required by the fuzz tests: store decoders, randomized genesis state and parameters, weighted operations and proposal contents. @@ -54,7 +54,7 @@ You can see how an example of what is needed to fully test parameter changes [he ### Random weighted operations -Operations are one of the crucial parts of the SDK simulation. They are the transactions +Operations are one of the crucial parts of the Cosmos SDK simulation. They are the transactions (`Msg`) that are simulated with random field values. The sender of the operation is also assigned randomly. @@ -75,7 +75,7 @@ For the last test a tool called runsim -# Using the SDK +# Using the Cosmos SDK - [Modules](../../x/README.md) - [Simulation](../core/simulation.md)