BCFR-1086 finality violation (#966)

* define finality violation error

Signed-off-by: Dmytro Haidashenko <dmytro.haidashenko@smartcontract.com>

* rename finality violation

Signed-off-by: Dmytro Haidashenko <dmytro.haidashenko@smartcontract.com>

* Test ContainsError

Signed-off-by: Dmytro Haidashenko <dmytro.haidashenko@smartcontract.com>

---------

Signed-off-by: Dmytro Haidashenko <dmytro.haidashenko@smartcontract.com>
Co-authored-by: Domino Valdano <domino.valdano@smartcontract.com>

pkg/services/health.go

@@ -257,3 +257,14 @@ func (c *HealthChecker) IsHealthy() (healthy bool, errors map[string]error) {
 
 	return
 }
+
+// ContainsError - returns true if report contains targetErr
+func ContainsError(report map[string]error, targetErr error) bool {
+	for _, err := range report {
+		if errors.Is(err, targetErr) {
+			return true
+		}
+	}
+
+	return false
+}

pkg/services/health_test.go

@@ -0,0 +1,58 @@
+package services
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestContainsError(t *testing.T) {
+	anError := errors.New("an error")
+	anotherError := errors.New("another error")
+	testCases := []struct {
+		Name           string
+		Report         map[string]error
+		Target         error
+		ExpectedResult bool
+	}{
+		{
+			Name:           "nil map",
+			Report:         nil,
+			Target:         anError,
+			ExpectedResult: false,
+		},
+		{
+			Name:           "report contains service, but it's healthy",
+			Report:         map[string]error{"service": nil},
+			Target:         anError,
+			ExpectedResult: false,
+		},
+		{
+			Name:           "service is not healthy, but it's not caused by target error",
+			Report:         map[string]error{"service": anotherError},
+			Target:         anError,
+			ExpectedResult: false,
+		},
+		{
+			Name:           "service is not healthy and contains wrapper target",
+			Report:         map[string]error{"service": fmt.Errorf("wrapped error: %w", anError)},
+			Target:         anError,
+			ExpectedResult: true,
+		},
+		{
+			Name:           "service is not healthy due to multiple errors including target",
+			Report:         map[string]error{"service": errors.Join(anError, anotherError)},
+			Target:         anError,
+			ExpectedResult: true,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.Name, func(t *testing.T) {
+			actualResult := ContainsError(tc.Report, tc.Target)
+			assert.Equal(t, tc.ExpectedResult, actualResult)
+		})
+	}
+}

pkg/types/contract_reader.go

@@ -16,6 +16,7 @@ const (
 	ErrContractReaderConfigMissing = UnimplementedError("ContractReader entry missing from RelayConfig")
 	ErrInternal                    = InternalError("internal error")
 	ErrNotFound                    = NotFoundError("not found")
+	ErrFinalityViolated            = InternalError("finality violated")
 )
 
 // ContractReader defines essential read operations a chain should implement for reading contract values and events.
@@ -70,6 +71,13 @@ type ContractReader interface {
 	// The iterator returns a pair of key and sequence.
 	QueryKeys(ctx context.Context, filters []ContractKeyFilter, limitAndSort query.LimitAndSort) (iter.Seq2[string, Sequence], error)
 
+	// HealthReport returns a full health report of the callee including its dependencies.
+	// Keys are based on Name(), with nil values when healthy or errors otherwise.
+	// Use CopyHealth to collect reports from sub-services.
+	// This should run very fast, so avoid doing computation and instead prefer reporting pre-calculated state.
+	// On finality violation report must contain at least one ErrFinalityViolation.
+	HealthReport() map[string]error
+
 	mustEmbedUnimplementedContractReader()
 }