config/docs: update and deprecated (#6879)

## Description - Add deprecated to config values in toml - update config in configuration doc - explain how to set up a node with the new network - add sentence about not needing to fork tendermint for built-in tutorial - closes #6865 - add note to use a released version of tendermint with the tutorials. This is to avoid unknown issues prior to a release.
2026-01-06 21:36:26 +00:00 · 2021-09-21 10:32:00 +00:00
parent 84ffaaaf37
commit df2d744ea9
4 changed files with 169 additions and 30 deletions
--- a/config/toml.go
+++ b/config/toml.go
@@ -159,14 +159,14 @@ state-file = "{{ js .PrivValidator.State }}"
 # when the listenAddr is prefixed with grpc instead of tcp it will use the gRPC Client
 laddr = "{{ .PrivValidator.ListenAddr }}"

-# Client certificate generated while creating needed files for secure connection.
+# Path to the client certificate generated while creating needed files for secure connection.
 # If a remote validator address is provided but no certificate, the connection will be insecure
 client-certificate-file = "{{ js .PrivValidator.ClientCertificate }}"

 # Client key generated while creating certificates for secure connection
 validator-client-key-file = "{{ js .PrivValidator.ClientKey }}"

-# Path Root Certificate Authority used to sign both client and server certificates
+# Path to the Root Certificate Authority used to sign both client and server certificates
 certificate-authority = "{{ js .PrivValidator.RootCA }}"


@@ -331,18 +331,28 @@ max-incoming-connection-attempts = {{ .P2P.MaxIncomingConnectionAttempts }}
 unconditional-peer-ids = "{{ .P2P.UnconditionalPeerIDs }}"

 # Maximum pause when redialing a persistent peer (if zero, exponential backoff is used)
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 persistent-peers-max-dial-period = "{{ .P2P.PersistentPeersMaxDialPeriod }}"

 # Time to wait before flushing messages out on the connection
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 flush-throttle-timeout = "{{ .P2P.FlushThrottleTimeout }}"

 # Maximum size of a message packet payload, in bytes
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 max-packet-msg-payload-size = {{ .P2P.MaxPacketMsgPayloadSize }}

 # Rate at which packets can be sent, in bytes/second
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 send-rate = {{ .P2P.SendRate }}

 # Rate at which packets can be received, in bytes/second
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 recv-rate = {{ .P2P.RecvRate }}

 # Set true to enable the peer-exchange reactor
@@ -519,7 +529,7 @@ peer-query-maj23-sleep-duration = "{{ .Consensus.PeerQueryMaj23SleepDuration }}"
 [tx-index]

 # The backend database list to back the indexer.
-# If list contains null, meaning no indexer service will be used.
+# If list contains "null" or "", meaning no indexer service will be used.
 #
 # The application will set which txs to index. In some cases a node operator will be able
 # to decide which txs to index based on configuration set in the application.
@@ -527,8 +537,8 @@ peer-query-maj23-sleep-duration = "{{ .Consensus.PeerQueryMaj23SleepDuration }}"
 # Options:
 #   1) "null"
 #   2) "kv" (default) - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend).
-# 		- When "kv" is chosen "tx.height" and "tx.hash" will always be indexed.
 #   3) "psql" - the indexer services backed by PostgreSQL.
+# When "kv" or "psql" is chosen "tx.height" and "tx.hash" will always be indexed.
 indexer = [{{ range $i, $e := .TxIndex.Indexer }}{{if $i}}, {{end}}{{ printf "%q" $e}}{{end}}]

 # The PostgreSQL connection configuration, the connection format:
--- a/docs/networks/README.md
+++ b/docs/networks/README.md
@@ -2,7 +2,7 @@
 order: 1
 parent:
  title: Networks
-  order: 6
+  order: 1
 ---

 # Overview
--- a/docs/nodes/configuration.md
+++ b/docs/nodes/configuration.md
@@ -16,8 +16,7 @@ the parameters set with their default values. It will look something
 like the file below, however, double check by inspecting the
 `config.toml` created with your version of `tendermint` installed:

-```toml
-# This is a TOML config file.
+```toml# This is a TOML config file.
 # For more information, see https://github.com/toml-lang/toml

 # NOTE: Any path below can be absolute (e.g. "/var/myawesomeapp/data") or
@@ -34,14 +33,14 @@ like the file below, however, double check by inspecting the
 proxy-app = "tcp://127.0.0.1:26658"

 # A custom human readable name for this node
-moniker = "anonymous"
+moniker = "ape"


 # Mode of Node: full | validator | seed (default: "validator")
 # * validator node (default)
 #   - all reactors
 #   - with priv_validator_key.json, priv_validator_state.json
-# * full node 
+# * full node
 #   - all reactors
 #   - No priv_validator_key.json, priv_validator_state.json
 # * seed node
@@ -49,6 +48,11 @@ moniker = "anonymous"
 #   - No priv_validator_key.json, priv_validator_state.json
 mode = "validator"

+# If this node is many blocks behind the tip of the chain, FastSync
+# allows them to catchup quickly by downloading blocks in parallel
+# and verifying their commits
+fast-sync = true
+
 # Database backend: goleveldb | cleveldb | boltdb | rocksdb | badgerdb
 # * goleveldb (github.com/syndtr/goleveldb - most popular implementation)
 #   - pure go
@@ -84,16 +88,6 @@ log-format = "plain"
 # Path to the JSON file containing the initial validator set and other meta data
 genesis-file = "config/genesis.json"

-# Path to the JSON file containing the private key to use as a validator in the consensus protocol
-priv-validator-key-file = "config/priv_validator_key.json"
-
-# Path to the JSON file containing the last sign state of a validator
-priv-validator-state-file = "data/priv_validator_state.json"
-
-# TCP or UNIX socket address for Tendermint to listen on for
-# connections from an external PrivValidator process
-priv-validator-laddr = ""
-
 # Path to the JSON file containing the private key to use for node authentication in the p2p protocol
 node-key-file = "config/node_key.json"

@@ -105,6 +99,33 @@ abci = "socket"
 filter-peers = false


+#######################################################
+###       Priv Validator Configuration              ###
+#######################################################
+[priv-validator]
+
+# Path to the JSON file containing the private key to use as a validator in the consensus protocol
+key-file = "config/priv_validator_key.json"
+
+# Path to the JSON file containing the last sign state of a validator
+state-file = "data/priv_validator_state.json"
+
+# TCP or UNIX socket address for Tendermint to listen on for
+# connections from an external PrivValidator process
+# when the listenAddr is prefixed with grpc instead of tcp it will use the gRPC Client
+laddr = ""
+
+# Path to the client certificate generated while creating needed files for secure connection.
+# If a remote validator address is provided but no certificate, the connection will be insecure
+client-certificate-file = ""
+
+# Client key generated while creating certificates for secure connection
+validator-client-key-file = ""
+
+# Path to the Root Certificate Authority used to sign both client and server certificates
+certificate-authority = ""
+
+
 #######################################################################
 ###                 Advanced Configuration Options                  ###
 #######################################################################
@@ -130,6 +151,7 @@ cors-allowed-headers = ["Origin", "Accept", "Content-Type", "X-Requested-With",

 # TCP or UNIX socket address for the gRPC server to listen on
 # NOTE: This server only supports /broadcast_tx_commit
+# Deprecated gRPC  in the RPC layer of Tendermint will be deprecated in 0.36.
 grpc-laddr = ""

 # Maximum number of simultaneous connections.
@@ -139,9 +161,10 @@ grpc-laddr = ""
 # 0 - unlimited.
 # Should be < {ulimit -Sn} - {MaxNumInboundPeers} - {MaxNumOutboundPeers} - {N of wal, db and other open files}
 # 1024 - 40 - 10 - 50 = 924 = ~900
+# Deprecated gRPC  in the RPC layer of Tendermint will be deprecated in 0.36.
 grpc-max-open-connections = 900

-# Activate unsafe RPC commands like /dial_seeds and /unsafe_flush_mempool
+# Activate unsafe RPC commands like /dial-seeds and /unsafe-flush-mempool
 unsafe = false

 # Maximum number of simultaneous connections (including WebSocket).
@@ -198,18 +221,34 @@ pprof-laddr = ""
 #######################################################
 [p2p]

+# Enable the legacy p2p layer.
+use-legacy = false
+
+# Select the p2p internal queue
+queue-type = "priority"
+
 # Address to listen for incoming connections
 laddr = "tcp://0.0.0.0:26656"

 # Address to advertise to peers for them to dial
 # If empty, will use the same port as the laddr,
 # and will introspect on the listener or use UPnP
-# to figure out the address.
+# to figure out the address. ip and port are required
+# example: 159.89.10.97:26656
 external-address = ""

 # Comma separated list of seed nodes to connect to
+# We only use these if we can’t connect to peers in the addrbook
+# NOTE: not used by the new PEX reactor. Please use BootstrapPeers instead.
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 seeds = ""

+# Comma separated list of peers to be added to the peer store
+# on startup. Either BootstrapPeers or PersistentPeers are
+# needed for peer discovery
+bootstrap-peers = ""
+
 # Comma separated list of nodes to keep persistent connections to
 persistent-peers = ""

@@ -217,6 +256,8 @@ persistent-peers = ""
 upnp = false

 # Path to address book
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 addr-book-file = "config/addrbook.json"

 # Set true for strict address routability rules
@@ -224,9 +265,15 @@ addr-book-file = "config/addrbook.json"
 addr-book-strict = true

 # Maximum number of inbound peers
+#
+# TODO: Remove once p2p refactor is complete in favor of MaxConnections.
+# ref: https://github.com/tendermint/tendermint/issues/5670
 max-num-inbound-peers = 40

 # Maximum number of outbound peers to connect to, excluding persistent peers
+#
+# TODO: Remove once p2p refactor is complete in favor of MaxConnections.
+# ref: https://github.com/tendermint/tendermint/issues/5670
 max-num-outbound-peers = 10

 # Maximum number of connections (inbound and outbound).
@@ -236,27 +283,40 @@ max-connections = 64
 max-incoming-connection-attempts = 100

 # List of node IDs, to which a connection will be (re)established ignoring any existing limits
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 unconditional-peer-ids = ""

 # Maximum pause when redialing a persistent peer (if zero, exponential backoff is used)
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 persistent-peers-max-dial-period = "0s"

 # Time to wait before flushing messages out on the connection
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 flush-throttle-timeout = "100ms"

 # Maximum size of a message packet payload, in bytes
-max-packet-msg-payload-size = 1024
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
+max-packet-msg-payload-size = 1400

 # Rate at which packets can be sent, in bytes/second
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 send-rate = 5120000

 # Rate at which packets can be received, in bytes/second
+# TODO: Remove once p2p refactor is complete
+# ref: https:#github.com/tendermint/tendermint/issues/5670
 recv-rate = 5120000

 # Set true to enable the peer-exchange reactor
 pex = true

 # Comma separated list of peer IDs to keep private (will not be gossiped to other peers)
+# Warning: IPs will be exposed at /net_info, for more information https://github.com/tendermint/tendermint/issues/3055
 private-peer-ids = ""

 # Toggle to disable guard against peers connecting from the same ip.
@@ -349,8 +409,15 @@ discovery-time = "15s"
 # Will create a new, randomly named directory within, and remove it when done.
 temp-dir = ""

+# The timeout duration before re-requesting a chunk, possibly from a different
+# peer (default: 15 seconds).
+chunk-request-timeout = "15s"
+
+# The number of concurrent chunk and block fetchers to run (default: 4).
+fetchers = "4"
+
 #######################################################
-###       BlockSync Configuration Connections       ###
+###       Block Sync Configuration Connections       ###
 #######################################################
 [blocksync]

@@ -410,7 +477,8 @@ peer-query-maj23-sleep-duration = "2s"
 #######################################################
 [tx-index]

-# What indexer to use for transactions
+# The backend database list to back the indexer.
+# If list contains "null" or "", meaning no indexer service will be used.
 #
 # The application will set which txs to index. In some cases a node operator will be able
 # to decide which txs to index based on configuration set in the application.
@@ -418,8 +486,13 @@ peer-query-maj23-sleep-duration = "2s"
 # Options:
 #   1) "null"
 #   2) "kv" (default) - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend).
-#   - When "kv" is chosen "tx.height" and "tx.hash" will always be indexed.
-indexer = "kv"
+#   3) "psql" - the indexer services backed by PostgreSQL.
+# When "kv" or "psql" is chosen "tx.height" and "tx.hash" will always be indexed.
+indexer = ["kv"]
+
+# The PostgreSQL connection configuration, the connection format:
+#   postgresql://<user>:<password>@<host>:<port>/<db>?<opts>
+psql-conn = ""

 #######################################################
 ###       Instrumentation Configuration Options     ###
@@ -520,10 +593,61 @@ This section will cover settings within the p2p section of the `config.toml`.

 - `external-address` = is the address that will be advertised for other nodes to use. We recommend setting this field with your public IP and p2p port.
  - > We recommend setting an external address. When used in a private network, Tendermint Core currently doesn't advertise the node's public address. There is active and ongoing work to improve the P2P system, but this is a helpful workaround for now.
- `seeds` = is a list of comma separated seed nodes that you will connect upon a start and ask for peers. A seed node is a node that does not participate in consensus but only helps propagate peers to nodes in the networks
 - `persistent-peers` = is a list of comma separated peers that you will always want to be connected to. If you're already connected to the maximum number of peers, persistent peers will not be added.
- `max-num-inbound-peers` = is the maximum number of peers you will accept inbound connections from at one time (where they dial your address and initiate the connection).
- `max-num-outbound-peers` = is the maximum number of peers you will initiate outbound connects to at one time (where you dial their address and initiate the connection).
- `unconditional-peer-ids` = is similar to `persistent-peers` except that these peers will be connected to even if you are already connected to the maximum number of peers. This can be a validator node ID on your sentry node.
 - `pex` = turns the peer exchange reactor on or off. Validator node will want the `pex` turned off so it would not begin gossiping to unknown peers on the network. PeX can also be turned off for statically configured networks with fixed network connectivity. For full nodes on open, dynamic networks, it should be turned on.
 - `private-peer-ids` = is a comma-separated list of node ids that will _not_ be exposed to other peers (i.e., you will not tell other peers about the ids in this list). This can be filled with a validator's node id.
+
+Recently the Tendermint Team conducted a refactor of the p2p layer. This lead to multiple config paramters being deprecated and/or replaced. 
+
+We will cover the new and deprecated parameters below.
+### New Parameters
+
+There are three new parameters, which are enabled if use-legacy is set to false.
+
+- `queue-type` = sets a type of queue to use in the p2p layer. There are three options available `fifo`, `priority` and `wdrr`. The default is priority
+- `bootstrap-peers` = is a list of comma seperated peers which will be used to bootstrap the address book. 
+- `max-connections` = is the max amount of allowed inbound and outbound connections.
+### Deprecated Parameters
+
+> Note: For Tendermint 0.35, there are two p2p implementations. The old version is used by deafult with the deprecated fields. The new implementation uses different config parameters, explained above.
+
+- `max-num-inbound-peers` = is the maximum number of peers you will accept inbound connections from at one time (where they dial your address and initiate the connection). *This was replaced by `max-connections`*
+- `max-num-outbound-peers` = is the maximum number of peers you will initiate outbound connects to at one time (where you dial their address and initiate the connection).*This was replaced by `max-connections`*
+- `unconditional-peer-ids` = is similar to `persistent-peers` except that these peers will be connected to even if you are already connected to the maximum number of peers. This can be a validator node ID on your sentry node. *Deprecated*
+- `seeds` = is a list of comma separated seed nodes that you will connect upon a start and ask for peers. A seed node is a node that does not participate in consensus but only helps propagate peers to nodes in the networks *Deprecated, replaced by bootstrap peers*
+
+## Indexing Settings
+
+Operators can configure indexing via the `[tx_index]` section. The `indexer`
+field takes a series of supported indexers. If `null` is included, indexing will
+be turned off regardless of other values provided.
+
+### Supported Indexers
+
+#### KV
+
+The `kv` indexer type is an embedded key-value store supported by the main
+underlying Tendermint database. Using the `kv` indexer type allows you to query
+for block and transaction events directly against Tendermint's RPC. However, the
+query syntax is limited and so this indexer type might be deprecated or removed
+entirely in the future.
+
+#### PostgreSQL
+
+The `psql` indexer type allows an operator to enable block and transaction event
+indexing by proxying it to an external PostgreSQL instance allowing for the events
+to be stored in relational models. Since the events are stored in a RDBMS, operators
+can leverage SQL to perform a series of rich and complex queries that are not
+supported by the `kv` indexer type. Since operators can leverage SQL directly,
+searching is not enabled for the `psql` indexer type via Tendermint's RPC -- any
+such query will fail.
+
+Note, the SQL schema is stored in `state/indexer/sink/psql/schema.sql` and operators
+must explicitly create the relations prior to starting Tendermint and enabling
+the `psql` indexer type.
+
+Example:
+
+```shell
+$ psql ... -f state/indexer/sink/psql/schema.sql
+```
--- a/docs/tutorials/go-built-in.md
+++ b/docs/tutorials/go-built-in.md
@@ -23,6 +23,8 @@ yourself with the syntax.
 By following along with this guide, you'll create a Tendermint Core project
 called kvstore, a (very) simple distributed BFT key-value store.

+> Note: please use a released version of Tendermint with this guide. The guides will work with the latest version. Please, do not use master. 
+
 ## Built-in app vs external app

 Running your application inside the same process as Tendermint Core will give
@@ -50,10 +52,13 @@ We'll start by creating a new Go project.
 ```bash
 mkdir kvstore
 cd kvstore
+go mod init github.com/<github_username>/<repo_name>
 ```

 Inside the example directory create a `main.go` file with the following content:

+> Note: there is no need to clone or fork Tendermint in this tutorial. 
+
 ```go
 package main