EVMC
evmc.h File Reference

EVMC: Ethereum Client-VM Connector API. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Classes

struct  evmc_bytes32
 The fixed size array of 32 bytes. More...
 
struct  evmc_address
 Big-endian 160-bit hash suitable for keeping an Ethereum address. More...
 
struct  evmc_message
 The message describing an EVM call, including a zero-depth calls from a transaction origin. More...
 
struct  evmc_tx_context
 The transaction and block data for execution. More...
 
struct  evmc_result
 The EVM code execution result. More...
 
struct  evmc_host_interface
 The Host interface. More...
 
struct  evmc_vm
 The VM instance. More...
 

Typedefs

typedef struct evmc_bytes32 evmc_bytes32
 The fixed size array of 32 bytes. More...
 
typedef struct evmc_bytes32 evmc_uint256be
 The alias for evmc_bytes32 to represent a big-endian 256-bit integer.
 
typedef struct evmc_address evmc_address
 Big-endian 160-bit hash suitable for keeping an Ethereum address. More...
 
typedef struct evmc_tx_context(* evmc_get_tx_context_fn) (struct evmc_host_context *context)
 Get transaction context callback function. More...
 
typedef evmc_bytes32(* evmc_get_block_hash_fn) (struct evmc_host_context *context, int64_t number)
 Get block hash callback function. More...
 
typedef void(* evmc_release_result_fn) (const struct evmc_result *result)
 Releases resources assigned to an execution result. More...
 
typedef bool(* evmc_account_exists_fn) (struct evmc_host_context *context, const evmc_address *address)
 Check account existence callback function. More...
 
typedef evmc_bytes32(* evmc_get_storage_fn) (struct evmc_host_context *context, const evmc_address *address, const evmc_bytes32 *key)
 Get storage callback function. More...
 
typedef enum evmc_storage_status(* evmc_set_storage_fn) (struct evmc_host_context *context, const evmc_address *address, const evmc_bytes32 *key, const evmc_bytes32 *value)
 Set storage callback function. More...
 
typedef evmc_uint256be(* evmc_get_balance_fn) (struct evmc_host_context *context, const evmc_address *address)
 Get balance callback function. More...
 
typedef size_t(* evmc_get_code_size_fn) (struct evmc_host_context *context, const evmc_address *address)
 Get code size callback function. More...
 
typedef evmc_bytes32(* evmc_get_code_hash_fn) (struct evmc_host_context *context, const evmc_address *address)
 Get code size callback function. More...
 
typedef size_t(* evmc_copy_code_fn) (struct evmc_host_context *context, const evmc_address *address, size_t code_offset, uint8_t *buffer_data, size_t buffer_size)
 Copy code callback function. More...
 
typedef void(* evmc_selfdestruct_fn) (struct evmc_host_context *context, const evmc_address *address, const evmc_address *beneficiary)
 Selfdestruct callback function. More...
 
typedef void(* evmc_emit_log_fn) (struct evmc_host_context *context, const evmc_address *address, const uint8_t *data, size_t data_size, const evmc_bytes32 topics[], size_t topics_count)
 Log callback function. More...
 
typedef struct evmc_result(* evmc_call_fn) (struct evmc_host_context *context, const struct evmc_message *msg)
 Pointer to the callback function supporting EVM calls. More...
 
typedef void(* evmc_destroy_fn) (struct evmc_vm *vm)
 Destroys the VM instance. More...
 
typedef enum evmc_set_option_result(* evmc_set_option_fn) (struct evmc_vm *vm, char const *name, char const *value)
 Configures the VM instance. More...
 
typedef struct evmc_result(* evmc_execute_fn) (struct evmc_vm *vm, const struct evmc_host_interface *host, struct evmc_host_context *context, enum evmc_revision rev, const struct evmc_message *msg, uint8_t const *code, size_t code_size)
 Executes the given code using the input from the message. More...
 
typedef uint32_t evmc_capabilities_flagset
 Alias for unsigned integer representing a set of bit flags of EVMC capabilities. More...
 
typedef evmc_capabilities_flagset(* evmc_get_capabilities_fn) (struct evmc_vm *vm)
 Return the supported capabilities of the VM instance. More...
 

Enumerations

enum  { EVMC_ABI_VERSION = 7 }
 
enum  evmc_call_kind {
  EVMC_CALL = 0, EVMC_DELEGATECALL = 1, EVMC_CALLCODE = 2, EVMC_CREATE = 3,
  EVMC_CREATE2 = 4
}
 The kind of call-like instruction. More...
 
enum  evmc_flags { EVMC_STATIC = 1 }
 The flags for evmc_message. More...
 
enum  evmc_status_code {
  EVMC_SUCCESS = 0, EVMC_FAILURE = 1, EVMC_REVERT = 2, EVMC_OUT_OF_GAS = 3,
  EVMC_INVALID_INSTRUCTION = 4, EVMC_UNDEFINED_INSTRUCTION = 5, EVMC_STACK_OVERFLOW = 6, EVMC_STACK_UNDERFLOW = 7,
  EVMC_BAD_JUMP_DESTINATION = 8, EVMC_INVALID_MEMORY_ACCESS = 9, EVMC_CALL_DEPTH_EXCEEDED = 10, EVMC_STATIC_MODE_VIOLATION = 11,
  EVMC_PRECOMPILE_FAILURE = 12, EVMC_CONTRACT_VALIDATION_FAILURE = 13, EVMC_ARGUMENT_OUT_OF_RANGE = 14, EVMC_WASM_UNREACHABLE_INSTRUCTION = 15,
  EVMC_WASM_TRAP = 16, EVMC_INTERNAL_ERROR = -1, EVMC_REJECTED = -2, EVMC_OUT_OF_MEMORY = -3
}
 The execution status code. More...
 
enum  evmc_storage_status {
  EVMC_STORAGE_UNCHANGED = 0, EVMC_STORAGE_MODIFIED = 1, EVMC_STORAGE_MODIFIED_AGAIN = 2, EVMC_STORAGE_ADDED = 3,
  EVMC_STORAGE_DELETED = 4
}
 The effect of an attempt to modify a contract storage item. More...
 
enum  evmc_set_option_result { EVMC_SET_OPTION_SUCCESS = 0, EVMC_SET_OPTION_INVALID_NAME = 1, EVMC_SET_OPTION_INVALID_VALUE = 2 }
 Possible outcomes of evmc_set_option.
 
enum  evmc_revision {
  EVMC_FRONTIER = 0, EVMC_HOMESTEAD = 1, EVMC_TANGERINE_WHISTLE = 2, EVMC_SPURIOUS_DRAGON = 3,
  EVMC_BYZANTIUM = 4, EVMC_CONSTANTINOPLE = 5, EVMC_PETERSBURG = 6, EVMC_ISTANBUL = 7,
  EVMC_BERLIN = 8, EVMC_MAX_REVISION = EVMC_BERLIN
}
 EVM revision. More...
 
enum  evmc_capabilities { EVMC_CAPABILITY_EVM1 = (1u << 0), EVMC_CAPABILITY_EWASM = (1u << 1), EVMC_CAPABILITY_PRECOMPILES = (1u << 2) }
 Possible capabilities of a VM. More...
 

Functions

struct evmc_vmevmc_create_example_vm (void)
 Example of a function creating an instance of an example EVM implementation. More...
 

Detailed Description

EVMC: Ethereum Client-VM Connector API.

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.

Definition in file evmc.h.