Include system contracts

README.md

@@ -23,6 +23,7 @@ eWASM is a restricted subset of WASM to be used for contracts in Ethereum.
 eWASM:
 * specifies the [semantics for an *eWASM contract*](./contract_interface.md)
 * specifies an [Ethereum environment interface](./eth_interface.md) to facilitate interaction with the Ethereum environment from an *eWASM contract*
+* specifies [system contracts](./system_contracts.md)
 * specifies [metering](./metering.md) for instructions
 * and aims to restrict [non-deterministic behavior](https://github.com/WebAssembly/design/blob/master/Nondeterminism.md)
 * specifies a backwards compatible upgrade path to EVM1
@@ -51,6 +52,7 @@ eWASM:
 * [Rationale](./rationale.md)
 * [Ethereum environment interface](./eth_interface.md)
 * [eWASM Contract Interface](./contract_interface.md)
+* [System contracts](./system_contracts.md)
 * [Backwards compatibility instructions](./backwardsCompatibility.md)
 * [Original Proposal](https://github.com/ethereum/EIPs/issues/48) (EIP#48)
 * [WebAssembly design documents](https://github.com/WebAssembly/design)

system_contracts.md

@@ -0,0 +1,120 @@
+# System Contracts
+
+System contracts are interfaces defined as contracts, which are essential or
+recommended for an eWASM VM.
+
+An eWASM VM implementation may opt to implement these interfaces natively
+or to rely on implementations written in eWASM.
+
+Each of these contracts have a pre defined address and can be executed through
+regular contract invocations.
+
+## Sentinel Contract
+
+Address: `0x000000000000000000000000000000000000000a`
+
+Every newly deployed eWASM contract must be processed by the *Sentinel Contract*
+prior to including the code in the state. The sentinel will perform three very
+important processing steps:
+- Validate eWASM semantics
+- Inject metering code
+- Wrap the result in the deployer preamble (*see Appendix*)
+
+Input:
+- **variable length**: *eWASM contract code*
+
+Output:
+- **variable length**: *eWASM contract code*
+
+## EVM Transcompiler
+
+Address: `0x000000000000000000000000000000000000000b`
+
+This is optional. It is provided for pure eWASM VMs to support EVM1 contracts.
+
+Input:
+- **variable length**: *EVM1 contract code*
+
+Output:
+- **variable length**: *eWASM contract code*
+
+## EVM Precompiled Contracts
+
+Precompiled contracts are defined for EVM1 (see the Yellow Paper). Several
+extensions have been proposed as *[Ethereum Improvement Proposals](https://github.com/ethereum/EIPs)*.
+
+We assume the contracts defined in the Yellow Paper still apply for eWASM.
+
+### ecrecover
+
+Address: `0x0000000000000000000000000000000000000001`
+
+Calculates the corresponding Ethereum address for the public key which created the given signature.
+
+Input:
+- **32 bytes**: *message hash*
+- **32 bytes**: *recovery id*
+- **32 bytes**: *R component*
+- **32 bytes**: *S component*
+
+Output:
+- **32 bytes**: *Ethereum address* (left padded with zeroes)
+
+### sha2-256
+
+Address: `0x0000000000000000000000000000000000000002`
+
+Returns the SHA2-256 hash of the input.
+
+Input:
+- **variable length**: *input data*
+
+Output:
+- **32 bytes**: *sha2-256 hash*
+
+### ripemd160
+
+Address: `0x0000000000000000000000000000000000000003`
+
+Returns the RIPEMD-160 hash of the input.
+
+Input:
+- **variable length**: *input data*
+
+Output:
+- **32 bytes**: *ripemd160 hash* (left padded with zeroes)
+
+### identity
+
+Address: `0x0000000000000000000000000000000000000004`
+
+Copies the input data to the output.
+
+Input:
+- **variable length**: *input data*
+
+Output:
+- **variable length**: *output data*
+
+### Appendix: eWASM deployer preamble
+
+```
+;;
+;; Standard eWASM deployer code.
+;;
+;; We keep the to-be-deployed contract as a memory segment and simply return it.
+;;
+
+(module
+  (memory 1
+    (segment 0 "\10\00\00\00")     ;; Here comes the size of the code in LSB
+    (segment 4 "Hello World CODE") ;; Here comes the code as a escaped hex string
+  )
+  (export "memory" memory)
+  (export "main" $main)
+  (import $ethereum_return "ethereum" "return" (param i32 i32))
+  (func $main
+    (call_import $ethereum_return (i32.const 4) (i32.load (i32.const 0)))
+  )
+)
+```