threshold-network
diff --git a/‎pkg/frost/roast/attempt/evidence_recorder.go‎
Lines changed: 115 additions & 0 deletions b/‎pkg/frost/roast/attempt/evidence_recorder.go‎
Lines changed: 115 additions & 0 deletions
diff --git a/‎pkg/frost/roast/attempt/evidence_recorder_test.go‎
Lines changed: 141 additions & 0 deletions b/‎pkg/frost/roast/attempt/evidence_recorder_test.go‎
Lines changed: 141 additions & 0 deletions
diff --git a/‎pkg/frost/signing/evidence_overflow.go‎
Lines changed: 43 additions & 0 deletions b/‎pkg/frost/signing/evidence_overflow.go‎
Lines changed: 43 additions & 0 deletions
@@ -0,0 +1,115 @@
+package attempt
+
+import (
+	"sync"
+
+	"github.com/keep-network/keep-core/pkg/protocol/group"
+)
+
+// OverflowQuotaDefault is the default per-sender overflow event quota
+// enforced by NewBoundedRecorder. It matches the categoryQuota.Overflow
+// value documented in RFC-21 Layer A.
+//
+// A peer that overflows the inbound message channel more than the
+// quota allows in a single attempt is recorded only up to the quota:
+// further overflows are silently dropped by the recorder. This bounds
+// the per-attempt evidence size to O(|IncludedSet| * quota) regardless
+// of how aggressively a peer (or its network link) misbehaves.
+const OverflowQuotaDefault uint = 8
+
+// EvidenceRecorder collects bounded, per-attempt evidence of receive-
+// path anomalies that the ROAST coordinator's exclusion policy may
+// later consume.
+//
+// Phase 2 introduces only the overflow channel; future phases extend
+// the interface with separate methods for reject events, first-write-
+// wins conflicts, and silent peers.
+//
+// Implementations must be safe for concurrent calls from multiple
+// goroutines, since the receive-callback closure in pkg/frost/signing
+// is driven by network goroutines.
+type EvidenceRecorder interface {
+	// RecordOverflow notes that the inbound message channel was full
+	// when a payload from the named sender arrived, causing the
+	// payload to be dropped at the receive callback. The recorder
+	// applies its own quota; callers do not need to suppress at the
+	// call site.
+	RecordOverflow(sender group.MemberIndex)
+	// Snapshot returns a copy of the recorded evidence so far. The
+	// returned value does not alias internal state; the recorder may
+	// continue receiving events after Snapshot is called.
+	Snapshot() Evidence
+}
+
+// Evidence is the per-attempt snapshot of receive-path anomalies
+// captured by an EvidenceRecorder. It is the value the ROAST
+// coordinator's NextAttempt policy consumes (in a later RFC-21
+// phase) to derive the next attempt's ExcludedSet.
+type Evidence struct {
+	// Overflows maps each sender to the number of overflow events
+	// observed for that sender during the attempt, saturated at the
+	// recorder's overflow quota. A missing key means the sender did
+	// not overflow at all during the attempt.
+	Overflows map[group.MemberIndex]uint
+}
+
+// NewBoundedRecorder returns an EvidenceRecorder with default
+// per-sender quotas. The recorder is safe for concurrent use.
+//
+// Phase 2 wiring uses NoOpRecorder by default at every call site;
+// real use of the bounded recorder lands in a later phase behind a
+// build tag, when the coordinator state machine arrives.
+func NewBoundedRecorder() EvidenceRecorder {
+	return NewBoundedRecorderWithQuota(OverflowQuotaDefault)
+}
+
+// NewBoundedRecorderWithQuota returns a recorder with a custom
+// overflow quota. Intended for tests; production callers should use
+// NewBoundedRecorder so the per-attempt evidence size is uniform
+// across the network.
+func NewBoundedRecorderWithQuota(overflowQuota uint) EvidenceRecorder {
+	return &boundedRecorder{
+		overflowQuota: overflowQuota,
+		overflows:     map[group.MemberIndex]uint{},
+	}
+}
+
+// NoOpRecorder returns a recorder that discards every event and
+// reports an empty Evidence on Snapshot. It is the default at every
+// Phase 2 call site so the receive loops' observable behaviour stays
+// identical to pre-Phase-2 until a later phase wires real recorders.
+func NoOpRecorder() EvidenceRecorder {
+	return noOpRecorder{}
+}
+
+type boundedRecorder struct {
+	mu            sync.Mutex
+	overflowQuota uint
+	overflows     map[group.MemberIndex]uint
+}
+
+func (r *boundedRecorder) RecordOverflow(sender group.MemberIndex) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.overflows[sender] < r.overflowQuota {
+		r.overflows[sender]++
+	}
+}
+
+func (r *boundedRecorder) Snapshot() Evidence {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	out := make(map[group.MemberIndex]uint, len(r.overflows))
+	for sender, count := range r.overflows {
+		out[sender] = count
+	}
+	return Evidence{Overflows: out}
+}
+
+type noOpRecorder struct{}
+
+func (noOpRecorder) RecordOverflow(group.MemberIndex) {}
+
+func (noOpRecorder) Snapshot() Evidence {
+	return Evidence{Overflows: map[group.MemberIndex]uint{}}
+}
@@ -0,0 +1,141 @@
+package attempt
+
+import (
+	"sync"
+	"testing"
+
+	"github.com/keep-network/keep-core/pkg/protocol/group"
+)
+
+func TestNoOpRecorder_IsObservablyInert(t *testing.T) {
+	rec := NoOpRecorder()
+	for i := 0; i < 1000; i++ {
+		rec.RecordOverflow(group.MemberIndex(i%5 + 1))
+	}
+	snap := rec.Snapshot()
+	if len(snap.Overflows) != 0 {
+		t.Fatalf(
+			"NoOp recorder must report zero overflows; got %d entries",
+			len(snap.Overflows),
+		)
+	}
+}
+
+func TestBoundedRecorder_CountsOverflowsBySender(t *testing.T) {
+	rec := NewBoundedRecorder()
+	rec.RecordOverflow(1)
+	rec.RecordOverflow(2)
+	rec.RecordOverflow(1)
+
+	snap := rec.Snapshot()
+	if got := snap.Overflows[1]; got != 2 {
+		t.Fatalf("sender 1 overflow count: got %d want 2", got)
+	}
+	if got := snap.Overflows[2]; got != 1 {
+		t.Fatalf("sender 2 overflow count: got %d want 1", got)
+	}
+	if _, ok := snap.Overflows[3]; ok {
+		t.Fatal("sender 3 should have no entry")
+	}
+}
+
+func TestBoundedRecorder_SaturatesAtQuota(t *testing.T) {
+	const quota uint = 4
+	rec := NewBoundedRecorderWithQuota(quota)
+
+	for i := uint(0); i < quota+10; i++ {
+		rec.RecordOverflow(1)
+	}
+	snap := rec.Snapshot()
+	if got := snap.Overflows[1]; got != quota {
+		t.Fatalf(
+			"overflow count must saturate at quota %d; got %d",
+			quota, got,
+		)
+	}
+}
+
+func TestBoundedRecorder_DefaultQuotaIs8(t *testing.T) {
+	rec := NewBoundedRecorder()
+	for i := 0; i < 100; i++ {
+		rec.RecordOverflow(1)
+	}
+	if got := rec.Snapshot().Overflows[1]; got != OverflowQuotaDefault {
+		t.Fatalf(
+			"default quota mismatch; got %d want %d",
+			got, OverflowQuotaDefault,
+		)
+	}
+	if OverflowQuotaDefault != 8 {
+		t.Fatalf(
+			"RFC-21 Layer A specifies overflow quota = 8; constant is %d",
+			OverflowQuotaDefault,
+		)
+	}
+}
+
+func TestBoundedRecorder_SnapshotIsDeepCopy(t *testing.T) {
+	rec := NewBoundedRecorder()
+	rec.RecordOverflow(1)
+	rec.RecordOverflow(1)
+
+	snap := rec.Snapshot()
+	snap.Overflows[1] = 999
+	snap.Overflows[42] = 7
+
+	freshSnap := rec.Snapshot()
+	if got := freshSnap.Overflows[1]; got != 2 {
+		t.Fatalf(
+			"snapshot mutation leaked into recorder state: got %d want 2",
+			got,
+		)
+	}
+	if _, ok := freshSnap.Overflows[42]; ok {
+		t.Fatal("snapshot mutation leaked a new key into recorder state")
+	}
+}
+
+func TestBoundedRecorder_ConcurrentRecordersAreRaceSafe(t *testing.T) {
+	const (
+		recordersPerSender = 8
+		sendersN           = 16
+		recordsPerRecorder = 200
+	)
+	rec := NewBoundedRecorderWithQuota(uint(recordersPerSender * recordsPerRecorder * 10))
+
+	var wg sync.WaitGroup
+	for senderIdx := 1; senderIdx <= sendersN; senderIdx++ {
+		sender := group.MemberIndex(senderIdx)
+		for w := 0; w < recordersPerSender; w++ {
+			wg.Add(1)
+			go func() {
+				defer wg.Done()
+				for n := 0; n < recordsPerRecorder; n++ {
+					rec.RecordOverflow(sender)
+				}
+			}()
+		}
+	}
+	wg.Wait()
+
+	snap := rec.Snapshot()
+	for senderIdx := 1; senderIdx <= sendersN; senderIdx++ {
+		want := uint(recordersPerSender * recordsPerRecorder)
+		if got := snap.Overflows[group.MemberIndex(senderIdx)]; got != want {
+			t.Fatalf(
+				"sender %d concurrent count: got %d want %d",
+				senderIdx, got, want,
+			)
+		}
+	}
+}
+
+func TestNoOpRecorder_DistinctInstancesShareSemantics(t *testing.T) {
+	a := NoOpRecorder()
+	b := NoOpRecorder()
+	a.RecordOverflow(1)
+	b.RecordOverflow(2)
+	if len(a.Snapshot().Overflows) != 0 || len(b.Snapshot().Overflows) != 0 {
+		t.Fatal("NoOp instances must not retain state")
+	}
+}
@@ -0,0 +1,43 @@
+//go:build frost_native
+
+package signing
+
+import (
+	"github.com/keep-network/keep-core/pkg/frost/roast/attempt"
+	"github.com/keep-network/keep-core/pkg/protocol/group"
+)
+
+// senderIndexedMessage is the minimal contract a protocol message must
+// satisfy for enqueueOrRecordOverflow to handle it: the message must
+// expose its sender so the recorder can attribute overflow events to a
+// specific member.
+type senderIndexedMessage interface {
+	SenderID() group.MemberIndex
+}
+
+// enqueueOrRecordOverflow attempts to enqueue payload onto target. If
+// the channel is full, the overflow is recorded against the payload's
+// sender on the supplied recorder instead. Returns true if the payload
+// was enqueued, false if the overflow was recorded.
+//
+// This is the shared select-or-record body that replaces the three
+// inline select { default } drop sites in the FROST/tbtc-signer
+// receive loops. Pulling it out lets the recorder integration be unit-
+// tested directly without spinning up a network channel.
+//
+// Phase 2 callers pass attempt.NoOpRecorder(), so behaviour is
+// observably unchanged from before RFC-21 wiring. A coordinator-aware
+// caller in a later phase injects a real recorder.
+func enqueueOrRecordOverflow[T senderIndexedMessage](
+	payload T,
+	target chan<- T,
+	recorder attempt.EvidenceRecorder,
+) bool {
+	select {
+	case target <- payload:
+		return true
+	default:
+		recorder.RecordOverflow(payload.SenderID())
+		return false
+	}
+}