feat: add FindFilterStartBlockNumber helper

go/teleportr/drivers/disburser/find_start_block_number.go

+package disburser
+
+// FilterStartBlockNumberParams holds the arguments passed to
+// FindFilterStartBlockNumber.
+type FilterStartBlockNumberParams struct {
+	// BlockNumber the current block height of the chain.
+	BlockNumber uint64
+
+	// NumConfirmations is the number of confirmations required to consider a
+	// block final.
+	NumConfirmations uint64
+
+	// DeployBlockNumber is the deployment height of the Deposit contract.
+	DeployBlockNumber uint64
+
+	// LastProcessedBlockNumber is the height of the last processed block.
+	//
+	// NOTE: This will be nil on the first invocation, before blocks have been
+	// ingested.
+	LastProcessedBlockNumber *uint64
+}
+
+func (p *FilterStartBlockNumberParams) unconfirmed(blockNumber uint64) bool {
+	return p.BlockNumber+1 < blockNumber+p.NumConfirmations
+}
+
+// FindFilterStartBlockNumber returns the block height from which to begin
+// filtering logs based on the relative heights of the chain, the contract
+// deployment, and the last block that was processed.
+func FindFilterStartBlockNumber(params FilterStartBlockNumberParams) uint64 {
+	// On initilization, always start at the deploy height.
+	if params.LastProcessedBlockNumber == nil {
+		return params.DeployBlockNumber
+	}
+
+	// If the deployment height has not exited the confirmation window, we can
+	// still begin our search from the deployment height.
+	if params.unconfirmed(params.DeployBlockNumber) {
+		return params.DeployBlockNumber
+	}
+
+	// Otherwise, start from the block immediately following the last processed
+	// block. If that height is still hasn't fully confirmed, we'll use the
+	// height of the last confirmed block.
+	var filterStartBlockNumber = *params.LastProcessedBlockNumber + 1
+	if params.unconfirmed(filterStartBlockNumber) {
+		filterStartBlockNumber = params.BlockNumber + 1 - params.NumConfirmations
+	}
+
+	return filterStartBlockNumber
+}

go/teleportr/drivers/disburser/find_start_block_number_test.go

+package disburser_test
+
+import (
+	"testing"
+
+	"github.com/ethereum-optimism/optimism/go/teleportr/drivers/disburser"
+	"github.com/stretchr/testify/require"
+)
+
+func uint64Ptr(x uint64) *uint64 {
+	return &x
+}
+
+type filterStartBlockNumberTestCase struct {
+	name                string
+	params              disburser.FilterStartBlockNumberParams
+	expStartBlockNumber uint64
+}
+
+// TestFindFilterStartBlockNumber exhaustively tests the behavior of
+// FindFilterStartBlockNumber and its edge cases.
+func TestFindFilterStartBlockNumber(t *testing.T) {
+	tests := []filterStartBlockNumberTestCase{
+		// Deploy number should be returned if LastProcessedBlockNumber is nil.
+		{
+			name: "init returns deploy block number",
+			params: disburser.FilterStartBlockNumberParams{
+				BlockNumber:              10,
+				NumConfirmations:         5,
+				DeployBlockNumber:        42,
+				LastProcessedBlockNumber: nil,
+			},
+			expStartBlockNumber: 42,
+		},
+		// Deploy number should be returned if the deploy number is still in our
+		// confirmation window.
+		{
+			name: "conf lookback before deploy number",
+			params: disburser.FilterStartBlockNumberParams{
+				BlockNumber:              43,
+				NumConfirmations:         5,
+				DeployBlockNumber:        42,
+				LastProcessedBlockNumber: uint64Ptr(43),
+			},
+			expStartBlockNumber: 42,
+		},
+		// Deploy number should be returned if the deploy number is still in our
+		// confirmation window.
+		{
+			name: "conf lookback before deploy number",
+			params: disburser.FilterStartBlockNumberParams{
+				BlockNumber:              43,
+				NumConfirmations:         44,
+				DeployBlockNumber:        42,
+				LastProcessedBlockNumber: uint64Ptr(43),
+			},
+			expStartBlockNumber: 42,
+		},
+		// If our confirmation window is ahead of the last deposit + 1, expect
+		// last deposit + 1.
+		{
+			name: "conf lookback gt last deposit plus one",
+			params: disburser.FilterStartBlockNumberParams{
+				BlockNumber:              100,
+				NumConfirmations:         5,
+				DeployBlockNumber:        42,
+				LastProcessedBlockNumber: uint64Ptr(43),
+			},
+			expStartBlockNumber: 44,
+		},
+		// If our confirmation window is equal to last deposit + 1, expect last
+		// deposit + 1.
+		{
+			name: "conf lookback eq last deposit plus one",
+			params: disburser.FilterStartBlockNumberParams{
+				BlockNumber:              48,
+				NumConfirmations:         5,
+				DeployBlockNumber:        42,
+				LastProcessedBlockNumber: uint64Ptr(43),
+			},
+			expStartBlockNumber: 44,
+		},
+		// If our confirmation window starts before last deposit + 1, expect
+		// block number - num confs + 1.
+		{
+			name: "conf lookback lt last deposit plus one",
+			params: disburser.FilterStartBlockNumberParams{
+				BlockNumber:              47,
+				NumConfirmations:         5,
+				DeployBlockNumber:        42,
+				LastProcessedBlockNumber: uint64Ptr(43),
+			},
+			expStartBlockNumber: 43,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			testFindFilterStartBlockNumber(t, test)
+		})
+	}
+}
+
+func testFindFilterStartBlockNumber(
+	t *testing.T,
+	test filterStartBlockNumberTestCase,
+) {
+
+	startBlockNumber := disburser.FindFilterStartBlockNumber(test.params)
+	require.Equal(t, test.expStartBlockNumber, startBlockNumber)
+}