Merge pull request #4976 from ethereum-optimism/jm/specs/messengers

fix(specs): Corrections to messenger workflow and iface

specs/messengers.md

@@ -27,20 +27,35 @@ upgrade.
 The `L2CrossDomainMessenger` is a predeploy contract located at
 `0x4200000000000000000000000000000000000007`.
 
+The base `CrossDomainMessenger` interface is:
+
 ```solidity
 interface CrossDomainMessenger {
     event FailedRelayedMessage(bytes32 indexed msgHash);
     event RelayedMessage(bytes32 indexed msgHash);
     event SentMessage(address indexed target, address sender, bytes message, uint256 messageNonce, uint256 gasLimit);
-
-    function MESSAGE_VERSION() view external returns (uint16);
-    function messageNonce() view external returns (uint256);
-    function otherMessenger() view external returns (address);
-    function failedMessages(bytes32) view external returns (bool);
-    function relayMessage(uint256 _nonce, address _sender, address _target, uint256 _value, uint256 _minGasLimit, bytes memory _message) payable external;
-    function sendMessage(address _target, bytes memory _message, uint32 _minGasLimit) payable external;
-    function successfulMessages(bytes32) view external returns (bool);
-    function xDomainMessageSender() view external returns (address);
+    event SentMessageExtension1(address indexed sender, uint256 value);
+
+    function MESSAGE_VERSION() external view returns (uint16);
+    function MIN_GAS_CALLDATA_OVERHEAD() external view returns (uint64);
+    function MIN_GAS_CONSTANT_OVERHEAD() external view returns (uint64);
+    function MIN_GAS_DYNAMIC_OVERHEAD_DENOMINATOR() external view returns (uint64);
+    function MIN_GAS_DYNAMIC_OVERHEAD_NUMERATOR() external view returns (uint64);
+    function OTHER_MESSENGER() external view returns (address);
+    function baseGas(bytes memory _message, uint32 _minGasLimit) external pure returns (uint64);
+    function failedMessages(bytes32) external view returns (bool);
+    function messageNonce() external view returns (uint256);
+    function relayMessage(
+        uint256 _nonce,
+        address _sender,
+        address _target,
+        uint256 _value,
+        uint256 _minGasLimit,
+        bytes memory _message
+    ) external payable;
+    function sendMessage(address _target, bytes memory _message, uint32 _minGasLimit) external payable;
+    function successfulMessages(bytes32) external view returns (bool);
+    function xDomainMessageSender() external view returns (address);
 }
 ```
 
@@ -56,9 +71,10 @@ The user experience when sending from L1 to L2 is a bit different than when
 sending a transaction from L2 to L1. When going into L2 from L1, the user does
 not need to call `relayMessage` on L2 themselves. The user pays for L2 gas on L1
 and the transaction is automatically pulled into L2 where it is executed on L2.
-When going from L2 into L1, the user must call `relayMessage` on the
-`L1CrossDomainMessenger` to finalize the withdrawal. This function can only
-be called after the finalization window has passed.
+When going from L2 into L1, the user proves their withdrawal on OptimismPortal,
+then waits for the finalization window to pass, and then finalizes the withdrawal
+on the OptimismPortal, which calls `relayMessage` on the
+`L1CrossDomainMessenger` to finalize the withdrawal.
 
 ## Upgradability