From 84f17699be0faf823343193d9c0e14f443be5702 Mon Sep 17 00:00:00 2001
From: Dmitry Vagner <dmitry.vagner@gmail.com>
Date: Fri, 28 Apr 2023 21:57:10 -0700
Subject: [PATCH] comments

---
 .../kernel/asm/core/precompiles/snarkv.asm    |  4 +-
 .../curve/bn254/curve_arithmetic/pairing.asm  | 48 ++++++++++++-------
 2 files changed, 33 insertions(+), 19 deletions(-)

diff --git a/evm/src/cpu/kernel/asm/core/precompiles/snarkv.asm b/evm/src/cpu/kernel/asm/core/precompiles/snarkv.asm
index 26bad450..433186b5 100644
--- a/evm/src/cpu/kernel/asm/core/precompiles/snarkv.asm
+++ b/evm/src/cpu/kernel/asm/core/precompiles/snarkv.asm
@@ -63,7 +63,7 @@ loading_loop_contd5:
     %jump(mload_packing)
 loading_loop_contd6:
     // stack: y_re, y_im, x_re, x_im, y, x, i, k, kexit_info
-    SWAP1
+    SWAP1  // the EVM serializes the imaginary part first
     // stack: y_im, y_re, x_re, x_im, y, x, i, k, kexit_info
     DUP7
     // stack: i, y_im, y_re, x_re, x_im, y, x, i, k, kexit_info
@@ -76,7 +76,7 @@ loading_loop_contd6:
     %mul_const(6) %add_const(@SNARKV_INP)
     %add_const(4)
     %mstore_kernel_bn254_pairing
-    SWAP1
+    SWAP1  // the EVM serializes the imaginary part first
     // stack: x_im, x_re, y, x, i, k, kexit_info
     DUP5
     // stack: i, x_im, x_re, y, x, i, k, kexit_info
diff --git a/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/pairing.asm b/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/pairing.asm
index ef109661..4479b965 100644
--- a/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/pairing.asm
+++ b/evm/src/cpu/kernel/asm/curve/bn254/curve_arithmetic/pairing.asm
@@ -1,3 +1,15 @@
+/// The input to the pairing script is a list of points
+///     P_i = n_i*G: Curve, Q_i = m_i*H: TwistedCurve
+/// where G, H are the respective generators, such that
+///     sum_i n_i*m_i = 0
+/// and therefore, due to bilinearity of the pairing:
+///     prod_i e(P_i, Q_i) 
+///   = prod_i e(n_i G, m_i H) 
+///   = prod_i e(G,H)^{n_i * m_i} 
+///   = e(G,H)^{sum_i n_i * m_i}
+///   = e(G,H)^0
+///   = 1: Fp12 
+
 /// def bn254_pairing(pairs: List((Curve, TwistedCurve))) -> Bool:
 ///     
 ///     for P, Q in pairs:
@@ -6,7 +18,8 @@
 ///     
 ///     out = 1
 ///     for P, Q in pairs:
-///         out *= miller_loop(P, Q)
+///         if P != 0 and Q != 0:
+///             out *= miller_loop(P, Q)
 ///
 ///     result = bn254_final_exponent(out)
 ///     return result == unit_fp12
@@ -71,41 +84,42 @@ bn_pairing_invalid_input:
 bn254_pairing_start:
     // stack:      0, k, inp, out,                   retdest
     %stack (j, k, inp, out) -> (out, 1, k, inp, out, bn254_pairing_output_validation, out)
-    // stack: out, 1, k, inp, out, final_label, out, retdest
+    // stack: out, 1, k, inp, out, bn254_pairing_output_validation, out, retdest
     %mstore_kernel_bn254_pairing
-    // stack:         k, inp, out, final_label, out, retdest
+    // stack:         k, inp, out, bn254_pairing_output_validation, out, retdest
 
 bn254_pairing_loop:
-    // stack:               k, inp, out, final_label
+    // stack:               k, inp, out, bn254_pairing_output_validation, out, retdest
     DUP1
     ISZERO
-    // stack:         end?, k, inp, out, final_label
+    // stack:         end?, k, inp, out, bn254_pairing_output_validation, out, retdest
     %jumpi(bn254_final_exponent)
-    // stack:               k, inp, out, final_label
+    // stack:               k, inp, out, bn254_pairing_output_validation, out, retdest
     %sub_const(1)
-    // stack:           k=k-1, inp, out, final_label
+    // stack:           k=k-1, inp, out, bn254_pairing_output_validation, out, retdest
     %stack (k, inp) -> (k, inp, k, inp)
-    // stack:       k, inp, k, inp, out, final_label
+    // stack:       k, inp, k, inp, out, bn254_pairing_output_validation, out, retdest
     %mul_const(6)
     ADD
-    // stack:        inp_k, k, inp, out, final_label
+    // stack:        inp_k, k, inp, out, bn254_pairing_output_validation, out, retdest
     DUP1
     %load_fp254_6
-    // stack:  P, Q, inp_k, k, inp, out, final_label
+    // stack:  P, Q, inp_k, k, inp, out, bn254_pairing_output_validation, out, retdest
     %neutral_input
-    // stack: skip?, inp_k, k, inp, out, final_label
+    // stack: skip?, inp_k, k, inp, out, bn254_pairing_output_validation, out, retdest
     %jumpi(bn_skip_input)
-    // stack:        inp_k, k, inp, out, final_label
+    // stack:        inp_k, k, inp, out, bn254_pairing_output_validation, out, retdest
     %stack (inp_k, k, inp, out) -> (bn254_miller, inp_k, 0, mul_fp254_12, 0, out, out, bn254_pairing_loop, k, inp, out)
-    // stack: bn254_miller,       inp_k, 0, 
-    //        mul_fp254_12,       0, out, out, 
-    //        bn254_pairing_loop, k, inp, out, final_label
+    // stack: bn254_miller,                       inp_k, 0, 
+    //        mul_fp254_12,                    0, out, out, 
+    //        bn254_pairing_loop,              k, inp, out, 
+    //        bn254_pairing_output_validation, out, retdest
     JUMP
 
 bn_skip_input:
-    // stack: inp_k, k, inp, out, final_label
+    // stack: inp_k, k, inp, out, bn254_pairing_output_validation, out, retdest
     POP
-    // stack:        k, inp, out, final_label
+    // stack:        k, inp, out, bn254_pairing_output_validation, out, retdest
     %jump(bn254_pairing_loop)