From 8e21b7dc793faea1dae185fcdb176c837d365e16 Mon Sep 17 00:00:00 2001 From: Marko Date: Mon, 31 Aug 2020 18:11:37 +0200 Subject: [PATCH] docs: add doc on state sync configuration (#5304) Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> --- docs/tendermint-core/README.md | 1 + docs/tendermint-core/light-client.md | 7 ++- docs/tendermint-core/mempool.md | 2 +- docs/tendermint-core/running-in-production.md | 7 +-- docs/tendermint-core/state-sync.md | 48 +++++++++++++++++++ 5 files changed, 55 insertions(+), 10 deletions(-) create mode 100644 docs/tendermint-core/state-sync.md diff --git a/docs/tendermint-core/README.md b/docs/tendermint-core/README.md index d424ed752..c97980e1c 100644 --- a/docs/tendermint-core/README.md +++ b/docs/tendermint-core/README.md @@ -17,5 +17,6 @@ This section dives into the internals of Tendermint the implementation. - [Block Structure](./block-structure.md) - [RPC](./rpc.md) - [Fast Sync](./fast-sync.md) +- [State Sync](./state-sync.md) - [Mempool](./mempool.md) - [Light Client](./light-client.md) diff --git a/docs/tendermint-core/light-client.md b/docs/tendermint-core/light-client.md index 335e69636..cf4537097 100644 --- a/docs/tendermint-core/light-client.md +++ b/docs/tendermint-core/light-client.md @@ -1,5 +1,5 @@ --- -order: 11 +order: 12 --- # Light Client @@ -16,8 +16,7 @@ package](https://pkg.go.dev/github.com/tendermint/tendermint/light?tab=doc). The objective of the light client protocol is to get a commit for a recent block hash where the commit includes a majority of signatures from the last known validator set. From there, all the application state is verifiable with -[merkle -proofs](https://github.com/tendermint/spec/blob/953523c3cb99fdb8c8f7a2d21e3a99094279e9de/spec/blockchain/encoding.md#iavl-tree). +[merkle proofs](https://github.com/tendermint/spec/blob/953523c3cb99fdb8c8f7a2d21e3a99094279e9de/spec/blockchain/encoding.md#iavl-tree). ## Properties @@ -49,7 +48,7 @@ $ curl -s https://233.123.0.140:26657:26657/commit | jq "{height: .result.signed ## Running a light client as an HTTP proxy server Tendermint comes with a built-in `tendermint light` command, which can be used -to run a light client proxy server, verifying Tendermint rpc. All calls that +to run a light client proxy server, verifying Tendermint RPC. All calls that can be tracked back to a block header by a proof will be verified before passing them back to the caller. Other than that, it will present the same interface as a full Tendermint node. diff --git a/docs/tendermint-core/mempool.md b/docs/tendermint-core/mempool.md index 23bba1aa4..da4b88d3d 100644 --- a/docs/tendermint-core/mempool.md +++ b/docs/tendermint-core/mempool.md @@ -1,5 +1,5 @@ --- -order: 10 +order: 11 --- # Mempool diff --git a/docs/tendermint-core/running-in-production.md b/docs/tendermint-core/running-in-production.md index 2b6a21a31..1170fe257 100644 --- a/docs/tendermint-core/running-in-production.md +++ b/docs/tendermint-core/running-in-production.md @@ -7,10 +7,7 @@ order: 4 ## Database By default, Tendermint uses the `syndtr/goleveldb` package for its in-process -key-value database. Unfortunately, this implementation of LevelDB seems to suffer under heavy load (see -[#226](https://github.com/syndtr/goleveldb/issues/226)). It may be best to -install the real C-implementation of LevelDB and compile Tendermint to use -that using `make build TENDERMINT_BUILD_OPTIONS=cleveldb`. See the [install instructions](../introduction/install.md) for details. +key-value database. Tendermint keeps multiple distinct databases in the `$TMROOT/data`: @@ -30,7 +27,7 @@ details. Applications can expose block pruning strategies to the node operator. Please read the documentation of your application to find out more details. -Applications can use State Sync to help nodes bootstrap quickly. +Applications can use [state sync](state-sync.md) to help nodes bootstrap quickly. ## Logging diff --git a/docs/tendermint-core/state-sync.md b/docs/tendermint-core/state-sync.md new file mode 100644 index 000000000..d5e54e4b7 --- /dev/null +++ b/docs/tendermint-core/state-sync.md @@ -0,0 +1,48 @@ +--- +order: 10 +--- + +# State Sync + +With fast sync a node is downloading all of the data of an application from genesis and verifying it. +With state sync your node will download data related to the head or near the head of the chain and verify the data. +This leads to drastically shorter times for joining a network. + +## Using State Sync + +State sync will continuously work in the background to supply nodes with chunked data when bootstrapping. + +> NOTE: Before trying to use state sync, see if the application you are operating a node for supports it. + +Under the state sync section in `config.toml` you will find multiple settings that need to be configured in order for your node to use state sync. + +Lets breakdown the settings: + +- `enable`: Enable is to inform the node that you will be using state sync to bootstrap your node. +- `rpc_servers`: RPC servers are needed because state sync utilizes the light client for verification. + - 2 servers are required, more is always helpful. +- `temp_dir`: Temporary directory is store the chunks in the machines local storage, If nothing is set it will create a directory in `/tmp` + +The next information you will need to acquire it through publicly exposed RPC's or a block explorer which you trust. + +- `trust_height`: Trusted height defines at which height your node should trust the chain. +- `trust_hash`: Trusted hash is the hash in the `BlockID` corresponding to the trusted height. +- `trust_period`: Trust period is the period in which headers can be verified. + > :warning: This value should be significantly smaller than the unbonding period. + +If you are relying on publicly exposed RPC's to get the need information, you can use `curl`. + +Example: + +```bash +curl -s https://233.123.0.140:26657:26657/commit | jq "{height: .result.signed_header.header.height, hash: .result.signed_header.commit.block_id.hash}" +``` + +The response will be: + +```json +{ + "height": "273", + "hash": "188F4F36CBCD2C91B57509BBF231C777E79B52EE3E0D90D06B1A25EB16E6E23D" +} +```