core/filtermaps: FilterMaps log index generator and search logic

core/filtermaps/chain_view.go

@@ -0,0 +1,156 @@
+// Copyright 2025 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library 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.
+//
+// The go-ethereum library 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 the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+package filtermaps
+
+import (
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/log"
+)
+
+// blockchain represents the underlying blockchain of ChainView.
+type blockchain interface {
+	GetHeader(hash common.Hash, number uint64) *types.Header
+	GetCanonicalHash(number uint64) common.Hash
+	GetReceiptsByHash(hash common.Hash) types.Receipts
+}
+
+// ChainView represents an immutable view of a chain with a block id and a set
+// of receipts associated to each block number and a block hash associated with
+// all block numbers except the head block. This is because in the future
+// ChainView might represent a view where the head block is currently being
+// created. Block id is a unique identifier that can also be calculated for the
+// head block.
+// Note that the view's head does not have to be the current canonical head
+// of the underlying blockchain, it should only possess the block headers
+// and receipts up until the expected chain view head.
+type ChainView struct {
+	chain      blockchain
+	headNumber uint64
+	hashes     []common.Hash // block hashes starting backwards from headNumber until first canonical hash
+}
+
+// NewChainView creates a new ChainView.
+func NewChainView(chain blockchain, number uint64, hash common.Hash) *ChainView {
+	cv := &ChainView{
+		chain:      chain,
+		headNumber: number,
+		hashes:     []common.Hash{hash},
+	}
+	cv.extendNonCanonical()
+	return cv
+}
+
+// getBlockHash returns the block hash belonging to the given block number.
+// Note that the hash of the head block is not returned because ChainView might
+// represent a view where the head block is currently being created.
+func (cv *ChainView) getBlockHash(number uint64) common.Hash {
+	if number >= cv.headNumber {
+		panic("invalid block number")
+	}
+	return cv.blockHash(number)
+}
+
+// getBlockId returns the unique block id belonging to the given block number.
+// Note that it is currently equal to the block hash. In the future it might
+// be a different id for future blocks if the log index root becomes part of
+// consensus and therefore rendering the index with the new head will happen
+// before the hash of that new head is available.
+func (cv *ChainView) getBlockId(number uint64) common.Hash {
+	if number > cv.headNumber {
+		panic("invalid block number")
+	}
+	return cv.blockHash(number)
+}
+
+// getReceipts returns the set of receipts belonging to the block at the given
+// block number.
+func (cv *ChainView) getReceipts(number uint64) types.Receipts {
+	if number > cv.headNumber {
+		panic("invalid block number")
+	}
+	return cv.chain.GetReceiptsByHash(cv.blockHash(number))
+}
+
+// limitedView returns a new chain view that is a truncated version of the parent view.
+func (cv *ChainView) limitedView(newHead uint64) *ChainView {
+	if newHead >= cv.headNumber {
+		return cv
+	}
+	return NewChainView(cv.chain, newHead, cv.blockHash(newHead))
+}
+
+// equalViews returns true if the two chain views are equivalent.
+func equalViews(cv1, cv2 *ChainView) bool {
+	if cv1 == nil || cv2 == nil {
+		return false
+	}
+	return cv1.headNumber == cv2.headNumber && cv1.getBlockId(cv1.headNumber) == cv2.getBlockId(cv2.headNumber)
+}
+
+// matchViews returns true if the two chain views are equivalent up until the
+// specified block number. If the specified number is higher than one of the
+// heads then false is returned.
+func matchViews(cv1, cv2 *ChainView, number uint64) bool {
+	if cv1 == nil || cv2 == nil {
+		return false
+	}
+	if cv1.headNumber < number || cv2.headNumber < number {
+		return false
+	}
+	if number == cv1.headNumber || number == cv2.headNumber {
+		return cv1.getBlockId(number) == cv2.getBlockId(number)
+	}
+	return cv1.getBlockHash(number) == cv2.getBlockHash(number)
+}
+
+// extendNonCanonical checks whether the previously known reverse list of head
+// hashes still ends with one that is canonical on the underlying blockchain.
+// If necessary then it traverses further back on the header chain and adds
+// more hashes to the list.
+func (cv *ChainView) extendNonCanonical() bool {
+	for {
+		hash, number := cv.hashes[len(cv.hashes)-1], cv.headNumber-uint64(len(cv.hashes)-1)
+		if cv.chain.GetCanonicalHash(number) == hash {
+			return true
+		}
+		if number == 0 {
+			log.Error("Unknown genesis block hash found")
+			return false
+		}
+		header := cv.chain.GetHeader(hash, number)
+		if header == nil {
+			log.Error("Header not found", "number", number, "hash", hash)
+			return false
+		}
+		cv.hashes = append(cv.hashes, header.ParentHash)
+	}
+}
+
+// blockHash returns the given block hash without doing the head number check.
+func (cv *ChainView) blockHash(number uint64) common.Hash {
+	if number+uint64(len(cv.hashes)) <= cv.headNumber {
+		hash := cv.chain.GetCanonicalHash(number)
+		if !cv.extendNonCanonical() {
+			return common.Hash{}
+		}
+		if number+uint64(len(cv.hashes)) <= cv.headNumber {
+			return hash
+		}
+	}
+	return cv.hashes[cv.headNumber-number]
+}

