From fcd976fe8c6c0cdd3363e39b0d2bc9489dee7ca7 Mon Sep 17 00:00:00 2001 From: samricotta <37125168+samricotta@users.noreply.github.com> Date: Wed, 31 Jan 2024 14:44:29 +0100 Subject: [PATCH] updates from adi Co-Authored-By: Adi Seredinschi --- docs/build/abci/00-introduction.md | 8 ++++---- docs/build/abci/01-prepare-proposal.md | 4 ++-- docs/build/abci/02-process-proposal.md | 10 +++++----- docs/build/abci/03-vote-extensions.md | 3 +-- 4 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/build/abci/00-introduction.md b/docs/build/abci/00-introduction.md index f0ff1d9938e7..5c82440dde07 100644 --- a/docs/build/abci/00-introduction.md +++ b/docs/build/abci/00-introduction.md @@ -2,9 +2,9 @@ ## What is ABCI? -ABCI, Application Blockchain Interface is the interface between CometBFT and the application, more information about ABCI can be found [here](https://docs.cometbft.com/v0.38/spec/abci/). Within the release of ABCI 2.0 for the 0.38 CometBFT release there were additional methods introduced. +ABCI, Application Blockchain Interface is the interface between CometBFT and the application. More information about ABCI can be found in the specs [here](https://docs.cometbft.com/v0.38/spec/abci/). Within the release of ABCI 2.0 for the 0.38 CometBFT release there were additional methods introduced. -The 5 methods introduced during ABCI 2.0 are: +The 5 methods introduced during ABCI 2.0 (compared to ABCI v0) are: * `PrepareProposal` * `ProcessProposal` @@ -17,7 +17,7 @@ The 5 methods introduced during ABCI 2.0 are: ## PrepareProposal -Based on their voting power, CometBFT chooses a block proposer and calls `PrepareProposal` on the block proposer's application (Cosmos SDK). The selected block proposer is responsible for collecting outstanding transactions from the mempool, adhering to the application's specifications. The application can enforce custom transaction ordering and incorporate additional transactions, potentially generated from vote extensions in the previous block. +Based on validator voting power, CometBFT chooses a block proposer and calls `PrepareProposal` on the block proposer's application (Cosmos SDK). The selected block proposer is responsible for collecting outstanding transactions from the mempool, adhering to the application's specifications. The application can enforce custom transaction ordering and incorporate additional transactions, potentially generated from vote extensions in the previous block. To perform this manipulation on the application side, a custom handler must be implemented. By default, the Cosmos SDK provides `PrepareProposalHandler`, used in conjunction with an application specific mempool. A custom handler can be written by application developer, if a noop handler provided, all transactions are considered valid. Please see [this](https://github.com/fatal-fruit/abci-workshop) tutorial for more information on custom handlers. @@ -48,4 +48,4 @@ Additionally, applications must keep the vote extension data concise as it can d ## FinalizeBlock -`FinalizeBlock` is then called and is responsible for updating the state of the blockchain and making the block available to users +`FinalizeBlock` is then called and is responsible for updating the state of the blockchain and making the block available to users. diff --git a/docs/build/abci/01-prepare-proposal.md b/docs/build/abci/01-prepare-proposal.md index b38243508573..74508e0a0882 100644 --- a/docs/build/abci/01-prepare-proposal.md +++ b/docs/build/abci/01-prepare-proposal.md @@ -37,8 +37,8 @@ favor of a custom implementation in [`app.go`](./01-app-go-v2.md): ```go prepareOpt := func(app *baseapp.BaseApp) { -abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app) -app.SetPrepareProposal(abciPropHandler.PrepareProposalHandler()) + abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app) + app.SetPrepareProposal(abciPropHandler.PrepareProposalHandler())) } baseAppOptions = append(baseAppOptions, prepareOpt) diff --git a/docs/build/abci/02-process-proposal.md b/docs/build/abci/02-process-proposal.md index 815c093fe782..9e5ddd4d0118 100644 --- a/docs/build/abci/02-process-proposal.md +++ b/docs/build/abci/02-process-proposal.md @@ -2,14 +2,14 @@ `ProcessProposal` handles the validation of a proposal from `PrepareProposal`, which also includes a block header. Meaning, that after a block has been proposed -the other validators have the right to vote on a block. The validator in the +the other validators have the right to accept or reject that block. The validator in the default implementation of `PrepareProposal` runs basic validity checks on each transaction. Note, `ProcessProposal` MAY NOT be non-deterministic, i.e. it must be deterministic. This means if `ProcessProposal` panics or fails and we reject, all honest validator -processes will prevote nil and the CometBFT round will proceed again until a valid -proposal is proposed. +processes should reject (i.e., prevote nil). If so, then CometBFT will start a new round with a new block proposal, and the same cycle will happen with `PrepareProposal` +and `ProcessProposal` for the new proposal. Here is the implementation of the default implementation: @@ -24,8 +24,8 @@ provided in the proposal DO NOT exceed the maximum block gas and `maxtxbytes` (i ```go processOpt := func(app *baseapp.BaseApp) { -abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app) -app.SetProcessProposal(abciPropHandler.ProcessProposalHandler()) + abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app) + app.SetProcessProposal(abciPropHandler.ProcessProposalHandler()) } baseAppOptions = append(baseAppOptions, processOpt) diff --git a/docs/build/abci/03-vote-extensions.md b/docs/build/abci/03-vote-extensions.md index 758c1ae45db6..9a97ec6c6f3c 100644 --- a/docs/build/abci/03-vote-extensions.md +++ b/docs/build/abci/03-vote-extensions.md @@ -7,8 +7,7 @@ defined in ABCI++. ## Extend Vote -ABCI++ allows an application to extend a pre-commit vote with arbitrary data. This -process does NOT have to be deterministic, and the data returned can be unique to the +ABCI2.0 (colloquially called ABCI++) allows an application to extend a pre-commit vote with arbitrary data. This process does NOT have to be deterministic, and the data returned can be unique to the validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/types/abci.go#L26-L27): ```go