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
32extern "C" {
33#endif
34
35/* BEGIN Python CFFI declarations */
36
37enum
38{
48};
49
50
56typedef struct evmc_bytes32
57{
59 uint8_t bytes[32];
61
66
68typedef struct evmc_address
69{
71 uint8_t bytes[20];
73
76{
82 EVMC_CREATE2 = 4
83};
84
87{
88 EVMC_STATIC = 1
89};
90
97{
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
159
167
175
190};
191
192
195{
199 int64_t block_number;
208};
209
215struct evmc_host_context;
216
226typedef struct evmc_tx_context (*evmc_get_tx_context_fn)(struct evmc_host_context* context);
227
240typedef evmc_bytes32 (*evmc_get_block_hash_fn)(struct evmc_host_context* context, int64_t number);
241
263{
266
269
277
280
290
293
299
302
305
312
315
318
325
331
337
342
348
351
354
367
371
372/* Forward declaration. */
373struct evmc_result;
374
391typedef void (*evmc_release_result_fn)(const struct evmc_result* result);
392
395{
398
405 int64_t gas_left;
406
413 int64_t gas_refund;
414
427 const uint8_t* output_data;
428
435
456
466
478 uint8_t padding[4];
479};
480
481
491typedef bool (*evmc_account_exists_fn)(struct evmc_host_context* context,
492 const evmc_address* address);
493
506 const evmc_address* address,
507 const evmc_bytes32* key);
508
522 const evmc_address* address,
523 const evmc_bytes32* key);
524
525
548{
564
571
578
585
592
599
606
613
621
622
637typedef enum evmc_storage_status (*evmc_set_storage_fn)(struct evmc_host_context* context,
638 const evmc_address* address,
639 const evmc_bytes32* key,
640 const evmc_bytes32* value);
641
656typedef void (*evmc_set_transient_storage_fn)(struct evmc_host_context* context,
657 const evmc_address* address,
658 const evmc_bytes32* key,
659 const evmc_bytes32* value);
660
671 const evmc_address* address);
672
683typedef size_t (*evmc_get_code_size_fn)(struct evmc_host_context* context,
684 const evmc_address* address);
685
698 const evmc_address* address);
699
717typedef size_t (*evmc_copy_code_fn)(struct evmc_host_context* context,
718 const evmc_address* address,
719 size_t code_offset,
720 uint8_t* buffer_data,
721 size_t buffer_size);
722
735typedef bool (*evmc_selfdestruct_fn)(struct evmc_host_context* context,
736 const evmc_address* address,
737 const evmc_address* beneficiary);
738
752typedef void (*evmc_emit_log_fn)(struct evmc_host_context* context,
753 const evmc_address* address,
754 const uint8_t* data,
755 size_t data_size,
756 const evmc_bytes32 topics[],
757 size_t topics_count);
758
763{
768
774
786typedef enum evmc_access_status (*evmc_access_account_fn)(struct evmc_host_context* context,
787 const evmc_address* address);
788
801typedef enum evmc_access_status (*evmc_access_storage_fn)(struct evmc_host_context* context,
802 const evmc_address* address,
803 const evmc_bytes32* key);
804
812typedef struct evmc_result (*evmc_call_fn)(struct evmc_host_context* context,
813 const struct evmc_message* msg);
814
824{
827
830
833
836
839
842
845
848
851
854
857
860
863
866
869
872};
873
874
875/* Forward declaration. */
876struct evmc_vm;
877
883typedef void (*evmc_destroy_fn)(struct evmc_vm* vm);
884
889{
890 EVMC_SET_OPTION_SUCCESS = 0,
891 EVMC_SET_OPTION_INVALID_NAME = 1,
892 EVMC_SET_OPTION_INVALID_VALUE = 2
893};
894
908typedef enum evmc_set_option_result (*evmc_set_option_fn)(struct evmc_vm* vm,
909 char const* name,
910 char const* value);
911
912
920{
927
934
941
948
955
962
971
978
985
992
999
1006
1014
1021
1024
1032
1033
1052typedef struct evmc_result (*evmc_execute_fn)(struct evmc_vm* vm,
1053 const struct evmc_host_interface* host,
1054 struct evmc_host_context* context,
1055 enum evmc_revision rev,
1056 const struct evmc_message* msg,
1057 uint8_t const* code,
1058 size_t code_size);
1059
1064{
1069
1074
1085 EVMC_CAPABILITY_PRECOMPILES = (1u << 2)
1087
1094
1105
1106
1113{
1120 const int abi_version;
1121
1128 const char* name;
1129
1136 const char* version;
1137
1144
1151
1163
1170};
1171
1172/* END Python CFFI declarations */
1173
1174#ifdef EVMC_DOCUMENTATION
1190struct evmc_vm* evmc_create_example_vm(void);
1191#endif
1192
1193#ifdef __cplusplus
1194}
1195#endif
1196
1197#endif
evmc_flags
The flags for evmc_message.
Definition: evmc.h:87
bool(* evmc_selfdestruct_fn)(struct evmc_host_context *context, const evmc_address *address, const evmc_address *beneficiary)
Selfdestruct callback function.
Definition: evmc.h:735
void(* evmc_destroy_fn)(struct evmc_vm *vm)
Destroys the VM instance.
Definition: evmc.h:883
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:889
void(* evmc_release_result_fn)(const struct evmc_result *result)
Releases resources assigned to an execution result.
Definition: evmc.h:391
size_t(* evmc_get_code_size_fn)(struct evmc_host_context *context, const evmc_address *address)
Get code size callback function.
Definition: evmc.h:683
evmc_capabilities
Possible capabilities of a VM.
Definition: evmc.h:1064
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_status_code
The execution status code.
Definition: evmc.h:263
bool(* evmc_account_exists_fn)(struct evmc_host_context *context, const evmc_address *address)
Check account existence callback function.
Definition: evmc.h:491
evmc_uint256be(* evmc_get_balance_fn)(struct evmc_host_context *context, const evmc_address *address)
Get balance callback function.
Definition: evmc.h:670
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:812
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:908
uint32_t evmc_capabilities_flagset
Alias for unsigned integer representing a set of bit flags of EVMC capabilities.
Definition: evmc.h:1093
evmc_bytes32(* evmc_get_code_hash_fn)(struct evmc_host_context *context, const evmc_address *address)
Get code hash callback function.
Definition: evmc.h:697
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:505
struct evmc_tx_context(* evmc_get_tx_context_fn)(struct evmc_host_context *context)
Get transaction context callback function.
Definition: evmc.h:226
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:717
enum evmc_access_status(* evmc_access_account_fn)(struct evmc_host_context *context, const evmc_address *address)
Access account callback function.
Definition: evmc.h:786
evmc_bytes32(* evmc_get_block_hash_fn)(struct evmc_host_context *context, int64_t number)
Get block hash callback function.
Definition: evmc.h:240
evmc_capabilities_flagset(* evmc_get_capabilities_fn)(struct evmc_vm *vm)
Return the supported capabilities of the VM instance.
Definition: evmc.h:1104
evmc_access_status
Access status per EIP-2929: Gas cost increases for state access opcodes.
Definition: evmc.h:763
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:752
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:801
evmc_storage_status
The effect of an attempt to modify a contract storage item.
Definition: evmc.h:548
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.
Definition: evmc.h:656
evmc_revision
EVM revision.
Definition: evmc.h:920
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:1052
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:637
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.
Definition: evmc.h:521
@ 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:1068
@ EVMC_CAPABILITY_PRECOMPILES
The VM is capable of executing the precompiled contracts defined for the range of code addresses.
Definition: evmc.h:1085
@ EVMC_CAPABILITY_EWASM
The VM is capable of executing ewasm bytecode.
Definition: evmc.h:1073
@ EVMC_INSUFFICIENT_BALANCE
The caller does not have enough funds for value transfer.
Definition: evmc.h:350
@ 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:336
@ EVMC_INVALID_MEMORY_ACCESS
Tried to read outside memory bounds.
Definition: evmc.h:311
@ EVMC_REJECTED
The execution of the given code and/or message has been rejected by the EVM implementation.
Definition: evmc.h:366
@ EVMC_UNDEFINED_INSTRUCTION
An undefined instruction has been encountered.
Definition: evmc.h:292
@ EVMC_SUCCESS
Execution finished with success.
Definition: evmc.h:265
@ EVMC_OUT_OF_MEMORY
The VM failed to allocate the amount of memory needed for execution.
Definition: evmc.h:369
@ EVMC_STACK_UNDERFLOW
Execution of an opcode has required more items on the EVM stack.
Definition: evmc.h:301
@ EVMC_BAD_JUMP_DESTINATION
Execution has violated the jump destination restrictions.
Definition: evmc.h:304
@ EVMC_INVALID_INSTRUCTION
The designated INVALID instruction has been hit during execution.
Definition: evmc.h:289
@ EVMC_STATIC_MODE_VIOLATION
Tried to execute an operation which is restricted in static mode.
Definition: evmc.h:317
@ EVMC_WASM_TRAP
A WebAssembly trap has been hit during execution.
Definition: evmc.h:347
@ EVMC_PRECOMPILE_FAILURE
A call to a precompiled or system contract has ended with a failure.
Definition: evmc.h:324
@ EVMC_INTERNAL_ERROR
EVM implementation generic internal error.
Definition: evmc.h:353
@ EVMC_OUT_OF_GAS
The execution has run out of gas.
Definition: evmc.h:279
@ EVMC_CONTRACT_VALIDATION_FAILURE
Contract validation has failed (e.g.
Definition: evmc.h:330
@ EVMC_CALL_DEPTH_EXCEEDED
Call depth has exceeded the limit (if any)
Definition: evmc.h:314
@ EVMC_WASM_UNREACHABLE_INSTRUCTION
A WebAssembly unreachable instruction has been hit during execution.
Definition: evmc.h:341
@ EVMC_STACK_OVERFLOW
The execution has attempted to put more items on the EVM stack than the specified limit.
Definition: evmc.h:298
@ EVMC_FAILURE
Generic execution failure.
Definition: evmc.h:268
@ EVMC_REVERT
Execution terminated with REVERT opcode.
Definition: evmc.h:276
@ EVMC_ACCESS_COLD
The entry hasn't been accessed before – it's the first access.
Definition: evmc.h:767
@ EVMC_ACCESS_WARM
The entry is already in accessed_addresses or accessed_storage_keys.
Definition: evmc.h:772
@ 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_ADDED_DELETED
A storage item is deleted by changing the current dirty nonzero to the original zero value.
Definition: evmc.h:612
@ EVMC_STORAGE_MODIFIED_RESTORED
A storage item is modified by changing the current dirty nonzero to the original nonzero value other ...
Definition: evmc.h:619
@ EVMC_STORAGE_DELETED_RESTORED
A storage item is added by changing the current dirty zero to the original value.
Definition: evmc.h:605
@ EVMC_STORAGE_ADDED
A new storage item is added by changing the current clean zero to a nonzero value.
Definition: evmc.h:570
@ EVMC_STORAGE_MODIFIED_DELETED
A storage item is deleted by changing the current dirty nonzero to the zero value and the original va...
Definition: evmc.h:598
@ EVMC_STORAGE_ASSIGNED
The new/same value is assigned to the storage item without affecting the cost structure.
Definition: evmc.h:563
@ EVMC_STORAGE_DELETED
A storage item is deleted by changing the current clean nonzero to the zero value.
Definition: evmc.h:577
@ EVMC_STORAGE_DELETED_ADDED
A storage item is added by changing the current dirty zero to a nonzero value other than the original...
Definition: evmc.h:591
@ EVMC_STORAGE_MODIFIED
A storage item is modified by changing the current clean nonzero to other nonzero value.
Definition: evmc.h:584
@ EVMC_HOMESTEAD
The Homestead revision.
Definition: evmc.h:933
@ EVMC_LATEST_STABLE_REVISION
The latest known EVM revision with finalized specification.
Definition: evmc.h:1030
@ EVMC_PRAGUE
The Prague revision.
Definition: evmc.h:1020
@ EVMC_ISTANBUL
The Istanbul revision.
Definition: evmc.h:977
@ EVMC_FRONTIER
The Frontier revision.
Definition: evmc.h:926
@ EVMC_PETERSBURG
The Petersburg revision.
Definition: evmc.h:970
@ EVMC_CONSTANTINOPLE
The Constantinople revision.
Definition: evmc.h:961
@ EVMC_TANGERINE_WHISTLE
The Tangerine Whistle revision.
Definition: evmc.h:940
@ EVMC_MAX_REVISION
The maximum EVM revision supported.
Definition: evmc.h:1023
@ EVMC_SPURIOUS_DRAGON
The Spurious Dragon revision.
Definition: evmc.h:947
@ EVMC_BYZANTIUM
The Byzantium revision.
Definition: evmc.h:954
@ EVMC_CANCUN
The Cancun revision.
Definition: evmc.h:1013
@ EVMC_SHANGHAI
The Shanghai revision.
Definition: evmc.h:1005
@ EVMC_LONDON
The London revision.
Definition: evmc.h:991
@ EVMC_PARIS
The Paris revision (aka The Merge).
Definition: evmc.h:998
@ EVMC_BERLIN
The Berlin revision.
Definition: evmc.h:984
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:824
evmc_get_code_hash_fn get_code_hash
Get code hash callback function.
Definition: evmc.h:841
evmc_call_fn call
Call callback function.
Definition: evmc.h:850
evmc_selfdestruct_fn selfdestruct
Selfdestruct callback function.
Definition: evmc.h:847
evmc_get_storage_fn get_storage
Get storage callback function.
Definition: evmc.h:829
evmc_copy_code_fn copy_code
Copy code callback function.
Definition: evmc.h:844
evmc_get_code_size_fn get_code_size
Get code size callback function.
Definition: evmc.h:838
evmc_get_transient_storage_fn get_transient_storage
Get transient storage callback function.
Definition: evmc.h:868
evmc_set_transient_storage_fn set_transient_storage
Set transient storage callback function.
Definition: evmc.h:871
evmc_get_block_hash_fn get_block_hash
Get block hash callback function.
Definition: evmc.h:856
evmc_emit_log_fn emit_log
Emit log callback function.
Definition: evmc.h:859
evmc_account_exists_fn account_exists
Check account existence callback function.
Definition: evmc.h:826
evmc_access_account_fn access_account
Access account callback function.
Definition: evmc.h:862
evmc_get_balance_fn get_balance
Get balance callback function.
Definition: evmc.h:835
evmc_set_storage_fn set_storage
Set storage callback function.
Definition: evmc.h:832
evmc_get_tx_context_fn get_tx_context
Get transaction context callback function.
Definition: evmc.h:853
evmc_access_storage_fn access_storage
Access storage callback function.
Definition: evmc.h:865
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:395
const uint8_t * output_data
The reference to output data.
Definition: evmc.h:427
enum evmc_status_code status_code
The execution status code.
Definition: evmc.h:397
evmc_release_result_fn release
The method releasing all resources associated with the result object.
Definition: evmc.h:455
int64_t gas_refund
The refunded gas accumulated from this execution and its sub-calls.
Definition: evmc.h:413
size_t output_size
The size of the output data.
Definition: evmc.h:434
uint8_t padding[4]
Reserved data that MAY be used by a evmc_result object creator.
Definition: evmc.h:478
evmc_address create_address
The address of the possibly created contract.
Definition: evmc.h:465
int64_t gas_left
The amount of gas left after the execution.
Definition: evmc.h:405
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
const evmc_bytes32 * blob_hashes
The array of blob hashes (EIP-4844).
Definition: evmc.h:206
evmc_uint256be tx_gas_price
The transaction gas price.
Definition: evmc.h:196
size_t blob_hashes_count
The number of blob hashes (EIP-4844).
Definition: evmc.h:207
evmc_uint256be chain_id
The blockchain's ChainID.
Definition: evmc.h:203
evmc_uint256be block_prev_randao
The block previous RANDAO (EIP-4399).
Definition: evmc.h:202
evmc_address block_coinbase
The miner of the block.
Definition: evmc.h:198
evmc_uint256be blob_base_fee
The blob base fee (EIP-7516).
Definition: evmc.h:205
int64_t block_gas_limit
The block gas limit.
Definition: evmc.h:201
The VM instance.
Definition: evmc.h:1113
evmc_set_option_fn set_option
Optional pointer to function modifying VM's options.
Definition: evmc.h:1169
evmc_get_capabilities_fn get_capabilities
A method returning capabilities supported by the VM instance.
Definition: evmc.h:1162
evmc_execute_fn execute
Pointer to function executing a code by the VM instance.
Definition: evmc.h:1150
const char * name
The name of the EVMC VM implementation.
Definition: evmc.h:1128
evmc_destroy_fn destroy
Pointer to function destroying the VM instance.
Definition: evmc.h:1143
const int abi_version
EVMC ABI version implemented by the VM instance.
Definition: evmc.h:1120
const char * version
The version of the EVMC VM implementation, e.g.
Definition: evmc.h:1136