Expand description
§WSTS
WSTS is a system for making Weighted Schnorr Threshold Signatures, aka WileyProofs. It allows a group of signers, each of whom controls a set of keys, to make a valid Schnorr signature, as long as T (the threshold) of them complete the protocol honestly. While there are many other threshold signature schemes, WSTS has several features which make it particularly useful in a cryptocurrency context.
First, it is optimized for a small number of rounds in the common case where there are no byzantine actors present. Since the protocol allows detection any bad actors in the system, it makes sense to optimize for the case where there are none. Such byzantine actors can be sanctioned in a way that severely disincentivezes attempts to subvert the protocol.
Second, in contrast to typical multisig protocols, WSTS produces a single aggregate signature which is indistinguisable from a standard Schnorr signature. Crucially, this signature can be verified the same way as any Schnorr signature. And since the signature is aggregated, it does not take any more space on chain than any other standard signature, and linearly less than traditional multisig signatures.
Finally, WSTS is designed to build aggregate threshold signatures which are weighted, i.e. not all signers control the same number of keys. The threshold is a function of keys, so a set of signers meets the threshold if and only if the sum of the number of keys they control equals or exceeds the threshold.
§Safety
WSTS has been independently audited and was exercised in production by the sBTC system, but that is history and it does not describe this code. sBTC vendored wsts 14.0.0 into its own tree on 2026-03-02 (sbtc#1938) and the two implementations have diverged in both directions since. sBTC removed the v1 module and the bitcoin helpers and reworked polynomial-commitment validation; this crate has taken protocol changes their copy never received. Neither tree’s audit or operational history transfers to the other.
Modifying the protocol without a thorough cryptographic review is strongly discouraged and may be insecure.
§Background
WSTS is based on FROST, i.e. Flexible Round-Optimized Schnorr Threshold signatures. FROST provides a system where a number of parties, each of which controls a single key, can form an aggregate group signing key, after which a threshold number of them can cooperate to form a valid Schnorr signature.
§Variants
This crate provides a simple implementation of WSTS in the v1 module, which is an extension of FROST where each signer controls a set of parties, each of which controls a single key.
This crate also contains a more complex version of WSTS optimized for the weighted threshold scenario in the v2 module. Like vanilla FROST, v2 keeps a single polynomial and nonce for each Party, but allows each Party to control multiple keys. This allows for order-of-magnitude reductions in data size and number of messages for the distributed key generation (DKG) and signing parts of the protocol.
§p256k1
This crate uses the Bitcoin secp256k1 curve. But since the C libsecp256k1 library only provides high level interfaces for operations used by Bitcoin, it was necessary to directly expose the scalars and curve points to allow arbitrary mathematical operations outside of sign/verify. So we provide a wrapper crate around libsecp256k1 which wraps the internal interfaces to scalars and points. We call this crate p256k1, to denote that it is not only the same curve as secp256k1, but also exposes the curve directly.
§Documentation
§Copyright and License
Copyright 2022-2024, Nassau Machines Inc
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
§Usage
Applications which use WSTS will typically run both Signer and Coordinator state machines, in order to be able to handle all parts of the protocol.
§Packet verification
Both state machines verify the signature on each incoming Packet, and do so by default. The coordinator is controlled by Config::verify_packet_sigs and the signer by the public Signer::verify_packet_sigs field, which is persisted in SavedState; both are true unless you set them otherwise.
Verification needs the state machine to know two things: the signer public keys, via public_keys, and the active coordinator’s public key, via coordinator_public_key. Without the latter, process and process_message return Error::MissingCoordinatorPublicKey; a packet whose signature does not check out returns Error::InvalidPacketSignature.
Set the flag to false if the calling application has already verified the packet, so the work is not done twice — an application running both state machines over the same packet stream would otherwise verify each packet twice. If you disable verification, the application must verify packets itself before calling process_message on them.
This is what addresses the audit critical issues CR-01 and CR-02. Verification moved into the library in #153; before that it was the application’s responsibility in every case.
§Random number generation
To ensure flexibility, these state machines require the user to provide a random number generator (RNG) that implements the RngCore and CryptoRng traits.
§Providing an RNG
You can use the following RNG implementations:
-
Operating System RNG (
OsRng)use rand_core::OsRng; let mut rng = OsRng; -
ChaCha20 RNG
use rand_chacha::ChaCha20Rng; use rand_core::SeedableRng; let mut rng = ChaCha20Rng::from_entropy(); -
Custom RNGs
Implement your own RNG by adhering to the
RngCoreandCryptoRngtraits.
§Example Usage
use wsts::util::create_rng;
use wsts::v2::Party;
// Protocol parameters
let num_parties: u32 = 5;
let num_keys: u32 = 10;
let threshold: u32 = 7;
// This party's id, and the key ids it controls
let party_id: u32 = 0;
let key_ids = [0, 1];
// Initialize your RNG
let mut rng = create_rng();
// Create a party
let party = Party::new(party_id, &key_ids, num_parties, num_keys, threshold, &mut rng);The v1 module is behind the with_v1 feature and is not built by default; use wsts::v1::Signer requires --features with_v1.
§Do not replay RNG state
WSTS derives signing nonces with the hedged construction from RFC 9591 section 4.1: each nonce is the hash of fresh RNG output together with the signer’s secret key. The secret key is mixed in so that a poor RNG does not immediately yield a predictable nonce, but the nonce is still a function of the bytes your RNG produces.
So never reuse or replay RNG state across signing rounds. Two rounds that draw the same bytes produce the same nonce, and two Schnorr signatures sharing a nonce reveal the signing key. This is why create_rng returns OsRng and why the example above seeds from entropy: neither is reproducible, deliberately. If you want a reproducible run, keep it to tests.
Re-exports§
pub use p256k1 as curve;
Modules§
- btc
- test bitcoin/taproot integration using libbitcoin_consensus
- common
- Types which are common to both v1 and v2
- compute
- Functions to perform various computations needed for v1 and v2
- errors
- Errors which are returned from objects and functions
- net
- Network messages
- schnorr
- Schnorr utility types
- state_
machine - State machines
- taproot
- Functions for doing BIP-340 schnorr proofs and other taproot actions
- traits
- Traits which are used for v1 and v2
- util
- Utilities for hashing and encryption
- v1
- Version 1 of WSTS, which encapsulates a number of parties using vanilla FROST
- v2
- Version 2 of WSTS, in which each party holds one polynomial and one nonce but may control many keys
- vss
- Shamir secret sharing, used in distributed key generation