Merge pull request #159 from ethereum/host-guide

docs: Host Implementation Guide

circle.yml

@@ -16,7 +16,7 @@ jobs:
         command: |
           sudo pip3 install --upgrade pip setuptools
           sudo pip3 install codespell
-          codespell --skip=".git" --ignore-words=./.codespell-whitelist
+          codespell --quiet-level=4 --ignore-words=./.codespell-whitelist
 
   build: &build
     docker:

docs/EVMC.md

@@ -6,6 +6,11 @@ On the Client-side it defines the interface for EVM implementations
 to access Ethereum environment and state.
 
 
+# Guides
+
+- [Host Implementation Guide](@ref hostguide)
+
+
 # Versioning {#versioning}
 
 The EVMC project uses [Semantic Versioning](https://semver.org).

docs/Host_Guide.md

@@ -0,0 +1,43 @@
+# EVMC Host Implementation Guide {#hostguide}
+
+> How to bring EVMC support to Your Ethereum Client.
+
+## Host interface
+
+First of all, you have to implement the Host interface. The Host interface
+allows VMs to query and modify Ethereum state during the execution.
+
+The implementation can be done in object-oriented manner. 
+The ::evmc_host_interface lists the methods any Host must implement.
+
+Moreover, each of the methods has a pointer to ::evmc_context 
+as a parameter. The context is owned entirely by the Host allowing a Host instance 
+to behave as an object with data.
+
+## VM usage
+
+When Host implementation is ready it's time to start using EVMC VMs.
+
+1. Firstly, create a VM instance. You need to know what is the name of the "create"
+   function in particular VM implementation. The EVMC recommends to name the 
+   function by the VM codename, e.g. ::evmc_create_examplevm().
+   Invoking the create function will give you the VM instance (::evmc_instance). 
+   It is recommended to create the VM instance once.
+
+2. If you are interested in loading VMs dynamically (i.e. to use DLLs) 
+   check out the [EVMC Loader](@ref loader) library.
+
+3. The ::evmc_instance contains information about the VM like 
+   name (::evmc_instance::name) or ABI version (::evmc_instance::abi_version)
+   and methods.
+
+4. To execute code in the VM use the "execute()" method (::evmc_instance::execute).
+   You will need:
+   - the code to execute,
+   - the message (::evmc_message) object that describes the execution context,
+   - the Host instance, passed as ::evmc_context pointer.
+
+5. When execution finishes you will receive ::evmc_result object that describes
+   the results of the execution.
+
+Have fun!