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_initcode
	The hashed initcode used for TXCREATE instruction. 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.

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_initcode	evmc_tx_initcode
	The hashed initcode used for TXCREATE instruction.

typedef struct evmc_tx_context(*	evmc_get_tx_context_fn) (struct evmc_host_context *context)
	Get transaction context callback function.

typedef evmc_bytes32(*	evmc_get_block_hash_fn) (struct evmc_host_context *context, int64_t number)
	Get block hash callback function.

typedef void(*	evmc_release_result_fn) (const struct evmc_result *result)
	Releases resources assigned to an execution result.

typedef bool(*	evmc_account_exists_fn) (struct evmc_host_context context, const evmc_address address)
	Check account existence callback function.

typedef evmc_bytes32(*	evmc_get_storage_fn) (struct evmc_host_context context, const evmc_address address, const evmc_bytes32 *key)
	Get storage callback function.

typedef evmc_bytes32(*	evmc_get_transient_storage_fn) (struct evmc_host_context context, const evmc_address address, const evmc_bytes32 *key)
	Get transient storage callback function.

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.

typedef void(*	evmc_set_transient_storage_fn) (struct evmc_host_context context, const evmc_address address, const evmc_bytes32 key, const evmc_bytes32 value)
	Set transient storage callback function.

typedef evmc_uint256be(*	evmc_get_balance_fn) (struct evmc_host_context context, const evmc_address address)
	Get balance callback function.

typedef size_t(*	evmc_get_code_size_fn) (struct evmc_host_context context, const evmc_address address)
	Get code size callback function.

typedef evmc_bytes32(*	evmc_get_code_hash_fn) (struct evmc_host_context context, const evmc_address address)
	Get code hash callback function.

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.

typedef bool(*	evmc_selfdestruct_fn) (struct evmc_host_context context, const evmc_address address, const evmc_address *beneficiary)
	Selfdestruct callback function.

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.

typedef enum evmc_access_status(*	evmc_access_account_fn) (struct evmc_host_context context, const evmc_address address)
	Access account callback function.

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.

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.

typedef void(*	evmc_destroy_fn) (struct evmc_vm *vm)
	Destroys the VM instance.

typedef enum evmc_set_option_result(*	evmc_set_option_fn) (struct evmc_vm vm, char const name, char const *value)
	Configures the VM instance.

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.

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

typedef evmc_capabilities_flagset(*	evmc_get_capabilities_fn) (struct evmc_vm *vm)
	Return the supported capabilities of the VM instance.

Enumerations
enum	{ EVMC_ABI_VERSION = 12 }

enum	evmc_call_kind { EVMC_CALL = 0 , EVMC_DELEGATECALL = 1 , EVMC_CALLCODE = 2 , EVMC_CREATE = 3 , EVMC_CREATE2 = 4 , EVMC_EOFCREATE = 5 }
	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_ASSIGNED = 0 , EVMC_STORAGE_ADDED = 1 , EVMC_STORAGE_DELETED = 2 , EVMC_STORAGE_MODIFIED = 3 , EVMC_STORAGE_DELETED_ADDED = 4 , EVMC_STORAGE_MODIFIED_DELETED = 5 , EVMC_STORAGE_DELETED_RESTORED = 6 , EVMC_STORAGE_ADDED_DELETED = 7 , EVMC_STORAGE_MODIFIED_RESTORED = 8 }
	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. More...

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_PARIS = 10 , EVMC_SHANGHAI = 11 , EVMC_CANCUN = 12 , EVMC_PRAGUE = 13 , EVMC_OSAKA = 14 , EVMC_MAX_REVISION = EVMC_OSAKA , EVMC_LATEST_STABLE_REVISION = EVMC_CANCUN }
	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_vm *	evmc_create_example_vm (void)
	Example of a function creating an instance of an example EVM implementation.

Detailed Description

EVMC: Ethereum Client-VM Connector API.

Copyright: Copyright 2016 The EVMC Authors. Licensed under the Apache License, Version 2.0.

Terms

VM – An Ethereum Virtual Machine instance/implementation.
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.

