Skip to content

Latest commit

 

History

History
190 lines (133 loc) · 6.2 KB

testing_rpc.md

File metadata and controls

190 lines (133 loc) · 6.2 KB
Raw

RFC XXXX Ethereum Testing RPC API March 2024 Category: Standards Track A. Author ISSN: 2070-1721

Ethereum Client Testing RPC API

Abstract

This document defines a JSON-RPC API that Ethereum clients can expose to facilitate testing the client's conformance to Ethereum specifications. The API includes methods for controlling the client's blockchain state and accessing account and storage data.

Table of Contents

  1. Introduction

  2. Conventions and Definitions

  3. Retesteth-Specific RPC Methods 3.1. debug_accountRange 3.2. debug_storageRangeAt 3.3. debug_traceTransaction 3.4. test_mineBlocks 3.5. test_modifyTimestamp 3.6. test_rewindToBlock 3.7. test_setChainParams

  4. Standard Ethereum RPC Methods

  5. Security Considerations

  6. IANA Considerations

  7. References 7.1. Normative References 7.2. Informative References Appendix A. Examples Author's Address

  8. Introduction

    Ethereum is a decentralized platform that runs smart contracts. Ethereum clients are software applications that implement the Ethereum specification [EthYellow]. To ensure that clients conform to the specification, a common testing approach is needed.

    This document defines a JSON-RPC API [JSON-RPC] that Ethereum clients can expose to allow testing tools, such as retesteth [Retesteth], to control the client's state and access data needed for tests.

    The API includes both methods that are specific to retesteth's functionality, and references to standard Ethereum RPC methods.

  9. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

  1. Retesteth-Specific RPC Methods

3.1. debug_accountRange

 This method retrieves a list of accounts at a specified point in time.

 Parameters:
 - blockHashOrNumber: [string] The hash or number of the block.
 - txIndex: [int] Transaction index at which to get the account list. 
 - addressHash: [string] The hash at which to start the list.
 - maxResults: [int] Maximum number of results to return.

 Returns:
 - addressMap: [object] Hash values and the addresses they represent.
 - nextKey: [string] The next hash if more results are available.

3.2. debug_storageRangeAt

 This method retrieves a list of storage values for an address.
 
 Parameters:
 - blockHashOrNumber: [string] The hash or number of the block.  
 - txIndex: [int] Transaction index at which to get the storage.
 - address: [string] The address to retrieve storage for. 
 - startKey: [string] The hash of the first storage key to return.
 - maxResults: [int] Maximum number of results to return.

 Returns: 
 - storage: [object] Hash values and the storage keys/values.
 - complete: [boolean] True if this completes the available storage.

3.3. debug_traceTransaction

 This method returns the virtual machine execution trace of a transaction.

 Parameters:
 - hash: [string] The transaction hash.

 Returns:  
 - [array] The virtual machine execution trace as a list of steps.
 
 Implementation Note: This method is not currently implemented in retesteth.

3.4. test_mineBlocks

 This method mines new blocks including all currently pending transactions.

 Parameters:
 - blocks: [int] The number of blocks to mine.  

 Returns:
 - [boolean] True if blocks were mined successfully.

3.5. test_modifyTimestamp

 This method modifies the timestamp of the next block.
 
 Parameters:
 - timestamp: [int] The new timestamp as a UNIX timestamp.

 Returns:
 - [boolean] True if the timestamp was modified successfully.

3.6. test_rewindToBlock

 This method rewinds the blockchain to the state at a previous block.
 
 Parameters:
 - block: [int] The block number to rewind to.

 Returns:  
 - [boolean] True if the blockchain was rewound successfully.

3.7. test_setChainParams

 This method initializes the blockchain with the provided state data.

 Parameters: 
 - params: [object] 
   - chainId: [string] The blockchain's chain identifier.
   - forkBlocks: [object] Block numbers for protocol upgrade forks.
 - accounts: [object] Account addresses and their initial state. 
 - sealEngine: [string] The consensus seal engine to use.
 - genesis: [object] Parameters of the genesis block.

 Returns:
 - [boolean] True if the chain was initialized successfully.
  1. Standard Ethereum RPC Methods

In addition to the retesteth-specific methods, clients MUST also implement the following standard Ethereum RPC methods:

  • eth_blockNumber
  • eth_getBalance
  • eth_getBlockByNumber
  • eth_getCode
  • eth_getTransactionCount
  • eth_sendRawTransaction
  • web3_clientVersion
  1. Security Considerations

The API is intended for use in controlled test environments and MUST NOT be enabled on production Ethereum networks as it allows modifying the client's state in ways that violate Ethereum rules.

API authentication and transport-level security SHOULD be implemented, especially if the client exposes the API on a network interface.

  1. IANA Considerations

This document has no IANA actions.

  1. References

7.1. Normative References

[JSON-RPC] JSON-RPC 2.0 Specification https://www.jsonrpc.org/specification

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017.

7.2. Informative References

[EthYellow] Ethereum Yellow Paper https://ethereum.github.io/yellowpaper/paper.pdf

[Retesteth] Ethereum retesteth tool https://github.com/ethereum/retesteth