feat(freshness): enhance diagnostics and update snapshot structure

- Introduced a new Diagnostics struct to capture transaction visibility state and activity state.
- Updated BuildSnapshot function to return diagnostics alongside snapshot, completeness, and sampling.
- Enhanced test cases to validate the new diagnostics data.
- Updated frontend components to utilize the new diagnostics information for improved user feedback on freshness context.

This change improves the observability of transaction activity and enhances the user experience by providing clearer insights into the freshness of data.

backend/api/rest/stats.go

@@ -25,6 +25,7 @@ type explorerStats struct {
 	Freshness                    freshness.Snapshot            `json:"freshness"`
 	Completeness                 freshness.SummaryCompleteness `json:"completeness"`
 	Sampling                     freshness.Sampling            `json:"sampling"`
+	Diagnostics                  freshness.Diagnostics         `json:"diagnostics"`
 }
 
 type explorerGasPrices struct {
@@ -160,7 +161,7 @@ func loadExplorerStats(ctx context.Context, chainID int, queryRow statsQueryFunc
 	}
 
 	rpcURL := strings.TrimSpace(os.Getenv("RPC_URL"))
-	snapshot, completeness, sampling, err := freshness.BuildSnapshot(
+	snapshot, completeness, sampling, diagnostics, err := freshness.BuildSnapshot(
 		ctx,
 		chainID,
 		queryRow,
@@ -185,6 +186,7 @@ func loadExplorerStats(ctx context.Context, chainID int, queryRow statsQueryFunc
 	stats.Freshness = snapshot
 	stats.Completeness = completeness
 	stats.Sampling = sampling
+	stats.Diagnostics = diagnostics
 
 	return stats, nil
 }

backend/api/rest/stats_internal_test.go

@@ -76,6 +76,13 @@ func TestLoadExplorerStatsReturnsValues(t *testing.T) {
 				case 11:
 					*dest[0].(*int64) = 40
 					*dest[1].(*time.Time) = time.Now().Add(-5 * time.Second)
+				case 12:
+					*dest[0].(*int64) = 42
+					*dest[1].(*time.Time) = time.Now().Add(-3 * time.Second)
+				case 13:
+					*dest[0].(*int64) = 128
+					*dest[1].(*int64) = 10
+					*dest[2].(*int64) = 22
 				default:
 					t.Fatalf("unexpected query call %d", call)
 				}
@@ -102,6 +109,8 @@ func TestLoadExplorerStatsReturnsValues(t *testing.T) {
 	require.NotNil(t, stats.Freshness.ChainHead.BlockNumber)
 	require.Equal(t, int64(40), *stats.Freshness.LatestIndexedTransaction.BlockNumber)
 	require.Equal(t, int64(4), *stats.Freshness.LatestNonEmptyBlock.DistanceFromHead)
+	require.Equal(t, "active", stats.Diagnostics.ActivityState)
+	require.Equal(t, int64(4), *stats.Diagnostics.TxLagBlocks)
 	require.Equal(t, "reported", string(stats.Freshness.ChainHead.Source))
 	require.Equal(t, freshness.CompletenessComplete, stats.Completeness.GasMetrics)
 	require.Equal(t, freshness.CompletenessComplete, stats.Completeness.UtilizationMetric)

backend/api/rest/track_routes.go

@@ -50,12 +50,12 @@ func (s *Server) SetupTrackRoutes(mux *http.ServeMux, authMiddleware *middleware
 	}
 
 	rpcGateway := gateway.NewRPCGateway(rpcURL, cache, rateLimiter)
-	track1Server := track1.NewServer(rpcGateway, func(ctx context.Context) (*freshness.Snapshot, *freshness.SummaryCompleteness, *freshness.Sampling, error) {
+	track1Server := track1.NewServer(rpcGateway, func(ctx context.Context) (*freshness.Snapshot, *freshness.SummaryCompleteness, *freshness.Sampling, *freshness.Diagnostics, error) {
 		if s.db == nil {
-			return nil, nil, nil, nil
+			return nil, nil, nil, nil, nil
 		}
 		now := time.Now().UTC()
-		snapshot, completeness, sampling, err := freshness.BuildSnapshot(
+		snapshot, completeness, sampling, diagnostics, err := freshness.BuildSnapshot(
 			ctx,
 			s.chainID,
 			s.db.QueryRow,
@@ -67,9 +67,9 @@ func (s *Server) SetupTrackRoutes(mux *http.ServeMux, authMiddleware *middleware
 			nil,
 		)
 		if err != nil {
-			return nil, nil, nil, err
+			return nil, nil, nil, nil, err
 		}
-		return &snapshot, &completeness, &sampling, nil
+		return &snapshot, &completeness, &sampling, &diagnostics, nil
 	})
 
 	// Track 1 routes (public, optional auth)