feat: Add XDPoS consensus engine for XDC Network

Port of XDPoS consensus engine from XDC Network's XDPoSChain to modern
go-ethereum 1.17.x. Based on PR #1 reference which shows the complete
XDPoS implementation against geth 1.8.x.

## Core Consensus Engine (consensus/XDPoS/)

### xdpos.go - Main Engine (~1000 lines)
- Full consensus.Engine interface for geth 1.17.x
- DPoS masternode rotation with epoch-based cycling
- Block sealing with turn-based difficulty adjustment
- Hook system for XDC-specific logic:
  * HookReward - Block reward distribution
  * HookPenalty - Masternode penalty calculation
  * HookValidator - Double validation
  * HookVerifyMNs - Masternode verification
- Block signer transaction caching
- Recent signer spam protection

### snapshot.go - Validator State Management (~300 lines)
- Authorization snapshots at checkpoints
- Vote tracking for masternode changes
- Persistent storage to database

### api.go - RPC API Endpoints (~150 lines)
- xdpos_getSnapshot, xdpos_getSigners, xdpos_getMasternodes
- xdpos_propose, xdpos_discard, xdpos_proposals

### constants.go - XDC Network Constants (~60 lines)
- Reward percentages, epoch configuration
- Masternode limits, penalty configuration

## Configuration (params/config.go)

Added XDPoSConfig struct and XDPoS field to ChainConfig

## Account Signing (accounts/)

- Added MimetypeXDPoS constant
- Added XDPoS signature handling in external signer

## Key Adaptations for geth 1.17.x

- Finalize() and FinalizeAndAssemble() separated
- VerifyHeader() signature simplified
- Seal() uses channel-based results
- Modern LRU cache with generics

## Known Limitations / TODOs

- XDC-specific header fields (Validators, Penalties) not in types.Header
- Smart contracts not included
- XDPoS V2 BFT not ported
- cmd/XDC CLI not created

Reference: https://github.com/XinFinOrg/XDPoSChain (stable101)

accounts/accounts.go

@@ -39,6 +39,7 @@ const (
 	MimetypeDataWithValidator = "data/validator"
 	MimetypeTypedData         = "data/typed"
 	MimetypeClique            = "application/x-clique-header"
+	MimetypeXDPoS             = "application/x-xdpos-header"
 	MimetypeTextPlain         = "text/plain"
 )
 

accounts/external/backend.go

@@ -163,9 +163,9 @@ func (api *ExternalSigner) SignData(account accounts.Account, mimeType string, d
 		hexutil.Encode(data)); err != nil {
 		return nil, err
 	}
-	// If V is on 27/28-form, convert to 0/1 for Clique
+	// If V is on 27/28-form, convert to 0/1 for Clique and XDPoS
-	if mimeType == accounts.MimetypeClique && (res[64] == 27 || res[64] == 28) {
+	if (mimeType == accounts.MimetypeClique || mimeType == accounts.MimetypeXDPoS) && (res[64] == 27 || res[64] == 28) {
-		res[64] -= 27 // Transform V from 27/28 to 0/1 for Clique use
+		res[64] -= 27 // Transform V from 27/28 to 0/1 for Clique/XDPoS use
 	}
 	return res, nil
 }

consensus/XDPoS/api.go

