mirrors/tendermint
1
0
Fork 0
mirror of https://github.com/tendermint/tendermint.git synced 2025-12-23 06:15:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: updates to various sections (#5285)

Browse Source 
## Description

Updates to various sections of docs. 
Fix docs deployment

Closes: #XXX
This commit is contained in:
Marko
2020-08-26 15:59:26 +02:00
committed by GitHub
parent 4827ed121f
commit 5df55f289c
12 changed files with 186 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.circleci/config.yml
View File

@@ -100,6 +100,9 @@ jobs:
executor: docs
steps:
- checkout
- run:
name: "Pull versions"
command: git fetch origin v0.32 v0.33
- run:
name: "Build docs"
command: make build-docs

29
README.md
View File

@@ -28,8 +28,7 @@ see our recent paper, "[The latest gossip on BFT consensus](https://arxiv.org/ab
## Releases
NOTE: The master branch is now an active development branch (starting with `v0.32`). Please, do not depend on it and
use [releases](https://github.com/tendermint/tendermint/releases) instead.
Note: Please, do not depend on master as your production branch, use [releases](https://github.com/tendermint/tendermint/releases) instead.
Tendermint is being used in production in both private and public environments,
most notably the blockchains of the [Cosmos Network](https://cosmos.network/).
@@ -37,7 +36,7 @@ However, we are still making breaking changes to the protocol and the APIs and h
See below for more details about [versioning](#versioning).
In any case, if you intend to run Tendermint in production,
please [contact us](mailto:partners@tendermint.com) and [join the chat](https://discord.gg/AzefAFd).
please [contact us](mailto:hello@interchain.berlin) and [join the chat](https://discord.gg/AzefAFd).
## Security
@@ -96,16 +95,24 @@ That said, breaking changes in the following packages will be documented in the
CHANGELOG even if they don't lead to MINOR version bumps:
- crypto
- types
- rpc/client
- config
- node
- libs
- bech32
- common
- db
- errors
- bits
- bytes
- json
- log
- math
- net
- os
- protoio
- rand
- sync
- strings
- service
- node
- rpc/client
- types
Exported objects in these packages that are not covered by the versioning scheme
are explicitly marked by `// UNSTABLE` in their go doc comment and may change at any
@@ -115,7 +122,7 @@ time without notice. Functions, types, and values in any other package may also
In an effort to avoid accumulating technical debt prior to 1.0.0,
we do not guarantee that breaking changes (ie. bumps in the MINOR version)
will work with existing tendermint blockchains. In these cases you will
will work with existing Tendermint blockchains. In these cases you will
have to start a new blockchain, or write something custom to get the old
data into the new chain.
@@ -149,8 +156,6 @@ Additional documentation is found [here](/docs/tools).
### Sub-projects
- [Amino](http://github.com/tendermint/go-amino), reflection-based proto3, with
interfaces
- [IAVL](http://github.com/tendermint/iavl), Merkleized IAVL+ Tree implementation
- [Tm-db](http://github.com/tendermint/tm-db), Data Base abstractions to be used in applications.

1
docs/.python-version
View File

@@ -1 +0,0 @@
2.7.14

2
docs/introduction/README.md
View File

@@ -1,5 +1,5 @@
---
order: 1
order: false
parent:
title: Introduction
order: 1

10
docs/introduction/install.md
View File

@@ -21,8 +21,6 @@ echo export PATH=\"\$PATH:\$GOPATH/bin\" >> ~/.bash_profile
### Get Source Code
```sh
mkdir -p $GOPATH/src/github.com/tendermint
cd $GOPATH/src/github.com/tendermint
git clone https://github.com/tendermint/tendermint.git
cd tendermint
```
@@ -47,12 +45,12 @@ make build
to put the binary in `./build`.
_DISCLAIMER_ The binary of tendermint is build/installed without the DWARF
symbol table. If you would like to build/install tendermint with the DWARF
_DISCLAIMER_ The binary of Tendermint is build/installed without the DWARF
symbol table. If you would like to build/install Tendermint with the DWARF
symbol and debug information, remove `-s -w` from `BUILD_FLAGS` in the make
file.
The latest tendermint is now installed. You can verify the installation by
The latest Tendermint is now installed. You can verify the installation by
running:
```sh
@@ -73,14 +71,12 @@ tendermint node --proxy_app=kvstore
If you already have Tendermint installed, and you make updates, simply
```sh
cd $GOPATH/src/github.com/tendermint/tendermint
make install
```
To upgrade, run
```sh
cd $GOPATH/src/github.com/tendermint/tendermint
git pull origin master
make install
```

2
docs/introduction/quick-start.md
View File

@@ -56,7 +56,7 @@ Configuring a cluster is covered further below.
## Local Node
Start tendermint with a simple in-process application:
Start Tendermint with a simple in-process application:
```sh
tendermint node --proxy_app=kvstore

126
docs/tendermint-core/configuration.md
View File

@@ -25,7 +25,9 @@ like the file below, however, double check by inspecting the
# "$HOME/.tendermint" by default, but could be changed via $TMHOME env variable
# or --home cmd flag.
##### main base config options #####
#######################################################################
### Main Base Config Options ###
#######################################################################
# TCP or UNIX socket address of the ABCI application,
# or the name of an ABCI application compiled in with the Tendermint binary
@@ -64,7 +66,7 @@ db_backend = "goleveldb"
db_dir = "data"
# Output level for logging, including package level options
log_level = "main:info,state:info,*:error"
log_level = "main:info,state:info,statesync:info,*:error"
# Output format: 'plain' (colored text) or 'json'
log_format = "plain"
@@ -75,7 +77,10 @@ log_format = "plain"
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_file = "config/priv_validator.json"
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
@@ -94,13 +99,18 @@ prof_laddr = ""
# so the app can decide if we should keep the connection or not
filter_peers = false
##### advanced configuration options #####
##### rpc server configuration options #####
#######################################################################
### Advanced Configuration Options ###
#######################################################################
#######################################################
### RPC Server Configuration Options ###
#######################################################
[rpc]
# TCP or UNIX socket address for the RPC server to listen on
laddr = "tcp://0.0.0.0:26657"
laddr = "tcp://127.0.0.1:26657"
# A list of origins a cross-domain request can be executed from
# Default value '[]' disables cors support
@@ -108,10 +118,10 @@ laddr = "tcp://0.0.0.0:26657"
cors_allowed_origins = []
# A list of methods the client is allowed to use with cross-domain requests
cors_allowed_methods = ["HEAD", "GET", "POST"]
cors_allowed_methods = ["HEAD", "GET", "POST", ]
# A list of non simple headers the client is allowed to use with cross-domain requests
cors_allowed_headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"]
cors_allowed_headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time", ]
# TCP or UNIX socket address for the gRPC server to listen on
# NOTE: This server only supports /broadcast_tx_commit
@@ -155,25 +165,29 @@ max_subscriptions_per_client = 5
timeout_broadcast_tx_commit = "10s"
# Maximum size of request body, in bytes
max_body_bytes = {{ .RPC.MaxBodyBytes }}
max_body_bytes = 1000000
# Maximum size of request header, in bytes
max_header_bytes = {{ .RPC.MaxHeaderBytes }}
max_header_bytes = 1048576
# The path to a file containing certificate that is used to create the HTTPS server.
# Migth be either absolute path or path related to tendermint's config directory.
# If the certificate is signed by a certificate authority,
# the certFile should be the concatenation of the server's certificate, any intermediates,
# and the CA's certificate.
# NOTE: both tls_cert_file and tls_key_file must be present for Tendermint to create HTTPS server. Otherwise, HTTP server is run.
# NOTE: both tls_cert_file and tls_key_file must be present for Tendermint to create HTTPS server.
# Otherwise, HTTP server is run.
tls_cert_file = ""
# The path to a file containing matching private key that is used to create the HTTPS server.
# Migth be either absolute path or path related to tendermint's config directory.
# NOTE: both tls_cert_file and tls_key_file must be present for Tendermint to create HTTPS server. Otherwise, HTTP server is run.
# NOTE: both tls_cert_file and tls_key_file must be present for Tendermint to create HTTPS server.
# Otherwise, HTTP server is run.
tls_key_file = ""
##### peer to peer configuration options #####
#######################################################
### P2P Configuration Options ###
#######################################################
[p2p]
# Address to listen for incoming connections
@@ -207,6 +221,12 @@ max_num_inbound_peers = 40
# Maximum number of outbound peers to connect to, excluding persistent peers
max_num_outbound_peers = 10
# List of node IDs, to which a connection will be (re)established ignoring any existing limits
unconditional_peer_ids = ""
# Maximum pause when redialing a persistent peer (if zero, exponential backoff is used)
persistent_peers_max_dial_period = "0s"
# Time to wait before flushing messages out on the connection
flush_throttle_timeout = "100ms"
@@ -238,7 +258,9 @@ allow_duplicate_ip = false
handshake_timeout = "20s"
dial_timeout = "3s"
##### mempool configuration options #####
#######################################################
### Mempool Configurattion Option ###
#######################################################
[mempool]
recheck = true
@@ -257,19 +279,49 @@ max_txs_bytes = 1073741824
cache_size = 10000
# Maximum size of a single transaction.
# NOTE: the max size of a tx transmitted over the network is {max_tx_bytes} + {amino overhead}.
# NOTE: the max size of a tx transmitted over the network is {max_tx_bytes}.
max_tx_bytes = 1048576
##### fast sync configuration options #####
#######################################################
### State Sync Configuration Options ###
#######################################################
[statesync]
# State sync rapidly bootstraps a new node by discovering, fetching, and restoring a state machine
# snapshot from peers instead of fetching and replaying historical blocks. Requires some peers in
# the network to take and serve state machine snapshots. State sync is not attempted if the node
# has any local state (LastBlockHeight > 0). The node will have a truncated block history,
# starting from the height of the snapshot.
enable = false
# RPC servers (comma-separated) for light client verification of the synced state machine and
# retrieval of state data for node bootstrapping. Also needs a trusted height and corresponding
# header hash obtained from a trusted source, and a period during which validators can be trusted.
#
# For Cosmos SDK-based chains, trust_period should usually be about 2/3 of the unbonding time (~2
# weeks) during which they can be financially punished (slashed) for misbehavior.
rpc_servers = ""
trust_height = 0
trust_hash = ""
trust_period = "0s"
# Temporary directory for state sync snapshot chunks, defaults to the OS tempdir (typically /tmp).
# Will create a new, randomly named directory within, and remove it when done.
temp_dir = ""
#######################################################
### Fast Sync Configuration Connections ###
#######################################################
[fastsync]
# Fast Sync version to use:
# 1) "v0" (default) - the legacy fast sync implementation
# 2) "v1" - refactor of v0 version for better testability
# 2) "v2" - complete redesign of v0, optimized for testability & readability
# 2) "v2" - complete redesign of v0, optimized for testability & readability
version = "v0"
##### consensus configuration options #####
#######################################################
### Consensus Configuration Options ###
#######################################################
[consensus]
wal_file = "data/cs.wal/wal"
@@ -293,42 +345,25 @@ create_empty_blocks_interval = "0s"
peer_gossip_sleep_duration = "100ms"
peer_query_maj23_sleep_duration = "2s"
# Block time parameters. Corresponds to the minimum time increment between consecutive blocks.
blocktime_iota = "1s"
##### transactions indexer configuration options #####
#######################################################
### Transaction Indexer Configuration Options ###
#######################################################
[tx_index]
# What indexer to use for transactions
#
# 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.
#
# 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"
# Comma-separated list of compositeKeys to index (by default the only key is "tx.hash")
# Remember that Event has the following structure: type.key
# type: [
# key: value,
# ...
# ]
#
# You can also index transactions by height by adding "tx.height" event here.
#
# It's recommended to index only a subset of keys due to possible memory
# bloat. This is, of course, depends on the indexer's DB and the volume of
# transactions.
index_keys = ""
# When set to true, tells indexer to index all compositeKeys (predefined keys:
# "tx.hash", "tx.height" and all keys from DeliverTx responses).
#
# Note this may be not desirable (see the comment above). IndexEvents has a
# precedence over IndexAllEvents (i.e. when given both, IndexEvents will be
# indexed).
index_all_keys = false
##### instrumentation configuration options #####
#######################################################
### Instrumentation Configuration Options ###
#######################################################
[instrumentation]
# When true, Prometheus metrics are served under /metrics on
@@ -347,6 +382,7 @@ max_open_connections = 3
# Instrumentation namespace
namespace = "tendermint"
```
## Empty blocks VS no empty blocks

16
docs/tendermint-core/fast-sync.md
View File

@@ -28,5 +28,21 @@ has at least one peer and it's height is at least as high as the max
reported peer height. See [the IsCaughtUp
method](https://github.com/tendermint/tendermint/blob/b467515719e686e4678e6da4e102f32a491b85a0/blockchain/pool.go#L128).
Note: There are three versions of fast sync. We recommend using v0 as v1 and v2 are still in beta.
If you would like to use a different version you can do so by changing the version in the `config.toml`:
```toml
#######################################################
### Fast Sync Configuration Connections ###
#######################################################
[fastsync]
# Fast Sync version to use:
# 1) "v0" (default) - the legacy fast sync implementation
# 2) "v1" - refactor of v0 version for better testability
# 2) "v2" - complete redesign of v0, optimized for testability & readability
version = "v0"
```
If we're lagging sufficiently, we should go back to fast syncing, but
this is an [open issue](https://github.com/tendermint/tendermint/issues/129).

30
docs/tendermint-core/mempool.md
View File

@@ -13,36 +13,36 @@ So the only way to specify the order is to send them to a single node.
valA:
- tx1
- tx2
- tx3
- `tx1`
- `tx2`
- `tx3`
If the transactions are split up across different nodes, there's no way to
ensure they are processed in the expected order.
valA:
- tx1
- tx2
- `tx1`
- `tx2`
valB:
- tx3
- `tx3`
If valB is the proposer, the order might be:
- tx3
- tx1
- tx2
- `tx3`
- `tx1`
- `tx2`
If valA is the proposer, the order might be:
- tx1
- tx2
- tx3
- `tx1`
- `tx2`
- `tx3`
That said, if the transactions contain some internal value, like an
order/nonce/sequence number, the application can reject transactions that are
out of order. So if a node receives tx3, then tx1, it can reject tx3 and then
accept tx1. The sender can then retry sending tx3, which should probably be
rejected until the node has seen tx2.
out of order. So if a node receives `tx3`, then `tx1`, it can reject `tx3` and then
accept `tx1`. The sender can then retry sending `tx3`, which should probably be
rejected until the node has seen `tx2`.

26
docs/tendermint-core/running-in-production.md
View File

@@ -27,28 +27,20 @@ By default, Tendermint will only index txs by their hash and height, not by thei
result events. See [indexing transactions](../app-dev/indexing-transactions.md) for
details.
There is no current strategy for pruning the databases. Consider reducing
block production by [controlling empty blocks](../tendermint-core/using-tendermint.md#no-empty-blocks)
or by increasing the `consensus.timeout_commit` param. Note both of these are
local settings and not enforced by the consensus.
Applications can expose block pruning strategies to the node operator. Please read the documentation of your application
to find out more details.
We're working on [state
syncing](https://github.com/tendermint/tendermint/issues/828),
which will enable history to be thrown away
and recent application state to be directly synced. We'll need to develop solutions
for archival nodes that allow queries on historical transactions and states.
The Cosmos project has had much success just dumping the latest state of a
blockchain to disk and starting a new chain from that state.
Applications can use State Sync <!--- TODO: add link to state sync doc when created ---> to help nodes bootstrap quickly.
## Logging
Default logging level (`main:info,state:info,*:`) should suffice for
Default logging level (`log_level = "main:info,state:info,statesync:info,*:error"`) should suffice for
normal operation mode. Read [this
post](https://blog.cosmos.network/one-of-the-exciting-new-features-in-0-10-0-release-is-smart-log-level-flag-e2506b4ab756)
for details on how to configure `log_level` config variable. Some of the
modules can be found [here](./how-to-read-logs.md#list-of-modules). If
you're trying to debug Tendermint or asked to provide logs with debug
logging level, you can do so by running tendermint with
logging level, you can do so by running Tendermint with
`--log_level="*:debug"`.
## Write Ahead Logs (WAL)
@@ -86,8 +78,7 @@ For the above reasons, the `mempool.wal` is disabled by default. To enable, set
Validators are supposed to setup [Sentry Node
Architecture](./validators.md)
to prevent Denial-of-service attacks. You can read more about it
[here](../interviews/tendermint-bft.md).
to prevent Denial-of-service attacks.
### P2P
@@ -98,7 +89,7 @@ send & receive rate per connection (`SendRate`, `RecvRate`).
The number of open P2P connections can become quite large, and hit the operating system's open
file limit (since TCP connections are considered files on UNIX-based systems). Nodes should be
given a sizeable open file limit, e.g. 8192, via `ulimit -n 8192` or other deployment-specific
given a sizable open file limit, e.g. 8192, via `ulimit -n 8192` or other deployment-specific
mechanisms.
### RPC
@@ -108,8 +99,7 @@ elements (100 max). See the [RPC Documentation](https://docs.tendermint.com/mast
for more information.
Rate-limiting and authentication are another key aspects to help protect
against DOS attacks. While in the future we may implement these
features, for now, validators are supposed to use external tools like
against DOS attacks. Validators are supposed to use external tools like
[NGINX](https://www.nginx.com/blog/rate-limiting-nginx/) or
[traefik](https://docs.traefik.io/middlewares/ratelimit/)
to achieve the same things.

18
docs/tendermint-core/using-tendermint.md
View File

@@ -47,6 +47,7 @@ definition](https://github.com/tendermint/tendermint/blob/master/types/genesis.g
- `chain_id`: ID of the blockchain. **This must be unique for
every blockchain.** If your testnet blockchains do not have unique
chain IDs, you will have a bad time. The ChainID must be less than 50 symbols.
- `initial_height`: Height at which Tendermint should begin at.
- `consensus_params` [spec](https://github.com/tendermint/spec/blob/master/spec/core/state.md#consensusparams)
- `block`
- `max_bytes`: Max block size, in bytes.
@@ -92,6 +93,7 @@ definition](https://github.com/tendermint/tendermint/blob/master/types/genesis.g
{
"genesis_time": "2020-04-21T11:17:42.341227868Z",
"chain_id": "test-chain-ROp9KF",
"initial_height": "0",
"consensus_params": {
"block": {
"max_bytes": "22020096",
@@ -100,7 +102,9 @@ definition](https://github.com/tendermint/tendermint/blob/master/types/genesis.g
},
"evidence": {
"max_age_num_blocks": "100000",
"max_age_duration": "172800000000000"
"max_age_duration": "172800000000000",
"max_num": 50,
"proof_trial_period": "5000000"
},
"validator": {
"pub_key_types": [
@@ -177,17 +181,12 @@ and the `latest_app_hash` in particular:
curl http://localhost:26657/status | json_pp | grep latest_app_hash
```
<!-- markdown-link-check-disable -->
Visit `http://localhost:26657` in your browser to see the list of other
endpoints. Some take no arguments (like `/status`), while others specify
the argument name and use `_` as a placeholder.
<!-- markdown-link-check-enable -->
::: tip
Find the RPC Documentation [here](https://docs.tendermint.com/master/rpc/)
:::
> TIP: Find the RPC Documentation [here](https://docs.tendermint.com/master/rpc/)
### Formatting
@@ -239,10 +238,9 @@ Note that raw hex cannot be used in `POST` transactions.
## Reset
::: warning
**UNSAFE** Only do this in development and only if you can
> :warning: **UNSAFE** Only do this in development and only if you can
afford to lose all blockchain data!
:::
To reset a blockchain, stop the node and run:

73
rpc/openapi/openapi.yaml
View File

@@ -520,20 +520,25 @@ paths:
schema:
$ref: "#/components/schemas/ErrorResponse"
/dial_seeds:
post:
get:
summary: Dial Seeds (Unsafe)
operationId: dial_seeds
tags:
- Unsafe
description: |
Dial a peer, this route in under unsafe, and has to manually enabled to use
requestBody:
description: string of possible peers
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/dialSeedsPost"
**Example:** curl 'localhost:26657/dial_seeds?seeds=\["f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:26656","0491d373a8e0fcf1023aaf18c51d6a1d0d4f31bd@5.6.7.8:26656"\]'
parameters:
- in: query
name: peers
description: list of seed nodes to dial
schema:
type: array
items:
type: string
example:
["f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:26656"]
responses:
"200":
description: Dialing seeds in progress. See /net_info for details
@@ -548,20 +553,31 @@ paths:
schema:
$ref: "#/components/schemas/ErrorResponse"
/dial_peers:
post:
get:
summary: Add Peers/Persistent Peers (unsafe)
operationId: dial_peers
tags:
- Unsafe
description: |
Set a persistent peer, this route in under unsafe, and has to manually enabled to use
requestBody:
description: string of possible peers, bool argument if they should be added as persistent
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/dialPeersPost"
Set a persistent peer, this route in under unsafe, and has to manually enabled to use.
**Example:** curl 'localhost:26657/dial_peers?peers=\["f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:26656","0491d373a8e0fcf1023aaf18c51d6a1d0d4f31bd@5.6.7.8:26656"\]&persistent=false'
parameters:
- in: query
name: persistent
description: Have the peers you are dialing be persistent
schema:
type: boolean
example: true
- in: query
name: peers
description: array of peers to dial
schema:
type: array
items:
type: string
example:
["f9baeaa15fedf5e1ef7448dd60f46c01f1a9e9c4@1.2.3.4:26656"]
responses:
"200":
description: Dialing seeds in progress. See /net_info for details
@@ -2649,29 +2665,6 @@ components:
type: string
example: ""
dialPeersPost:
type: object
properties:
Persistent:
type: boolean
example: false
Peers:
type: array
items:
type: string
example:
["6f172048b821e3b1ab98ffb0973ba737966eecf8@192.168.1.2:26656"]
dialSeedsPost:
type: object
properties:
Peers:
type: array
items:
type: string
example:
["6f172048b821e3b1ab98ffb0973ba737966eecf8@192.168.1.2:26656"]
dialResp:
type: object
properties: