Merge pull request #8088 from ethereum-optimism/jg/withdrawls_specs

specs: Clarify withdrawals specs better

specs/derivation.md

@@ -895,7 +895,7 @@ without dispute (fault proof challenge window), a name-collision with the proof-
 [deriving-payload-attr]: #deriving-payload-attributes
 
 For every L2 block derived from L1 data, we need to build [payload attributes][g-payload-attr],
-represented by an [expanded version][expanded-payload] of the [`PayloadAttributesV1`][eth-payload] object,
+represented by an [expanded version][expanded-payload] of the [`PayloadAttributesV2`][eth-payload] object,
 which includes additional `transactions` and `noTxPool` fields.
 
 This process happens during the payloads-attributes queue ran by a verifier node, as well as during block-production
@@ -915,7 +915,7 @@ This block is part of a [sequencing epoch][g-sequencing-epoch],
 whose number matches that of an L1 block (its *[L1 origin][g-l1-origin]*).
 This L1 block is used to derive L1 attributes and (for the first L2 block in the epoch) user deposits.
 
-Therefore, a [`PayloadAttributesV1`][expanded-payload] object must include the following transactions:
+Therefore, a [`PayloadAttributesV2`][expanded-payload] object must include the following transactions:
 
 - one or more [deposited transactions][g-deposited], of two kinds:
   - a single *[L1 attributes deposited transaction][g-l1-attr-deposit]*, derived from the L1 origin.
@@ -936,7 +936,7 @@ entries.
 
 [payload attributes]: #building-individual-payload-attributes
 
-After deriving the transactions list, the rollup node constructs a [`PayloadAttributesV1`][extended-attributes] as
+After deriving the transactions list, the rollup node constructs a [`PayloadAttributesV2`][extended-attributes] as
 follows:
 
 - `timestamp` is set to the batch's timestamp.
@@ -946,6 +946,7 @@ follows:
   encoded with [EIP-2718].
 - `noTxPool` is set to `true`, to use the exact above `transactions` list when constructing the block.
 - `gasLimit` is set to the current `gasLimit` value in the [system configuration][g-system-config] of this payload.
+- 'withdrawals' is set to nil prior to Canyon and an empty array after Canyon
 
 [extended-attributes]: exec-engine.md#extended-payloadattributesv1
 [Fee Vaults]: exec-engine.md#fee-vaults

specs/exec-engine.md

@@ -14,7 +14,7 @@
   - [L1-Cost fees (L1 Fee Vault)](#l1-cost-fees-l1-fee-vault)
 - [Engine API](#engine-api)
   - [`engine_forkchoiceUpdatedV2`](#engine_forkchoiceupdatedv2)
-    - [Extended PayloadAttributesV1](#extended-payloadattributesv1)
+    - [Extended PayloadAttributesV2](#extended-payloadattributesv2)
   - [`engine_newPayloadV2`](#engine_newpayloadv2)
   - [`engine_getPayloadV2`](#engine_getpayloadv2)
   - [`engine_signalSuperchainV1`](#engine_signalsuperchainv1)
@@ -149,17 +149,18 @@ Within the rollup, the types of forkchoice updates translate as:
 - `finalizedBlockHash`: irreversible block hash, matches lower boundary of the dispute period.
 
 To support rollup functionality, one backwards-compatible change is introduced
-to [`engine_forkchoiceUpdatedV2`][engine_forkchoiceUpdatedV2]: the extended `PayloadAttributesV1`
+to [`engine_forkchoiceUpdatedV2`][engine_forkchoiceUpdatedV2]: the extended `PayloadAttributesV2`
 
-#### Extended PayloadAttributesV1
+#### Extended PayloadAttributesV2
 
-[`PayloadAttributesV1`][PayloadAttributesV1] is extended to:
+[`PayloadAttributesV2`][PayloadAttributesV2] is extended to:
 
 ```js
-PayloadAttributesV1: {
+PayloadAttributesV2: {
     timestamp: QUANTITY
     random: DATA (32 bytes)
     suggestedFeeRecipient: DATA (20 bytes)
+    withdrawals: array of WithdrawalV1
     transactions: array of DATA
     noTxPool: bool
     gasLimit: QUANTITY or null
@@ -172,7 +173,7 @@ to a JSON array.
 
 Each item of the `transactions` array is a byte list encoding a transaction: `TransactionType ||
 TransactionPayload` or `LegacyTransaction`, as defined in [EIP-2718][eip-2718].
-This is equivalent to the `transactions` field in [`ExecutionPayloadV1`][ExecutionPayloadV1]
+This is equivalent to the `transactions` field in [`ExecutionPayloadV2`][ExecutionPayloadV2]
 
 The `transactions` field is optional:
 
@@ -310,7 +311,7 @@ the operation within the engine is the exact same as with L1 (although with an E
 [eip-2718-transactions]: https://eips.ethereum.org/EIPS/eip-2718#transactions
 [exec-api-data]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md#structures
 [l1-api-spec]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md
-[PayloadAttributesV1]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md#PayloadAttributesV1
+[PayloadAttributesV2]: https://github.com/ethereum/execution-apis/blob/584905270d8ad665718058060267061ecfd79ca5/src/engine/shanghai.md#PayloadAttributesV2
 [ExecutionPayloadV1]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md#ExecutionPayloadV1
 [engine_forkchoiceUpdatedV2]: https://github.com/ethereum/execution-apis/blob/584905270d8ad665718058060267061ecfd79ca5/src/engine/shanghai.md#engine_forkchoiceupdatedv2
 [engine_newPayloadV2]: https://github.com/ethereum/execution-apis/blob/584905270d8ad665718058060267061ecfd79ca5/src/engine/shanghai.md#engine_newpayloadv2

specs/glossary.md

@@ -797,7 +797,7 @@ In these specifications, "execution engine" always refer to the L2 execution eng
 [Solidity events]: https://docs.soliditylang.org/en/latest/contracts.html?highlight=events#events
 [nano-header]: https://github.com/norswap/nanoeth/blob/cc5d94a349c90627024f3cd629a2d830008fec72/src/com/norswap/nanoeth/blocks/BlockHeader.java#L22-L156
 [yellow]: https://ethereum.github.io/yellowpaper/paper.pdf
-[engine-api]: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#PayloadAttributesV1
+[engine-api]: https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#PayloadAttributesV2
 [merge]: https://ethereum.org/en/eth2/merge/
 [mempool]: https://www.quicknode.com/guides/defi/how-to-access-ethereum-mempool
 [L1 consensus layer]: https://github.com/ethereum/consensus-specs/#readme