From 9769e2404ec62cb8cdf12a7931bd0b6b818a0b40 Mon Sep 17 00:00:00 2001 From: Marko Date: Fri, 9 Jun 2023 13:06:44 +0200 Subject: [PATCH] chore: changelog & upgrading documentation for ABCI++ (#16315) Co-authored-by: Aleksandr Bezobchuk Co-authored-by: Aleksandr Bezobchuk Co-authored-by: Julien Robert --- CHANGELOG.md | 9 ++- UPGRADING.md | 31 ++++++++- docs/docs/building-apps/04-vote-extensions.md | 67 +++++++++++++++++++ 3 files changed, 105 insertions(+), 2 deletions(-) create mode 100644 docs/docs/building-apps/04-vote-extensions.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e0848b427eec..da300d44e26c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -254,6 +254,11 @@ Ref: https://keepachangelog.com/en/1.0.0/ * this finalizes the gov collections migration * Removed: keeper `InsertActiveProposalsQueue`, `RemoveActiveProposalsQueue`, `InsertInactiveProposalsQueue`, `RemoveInactiveProposalsQueue`, `IterateInactiveProposalsQueue`, `IterateActiveProposalsQueue`, `ActiveProposalsQueueIterator`, `InactiveProposalsQueueIterator` * Remove: types all the key related functions +* (baseapp) [#15519](https://github.com/cosmos/cosmos-sdk/pull/15519/files) BeginBlock and EndBlock are now internal to baseapp. For testing, user must call `FinalizeBlock`. BeginBlock and EndBlock calls are internal to Baseapp. +* (baseapp) [#15519](https://github.com/cosmos/cosmos-sdk/pull/15519/files) Writing of state to the multistore was moved to FinalizeBlock. Commit still handles the commiting values to disk. +* (baseapp) [#15519](https://github.com/cosmos/cosmos-sdk/pull/15519/files) `runTxMode`s were renamed to `execMode`. ModeDeliver as changed to `ModeFinalize` and a new `ModeVoteExtension` was added for vote extensions. +* (baseapp) [#15519](https://github.com/cosmos/cosmos-sdk/pull/15519/files) All calls to ABCI methods now accept a pointer of the abci request and response types +* (baseapp) [#15519](https://github.com/cosmos/cosmos-sdk/pull/15519/files) Calls to BeginBlock and EndBlock have been replaced with core api beginblock & endblock. * (x/crisis) [#16328](https://github.com/cosmos/cosmos-sdk/pull/16328) Use collections for state management: * Removed: keeper `GetConstantFee`, `SetConstantFee` * (x/mint) [#16329](https://github.com/cosmos/cosmos-sdk/pull/16329) Use collections for state management: @@ -269,6 +274,8 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (grpc-web) [#14652](https://github.com/cosmos/cosmos-sdk/pull/14652) Use same port for gRPC-Web and the API server. * (abci) [#15845](https://github.com/cosmos/cosmos-sdk/pull/15845) Add `msg_index` to all event attributes to associate events and messages * (abci) [#15845](https://github.com/cosmos/cosmos-sdk/pull/15845) Remove duplicating events in `logs` +* (baseapp) [#15519](https://github.com/cosmos/cosmos-sdk/pull/15519/files) BeginBlock & EndBlock events have begin or endblock in the events in order to identify which stage they are emitted from since they are returned to comet as FinalizeBlock events, +* (store/streaming) [#15519](https://github.com/cosmos/cosmos-sdk/pull/15519/files) State Streaming removed emitting of beginblock, endblock and delivertx in favour of emitting FinalizeBlock. ### CLI Breaking Changes @@ -285,7 +292,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (store) [#16449](https://github.com/cosmos/cosmos-sdk/pull/16449) Fix StateSync Restore by excluding memory store * (cli) [#16312](https://github.com/cosmos/cosmos-sdk/pull/16312) Allow any addresses in `client.ValidatePromptAddress`. * (baseapp) [#16259](https://github.com/cosmos/cosmos-sdk/pull/16259) Ensure the `Context` block height is correct after `InitChain` and prior to the second block. -* (x/staking) [#16043](https://github.com/cosmos/cosmos-sdk/pull/16043) Call `AfterUnbondingInitiated` hook for new unbonding entries only and fix `UnbondingDelegation` entries handling +* (x/staking) [#16043](https://github.com/cosmos/cosmos-sdk/pull/16043) Call `AfterUnbondingInitiated` hook for new unbonding entries only and fix `UnbondingDelegation` entries handling. This is a behavior change compared to Cosmos SDK v0.47.x, now the hook is called only for new unbonding entries. * (types) [#16010](https://github.com/cosmos/cosmos-sdk/pull/16010) Let `module.CoreAppModuleBasicAdaptor` fallback to legacy genesis handling. * (x/group) [#16017](https://github.com/cosmos/cosmos-sdk/pull/16017) Correctly apply account number in group v2 migration. * (types) [#15691](https://github.com/cosmos/cosmos-sdk/pull/15691) Make `Coin.Validate()` check that `.Amount` is not nil. diff --git a/UPGRADING.md b/UPGRADING.md index 83e2d3cb78a4..0d025db81303 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -29,6 +29,28 @@ Additionally, the SDK is starting its abstraction from CometBFT Go types thoroug * The usage of CometBFT have been replaced to use the Cosmos SDK logger interface (`cosmossdk.io/log.Logger`). * The usage of `github.com/cometbft/cometbft/libs/bytes.HexByte` have been replaced by `[]byte`. +### BaseApp + +All ABCI methods now accept a pointer to the request and response types defined +by CometBFT. In addition, they also return errors. An ABCI method should only +return errors in cases where a catastrophic failure has occurred and the application +should halt. However, this is abstracted away from the application developer. Any +handler that an application can define or set that returns an error, will gracefully +by handled by `BaseApp` on behalf of the application. + +BaseApp calls of `BeginBlock` & `Endblock` are now private but are still exposed +to the application to define via the `Manager` type. `FinalizeBlock` is public +and should be used in order to test and run operations. This means that although +`BeginBlock` & `Endblock` no longer exist in the ABCI interface, they are automatically +called by `BaseApp` during `FinalizeBlock`. Specifically, the order of operations +is `BeginBlock` -> `DeliverTx` (for all txs) -> `EndBlock`. + +ABCI++ 2.0 also brings `ExtendVote` and `VerifyVoteExtension` ABCI methods. These +methods allow applications to extend and verify pre-commit votes. The Cosmos SDK +allows an application to define handlers for these methods via `ExtendVoteHandler` +and `VerifyVoteExtensionHandler` respectively. Please see [here](https://docs.cosmos.network/v0.50/building-apps/vote-extensions) +for more info. + ### Configuration A new tool have been created for migrating configuration of the SDK. Use the following command to migrate your configuration: @@ -41,7 +63,14 @@ More information about [confix](https://docs.cosmos.network/main/tooling/confix) #### Events -The log section of abci.TxResult is not populated in the case of successful msg(s) execution. Instead a new attribute is added to all messages indicating the `msg_index` which identifies which events and attributes relate the same transaction +The log section of `abci.TxResult` is not populated in the case of successful +msg(s) execution. Instead a new attribute is added to all messages indicating +the `msg_index` which identifies which events and attributes relate the same +transaction. + +`BeginBlock` & `EndBlock` Events are now emitted through `FinalizeBlock` but have +an added attribute, `mode=BeginBlock|EndBlock`, to identify if the event belongs +to `BeginBlock` or `EndBlock`. #### gRPC-Web diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/building-apps/04-vote-extensions.md new file mode 100644 index 000000000000..a47102a6674f --- /dev/null +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 1 +--- + +# Vote Extensions + +:::note Synopsis +This sections describes how the application can define and use vote extensions +defined in ABCI++. +::: + +## Extend Vote + +ABCI++ allows an application to extend a pre-commit vote with arbitrary data. This +process does NOT have be deterministic and the data returned can be unique to the +validator process. The Cosmos SDK defines `baseapp.ExtendVoteHandler`: + +```go +type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) +``` + +An application can set this handler in `app.go` via the `baseapp.SetExtendVoteHandler` +`BaseApp` option function. The `sdk.ExtendVoteHandler`, if defined, is called during +the `ExtendVote` ABCI method. Note, if an application decides to implement +`baseapp.ExtendVoteHandler`, it MUST return a non-nil `VoteExtension`. However, the vote +extension can be empty. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#extendvote) +for more details. + +There are many decentralized censorship-resistant use cases for vote extensions. +For example, a validator may want to submit prices for a price oracle or encryption +shares for an encrypted transaction mempool. Note, an application should be careful +to consider the size of the vote extensions as they could increase latency in block +production. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/docs/qa/CometBFT-QA-38.md#vote-extensions-testbed) +for more details. + +## Verify Vote Extension + +Similar to extending a vote, an application can also verify vote extensions from +other validators when validating their pre-commits. For a given vote extension, +this process MUST be deterministic. The Cosmos SDK defines `sdk.VerifyVoteExtensionHandler`: + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/types/abci.go#L26-L27 +``` + +An application can set this handler in `app.go` via the `baseapp.SetVerifyVoteExtensionHandler` +`BaseApp` option function. The `sdk.VerifyVoteExtensionHandler`, if defined, is called +during the `VerifyVoteExtension` ABCI method. If an application defines a vote +extension handler, it should also define a verification handler. Note, not all +validators will share the same view of what vote extensions they verify depending +on how votes are propagated. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#verifyvoteextension) +for more details. + +## Vote Extension Propagation + +The agreed upon vote extensions at height `H` are provided to the proposing validator +at height `H+1` during `PrepareProposal`. As a result, the vote extensions are +not natively provided or exposed to the remaining validators during `ProcessProposal`. +As a result, if an application requires that the agreed upon vote extensions from +height `H` are available to all validators at `H+1`, the application must propagate +these vote extensions manually in the block proposal itself. This can be done by +"injecting" them into the block proposal, since the `Txs` field in `PrepareProposal` +is just a slice of byte slices. + +`FinalizeBlock` will ignore any byte slice that doesn't implement an `sdk.Tx` so +any injected vote extensions will safely be ignored in `FinalizeBlock`. For more +details on propagation, see the [ABCI++ 2.0 ADR](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-064-abci-2.0.md#vote-extension-propagation--verification).