Merge pull request #151 from ewasm/sentinel

Explain the Sentinel interface in more depth

Author: axic

sentinel.md

@@ -8,3 +8,30 @@ The process of metering is [explained in its own chapter](./metering.md).
 
 The Sentinel is a system contract which means its code is fixed and is part of the genesis or hardfork ewasm is enabled on.
 As a result, changing or updating it requires a hard fork.
+
+The Sentinel contract has two interfaces:
+- raw interface
+- ABI encoded interface
+
+The raw interface is used by the node for contract validation during deployment, while the ABI encoded interface is a more
+friendly way to interact with the contract otherwise.
+
+## Error handling
+
+In both modes, the contract will use an invalid instruction (e.g. regular failure) when an unexpected issue occurs,
+or the `revert` operation if the supplied input is invalid.
+
+## Raw interface
+
+In the raw interface it accepts any valid WebAssembly binary, applies the Sentinel steps, and returns the transformed
+WebAssembly binary. There is no encapsulation of any kind.
+
+## ABI encoded interface
+
+The ABI encoded interface is demonstrated by the following Solidity interface:
+```solidity
+interface Sentinel {
+     // Expects a WebAssembly binary and returns a transformed WebAssembly binary.
+     function validateAndMeter(bytes) external view returns (bytes);
+}
+```

system_contracts.md

@@ -22,12 +22,6 @@ important processing steps:
 
 See the [dedicated chapter](./sentinel.md) about it.
 
-Input:
-- **variable length**: *ewasm contract code*
-
-Output:
-- **variable length**: *ewasm contract code*
-
 ## EVM Transcompiler
 
 Address: `0x000000000000000000000000000000000000000b`