From 56be7317e0a826a46a99cd07fae786116a629cac Mon Sep 17 00:00:00 2001
From: Dmitry Vagner <dmitry.vagner@gmail.com>
Date: Wed, 25 Jan 2023 16:20:24 +0700
Subject: [PATCH] comments

---
 evm/src/bn254_pairing.rs                      | 27 ++++++++++---------
 .../bn254/curve_arithmetic/constants.asm      | 13 +++++++--
 2 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/evm/src/bn254_pairing.rs b/evm/src/bn254_pairing.rs
index f67cb020..be6c1348 100644
--- a/evm/src/bn254_pairing.rs
+++ b/evm/src/bn254_pairing.rs
@@ -45,18 +45,6 @@ pub fn tate(p: Curve, q: TwistedCurve) -> Fp12 {
 }
 
 pub fn miller_loop(p: Curve, q: TwistedCurve) -> Fp12 {
-    const EXP: [usize; 253] = [
-        1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 1, 0, 1,
-        1, 1, 0, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0,
-        1, 1, 0, 1, 1, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0, 1, 1, 0,
-        1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 1, 0,
-        1, 1, 1, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 0, 0, 0,
-        1, 0, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 0, 0,
-        0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0,
-        1, 0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 1, 1, 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,
-    ];
-
     let mut o = p;
     let mut acc = UNIT_FP12;
     let mut line;
@@ -87,6 +75,8 @@ pub fn cord(p1: Curve, p2: Curve, q: TwistedCurve) -> Fp12 {
     sparse_embed(p1.y * p2.x - p2.y * p1.x, q.x.scale(cx), q.y.scale(cy))
 }
 
+/// The tangent and cord functions output sparse Fp12 elements.
+/// This map embeds the nonzero coefficients into an Fp12.
 pub fn sparse_embed(g000: Fp, g01: Fp2, g11: Fp2) -> Fp12 {
     let g0 = Fp6 {
         t0: Fp2 {
@@ -194,6 +184,19 @@ fn get_custom_powers(f: Fp12) -> (Fp12, Fp12, Fp12) {
     (y2, y4 * y2 * y2 * y0_inv, y0_inv)
 }
 
+
+const EXP: [usize; 253] = [
+    1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0, 0, 1, 0, 1,
+    1, 1, 0, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0,
+    1, 1, 0, 1, 1, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1, 0, 1, 1, 0,
+    1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 1, 0,
+    1, 1, 1, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1, 1, 1, 0, 1, 0, 0, 0, 0,
+    1, 0, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 0, 0,
+    0, 1, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0,
+    1, 0, 1, 1, 0, 0, 1, 0, 0, 1, 1, 1, 1, 1, 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,
+];
+
 // The folowing constants are defined above get_custom_powers
 
 const EXPS4: [(usize, usize, usize); 64] = [
diff --git a/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/constants.asm b/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/constants.asm
index 93878b57..ba0631fd 100644
--- a/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/constants.asm
+++ b/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/constants.asm
@@ -1,10 +1,10 @@
-/// the following is defined by
+/// miller_data is defined by
 /// (1) taking the binary expansion of N254, the order of the elliptic curve group
 /// (2) popping the first and last elements, then appending a 0:
 ///     exp = bin(N254)[1:-1] + [0]
 /// (3) counting the lengths of runs of 1s then 0s in exp, e.g.
 ///     if exp = 1100010011110, then EXP = [(2,3), (1,2), (4,1)]
-/// (4) encoding each pair (n,m) as 0xnm:
+/// (4) byte encoding each pair (n,m) as follows:
 ///     miller_data = [(0x20)n + m for (n,m) in EXP]
 
 global miller_data:
@@ -23,6 +23,15 @@ global miller_data:
     BYTES 0x62, 0x22, 0x23, 0x42
     BYTES 0x25
 
+
+/// final_exp first computes y^a4, y^a2, y^a0
+/// representing a4, a2, a0 in *little endian* binary, define
+///     EXPS4 = [(a4[i], a2[i], a0[i]) for i in       0..len(a4)]
+///     EXPS2 = [       (a2[i], a0[i]) for i in len(a4)..len(a2)]
+///     EXPS0 = [               a0[i]  for i in len(a2)..len(a0)]
+/// power_data_n is simply a reverse-order byte encoding of EXPSn
+///     where (i,j,k) is sent to (0b100)i + (0b10)j + k
+
 global power_data_4:
     BYTES 111, 010, 011, 111
     BYTES 110, 101, 001, 100