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.

Sign up for GitHub

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

Jump to bottom

Extend EIP-4844 to include withdrawals #322

Merged
merged 4 commits into from
Dec 16, 2022
Merged

Extend EIP-4844 to include withdrawals #322

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
198c96b
Extend EIP-4844 to include withdrawals
Inphi Nov 10, 2022
c19a198
Reference v2 apis; reorder fields
Inphi Nov 28, 2022
6ecb048
update wordlist for spellcheck
Inphi Nov 29, 2022
ff95a01
V3 naming for 4844 types/methods
Inphi Dec 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 49 additions & 2 deletions src/engine/blob-extension.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,49 @@
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Shard Blob Extension](#shard-blob-extension)
- [Structures](#structures)
- [ExecutionPayloadV2](#executionpayloadv2)
- [BlobsBundleV1](#blobsbundlev1)
- [Methods](#methods)
- [engine_newPayloadV2](#engine_newpayloadv2)
- [engine_getPayloadV2](#engine_getpayloadv2)
- [engine_getBlobsBundleV1](#engine_getblobsbundlev1)
- [Request](#request)
- [Response](#response)
- [Specification](#specification)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Shard Blob Extension

This is an extension specific to [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) to the `core` methods as defined in the [Engine API](./specification.md).
This extension is backwards-compatible, but not part of the initial Engine API.

## Structures

### ExecutionPayloadV2
Copy link
Member

Choose a reason for hiding this comment

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

how does this interact w/ the existing ExecutionPayloadV2?

is this extension an alternative fork of the spec?

or should this be a V3 to include the excessDataGas field?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

it's an alternative fork where withdrawals and 4844 are part of the same upgrade.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

so we reuse the existing v2 apis rather than create another one

Copy link
Member

Choose a reason for hiding this comment

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

likely worth adding a note to this effect in this document

Copy link
Contributor Author

@Inphi Inphi Nov 11, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

This is already noted here in the document. I can edit it if the wording isn't clear enough.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've added more wording to clarify this, including adding V2 API methods to this spec.

Copy link
Contributor

Choose a reason for hiding this comment

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

it's an alternative fork where withdrawals and 4844 are part of the same upgrade.

This is different than the consensus spec. The consensus spec is treating them as different forks that are going from bellatrix -> capella -> eip4844. If we implement engine API as it is, then the Capella block processing will fail

Copy link
Contributor

Choose a reason for hiding this comment

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

So I think this should be V3


This existing structure is extended to include a single field: `excessDataGas`. All APIs referencing the `ExecutionPayloadV2` in the [original Engine API](./specification.md) must use this extended structure instead.

- `parentHash`: `DATA`, 32 Bytes
- `feeRecipient`: `DATA`, 20 Bytes
- `stateRoot`: `DATA`, 32 Bytes
- `receiptsRoot`: `DATA`, 32 Bytes
- `logsBloom`: `DATA`, 256 Bytes
- `prevRandao`: `DATA`, 32 Bytes
- `blockNumber`: `QUANTITY`, 64 Bits
- `gasLimit`: `QUANTITY`, 64 Bits
- `gasUsed`: `QUANTITY`, 64 Bits
- `timestamp`: `QUANTITY`, 64 Bits
- `extraData`: `DATA`, 0 to 32 Bytes
- `baseFeePerGas`: `QUANTITY`, 256 Bits
- `excessDataGas`: `QUANTITY`, 256 bits
- `blockHash`: `DATA`, 32 Bytes
- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.

### BlobsBundleV1

The fields are encoded as follows:
Expand All @@ -15,12 +54,20 @@ The fields are encoded as follows:

## Methods

### engine_newPayloadV2

This method parameter updated to accept the extended EIP-4844 `ExecutionPayloadV2` structure.

### engine_getPayloadV2

This method is extended to return the extended EIP-4844 `ExecutionPayloadV2` structure.

### engine_getBlobsBundleV1

This method retrieves the blobs and their respective KZG commitments corresponding to the `versioned_hashes`
included in the blob transactions of the referenced execution payload.

This method may be combined with `engine_getPayloadV1` into a `engine_getPayloadV2` in a later stage of EIP-4844.
This method may be combined with `engine_getPayloadV2`.
The separation of concerns aims to minimize changes during the testing phase of the EIP.

#### Request
Expand All @@ -37,7 +84,7 @@ The separation of concerns aims to minimize changes during the testing phase of
#### Specification

1. Given the `payloadId` client software **MUST** return the blobs bundle corresponding to the most recent version of the payload that was served with `engine_getPayload`, if any,
and halt any further changes to the payload. The `engine_getBlobsBundleV1` and `engine_getPayloadV1` results **MUST** be consistent as outlined in items 3, 4 and 5 below.
and halt any further changes to the payload. The `engine_getBlobsBundleV1` and `engine_getPayloadV2` results **MUST** be consistent as outlined in items 3, 4 and 5 below.

2. The call **MUST** return `-32001: Unknown payload` error if the build process identified by the `payloadId` does not exist. Note that a payload without any blobs **MUST** return an empty `blobs` and `kzgs` list, not an error.

Expand Down
1 change: 1 addition & 0 deletions wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,3 +48,4 @@ besu
graphql
gwei
withdrawalv
DocToc