From a05b73ee7975919b65fd86afc1584cfa842e5f75 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 15 Nov 2023 09:12:38 +0400 Subject: [PATCH] docs: various improvements (#1603) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 gogoproto@v1.4.6/proto/merge.go:123:28: type error go: go1.21.3 darwin/amd64 cometbft: v0.38.0 ``` ../../../go/pkg/mod/github.com/cosmos/gogoproto@v1.4.6/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 a4a1a04e423ec93a27a72ebb6bacecb747f76276. --- docs/guides/go-built-in.md | 44 ++++++++++++++++--------------------- docs/guides/go.md | 37 ++++++++++++++----------------- docs/guides/install.md | 8 +++---- docs/introduction/README.md | 8 +++---- 4 files changed, 43 insertions(+), 54 deletions(-) diff --git a/docs/guides/go-built-in.md b/docs/guides/go-built-in.md index ea2ad7b87d0..dfee3c9beec 100644 --- a/docs/guides/go-built-in.md +++ b/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/gogoproto@v1.4.11 +``` + 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 diff --git a/docs/guides/go.md b/docs/guides/go.md index 15fcc972f92..3b3c372633a 100644 --- a/docs/guides/go.md +++ b/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/gogoproto@v1.4.11 +``` + 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 diff --git a/docs/guides/install.md b/docs/guides/install.md index 366c0c90a27..ebca6d46cf2 100644 --- a/docs/guides/install.md +++ b/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`: diff --git a/docs/introduction/README.md b/docs/introduction/README.md index 1c2b5850b38..7eae0c1ecc7 100644 --- a/docs/introduction/README.md +++ b/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