# Transaction Inclusion List for MEV-Boost

Ideas, questions and technical approach to implementing [inclusion lists](https://ethresear.ch/t/how-much-can-we-constrain-builders-without-bringing-back-heavy-burdens-to-proposers/13808).

Note: This document assumes the inclusion list functionality being implemented by both beacon node and mev-boost. It might be worth investigating whether this can be done exclusively in mev-boost, without changes to the BN.

## References

- Vitalik’s post about inclusion lists and partial block auctions: [ethresear.ch/t/how-much-can-we-constrain-builders-without-bringing-back-heavy-burdens-to-proposers/13808](https://ethresear.ch/t/how-much-can-we-constrain-builders-without-bringing-back-heavy-burdens-to-proposers/13808)
- Robert’s specific proposal: [ethresear.ch/t/how-much-can-we-constrain-builders-without-bringing-back-heavy-burdens-to-proposers/13808/12](https://ethresear.ch/t/how-much-can-we-constrain-builders-without-bringing-back-heavy-burdens-to-proposers/13808/12?u=metachris)
- Inclusion-list discussion on Github: [github.com/ethereum/builder-specs/issues/52](https://github.com/ethereum/builder-specs/issues/52)
- [Censorship Resistance: crlists in mev-boost (#215)](https://github.com/flashbots/mev-boost/issues/215)

More:
* [Unbundling PBS: Towards protocol-enforced proposer commitments (PEPC) (Barnabe)](https://ethresear.ch/t/unbundling-pbs-towards-protocol-enforced-proposer-commitments-pepc/13879?u=barnabe)
* [Barnabe Twitter thread on IL, partial block auctions, proposer-built prefixes and proposer-built suffixes](https://twitter.com/barnabemonnot/status/1582660856885628928?t=1AB4vKfnC-juUivDuU-itQ&s=19)

## High-level idea

1. Proposer sends a list of transactions to mev-boost relays that *must* be included in a block (for a specific slot duty of this proposer).
* Request with the inclusion list must be signed by the proposer.
* Needs to be sent before the slot duty, so builders have the information ready when they start building.
2. (The builders request the final inclusion list from the relay, when they start building.)
4. Proposer asks for a block header (bid) which includes Merkle proofs ([multiproof](https://www.wealdtech.com/articles/understanding-sparse-merkle-multiproofs/)) for the transactions being present in the block.
5. The proofs are validated by the beacon-node (and by mev-boost, which chooses the best valid bid of all the relays)

## Assumptions

1. An inclusion-list request is specific for a particular slot duty
2. The inclusion list is sent two slots before the proposer duty
* i.e. a proposer duty on slot 20
* when payload for slot 18 is received, BN sends the inclusion list
* when payload for slot 19 is received, the builders request the current inclusion list from the relay and start building blocks.

## Questions

1. **How is the inclusion list compiled?**
* Mempool is the source of transaction information.
* EL client, or a standalone tool, could offer a JSON-RPC API to receive transactions for inclusion.
* Beacon node sends a signed API request to set an inclusion list.
1. **Is this compatible with mev-boost?**
* Can mev-boost verify the necessary proofs (without EL access)? In particular proof of inclusion in previous block, and the other legitimate failure modes outlined below (if necessary).
* Would we consider connecting mev-boost to the EL client, or deprecating mev-boost-the-software?
3. **Merkle proofs**
* Are there any problems with [Merkle multiproof](https://www.wealdtech.com/articles/understanding-sparse-merkle-multiproofs/) for this?
* Does this scale well with many must-include transactions and blocks with large number of transactions?
* How do we deal with the transaction cases below, which are legitimate cases for a transaction to not be included even though on the inclusion list? How could mev-boost know which bid is valid with such cases?
* Any other concerns about the proofs?
4. **Transaction edge-cases**
1. **Transaction was already included in a previous block**
* Is there a way to add a Merkle proof for this too? If not, how could mev-boost know about the previous inclusion and still allow the bid?
* Can this be ignored for now? Could mev-boost still choose the best correct bid?
2. **Base fee rises above that in a required tx**
* BN could check that, but mev-boost not?
* Can this be ignored for now? Could mev-boost still choose the best correct bid?
* (Keep in mind that bundles might have transactions with 0 gas fee in them.)
3. **Transaction is now invalid (i.e. not enough Ether in account to pay for gas)**
* Seems neither BN nor mev-boost could check that
* Can this be ignored for now? Could mev-boost still choose the best correct bid?
4. **Other tx edge-cases to think about?**

---
## Tasks

1. Double-check high-level idea and steps.
2. Consider the questions, document answers and ideas.
3. Define example payloads for requests and bids.

---

## Example payloads

### Inclusion-list request for a specific slot: (BN -> builder network)

`POST /eth/v1/builder/inclusion_list`

{
    "message": {
        "slot": "123",
        "proposer_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
        "transactions": ["0xtx1", "0xtx2", ...]
    },
    "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}

Response: `200 OK`

### Bid (with added proofs)

Original [getHeader response](https://ethereum.github.io/builder-specs/#/Builder/getHeader) with additional proof of inclusion.

{
    "version": "bellatrix",
    "data": {
        "message": {
            "header": ExecutionPayloadHeader,
            "value": "1",
            "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
            "inclusion_proof??": ???
        },
        "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
    }
}

TODO: adding proof of inclusion to the message part of the bid.