clean doc todos

Author: nickfarrow

schnorr_fun/src/musig.rs

@@ -3,27 +3,25 @@
 //! ## Synopsis
 //!
 //! ```
-//! use schnorr_fun::{musig::MuSig, Schnorr, Message, nonce::Deterministic};
+//! use schnorr_fun::{musig::MuSig, nonce::Deterministic, Message, Schnorr};
 //! use sha2::Sha256;
 //! // use sha256 with deterministic nonce generation
 //! let musig = MuSig::<Sha256, Schnorr<Sha256, Deterministic<Sha256>>>::default();
 //! // create a keylist
 //! use schnorr_fun::fun::Scalar;
-//! let kp1 = musig.schnorr.new_keypair(Scalar::random(&mut rand::thread_rng()));
+//! let kp1 = musig
+//!     .schnorr
+//!     .new_keypair(Scalar::random(&mut rand::thread_rng()));
 //! let public_key1 = kp1.public_key();
 //! # let kp2 = musig.schnorr.new_keypair(Scalar::random(&mut rand::thread_rng()));
 //! # let public_key2 = kp2.public_key();
 //! # let kp3 = musig.schnorr.new_keypair(Scalar::random(&mut rand::thread_rng()));
 //! # let public_key3 = kp3.public_key();
 //! // recieve the public keys of all other participants to form the aggregate key.
-//! let keylist = musig.new_keylist(vec![
-//!     public_key1,
-//!     public_key2,
-//!     public_key3,
-//! ]);
+//! let keylist = musig.new_keylist(vec![public_key1, public_key2, public_key3]);
 //! let agg_key = keylist.agg_public_key();
 //!
-//! // create unique nonce, and send public nonce to other parties.
+//! // create a unique nonce, and send the public nonce to other parties.
 //! let p1_nonce = musig.gen_nonces(kp1.secret_key(), &keylist, b"session-id-1337");
 //! let p1_public_nonce = p1_nonce.public();
 //! # let p2_nonce = musig.gen_nonces(kp2.secret_key(), &keylist, b"session-id-1337");
@@ -34,8 +32,8 @@
 //! let nonces = vec![p1_public_nonce, p2_public_nonce, p3_public_nonce];
 //! let message = Message::plain("my-app", b"chancellor on brink of second bailout for banks");
 //! // start the signing session
-//! let mut session = musig.start_sign_session(&keylist, nonces, message).unwrap();
-//! // sign with our (single) local keypair
+//! let session = musig.start_sign_session(&keylist, nonces, message).unwrap();
+//! // sign with our single local keypair
 //! let p1_sig = musig.sign(&keylist, 0, kp1.secret_key(), p1_nonce, &session);
 //! # let p2_sig = musig.sign(&keylist, 1, kp2.secret_key(), p2_nonce, &session);
 //! # let p3_sig = musig.sign(&keylist, 2, kp3.secret_key(), p3_nonce, &session);
@@ -45,7 +43,9 @@
 //! // combine them with ours into the final signature
 //! let sig = musig.combine_partial_signatures(&keylist, &session, [p1_sig, p2_sig, p3_sig]);
 //! // check it's a valid normal Schnorr signature
-//! musig.schnorr.verify(&keylist.agg_verification_key(), message, &sig);
+//! musig
+//!     .schnorr
+//!     .verify(&keylist.agg_verification_key(), message, &sig);
 //! ```
 //!
 //! ## Description
