From 1f900ccef87b3454ef0d2aa62ae30dd3cc4f1a9e Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Fri, 26 May 2023 15:47:05 +0200 Subject: [PATCH 01/17] changelog for abci++ --- CHANGELOG.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cced6302e780..b6012bebca06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -223,24 +223,29 @@ Ref: https://keepachangelog.com/en/1.0.0/ * The field `OperationMsg.Msg` is now of type `[]byte` instead of `json.RawMessage`. * (cli) [#16209](https://github.com/cosmos/cosmos-sdk/pull/16209) Add API `StartCmdWithOptions` to create customized start command. * (x/auth) [#16016](https://github.com/cosmos/cosmos-sdk/pull/16016) Use collections for accounts state management: - - removed: keeper `HasAccountByID`, `AccountAddressByID`, `SetParams + * removed: keeper `HasAccountByID`, `AccountAddressByID`, `SetParams * (x/distribution) [#16211](https://github.com/cosmos/cosmos-sdk/pull/16211) Use collections for params state management. * [#15284](https://github.com/cosmos/cosmos-sdk/pull/15284) - * `sdk.Msg.GetSigners` was deprecated and is no longer supported. Use the `cosmos.msg.v1.signer` protobuf annotation instead. - * `sdk.Tx` now requires a new method `GetMsgsV2()`. - * `types/tx.Tx` no longer implements `sdk.Tx`. - * `TxConfig` has a new method `SigningContext() *signing.Context`. - * `AccountKeeper` now has an `AddressCodec() address.Codec` method and the expected `AccountKeeper` for `x/auth/ante` expects this method. - * `SigVerifiableTx.GetSigners()` now returns `([][]byte, error)` instead of `[]sdk.AccAddress`. + * `sdk.Msg.GetSigners` was deprecated and is no longer supported. Use the `cosmos.msg.v1.signer` protobuf annotation instead. + * `sdk.Tx` now requires a new method `GetMsgsV2()`. + * `types/tx.Tx` no longer implements `sdk.Tx`. + * `TxConfig` has a new method `SigningContext() *signing.Context`. + * `AccountKeeper` now has an `AddressCodec() address.Codec` method and the expected `AccountKeeper` for `x/auth/ante` expects this method. + * `SigVerifiableTx.GetSigners()` now returns `([][]byte, error)` instead of `[]sdk.AccAddress`. * (x/authx) [#15284](https://github.com/cosmos/cosmos-sdk/pull/15284) `NewKeeper` now requires `codec.Codec`. * (x/gov) [#15284](https://github.com/cosmos/cosmos-sdk/pull/15284) `NewKeeper` now requires `codec.Codec`. * (x/distribution) [](https://github.com/cosmos/cosmos-sdk/pull/16302) Use collections for FeePool state management. - * removed: keeper `GetFeePool`, `SetFeePool`, `GetFeePoolCommunityCoins` + * removed: keeper `GetFeePool`, `SetFeePool`, `GetFeePoolCommunityCoins` * (x/gov) [#16268](https://github.com/cosmos/cosmos-sdk/pull/16268) Use collections for proposal state management (part 2): - * this finalizes the gov collections migration - * Removed: keeper `InsertActiveProposalsQueue`, `RemoveActiveProposalsQueue`, `InsertInactiveProposalsQueue`, `RemoveInactiveProposalsQueue`, `IterateInactiveProposalsQueue`, `IterateActiveProposalsQueue`, `ActiveProposalsQueueIterator`, `InactiveProposalsQueueIterator` - * Remove: types all the key related functions + * 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 + ### Client Breaking Changes @@ -248,6 +253,7 @@ 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, ### CLI Breaking Changes From 5a05f7d4c737472e1559dc87613207adb6d06867 Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Fri, 26 May 2023 16:54:21 +0200 Subject: [PATCH 02/17] cahngelog and upgrading.md changes --- CHANGELOG.md | 2 ++ UPGRADING.md | 8 +++++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b6012bebca06..748cd270d2c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -245,6 +245,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (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. ### Client Breaking Changes @@ -254,6 +255,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (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 diff --git a/UPGRADING.md b/UPGRADING.md index d55480a3e2ad..d43446873861 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -27,6 +27,10 @@ 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 calls accept a pointer to the request and response types defined by Comet. + ### Configuration A new tool have been created for migrating configuration of the SDK. Use the following command to migrate your configuration: @@ -41,6 +45,8 @@ More information about [confix](https://docs.cosmos.network/main/tooling/confix) 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 to identify if it belongs to Begin or EndBlock + #### gRPC-Web gRPC-Web is now listening to the same address as the gRPC Gateway API server (default: `localhost:1317`). @@ -53,7 +59,7 @@ ClevelDB, BoltDB and BadgerDB are not supported anymore. To migrate from a unsup ### Protobuf -The SDK is in the process of removing all `gogoproto` annotations. +The SDK is in the process of removing all `gogoproto` annotations. It is recommended to not introduce new types and add gogoproto annotations #### Stringer From 5570ac96da8387995460a970aca219a72eec3e49 Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Sun, 28 May 2023 23:31:09 +0200 Subject: [PATCH 03/17] add more upgrading.md info --- UPGRADING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/UPGRADING.md b/UPGRADING.md index d43446873861..c6e43736f3b0 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -31,6 +31,10 @@ Additionally, the SDK is starting its abstraction from CometBFT Go types thoroug All ABCI calls accept a pointer to the request and response types defined by Comet. +Baseapp calls of BeginBlock & Endblock are now private. FinalizeBlock is public and should be used in order to test and run operations. + +VoteExtensions were added and can be used in a variety of locations. Please see [TODO DOCS LINK FOR VOTE EXTENSIONS]() + ### Configuration A new tool have been created for migrating configuration of the SDK. Use the following command to migrate your configuration: From a99f37b31bd40621524b632effc36c281051e78a Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Thu, 8 Jun 2023 12:10:10 +0200 Subject: [PATCH 04/17] remove extra --- CHANGELOG.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb236e6092e6..5fec9958c0fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -252,9 +252,6 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (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. - * this finalizes the gov collections migration - * Removed: keeper `InsertActiveProposalsQueue`, `RemoveActiveProposalsQueue`, `InsertInactiveProposalsQueue`, `RemoveInactiveProposalsQueue`, `IterateInactiveProposalsQueue`, `IterateActiveProposalsQueue`, `ActiveProposalsQueueIterator`, `InactiveProposalsQueueIterator` - * Remove: types all the key related functions * (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: From 71ba91a40f36416c65eb7a6ef07a3e8a9d2e70aa Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Thu, 8 Jun 2023 15:33:24 +0200 Subject: [PATCH 05/17] remove extra --- UPGRADING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index af88e72c9db0..0c197bfff313 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -65,8 +65,6 @@ ClevelDB, BoltDB and BadgerDB are not supported anymore. To migrate from a unsup ### Protobuf -The SDK is in the process of removing all `gogoproto` annotations. It is recommended to not introduce new types and add gogoproto annotations - With the deprecation of the amino JSON codec defined in [cosmos/gogoproto](https://github.com/cosmos/gogoproto) in favor of the protoreflect powered x/tx/aminojson codec, module developers are encouraged verify that their messages have the correct protobuf annotations to deterministically produce identical output from both codecs. For core SDK types equivalence is asserted by generative testing of [SignableTypes](https://github.com/cosmos/cosmos-sdk/blob/76f0d101530ed78befc95506ab473c771d0d8a8c/tests/integration/rapidgen/rapidgen.go#L106) in [TestAminoJSON_Equivalence](https://github.com/cosmos/cosmos-sdk/blob/76f0d101530ed78befc95506ab473c771d0d8a8c/tests/integration/aminojson/aminojson_test.go#L90). From d6b7b8cde37c4b25c53eedccac9052a5b5f3a60d Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 10:07:59 -0400 Subject: [PATCH 06/17] updates --- UPGRADING.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 0c197bfff313..a6246cf53a2f 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -29,7 +29,7 @@ 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 +### BaseApp All ABCI calls accept a pointer to the request and response types defined by Comet. @@ -49,9 +49,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 to identify if it belongs to Begin or EndBlock +`BeginBlock` & `EndBlock` Events are now emitted through `FinalizeBlock` but have +an added attribute, `mode=BeginBlock|EndBlock`, to identify if it belongs to +`BeginBlock` or `EndBlock`. #### gRPC-Web From de000d4b82240d5de60f1a432f50d49fc75cc492 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 10:30:13 -0400 Subject: [PATCH 07/17] updates --- UPGRADING.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index a6246cf53a2f..683e09614446 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -31,11 +31,18 @@ Additionally, the SDK is starting its abstraction from CometBFT Go types thoroug ### BaseApp -All ABCI calls accept a pointer to the request and response types defined by Comet. - -Baseapp calls of BeginBlock & Endblock are now private. FinalizeBlock is public and should be used in order to test and run operations. - -VoteExtensions were added and can be used in a variety of locations. Please see [TODO DOCS LINK FOR VOTE EXTENSIONS]() +All ABCI calls now accept a pointer to the request and response types defined by +CometBFT. 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 [TODO_LINK]() for more info. ### Configuration @@ -55,8 +62,8 @@ 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 it belongs to -`BeginBlock` or `EndBlock`. +an added attribute, `mode=BeginBlock|EndBlock`, to identify if the event belongs +to `BeginBlock` or `EndBlock`. #### gRPC-Web From 972f1ee42f02414189e218b1d6399d3891ca2dc6 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 10:34:28 -0400 Subject: [PATCH 08/17] updates --- UPGRADING.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 683e09614446..7fcdd15dd7b5 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -31,13 +31,17 @@ Additionally, the SDK is starting its abstraction from CometBFT Go types thoroug ### BaseApp -All ABCI calls now accept a pointer to the request and response types defined by -CometBFT. 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`. +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. + +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 From 937da434137656b98029a859efbc5ebf4a020c7a Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 10:39:44 -0400 Subject: [PATCH 09/17] updates --- UPGRADING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/UPGRADING.md b/UPGRADING.md index 7fcdd15dd7b5..bba05732c12d 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -34,7 +34,9 @@ Additionally, the SDK is starting its abstraction from CometBFT Go types thoroug 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. +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 From 23af034ee759ed5cc63bc1a96d652ad8b3d1da63 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 10:44:39 -0400 Subject: [PATCH 10/17] updates --- UPGRADING.md | 3 ++- docs/docs/building-apps/01-app-go-v2.md | 2 +- docs/docs/building-apps/02-app-mempool.md | 2 +- docs/docs/building-apps/04-vote-extensions.md | 14 ++++++++++++++ 4 files changed, 18 insertions(+), 3 deletions(-) create mode 100644 docs/docs/building-apps/04-vote-extensions.md diff --git a/UPGRADING.md b/UPGRADING.md index bba05732c12d..d470038029d9 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -48,7 +48,8 @@ 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 [TODO_LINK]() for more info. +and `VerifyVoteExtensionHandler` respectively. Please see [here](./docs/docs/building-apps/04-vote-extensions.md) +for more info. ### Configuration diff --git a/docs/docs/building-apps/01-app-go-v2.md b/docs/docs/building-apps/01-app-go-v2.md index d22b9b040216..ab83eeff7bed 100644 --- a/docs/docs/building-apps/01-app-go-v2.md +++ b/docs/docs/building-apps/01-app-go-v2.md @@ -13,7 +13,7 @@ Learn more about the rationale of App Wiring in [ADR-057](../architecture/adr-05 :::note -### Pre-requisite Readings +## Pre-requisite Readings * [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md) * [Depinject Documentation](../packages/01-depinject.md) diff --git a/docs/docs/building-apps/02-app-mempool.md b/docs/docs/building-apps/02-app-mempool.md index a8083f76f42b..fdeaad912510 100644 --- a/docs/docs/building-apps/02-app-mempool.md +++ b/docs/docs/building-apps/02-app-mempool.md @@ -15,7 +15,7 @@ Notably it introduces the `PrepareProposal` and `ProcessProposal` steps of ABCI+ :::note -### Pre-requisite Readings +## Pre-requisite Readings * [BaseApp](../core/00-baseapp.md) 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..00605caa2809 --- /dev/null +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -0,0 +1,14 @@ +--- +sidebar_position: 1 +--- + +# Vote Extensions + +:::note Synopsis +This sections describes how the application can define and use vote extensions +defined in ABCI++. +::: + +## Extend Vote + +## Verify Vote Extension From 39a0f9666700912094b9ef1cbd0110a0d95343bd Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 11:08:10 -0400 Subject: [PATCH 11/17] updates --- docs/docs/building-apps/04-vote-extensions.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/building-apps/04-vote-extensions.md index 00605caa2809..70e507cc71e5 100644 --- a/docs/docs/building-apps/04-vote-extensions.md +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -11,4 +11,26 @@ 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 `ExtendVoteHandler`: + +```go +type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) +``` + +An application can set this handler in `app.go` via the `SetExtendVoteHandler` +`BaseApp` option function. The `ExtendVoteHandler`, if defined, is called during +the `ExtendVote` ABCI method. Note, if an application decides to implement +`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%2B%2B_methods.md) +for more details on these methods. + +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 From ec3d0eec4df8b766bece133353efc43521643945 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 11:14:20 -0400 Subject: [PATCH 12/17] updates --- docs/docs/building-apps/04-vote-extensions.md | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/building-apps/04-vote-extensions.md index 70e507cc71e5..e981e96ebe32 100644 --- a/docs/docs/building-apps/04-vote-extensions.md +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -23,8 +23,8 @@ An application can set this handler in `app.go` via the `SetExtendVoteHandler` `BaseApp` option function. The `ExtendVoteHandler`, if defined, is called during the `ExtendVote` ABCI method. Note, if an application decides to implement `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%2B%2B_methods.md) -for more details on these methods. +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 @@ -34,3 +34,21 @@ production. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/doc 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 `VerifyVoteExtensionHandler`: + +```go +type VerifyVoteExtensionHandler func(Context, *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error) +``` + +An application can set this handler in `app.go` via the `SetVerifyVoteExtensionHandler` +`BaseApp` option function. The `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 From 57c39de5764ed466d7b95f7705dcf51923e4c9cf Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 14:43:58 -0400 Subject: [PATCH 13/17] updates --- docs/docs/building-apps/04-vote-extensions.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/building-apps/04-vote-extensions.md index e981e96ebe32..d166b4c939a6 100644 --- a/docs/docs/building-apps/04-vote-extensions.md +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -52,3 +52,16 @@ on how votes are propagated. See [here](https://github.com/cometbft/cometbft/blo 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). From 86fe86d23f37bfaa9527731dd8646d3b6d3f64b5 Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 18:35:00 -0400 Subject: [PATCH 14/17] Update docs/docs/building-apps/04-vote-extensions.md --- docs/docs/building-apps/04-vote-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/building-apps/04-vote-extensions.md index d166b4c939a6..a6e896f21044 100644 --- a/docs/docs/building-apps/04-vote-extensions.md +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -13,7 +13,7 @@ defined in ABCI++. 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 `ExtendVoteHandler`: +validator process. The Cosmos SDK defines `baseapp.ExtendVoteHandler`: ```go type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) From 1e5a1e79a788daff3b55286579b6c121fff3f52d Mon Sep 17 00:00:00 2001 From: Aleksandr Bezobchuk Date: Thu, 8 Jun 2023 18:36:40 -0400 Subject: [PATCH 15/17] updates --- docs/docs/building-apps/04-vote-extensions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/building-apps/04-vote-extensions.md index a6e896f21044..36b4d048107b 100644 --- a/docs/docs/building-apps/04-vote-extensions.md +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -19,10 +19,10 @@ validator process. The Cosmos SDK defines `baseapp.ExtendVoteHandler`: type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) ``` -An application can set this handler in `app.go` via the `SetExtendVoteHandler` -`BaseApp` option function. The `ExtendVoteHandler`, if defined, is called during +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 -`ExtendVoteHandler`, it MUST return a non-nil `VoteExtension`. However, the vote +`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. @@ -37,14 +37,14 @@ for more details. 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 `VerifyVoteExtensionHandler`: +this process MUST be deterministic. The Cosmos SDK defines `sdk.VerifyVoteExtensionHandler`: ```go type VerifyVoteExtensionHandler func(Context, *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error) ``` -An application can set this handler in `app.go` via the `SetVerifyVoteExtensionHandler` -`BaseApp` option function. The `VerifyVoteExtensionHandler`, if defined, is called +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 From 443635bb1c5c748f6331ebabb21e5dcb507be0ab Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Fri, 9 Jun 2023 01:07:37 +0200 Subject: [PATCH 16/17] updates --- UPGRADING.md | 2 +- docs/docs/building-apps/01-app-go-v2.md | 2 +- docs/docs/building-apps/02-app-mempool.md | 2 +- docs/docs/building-apps/04-vote-extensions.md | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index d470038029d9..0d025db81303 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -48,7 +48,7 @@ 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](./docs/docs/building-apps/04-vote-extensions.md) +and `VerifyVoteExtensionHandler` respectively. Please see [here](https://docs.cosmos.network/v0.50/building-apps/vote-extensions) for more info. ### Configuration diff --git a/docs/docs/building-apps/01-app-go-v2.md b/docs/docs/building-apps/01-app-go-v2.md index ab83eeff7bed..d22b9b040216 100644 --- a/docs/docs/building-apps/01-app-go-v2.md +++ b/docs/docs/building-apps/01-app-go-v2.md @@ -13,7 +13,7 @@ Learn more about the rationale of App Wiring in [ADR-057](../architecture/adr-05 :::note -## Pre-requisite Readings +### Pre-requisite Readings * [ADR 057: App Wiring](../architecture/adr-057-app-wiring.md) * [Depinject Documentation](../packages/01-depinject.md) diff --git a/docs/docs/building-apps/02-app-mempool.md b/docs/docs/building-apps/02-app-mempool.md index fdeaad912510..a8083f76f42b 100644 --- a/docs/docs/building-apps/02-app-mempool.md +++ b/docs/docs/building-apps/02-app-mempool.md @@ -15,7 +15,7 @@ Notably it introduces the `PrepareProposal` and `ProcessProposal` steps of ABCI+ :::note -## Pre-requisite Readings +### Pre-requisite Readings * [BaseApp](../core/00-baseapp.md) diff --git a/docs/docs/building-apps/04-vote-extensions.md b/docs/docs/building-apps/04-vote-extensions.md index 36b4d048107b..a47102a6674f 100644 --- a/docs/docs/building-apps/04-vote-extensions.md +++ b/docs/docs/building-apps/04-vote-extensions.md @@ -39,8 +39,8 @@ 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 -type VerifyVoteExtensionHandler func(Context, *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error) +```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` From 11d95b80c17cb272fc563c0ea37e05ed624d5803 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Fri, 9 Jun 2023 01:09:27 +0200 Subject: [PATCH 17/17] updates --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a43a6aa4a111..3d5ec8291f5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -287,7 +287,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.