specs: Fix inconsistencies within documentation (#2658)

* specs: Update executePayloadV1 to newPayloadV1

Just updating the name in the specs. This has already been changed
in the code.

* specs: Deposits -> Withdrawals spec clarification

Wording was incorrect.

* specs: Remove unnecessary cast

The casts from bytes32 -> uint256 -> bytes32 is not needed.

* specs: no alias on withdrawals

* fix lint

* specs: fix parentheses
Co-authored-by: Diederik Loerakker <proto@protolambda.com>
Co-authored-by: Maurelian <maurelian@protonmail.ch>
Co-authored-by: Diederik Loerakker <proto@protolambda.com>

specs/deposits.md

@@ -84,7 +84,7 @@ The `sourceHash` of a deposit transaction is computed based on the origin:
   Where the `l1BlockHash`, and `l1LogIndex` all refer to the inclusion of the deposit log event on L1.
   `l1LogIndex` is the index of the deposit event log in the combined list of log events of the block.
 - L1 attributes deposited:
-  `keccak256(bytes32(uint256(1)), keccak256(bytes32(uint256(l1BlockHash)), bytes32(uint256(seqNumber))`.
+  `keccak256(bytes32(uint256(1)), keccak256(l1BlockHash), bytes32(uint256(seqNumber)))`.
   Where `l1BlockHash` refers to the L1 block hash of which the info attributes are deposited.
   And `seqNumber = l2BlockNum - l2EpochStartBlockNum`,
   where `l2BlockNum` is the L2 block number of the inclusion of the deposit tx in L2,
@@ -256,8 +256,7 @@ The deposit contract handles two special cases:
 [address-aliasing]: #address-aliasing
 
 If the caller is a contract, the address will be transformed by adding
-`0x1111000000000000000000000000000000001111` to it. This is the reverse of the
-transformation described in the [deposits spec](./withdrawals.md#address-aliasing). This prevents attacks in which a
+`0x1111000000000000000000000000000000001111` to it. This prevents attacks in which a
 contract on L1 has the same address as a contract on L2 but doesn't have the same code. We can safely ignore this
 for EOAs because they're guaranteed to have the same "code" (i.e. no code at all). This also makes
 it possible for users to interact with contracts on L2 even when the Sequencer is down.

specs/exec-engine.md

@@ -9,7 +9,7 @@
 - [Engine API](#engine-api)
   - [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1)
     - [Extended PayloadAttributesV1](#extended-payloadattributesv1)
-  - [`engine_executePayloadV1`](#engine_executepayloadv1)
+  - [`engine_newPayloadV1`](#engine_newpayloadv1)
   - [`engine_getPayloadV1`](#engine_getpayloadv1)
 - [Networking](#networking)
 - [Sync](#sync)
@@ -103,9 +103,9 @@ The `noTxPool` is optional as well, and extends the `transactions` meaning:
 
 [rollup-driver]: rollup-node.md
 
-### `engine_executePayloadV1`
+### `engine_newPayloadV1`
 
-No modifications to [`engine_executePayloadV1`][engine_executePayloadV1].
+No modifications to [`engine_newPayloadV1`][engine_newPayloadV1].
 Applies a L2 block to the engine state.
 
 ### `engine_getPayloadV1`
@@ -157,7 +157,7 @@ as the engine implementation can sync state faster through methods like [snap-sy
 ### Happy-path sync
 
 1. The rollup node informs the engine of the L2 chain head, unconditionally (part of regular node operation):
-   - [`engine_executePayloadV1`][engine_executePayloadV1] is called with latest L2 block derived from L1.
+   - [`engine_newPayloadV1`][engine_newPayloadV1] is called with latest L2 block derived from L1.
    - [`engine_forkchoiceUpdatedV1`][engine_forkchoiceUpdatedV1] is called with the current
      `unsafe`/`safe`/`finalized` L2 block hashes.
 2. The engine requests headers from peers, in reverse till the parent hash matches the local chain
@@ -174,18 +174,18 @@ the operation within the engine is the exact same as with L1 (although with an E
 2. The rollup node maintains latest head from engine (poll `eth_getBlockByNumber` and/or maintain a header subscription)
 3. The rollup node activates sync if the engine is out of sync but not syncing through P2P (`eth_syncing`)
 4. The rollup node inserts blocks, derived from L1, one by one, potentially adapting to L1 reorg(s),
-   as outlined in the [rollup node spec] (`engine_forkchoiceUpdatedV1`, `engine_executePayloadV1`)
+   as outlined in the [rollup node spec] (`engine_forkchoiceUpdatedV1`, `engine_newPayloadV1`)
 
 [rollup node spec]: rollup-node.md
 
 [eip-2718]: https://eips.ethereum.org/EIPS/eip-2718
 [eip-2718-transactions]: https://eips.ethereum.org/EIPS/eip-2718#transactions
-[exec-api-data]: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.5/src/engine/specification.md#structures
-[l1-api-spec]: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.5/src/engine/specification.md
-[PayloadAttributesV1]: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.5/src/engine/specification.md#PayloadAttributesV1
-[ExecutionPayloadV1]: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.5/src/engine/specification.md#ExecutionPayloadV1
-[engine_forkchoiceUpdatedV1]: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.5/src/engine/specification.md#engine_forkchoiceupdatedv1
-[engine_executePayloadV1]: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.5/src/engine/specification.md#engine_executePayloadV1
-[engine_getPayloadV1]: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.5/src/engine/specification.md#engine_getPayloadV1
+[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
+[ExecutionPayloadV1]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md#ExecutionPayloadV1
+[engine_forkchoiceUpdatedV1]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md#engine_forkchoiceupdatedv1
+[engine_newPayloadV1]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md#engine_newPayloadV1
+[engine_getPayloadV1]: https://github.com/ethereum/execution-apis/blob/769c53c94c4e487337ad0edea9ee0dce49c79bfa/src/engine/specification.md#engine_getPayloadV1
 [HEX value encoding]: https://eth.wiki/json-rpc/API#hex-value-encoding
 [JSON-RPC-API]: https://github.com/ethereum/execution-apis

specs/overview.md

@@ -189,7 +189,7 @@ state parameter for now - just know that one of its fields is the L2 chain's `he
 block hash of the tip of the L2 chain. The Engine API returns a payload ID.
 2. Call `engine_getPayloadV1` with the payload ID returned in step 1. The engine API returns a payload object that
 includes a block hash as one of its fields.
-3. Call `engine_executePayloadV1` with the payload returned in step 2.
+3. Call `engine_newPayloadV1` with the payload returned in step 2.
 4. Call `engine_forkChoiceUpdatedV1` with the fork choice parameter's `headBlockHash` set to the block hash returned in
 step 2. The tip of the L2 chain is now the block created in step 1.
 

specs/rollup-node.md

@@ -248,7 +248,7 @@ if (status != "SUCCESS") error()
 // retrieve and execute the execution payload
 [executionPayload, error] = engine_getPayloadV1(payloadID)
 if (error != null) error()
-[status, latestValidHash, validationError] = engine_executePayloadV1(executionPayload)
+[status, latestValidHash, validationError] = engine_newPayloadV1(executionPayload)
 if (status != "VALID" || validationError != null) error()
 
 refL2 = latestValidHash
@@ -277,11 +277,11 @@ The following JSON-RPC methods are part of the [execution engine API][exec-engin
 - [`engine_forkchoiceUpdatedV1`] — updates the forkchoice (i.e. the chain head) to `headBlockHash` if different, and
   instructs the engine to start building an execution payload given payload attributes the second argument isn't `null`
 - [`engine_getPayloadV1`] — retrieves a previously requested execution payload
-- [`engine_executePayloadV1`] — executes an execution payload to create a block
+- [`engine_newPayloadV1`] — executes an execution payload to create a block
 
 [`engine_forkchoiceUpdatedV1`]: exec-engine.md#engine_forkchoiceUpdatedV1
-[`engine_getPayloadV1`]: exec-engine.md#engine_executepayloadv1
-[`engine_executePayloadV1`]: exec-engine.md#engine_executepayloadv1
+[`engine_getPayloadV1`]: exec-engine.md#engine_newPayloadV1
+[`engine_newPayloadV1`]: exec-engine.md#engine_newPayloadV1
 
 The execution payload is an object of type [`ExecutionPayloadV1`].
 
@@ -308,7 +308,7 @@ for more details.
 
 [error-handling]: #engine-api-error-handling
 
-All invocations of [`engine_forkchoiceUpdatedV1`], [`engine_getPayloadV1`] and [`engine_executePayloadV1`] by the
+All invocations of [`engine_forkchoiceUpdatedV1`], [`engine_getPayloadV1`] and [`engine_newPayloadV1`] by the
 rollup driver should not result in errors assuming conformity with the specification. Said otherwise, all errors are
 implementation concerns and it is up to them to handle them (e.g. by retrying, or by stopping the chain derivation and
 requiring manual user intervention).
@@ -316,8 +316,8 @@ requiring manual user intervention).
 The following scenarios are assimilated to errors:
 
 - [`engine_forkchoiceUpdatedV1`] returning a `status` of `"SYNCING"` instead of `"SUCCESS"` whenever passed a
-  `headBlockHash` that it retrieved from a previous call to [`engine_executePayloadV1`].
-- [`engine_executePayloadV1`] returning a `status` of `"SYNCING"` or `"INVALID"` whenever passed an execution payload
+  `headBlockHash` that it retrieved from a previous call to [`engine_newPayloadV1`].
+- [`engine_newPayloadV1`] returning a `status` of `"SYNCING"` or `"INVALID"` whenever passed an execution payload
   that was obtained by a previous call to [`engine_getPayloadV1`].
 
 ### Finalization Guarantees

specs/withdrawals.md

@@ -100,13 +100,20 @@ interface L2ToL1MessagePasser {
 
 ```
 
-### Address Aliasing
+### Addresses are not Aliased on Withdrawals
 
-[address-aliasing]: #address-aliasing
+[address-aliasing]: #no-address-aliasing
 
-If called by a contract, the `initiateWithdrawal` function will alias the `sender` address by subtracting
-`0x1111000000000000000000000000000000001111`. This is the reverse of the
-transformation described in the [deposits spec](./deposits.md#address-aliasing).
+When a contract makes a deposit, the sender's address is [aliased](./deposits.md#address-aliasing). The same is not true
+of withdrawals, which do not modify the sender's address. The difference is that:
+
+- on L2, the deposit sender's address is returned by the `CALLER` opcode, meaning a contract cannot easily tell if the
+  call originated on L1 or L2, whereas
+- on L1, the withdrawal sender's address is accessed by calling the `l2Sender`() function on the `OptimismPortal`
+  contract.
+
+Calling `l2Sender()` removes any ambiguity about which domain the call originated from. Still, developers will need to
+recognize that having the same address does not imply that a contract on L2 will behave the same as a contract on L1.
 
 ## The Optimism Portal Contract
 
@@ -119,6 +126,8 @@ interface OptimismPortal {
 
     event WithdrawalFinalized(bytes32 indexed);
 
+    function l2Sender() returns(address) external;
+
     function finalizeWithdrawalTransaction(
         uint256 _nonce,
         address _sender,