From 3c79251ffc93d4653e42083c20c6d62c4a177efa Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Mon, 22 Jun 2020 16:27:43 +0400 Subject: [PATCH] Update UPGRADING.md and bump p2p/block protocol versions (#5038) Closes #4411 --- CHANGELOG.md | 2 +- CONTRIBUTING.md | 22 ++++++--- UPGRADING.md | 111 +++++++++++++++++++++++++++++++++++---------- version/version.go | 4 +- 4 files changed, 106 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a74183ce5..76cb3a55c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## v.0.33.5 +## v0.33.5 Special thanks to external contributors on this release: @tau3, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10db28188..4f8b80704 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -191,6 +191,10 @@ To begin contributing, create a development branch either on github.com/tendermi Make changes, and before submitting a pull request, update the `CHANGELOG_PENDING.md` to record your change. Also, run either `git rebase` or `git merge` on top of the latest `master`. (Since pull requests are squash-merged, either is fine!) +Update the `UPGRADING.md` if the change you've made is breaking and the +instructions should be in place for a user on how he/she can upgrade it's +software (ABCI application, Tendermint-based blockchain, light client, wallet). + Once you have submitted a pull request label the pull request with either `R:minor`, if the change should be included in the next minor release, or `R:major`, if the change is meant for a major release. Sometimes (often!) pull requests get out-of-date with master, as other people merge different pull requests to master. It is our convention that pull request authors are responsible for updating their branches with master. (This also means that you shouldn't update someone else's branch for them; even if it seems like you're doing them a favor, you may be interfering with their git flow in some way!) @@ -249,7 +253,10 @@ Each PR should have one commit once it lands on `master`; this can be accomplish release, and add the github aliases of external contributors to the top of the changelog. To lookup an alias from an email, try `bash ./scripts/authors.sh ` - reset the `CHANGELOG_PENDING.md` - - bump the appropriate versions in `version.go` + - bump Tendermint version in `version.go` + - bump P2P and block protocol versions in `version.go`, if necessary + - bump ABCI protocol version in `version.go`, if necessary + - make sure all significant breaking changes are covered in `UPGRADING.md` 4. push your changes with prepared release details to `vX.X` (this will trigger the release `vX.X.0`) 5. merge back to master (don't squash merge!) @@ -260,11 +267,14 @@ Minor releases are done differently from major releases: They are built off of l 1. Checkout the long-lived release candidate branch: `git checkout rcX/vX.X.X` 2. Run integration tests: `make test_integrations` 3. Prepare the release: - - Copy `CHANGELOG_PENDING.md` to top of `CHANGELOG.md` - - Run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for all issues - - Run `bash ./scripts/authors.sh` to get a list of authors since the latest release, and add the GitHub aliases of external contributors to the top of the CHANGELOG. To lookup an alias from an email, try `bash ./scripts/authors.sh ` - - Reset the `CHANGELOG_PENDING.md` - - Bump the appropriate versions in `version.go` + - copy `CHANGELOG_PENDING.md` to top of `CHANGELOG.md` + - run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for all issues + - run `bash ./scripts/authors.sh` to get a list of authors since the latest release, and add the GitHub aliases of external contributors to the top of the CHANGELOG. To lookup an alias from an email, try `bash ./scripts/authors.sh ` + - reset the `CHANGELOG_PENDING.md` + - bump Tendermint version in `version.go` + - bump P2P and block protocol versions in `version.go`, if necessary + - bump ABCI protocol version in `version.go`, if necessary + - make sure all significant breaking changes are covered in `UPGRADING.md` 4. Create a release branch `release/vX.X.x` off the release candidate branch: - `git checkout -b release/vX.X.x` - `git push -u origin release/vX.X.x` diff --git a/UPGRADING.md b/UPGRADING.md index a60c7ef02..0b0564c15 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -5,31 +5,43 @@ a newer version of Tendermint Core. ## v0.34.0 -This release is not compatible with previous blockchains due to switching from -amino to proto3 encoding and breaking changes to the header. +**This release is not compatible with previous blockchains** due to switching +from amino to proto3 encoding and breaking changes to the header. -### Blockchain Protocol +### ABCI application changes -- `Header#LastResultsHash`, which previously was the root hash of a Merkle tree - built from `ResponseDeliverTx(Code, Data)` responses, became the root hash of - a Merkle tree built from: - - `BeginBlock#Events`; - - root hash of a Merkle tree built from `ResponseDeliverTx(Code, Data, GasWanted, GasUsed, Events)` responses; - - `BeginBlock#Events`. +New ABCI methods (`ListSnapshots`, `LoadSnapshotChunk`, `OfferSnapshot`, and +`ApplySnapshotChunk`) were added for the highly anticipated state sync feature. +With it, new nodes are able to join the network in a matter of seconds. Read +[the spec](https://docs.tendermint.com/master/spec/abci/apps.html#state-sync) +if you want to learn more & support it (with cosmos-sdk you get it + automatically). If you don't want to support it, just leave these methods + empty. -### Events +`KV.Pair` has been replaced with `abci.EventAttribute`. `EventAttribute.Index` +field allows ABCI applications to dictate which events should be indexed +ignoring the `tx_index.index_keys` config setting. See +[\#4877](https://github.com/tendermint/tendermint/issues/4877), where we're +discussing future direction of indexing. -- `KV.Pair` has been replaced with `abci.EventAttribute`. This allows - applications to indicate if a msg should be indexed at runtime. Previously - this was only possible if the node operator decided to index specific or all - messages on startup of the node, now the application can indicate which msgs - should be indexed. +### P2P Protocol + +The default codec is now proto3, not amino. Check out the [TODO]() for +motivation behind this change. The schema files can be found in the `/proto` +directory. In the future we're considering using gRPC for the remote private +validator and ABCI +([\#4698](https://github.com/tendermint/tendermint/issues/4698)). + +### Blockchain Protocol -### Crypto +`Header#LastResultsHash`, which previously was the root hash of a Merkle tree +built from `ResponseDeliverTx(Code, Data)` responses, became the root hash of a +Merkle tree built from: -- `Multsig` & `PubKeyMultisigThreshold` have been moved to the - [Cosmos-SDK](https://github.com/cosmos/cosmos-sdk). - (https://github.com/cosmos/cosmos-sdk/blob/master/crypto/types/multisig/multisignature.go) + - `BeginBlock#Events`; + - root hash of a Merkle tree built from `ResponseDeliverTx(Code, Data, + GasWanted, GasUsed, Events)` responses; + - `BeginBlock#Events`. ### Protobuf @@ -44,22 +56,73 @@ With this release we are happy to announce the full protobuf migration of the Te ### Go API -- `rpc/client` HTTP and local clients have been moved into `http` and `local` subpackages, and their constructors have been renamed to `New()`. +- `rpc/client` HTTP and local clients have been moved into `http` and `local` + subpackages, and their constructors have been renamed to `New()`. ### Protobuf Changes -When upgrading to version 0.33.4 you will have to fetch the `third_party` directory along with the updated proto files. +When upgrading to version 0.33.4 you will have to fetch the `third_party` +directory along with the updated proto files. ## v0.33.0 -This release is not compatible with previous blockchains due to commit becoming signatures only and fields in the header have been removed. +This release is not compatible with previous blockchains due to commit becoming +signatures only and fields in the header have been removed. + +### Blockchain Protocol + +`TotalTxs` and `NumTxs` were removed from the header. `Commit` now consists +mostly of just signatures. + +```go +type Commit struct { + Height int64 + Round int + BlockID BlockID + Signatures []CommitSig +} +``` + +```go +type BlockIDFlag byte + +const ( + // BlockIDFlagAbsent - no vote was received from a validator. + BlockIDFlagAbsent BlockIDFlag = 0x01 + // BlockIDFlagCommit - voted for the Commit.BlockID. + BlockIDFlagCommit = 0x02 + // BlockIDFlagNil - voted for nil. + BlockIDFlagNil = 0x03 +) + +type CommitSig struct { + BlockIDFlag BlockIDFlag + ValidatorAddress Address + Timestamp time.Time + Signature []byte +} +``` + +See [\#63](https://github.com/tendermint/spec/pull/63) for the complete spec +change. + +### P2P Protocol + +The secret connection now includes a transcript hashing. If you want to +implement a handshake (or otherwise have an existing implementation), you'll +need to make the same changes that were made +[here](https://github.com/tendermint/tendermint/pull/3668). ### Config Changes You will need to generate a new config if you have used a prior version of tendermint. -- Tags have been entirely renamed throughout the codebase to events and there keys are called [compositeKeys](https://github.com/tendermint/tendermint/blob/6d05c531f7efef6f0619155cf10ae8557dd7832f/docs/app-dev/indexing-transactions.md). -- Evidence Params has been changed to include duration. +Tags have been entirely renamed throughout the codebase to events and there +keys are called +[compositeKeys](https://github.com/tendermint/tendermint/blob/6d05c531f7efef6f0619155cf10ae8557dd7832f/docs/app-dev/indexing-transactions.md). + +Evidence Params has been changed to include duration. + - `consensus_params.evidence.max_age_duration`. - Renamed `consensus_params.evidence.max_age` to `max_age_num_blocks`. diff --git a/version/version.go b/version/version.go index 47d5e079e..3521cc61a 100644 --- a/version/version.go +++ b/version/version.go @@ -31,9 +31,9 @@ const ( var ( // P2PProtocol versions all p2p behaviour and msgs. // This includes proposer selection. - P2PProtocol uint64 = 7 + P2PProtocol uint64 = 8 // BlockProtocol versions all block data structures and processing. // This includes validity of blocks and state updates. - BlockProtocol uint64 = 10 + BlockProtocol uint64 = 11 )