Users and searchers can use mev_sendBundle to send a bundle of transactions [and transaction hashes] to a MEV-Share Node. Nodes can use mev_sendBundle to send a bundle of transactions to a block builder.
type requestBody = {
jsonrpc: "2.0",
id: string | number,
method: "mev_sendBundle",
params: [{ /* MevSendBundleParams */
version: "v0.1", // Not optional
inclusion: {
block: string, // hex-encoded number
maxBlock?: string, // hex-encoded number
},
body: Array<
{ hash: string } |
{ tx: string, canRevert: boolean } |
{ bundle: MevSendBundleParams }
>,
validity? : {
refund?: Array<{
bodyIdx: number,
percent: number,
}>,
refundConfig?: Array<{
address: string,
percent: number,
}>,
},
privacy?: {
hints?: Array<
"calldata" |
"contract_address" |
"logs" |
"function_selector" |
"hash" |
"tx_hash"
>,
builders?: Array<string>,
},
}]
}NOTE: Optional fields are marked with a ?.
Version of MEV-Share API specification to use.
Data used by block builders to check if bundle should be considered for inclusion in their block-building attempt. Data from inclusion is used as input for a predicate function that is fast to compute.
| Param | Type Info | Description |
|---|---|---|
block |
Hex-encoded string | The [first] block in which this bundle must be included. |
maxBlock |
Hex-encoded string; optional | The maximum block height in which this bundle may be included. |
If only block is specified, the bundle may only be included in that block. If maxBlock is specified, the bundle may be included in any block between block and maxBlock, inclusively.
An array of transactions to be sent; the body of the bundle. Each item in the array may include per-transaction validity conditions.
A transaction is wrapped in an object to specify which type of transaction it is.
Transactions picked up from listening to the mev-share endpoint will only give listeners a transaction hash (and not a signature). These transactions are placed in the array with the {hash} wrapper.
New signed transactions are placed in the array with the {tx, canRevert} wrapper.
If canRevert is true, the item is allowed to either revert or be discarded from the bundle.
An example (backrun) might look something like this:
...
"body": [
{
"hash": "0x3232323232323232323232323232323232323232323232323232323232323232"
},
{
"tx": "0x020424242424212312312312301230123012301230123012301230123012032424242123123124242421231231242424212312312424242123123124242421231231",
"canRevert": false
}
]Bundles are designed to support composition with other bundles.
By specifying a bundle hash in the body parameter, searchers can nest bundles within their bundles, achieving the same atomicity as if the transactions in the nested bundle were in the parent bundle.
Bundles appear the same as transactions in the event stream; this is why the hash is named as such. It can be either a bundle hash or a transaction hash.
"body": [
{ "hash": "0x4567..." }, // bundle hash
{ "hash": "0x3232..." }, // transaction hash
{ "tx": "0x0204...", "canRevert": false } // signed tx
]Entire bundles can also be included using the {bundle} wrapper. This example backruns a bundle with a transaction:
{
...,
"body": [
{
"bundle": {
"version": "v0.2",
"inclusion": {
"block": "0x463e",
"maxBlock": "0x4648"
},
"body": [
{
"tx": "0x02..."
}
],
"privacy": {
"hints": [
"calldata"
]
},
"validity": {
"refundConfig": [
{
"address": "0x8EC1237b1E80A6adf191F40D4b7D095E21cdb18f",
"percent": 100
}
]
}
}
},
{
"tx": "0x02..."
}
],
...
}Requirements for the bundle to be included in a block, checked by the builder after the bundle is considered for placement in a block.
For example, refund (MEV kickback) parameters are considered as a post-inclusion predicate, so they are specified here.
| Param | Type Info | Description |
|---|---|---|
refund |
Array of objects | Specifies the minimum percent of a given bundle's earnings to redistribute for it to be included in a builder's block. |
refund.bodyIdx |
Number | Index of the entry in body to which the refund percentage applies. |
refund.percent |
Number | Minimum refund percentage required for this bundle to be eligible for use by another searcher, paid by said searcher from the profit generated by including this bundle in theirs. |
refundConfig |
Array of objects | Specifies what addresses should receive what percent of the overall refund for this bundle, if it is enveloped by another bundle (eg. a searcher backrun). The sum of percents in this array should equal 100. |
refundConfig.address |
String | Address which receives the portion of the refund. |
refundConfig.percent |
Number | Percentage of refund to pay to the address. |
The refundConfig is specified by the original party (eg. user) who sends an input to MEV-Share. Given some refund X, the refundConfig specifies what % of X should be paid to what address(es). The refundConfig is not aware of the precise refund amount X, because this is not known until after the input has been sent to MEV-Share.
The refund is set by the MEV-Share Node. It identifies what items in the bundle should be refunded -- ie. when a searcher submits a new bundle back to the MEV-Share Node, what indices contained hashes. The builder must simulate the bundle without these input transactions to determine what portion of the overall bundle payment came from searcher bids and should be redistributed. If bundles contain multiple input items then the MEV-Share Node is responsible for allocating the searcher bids across the other items in the bundle. The party who submits the input to the MEV-Share Node could also use this field to specify their preference for what percentage of the searcher bid they receive. The MEV-Share Node would use this information when producing the final refund field that is sent to a block builder.
Preferences on what data should be shared about the bundle and its transactions. Optional.
| Param | Type Info | Description |
|---|---|---|
hints |
Array of strings; optional | Each item additively specifies which data about all transactions in the bundle to share. If no hints are specified, no data is shared. Transactions from other users that do not specify the same hints will not share additional information. |
builders |
Array of strings; optional | Builders that have permission to receive this bundle and include it in a block. |
type responseBody = {
"bundleHash": string // hex-string
}Hash of the list of bundle bodies defined by bundle composition. If there is only one bundle in the list, the bundleHash returns the hash of that bundle body.