feat(eip): add eth_getbundlestat and eth_getinclusionstats

.github/workflows/spellcheck.yml

@@ -0,0 +1,11 @@
+name: 'Check spelling'
+on: # rebuild any PRs and main branch changes
+  pull_request:
+  push:
+
+jobs:
+  spellcheck: # run the action
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: streetsidesoftware/cspell-action@v6

.prettierrc.js

@@ -0,0 +1,29 @@
+'use strict';
+// "schema": "https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/prettierrc.json",
+// "$schema": "http://json.schemastore.org/prettierrc",
+module.exports = {
+  arrowParens: 'always',
+  bracketSpacing: true,
+  endOfLine: 'lf',
+  printWidth: 100,
+  proseWrap: 'never',
+  singleQuote: true,
+  tabWidth: 2,
+  trailingComma: 'all',
+  quoteProps: 'as-needed',
+  semi: true,
+  overrides: [
+    {
+      files: '*.md',
+      options: {
+        parser: 'markdown',
+        printWidth: 120,
+        proseWrap: 'never',
+        tabWidth: 4,
+        useTabs: true,
+        singleQuote: false,
+        bracketSpacing: true,
+      },
+    },
+  ],
+};

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Draft RPC Proposals
 
 > RPC Methods for various proposed/draft EIPs
 
 ## Abstract
 
@@ -12,25 +12,23 @@
 
 ## Motivation
 
-> Consider this use case. We journal everything we do. If the system dies we recover the state from that journal and move on. You need to re sync your local state with the chain first. That may mean a tx having been replaced. You can get the new tx, you can only try to fetch the old one and you receive a null. -- *Patricio Palladino*
-
-If a user accidentally uses the same account outside of your system you want to detect it, and without this method it is exceeding difficult. 
+> Consider this use case. We journal everything we do. If the system dies we recover the state from that journal and move on. You need to re sync your local state with the chain first. That may mean a tx having been replaced. You can get the new tx, you can only try to fetch the old one and you receive a null. -- _Patricio Palladino_
 
+If a user accidentally uses the same account outside of your system you want to detect it, and without this method it is exceeding difficult.
 
 ## List of RPC Specifications
 
-[eth_getTransactionBySenderAndNonce](./eth_getTransactionBySenderAndNonce.md)     
-[eth_getLogs+timestamp](./eth_getLogs+timestamp.md)        
-- https://ethereum-magicians.org/t/proposal-for-adding-blocktimestamp-to-logs-object-returned-by-eth-getlogs-and-related-requests/11183
+[eth_getTransactionBySenderAndNonce](./eth_getTransactionBySenderAndNonce.md)  
+[eth_getLogs+timestamp](./eth_getLogs+timestamp.md)
+
+-   https://ethereum-magicians.org/t/proposal-for-adding-blocktimestamp-to-logs-object-returned-by-eth-getlogs-and-related-requests/11183
 
 ## Contributors
 
-Patricio Palladino    
-Sam Bacha     
+Patricio Palladino  
+Sam Bacha  
 Wighawag
 
-## License 
+## License
 
 UPL-1.0 / CC-1.0
-
-

README.md

@@ -1,40 +1,36 @@
 # Draft Specifications for EIP and ERC's
 
 ## EIP Proposal for new Transaction Type and corresponding RPC
 
 ## Draft EIPS
 
 ### eth_getTransactionConfirmations
 
-  The purpose of this method is to return the number of transactions an account has broadcasted or sent.
+The purpose of this method is to return the number of transactions an account has broadcasted or sent.
 
 ## Well Defined EIPs
 
 Below EIPs are considered a **requeriment** for us:
 