Macro Definition Documentation

◆ EVMC_DEPRECATED

#define EVMC_DEPRECATED

Definition at line 23 of file evmc.h.

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

context	The Host execution context.
address	The address of the account.

Returns: EVMC_ACCESS_WARM if accessed_addresses already contained the address or EVMC_ACCESS_COLD otherwise.

Definition at line 773 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

context	The Host execution context.
address	The address of the account.
key	The 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 773 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

context	The pointer to the Host execution context.
address	The address of the account the query is about.

Returns: true if exists, false otherwise.

Definition at line 512 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

context	The pointer to the Host execution context.
msg	The call parameters.

Returns: The result of the call.

Definition at line 773 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 1120 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

context	The pointer to the Host execution context. See evmc_host_context.
address	The address of the account.
code_offset	The offset of the code to copy.
buffer_data	The pointer to the memory buffer allocated by the EVM to store a copy of the requested code.
buffer_size	The size of the memory buffer.

Returns: The number of bytes copied to the buffer by the Client.

Definition at line 738 of file evmc.h.

◆ evmc_destroy_fn

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

Destroys the VM instance.

Parameters

vm	The VM instance to be destroyed.

Definition at line 904 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

context	The pointer to the Host execution context. See evmc_host_context.
address	The address of the contract that generated the log.
data	The pointer to unindexed data attached to the log.
data_size	The length of the data.
topics	The pointer to the array of topics attached to the log.
topics_count	The number of the topics. Valid values are between 0 and 4 inclusively.

Definition at line 773 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

vm	The VM instance. This argument MUST NOT be NULL.
host	The Host interface. This argument MUST NOT be NULL unless the `vm` has the EVMC_CAPABILITY_PRECOMPILES capability.
context	The 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.
rev	The requested EVM specification revision.
msg	The call parameters. See evmc_message. This argument MUST NOT be NULL.
code	The reference to the code to be executed. This argument MAY be NULL.
code_size	The length of the code. If `code` is NULL this argument MUST be 0.

Returns: The execution result.

Definition at line 904 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

context	The pointer to the Host execution context.
address	The address of the account.

Returns: The balance of the given account or 0 if the account does not exist.

Definition at line 691 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

context	The pointer to the Host execution context.
number	The block number.

Returns: The block hash or null bytes if the information about the block is not available.

Definition at line 261 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

vm	The VM instance.

Returns: The supported capabilities of the VM.

See also: evmc_capabilities.

Definition at line 1131 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

context	The pointer to the Host execution context.
address	The 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 718 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

context	The pointer to the Host execution context.
address	The address of the account.

Returns: The size of the code in the account or 0 if the account does not exist.

Definition at line 704 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

context	The Host execution context.
address	The address of the account.
key	The 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 526 of file evmc.h.

◆ evmc_get_transient_storage_fn

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

Get transient storage callback function.

This callback function is used by a VM to query the given account transient storage (EIP-1153) entry.

Parameters

context	The Host execution context.
address	The address of the account.
key	The index of the account's transient storage entry.

Returns: The transient storage value at the given storage key or null bytes if the account does not exist.

Definition at line 542 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

context The pointer to the Host execution context.

Returns: The transaction context.

Definition at line 65 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

result The 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 412 of file evmc.h.

◆ evmc_selfdestruct_fn

typedef bool(* 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

context	The pointer to the Host execution context. See evmc_host_context.
address	The address of the contract to be selfdestructed.
beneficiary	The address where the remaining ETH is going to be transferred.

Returns: The information if the given address has not been registered as selfdestructed yet. True if registered for the first time, false otherwise.

Definition at line 756 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

vm	The VM instance to be configured.
name	The option name. NULL-terminated string. Cannot be NULL.
value	The new option value. NULL-terminated string. Cannot be NULL.

Returns: The outcome of the operation.

Definition at line 904 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::recipient).

Parameters

context	The pointer to the Host execution context.
address	The address of the account.
key	The index of the storage entry.
value	The value to be stored.

Returns: The effect on the storage item.

Definition at line 542 of file evmc.h.