@@ -0,0 +1,143 @@
+// Copyright (c) 2018 XDCchain
+// Copyright 2024 The go-ethereum Authors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+package XDPoS
+
+import (
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/consensus"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/rpc"
+)
+
+// API is a user facing RPC API to allow controlling the signer and voting
+// mechanisms of the XDPoS consensus engine.
+type API struct {
+	chain consensus.ChainHeaderReader
+	xdpos *XDPoS
+}
+
+// GetSnapshot retrieves the state snapshot at a given block.
+func (api *API) GetSnapshot(number *rpc.BlockNumber) (*Snapshot, error) {
+	var header *types.Header
+	if number == nil || *number == rpc.LatestBlockNumber {
+		header = api.chain.CurrentHeader()
+	} else {
+		header = api.chain.GetHeaderByNumber(uint64(number.Int64()))
+	}
+	if header == nil {
+		return nil, errUnknownBlock
+	}
+	return api.xdpos.GetSnapshot(api.chain, header)
+}
+
+// GetSnapshotAtHash retrieves the state snapshot at a given block hash.
+func (api *API) GetSnapshotAtHash(hash common.Hash) (*Snapshot, error) {
+	header := api.chain.GetHeaderByHash(hash)
+	if header == nil {
+		return nil, errUnknownBlock
+	}
+	return api.xdpos.GetSnapshot(api.chain, header)
+}
+
+// GetSigners retrieves the list of authorized signers at the specified block.
+func (api *API) GetSigners(number *rpc.BlockNumber) ([]common.Address, error) {
+	var header *types.Header
+	if number == nil || *number == rpc.LatestBlockNumber {
+		header = api.chain.CurrentHeader()
+	} else {
+		header = api.chain.GetHeaderByNumber(uint64(number.Int64()))
+	}
+	if header == nil {
+		return nil, errUnknownBlock
+	}
+	snap, err := api.xdpos.GetSnapshot(api.chain, header)
+	if err != nil {
+		return nil, err
+	}
+	return snap.GetSigners(), nil
+}
+
+// GetSignersAtHash retrieves the list of authorized signers at the specified block hash.
+func (api *API) GetSignersAtHash(hash common.Hash) ([]common.Address, error) {
+	header := api.chain.GetHeaderByHash(hash)
+	if header == nil {
+		return nil, errUnknownBlock
+	}
+	snap, err := api.xdpos.GetSnapshot(api.chain, header)
+	if err != nil {
+		return nil, err
+	}
+	return snap.GetSigners(), nil
+}
+
+// GetMasternodes retrieves the list of masternodes at the specified block.
+func (api *API) GetMasternodes(number *rpc.BlockNumber) ([]common.Address, error) {
+	var header *types.Header
+	if number == nil || *number == rpc.LatestBlockNumber {
+		header = api.chain.CurrentHeader()
+	} else {
+		header = api.chain.GetHeaderByNumber(uint64(number.Int64()))
+	}
+	if header == nil {
+		return nil, errUnknownBlock
+	}
+	return api.xdpos.GetMasternodes(api.chain, header), nil
+}
+
+// Proposals returns the current proposals the node tries to uphold and vote on.
+func (api *API) Proposals() map[common.Address]bool {
+	api.xdpos.lock.RLock()
+	defer api.xdpos.lock.RUnlock()
+
+	proposals := make(map[common.Address]bool)
+	for address, auth := range api.xdpos.proposals {
+		proposals[address] = auth
+	}
+	return proposals
+}
+
+// Propose injects a new authorization proposal that the signer will attempt to push through.
+func (api *API) Propose(address common.Address, auth bool) {
+	api.xdpos.lock.Lock()
+	defer api.xdpos.lock.Unlock()
+	api.xdpos.proposals[address] = auth
+}
+
+// Discard drops a currently running proposal.
+func (api *API) Discard(address common.Address) {
+	api.xdpos.lock.Lock()
+	defer api.xdpos.lock.Unlock()
+	delete(api.xdpos.proposals, address)
+}
+
+// GetCandidates returns the current candidates
+func (api *API) GetCandidates(number *rpc.BlockNumber) ([]common.Address, error) {
+	var header *types.Header
+	if number == nil || *number == rpc.LatestBlockNumber {
+		header = api.chain.CurrentHeader()
+	} else {
+		header = api.chain.GetHeaderByNumber(uint64(number.Int64()))
+	}
+	if header == nil {
+		return nil, errUnknownBlock
+	}
+	snap, err := api.xdpos.GetSnapshot(api.chain, header)
+	if err != nil {
+		return nil, err
+	}
+	return snap.GetSigners(), nil
+}

consensus/XDPoS/constants.go

