Release new RPC Methods

mev_sendBetaBundle.md

@@ -0,0 +1,83 @@
+Creating an Ethereum Improvement Proposal (EIP) for a custom JSON-RPC method involves several key components. Below is a structured approach to drafting an EIP for the `mev_sendBetaBundle` method, based on the provided information. This draft aims to follow the EIP format closely, incorporating rationale, specifications, and examples.
+
+---
+
+# 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.
+
+### 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.
+
+### Example
+Request:
+```json
+{
+  "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
+}
+```
+
+## 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.
+
+## 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.
+
+## 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.

testing_rpc.md

@@ -0,0 +1,190 @@
+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
+
+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.
+
+2.  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
+
+     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.  
+
+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  
+
+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.
+
+6.  IANA Considerations
+
+   This document has no IANA actions.
+
+7.  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