feat(tbtc/node): FROST/ROAST Go node — distributed DKG, interactive signing loop, Taproot wallet lifecycle

.dockerignore

@@ -31,6 +31,11 @@ token-tracker/
 **/gen/**/*.go
 !**/gen/gen.go
 !**/gen/cmd/cmd.go
+!pkg/chain/ethereum/frost/gen/abi/*.go
+!pkg/chain/ethereum/frost/gen/validatorabi/*.go
+!pkg/chain/ethereum/tbtc/gen/abi/*.go
+!pkg/chain/ethereum/tbtc/gen/contract/*.go
+!pkg/chain/ethereum/tbtc/gen/cmd/*.go
 
 # Legacy V1 contracts bindings.
 # We won't generate new bindings in the docker build process, but use the existing ones.

.github/actions/install-yarn-deps/action.yml

@@ -43,14 +43,18 @@ runs:
         export YARN_ENABLE_HARDENED_MODE=0
         corepack enable
         yarn --version
+        SAFE_GIT_HOME="${RUNNER_TEMP:-/tmp}/git-clean-home"
+        SAFE_GIT_CONFIG="${SAFE_GIT_HOME}/.gitconfig"
+        mkdir -p "$SAFE_GIT_HOME"
+        touch "$SAFE_GIT_CONFIG"
         unset_args=()
         while IFS='=' read -r key _; do
           case "$key" in
             GIT_CONFIG_*) unset_args+=("-u" "$key") ;;
           esac
         done < <(env)
         env "${unset_args[@]}" \
+          GIT_CONFIG_GLOBAL="$SAFE_GIT_CONFIG" \
           GIT_CONFIG_NOSYSTEM=1 \
-          GIT_CONFIG_SYSTEM=/dev/null \
           GIT_CONFIG_COUNT=0 \
           yarn install --immutable

.github/actions/setup-git-for-yarn/action.yml

@@ -1,8 +1,9 @@
 name: Setup Git for Yarn (git dependencies)
 description: >
   Configure Git so Yarn can clone dependencies (e.g. thesis/eslint-config) on
-  GitHub-hosted runners. Sets GIT_CONFIG_GLOBAL and GIT_CONFIG_NOSYSTEM to avoid
-  broken system config ("invalid key core.autocrlf" / unable to write config).
+  GitHub-hosted runners. Sets GIT_CONFIG_GLOBAL to a writable temporary file and
+  GIT_CONFIG_NOSYSTEM to avoid broken system config ("invalid key core.autocrlf"
+  / unable to write config).
 runs:
   using: composite
   steps:
@@ -14,9 +15,11 @@ runs:
         WRAPPER_DIR="${RUNNER_TEMP:-/tmp}/git-clean-bin"
         SAFE_HOME="${SAFE_TMP}/git-clean-home"
         SAFE_XDG_CONFIG_HOME="${SAFE_TMP}/git-clean-xdg-config"
+        SAFE_GLOBAL_CONFIG="${SAFE_HOME}/.gitconfig"
         REAL_GIT="$(command -v git)"
 
         mkdir -p "$WRAPPER_DIR" "$SAFE_HOME" "$SAFE_XDG_CONFIG_HOME"
+        touch "$SAFE_GLOBAL_CONFIG"
         printf '%s\n' \
           '#!/usr/bin/env bash' \
           'set -euo pipefail' \
@@ -28,9 +31,8 @@ runs:
           'done < <(env)' \
           "export HOME=\"${SAFE_HOME}\"" \
           "export XDG_CONFIG_HOME=\"${SAFE_XDG_CONFIG_HOME}\"" \
-          'export GIT_CONFIG_GLOBAL=/dev/null' \
+          "export GIT_CONFIG_GLOBAL=\"${SAFE_GLOBAL_CONFIG}\"" \
           'export GIT_CONFIG_NOSYSTEM=1' \
-          'export GIT_CONFIG_SYSTEM=/dev/null' \
           'export GIT_CONFIG_COUNT=0' \
           "if ! pwd >/dev/null 2>&1; then cd \"${SAFE_TMP}\"; fi" \
           "exec \"${REAL_GIT}\" \"\$@\"" \

.github/workflows/client.yml

@@ -310,6 +310,55 @@ jobs:
           install-go: false
           checks: "-SA1019"
 
+  # Compiles and unit-tests the interactive FROST + ROAST retry coordinator path,
+  # which lives behind the `frost_roast_retry` (and `frost_native`) build tags. The
+  # default untagged build the other jobs run compiles only the `!frost_roast_retry`
+  # no-op stubs, so without this job the entire ROAST retry state machine (liveness +
+  # evidence/blame) and the ~30 `frost_native` unit tests never compile or run in CI.
+  #
+  # This is the mock-FFI path: it exercises the Go coordinator flow with cgo DISABLED,
+  # so it needs neither libfrost_tbtc (the Rust signer lib) nor Docker. The real-crypto
+  # cgo variant of these tags is gated separately by frost-cgo-integration.yml.
+  client-frost-roast-retry:
+    needs: client-detect-changes
+    if: |
+      github.event_name == 'push'
+        || needs.client-detect-changes.outputs.path-filter == 'true'
+    runs-on: ubuntu-latest
+    env:
+      CGO_ENABLED: "0"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: "go.mod"
+
+      - name: Build the ROAST retry coordinator path (mock FFI, no cgo)
+        run: |
+          # `frost_roast_retry` alone compiles the coordinator registry / evidence /
+          # blame flow against mock producers; adding `frost_native` also compiles the
+          # native-engine <-> retry integration files (mock FFI engine, still no lib).
+          go build -tags "frost_roast_retry" ./...
+          go build -tags "frost_native frost_roast_retry" ./...
+
+      - name: Unit-test the tagged path (mock FFI, no cgo)
+        run: |
+          # These three tag sets cover every non-cgo tagged test file in pkg/frost and
+          # pkg/tbtc:
+          #   frost_native                    -> frost_native (and && !frost_roast_retry)
+          #   frost_roast_retry               -> frost_roast_retry (and && !frost_native)
+          #   frost_native frost_roast_retry  -> the intersection integration tests
+          # The `frost_native frost_tbtc_signer cgo` real-crypto tests are NOT run here;
+          # they are covered by frost-cgo-integration.yml.
+          for tags in \
+            "frost_native" \
+            "frost_roast_retry" \
+            "frost_native frost_roast_retry"; do
+            echo "::group::go test -tags \"$tags\""
+            go test -tags "$tags" -count=1 -timeout 25m ./pkg/frost/... ./pkg/tbtc/...
+            echo "::endgroup::"
+          done
+
   client-integration-test:
     needs: [client-detect-changes, electrum-integration-detect-changes, client-build-test-publish]
     if: |

.github/workflows/frost-cgo-integration.yml

@@ -0,0 +1,139 @@
+name: FROST cgo integration
+
+# Pre-merge validation gate for the interactive FROST cgo path (RFC-21 Phase 7.3).
+#
+# The rest of CI builds NONE of the `frost_native frost_tbtc_signer cgo` tags, so the
+# real-crypto interactive tests (which link libfrost_tbtc, built from the Rust signer
+# crate) are otherwise validated only locally and can silently rot. This job builds the
+# lib from a PINNED signer source (ci/frost-signer-pin.env) and runs the cgo-tagged tests
+# against it with skips FORBIDDEN (KEEP_CORE_FROST_REQUIRE_CGO=true), so a stale/missing/
+# unloadable lib fails the job instead of quietly dropping coverage.
+#
+# The tag set also includes `frost_roast_retry`, so the ROAST retry coordinator flow is
+# compiled and tested against real crypto here (the mock-FFI variant runs in client.yml),
+# and the job smoke-builds the full activation artifact via `make build-frost`. The
+# non-cgo tagged build/test coverage lives in the client.yml `client-frost-roast-retry`
+# job; together they cover the tag matrix that the default untagged CI never touches.
+#
+# The Go interactive code and the signer crate currently live on separate branches, so
+# this checks the pinned mirror commit out into a side path and builds from there. After
+# the branches merge, replace the cross-branch checkout with an in-tree cargo build and
+# keep the gate.
+
+on:
+  pull_request:
+    paths:
+      - "pkg/frost/**"
+      - "pkg/tbtc/**"
+      - "pkg/net/**"
+      - "go.mod"
+      - "go.sum"
+      - "Makefile"
+      - "ci/frost-signer-pin.env"
+      - ".github/workflows/frost-cgo-integration.yml"
+  workflow_dispatch: {}
+
+jobs:
+  frost-cgo-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the Go branch
+        uses: actions/checkout@v4
+
+      - name: Read the pinned signer source ref
+        id: pin
+        run: |
+          set -euo pipefail
+          # shellcheck disable=SC1091
+          source ci/frost-signer-pin.env
+          if [ -z "${FROST_SIGNER_MIRROR_REF:-}" ]; then
+            echo "FROST_SIGNER_MIRROR_REF is not set in ci/frost-signer-pin.env"
+            exit 1
+          fi
+          echo "ref=${FROST_SIGNER_MIRROR_REF}" >> "$GITHUB_OUTPUT"
+          echo "Pinned tbtc-signer source: ${FROST_SIGNER_MIRROR_REF}"
+
+      - name: Check out the pinned signer source
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.pin.outputs.ref }}
+          path: _signer-mirror
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: "go.mod"
+
+      - name: Build libfrost_tbtc from the pinned source
+        env:
+          CARGO_TARGET_DIR: ${{ github.workspace }}/_frost-target
+        run: |
+          set -euo pipefail
+          test -f _signer-mirror/pkg/tbtc/signer/Cargo.toml || {
+            echo "signer crate not found at the pinned ref (_signer-mirror/pkg/tbtc/signer)"; exit 1; }
+          cargo build --manifest-path _signer-mirror/pkg/tbtc/signer/Cargo.toml
+          lib="${CARGO_TARGET_DIR}/debug/libfrost_tbtc.so"
+          test -f "$lib" || { echo "libfrost_tbtc.so not found at $lib"; exit 1; }
+          echo "FROST_LIB_DIR=${CARGO_TARGET_DIR}/debug" >> "$GITHUB_ENV"
+
+      - name: Verify the engine ABI symbols are exported
+        run: |
+          set -euo pipefail
+          lib="${FROST_LIB_DIR}/libfrost_tbtc.so"
+          # A representative slice of the symbols the cgo bridge resolves via
+          # dlsym(RTLD_DEFAULT). A miss here means the pinned lib is stale vs. the bridge;
+          # fail with a clear message (the require-cgo run below would also catch it).
+          missing=0
+          for sym in \
+            frost_tbtc_persist_distributed_dkg_key_package \
+            frost_tbtc_dkg_part1 \
+            frost_tbtc_derive_interactive_attempt_context \
+            frost_tbtc_interactive_session_open \
+            frost_tbtc_interactive_session_abort \
+            frost_tbtc_new_signing_package \
+            frost_tbtc_interactive_aggregate \
+            frost_tbtc_verify_signature_share \
+            frost_tbtc_version \
+            frost_tbtc_abi_version; do
+            if ! nm -D --defined-only "$lib" | grep -q " ${sym}$"; then
+              echo "missing exported symbol: ${sym}"
+              missing=1
+            fi
+          done
+          test "$missing" -eq 0 || { echo "pinned libfrost_tbtc is missing required symbols"; exit 1; }
+
+      - name: Run the cgo-tagged real-crypto tests (skips forbidden)
+        env:
+          CGO_ENABLED: "1"
+          KEEP_CORE_FROST_REQUIRE_CGO: "true"
+        run: |
+          set -euo pipefail
+          # --no-as-needed keeps the DT_NEEDED on libfrost_tbtc even though the bridge
+          # references its symbols only via dlsym (no direct references), so the loader
+          # makes them resolvable at runtime; rpath lets the test binary find the .so.
+          export CGO_LDFLAGS="-L${FROST_LIB_DIR} -Wl,--no-as-needed -lfrost_tbtc -Wl,-rpath,${FROST_LIB_DIR}"
+          # Run the WHOLE tagged pkg/frost/signing suite against the linked lib, not a
+          # narrow -run subset. `frost_roast_retry` is added to the tag set so the ROAST
+          # retry coordinator flow (liveness + evidence/blame) is compiled and tested
+          # against real crypto here too, not only in the mock-FFI job (client.yml).
+          # With KEEP_CORE_FROST_REQUIRE_CGO=true a lib-unavailable would-be skip becomes
+          # a hard failure, so a stale/missing symbol fails the gate instead of silently
+          # dropping coverage. This gate is the only CI that builds the cgo tag set.
+          go test -tags "frost_native frost_tbtc_signer frost_roast_retry" -count=1 \
+            -timeout 20m \
+            ./pkg/frost/signing/
+
+      - name: Smoke-build the FROST activation artifact (make build-frost)
+        env:
+          CGO_ENABLED: "1"
+        run: |
+          set -euo pipefail
+          # Proves the release/activation binary - the keep-client built with
+          # `frost_native frost_tbtc_signer frost_roast_retry` and linked against
+          # libfrost_tbtc - actually compiles and links. The default `make build` the
+          # release/Docker path runs ships the `!frost_roast_retry` no-op stubs; this is
+          # the target that produces the ROAST-retry-enabled artifact once the readiness
+          # manifest flips. Reuses the same lib built above (frost_lib_dir=FROST_LIB_DIR).
+          make build-frost frost_lib_dir="${FROST_LIB_DIR}"
+          test -x ./keep-client || { echo "keep-client activation binary was not produced"; exit 1; }
+          ./keep-client --version

Dockerfile

@@ -46,6 +46,7 @@ COPY ./pkg/chain/ethereum/common/gen $APP_DIR/pkg/chain/ethereum/common/gen
 COPY ./pkg/chain/ethereum/ecdsa/gen $APP_DIR/pkg/chain/ethereum/ecdsa/gen
 COPY ./pkg/chain/ethereum/tbtc/gen $APP_DIR/pkg/chain/ethereum/tbtc/gen
 COPY ./pkg/chain/ethereum/threshold/gen $APP_DIR/pkg/chain/ethereum/threshold/gen
+COPY ./pkg/frost/roast/gen $APP_DIR/pkg/frost/roast/gen
 COPY ./pkg/net/gen $APP_DIR/pkg/net/gen
 COPY ./pkg/tbtc/gen $APP_DIR/pkg/tbtc/gen
 COPY ./pkg/tecdsa/dkg/gen $APP_DIR/pkg/tecdsa/dkg/gen

Makefile

@@ -77,6 +77,10 @@ else
 	$(foreach module,$(modules),$(call get_npm_package,$(module),$(environment)))
 endif
 
+# NOTE: a new *.proto package must also be added to the gen-directory COPY
+# allowlist in the Dockerfile: the image strips committed **/gen/**/*.go
+# (.dockerignore) and regenerates protobufs in-image, and make generate only
+# sees gen directories copied before it runs.
 proto_files := $(shell find ./pkg -name '*.proto')
 proto_targets := $(proto_files:.proto=.pb.go)
 
