REVERT instruction

EIPS/eip-140.md

@@ -0,0 +1,58 @@
+## Preamble
+
+    EIP: 140
+    Title: REVERT instruction in the Ethereum Virtual Machine
+    Author: Alex Beregszaszi, Nikolai Mushegian ([email protected])
+    Type: Standard Track
+    Category: Core
+    Status: Accepted
+    Created: 2017-02-06
+
+## Simple Summary
+
+The `REVERT` instruction provides a way to stop execution and revert state changes, without consuming all provided gas and with the ability to return a reason.
+
+## Abstract
+
+The `REVERT` instruction will stop execution, roll back all state changes done so far and provide a pointer to a memory section, which can be interpreted as an error code or message. While doing so, it will not consume all the remaining gas.
+
+## Motivation
+
+Currently this is not possible. There are two practical ways to revert a transaction from within a contract: running out of gas or executing an invalid instruction. Both of these options will consume all remaining gas. Additionally, reverting a transaction means that all changes, including LOGs, are lost and there is no way to convey a reason for aborting a transaction.
+
+## Specification
+
+The `REVERT` instruction is introduced at `0xfd`. It expects two stack items, the top item is the `memory_offset` followed by `memory_length`. It does not return anything because it stops execution.
+
+The semantics of `REVERT` with respect to memory and memory cost are identical to those of `RETURN`. The sequence of bytes given by `memory_offset` and `memory_length` is called "error message" in the following.
+
+The effect of `REVERT` is that execution is aborted, considered as failed, and state changes are rolled back. The error message will be available to the caller in the returndata buffer and will also be copied to the output area, i.e. it is handled in the same way as the regular return data is handled.
+
+The cost of the `REVERT` instruction equals to that of the `RETURN` instruction, i.e. the rollback itself does not consume all gas, the contract only has to pay for memory.
+
+In case there is not enough gas left to cover the cost of `REVERT` or there is a stack underflow, the effect of the `REVERT` instruction will equal to that of a regular out of gas exception, i.e. it will consume all gas.
+
+In the same way as all other failures, the calling opcode returns `0` on the stack following a `REVERT` opcode in the callee.
+
+In case `REVERT` is used in the context of a `CREATE` or `CREATE2` call, no code is deployed, `0` is put on the stack and the error message is available in the returndata buffer.
+
+The content of the optionally provided memory section is not defined by this EIP, but is a candidate for another Informational EIP.
+
+## Backwards Compatibility
+
+This change has no effect on contracts created in the past.
+
+## Test Cases
+
+```
+6c726576657274656420646174616000557f726576657274206d657373616765000000000000000000000000000000000000600052600e6000fd
+```
+
+should:
+- return `726576657274206d657373616765` as `REVERT` data,
+- the storage at key `0x0` should be left as unset and
+- use 20024 gas in total.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).