docs: add abci docs for 0.50

docs/docs/build/abci/00-introduction.md

@@ -0,0 +1,51 @@
+# Introduction
+
+## What is ABCI?
+
+ABC, 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.
+
+The 5 methods introduced during ABCI 2.0 are:
+
+* `PrepareProposal`
+* `ProcessProposal`
+* `ExtendVote`
+* `VerifyVoteExtension`
+* `FinalizeBlock`
+
+
+## The Flow
+
+## 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.
+
+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.
+
+Please note that vote extensions will only be available on the following height in which vote extensions are enabled. More information about vote extensions can be found [here](https://docs.cosmos.network/main/build/abci/03-vote-extensions.md).
+
+After creating the proposal, the proposer returns it to CometBFT.
+
+PrepareProposal CAN be non-deterministic.
+
+## ProcessProposal
+
+This method allows validators to perform application-specific checks on the block proposal and is called on all validators. This is an important step in the consensus process, as it ensures that the block is valid and meets the requirements of the application. For example, validators could check that the block contains all the required transactions or that the block does not create any invalid state transitions.
+
+The implementation of `ProcessProposal` MUST be deterministic.
+
+## ExtendVote and VerifyVoteExtensions
+
+These methods allow applications to extend the voting process by requiring validators to perform additional actions beyond simply validating blocks.
+
+If vote extensions are enabled, `ExtendVote` will be called on every validator and each one will return its vote extension which is in practice a bunch of bytes. As mentioned above this data (vote extension) can only be retrieved in the next block height during `PrepareProposal`. Additionally, this data can be arbitrary, but in the provided tutorials, it serves as an oracle or proof of transactions in the mempool. Essentially, vote extensions are processed and injected as transactions. Examples of use-cases for vote extensions include prices for a price oracle or encryption shares for an encrypted transaction mempool. `ExtendVote` CAN be non-deterministic.
+
+`VerifyVoteExtensions` is performed on every validator multiple times in order to verify other validators' vote extensions. This check is submitted to validate the integrity and validity of the vote extensions preventing malicious or invalid vote extensions.
+
+Additionally, applications must keep the vote extension data concise as it can degrade the performance of their chain, see testing results [here](https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed).
+
+`VerifyVoteExtensions` MUST be deterministic.
+
+
+## FinalizeBlock
+
+`FinalizeBlock` is then called and is responsible for updating the state of the blockchain and making the block available to users

docs/docs/build/abci/01-prepare-proposal.md

@@ -0,0 +1,45 @@
+# Prepare Proposal
+
+`PrepareProposal` handles construction of the block, meaning that when a proposer
+is preparing to propose a block, it requests the application to evaluate a
+`RequestPrepareProposal`, which contains a series of transactions from CometBFT's
+mempool. At this point, the application has complete control over the proposal.
+It can modify, delete, and inject transactions from its own app-side mempool into
+the proposal or even ignore all the transactions altogether. What the application
+does with the transactions provided to it by `RequestPrepareProposal` has no
+effect on CometBFT's mempool.
+
+Note, that the application defines the semantics of the `PrepareProposal` and it
+MAY be non-deterministic and is only executed by the current block proposer.
+
+Now, reading mempool twice in the previous sentence is confusing, lets break it down.
+CometBFT has a mempool that handles gossiping transactions to other nodes
+in the network. The order of these transactions is determined by CometBFT's mempool,
+using FIFO as the sole ordering mechanism. It's worth noting that the priority mempool
+in Comet was removed or deprecated.
+However, since the application is able to fully inspect
+all transactions, it can provide greater control over transaction ordering.
+Allowing the application to handle ordering enables the application to define how
+it would like the block constructed.
+
+The Cosmos SDK defines the `DefaultProposalHandler` type, which provides applications with
+`PrepareProposal` and `ProcessProposal` handlers. If you decide to implement your
+own `PrepareProposal` handler, you must be sure to ensure that the transactions
+selected DO NOT exceed the maximum block gas (if set) and the maximum bytes provided
+by `req.MaxBytes`.
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci_utils.go
+```
+
+This default implementation can be overridden by the application developer in
+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())
+}
+
+baseAppOptions = append(baseAppOptions, prepareOpt)
+```

docs/docs/build/abci/02-process-proposal.md

@@ -0,0 +1,32 @@
+# Process Proposal
+
+`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
+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.
+
+Here is the implementation of the default implementation:
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci_utils.go#L153-L159
+```
+
+Like `PrepareProposal` this implementation is the default and can be modified by
+the application developer in [`app.go`](./01-app-go-v2.md). If you decide to implement
+your own `ProcessProposal` handler, you must be sure to ensure that the transactions
+provided in the proposal DO NOT exceed the maximum block gas and `maxtxbytes` (if set).
+
+```go
+processOpt := func(app *baseapp.BaseApp) {
+abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app)
+app.SetProcessProposal(abciPropHandler.ProcessProposalHandler())
+}
+
+baseAppOptions = append(baseAppOptions, processOpt)
+```

docs/docs/build/abci/03-vote-extensions.md

@@ -0,0 +1,123 @@
+# Vote Extensions
+
+:::note Synopsis
+This section 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 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
+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.
+
+Click [here](https://docs.cosmos.network/main/user/tutorials/vote-extensions) if you would like a walkthrough of how to implement vote extensions.
+
+
+## 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`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/types/abci.go#L29-L31):
+
+```go
+type VerifyVoteExtensionHandler func(Context, *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error)
+```
+
+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.
+
+Additionally, please keep in mind that performance can be degraded if vote extensions are too big (https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed), so we highly recommend a size validation in `VerifyVoteExtensions`.
+
+
+## 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).
+
+### Recovery of injected Vote Extensions
+
+As stated before, vote extensions can be injected into a block proposal (along with
+other transactions in the `Txs` field). The Cosmos SDK provides a pre-FinalizeBlock
+hook to allow applications to recover vote extensions, perform any necessary
+computation on them, and then store the results in the cached store. These results
+will be available to the application during the subsequent `FinalizeBlock` call.
+
+An example of how a pre-FinalizeBlock hook could look like is shown below:
+
+```go
+app.SetPreBlocker(func(ctx sdk.Context, req *abci.RequestFinalizeBlock) error {
+    allVEs := []VE{} // store all parsed vote extensions here
+    for _, tx := range req.Txs {
+        // define a custom function that tries to parse the tx as a vote extension
+        ve, ok := parseVoteExtension(tx)
+        if !ok {
+            continue
+        }
+
+        allVEs = append(allVEs, ve)
+    }
+
+    // perform any necessary computation on the vote extensions and store the result
+    // in the cached store
+    result := compute(allVEs)
+    err := storeVEResult(ctx, result)
+    if err != nil {
+        return err
+    }
+
+    return nil
+})
+
+```
+
+Then, in an app's module, the application can retrieve the result of the computation
+of vote extensions from the cached store:
+
+```go
+func (k Keeper) BeginBlocker(ctx context.Context) error {
+    // retrieve the result of the computation of vote extensions from the cached store
+    result, err := k.GetVEResult(ctx)
+    if err != nil {
+        return err
+    }
+
+    // use the result of the computation of vote extensions
+    k.setSomething(result)
+
+    return nil
+}
+```

docs/docs/build/abci/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "ABCI",
+    "position": 2,
+    "link": null
+}