@@ -125,6 +129,39 @@ build:
 	$(info Building Go code)
 	$(call go_build_cmd,.,$(app_name))
 
+# FROST activation build.
+#
+# Produces the keep-client binary with the interactive FROST + ROAST retry
+# coordinator path compiled in (build tags `frost_native frost_tbtc_signer
+# frost_roast_retry`). The default `build` target above compiles the
+# `!frost_roast_retry` no-op stubs, so the released image ships with the ROAST
+# retry coordinator disabled; this target is the artifact that actually enables
+# it once the readiness manifest flips (see
+# docs/development/frost-roast-retry-rollout.adoc).
+#
+# Unlike `build` this is a cgo build that links libfrost_tbtc (the Rust signer
+# lib built from the tbtc-signer crate). Point `frost_lib_dir` at the directory
+# holding the built `libfrost_tbtc.{so,dylib}`. The CGO_LDFLAGS mirror the
+# frost-cgo-integration CI workflow: `--no-as-needed` keeps the DT_NEEDED entry
+# even though the cgo bridge resolves the frost_tbtc_* symbols via dlsym (no
+# direct references), and the rpath lets the binary find the lib at runtime.
+# These are GNU-ld flags; the target is meant for the Linux CI/release toolchain.
+frost_build_tags := frost_native frost_tbtc_signer frost_roast_retry
+
+ifndef frost_lib_dir
+override frost_lib_dir = $(CURDIR)/_frost-target/debug
+endif
+
+build-frost:
+	$(info Building Go code with the FROST activation tags [$(frost_build_tags)])
+	CGO_ENABLED=1 \
+	CGO_LDFLAGS="-L$(frost_lib_dir) -Wl,--no-as-needed -lfrost_tbtc -Wl,-rpath,$(frost_lib_dir)" \
+	go build \
+		-tags "$(frost_build_tags)" \
+		-ldflags "-X github.com/keep-network/keep-core/build.Version=$(version) -X github.com/keep-network/keep-core/build.Revision=$(revision) -checklinkname=0" \
+		-o $(app_name) \
+		.
+
 platforms := linux/amd64 \
 	darwin/amd64
 
