EVMC
evmc.h
Go to the documentation of this file.
1 
11 #ifndef EVMC_H
12 #define EVMC_H
13 
14 #if defined(__clang__) || (defined(__GNUC__) && __GNUC__ >= 6)
21 #define EVMC_DEPRECATED __attribute__((deprecated))
22 #else
23 #define EVMC_DEPRECATED
24 #endif
25 
26 
27 #include <stdbool.h> /* Definition of bool, true and false. */
28 #include <stddef.h> /* Definition of size_t. */
29 #include <stdint.h> /* Definition of int64_t, uint64_t. */
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /* BEGIN Python CFFI declarations */
36 
37 enum
38 {
47  EVMC_ABI_VERSION = 10
48 };
49 
50 
56 typedef struct evmc_bytes32
57 {
59  uint8_t bytes[32];
61 
65 typedef struct evmc_bytes32 evmc_uint256be;
66 
68 typedef struct evmc_address
69 {
71  uint8_t bytes[20];
73 
76 {
77  EVMC_CALL = 0,
78  EVMC_DELEGATECALL = 1,
82  EVMC_CREATE2 = 4
83 };
84 
87 {
88  EVMC_STATIC = 1
89 };
90 
97 {
99  enum evmc_call_kind kind;
100 
105  uint32_t flags;
106 
112  int32_t depth;
113 
119  int64_t gas;
120 
133 
143 
151  const uint8_t* input_data;
152 
158  size_t input_size;
159 
167 
175 
190 };
191 
192 
195 {
199  int64_t block_number;
200  int64_t block_timestamp;
201  int64_t block_gas_limit;
205 };
206 
212 struct evmc_host_context;
213 
223 typedef struct evmc_tx_context (*evmc_get_tx_context_fn)(struct evmc_host_context* context);
224 
237 typedef evmc_bytes32 (*evmc_get_block_hash_fn)(struct evmc_host_context* context, int64_t number);
238 
260 {
263 
266 
274 
277 
287 
290 
296 
299 
302 
309 
312 
315 
322 
328 
334 
339 
345 
348 
351 
364 
366  EVMC_OUT_OF_MEMORY = -3
367 };
368 
369 /* Forward declaration. */
370 struct evmc_result;
371 
388 typedef void (*evmc_release_result_fn)(const struct evmc_result* result);
389 
392 {
395 
402  int64_t gas_left;
403 
415  const uint8_t* output_data;
416 
422  size_t output_size;
423 
444 
455 
467  uint8_t padding[4];
468 };
469 
470 
480 typedef bool (*evmc_account_exists_fn)(struct evmc_host_context* context,
481  const evmc_address* address);
482 
495  const evmc_address* address,
496  const evmc_bytes32* key);
497 
498 
511 {
516 
521 
526 
531 
536 };
537 
538 
553 typedef enum evmc_storage_status (*evmc_set_storage_fn)(struct evmc_host_context* context,
554  const evmc_address* address,
555  const evmc_bytes32* key,
556  const evmc_bytes32* value);
557 
568  const evmc_address* address);
569 
580 typedef size_t (*evmc_get_code_size_fn)(struct evmc_host_context* context,
581  const evmc_address* address);
582 
595  const evmc_address* address);
596 
614 typedef size_t (*evmc_copy_code_fn)(struct evmc_host_context* context,
615  const evmc_address* address,
616  size_t code_offset,
617  uint8_t* buffer_data,
618  size_t buffer_size);
619 
630 typedef void (*evmc_selfdestruct_fn)(struct evmc_host_context* context,
631  const evmc_address* address,
632  const evmc_address* beneficiary);
633 
647 typedef void (*evmc_emit_log_fn)(struct evmc_host_context* context,
648  const evmc_address* address,
649  const uint8_t* data,
650  size_t data_size,
651  const evmc_bytes32 topics[],
652  size_t topics_count);
653 
658 {
663 
667  EVMC_ACCESS_WARM = 1
668 };
669 
681 typedef enum evmc_access_status (*evmc_access_account_fn)(struct evmc_host_context* context,
682  const evmc_address* address);
683 
696 typedef enum evmc_access_status (*evmc_access_storage_fn)(struct evmc_host_context* context,
697  const evmc_address* address,
698  const evmc_bytes32* key);
699 
707 typedef struct evmc_result (*evmc_call_fn)(struct evmc_host_context* context,
708  const struct evmc_message* msg);
709 
719 {
722 
725 
728 
731 
734 
737 
740 
743 
746 
749 
752 
755 
758 
761 };
762 
763 
764 /* Forward declaration. */
765 struct evmc_vm;
766 
772 typedef void (*evmc_destroy_fn)(struct evmc_vm* vm);
773 
778 {
779  EVMC_SET_OPTION_SUCCESS = 0,
780  EVMC_SET_OPTION_INVALID_NAME = 1,
781  EVMC_SET_OPTION_INVALID_VALUE = 2
782 };
783 
797 typedef enum evmc_set_option_result (*evmc_set_option_fn)(struct evmc_vm* vm,
798  char const* name,
799  char const* value);
800 
801 
809 {
816 
823 
830 
837 
844 
851 
860 
867 
874 
881 
888 
891 
898 };
899 
900 
919 typedef struct evmc_result (*evmc_execute_fn)(struct evmc_vm* vm,
920  const struct evmc_host_interface* host,
921  struct evmc_host_context* context,
922  enum evmc_revision rev,
923  const struct evmc_message* msg,
924  uint8_t const* code,
925  size_t code_size);
926 
931 {
935  EVMC_CAPABILITY_EVM1 = (1u << 0),
936 
941 
952  EVMC_CAPABILITY_PRECOMPILES = (1u << 2)
953 };
954 
960 typedef uint32_t evmc_capabilities_flagset;
961 
972 
973 
979 struct evmc_vm
980 {
987  const int abi_version;
988 
995  const char* name;
996 
1003  const char* version;
1004 
1011 
1018 
1030 
1037 };
1038 
1039 /* END Python CFFI declarations */
1040 
1041 #ifdef EVMC_DOCUMENTATION
1057 struct evmc_vm* evmc_create_example_vm(void);
1058 #endif
1059 
1060 #ifdef __cplusplus
1061 }
1062 #endif
1063 
1064 #endif
struct evmc_address evmc_address
Big-endian 160-bit hash suitable for keeping an Ethereum address.
evmc_flags
The flags for evmc_message.
Definition: evmc.h:87
void(* evmc_destroy_fn)(struct evmc_vm *vm)
Destroys the VM instance.
Definition: evmc.h:772
struct evmc_bytes32 evmc_uint256be
The alias for evmc_bytes32 to represent a big-endian 256-bit integer.
Definition: evmc.h:65
evmc_set_option_result
Possible outcomes of evmc_set_option.
Definition: evmc.h:778
void(* evmc_release_result_fn)(const struct evmc_result *result)
Releases resources assigned to an execution result.
Definition: evmc.h:388
size_t(* evmc_get_code_size_fn)(struct evmc_host_context *context, const evmc_address *address)
Get code size callback function.
Definition: evmc.h:580
evmc_capabilities
Possible capabilities of a VM.
Definition: evmc.h:931
evmc_status_code
The execution status code.
Definition: evmc.h:260
bool(* evmc_account_exists_fn)(struct evmc_host_context *context, const evmc_address *address)
Check account existence callback function.
Definition: evmc.h:480
evmc_uint256be(* evmc_get_balance_fn)(struct evmc_host_context *context, const evmc_address *address)
Get balance callback function.
Definition: evmc.h:567
struct evmc_result(* evmc_call_fn)(struct evmc_host_context *context, const struct evmc_message *msg)
Pointer to the callback function supporting EVM calls.
Definition: evmc.h:707
enum evmc_set_option_result(* evmc_set_option_fn)(struct evmc_vm *vm, char const *name, char const *value)
Configures the VM instance.
Definition: evmc.h:797
uint32_t evmc_capabilities_flagset
Alias for unsigned integer representing a set of bit flags of EVMC capabilities.
Definition: evmc.h:960
void(* evmc_selfdestruct_fn)(struct evmc_host_context *context, const evmc_address *address, const evmc_address *beneficiary)
Selfdestruct callback function.
Definition: evmc.h:630
evmc_bytes32(* evmc_get_code_hash_fn)(struct evmc_host_context *context, const evmc_address *address)
Get code hash callback function.
Definition: evmc.h:594
evmc_bytes32(* evmc_get_storage_fn)(struct evmc_host_context *context, const evmc_address *address, const evmc_bytes32 *key)
Get storage callback function.
Definition: evmc.h:494
struct evmc_tx_context(* evmc_get_tx_context_fn)(struct evmc_host_context *context)
Get transaction context callback function.
Definition: evmc.h:223
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.
Definition: evmc.h:614
enum evmc_access_status(* evmc_access_account_fn)(struct evmc_host_context *context, const evmc_address *address)
Access account callback function.
Definition: evmc.h:681
evmc_bytes32(* evmc_get_block_hash_fn)(struct evmc_host_context *context, int64_t number)
Get block hash callback function.
Definition: evmc.h:237
evmc_capabilities_flagset(* evmc_get_capabilities_fn)(struct evmc_vm *vm)
Return the supported capabilities of the VM instance.
Definition: evmc.h:971
evmc_access_status
Access status per EIP-2929: Gas cost increases for state access opcodes.
Definition: evmc.h:658
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.
Definition: evmc.h:647
struct evmc_bytes32 evmc_bytes32
The fixed size array of 32 bytes.
evmc_call_kind
The kind of call-like instruction.
Definition: evmc.h:76
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.
Definition: evmc.h:696
struct evmc_vm * evmc_create_example_vm(void)
Example of a function creating an instance of an example EVM implementation.
Definition: example_vm.cpp:392
evmc_storage_status
The effect of an attempt to modify a contract storage item.
Definition: evmc.h:511
evmc_revision
EVM revision.
Definition: evmc.h:809
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.
Definition: evmc.h:919
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.
Definition: evmc.h:553
@ EVMC_ABI_VERSION
The EVMC ABI version number of the interface declared in this file.
Definition: evmc.h:47
@ EVMC_STATIC
Static call mode.
Definition: evmc.h:88
@ EVMC_CAPABILITY_EVM1
The VM is capable of executing EVM1 bytecode.
Definition: evmc.h:935
@ EVMC_CAPABILITY_PRECOMPILES
The VM is capable of executing the precompiled contracts defined for the range of code addresses.
Definition: evmc.h:952
@ EVMC_CAPABILITY_EWASM
The VM is capable of executing ewasm bytecode.
Definition: evmc.h:940
@ EVMC_INSUFFICIENT_BALANCE
The caller does not have enough funds for value transfer.
Definition: evmc.h:347
@ 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:333
@ EVMC_INVALID_MEMORY_ACCESS
Tried to read outside memory bounds.
Definition: evmc.h:308
@ EVMC_REJECTED
The execution of the given code and/or message has been rejected by the EVM implementation.
Definition: evmc.h:363
@ EVMC_UNDEFINED_INSTRUCTION
An undefined instruction has been encountered.
Definition: evmc.h:289
@ EVMC_SUCCESS
Execution finished with success.
Definition: evmc.h:262
@ EVMC_OUT_OF_MEMORY
The VM failed to allocate the amount of memory needed for execution.
Definition: evmc.h:366
@ EVMC_STACK_UNDERFLOW
Execution of an opcode has required more items on the EVM stack.
Definition: evmc.h:298
@ EVMC_BAD_JUMP_DESTINATION
Execution has violated the jump destination restrictions.
Definition: evmc.h:301
@ EVMC_INVALID_INSTRUCTION
The designated INVALID instruction has been hit during execution.
Definition: evmc.h:286
@ EVMC_STATIC_MODE_VIOLATION
Tried to execute an operation which is restricted in static mode.
Definition: evmc.h:314
@ EVMC_WASM_TRAP
A WebAssembly trap has been hit during execution.
Definition: evmc.h:344
@ EVMC_PRECOMPILE_FAILURE
A call to a precompiled or system contract has ended with a failure.
Definition: evmc.h:321
@ EVMC_INTERNAL_ERROR
EVM implementation generic internal error.
Definition: evmc.h:350
@ EVMC_OUT_OF_GAS
The execution has run out of gas.
Definition: evmc.h:276
@ EVMC_CONTRACT_VALIDATION_FAILURE
Contract validation has failed (e.g.
Definition: evmc.h:327
@ EVMC_CALL_DEPTH_EXCEEDED
Call depth has exceeded the limit (if any)
Definition: evmc.h:311
@ EVMC_WASM_UNREACHABLE_INSTRUCTION
A WebAssembly unreachable instruction has been hit during execution.
Definition: evmc.h:338
@ EVMC_STACK_OVERFLOW
The execution has attempted to put more items on the EVM stack than the specified limit.
Definition: evmc.h:295
@ EVMC_FAILURE
Generic execution failure.
Definition: evmc.h:265
@ EVMC_REVERT
Execution terminated with REVERT opcode.
Definition: evmc.h:273
@ EVMC_ACCESS_COLD
The entry hasn't been accessed before – it's the first access.
Definition: evmc.h:662
@ EVMC_ACCESS_WARM
The entry is already in accessed_addresses or accessed_storage_keys.
Definition: evmc.h:667
@ 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_STORAGE_MODIFIED_AGAIN
A storage item has been modified after being modified before: X -> Y -> Z.
Definition: evmc.h:525
@ EVMC_STORAGE_ADDED
A new storage item has been added: 0 -> X.
Definition: evmc.h:530
@ EVMC_STORAGE_UNCHANGED
The value of a storage item has been left unchanged: 0 -> 0 and X -> X.
Definition: evmc.h:515
@ EVMC_STORAGE_DELETED
A storage item has been deleted: X -> 0.
Definition: evmc.h:535
@ EVMC_STORAGE_MODIFIED
The value of a storage item has been modified: X -> Y.
Definition: evmc.h:520
@ EVMC_HOMESTEAD
The Homestead revision.
Definition: evmc.h:822
@ EVMC_LATEST_STABLE_REVISION
The latest known EVM revision with finalized specification.
Definition: evmc.h:897
@ EVMC_ISTANBUL
The Istanbul revision.
Definition: evmc.h:866
@ EVMC_FRONTIER
The Frontier revision.
Definition: evmc.h:815
@ EVMC_PETERSBURG
The Petersburg revision.
Definition: evmc.h:859
@ EVMC_CONSTANTINOPLE
The Constantinople revision.
Definition: evmc.h:850
@ EVMC_TANGERINE_WHISTLE
The Tangerine Whistle revision.
Definition: evmc.h:829
@ EVMC_MAX_REVISION
The maximum EVM revision supported.
Definition: evmc.h:890
@ EVMC_SPURIOUS_DRAGON
The Spurious Dragon revision.
Definition: evmc.h:836
@ EVMC_BYZANTIUM
The Byzantium revision.
Definition: evmc.h:843
@ EVMC_SHANGHAI
The Shanghai revision.
Definition: evmc.h:887
@ EVMC_LONDON
The London revision.
Definition: evmc.h:880
@ EVMC_BERLIN
The Berlin revision.
Definition: evmc.h:873
Big-endian 160-bit hash suitable for keeping an Ethereum address.
Definition: evmc.h:69
uint8_t bytes[20]
The 20 bytes of the hash.
Definition: evmc.h:71
The fixed size array of 32 bytes.
Definition: evmc.h:57
uint8_t bytes[32]
The 32 bytes.
Definition: evmc.h:59
The opaque data type representing the Host execution context.
The Host interface.
Definition: evmc.h:719
evmc_get_code_hash_fn get_code_hash
Get code hash callback function.
Definition: evmc.h:736
evmc_call_fn call
Call callback function.
Definition: evmc.h:745
evmc_selfdestruct_fn selfdestruct
Selfdestruct callback function.
Definition: evmc.h:742
evmc_get_storage_fn get_storage
Get storage callback function.
Definition: evmc.h:724
evmc_copy_code_fn copy_code
Copy code callback function.
Definition: evmc.h:739
evmc_get_code_size_fn get_code_size
Get code size callback function.
Definition: evmc.h:733
evmc_get_block_hash_fn get_block_hash
Get block hash callback function.
Definition: evmc.h:751
evmc_emit_log_fn emit_log
Emit log callback function.
Definition: evmc.h:754
evmc_account_exists_fn account_exists
Check account existence callback function.
Definition: evmc.h:721
evmc_access_account_fn access_account
Access account callback function.
Definition: evmc.h:757
evmc_get_balance_fn get_balance
Get balance callback function.
Definition: evmc.h:730
evmc_set_storage_fn set_storage
Set storage callback function.
Definition: evmc.h:727
evmc_get_tx_context_fn get_tx_context
Get transaction context callback function.
Definition: evmc.h:748
evmc_access_storage_fn access_storage
Access storage callback function.
Definition: evmc.h:760
The message describing an EVM call, including a zero-depth calls from a transaction origin.
Definition: evmc.h:97
const uint8_t * input_data
The message input data.
Definition: evmc.h:151
evmc_bytes32 create2_salt
The optional value used in new contract address construction.
Definition: evmc.h:174
size_t input_size
The size of the message input data.
Definition: evmc.h:158
evmc_address recipient
The recipient of the message.
Definition: evmc.h:132
enum evmc_call_kind kind
The kind of the call.
Definition: evmc.h:99
int32_t depth
The present depth of the message call stack.
Definition: evmc.h:112
uint32_t flags
Additional flags modifying the call execution behavior.
Definition: evmc.h:105
evmc_address code_address
The address of the code to be executed.
Definition: evmc.h:189
evmc_uint256be value
The amount of Ether transferred with the message.
Definition: evmc.h:166
evmc_address sender
The sender of the message.
Definition: evmc.h:142
int64_t gas
The amount of gas available to the message execution.
Definition: evmc.h:119
The EVM code execution result.
Definition: evmc.h:392
const uint8_t * output_data
The reference to output data.
Definition: evmc.h:415
enum evmc_status_code status_code
The execution status code.
Definition: evmc.h:394
evmc_release_result_fn release
The method releasing all resources associated with the result object.
Definition: evmc.h:443
size_t output_size
The size of the output data.
Definition: evmc.h:422
uint8_t padding[4]
Reserved data that MAY be used by a evmc_result object creator.
Definition: evmc.h:467
evmc_address create_address
The address of the contract created by create instructions.
Definition: evmc.h:454
int64_t gas_left
The amount of gas left after the execution.
Definition: evmc.h:402
The transaction and block data for execution.
Definition: evmc.h:195
evmc_address tx_origin
The transaction origin account.
Definition: evmc.h:197
evmc_uint256be block_base_fee
The block base fee per gas (EIP-1559, EIP-3198).
Definition: evmc.h:204
int64_t block_number
The block number.
Definition: evmc.h:199
int64_t block_timestamp
The block timestamp.
Definition: evmc.h:200
evmc_uint256be tx_gas_price
The transaction gas price.
Definition: evmc.h:196
evmc_uint256be chain_id
The blockchain's ChainID.
Definition: evmc.h:203
evmc_address block_coinbase
The miner of the block.
Definition: evmc.h:198
int64_t block_gas_limit
The block gas limit.
Definition: evmc.h:201
evmc_uint256be block_difficulty
The block difficulty.
Definition: evmc.h:202
The VM instance.
Definition: evmc.h:980
evmc_set_option_fn set_option
Optional pointer to function modifying VM's options.
Definition: evmc.h:1036
evmc_get_capabilities_fn get_capabilities
A method returning capabilities supported by the VM instance.
Definition: evmc.h:1029
evmc_execute_fn execute
Pointer to function executing a code by the VM instance.
Definition: evmc.h:1017
const char * name
The name of the EVMC VM implementation.
Definition: evmc.h:995
evmc_destroy_fn destroy
Pointer to function destroying the VM instance.
Definition: evmc.h:1010
const int abi_version
EVMC ABI version implemented by the VM instance.
Definition: evmc.h:987
const char * version
The version of the EVMC VM implementation, e.g.
Definition: evmc.h:1003