From 9353a8df778349254417f29fa81e4d2a329b51c5 Mon Sep 17 00:00:00 2001
From: enitrat <msaug@protonmail.com>
Date: Mon, 23 Sep 2024 22:30:53 +0200
Subject: [PATCH] add code doc and fix return code in precompiles

---
 src/kakarot/precompiles/precompiles.cairo | 54 ++++++++++++++++-------
 1 file changed, 38 insertions(+), 16 deletions(-)

diff --git a/src/kakarot/precompiles/precompiles.cairo b/src/kakarot/precompiles/precompiles.cairo
index f2060008e..f2c2cdad5 100644
--- a/src/kakarot/precompiles/precompiles.cairo
+++ b/src/kakarot/precompiles/precompiles.cairo
@@ -161,10 +161,11 @@ namespace Precompiles {
     }
 
     // @notice A placeholder for attempts to call a precompile without permissions
-    // @dev Halts execution.
-    // @param evm_address The evm_address.
-    // @param input_len The length of the input array.
-    // @param input The input array.
+    // @dev Halts execution with an unauthorized precompile error.
+    // @return output_len The length of the error message.
+    // @return output The error message.
+    // @return gas_used The gas used (always 0 for this function).
+    // @return reverted The reverted code (EXCEPTIONAL_HALT).
     func unauthorized_precompile{
         syscall_ptr: felt*,
         pedersen_ptr: HashBuiltin*,
@@ -172,14 +173,18 @@ namespace Precompiles {
         bitwise_ptr: BitwiseBuiltin*,
     }() -> (output_len: felt, output: felt*, gas_used: felt, reverted: felt) {
         let (revert_reason_len, revert_reason) = Errors.unauthorizedPrecompile();
-        return (revert_reason_len, revert_reason, 0, Errors.REVERT);
+        return (revert_reason_len, revert_reason, 0, Errors.EXCEPTIONAL_HALT);
     }
 
-    // @notice A placeholder for precompile that don't exist.
-    // @dev Halts execution.
-    // @param evm_address The evm_address.
-    // @param input_len The length of the input array.
-    // @param input The input array.
+    // @notice A placeholder for precompiles that don't exist.
+    // @dev Halts execution with an unknown precompile error.
+    // @param evm_address The address of the unknown precompile.
+    // @param input_len The length of the input array (unused).
+    // @param input The input array (unused).
+    // @return output_len The length of the error message.
+    // @return output The error message.
+    // @return gas_used The gas used (always 0 for this function).
+    // @return reverted The reverted code (EXCEPTIONAL_HALT).
     func unknown_precompile{
         syscall_ptr: felt*,
         pedersen_ptr: HashBuiltin*,
@@ -192,11 +197,15 @@ namespace Precompiles {
         return (revert_reason_len, revert_reason, 0, Errors.EXCEPTIONAL_HALT);
     }
 
-    // @notice A placeholder for precompile that are not implemented yet.
-    // @dev Halts execution.
-    // @param evm_address The evm_address.
-    // @param input_len The length of the input array.
-    // @param input The input array.
+    // @notice A placeholder for precompiles that are not implemented yet.
+    // @dev Halts execution with a not implemented precompile error.
+    // @param evm_address The address of the not implemented precompile.
+    // @param input_len The length of the input array (unused).
+    // @param input The input array (unused).
+    // @return output_len The length of the error message.
+    // @return output The error message.
+    // @return gas_used The gas used (always 0 for this function).
+    // @return reverted The reverted code (EXCEPTIONAL_HALT).
     func not_implemented_precompile{
         syscall_ptr: felt*,
         pedersen_ptr: HashBuiltin*,
@@ -209,6 +218,15 @@ namespace Precompiles {
         return (revert_reason_len, revert_reason, 0, Errors.EXCEPTIONAL_HALT);
     }
 
+    // @notice Executes an external precompile using a Cairo 1 helper contract.
+    // @dev Calls the library_call_exec_precompile function of the ICairo1Helpers interface.
+    // @param evm_address The address of the external precompile.
+    // @param input_len The length of the input array.
+    // @param input The input array.
+    // @return output_len The length of the output data.
+    // @return output The output data.
+    // @return gas_used The gas used by the precompile execution.
+    // @return reverted 0 if successful, EXCEPTIONAL_HALT if execution failed.
     func external_precompile{
         syscall_ptr: felt*,
         pedersen_ptr: HashBuiltin*,
@@ -229,6 +247,10 @@ namespace Precompiles {
             class_hash=implementation, address=evm_address, data_len=input_len, data=input
         );
         let gas = gas_if_success * success;
-        return (return_data_len, return_data, gas, 1 - success);
+        if (success != FALSE) {
+            return (return_data_len, return_data, gas, 0);
+        }
+        // Precompiles can only revert with exceptions. Thus if the execution failed, it's an error EXCEPTIONAL_HALT.
+        return (return_data_len, return_data, gas, Errors.EXCEPTIONAL_HALT);
     }
 }