From a64e42463ab73ceb52a416cfe9cc47abe374b6b8 Mon Sep 17 00:00:00 2001
From: Daniel Liu <liudaniel@qq.com>
Date: Fri, 29 Nov 2024 16:08:31 +0800
Subject: [PATCH] crypto/bn256: refine comments according to #19577, #21595,
 and #21836 (#21847)

---
 crypto/bn256/cloudflare/bn256.go | 9 +++++++--
 crypto/bn256/google/bn256.go     | 5 +++--
 crypto/bn256/google/constants.go | 2 ++
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/crypto/bn256/cloudflare/bn256.go b/crypto/bn256/cloudflare/bn256.go
index a6dd972ba8b2..4f607af2ad35 100644
--- a/crypto/bn256/cloudflare/bn256.go
+++ b/crypto/bn256/cloudflare/bn256.go
@@ -9,8 +9,13 @@
 //
 // This package specifically implements the Optimal Ate pairing over a 256-bit
 // Barreto-Naehrig curve as described in
-// http://cryptojedi.org/papers/dclxvi-20100714.pdf. Its output is compatible
-// with the implementation described in that paper.
+// http://cryptojedi.org/papers/dclxvi-20100714.pdf. Its output is not
+// compatible with the implementation described in that paper, as different
+// parameters are chosen.
+//
+// (This package previously claimed to operate at a 128-bit security level.
+// However, recent improvements in attacks mean that is no longer true. See
+// https://moderncrypto.org/mail-archive/curves/2016/000740.html.)
 package bn256
 
 import (
diff --git a/crypto/bn256/google/bn256.go b/crypto/bn256/google/bn256.go
index e0402e51f0e2..0a9d5cd35dce 100644
--- a/crypto/bn256/google/bn256.go
+++ b/crypto/bn256/google/bn256.go
@@ -12,8 +12,9 @@
 //
 // This package specifically implements the Optimal Ate pairing over a 256-bit
 // Barreto-Naehrig curve as described in
-// http://cryptojedi.org/papers/dclxvi-20100714.pdf. Its output is compatible
-// with the implementation described in that paper.
+// http://cryptojedi.org/papers/dclxvi-20100714.pdf. Its output is not
+// compatible with the implementation described in that paper, as different
+// parameters are chosen.
 //
 // (This package previously claimed to operate at a 128-bit security level.
 // However, recent improvements in attacks mean that is no longer true. See
diff --git a/crypto/bn256/google/constants.go b/crypto/bn256/google/constants.go
index 0db432c9cfe1..2990bd951282 100644
--- a/crypto/bn256/google/constants.go
+++ b/crypto/bn256/google/constants.go
@@ -20,7 +20,9 @@ var u = bigFromBase10("4965661367192848881")
 var P = bigFromBase10("21888242871839275222246405745257275088696311157297823662689037894645226208583")
 
 // Order is the number of elements in both G₁ and G₂: 36u⁴+36u³+18u²+6u+1.
+// Needs to be highly 2-adic for efficient SNARK key and proof generation.
 // Order - 1 = 2^28 * 3^2 * 13 * 29 * 983 * 11003 * 237073 * 405928799 * 1670836401704629 * 13818364434197438864469338081.
+// Refer to https://eprint.iacr.org/2013/879.pdf and https://eprint.iacr.org/2013/507.pdf for more information on these parameters.
 var Order = bigFromBase10("21888242871839275222246405745257275088548364400416034343698204186575808495617")
 
 // xiToPMinus1Over6 is ξ^((p-1)/6) where ξ = i+9.