Implement BLS12-381 point negation (#1456)

### What

Split out point negation part
([0945897](0945897))
from #1449, and address
review comments on this part.

### Why

Improves usability of the BLS12-381 features in a Groth16 verifier
application ([example
contract](stellar/soroban-examples#350))

- `Neg` is an common operation, needed for using the proof parameter as
pairing input, and is cheap and simple enough to be implemented as an
sdk function.

### Known limitations

[TODO or N/A]

Author: jayz22

soroban-sdk/src/bytes.rs

@@ -104,7 +104,7 @@ macro_rules! bytesn {
 
 #[macro_export]
 macro_rules! impl_bytesn_repr {
-    ($elem: ident, $size: literal) => {
+    ($elem: ident, $size: expr) => {
         impl $elem {
             pub fn from_bytes(bytes: BytesN<$size>) -> Self {
                 Self(bytes)

soroban-sdk/src/crypto/bls12_381.rs

@@ -7,15 +7,79 @@ use crate::{
 use core::{
     cmp::Ordering,
     fmt::Debug,
-    ops::{Add, Mul, Sub},
+    ops::{Add, Mul, Neg, Sub},
 };
 
+pub const FP_SERIALIZED_SIZE: usize = 48; // Size in bytes of a serialized Fp element in BLS12-381. The field modulus is 381 bits, requiring 48 bytes (384 bits) with 3 bits reserved for flags.
+pub const FP2_SERIALIZED_SIZE: usize = FP_SERIALIZED_SIZE * 2;
+pub const G1_SERIALIZED_SIZE: usize = FP_SERIALIZED_SIZE * 2;
+pub const G2_SERIALIZED_SIZE: usize = FP2_SERIALIZED_SIZE * 2;
+
 /// Bls12_381 provides access to curve and field arithmetics on the BLS12-381
 /// curve.
 pub struct Bls12_381 {
     env: Env,
 }
 
+// This routine was copied with slight modification from the arkworks library:
+// https://github.com/arkworks-rs/algebra/blob/bf1c9b22b30325ef4df4f701dedcb6dea904c587/ff/src/biginteger/arithmetic.rs#L66-L79
+fn sbb_for_sub_with_borrow(a: &mut u64, b: u64, borrow: u8) -> u8 {
+    let tmp = (1u128 << 64) + u128::from(*a) - u128::from(b) - u128::from(borrow);
+    // casting is safe here because `tmp` can only exceed u64 by a single
+    // (borrow) bit, which we capture in the next line.
+    *a = tmp as u64;
+    u8::from(tmp >> 64 == 0)
+}
+
+#[derive(Debug)]
+pub(crate) struct BigInt<const N: usize>(pub [u64; N]);
+
+impl<const N: usize> BigInt<N> {
+    pub fn sub_with_borrow(&mut self, other: &Self) -> bool {
+        let mut borrow = 0;
+        for i in 0..N {
+            borrow = sbb_for_sub_with_borrow(&mut self.0[i], other.0[i], borrow);
+        }
+        borrow != 0
+    }
+
+    pub fn copy_into_array<const M: usize>(&self, slice: &mut [u8; M]) {
+        const {
+            if M != N * 8 {
+                panic!("BigInt::copy_into_array with mismatched array length")
+            }
+        }
+
+        for i in 0..N {
+            let limb_bytes = self.0[N - 1 - i].to_be_bytes();
+            slice[i * 8..(i + 1) * 8].copy_from_slice(&limb_bytes);
+        }
+    }
+
+    pub fn is_zero(&self) -> bool {
+        self.0 == [0; N]
+    }
+}
+
+impl<const N: usize, const M: usize> From<&BytesN<M>> for BigInt<N> {
+    fn from(bytes: &BytesN<M>) -> Self {
+        if M != N * 8 {
+            panic!("BytesN::Into<BigInt> - length mismatch")
+        }
+
+        let array = bytes.to_array();
+        let mut limbs = [0u64; N];
+        for i in 0..N {
+            let start = i * 8;
+            let end = start + 8;
+            let mut chunk = [0u8; 8];
+            chunk.copy_from_slice(&array[start..end]);
+            limbs[N - 1 - i] = u64::from_be_bytes(chunk);
+        }
+        BigInt(limbs)
+    }
+}
+
 /// `G1Affine` is a point in the G1 group (subgroup defined over the base field
 ///  `Fq`) of the BLS12-381 elliptic curve
 ///
@@ -44,7 +108,7 @@ pub struct Bls12_381 {
 /// ```
 #[derive(Clone)]
 #[repr(transparent)]
-pub struct G1Affine(BytesN<96>);
+pub struct G1Affine(BytesN<G1_SERIALIZED_SIZE>);
 
 /// `G2Affine` is a point in the G2 group (subgroup defined over the quadratic
 /// extension field `Fq2`) of the BLS12-381 elliptic curve
@@ -64,7 +128,7 @@ pub struct G1Affine(BytesN<96>);
 ///   - sort_flag (bit 2): Must always be unset (0).
 #[derive(Clone)]
 #[repr(transparent)]
-pub struct G2Affine(BytesN<192>);
+pub struct G2Affine(BytesN<G2_SERIALIZED_SIZE>);
 
 /// `Fp` represents an element of the base field `Fq` of the BLS12-381 elliptic
 /// curve
@@ -74,7 +138,7 @@ pub struct G2Affine(BytesN<192>);
 ///   field `Fp`. The value is serialized as a big-endian integer.
 #[derive(Clone)]
 #[repr(transparent)]
-pub struct Fp(BytesN<48>);
+pub struct Fp(BytesN<FP_SERIALIZED_SIZE>);
 
 /// `Fp2` represents an element of the quadratic extension field `Fq2` of the
 /// BLS12-381 elliptic curve
@@ -86,7 +150,7 @@ pub struct Fp(BytesN<48>);
 ///   and imaginary components).
 #[derive(Clone)]
 #[repr(transparent)]
-pub struct Fp2(BytesN<96>);
+pub struct Fp2(BytesN<FP2_SERIALIZED_SIZE>);
 
 /// `Fr` represents an element in the BLS12-381 scalar field, which is a prime
 /// field of order `r` (the order of the G1 and G2 groups). The struct is
@@ -96,10 +160,88 @@ pub struct Fp2(BytesN<96>);
 #[repr(transparent)]
 pub struct Fr(U256);
 
-impl_bytesn_repr!(G1Affine, 96);
-impl_bytesn_repr!(G2Affine, 192);
-impl_bytesn_repr!(Fp, 48);
-impl_bytesn_repr!(Fp2, 96);
+impl_bytesn_repr!(G1Affine, G1_SERIALIZED_SIZE);
+impl_bytesn_repr!(G2Affine, G2_SERIALIZED_SIZE);
+impl_bytesn_repr!(Fp, FP_SERIALIZED_SIZE);
+impl_bytesn_repr!(Fp2, FP2_SERIALIZED_SIZE);
+
+impl Fp {
+    pub fn env(&self) -> &Env {
+        self.0.env()
+    }
+
+    // `Fp` represents an element in the base field of the BLS12-381 elliptic curve.
+    // For an element a ∈ Fp, its negation `-a` is defined as:
+    //   a + (-a) = 0 (mod p)
+    // where `p` is the field modulus, and to make a valid point coordinate on the
+    // curve, `a` also must be within the field range (i.e., 0 ≤ a < p).
+    fn checked_neg(&self) -> Option<Fp> {
+        let fp_bigint: BigInt<6> = (&self.0).into();
+        if fp_bigint.is_zero() {
+            return Some(self.clone());
+        }
+
+        // BLS12-381 base field modulus
+        const BLS12_381_MODULUS: [u64; 6] = [
+            13402431016077863595,
+            2210141511517208575,
+            7435674573564081700,
+            7239337960414712511,
+            5412103778470702295,
+            1873798617647539866,
+        ];
+        let mut res = BigInt(BLS12_381_MODULUS);
+
+        // Compute modulus - value
+        let borrow = res.sub_with_borrow(&fp_bigint);
+        if borrow {
+            return None;
+        }
+
+        let mut bytes = [0u8; FP_SERIALIZED_SIZE];
+        res.copy_into_array(&mut bytes);
+        Some(Fp::from_array(self.env(), &bytes))
+    }
+
+    /// Maps to a `G1Affine` point via [simplified SWU
+    /// mapping](https://www.rfc-editor.org/rfc/rfc9380.html#name-simplified-swu-for-ab-0)
+    pub fn map_to_g1(&self) -> G1Affine {
+        self.env().crypto().bls12_381().map_fp_to_g1(self)
+    }
+}
+
+impl From<Fp> for BigInt<6> {
+    fn from(fp: Fp) -> Self {
+        let inner: Bytes = fp.0.into();
+        let mut limbs = [0u64; 6];
+        for i in 0..6u32 {
+            let start = i * 8;
+            let mut slice = [0u8; 8];
+            inner.slice(start..start + 8).copy_into_slice(&mut slice);
+            limbs[5 - i as usize] = u64::from_be_bytes(slice);
+        }
+        BigInt(limbs)
+    }
+}
+
+impl Neg for &Fp {
+    type Output = Fp;
+
+    fn neg(self) -> Self::Output {
+        match self.checked_neg() {
+            Some(v) => v,
+            None => sdk_panic!("invalid input - Fp is larger than the field modulus"),
+        }
+    }
+}
+
+impl Neg for Fp {
+    type Output = Fp;
+
+    fn neg(self) -> Self::Output {
+        (&self).neg()
+    }
+}
 
 impl G1Affine {
     pub fn env(&self) -> &Env {
@@ -131,6 +273,87 @@ impl Mul<Fr> for G1Affine {
     }
 }
 
+// G1Affine represents a point (X, Y) on the BLS12-381 curve where X, Y ∈ Fp
+// Negation of (X, Y) is defined as (X, -Y)
+impl Neg for &G1Affine {
+    type Output = G1Affine;
+
+    fn neg(self) -> Self::Output {
+        let mut inner: Bytes = (&self.0).into();
+        let y = Fp::try_from_val(
+            inner.env(),
+            inner.slice(FP_SERIALIZED_SIZE as u32..).as_val(),
+        )
+        .unwrap_optimized();
+        let neg_y = -y;
+        inner.copy_from_slice(FP_SERIALIZED_SIZE as u32, &neg_y.to_array());
+        G1Affine::from_bytes(BytesN::try_from_val(inner.env(), inner.as_val()).unwrap_optimized())
+    }
+}
+
+impl Neg for G1Affine {
+    type Output = G1Affine;
+
+    fn neg(self) -> Self::Output {
+        (&self).neg()
+    }
+}
+
+impl Fp2 {
+    pub fn env(&self) -> &Env {
+        self.0.env()
+    }
+
+    // An Fp2 element is represented as c0 + c1 * X, where:
+    // - c0, c1 are base field elements (Fp)
+    // - X is the quadratic non-residue used to construct the field extension
+    // The negation of c0 + c1 * X is (-c0) + (-c1) * X.
+    fn checked_neg(&self) -> Option<Fp2> {
+        let mut inner = self.to_array();
+        let mut slice0 = [0; FP_SERIALIZED_SIZE];
+        let mut slice1 = [0; FP_SERIALIZED_SIZE];
+        slice0.copy_from_slice(&inner[0..FP_SERIALIZED_SIZE]);
+        slice1.copy_from_slice(&inner[FP_SERIALIZED_SIZE..FP2_SERIALIZED_SIZE]);
+
+        // Convert both components to Fp and negate them
+        let c0 = Fp::from_array(self.env(), &slice0);
+        let c1 = Fp::from_array(self.env(), &slice1);
+
+        // If either component's negation fails, the whole operation fails
+        let neg_c0 = c0.checked_neg()?;
+        let neg_c1 = c1.checked_neg()?;
+
+        // Reconstruct the Fp2 element from negated components
+        inner[0..FP_SERIALIZED_SIZE].copy_from_slice(&neg_c0.to_array());
+        inner[FP_SERIALIZED_SIZE..FP2_SERIALIZED_SIZE].copy_from_slice(&neg_c1.to_array());
+
+        Some(Fp2::from_array(self.env(), &inner))
+    }
+
+    pub fn map_to_g2(&self) -> G2Affine {
+        self.env().crypto().bls12_381().map_fp2_to_g2(self)
+    }
+}
+
+impl Neg for &Fp2 {
+    type Output = Fp2;
+
+    fn neg(self) -> Self::Output {
+        match self.checked_neg() {
+            Some(v) => v,
+            None => sdk_panic!("invalid input - Fp2 component is larger than the field modulus"),
+        }
+    }
+}
+
+impl Neg for Fp2 {
+    type Output = Fp2;
+
+    fn neg(self) -> Self::Output {
+        (&self).neg()
+    }
+}
+
 impl G2Affine {
     pub fn env(&self) -> &Env {
         self.0.env()
@@ -161,23 +384,29 @@ impl Mul<Fr> for G2Affine {
     }
 }
 
-impl Fp {
-    pub fn env(&self) -> &Env {
-        self.0.env()
-    }
+// G2Affine represents a point (X, Y) on the BLS12-381 quadratic extension curve where X, Y ∈ Fp2
+// Negation of (X, Y) is defined as (X, -Y)
+impl Neg for &G2Affine {
+    type Output = G2Affine;
 
-    pub fn map_to_g1(&self) -> G1Affine {
-        self.env().crypto().bls12_381().map_fp_to_g1(self)
+    fn neg(self) -> Self::Output {
+        let mut inner: Bytes = (&self.0).into();
+        let y = Fp2::try_from_val(
+            inner.env(),
+            inner.slice(FP2_SERIALIZED_SIZE as u32..).as_val(),
+        )
+        .unwrap_optimized();
+        let neg_y = -y;
+        inner.copy_from_slice(FP2_SERIALIZED_SIZE as u32, &neg_y.to_array());
+        G2Affine::from_bytes(BytesN::try_from_val(inner.env(), inner.as_val()).unwrap_optimized())
     }
 }
 
-impl Fp2 {
-    pub fn env(&self) -> &Env {
-        self.0.env()
-    }
+impl Neg for G2Affine {
+    type Output = G2Affine;
 
-    pub fn map_to_g2(&self) -> G2Affine {
-        self.env().crypto().bls12_381().map_fp2_to_g2(self)
+    fn neg(self) -> Self::Output {
+        (&self).neg()
     }
 }