Merge rust-bitcoin/rust-secp256k1#465: Add must_use for mut self key manipulation methods

56f18430ff Add must_use for mut self key manipulation methods (Tobin C. Harding)
5b86e38aea Put compiler attributes below rustdocs (Tobin C. Harding)

Pull request description:

  We recently added a bunch of key tweaking methods that take `mut self`
  and return the tweaked/negated keys. These functions are pure and as
  such the returned result is expected to be used. To help downstream
  users use the API correctly add `must_use` attributes with a descriptive
  error string for each of the methods that takes `mut self`.

  Patch 1 is preparatory cleanup.

ACKs for top commit:
  apoelstra:
    ACK 56f18430ff

Tree-SHA512: 95ee63d5d0a34a9915551471d2f71de1963875eda04bf4217544076be0ed2836dcdee1875432dba5e02678556af86d7487e39daac6e928083807661430ddbcd6
This commit is contained in:
Andrew Poelstra 2022-06-28 14:56:48 +00:00
commit 5f59820a8a
No known key found for this signature in database
GPG Key ID: C588D63CE41B97C1
2 changed files with 12 additions and 4 deletions

View File

@ -20,26 +20,26 @@ macro_rules! impl_array_newtype {
impl Copy for $thing {} impl Copy for $thing {}
impl $thing { impl $thing {
#[inline]
/// Converts the object to a raw pointer for FFI interfacing /// Converts the object to a raw pointer for FFI interfacing
#[inline]
pub fn as_ptr(&self) -> *const $ty { pub fn as_ptr(&self) -> *const $ty {
let &$thing(ref dat) = self; let &$thing(ref dat) = self;
dat.as_ptr() dat.as_ptr()
} }
#[inline]
/// Converts the object to a mutable raw pointer for FFI interfacing /// Converts the object to a mutable raw pointer for FFI interfacing
#[inline]
pub fn as_mut_ptr(&mut self) -> *mut $ty { pub fn as_mut_ptr(&mut self) -> *mut $ty {
let &mut $thing(ref mut dat) = self; let &mut $thing(ref mut dat) = self;
dat.as_mut_ptr() dat.as_mut_ptr()
} }
#[inline]
/// Returns the length of the object as an array /// Returns the length of the object as an array
#[inline]
pub fn len(&self) -> usize { $len } pub fn len(&self) -> usize { $len }
#[inline]
/// Returns whether the object as an array is empty /// Returns whether the object as an array is empty
#[inline]
pub fn is_empty(&self) -> bool { false } pub fn is_empty(&self) -> bool { false }
} }

View File

@ -243,6 +243,7 @@ impl SecretKey {
/// Negates the secret key. /// Negates the secret key.
#[inline] #[inline]
#[must_use = "you forgot to use the negated secret key"]
pub fn negate(mut self) -> SecretKey { pub fn negate(mut self) -> SecretKey {
unsafe { unsafe {
let res = ffi::secp256k1_ec_seckey_negate( let res = ffi::secp256k1_ec_seckey_negate(
@ -272,6 +273,7 @@ impl SecretKey {
/// ///
/// Returns an error if the resulting key would be invalid. /// Returns an error if the resulting key would be invalid.
#[inline] #[inline]
#[must_use = "you forgot to use the tweaked secret key"]
pub fn add_tweak(mut self, tweak: &Scalar) -> Result<SecretKey, Error> { pub fn add_tweak(mut self, tweak: &Scalar) -> Result<SecretKey, Error> {
unsafe { unsafe {
if ffi::secp256k1_ec_seckey_tweak_add( if ffi::secp256k1_ec_seckey_tweak_add(
@ -302,6 +304,7 @@ impl SecretKey {
/// ///
/// Returns an error if the resulting key would be invalid. /// Returns an error if the resulting key would be invalid.
#[inline] #[inline]
#[must_use = "you forgot to use the tweaked secret key"]
pub fn mul_tweak(mut self, tweak: &Scalar) -> Result<SecretKey, Error> { pub fn mul_tweak(mut self, tweak: &Scalar) -> Result<SecretKey, Error> {
unsafe { unsafe {
if ffi::secp256k1_ec_seckey_tweak_mul( if ffi::secp256k1_ec_seckey_tweak_mul(
@ -536,6 +539,7 @@ impl PublicKey {
/// Negates the public key. /// Negates the public key.
#[inline] #[inline]
#[must_use = "you forgot to use the negated public key"]
pub fn negate<C: Verification>(mut self, secp: &Secp256k1<C>) -> PublicKey { pub fn negate<C: Verification>(mut self, secp: &Secp256k1<C>) -> PublicKey {
unsafe { unsafe {
let res = ffi::secp256k1_ec_pubkey_negate(secp.ctx, &mut self.0); let res = ffi::secp256k1_ec_pubkey_negate(secp.ctx, &mut self.0);
@ -566,6 +570,7 @@ impl PublicKey {
/// ///
/// Returns an error if the resulting key would be invalid. /// Returns an error if the resulting key would be invalid.
#[inline] #[inline]
#[must_use = "you forgot to use the tweaked public key"]
pub fn add_exp_tweak<C: Verification>( pub fn add_exp_tweak<C: Verification>(
mut self, mut self,
secp: &Secp256k1<C>, secp: &Secp256k1<C>,
@ -602,6 +607,7 @@ impl PublicKey {
/// ///
/// Returns an error if the resulting key would be invalid. /// Returns an error if the resulting key would be invalid.
#[inline] #[inline]
#[must_use = "you forgot to use the tweaked public key"]
pub fn mul_tweak<C: Verification>( pub fn mul_tweak<C: Verification>(
mut self, mut self,
secp: &Secp256k1<C>, secp: &Secp256k1<C>,
@ -971,6 +977,7 @@ impl KeyPair {
/// ``` /// ```
// TODO: Add checked implementation // TODO: Add checked implementation
#[inline] #[inline]
#[must_use = "you forgot to use the tweaked key pair"]
pub fn add_xonly_tweak<C: Verification>( pub fn add_xonly_tweak<C: Verification>(
mut self, mut self,
secp: &Secp256k1<C>, secp: &Secp256k1<C>,
@ -1270,6 +1277,7 @@ impl XOnlyPublicKey {
/// let tweaked = xonly.add_tweak(&secp, &tweak).expect("Improbable to fail with a randomly generated tweak"); /// let tweaked = xonly.add_tweak(&secp, &tweak).expect("Improbable to fail with a randomly generated tweak");
/// # } /// # }
/// ``` /// ```
#[must_use = "you forgot to use the tweaked xonly pubkey"]
pub fn add_tweak<V: Verification>( pub fn add_tweak<V: Verification>(
mut self, mut self,
secp: &Secp256k1<V>, secp: &Secp256k1<V>,