frost_enrollment: finish the module documentation and integration

Sixth and last commit of the series. Completes frost_enrollment.md, adds
the README feature link, and records the results of the full
cross-build verification pass.

frost_enrollment.md gains the four sections that only made sense once
the code existed:

- A round diagram naming who sends what to whom for u = 3, because the
  transposition between round 1.1's output buffers and round 1.2's input
  buffer is the one part of this protocol that is genuinely easy to wire
  up backwards, and prose does not make it obvious.
- An API table in protocol order, plus the two array conventions stated
  once in a place a reader will find them: everything of length u is
  aligned with the caller's own ids order, and the parameters hash is
  the sole exception because it sorts a local copy; and the deliberately
  opposite own-slot conventions of share_agg's two u*32 buffers.
- The Test vectors section, saying plainly what the vectors are and are
  not. They are regression vectors: they pin the tag strings, the
  serialization, the derivation and the identifier conventions, so that
  changing any of those is loud. They are not cross-validation, because
  the protocol has no BIP and the reference proof of concept's
  randomness is not seedable. The algebraic invariants in tests_impl.h
  are what carry correctness, and the section says which ones.
- Frozen encodings, giving both tagged hashes in full so an
  interoperating implementation does not have to read the C.

The verification section also now records what the fault-injection test
demonstrates, since it is the concrete argument for the
expected_pubshare parameter: a flipped bit in one sigma makes
secshare_gen fail and wipe its output, while the same call with NULL
succeeds and returns a wrong share.

README.md gains the module link beside the other four FROST-stack
entries, pointing at the module-local document. That keeps it consistent
with EXTRA_DIST, which has carried the file since the scaffolding commit
-- the pairing 42f827a7 established and 0e5369de completed for
prefractal.

CI wiring landed with the scaffolding commit and is unchanged here.

NOT DONE, deliberately: the plan called for a CHANGELOG.md entry. That
file opens by stating it is not this fork's changelog but upstream
libsecp256k1's, and it has no "fork's experimental additions" section to
add one under. None of frost, chilldkg, iceberg or prefractal has an
entry there. Adding the first one would put fork-only content into a
file documenting upstream releases and break with four modules' worth of
precedent, so it is left out rather than done quietly. If a fork
changelog is wanted, it is a separate decision affecting all five
modules.

ALSO NOT DONE, and flagged: no CI job builds any experimental module
through CMake -- the only module flag in the workflow is
-DSECP256K1_ENABLE_MODULE_RECOVERY=ON in the MSVC job (ci.yml:702). So
the src/CMakeLists.txt block, the EXPERIMENTAL gate entry and the
PARENT_SCOPE lift added by this series have no standing CI guard, exactly
as they have none for frost, chilldkg, iceberg or prefractal. The plan
offered closing the gap as optional; it would change what an existing job
covers for five modules at once, which is wider than this series, so it
is left as a separate decision. The CMake path was therefore verified by
hand, below.

Final verification, run over the finished tree:

Autotools.
- Ordering regression: configuring with ONLY
  --enable-module-frost-enrollment emits both
  -DENABLE_MODULE_FROST_ENROLLMENT=1 and -DENABLE_MODULE_FROST=1, the
  summary reports frost = yes, the build is warning-free and ./tests
  exits 0.
- Full build with frost, chilldkg, iceberg, prefractal,
  frost-enrollment, recovery, ellswift, examples and ctime tests: zero
  warnings, `make check` reports 12/12 PASS including
  frost_enrollment_example.
- ctime_tests under valgrind: 0 errors from 0 contexts.
- make dist succeeds and the tarball carries the public header, all five
  module files including frost_enrollment.md, and the example.
- With the module off (the default), nm shows zero frost_enrollment
  symbols in libsecp256k1.so.
- --enable-module-frost-enrollment without --enable-experimental is
  rejected with the expected message.

CMake, by hand.
- Full FROST stack plus examples: configure reports frost-enrollment ON
  and frost ON (the PARENT_SCOPE lift working), the build is
  warning-free, ctest is 532/532 including
  secp256k1.example.frost_enrollment.
- -DSECP256K1_ENABLE_MODULE_FROST_ENROLLMENT=ON without
  -DSECP256K1_EXPERIMENTAL=ON is rejected with the expected message.
- The dev-mode preset that tools/check-abi.sh uses leaves both frost and
  frost-enrollment OFF, so the ABI comparison is unaffected by this
  series.

Symbols. tools/symbol-check.py derives its expected set by grepping
SECP256K1_API declarations under include/; simulating that grep yields
exactly the five new names, and nm reports exactly those five exported
from a frost-enrollment build, with no duplicates. The script itself
could not be run here because python3-lief is not installed in this
environment.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso Ngako
2026-09-04 04:37:44 +02:00
parent 5155ee03f7
commit 782fede2c5
2 changed files with 113 additions and 1 deletions

View File

@@ -15,6 +15,7 @@ Added features:
* Experimental module for [ChillDKG](src/modules/chilldkg/chilldkg.md), distributed key generation for FROST (bip-frost-dkg draft).
* Experimental module for [Iceberg](doc/iceberg.md), a threshold scheme that lets a group of parties stand in for a single MuSig2 (BIP 327) participant.
* Experimental module for [Prefractal](doc/prefractal.md), a nested FROST+MuSig2 signer that lets a FROST group occupy one participant slot of an ordinary MuSig2 (BIP 327) session.
* Experimental module for [FROST enrollment](src/modules/frost_enrollment/frost_enrollment.md), which grows a (t, n) FROST group into a (t, n+1) one, and repairs a lost share, without re-running key generation.
Experimental features are made available for testing and review by the community. The APIs of these features should not be considered stable.