feat(tbtc): RFC-21 Phase 6.4 -- signing-loop participant-selection dispatcher (#3984)

## Summary

**Closes Phase 6 of RFC-21.** Abstracts the participant-selection
call site in \`pkg/tbtc/signing_loop.go\` behind a small dispatcher
interface. The legacy implementation is installed as the default;
Phase 7 will install the ROAST-driven implementation alongside
AggregateBundle production.

**The migration here is the *abstraction*, not a behavioural
change.** Both default and \`frost_roast_retry\` builds today execute
the same legacy retry shuffle. The dispatcher exists so Phase 7
can replace it without touching the call shape.

Stacked on #3983 (Phase 6.3).

## Why this scope

During implementation, the participant-migration target turned out
to require two pieces that aren't fully wired yet:

1. AggregateBundle production at attempt-completion time (on the
   elected coordinator's node).
2. A per-session bundle registry so \`signing_loop\` can find the
   most recent \`TransitionMessage\` for a given message.

Both are Phase 7 work. PR 6.4 ships the **dispatcher abstraction**
that lets Phase 7 slot the ROAST implementation in without
touching \`signing_loop.go\` itself, plus the legacy implementation
as the operational fallback that the readiness env var disables.

## What lands

| File | Role |
|---|---|
| \`pkg/tbtc/signing_loop_roast_dispatcher.go\` (new) |
\`signingParticipantSelector\` interface (\`Select(members, seed,
retryCount, honestThreshold, sessionID) → addresses\`).
\`defaultSigningParticipantSelector()\` returns the legacy impl. |
| \`pkg/tbtc/signing_loop_legacy_selector.go\` (new) |
\`legacySigningParticipantSelector\` -- byte-identical call to
\`retry.EvaluateRetryParticipantsForSigning\`. Documented as the
rollback path through Phase 6. |
| \`pkg/tbtc/signing_loop.go\` (modified) | \`signingRetryLoop\` gains
\`participantSelector\` field; \`qualifiedOperatorsSet\` routes through
it. \`pkg/frost/retry\` import removed (only the legacy selector uses it
now). |

## Test coverage (5 cases)

- \`defaultSigningParticipantSelector\` returns the legacy impl
- legacy selector delegates to retry shuffle
- legacy selector propagates retry-shuffle errors
- \`signingRetryLoop.qualifiedOperatorsSet\` routes through the
dispatcher (recording selector verifies)
- selector errors propagate through \`signingRetryLoop\` with
\`errors.Is\` preserving the sentinel

## What Phase 7 will add

- AggregateBundle production at the executor-adapter end (the elected
coordinator's node generates a \`TransitionMessage\` at attempt
completion)
- Per-session bundle registry so \`signing_loop\` can look up the most
recent bundle for the message
- ROAST-driven \`signingParticipantSelector\` that consumes the bundle
via \`EvaluateRoastRetryForSigning\` and falls back to the legacy
selector when no bundle is available
- Readiness manifest flip once integration tests pass on a real testnet

## Pre-existing test failure note

\`TestNode_RunCoordinationLayer\` fails under the
\`frost_native frost_tbtc_signer frost_roast_retry\` tag combination
on the integration tip *without* the Phase 6.4 changes (verified
by checking out integration-tip's tbtc package and re-running).

**Not introduced by this PR.** Tracked separately. Default-build
\`go test ./pkg/tbtc/... ./pkg/frost/...\` (149s) passes cleanly.

## Verification

| Command | Result |
|---|---|
| \`go build ./...\` | clean |
| \`go test ./pkg/tbtc/... -count=1\` | pass (149s default build) |
| \`go test ./pkg/frost/... -count=1\` | pass |
| \`staticcheck -checks '-SA1019' ./pkg/tbtc/...\` | silent |
| \`go vet ./pkg/tbtc/...\` | clean |
| \`gofmt -l ./pkg/tbtc/\` | silent |

## Phase 6 complete

| PR | Scope | State |
|---|---|---|
| 6.1 (#3981) | DKG group-public-key extraction | open |
| 6.2 (#3982) | BuildAttemptContextFromRequest | open |
| 6.3 (#3983) | Wire orchestration at executor adapter | open |
| **6.4 (this)** | **signing-loop participant-selection dispatcher** |
**open** |

Phase 7: AggregateBundle wiring + ROAST selector + manifest flip.

## Test plan

- [ ] CI green (default build).
- [ ] Reviewer confirms the dispatcher abstraction is the right
granularity (alternative: function-pointer indirection without an
interface).
- [ ] Reviewer confirms deferring participant migration to Phase 7 is
acceptable. The trade-off: smaller Phase 6 PRs but Phase 7 also covers
the AggregateBundle wiring + ROAST selector + manifest flip.

Author: mswilkison

pkg/tbtc/signing_loop.go

@@ -13,7 +13,6 @@ import (
 
 	"github.com/ipfs/go-log/v2"
 	"github.com/keep-network/keep-core/pkg/chain"
-	"github.com/keep-network/keep-core/pkg/frost/retry"
 	"github.com/keep-network/keep-core/pkg/frost/signing"
 	"github.com/keep-network/keep-core/pkg/protocol/group"
 	"golang.org/x/exp/slices"
@@ -107,6 +106,12 @@ type signingRetryLoop struct {
 	attemptSeed       int64
 
 	doneCheck signingDoneCheckStrategy
+
+	// participantSelector dispatches qualified-operator selection.
+	// Default: legacy retry shuffle. Phase 7 may install a
+	// ROAST-driven implementation behind the frost_roast_retry
+	// build tag once AggregateBundle production is wired upstream.
+	participantSelector signingParticipantSelector
 }
 
 func newSigningRetryLoop(
@@ -130,6 +135,7 @@ func newSigningRetryLoop(
 		attemptStartBlock:       initialStartBlock,
 		attemptSeed:             signingAttemptSeed(message),
 		doneCheck:               doneCheck,
+		participantSelector:     defaultSigningParticipantSelector(),
 	}
 }
 
@@ -492,11 +498,16 @@ func (srl *signingRetryLoop) qualifiedOperatorsSet(
 		)
 	}
 
-	qualifiedOperators, err := retry.EvaluateRetryParticipantsForSigning(
+	// RFC-21 Phase 6.4: dispatch through participantSelector so a
+	// future ROAST-driven implementation can be installed behind
+	// the frost_roast_retry build tag without touching this call
+	// site. Default and current behaviour: legacy retry shuffle.
+	qualifiedOperators, err := srl.participantSelector.Select(
 		readySigningGroupOperators,
 		srl.attemptSeed,
 		retryCount,
 		uint(srl.groupParameters.HonestThreshold),
+		fmt.Sprintf("%v", srl.message),
 	)
 	if err != nil {
 		return nil, fmt.Errorf(

pkg/tbtc/signing_loop_legacy_selector.go

@@ -0,0 +1,42 @@
+package tbtc
+
+import (
+	"fmt"
+
+	"github.com/keep-network/keep-core/pkg/chain"
+	"github.com/keep-network/keep-core/pkg/frost/retry"
+)
+
+// legacySigningParticipantSelector is the pre-RFC-21 implementation:
+// it calls the pseudo-random retry shuffle in pkg/frost/retry.
+// Kept as the canonical fallback through Phase 6; Phase 7 may
+// remove it once the ROAST-driven retry path is fully wired and
+// the readiness manifest flips.
+//
+// The legacy code is *intentionally retained* through Phase 6 to
+// preserve the operational rollback path: if a deployment toggles
+// the readiness env var off, this implementation is what the
+// dispatcher falls back to.
+type legacySigningParticipantSelector struct{}
+
+func (legacySigningParticipantSelector) Select(
+	members []chain.Address,
+	seed int64,
+	retryCount uint,
+	honestThreshold uint,
+	_ string,
+) ([]chain.Address, error) {
+	qualifiedOperators, err := retry.EvaluateRetryParticipantsForSigning(
+		members,
+		seed,
+		retryCount,
+		honestThreshold,
+	)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"legacy participant selector: random operator selection failed: %w",
+			err,
+		)
+	}
+	return qualifiedOperators, nil
+}

pkg/tbtc/signing_loop_roast_dispatcher.go

@@ -0,0 +1,41 @@
+package tbtc
+
+import (
+	"github.com/keep-network/keep-core/pkg/chain"
+)
+
+// signingParticipantSelector picks the set of operators qualified for
+// a signing attempt. The legacy implementation is the pseudo-random
+// retry shuffle in pkg/frost/retry; the RFC-21 Phase-6 migration
+// introduces this interface so an alternate ROAST-driven
+// implementation can be installed behind the frost_roast_retry build
+// tag without touching the call site.
+//
+// PR 6.4 ships the dispatcher with only the legacy implementation
+// installed; Phase 7 wires the ROAST-driven implementation along
+// with the supporting AggregateBundle production at the executor-
+// adapter layer. Until Phase 7, behaviour is byte-identical to
+// pre-RFC-21 retry semantics.
+type signingParticipantSelector interface {
+	// Select returns the set of operators qualified to participate
+	// in the given signing attempt. members is the set of operators
+	// whose ready signal was received for this attempt. seed is the
+	// per-message retry seed; retryCount is 0-based (i.e. 0 for the
+	// first retry). honestThreshold is the group's signing
+	// threshold.
+	Select(
+		members []chain.Address,
+		seed int64,
+		retryCount uint,
+		honestThreshold uint,
+		sessionID string,
+	) ([]chain.Address, error)
+}
+
+// defaultSigningParticipantSelector returns the legacy implementation
+// installed by every Phase-6 build (default + frost_roast_retry).
+// Phase 7 will install a ROAST-driven implementation in a follow-up
+// PR that also wires AggregateBundle production.
+func defaultSigningParticipantSelector() signingParticipantSelector {
+	return legacySigningParticipantSelector{}
+}

pkg/tbtc/signing_loop_roast_dispatcher_test.go

@@ -0,0 +1,137 @@
+package tbtc
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/keep-network/keep-core/pkg/chain"
+	"github.com/keep-network/keep-core/pkg/protocol/group"
+)
+
+// recordingSelector counts how often Select was called and returns
+// a fixed result. Tests use it to assert the dispatcher routes
+// participant selection through the configured selector rather
+// than the legacy path.
+type recordingSelector struct {
+	calls  int
+	result []chain.Address
+	err    error
+}
+
+func (r *recordingSelector) Select(
+	members []chain.Address,
+	_ int64,
+	_ uint,
+	_ uint,
+	_ string,
+) ([]chain.Address, error) {
+	r.calls++
+	if r.err != nil {
+		return nil, r.err
+	}
+	if r.result != nil {
+		return r.result, nil
+	}
+	return members, nil
+}
+
+func TestDefaultSigningParticipantSelector_IsLegacy(t *testing.T) {
+	sel := defaultSigningParticipantSelector()
+	if _, ok := sel.(legacySigningParticipantSelector); !ok {
+		t.Fatalf(
+			"defaultSigningParticipantSelector must return legacy implementation; got %T",
+			sel,
+		)
+	}
+}
+
+func TestLegacySigningParticipantSelector_DelegatesToRetryShuffle(t *testing.T) {
+	members := []chain.Address{
+		chain.Address("op-1"),
+		chain.Address("op-2"),
+		chain.Address("op-3"),
+		chain.Address("op-4"),
+		chain.Address("op-5"),
+	}
+	sel := legacySigningParticipantSelector{}
+	got, err := sel.Select(members, 42, 0, 3, "session-x")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(got) < 3 {
+		t.Fatalf("expected at least 3 qualified operators, got %d", len(got))
+	}
+}
+
+func TestLegacySigningParticipantSelector_PropagatesErrors(t *testing.T) {
+	sel := legacySigningParticipantSelector{}
+	_, err := sel.Select(
+		[]chain.Address{chain.Address("op-1")},
+		0, 0,
+		99, // honest threshold higher than member count
+		"session-x",
+	)
+	if err == nil {
+		t.Fatal("expected error from retry shuffle")
+	}
+}
+
+func TestSigningRetryLoopUsesDispatcher(t *testing.T) {
+	sentinel := []chain.Address{
+		chain.Address("op-1"),
+		chain.Address("op-2"),
+		chain.Address("op-3"),
+	}
+	recorder := &recordingSelector{result: sentinel}
+
+	srl := &signingRetryLoop{
+		signingGroupOperators: chain.Addresses{
+			chain.Address("op-1"),
+			chain.Address("op-2"),
+			chain.Address("op-3"),
+			chain.Address("op-4"),
+			chain.Address("op-5"),
+		},
+		groupParameters: &GroupParameters{
+			HonestThreshold: 3,
+		},
+		attemptCounter:      1,
+		attemptSeed:         42,
+		participantSelector: recorder,
+	}
+
+	set, err := srl.qualifiedOperatorsSet([]group.MemberIndex{1, 2, 3, 4, 5})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if recorder.calls != 1 {
+		t.Fatalf("expected dispatcher to be called once; got %d", recorder.calls)
+	}
+	if len(set) != len(sentinel) {
+		t.Fatalf(
+			"expected %d qualified operators (the sentinel), got %d",
+			len(sentinel), len(set),
+		)
+	}
+}
+
+func TestSigningRetryLoopPropagatesSelectorError(t *testing.T) {
+	wantErr := errors.New("synthetic selector failure")
+	srl := &signingRetryLoop{
+		signingGroupOperators: chain.Addresses{
+			chain.Address("op-1"),
+			chain.Address("op-2"),
+		},
+		groupParameters:     &GroupParameters{HonestThreshold: 2},
+		attemptCounter:      1,
+		attemptSeed:         0,
+		participantSelector: &recordingSelector{err: wantErr},
+	}
+	_, err := srl.qualifiedOperatorsSet([]group.MemberIndex{1, 2})
+	if err == nil {
+		t.Fatal("expected selector error to propagate")
+	}
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("expected wrapped sentinel; got %v", err)
+	}
+}