docs: various improvements (cometbft#1603)

* docs: fix Query return parameters

* docs: fix the number of ABCI connections

ABCI creates 4 connections, not 3

* docs: bump cleveldb version

1.20 is 6 years old! 1.23 was released on Feb 24, 2021

* docs: remove check from PrepareProposal

This check only confuses readers. PrepareProposal returns
`proposal.Txs` (original list), not `txs`. Thus for loop is essentially
noop and can be removed. Even if we modify PrepareProposal to return
txs, it confuses application devs since CometBFT respects the limit when
creating a proposal! Therefore, application devs should only check the
limit when modifying the transactions, which is not the case here.

* docs: minor highlighting

* docs: fix syntax error

missing comma

* docs: fix [email protected]/proto/merge.go:123:28: type error

go: go1.21.3 darwin/amd64
cometbft: v0.38.0

```
../../../go/pkg/mod/github.com/cosmos/[email protected]/proto/merge.go:123:28:
type func(x *descriptorpb.FileDescriptorProto, y
*descriptorpb.FileDescriptorProto) bool of func(x, y
*descriptorpb.FileDescriptorProto) bool {…} does not match inferred type
func(a *descriptorpb.FileDescriptorProto, b
*descriptorpb.FileDescriptorProto) int for func(a E, b E) int
```

* docs: add missing double quote

* docs: make the same changes in go guide

- add a note about gogoproto
- simplify PrepareProposal
- add missing double quote

* docs: remove XXX

will create a separate PR updating gogoproto for v0.38

* Revert "docs: remove XXX"

This reverts commit a4a1a04.

docs/guides/go-built-in.md

@@ -101,10 +101,18 @@ github.com/cometbft/cometbft v0.38.0
 )
 ```
 
+XXX: CometBFT `v0.38.0` uses a slightly outdated `gogoproto` library, which
+may fail to compile with newer Go versions. To avoid any compilation errors,
+upgrade `gogoproto` manually:
+
+```bash
+go get github.com/cosmos/[email protected]
+```
+
 As you write the kvstore application, you can rebuild the binary by
 pulling any new dependencies and recompiling it.
 
-```sh
+```bash
 go get
 go build
 ```
