EVMC
EVMC

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

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...
 
struct  evmc_host_context
 The opaque data type representing the Host execution context. 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

Host

Typedef Documentation

◆ evmc_access_account_fn

typedef enum evmc_access_status(* evmc_access_account_fn) (struct evmc_host_context *context, const evmc_address *address)

Access account callback function.

This callback function is used by a VM to add the given address to accessed_addresses substate (EIP-2929).

Parameters
contextThe Host execution context.
addressThe address of the account.
Returns
EVMC_ACCESS_WARM if accessed_addresses already contained the address or EVMC_ACCESS_COLD otherwise.

Definition at line 600 of file evmc.h.

◆ evmc_access_storage_fn

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.

This callback function is used by a VM to add the given account storage entry to accessed_storage_keys substate (EIP-2929).

Parameters
contextThe Host execution context.
addressThe address of the account.
keyThe index of the account's storage entry.
Returns
EVMC_ACCESS_WARM if accessed_storage_keys already contained the key or EVMC_ACCESS_COLD otherwise.

Definition at line 600 of file evmc.h.

◆ evmc_account_exists_fn

typedef bool(* evmc_account_exists_fn) (struct evmc_host_context *context, const evmc_address *address)

Check account existence callback function.

This callback function is used by the VM to check if there exists an account at given address.

Parameters
contextThe pointer to the Host execution context.
addressThe address of the account the query is about.
Returns
true if exists, false otherwise.

Definition at line 433 of file evmc.h.

◆ evmc_bytes32

typedef struct evmc_bytes32 evmc_bytes32

The fixed size array of 32 bytes.

32 bytes of data capable of storing e.g. 256-bit hashes.

◆ evmc_call_fn

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.

Parameters
contextThe pointer to the Host execution context.
msgThe call parameters.
Returns
The result of the call.

Definition at line 600 of file evmc.h.

◆ evmc_capabilities_flagset

typedef uint32_t evmc_capabilities_flagset

Alias for unsigned integer representing a set of bit flags of EVMC capabilities.

See also
evmc_capabilities

Definition at line 899 of file evmc.h.

◆ evmc_copy_code_fn

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.

This callback function is used by an EVM to request a copy of the code of the given account to the memory buffer provided by the EVM. The Client MUST copy the requested code, starting with the given offset, to the provided memory buffer up to the size of the buffer or the size of the code, whichever is smaller.

Parameters
contextThe pointer to the Host execution context. See evmc_host_context.
addressThe address of the account.
code_offsetThe offset of the code to copy.
buffer_dataThe pointer to the memory buffer allocated by the EVM to store a copy of the requested code.
buffer_sizeThe size of the memory buffer.
Returns
The number of bytes copied to the buffer by the Client.

Definition at line 567 of file evmc.h.

◆ evmc_destroy_fn

typedef void(* evmc_destroy_fn) (struct evmc_vm *vm)

Destroys the VM instance.

Parameters
vmThe VM instance to be destroyed.

Definition at line 725 of file evmc.h.

◆ evmc_emit_log_fn

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.

This callback function is used by an EVM to inform about a LOG that happened during an EVM bytecode execution.

Parameters
contextThe pointer to the Host execution context. See evmc_host_context.
addressThe address of the contract that generated the log.
dataThe pointer to unindexed data attached to the log.
data_sizeThe length of the data.
topicsThe pointer to the array of topics attached to the log.
topics_countThe number of the topics. Valid values are between 0 and 4 inclusively.

Definition at line 600 of file evmc.h.

◆ evmc_execute_fn

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.

This function MAY be invoked multiple times for a single VM instance.

Parameters
vmThe VM instance. This argument MUST NOT be NULL.
hostThe Host interface. This argument MUST NOT be NULL unless the vm has the EVMC_CAPABILITY_PRECOMPILES capability.
contextThe opaque pointer to the Host execution context. This argument MAY be NULL. The VM MUST pass the same pointer to the methods of the host interface. The VM MUST NOT dereference the pointer.
revThe requested EVM specification revision.
msgThe call parameters. See evmc_message. This argument MUST NOT be NULL.
codeThe reference to the code to be executed. This argument MAY be NULL.
code_sizeThe length of the code. If code is NULL this argument MUST be 0.
Returns
The execution result.

Definition at line 725 of file evmc.h.

◆ evmc_get_balance_fn

