diff --git a/docs/architecture/adr-041-in-place-store-migrations.md b/docs/architecture/adr-041-in-place-store-migrations.md index 072a121f5d6..4687ef31f88 100644 --- a/docs/architecture/adr-041-in-place-store-migrations.md +++ b/docs/architecture/adr-041-in-place-store-migrations.md @@ -75,7 +75,7 @@ func (m Migrator) Migrate1to2(ctx sdk.Context) error { } ``` -Each module's migration functions are specific to the module's store evolutions, and are not described in this ADR. An example of x/bank store key migrations following the introduction of ADR-028 length-prefixed addresses can be seen [here](https://github.com/cosmos/cosmos-sdk/blob/ef8dabcf0f2ecaf26db1c6c6d5922e9399458bb3/x/bank/legacy/v042/store.go#L15). +Each module's migration functions are specific to the module's store evolutions, and are not described in this ADR. An example of x/bank store key migrations after the introduction of ADR-028 length-prefixed addresses can be seen in this [store.go code](https://github.com/cosmos/cosmos-sdk/blob/36f68eb9e041e20a5bb47e216ac5eb8b91f95471/x/bank/legacy/v043/store.go#L41-L62). ### Tracking Module Versions in `x/upgrade` diff --git a/docs/basics/accounts.md b/docs/basics/accounts.md index 756545af4aa..9b7648b8c7d 100644 --- a/docs/basics/accounts.md +++ b/docs/basics/accounts.md @@ -98,7 +98,7 @@ Also see the [`Addresses`](#addresses) section for more information. `PubKey`s used in the Cosmos SDK are Protobuf messages and have the following methods: -+++ https://github.com/cosmos/cosmos-sdk/blob/master/crypto/types/types.go#L8-L17 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/types/types.go#L8-L17 - For `secp256k1` keys, the actual implementation can be found [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/crypto/keys/secp256k1/secp256k1.go). - For `ed25519` keys, it can be found [here](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/crypto/keys/ed25519/ed25519.go). diff --git a/docs/basics/app-anatomy.md b/docs/basics/app-anatomy.md index 8980ebda54a..70b725865ab 100644 --- a/docs/basics/app-anatomy.md +++ b/docs/basics/app-anatomy.md @@ -113,8 +113,8 @@ The `EncodingConfig` structure is the last important part of the `app.go` file. Here are descriptions of what each of the four fields means: -- `InterfaceRegistry`: The `InterfaceRegistry` is used by the Protobuf codec to handle interfaces, which 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 which 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, which can be used to register the module's own interfaces and implementations. - - You can read more about Any in [ADR-19](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-019-protobuf-state-encoding.md#usage-of-any-to-encode-interfaces). +- `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 `BinaryMarshaler` used to encode and decode state, and a `JSONMarshaler` 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). diff --git a/docs/building-modules/invariants.md b/docs/building-modules/invariants.md index d21100cb24b..32fd30591b0 100644 --- a/docs/building-modules/invariants.md +++ b/docs/building-modules/invariants.md @@ -74,7 +74,7 @@ At its core, the `InvariantRegistry` is defined in the SDK as an interface: Typically, this interface is implemented in the `keeper` of a specific module. The most used implementation of an `InvariantRegistry` can be found in the `crisis` module: -+++ https://github.com/cosmos/cosmos-sdk/blob/master/x/crisis/keeper/keeper.go#L50-L54 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/crisis/keeper/keeper.go#L50-L54 The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../basics/app-anatomy.md#constructor-function). diff --git a/docs/building-modules/simulator.md b/docs/building-modules/simulator.md index 1d46f3c70e4..7a9e72ca00d 100644 --- a/docs/building-modules/simulator.md +++ b/docs/building-modules/simulator.md @@ -63,9 +63,9 @@ Operations on the simulation are simulated using the full [transaction cycle](.. Shown below is how weights are set: -+++ https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/simulation/operations.go#L18-L68 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/simulation/operations.go#L18-L68 -As you can see the weights are predefined in this case but there are options on how to override this behavior with different weights. One is allowing `*rand.Rand` to define a random weight for the operation, or you can inject your own predefined weights. +As you can see, the weights are predefined in this case. Options exist to override this behavior with different weights. One option is to use `*rand.Rand` to define a random weight for the operation, or you can inject your own predefined weights. Here is how one can override the above package `simappparams`. diff --git a/docs/core/baseapp.md b/docs/core/baseapp.md index c17ce939de4..67dbd557e03 100644 --- a/docs/core/baseapp.md +++ b/docs/core/baseapp.md @@ -126,7 +126,7 @@ is the canonical state of the application and the volatile states, `checkState` are used to handle state transitions in-between the main state made during [`Commit`](#commit). Internally, there is only a single `CommitMultiStore` which we refer to as the main or root state. -From this root state, we derive two volatile state through a mechanism called _store branching_ (performed by `CacheWrap` function). +From this root state, we derive two volatile states by using a mechanism called _store branching_ (performed by `CacheWrap` function). The types can be illustrated as follows: ![Types](./baseapp_state_types.png) @@ -333,7 +333,7 @@ The `AnteHandler` is theoretically optional, but still a very important componen - Perform preliminary _stateful_ validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees. - Play a role in the incentivisation of stakeholders via the collection of transaction fees. -`BaseApp` holds an `anteHandler` as paraemter, which is initialized in the [application's constructor](../basics/app-anatomy.md#application-constructor). The most widely used `anteHandler` today is that of the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/master/x/auth/ante/ante.go). +`BaseApp` holds an `anteHandler` as parameter that is initialized in the [application's constructor](../basics/app-anatomy.md#application-constructor). The most widely used `anteHandler` is the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/ante/ante.go). Click [here](../basics/gas-fees.md#antehandler) for more on the `anteHandler`. diff --git a/docs/core/encoding.md b/docs/core/encoding.md index a4cbddc2acd..fc390f79dd5 100644 --- a/docs/core/encoding.md +++ b/docs/core/encoding.md @@ -69,9 +69,141 @@ typically used for when the data needs to be streamed or grouped together ### Gogoproto -Modules are encouraged to utilize Protobuf encoding for their respective types. +Modules are encouraged to utilize Protobuf encoding for their respective types. In the SDK, we use the [Gogoproto](https://github.com/gogo/protobuf) specific implementation of the Protobuf spec that offers speed and DX improvements compared to the official [Google protobuf implementation](https://github.com/protocolbuffers/protobuf). -#### FAQ +### Guidelines for protobuf message definitions + +In addition to [following official Protocol Buffer guidelines](https://developers.google.com/protocol-buffers/docs/proto3#simple), we recommend using these annotations in .proto files when dealing with interfaces: + +- use `cosmos_proto.accepts_interface` to annote fields that accept interfaces +- pass the same fully qualified name as `protoName` to `InterfaceRegistry.RegisterInterface` +- annotate interface implementations with `cosmos_proto.implements_interface` +- pass the same fully qualified name as `protoName` to `InterfaceRegistry.RegisterInterface` + +### Transaction Encoding + +Another important use of Protobuf is the encoding and decoding of +[transactions](./transactions.md). Transactions are defined by the application or +the SDK but are then passed to the underlying consensus engine to be relayed to +other peers. Since the underlying consensus engine is agnostic to the application, +the consensus engine accepts only transactions in the form of raw bytes. + +- The `TxEncoder` object performs the encoding. +- The `TxDecoder` object performs the decoding. + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/types/tx_msg.go#L83-L87 + +A standard implementation of both these objects can be found in the [`auth` module](../../x/auth/spec/README.md): + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/decoder.go + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/encoder.go + +See [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. + +### Interface Encoding and Usage of `Any` + +The Protobuf DSL is strongly typed, which can make inserting variable-typed fields difficult. Imagine we want to create a `Profile` protobuf message that serves as a wrapper over [an account](../basics/accounts.md): + +```proto +message Profile { + // account is the account associated to a profile. + cosmos.auth.v1beta1.BaseAccount account = 1; + // bio is a short description of the account. + string bio = 4; +} +``` + +In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../../x/auth/spec/05_vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface? + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/types/account.go#L307-L330 + +In [ADR-019](../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: + +```protobuf +message Profile { + // account is the account associated to a profile. + google.protobuf.Any account = 1 [ + (cosmos_proto.accepts_interface) = "AccountI"; // Asserts that this field only accepts Go types implementing `AccountI`. It is purely informational for now. + ]; + // bio is a short description of the account. + string bio = 4; +} +``` + +To add an account inside a profile, we need to "pack" it inside an `Any` first, using `codectypes.NewAnyWithValue`: + +```go +var myAccount AccountI +myAccount = ... // Can be a BaseAccount, a ContinuousVestingAccount or any struct implementing `AccountI` + +// Pack the account into an Any +accAny, err := codectypes.NewAnyWithValue(myAccount) +if err != nil { + return nil, err +} + +// Create a new Profile with the any. +profile := Profile { + Account: accAny, + Bio: "some bio", +} + +// We can then marshal the profile as usual. +bz, err := cdc.MarshalBinaryBare(profile) +jsonBz, err := cdc.MarshalJSON(profile) +``` + +To summarize, to encode an interface, you must 1/ pack the interface into an `Any` and 2/ marshal the `Any`. For convenience, the SDK provides a `MarshalInterface` method to bundle these two steps. Have a look at [a real-life example in the x/auth module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/keeper/keeper.go#L218-L221). + +The reverse operation of retrieving the concrete Go type from inside an `Any`, called "unpacking", is done with the `GetCachedValue()` on `Any`. + +```go +profileBz := ... // The proto-encoded bytes of a Profile, e.g. retrieved through gRPC. +var myProfile Profile +// Unmarshal the bytes into the myProfile struct. +err := cdc.UnmarshalBinaryBare(profilebz, &myProfile) + +// Let's see the types of the Account field. +fmt.Printf("%T\n", myProfile.Account) // Prints "Any" +fmt.Printf("%T\n", myProfile.Account.GetCachedValue()) // Prints "BaseAccount", "ContinuousVestingAccount" or whatever was initially packed in the Any. + +// Get the address of the accountt. +accAddr := myProfile.Account.GetCachedValue().(AccountI).GetAddress() +``` + +It is important to note that for `GetCachedValue()` to work, `Profile` (and any other structs embedding `Profile`) must implement the `UnpackInterfaces` method: + +```go +func (p *Profile) UnpackInterfaces(unpacker codectypes.AnyUnpacker) error { + if p.Account != nil { + var account AccountI + return unpacker.UnpackAny(p.Account, &account) + } + + return nil +} +``` + +The `UnpackInterfaces` gets called recursively on all structs implementing this method, to allow all `Any`s to have their `GetCachedValue()` correctly populated. + +For more information about interface encoding, and especially on `UnpackInterfaces` and how the `Any`'s `type_url` gets resolved using the `InterfaceRegistry`, please refer to [ADR-019](../architecture/adr-019-protobuf-state-encoding.md). + +#### `Any` Encoding in the SDK + +The above `Profile` example is a fictive example used for educational purposes. In the SDK, we use `Any` encoding in several places (non-exhaustive list): + +- the `cryptotypes.PubKey` interface for encoding different types of public keys, +- the `sdk.Msg` interface for encoding different `Msg`s in a transaction, +- the `AccountI` interface for encodinig different types of accounts (similar to the above example) in the x/auth query responses, +- the `Evidencei` interface for encoding different types of evidences in the x/evidence module, +- the `AuthorizationI` interface for encoding different types of x/authz authorizations. + +A real-life example of encoding the pubkey as `Any` inside the Validator struct in x/staking is shown in the following example: + ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/types/validator.go#L40-L61 + +## FAQ 1. How to create modules using protobuf encoding? @@ -123,32 +255,6 @@ type UnpackInterfacesMessage interface { } ``` -#### Guidelines for protobuf message definitions - -In addition to [following official guidelines](https://developers.google.com/protocol-buffers/docs/proto3#simple), we recommend to use these annotations in .proto files when dealing with interfaces: - -- fields which accept interfaces should be annotated with `cosmos_proto.accepts_interface` - using the same full-qualified name passed as `protoName` to `InterfaceRegistry.RegisterInterface` -- interface implementations should be annotated with `cosmos_proto.implements_interface` - using the same full-qualified name passed as `protoName` to `InterfaceRegistry.RegisterInterface` - -#### Transaction Encoding - -Another important use of Protobuf is the encoding and decoding of -[transactions](./transactions.md). Transactions are defined by the application or -the SDK, but passed to the underlying consensus engine in order to be relayed to -other peers. Since the underlying consensus engine is agnostic to the application, -it only accepts transactions in the form of raw bytes. The encoding is done by an -object called `TxEncoder` and the decoding by an object called `TxDecoder`. - -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/types/tx_msg.go#L83-L87 - -A standard implementation of both these objects can be found in the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/master/x/auth): - -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/decoder.go - -+++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/encoder.go - ## Next {hide} Learn about [gRPC, REST and other endpoints](./grpc_rest.md) {hide} diff --git a/docs/core/events.md b/docs/core/events.md index d199d94ced5..999d2876169 100644 --- a/docs/core/events.md +++ b/docs/core/events.md @@ -9,20 +9,28 @@ order: 9 ## Pre-requisite Readings - [Anatomy of an SDK application](../basics/app-anatomy.md) {prereq} +- [Tendermint Documentation on Events](https://docs.tendermint.com/master/spec/abci/abci.html#events) {prereq} ## Events Events are implemented in the Cosmos SDK as an alias of the ABCI `Event` type and -take the form of: `{eventType}.{eventAttribute}={value}`. +take the form of: `{eventType}.{attributeKey}={attributeValue}`. -+++ https://github.com/tendermint/tendermint/blob/bc572217c07b90ad9cee851f193aaa8e9557cbc7/abci/types/types.pb.go#L2187-L2193 ++++ https://github.com/tendermint/tendermint/blob/v0.34.8/proto/tendermint/abci/types.proto#L304-L313 -Events contain: +An Event contains: -- A `type`, which is meant to categorize an event at a high-level (e.g. by module (e.g. `module=bank`) or action (e.g. `action=/cosmos.bank.v1beta1.Msg/Send`)). -- A list of `attributes`, which are key-value pairs that give more information about - the categorized `event`. - +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/events.go#L51-L56 +- A `type` to categorize the Event at a high-level; for example, the SDK uses the `"message"` type to filter Events by `Msg`s. +- A list of `attributes` are key-value pairs that give more information about the categorized Event. For example, for the `"message"` type, we can filter Events by key-value pairs using `message.action={some_action}`, `message.module={some_module}` or `message.sender={some_sender}`. + +::: tip +To parse the attribute values as strings, make sure to add `'` (single quotes) around each attribute value. +::: + +Events, the `type` and `attributes` are defined on a **per-module basis** in the module's +`/types/events.go` file, and triggered from the module's [`Msg` service](../building-modules/msg-services.md) +by using the [`EventManager`](#eventmanager). In addition, each module documents its Events under +`spec/xx_events.md`. Events are returned to the underlying consensus engine in the response of the following ABCI messages: @@ -31,28 +39,35 @@ Events are returned to the underlying consensus engine in the response of the fo - [`CheckTx`](./baseapp.md#checktx) - [`DeliverTx`](./baseapp.md#delivertx) -Events, the `type` and `attributes`, are defined on a **per-module basis** in the module's -`/types/events.go` file, and triggered from the module's [`Msg` service](../building-modules/msg-services.md) -via the [`EventManager`](#eventmanager). In addition, each module documents its events under -`spec/xx_events.md`. +### Examples + +The following examples show how to query Events using the SDK. + +| Event | Description | +| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tx.height=23` | Query all transactions at height 23 | +| `message.action='/cosmos.bank.v1beta1.Msg/Send'` | Query all transactions containing a x/bank `Send` [Service `Msg`](../building-modules/msg-services.md). Note the `'`s around the value. | +| `message.action='send'` | Query all transactions containing a x/bank `Send` [legacy `Msg`](../building-modules/msg-services.md#legacy-amino-msgs). Note the `'`s around the value. | +| `message.module='bank'` | Query all transactions containing messages from the x/bank module. Note the `'`s around the value. | +| `create_validator.validator='cosmosval1...'` | x/staking-specific Event, see [x/staking SPEC](../../../cosmos-sdk/x/staking/spec/07_events.md). | ## EventManager -In Cosmos SDK applications, events are managed by an abstraction called the `EventManager`. -Internally, the `EventManager` tracks a list of `Events` for the entire execution flow of a +In Cosmos SDK applications, Events are managed by an abstraction called the `EventManager`. +Internally, the `EventManager` tracks a list of Events for the entire execution flow of a transaction or `BeginBlock`/`EndBlock`. -+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/events.go#L16-L20 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L17-L25 -The `EventManager` comes with a set of useful methods to manage events. Among them, the one that is -used the most by module and application developers is the `EmitEvent` method, which tracks -an `event` in the `EventManager`. +The `EventManager` comes with a set of useful methods to manage Events. The method +that is used most by module and application developers is `EmitEvent` that tracks +an Event in the `EventManager`. -+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/events.go#L29-L31 ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L33-L37 -Module developers should handle event emission via the `EventManager#EmitEvent` in each message +Module developers should handle Event emission via the `EventManager#EmitEvent` in each message `Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via -the [`Context`](./context.md), where event emission generally follows this pattern: +the [`Context`](./context.md), where Event emission generally follows this pattern: ```go ctx.EventManager().EmitEvent( @@ -60,7 +75,8 @@ ctx.EventManager().EmitEvent( ) ``` -Module's `handler` function should also set a new `EventManager` to the `context` to isolate emitted events per `message`: +Module's `handler` function should also set a new `EventManager` to the `context` to isolate emitted Events per `message`: + ```go func NewHandler(keeper Keeper) sdk.Handler { return func(ctx sdk.Context, msg sdk.Msg) (*sdk.Result, error) { @@ -69,48 +85,53 @@ func NewHandler(keeper Keeper) sdk.Handler { ``` See the [`Msg` services](../building-modules/msg-services.md) concept doc for a more detailed -view on how to typically implement `Events` and use the `EventManager` in modules. +view on how to typically implement Events and use the `EventManager` in modules. ## Subscribing to Events -It is possible to subscribe to `Events` via Tendermint's [Websocket](https://tendermint.com/docs/app-dev/subscribing-to-events-via-websocket.html#subscribing-to-events-via-websocket). -This is done by calling the `subscribe` RPC method via Websocket: +You can use Tendermint's [Websocket](https://docs.tendermint.com/master/tendermint-core/subscription.html#subscribing-to-events-via-websocket) to subscribe to Events by calling the `subscribe` RPC method: ```json { - "jsonrpc": "2.0", - "method": "subscribe", - "id": "0", - "params": { - "query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'" - } + "jsonrpc": "2.0", + "method": "subscribe", + "id": "0", + "params": { + "query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'" + } } ``` The main `eventCategory` you can subscribe to are: -- `NewBlock`: Contains `events` triggered during `BeginBlock` and `EndBlock`. -- `Tx`: Contains `events` triggered during `DeliverTx` (i.e. transaction processing). +- `NewBlock`: Contains Events triggered during `BeginBlock` and `EndBlock`. +- `Tx`: Contains Events triggered during `DeliverTx` (i.e. transaction processing). - `ValidatorSetUpdates`: Contains validator set updates for the block. -These events are triggered from the `state` package after a block is committed. You can get the -full list of `event` categories [here](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants). +These Events are triggered from the `state` package after a block is committed. You can get the +full list of Event categories [on the Tendermint Godoc page](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants). -The `type` and `attribute` value of the `query` allow you to filter the specific `event` you are looking for. For example, a `transfer` transaction triggers an `event` of type `Transfer` and has `Recipient` and `Sender` as `attributes` (as defined in the [`events` file of the `bank` module](https://github.com/cosmos/cosmos-sdk/blob/master/x/bank/types/events.go)). Subscribing to this `event` would be done like so: +The `type` and `attribute` value of the `query` allow you to filter the specific Event you are looking for. For example, a `transfer` transaction triggers an Event of type `Transfer` and has `Recipient` and `Sender` as `attributes` (as defined in the [`events.go` file of the `bank` module](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/bank/types/events.go)). Subscribing to this Event would be done like so: ```json { - "jsonrpc": "2.0", - "method": "subscribe", - "id": "0", - "params": { - "query": "tm.event='Tx' AND transfer.sender='senderAddress'" - } + "jsonrpc": "2.0", + "method": "subscribe", + "id": "0", + "params": { + "query": "tm.event='Tx' AND transfer.sender='senderAddress'" + } } ``` where `senderAddress` is an address following the [`AccAddress`](../basics/accounts.md#addresses) format. +## Typed Events (coming soon) + +As previously described, Events are defined on a per-module basis. It is the responsibility of the module developer to define Event types and Event attributes. Except in the `spec/XX_events.md` file, these Event types and attributes are unfortunately not easily discoverable, so the SDK proposes to use Protobuf-defined [Typed Events](../architecture/adr-032-typed-events.md) for emitting and querying Events. + +The Typed Events proposal has not yet been fully implemented. Documentation is not yet available. + ## Next {hide} Learn about SDK [telemetry](./telemetry.md) {hide} diff --git a/docs/core/store.md b/docs/core/store.md index 5de83b8269c..a469b77ebfd 100644 --- a/docs/core/store.md +++ b/docs/core/store.md @@ -56,11 +56,11 @@ The Cosmos SDK comes with a large set of stores to persist the state of applicat ### Store Interface -At its very core, a Cosmos SDK `store` is an object that holds a `CacheWrapper` and has a `GetStoreType()` method: +At its very core, a Cosmos SDK `store` is an object that holds a `CacheWrapper` and has a `GetStoreType()` method: +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L15-L18 -The `GetStoreType` is a simple method that returns the type of store, whereas a `CacheWrapper` is a simple interface that implements store read caching and write branching through `Write` method: +The `GetStoreType` is a simple method that returns the type of store, whereas a `CacheWrapper` is a simple interface that implements store read caching and write branching through `Write` method: +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L240-L264 @@ -104,7 +104,7 @@ The `rootMulti.Store` is a base-layer multistore built around a `db` on top of w ### CacheMultiStore -Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](https://github.com/cosmos/cosmos-sdk/blob/master/store/cachemulti/store.go) is used. +Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/store/cachemulti/store.go) is used. +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachemulti/store.go#L17-L28