EVMC
helpers.h
Go to the documentation of this file.
1 // EVMC: Ethereum Client-VM Connector API.
2 // Copyright 2018 The EVMC Authors.
3 // Licensed under the Apache License, Version 2.0.
4 
15 #pragma once
16 
17 #include <evmc/evmc.h>
18 #include <stdlib.h>
19 #include <string.h>
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #pragma GCC diagnostic push
24 #pragma GCC diagnostic ignored "-Wold-style-cast"
25 #endif
26 
30 static inline bool evmc_is_abi_compatible(struct evmc_vm* vm)
31 {
32  return vm->abi_version == EVMC_ABI_VERSION;
33 }
34 
38 static inline const char* evmc_vm_name(struct evmc_vm* vm)
39 {
40  return vm->name;
41 }
42 
46 static inline const char* evmc_vm_version(struct evmc_vm* vm)
47 {
48  return vm->version;
49 }
50 
56 static inline bool evmc_vm_has_capability(struct evmc_vm* vm, enum evmc_capabilities capability)
57 {
58  return (vm->get_capabilities(vm) & (evmc_capabilities_flagset)capability) != 0;
59 }
60 
66 static inline void evmc_destroy(struct evmc_vm* vm)
67 {
68  vm->destroy(vm);
69 }
70 
76 static inline enum evmc_set_option_result evmc_set_option(struct evmc_vm* vm,
77  char const* name,
78  char const* value)
79 {
80  if (vm->set_option)
81  return vm->set_option(vm, name, value);
82  return EVMC_SET_OPTION_INVALID_NAME;
83 }
84 
90 static inline struct evmc_result evmc_execute(struct evmc_vm* vm,
91  const struct evmc_host_interface* host,
92  struct evmc_host_context* context,
93  enum evmc_revision rev,
94  const struct evmc_message* msg,
95  uint8_t const* code,
96  size_t code_size)
97 {
98  return vm->execute(vm, host, context, rev, msg, code, code_size);
99 }
100 
107 static void evmc_free_result_memory(const struct evmc_result* result)
108 {
109  free((uint8_t*)result->output_data);
110 }
111 
124 static inline struct evmc_result evmc_make_result(enum evmc_status_code status_code,
125  int64_t gas_left,
126  const uint8_t* output_data,
127  size_t output_size)
128 {
129  struct evmc_result result;
130  memset(&result, 0, sizeof(result));
131 
132  if (output_size != 0)
133  {
134  uint8_t* buffer = (uint8_t*)malloc(output_size);
135 
136  if (!buffer)
137  {
138  result.status_code = EVMC_OUT_OF_MEMORY;
139  return result;
140  }
141 
142  memcpy(buffer, output_data, output_size);
143  result.output_data = buffer;
144  result.output_size = output_size;
145  result.release = evmc_free_result_memory;
146  }
147 
148  result.status_code = status_code;
149  result.gas_left = gas_left;
150  return result;
151 }
152 
160 static inline void evmc_release_result(struct evmc_result* result)
161 {
162  if (result->release)
163  result->release(result);
164 }
165 
166 
194 {
195  uint8_t bytes[24];
196  void* pointer;
197 };
198 
201  struct evmc_result* result)
202 {
203  return (union evmc_result_optional_storage*)&result->create_address;
204 }
205 
208  const struct evmc_result* result)
209 {
210  return (const union evmc_result_optional_storage*)&result->create_address;
211 }
212 
216 static inline const char* evmc_status_code_to_string(enum evmc_status_code status_code)
217 {
218  switch (status_code)
219  {
220  case EVMC_SUCCESS:
221  return "success";
222  case EVMC_FAILURE:
223  return "failure";
224  case EVMC_REVERT:
225  return "revert";
226  case EVMC_OUT_OF_GAS:
227  return "out of gas";
229  return "invalid instruction";
231  return "undefined instruction";
232  case EVMC_STACK_OVERFLOW:
233  return "stack overflow";
235  return "stack underflow";
237  return "bad jump destination";
239  return "invalid memory access";
241  return "call depth exceeded";
243  return "static mode violation";
245  return "precompile failure";
247  return "contract validation failure";
249  return "argument out of range";
251  return "wasm unreachable instruction";
252  case EVMC_WASM_TRAP:
253  return "wasm trap";
255  return "insufficient balance";
256  case EVMC_INTERNAL_ERROR:
257  return "internal error";
258  case EVMC_REJECTED:
259  return "rejected";
260  case EVMC_OUT_OF_MEMORY:
261  return "out of memory";
262  }
263  return "<unknown>";
264 }
265 
267 static inline const char* evmc_revision_to_string(enum evmc_revision rev)
268 {
269  switch (rev)
270  {
271  case EVMC_FRONTIER:
272  return "Frontier";
273  case EVMC_HOMESTEAD:
274  return "Homestead";
276  return "Tangerine Whistle";
278  return "Spurious Dragon";
279  case EVMC_BYZANTIUM:
280  return "Byzantium";
281  case EVMC_CONSTANTINOPLE:
282  return "Constantinople";
283  case EVMC_PETERSBURG:
284  return "Petersburg";
285  case EVMC_ISTANBUL:
286  return "Istanbul";
287  case EVMC_BERLIN:
288  return "Berlin";
289  case EVMC_LONDON:
290  return "London";
291  case EVMC_PARIS:
292  return "Paris";
293  case EVMC_SHANGHAI:
294  return "Shanghai";
295  case EVMC_CANCUN:
296  return "Cancun";
297  }
298  return "<unknown>";
299 }
300 
303 #ifdef __cplusplus
304 #pragma GCC diagnostic pop
305 } // extern "C"
306 #endif
EVMC: Ethereum Client-VM Connector API.
evmc_set_option_result
Possible outcomes of evmc_set_option.
Definition: evmc.h:778
evmc_capabilities
Possible capabilities of a VM.
Definition: evmc.h:945
evmc_status_code
The execution status code.
Definition: evmc.h:260
uint32_t evmc_capabilities_flagset
Alias for unsigned integer representing a set of bit flags of EVMC capabilities.
Definition: evmc.h:974
evmc_revision
EVM revision.
Definition: evmc.h:809
@ EVMC_ABI_VERSION
The EVMC ABI version number of the interface declared in this file.
Definition: evmc.h:47
@ 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_HOMESTEAD
The Homestead revision.
Definition: evmc.h:822
@ 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_SPURIOUS_DRAGON
The Spurious Dragon revision.
Definition: evmc.h:836
@ EVMC_BYZANTIUM
The Byzantium revision.
Definition: evmc.h:843
@ EVMC_CANCUN
The Cancun revision.
Definition: evmc.h:901
@ EVMC_SHANGHAI
The Shanghai revision.
Definition: evmc.h:894
@ EVMC_LONDON
The London revision.
Definition: evmc.h:880
@ EVMC_PARIS
The Paris revision (aka The Merge).
Definition: evmc.h:887
@ EVMC_BERLIN
The Berlin revision.
Definition: evmc.h:873
static struct evmc_result evmc_make_result(enum evmc_status_code status_code, int64_t gas_left, const uint8_t *output_data, size_t output_size)
Creates the result from the provided arguments.
Definition: helpers.h:124
static void evmc_free_result_memory(const struct evmc_result *result)
The evmc_result release function using free() for releasing the memory.
Definition: helpers.h:107
static bool evmc_vm_has_capability(struct evmc_vm *vm, enum evmc_capabilities capability)
Checks if the VM has the given capability.
Definition: helpers.h:56
static void evmc_destroy(struct evmc_vm *vm)
Destroys the VM instance.
Definition: helpers.h:66
static const char * evmc_status_code_to_string(enum evmc_status_code status_code)
Returns text representation of the evmc_status_code.
Definition: helpers.h:216
static void evmc_release_result(struct evmc_result *result)
Releases the resources allocated to the execution result.
Definition: helpers.h:160
static bool evmc_is_abi_compatible(struct evmc_vm *vm)
Returns true if the VM has a compatible ABI version.
Definition: helpers.h:30
static struct evmc_result evmc_execute(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 code in the VM instance.
Definition: helpers.h:90
static const char * evmc_vm_version(struct evmc_vm *vm)
Returns the version of the VM.
Definition: helpers.h:46
static enum evmc_set_option_result evmc_set_option(struct evmc_vm *vm, char const *name, char const *value)
Sets the option for the VM, if the feature is supported by the VM.
Definition: helpers.h:76
static const char * evmc_revision_to_string(enum evmc_revision rev)
Returns the name of the evmc_revision.
Definition: helpers.h:267
static const char * evmc_vm_name(struct evmc_vm *vm)
Returns the name of the VM.
Definition: helpers.h:38
static const union evmc_result_optional_storage * evmc_get_const_optional_storage(const struct evmc_result *result)
Provides read-only access to evmc_result "optional storage".
Definition: helpers.h:207
static union evmc_result_optional_storage * evmc_get_optional_storage(struct evmc_result *result)
Provides read-write access to evmc_result "optional storage".
Definition: helpers.h:200
The opaque data type representing the Host execution context.
The Host interface.
Definition: evmc.h:719
The message describing an EVM call, including a zero-depth calls from a transaction origin.
Definition: evmc.h:97
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
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 VM instance.
Definition: evmc.h:994
evmc_set_option_fn set_option
Optional pointer to function modifying VM's options.
Definition: evmc.h:1050
evmc_get_capabilities_fn get_capabilities
A method returning capabilities supported by the VM instance.
Definition: evmc.h:1043
const char * name
The name of the EVMC VM implementation.
Definition: evmc.h:1009
evmc_destroy_fn destroy
Pointer to function destroying the VM instance.
Definition: evmc.h:1024
const int abi_version
EVMC ABI version implemented by the VM instance.
Definition: evmc.h:1001
const char * version
The version of the EVMC VM implementation, e.g.
Definition: evmc.h:1017
The union representing evmc_result "optional storage".
Definition: helpers.h:194
void * pointer
Optional pointer.
Definition: helpers.h:196
uint8_t bytes[24]
24 bytes of optional storage.
Definition: helpers.h:195