Skip to content

Latest commit

 

History

History
59 lines (37 loc) · 2.59 KB

contract_interface.md

File metadata and controls

59 lines (37 loc) · 2.59 KB

Ewasm Contract Interface (ECI) Specification

The Ewasm Contract Interface (ECI) specifies the structure of a contract module.

Wire format

Every contract must be stored in the WebAssembly Binary Encoding format (in short, Wasm bytecode).

Imports

A contract can only import symbols specified in the Ethereum Environment Interface or EEI.

In practice, this means that all imports specified by an ewasm module must be from the ethereum namespace, and having a function signature and name directly correspondent to a function specified in the EEI.

As mentioned below, there is a debug namespace as well, but that is disallowed in production systems.

Debug-mode

Debug-mode is a special VM option, where an additional set of debugging interfaces are available to contracts. On a live VM, any bytecode trying to import these symbols should be rejected.

The imports are available under the debug namespace:

  • print32(value: i32) - print value
  • print64(value: i64) - print value
  • printMem(offset: i32, len: i32) - print memory segment as printable characters
  • printMemHex(offset: i32, len: i32) - print memory segment as hex
  • printStorage(pathOffset: i32) - print storage value as printable characters
  • printStorageHex(pathOffset: i32) - print storage value as hex

Exports

A contract must have exactly two exported symbols:

  • memory: the shared memory space available for the EEI to write into.
  • main: a function with no parameters and no result value.

Entry point

The method exported as main will be executed by the VM.

On successful execution, the code should return via a normal code path.

If it needs to abort due to a failure, an unreachable instruction should be executed.

Start function

The use of a start function is disallowed.

The reason for this is that an ewasm VM would need to have access to the memory space of a contract and that must be acquired prior to executing it. In the WebAssembly Javascript API however the start function is executed right during instantiation, which leaves no time for the client to acquire the memory area.

Note: This decision was made on WebAssembly version 0xb (pre version 1) and should be revisited.

Traps

If execution of wasm code triggers the wasm trap, the contract execution is terminated with failure and all remaining gas is consumed (OOG-like exception). This includes execution of unreachable instruction.