@@ -0,0 +1,75 @@
+// Copyright (c) 2018 XDCchain
+// Copyright 2024 The go-ethereum Authors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+package XDPoS
+
+import "math/big"
+
+// XDC Network constants
+const (
+	// Reward distribution percentages
+	RewardMasterPercent     = 90
+	RewardVoterPercent      = 0
+	RewardFoundationPercent = 10
+
+	// Method signatures for contract calls
+	HexSignMethod  = "e341eaa4"
+	HexSetSecret   = "34d38600"
+	HexSetOpening  = "e11f5ba2"
+
+	// Epoch block offsets
+	EpocBlockSecret    = 800
+	EpocBlockOpening   = 850
+	EpocBlockRandomize = 900
+
+	// Masternode limits
+	MaxMasternodes   = 18
+	MaxMasternodesV2 = 108
+
+	// Penalty configuration
+	LimitPenaltyEpoch = 4
+
+	// Blocks per year (assuming 2 second blocks)
+	BlocksPerYear = uint64(15768000)
+
+	// Queue limits
+	LimitThresholdNonceInQueue = 10
+
+	// Gas price
+	DefaultMinGasPrice = 2500
+
+	// Block signing
+	MergeSignRange    = 15
+	RangeReturnSigner = 150
+
+	// Minimum miner blocks per epoch
+	MinimunMinerBlockPerEpoch = 1
+)
+
+// Fork block numbers
+var (
+	TIP2019Block           = big.NewInt(1)
+	TIPSigning             = big.NewInt(3000000)
+	TIPRandomize           = big.NewInt(3464000)
+	TIPIncreaseMasternodes = big.NewInt(5000000) // Upgrade MN Count at Block
+)
+
+// Global configuration variables
+var (
+	IsTestnet         bool   = false
+	StoreRewardFolder string
+	MinGasPrice       int64
+)

consensus/XDPoS/snapshot.go

