-
Notifications
You must be signed in to change notification settings - Fork 303
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #159 from ethereum/host-guide
docs: Host Implementation Guide
- Loading branch information
Showing
3 changed files
with
49 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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! |