diff --git a/eth_estimateGasBundle/api-spec.yml b/eth_estimateGasBundle/api-spec.yml index 77786a5..a740dfa 100644 --- a/eth_estimateGasBundle/api-spec.yml +++ b/eth_estimateGasBundle/api-spec.yml @@ -1,16 +1,14 @@ openapi: 3.0.0 info: title: Ethereum Bundle API - version: "1.0" + version: '1.0' paths: /eth_callBundle: post: summary: Simulate a bundle of transactions description: > - Simulate a bundle of transactions at the top of a given block with the state of another - (or the same) block. This can be used to simulate future blocks with the current state, - or it can be used to simulate a past block. The sender is responsible for signing the - transactions and using the correct nonce and ensuring validity. + Simulate a bundle of transactions at the top of a given block with the state of another (or the same) block. This can be used to simulate future blocks with the current state, or it can be used to simulate a past block. The sender is responsible for signing the transactions and using the correct nonce and ensuring validity. + requestBody: required: true content: @@ -39,8 +37,8 @@ paths: post: summary: Estimate gas for a bundle of transactions description: > - Estimate the gas required for executing a bundle of transactions without actually - sending them to the network. This is useful for predicting gas usage and costs. + Estimate the gas required for executing a bundle of transactions without actually sending them to the network. This is useful for predicting gas usage and costs. + requestBody: required: true content: diff --git a/eth_getLogs+timestamp/README.md b/eth_getLogs+timestamp/README.md index 6731bb3..607e600 100644 --- a/eth_getLogs+timestamp/README.md +++ b/eth_getLogs+timestamp/README.md @@ -52,8 +52,8 @@ params: [ - `transactionIndex`: `QUANTITY` - integer of the transactions index position log was created from. `null` when its pending log. - `transactionHash`: `DATA`, 32 Bytes - hash of the transactions this log was created from. `null` when its pending log. - `blockHash`: `DATA`, 32 Bytes - hash of the block where this log was in. `null` when its pending. `null` when its pending log. -- `blockNumber`: `QUANTITY` - the block number where this log was in. `null` when its pending. `null` when its pending log. -- `blockTimestamp`: `QUANTITY` - the unix timestamp for when the block where this log was in, was collated. `null` when its pending. `null` when its pending log.** +- `blockNumber`: `QUANTITY` - the block number where this log was in. `null` when its pending. `null` when its pending log. +- `blockTimestamp`: `QUANTITY` - the unix timestamp for when the block where this log was in, was collated. `null` when its pending. `null` when its pending log.\*\* - `address`: `DATA`, 20 Bytes - address from which this log originated. - `data`: `DATA` - contains one or more 32 Bytes non-indexed arguments of the log. - `topics`: `Array of DATA` - Array of 0 to 4 32 Bytes `DATA` of indexed log arguments. (In _solidity_: The first topic is the _hash_ of the signature of the event (e.g. `Deposit(address,bytes32,uint256)`), except you declared the event with the `anonymous` specifier.) diff --git a/eth_getinclusionstats/SPEC.md b/eth_getinclusionstats/SPEC.md index 9e0549c..7bc82c8 100644 --- a/eth_getinclusionstats/SPEC.md +++ b/eth_getinclusionstats/SPEC.md @@ -1,4 +1,3 @@ - --- EIP: XXXX Title: Add `eth_getinclusionstats` RPC Method @@ -23,40 +22,44 @@ Understanding transaction inclusion dynamics is crucial for both users and devel ### **Method Name**: `eth_getinclusionstats` ### **Parameters**: - 1. `TRANSACTION_HASH`: The hash of the transaction for which inclusion statistics are being requested. - 2. `BLOCK_PARAMETER`: An optional parameter specifying the block (by number, hash, or the string "latest") up to which the search should be conducted. If omitted, the search includes the latest block. + +1. `TRANSACTION_HASH`: The hash of the transaction for which inclusion statistics are being requested. +2. `BLOCK_PARAMETER`: An optional parameter specifying the block (by number, hash, or the string "latest") up to which the search should be conducted. If omitted, the search includes the latest block. ### **Returns**: An object containing: - - `included`: A boolean indicating whether the transaction was included in a block (`true`) or not (`false`). - - `blockHash`: The hash of the block in which the transaction was included. `null` if the transaction has not been included in any block. - - `blockNumber`: The number of the block in which the transaction was included. `null` if the transaction has not been included in any block. - - `transactionIndex`: The index position of the transaction in the block. `null` if the transaction has not been included in any block. - - Additional fields may be included to provide further analytics, such as average inclusion time, network congestion metrics, etc. + +- `included`: A boolean indicating whether the transaction was included in a block (`true`) or not (`false`). +- `blockHash`: The hash of the block in which the transaction was included. `null` if the transaction has not been included in any block. +- `blockNumber`: The number of the block in which the transaction was included. `null` if the transaction has not been included in any block. +- `transactionIndex`: The index position of the transaction in the block. `null` if the transaction has not been included in any block. +- Additional fields may be included to provide further analytics, such as average inclusion time, network congestion metrics, etc. ### **Example**: + ```jsonc - // Request - { - "jsonrpc": "2.0", - "method": "eth_getinclusionstats", - "params": ["0x...transaction hash...", "latest"], - "id": 1 - } +// Request +{ + "jsonrpc": "2.0", + "method": "eth_getinclusionstats", + "params": ["0x...transaction hash...", "latest"], + "id": 1 +} ``` - // Response +// Response + ```jsonc - { - "jsonrpc": "2.0", - "id": 1, - "result": { - "included": true, - "blockHash": "0x...block hash...", - "blockNumber": "0x...block number...", - "transactionIndex": "0x15" - // Additional fields as necessary - } - } +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "included": true, + "blockHash": "0x...block hash...", + "blockNumber": "0x...block number...", + "transactionIndex": "0x15" + // Additional fields as necessary + } +} ``` **Rationale** @@ -74,9 +77,10 @@ This EIP is fully backwards compatible as it introduces a new method without alt **Test Cases** Test cases for an implementation are essential for ensuring the method behaves as expected across different scenarios. These should cover, at a minimum: -- A transaction included in a block. -- A transaction not yet included in any block. -- Querying with and without the `BLOCK_PARAMETER`. + +- A transaction included in a block. +- A transaction not yet included in any block. +- Querying with and without the `BLOCK_PARAMETER`. **Implementation** @@ -84,5 +88,5 @@ Test cases for an implementation are essential for ensuring the method behaves a **References** -- Existing Ethereum JSON RPC documentation. -- Related EIPs and Ethereum GitHub discussions. +- Existing Ethereum JSON RPC documentation. +- Related EIPs and Ethereum GitHub discussions. diff --git a/eth_testMethod/README.md b/eth_testMethod/README.md index ad9c8b5..0d7345f 100644 --- a/eth_testMethod/README.md +++ b/eth_testMethod/README.md @@ -1,6 +1,7 @@ ### EIP-XXXX: Custom JSON-RPC Methods for Ethereum Client Testing #### Preamble + ``` EIP: Title: Custom JSON-RPC Methods for Ethereum Client Testing @@ -13,62 +14,71 @@ Requires (*optional): ``` #### Abstract + This EIP introduces a set of custom JSON-RPC methods designed to facilitate comprehensive testing of Ethereum clients. These methods enable the simulation of various network conditions, smart contract interactions, and blockchain states, providing developers with powerful tools for evaluating client performance, security, and compatibility. #### Motivation + The motivation behind introducing these custom JSON-RPC methods is to address the lack of standardized testing mechanisms that can simulate a wide range of Ethereum network scenarios. These methods allow for more rigorous and exhaustive testing of Ethereum clients, ensuring they can operate reliably under different conditions and adhere to the Ethereum protocol specifications. #### Specification ##### Method: `eth_testMethod` -- **Description**: This method simulates a specified blockchain condition or operation for testing purposes. -- **Parameters**: - 1. `testType` - A string specifying the type of test to simulate (e.g., "networkDelay", "smartContractInteraction"). - 2. `parameters` - An object containing parameters relevant to the specified test. -- **Returns**: An object containing the results of the simulated test, including any relevant data or metrics. + +- **Description**: This method simulates a specified blockchain condition or operation for testing purposes. +- **Parameters**: + 1. `testType` - A string specifying the type of test to simulate (e.g., "networkDelay", "smartContractInteraction"). + 2. `parameters` - An object containing parameters relevant to the specified test. +- **Returns**: An object containing the results of the simulated test, including any relevant data or metrics. ##### Example + ```jsonc // Request { - "jsonrpc": "2.0", - "method": "eth_testMethod", - "params": [ - "smartContractInteraction", - { - "contractAddress": "0x...", - "functionSignature": "transfer(address,uint256)", - "parameters": ["0xrecipientAddress...", 100] - } - ], - "id": 1 + "jsonrpc": "2.0", + "method": "eth_testMethod", + "params": [ + "smartContractInteraction", + { + "contractAddress": "0x...", + "functionSignature": "transfer(address,uint256)", + "parameters": ["0xrecipientAddress...", 100] + } + ], + "id": 1 } ``` - Response +Response + ```jsonc { - "id": 1, - "jsonrpc": "2.0", - "result": { - "success": true, - "transactionHash": "0x..." - } + "id": 1, + "jsonrpc": "2.0", + "result": { + "success": true, + "transactionHash": "0x..." + } } ``` #### Rationale + The custom methods introduced in this EIP are designed to be flexible and comprehensive, allowing developers to simulate a wide range of Ethereum network conditions and behaviors. This flexibility is crucial for thorough testing and validation of Ethereum clients across different scenarios. #### Backwards Compatibility + These custom JSON-RPC methods are designed to be fully compatible with existing Ethereum JSON-RPC specifications. They do not modify or replace existing methods, but rather supplement them with additional functionality for testing purposes. #### Test Cases + Test cases should cover a variety of scenarios, including but not limited to network delays, smart contract deployments, transaction processing under heavy load, and consensus algorithm behaviors. #### Implementation + A reference implementation of these custom methods should be provided, demonstrating their integration with existing Ethereum client software. This implementation should include detailed documentation on method usage, parameters, and expected outcomes. #### Security Considerations -The introduction of custom JSON-RPC methods for testing purposes should not compromise the security of Ethereum clients or networks. These methods should be designed with security in mind, ensuring that they cannot be exploited to introduce vulnerabilities into client implementations or network operations. +The introduction of custom JSON-RPC methods for testing purposes should not compromise the security of Ethereum clients or networks. These methods should be designed with security in mind, ensuring that they cannot be exploited to introduce vulnerabilities into client implementations or network operations. diff --git a/mev_sendbetabundle/.default-spectral.yml b/mev_sendbetabundle/.default-spectral.yml index 1cac3b3..4807a51 100644 --- a/mev_sendbetabundle/.default-spectral.yml +++ b/mev_sendbetabundle/.default-spectral.yml @@ -1 +1 @@ -extends: ["spectral:oas", "spectral:asyncapi"] +extends: ['spectral:oas', 'spectral:asyncapi'] diff --git a/mev_sendbetabundle/.spectral.yaml b/mev_sendbetabundle/.spectral.yaml index afdb6ad..4ba3d11 100644 --- a/mev_sendbetabundle/.spectral.yaml +++ b/mev_sendbetabundle/.spectral.yaml @@ -1 +1 @@ -extends: ["@stoplight/spectral-documentation"] +extends: ['@stoplight/spectral-documentation'] diff --git a/mev_sendbetabundle/README.md b/mev_sendbetabundle/README.md index 7732959..c3bdf42 100644 --- a/mev_sendbetabundle/README.md +++ b/mev_sendbetabundle/README.md @@ -5,79 +5,93 @@ Creating an Ethereum Improvement Proposal (EIP) for a custom JSON-RPC method inv # EIP-XXXX: MEV Send Beta Bundle Method ## Simple Summary + Introduces a custom JSON-RPC method `mev_sendBetaBundle` for submitting a set of transactions as a bundle to be included in a specific block on the Ethereum blockchain, targeting scenarios where transactions are not priority-sensitive. ## Abstract + This EIP proposes a new JSON-RPC method that allows the submission of a bundle of transactions to be included in a specific block. This method is designed for transactions that do not require priority ordering within the block. The method ensures that transactions originating from the sender have a corresponding call option for the specified slot. Transactions exceeding the block's remaining gas limit are dropped in the order listed within the bundle, allowing partial fulfillment of the bundle. ## Motivation + Miner Extractable Value (MEV) strategies often require the submission of transaction bundles that are executed together within the same block to exploit arbitrage opportunities, perform liquidations, or protect against front-running. The existing JSON-RPC methods do not support the submission of transaction bundles with specific block targeting and handling for non-priority sensitive transactions. This EIP aims to fill this gap, providing developers and MEV searchers with a tool to more effectively manage their transactions. ## Specification ### Method Name + `mev_sendBetaBundle` ### Parameters + 1. `txs` - Array of raw transactions (as hex strings) to be included in the bundle. 2. `slot` - The block number (as a string) at which the bundle should be included. ### Returns -- `jsonrpc`: The JSON-RPC version (e.g., "2.0"). -- `method`: The method name (`mev_sendBetaBundle`). -- `params`: An array containing a single object with two fields: `txs` (an array of raw transaction data) and `slot` (the target block number as a string). -- `id`: A unique identifier for the request. + +- `jsonrpc`: The JSON-RPC version (e.g., "2.0"). +- `method`: The method name (`mev_sendBetaBundle`). +- `params`: An array containing a single object with two fields: `txs` (an array of raw transaction data) and `slot` (the target block number as a string). +- `id`: A unique identifier for the request. ### Errors -- If the transaction originator does not have a corresponding call option for the specified slot, the method will fail. -- Transactions that would cause the block's gas limit to be exceeded are dropped in the order they appear in the bundle. + +- If the transaction originator does not have a corresponding call option for the specified slot, the method will fail. +- Transactions that would cause the block's gas limit to be exceeded are dropped in the order they appear in the bundle. ### Example + Request: + ```json { - "jsonrpc": "2.0", - "method": "mev_sendBetaBundle", - "params": [ - { - "txs": ["0x..."], - "slot": "1001" - } - ], - "id": 8 + "jsonrpc": "2.0", + "method": "mev_sendBetaBundle", + "params": [ + { + "txs": ["0x..."], + "slot": "1001" + } + ], + "id": 8 } ``` Response: + ```json { - "jsonrpc": "2.0", - "method": "mev_sendBetaBundle", - "params": [ - { - "txs": ["0x... - rawData"], - "slot": "1001" - } - ], - "id": 8 + "jsonrpc": "2.0", + "method": "mev_sendBetaBundle", + "params": [ + { + "txs": ["0x... - rawData"], + "slot": "1001" + } + ], + "id": 8 } ``` ## Rationale + The `mev_sendBetaBundle` method is designed to accommodate the specific needs of MEV strategies that do not require transactions to be executed in a priority order within a block. By allowing transactions to be bundled and specifying the block in which they should be included, this method provides a more flexible and efficient way to manage MEV-related transactions. The decision to drop transactions exceeding the block's gas limit in the order they are listed allows for partial fulfillment of the bundle, ensuring that the most critical transactions can be prioritized by the sender. ## Security Considerations -- This method requires careful management of the block's gas limit to prevent denial of service attacks by submitting large bundles that could monopolize block space. -- Implementers should ensure that only authorized users have the ability to submit transaction bundles to prevent spam and potential manipulation of block contents. + +- This method requires careful management of the block's gas limit to prevent denial of service attacks by submitting large bundles that could monopolize block space. +- Implementers should ensure that only authorized users have the ability to submit transaction bundles to prevent spam and potential manipulation of block contents. ## Test Cases -- Submission of a valid transaction bundle for a future block. -- Handling of a bundle when the block's gas limit is exceeded. -- Rejection of a bundle when the sender does not have a corresponding call option for the specified slot. + +- Submission of a valid transaction bundle for a future block. +- Handling of a bundle when the block's gas limit is exceeded. +- Rejection of a bundle when the sender does not have a corresponding call option for the specified slot. ## Implementation + This EIP requires changes to Ethereum client software to support the new JSON-RPC method. Implementations should follow the specifications outlined above to ensure compatibility across different clients. --- -This draft EIP provides a comprehensive overview of the proposed `mev_sendBetaBundle` method, including its purpose, specifications, and considerations. It's structured to fit within the Ethereum Improvement Proposal framework, aiming for clarity, completeness, and technical accuracy. \ No newline at end of file +This draft EIP provides a comprehensive overview of the proposed `mev_sendBetaBundle` method, including its purpose, specifications, and considerations. It's structured to fit within the Ethereum Improvement Proposal framework, aiming for clarity, completeness, and technical accuracy. diff --git a/mev_sendbetabundle/openapi.yaml b/mev_sendbetabundle/openapi.yaml index 475e438..36e5f33 100644 --- a/mev_sendbetabundle/openapi.yaml +++ b/mev_sendbetabundle/openapi.yaml @@ -2,7 +2,7 @@ openapi: 3.0.0 info: title: MEV Send Beta Bundle API description: API for submitting transaction bundles for MEV purposes on Ethereum. - version: "1.0.0" + version: '1.0.0' servers: - url: https://holesky-api.securerpc.com/v2 description: Testnet Server for MEV Send Beta Bundle @@ -15,6 +15,7 @@ paths: summary: Submit a bundle of transactions to be included in a specific block. description: > This endpoint allows for the submission of a set of transactions as a bundle for inclusion in a specific block. It is designed for transactions that are not priority-sensitive. Transactions that exceed the block's gas limit will be dropped in the order they are listed, allowing for partial fulfillment of the bundle. + operationId: mev_sendBetaBundle requestBody: required: true @@ -44,11 +45,11 @@ components: jsonrpc: type: string description: JSON-RPC protocol version, should always be "2.0". - example: "2.0" + example: '2.0' method: type: string description: The JSON-RPC method name, for this operation it should be "mev_sendBetaBundle". - example: "mev_sendBetaBundle" + example: 'mev_sendBetaBundle' params: type: array description: An array containing a single object with the transaction bundle details. @@ -77,11 +78,11 @@ components: jsonrpc: type: string description: JSON-RPC protocol version, echoed back from the request. - example: "2.0" + example: '2.0' method: type: string description: The JSON-RPC method name, echoed back from the request. - example: "mev_sendBetaBundle" + example: 'mev_sendBetaBundle' params: type: array description: An array containing a single object with the transaction bundle details, echoed back from the request. diff --git a/test_setChainParams/README.md b/test_setChainParams/README.md index 57795bc..970bac2 100644 --- a/test_setChainParams/README.md +++ b/test_setChainParams/README.md @@ -2,7 +2,6 @@ > This EIP draft provides a structured approach to proposing the `test_setChainParams` method as a standardized feature for Ethereum clients, focusing on its utility for development and testing purposes. - #### Abstract This EIP proposes a new JSON-RPC method `test_setChainParams` for Ethereum clients. This method allows for the dynamic configuration of blockchain parameters in a testing environment, enabling developers to simulate various blockchain states and fork configurations without the need to restart the client or configure a private blockchain from scratch. @@ -17,43 +16,43 @@ The `test_setChainParams` method accepts a single parameter: an object containin ```jsonc { - "jsonrpc": "2.0", - "method": "test_setChainParams", - "params": [ - { - "params": { - "homesteadForkBlock": "0x00", - "EIP150ForkBlock": "0x00", - "EIP158ForkBlock": "0x00", - "byzantiumForkBlock": "0x00", - "constantinopleForkBlock": "0x00", - "constantinopleFixForkBlock": "0x00", - "istanbulForkBlock": "0x00", - "berlinForkBlock": "0x00", - "chainID": "0x01" - }, - "accounts": { - "0x095e7baea6a6c7c4c2dfeb977efac326af552d87": { - "balance": "0x0de0b6b3a7640000", - "code": "0x600160010160005500", - "nonce": "0x00", - "storage": {} - }, -// ... - }, - "sealEngine": "NoReward", - "genesis": { - "author": "0x2adc25665018aa1fe0e6bc666dac8fc2697ff9ba", - "difficulty": "0x020000", - "gasLimit": "0xff112233445566", - "extraData": "0x00", - "timestamp": "0x00", - "nonce": "0x0000000000000000", - "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000" - } - } - ], - "id": 1 + "jsonrpc": "2.0", + "method": "test_setChainParams", + "params": [ + { + "params": { + "homesteadForkBlock": "0x00", + "EIP150ForkBlock": "0x00", + "EIP158ForkBlock": "0x00", + "byzantiumForkBlock": "0x00", + "constantinopleForkBlock": "0x00", + "constantinopleFixForkBlock": "0x00", + "istanbulForkBlock": "0x00", + "berlinForkBlock": "0x00", + "chainID": "0x01" + }, + "accounts": { + "0x095e7baea6a6c7c4c2dfeb977efac326af552d87": { + "balance": "0x0de0b6b3a7640000", + "code": "0x600160010160005500", + "nonce": "0x00", + "storage": {} + } + // ... + }, + "sealEngine": "NoReward", + "genesis": { + "author": "0x2adc25665018aa1fe0e6bc666dac8fc2697ff9ba", + "difficulty": "0x020000", + "gasLimit": "0xff112233445566", + "extraData": "0x00", + "timestamp": "0x00", + "nonce": "0x0000000000000000", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000" + } + } + ], + "id": 1 } ``` @@ -68,9 +67,10 @@ This method is intended for use in test environments and should not affect live #### Test Cases Test cases should cover scenarios including, but not limited to: -- Setting various fork block numbers and verifying the activation of corresponding protocol features. -- Configuring pre-defined accounts with specific balances, code, and storage, and interacting with these accounts through transactions. -- Testing with different chain IDs to ensure transaction replay protection behaves as expected. + +- Setting various fork block numbers and verifying the activation of corresponding protocol features. +- Configuring pre-defined accounts with specific balances, code, and storage, and interacting with these accounts through transactions. +- Testing with different chain IDs to ensure transaction replay protection behaves as expected. #### Implementation @@ -81,4 +81,3 @@ Implementations of this method should allow for the dynamic modification of the While this method is intended for testing purposes only, implementers should ensure that it cannot be invoked in live environments where it could be used to manipulate the state or behavior of the network. Adequate safeguards should be in place to prevent its use outside of controlled test environments. --- - diff --git a/testing_rpc.md b/testing_rpc.md index 2754902..c27a8f1 100644 --- a/testing_rpc.md +++ b/testing_rpc.md @@ -1,190 +1,169 @@ -RFC XXXX Ethereum Testing RPC API March 2024 -Category: Standards Track A. Author -ISSN: 2070-1721 +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. +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 - -1. 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. - +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. - 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. +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. 3. Retesteth-Specific RPC Methods - 3.1. debug_accountRange + 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. - This method retrieves a list of accounts at a specified point in time. + Parameters: - 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. + - 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: - - addressMap: [object] Hash values and the addresses they represent. - - nextKey: [string] The next hash if more results are available. + Returns: - 3.2. debug_storageRangeAt + - storage: [object] Hash values and the storage keys/values. + - complete: [boolean] True if this completes the available storage. - 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. + 3.3. debug_traceTransaction - Returns: - - storage: [object] Hash values and the storage keys/values. - - complete: [boolean] True if this completes the available storage. + This method returns the virtual machine execution trace of a transaction. - 3.3. debug_traceTransaction + Parameters: - This method returns the virtual machine execution trace of a transaction. + - hash: [string] The transaction hash. - Parameters: - - hash: [string] The transaction hash. + Returns: - Returns: - - [array] The virtual machine execution trace as a list of steps. - - Implementation Note: This method is not currently implemented in retesteth. + - [array] The virtual machine execution trace as a list of steps. - 3.4. test_mineBlocks + Implementation Note: This method is not currently implemented in retesteth. - This method mines new blocks including all currently pending transactions. + 3.4. test_mineBlocks - Parameters: - - blocks: [int] The number of blocks to mine. + This method mines new blocks including all currently pending transactions. - Returns: - - [boolean] True if blocks were mined successfully. + Parameters: - 3.5. test_modifyTimestamp + - blocks: [int] The number of blocks to mine. - This method modifies the timestamp of the next block. - - Parameters: - - timestamp: [int] The new timestamp as a UNIX timestamp. + Returns: - Returns: - - [boolean] True if the timestamp was modified successfully. + - [boolean] True if blocks were mined successfully. - 3.6. test_rewindToBlock + 3.5. test_modifyTimestamp - This method rewinds the blockchain to the state at a previous block. - - Parameters: - - block: [int] The block number to rewind to. + This method modifies the timestamp of the next block. - Returns: - - [boolean] True if the blockchain was rewound successfully. + Parameters: - 3.7. test_setChainParams + - timestamp: [int] The new timestamp as a UNIX timestamp. - This method initializes the blockchain with the provided state data. + Returns: - 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. + - [boolean] True if the timestamp was modified successfully. - Returns: - - [boolean] True if the chain was initialized 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. 4. 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 - +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 + 5. 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. +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. 6. IANA Considerations - - This document has no IANA actions. + +This document has no IANA actions. 7. References - 7.1. Normative References + 7.1. Normative References - [JSON-RPC] JSON-RPC 2.0 Specification - https://www.jsonrpc.org/specification +[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. +[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. +[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017. - 7.2. Informative References +7.2. Informative References - [EthYellow] Ethereum Yellow Paper - https://ethereum.github.io/yellowpaper/paper.pdf +[EthYellow] Ethereum Yellow Paper https://ethereum.github.io/yellowpaper/paper.pdf - [Retesteth] Ethereum retesteth tool - https://github.com/ethereum/retesteth \ No newline at end of file +[Retesteth] Ethereum retesteth tool https://github.com/ethereum/retesteth