@@ -0,0 +1,272 @@
+// Copyright (c) 2018 XDCchain
+// Copyright 2024 The go-ethereum Authors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+package XDPoS
+
+import (
+	"bytes"
+	"encoding/json"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/lru"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/ethdb"
+	"github.com/ethereum/go-ethereum/params"
+)
+
+// Vote represents a single vote that an authorized signer made to modify the
+// list of authorizations.
+type Vote struct {
+	Signer    common.Address `json:"signer"`    // Authorized signer that cast this vote
+	Block     uint64         `json:"block"`     // Block number the vote was cast in (expire old votes)
+	Address   common.Address `json:"address"`   // Account being voted on to change its authorization
+	Authorize bool           `json:"authorize"` // Whether to authorize or deauthorize the voted account
+}
+
+// Tally is a simple vote tally to keep the current score of votes.
+type Tally struct {
+	Authorize bool `json:"authorize"` // Whether the vote is about authorizing or kicking someone
+	Votes     int  `json:"votes"`     // Number of votes until now wanting to pass the proposal
+}
+
+// Snapshot is the state of the authorization voting at a given point in time.
+type Snapshot struct {
+	config   *params.XDPoSConfig                     // Consensus engine parameters to fine tune behavior
+	sigcache *lru.Cache[common.Hash, common.Address] // Cache of recent block signatures to speed up ecrecover
+
+	Number  uint64                      `json:"number"`  // Block number where the snapshot was created
+	Hash    common.Hash                 `json:"hash"`    // Block hash where the snapshot was created
+	Signers map[common.Address]struct{} `json:"signers"` // Set of authorized signers at this moment
+	Recents map[uint64]common.Address   `json:"recents"` // Set of recent signers for spam protections
+	Votes   []*Vote                     `json:"votes"`   // List of votes cast in chronological order
+	Tally   map[common.Address]Tally    `json:"tally"`   // Current vote tally to avoid recalculating
+}
+
+// newSnapshot creates a new snapshot with the specified startup parameters.
+func newSnapshot(config *params.XDPoSConfig, sigcache *lru.Cache[common.Hash, common.Address], number uint64, hash common.Hash, signers []common.Address) *Snapshot {
+	snap := &Snapshot{
+		config:   config,
+		sigcache: sigcache,
+		Number:   number,
+		Hash:     hash,
+		Signers:  make(map[common.Address]struct{}),
+		Recents:  make(map[uint64]common.Address),
+		Tally:    make(map[common.Address]Tally),
+	}
+	for _, signer := range signers {
+		snap.Signers[signer] = struct{}{}
+	}
+	return snap
+}
+
+// loadSnapshot loads an existing snapshot from the database.
+func loadSnapshot(config *params.XDPoSConfig, sigcache *lru.Cache[common.Hash, common.Address], db ethdb.Database, hash common.Hash) (*Snapshot, error) {
+	blob, err := db.Get(append([]byte("XDPoS-"), hash[:]...))
+	if err != nil {
+		return nil, err
+	}
+	snap := new(Snapshot)
+	if err := json.Unmarshal(blob, snap); err != nil {
+		return nil, err
+	}
+	snap.config = config
+	snap.sigcache = sigcache
+	return snap, nil
+}
+
+// store inserts the snapshot into the database.
+func (s *Snapshot) store(db ethdb.Database) error {
+	blob, err := json.Marshal(s)
+	if err != nil {
+		return err
+	}
+	return db.Put(append([]byte("XDPoS-"), s.Hash[:]...), blob)
+}
+
+// copy creates a deep copy of the snapshot.
+func (s *Snapshot) copy() *Snapshot {
+	cpy := &Snapshot{
+		config:   s.config,
+		sigcache: s.sigcache,
+		Number:   s.Number,
+		Hash:     s.Hash,
+		Signers:  make(map[common.Address]struct{}),
+		Recents:  make(map[uint64]common.Address),
+		Votes:    make([]*Vote, len(s.Votes)),
+		Tally:    make(map[common.Address]Tally),
+	}
+	for signer := range s.Signers {
+		cpy.Signers[signer] = struct{}{}
+	}
+	for block, signer := range s.Recents {
+		cpy.Recents[block] = signer
+	}
+	for address, tally := range s.Tally {
+		cpy.Tally[address] = tally
+	}
+	copy(cpy.Votes, s.Votes)
+	return cpy
+}
+
+// validVote returns whether it makes sense to cast the specified vote.
+func (s *Snapshot) validVote(address common.Address, authorize bool) bool {
+	_, signer := s.Signers[address]
+	return (signer && !authorize) || (!signer && authorize)
+}
+
+// cast adds a new vote into the tally.
+func (s *Snapshot) cast(address common.Address, authorize bool) bool {
+	if !s.validVote(address, authorize) {
+		return false
+	}
+	if old, ok := s.Tally[address]; ok {
+		old.Votes++
+		s.Tally[address] = old
+	} else {
+		s.Tally[address] = Tally{Authorize: authorize, Votes: 1}
+	}
+	return true
+}
+
+// uncast removes a previously cast vote from the tally.
+func (s *Snapshot) uncast(address common.Address, authorize bool) bool {
+	tally, ok := s.Tally[address]
+	if !ok {
+		return false
+	}
+	if tally.Authorize != authorize {
+		return false
+	}
+	if tally.Votes > 1 {
+		tally.Votes--
+		s.Tally[address] = tally
+	} else {
+		delete(s.Tally, address)
+	}
+	return true
+}
+
+// apply creates a new authorization snapshot by applying the given headers.
+func (s *Snapshot) apply(headers []*types.Header) (*Snapshot, error) {
+	if len(headers) == 0 {
+		return s, nil
+	}
+	for i := 0; i < len(headers)-1; i++ {
+		if headers[i+1].Number.Uint64() != headers[i].Number.Uint64()+1 {
+			return nil, errInvalidVotingChain
+		}
+	}
+	if headers[0].Number.Uint64() != s.Number+1 {
+		return nil, errInvalidVotingChain
+	}
+
+	snap := s.copy()
+
+	for _, header := range headers {
+		number := header.Number.Uint64()
+		if number%s.config.Epoch == 0 {
+			snap.Votes = nil
+			snap.Tally = make(map[common.Address]Tally)
+		}
+		if limit := uint64(len(snap.Signers)/2 + 1); number >= limit {
+			delete(snap.Recents, number-limit)
+		}
+		signer, err := ecrecover(header, s.sigcache)
+		if err != nil {
+			return nil, err
+		}
+		snap.Recents[number] = signer
+
+		for i, vote := range snap.Votes {
+			if vote.Signer == signer && vote.Address == header.Coinbase {
+				snap.uncast(vote.Address, vote.Authorize)
+				snap.Votes = append(snap.Votes[:i], snap.Votes[i+1:]...)
+				break
+			}
+		}
+
+		var authorize bool
+		switch {
+		case bytes.Equal(header.Nonce[:], nonceAuthVote):
+			authorize = true
+		case bytes.Equal(header.Nonce[:], nonceDropVote):
+			authorize = false
+		default:
+			return nil, errInvalidVote
+		}
+		if snap.cast(header.Coinbase, authorize) {
+			snap.Votes = append(snap.Votes, &Vote{
+				Signer:    signer,
+				Block:     number,
+				Address:   header.Coinbase,
+				Authorize: authorize,
+			})
+		}
+
+		if tally := snap.Tally[header.Coinbase]; tally.Votes > len(snap.Signers)/2 {
+			if tally.Authorize {
+				snap.Signers[header.Coinbase] = struct{}{}
+			} else {
+				delete(snap.Signers, header.Coinbase)
+				if limit := uint64(len(snap.Signers)/2 + 1); number >= limit {
+					delete(snap.Recents, number-limit)
+				}
+				for i := 0; i < len(snap.Votes); i++ {
+					if snap.Votes[i].Signer == header.Coinbase {
+						snap.uncast(snap.Votes[i].Address, snap.Votes[i].Authorize)
+						snap.Votes = append(snap.Votes[:i], snap.Votes[i+1:]...)
+						i--
+					}
+				}
+			}
+			for i := 0; i < len(snap.Votes); i++ {
+				if snap.Votes[i].Address == header.Coinbase {
+					snap.Votes = append(snap.Votes[:i], snap.Votes[i+1:]...)
+					i--
+				}
+			}
+			delete(snap.Tally, header.Coinbase)
+		}
+	}
+	snap.Number += uint64(len(headers))
+	snap.Hash = headers[len(headers)-1].Hash()
+	return snap, nil
+}
+
+// GetSigners retrieves the list of authorized signers in ascending order.
+func (s *Snapshot) GetSigners() []common.Address {
+	signers := make([]common.Address, 0, len(s.Signers))
+	for signer := range s.Signers {
+		signers = append(signers, signer)
+	}
+	for i := 0; i < len(signers); i++ {
+		for j := i + 1; j < len(signers); j++ {
+			if bytes.Compare(signers[i][:], signers[j][:]) > 0 {
+				signers[i], signers[j] = signers[j], signers[i]
+			}
+		}
+	}
+	return signers
+}
+
+// inturn returns if a signer at a given block height is in-turn or not.
+func (s *Snapshot) inturn(number uint64, signer common.Address) bool {
+	signers, offset := s.GetSigners(), 0
+	for offset < len(signers) && signers[offset] != signer {
+		offset++
+	}
+	return (number % uint64(len(signers))) == uint64(offset)
+}