typedef evmc_uint256be(* evmc_get_balance_fn) (struct evmc_host_context *context, const evmc_address *address)

Get balance callback function.

This callback function is used by a VM to query the balance of the given account.

Parameters
contextThe pointer to the Host execution context.
addressThe address of the account.
Returns
The balance of the given account or 0 if the account does not exist.

Definition at line 520 of file evmc.h.

◆ evmc_get_block_hash_fn

typedef evmc_bytes32(* evmc_get_block_hash_fn) (struct evmc_host_context *context, int64_t number)

Get block hash callback function.

This callback function is used by a VM to query the hash of the header of the given block. If the information about the requested block is not available, then this is signalled by returning null bytes.

Parameters
contextThe pointer to the Host execution context.
numberThe block number.
Returns
The block hash or null bytes if the information about the block is not available.

Definition at line 190 of file evmc.h.

◆ evmc_get_capabilities_fn

typedef evmc_capabilities_flagset(* evmc_get_capabilities_fn) (struct evmc_vm *vm)

Return the supported capabilities of the VM instance.

This function MAY be invoked multiple times for a single VM instance, and its value MAY be influenced by calls to evmc_vm::set_option.

Parameters
vmThe VM instance.
Returns
The supported capabilities of the VM.
See also
evmc_capabilities.

Definition at line 910 of file evmc.h.

◆ evmc_get_code_hash_fn

typedef evmc_bytes32(* evmc_get_code_hash_fn) (struct evmc_host_context *context, const evmc_address *address)

Get code hash callback function.

This callback function is used by a VM to get the keccak256 hash of the code stored in the account at the given address. For existing accounts not having a code, this function returns keccak256 hash of empty data.

Parameters
contextThe pointer to the Host execution context.
addressThe address of the account.
Returns
The hash of the code in the account or null bytes if the account does not exist.

Definition at line 547 of file evmc.h.

◆ evmc_get_code_size_fn

typedef size_t(* evmc_get_code_size_fn) (struct evmc_host_context *context, const evmc_address *address)

Get code size callback function.

This callback function is used by a VM to get the size of the code stored in the account at the given address.

Parameters
contextThe pointer to the Host execution context.
addressThe address of the account.
Returns
The size of the code in the account or 0 if the account does not exist.

Definition at line 533 of file evmc.h.

◆ evmc_get_storage_fn

typedef evmc_bytes32(* evmc_get_storage_fn) (struct evmc_host_context *context, const evmc_address *address, const evmc_bytes32 *key)

Get storage callback function.

This callback function is used by a VM to query the given account storage entry.

Parameters
contextThe Host execution context.
addressThe address of the account.
keyThe index of the account's storage entry.
Returns
The storage value at the given storage key or null bytes if the account does not exist.

Definition at line 447 of file evmc.h.

◆ evmc_get_tx_context_fn

typedef struct evmc_tx_context(* evmc_get_tx_context_fn) (struct evmc_host_context *context)

Get transaction context callback function.

This callback function is used by an EVM to retrieve the transaction and block context.

Parameters
contextThe pointer to the Host execution context.
Returns
The transaction context.

Definition at line 1 of file evmc.h.

◆ evmc_release_result_fn

typedef void(* evmc_release_result_fn) (const struct evmc_result *result)

Releases resources assigned to an execution result.

This function releases memory (and other resources, if any) assigned to the specified execution result making the result object invalid.

Parameters
resultThe execution result which resources are to be released. The result itself it not modified by this function, but becomes invalid and user MUST discard it as well. This MUST NOT be NULL.
Note
The result is passed by pointer to avoid (shallow) copy of the evmc_result struct. Think of this as the best possible C language approximation to passing objects by reference.

Definition at line 341 of file evmc.h.

◆ evmc_selfdestruct_fn

typedef void(* evmc_selfdestruct_fn) (struct evmc_host_context *context, const evmc_address *address, const evmc_address *beneficiary)

Selfdestruct callback function.

This callback function is used by an EVM to SELFDESTRUCT given contract. The execution of the contract will not be stopped, that is up to the EVM.

Parameters
contextThe pointer to the Host execution context. See evmc_host_context.
addressThe address of the contract to be selfdestructed.
beneficiaryThe address where the remaining ETH is going to be transferred.

Definition at line 583 of file evmc.h.

◆ evmc_set_option_fn

