(feat): reserved blockspace

cmd/keeper/go.mod

@@ -48,9 +48,9 @@ require (
 	github.com/tklauser/go-sysconf v0.3.16 // indirect
 	github.com/tklauser/numcpus v0.11.0 // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
-	golang.org/x/crypto v0.50.0 // indirect
+	golang.org/x/crypto v0.51.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/sys v0.45.0 // indirect
 	golang.org/x/time v0.12.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )

consensus/bor/bor.go

@@ -32,6 +32,7 @@ import (
 	"github.com/ethereum/go-ethereum/consensus/bor/api"
 	"github.com/ethereum/go-ethereum/consensus/bor/clerk"
 	borSpan "github.com/ethereum/go-ethereum/consensus/bor/heimdall/span"
+	"github.com/ethereum/go-ethereum/consensus/bor/registryreader"
 	"github.com/ethereum/go-ethereum/consensus/bor/statefull"
 	"github.com/ethereum/go-ethereum/consensus/bor/valset"
 	"github.com/ethereum/go-ethereum/consensus/misc"
@@ -106,6 +107,15 @@ var (
 	// the gas target or base fee change denominator in its extra data.
 	errMissingGiuglianoFields = errors.New("missing gas target or base fee change denominator in extra data")
 
+	// errMissingReservedBlockspaceFields is returned if a post-ReservedBlockspace
+	// block is missing the reserved tx count or reserved gas used in its extra data.
+	errMissingReservedBlockspaceFields = errors.New("missing reserved tx count or reserved gas used in extra data")
+
+	// errReservedGasUsedExceedsBlock is returned if a header's reserved gas used
+	// is larger than the block's total gas used — an impossible value, since the
+	// reserved region is a subset of the block.
+	errReservedGasUsedExceedsBlock = errors.New("reserved gas used exceeds block gas used")
+
 	// errInvalidMixDigest is returned if a block's mix digest is non-zero.
 	errInvalidMixDigest = errors.New("non-zero mix digest")
 
@@ -393,6 +403,17 @@ func (c *Bor) GetSpanner() Spanner {
 	return c.spanner
 }
 
+// ReservedRegistry returns the read-only handle to the reserved blockspace
+// registry, or nil when the GenesisContractsClient does not implement the
+// reader (e.g. test mocks). Callers must tolerate a nil return.
+func (c *Bor) ReservedRegistry() registryreader.Reader {
+	if c == nil {
+		return nil
+	}
+	reader, _ := c.GenesisContractsClient.(registryreader.Reader)
+	return reader
+}
+
 func (c *Bor) SetSpanner(spanner Spanner) {
 	c.spanner = spanner
 }
@@ -506,6 +527,10 @@ func (c *Bor) verifyHeader(chain consensus.ChainHeaderReader, header *types.Head
 		}
 	}
 
+	if err := c.verifyReservedFields(header); err != nil {
+		return err
+	}
+
 	// Ensure that the mix digest is zero as we don't have fork protection currently
 	if header.MixDigest != (common.Hash{}) {
 		return errInvalidMixDigest
@@ -1021,6 +1046,40 @@ func (c *Bor) setGiuglianoExtraFields(header *types.Header, parent *types.Header
 	}
 }
 
+// setReservedBlockspaceExtraFields initializes the reserved-region header field
+// for post-ReservedBlockspace blocks: a placeholder zero so the field is
+// present (non-nil) and the header passes the verifyReservedFields presence
+// check even when there are no reserved transactions. The miner overwrites it
+// with the block's real reserved gas total at the end of block building
+// (worker.writeReservedGasUsed).
+func (c *Bor) setReservedBlockspaceExtraFields(header *types.Header, blockExtraData *types.BlockExtraData) {
+	if c.config.IsReservedBlockspace(header.Number) {
+		var zeroGas uint64
+		blockExtraData.ReservedGasUsed = &zeroGas
+	}
+}
+
+// verifyReservedFields checks that post-ReservedBlockspace headers carry the
+// reserved-region gas field, plus a header-only bound on its value. Value
+// correctness (the sum over the block's reserved transactions, per-client
+// quota) is a body-level check that lands with the block-validation slice.
+func (c *Bor) verifyReservedFields(header *types.Header) error {
+	if !c.config.IsReservedBlockspace(header.Number) {
+		return nil
+	}
+	reservedGasUsed := header.GetReservedGasUsed(c.chainConfig)
+	if reservedGasUsed == nil {
+		return errMissingReservedBlockspaceFields
+	}
+	// The reserved region is a subset of the block, so its gas cannot exceed the
+	// block's gas used. Reject the impossible value rather than letting CalcBaseFee
+	// silently clamp it (the base fee consumes parent.ReservedGasUsed).
+	if *reservedGasUsed > header.GasUsed {
+		return errReservedGasUsedExceedsBlock
+	}
+	return nil
+}
+
 // Prepare implements consensus.Engine, preparing all the consensus fields of the
 // header for running the transactions on top.
 func (c *Bor) Prepare(chain consensus.ChainHeaderReader, header *types.Header, waitOnPrepare bool) error {
@@ -1076,6 +1135,7 @@ func (c *Bor) Prepare(chain consensus.ChainHeaderReader, header *types.Header, w
 			}
 
 			c.setGiuglianoExtraFields(header, parent, blockExtraData)
+			c.setReservedBlockspaceExtraFields(header, blockExtraData)
 
 			blockExtraDataBytes, err := rlp.EncodeToBytes(blockExtraData)
 			if err != nil {
@@ -1096,6 +1156,7 @@ func (c *Bor) Prepare(chain consensus.ChainHeaderReader, header *types.Header, w
 		}
 
 		c.setGiuglianoExtraFields(header, parent, blockExtraData)
+		c.setReservedBlockspaceExtraFields(header, blockExtraData)
 
 		blockExtraDataBytes, err := rlp.EncodeToBytes(blockExtraData)
 		if err != nil {

consensus/bor/bor_test.go

@@ -5911,6 +5911,89 @@ func TestVerifyHeader_PreGiugliano_NoCheck(t *testing.T) {
 	}
 }
 
+func TestSetReservedBlockspaceExtraFields(t *testing.T) {
+	t.Parallel()
+
+	// Pre-fork: the reserved field is left nil.
+	bPre := &Bor{config: &params.BorConfig{ReservedBlockspaceBlock: big.NewInt(100)}}
+	bedPre := &types.BlockExtraData{}
+	bPre.setReservedBlockspaceExtraFields(&types.Header{Number: big.NewInt(99)}, bedPre)
+	require.Nil(t, bedPre.ReservedGasUsed)
+
+	// Post-fork: the field is initialized to non-nil zero so the block is valid
+	// even before the miner writes the real value.
+	bPost := &Bor{config: &params.BorConfig{ReservedBlockspaceBlock: big.NewInt(100)}}
+	bedPost := &types.BlockExtraData{}
+	bPost.setReservedBlockspaceExtraFields(&types.Header{Number: big.NewInt(100)}, bedPost)
+	require.NotNil(t, bedPost.ReservedGasUsed)
+	require.Equal(t, uint64(0), *bedPost.ReservedGasUsed)
+}
+
+func TestVerifyHeader_ReservedBlockspaceMissingFields(t *testing.T) {
+	t.Parallel()
+	s := newGiuglianoVerifySetup(t, true)
+	s.b.config.ReservedBlockspaceBlock = big.NewInt(0) // reserved-blockspace active from genesis
+
+	// Giugliano fields present (passes that check) but reserved fields absent.
+	gasTarget := uint64(15_000_000)
+	bfcd := uint64(64)
+	extra := buildBlockExtraBytes(&types.BlockExtraData{
+		GasTarget:                &gasTarget,
+		BaseFeeChangeDenominator: &bfcd,
+	})
+	h := s.makeSignedChild(t, extra, big.NewInt(params.InitialBaseFee))
+
+	chain := newRawDBChain(s.db, s.cfg, h, nil, nil)
+	err := s.b.verifyHeader(chain, h, nil)
+	require.ErrorIs(t, err, errMissingReservedBlockspaceFields)
+}
+
+func TestVerifyHeader_ReservedBlockspaceFieldsPresent(t *testing.T) {
+	t.Parallel()
+	s := newGiuglianoVerifySetup(t, true)
+	s.b.config.ReservedBlockspaceBlock = big.NewInt(0)
+
+	gasTarget := uint64(15_000_000)
+	bfcd := uint64(64)
+	gasUsed := uint64(0)
+	extra := buildBlockExtraBytes(&types.BlockExtraData{
+		GasTarget:                &gasTarget,
+		BaseFeeChangeDenominator: &bfcd,
+		ReservedGasUsed:          &gasUsed,
+	})
+	h := s.makeSignedChild(t, extra, big.NewInt(params.InitialBaseFee))
+
+	chain := newRawDBChain(s.db, s.cfg, h, nil, nil)
+	err := s.b.verifyHeader(chain, h, nil)
+	if err != nil {
+		require.NotErrorIs(t, err, errMissingReservedBlockspaceFields)
+		require.NotErrorIs(t, err, errMissingGiuglianoFields)
+	}
+}
+
+func TestVerifyReservedFields_GasUsedBound(t *testing.T) {
+	t.Parallel()
+	s := newGiuglianoVerifySetup(t, true)
+	s.b.config.ReservedBlockspaceBlock = big.NewInt(0)
+
+	gasTarget := uint64(15_000_000)
+	bfcd := uint64(64)
+	reservedGasUsed := uint64(5_000)
+	extra := buildBlockExtraBytes(&types.BlockExtraData{
+		GasTarget:                &gasTarget,
+		BaseFeeChangeDenominator: &bfcd,
+		ReservedGasUsed:          &reservedGasUsed,
+	})
+
+	// Reserved gas used exceeds the block's gas used — impossible, must be rejected.
+	h := &types.Header{Number: big.NewInt(1), GasUsed: 4_000, Extra: extra}
+	require.ErrorIs(t, s.b.verifyReservedFields(h), errReservedGasUsedExceedsBlock)
+
+	// Equal-or-below the block's gas used passes the bound.
+	h.GasUsed = 5_000
+	require.NoError(t, s.b.verifyReservedFields(h))
+}
+
 // TestApplyMessage_StateSyncTxContext validates if TxContext is correctly
 // set for state-sync transactions.
 func TestApplyMessage_StateSyncTxContext(t *testing.T) {

consensus/bor/contract/client.go

@@ -22,12 +22,14 @@ import (
 )
 
 type GenesisContractsClient struct {
-	validatorSetABI       abi.ABI
-	stateReceiverABI      abi.ABI
-	ValidatorContract     string
-	StateReceiverContract string
-	chainConfig           *params.ChainConfig
-	ethAPI                api.Caller
+	validatorSetABI          abi.ABI
+	stateReceiverABI         abi.ABI
+	reservedRegistryABI      abi.ABI
+	ValidatorContract        string
+	StateReceiverContract    string
+	ReservedRegistryContract string
+	chainConfig              *params.ChainConfig
+	ethAPI                   api.Caller
 }
 
 func NewGenesisContractsClient(
@@ -37,12 +39,14 @@ func NewGenesisContractsClient(
 	ethAPI api.Caller,
 ) *GenesisContractsClient {
 	return &GenesisContractsClient{
-		validatorSetABI:       borabi.ValidatorSet(),
-		stateReceiverABI:      borabi.StateReceiver(),
-		ValidatorContract:     validatorContract,
-		StateReceiverContract: stateReceiverContract,
-		chainConfig:           chainConfig,
-		ethAPI:                ethAPI,
+		validatorSetABI:          borabi.ValidatorSet(),
+		stateReceiverABI:         borabi.StateReceiver(),
+		reservedRegistryABI:      borabi.ReservedBlockspaceRegistry(),
+		ValidatorContract:        validatorContract,
+		StateReceiverContract:    stateReceiverContract,
+		ReservedRegistryContract: chainConfig.Bor.ReservedRegistryContract,
+		chainConfig:              chainConfig,
+		ethAPI:                   ethAPI,
 	}
 }