params/config.go

@@ -490,6 +490,7 @@ type ChainConfig struct {
 	// Various consensus engines
 	Ethash             *EthashConfig       `json:"ethash,omitempty"`
 	Clique             *CliqueConfig       `json:"clique,omitempty"`
+	XDPoS              *XDPoSConfig        `json:"xdpos,omitempty"`
 	BlobScheduleConfig *BlobScheduleConfig `json:"blobSchedule,omitempty"`
 }
 
@@ -512,6 +513,21 @@ func (c CliqueConfig) String() string {
 	return fmt.Sprintf("clique(period: %d, epoch: %d)", c.Period, c.Epoch)
 }
 
+// XDPoSConfig is the consensus engine configs for XDC Network's delegated-proof-of-stake based sealing.
+type XDPoSConfig struct {
+	Period              uint64         `json:"period"`              // Number of seconds between blocks to enforce
+	Epoch               uint64         `json:"epoch"`               // Epoch length to reset votes and checkpoint
+	Reward              uint64         `json:"reward"`              // Block reward - unit Ether
+	RewardCheckpoint    uint64         `json:"rewardCheckpoint"`    // Checkpoint block for calculate rewards
+	Gap                 uint64         `json:"gap"`                 // Gap time preparing for the next epoch
+	FoudationWalletAddr common.Address `json:"foudationWalletAddr"` // Foundation Address Wallet
+}
+
+// String implements the stringer interface, returning the consensus engine details.
+func (c XDPoSConfig) String() string {
+	return fmt.Sprintf("xdpos(period: %d, epoch: %d, reward: %d)", c.Period, c.Epoch, c.Reward)
+}
+
 // String implements the fmt.Stringer interface, returning a string representation
 // of ChainConfig.
 func (c *ChainConfig) String() string {