From 964032e5c3f180afe35e4dbd7c9e431a1fb9da99 Mon Sep 17 00:00:00 2001
From: Ignasirv <ignasirv@hotmail.com>
Date: Wed, 9 Nov 2022 14:15:37 +0100
Subject: [PATCH] Comment flow crypto opcodes group

---
 main/opcodes/crypto.zkasm         | 65 +++++++++++++++++++++++--------
 main/opcodes/storage-memory.zkasm |  2 +-
 2 files changed, 50 insertions(+), 17 deletions(-)

diff --git a/main/opcodes/crypto.zkasm b/main/opcodes/crypto.zkasm
index 167870c8..1c230b70 100644
--- a/main/opcodes/crypto.zkasm
+++ b/main/opcodes/crypto.zkasm
@@ -1,6 +1,18 @@
-
+/**
+ * @link [https://www.evm.codes/#20?fork=berlin]
+ * @zk-counters
+ *  - 192 arith
+ *  - dynamic binary: 193 + length
+ *  - 2 mem align
+ *  - 2 keccak
+ *  - 10 poseidon
+ *  - dynamic steps: 200 + 100 * length
+ * @process-opcode
+ *  - stack input: offset, size
+ *  - stack output: hash
+ */
 opSHA3:
-
+    ; checks zk-counters
     %MAX_CNT_ARITH - CNT_ARITH - 192 :JMPN(outOfCountersArith)
     %MAX_CNT_BINARY - CNT_BINARY - 193 :JMPN(outOfCountersBinary)
     %MAX_CNT_MEM_ALIGN - CNT_MEM_ALIGN - 2 :JMPN(outOfCountersMemalign)
@@ -9,73 +21,94 @@ opSHA3:
     %MAX_CNT_POSEIDON_G - CNT_POSEIDON_G - 10 :JMPN(outOfCountersPoseidon)
     %MAX_CNT_STEPS - STEP - 200 :JMPN(outOfCountersStep)
 
+    ; check stack underflow
     SP - 2          :JMPN(stackUnderflow)
+    
+    ; check out-of-gas
+    GAS - 30 => GAS :JMPN(outOfGas)
     SP - 1 => SP
-    $ => E          :MLOAD(SP--) ; offset
-    $ => C          :MLOAD(SP) ; length
+    $ => E          :MLOAD(SP--); offset => E
+    $ => C          :MLOAD(SP) ; length => C
+    ; store lastMemOffset for memory expansion gas cost
     E               :MSTORE(lastMemOffset)
+    ; store lastMemLength for memory expansion gas cost
     C               :MSTORE(lastMemLength)
-    ; gas
-    GAS - 30 => GAS :JMPN(outOfGas); gas static = 30
-                    :CALL(saveMem)
-    ; Div operation with Arith
+    ; compute memory expansion gas cost
+                    :CALL(saveMem); in: [lastMemOffset, lastMemLength]
+    ; check out-of-gas, dynamic                
     ;${6*((C+31)/32)}
     C+31 => A
     ;(C+31)/32
     A               :MSTORE(arithA)
     32              :MSTORE(arithB)
                     :CALL(divARITH)
-    $ => A          :MLOAD(arithRes1)
+    $ => A          :MLOAD(arithRes1); in: [arithA, arithB] out: [arithRes1: arithA/arithB, arithRes2: arithA%arithB]
     ; Mul operation with Arith
     ; 6*((C+31)/32)
     6               :MSTORE(arithA)
     A               :MSTORE(arithB)
                     :CALL(mulARITH)
     $ => A          :MLOAD(arithRes1)
-    GAS - A => GAS  :JMPN(outOfGas)  ; dynamic_gas = dynamic_gas = 6 * minimum_word_size + memory_expansion_cost
+    GAS - A => GAS  :JMPN(outOfGas)  ; dynamic_gas = 6 * minimum_word_size + memory_expansion_cost
     ; new hash id
     $ => B           :MLOAD(lastHashKIdUsed)
     B + 1 => B       :MSTORE(lastHashKIdUsed)
+    ; set bytes to hash at D
     32 => D
     ; A new hash with position 0 is started
     0 => HASHPOS
 
 opSHA3Loop:
-
+    ; checks zk-counters
     %MAX_CNT_BINARY - CNT_BINARY - 1 :JMPN(outOfCountersBinary)
     %MAX_CNT_STEPS - STEP - 100 :JMPN(outOfCountersStep)
 
     C - 1           :JMPN(opSHA3End)
     C - 32          :JMPN(opSHA3Final)
-                    :CALL(MLOAD32)
+    ; load next 32 bytes from memory
+                    :CALL(MLOAD32); in: [E: offset] out: [A: value, E: new offset]
+    ; save new offset at B                   
     E => B
+    ; get current hash pointer
     $ => E          :MLOAD(lastHashKIdUsed)
+    ; append A to hash pointer E
     A               :HASHK(E)
+    ; restore new offset at E
     B => E
     C - 32 => C
                     :JMP(opSHA3Loop)
 opSHA3Final:
-                    :CALL(MLOADX)
+    ; load next C bytes from memory
+                    :CALL(MLOADX); in: [E: offset, C: length] out: [A: value, E: new offset]
+    ; set #bytes to right shift
     32 - C => D
-                    :CALL(SHRarith)
+                    :CALL(SHRarith); in: [A: value, D: #bytes to right shift] out: [A: shifted result]
+    ; get current hash pointer
     $ => E          :MLOAD(lastHashKIdUsed)
+    ; set remaining bytes length to hash at D                    
     C => D
+    ; append A to hash pointer E
     A               :HASHK(E)
 
 opSHA3End:
+    ; get current hash pointer
     $ => E          :MLOAD(lastHashKIdUsed)
+    ; append A to hash pointer E
     HASHPOS         :HASHKLEN(E)
     
     ; Check keccak counters
     HASHPOS         :MSTORE(arithA)
     136             :MSTORE(arithB)
-                    :CALL(divARITH)
+                    :CALL(divARITH); in: [arithA, arithB] out: [arithRes1: arithA/arithB, arithRes2: arithA%arithB]
     $ => B          :MLOAD(arithRes1)
     $ => A          :MLOAD(cntKeccakPreProcess)
+    ; checks keccak counters
     %MAX_CNT_KECCAK_F - CNT_KECCAK_F - A => A
     $               :LT, JMPC(outOfCountersKeccak)
-    
+    ; compute hash
     $ => A          :HASHKDIGEST(E)
+    ; store hash
     A               :MSTORE(SP++)
+    ; check stack overflow
     1024 - SP       :JMPN(stackOverflow)
                     :JMP(readCode)
diff --git a/main/opcodes/storage-memory.zkasm b/main/opcodes/storage-memory.zkasm
index f130f63e..e7da1fb1 100644
--- a/main/opcodes/storage-memory.zkasm
+++ b/main/opcodes/storage-memory.zkasm
@@ -27,7 +27,7 @@ opMLOAD:
     $ => E          :MLOAD(SP); offset => E
     ; store lastMemOffset for memory expansion gas cost
     E               :MSTORE(lastMemOffset)
-                    :CALL(MLOAD32); in: [E: offset] out: [A: value]
+                    :CALL(MLOAD32); in: [E: offset] out: [A: value, E: new offset]
     ; store lastMemLength for memory expansion gas cost
     32              :MSTORE(lastMemLength)
     ; compute memory expansion gas cost