From 9020ce23423157cf7b0d67027b7e0eddbd3b0b2d Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Mon, 11 Dec 2023 16:38:11 +0400 Subject: [PATCH] chore(docs): small improvements (#1781) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: remove "Run" section from install The "Quick Start" guide does a much better job explaining what is happening, and readers should follow that guide instead. * docs: move "CometBFT Quality Assurance" down No reason to have “CometBFT Quality Assurance” as a second item. The target audience for that document is probably security researchers - not the primary audience. * docs: remove cmdKVStore func in favor of link I can’t see a single reason why users need to see the source code of that function in order to progress with the abci-cli tool. Also the link should point to kvstore app, not abci-cli tool! * docs: swap abci-cli and getting-started items https://docs.cometbft.com/v0.38/app-dev/getting-started#first-cometbft-app should go before https://docs.cometbft.com/v0.38/app-dev/abci-cli because the latter is used to test ABCI applications. And by this point, the reader doesn’t have an app to test. * docs: remove "Committing a Block" from validators page not clear what’s the reason of explaining consensus details in the validators section. If a validator wants to get familiar with consensus, shouldn’t it go to consensus spec / page? * docs: make it clear who curates the validator set “Validators are expected to be online, and the set of validators is permissioned/curated by some external process.” This sentence is confusing to me. The set is curated by the ABCI application. * docs: replace EndBlock with FinalizeBlock * docs: add Bash script to compile persistent peers string Getting an ID from every machine is tedious and can be streamlined with a script, which, given IPs, collects IDs and outputs the command to run CometBFT. --- docs/app-dev/abci-cli.md | 51 +++------------------------ docs/app-dev/app-architecture.md | 2 +- docs/app-dev/getting-started.md | 2 +- docs/app-dev/indexing-transactions.md | 2 +- docs/core/metrics.md | 2 +- docs/core/validators.md | 30 +++++----------- docs/data-companion/README.md | 2 +- docs/guides/install.md | 9 ----- docs/guides/quick-start.md | 40 +++++++++++++++++++++ docs/qa/README.md | 2 +- docs/tools/README.md | 2 +- 11 files changed, 60 insertions(+), 84 deletions(-) diff --git a/docs/app-dev/abci-cli.md b/docs/app-dev/abci-cli.md index 4f19fe211f8..6b45ace7377 100644 --- a/docs/app-dev/abci-cli.md +++ b/docs/app-dev/abci-cli.md @@ -1,5 +1,5 @@ --- -order: 2 +order: 3 --- # Using ABCI-CLI @@ -62,51 +62,10 @@ The most important messages are `deliver_tx`, `check_tx`, and `commit`, but there are others for convenience, configuration, and information purposes. -We'll start a kvstore application, which was installed at the same time -as `abci-cli` above. The kvstore just stores transactions in a merkle -tree. Its code can be found -[here](https://github.com/cometbft/cometbft/blob/main/abci/cmd/abci-cli/abci-cli.go) -and looks like the following: - -```go -func cmdKVStore(cmd *cobra.Command, args []string) error { - logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) - - // Create the application - in memory or persisted to disk - var app types.Application - if flagPersist == "" { - var err error - flagPersist, err = os.MkdirTemp("", "persistent_kvstore_tmp") - if err != nil { - return err - } - } - app = kvstore.NewPersistentKVStoreApplication(flagPersist) - app.(*kvstore.PersistentKVStoreApplication).SetLogger(logger.With("module", "kvstore")) - - // Start the listener - srv, err := server.NewServer(flagAddress, flagAbci, app) - if err != nil { - return err - } - srv.SetLogger(logger.With("module", "abci-server")) - if err := srv.Start(); err != nil { - return err - } - - // Stop upon receiving SIGTERM or CTRL-C. - tmos.TrapSignal(logger, func() { - // Cleanup - if err := srv.Stop(); err != nil { - logger.Error("Error while stopping server", "err", err) - } - }) - - // Run forever. - select {} -} - -``` +We'll start a kvstore application, which was installed at the same time as +`abci-cli` above. The kvstore just stores transactions in a Merkle tree. Its +code can be found +[here](https://github.com/cometbft/cometbft/blob/main/abci/example/kvstore/kvstore.go). Start the application by running: diff --git a/docs/app-dev/app-architecture.md b/docs/app-dev/app-architecture.md index 97ebf502cf2..fe22582faba 100644 --- a/docs/app-dev/app-architecture.md +++ b/docs/app-dev/app-architecture.md @@ -1,5 +1,5 @@ --- -order: 3 +order: 4 --- # Application Architecture Guide diff --git a/docs/app-dev/getting-started.md b/docs/app-dev/getting-started.md index 94076287224..f2ce5221cf8 100644 --- a/docs/app-dev/getting-started.md +++ b/docs/app-dev/getting-started.md @@ -1,5 +1,5 @@ --- -order: 1 +order: 2 --- # Getting Started diff --git a/docs/app-dev/indexing-transactions.md b/docs/app-dev/indexing-transactions.md index 326de1accb9..69f610a3bb1 100644 --- a/docs/app-dev/indexing-transactions.md +++ b/docs/app-dev/indexing-transactions.md @@ -1,5 +1,5 @@ --- -order: 6 +order: 5 --- # Indexing Transactions diff --git a/docs/core/metrics.md b/docs/core/metrics.md index 71cc8d2093b..5e97318f358 100644 --- a/docs/core/metrics.md +++ b/docs/core/metrics.md @@ -61,7 +61,7 @@ The following metrics are available: | mempool\_tx\_size\_bytes | Histogram | | Transaction sizes in bytes | | mempool\_failed\_txs | Counter | | Number of failed transactions | | mempool\_recheck\_times | Counter | | Number of transactions rechecked in the mempool | -| state\_block\_processing\_time | Histogram | | Time between BeginBlock and EndBlock in ms | +| state\_block\_processing\_time | Histogram | | Time spent processing FinalizeBlock in ms | | state\_consensus\_param\_updates | Counter | | Number of consensus parameter updates returned by the application since process start | | state\_validator\_set\_updates | Counter | | Number of validator set updates returned by the application since process start | | statesync\_syncing | Gauge | | Either 0 (not state syncing) or 1 (syncing) | diff --git a/docs/core/validators.md b/docs/core/validators.md index 34f99290856..86c4626ee6c 100644 --- a/docs/core/validators.md +++ b/docs/core/validators.md @@ -10,14 +10,13 @@ _votes_ which contain cryptographic signatures signed by each validator's private key. Some Proof-of-Stake consensus algorithms aim to create a "completely" -decentralized system where all stakeholders (even those who are not -always available online) participate in the committing of blocks. -CometBFT has a different approach to block creation. Validators are -expected to be online, and the set of validators is permissioned/curated -by some external process. Proof-of-stake is not required, but can be -implemented on top of CometBFT consensus. That is, validators may be -required to post collateral on-chain, off-chain, or may not be required -to post any collateral at all. +decentralized system where all stakeholders (even those who are not always +available online) participate in the committing of blocks. CometBFT has a +different approach to block creation. Validators are expected to be online, and +the set of validators is permissioned/curated by the ABCI application. +Proof-of-stake is not required, but can be implemented on top of CometBFT +consensus. That is, validators may be required to post collateral on-chain, +off-chain, or may not be required to post any collateral at all. Validators have a cryptographic key-pair and an associated amount of "voting power". Voting power need not be the same. @@ -27,7 +26,7 @@ Validators have a cryptographic key-pair and an associated amount of There are two ways to become validator. 1. They can be pre-established in the [genesis state](./using-cometbft.md#genesis) -2. The ABCI app responds to the EndBlock message with changes to the +2. The ABCI app responds to the FinalizeBlock message with changes to the existing validator set. ## Setting up a Validator @@ -100,16 +99,3 @@ More Information can be found at these links: Protecting a validator's consensus key is the most important factor to take in when designing your setup. The key that a validator is given upon creation of the node is called a consensus key, it has to be online at all times in order to vote on blocks. It is **not recommended** to merely hold your private key in the default json file (`priv_validator_key.json`). Fortunately, the [Interchain Foundation](https://interchain.io) has worked with a team to build a key management server for validators. You can find documentation on how to use it [here](https://github.com/iqlusioninc/tmkms), it is used extensively in production. You are not limited to using this tool, there are also [HSMs](https://safenet.gemalto.com/data-encryption/hardware-security-modules-hsms/), there is not a recommended HSM. Currently CometBFT uses [Ed25519](https://ed25519.cr.yp.to/) keys which are widely supported across the security sector and HSMs. - -## Committing a Block - -> **+2/3 is short for "more than 2/3"** - -A block is committed when +2/3 of the validator set sign -[precommit votes](https://github.com/cometbft/cometbft/blob/main/spec/core/data_structures.md#vote) -for that block at the same `round`. -The +2/3 set of precommit votes is called a -[commit](https://github.com/cometbft/cometbft/blob/main/spec/core/data_structures.md#commit). -While any +2/3 set of precommits for the same block at the same height&round can serve as -validation, the canonical commit is included in the next block (see -[LastCommit](https://github.com/cometbft/cometbft/blob/main/spec/core/data_structures.md#block)). diff --git a/docs/data-companion/README.md b/docs/data-companion/README.md index 5943a444067..4bc2b579fc5 100644 --- a/docs/data-companion/README.md +++ b/docs/data-companion/README.md @@ -2,7 +2,7 @@ order: false parent: title: Data Companion - order: 7 + order: 6 --- # Guides diff --git a/docs/guides/install.md b/docs/guides/install.md index ebca6d46cf2..852ab8524e2 100644 --- a/docs/guides/install.md +++ b/docs/guides/install.md @@ -51,15 +51,6 @@ running: cometbft version ``` -## Run - -To start a one-node blockchain with a simple in-process application: - -```sh -cometbft init -cometbft node --proxy_app=kvstore -``` - ## Reinstall If you already have CometBFT installed, and you make updates, simply diff --git a/docs/guides/quick-start.md b/docs/guides/quick-start.md index b0eecf25187..d5f1481710c 100644 --- a/docs/guides/quick-start.md +++ b/docs/guides/quick-start.md @@ -108,6 +108,46 @@ cometbft show_node_id --home ./mytestnet/node2 cometbft show_node_id --home ./mytestnet/node3 ``` +Here's a handy Bash script to compile the persistent peers string, which will +be needed for our next step: + +```bash +#!/bin/bash + +# Check if the required argument is provided +if [ $# -eq 0 ]; then + echo "Usage: $0 ..." + exit 1 +fi + +# Command to run on each IP +BASE_COMMAND="cometbft show_node_id --home ./mytestnet/node" + +# Initialize an array to store results +PERSISTENT_PEERS="" + +# Iterate through provided IPs +for i in "${!@}"; do + IP="${!i}" + NODE_IDX=$((i - 1)) # Adjust for zero-based indexing + + echo "Getting ID of $IP (node $NODE_IDX)..." + + # Run the command on the current IP and capture the result + ID=$($BASE_COMMAND$NODE_IDX) + + # Store the result in the array + PERSISTENT_PEERS+="$ID@$IP:26656" + + # Add a comma if not the last IP + if [ $i -lt $# ]; then + PERSISTENT_PEERS+="," + fi +done + +echo "$PERSISTENT_PEERS" +``` + Finally, from each machine, run: ```sh diff --git a/docs/qa/README.md b/docs/qa/README.md index 52071d4003a..d019d45808d 100644 --- a/docs/qa/README.md +++ b/docs/qa/README.md @@ -3,7 +3,7 @@ order: 1 parent: title: CometBFT Quality Assurance description: This is a report on the process followed and results obtained when running v0.34.x on testnets - order: 2 + order: 7 --- # CometBFT Quality Assurance diff --git a/docs/tools/README.md b/docs/tools/README.md index de29e17f122..88e19b76711 100644 --- a/docs/tools/README.md +++ b/docs/tools/README.md @@ -2,7 +2,7 @@ order: 1 parent: title: Tools - order: 6 + order: 5 --- # Overview