@@ -142,7 +150,7 @@ func (app *KVStoreApplication) Info(_ context.Context, info *abcitypes.RequestIn
 }
 
 func (app *KVStoreApplication) Query(_ context.Context, req *abcitypes.RequestQuery) (*abcitypes.ResponseQuery, error) {
-    return &abcitypes.ResponseQuery{}
+    return &abcitypes.ResponseQuery{}, nil
 }
 
 func (app *KVStoreApplication) CheckTx(_ context.Context, check *abcitypes.RequestCheckTx) (*abcitypes.ResponseCheckTx, error) {
@@ -457,30 +465,15 @@ The application is free to modify the group before returning from the call, as l
 does not use more bytes than `RequestPrepareProposal.max_tx_bytes`
 For example, the application may reorder, add, or even remove transactions from the group to improve the
 execution of the block once accepted.
+
 In the following code, the application simply returns the unmodified group of transactions:
 
 ```go
- func (app *KVStoreApplication) PrepareProposal(_ context.Context, proposal *abcitypes.RequestPrepareProposal) (*abcitypes.ResponsePrepareProposal, error) {
-   totalBytes := int64(0)
-   txs := make([]byte, 0)
-
-   for _, tx := range proposal.Txs {
-     totalBytes += int64(len(tx))
-     txs = append(txs, tx...)
-
-       if totalBytes > int64(proposal.MaxTxBytes) {
-         break
-       }
-     }
-
-     return &abcitypes.ResponsePrepareProposal{Txs: proposal.Txs}, nil
- }
+func (app *KVStoreApplication) PrepareProposal(_ context.Context, proposal *abcitypes.RequestPrepareProposal) (*abcitypes.ResponsePrepareProposal, error) {
+    return &abcitypes.ResponsePrepareProposal{Txs: proposal.Txs}, nil
+}
 ```
 
-This code snippet iterates through the proposed transactions and calculates the `total bytes`. If the `total bytes` exceeds the `MaxTxBytes` specified in the `RequestPrepareProposal` struct, the loop breaks and the transactions processed so far are returned.
-
-Note: It is the responsibility of the application to ensure that the `total bytes` of transactions returned does not exceed the `RequestPrepareProposal.max_tx_bytes` limit.
-
 Once a proposed block is received by a node, the proposal is passed to the application to give
 its blessing before voting to accept the proposal.
 
@@ -497,7 +490,8 @@ func (app *KVStoreApplication) ProcessProposal(_ context.Context, proposal *abci
 
 ## 1.4 Starting an application and a CometBFT instance in the same process
 
-Now that we have the basic functionality of our application in place, let's put it all together inside of our main.go file.
+Now that we have the basic functionality of our application in place, let's put
+it all together inside of our `main.go` file.
 
 Change the contents of your `main.go` file to the following.
 
@@ -588,7 +582,7 @@ func main() {
         nm.DefaultGenesisDocProviderFunc(config),
         cfg.DefaultDBProvider,
         nm.DefaultMetricsProvider(config.Instrumentation),
-        logger
+        logger,
     )
 
     if err != nil {
@@ -678,7 +672,7 @@ node, err := nm.NewNode(
     nm.DefaultGenesisDocProviderFunc(config),
     cfg.DefaultDBProvider,
     nm.DefaultMetricsProvider(config.Instrumentation),
-logger)
+    logger)
 
 if err != nil {
     log.Fatalf("Creating node: %v", err)
@@ -795,7 +789,7 @@ The response contains a `base64` encoded representation of the data we submitted
 To get the original value out of this data, we can use the `base64` command line utility:
 
 ```bash
-echo cm9ja3M=" | base64 -d
+echo "cm9ja3M=" | base64 -d
 ```
 
 ## Outro

docs/guides/go.md

@@ -101,10 +101,18 @@ github.com/cometbft/cometbft v0.38.0
 )
 ```
 
+XXX: CometBFT `v0.38.0` uses a slightly outdated `gogoproto` library, which
+may fail to compile with newer Go versions. To avoid any compilation errors,
+upgrade `gogoproto` manually:
+
+```bash
+go get github.com/cosmos/[email protected]
+```
+
 As you write the kvstore application, you can rebuild the binary by
 pulling any new dependencies and recompiling it.
 
-```sh
+```bash
 go get
 go build
 ```
@@ -449,34 +457,20 @@ included in blocks, it groups some of these transactions and then gives the appl
 to modify the group by invoking `PrepareProposal`.
 
 The application is free to modify the group before returning from the call, as long as the resulting set
-does not use more bytes than `RequestPrepareProposal.max_tx_bytes'
+does not use more bytes than `RequestPrepareProposal.max_tx_bytes`.
 For example, the application may reorder, add, or even remove transactions from the group to improve the
 execution of the block once accepted.
+
 In the following code, the application simply returns the unmodified group of transactions:
 
 ```go
 func (app *KVStoreApplication) PrepareProposal(_ context.Context, proposal *abcitypes.RequestPrepareProposal) (*abcitypes.ResponsePrepareProposal, error) {
-  totalBytes := int64(0)
-  txs := make([]byte, 0)
-
-  for _, tx := range proposal.Txs {
-    totalBytes += int64(len(tx))
-    txs = append(txs, tx...)
-
-      if totalBytes > int64(proposal.MaxTxBytes) {
-        break
-      }
-    }
-
     return &abcitypes.ResponsePrepareProposal{Txs: proposal.Txs}, nil
 }
 ```
 
-This code snippet iterates through the proposed transactions and calculates the `total bytes`. If the `total bytes` exceeds the `MaxTxBytes` specified in the `RequestPrepareProposal` struct, the loop breaks and the transactions processed so far are returned.
-
-Note: It is the responsibility of the application to ensure that the `total bytes` of transactions returned does not exceed the `RequestPrepareProposal.max_tx_bytes` limit.
-
-Once a proposed block is received by a node, the proposal is passed to the application to determine its validity before voting to accept the proposal.
+Once a proposed block is received by a node, the proposal is passed to the
+application to determine its validity before voting to accept the proposal.
 
 This mechanism may be used for different reasons, for example to deal with blocks manipulated
 by malicious nodes, in which case the block should not be considered valid.
@@ -491,7 +485,8 @@ func (app *KVStoreApplication) ProcessProposal(_ context.Context, proposal *abci
 
 ## 1.4 Starting an application and a CometBFT instance
 
-Now that we have the basic functionality of our application in place, let's put it all together inside of our `main.go` file.
+Now that we have the basic functionality of our application in place, let's put
+it all together inside of our `main.go` file.
 
 Change the contents of your `main.go` file to the following.
 
@@ -706,7 +701,7 @@ The response contains a `base64` encoded representation of the data we submitted
 To get the original value out of this data, we can use the `base64` command line utility:
 
 ```bash
-echo cm9ja3M=" | base64 -d
+echo "cm9ja3M=" | base64 -d
 ```
 
 ## Outro

docs/guides/install.md

@@ -87,15 +87,15 @@ sudo apt install build-essential
 
 sudo apt-get install libsnappy-dev
 
-wget https://github.com/google/leveldb/archive/v1.20.tar.gz && \
-  tar -zxvf v1.20.tar.gz && \
-  cd leveldb-1.20/ && \
+wget https://github.com/google/leveldb/archive/v1.23.tar.gz && \
+  tar -zxvf v1.23.tar.gz && \
+  cd leveldb-1.23/ && \
   make && \
   sudo cp -r out-static/lib* out-shared/lib* /usr/local/lib/ && \
   cd include/ && \
   sudo cp -r leveldb /usr/local/include/ && \
   sudo ldconfig && \
-  rm -f v1.20.tar.gz
+  rm -f v1.23.tar.gz
 ```
 
 Set a database backend to `cleveldb`:

docs/introduction/README.md

@@ -220,10 +220,10 @@ lightweight clients, as Merkle-hash proofs can be verified by checking
 against the block hash, and that the block hash is signed by a quorum.
 
 There can be multiple ABCI socket connections to an application.
-CometBFT creates three ABCI connections to the application; one
-for the validation of transactions when broadcasting in the mempool, one
-for the consensus engine to run block proposals, and one more for
-querying the application state.
+CometBFT creates four ABCI connections to the application; one
+for the validation of transactions when broadcasting in the mempool, one for
+the consensus engine to run block proposals, one for creating snapshots of the
+application state, and one more for querying the application state.
 
 It's probably evident that application designers need to very carefully
 design their message handlers to create a blockchain that does anything