Draft of "EVMC modules for implementations of precompiled contracts"

EIPS/eip-evmc-precompiles.md

@@ -0,0 +1,91 @@
+---
+eip: XXXX
+title: EVMC modules for implementations of precompiled contracts
+author: Paweł Bylica (@chfast)
+discussions-to:
+status: Draft
+type: Informational
+created: 2019-05-09
+---
+
+## Abstract
+
+[EVMC] specifies generic API for Ethereum execution engines.
+This EIP specifies a way of providing implementations of Ethereum precompiled contracts
+as a degenerated EVM implementations using [EVMC VM API].
+
+
+## Specification
+
+The EVMC module with implementations of precompiled contracts SHOULD:
+
+1. Advertise [`EVMC_CAPABILITY_PRECOMPILES`] capability in the `get_capabilities()` method.
+2. Implement the [`execute()`] method in the following way:
+   1. Check if the call destination address (`evmc_message::destination`)
+      is within the range of precompiled contracts defined by [EIP-1352].
+      If not, abort execution with the `EVMC_REJECTED` status code.
+   2. Check if the call destination address (`evmc_message::destination`)
+      targets existing precompiled contract.
+      Take into consideration the EVM revision (`evmc_revision`) requested by `rev` parameter of [`execute()`].
+      If yes, execute as follows:
+      1. Inspect the input data (`evmc_message::input_data`, `evmc_message::input_size`)
+         and calculate the _gas cost_ of the execution.
+      2. Compute the amount of _gas left_ after execution by
+         subtracting the _gas cost_ from the call gas limit (`evmc_message::gas`).
+      3. If _gas left_ is negative,
+         abort execution with the `EVMC_OUT_OF_GAS` status code.
+      4. Otherwise,
+         execute the code of the precompiled contract,
+         return the [`EVMC_SUCCESS`] status code, the output and _gas left_
+         (`evmc_result::output_data`, `evmc_result::output_size`, `evmc_result::gas_left`).
+   3. Otherwise, emulate execution of empty code by returning
+      the [`EVMC_SUCCESS`] status code
+      and _gas left_ equal the call gas limit (`evmc_message::gas`).
+
+
+## Rationale
+
+TODO
+
+
+## Test Cases
+
+EVMC provides the [evmc-vmtester] tool for checking compatibility with EVMC specification.
+
+
+## Implementations
+
+- the [example_precompiles_vm.cpp]
+- ewasm/precompiles
+- Aleth code for precompiles
+- Parity code for precompiles
+- Other EVMC VMs?
+
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+
+## References
+
+- EVMC docs
+- EVMC guides
+- EVMC example
+- EIP-1352
+
+
+## TODO
+
+- What if message::kind is CREATE?
+- What if message contains code?
+- Add code snippets from the example?
+
+
+[EVMC]: https://github.com/ethereum/evmc
+[EVMC VM API]: https://ethereum.github.io/evmc/vmguide.html
+[evmc-vmtester]: https://ethereum.github.io/evmc/vmtester.html
+[example_precompiles_vm.cpp]: https://github.com/ethereum/evmc/blob/precompiles-capacity/examples/example_precompiles_vm/example_precompiles_vm.cpp
+
+[`EVMC_CAPABILITY_PRECOMPILES`]: 404
+[`EVMC_SUCCESS`]: https://ethereum.github.io/evmc/group__EVMC.html#gga4c0be97f333c050ff45321fcaa34d920a4bc3069fec2bab2a55355a72b7db68b7
+[`execute()`]: https://ethereum.github.io/evmc/structevmc__instance.html#a0823ebff21f9b0395b157e8c6b14a207