feature: block tag support(safe&finalize)

core/blockchain.go

@@ -194,6 +194,9 @@ type BlockChain struct {
 	currentBlock     atomic.Value // Current head of the block chain
 	currentFastBlock atomic.Value // Current head of the fast-sync chain (may be above the block chain!)
 
+	currentSafeBlock      atomic.Pointer[types.Header] // Current safe block (derived from L1 batch committed)
+	currentFinalizedBlock atomic.Pointer[types.Header] // Current finalized block (derived from L1 batch finalized)
+
 	stateCache    state.Database // State database to reuse between imports (contains state cache)
 	bodyCache     *lru.Cache     // Cache for the most recent block bodies
 	bodyRLPCache  *lru.Cache     // Cache for the most recent block bodies in RLP encoded format
@@ -478,6 +481,14 @@ func (bc *BlockChain) loadLastState() error {
 			headFastBlockGauge.Update(int64(block.NumberU64()))
 		}
 	}
+	// Restore the last known finalized block, and set safe = finalized on startup
+	if head := rawdb.ReadFinalizedBlockHash(bc.db); head != (common.Hash{}) {
+		if header := bc.GetHeaderByHash(head); header != nil {
+			bc.currentFinalizedBlock.Store(header)
+			bc.currentSafeBlock.Store(header) // safe = finalized on startup
+			log.Info("Loaded finalized block", "number", header.Number, "hash", header.Hash())
+		}
+	}
 	// Issue a status log for the user
 	currentFastBlock := bc.CurrentFastBlock()
 
@@ -488,6 +499,9 @@ func (bc *BlockChain) loadLastState() error {
 	log.Info("Loaded most recent local header", "number", currentHeader.Number, "hash", currentHeader.Hash(), "td", headerTd, "age", common.PrettyAge(time.Unix(int64(currentHeader.Time), 0)))
 	log.Info("Loaded most recent local full block", "number", currentBlock.Number(), "hash", currentBlock.Hash(), "td", blockTd, "age", common.PrettyAge(time.Unix(int64(currentBlock.Time()), 0)))
 	log.Info("Loaded most recent local fast block", "number", currentFastBlock.Number(), "hash", currentFastBlock.Hash(), "td", fastTd, "age", common.PrettyAge(time.Unix(int64(currentFastBlock.Time()), 0)))
+	if finalizedBlock := bc.CurrentFinalizedBlock(); finalizedBlock != nil {
+		log.Info("Loaded most recent local finalized block", "number", finalizedBlock.Number, "hash", finalizedBlock.Hash())
+	}
 	if pivot := rawdb.ReadLastPivotNumber(bc.db); pivot != nil {
 		log.Info("Loaded last fast-sync pivot marker", "number", *pivot)
 	}

core/blockchain_l2.go

@@ -247,3 +247,22 @@ func (bc *BlockChain) collectLogs(b *types.Block, removed bool) []*types.Log {
 	}
 	return logs
 }
+
+// SetSafe sets the safe block header. The safe block is derived from
+// L1 batch committed status. It represents the block that has been
+// submitted to L1 and is considered safe.
+func (bc *BlockChain) SetSafe(header *types.Header) {
+	bc.currentSafeBlock.Store(header)
+	log.Debug("Set safe block", "number", header.Number, "hash", header.Hash())
+}
+
+// SetFinalized sets the finalized block header. The finalized block is
+// derived from L1 batch finalized status. It represents the block that
+// has been finalized on L1 and is considered irreversible.
+// Also persists to rawdb for recovery on restart.
+func (bc *BlockChain) SetFinalized(header *types.Header) {
+	bc.currentFinalizedBlock.Store(header)
+	// Persist to rawdb for recovery on restart
+	rawdb.WriteFinalizedBlockHash(bc.db, header.Hash())
+	log.Debug("Set finalized block", "number", header.Number, "hash", header.Hash())
+}

core/blockchain_reader.go

@@ -49,6 +49,20 @@ func (bc *BlockChain) CurrentFastBlock() *types.Block {
 	return bc.currentFastBlock.Load().(*types.Block)
 }
 
