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/freshness/freshness_test.go

@@ -42,6 +42,19 @@ func TestBuildSnapshotHealthyState(t *testing.T) {
 				*dest[1].(*time.Time) = now.Add(-5 * time.Second)
 				return nil
 			}}
+		case 4:
+			return fakeRow{scan: func(dest ...any) error {
+				*dest[0].(*int64) = 198
+				*dest[1].(*time.Time) = now.Add(-5 * time.Second)
+				return nil
+			}}
+		case 5:
+			return fakeRow{scan: func(dest ...any) error {
+				*dest[0].(*int64) = 128
+				*dest[1].(*int64) = 12
+				*dest[2].(*int64) = 34
+				return nil
+			}}
 		default:
 			t.Fatalf("unexpected call %d", call)
 			return nil
@@ -63,13 +76,14 @@ func TestBuildSnapshotHealthyState(t *testing.T) {
 		}, nil
 	}
 
-	snapshot, completeness, sampling, err := BuildSnapshot(context.Background(), 138, queryRow, probe, now, nil, nil)
+	snapshot, completeness, sampling, diagnostics, err := BuildSnapshot(context.Background(), 138, queryRow, probe, now, nil, nil)
 	require.NoError(t, err)
 	require.Equal(t, int64(200), *snapshot.ChainHead.BlockNumber)
 	require.Equal(t, int64(198), *snapshot.LatestIndexedTransaction.BlockNumber)
 	require.Equal(t, int64(2), *snapshot.LatestNonEmptyBlock.DistanceFromHead)
 	require.Equal(t, CompletenessComplete, completeness.TransactionsFeed)
 	require.NotNil(t, sampling.StatsGeneratedAt)
+	require.Equal(t, "active", diagnostics.ActivityState)
 }
 
 func TestBuildSnapshotFreshHeadStaleTransactionVisibility(t *testing.T) {
@@ -97,6 +111,19 @@ func TestBuildSnapshotFreshHeadStaleTransactionVisibility(t *testing.T) {
 				*dest[1].(*time.Time) = now.Add(-(9*time.Hour + 8*time.Minute))
 				return nil
 			}}
+		case 4:
+			return fakeRow{scan: func(dest ...any) error {
+				*dest[0].(*int64) = 3875998
+				*dest[1].(*time.Time) = now.Add(-4 * time.Second)
+				return nil
+			}}
+		case 5:
+			return fakeRow{scan: func(dest ...any) error {
+				*dest[0].(*int64) = 128
+				*dest[1].(*int64) = 3
+				*dest[2].(*int64) = 9
+				return nil
+			}}
 		default:
 			t.Fatalf("unexpected call %d", call)
 			return nil
@@ -118,11 +145,12 @@ func TestBuildSnapshotFreshHeadStaleTransactionVisibility(t *testing.T) {
 		}, nil
 	}
 
-	snapshot, completeness, _, err := BuildSnapshot(context.Background(), 138, queryRow, probe, now, nil, nil)
+	snapshot, completeness, _, diagnostics, err := BuildSnapshot(context.Background(), 138, queryRow, probe, now, nil, nil)
 	require.NoError(t, err)
 	require.Equal(t, int64(15340), *snapshot.LatestNonEmptyBlock.DistanceFromHead)
 	require.Equal(t, CompletenessStale, completeness.TransactionsFeed)
 	require.Equal(t, CompletenessComplete, completeness.BlocksFeed)
+	require.Equal(t, "fresh_head_stale_transaction_visibility", diagnostics.ActivityState)
 }
 
 func TestBuildSnapshotQuietChainButCurrent(t *testing.T) {
@@ -150,6 +178,19 @@ func TestBuildSnapshotQuietChainButCurrent(t *testing.T) {
 				*dest[1].(*time.Time) = now.Add(-512 * time.Second)
 				return nil
 			}}
+		case 4:
+			return fakeRow{scan: func(dest ...any) error {
+				*dest[0].(*int64) = 3874902
+				*dest[1].(*time.Time) = now.Add(-512 * time.Second)
+				return nil
+			}}
+		case 5:
+			return fakeRow{scan: func(dest ...any) error {
+				*dest[0].(*int64) = 128
+				*dest[1].(*int64) = 0
+				*dest[2].(*int64) = 0
+				return nil
+			}}
 		default:
 			t.Fatalf("unexpected call %d", call)
 			return nil
@@ -171,10 +212,11 @@ func TestBuildSnapshotQuietChainButCurrent(t *testing.T) {
 		}, nil
 	}
 
-	snapshot, completeness, _, err := BuildSnapshot(context.Background(), 138, queryRow, probe, now, nil, nil)
+	snapshot, completeness, _, diagnostics, err := BuildSnapshot(context.Background(), 138, queryRow, probe, now, nil, nil)
 	require.NoError(t, err)
 	require.Equal(t, int64(98), *snapshot.LatestNonEmptyBlock.DistanceFromHead)
 	require.Equal(t, CompletenessComplete, completeness.TransactionsFeed)
+	require.Equal(t, "quiet_chain", diagnostics.ActivityState)
 }
 
 func TestBuildSnapshotUnknownFieldsRemainNullSafe(t *testing.T) {
@@ -184,9 +226,10 @@ func TestBuildSnapshotUnknownFieldsRemainNullSafe(t *testing.T) {
 		}}
 	}
 
-	snapshot, completeness, sampling, err := BuildSnapshot(context.Background(), 138, queryRow, nil, time.Now().UTC(), nil, nil)
+	snapshot, completeness, sampling, diagnostics, err := BuildSnapshot(context.Background(), 138, queryRow, nil, time.Now().UTC(), nil, nil)
 	require.NoError(t, err)
 	require.Nil(t, snapshot.ChainHead.BlockNumber)
 	require.Equal(t, CompletenessUnavailable, completeness.TransactionsFeed)
 	require.NotNil(t, sampling.StatsGeneratedAt)
+	require.Equal(t, "limited_observability", diagnostics.ActivityState)
 }