Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add initial electra spec #101

Merged
merged 11 commits into from
Oct 9, 2024
60 changes: 60 additions & 0 deletions specs/electra/builder.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Electra -- Builder Specification

## Introduction

This is the modification of the builder specification accompanying the Electra upgrade.

jacobkaufmann marked this conversation as resolved.
Show resolved Hide resolved
The behavior defined by the specification is consistent with previous forks except for the changes to the types given below.

## Containers

### New containers

#### `ExecutionBundle`

jacobkaufmann marked this conversation as resolved.
Show resolved Hide resolved
The `ExecutionBundle` supersedes the [`ExecutionPayloadAndBlobsBundle`][execution-payload-and-blobs-bundle-deneb].

```python
class ExecutionBundle(Container):
execution_payload: ExecutionPayload
blobs_bundle: BlobsBundle
execution_requests: ExecutionRequests
ralexstokes marked this conversation as resolved.
Show resolved Hide resolved
jacobkaufmann marked this conversation as resolved.
Show resolved Hide resolved
```

### Extended containers

#### `BuilderBid`

Note: `SignedBuilderBid` is updated indirectly.

```python
class BuilderBid(Container):
header: ExecutionPayloadHeader
blob_kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK]
execution_requests: ExecutionRequests # [New in Electra]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this field type be switched to bytes If ethereum/execution-apis#591 is accepted?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it makes sense to keep them consistent. So it makes sense to change it. Otherwise we need two decoding implementations on the CL side.

Copy link
Member

@ralexstokes ralexstokes Oct 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I would leave this as-is in the spec, this repo leverages the beacon-apis so its most natural to use those definitions

can mirror the Engine API for the Builder API HTTP definition

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to @lucassaldanha point, given that this version will be in the beacon-apis, I don't think we are making an additional ask of CLs to deal with this version here

will go ahead and merge this for now to unblock devnet-4, if we decide we want to mirror the Engine API we can address in a future PR

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this field type be switched to bytes

What would be the difference of this compared to using SSZ encoding for the whole BuilderBid? It seems much cleaner to have the option to use JSON (for debugging purposes) or SSZ in transit and is what we do on the beacon-api for most of the time sensitive apis.

If we are concerned about latency, should move to using SSZ on the builder api as proposed in #104

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah I think that's a nice resolution here! and honestly likely how we should be thinking about it in the Engine API but full SSZ there will take more time

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but full SSZ there will take more time

yeah I see why this is done on the engine api, but please not on CL side, embedding ssz inside json data is just the worst of both worlds, it's harder to debug issues during development and you still send json around for all others fields + it does not allow streaming the response. Ideally, we only wanna use json for development and stuff like kurtosis testing.

value: uint256
pubkey: BLSPubkey
```

#### `BlindedBeaconBlockBody`

Note: `BlindedBeaconBlock` and `SignedBlindedBeaconBlock` types are updated indirectly.

```python
class BlindedBeaconBlockBody(Container):
randao_reveal: BLSSignature
eth1_data: Eth1Data
graffiti: Bytes32
proposer_slashings: List[ProposerSlashing, MAX_PROPOSER_SLASHINGS]
attester_slashings: List[AttesterSlashing, MAX_ATTESTER_SLASHINGS_ELECTRA] # [Modified in Electra:EIP7549]
attestations: List[Attestation, MAX_ATTESTATIONS_ELECTRA] # [Modified in Electra:EIP7549]
deposits: List[Deposit, MAX_DEPOSITS]
voluntary_exits: List[SignedVoluntaryExit, MAX_VOLUNTARY_EXITS]
sync_aggregate: SyncAggregate
execution_payload_header: ExecutionPayloadHeader
bls_to_execution_changes: List[SignedBLSToExecutionChange, MAX_BLS_TO_EXECUTION_CHANGES]
blob_kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK]
execution_requests: ExecutionRequests # [New in Electra]
```

[execution-payload-and-blobs-bundle-deneb]: ../deneb/builder.md#executionpayloadandblobsbundle
Loading