feat: add FindHeaderForHeight to retrieve block header by height (#687)

Author: chris-4chain

pkg/services/chaintracks/bulk_manager.go

@@ -9,6 +9,7 @@ import (
 	"github.com/bsv-blockchain/go-wallet-toolbox/pkg/internal/logging"
 	"github.com/bsv-blockchain/go-wallet-toolbox/pkg/services/chaintracks/ingest"
 	"github.com/bsv-blockchain/go-wallet-toolbox/pkg/services/chaintracks/models"
+	"github.com/bsv-blockchain/go-wallet-toolbox/pkg/wdk"
 	"github.com/go-softwarelab/common/pkg/must"
 )
 
@@ -84,6 +85,26 @@ func (bm *bulkManager) GetHeightRange() models.HeightRange {
 	return models.NewHeightRange(minHeight, maxHeight)
 }
 
+func (bm *bulkManager) FindHeaderForHeight(height uint) (*wdk.ChainBlockHeader, error) {
+	bm.locker.RLock()
+	defer bm.locker.RUnlock()
+
+	for _, bulkFile := range bm.bulkFiles {
+		fileRange := bulkFile.Info.ToHeightRange()
+		if fileRange.ContainsHeight(height) {
+			index := height - bulkFile.Info.FirstHeight
+			header, err := bulkFile.GetHeaderAtIndex(index)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get header for height %d from bulk file %v: %w", height, bulkFile.Info, err)
+			}
+
+			return header, nil
+		}
+	}
+
+	return nil, nil
+}
+
 func (bm *bulkManager) processBulkChunks(ctx context.Context, bulkChunks []ingest.BulkHeaderFileInfo, downloader ingest.BulkFileDownloader) error {
 	chunksToLoad := bm.getChunksToLoad(bulkChunks)
 	loadedChunks := make([]ingest.BulkFileData, 0, len(chunksToLoad))

pkg/services/chaintracks/chaintracks_service.go

@@ -227,6 +227,30 @@ func (s *Service) FindChainTipHash(ctx context.Context) (string, error) {
 	}
 }
 