◆ evmc_set_transient_storage_fn

typedef void(* evmc_set_transient_storage_fn) (struct evmc_host_context *context, const evmc_address *address, const evmc_bytes32 *key, const evmc_bytes32 *value)

Set transient storage callback function.

This callback function is used by a VM to update the given account's transient storage (EIP-1153) 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::recipient).

Parameters

context	The pointer to the Host execution context.
address	The address of the account.
key	The index of the transient storage entry.
value	The value to be stored.

Definition at line 677 of file evmc.h.

◆ evmc_uint256be

typedef struct evmc_bytes32 evmc_uint256be

The alias for evmc_bytes32 to represent a big-endian 256-bit integer.

Definition at line 65 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.

{
    EVMC_ABI_VERSION = 12
};

◆ evmc_access_status

enum 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 783 of file evmc.h.

{
    EVMC_ACCESS_COLD = 0,
 
    EVMC_ACCESS_WARM = 1
};

◆ evmc_call_kind

enum 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.
EVMC_EOFCREATE	Request EOFCREATE. Valid since Osaka.

Definition at line 75 of file evmc.h.

{
    EVMC_CALL = 0,         
    EVMC_DELEGATECALL = 1, 
    EVMC_CALLCODE = 2,     
    EVMC_CREATE = 3,       
    EVMC_CREATE2 = 4,      
    EVMC_EOFCREATE = 5     
};

◆ evmc_capabilities

enum 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 code 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 1090 of file evmc.h.

{
    EVMC_CAPABILITY_EVM1 = (1u << 0),
 
    EVMC_CAPABILITY_EWASM = (1u << 1),
 
    EVMC_CAPABILITY_PRECOMPILES = (1u << 2)
};

◆ evmc_flags

enum evmc_flags

The flags for evmc_message.

Enumerator
EVMC_STATIC	Static call mode.

Definition at line 87 of file evmc.h.

{
    EVMC_STATIC = 1 
};

◆ evmc_revision

enum 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/execution-specs/blob/master/network-upgrades/mainnet-upgrades/berlin.md
EVMC_LONDON	The London revision. https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/london.md
EVMC_PARIS	The Paris revision (aka The Merge). https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/paris.md
EVMC_SHANGHAI	The Shanghai revision. https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/shanghai.md
EVMC_CANCUN	The Cancun revision. https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/cancun.md
EVMC_PRAGUE	The Prague revision. The future next revision after Cancun.
EVMC_OSAKA	The Osaka revision. The future next revision after Prague.
EVMC_MAX_REVISION	The maximum EVM revision supported.
EVMC_LATEST_STABLE_REVISION	The latest known EVM revision with finalized specification. This is handy for EVM tools to always use the latest revision available.

Definition at line 940 of file evmc.h.

{
    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_PARIS = 10,
 
    EVMC_SHANGHAI = 11,
 
    EVMC_CANCUN = 12,
 
    EVMC_PRAGUE = 13,
 
    EVMC_OSAKA = 14,
 
    EVMC_MAX_REVISION = EVMC_OSAKA,
 
    EVMC_LATEST_STABLE_REVISION = EVMC_CANCUN
};

◆ evmc_set_option_result

enum evmc_set_option_result

Possible outcomes of evmc_set_option.

Definition at line 909 of file evmc.h.

{
    EVMC_SET_OPTION_SUCCESS = 0,
    EVMC_SET_OPTION_INVALID_NAME = 1,
    EVMC_SET_OPTION_INVALID_VALUE = 2
};

◆ evmc_status_code

enum 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 283 of file evmc.h.

{
    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
};

◆ evmc_storage_status

enum evmc_storage_status

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

See EVM Storage Change Status for additional information about design of this enum and analysis of the specification.

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 != 0, Y != X, (Y is any value other than X and 0),
Z != 0, Z != X, Z != X (Z is any value other than Y and X and 0),
the "o -> c -> v" triple describes the change status in the context of:
- o: original value (cold value before a transaction started),
- c: current storage value,
- v: new storage value to be set.

The order of elements follows EIPs introducing net storage gas costs:

