Skip to content

Commit

Permalink
docs: various improvements (cometbft#1603)
Browse files Browse the repository at this point in the history
* 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 a4a1a04.
  • Loading branch information
melekes authored Nov 15, 2023
1 parent 3b1cdce commit a05b73e
Show file tree
Hide file tree
Showing 4 changed files with 43 additions and 54 deletions.
44 changes: 19 additions & 25 deletions docs/guides/go-built-in.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -588,7 +582,7 @@ func main() {
nm.DefaultGenesisDocProviderFunc(config),
cfg.DefaultDBProvider,
nm.DefaultMetricsProvider(config.Instrumentation),
logger
logger,
)

if err != nil {
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
37 changes: 16 additions & 21 deletions docs/guides/go.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/guides/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand Down
8 changes: 4 additions & 4 deletions docs/introduction/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit a05b73e

Please sign in to comment.