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.
 
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 hash 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 enum evmc_access_status(* evmc_access_account_fn) (struct evmc_host_context *context, const evmc_address *address)
 Access account callback function. More...
 
typedef enum evmc_access_status(* evmc_access_storage_fn) (struct evmc_host_context *context, const evmc_address *address, const evmc_bytes32 *key)
 Access storage 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 = 9 }
 
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_INSUFFICIENT_BALANCE = 17 , 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_access_status { EVMC_ACCESS_COLD = 0 , EVMC_ACCESS_WARM = 1 }
 Access status per EIP-2929: Gas cost increases for state access opcodes. 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_LONDON = 9 , EVMC_MAX_REVISION = EVMC_LONDON
}
 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.