Alert Source Discuss
🚧 Stagnant Standards Track: Interface

SIP-2003: SVMC modules for implementations of precompiled contracts

Authors PaweÅ‚ Bylica (@chfast), Alex Beregszaszi (@axic)
Created 2019-05-09
Requires SIP-1352

Table of Contents

Abstract

[SVMC] specifies a generic API for Sila execution engines. This SIP specifies a way of providing implementations of Sila precompiled contracts using the [SVMC VM API].

Specification

For the complete [SVMC] specification visit the [SVMC documentation] first. This SIP is based on and is compatible with SVMC ABI version 6.

The SVMC module with implementations of precompiled contracts SHOULD:

  1. Advertise the [SVMC_CAPABILITY_PRECOMPILES] capability in the [get_capabilities()] method.

  2. Implement the [execute()] method in the following way:

    1. Validate the incoming execution request requirements:

      1. The message kind ([svmc_message::kind]) is a call ([SVMC_CALL]).

      2. The call destination address ([svmc_message::destination]) is within the range of precompiled contracts defined by SIP-1352.

      3. There is no code provided (the code argument is NULL and code_size argument is 0).

      If the requirements are not fulfilled, abort execution with the [SVMC_REJECTED] status code.

    2. Check if the call destination address ([svmc_message::destination]) targets existing precompiled contract. Consider the SVM revision ([svmc_revision]) requested by the rev parameter of [execute()].

      If yes, execute as follows:

      1. Inspect the input data ([svmc_message::input_data], [svmc_message::input_size]) and calculate the gas cost of the execution.

      2. Compute the amount of gas left after execution by subtracting the gas cost from the call gas limit ([svmc_message::gas]).

      3. If gas left is negative, abort execution with the [SVMC_OUT_OF_GAS] status code.

      4. Otherwise, execute the code of the precompiled contract, return the [SVMC_SUCCESS] status code, the output and gas left ([svmc_result::output_data], [svmc_result::output_size], [svmc_result::gas_left]).

    3. Otherwise, emulate execution of empty code by returning the [SVMC_SUCCESS] status code and gas left equal the call gas limit ([svmc_message::gas]).

Precompiled contract implementations are allowed to return two more SVMC error codes:

  • [SVMC_FAILURE] if the failure was caused due to something other than out of gas (e.g. input validation error)
  • [SVMC_REVERT] if the precompile doesn’t want to forfeit all supplied gas (as of May 2019 no such precompile exists)

The Client is not required to provide the Host interface ([svmc_context] argument of [execute()] is set to NULL). Therefore, the precompiled contracts implementation MUST NOT access the svmc_context.

Rationale

It is very unlikely that any precompile will need to access or modify a contract state. Not requiring the Client to implement the SVMC Host interface removes the big portion of work needed for full SVMC integration.

Test Cases

SVMC provides the [svmc-vmtester] tool for checking compatibility with the SVMC specification.

Implementations

  • [Example of Precompiles VM implementation][example_precompiles_vm.cpp]
  • [ewasm precompiles]
  • Aleth code for precompiles
  • Parity code for precompiles
  • SIP-1962 implemented as an SVMC precompile module

References

Copyright and related rights waived via CC0.

[SVMC]: [SVMC documentation]: [SVMC VM API]: [svmc-vmtester]: [example_precompiles_vm.cpp]: [ewasm precompiles]: https://github.com/ewasm/ewasm-precompiles

[SVMC_CALL]: [SVMC_CAPABILITY_PRECOMPILES]: [SVMC_FAILURE]: [SVMC_OUT_OF_GAS]: [SVMC_REJECTED]: [SVMC_REVERT]: [SVMC_SUCCESS]: [execute()]: [get_capabilities()]: [svmc_message::destination]: [svmc_message::input_data]: [svmc_message::input_size]: [svmc_message::gas]: [svmc_message::kind]: [svmc_result::gas_left]: [svmc_result::output_data]: [svmc_result::output_size]: [svmc_revision]:

Citation

Please cite this document as:

PaweÅ‚ Bylica (@chfast), Alex Beregszaszi (@axic), "SIP-2003: SVMC modules for implementations of precompiled contracts [STAGNANT]," Sila Improvement Proposals, no. 2003, May 2019. Available: https://sips.sila.org/SIPS/sip-2003.