feat: add from_be_bytes_mod_order to facilitate hash_to_field implementation

Author: gilcu3

src/scalar.rs

@@ -569,6 +569,25 @@ impl Scalar {
         Self::from_bytes_le(&le_bytes)
     }
 
+    /// Interprets `bytes` as a big-endian integer of any length and reduces it modulo the
+    /// group order.
+    pub fn from_be_bytes_mod_order(bytes: &[u8]) -> Self {
+        // Memory safety: on length 0, `blst_scalar_from_be_bytes` reads 32 bytes past `bytes`
+        // and underflows its digit count.
+        if bytes.is_empty() {
+            return Self::ZERO;
+        }
+
+        let mut raw = blst_scalar::default();
+        // This step does the modular reduction
+        unsafe { blst_scalar_from_be_bytes(&mut raw, bytes.as_ptr(), bytes.len()) };
+
+        let mut out = blst_fr::default();
+        unsafe { blst_fr_from_scalar(&mut out, &raw) };
+
+        Scalar(out)
+    }
+
     /// Converts an element of `Scalar` into a byte representation in
     /// little-endian byte order.
     #[inline]
@@ -1895,4 +1914,30 @@ mod tests {
         }
         assert_eq!(0, yep_bad.len());
     }
+
+    /// Vectors from `bls12_381`'s `map_scalar`. These pin the endianness; blst covers the
+    /// reduction itself.
+    #[test]
+    fn test_from_be_bytes_mod_order() {
+        let vectors: &[(&[u8], &str)] = &[
+            (
+                b"aaaaaabbbbbbccccccddddddeeeeeeffffffgggggghhhhhh",
+                "Scalar(0x2228450bf55d8fe62395161bd3677ff6fc28e45b89bc87e02a818eda11a8c5da)",
+            ),
+            (
+                b"111111222222333333444444555555666666777777888888",
+                "Scalar(0x4aa543cbd2f0c8f37f8a375ce2e383eb343e7e3405f61e438b0a15fb8899d1ae)",
+            ),
+        ];
+
+        for (okm, expected) in vectors {
+            assert_eq!(
+                &format!("{:?}", Scalar::from_be_bytes_mod_order(okm)),
+                expected
+            );
+        }
+
+        // The empty-input guard is ours: blst would read out of bounds here.
+        assert_eq!(Scalar::from_be_bytes_mod_order(&[]), Scalar::ZERO);
+    }
 }