typedef enum evmc_set_option_result(* evmc_set_option_fn) (struct evmc_vm *vm, char const *name, char const *value)

Configures the VM instance.

Allows modifying options of the VM instance. Options:

  • code cache behavior: on, off, read-only, ...
  • optimizations,
Parameters
vmThe VM instance to be configured.
nameThe option name. NULL-terminated string. Cannot be NULL.
valueThe new option value. NULL-terminated string. Cannot be NULL.
Returns
The outcome of the operation.

Definition at line 725 of file evmc.h.

◆ evmc_set_storage_fn

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.

This callback function is used by a VM to update the given account storage entry. The VM MUST make sure that the account exists. This requirement is only a formality because VM implementations only modify storage of the account of the current execution context (i.e. referenced by evmc_message::destination).

Parameters
contextThe pointer to the Host execution context.
addressThe address of the account.
keyThe index of the storage entry.
valueThe value to be stored.
Returns
The effect on the storage item.

Definition at line 447 of file evmc.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
EVMC_ABI_VERSION 

The EVMC ABI version number of the interface declared in this file.

The EVMC ABI version always equals the major version number of the EVMC project. The Host SHOULD check if the ABI versions match when dynamically loading VMs.

See also
Versioning

Definition at line 37 of file evmc.h.

38 {
48 };
@ EVMC_ABI_VERSION
The EVMC ABI version number of the interface declared in this file.
Definition: evmc.h:47

◆ evmc_access_status

Access status per EIP-2929: Gas cost increases for state access opcodes.

Enumerator
EVMC_ACCESS_COLD 

The entry hasn't been accessed before – it's the first access.

EVMC_ACCESS_WARM 

The entry is already in accessed_addresses or accessed_storage_keys.

Definition at line 610 of file evmc.h.

611 {
615  EVMC_ACCESS_COLD = 0,
616 
620  EVMC_ACCESS_WARM = 1
621 };
@ EVMC_ACCESS_COLD
The entry hasn't been accessed before – it's the first access.
Definition: evmc.h:615
@ EVMC_ACCESS_WARM
The entry is already in accessed_addresses or accessed_storage_keys.
Definition: evmc.h:620

◆ evmc_call_kind

The kind of call-like instruction.

Enumerator
EVMC_CALL 

Request CALL.

EVMC_DELEGATECALL 

Request DELEGATECALL.

Valid since Homestead. The value param ignored.

EVMC_CALLCODE 

Request CALLCODE.

EVMC_CREATE 

Request CREATE.

EVMC_CREATE2 

Request CREATE2.

Valid since Constantinople.

Definition at line 75 of file evmc.h.

76 {
77  EVMC_CALL = 0,
78  EVMC_DELEGATECALL = 1,
80  EVMC_CALLCODE = 2,
81  EVMC_CREATE = 3,
82  EVMC_CREATE2 = 4
83 };
@ EVMC_CREATE
Request CREATE.
Definition: evmc.h:81
@ EVMC_DELEGATECALL
Request DELEGATECALL.
Definition: evmc.h:78
@ EVMC_CREATE2
Request CREATE2.
Definition: evmc.h:82
@ EVMC_CALL
Request CALL.
Definition: evmc.h:77
@ EVMC_CALLCODE
Request CALLCODE.
Definition: evmc.h:80

◆ evmc_capabilities

Possible capabilities of a VM.

Enumerator
EVMC_CAPABILITY_EVM1 

The VM is capable of executing EVM1 bytecode.

EVMC_CAPABILITY_EWASM 

The VM is capable of executing ewasm bytecode.

EVMC_CAPABILITY_PRECOMPILES 

The VM is capable of executing the precompiled contracts defined for the range of destination addresses.

