Skip to content

Commit c395940

Browse files
sambachasambacha
authored
Create README.md
1 parent 5e5edb7 commit c395940

File tree

1 file changed

+205
-0
lines changed

1 file changed

+205
-0
lines changed

‎eth_computeBundleGas/README.md

+205
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
eip: TBD
3+
title: Bundle Gas Computation RPC Method
4+
description: A new RPC method, eth_computeBundleGas, for calculating adjusted gas prices for transaction bundles
5+
author:
6+
discussions-to: TBD
7+
status: Draft
8+
type: Standards Track
9+
category: Interface
10+
created: 2024-12-16
11+
requires: 1559, 4337
12+
---
13+
14+
## Abstract
15+
16+
This EIP introduces a new JSON-RPC method `eth_computeBundleGas` that calculates the adjusted gas price for a bundle of transactions, taking into account gas usage, original gas prices, and direct coinbase transfers. This method is particularly useful for MEV-aware applications and bundle builders.
17+
18+
## Motivation
19+
20+
Transaction bundles have become increasingly important with the rise of MEV extraction and complex DeFi interactions. Currently, there is no standardized way to:
21+
22+
1. Calculate the effective gas price for a bundle of transactions
23+
2. Account for direct coinbase payments in bundle pricing
24+
3. Determine the total value extraction from a bundle
25+
26+
## Specification
27+
28+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
29+
30+
31+
### eth_computeBundleGas
32+
33+
> [!IMPORTANT]
34+
> JSON-RPC Method Definition
35+
>
36+
37+
Computes the adjusted gas price for a bundle of transactions, accounting for all gas expenditure and coinbase transfers.
38+
39+
##### Parameters
40+
41+
1. `Array of Object` - The bundle of transactions
42+
- Each object MUST contain:
43+
- `hash`: `DATA` - Transaction hash
44+
- `gasUsed`: `QUANTITY` - Gas used by the transaction
45+
- `gasPrice`: `QUANTITY` - Original gas price
46+
- `coinbaseTransfers`: `QUANTITY` - Value transferred to coinbase
47+
48+
##### Returns
49+
50+
`Object` - The bundle gas calculation results
51+
- `adjustedGasPrice`: `QUANTITY` - The computed adjusted gas price for the bundle
52+
- `totalGasUsed`: `QUANTITY` - Total gas consumed by the bundle
53+
- `totalValue`: `QUANTITY` - Total value including gas costs and coinbase transfers
54+
- `perTxMetrics`: `Array of Object` - OPTIONAL. Detailed metrics for each transaction
55+
- `effectiveGasPrice`: `QUANTITY` - Individual transaction's effective gas price
56+
- `valueContribution`: `QUANTITY` - Transaction's contribution to total value
57+
58+
##### Implementation Requirements
59+
60+
Clients implementing this method MUST:
61+
62+
1. Calculate bundle metrics using the following formulas:
63+
```
64+
totalGasUsed = sum(tx.gasUsed for tx in bundle)
65+
totalGasCost = sum(tx.gasUsed * tx.gasPrice for tx in bundle)
66+
totalCoinbaseTransfers = sum(tx.coinbaseTransfers for tx in bundle)
67+
adjustedGasPrice = (totalGasCost + totalCoinbaseTransfers) / totalGasUsed
68+
```
69+
70+
2. Validate the bundle:
71+
- Ensure at least one transaction is present
72+
- Verify all required fields are present for each transaction
73+
- Check that all numerical values are valid and non-negative
74+
75+
3. Handle edge cases:
76+
- Return an error if totalGasUsed is zero
77+
- Handle arithmetic overflow in calculations
78+
- Properly round results when division is not exact
79+
80+
##### Example
81+
82+
Request:
83+
```json
84+
{
85+
"id": 1,
86+
"jsonrpc": "2.0",
87+
"method": "eth_computeBundleGas",
88+
"params": [[
89+
{
90+
"hash": "0x123...",
91+
"gasUsed": "0x5208",
92+
"gasPrice": "0x4a817c800",
93+
"coinbaseTransfers": "0x0"
94+
},
95+
{
96+
"hash": "0x456...",
97+
"gasUsed": "0x7530",
98+
"gasPrice": "0x4a817c800",
99+
"coinbaseTransfers": "0x2386f26fc10000"
100+
}
101+
]]
102+
}
103+
```
104+
105+
Response:
106+
```json
107+
{
108+
"id": 1,
109+
"jsonrpc": "2.0",
110+
"result": {
111+
"adjustedGasPrice": "0x4d853c800",
112+
"totalGasUsed": "0xc738",
113+
"totalValue": "0x2386f26fc10000",
114+
"perTxMetrics": [
115+
{
116+
"effectiveGasPrice": "0x4a817c800",
117+
"valueContribution": "0x1234"
118+
},
119+
{
120+
"effectiveGasPrice": "0x4f817c800",
121+
"valueContribution": "0x5678"
122+
}
123+
]
124+
}
125+
}
126+
```
127+
128+
### Security Considerations
129+
130+
1. Bundle Size Limits
131+
- Implementations MUST set a maximum bundle size
132+
- Implementations SHOULD limit total computation time
133+
134+
2. Numerical Handling
135+
- All arithmetic operations MUST handle overflow conditions
136+
- Implementations SHOULD use appropriate precision for calculations
137+
138+
3. Resource Protection
139+
- Methods MUST implement rate limiting
140+
- Implementations SHOULD cache results for identical bundles briefly
141+
142+
4. Input Validation
143+
- All transaction parameters MUST be validated
144+
- Implementations SHOULD check for realistic value ranges
145+
146+
### Backwards Compatibility
147+
148+
This EIP introduces a new method and does not modify existing behavior. No backwards compatibility issues are present.
149+
150+
## Rationale
151+
152+
The design choices in this specification are motivated by several factors:
153+
154+
1. Including per-transaction metrics allows for detailed analysis of bundle composition
155+
156+
2. Separating coinbase transfers from gas costs provides transparency into MEV extraction
157+
158+
3. The comprehensive validation requirements ensure consistent behavior across clients
159+
160+
4. The method name clearly indicates its purpose while following Ethereum naming conventions
161+
162+
## Reference Implementation
163+
164+
```go
165+
func (s *PublicBlockChainAPI) ComputeBundleGas(bundle []BundleTransaction) (*BundleGasResult, error) {
166+
if len(bundle) == 0 {
167+
return nil, errors.New("empty bundle")
168+
}
169+
170+
totalGasUsed := new(big.Int)
171+
totalGasCost := new(big.Int)
172+
totalCoinbaseTransfers := new(big.Int)
173+
perTxMetrics := make([]TxMetrics, len(bundle))
174+
175+
for i, tx := range bundle {
176+
// Calculate gas cost
177+
gasCost := new(big.Int).Mul(tx.GasUsed, tx.GasPrice)
178+
totalGasCost.Add(totalGasCost, gasCost)
179+
180+
// Add gas used
181+
totalGasUsed.Add(totalGasUsed, tx.GasUsed)
182+
183+
// Add coinbase transfers
184+
totalCoinbaseTransfers.Add(totalCoinbaseTransfers, tx.CoinbaseTransfers)
185+
186+
// Calculate per-tx metrics
187+
perTxMetrics[i] = calculateTxMetrics(tx, gasCost)
188+
}
189+
190+
// Calculate adjusted gas price
191+
adjustedGasPrice := new(big.Int).Add(totalGasCost, totalCoinbaseTransfers)
192+
adjustedGasPrice.Div(adjustedGasPrice, totalGasUsed)
193+
194+
return &BundleGasResult{
195+
AdjustedGasPrice: (*hexutil.Big)(adjustedGasPrice),
196+
TotalGasUsed: (*hexutil.Big)(totalGasUsed),
197+
TotalValue: (*hexutil.Big)(totalCoinbaseTransfers),
198+
PerTxMetrics: perTxMetrics,
199+
}, nil
200+
}
201+
```
202+
203+
## Copyright
204+
205+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

0 commit comments

Comments
 (0)