@@ -210,10 +210,7 @@ impl<H: Digest<OutputSize = U32> + Clone, S> MuSig<H, S> {
     /// let my_keypair = musig.schnorr.new_keypair(my_secret_key);
     /// let my_public_key = my_keypair.public_key();
     /// // Note the keys have to come in the same order on the other side!
-    /// let keylist = musig.new_keylist(vec![
-    ///     their_public_key,
-    ///     my_public_key,
-    /// ]);
+    /// let keylist = musig.new_keylist(vec![their_public_key, my_public_key]);
     /// ```
     pub fn new_keylist(&self, parties: Vec<XOnly>) -> KeyList {
         let keys = parties.clone();
@@ -255,7 +252,6 @@ impl<H: Digest<OutputSize = U32> + Clone, S> MuSig<H, S> {
 }
 
 impl<H: Digest<OutputSize = U32> + Clone, NG: NonceGen> MuSig<H, Schnorr<H, NG>> {
-    /// TODO
     /// Generate nonces for your local keys in keylist.
     ///
     /// It is very important to carefully consider the implications of your choice of underlying
@@ -268,17 +264,14 @@ impl<H: Digest<OutputSize = U32> + Clone, NG: NonceGen> MuSig<H, Schnorr<H, NG>>
     ///
     /// Using a [`Deterministic`] nonce generator means you **must** never start two signing
     /// sessions with nonces generated from the same `sid`. If you do your secret key will be
-    /// recoverable from the two partial signatures you created with the same nonce. The upside is
-    /// that you can call [`start_sign_session_deterministic`] with the `sid` you originally passed
-    /// to `gen_nonces` without having to store the output of `gen_nonces`.
+    /// recoverable from the two partial signatures you created with the same nonce.
     ///
     /// Note that the API allows you to BYO nonces by creating `NonceKeyPair`s manually.
     ///
     /// [`NonceGen`]: secp256kfun::nonce::NonceGen
     /// [`Synthetic`]: secp256kfun::nonce::Synthetic
     /// [`Deterministic`]: secp256kfun::nonce::Deterministic
     /// [`start_sign_session`]: Self::start_sign_session
-    /// [`start_sign_session_deterministic`]: Self::start_sign_session_deterministic
     /// [`NonceKeyPair`]: schnorr_fun::binonce::NonceKeyPair
     pub fn gen_nonces(&self, secret: &Scalar, keylist: &KeyList, sid: &[u8]) -> NonceKeyPair {
         let r1 = derive_nonce!(
@@ -329,15 +322,14 @@ pub struct Adaptor {
 ///
 /// ## Security
 ///
-/// This struct has **secret nonces** in it up until you call [`clear_secrets`] or [`sign`]. If
-/// a malicious party gains access to it before and you generate a partial signature with this session they
+/// This struct has **secret nonces** in it up until you call [`sign`]. If a malicious party
+/// gains access to it before and you generate a partial signature with this session they
 /// will be able to recover your secret key. If this is a concern simply avoid serializing this
 /// struct (until you've cleared it) and recreate it only when you need it.
 ///
 /// [`start_sign_session`]: MuSig::start_sign_session
 /// [`start_encrypted_sign_session`]: MuSig::start_encrypted_sign_session
-/// [`clear_secrets`]: SignSession::clear_secrets
-/// [`sign_all`]: MuSig::sign_all
+/// [`sign`]: MuSig::sign
 #[derive(Debug, Clone, PartialEq)]
 #[cfg_attr(
     feature = "serde",
@@ -390,9 +382,8 @@ impl<H: Digest<OutputSize = U32> + Clone, NG> MuSig<H, Schnorr<H, NG>> {
     /// i.e. a session to produce an adaptor signature under `encryption_key`.
     /// See [`adaptor`] for a more general description of adaptor signatures.
     ///
-    /// You must provide you local secret nonces (the public portion must be shared with the other
-    /// signer(s)). If you are using deterministic nonce generation it's possible to use
-    /// [`start_encrypted_sign_session_deterministic`] instead.
+    /// You must provide the public nonces (where your public portions must be
+    /// shared with the other signer(s)).
     ///
     /// ## Return Value
     ///
@@ -405,7 +396,6 @@ impl<H: Digest<OutputSize = U32> + Clone, NG> MuSig<H, Schnorr<H, NG>> {
     /// Panics if number of local or remote nonces passed in does not align with the parties in
     /// `keylist`.
     ///
-    /// [`start_encrypted_sign_session_deterministic`]: Self::start_sign_session_deterministic
     /// [`adaptor`]: crate::adaptor
     pub fn start_encrypted_sign_session(
         &self,
@@ -419,7 +409,6 @@ impl<H: Digest<OutputSize = U32> + Clone, NG> MuSig<H, Schnorr<H, NG>> {
         Some(SignSession {
             b,
             c,
-            // local_secret_nonce,
             public_nonces,
             R,
             nonce_needs_negation,
@@ -482,12 +471,6 @@ impl<H: Digest<OutputSize = U32> + Clone, NG> MuSig<H, Schnorr<H, NG>> {
     }
 
     /// Generates a partial signature (or partial encrypted signature depending on `T`) for the local_secret_nonce.
-    ///
-    /// TODO
-    /// This can only be called once per session as it clears the session (see also [`clear_secrets`]).
-    /// Calling `sign` again will return an empty vector.
-    ///
-    /// [`clear_secrets`]: SignSession::clear_secrets
     pub fn sign<T>(
         &self,
         keylist: &KeyList,