diff --git a/docs/spec/blockchain/blockchain.md b/docs/spec/blockchain/blockchain.md index eb34f4c87..e3171818a 100644 --- a/docs/spec/blockchain/blockchain.md +++ b/docs/spec/blockchain/blockchain.md @@ -52,7 +52,8 @@ type Header struct { // application ResultsHash []byte // SimpleMerkle of []abci.Result from prevBlock AppHash []byte // Arbitrary state digest - ValidatorsHash []byte // SimpleMerkle of the ValidatorSet + ValidatorsHash []byte // SimpleMerkle of the current ValidatorSet + NextValidatorsHash []byte // SimpleMerkle of the next ValidatorSet ConsensusParamsHash []byte // SimpleMerkle of the ConsensusParams // consensus @@ -160,9 +161,12 @@ We refer to certain globally available objects: `block` is the block under consideration, `prevBlock` is the `block` at the previous height, and `state` keeps track of the validator set, the consensus parameters -and other results from the application. +and other results from the application. At the point when `block` is the block under consideration, +the current version of the `state` corresponds to the state +after executing transactions from the `prevBlock`. Elements of an object are accessed as expected, -ie. `block.Header`. See [here](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/state.md) for the definition of `state`. +ie. `block.Header`. +See [here](https://github.com/tendermint/tendermint/blob/master/docs/spec/blockchain/state.md) for the definition of `state`. ### Header @@ -278,7 +282,14 @@ block.ValidatorsHash == SimpleMerkleRoot(state.Validators) Simple Merkle root of the current validator set that is committing the block. This can be used to validate the `LastCommit` included in the next block. -May be updated by the application. + +### NextValidatorsHash + +```go +block.NextValidatorsHash == SimpleMerkleRoot(state.NextValidators) +``` +Simple Merkle root of the next validator set that will be the validator set that commits the next block. +Modifications to the validator set are defined by the application. ### ConsensusParamsHash @@ -407,25 +418,20 @@ set (TODO). Execute is defined as: ```go Execute(s State, app ABCIApp, block Block) State { - TODO: just spell out ApplyBlock here - and remove ABCIResponses struct. - abciResponses := app.ApplyBlock(block) + // Fuction ApplyBlock executes block of transactions against the app and returns the new root hash of the app state, + // modifications to the validator set and the changes of the consensus parameters. + AppHash, ValidatorChanges, ConsensusParamChanges := app.ApplyBlock(block) return State{ LastResults: abciResponses.DeliverTxResults, - AppHash: abciResponses.AppHash, - Validators: UpdateValidators(state.Validators, abciResponses.ValidatorChanges), + AppHash: AppHash, LastValidators: state.Validators, - ConsensusParams: UpdateConsensusParams(state.ConsensusParams, abci.Responses.ConsensusParamChanges), + Validators: state.NextValidators, + NextValidators: UpdateValidators(state.NextValidators, ValidatorChanges), + ConsensusParams: UpdateConsensusParams(state.ConsensusParams, ConsensusParamChanges), } } -type ABCIResponses struct { - DeliverTxResults []Result - ValidatorChanges []Validator - ConsensusParamChanges ConsensusParams - AppHash []byte -} ``` diff --git a/docs/spec/blockchain/state.md b/docs/spec/blockchain/state.md index 3b374f70a..df86cd450 100644 --- a/docs/spec/blockchain/state.md +++ b/docs/spec/blockchain/state.md @@ -3,7 +3,7 @@ ## State The state contains information whose cryptographic digest is included in block headers, and thus is -necessary for validating new blocks. For instance, the set of validators and the results of +necessary for validating new blocks. For instance, the validators set and the results of transactions are never included in blocks, but their Merkle roots are - the state keeps track of them. Note that the `State` object itself is an implementation detail, since it is never @@ -18,8 +18,9 @@ type State struct { LastResults []Result AppHash []byte - Validators []Validator LastValidators []Validator + Validators []Validator + NextValidators []Validator ConsensusParams ConsensusParams }