HIP-584: Mirror EVM Archive Node

Abstract

This HIP describes EVM execution APIs on the mirror node and transaction simulations. The HIP also describes initial Mirror Node APIs that will handle contract execution related queries, thus allowing the Mirror Node to serve the role of an EVM Archive Node.

Motivation

Ongoing user experience work needs EVM execution to enable features such as cost-free execution of read-only smart contract queries, gas estimation, and transient simulation of read-write operations.

Rationale

In order to be possible to simulate transactions Mirror Node will use a module encapsulating all of the EVM logic.

The library would allow us to fulfil the following use cases:

• Execute simulations that perform read-only operations
• Execute transaction simulations that perform speculative writes without committing changes to state
• Execute transaction simulations that perform speculative writes using historical data for transaction replay, without committing changes to state

User stories

• As a user, I want to perform eth_call calls from the Ethereum JSON-RPC standard
• As a user, I want to perform eth_estimateGas calls from the Ethereum JSON-RPC standard
• As a user, I want to use a library that can be used to re-run historical EVM transactions accurately so that I can inspect and debug the execution of the bytecode logic.

Specification

Mirror Node

Information will be made available via new REST API

Read-only queries and gas estimate REST API

A new /api/v1/contracts/call POST REST API will be added to execute read-only queries and gas estimate. The estimate(if omitted = false) field in the request body would determine what the result represents.

The following JSON represents a typical request body:

{
  "block": "latest", 
  "data": "0x81a73ad500000000000000000000000000000000000000000000000000000000000004e5",
  "estimate": true,
  "from": "0x00000000000000000000000000000000000004e2", 
  "gas": 100000000, 
  "gas_price": 100000000,
  "to": "0x00000000000000000000000000000000000004e4", 
  "value": 0
}

The following JSON represents a typical response result with the information read in the query:
With the estimate field set to true in the request body:

{
    "result": "0x3234333230"
}

With the estimate field omitted or set to false in the request body:

{
    "result": "0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000037474740000000000000000000000000000000000000000000000000000000000"
}

Backwards Compatibility

Mirror Nodes that will support the new REST APIs should have enabled importing of CONTRACT_BYTECODE and CONTRACT_STATE_CHANGE sidecar types. Otherwise, executing the endpoints would result in missing runtime bytecode for execution or using stale contract storage data.

Security Implications

There would be some security implementations for Mirror Nodes. Since the invocation of eth_call and eth_gasEstimate RPC calls would be free of charge and the Mirror Nodes don’t have throttle mechanism, some attack vectors would be possible. The Nodes could be overloaded with huge amount of calls or calls invoking smart contract methods with huge gas usage, both of which might take more system usage and slow down the network for other users. A rate limit mechanism will be implemented, so that the load put on Mirror Nodes to be balanced.

How to Teach This

Respective documentation will be added.

Reference Implementation

Rejected Ideas

None.

Open Issues

None.

References

Copyright/License

This document is licensed under the Apache License, Version 2.0 – see LICENSE or (https://www.apache.org/licenses/LICENSE-2.0)

Citation

Please cite this document as: