EVM-C – C interface to Ethereum Virtual Machine. More...

Classes
struct	evm_uint256be
	Big-endian 256-bit integer. More...

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

struct	evm_result
	The EVM code execution result. More...

union	evm_variant
	Variant type to represent possible types of values used in EVM. More...

struct	evm_instance
	The EVM instance. More...

struct	evm_factory
	The EVM instance factory. More...

Typedefs
typedef void(*	evm_release_result_fn) (struct evm_result const *result)
	Forward declaration. More...

typedef void(*	evm_query_fn) (union evm_variant result, struct evm_env env, enum evm_query_key key, const union evm_variant *arg)
	Query callback function. More...

typedef void(*	evm_update_fn) (struct evm_env env, enum evm_update_key key, const union evm_variant arg1, const union evm_variant *arg2)
	Update callback function. More...

typedef int64_t(*	evm_call_fn) (struct evm_env env, enum evm_call_kind kind, int64_t gas, const struct evm_uint160be address, const struct evm_uint256be value, uint8_t const input, size_t input_size, uint8_t *output, size_t output_size)
	Pointer to the callback function supporting EVM calls. More...

typedef struct evm_instance (	evm_create_fn) (evm_query_fn query_fn, evm_update_fn update_fn, evm_call_fn call_fn)
	Forward declaration. More...

typedef void(*	evm_destroy_fn) (struct evm_instance *evm)
	Destroys the EVM instance. More...

typedef int(*	evm_set_option_fn) (struct evm_instance evm, char const name, char const *value)
	Configures the EVM instance. More...

typedef struct evm_result(*	evm_execute_fn) (struct evm_instance instance, struct evm_env env, enum evm_mode mode, struct evm_uint256be code_hash, uint8_t const code, size_t code_size, int64_t gas, uint8_t const input, size_t input_size, struct evm_uint256be value)
	Generates and executes machine code for given EVM bytecode. More...

typedef enum evm_code_status(*	evm_get_code_status_fn) (struct evm_instance *instance, enum evm_mode mode, struct evm_uint256be code_hash)
	Get information the status of the code in the VM. More...

typedef void(*	evm_prepare_code_fn) (struct evm_instance instance, enum evm_mode mode, struct evm_uint256be code_hash, uint8_t const code, size_t code_size)
	Request preparation of the code for faster execution. More...

Enumerations
enum	{ EVM_ABI_VERSION = 0 }
	The EVM-C ABI version number matching the interface declared in this file. More...

enum	evm_result_code { EVM_SUCCESS = 0, EVM_FAILURE = 1, EVM_OUT_OF_GAS = 2, EVM_BAD_INSTRUCTION = 3, EVM_BAD_JUMP_DESTINATION = 4, EVM_STACK_OVERFLOW = 5, EVM_STACK_UNDERFLOW = 6 }
	The execution result code. More...

enum	evm_query_key { EVM_SLOAD = 0, EVM_ADDRESS = 1, EVM_CALLER = 2, EVM_ORIGIN = 3, EVM_GAS_PRICE = 4, EVM_COINBASE = 5, EVM_DIFFICULTY = 6, EVM_GAS_LIMIT = 7, EVM_NUMBER = 8, EVM_TIMESTAMP = 9, EVM_CODE_BY_ADDRESS = 10, EVM_CODE_SIZE = 11, EVM_BALANCE = 12, EVM_BLOCKHASH = 13, EVM_ACCOUNT_EXISTS = 14, EVM_CALL_DEPTH = 15 }
	The query callback key. More...

enum	evm_update_key { EVM_SSTORE = 0, EVM_LOG = 1, EVM_SELFDESTRUCT = 2 }
	The update callback key. More...

enum	evm_call_kind { EVM_CALL = 0, EVM_DELEGATECALL = 1, EVM_CALLCODE = 2, EVM_CREATE = 3 }
	The kind of call-like instruction. More...

enum	evm_mode { EVM_FRONTIER = 0, EVM_HOMESTEAD = 1, EVM_ANTI_DOS = 2, EVM_CLEARING = 3 }
	EVM compatibility mode aka chain mode. More...

enum	evm_code_status { EVM_UNKNOWN, EVM_READY, EVM_CACHED }
	Status of a code in VM. Useful for JIT-like implementations. More...

Functions
struct evm_factory	examplevm_get_factory (void)
	Example of a function creating uninitialized instance of an example VM. More...

Detailed Description

EVM-C – C interface to Ethereum Virtual Machine.

High level design rules

Pass function arguments and results by value. This rule comes from modern C++ and tries to avoid costly alias analysis needed for optimization. As the result we have a lots of complex structs and unions. And variable sized arrays of bytes cannot be passed by copy.
The EVM operates on integers so it prefers values to be host-endian. On the other hand, LLVM can generate good code for byte swaping. The interface also tries to match host application "natural" endianess. I would like to know what endianess you use and where.

Typedef Documentation

typedef int64_t(* evm_call_fn) (struct evm_env *env, enum evm_call_kind kind, int64_t gas, const struct evm_uint160be *address, const struct evm_uint256be *value, uint8_t const *input, size_t input_size, uint8_t *output, size_t output_size)

Pointer to the callback function supporting EVM calls.

Parameters

env	Pointer to execution environment managed by the host application.
kind	The kind of call-like opcode requested.
gas	The amount of gas for the call.
address	The address of a contract to be called. Ignored in case of CREATE.
value	The value sent to the callee. The endowment in case of CREATE.
input	The call input data or the CREATE init code.
input_size	The size of the input data.
output	The reference to the memory where the call output is to be copied. In case of CREATE, the memory is guaranteed to be at least 20 bytes to hold the address of the created contract.
output_data	The size of the output data. In case of CREATE, expected value is 20.

Returns: If non-negative - the amount of gas left, If negative - an exception occurred during the call/create. There is no need to set 0 address in the output in this case.

Definition at line 308 of file evm.h.

typedef struct evm_instance*(* evm_create_fn) (evm_query_fn query_fn, evm_update_fn update_fn, evm_call_fn call_fn)

Forward declaration.

Creates the EVM instance.

Creates and initializes an EVM instance by providing the information about runtime callback functions.

Parameters

query_fn	Pointer to query callback function. Nonnull.
update_fn	Pointer to update callback function. Nonnull.
call_fn	Pointer to call callback function. Nonnull.

Returns: Pointer to the created EVM instance.

Definition at line 331 of file evm.h.

typedef void(* evm_destroy_fn) (struct evm_instance *evm)

Destroys the EVM instance.

Parameters

evm	The EVM instance to be destroyed.

Definition at line 338 of file evm.h.

typedef struct evm_result(* evm_execute_fn) (struct evm_instance *instance, struct evm_env *env, enum evm_mode mode, struct evm_uint256be code_hash, uint8_t const *code, size_t code_size, int64_t gas, uint8_t const *input, size_t input_size, struct evm_uint256be value)

Generates and executes machine code for given EVM bytecode.

All the fun is here. This function actually does something useful.

Parameters

instance	A EVM instance.
env	A pointer to the execution environment provided by the user and passed to callback functions.
mode	EVM compatibility mode.
code_hash	A hash of the bytecode, usually Keccak. The EVM uses it as the code identifier. A EVM implementation is able to hash the code itself if it requires it, but the host application usually has the hash already.
code	Reference to the bytecode to be executed.
code_size	The length of the bytecode.
gas	Gas for execution. Min 0, max 2^63-1.
input	Reference to the input data.
input_size	The size of the input data.
value	Call value.

Returns: All execution results.

Definition at line 386 of file evm.h.

typedef enum evm_code_status(* evm_get_code_status_fn) (struct evm_instance *instance, enum evm_mode mode, struct evm_uint256be code_hash)

Get information the status of the code in the VM.

Definition at line 413 of file evm.h.

typedef void(* evm_prepare_code_fn) (struct evm_instance *instance, enum evm_mode mode, struct evm_uint256be code_hash, uint8_t const *code, size_t code_size)

Request preparation of the code for faster execution.

It is not required to execute the code but allows compilation of the code ahead of time in JIT-like VMs.

Definition at line 420 of file evm.h.

typedef void(* evm_query_fn) (union evm_variant *result, struct evm_env *env, enum evm_query_key key, const union evm_variant *arg)

Query callback function.

This callback function is used by the EVM to query the host application about additional data required to execute EVM code.

Parameters

env	Pointer to execution environment managed by the host application.
key	The kind of the query. See evm_query_key and details below.
arg	Additional argument to the query. It has defined value only for the subset of query keys.

Types of queries

EVM_GAS_PRICE
Parameters

arg n/a

Returns
evm_variant::uint256be The transaction gas price.
EVM_ADDRESS
Parameters

arg n/a

Returns
evm_variant::address The address of the current contract.
EVM_CALLER
Parameters

arg n/a

Returns
evm_variant::address The address of the caller.
EVM_ORIGIN
Parameters

arg n/a

Returns
evm_variant::address The address of the transaction initiator.
EVM_COINBASE
Parameters

arg n/a

Returns
evm_variant::address The address of the beneficiary of the block fees.
EVM_DIFFICULTY
Parameters

arg n/a

Returns
evm_variant::uint256be The block difficulty.
EVM_GAS_LIMIT
Parameters

arg n/a

Returns
evm_variant::uint256be The block gas limit.
EVM_NUMBER
Parameters

arg n/a

Returns
evm_variant::int64 The block number.
EVM_TIMESTAMP
Parameters

arg n/a

Returns
evm_variant::int64 The block timestamp.
EVM_CODE_BY_ADDRESS
Parameters

arg evm_variant::address The address to look up.

Returns
evm_variant::data The appropriate code for the given address or NULL if not found.
EVM_CODE_SIZE
Parameters

arg evm_variant::address The address to look up.

Returns
evm_variant::data The appropriate code size for the given address or 0 if not found.
EVM_BALANCE
Parameters

arg evm_variant::address The address to look up.

Returns
evm_variant::data The appropriate balance for the given address or 0 if not found.
EVM_BLOCKHASH
Parameters

arg evm_variant::int64 The block number to look up.

Returns
evm_variant::uint256be The hash of the requested block or 0 if not found.
EVM_SLOAD
Parameters

arg evm_variant::uint256be The index of the storage entry.

Returns
evm_variant::uint256be The current value of the storage entry.

Definition at line 232 of file evm.h.

typedef void(* evm_release_result_fn) (struct evm_result const *result)

Forward declaration.

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 resource are to be released. The result itself it not modified by this function, but becomes invalid and user should discard it as well.

Definition at line 68 of file evm.h.

typedef int(* evm_set_option_fn) (struct evm_instance *evm, char const *name, char const *value)

Configures the EVM instance.

Allows modifying options of the EVM instance. Options:

code cache behavior: on, off, read-only, ...
optimizations,

Parameters

evm	The EVM 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: 1 if the option set successfully, 0 otherwise.

Definition at line 352 of file evm.h.

typedef void(* evm_update_fn) (struct evm_env *env, enum evm_update_key key, const union evm_variant *arg1, const union evm_variant *arg2)

Update callback function.

This callback function is used by the EVM to modify contract state in the host application.

Parameters

env	Pointer to execution environment managed by the host application.
key	The kind of the update. See evm_update_key and details below.

Kinds of updates

EVM_SSTORE
Parameters

arg1 evm_variant::uint256be The index of the storage entry.

arg2 evm_variant::uint256be The value to be stored.

EVM_LOG

Parameters

arg1	evm_variant::data The log unindexed data.
arg2	evm_variant::data The log topics. The referenced data is an array of evm_uint256be[] of possible length from 0 to 4. So the valid evm_variant::data_size values are 0, 32, 64 92 and 128.

EVM_SELFDESTRUCT
Parameters

arg1 evm_variant::address The beneficiary address.

arg2 n/a

Definition at line 271 of file evm.h.

Enumeration Type Documentation

anonymous enum

The EVM-C ABI version number matching the interface declared in this file.

Enumerator
EVM_ABI_VERSION

Definition at line 28 of file evm.h.

enum evm_call_kind

The kind of call-like instruction.

Enumerator
EVM_CALL	Request CALL.
EVM_DELEGATECALL	Request DELEGATECALL. The value param ignored.
EVM_CALLCODE	Request CALLCODE.
EVM_CREATE	Request CREATE. Semantic of some params changes.

Definition at line 277 of file evm.h.

enum evm_code_status

Status of a code in VM. Useful for JIT-like implementations.

Enumerator
EVM_UNKNOWN	The code is uknown to the VM.
EVM_READY	The code has been compiled and is available in memory.
EVM_CACHED	The compiled version of the code is available in on-disk cache.

Definition at line 399 of file evm.h.

enum evm_mode

EVM compatibility mode aka chain mode.

The names for the last two hard forks come from Python implementation.

Enumerator
EVM_FRONTIER
EVM_HOMESTEAD
EVM_ANTI_DOS
EVM_CLEARING

Definition at line 359 of file evm.h.

enum evm_query_key

The query callback key.

Enumerator
EVM_SLOAD	Storage value of a given key for SLOAD.
EVM_ADDRESS	Address of the contract for ADDRESS.
EVM_CALLER	Message sender address for CALLER.
EVM_ORIGIN	Transaction origin address for ORIGIN.
EVM_GAS_PRICE	Transaction gas price for GASPRICE.
EVM_COINBASE	Current block miner address for COINBASE.
EVM_DIFFICULTY	Current block difficulty for DIFFICULTY.
EVM_GAS_LIMIT	Current block gas limit for GASLIMIT.
EVM_NUMBER	Current block number for NUMBER.
EVM_TIMESTAMP	Current block timestamp for TIMESTAMP.
EVM_CODE_BY_ADDRESS	Code by an address for EXTCODECOPY.
EVM_CODE_SIZE	Code size by an address for EXTCODESIZE.
EVM_BALANCE	Balance of a given address for BALANCE.
EVM_BLOCKHASH	Block hash of by block number for BLOCKHASH.
EVM_ACCOUNT_EXISTS	Check if an account exists.
EVM_CALL_DEPTH	Current call depth.

Definition at line 109 of file evm.h.

enum evm_result_code

The execution result code.

Enumerator
EVM_SUCCESS	Execution finished with success.
EVM_FAILURE	Generic execution failure.
EVM_OUT_OF_GAS
EVM_BAD_INSTRUCTION
EVM_BAD_JUMP_DESTINATION
EVM_STACK_OVERFLOW
EVM_STACK_UNDERFLOW

Definition at line 48 of file evm.h.

enum evm_update_key

The update callback key.

Enumerator
EVM_SSTORE	Update storage entry.
EVM_LOG	Log.
EVM_SELFDESTRUCT	Mark contract as selfdestructed and set beneficiary address.

Definition at line 238 of file evm.h.

Function Documentation

struct evm_factory examplevm_get_factory ( void )

Example of a function creating uninitialized instance of an example VM.

Each EVM implementation is obligated to provided a function returning an EVM instance. The function has to be named as <vm-name>_get_factory(void).

Returns: EVM instance.

Definition at line 72 of file examplevm.c.

Here is the caller graph for this function:

arg1	evm_variant::uint256be The index of the storage entry.
arg2	evm_variant::uint256be The value to be stored.

Classes

Typedefs

Enumerations

Functions

Detailed Description

High level design rules

Typedef Documentation

Types of queries

Kinds of updates

Enumeration Type Documentation

Function Documentation