github.com/ConsenSys/Quorum@v20.10.0+incompatible/consensus/consensus.go (about) 1 // Copyright 2017 The go-ethereum Authors 2 // This file is part of the go-ethereum library. 3 // 4 // The go-ethereum library is free software: you can redistribute it and/or modify 5 // it under the terms of the GNU Lesser General Public License as published by 6 // the Free Software Foundation, either version 3 of the License, or 7 // (at your option) any later version. 8 // 9 // The go-ethereum library is distributed in the hope that it will be useful, 10 // but WITHOUT ANY WARRANTY; without even the implied warranty of 11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 // GNU Lesser General Public License for more details. 13 // 14 // You should have received a copy of the GNU Lesser General Public License 15 // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>. 16 17 // Package consensus implements different Ethereum consensus engines. 18 package consensus 19 20 import ( 21 "math/big" 22 23 "github.com/ethereum/go-ethereum/common" 24 "github.com/ethereum/go-ethereum/core/state" 25 "github.com/ethereum/go-ethereum/core/types" 26 "github.com/ethereum/go-ethereum/p2p" 27 "github.com/ethereum/go-ethereum/params" 28 "github.com/ethereum/go-ethereum/rpc" 29 ) 30 31 // ChainReader defines a small collection of methods needed to access the local 32 // blockchain during header and/or uncle verification. 33 type ChainReader interface { 34 // Config retrieves the blockchain's chain configuration. 35 Config() *params.ChainConfig 36 37 // CurrentHeader retrieves the current header from the local chain. 38 CurrentHeader() *types.Header 39 40 // GetHeader retrieves a block header from the database by hash and number. 41 GetHeader(hash common.Hash, number uint64) *types.Header 42 43 // GetHeaderByNumber retrieves a block header from the database by number. 44 GetHeaderByNumber(number uint64) *types.Header 45 46 // GetHeaderByHash retrieves a block header from the database by its hash. 47 GetHeaderByHash(hash common.Hash) *types.Header 48 49 // GetBlock retrieves a block from the database by hash and number. 50 GetBlock(hash common.Hash, number uint64) *types.Block 51 } 52 53 // Engine is an algorithm agnostic consensus engine. 54 type Engine interface { 55 // Author retrieves the Ethereum address of the account that minted the given 56 // block, which may be different from the header's coinbase if a consensus 57 // engine is based on signatures. 58 Author(header *types.Header) (common.Address, error) 59 60 // VerifyHeader checks whether a header conforms to the consensus rules of a 61 // given engine. Verifying the seal may be done optionally here, or explicitly 62 // via the VerifySeal method. 63 VerifyHeader(chain ChainReader, header *types.Header, seal bool) error 64 65 // VerifyHeaders is similar to VerifyHeader, but verifies a batch of headers 66 // concurrently. The method returns a quit channel to abort the operations and 67 // a results channel to retrieve the async verifications (the order is that of 68 // the input slice). 69 VerifyHeaders(chain ChainReader, headers []*types.Header, seals []bool) (chan<- struct{}, <-chan error) 70 71 // VerifyUncles verifies that the given block's uncles conform to the consensus 72 // rules of a given engine. 73 VerifyUncles(chain ChainReader, block *types.Block) error 74 75 // VerifySeal checks whether the crypto seal on a header is valid according to 76 // the consensus rules of the given engine. 77 VerifySeal(chain ChainReader, header *types.Header) error 78 79 // Prepare initializes the consensus fields of a block header according to the 80 // rules of a particular engine. The changes are executed inline. 81 Prepare(chain ChainReader, header *types.Header) error 82 83 // Finalize runs any post-transaction state modifications (e.g. block rewards) 84 // but does not assemble the block. 85 // 86 // Note: The block header and state database might be updated to reflect any 87 // consensus rules that happen at finalization (e.g. block rewards). 88 Finalize(chain ChainReader, header *types.Header, state *state.StateDB, txs []*types.Transaction, 89 uncles []*types.Header) 90 91 // FinalizeAndAssemble runs any post-transaction state modifications (e.g. block 92 // rewards) and assembles the final block. 93 // 94 // Note: The block header and state database might be updated to reflect any 95 // consensus rules that happen at finalization (e.g. block rewards). 96 FinalizeAndAssemble(chain ChainReader, header *types.Header, state *state.StateDB, txs []*types.Transaction, 97 uncles []*types.Header, receipts []*types.Receipt) (*types.Block, error) 98 99 // Seal generates a new sealing request for the given input block and pushes 100 // the result into the given channel. 101 // 102 // Note, the method returns immediately and will send the result async. More 103 // than one result may also be returned depending on the consensus algorithm. 104 Seal(chain ChainReader, block *types.Block, results chan<- *types.Block, stop <-chan struct{}) error 105 106 // SealHash returns the hash of a block prior to it being sealed. 107 SealHash(header *types.Header) common.Hash 108 109 // CalcDifficulty is the difficulty adjustment algorithm. It returns the difficulty 110 // that a new block should have. 111 CalcDifficulty(chain ChainReader, time uint64, parent *types.Header) *big.Int 112 113 // APIs returns the RPC APIs this consensus engine provides. 114 APIs(chain ChainReader) []rpc.API 115 116 // Protocol returns the protocol for this consensus 117 Protocol() Protocol 118 119 // Close terminates any background threads maintained by the consensus engine. 120 Close() error 121 } 122 123 // Handler should be implemented is the consensus needs to handle and send peer's message 124 type Handler interface { 125 // NewChainHead handles a new head block comes 126 NewChainHead() error 127 128 // HandleMsg handles a message from peer 129 HandleMsg(address common.Address, data p2p.Msg) (bool, error) 130 131 // SetBroadcaster sets the broadcaster to send message to peers 132 SetBroadcaster(Broadcaster) 133 } 134 135 // PoW is a consensus engine based on proof-of-work. 136 type PoW interface { 137 Engine 138 139 // Hashrate returns the current mining hashrate of a PoW consensus engine. 140 Hashrate() float64 141 } 142 143 // Istanbul is a consensus engine to avoid byzantine failure 144 type Istanbul interface { 145 Engine 146 147 // Start starts the engine 148 Start(chain ChainReader, currentBlock func() *types.Block, hasBadBlock func(hash common.Hash) bool) error 149 150 // Stop stops the engine 151 Stop() error 152 }