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 <barrie.byron@tendermint.com> * Update docs/architecture/adr-010-modular-antehandler.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/basics/README.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/architecture/adr-040-storage-and-smt-state-commitments.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/core/baseapp.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/building-modules/intro.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * Update docs/basics/accounts.md Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> * docs 10180 fix 'an Cosmos SDK' where used Co-authored-by: Barrie Byron <barrie.byron@tendermint.com> Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com> Co-authored-by: Robert Zaremba <robert@zaremba.ch>
This commit is contained in:
Brenn Hill
co-authored by
Barrie Byron
Amaury
Robert Zaremba
Barrie Byron
Amaury
Robert Zaremba
parent
f757c90f61
commit
a47bd592e9
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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`.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user