The EIP-1352 (https://eips.ethereum.org/EIPS/eip-1352) specifies the range 0x000...0000 - 0x000...ffff of addresses reserved for precompiled and system contracts.

This capability is experimental and MAY be removed without notice.

Definition at line 869 of file evmc.h.

870 {
874  EVMC_CAPABILITY_EVM1 = (1u << 0),
875 
879  EVMC_CAPABILITY_EWASM = (1u << 1),
880 
891  EVMC_CAPABILITY_PRECOMPILES = (1u << 2)
892 };
@ EVMC_CAPABILITY_EVM1
The VM is capable of executing EVM1 bytecode.
Definition: evmc.h:874
@ EVMC_CAPABILITY_PRECOMPILES
The VM is capable of executing the precompiled contracts defined for the range of destination address...
Definition: evmc.h:891
@ EVMC_CAPABILITY_EWASM
The VM is capable of executing ewasm bytecode.
Definition: evmc.h:879

◆ evmc_flags

enum evmc_flags

The flags for evmc_message.

Enumerator
EVMC_STATIC 

Static call mode.

Definition at line 86 of file evmc.h.

87 {
88  EVMC_STATIC = 1
89 };
@ EVMC_STATIC
Static call mode.
Definition: evmc.h:88

◆ evmc_revision

EVM revision.

The revision of the EVM specification based on the Ethereum upgrade / hard fork codenames.

Enumerator
EVMC_FRONTIER 

The Frontier revision.

The one Ethereum launched with.

EVMC_HOMESTEAD 

The Homestead revision.

https://eips.ethereum.org/EIPS/eip-606

EVMC_TANGERINE_WHISTLE 

The Tangerine Whistle revision.

https://eips.ethereum.org/EIPS/eip-608

EVMC_SPURIOUS_DRAGON 

The Spurious Dragon revision.

https://eips.ethereum.org/EIPS/eip-607

EVMC_BYZANTIUM 

The Byzantium revision.

https://eips.ethereum.org/EIPS/eip-609

EVMC_CONSTANTINOPLE 

The Constantinople revision.

https://eips.ethereum.org/EIPS/eip-1013

EVMC_PETERSBURG 

The Petersburg revision.

Other names: Constantinople2, ConstantinopleFix.

https://eips.ethereum.org/EIPS/eip-1716

EVMC_ISTANBUL 

The Istanbul revision.

https://eips.ethereum.org/EIPS/eip-1679

EVMC_BERLIN 

The Berlin revision.

https://github.com/ethereum/eth1.0-specs/blob/master/network-upgrades/mainnet-upgrades/berlin.md

EVMC_LONDON 

The London revision.

https://github.com/ethereum/eth1.0-specs/blob/master/network-upgrades/mainnet-upgrades/london.md

EVMC_MAX_REVISION 

The maximum EVM revision supported.

Definition at line 761 of file evmc.h.

762 {
768  EVMC_FRONTIER = 0,
769 
775  EVMC_HOMESTEAD = 1,
776 
783 
790 
796  EVMC_BYZANTIUM = 4,
797 
804 
812  EVMC_PETERSBURG = 6,
813 
819  EVMC_ISTANBUL = 7,
820 
826  EVMC_BERLIN = 8,
827 
833  EVMC_LONDON = 9,
834 
837 };
@ EVMC_HOMESTEAD
The Homestead revision.
Definition: evmc.h:775
@ EVMC_ISTANBUL
The Istanbul revision.
Definition: evmc.h:819
@ EVMC_FRONTIER
The Frontier revision.
Definition: evmc.h:768
@ EVMC_PETERSBURG
The Petersburg revision.
Definition: evmc.h:812
@ EVMC_CONSTANTINOPLE
The Constantinople revision.
Definition: evmc.h:803
@ EVMC_TANGERINE_WHISTLE
The Tangerine Whistle revision.
Definition: evmc.h:782
@ EVMC_MAX_REVISION
The maximum EVM revision supported.
Definition: evmc.h:836
@ EVMC_SPURIOUS_DRAGON
The Spurious Dragon revision.
Definition: evmc.h:789
@ EVMC_BYZANTIUM
The Byzantium revision.
Definition: evmc.h:796
@ EVMC_LONDON
The London revision.
Definition: evmc.h:833
@ EVMC_BERLIN
The Berlin revision.
Definition: evmc.h:826

◆ evmc_status_code

The execution status code.

Successful execution is represented by EVMC_SUCCESS having value 0.

Positive values represent failures defined by VM specifications with generic EVMC_FAILURE code of value 1.

Status codes with negative values represent VM internal errors not provided by EVM specifications. These errors MUST not be passed back to the caller. They MAY be handled by the Client in predefined manner (see e.g. EVMC_REJECTED), otherwise internal errors are not recoverable. The generic representant of errors is EVMC_INTERNAL_ERROR but an EVM implementation MAY return negative status codes that are not defined in the EVMC documentation.

Note
In case new status codes are needed, please create an issue or pull request in the EVMC repository (https://github.com/ethereum/evmc).
Enumerator
EVMC_SUCCESS 

Execution finished with success.

EVMC_FAILURE 

Generic execution failure.

EVMC_REVERT 

Execution terminated with REVERT opcode.

In this case the amount of gas left MAY be non-zero and additional output data MAY be provided in evmc_result.

EVMC_OUT_OF_GAS 

The execution has run out of gas.

EVMC_INVALID_INSTRUCTION 

The designated INVALID instruction has been hit during execution.

The EIP-141 (https://github.com/ethereum/EIPs/blob/master/EIPS/eip-141.md) defines the instruction 0xfe as INVALID instruction to indicate execution abortion coming from high-level languages. This status code is reported in case this INVALID instruction has been encountered.

EVMC_UNDEFINED_INSTRUCTION 

An undefined instruction has been encountered.

EVMC_STACK_OVERFLOW 

The execution has attempted to put more items on the EVM stack than the specified limit.

EVMC_STACK_UNDERFLOW 

Execution of an opcode has required more items on the EVM stack.

EVMC_BAD_JUMP_DESTINATION 

Execution has violated the jump destination restrictions.

EVMC_INVALID_MEMORY_ACCESS 

Tried to read outside memory bounds.

An example is RETURNDATACOPY reading past the available buffer.

EVMC_CALL_DEPTH_EXCEEDED 

Call depth has exceeded the limit (if any)

EVMC_STATIC_MODE_VIOLATION 

Tried to execute an operation which is restricted in static mode.

EVMC_PRECOMPILE_FAILURE 

A call to a precompiled or system contract has ended with a failure.

An example: elliptic curve functions handed invalid EC points.

EVMC_CONTRACT_VALIDATION_FAILURE 

Contract validation has failed (e.g.

due to EVM 1.5 jump validity, Casper's purity checker or ewasm contract rules).

EVMC_ARGUMENT_OUT_OF_RANGE 

An argument to a state accessing method has a value outside of the accepted range of values.

EVMC_WASM_UNREACHABLE_INSTRUCTION 

A WebAssembly unreachable instruction has been hit during execution.

EVMC_WASM_TRAP 

A WebAssembly trap has been hit during execution.

This can be for many reasons, including division by zero, validation errors, etc.

EVMC_INSUFFICIENT_BALANCE 

The caller does not have enough funds for value transfer.

EVMC_INTERNAL_ERROR 

EVM implementation generic internal error.

EVMC_REJECTED 

The execution of the given code and/or message has been rejected by the EVM implementation.

This error SHOULD be used to signal that the EVM is not able to or willing to execute the given code type or message. If an EVM returns the EVMC_REJECTED status code, the Client MAY try to execute it in other EVM implementation. For example, the Client tries running a code in the EVM 1.5. If the code is not supported there, the execution falls back to the EVM 1.0.

EVMC_OUT_OF_MEMORY 

The VM failed to allocate the amount of memory needed for execution.

Definition at line 212 of file evmc.h.

213 {
215  EVMC_SUCCESS = 0,
216 
218  EVMC_FAILURE = 1,
219 
226  EVMC_REVERT = 2,
227 
229  EVMC_OUT_OF_GAS = 3,
230 
240 
243 
249 
252 
255 
262 
265 
268 
275 
281 
287 
292 
297  EVMC_WASM_TRAP = 16,
298 
301 
303  EVMC_INTERNAL_ERROR = -1,
304 
316  EVMC_REJECTED = -2,
317 
319  EVMC_OUT_OF_MEMORY = -3
320 };
@ EVMC_INSUFFICIENT_BALANCE
The caller does not have enough funds for value transfer.
Definition: evmc.h:300
@ EVMC_ARGUMENT_OUT_OF_RANGE
An argument to a state accessing method has a value outside of the accepted range of values.
Definition: evmc.h:286
@ EVMC_INVALID_MEMORY_ACCESS
Tried to read outside memory bounds.
Definition: evmc.h:261
@ EVMC_REJECTED
The execution of the given code and/or message has been rejected by the EVM implementation.
Definition: evmc.h:316
@ EVMC_UNDEFINED_INSTRUCTION
An undefined instruction has been encountered.
Definition: evmc.h:242
@ EVMC_SUCCESS
Execution finished with success.
Definition: evmc.h:215
@ EVMC_OUT_OF_MEMORY
The VM failed to allocate the amount of memory needed for execution.
Definition: evmc.h:319
@ EVMC_STACK_UNDERFLOW
Execution of an opcode has required more items on the EVM stack.
Definition: evmc.h:251
@ EVMC_BAD_JUMP_DESTINATION
Execution has violated the jump destination restrictions.
Definition: evmc.h:254
@ EVMC_INVALID_INSTRUCTION
The designated INVALID instruction has been hit during execution.
Definition: evmc.h:239
@ EVMC_STATIC_MODE_VIOLATION
Tried to execute an operation which is restricted in static mode.
Definition: evmc.h:267
@ EVMC_WASM_TRAP
A WebAssembly trap has been hit during execution.
Definition: evmc.h:297
@ EVMC_PRECOMPILE_FAILURE
A call to a precompiled or system contract has ended with a failure.
Definition: evmc.h:274
@ EVMC_INTERNAL_ERROR
EVM implementation generic internal error.
Definition: evmc.h:303
@ EVMC_OUT_OF_GAS
The execution has run out of gas.
Definition: evmc.h:229
@ EVMC_CONTRACT_VALIDATION_FAILURE
Contract validation has failed (e.g.
Definition: evmc.h:280
@ EVMC_CALL_DEPTH_EXCEEDED
Call depth has exceeded the limit (if any)
Definition: evmc.h:264
@ EVMC_WASM_UNREACHABLE_INSTRUCTION
A WebAssembly unreachable instruction has been hit during execution.
Definition: evmc.h:291
@ EVMC_STACK_OVERFLOW
The execution has attempted to put more items on the EVM stack than the specified limit.
Definition: evmc.h:248
@ EVMC_FAILURE
Generic execution failure.
Definition: evmc.h:218
@ EVMC_REVERT
Execution terminated with REVERT opcode.
Definition: evmc.h:226

◆ evmc_storage_status

The effect of an attempt to modify a contract storage item.

For the purpose of explaining the meaning of each element, the following notation is used:

  • 0 is zero value,
  • X != 0 (X is any value other than 0),
  • Y != X, Y != 0 (Y is any value other than X and 0),
  • Z != Y (Z is any value other than Y),
  • the "->" means the change from one value to another.
Enumerator
EVMC_STORAGE_UNCHANGED 

The value of a storage item has been left unchanged: 0 -> 0 and X -> X.

EVMC_STORAGE_MODIFIED 

The value of a storage item has been modified: X -> Y.

EVMC_STORAGE_MODIFIED_AGAIN 

A storage item has been modified after being modified before: X -> Y -> Z.

EVMC_STORAGE_ADDED 

A new storage item has been added: 0 -> X.

EVMC_STORAGE_DELETED 

A storage item has been deleted: X -> 0.

Definition at line 463 of file evmc.h.

464 {
469 
474 
479 
483  EVMC_STORAGE_ADDED = 3,
484 
489 };
@ EVMC_STORAGE_MODIFIED_AGAIN
A storage item has been modified after being modified before: X -> Y -> Z.
Definition: evmc.h:478
@ EVMC_STORAGE_ADDED
A new storage item has been added: 0 -> X.
Definition: evmc.h:483
@ EVMC_STORAGE_UNCHANGED
The value of a storage item has been left unchanged: 0 -> 0 and X -> X.
Definition: evmc.h:468
@ EVMC_STORAGE_DELETED
A storage item has been deleted: X -> 0.
Definition: evmc.h:488
@ EVMC_STORAGE_MODIFIED
The value of a storage item has been modified: X -> Y.
Definition: evmc.h:473

Function Documentation

◆ evmc_create_example_vm()

struct evmc_vm* evmc_create_example_vm ( void  )

Example of a function creating an instance of an example EVM implementation.

Each EVM implementation MUST provide a function returning an EVM instance. The function SHOULD be named evmc_create_<vm-name>(void). If the VM name contains hyphens replaces them with underscores in the function names.

Binaries naming convention
For VMs distributed as shared libraries, the name of the library SHOULD match the VM name. The convetional library filename prefixes and extensions SHOULD be ignored by the Client. For example, the shared library with the "beta-interpreter" implementation may be named libbeta-interpreter.so.
Returns
The VM instance or NULL indicating instance creation failure.

Definition at line 392 of file example_vm.cpp.

393 {
394  return new ExampleVM;
395 }