@@ -146,4 +183,4 @@ cmd-help: build
 	@echo '$$ $(app_name) start --help' > docs/resources/client-start-help
 	./$(app_name) start --help >> docs/resources/client-start-help
 
-.PHONY: all development sepolia download_artifacts generate gen_proto build cmd-help release build_multi
+.PHONY: all development sepolia download_artifacts generate gen_proto build build-frost cmd-help release build_multi

ci/frost-signer-pin.env

@@ -0,0 +1,18 @@
+# Pinned tbtc-signer (libfrost_tbtc) source for the frost-cgo-integration CI gate.
+#
+# The Go cgo bridge (pkg/frost/signing, build tags `frost_native frost_tbtc_signer`)
+# resolves frost_tbtc_* symbols at runtime from libfrost_tbtc, which is built from the
+# Rust signer crate. The Go interactive code and that crate currently live on SEPARATE
+# branches of this repo (the Go "scaffold" branch vs. the "mirror" branch that holds
+# pkg/tbtc/signer), so the gate checks out THIS exact mirror commit, builds the lib, and
+# runs the cgo-tagged Go tests against it with skips FORBIDDEN.
+#
+# Why an explicit pin (not the mirror branch tip): the bridge skips on a stale lib that
+# is missing a newer symbol. If CI tracked the moving tip, an engine/bridge drift could
+# silently turn the real-crypto tests into skips (lost coverage) or break the gate for
+# code nobody reviewed together. Bump this SHA deliberately, in the same PR that requires
+# a newer engine ABI, so the change is reviewed as one unit.
+#
+# After the scaffold and mirror branches merge into one, replace the cross-branch
+# checkout with an in-tree cargo build and retire this pin (keep the gate).
+FROST_SIGNER_MIRROR_REF=6e0fa9741ffb6b0bb5603eabe26fb4cc1b13ecd9

