Reorder status codes

include/evmc/evmc.h

@@ -140,55 +140,112 @@ typedef void (*evmc_get_block_hash_fn)(struct evmc_uint256be* result,
                                        struct evmc_context* context,
                                        int64_t number);
 
-/// The execution status code.
-enum evmc_status_code {
-    EVMC_SUCCESS = 0,               ///< Execution finished with success.
-    EVMC_FAILURE = 1,               ///< Generic execution failure.
-    EVMC_OUT_OF_GAS = 2,
-    EVMC_UNDEFINED_INSTRUCTION = 3, ///< Unknown instruction encountered by the VM.
-    EVMC_BAD_JUMP_DESTINATION = 4,
-    EVMC_STACK_OVERFLOW = 5,
-    EVMC_STACK_UNDERFLOW = 6,
-    EVMC_REVERT = 7,                ///< Execution terminated with REVERT opcode.
+/**
+ * The execution status code.
+ *
+ * Successful execution is represented by ::EVMC_SUCCESS having value 0.
+ *
+ * Positive values represent failures defined by VM specifications with generic
+ * ::EVMC_FAILURE code of value 1.
+ *
+ * Status codes with negative values represent VM internal errors
+ * not provided by EVM specifications. These errors MUST not be passed back
+ * to the caller. They MAY be handled by the Client in predefined manner
+ * (see e.g. ::EVMC_REJECTED), otherwise internal errors are not recoverable.
+ * The generic representant of errors is ::EVMC_INTERNAL_ERROR but
+ * an EVM implementation MAY return negative status codes that are not defined
+ * in the EVMC documentation.
+ *
+ * @note
+ * In case new status codes are needed, please create an issue or pull request
+ * in the EVMC repository (https://github.com/ethereum/evmc).
+ */
+enum evmc_status_code
+{
+    /** Execution finished with success. */
+    EVMC_SUCCESS = 0,
 
-    /// Tried to execute an operation which is restricted in static mode.
-    EVMC_STATIC_MODE_VIOLATION = 8,
+    /** Generic execution failure. */
+    EVMC_FAILURE = 1,
 
-    /// The dedicated INVALID instruction was hit.
-    EVMC_INVALID_INSTRUCTION = 9,
+    /**
+     * Execution terminated with REVERT opcode.
+     *
+     * In this case the amount of gas left MAY be non-zero and additional output
+     * data MAY be provided in ::evmc_result.
+     */
+    EVMC_REVERT = 2,
 
-    /// Tried to read outside memory bounds.
-    ///
-    /// An example is RETURNDATACOPY reading past the available buffer.
-    EVMC_INVALID_MEMORY_ACCESS = 10,
+    /** The execution has run out of gas. */
+    EVMC_OUT_OF_GAS = 3,
 
-    /// Exceptions produced by precompiles/system contracts
-    ///
-    /// An example: elliptic curve functions handed invalid EC points
-    EVMC_PRECOMPILE_FAILURE = 11,
+    /**
+     * The designated INVALID instruction has been hit during execution.
+     *
+     * The EIP-141 (https://github.com/ethereum/EIPs/blob/master/EIPS/eip-141.md)
+     * defines the instruction 0xfe as INVALID instruction to indicate execution
+     * abortion coming from high-level languages. This status code is reported
+     * in case this INVALID instruction has been encountered.
+     */
+    EVMC_INVALID_INSTRUCTION = 4,
 
-    /// Call depth exceded (if there is a call depth limit)
-    EVMC_CALL_DEPTH_EXCEDED = 12,
+    /** An undefined instruction has been encountered. */
+    EVMC_UNDEFINED_INSTRUCTION = 5,
 
-    /// Contract validation has failed (e.g. due to EVM 1.5 jump validity,
-    /// Casper's purity checker or ewasm contract rules).
+    /**
+     * The execution has attempted to put more items on the EVM stack
+     * than the specified limit.
+     */
+    EVMC_STACK_OVERFLOW = 6,
+
+    /** Execution of an opcode has required more items on the EVM stack. */
+    EVMC_STACK_UNDERFLOW = 7,
+
+    /** Execution has violated the jump destination restrictions. */
+    EVMC_BAD_JUMP_DESTINATION = 8,
+
+    /**
+     * Tried to read outside memory bounds.
+     *
+     * An example is RETURNDATACOPY reading past the available buffer.
+     */
+    EVMC_INVALID_MEMORY_ACCESS = 9,
+
+    /** Call depth has exceeded the limit (if any) */
+    EVMC_CALL_DEPTH_EXCEEDED = 10,
+
+    /** Tried to execute an operation which is restricted in static mode. */
+    EVMC_STATIC_MODE_VIOLATION = 11,
+
+    /**
+     * A call to a precompiled or system contract has ended with a failure.
+     *
+     * An example: elliptic curve functions handed invalid EC points.
+     */
+    EVMC_PRECOMPILE_FAILURE = 12,
+
+    /**
+     * Contract validation has failed (e.g. due to EVM 1.5 jump validity,
+     * Casper's purity checker or ewasm contract rules).
+     */
     EVMC_CONTRACT_VALIDATION_FAILURE = 13,
 
-    /// The EVM rejected the execution of the given code or message.
-    ///
-    /// This error SHOULD be used to signal that the EVM is not able to or
-    /// willing to execute the given code type or message.
-    /// If an EVM returns the ::EVMC_REJECTED status code,
-    /// the Client MAY try to execute it in other EVM implementation.
-    /// For example, the Client tries running a code in the EVM 1.5. If the
-    /// code is not supported there, the execution falls back to the EVM 1.0.
-    EVMC_REJECTED = -1,
 
-    /// EVM implementation internal error.
-    ///
-    /// @todo We should rethink reporting internal errors. One of the options
-    ///       it to allow using any negative value to represent internal errors.
-    EVMC_INTERNAL_ERROR = -2,
+    /** EVM implementation generic internal error. */
+    EVMC_INTERNAL_ERROR = -1,
+
+    /**
+     * The execution of the given code and/or message has been rejected
+     * by the EVM implementation.
+     *
+     * This error SHOULD be used to signal that the EVM is not able to or
+     * willing to execute the given code type or message.
+     * If an EVM returns the ::EVMC_REJECTED status code,
+     * the Client MAY try to execute it in other EVM implementation.
+     * For example, the Client tries running a code in the EVM 1.5. If the
+     * code is not supported there, the execution falls back to the EVM 1.0.
+     */
+    EVMC_REJECTED = -2,
 };
 
 struct evmc_result;  ///< Forward declaration.