chore: run script again (???)

versioned_docs/version-0.52/build/abci/00-introduction.md

@@ -0,0 +1,51 @@
+# Introduction
+
+## What is ABCI?
+
+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/v1.0/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 (compared to ABCI v0) are:
+
+* `PrepareProposal`
+* `ProcessProposal`
+* `ExtendVote`
+* `VerifyVoteExtension`
+* `FinalizeBlock`
+
+
+## The Flow
+
+## PrepareProposal
+
+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 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/vote-extensions).
+
+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/v1.0/references/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.

versioned_docs/version-0.52/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 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.52.0-beta.1/baseapp/abci_utils.go
+```
+
+This default implementation can be overridden by the application developer in
+favor of a custom implementation in [`app_di.go`](https://docs.cosmos.network/main/build/building-apps/app-go-di):
+
+```go
+prepareOpt := func(app *baseapp.BaseApp) {
+    abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app)
+    app.SetPrepareProposal(abciPropHandler.PrepareProposalHandler())
+}
+
+baseAppOptions = append(baseAppOptions, prepareOpt)
+```

versioned_docs/version-0.52/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 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 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:
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.1/baseapp/abci_utils.go#L224-L231
+```
+
+Like `PrepareProposal` this implementation is the default and can be modified by
+the application developer in [`app_di.go`](https://docs.cosmos.network/main/build/building-apps/app-go-di). If you decide to implement
+your own `ProcessProposal` handler, you must 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)
+```

versioned_docs/version-0.52/build/abci/03-vote-extensions.md

@@ -0,0 +1,122 @@
+# Vote Extensions
+
+:::note Synopsis
+This section describes how the application can define and use vote extensions
+defined in ABCI++.
+:::
+
+## Extend Vote
+
+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.52.0-beta.1/types/abci.go#L26-L27):
+
+```go
+type ExtendVoteHandler func(Context, *abci.ExtendVoteRequest) (*abci.ExtendVoteResponse, 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://docs.cometbft.com/v1.0/spec/abci/abci++_methods#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://docs.cometbft.com/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed)
+for more details.
+
+Click [here](https://docs.cosmos.network/main/build/abci/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.52.0-beta.1/types/abci.go#L29-L31):
+
+```go
+type VerifyVoteExtensionHandler func(Context, *abci.VerifyVoteExtensionRequest) (*abci.VerifyVoteExtensionResponse, 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://docs.cometbft.com/v1.0/spec/abci/abci++_methods#verifyvoteextension)
+for more details.
+
+Additionally, please keep in mind that performance can be degraded if vote extensions are too big ([see vote extension testbed](https://docs.cometbft.com/v1.0/references/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
+}
+```

versioned_docs/version-0.52/build/abci/04-checktx.md

@@ -0,0 +1,50 @@
+# CheckTx
+
+CheckTx is called by the `BaseApp` when comet receives a transaction from a client, over the p2p network or RPC. The CheckTx method is responsible for validating the transaction and returning an error if the transaction is invalid. 
+
+```mermaid
+graph TD
+    subgraph SDK[Cosmos SDK]
+        B[Baseapp]
+        A[AnteHandlers]
+        B <-->|Validate TX| A
+    end
+    C[CometBFT] <-->|CheckTx|SDK
+    U((User)) -->|Submit TX| C
+    N[P2P] -->|Receive TX| C
+```
+
+```go reference
+https://github.com/cosmos/cosmos-sdk/blob/31c604762a434c7b676b6a89897ecbd7c4653a23/baseapp/abci.go#L350-L390
+```
+
+## CheckTx Handler
+
+`CheckTxHandler` allows users to extend the logic of `CheckTx`. `CheckTxHandler` is called by pasding context and the transaction bytes received through ABCI. It is required that the handler returns deterministic results given the same transaction bytes. 
+
+:::note
+we return the raw decoded transaction here to avoid decoding it twice.
+:::
+
+```go
+type CheckTxHandler func(ctx sdk.Context, tx []byte) (Tx, error)
+```
+
+Setting a custom `CheckTxHandler` is optional. It can be done from your app.go file:
+
+```go
+func NewSimApp(
+	logger log.Logger,
+	db corestore.KVStoreWithBatch,
+	traceStore io.Writer,
+	loadLatest bool,
+	appOpts servertypes.AppOptions,
+	baseAppOptions ...func(*baseapp.BaseApp),
+) *SimApp {
+  ...
+  // Create ChecktxHandler
+  checktxHandler := abci.NewCustomCheckTxHandler(...)
+  app.SetCheckTxHandler(checktxHandler)
+  ...
+}
+```

versioned_docs/version-0.52/build/abci/_category_.json

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

versioned_docs/version-0.52/build/architecture/PROCESS.md

@@ -0,0 +1,58 @@
+# ADR Creation Process
+
+1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md`
+2. Create a draft Pull Request if you want to get early feedback.
+3. Make sure the context and solution are clear and well documented.
+4. Add an entry to a list in the [README](./README.md) file.
+5. Create a Pull Request to propose a new ADR.
+
+## What is an ADR? 
+
+An ADR is a document to document an implementation and design that may or may not have been discussed in an RFC. While an RFC is meant to replace synchronous communication in a distributed environment, an ADR is meant to document an already made decision. An ADR won't come with much of a communication overhead because the discussion was recorded in an RFC or a synchronous discussion. If the consensus came from a synchronous discussion then a short excerpt should be added to the ADR to explain the goals. 
+
+## ADR life cycle
+
+ADR creation is an **iterative** process. Instead of having a high amount of communication overhead, an ADR is used when there is already a decision made and implementation details need to be added. The ADR should document what the collective consensus for the specific issue is and how to solve it. 
+
+1. Every ADR should start with either an RFC or a discussion where consensus has been met. 
+
+2. Once consensus is met, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`.
+
+3. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue.
+
+4. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to  merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it.
+
+5. Merged ADRs SHOULD NOT be pruned.
+
+### ADR status
+
+Status has two components:
+
+```text
+{CONSENSUS STATUS} {IMPLEMENTATION STATUS}
+```
+
+IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`.
+
+#### Consensus Status
+
+```text
+DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by ADR-xxx
+                  \        |
+                   \       |
+                    v      v
+                     ABANDONED
+```
+
+* `DRAFT`: [optional] an ADR which is a work in progress, not being ready for a general review. This is to present an early work and get early feedback in a Draft Pull Request form.
+* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreement yet.
+* `LAST CALL <date for the last call>`: [optional] Notify that we are close to accepting updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze.
+* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design.
+* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so.
+* `SUPERSEDED by ADR-xxx`: ADR which has been superseded by a new ADR.
+* `ABANDONED`: the ADR is no longer pursued by the original authors.
+
+## Language used in ADR
+
+* The context/background should be written in the present tense.
+* Avoid using a first, personal form.