cmd/flags.go

@@ -310,6 +310,36 @@ 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.",
+	)
+
+	cmd.Flags().BoolVar(
+		&cfg.Tbtc.DisableLegacyECDSA,
+		"tbtc.disableLegacyECDSA",
+		false,
+		"Disable legacy ECDSA wallet DKG and pre-params generation for FROST-only deployments.",
+	)
+
+	cmd.Flags().BoolVar(
+		&cfg.Tbtc.DisableLegacySortitionPoolMonitoring,
+		"tbtc.disableLegacySortitionPoolMonitoring",
+		false,
+		"Disable legacy ECDSA sortition pool monitoring for FROST-only deployments.",
+	)
+
+	cmd.Flags().BoolVar(
+		&cfg.Tbtc.DisableFrostSortitionPoolMonitoring,
+		"tbtc.disableFrostSortitionPoolMonitoring",
+		false,
+		"Disable FROST sortition pool monitoring for operators that manage FROST pool membership out of band.",
+	)
 }
 
 // Initialize flags for Maintainer configuration.
@@ -395,5 +425,7 @@ func initDeveloperFlags(command *cobra.Command) {
 	initContractAddressFlag(chainEthereum.RandomBeaconContractName)
 	initContractAddressFlag(chainEthereum.TokenStakingContractName)
 	initContractAddressFlag(chainEthereum.WalletRegistryContractName)
+	initContractAddressFlag(chainEthereum.FrostWalletRegistryContractName)
+	initContractAddressFlag(chainEthereum.FrostDkgValidatorContractName)
 	initContractAddressFlag(chainEthereum.WalletProposalValidatorContractName)
 }