status-im
/
evmc
mirror of https://github.com/status-im/evmc.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
evmc/docs/EVMC.md

2.8 KiB
Raw Permalink Blame History

EVMC – Ethereum Client-VM Connector API

ABI version 7

The EVMC is the low-level ABI between Ethereum Virtual Machines (EVMs) and Ethereum Clients. On the EVM-side it supports classic EVM1 and ewasm. On the Client-side it defines the interface for EVM implementations to access Ethereum environment and state.

Guides

  • [Host Implementation Guide](@ref hostguide)
  • [VM Implementation Guide](@ref vmguide)

Versioning

The EVMC project uses Semantic Versioning. The version format is MAJOR.MINOR.PATCH.

The MAJOR version number is also referenced as the EVMC ABI version. This ABI version is available to VM and Host implementations by ::EVMC_ABI_VERSION. For example EVMC 3.2.1 would have ABI version 3 and therefore this project release can be referenced as EVMC ABIv3 or just EVMC 3. Every C ABI breaking change requires increasing the MAJOR version number.

The releases with MINOR version change allow adding new API features and modifying the language bindings API. Backward incompatible API changes are allowed but should be avoided if possible.

The releases with PATCH should only include bug fixes. Exceptionally, API changes are allowed when required to fix a broken feature.

Modules

  • [EVMC](@ref EVMC) – the main component that defines API for VMs and Clients (Hosts).
  • [EVMC C++ API](@ref evmc) – the wrappers and bindings for C++.
  • [EVMC Loader](@ref loader) – the library for loading VMs implemented as Dynamically Loaded Libraries (DLLs, shared objects).
  • [EVMC Helpers](@ref helpers) – a collection of utility functions for easier integration with EVMC.
  • [EVM Instructions](@ref instructions) – the library with collection of metrics for EVM1 instruction set.
  • [EVMC VM Tester](@ref vmtester) – the EVMC-compatibility testing tool for VM implementations.

Language bindings

Go

import "github.com/ethereum/evmc/bindings/go/evmc"

@addtogroup EVMC

Terms

  1. VM – An Ethereum Virtual Machine instance/implementation.
  2. Host – An entity controlling the VM. The Host requests code execution and responses to VM queries by callback functions. This usually represents an Ethereum Client.

Responsibilities

VM

  • Executes the code (obviously).
  • Calculates the running gas cost and manages the gas counter except the refund counter.
  • Controls the call depth, including the exceptional termination of execution in case the maximum depth is reached.

Host

  • Provides access to State.
  • Creates new accounts (with code being a result of VM execution).
  • Handles refunds entirely.
  • Manages the set of precompiled contracts and handles execution of messages coming to them.