Clean comments in gnark-crypto codebase (curves)

ecc/bls12-377/bls12-377.go

@@ -9,25 +9,28 @@ import (
 	"github.com/consensys/gnark-crypto/ecc/bls12-377/internal/fptower"
 )
 
-// E: y**2=x**3+1
-// Etwist: y**2 = x**3+u**-1
-// Tower: Fp->Fp2, u**2=-5 -> Fp12, v**6=u
-// Generator (BLS12 family): x=9586122913090633729
-// optimal Ate loop: trace(frob)-1=x
-// trace of pi: x+1
-// Fp: p=258664426012969094010652733694893533536393512754914660539884262666720468348340822774968888139573360124440321458177
-// Fr: r=8444461749428370424248824938781546531375899335154063827935233455917409239041 (x**4-x**2+1)
+// BLS12-377: A Barreto--Lynn--Scott curve of embedding degree k=12 with seed x₀=9586122913090633729
+// 𝔽r: r=8444461749428370424248824938781546531375899335154063827935233455917409239041 (x₀⁴-x₀²+1)
+// 𝔽p: p=258664426012969094010652733694893533536393512754914660539884262666720468348340822774968888139573360124440321458177 ((x₀-1)² ⋅ r(x₀)/3+x₀)
+// (E/𝔽p): Y²=X³+1
+// (Eₜ/𝔽p²): Y² = X³+1/u (D-type twist)
+// r ∣ #E(Fp) and r ∣ #Eₜ(𝔽p²)
+// Extension fields tower:
+//     𝔽p²[u] = 𝔽p/u²+5
+//     𝔽p⁶[v] = 𝔽p²/v³-u
+//     𝔽p¹²[w] = 𝔽p⁶/w²-v
+// optimal Ate loop size: x₀
 
 // ID bls377 ID
 const ID = ecc.BLS12_377
 
-// bCurveCoeff b coeff of the curve
+// bCurveCoeff b coeff of the curve Y²=X³+b
 var bCurveCoeff fp.Element
 
 // twist
 var twist fptower.E2
 
-// bTwistCurveCoeff b coeff of the twist (defined over Fp2) curve
+// bTwistCurveCoeff b coeff of the twist (defined over 𝔽p²) curve
 var bTwistCurveCoeff fptower.E2
 
 // generators of the r-torsion group, resp. in ker(pi-id), ker(Tr)
@@ -41,40 +44,40 @@ var g2GenAff G2Affine
 var g1Infinity G1Jac
 var g2Infinity G2Jac
 
-// optimal Ate loop counter (=trace-1 = x in BLS family)
+// optimal Ate loop counter
 var loopCounter [64]int8
 
 // Parameters useful for the GLV scalar multiplication. The third roots define the
-//  endomorphisms phi1 and phi2 for <G1Affine> and <G2Affine>. lambda is such that <r, phi-lambda> lies above
-// <r> in the ring Z[phi]. More concretely it's the associated eigenvalue
-// of phi1 (resp phi2) restricted to <G1Affine> (resp <G2Affine>)
-// cf https://www.cosic.esat.kuleuven.be/nessie/reports/phase2/GLV.pdf
+// endomorphisms ϕ₁ and ϕ₂ for <G1Affine> and <G2Affine>. lambda is such that <r, ϕ-λ> lies above
+// <r> in the ring Z[ϕ]. More concretely it's the associated eigenvalue
+// of ϕ₁ (resp ϕ₂) restricted to <G1Affine> (resp <G2Affine>)
+// see https://www.cosic.esat.kuleuven.be/nessie/reports/phase2/GLV.pdf
 var thirdRootOneG1 fp.Element
 var thirdRootOneG2 fp.Element
 var lambdaGLV big.Int
 
 // glvBasis stores R-linearly independent vectors (a,b), (c,d)
-// in ker((u,v)->u+vlambda[r]), and their determinant
+// in ker((u,v) → u+vλ[r]), and their determinant
 var glvBasis ecc.Lattice
 
-// psi o pi o psi**-1, where psi:E->E' is the degree 6 iso defined over Fp12
+// ψ o π o ψ⁻¹, where ψ:E → E' is the degree 6 iso defined over 𝔽p¹²
 var endo struct {
 	u fptower.E2
 	v fptower.E2
 }
 
-// generator of the curve
+// seed x₀ of the curve
 var xGen big.Int
 
 // expose the tower -- github.com/consensys/gnark uses it in a gnark circuit
 
-// E2 is a degree two finite field extension of fp.Element
+// 𝔽p²
 type E2 = fptower.E2
 
-// E6 is a degree three finite field extension of fp2
+// 𝔽p⁶
 type E6 = fptower.E6
 
-// E12 is a degree two finite field extension of fp6
+// 𝔽p¹²
 type E12 = fptower.E12
 
 func init() {
@@ -98,23 +101,25 @@ func init() {
 	g1GenAff.FromJacobian(&g1Gen)
 	g2GenAff.FromJacobian(&g2Gen)
 
+	// (X,Y,Z) = (1,1,0)
 	g1Infinity.X.SetOne()
 	g1Infinity.Y.SetOne()
 	g2Infinity.X.SetOne()
 	g2Infinity.Y.SetOne()
 
 	thirdRootOneG1.SetString("80949648264912719408558363140637477264845294720710499478137287262712535938301461879813459410945")
 	thirdRootOneG2.Square(&thirdRootOneG1)
-	lambdaGLV.SetString("91893752504881257701523279626832445440", 10) //(x**2-1)
+	lambdaGLV.SetString("91893752504881257701523279626832445440", 10) //(x₀²-1)
 	_r := fr.Modulus()
 	ecc.PrecomputeLattice(_r, &lambdaGLV, &glvBasis)
 
 	endo.u.A0.SetString("80949648264912719408558363140637477264845294720710499478137287262712535938301461879813459410946")
 	endo.v.A0.SetString("216465761340224619389371505802605247630151569547285782856803747159100223055385581585702401816380679166954762214499")
 
-	// binary decomposition of xGen little endian
+	// binary decomposition of x₀ little endian
 	loopCounter = [64]int8{1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1}
 
+	// x₀
 	xGen.SetString("9586122913090633729", 10)
 
 }