# Builder-API post ePBS for Off-Protocol Builders Design 2
## Introduction
This document aims to explore one design on how the Builder-API can evolve post ePBS for off-protocol builders. We can refer to a previous design in https://hackmd.io/SecxqKCKTTCQE0NA9AMBnA?both
## Type definitions
We define some of the types we will be frequently using in our discussion of the API.
```python
class ExecutionPayloadHeader(Container):
parent_hash: Hash32
fee_recipient: ExecutionAddress
state_root: Bytes32
receipts_root: Bytes32
logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
prev_randao: Bytes32
block_number: uint64
gas_limit: uint64
gas_used: uint64
timestamp: uint64
extra_data: ByteList[MAX_EXTRA_DATA_BYTES]
base_fee_per_gas: uint256
block_hash: Hash32
transactions_root: Root
withdrawals_root: Root
blob_gas_used: uint64
excess_blob_gas: uint64
```
```python
class ExecutionPayloadBid(Container):
parent_block_hash: Hash32
parent_block_root: Root
block_hash: Hash32
prev_randao: Bytes32
fee_recipient: ExecutionAddress
gas_limit: uint64
builder_index: ValidatorIndex
slot: Slot
value: Gwei
execution_payment: Gwei
blob_kzg_commitments_root: Root
```
```python
class SignedExecutionPayloadBid(Container):
message: ExecutionPayloadBid
signature: BLSSignature
```
```python
class ExecutionPayloadEnvelope(Container):
payload: ExecutionPayload
execution_requests: ExecutionRequests
builder_index: ValidatorIndex
beacon_block_root: Root
slot: Slot
blob_kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK]
state_root: Root
```
```python
class SignedExecutionPayloadEnvelope(Container):
message: ExecutionPayloadEnvelope
signature: BLSSignature
```
```python
class BlindedExecutionPayloadEnvelope(Container):
payload: Root
execution_requests: Root
builder_index: ValidatorIndex
beacon_block_root: Root
slot: Slot
blob_kzg_commitments: Root
state_root: Root
```
```python
class SignedBlindedExecutionPayloadEnvelope(Container):
message: BlindedExecutionPayloadEnvelope
signature: BLSSignature
```
## Builder-API with ePBS
When the proposer sources bids from external relays/builders using the Builder-API, it has to behave as if it is self-building to the protocol.
On a high level, the proposer<>relay/builder interactions would look like the following (Note that we use relay and builder interchangably):
1. The proposer sends a `getHeader` request to the relay. It receives the `ExecutionPayloadBid` along with the `ExecutionPayloadHeader`, `ExecutionRequests` and `BlobKZGCommitments`. Similar to the data sent in the `getHeader` call today : https://github.com/ethereum/builder-specs/blob/main/types/electra/bid.yaml
2. If the proposer accepts this bid, it creates a `SignedBeaconBlock` with the `ExecutionPayloadBid` embedded into it. It also creates a `SignedBlindedExecutionPayloadEnvelope`. The proposer will have enough information to run a modified version of [process_execution_payload](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#new-process_execution_payload). More details on this in an upcoming section.
3. The proposer sends the relay back the `SignedBeaconBlock` and `SignedBlindedExecutionPayloadEnvelope`. The relay and proposer can both broadcast the `SignedBeaconBlock`. The relay can construct a `SignedExecutionPayloadEnvelope` and broadcast it to the PTC commitee.
The API is generally unopinionated about how the builder pays the proposer but we can assume the status quo as today where the builder inserts a payment transaction at the end of the block to the proposer's fee recipient.
## API definitions
### Execution Payload Bid retrival
The proposer queries this API and receives the `SignedExecutionPayloadBid` along with the `ExecutionPayloadHeader`, `ExecutionRequests` and `BlobKZGCommitments` for this slot.
GET `/eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{pub_key}`
### Execution Payload Bid commitment
The proposer commits to the `ExecutionPayloadBid` by sending back to the relay, the `SignedBeaconBlock` which embeds the `ExecutionPayloadBid`. It also sends a `SignedBlindedExecutionPayloadEnvelope` to the relay which it has constructed.
POST `/eth/v1/builder/beacon_block`
## Sequence Diagram
## Creating the BlindedExecutionPayloadEnvelope
The proposer receives the `ExecutionPayloadBid`, `ExecutionPayloadHeader`, `ExecutionRequests` and `BlobKZGCommitments` from the relay.
The proposer can run a modified version of `process_execution_payload` without the engine_api invocation to validate the payload. The proposer runs `process_execution_payload` on the post-state after creating the `SignedBeaconBlock`.
## Security Considerations
1. The proposer trusts the relay to make the payment according to the value provided by `execution_payment`.
2. The proposer trusts the relay to broadcast the execution payload envelope on time.
3. The proposer trusts the relay to provide the correct payload and execution requests root along with the bid.
## Questions
1. Should the relay wait for the BeaconBlock to get enough attestations before broadcasting the `SignedExecutionPayloadEnvelope`. If the BeaconBlock doesn't get enough attestations, it could be re-orged out and the relay could avoid broadcasting the full payload to avoid paying for a block that might be re-orged out. Very unlikely to happen tho.
2. Should we have a push based system where the relay can push the bid to the proposer instead of the proposer querying the relay. The main issue with this is that the relays have to trust the proposer to pick the latest bid(and not the highest bid). It is generally not a good idea to trust the proposer.
3. We can rename the APIs.
4. We can add payment proofs in the when the proposer receives the bid. Inspired by: https://github.com/ethereum/builder-specs/pull/51
5. Do we still need to specify the slot, pubkey and parent_hash in the request to get the execution payload bid?
6. One big question we have is state_root computation of the ExecutionPayloadEnvelope. The relay can compute the state_root of the execution payload envelope but will require the proposer to sign it. This involves another signing step.
## Notes
1. If the relay fails to deliver the ExecutionPayloadEnvelope, then it will result in a missed slot. The relay and proposer would have to settle the payment offchain in such cases.
2. The relay doesn't have to return the ExecutionPayloadEnvelope back to the proposer since it will be a very large object. This is similar behaviour to the `getPayloadV2` API.
3. With `execution_payment` being specified in ExecutionPayloadBid, we can have mechanisms on-chain going forward to validate whether the payment has been indeed made by the off-chain builder.
4. The MEV-Relay probably would want the beacon block to get enough attestations before publishing the Envelope to avoid any potential unbundling attacks by the proposer.
5. Based on my knowledge, some client teams mentioned that they wouldn't support MEV-Boost or the builder-api. Regardless of what client teams do, there might be demand for out of protocol bids and it would be good to have a specification on how to source these bids.
6. Exercising the free-option problem is much easier with off-protocol bids because the payment is done via the execution payload. If the builder chooses to not broadcast the envelope than the proposer would not get paid too. We need to trust the relay to broadcast the execution payload envelope in time to the PTC.
7. The relay and builder will get the fee recipient of the validator via validator registrations.
8. We ideally don't want to return the full `ExecutionPayloadEnvelope` to the proposer as the `payload` size can go up as we increase the gas limit.
9. The beacon block has to be propagated in time for attesters to attest to it by the attestation deadline. Payload attestations are broadcasted at t=9s so there is enough time to broadcast an Execution payload envelope.
## In contrast with the design with 4 API calls
The previous design had 4 API calls. There were 4 API calls because the relay returns only the `ExecutionPayloadBid` unlike in this design where the relay returned more information namely the `ExecutionPayloadHeader`, `ExecutionRequests` and `BlobKZGCommitments`. Using this extra information, the proposer could construct a `BlindedExecutionPayloadEnvelope` albeit some modification is required to `process_execution_payload`.
It is much nicer to reduce the API calls tho.
## TODO
Add links to types
Sign in with Wallet
Connect another wallet