b6791ba867
First of six commits adding a frost_enrollment module: FROST enrollment,
the protocol of Section 4.1.1 of the FROST paper, which converts a (t, n)
group into a (t, n+1) group without re-running key generation and without
any participant revealing its share. Running it at an existing
participant's identifier repairs that participant's lost share instead.
This commit is the design freeze. It adds no code and touches no build
file; nothing here is compiled yet. The header and the module document
are what the following commits implement against.
Why a separate module rather than part of frost:
- The frost module is deliberately scoped to BIP 445, whose own header
states DKG is out of scope for the same reason. Enrollment has no BIP.
- The repo already puts one protocol per module across the FROST stack:
chilldkg is the DKG, prefractal is the nested FROST+MuSig2 signer, and
both are separate modules layered on frost's key material.
- Enrollment moves share-shaped secrets between participants, has no
authorization mechanism at all, and rests on transport assumptions the
library cannot enforce. Its own --enable-module-frost-enrollment flag
keeps that surface opt-in.
Five functions, named after the round they run:
- params_hash pure, public; every party recomputes it
- shares_gen round 1.1, each helper
- share_agg round 1.2, each helper
- pubshare_derive pure, public; the expected public share at x_new
- secshare_gen round 2, the target participant
Decisions frozen here, in the order they will matter to the
implementation:
Tag strings and encoding. The params hash is
TH("FROST enrollment/params_hash",
cbytes(thresh_pk) || ser32(n) || ser32(t) || ser32(new_id) ||
ser32(u) || ser32(sorted_ids[0]) || ... )
mirroring chilldkg's params_hash (src/modules/chilldkg/util_impl.h:399)
in both its fixed-width u32be discipline and its commitment to key
material rather than to integers alone. Binding thresh_pk is what makes
the hash name a GROUP: two unrelated groups sharing (t, n, ids, new_id)
get different hashes, so the agreement checks prove the parties mean the
same group and not merely the same numbers. Ids are sorted before
hashing so helpers holding the same set in different orders agree; every
other array in the API stays aligned with the caller's own ids order.
The second tag, "FROST enrollment/share_split", is introduced by the
next commit. Both freeze once vectors.h exists.
params_hash returns int, not void. Void-returning public functions in
this library are lifecycle-only (context_destroy, selftest, callback
setters), and ARG_CHECK_VOID (src/secp256k1.c:73) fires the illegal
callback and returns with the output UNWRITTEN. Under a non-aborting
illegal callback -- a supported configuration -- a caller would then
compare a 32-byte buffer that was never computed, silently defeating
both hash gates while every call still appears to succeed.
The two u*32 buffers of share_agg take deliberately opposite own-slot
conventions, and the header says so loudly: all_shares32 READS the slot
at my position (the share shares_gen kept), while
received_params_hashes32 never reads it. The asymmetry is the mechanism
-- the own hash is recomputed from the group key and the parameter
tuple, never taken from a buffer, so a caller cannot copy a received
hash into its own slot and launder a mismatch into a pass.
mismatch_id carries the participant IDENTIFIER, following chilldkg's
fault_index convention (include/secp256k1_chilldkg.h:276), not an array
index: identifiers need not be 0..u-1, so an index would be ambiguous.
threshold >= 2, a deliberate divergence from the frost module, which
accepts threshold >= 1 (keygen_impl.h:231, :321, session_impl.h:541).
The rationale is not that t = 1 is a weak threshold; a lone member of a
1-of-n group can already sign anything. It is that this API permits any
threshold <= n_ids, so t = 1 admits u = 1, and at u = 1 the additive
split degenerates to one share: the lone helper sends the unsplit v_1,
which at t = 1 is the whole group secret. t >= 2 forces u >= 2, which is
what actually makes the split non-degenerate.
Mode-specific bounds. new_id == n_participants means enrollment and
requires n < 128, because the resulting n+1 group must still be one
frost_session_init accepts; new_id < n_participants means repair, which
does not change n and allows n <= 128. The id cap is id <
n_participants; 128 caps n, not id values.
Two deviations from the plan's draft signatures, both to match the frost
module rather than the draft:
- threshold is uint32_t, not size_t. Every frost entry point that takes
a threshold takes uint32_t (trusted_dealer_keygen,
threshold_info_validate, session_init), against size_t for
n_participants and n_signers.
- session_secrand32 sits with the outputs as an in/out parameter rather
than last, which is where secp256k1_frost_nonce_gen puts it
(include/secp256k1_frost.h:365). It is wiped by the call, so grouping
it with the inputs would misdescribe it.
frost_enrollment.md carries the protocol derivation, the two modes and
their bounds, and the four security topics the API cannot enforce on its
own: transport confidentiality for the delta and sigma values, the
missing authorization step, the circularity of the public-share check
when thresh_pk comes from the helpers themselves, and the three separate
roles of parameter binding (helper-to-helper detection, helper-to-target
detection, and seed-reuse domain separation). The verification-flow
walkthrough and the regression-vector caveat land with their code.
The header compiles clean standalone under gcc -std=c89 -pedantic -Wall
-Wextra.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
libsecp256k1-zkp
A fork of libsecp256k1 with support for advanced and experimental features
Added features:
- Experimental module for ECDSA adaptor signatures.
- Experimental module for ECDSA sign-to-contract.
- Experimental modules for Confidential Assets (Pedersen commitments, range proofs, and surjection proofs).
- Experimental module for address whitelisting.
- Experimental module for Schnorr signature half-aggregation.
- Experimental module for FROST (BIP 445).
- Experimental module for ChillDKG, distributed key generation for FROST (bip-frost-dkg draft).
- Experimental module for Iceberg, a threshold scheme that lets a group of parties stand in for a single MuSig2 (BIP 327) participant.
- Experimental module for Prefractal, a nested FROST+MuSig2 signer that lets a FROST group occupy one participant slot of an ordinary MuSig2 (BIP 327) session.
Experimental features are made available for testing and review by the community. The APIs of these features should not be considered stable.
Build steps
Obtaining and verifying
The git tag for each release (e.g. v0.6.0) is GPG-signed by one of the maintainers.
For a fully verified build of this project, it is recommended to obtain this repository
via git, obtain the GPG keys of the signing maintainer(s), and then verify the release
tag's signature using git.
This can be done with the following steps:
- Obtain the GPG keys listed in SECURITY.md.
- If possible, cross-reference these key IDs with another source controlled by its owner (e.g. social media, personal website). This is to mitigate the unlikely case that incorrect content is being presented by this repository.
- Clone the repository:
git clone https://github.com/bitcoin-core/secp256k1 - Check out the latest release tag, e.g.
git checkout v0.7.1 - Use git to verify the GPG signature:
% git tag -v v0.7.1 | grep -C 3 'Good signature' gpg: Signature made Mon 26 Jan 2026 07:42:46 PM UTC gpg: using RSA key 2840EAABF4BC9F0FFD716AFAFBAFCC46DE2D3FE2 gpg: Good signature from "Pieter Wuille <pieter@wuille.net>" [unknown] gpg: aka "Pieter Wuille <pieter.wuille@gmail.com>" [full] gpg: aka "[jpeg image of size 5996]" [undefined] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 133E AC17 9436 F14A 5CF1 B794 860F EB80 4E66 9320 Subkey fingerprint: 2840 EAAB F4BC 9F0F FD71 6AFA FBAF CC46 DE2D 3FE2
Building with Autotools
$ ./autogen.sh # Generate a ./configure script
$ ./configure # Generate a build system
$ make # Run the actual build process
$ make check # Run the test suite
$ sudo make install # Install the library into the system (optional)
To compile optional modules (such as Schnorr signatures), you need to run ./configure with additional flags (such as --enable-module-schnorrsig). Run ./configure --help to see the full list of available flags. For experimental modules, you will also need --enable-experimental as well as a flag for each individual module, e.g. --enable-module-rangeproof.
Building with CMake
To maintain a pristine source tree, CMake encourages to perform an out-of-source build by using a separate dedicated build tree.
Building on POSIX systems
$ cmake -B build # Generate a build system in subdirectory "build"
$ cmake --build build # Run the actual build process
$ ctest --test-dir build # Run the test suite
$ sudo cmake --install build # Install the library into the system (optional)
To compile optional modules (such as Schnorr signatures), you need to run cmake with additional flags (such as -DSECP256K1_ENABLE_MODULE_SCHNORRSIG=ON). Run cmake -B build -LH or ccmake -B build to see the full list of available flags.
Cross compiling
To alleviate issues with cross compiling, preconfigured toolchain files are available in the cmake directory.
For example, to cross compile for Windows:
$ cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/x86_64-w64-mingw32.toolchain.cmake
To cross compile for Android with NDK (using NDK's toolchain file, and assuming the ANDROID_NDK_ROOT environment variable has been set):
$ cmake -B build -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_ROOT}/build/cmake/android.toolchain.cmake" -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=28
Building on Windows
The following example assumes Visual Studio 2022. Using clang-cl is recommended.
In "Developer Command Prompt for VS 2022":
>cmake -B build -T ClangCL
>cmake --build build --config RelWithDebInfo
Usage examples
Usage examples can be found in the examples directory. To compile them you need to configure with --enable-examples.
- ECDSA example
- Schnorr signatures example
- Deriving a shared secret (ECDH) example
- ElligatorSwift key exchange example
- MuSig2 Schnorr multi-signatures example
To compile the examples, make sure the corresponding modules are enabled.
Benchmark
If configured with --enable-benchmark (which is the default), binaries for benchmarking the libsecp256k1-zkp functions will be present in the root directory after the build.
To print the benchmark result to the command line:
$ ./bench_name
To create a CSV file for the benchmark result :
$ ./bench_name | sed '2d;s/ \{1,\}//g' > bench_name.csv
Reporting a vulnerability
See SECURITY.md
Contributing to libsecp256k1
See CONTRIBUTING.md