Rename BernsteinYang* to SafeGcd* (#655)

And `bernstein_yang` => `safegcd` for snake case.

I've been noticing that in code, the algorithm tends to be referred to
using the shorter "safegcd" name as opposed to the much longer
"Bernstein-Yang".

This renames the implementation accordingly.

Author: tarcieri

src/const_choice.rs

@@ -1,6 +1,6 @@
 use subtle::{Choice, CtOption};
 
-use crate::{modular::BernsteinYangInverter, Limb, NonZero, Odd, Uint, WideWord, Word};
+use crate::{modular::SafeGcdInverter, Limb, NonZero, Odd, Uint, WideWord, Word};
 
 /// A boolean value returned by constant-time `const fn`s.
 // TODO: should be replaced by `subtle::Choice` or `CtOption`
@@ -428,7 +428,7 @@ impl ConstCtOption<NonZero<Limb>> {
 }
 
 impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
-    ConstCtOption<BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>>
+    ConstCtOption<SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>>
 {
     /// Returns the contained value, consuming the `self` value.
     ///
@@ -437,7 +437,7 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
     /// Panics if the value is none with a custom panic message provided by
     /// `msg`.
     #[inline]
-    pub const fn expect(self, msg: &str) -> BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS> {
+    pub const fn expect(self, msg: &str) -> SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS> {
         assert!(self.is_some.is_true_vartime(), "{}", msg);
         self.value
     }

src/macros.rs

@@ -15,10 +15,10 @@ macro_rules! nlimbs {
 /// We need to ensure that:
 ///
 /// ```text
-/// $bits <= (bernstein_yang_nlimbs($bits) * 62) - 64
+/// $bits <= (safegcd_nlimbs($bits) * 62) - 64
 /// ```
 // TODO(tarcieri): replace with `generic_const_exprs` (rust-lang/rust#76560) when stable
-macro_rules! bernstein_yang_nlimbs {
+macro_rules! safegcd_nlimbs {
     ($bits:expr) => {
         ($bits + 64).div_ceil(62)
     };

src/modular.rs

@@ -21,26 +21,26 @@ mod monty_form;
 mod reduction;
 
 mod add;
-pub(crate) mod bernstein_yang;
 mod div_by_2;
 mod mul;
 mod pow;
+pub(crate) mod safegcd;
 mod sub;
 
 #[cfg(feature = "alloc")]
 pub(crate) mod boxed_monty_form;
 
 pub use self::{
-    bernstein_yang::BernsteinYangInverter,
     const_monty_form::{inv::ConstMontyFormInverter, ConstMontyForm, ConstMontyParams},
     monty_form::{inv::MontyFormInverter, MontyForm, MontyParams},
     reduction::montgomery_reduction,
+    safegcd::SafeGcdInverter,
 };
 
 #[cfg(feature = "alloc")]
 pub use self::{
-    bernstein_yang::boxed::BoxedBernsteinYangInverter,
     boxed_monty_form::{BoxedMontyForm, BoxedMontyParams},
+    safegcd::boxed::BoxedSafeGcdInverter,
 };
 
 /// A generalization for numbers kept in optimized representations (e.g. Montgomery)

src/modular/boxed_monty_form/inv.rs

@@ -2,7 +2,7 @@
 
 use super::{BoxedMontyForm, BoxedMontyParams};
 use crate::{
-    modular::BoxedBernsteinYangInverter, Invert, Inverter, PrecomputeInverter,
+    modular::BoxedSafeGcdInverter, Invert, Inverter, PrecomputeInverter,
     PrecomputeInverterWithAdjuster,
 };
 use alloc::sync::Arc;
@@ -40,7 +40,7 @@ impl PrecomputeInverter for BoxedMontyParams {
 /// Bernstein-Yang inverter which inverts [`DynResidue`] types.
 pub struct BoxedMontyFormInverter {
     /// Precomputed Bernstein-Yang inverter.
-    inverter: BoxedBernsteinYangInverter,
+    inverter: BoxedSafeGcdInverter,
 
     /// Residue parameters.
     params: Arc<BoxedMontyParams>,

src/modular/const_monty_form.rs

@@ -8,7 +8,7 @@ mod pow;
 mod sub;
 
 use self::inv::ConstMontyFormInverter;
-use super::{div_by_2::div_by_2, reduction::montgomery_reduction, BernsteinYangInverter, Retrieve};
+use super::{div_by_2::div_by_2, reduction::montgomery_reduction, Retrieve, SafeGcdInverter};
 use crate::{ConstZero, Limb, Odd, PrecomputeInverter, Uint};
 use core::{fmt::Debug, marker::PhantomData};
 use subtle::{Choice, ConditionallySelectable, ConstantTimeEq};
@@ -56,7 +56,7 @@ pub trait ConstMontyParams<const LIMBS: usize>:
     fn precompute_inverter<const UNSAT_LIMBS: usize>() -> ConstMontyFormInverter<Self, LIMBS>
     where
         Odd<Uint<LIMBS>>: PrecomputeInverter<
-            Inverter = BernsteinYangInverter<LIMBS, UNSAT_LIMBS>,
+            Inverter = SafeGcdInverter<LIMBS, UNSAT_LIMBS>,
             Output = Uint<LIMBS>,
         >,
     {

src/modular/const_monty_form/inv.rs

@@ -2,7 +2,7 @@
 
 use super::{ConstMontyForm, ConstMontyParams};
 use crate::{
-    modular::BernsteinYangInverter, ConstCtOption, Invert, Inverter, Odd, PrecomputeInverter, Uint,
+    modular::SafeGcdInverter, ConstCtOption, Invert, Inverter, Odd, PrecomputeInverter, Uint,
 };
 use core::{fmt, marker::PhantomData};
 use subtle::CtOption;
@@ -11,7 +11,7 @@ impl<MOD: ConstMontyParams<SAT_LIMBS>, const SAT_LIMBS: usize, const UNSAT_LIMBS
     ConstMontyForm<MOD, SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {
@@ -39,7 +39,7 @@ impl<MOD: ConstMontyParams<SAT_LIMBS>, const SAT_LIMBS: usize, const UNSAT_LIMBS
     for ConstMontyForm<MOD, SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {
@@ -62,13 +62,13 @@ impl<MOD: ConstMontyParams<SAT_LIMBS>, const SAT_LIMBS: usize, const UNSAT_LIMBS
     ConstMontyFormInverter<MOD, SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {
     /// Create a new [`ConstMontyFormInverter`] for the given [`ConstMontyParams`].
     pub const fn new() -> Self {
-        let inverter = BernsteinYangInverter::new(&MOD::MODULUS, &MOD::R2);
+        let inverter = SafeGcdInverter::new(&MOD::MODULUS, &MOD::R2);
 
         Self {
             inverter,
@@ -96,7 +96,7 @@ impl<MOD: ConstMontyParams<SAT_LIMBS>, const SAT_LIMBS: usize, const UNSAT_LIMBS
     for ConstMontyFormInverter<MOD, SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {
@@ -111,7 +111,7 @@ impl<MOD: ConstMontyParams<SAT_LIMBS>, const SAT_LIMBS: usize, const UNSAT_LIMBS
     for ConstMontyFormInverter<MOD, SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {

src/modular/monty_form/inv.rs

@@ -2,16 +2,16 @@
 
 use super::{MontyForm, MontyParams};
 use crate::{
-    modular::BernsteinYangInverter, traits::Invert, ConstCtOption, Inverter, Odd,
-    PrecomputeInverter, PrecomputeInverterWithAdjuster, Uint,
+    modular::SafeGcdInverter, traits::Invert, ConstCtOption, Inverter, Odd, PrecomputeInverter,
+    PrecomputeInverterWithAdjuster, Uint,
 };
 use core::fmt;
 use subtle::CtOption;
 
 impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> MontyForm<SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {
@@ -40,7 +40,7 @@ where
 impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> Invert for MontyForm<SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {
@@ -97,7 +97,7 @@ where
 impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> fmt::Debug for MontyFormInverter<SAT_LIMBS>
 where
     Odd<Uint<SAT_LIMBS>>: PrecomputeInverter<
-        Inverter = BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>,
+        Inverter = SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>,
         Output = Uint<SAT_LIMBS>,
     >,
 {

src/modular/bernstein_yang.rs renamed to src/modular/safegcd.rs

@@ -1,7 +1,8 @@
-//! Implementation of Bernstein-Yang modular inversion and GCD algorithm as described in:
-//! <https://eprint.iacr.org/2019/266>.
+//! Implementation of Bernstein-Yang modular inversion and GCD algorithm (a.k.a. safegcd)
+//! as described in: <https://eprint.iacr.org/2019/266>.
 //!
 //! Adapted from the Apache 2.0+MIT licensed implementation originally from:
+//! <https://github.com/taikoxyz/halo2curves/pull/2>
 //! <https://github.com/privacy-scaling-explorations/halo2curves/pull/83>
 //!
 //! Copyright (c) 2023 Privacy Scaling Explorations Team
@@ -44,7 +45,7 @@ use subtle::CtOption;
 /// - P. Wuille, "The safegcd implementation in libsecp256k1 explained",
 /// <https://github.com/bitcoin-core/secp256k1/blob/master/doc/safegcd_implementation.md>
 #[derive(Clone, Debug)]
-pub struct BernsteinYangInverter<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> {
+pub struct SafeGcdInverter<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> {
     /// Modulus
     pub(super) modulus: UnsatInt<UNSAT_LIMBS>,
 
@@ -58,9 +59,7 @@ pub struct BernsteinYangInverter<const SAT_LIMBS: usize, const UNSAT_LIMBS: usiz
 /// Type of the Bernstein-Yang transition matrix multiplied by 2^62
 type Matrix = [[i64; 2]; 2];
 
-impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
-    BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>
-{
+impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS> {
     /// Creates the inverter for specified modulus and adjusting parameter.
     ///
     /// Modulus must be odd. Returns `None` if it is not.
@@ -135,7 +134,7 @@ impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize>
 }
 
 impl<const SAT_LIMBS: usize, const UNSAT_LIMBS: usize> Inverter
-    for BernsteinYangInverter<SAT_LIMBS, UNSAT_LIMBS>
+    for SafeGcdInverter<SAT_LIMBS, UNSAT_LIMBS>
 {
     type Output = Uint<SAT_LIMBS>;
 
@@ -386,7 +385,7 @@ impl<const LIMBS: usize> UnsatInt<LIMBS> {
     /// The ordering of the chunks in these arrays is little-endian.
     #[allow(trivial_numeric_casts)]
     pub const fn from_uint<const SAT_LIMBS: usize>(input: &Uint<SAT_LIMBS>) -> Self {
-        if LIMBS != bernstein_yang_nlimbs!(SAT_LIMBS * Limb::BITS as usize) {
+        if LIMBS != safegcd_nlimbs!(SAT_LIMBS * Limb::BITS as usize) {
             panic!("incorrect number of limbs");
         }
 
@@ -410,7 +409,7 @@ impl<const LIMBS: usize> UnsatInt<LIMBS> {
             "can't convert negative number to Uint"
         );
 
-        if LIMBS != bernstein_yang_nlimbs!(SAT_LIMBS * Limb::BITS as usize) {
+        if LIMBS != safegcd_nlimbs!(SAT_LIMBS * Limb::BITS as usize) {
             panic!("incorrect number of limbs");
         }
 
@@ -564,7 +563,7 @@ mod tests {
 
     type UnsatInt = super::UnsatInt<4>;
 
-    impl<const LIMBS: usize> PartialEq for crate::modular::bernstein_yang::UnsatInt<LIMBS> {
+    impl<const LIMBS: usize> PartialEq for crate::modular::safegcd::UnsatInt<LIMBS> {
         fn eq(&self, other: &Self) -> bool {
             self.eq(other).to_bool_vartime()
         }

src/modular/bernstein_yang/boxed.rs renamed to src/modular/safegcd/boxed.rs

@@ -1,5 +1,5 @@
-//! Implementation of Bernstein-Yang modular inversion and GCD algorithm as described in:
-//! <https://eprint.iacr.org/2019/266>.
+//! Implementation of Bernstein-Yang modular inversion and GCD algorithm (a.k.a. safegcd)
+//! as described in: <https://eprint.iacr.org/2019/266>.
 //!
 //! See parent module for more information.
 
@@ -14,9 +14,9 @@ use subtle::{Choice, ConditionallySelectable, ConstantTimeEq, ConstantTimeGreate
 
 /// Modular multiplicative inverter based on the Bernstein-Yang method.
 ///
-/// See [`super::BernsteinYangInverter`] for more information.
+/// See [`super::SafeGcdInverter`] for more information.
 #[derive(Clone, Debug)]
-pub struct BoxedBernsteinYangInverter {
+pub struct BoxedSafeGcdInverter {
     /// Modulus
     pub(crate) modulus: BoxedUnsatInt,
 
@@ -27,7 +27,7 @@ pub struct BoxedBernsteinYangInverter {
     inverse: i64,
 }
 
-impl BoxedBernsteinYangInverter {
+impl BoxedSafeGcdInverter {
     /// Creates the inverter for specified modulus and adjusting parameter.
     ///
     /// Modulus must be odd. Returns `None` if it is not.
@@ -50,7 +50,7 @@ impl BoxedBernsteinYangInverter {
     }
 }
 
-impl Inverter for BoxedBernsteinYangInverter {
+impl Inverter for BoxedSafeGcdInverter {
     type Output = BoxedUint;
 
     fn invert(&self, value: &BoxedUint) -> CtOption<Self::Output> {
@@ -78,7 +78,7 @@ fn unsat_nlimbs_for_sat_nlimbs(saturated_nlimbs: usize) -> usize {
         saturated_nlimbs
     };
 
-    bernstein_yang_nlimbs!(saturated_nlimbs * Limb::BITS as usize)
+    safegcd_nlimbs!(saturated_nlimbs * Limb::BITS as usize)
 }
 
 /// Returns the greatest common divisor (GCD) of the two given numbers.
@@ -300,10 +300,7 @@ impl BoxedUnsatInt {
             bits_precision = 64;
         }
 
-        debug_assert_eq!(
-            self.nlimbs(),
-            bernstein_yang_nlimbs!(bits_precision as usize)
-        );
+        debug_assert_eq!(self.nlimbs(), safegcd_nlimbs!(bits_precision as usize));
         assert!(
             !bool::from(self.is_negative()),
             "can't convert negative number to BoxedUint"
@@ -522,7 +519,7 @@ mod tests {
     use subtle::ConstantTimeEq;
 
     #[cfg(not(miri))]
-    use crate::modular::bernstein_yang::UnsatInt;
+    use crate::modular::safegcd::UnsatInt;
 
     impl PartialEq for BoxedUnsatInt {
         fn eq(&self, other: &Self) -> bool {
@@ -669,8 +666,8 @@ mod tests {
         #[test]
         #[cfg(not(miri))]
         fn boxed_unsatint_add(x in u256(), y in u256()) {
-            let x_ref = UnsatInt::<{ bernstein_yang_nlimbs!(256usize) }>::from_uint(&x);
-            let y_ref = UnsatInt::<{ bernstein_yang_nlimbs!(256usize) }>::from_uint(&y);
+            let x_ref = UnsatInt::<{ safegcd_nlimbs!(256usize) }>::from_uint(&x);
+            let y_ref = UnsatInt::<{ safegcd_nlimbs!(256usize) }>::from_uint(&y);
             let mut x_boxed = BoxedUnsatInt::from(&x.into());
             let y_boxed = BoxedUnsatInt::from(&y.into());
 
@@ -682,7 +679,7 @@ mod tests {
         #[test]
         #[cfg(not(miri))]
         fn boxed_unsatint_mul(x in u256(), y in any::<i64>()) {
-            let x_ref = UnsatInt::<{ bernstein_yang_nlimbs!(256usize) }>::from_uint(&x);
+            let x_ref = UnsatInt::<{ safegcd_nlimbs!(256usize) }>::from_uint(&x);
             let x_boxed = BoxedUnsatInt::from(&x.into());
 
             let expected = x_ref.mul(y);
@@ -693,7 +690,7 @@ mod tests {
         #[test]
         #[cfg(not(miri))]
         fn boxed_unsatint_neg(x in u256()) {
-            let x_ref = UnsatInt::<{ bernstein_yang_nlimbs!(256usize) }>::from_uint(&x);
+            let x_ref = UnsatInt::<{ safegcd_nlimbs!(256usize) }>::from_uint(&x);
             let x_boxed = BoxedUnsatInt::from(&x.into());
 
             let expected = x_ref.neg();
@@ -704,7 +701,7 @@ mod tests {
         #[test]
         #[cfg(not(miri))]
         fn boxed_unsatint_shr(x in u256()) {
-            let x_ref = UnsatInt::<{ bernstein_yang_nlimbs!(256usize) }>::from_uint(&x);
+            let x_ref = UnsatInt::<{ safegcd_nlimbs!(256usize) }>::from_uint(&x);
             let mut x_boxed = BoxedUnsatInt::from(&x.into());
             x_boxed.shr_assign();
 
@@ -716,7 +713,7 @@ mod tests {
                 #[cfg(not(miri))]
 
         fn boxed_unsatint_is_negative(x in u256()) {
-            let x_ref = UnsatInt::<{ bernstein_yang_nlimbs!(256usize) }>::from_uint(&x);
+            let x_ref = UnsatInt::<{ safegcd_nlimbs!(256usize) }>::from_uint(&x);
             let x_boxed = BoxedUnsatInt::from(&x.into());
             assert_eq!(x_ref.is_negative().to_bool_vartime(), bool::from(x_boxed.is_negative()));
         }
@@ -725,7 +722,7 @@ mod tests {
                 #[cfg(not(miri))]
 
         fn boxed_unsatint_is_minus_one(x in u256()) {
-            let x_ref = UnsatInt::<{ bernstein_yang_nlimbs!(256usize) }>::from_uint(&x);
+            let x_ref = UnsatInt::<{ safegcd_nlimbs!(256usize) }>::from_uint(&x);
             let x_boxed = BoxedUnsatInt::from(&x.into());
             assert!(bool::from(x_boxed.is_minus_one().ct_eq(&x_ref.eq(&UnsatInt::MINUS_ONE).into())));
         }