FROST/ROAST readiness branch

cmd/flags.go

@@ -308,6 +308,15 @@ func initTbtcFlags(cmd *cobra.Command, cfg *config.Config) {
 		tbtc.DefaultKeyGenerationConcurrency,
 		"tECDSA key generation concurrency.",
 	)
+
+	cmd.Flags().StringVar(
+		&cfg.Tbtc.FrostSigningBackend,
+		"tbtc.frostSigningBackend",
+		"",
+		"FROST signing backend name (legacy, native, ffi). "+
+			"`native` allows transitional legacy fallback; `ffi` requires native execution. "+
+			"Empty value selects legacy.",
+	)
 }
 
 // Initialize flags for Maintainer configuration.

cmd/flags_test.go

@@ -225,6 +225,13 @@ var cmdFlagsTests = map[string]struct {
 		expectedValueFromFlag: 101,
 		defaultValue:          runtime.GOMAXPROCS(0),
 	},
+	"tbtc.frostSigningBackend": {
+		readValueFunc:         func(c *config.Config) interface{} { return c.Tbtc.FrostSigningBackend },
+		flagName:              "--tbtc.frostSigningBackend",
+		flagValue:             "native",
+		expectedValueFromFlag: "native",
+		defaultValue:          "",
+	},
 	"maintainer.bitcoinDifficulty": {
 		readValueFunc:         func(c *config.Config) interface{} { return c.Maintainer.BitcoinDifficulty.Enabled },
 		flagName:              "--bitcoinDifficulty",

docs/development/frost-roast-retry-rollout.adoc

@@ -0,0 +1,132 @@
+= FROST/ROAST Retry Rollout Guide
+
+*Author:* Threshold Labs
+*Status:* Draft
+*Date:* 2026-05-23
+
+== Summary
+
+This document describes the operational lifecycle of the
+ROAST-driven retry path introduced by RFC-21
+(`docs/rfc/rfc-21-roast-coordinator-retry-and-transition-evidence.adoc`)
+and implemented across Phases 1-7 of that RFC. It is intended for
+node operators and release engineers planning a rollout of the new
+retry semantics.
+
+The feature ships as a build-tagged code path. A production
+binary built without the tag contains *no ROAST retry code*;
+every signing flow uses the pre-RFC-21 legacy retry shuffle. A
+binary built with the tag still executes the legacy path unless
+the operator explicitly opts in via an environment variable, and
+even then the new path silently falls back to legacy whenever its
+preconditions are not met.
+
+== Activation prerequisites
+
+All three must be true at the same time for the ROAST retry path
+to influence participant selection on a given session attempt:
+
+. *Build tag set.* The keep-core binary is built with
+  `-tags frost_roast_retry`. Without the tag, the dispatcher
+  package does not include the ROAST selector at all.
+. *Operator opt-in env var.* The runtime environment defines
+  `KEEP_CORE_FROST_ROAST_RETRY_ENABLED=true` (case-insensitive,
+  whitespace-trimmed). The variable is read per call (not
+  cached), so an operator can flip the switch during a debugging
+  session without restarting the node.
+. *Coordinator registered.* A caller has invoked
+  `signing.RegisterRoastRetryCoordinator(deps)` at process
+  startup with the node's operator-key signer, the network's
+  signature verifier, and the node's member index.
+
+When any of these is missing, the receive loops, executor
+adapter, and signing-loop selector all behave as in the legacy
+pre-RFC-21 path. The behavioural rollback is therefore *configuration-
+only*: toggle the env var off and the next signing attempt uses
+the legacy retry shuffle.
+
+== Behavioural matrix
+
+[options="header"]
+|===
+| Build tag | Env var | Registry | Bundle present | Behaviour
+| not set   | _any_   | _any_     | _any_          | Legacy retry shuffle
+| set       | unset   | _any_     | _any_          | Legacy retry shuffle (env-var gate)
+| set       | true    | empty     | _any_          | Legacy retry shuffle (no coordinator)
+| set       | true    | populated | absent         | Legacy retry shuffle (first attempt / no transition yet)
+| set       | true    | populated | present        | ROAST `EvaluateRoastRetryForSigning`
+|===
+
+The bundle is "present" once the elected coordinator's node has
+produced a `TransitionMessage` at the end of a prior attempt
+(see Phase 7.1 in RFC-21). Until that happens, the ROAST path is
+dormant and the legacy path provides liveness.
+
+== Error handling discipline
+
+The orchestration layer distinguishes two error classes:
+
+* *Static-configuration errors.* Env var unset, no coordinator
+  registered, signer-material format not extractable. These are
+  deterministic per deployment configuration: every honest signer
+  observes the same outcome. Logged at INFO, signing flow
+  continues with the legacy retry shuffle.
+
+* *Runtime state-machine errors.* `Coordinator.BeginAttempt`
+  failures, internal invariant violations,
+  `ErrAttemptInfeasible` from the policy's threshold floor. These
+  are non-deterministic across nodes. Treated as *hard failures*:
+  the session is declared failed and the operator is notified
+  via the standard signing-failure log path. Falling back to
+  legacy on these errors would let one node use legacy retry
+  while another uses ROAST, which would split the signing group
+  on `NextAttempt` agreement.
+
+This discipline is the load-bearing safety property of the
+RFC-21 design and is enforced in
+`pkg/frost/signing/roast_retry_executor_entry_frost_native.go`.
+
+== Production rollout sequencing
+
+. *Build the binary with the tag.* Internal builds and CI
+  pipelines already exercise the tag via
+  `go test -tags 'frost_roast_retry' ./pkg/frost/... ./pkg/tbtc/...`.
+  Production binaries adopt the tag once the readiness manifest
+  in the cross-repo tBTC monorepo's `docs/operations/` directory
+  flips to `present`.
+. *Verify FROST/UniFFI V1 migration.* The DKG-pubkey extraction
+  helper rejects FrostUniFFIV1 signer material. The Phase 7
+  manifest flip is gated on verified migration off V1 across
+  production signers; until that migration completes, ROAST
+  retry would silently fall back to legacy on V1-bearing nodes.
+. *Stage operator opt-in.* Operators set
+  `KEEP_CORE_FROST_ROAST_RETRY_ENABLED=true` on a subset of nodes
+  first. Static-configuration fallback guarantees mixed-state
+  deployments stay correct: nodes without the env var simply use
+  legacy. Beware: a node with the env var set but no registered
+  coordinator (e.g., due to a misconfigured startup script) still
+  uses legacy, so the safety property holds.
+. *Monitor for runtime hard-failures.* The "ROAST orchestration"
+  log lines under
+  `keep-frost-roast-orchestration` and
+  `keep-frost-roast-retry` loggers indicate transitions of the
+  new state machine. A spike in WARN/ERROR entries from these
+  loggers is the early signal of trouble.
+. *Roll back via env var.* If anything misbehaves, unset
+  `KEEP_CORE_FROST_ROAST_RETRY_ENABLED` and restart (or wait for
+  the per-call check to flip the next attempt). The legacy code
+  paths are retained through Phase 6 and 7 deliberately to make
+  this rollback bit-for-bit safe.
+
+== Cross-references
+
+* RFC-21: `docs/rfc/rfc-21-roast-coordinator-retry-and-transition-evidence.adoc`
+* Build-tag scaffolding: `pkg/frost/signing/roast_retry_registration_*.go`
+* Orchestration entry point: `pkg/frost/signing/roast_retry_orchestration.go`
+* Executor-adapter wiring: `pkg/frost/signing/native_ffi_executor_adapter.go`
+* Signing-loop dispatcher: `pkg/tbtc/signing_loop_roast_dispatcher.go`
+* ROAST-driven selector: `pkg/tbtc/signing_loop_selector_frost_roast_retry.go`
+* Bundle registry: `pkg/frost/signing/roast_retry_bundle_registry_*.go`
+* Readiness env var: `pkg/frost/signing/roast_retry_readiness.go`
+* Coordinator state machine: `pkg/frost/roast/coordinator_state.go`
+* Adapter type: `pkg/frost/roast/signing_retry_adapter.go`

docs/rfc/rfc-20-schnorr-frost-migration-scaffold.adoc

@@ -0,0 +1,49 @@
+= RFC-20: Schnorr/FROST Migration Scaffold
+
+*Author:* Threshold Labs
+*Status:* Draft
+*Date:* 2026-02-19
+
+== Summary
+
+This RFC introduces the initial keep-core scaffolding for migrating tBTC from
+threshold ECDSA signatures to Schnorr/FROST signatures.
+
+This change does not switch runtime signing logic yet. It defines core data
+types and compatibility helpers required by follow-up protocol, chain, and
+wallet orchestration changes.
+
+== Initial Deliverables
+
+* New `pkg/frost` package with:
+** Taproot x-only output key type (`OutputKey`)
+** BIP-340 Schnorr signature type (`Signature`)
+** Serialization and logging helpers for Schnorr signatures
+** Legacy compatibility alias helper:
+`HASH160(0x02 || xOnlyOutputKey)`
+
+== Compatibility Model
+
+FROST wallets are expected to use 32-byte x-only keys as canonical identifiers.
+During migration, legacy 20-byte wallet key hash paths are supported via
+compatibility alias:
+
+----
+walletPubKeyHashCompat = HASH160(0x02 || xOnlyOutputKey)
+----
+
+== Follow-up Work
+
+1. Add FROST signer and coordinator interfaces to replace `pkg/tecdsa/signing`.
+2. Introduce FROST DKG executor replacing GG18 pre-params and DKG wiring.
+3. Update tBTC chain interfaces and wallet registry integration to accept
+   x-only keys as canonical wallet identities.
+4. Update Bitcoin transaction builders to support P2TR key-path spends.
+5. Add dual-stack runtime routing: GG18 existing wallets + FROST new wallets.
+6. Add full integration tests for mixed wallet generations and migration flows.
+
+== Non-Goals (This RFC Revision)
+
+* No production FROST coordinator implementation.
+* No on-chain contract ABI migration in this repository.
+* No replacement of existing GG18 runtime paths yet.