core/filtermaps/checkpoints.go

@@ -0,0 +1,63 @@
+// Copyright 2025 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library 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.
+//
+// The go-ethereum library 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 the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+package filtermaps
+
+import (
+	_ "embed"
+	"encoding/json"
+
+	"github.com/ethereum/go-ethereum/common"
+)
+
+// checkpointList lists checkpoints for finalized epochs of a given chain.
+// This allows the indexer to start indexing from the latest available
+// checkpoint and then index tail epochs in reverse order.
+type checkpointList []epochCheckpoint
+
+// epochCheckpoint specified the last block of the epoch and the first log
+// value index where that block starts. This allows a log value iterator to
+// be initialized at the epoch boundary.
+type epochCheckpoint struct {
+	BlockNumber uint64 // block that generated the last log value of the given epoch
+	BlockId     common.Hash
+	FirstIndex  uint64 // first log value index of the given block
+}
+
+//go:embed checkpoints_mainnet.json
+var checkpointsMainnetJSON []byte
+
+//go:embed checkpoints_sepolia.json
+var checkpointsSepoliaJSON []byte
+
+//go:embed checkpoints_holesky.json
+var checkpointsHoleskyJSON []byte
+
+// checkpoints lists sets of checkpoints for multiple chains. The matching
+// checkpoint set is autodetected by the indexer once the canonical chain is
+// known.
+var checkpoints = []checkpointList{
+	decodeCheckpoints(checkpointsMainnetJSON),
+	decodeCheckpoints(checkpointsSepoliaJSON),
+	decodeCheckpoints(checkpointsHoleskyJSON),
+}
+
+func decodeCheckpoints(encoded []byte) (result checkpointList) {
+	if err := json.Unmarshal(encoded, &result); err != nil {
+		panic(err)
+	}
+	return
+}

core/filtermaps/checkpoints_holesky.json

@@ -0,0 +1,20 @@
+[
+{"blockNumber": 814411, "blockId": "0xf763e96fc3920359c5f706803024b78e83796a3a8563bb5a83c3ddd7cbfde287", "firstIndex": 67107637},
+{"blockNumber": 914278, "blockId": "0x0678cf8d53c0d6d27896df657d98cc73bc63ca468b6295068003938ef9b0f927", "firstIndex": 134217671},
+{"blockNumber": 1048874, "blockId": "0x3620c3d52a40ff4d9fc58c3104cfa2f327f55592caf6a2394c207a5e00b4f740", "firstIndex": 201326382},
+{"blockNumber": 1144441, "blockId": "0x438fb42850f5a0d8e1666de598a4d0106b62da0f7448c62fe029b8cbad35d08d", "firstIndex": 268435440},
+{"blockNumber": 1230411, "blockId": "0xf0ee07e60a93910723b259473a253dd9cf674e8b78c4f153b32ad7032efffeeb", "firstIndex": 335543079},
+{"blockNumber": 1309112, "blockId": "0xc1646e5ef4b4343880a85b1a4111e3321d609a1225e9cebbe10d1c7abf99e58d", "firstIndex": 402653100},
+{"blockNumber": 1380522, "blockId": "0x1617cae91989d97ac6335c4217aa6cc7f7f4c2837e20b3b5211d98d6f9e97e44", "firstIndex": 469761917},
+{"blockNumber": 1476962, "blockId": "0xd978455d2618d093dfc685d7f43f61be6dae0fa8a9cb915ae459aa6e0a5525f0", "firstIndex": 536870773},
+{"blockNumber": 1533518, "blockId": "0xe7d39d71bd9d5f1f3157c35e0329531a7950a19e3042407e38948b89b5384f78", "firstIndex": 603979664},
+{"blockNumber": 1613787, "blockId": "0xa793168d135c075732a618ec367faaed5f359ffa81898c73cb4ec54ec2caa696", "firstIndex": 671088003},
+{"blockNumber": 1719099, "blockId": "0xc4394c71a8a24efe64c5ff2afcdd1594f3708524e6084aa7dadd862bd704ab03", "firstIndex": 738196914},
+{"blockNumber": 1973165, "blockId": "0xee3a9e959a437c707a3036736ec8d42a9261ac6100972c26f65eedcde315a81d", "firstIndex": 805306333},
+{"blockNumber": 2274844, "blockId": "0x76e2d33653ed9282c63ad09d721e1f2e29064aa9c26202e20fc4cc73e8dfe5f6", "firstIndex": 872415141},
+{"blockNumber": 2530503, "blockId": "0x59f4e45345f8b8f848be5004fe75c4a28f651864256c3aa9b2da63369432b718", "firstIndex": 939523693},
+{"blockNumber": 2781903, "blockId": "0xc981e91c6fb69c5e8146ead738fcfc561831f11d7786d39c7fa533966fc37675", "firstIndex": 1006632906},
+{"blockNumber": 3101713, "blockId": "0xc7baa577c91d8439e3fc79002d2113d07ca54a4724bf2f1f5af937b7ba8e1f32", "firstIndex": 1073741382},
+{"blockNumber": 3221770, "blockId": "0xa6b8240b7883fcc71aa5001b5ba66c889975c5217e14c16edebdd6f6e23a9424", "firstIndex": 1140850360}
+]
+