Skip to content

Commit 36236d5

Browse files
tkstanczakjparyani
tkstanczak
authored and
jparyani
committed
Update README.md
1 parent cb4764f commit 36236d5

File tree

5 files changed

+575
-184
lines changed

5 files changed

+575
-184
lines changed

‎MEV_spec_RPC_v0_1.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
tags: spec
3+
---
4+
5+
# MEV-Geth RPC v0.1
6+
7+
# eth_sendBundle
8+
9+
### Description
10+
11+
Sends a bundle of transactions to the miner. The bundle has to be executed at the beginning of the block (before any other transactions), with bundle transactions executed exactly in the same order as provided in the bundle. During the Flashbots Alpha this is only called by the Flashbots relay.
12+
13+
| Name | Type | Description | Comment
14+
--------|----------|-----------|-----------
15+
transactions | `Array<Data>` | Array of signed transactions (`eth_sendRawTransaction` style, signed and RLP-encoded) | a no-op in the light mode
16+
blockNumber |`Quantity` |Exact block number at which the bundle can be included. |bundle is evicted after the block
17+
minTimestamp |`Quantity` |Minimum (inclusive) block timestamp at which the bundle can be included. If this value is 0 then any timestamp is acceptable.
18+
maxTimestamp |`Quantity` |Maximum (inclusive) block timestamp at which the bundle can be included. If this value is 0 then any timestamp is acceptable.
19+
20+
### Returns
21+
22+
{`boolean`} - `true` if bundle has been accepted by the node, otherwise `false`
23+
24+
### Example
25+
26+
```bash
27+
# Request
28+
curl -X POST --data '{
29+
"id": 1337,
30+
"jsonrpc": "2.0",
31+
"method": "eth_sendBundle",
32+
"params": [
33+
[
34+
"f9014946843b9aca00830493e094a011e5f4ea471ee4341a135bb1a4af368155d7a280b8e40d5f2659000000000000000000000000fdd45a22dd1d606b3782f2119621e928e32743000000000000000000000000000000000000000000000000000000000077359400000000000000000000000000000000000000000000000",
35+
"f86e8204d085012a05f200830c350094daf24c20717f428f00d8448d74d67a77f67ceb8287354a6ba7a18000802ea00e411bcb660dd8d47717df89078d2e8160c08e7f11cb7ad0ee935e7436eceb32a013ee00a21b7fa0a9f9c1224d11261648191875d4633aed6003543ea319f12b62"
36+
],
37+
"0x12ab34",
38+
"0x0",
39+
"0x0"
40+
]
41+
}' <url>
42+
43+
# Response
44+
{
45+
"id": 1337,
46+
"jsonrpc": "2.0",
47+
"result": "true"
48+
}
49+
```
50+
51+
# eth_callBundle
52+
53+
### Description
54+
55+
Simulate a bundle of transactions at the top of a block.
56+
57+
After retrieving the block specified in the `blockNrOrHash` it takes the same `blockhash`, `gasLimit`, `difficulty`, same `timestamp` unless the `blockTimestamp` property is specified, and increases the block number by `1`. `eth_callBundle` will timeout after `5` seconds.
58+
59+
| Name | Type | Description |
60+
| ---- | ---- | ----------- |
61+
| encodedTxs | `Array<Data>` | Array of signed transactions (`eth_sendRawTransaction` style, signed and RLP-encoded) |
62+
| blockNrOrHash | `Quantity\|string\|Block Identifier` | Block number, or one of "latest", "earliest" or "pending", or a block identifier as described in {Block Identifier} |
63+
| blockTimestamp |`Quantity` |Block timestamp to be used in replacement of the timestamp taken from the parent block. |
64+
65+
### Returns
66+
67+
Map<`Data`, "error|value" : `Data`> - a mapping from transaction hashes to execution results with error or output (value) for each of the transactions
68+
69+
### Example
70+
71+
```bash
72+
# Request
73+
curl -X POST --data '{
74+
"id": 1337,
75+
"jsonrpc": "2.0",
76+
"method": "eth_callBundle",
77+
"params": [
78+
[
79+
"f9014946843b9aca00830493e094a011e5f4ea471ee4341a135bb1a4af368155d7a280b8e40d5f2659000000000000000000000000fdd45a22dd1d606b3782f2119621e928e32743000000000000000000000000000000000000000000000000000000000077359400000000000000000000000000000000000000000000000",
80+
"f86e8204d085012a05f200830c350094daf24c20717f428f00d8448d74d67a77f67ceb8287354a6ba7a18000802ea00e411bcb660dd8d47717df89078d2e8160c08e7f11cb7ad0ee935e7436eceb32a013ee00a21b7fa0a9f9c1224d11261648191875d4633aed6003543ea319f12b62"
81+
],
82+
"0x12ab34"
83+
]
84+
}' <url>
85+
86+
# Response
87+
{
88+
"id": 1337,
89+
"jsonrpc": "2.0",
90+
"result":
91+
{
92+
"0x22b3806fbef9532db4105475222983404783aacd4d865ea5dab76a84aa1a07eb" : {
93+
"value" : "0x0012"
94+
},
95+
"0x489e3b5493af31d55059f8e296351b267720bc4ba7dc170871c1d789e5541027" : {
96+
"value" : "0xabcd"
97+
}
98+
}
99+
}
100+
```
101+
102+
---
103+
104+
Below type description can also be found in [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474)
105+
106+
### `Quantity`
107+
108+
- A `Quantity` value **MUST** be hex-encoded.
109+
- A `Quantity` value **MUST** be "0x"-prefixed.
110+
- A `Quantity` value **MUST** be expressed using the fewest possible hex digits per byte.
111+
- A `Quantity` value **MUST** express zero as "0x0".
112+
113+
### `Data`
114+
115+
- A `Data` value **MUST** be hex-encoded.
116+
- A `Data` value **MUST** be “0x”-prefixed.
117+
- A `Data` value **MUST** be expressed using two hex digits per byte.
118+
119+
### `Block Identifier`
120+
121+
Since there is no way to clearly distinguish between a `Data` parameter and a `Quantity` parameter, [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898) provides a format to specify a block either using the block hash or block number. The block identifier is a JSON `object` with the following fields:
122+
123+
| Position | Name | Type | Description |
124+
| -------- | ---- | ---- | ------------|
125+
| 0A |blockNumber |`Quantity` |The block in the canonical chain with this number |
126+
| 0B |blockHash |`Data` | The block uniquely identified by this hash. The blockNumber and blockHash properties are mutually exclusive; exactly one of them must be set. |
127+
| 1B |requireCanonical |`boolean` | (optional) Whether or not to throw an error if the block is not in the canonical chain as described below. Only allowed in conjunction with the blockHash tag. Defaults to false. |
128+
129+
130+
If the block is not found, the callee SHOULD raise a JSON-RPC error (the recommended error code is `-32001: Resource not found`. If the tag is `blockHash` and `requireCanonical` is `true`, the callee SHOULD additionally raise a JSON-RPC error if the block is not in the canonical chain (the recommended error code is `-32000: Invalid input` and in any case should be different than the error code for the block not found case so that the caller can distinguish the cases). The block-not-found check SHOULD take precedence over the block-is-canonical check, so that if the block is not found the callee raises block-not-found rather than block-not-canonical.

‎MEV_spec_RPC_v0_2.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
tags: spec
3+
---
4+
5+
# MEV-Geth RPC v0.2
6+
7+
# eth_sendBundle
8+
9+
### Description
10+
11+
Sends a bundle of transactions to the miner. The bundle has to be executed at the beginning of the block (before any other transactions), with bundle transactions executed exactly in the same order as provided in the bundle. During the Flashbots Alpha this is only called by the Flashbots relay.
12+
13+
| Name | Type | Description | Comment
14+
--------|----------|-----------|-----------
15+
txs | `Array<Data>` | Array of signed transactions (`eth_sendRawTransaction` style, signed and RLP-encoded) | a no-op in the light mode
16+
blockNumber |`Quantity` |Exact block number at which the bundle can be included. |bundle is evicted after the block
17+
minTimestamp |`Quantity` |Minimum (inclusive) block timestamp at which the bundle can be included. If this value is 0 then any timestamp is acceptable.
18+
maxTimestamp |`Quantity` |Maximum (inclusive) block timestamp at which the bundle can be included. If this value is 0 then any timestamp is acceptable.
19+
revertingTxHashes |Array<`Data`> |Array of tx hashes within the bundle that are allowed to cause the EVM execution to revert without preventing the bundle inclusion in a block.
20+
21+
### Returns
22+
23+
{`boolean`} - `true` if bundle has been accepted by the node, otherwise `false`
24+
25+
### Example
26+
27+
```bash
28+
# Request
29+
curl -X POST --data '{
30+
"id": 1337,
31+
"jsonrpc": "2.0",
32+
"method": "eth_sendBundle",
33+
"params": [
34+
{
35+
"txs" : [
36+
"f9014946843b9aca00830493e094a011e5f4ea471ee4341a135bb1a4af368155d7a280b8e40d5f2659000000000000000000000000fdd45a22dd1d606b3782f2119621e928e32743000000000000000000000000000000000000000000000000000000000077359400000000000000000000000000000000000000000000000",
37+
"f86e8204d085012a05f200830c350094daf24c20717f428f00d8448d74d67a77f67ceb8287354a6ba7a18000802ea00e411bcb660dd8d47717df89078d2e8160c08e7f11cb7ad0ee935e7436eceb32a013ee00a21b7fa0a9f9c1224d11261648191875d4633aed6003543ea319f12b62"
38+
],
39+
"blockNumber" : "0x12ab34",
40+
"minTimestamp" : "0x0",
41+
"minTimestamp" :"0x0"
42+
}
43+
]
44+
}' <url>
45+
46+
# Response
47+
{
48+
"id": 1337,
49+
"jsonrpc": "2.0",
50+
"result": "true"
51+
}
52+
```
53+
54+
# eth_callBundle
55+
56+
### Description
57+
58+
Simulate a bundle of transactions at the top of a block.
59+
60+
After retrieving the block specified in the `blockNrOrHash` it takes the same `blockhash`, `gasLimit`, `difficulty`, same `timestamp` unless the `blockTimestamp` property is specified, and increases the block number by `1`. `eth_callBundle` will timeout after `5` seconds.
61+
62+
| Name | Type | Description |
63+
| ---- | ---- | ----------- |
64+
| encodedTxs | `Array<Data>` | Array of signed transactions (`eth_sendRawTransaction` style, signed and RLP-encoded) |
65+
| blockNrOrHash | `Quantity\|string\|Block Identifier` | Block number, or one of "latest", "earliest" or "pending", or a block identifier as described in {Block Identifier} |
66+
| blockTimestamp |`Quantity` |Block timestamp to be used in replacement of the timestamp taken from the parent block. |
67+
68+
### Returns
69+
70+
Map<`Data`, "error|value" : `Data`> - a mapping from transaction hashes to execution results with error or output (value) for each of the transactions
71+
72+
### Example
73+
74+
```bash
75+
# Request
76+
curl -X POST --data '{
77+
"id": 1337,
78+
"jsonrpc": "2.0",
79+
"method": "eth_callBundle",
80+
"params": [
81+
[
82+
"f9014946843b9aca00830493e094a011e5f4ea471ee4341a135bb1a4af368155d7a280b8e40d5f2659000000000000000000000000fdd45a22dd1d606b3782f2119621e928e32743000000000000000000000000000000000000000000000000000000000077359400000000000000000000000000000000000000000000000",
83+
"f86e8204d085012a05f200830c350094daf24c20717f428f00d8448d74d67a77f67ceb8287354a6ba7a18000802ea00e411bcb660dd8d47717df89078d2e8160c08e7f11cb7ad0ee935e7436eceb32a013ee00a21b7fa0a9f9c1224d11261648191875d4633aed6003543ea319f12b62"
84+
],
85+
"0x12ab34"
86+
]
87+
}' <url>
88+
89+
# Response
90+
{
91+
"id": 1337,
92+
"jsonrpc": "2.0",
93+
"result":
94+
{
95+
"0x22b3806fbef9532db4105475222983404783aacd4d865ea5dab76a84aa1a07eb" : {
96+
"value" : "0x0012"
97+
},
98+
"0x489e3b5493af31d55059f8e296351b267720bc4ba7dc170871c1d789e5541027" : {
99+
"value" : "0xabcd"
100+
}
101+
}
102+
}
103+
```
104+
105+
---
106+
107+
Below type description can also be found in [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474)
108+
109+
### `Quantity`
110+
111+
- A `Quantity` value **MUST** be hex-encoded.
112+
- A `Quantity` value **MUST** be "0x"-prefixed.
113+
- A `Quantity` value **MUST** be expressed using the fewest possible hex digits per byte.
114+
- A `Quantity` value **MUST** express zero as "0x0".
115+
116+
### `Data`
117+
118+
- A `Data` value **MUST** be hex-encoded.
119+
- A `Data` value **MUST** be “0x”-prefixed.
120+
- A `Data` value **MUST** be expressed using two hex digits per byte.
121+
122+
### `Block Identifier`
123+
124+
Since there is no way to clearly distinguish between a `Data` parameter and a `Quantity` parameter, [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898) provides a format to specify a block either using the block hash or block number. The block identifier is a JSON `object` with the following fields:
125+
126+
| Position | Name | Type | Description |
127+
| -------- | ---- | ---- | ------------|
128+
| 0A |blockNumber |`Quantity` |The block in the canonical chain with this number |
129+
| 0B |blockHash |`Data` | The block uniquely identified by this hash. The blockNumber and blockHash properties are mutually exclusive; exactly one of them must be set. |
130+
| 1B |requireCanonical |`boolean` | (optional) Whether or not to throw an error if the block is not in the canonical chain as described below. Only allowed in conjunction with the blockHash tag. Defaults to false. |
131+
132+
133+
If the block is not found, the callee SHOULD raise a JSON-RPC error (the recommended error code is `-32001: Resource not found`. If the tag is `blockHash` and `requireCanonical` is `true`, the callee SHOULD additionally raise a JSON-RPC error if the block is not in the canonical chain (the recommended error code is `-32000: Invalid input` and in any case should be different than the error code for the block not found case so that the caller can distinguish the cases). The block-not-found check SHOULD take precedence over the block-is-canonical check, so that if the block is not found the callee raises block-not-found rather than block-not-canonical.

‎MEV_spec_v0_1.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
tags: spec
3+
---
4+
5+
# MEV-Geth v0.1 specification
6+
7+
## Simple Summary
8+
9+
Defines the construction and usage of MEV bundles by the miners. Provides specification for custom implementation of required node changes so that MEV bundles can be used correctly.
10+
11+
## Abstract
12+
13+
`MevBundles` are stored by the node and the best bundle is added to the block in front of other transactions. `MevBundles` are sorted by their `adjusted gas price`.
14+
15+
## Motivation
16+
17+
We believe that without the adoption of neutral, public, open-source infrastructure for permissionless MEV extraction, MEV risks becoming an insiders' game. We commit as an organisation to releasing reference implementations for participation in fair, ethical, and politically neutral MEV extraction.
18+
19+
## Specification
20+
21+
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](https://www.ietf.org/rfc/rfc2119.txt).
22+
23+
### Definitions
24+
25+
#### `Bundle`
26+
A set of transactions that `MUST` be executed together and `MUST` be executed at the beginning of the block.
27+
28+
#### `Unit of work`
29+
A `transaction`, a `bundle` or a `block`.
30+
31+
#### `Subunit`
32+
A discernible `unit of work` that is a part of a bigger `unit of work`. A `transaction` is a `subunit` of a `bundle` or a `block`. A `bundle` is a `subunit` of a `block`.
33+
34+
#### `Total gas used`
35+
A sum of gas units used by each transaction from the `unit of work`.
36+
37+
#### `Average gas price`
38+
Sum of (`gas price` * `total gas used`) of all `subunits` divided by the `total gas used` of the unit.
39+
40+
#### `Direct coinbase payment`
41+
A value of a transaction with a recipient set to be the same as the `coinbase` address.
42+
43+
#### `Contract coinbase payment`
44+
A payment from a smart contract to the `coinbase` address.
45+
46+
#### `Profit`
47+
A difference between the balance of the `coinbase` account at the end and at the beginning of the execution of a `unit of work`. We can measure a `transaction profit`, a `bundle profit`, and a `block profit`.
48+
49+
Balance of the `coinbase` account changes in the following way
50+
|Unit of work|Balance Change|
51+
|-|-|
52+
|Transaction| `average gas price` * `total gas used` + `direct coinbase payment` + `contract coinbase payment` |
53+
|Bundle | `average gas price` * `total gas used` + `direct coinbase payment` + `contract coinbase payment` |
54+
|Block | `block reward` + `average gas price` * `total gas used` + `direct coinbase payment` + `contract coinbase payment` |
55+
56+
#### `Adjusted gas price`
57+
`Unit of work` `profit` divided by the `total gas used` by the `unit of work`.
58+
59+
#### `MevBundle`
60+
An object with four properties:
61+
62+
|Property| Type|Description|
63+
|-|-|-|
64+
|`transactions`|`Array<RLP(SignedTransaction)>`|A list of transactions in the bundle. Each transaction is signed and RLP-encoded.|
65+
|`blockNumber`|`uint64`|The exact block number at which the bundle can be executed|
66+
|`minTimestamp`|`uint64`|Minimum block timestamp (inclusive) at which the bundle can be executed|
67+
|`maxTimestamp`|`uint64`|Maximum block timestamp (inclusive) at which the bundle can be executed|
68+
69+
### Bundle construction
70+
71+
Bundle `SHOULD` contain transactions with nonces that are following the current nonces of the signing addresses or other transactions preceding them in the same bundle.
72+
73+
A bundle `MUST` contain at least one transaction. There is no upper limit for the number of transactions in the bundle, however bundles that exceed the block gas limit will always be rejected.
74+
75+
A bundle `MAY` include a `direct coinbase payment` or a `contract coinbase payment`. Bundles that do not contain such payments may lose comparison when their `profit` is compared with other bundles.
76+
77+
The `maxTimestamp` value `MUST` be greater or equal the `minTimestamp` value.
78+
79+
### Accepting bundles from the network
80+
81+
Node `MUST` provide a way of exposing a JSON RPC endpoint accepting `eth_sendBundle` calls (specified [here](MEV_spec_RPC_v0_1.md)). Such endpoint `SHOULD` only be accepting calls from `MEV-relay` but there is no requirement to restrict it through the node source code as it can be done on the infrastructure level.
82+
83+
### Bundle eligibility
84+
85+
Any bundle that is correctly constructed `MUST` have a `blockNumber` field set which specifies in which block it can be included. If the node has already progressed to a later block number then such bundle `MAY` be removed from memory.
86+
87+
Any bundle that is correctly constructed `MAY` have a `minTimestamp` and/or a `maxTimestamp` field set. Default values for both of these fields are `0` and the meaning of `0` is that any block timestamp value is accepted. When these values are not `0`, then `block.timestamp` is compared with them. If the current `block.timestamp` is greater than the `maxTimestamp` then the bundle `MUST NOT` be included in the block and `MAY` be removed from memory. If the `block.timestamp` is less than `minTimestamp` then the bundle `MUST NOT` be included in the block and `SHOULD NOT` be removed from memory (it awaits future blocks).
88+
89+
### Block construction
90+
91+
A block `MUST` either contain one bundle or no bundles. When a bundle is included it `MUST` be the bundle with the highest `adjusted gas price` among eligible bundles. The node `SHOULD` be able to compare a `block profit` in cases when a bundle is included (MEV block) and when no bundles are included (regular block) and choose a block with the highest `profit`.
92+
93+
A block with a bundle `MUST` place the bundle at the beginning of the block and `MUST NOT` insert any transactions between the bundle transactions.
94+
95+
### Bundle eviction
96+
97+
Node `SHOULD` be able to limit the number of bundles kept in memory and apply an algorithm for selecting bundles to be evicted when too many eligible bundles have been received.
98+
99+
## Rationale
100+
101+
### At most one MevBundle gets included in the block
102+
103+
There are two reasons for which multiple bundles in a block may cause problems:
104+
105+
- two bundles may affect each other's `profit` and so the bundle creator may not be willing to accept a possibility of not being added in the front of the block
106+
- simulating multiple bundle combinations may be very straining for the node infrastructure and introduce excessive latency into the block creation process
107+
108+
Both of these problems may be addressed in the future versions.
109+
110+
## Each bundle needs a blockNumber
111+
112+
This allows specifying bundles to be included in the future blocks (e.g. just after some smart contracts change their state). This cannot be used to ensure a specific parent block / hash.
113+
114+
## Backwards Compatibility
115+
116+
This change is not affecting consensus and is fully backwards compatible.
117+
118+
## Security Considerations
119+
120+
`MevBundles` that are awaiting future blocks must be stored by the miner's node and it is important to ensure that there is a mechanism to ensure that the storage is limits are not exceeded (whether they are store in memory or persisted).

0 commit comments

Comments
 (0)