[PoC] Implement response wrapper for ValidatorBalances

api/v1/response.go

@@ -0,0 +1,28 @@
+package v1
+
+import "fmt"
+
+const MetadataKeyFinalized = "finalized"
+const MetadataKeyExecutionOptimistic = "execution_optimistic"
+
+// Response is a response from the beacon API which may contain metadata.
+type Response[T any] struct {
+	Data     T
+	Metadata map[string]interface{}
+}
+
+func (r Response[T]) Finalized() (bool, error) {
+	val, ok := r.Metadata[MetadataKeyFinalized]
+	if !ok {
+		return false, fmt.Errorf("metadata key %s not found", MetadataKeyFinalized)
+	}
+	return val.(bool), nil
+}
+
+func (r Response[T]) ExecutionOptimistic() (bool, error) {
+	val, ok := r.Metadata[MetadataKeyExecutionOptimistic]
+	if !ok {
+		return false, fmt.Errorf("metadata key %s not found", MetadataKeyExecutionOptimistic)
+	}
+	return val.(bool), nil
+}

http/validatorbalances.go

@@ -25,14 +25,19 @@ import (
 )
 
 type validatorBalancesJSON struct {
-	Data []*api.ValidatorBalance `json:"data"`
+	ExecutionOptimistic bool                    `json:"execution_optimistic"`
+	Finalized           bool                    `json:"finalized"`
+	Data                []*api.ValidatorBalance `json:"data"`
 }
 
 // ValidatorBalances provides the validator balances for a given state.
 // stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
 // validatorIndices is a list of validator indices to restrict the returned values.  If no validators are supplied no filter
 // will be applied.
-func (s *Service) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]phase0.Gwei, error) {
+
+type validatorBalancesResponse = api.Response[map[phase0.ValidatorIndex]phase0.Gwei]
+
+func (s *Service) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (*validatorBalancesResponse, error) {
 	if stateID == "" {
 		return nil, errors.New("no state ID specified")
 	}
@@ -66,16 +71,25 @@ func (s *Service) ValidatorBalances(ctx context.Context, stateID string, validat
 		return nil, errors.New("no validator balances returned")
 	}
 
-	res := make(map[phase0.ValidatorIndex]phase0.Gwei)
+	res := &validatorBalancesResponse{
+		Data: make(map[phase0.ValidatorIndex]phase0.Gwei),
+		Metadata: map[string]interface{}{
+			api.MetadataKeyExecutionOptimistic: validatorBalancesJSON.ExecutionOptimistic,
+			api.MetadataKeyFinalized:           validatorBalancesJSON.Finalized,
+		},
+	}
+
 	for _, validatorBalance := range validatorBalancesJSON.Data {
-		res[validatorBalance.Index] = validatorBalance.Balance
+		res.Data[validatorBalance.Index] = validatorBalance.Balance
 	}
 	return res, nil
 }
 
 // chunkedValidatorBalances obtains the validator balances a chunk at a time.
-func (s *Service) chunkedValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]phase0.Gwei, error) {
-	res := make(map[phase0.ValidatorIndex]phase0.Gwei)
+func (s *Service) chunkedValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (*validatorBalancesResponse, error) {
+	res := &validatorBalancesResponse{
+		Data: make(map[phase0.ValidatorIndex]phase0.Gwei),
+	}
 	indexChunkSize := s.indexChunkSize(ctx)
 	for i := 0; i < len(validatorIndices); i += indexChunkSize {
 		chunkStart := i
@@ -88,8 +102,28 @@ func (s *Service) chunkedValidatorBalances(ctx context.Context, stateID string,
 		if err != nil {
 			return nil, errors.Wrap(err, "failed to obtain chunk")
 		}
-		for k, v := range chunkRes {
-			res[k] = v
+		for k, v := range chunkRes.Data {
+			res.Data[k] = v
+		}
+
+		// For metadata, if any of the chunks are optimistic then the result is optimistic.
+		// If any of the chunks are not finalized then the result is not finalized.
+		finalized, err := chunkRes.Finalized()
+		if err != nil {
+			return nil, errors.Wrap(err, "failed to obtain finalized")
+		}
+
+		if !finalized {
+			res.Metadata[api.MetadataKeyFinalized] = finalized
+		}
+
+		executionOptimistic, err := chunkRes.ExecutionOptimistic()
+		if err != nil {
+			return nil, errors.Wrap(err, "failed to obtain execution optimistic")
+		}
+
+		if executionOptimistic {
+			res.Metadata[api.MetadataKeyExecutionOptimistic] = executionOptimistic
 		}
 	}
 	return res, nil

multi/validatorbalances.go

@@ -17,14 +17,15 @@ import (
 	"context"
 
 	consensusclient "github.com/attestantio/go-eth2-client"
+	v1 "github.com/attestantio/go-eth2-client/api/v1"
 	"github.com/attestantio/go-eth2-client/spec/phase0"
 )
 
 // ValidatorBalances provides the validator balances for a given state.
 // stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
 // validatorIndices is a list of validator indices to restrict the returned values.  If no validators are supplied no filter
 // will be applied.
-func (s *Service) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]phase0.Gwei, error) {
+func (s *Service) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (*v1.Response[map[phase0.ValidatorIndex]phase0.Gwei], error) {
 	res, err := s.doCall(ctx, func(ctx context.Context, client consensusclient.Service) (interface{}, error) {
 		block, err := client.(consensusclient.ValidatorBalancesProvider).ValidatorBalances(ctx, stateID, validatorIndices)
 		if err != nil {
@@ -38,5 +39,5 @@ func (s *Service) ValidatorBalances(ctx context.Context, stateID string, validat
 	if res == nil {
 		return nil, nil
 	}
-	return res.(map[phase0.ValidatorIndex]phase0.Gwei), nil
+	return res.(*v1.Response[map[phase0.ValidatorIndex]phase0.Gwei]), nil
 }

service.go

@@ -359,7 +359,7 @@ type ValidatorBalancesProvider interface {
 	// stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
 	// validatorIndices is a list of validator indices to restrict the returned values.  If no validators are supplied no filter
 	// will be applied.
-	ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]phase0.Gwei, error)
+	ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (*apiv1.Response[map[phase0.ValidatorIndex]phase0.Gwei], error)
 }
 
 // ValidatorsProvider is the interface for providing validator information.

testclients/erroring.go

@@ -565,7 +565,7 @@ func (s *Erroring) Spec(ctx context.Context) (map[string]interface{}, error) {
 // stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
 // validatorIndices is a list of validator indices to restrict the returned values.  If no validators are supplied no filter
 // will be applied.
-func (s *Erroring) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]phase0.Gwei, error) {
+func (s *Erroring) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (*apiv1.Response[map[phase0.ValidatorIndex]phase0.Gwei], error) {
 	if err := s.maybeError(ctx); err != nil {
 		return nil, err
 	}

testclients/sleepy.go

@@ -382,7 +382,7 @@ func (s *Sleepy) Spec(ctx context.Context) (map[string]interface{}, error) {
 // stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
 // validatorIndices is a list of validator indices to restrict the returned values.  If no validators are supplied no filter
 // will be applied.
-func (s *Sleepy) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]phase0.Gwei, error) {
+func (s *Sleepy) ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (*apiv1.Response[map[phase0.ValidatorIndex]phase0.Gwei], error) {
 	s.sleep(ctx)
 	next, isNext := s.next.(consensusclient.ValidatorBalancesProvider)
 	if !isNext {