EIP-2200: https://eips.ethereum.org/EIPS/eip-2200,
EIP-1283: https://eips.ethereum.org/EIPS/eip-1283.

Enumerator
EVMC_STORAGE_ASSIGNED	The new/same value is assigned to the storage item without affecting the cost structure. The storage value item is either: left unchanged (c == v) or the dirty value (o != c) is modified again (c != v). This is the group of cases related to minimal gas cost of only accessing warm storage. 0\|X -> 0 -> 0 (current value unchanged) 0\|X\|Y -> Y -> Y (current value unchanged) 0\|X -> Y -> Z (modified previously added/modified value) This is "catch all remaining" status. I.e. if all other statuses are correctly matched this status should be assigned to all remaining cases.
EVMC_STORAGE_ADDED	A new storage item is added by changing the current clean zero to a nonzero value. 0 -> 0 -> Z
EVMC_STORAGE_DELETED	A storage item is deleted by changing the current clean nonzero to the zero value. X -> X -> 0
EVMC_STORAGE_MODIFIED	A storage item is modified by changing the current clean nonzero to other nonzero value. X -> X -> Z
EVMC_STORAGE_DELETED_ADDED	A storage item is added by changing the current dirty zero to a nonzero value other than the original value. X -> 0 -> Z
EVMC_STORAGE_MODIFIED_DELETED	A storage item is deleted by changing the current dirty nonzero to the zero value and the original value is not zero. X -> Y -> 0
EVMC_STORAGE_DELETED_RESTORED	A storage item is added by changing the current dirty zero to the original value. X -> 0 -> X
EVMC_STORAGE_ADDED_DELETED	A storage item is deleted by changing the current dirty nonzero to the original zero value. 0 -> Y -> 0
EVMC_STORAGE_MODIFIED_RESTORED	A storage item is modified by changing the current dirty nonzero to the original nonzero value other than the current value. X -> Y -> X

Definition at line 568 of file evmc.h.

{
    EVMC_STORAGE_ASSIGNED = 0,
 
    EVMC_STORAGE_ADDED = 1,
 
    EVMC_STORAGE_DELETED = 2,
 
    EVMC_STORAGE_MODIFIED = 3,
 
    EVMC_STORAGE_DELETED_ADDED = 4,
 
    EVMC_STORAGE_MODIFIED_DELETED = 5,
 
    EVMC_STORAGE_DELETED_RESTORED = 6,
 
    EVMC_STORAGE_ADDED_DELETED = 7,
 
    EVMC_STORAGE_MODIFIED_RESTORED = 8
};

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

{
    return new ExampleVM;
}

Classes

Typedefs

Enumerations

Functions

Detailed Description

Terms

Responsibilities

VM

Host

Macro Definition Documentation

◆ EVMC_DEPRECATED

Typedef Documentation

◆ evmc_access_account_fn

◆ evmc_access_storage_fn

◆ evmc_account_exists_fn

◆ evmc_bytes32

◆ evmc_call_fn

◆ evmc_capabilities_flagset

◆ evmc_copy_code_fn

◆ evmc_destroy_fn

◆ evmc_emit_log_fn

◆ evmc_execute_fn

◆ evmc_get_balance_fn

◆ evmc_get_block_hash_fn

◆ evmc_get_capabilities_fn

◆ evmc_get_code_hash_fn

◆ evmc_get_code_size_fn

◆ evmc_get_storage_fn

◆ evmc_get_transient_storage_fn

◆ evmc_get_tx_context_fn

◆ evmc_release_result_fn

◆ evmc_selfdestruct_fn

◆ evmc_set_option_fn

◆ evmc_set_storage_fn

◆ evmc_set_transient_storage_fn

◆ evmc_uint256be

Enumeration Type Documentation

◆ anonymous enum

◆ evmc_access_status

◆ evmc_call_kind

◆ evmc_capabilities

◆ evmc_flags

◆ evmc_revision

◆ evmc_set_option_result

◆ evmc_status_code

◆ evmc_storage_status

Function Documentation

◆ evmc_create_example_vm()