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. 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

Host

Typedef Documentation

◆ 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 429 of file evmc.h.

◆ evmc_address

typedef struct evmc_address evmc_address

Big-endian 160-bit hash suitable for keeping an Ethereum address.

◆ 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 610 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 836 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 563 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 669 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 596 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 795 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 516 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 189 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 847 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 size 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 543 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 529 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 443 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 175 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 337 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 579 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 694 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 502 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 };
The EVMC ABI version number of the interface declared in this file.
Definition: evmc.h:47

◆ 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 };
Request CREATE.
Definition: evmc.h:81
Request CREATE2.
Definition: evmc.h:82
Request CALLCODE.
Definition: evmc.h:80
Request CALL.
Definition: evmc.h:77
Request DELEGATECALL.
Definition: evmc.h:78

◆ 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 806 of file evmc.h.

807 {
811  EVMC_CAPABILITY_EVM1 = (1u << 0),
812 
816  EVMC_CAPABILITY_EWASM = (1u << 1),
817 
828  EVMC_CAPABILITY_PRECOMPILES = (1u << 2)
829 };
The VM is capable of executing ewasm bytecode.
Definition: evmc.h:816
The VM is capable of executing EVM1 bytecode.
Definition: evmc.h:811
The VM is capable of executing the precompiled contracts defined for the range of destination address...
Definition: evmc.h:828

◆ 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 };
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.

The spec draft: https://eips.ethereum.org/EIPS/eip-1679.

EVMC_BERLIN 

The Berlin revision.

The spec draft: https://eips.ethereum.org/EIPS/eip-2070.

EVMC_MAX_REVISION 

The maximum EVM revision supported.

Definition at line 705 of file evmc.h.

706 {
712  EVMC_FRONTIER = 0,
713 
719  EVMC_HOMESTEAD = 1,
720 
727 
734 
740  EVMC_BYZANTIUM = 4,
741 
748 
756  EVMC_PETERSBURG = 6,
757 
763  EVMC_ISTANBUL = 7,
764 
770  EVMC_BERLIN = 8,
771 
774 };
The Tangerine Whistle revision.
Definition: evmc.h:726
The Berlin revision.
Definition: evmc.h:770
The Istanbul revision.
Definition: evmc.h:763
The Constantinople revision.
Definition: evmc.h:747
The Petersburg revision.
Definition: evmc.h:756
The Homestead revision.
Definition: evmc.h:719
The Frontier revision.
Definition: evmc.h:712
The Spurious Dragon revision.
Definition: evmc.h:733
The maximum EVM revision supported.
Definition: evmc.h:773
The Byzantium revision.
Definition: evmc.h:740

◆ 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_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 211 of file evmc.h.

212 {
214  EVMC_SUCCESS = 0,
215 
217  EVMC_FAILURE = 1,
218 
225  EVMC_REVERT = 2,
226 
228  EVMC_OUT_OF_GAS = 3,
229 
239 
242 
248 
251 
254 
261 
264 
267 
274 
280 
286 
291 
296  EVMC_WASM_TRAP = 16,
297 
299  EVMC_INTERNAL_ERROR = -1,
300 
312  EVMC_REJECTED = -2,
313 
315  EVMC_OUT_OF_MEMORY = -3
316 };
The VM failed to allocate the amount of memory needed for execution.
Definition: evmc.h:315
Tried to execute an operation which is restricted in static mode.
Definition: evmc.h:266
The execution has attempted to put more items on the EVM stack than the specified limit...
Definition: evmc.h:247
Execution of an opcode has required more items on the EVM stack.
Definition: evmc.h:250
Call depth has exceeded the limit (if any)
Definition: evmc.h:263
The execution of the given code and/or message has been rejected by the EVM implementation.
Definition: evmc.h:312
An argument to a state accessing method has a value outside of the accepted range of values...
Definition: evmc.h:285
A WebAssembly unreachable instruction has been hit during execution.
Definition: evmc.h:290
A WebAssembly trap has been hit during execution.
Definition: evmc.h:296
Tried to read outside memory bounds.
Definition: evmc.h:260
An undefined instruction has been encountered.
Definition: evmc.h:241
EVM implementation generic internal error.
Definition: evmc.h:299
The designated INVALID instruction has been hit during execution.
Definition: evmc.h:238
Execution terminated with REVERT opcode.
Definition: evmc.h:225
Execution has violated the jump destination restrictions.
Definition: evmc.h:253
A call to a precompiled or system contract has ended with a failure.
Definition: evmc.h:273
Contract validation has failed (e.g.
Definition: evmc.h:279
The execution has run out of gas.
Definition: evmc.h:228
Generic execution failure.
Definition: evmc.h:217
Execution finished with success.
Definition: evmc.h:214

◆ 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 459 of file evmc.h.

460 {
465 
470 
475 
479  EVMC_STORAGE_ADDED = 3,
480 
485 };
A storage item has been deleted: X -> 0.
Definition: evmc.h:484
The value of a storage item has been modified: X -> Y.
Definition: evmc.h:469
A storage item has been modified after being modified before: X -> Y -> Z.
Definition: evmc.h:474
The value of a storage item has been left unchanged: 0 -> 0 and X -> X.
Definition: evmc.h:464
A new storage item has been added: 0 -> X.
Definition: evmc.h:479

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 219 of file example_vm.c.

220 {
221  struct evmc_vm init = {
223  .name = "example_vm",
224  .version = PROJECT_VERSION,
225  .destroy = destroy,
226  .execute = execute,
227  .get_capabilities = get_capabilities,
228  .set_option = set_option,
229  };
230  struct example_vm* vm = calloc(1, sizeof(struct example_vm));
231  struct evmc_vm* interface = &vm->instance;
232  memcpy(interface, &init, sizeof(init));
233  return interface;
234 }
static enum evmc_set_option_result set_option(struct evmc_vm *instance, const char *name, const char *value)
Example VM options.
Definition: example_vm.c:46
static evmc_capabilities_flagset get_capabilities(struct evmc_vm *vm)
The example implementation of the evmc_vm::get_capabilities() method.
Definition: example_vm.c:36
static void destroy(struct evmc_vm *vm)
The implementation of the evmc_vm::destroy() method.
Definition: example_vm.c:30
struct evmc_vm instance
The base struct.
Definition: example_vm.c:25
const int abi_version
EVMC ABI version implemented by the VM instance.
Definition: evmc.h:863
The example VM instance struct extending the evmc_vm.
Definition: example_vm.c:23
The EVMC ABI version number of the interface declared in this file.
Definition: evmc.h:47
The VM instance.
Definition: evmc.h:855
static struct evmc_result execute(struct evmc_vm *instance, const struct evmc_host_interface *host, struct evmc_host_context *context, enum evmc_revision rev, const struct evmc_message *msg, const uint8_t *code, size_t code_size)
The example implementation of the evmc_vm::execute() method.
Definition: example_vm.c:77