+// CurrentSafeBlock retrieves the current safe block of the canonical chain.
+// The safe block is derived from L1 batch committed status.
+// Returns nil if no safe block has been set yet.
+func (bc *BlockChain) CurrentSafeBlock() *types.Header {
+	return bc.currentSafeBlock.Load()
+}
+
+// CurrentFinalizedBlock retrieves the current finalized block of the canonical chain.
+// The finalized block is derived from L1 batch finalized status.
+// Returns nil if no finalized block has been set yet.
+func (bc *BlockChain) CurrentFinalizedBlock() *types.Header {
+	return bc.currentFinalizedBlock.Load()
+}
+
 // HasHeader checks if a block header is present in the database or not, caching
 // it if present.
 func (bc *BlockChain) HasHeader(hash common.Hash, number uint64) bool {

core/rawdb/accessors_chain.go

@@ -215,6 +215,22 @@ func WriteHeadFastBlockHash(db ethdb.KeyValueWriter, hash common.Hash) {
 	}
 }
 
+// ReadFinalizedBlockHash retrieves the hash of the current finalized block.
+func ReadFinalizedBlockHash(db ethdb.KeyValueReader) common.Hash {
+	data, _ := db.Get(headFinalizedBlockKey)
+	if len(data) == 0 {
+		return common.Hash{}
+	}
+	return common.BytesToHash(data)
+}
+
+// WriteFinalizedBlockHash stores the hash of the current finalized block.
+func WriteFinalizedBlockHash(db ethdb.KeyValueWriter, hash common.Hash) {
+	if err := db.Put(headFinalizedBlockKey, hash.Bytes()); err != nil {
+		log.Crit("Failed to store finalized block's hash", "err", err)
+	}
+}
+
 // ReadLastPivotNumber retrieves the number of the last pivot block. If the node
 // full synced, the last pivot will always be nil.
 func ReadLastPivotNumber(db ethdb.KeyValueReader) *uint64 {

core/rawdb/schema.go

@@ -43,6 +43,9 @@ var (
 	// headFastBlockKey tracks the latest known incomplete block's hash during fast sync.
 	headFastBlockKey = []byte("LastFast")
 
+	// headFinalizedBlockKey tracks the latest known finalized block's hash.
+	headFinalizedBlockKey = []byte("LastFinalized")
+
 	// lastPivotKey tracks the last pivot block used by fast sync (to reenable on sethead).
 	lastPivotKey = []byte("LastPivot")
 

eth/api.go

@@ -176,16 +176,25 @@ func (api *PublicDebugAPI) DumpBlock(blockNr rpc.BlockNumber) (state.Dump, error
 		_, _, stateDb := api.eth.miner.Pending()
 		return stateDb.RawDump(opts), nil
 	}
-	var block *types.Block
-	if blockNr == rpc.LatestBlockNumber {
-		block = api.eth.blockchain.CurrentBlock()
-	} else {
-		block = api.eth.blockchain.GetBlockByNumber(uint64(blockNr))
+	var header *types.Header
+	switch blockNr {
+	case rpc.LatestBlockNumber:
+		header = api.eth.blockchain.CurrentBlock().Header()
+	case rpc.SafeBlockNumber:
+		header = api.eth.blockchain.CurrentSafeBlock()
+	case rpc.FinalizedBlockNumber:
+		header = api.eth.blockchain.CurrentFinalizedBlock()
+	default:
+		block := api.eth.blockchain.GetBlockByNumber(uint64(blockNr))
+		if block == nil {
+			return state.Dump{}, fmt.Errorf("block #%d not found", blockNr)
+		}
+		header = block.Header()
 	}
-	if block == nil {
+	if header == nil {
 		return state.Dump{}, fmt.Errorf("block #%d not found", blockNr)
 	}
-	stateDb, err := api.eth.BlockChain().StateAt(block.Root())
+	stateDb, err := api.eth.BlockChain().StateAt(header.Root)
 	if err != nil {
 		return state.Dump{}, err
 	}
@@ -264,16 +273,25 @@ func (api *PublicDebugAPI) AccountRange(blockNrOrHash rpc.BlockNumberOrHash, sta
 			// the miner and operate on those
 			_, _, stateDb = api.eth.miner.Pending()
 		} else {
-			var block *types.Block
-			if number == rpc.LatestBlockNumber {
-				block = api.eth.blockchain.CurrentBlock()
-			} else {
-				block = api.eth.blockchain.GetBlockByNumber(uint64(number))
+			var header *types.Header
+			switch number {
+			case rpc.LatestBlockNumber:
+				header = api.eth.blockchain.CurrentBlock().Header()
+			case rpc.SafeBlockNumber:
+				header = api.eth.blockchain.CurrentSafeBlock()
+			case rpc.FinalizedBlockNumber:
+				header = api.eth.blockchain.CurrentFinalizedBlock()
+			default:
+				block := api.eth.blockchain.GetBlockByNumber(uint64(number))
+				if block == nil {
+					return state.IteratorDump{}, fmt.Errorf("block #%d not found", number)
+				}
+				header = block.Header()
 			}
-			if block == nil {
+			if header == nil {
 				return state.IteratorDump{}, fmt.Errorf("block #%d not found", number)
 			}
-			stateDb, err = api.eth.BlockChain().StateAt(block.Root())
+			stateDb, err = api.eth.BlockChain().StateAt(header.Root)
 			if err != nil {
 				return state.IteratorDump{}, err
 			}

eth/api_backend.go

@@ -75,6 +75,22 @@ func (b *EthAPIBackend) HeaderByNumber(ctx context.Context, number rpc.BlockNumb
 	if number == rpc.LatestBlockNumber {
 		return b.eth.blockchain.CurrentBlock().Header(), nil
 	}
+	// Safe block
+	if number == rpc.SafeBlockNumber {
+		header := b.eth.blockchain.CurrentSafeBlock()
+		if header == nil {
+			return nil, errors.New("safe block not available")
+		}
+		return header, nil
+	}
+	// Finalized block
+	if number == rpc.FinalizedBlockNumber {
+		header := b.eth.blockchain.CurrentFinalizedBlock()
+		if header == nil {
+			return nil, errors.New("finalized block not available")
+		}
+		return header, nil
+	}
 	return b.eth.blockchain.GetHeaderByNumber(uint64(number)), nil
 }
 
@@ -109,6 +125,22 @@ func (b *EthAPIBackend) BlockByNumber(ctx context.Context, number rpc.BlockNumbe
 	if number == rpc.LatestBlockNumber {
 		return b.eth.blockchain.CurrentBlock(), nil
 	}
+	// Safe block
+	if number == rpc.SafeBlockNumber {
+		header := b.eth.blockchain.CurrentSafeBlock()
+		if header == nil {
+			return nil, errors.New("safe block not available")
+		}
+		return b.eth.blockchain.GetBlock(header.Hash(), header.Number.Uint64()), nil
+	}
+	// Finalized block
+	if number == rpc.FinalizedBlockNumber {
+		header := b.eth.blockchain.CurrentFinalizedBlock()
+		if header == nil {
+			return nil, errors.New("finalized block not available")
+		}
+		return b.eth.blockchain.GetBlock(header.Hash(), header.Number.Uint64()), nil
+	}
 	return b.eth.blockchain.GetBlockByNumber(uint64(number)), nil
 }
 

eth/catalyst/l2_api.go

@@ -360,3 +360,32 @@ func (api *l2ConsensusAPI) isVerified(blockHash common.Hash) (executionResult, b
 	er, found := api.verified[blockHash]
 	return er, found
 }
+
+// SetBlockTags sets the safe and finalized block by hash.
+// This is called by the node layer when it determines the safe/finalized
+// status based on L1 batch information.
+func (api *l2ConsensusAPI) SetBlockTags(safeBlockHash common.Hash, finalizedBlockHash common.Hash) error {
+	bc := api.eth.BlockChain()
+
+	// Set finalized block
+	if finalizedBlockHash != (common.Hash{}) {
+		finalizedHeader := bc.GetHeaderByHash(finalizedBlockHash)
+		if finalizedHeader == nil {
+			return fmt.Errorf("finalized block %s not found", finalizedBlockHash.Hex())
+		}
+		bc.SetFinalized(finalizedHeader)
+		log.Info("Set finalized block", "number", finalizedHeader.Number, "hash", finalizedBlockHash)
+	}
+
+	// Set safe block
+	if safeBlockHash != (common.Hash{}) {
+		safeHeader := bc.GetHeaderByHash(safeBlockHash)
+		if safeHeader == nil {
+			return fmt.Errorf("safe block %s not found", safeBlockHash.Hex())
+		}
+		bc.SetSafe(safeHeader)
+		log.Info("Set safe block", "number", safeHeader.Number, "hash", safeBlockHash)
+	}
+
+	return nil
+}

eth/filters/filter.go

@@ -122,21 +122,55 @@ func (f *Filter) Logs(ctx context.Context) ([]*types.Log, error) {
 		return f.pendingLogs()
 	}
 	// Figure out the limits of the filter range
-	header, _ := f.sys.backend.HeaderByNumber(ctx, rpc.LatestBlockNumber)
-	if header == nil {
-		return nil, nil
+	resolveSpecial := func(number int64) (uint64, error) {
+		switch number {
+		case rpc.PendingBlockNumber.Int64(), // inheriting the current logic, pending logs will be disabled in the future
+			rpc.LatestBlockNumber.Int64():
+			hdr, _ := f.sys.backend.HeaderByNumber(ctx, rpc.LatestBlockNumber)
+			if hdr == nil {
+				return 0, errors.New("latest header not found")
+			}
+			return hdr.Number.Uint64(), nil
+		case rpc.SafeBlockNumber.Int64():
+			hdr, _ := f.sys.backend.HeaderByNumber(ctx, rpc.SafeBlockNumber)
+			if hdr == nil {
+				return 0, errors.New("safe header not found")
+			}
+			return hdr.Number.Uint64(), nil
+		case rpc.FinalizedBlockNumber.Int64():
+			hdr, _ := f.sys.backend.HeaderByNumber(ctx, rpc.FinalizedBlockNumber)
+			if hdr == nil {
+				return 0, errors.New("finalized header not found")
+			}
+			return hdr.Number.Uint64(), nil
+		default:
+			if number < 0 {
+				return 0, errors.New("negative block number")
+			}
+			return uint64(number), nil
+		}
 	}
+
 	var (
-		head    = header.Number.Uint64()
-		end     = uint64(f.end)
-		pending = f.end == rpc.PendingBlockNumber.Int64()
+		begin, end uint64
+		pending    = f.end == rpc.PendingBlockNumber.Int64()
+		err        error
 	)
-	if f.begin == rpc.LatestBlockNumber.Int64() {
-		f.begin = int64(head)
+
+	begin, err = resolveSpecial(f.begin)
+	if err != nil {
+		return nil, err
 	}
-	if f.end == rpc.LatestBlockNumber.Int64() || f.end == rpc.PendingBlockNumber.Int64() {
-		end = head
+	end, err = resolveSpecial(f.end)
+	if err != nil {
+		return nil, err
+	}
+
+	if begin > end {
+		return nil, nil
 	}
+	f.begin = int64(begin)
+	f.end = int64(end)
 
 	// if maxBlockRange configured then check for
 	if f.maxBlockRange != -1 && int64(end)-f.begin+1 > f.maxBlockRange {
@@ -145,7 +179,6 @@ func (f *Filter) Logs(ctx context.Context) ([]*types.Log, error) {
 	// Gather all indexed logs, and finish with non indexed ones
 	var (
 		logs           []*types.Log
-		err            error
 		size, sections = f.sys.backend.BloomStatus()
 	)
 	if indexed := sections * size; indexed > uint64(f.begin) {