From 299d46304decdf9eb68225e7e6615b2fa7ae1ba2 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Thu, 6 Sep 2018 22:35:31 -0400 Subject: [PATCH] update UPGRADING.md and minor docs fixes --- CHANGELOG.md | 13 ++++++++++--- UPGRADING.md | 38 ++++++++++++++++++++++++++++++++++---- docs/spec/software/abci.md | 2 +- 3 files changed, 45 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14615ab16..726ca9aed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,9 +9,13 @@ peerlink, Ahmah2009, bluele, b00f. This release includes breaking upgrades in the block header, including the long awaited changes for delaying validator set updates by one -block. It also fixes enforcement on the max size of blocks, and includes a BFT -timestamp in each block that can be safely used by applications. There are also some -minor breaking changes to the rpc, config, and ABCI. +block to better support light clients. +It also fixes enforcement on the maximum size of blocks, and includes a BFT +timestamp in each block that can be safely used by applications. +There are also some minor breaking changes to the rpc, config, and ABCI. + +See the [UPGRADING.md](UPGRADING.md#v0.24.0) for details on upgrading to the new +version. From here on, breaking changes will be broken down to better reflect how users are affected by a change. @@ -20,6 +24,8 @@ A few more breaking changes are in the works - each will come with a clear Architecture Decision Record (ADR) explaining the change. You can review ADRs [here](https://github.com/tendermint/tendermint/tree/develop/docs/architecture) or in the [open Pull Requests](https://github.com/tendermint/tendermint/pulls). +You can also check in on the [issues marked as +breaking](https://github.com/tendermint/tendermint/issues?q=is%3Aopen+is%3Aissue+label%3Abreaking). BREAKING CHANGES: @@ -84,6 +90,7 @@ FEATURES: IMPROVEMENTS: - [docs] Lint documentation with `write-good` and `stop-words`. +- [docs] [\#2249](https://github.com/tendermint/tendermint/issues/2249) Refactor, deduplicate, and improve the ABCI docs and spec (with thanks to @ttmc). - [scripts] [\#2196](https://github.com/tendermint/tendermint/issues/2196) Added json2wal tool, which is supposed to help our users restore (@bradyjoestar) corrupted WAL files and compose test WAL files (@bradyjoestar) - [mempool] [\#2234](https://github.com/tendermint/tendermint/issues/2234) Now stores txs by hash inside of the cache, to mitigate memory leakage diff --git a/UPGRADING.md b/UPGRADING.md index a290d57d7..66a78295e 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -3,10 +3,11 @@ This guide provides steps to be followed when you upgrade your applications to a newer version of Tendermint Core. -## Upgrading from 0.23.0 to 0.24.0 +## v0.24.0 New 0.24.0 release contains a lot of changes to the state and types. It's not -compatible to the old versions. +compatible to the old versions and there is no straight forward way to update +old data to be compatible with the new version. To reset the state do: @@ -14,10 +15,12 @@ To reset the state do: $ tendermint unsafe_reset_all ``` +Here we summarize some other notable changes to be mindful of. + ### Config changes `p2p.max_num_peers` was removed in favor of `p2p.max_num_inbound_peers` and -`p2p.max_num_outbound_peers`. +`p2p.max_num_outbound_peers`. ``` # Maximum number of inbound peers @@ -28,5 +31,32 @@ max_num_outbound_peers = 10 ``` As you can see, the default ratio of inbound/outbound peers is 4/1. The reason -as we want it to be easier for new nodes to connect to the network. You can +is we want it to be easier for new nodes to connect to the network. You can tweak these parameters to alter the network topology. + +### RPC Changes + +The result of `/commit` used to contain `header` and `commit` fields at the top level. These are now contained under the `signed_header` field. + +### ABCI Changes + +The header has been upgraded and contains new fields, but none of the existing +fields were changed, except their order. + +The `Validator` type was split into two, one containing an `Address` and one +containing a `PubKey`. When processing `RequestBeginBlock`, use the `Validator` +type, which contains just the `Address`. When returning `ResponseEndBlock`, use +the `ValidatorUpdate` type, which contains just the `PubKey`. + +### Validator Set Updates + +Validator set updates returned in ResponseEndBlock for height `H` used to take +effect immediately at height `H+1`. Now they will be delayed one block, to take +effect at height `H+2`. Note this means that the change will be seen by the ABCI +app in the `RequestBeginBlock.LastCommitInfo` at block `H+3`. + +### Block Size + +The `ConsensusParams.BlockSize.MaxTxs` was removed in favour of +`ConsensusParams.BlockSize.MaxBytes`, which is now enforced. This means blocks +are limitted only by byte-size, not by number of transactions. diff --git a/docs/spec/software/abci.md b/docs/spec/software/abci.md index 44d48f170..6e17089f3 100644 --- a/docs/spec/software/abci.md +++ b/docs/spec/software/abci.md @@ -1,3 +1,3 @@ # Application Blockchain Interface (ABCI) -This page has [moved](../spec/abci/apps.md). +This page has [moved](../abci/apps.md).