diff --git a/include/evmc/evmc.h b/include/evmc/evmc.h index ca9de8b..610058c 100644 --- a/include/evmc/evmc.h +++ b/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.