-- [EIP-2718 | Transaction Envelopes](https://eips.ethereum.org/EIPS/eip-2718)
+-   [EIP-2718 | Transaction Envelopes](https://eips.ethereum.org/EIPS/eip-2718)
 
-  **Abstract**: `TransactionType || TransactionPayload` is a valid transaction and `TransactionType || ReceiptPayload` is a valid transaction receipt where `TransactionType` identifies the format of the transaction and `*Payload` is the transaction/receipt contents, which are defined in future EIPs.
+    **Abstract**: `TransactionType || TransactionPayload` is a valid transaction and `TransactionType || ReceiptPayload` is a valid transaction receipt where `TransactionType` identifies the format of the transaction and `*Payload` is the transaction/receipt contents, which are defined in future EIPs.
 
-- [EIP-2930 | Optional access lists](https://eips.ethereum.org/EIPS/eip-2930)
+-   [EIP-2930 | Optional access lists](https://eips.ethereum.org/EIPS/eip-2930)
 
-  **Abstract**: We introduce a new [EIP-2718](./reference/EIPS/eip-2718.md) transaction type, with the format `0x01 || rlp([chainId, nonce, gasPrice, gasLimit, to, value, data, accessList, signatureYParity, signatureR, signatureS])`.
-  The `accessList` specifies a list of addresses and storage keys; these addresses and storage keys are added into the `accessed_addresses` and `accessed_storage_keys` global sets (introduced in [EIP-2929](./reference/EIPS/eip-2929.md)). A gas cost is charged, though at a discount relative to the cost of accessing outside the list.
+    **Abstract**: We introduce a new [EIP-2718](./reference/EIPS/eip-2718.md) transaction type, with the format `0x01 || rlp([chainId, nonce, gasPrice, gasLimit, to, value, data, accessList, signatureYParity, signatureR, signatureS])`. The `accessList` specifies a list of addresses and storage keys; these addresses and storage keys are added into the `accessed_addresses` and `accessed_storage_keys` global sets (introduced in [EIP-2929](./reference/EIPS/eip-2929.md)). A gas cost is charged, though at a discount relative to the cost of accessing outside the list.
 
-- [EIP-3584 | Block Access Lists](https://eips.ethereum.org/EIPS/eip-3584)
+-   [EIP-3584 | Block Access Lists](https://eips.ethereum.org/EIPS/eip-3584)
 
-  **Abstract**: A proposal to build a block's `access_list` and include its fingerprint `AccessListRoot` in the block header.
+    **Abstract**: A proposal to build a block's `access_list` and include its fingerprint `AccessListRoot` in the block header.
 
 ### Complementary EIPs
 
 Below EIPs are considered **complimentary** we don't depend on but can serve us as inspiration:
 
-- [EIP 2976 | Typed Transactions over Gossip](https://eips.ethereum.org/EIPS/eip-2976)
+-   [EIP 2976 | Typed Transactions over Gossip](https://eips.ethereum.org/EIPS/eip-2976)
 
-  **Abstract**: [Typed Transactions](./reference/EIPS/eip-2976.md) can be sent over devp2p as `TransactionType || TransactionPayload`.
-  The exact contents of the `TransactionPayload` are defined by the `TransactionType` in future EIPs, and clients may start supporting their gossip without incrementing the devp2p version.
-  If a client receives a `TransactionType` that it doesn't recognize, it **SHOULD** disconnect from the peer who sent it.
-  Clients **MUST NOT** send new transaction types before they believe the fork block is reached.
+    **Abstract**: [Typed Transactions](./reference/EIPS/eip-2976.md) can be sent over devp2p as `TransactionType || TransactionPayload`. The exact contents of the `TransactionPayload` are defined by the `TransactionType` in future EIPs, and clients may start supporting their gossip without incrementing the devp2p version. If a client receives a `TransactionType` that it doesn't recognize, it **SHOULD** disconnect from the peer who sent it. Clients **MUST NOT** send new transaction types before they believe the fork block is reached.
 
 ## EIP Political Process
 
@@ -55,4 +51,3 @@
   Implementation --> Deferred
   Withdrawn --> [*]
 ```
-

custom-payload-header/README.md

@@ -0,0 +1,68 @@
+---
+title: Custom Payload Signature Scheme for Authenticated JSON RPC Service Access
+---
+
+> [!NOTE]  
+> This is written as an IETF RFC format with adherence to BCP 14
+
+> [!IMPORTANT]  
+>  This specification provides a structured approach to implementing a secure and authenticated method for interacting with JSON RPC service endpoints. It ensures that the requests are authenticated and traceable, enhancing the security and usability of the service.
+
+**Title**: Custom Payload Signature Scheme for Authenticated JSON RPC Service Access
+
+**Abstract**: This document specifies a method for authenticating requests to a JSON RPC service endpoint using a custom payload signature scheme. The scheme involves signing the request payload with an Ethereum key and including this signature in the request headers.
+
+**1. Introduction**: This specification defines a method for authenticating requests made to a JSON RPC service endpoint. The authentication is achieved by signing the request payload using an Ethereum key and including this signature in the request's HTTP headers. This method ensures that the requests are authenticated and can be tracked over time for user statistics.
+
+**2. Terminology**:
+
+-   **JSON RPC**: A remote procedure call protocol encoded in JSON.
+-   **Ethereum Key**: A cryptographic key used for signing transactions in the Ethereum blockchain.
+-   **Payload Signature**: A digital signature generated by signing the request payload.
+-   **X-Flashbots-Signature**: HTTP header used to include the payload signature for Flashbots requests.
+-   **X-Auction-Signature**: HTTP header used to include the payload signature for auction requests.
+
+**3. Specification**:
+
+-   **Signature Generation**:
+
+    -   The client MUST generate a digital signature by signing the hash of the JSON body of the request. The JSON body MUST be encoded as UTF-8 bytes before hashing.
+    -   Any valid Ethereum key CAN be used for signing the payload.
+    -   The Ethereum address associated with the key used for signing WILL be utilized by the service to track requests and provide user statistics.
+
+-   **Request Headers**:
+
+    -   The client MUST include the generated signature in the request headers.
+    -   For Flashbots requests, the signature MUST be included in the `X-Flashbots-Signature` header.
+    -   For auction requests, the signature MUST be included in the `X-Auction-Signature` header.
+    -   The headers `X-Flashbots-Signature` and `X-Auction-Signature` are CASE-INSENSITIVE.
+
+-   **Example Usage with cURL**:
+    -   For Flashbots requests:
+        ```
+        curl -X POST -H "Content-Type: application/json" -H "X-Flashbots-Signature: 0x1234:0xabcd" --data '{"jsonrpc":"2.0","method":"eth_sendBundle","params":[...],"id":1}' <https://api.example.com/v1/auction>
+        ```
+    -   For auction requests:
+        ```
+        curl -X POST -H "Content-Type: application/json" -H "X-Auction-Signature: 0x1234:0xabcd" --data '{"jsonrpc":"2.0","method":"eth_sendBundle","params":[...],"id":1}' <https://api.example.com/v1/auction>
+        ```
+
+**4. Security Considerations**:
+
+-   The use of Ethereum keys for signing the payload adds a layer of security by ensuring that the sender holds the corresponding private key.
+-   Clients MUST protect their Ethereum private keys to prevent unauthorized access and request forgery.
+
+**5. Backwards Compatibility**:
+
+-   This specification does not affect existing JSON RPC implementations that do not use payload signature authentication.
+-   Implementations not supporting this scheme WILL treat requests as unauthenticated.
+
+**6. References**:
+
+-   [JSON RPC Specification]
+-   [Ethereum Key Management]
+-   [Digital Signature Standards]
+
+**7. Acknowledgments**:
+
+-   Contributions to this specification by [List of Contributors].

eth_getLogs+timestamp/README.md

@@ -1,15 +1,7 @@
----
-title: Extending eth_getLogs to also return blockTimestamp
-authors: wighawag
-source: <https://github.com/ethereum/execution-apis/issues/295>
-description: A Proposal for adding blockTimestamp to logs object returned by eth_getLogs and related requests
----
-
-# `eth_getLogs` with `blockTimestamp` 
+# `eth_getLogs` with `blockTimestamp`
 
 A Proposal for adding blockTimestamp to logs object returned by eth_getLogs and related requests
 
-
 ## [](https://ethereum-magicians.org/t/proposal-for-adding-blocktimestamp-to-logs-object-returned-by-eth-getlogs-and-related-requests/11183#motivation-1)Motivation
 
 Currently, most contract events that act on the notion of time do not add timestamp information as it is already available on the block where the event occurs. This saves them the extra gas cost of adding timestamps to the events.
@@ -38,7 +30,7 @@
 -   `toBlock`: `QUANTITY|TAG` - (optional, default: `"latest"`) Integer block number, or `"latest"` for the last mined block or `"pending"`, `"earliest"` for not yet mined transactions.
 -   `address`: `DATA|Array`, 20 Bytes - (optional) Contract address or a list of addresses from which logs should originate.
 -   `topics`: `Array of DATA`, - (optional) Array of 32 Bytes `DATA` topics. Topics are order-dependent. Each topic can also be an array of DATA with “or” options.
 -   `blockhash`: `DATA`, 32 Bytes - (optional, **future**) With the addition of EIP-234, `blockHash` will be a new filter option which restricts the logs returned to the single block with the 32-byte hash `blockHash`. Using `blockHash` is equivalent to `fromBlock` = `toBlock` = the block number with hash `blockHash`. If `blockHash` is present in in the filter criteria, then neither `fromBlock` nor `toBlock` are allowed.
 
 ```jsonc
 params: [
@@ -51,7 +43,8 @@
 
 ```
 
-#### **Returns**  
+#### **Returns**
+
 `Array` - Array of log objects, with following params:
 
 -   `removed`: `TAG` - `true` when the log was removed, due to a chain reorganization. `false` if its a valid log.

eth_getTransactionConfirmations/README.md

@@ -1,7 +1,7 @@
 ---
 Title: eth_getTransactionConfirmations JSON-RPC Method Specification for Ethereum Clients
 Author: Sam Bacha, {{ contributors }}
-Date: {{ rfc.3339=seconds }}
+Date: { { rfc.3339=seconds } }
 Status: Draft
 ---
 
@@ -11,9 +11,9 @@ This document proposes a new JSON-RPC method for Ethereum clients named "eth_get
 
 ## Terminology
 
-- JSON-RPC: A remote procedure call (RPC) protocol encoded in JSON.
-- Ethereum: An open-source, blockchain-based platform featuring smart contract functionality.
-- Transaction: A signed data package that stores a message to be sent from an externally owned account.
+-   JSON-RPC: A remote procedure call (RPC) protocol encoded in JSON.
+-   Ethereum: An open-source, blockchain-based platform featuring smart contract functionality.
+-   Transaction: A signed data package that stores a message to be sent from an externally owned account.
 
 ## Specification
 
@@ -37,20 +37,20 @@ eth_getTransactionConfirmations
 
 ```json
 {
-  "id":1,
-  "jsonrpc":"2.0",
-  "method":"eth_getTransactionConfirmations",
-  "params":["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "latest", "0x1b4"]
+	"id": 1,
+	"jsonrpc": "2.0",
+	"method": "eth_getTransactionConfirmations",
+	"params": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "latest", "0x1b4"]
 }
 ```
 
 ##### Response
 
 ```json
 {
-  "id":1,
-  "jsonrpc":"2.0",
-  "result":"0x41"
+	"id": 1,
+	"jsonrpc": "2.0",
+	"result": "0x41"
 }
 ```
 

eth_getbundlestats/README.md

@@ -0,0 +1,105 @@
+---
+EIP: XXXX
+Title: Add `eth_getbundlestats` RPC Method for Bundle Analytics
+Author: [Author's Name] <[email|website]>
+Type: Standards Track
+Category: Interface
+Status: Draft
+Created: [Creation Date]
+---
+
+**EIP-XXXX: `eth_getbundlestats` RPC Method**
+
+**Preamble**
+
+**Abstract**
+
+This EIP proposes the introduction of a new JSON-RPC method, `eth_getbundlestats`, designed to provide statistical data on transaction bundles within the Ethereum network. This method aims to enhance network transparency by offering insights into bundle composition, success rates, and their impact on network congestion and gas prices.
+
+**Motivation**
+
+With the increasing complexity of Ethereum transactions and the use of transaction bundles by miners and traders, there's a growing need for better analytics around these bundles. Understanding the dynamics of bundle inclusion, their sizes, gas prices, and how they affect the Ethereum network can provide valuable insights for developers, traders, and researchers. The `eth_getbundlestats` method will fill this gap by offering detailed analytics on transaction bundles.
+
+**Specification**
+
+-   **Method Name**: `eth_getbundlestats`
+
+-   **Parameters**:
+
+    1. `BLOCK_NUMBER`: The specific block number to retrieve bundle statistics for. This parameter is REQUIRED.
+    2. `BUNDLE_IDENTIFIER`: An optional identifier for specific bundles to filter the statistics. If omitted, statistics for all bundles in the specified block are returned.
+
+-   **Returns**: An object containing statistical data about the transaction bundles within the specified block. The object includes:
+
+    -   `totalBundles`: The total number of bundles included in the block.
+    -   `averageBundleSize`: The average number of transactions per bundle.
+    -   `averageGasPrice`: The average gas price of transactions within the bundles.
+    -   `successRate`: The percentage of bundles successfully included in the block without reverts.
+    -   `details`: An array of objects, each representing a bundle, including its identifier, size, gas price, and success status.
+
+-   **Example**:
+
+    ```
+    // Request
+    {
+      "jsonrpc": "2.0",
+      "method": "eth_getbundlestats",
+      "params": [1234567],
+      "id": 1
+    }
+
+    // Response
+    {
+      "jsonrpc": "2.0",
+      "id": 1,
+      "result": {
+        "totalBundles": 5,
+        "averageBundleSize": 10,
+        "averageGasPrice": "100000000000",
+        "successRate": 80,
+        "details": [
+          {
+            "bundleIdentifier": "0x...",
+            "size": 12,
+            "gasPrice": "120000000000",
+            "success": true
+          },
+          // Additional bundles...
+        ]
+      }
+    }
+    ```
+
+**Rationale**
+
+The choice of parameters allows users to specify the exact block for which they seek bundle statistics, offering flexibility in analysis. Including an optional bundle identifier parameter enables focused studies on particular bundles of interest. The structure of the return object is designed to provide a comprehensive overview of bundle activity within a block, catering to various analytical needs.
+
+**Security Considerations**
+
+Implementations should ensure that the method does not expose nodes to additional security vulnerabilities, particularly in relation to privacy or DoS attacks. Care must be taken to prevent excessive resource consumption when calculating statistics, especially for blocks with a high number of transactions and bundles.
+
+**Backwards Compatibility**
+
+This EIP is fully backwards compatible as it introduces a new method without modifying any existing functionality.
+
+**Test Cases**
+
+Test cases should cover various scenarios, including blocks with:
+
+-   A high number of bundles
+-   No bundles
+-   Blocks during periods of high and low network congestion
+-   Requests specifying a bundle identifier and requests without it
+
+**Implementation**
+
+[Note: Implementation details or a link to the implementation code would be provided here.]
+
+**References**
+
+-   Existing JSON-RPC specification documents.
+-   Related EIPs and discussions on Ethereum transaction bundles and analytics.
+
+---
+
+This example EIP for the `eth_getbundlestats` method is hypothetical and based on assumed functionality. For a real proposal, you would need to replace placeholders with actual data and ensure the specification accurately reflects the method's implementation and intended use.