exporter: fork-straddling trace ranges + /committee cardinality doc (#2968 items 1, 2)

api/handlers/exporter/committee_http.go

@@ -10,7 +10,7 @@ import (
 
 // CommitteeTraces godoc
 // @Summary Retrieve committee duty traces
-// @Description Returns consensus and post-consensus traces for requested committees.
+// @Description Returns consensus and post-consensus traces for requested committees. Without a 'roles' filter, the response contains one trace per (slot, committeeID, role) - up to two rows per (slot, committeeID), distinguished by the 'role' field.
 // @Tags Exporter
 // @Accept json
 // @Produce json

api/handlers/exporter/exporter_test.go

@@ -2613,7 +2613,7 @@ func TestExporterValidatorTraces_ForkGating_CrossForkRange(t *testing.T) {
 	}
 
 	for _, role := range roles {
-		t.Run(role.name+" without filters requires pubkeys/indices", func(t *testing.T) {
+		t.Run(role.name+" without filters returns a partial response with post-fork notes", func(t *testing.T) {
 			exp := newTestExporterForV2WithNetwork(newMockTraceStore(), newMockValidatorStore(), &netCfg)
 
 			req := httptest.NewRequest(http.MethodPost, "/traces/validator", buildJSONBody(t, map[string]any{
@@ -2624,7 +2624,20 @@ func TestExporterValidatorTraces_ForkGating_CrossForkRange(t *testing.T) {
 			req.Header.Set("Content-Type", "application/json")
 			rec := httptest.NewRecorder()
 
-			require.Error(t, exp.ValidatorTraces(rec, req))
+			// the pre-fork portion of the range legitimately yields zero traces (no
+			// mock data), so the post-fork "requires pubkeys/indices" notes must not
+			// be treated as a hard failure: expect 200 with empty data and the notes
+			// surfaced in Errors.
+			require.NoError(t, exp.ValidatorTraces(rec, req))
+			require.Equal(t, http.StatusOK, rec.Code)
+
+			var resp ValidatorTracesResponse
+			require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+			require.Empty(t, resp.Data)
+			require.NotEmpty(t, resp.Errors)
+			for _, msg := range resp.Errors {
+				require.Contains(t, msg, "committee duty post-fork")
+			}
 		})
 
 		t.Run(role.name+" with indices routes each slot by its own fork state", func(t *testing.T) {
@@ -2671,6 +2684,67 @@ func TestExporterValidatorTraces_ForkGating_CrossForkRange(t *testing.T) {
 	}
 }
 
+// TestExporterValidatorTraces_ForkGating_ZeroPreForkTraces covers the fix for a
+// fork-straddling AGGREGATOR/SYNC_COMMITTEE_CONTRIBUTION request without
+// pubkeys/indices whose pre-fork slots legitimately yield zero traces (e.g.
+// sparse aggregator duties): the response must be 200 with empty traces and
+// the post-fork notes surfaced, not a 500. A genuine error alongside those
+// notes must still yield 500.
+func TestExporterValidatorTraces_ForkGating_ZeroPreForkTraces(t *testing.T) {
+	const booleEpoch = phase0.Epoch(5)
+
+	ssvCopy := *networkconfig.TestNetwork.SSV
+	ssvCopy.Forks.Boole = booleEpoch
+	netCfg := *networkconfig.TestNetwork
+	netCfg.SSV = &ssvCopy
+
+	booleSlot := netCfg.FirstSlotAtEpoch(booleEpoch)
+	require.GreaterOrEqual(t, uint64(booleSlot), uint64(2), "boole fork slot too low for the range below")
+	from := uint64(booleSlot) - 2 // pre-Boole
+	to := uint64(booleSlot) + 2   // post-Boole
+
+	t.Run("only post-fork notes and no pre-fork traces -> 200 with empty data", func(t *testing.T) {
+		exp := newTestExporterForV2WithNetwork(newMockTraceStore(), newMockValidatorStore(), &netCfg)
+
+		req := httptest.NewRequest(http.MethodPost, "/traces/validator", buildJSONBody(t, map[string]any{
+			"from":  from,
+			"to":    to,
+			"roles": []string{"AGGREGATOR"},
+		}))
+		req.Header.Set("Content-Type", "application/json")
+		rec := httptest.NewRecorder()
+
+		require.NoError(t, exp.ValidatorTraces(rec, req))
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		var resp ValidatorTracesResponse
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+		require.Empty(t, resp.Data)
+		require.NotEmpty(t, resp.Errors, "expected post-fork notes to surface")
+		for _, msg := range resp.Errors {
+			require.Contains(t, msg, "committee duty post-fork")
+		}
+	})
+
+	t.Run("genuine error alongside notes still yields 500", func(t *testing.T) {
+		store := newMockTraceStore()
+		store.GetValidatorDutiesFunc = func(role spectypes.BeaconRole, slot phase0.Slot) ([]*traces.ValidatorDutyTrace, error) {
+			return nil, fmt.Errorf("forced error on GetValidatorDuties")
+		}
+		exp := newTestExporterForV2WithNetwork(store, newMockValidatorStore(), &netCfg)
+
+		req := httptest.NewRequest(http.MethodPost, "/traces/validator", buildJSONBody(t, map[string]any{
+			"from":  from,
+			"to":    to,
+			"roles": []string{"AGGREGATOR"},
+		}))
+		req.Header.Set("Content-Type", "application/json")
+		rec := httptest.NewRecorder()
+
+		require.Error(t, exp.ValidatorTraces(rec, req))
+	})
+}
+
 // mockValidatorStore is a simple in-memory ValidatorStore implementation for tests.
 type mockValidatorStore struct {
 	byIndex  map[phase0.ValidatorIndex]*ssvtypes.SSVShare

api/handlers/exporter/validator_http.go

@@ -1,9 +1,13 @@
 package exporter
 
 import (
+	"errors"
 	"net/http"
 
+	"github.com/hashicorp/go-multierror"
+
 	"github.com/ssvlabs/ssv/api"
+	exportercore "github.com/ssvlabs/ssv/exporter"
 )
 
 // ValidatorTraces godoc
@@ -39,12 +43,29 @@ func (e *Exporter) ValidatorTraces(w http.ResponseWriter, r *http.Request) error
 		return toApiError(e.logger, r, "validator_traces", http.StatusBadRequest, request, underlyingValidationError(errs))
 	}
 
-	// if we don't have a single valid result and we have at least one meaningful error, return an error
-	if len(result.Traces) == 0 && errs.ErrorOrNil() != nil {
+	// if we don't have a single valid result and we have at least one meaningful error, return an error.
+	// post-fork committee-duty notes are expected on fork-straddling ranges whose pre-fork slots
+	// yield no traces (e.g. sparse aggregator duties), so they don't count as a hard failure here.
+	if len(result.Traces) == 0 && errs.ErrorOrNil() != nil && !onlyPostForkCommitteeDutyNotes(errs) {
 		return toApiError(e.logger, r, "validator_traces", http.StatusInternalServerError, request, errs.ErrorOrNil())
 	}
 
 	// otherwise return a partial response with valid duties
 	response := toValidatorTraceResponse(result, errs)
 	return api.Render(w, r, response)
 }
+
+// onlyPostForkCommitteeDutyNotes reports whether every error in errs is (or wraps)
+// exportercore.ErrPostForkCommitteeDutyNote, i.e. the errors are non-fatal notes
+// rather than genuine processing failures.
+func onlyPostForkCommitteeDutyNotes(errs *multierror.Error) bool {
+	if errs.ErrorOrNil() == nil {
+		return false
+	}
+	for _, err := range errs.Errors {
+		if !errors.Is(err, exportercore.ErrPostForkCommitteeDutyNote) {
+			return false
+		}
+	}
+	return true
+}

docs/api/ssvnode.openapi.json

@@ -229,7 +229,7 @@
         },
         "/v1/exporter/traces/committee": {
             "get": {
-                "description": "Returns consensus and post-consensus traces for requested committees.",
+                "description": "Returns consensus and post-consensus traces for requested committees. Without a 'roles' filter, the response contains one trace per (slot, committeeID, role) - up to two rows per (slot, committeeID), distinguished by the 'role' field.",
                 "consumes": [
                     "application/json"
                 ],
@@ -318,7 +318,7 @@
                 }
             },
             "post": {
-                "description": "Returns consensus and post-consensus traces for requested committees.",
+                "description": "Returns consensus and post-consensus traces for requested committees. Without a 'roles' filter, the response contains one trace per (slot, committeeID, role) - up to two rows per (slot, committeeID), distinguished by the 'role' field.",
                 "consumes": [
                     "application/json"
                 ],

docs/api/ssvnode.openapi.yaml

@@ -742,6 +742,9 @@ paths:
       consumes:
       - application/json
       description: Returns consensus and post-consensus traces for requested committees.
+        Without a 'roles' filter, the response contains one trace per (slot, committeeID,
+        role) - up to two rows per (slot, committeeID), distinguished by the 'role'
+        field.
       parameters:
       - collectionFormat: csv
         description: CommitteeIDs is a comma-separated list of committee IDs (hex,
@@ -805,6 +808,9 @@ paths:
       consumes:
       - application/json
       description: Returns consensus and post-consensus traces for requested committees.
+        Without a 'roles' filter, the response contains one trace per (slot, committeeID,
+        role) - up to two rows per (slot, committeeID), distinguished by the 'role'
+        field.
       parameters:
       - collectionFormat: csv
         description: CommitteeIDs is a comma-separated list of committee IDs (hex,

exporter/validator.go

@@ -1,6 +1,7 @@
 package exporter
 
 import (
+	"errors"
 	"fmt"
 	"slices"
 
@@ -16,6 +17,12 @@ import (
 	ssvtypes "github.com/ssvlabs/ssv/protocol/v2/types"
 )
 
+// ErrPostForkCommitteeDutyNote marks the non-fatal note appended when a
+// fork-straddling request reaches a post-fork slot/role pair without
+// pubkeys/indices. It lets callers (e.g. the HTTP layer) tell this expected,
+// partial-coverage note apart from genuine processing failures.
+var ErrPostForkCommitteeDutyNote = errors.New("committee duty post-fork requires pubkeys or indices")
+
 // ValidatorTracesCore contains the core logic for ValidatorTraces without any HTTP concerns.
 func (e *Exporter) ValidatorTracesCore(request *ValidatorTracesQuery) (*ValidatorTracesResult, *multierror.Error) {
 	if err := e.validateValidatorRequest(request); err != nil {
@@ -36,6 +43,14 @@ func (e *Exporter) ValidatorTracesCore(request *ValidatorTracesQuery) (*Validato
 	for s := request.From; s <= request.To; s++ {
 		slot := phase0.Slot(s)
 		for _, role := range request.Roles {
+			if e.isCommitteeDutyAtSlot(role, slot) && len(indices) == 0 {
+				// request validation only gates on 'from': a window whose tail crosses
+				// Boole reaches here for its post-fork slots without pubkeys/indices,
+				// so report the gap as a non-fatal note instead of silently skipping it.
+				errs = multierror.Append(errs, fmt.Errorf("%w: slot %d: role %s is a committee duty post-fork, please provide either pubkeys or indices to filter the duty for a specific validators subset or use the /committee endpoint to query all the corresponding duties", ErrPostForkCommitteeDutyNote, slot, role.String()))
+				continue
+			}
+
 			providerFunc := e.getValidatorDutiesForRoleAndSlot
 			if e.isCommitteeDutyAtSlot(role, slot) {
 				providerFunc = e.getValidatorCommitteeDutiesForRoleAndSlot
@@ -66,11 +81,12 @@ func (e *Exporter) validateValidatorRequest(request *ValidatorTracesQuery) error
 	}
 
 	// either PubKeys or Indices are required for committee duty roles.
-	// Fork state is evaluated at the range's upper bound: if any slot in
-	// [from, to] is post-Boole, the 'to' slot is too.
+	// Fork state is evaluated at the range's lower bound so that a window
+	// whose tail crosses Boole still serves its pre-fork portion; the
+	// post-fork tail is reported as a non-fatal note in the per-slot loop.
 	if len(request.PubKeys) == 0 && len(request.Indices) == 0 {
 		for _, role := range request.Roles {
-			if e.isCommitteeDutyAtSlot(role, phase0.Slot(request.To)) {
+			if e.isCommitteeDutyAtSlot(role, phase0.Slot(request.From)) {
 				return fmt.Errorf("role %s is a committee duty, please provide either pubkeys or indices to filter the duty for a specific validators subset or use the /committee endpoint to query all the corresponding duties", role.String())
 			}
 		}

exporter/validator_test.go

@@ -1,6 +1,7 @@
 package exporter
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/attestantio/go-eth2-client/spec/phase0"
@@ -10,6 +11,7 @@ import (
 
 	spectypes "github.com/ssvlabs/ssv-spec/types"
 
+	"github.com/ssvlabs/ssv/exporter/rolemask"
 	estore "github.com/ssvlabs/ssv/exporter/store"
 	"github.com/ssvlabs/ssv/exporter/traces"
 	"github.com/ssvlabs/ssv/networkconfig"
@@ -36,6 +38,18 @@ func postBooleNetwork() *networkconfig.Network {
 	return &netCfg
 }
 
+// straddlingNetwork returns a *networkconfig.Network clone whose Boole fork
+// activates one epoch after "now", so a slot range that starts before the
+// fork epoch and ends after it genuinely straddles the fork boundary. It
+// never mutates the shared TestNetwork.
+func straddlingNetwork() *networkconfig.Network {
+	ssvCopy := *networkconfig.TestNetwork.SSV
+	ssvCopy.Forks.Boole = networkconfig.TestNetwork.EstimatedCurrentEpoch() + 1
+	netCfg := *networkconfig.TestNetwork
+	netCfg.SSV = &ssvCopy
+	return &netCfg
+}
+
 func TestIsCommitteeDutyAtSlot(t *testing.T) {
 	preFork := preBooleNetwork()
 	postFork := postBooleNetwork()
@@ -73,9 +87,11 @@ func TestIsCommitteeDutyAtSlot(t *testing.T) {
 func TestValidateValidatorRequest(t *testing.T) {
 	preFork := preBooleNetwork()
 	postFork := postBooleNetwork()
+	straddle := straddlingNetwork()
 
 	preForkSlot := uint64(preFork.FirstSlotAtEpoch(1))
 	postForkSlot := uint64(postFork.FirstSlotAtEpoch(1))
+	straddleBoundarySlot := uint64(straddle.FirstSlotAtEpoch(straddle.SSV.Forks.Boole))
 
 	tests := []struct {
 		name    string
@@ -162,7 +178,7 @@ func TestValidateValidatorRequest(t *testing.T) {
 			wantErr: true,
 		},
 		{
-			name:   "range straddling the fork resolves on the 'to' bound: pre-fork 'to' is accepted",
+			name:   "range straddling the fork resolves on the 'from' bound: pre-fork 'to' is accepted",
 			netCfg: preFork,
 			request: &ValidatorTracesQuery{
 				From:  1,
@@ -172,7 +188,7 @@ func TestValidateValidatorRequest(t *testing.T) {
 			wantErr: false,
 		},
 		{
-			name:   "range straddling the fork resolves on the 'to' bound: post-fork 'to' is rejected",
+			name:   "range straddling the fork resolves on the 'from' bound: post-fork 'to' is rejected",
 			netCfg: postFork,
 			request: &ValidatorTracesQuery{
 				From:  1,
@@ -181,6 +197,26 @@ func TestValidateValidatorRequest(t *testing.T) {
 			},
 			wantErr: true,
 		},
+		{
+			name:   "range genuinely straddling the fork boundary is accepted (gate evaluated at 'from', not 'to')",
+			netCfg: straddle,
+			request: &ValidatorTracesQuery{
+				From:  straddleBoundarySlot - 1,
+				To:    straddleBoundarySlot + 10,
+				Roles: []spectypes.BeaconRole{spectypes.BNRoleAggregator},
+			},
+			wantErr: false,
+		},
+		{
+			name:   "range whose 'from' is already post-fork is rejected even if narrower than 'to'",
+			netCfg: straddle,
+			request: &ValidatorTracesQuery{
+				From:  straddleBoundarySlot,
+				To:    straddleBoundarySlot + 10,
+				Roles: []spectypes.BeaconRole{spectypes.BNRoleAggregator},
+			},
+			wantErr: true,
+		},
 	}
 
 	for _, tt := range tests {
@@ -196,6 +232,54 @@ func TestValidateValidatorRequest(t *testing.T) {
 	}
 }
 
+// mockCoreTraceStore is a minimal dutyTraceStore implementation for exercising
+// ValidatorTracesCore end-to-end over a fork-straddling slot range.
+type mockCoreTraceStore struct {
+	dutyTraceStore
+}
+
+func (m *mockCoreTraceStore) GetValidatorDuties(_ spectypes.BeaconRole, _ phase0.Slot) ([]*traces.ValidatorDutyTrace, error) {
+	return nil, nil
+}
+
+func (m *mockCoreTraceStore) GetScheduled(_ phase0.Slot) (map[phase0.ValidatorIndex]rolemask.Mask, error) {
+	return map[phase0.ValidatorIndex]rolemask.Mask{}, nil
+}
+
+func TestValidatorTracesCore_StraddlingFork(t *testing.T) {
+	straddle := straddlingNetwork()
+	boundarySlot := straddle.FirstSlotAtEpoch(straddle.SSV.Forks.Boole)
+
+	e := &Exporter{
+		traceStore:    &mockCoreTraceStore{},
+		logger:        zap.NewNop(),
+		networkConfig: straddle,
+	}
+
+	request := &ValidatorTracesQuery{
+		From:  uint64(boundarySlot) - 1,
+		To:    uint64(boundarySlot) + 1,
+		Roles: []spectypes.BeaconRole{spectypes.BNRoleAggregator},
+	}
+
+	result, errs := e.ValidatorTracesCore(request)
+	require.NotNil(t, result)
+
+	// no *ValidationError: the request is accepted despite its tail crossing Boole.
+	for _, err := range errs.Errors {
+		var valErr *ValidationError
+		assert.NotErrorAs(t, err, &valErr)
+	}
+
+	// the two post-fork slots (boundarySlot, boundarySlot+1) are reported as
+	// non-fatal notes since no pubkeys/indices were supplied to filter the
+	// now-committee-backed AGGREGATOR duty.
+	require.Len(t, errs.Errors, 2)
+	assert.Contains(t, errs.Errors[0].Error(), fmt.Sprintf("slot %d", boundarySlot))
+	assert.Contains(t, errs.Errors[0].Error(), "committee duty")
+	assert.Contains(t, errs.Errors[1].Error(), fmt.Sprintf("slot %d", boundarySlot+1))
+}
+
 // mockValidatorTraceStore is a minimal dutyTraceStore implementation for
 // exercising getValidatorCommitteeDutiesForRoleAndSlot's signer-bucket gating.
 type mockValidatorTraceStore struct {