chore(docs): small improvements (backport tendermint#1781) (tendermin…

…t#1803) * chore(docs): small improvements (tendermint#1781) * 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. (cherry picked from commit 9020ce2) # Conflicts: # docs/app-dev/abci-cli.md # docs/core/validators.md # docs/data-companion/README.md * fix conflicts * correct number for qa item --------- Co-authored-by: Anton Kaliaev <[email protected]>
scrtlabs · Dec 11, 2023 · 6224629 · 6224629
1 parent 1b1ef9a
commit 6224629
Show file tree

Hide file tree

Showing 10 changed files with 59 additions and 83 deletions.
diff --git 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/v0.38.x/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/v0.38.x/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
@@ -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
@@ -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
@@ -1,5 +1,5 @@
 ---
-order: 6
+order: 5
 ---
 
 # Indexing Transactions

diff --git 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
@@ -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/v0.38.x/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/v0.38.x/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/v0.38.x/spec/core/data_structures.md#block)).
diff --git 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
@@ -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 <ip1> <ip2> <ip3> ..."
+    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
@@ -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: 6
 ---
 
 # CometBFT Quality Assurance

diff --git a/docs/tools/README.md b/docs/tools/README.md
@@ -2,7 +2,7 @@
 order: 1
 parent:
   title: Tools
-  order: 6
+  order: 5
 ---
 
 # Overview