all: separate catalyst package (#24280)

* all: seperate catalyst package

* eth/catalyst: moved some methods, added docs

* eth/catalyst, les/catalyst: add method docs

* core, eth, les, miner: move common function to beacon package

* eth/catalyst: goimported

* cmd/utils, miner/stress/beacon: naming nitpicks

Co-authored-by: Marius van der Wijden <m.vanderwijden@live.de>
Co-authored-by: Péter Szilágyi <peterke@gmail.com>

eth/catalyst/api.go

@@ -20,29 +20,15 @@ package catalyst
 import (
 	"crypto/sha256"
 	"encoding/binary"
-	"errors"
 	"fmt"
-	"math/big"
 
 	"github.com/ethereum/go-ethereum/common"
-	"github.com/ethereum/go-ethereum/consensus"
+	"github.com/ethereum/go-ethereum/core/beacon"
 	"github.com/ethereum/go-ethereum/core/types"
 	"github.com/ethereum/go-ethereum/eth"
-	"github.com/ethereum/go-ethereum/les"
 	"github.com/ethereum/go-ethereum/log"
 	"github.com/ethereum/go-ethereum/node"
 	"github.com/ethereum/go-ethereum/rpc"
-	"github.com/ethereum/go-ethereum/trie"
-)
-
-var (
-	VALID              = GenericStringResponse{"VALID"}
-	SUCCESS            = GenericStringResponse{"SUCCESS"}
-	INVALID            = ForkChoiceResponse{Status: "INVALID", PayloadID: nil}
-	SYNCING            = ForkChoiceResponse{Status: "SYNCING", PayloadID: nil}
-	GenericServerError = rpc.CustomError{Code: -32000, ValidationError: "Server error"}
-	UnknownPayload     = rpc.CustomError{Code: -32001, ValidationError: "Unknown payload"}
-	InvalidTB          = rpc.CustomError{Code: -32002, ValidationError: "Invalid terminal block"}
 )
 
 // Register adds catalyst APIs to the full node.
@@ -52,21 +38,7 @@ func Register(stack *node.Node, backend *eth.Ethereum) error {
 		{
 			Namespace: "engine",
 			Version:   "1.0",
-			Service:   NewConsensusAPI(backend, nil),
-			Public:    true,
-		},
-	})
-	return nil
-}
-
-// RegisterLight adds catalyst APIs to the light client.
-func RegisterLight(stack *node.Node, backend *les.LightEthereum) error {
-	log.Warn("Catalyst mode enabled", "protocol", "les")
-	stack.RegisterAPIs([]rpc.API{
-		{
-			Namespace: "engine",
-			Version:   "1.0",
-			Service:   NewConsensusAPI(nil, backend),
+			Service:   NewConsensusAPI(backend),
 			Public:    true,
 		},
 	})
@@ -74,143 +46,86 @@ func RegisterLight(stack *node.Node, backend *les.LightEthereum) error {
 }
 
 type ConsensusAPI struct {
-	light          bool
 	eth            *eth.Ethereum
-	les            *les.LightEthereum
 	preparedBlocks *payloadQueue // preparedBlocks caches payloads (*ExecutableDataV1) by payload ID (PayloadID)
 }
 
-func NewConsensusAPI(eth *eth.Ethereum, les *les.LightEthereum) *ConsensusAPI {
-	if eth == nil {
-		if les.BlockChain().Config().TerminalTotalDifficulty == nil {
-			panic("Catalyst started without valid total difficulty")
-		}
-	} else {
-		if eth.BlockChain().Config().TerminalTotalDifficulty == nil {
-			panic("Catalyst started without valid total difficulty")
-		}
+// NewConsensusAPI creates a new consensus api for the given backend.
+// The underlying blockchain needs to have a valid terminal total difficulty set.
+func NewConsensusAPI(eth *eth.Ethereum) *ConsensusAPI {
+	if eth.BlockChain().Config().TerminalTotalDifficulty == nil {
+		panic("Catalyst started without valid total difficulty")
 	}
-
 	return &ConsensusAPI{
-		light:          eth == nil,
 		eth:            eth,
-		les:            les,
 		preparedBlocks: newPayloadQueue(),
 	}
 }
 
-func (api *ConsensusAPI) GetPayloadV1(payloadID PayloadID) (*ExecutableDataV1, error) {
-	log.Trace("Engine API request received", "method", "GetPayload", "id", payloadID)
-	data := api.preparedBlocks.get(payloadID)
-	if data == nil {
-		return nil, &UnknownPayload
-	}
-	return data, nil
-}
-
-func (api *ConsensusAPI) ForkchoiceUpdatedV1(heads ForkchoiceStateV1, payloadAttributes *PayloadAttributesV1) (ForkChoiceResponse, error) {
+// ForkchoiceUpdatedV1 has several responsibilities:
+// If the method is called with an empty head block:
+// 		we return success, which can be used to check if the catalyst mode is enabled
+// If the total difficulty was not reached:
+// 		we return INVALID
+// If the finalizedBlockHash is set:
+// 		we check if we have the finalizedBlockHash in our db, if not we start a sync
+// We try to set our blockchain to the headBlock
+// If there are payloadAttributes:
+// 		we try to assemble a block with the payloadAttributes and return its payloadID
+func (api *ConsensusAPI) ForkchoiceUpdatedV1(heads beacon.ForkchoiceStateV1, payloadAttributes *beacon.PayloadAttributesV1) (beacon.ForkChoiceResponse, error) {
 	log.Trace("Engine API request received", "method", "ForkChoiceUpdated", "head", heads.HeadBlockHash, "finalized", heads.FinalizedBlockHash, "safe", heads.SafeBlockHash)
 	if heads.HeadBlockHash == (common.Hash{}) {
-		return ForkChoiceResponse{Status: SUCCESS.Status, PayloadID: nil}, nil
+		return beacon.ForkChoiceResponse{Status: beacon.SUCCESS.Status, PayloadID: nil}, nil
 	}
 	if err := api.checkTerminalTotalDifficulty(heads.HeadBlockHash); err != nil {
-		if api.light {
-			if header := api.les.BlockChain().GetHeaderByHash(heads.HeadBlockHash); header == nil {
-				// TODO (MariusVanDerWijden) trigger sync
-				return SYNCING, nil
-			}
-			return INVALID, err
-		} else {
-			if block := api.eth.BlockChain().GetBlockByHash(heads.HeadBlockHash); block == nil {
-				// TODO (MariusVanDerWijden) trigger sync
-				return SYNCING, nil
-			}
-			return INVALID, err
+		if block := api.eth.BlockChain().GetBlockByHash(heads.HeadBlockHash); block == nil {
+			// TODO (MariusVanDerWijden) trigger sync
+			return beacon.SYNCING, nil
 		}
+		return beacon.INVALID, err
 	}
 	// If the finalized block is set, check if it is in our blockchain
 	if heads.FinalizedBlockHash != (common.Hash{}) {
-		if api.light {
-			if header := api.les.BlockChain().GetHeaderByHash(heads.FinalizedBlockHash); header == nil {
-				// TODO (MariusVanDerWijden) trigger sync
-				return SYNCING, nil
-			}
-		} else {
-			if block := api.eth.BlockChain().GetBlockByHash(heads.FinalizedBlockHash); block == nil {
-				// TODO (MariusVanDerWijden) trigger sync
-				return SYNCING, nil
-			}
+		if block := api.eth.BlockChain().GetBlockByHash(heads.FinalizedBlockHash); block == nil {
+			// TODO (MariusVanDerWijden) trigger sync
+			return beacon.SYNCING, nil
 		}
 	}
 	// SetHead
 	if err := api.setHead(heads.HeadBlockHash); err != nil {
-		return INVALID, err
+		return beacon.INVALID, err
 	}
 	// Assemble block (if needed). It only works for full node.
-	if !api.light && payloadAttributes != nil {
+	if payloadAttributes != nil {
 		data, err := api.assembleBlock(heads.HeadBlockHash, payloadAttributes)
 		if err != nil {
-			return INVALID, err
+			return beacon.INVALID, err
 		}
 		id := computePayloadId(heads.HeadBlockHash, payloadAttributes)
 		api.preparedBlocks.put(id, data)
 		log.Info("Created payload", "payloadID", id)
-		return ForkChoiceResponse{Status: SUCCESS.Status, PayloadID: &id}, nil
+		return beacon.ForkChoiceResponse{Status: beacon.SUCCESS.Status, PayloadID: &id}, nil
 	}
-	return ForkChoiceResponse{Status: SUCCESS.Status, PayloadID: nil}, nil
+	return beacon.ForkChoiceResponse{Status: beacon.SUCCESS.Status, PayloadID: nil}, nil
 }
 
-func computePayloadId(headBlockHash common.Hash, params *PayloadAttributesV1) PayloadID {
-	// Hash
-	hasher := sha256.New()
-	hasher.Write(headBlockHash[:])
-	binary.Write(hasher, binary.BigEndian, params.Timestamp)
-	hasher.Write(params.Random[:])
-	hasher.Write(params.SuggestedFeeRecipient[:])
-	var out PayloadID
-	copy(out[:], hasher.Sum(nil)[:8])
-	return out
-}
-
-func (api *ConsensusAPI) invalid() ExecutePayloadResponse {
-	if api.light {
-		return ExecutePayloadResponse{Status: INVALID.Status, LatestValidHash: api.les.BlockChain().CurrentHeader().Hash()}
+// GetPayloadV1 returns a cached payload by id.
+func (api *ConsensusAPI) GetPayloadV1(payloadID beacon.PayloadID) (*beacon.ExecutableDataV1, error) {
+	log.Trace("Engine API request received", "method", "GetPayload", "id", payloadID)
+	data := api.preparedBlocks.get(payloadID)
+	if data == nil {
+		return nil, &beacon.UnknownPayload
 	}
-	return ExecutePayloadResponse{Status: INVALID.Status, LatestValidHash: api.eth.BlockChain().CurrentHeader().Hash()}
+	return data, nil
 }
 
 // ExecutePayloadV1 creates an Eth1 block, inserts it in the chain, and returns the status of the chain.
-func (api *ConsensusAPI) ExecutePayloadV1(params ExecutableDataV1) (ExecutePayloadResponse, error) {
+func (api *ConsensusAPI) ExecutePayloadV1(params beacon.ExecutableDataV1) (beacon.ExecutePayloadResponse, error) {
 	log.Trace("Engine API request received", "method", "ExecutePayload", params.BlockHash, "number", params.Number)
-	block, err := ExecutableDataToBlock(params)
+	block, err := beacon.ExecutableDataToBlock(params)
 	if err != nil {
 		return api.invalid(), err
 	}
-	if api.light {
-		if !api.les.BlockChain().HasHeader(block.ParentHash(), block.NumberU64()-1) {
-			/*
-				TODO (MariusVanDerWijden) reenable once sync is merged
-				if err := api.eth.Downloader().BeaconSync(api.eth.SyncMode(), block.Header()); err != nil {
-					return SYNCING, err
-				}
-			*/
-			// TODO (MariusVanDerWijden) we should return nil here not empty hash
-			return ExecutePayloadResponse{Status: SYNCING.Status, LatestValidHash: common.Hash{}}, nil
-		}
-		parent := api.les.BlockChain().GetHeaderByHash(params.ParentHash)
-		td := api.les.BlockChain().GetTd(parent.Hash(), block.NumberU64()-1)
-		ttd := api.les.BlockChain().Config().TerminalTotalDifficulty
-		if td.Cmp(ttd) < 0 {
-			return api.invalid(), fmt.Errorf("can not execute payload on top of block with low td got: %v threshold %v", td, ttd)
-		}
-		if err = api.les.BlockChain().InsertHeader(block.Header()); err != nil {
-			return api.invalid(), err
-		}
-		if merger := api.merger(); !merger.TDDReached() {
-			merger.ReachTTD()
-		}
-		return ExecutePayloadResponse{Status: VALID.Status, LatestValidHash: block.Hash()}, nil
-	}
 	if !api.eth.BlockChain().HasBlock(block.ParentHash(), block.NumberU64()-1) {
 		/*
 			TODO (MariusVanDerWijden) reenable once sync is merged
@@ -219,7 +134,7 @@ func (api *ConsensusAPI) ExecutePayloadV1(params ExecutableDataV1) (ExecutePaylo
 			}
 		*/
 		// TODO (MariusVanDerWijden) we should return nil here not empty hash
-		return ExecutePayloadResponse{Status: SYNCING.Status, LatestValidHash: common.Hash{}}, nil
+		return beacon.ExecutePayloadResponse{Status: beacon.SYNCING.Status, LatestValidHash: common.Hash{}}, nil
 	}
 	parent := api.eth.BlockChain().GetBlockByHash(params.ParentHash)
 	td := api.eth.BlockChain().GetTd(parent.Hash(), block.NumberU64()-1)
@@ -232,97 +147,39 @@ func (api *ConsensusAPI) ExecutePayloadV1(params ExecutableDataV1) (ExecutePaylo
 		return api.invalid(), err
 	}
 
-	if merger := api.merger(); !merger.TDDReached() {
+	if merger := api.eth.Merger(); !merger.TDDReached() {
 		merger.ReachTTD()
 	}
-	return ExecutePayloadResponse{Status: VALID.Status, LatestValidHash: block.Hash()}, nil
+	return beacon.ExecutePayloadResponse{Status: beacon.VALID.Status, LatestValidHash: block.Hash()}, nil
 }
 
-// AssembleBlock creates a new block, inserts it into the chain, and returns the "execution
-// data" required for eth2 clients to process the new block.
-func (api *ConsensusAPI) assembleBlock(parentHash common.Hash, params *PayloadAttributesV1) (*ExecutableDataV1, error) {
-	if api.light {
-		return nil, errors.New("not supported")
-	}
+// computePayloadId computes a pseudo-random payloadid, based on the parameters.
+func computePayloadId(headBlockHash common.Hash, params *beacon.PayloadAttributesV1) beacon.PayloadID {
+	// Hash
+	hasher := sha256.New()
+	hasher.Write(headBlockHash[:])
+	binary.Write(hasher, binary.BigEndian, params.Timestamp)
+	hasher.Write(params.Random[:])
+	hasher.Write(params.SuggestedFeeRecipient[:])
+	var out beacon.PayloadID
+	copy(out[:], hasher.Sum(nil)[:8])
+	return out
+}
+
+// invalid returns a response "INVALID" with the latest valid hash set to the current head.
+func (api *ConsensusAPI) invalid() beacon.ExecutePayloadResponse {
+	return beacon.ExecutePayloadResponse{Status: beacon.INVALID.Status, LatestValidHash: api.eth.BlockChain().CurrentHeader().Hash()}
+}
+
+// assembleBlock creates a new block and returns the "execution
+// data" required for beacon clients to process the new block.
+func (api *ConsensusAPI) assembleBlock(parentHash common.Hash, params *beacon.PayloadAttributesV1) (*beacon.ExecutableDataV1, error) {
 	log.Info("Producing block", "parentHash", parentHash)
 	block, err := api.eth.Miner().GetSealingBlock(parentHash, params.Timestamp, params.SuggestedFeeRecipient, params.Random)
 	if err != nil {
 		return nil, err
 	}
-	return BlockToExecutableData(block), nil
-}
-
-func encodeTransactions(txs []*types.Transaction) [][]byte {
-	var enc = make([][]byte, len(txs))
-	for i, tx := range txs {
-		enc[i], _ = tx.MarshalBinary()
-	}
-	return enc
-}
-
-func decodeTransactions(enc [][]byte) ([]*types.Transaction, error) {
-	var txs = make([]*types.Transaction, len(enc))
-	for i, encTx := range enc {
-		var tx types.Transaction
-		if err := tx.UnmarshalBinary(encTx); err != nil {
-			return nil, fmt.Errorf("invalid transaction %d: %v", i, err)
-		}
-		txs[i] = &tx
-	}
-	return txs, nil
-}
-
-func ExecutableDataToBlock(params ExecutableDataV1) (*types.Block, error) {
-	txs, err := decodeTransactions(params.Transactions)
-	if err != nil {
-		return nil, err
-	}
-	if len(params.ExtraData) > 32 {
-		return nil, fmt.Errorf("invalid extradata length: %v", len(params.ExtraData))
-	}
-	header := &types.Header{
-		ParentHash:  params.ParentHash,
-		UncleHash:   types.EmptyUncleHash,
-		Coinbase:    params.FeeRecipient,
-		Root:        params.StateRoot,
-		TxHash:      types.DeriveSha(types.Transactions(txs), trie.NewStackTrie(nil)),
-		ReceiptHash: params.ReceiptsRoot,
-		Bloom:       types.BytesToBloom(params.LogsBloom),
-		Difficulty:  common.Big0,
-		Number:      new(big.Int).SetUint64(params.Number),
-		GasLimit:    params.GasLimit,
-		GasUsed:     params.GasUsed,
-		Time:        params.Timestamp,
-		BaseFee:     params.BaseFeePerGas,
-		Extra:       params.ExtraData,
-		MixDigest:   params.Random,
-	}
-	block := types.NewBlockWithHeader(header).WithBody(txs, nil /* uncles */)
-	if block.Hash() != params.BlockHash {
-		return nil, fmt.Errorf("blockhash mismatch, want %x, got %x", params.BlockHash, block.Hash())
-	}
-	return block, nil
-}
-
-// BlockToExecutableData constructs the executableDataV1 structure by filling the
-// fields from the given block. It assumes the given block is post-merge block.
-func BlockToExecutableData(block *types.Block) *ExecutableDataV1 {
-	return &ExecutableDataV1{
-		BlockHash:     block.Hash(),
-		ParentHash:    block.ParentHash(),
-		FeeRecipient:  block.Coinbase(),
-		StateRoot:     block.Root(),
-		Number:        block.NumberU64(),
-		GasLimit:      block.GasLimit(),
-		GasUsed:       block.GasUsed(),
-		BaseFeePerGas: block.BaseFee(),
-		Timestamp:     block.Time(),
-		ReceiptsRoot:  block.ReceiptHash(),
-		LogsBloom:     block.Bloom().Bytes(),
-		Transactions:  encodeTransactions(block.Transactions()),
-		Random:        block.MixDigest(),
-		ExtraData:     block.Extra(),
-	}
+	return beacon.BlockToExecutableData(block), nil
 }
 
 // Used in tests to add a the list of transactions from a block to the tx pool.
@@ -335,29 +192,17 @@ func (api *ConsensusAPI) insertTransactions(txs types.Transactions) error {
 
 func (api *ConsensusAPI) checkTerminalTotalDifficulty(head common.Hash) error {
 	// shortcut if we entered PoS already
-	if api.merger().PoSFinalized() {
-		return nil
-	}
-	if api.light {
-		// make sure the parent has enough terminal total difficulty
-		header := api.les.BlockChain().GetHeaderByHash(head)
-		if header == nil {
-			return &GenericServerError
-		}
-		td := api.les.BlockChain().GetTd(header.Hash(), header.Number.Uint64())
-		if td != nil && td.Cmp(api.les.BlockChain().Config().TerminalTotalDifficulty) < 0 {
-			return &InvalidTB
-		}
+	if api.eth.Merger().PoSFinalized() {
 		return nil
 	}
 	// make sure the parent has enough terminal total difficulty
 	newHeadBlock := api.eth.BlockChain().GetBlockByHash(head)
 	if newHeadBlock == nil {
-		return &GenericServerError
+		return &beacon.GenericServerError
 	}
 	td := api.eth.BlockChain().GetTd(newHeadBlock.Hash(), newHeadBlock.NumberU64())
 	if td != nil && td.Cmp(api.eth.BlockChain().Config().TerminalTotalDifficulty) < 0 {
-		return &InvalidTB
+		return &beacon.InvalidTB
 	}
 	return nil
 }
@@ -365,48 +210,22 @@ func (api *ConsensusAPI) checkTerminalTotalDifficulty(head common.Hash) error {
 // setHead is called to perform a force choice.
 func (api *ConsensusAPI) setHead(newHead common.Hash) error {
 	log.Info("Setting head", "head", newHead)
-	if api.light {
-		headHeader := api.les.BlockChain().CurrentHeader()
-		if headHeader.Hash() == newHead {
-			return nil
-		}
-		newHeadHeader := api.les.BlockChain().GetHeaderByHash(newHead)
-		if newHeadHeader == nil {
-			return &GenericServerError
-		}
-		if err := api.les.BlockChain().SetChainHead(newHeadHeader); err != nil {
-			return err
-		}
-		// Trigger the transition if it's the first `NewHead` event.
-		if merger := api.merger(); !merger.PoSFinalized() {
-			merger.FinalizePoS()
-		}
-		return nil
-	}
 	headBlock := api.eth.BlockChain().CurrentBlock()
 	if headBlock.Hash() == newHead {
 		return nil
 	}
 	newHeadBlock := api.eth.BlockChain().GetBlockByHash(newHead)
 	if newHeadBlock == nil {
-		return &GenericServerError
+		return &beacon.GenericServerError
 	}
 	if err := api.eth.BlockChain().SetChainHead(newHeadBlock); err != nil {
 		return err
 	}
 	// Trigger the transition if it's the first `NewHead` event.
-	if merger := api.merger(); !merger.PoSFinalized() {
+	if merger := api.eth.Merger(); !merger.PoSFinalized() {
 		merger.FinalizePoS()
 	}
 	// TODO (MariusVanDerWijden) are we really synced now?
 	api.eth.SetSynced()
 	return nil
 }
-
-// Helper function, return the merger instance.
-func (api *ConsensusAPI) merger() *consensus.Merger {
-	if api.light {
-		return api.les.Merger()
-	}
-	return api.eth.Merger()
-}