+// FindHeaderForHeight returns the chain block header for the given height from live storage or bulk storage if available.
+// Returns an error if the header is not found or if storage access fails.
+// In case of "not-found" the error wraps wdk.ErrNotFoundError for easier identification.
+func (s *Service) FindHeaderForHeight(ctx context.Context, height uint) (*wdk.ChainBlockHeader, error) {
+	liveHeader, err := s.storage.Query(ctx).GetLiveHeaderByHeight(height)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get live header by height: %w", err)
+	}
+	if liveHeader != nil {
+		return &liveHeader.ChainBlockHeader, nil
+	}
+
+	header, err := s.bulkMgr.FindHeaderForHeight(height)
+	if err != nil {
+		return nil, fmt.Errorf("failed to find header for height in bulk storage: %w", err)
+	}
+
+	if header == nil {
+		return nil, fmt.Errorf("header not found for height %d: %w", height, wdk.ErrNotFoundError)
+	}
+
+	return header, nil
+}
+
 func (s *Service) getMissingBlockHeader(ctx context.Context, hash string) *wdk.ChainBlockHeader {
 	for _, liveIngestor := range s.liveIngestors {
 		header, err := liveIngestor.Ingestor.GetHeaderByHash(ctx, hash)

pkg/services/chaintracks/chaintracks_service_test.go

@@ -29,32 +29,70 @@ func TestService_Lifecycle(t *testing.T) {
 	require.NoError(t, err, "make available should not return error")
 	require.True(t, service.Available(), "service should be available after make available")
 
-	// when
-	info, err := service.GetInfo(t.Context())
-
-	// then:
-	require.NoError(t, err, "get info should not return error")
-	assert.Equal(t, defs.NetworkMainnet, info.Chain)
-	assert.Equal(t, "gorm-sqlite-inmemory", info.Storage)
-	assert.Equal(t, []string{"woc_poll"}, info.LiveIngestors)
-	assert.Equal(t, []string{"chaintracks_cdn (source_url=https://cdn.projectbabbage.com/blockheaders)", "whats_on_chain_cdn"}, info.BulkIngestors)
-	t.Logf("Bulk height: %d", info.HeightBulk) // TODO: When we use live data (not mocked), this value is not constant; will be changed to assert.Equal later
-	t.Logf("Live height: %d", info.HeightLive)
-
 	// when:
 	height, err := service.GetPresentHeight(t.Context())
 
 	// then:
 	require.NoError(t, err, "get present height should not return error")
 	require.Greater(t, height, uint(900000), "present height should be greater than 900000")
 
-	// when:
-	tipHeader, err := service.FindChainTipHeader(t.Context())
+	t.Run("GetInfo", func(t *testing.T) {
+		// when:
+		info, err := service.GetInfo(t.Context())
+
+		// then:
+		require.NoError(t, err, "get info should not return error")
+		assert.Equal(t, defs.NetworkMainnet, info.Chain)
+		assert.Equal(t, "gorm-sqlite-inmemory", info.Storage)
+		assert.Equal(t, []string{"woc_poll"}, info.LiveIngestors)
+		assert.Equal(t, []string{"chaintracks_cdn (source_url=https://cdn.projectbabbage.com/blockheaders)", "whats_on_chain_cdn"}, info.BulkIngestors)
+		t.Logf("Bulk height: %d", info.HeightBulk) // TODO: When we use live data (not mocked), this value is not constant; will be changed to assert.Equal later
+		t.Logf("Live height: %d", info.HeightLive)
+	})
 
-	// then:
-	require.NoError(t, err, "find chain tip header should not return error")
-	require.NotNil(t, tipHeader, "tip header should not be nil")
-	require.Equal(t, height, tipHeader.Height, "tip header height should be equal to present height")
+	t.Run("FindChainTipHeader", func(t *testing.T) {
+		// when:
+		tipHeader, err := service.FindChainTipHeader(t.Context())
+
+		// then:
+		require.NoError(t, err, "find chain tip header should not return error")
+		require.NotNil(t, tipHeader, "tip header should not be nil")
+		require.Equal(t, height, tipHeader.Height, "tip header height should be equal to present height")
+	})
+
+	t.Run("FindHeaderForHeight_recent", func(t *testing.T) {
+		// when:
+		header, err := service.FindHeaderForHeight(t.Context(), height-10)
+
+		// then:
+		require.NoError(t, err, "find header for height should not return error")
+		require.NotNil(t, header, "header should not be nil")
+		require.Equal(t, height-10, header.Height, "header height should be equal to requested height")
+		t.Logf("Header at height %d: %#+v", header.Height, header)
+	})
+
+	t.Run("FindHeaderForHeight_genesis", func(t *testing.T) {
+		// when:
+		header, err := service.FindHeaderForHeight(t.Context(), 0)
+
+		// then:
+		require.NoError(t, err, "find header for height 0 should not return error")
+		require.NotNil(t, header, "header at height 0 should not be nil")
+		require.Equal(t, uint(0), header.Height, "header height should be 0")
+		require.Equal(t, "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f", header.Hash, "header hash at height 0 should be genesis hash")
+		t.Logf("Genesis header: %#+v", header)
+	})
+
+	t.Run("FindHeaderForHeight_old", func(t *testing.T) {
+		// when:
+		header, err := service.FindHeaderForHeight(t.Context(), height-5000)
+
+		// then:
+		require.NoError(t, err, "find header for height should not return error")
+		require.NotNil(t, header, "header should not be nil")
+		require.Equal(t, height-5000, header.Height, "header height should be equal to requested height")
+		t.Logf("Header at height %d: %#+v", header.Height, header)
+	})
 
 	// when:
 	service.Destroy()

pkg/services/chaintracks/gormstorage/storage_queries.go

@@ -164,3 +164,18 @@ func (i *storageQueries) FindLiveHeightRange() (models.HeightRange, error) {
 
 	return models.NewHeightRange(*res.MinHeight, *res.MaxHeight), nil
 }
+
+func (i *storageQueries) GetLiveHeaderByHeight(height uint) (*models.LiveBlockHeader, error) {
+	table := i.getQuery().ChaintracksLiveHeader
+	model, err := table.
+		Where(table.Height.Eq(height)).
+		Where(table.IsActive.Is(true)).
+		First()
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("failed to get live header by height: %w", err)
+	}
+	return mapLiveHeader(model), nil
+}

pkg/services/chaintracks/models/storage_queries.go

@@ -14,6 +14,6 @@ type StorageQueries interface {
 	SetChainTipByID(id uint, isChainTip bool) error
 	InsertNewLiveHeader(header *LiveBlockHeader) error
 	CountLiveHeaders() (int64, error)
-
+	GetLiveHeaderByHeight(height uint) (*LiveBlockHeader, error)
 	FindLiveHeightRange() (HeightRange, error)
 }