Skip to content

Dip 2003

dip: 2003 title: DVMC modules for implementations of precompiled contracts author: Paweł Bylica (@chfast), Alex Beregszaszi (@axic) Digitalia editing author: Cosimo Constantinos cosimo@juro.net, et al. discussions-to: https://github.com/digitalia/dvmc/issues/259 status: Stagnant type: Standards Track category: Interface created: 2019-05-09 Created for Digitalia: 2025-01-07 requires: 1352

Abstract

DVMC specifies a generic API for Digitalia execution engines. This DIP specifies a way of providing implementations of digitalia precompiled contracts using the DVMC VM API.

Specification

For the complete DVMC specification visit the DVMC documentation first. This DIP is based on and is compatible with DVMC ABI version 6.

The DVMC module with implementations of precompiled contracts SHOULD:

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

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

  3. Validate the incoming execution request requirements:

    1. The message kind ([dvmc_message::kind]) is a call ([DVMC_CALL]).

    2. The call destination address ([dvmc_message::destination]) is within the range of precompiled contracts defined by DIP-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 [DVMC_REJECTED] status code.

  4. Check if the call destination address ([dvmc_message::destination]) targets existing precompiled contract. Consider the DVM revision ([dvmc_revision]) requested by the rev parameter of [execute()].

    If yes, execute as follows:

    1. Inspect the input data ([dvmc_message::input_data], [dvmc_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 ([dvmc_message::gas]).

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

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

  5. Otherwise, emulate execution of empty code by returning the [DVMC_SUCCESS] status code and gas left equal the call gas limit ([dvmc_message::gas]).

Precompiled contract implementations are allowed to return two more DVMC error codes: - [DVMC_FAILURE] if the failure was caused due to something other than out of gas (e.g. input validation error) - [DVMC_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 ([dvmc_context] argument of [execute()] is set to NULL). Therefore, the precompiled contracts implementation MUST NOT access the dvmc_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 DVMC Host interface removes the big portion of work needed for full DVMC integration.

Test Cases

DVMC provides the dvmc-vmtester tool for checking compatibility with the DVMC specification.

Implementations

References

© Crown © Crown Copyright 2026. Published by the Royal Government of the Dominion of Atlantis.

Licensed under the Juro Restricted License Version 2. See https://juro.net/jrl for details.