@arbitrum/nitro-contracts 1.0.0-beta.8 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbitrum/nitro-contracts",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Layer 2 precompiles and rollup for Arbitrum Nitro",
   "author": "Offchain Labs, Inc.",
   "license": "BUSL-1.1",
@@ -24,7 +24,9 @@
     "hardhat:prod": "hardhat --config hardhat.prod-config.js",
     "build:0.6": "INTERFACE_TESTER_SOLC_VERSION=0.6.9 yarn run build",
     "build:0.7": "INTERFACE_TESTER_SOLC_VERSION=0.7.0 yarn run build",
-    "test:compatibility": "yarn run build:0.6 && yarn run build:0.7"
+    "test:compatibility": "yarn run build:0.6 && yarn run build:0.7",
+    "test:storage": "./test/storage/test.bash",
+    "postinstall": "patch-package"
   },
   "dependencies": {
     "@openzeppelin/contracts": "4.5.0",
@@ -34,6 +36,7 @@
   "private": false,
   "devDependencies": {
     "@nomiclabs/hardhat-ethers": "npm:hardhat-deploy-ethers@^0.3.0-beta.13",
+    "@nomiclabs/hardhat-etherscan": "^3.1.0",
     "@nomiclabs/hardhat-waffle": "^2.0.1",
     "@typechain/ethers-v5": "^10.0.0",
     "@typechain/hardhat": "^6.0.0",
@@ -45,6 +48,8 @@
     "ethers": "^5.5.2",
     "hardhat-deploy": "^0.11.4",
     "hardhat-gas-reporter": "^1.0.8",
+    "patch-package": "^6.4.7",
+    "postinstall-postinstall": "^2.1.0",
     "prettier": "^2.5.1",
     "prettier-plugin-solidity": "^1.0.0-beta.19",
     "solhint": "^3.3.7",
@@ -53,5 +58,8 @@
     "ts-node": "^10.4.0",
     "typechain": "^8.0.0",
     "typescript": "^4.5.4"
+  },
+  "optionalDependencies":{
+    "sol2uml": "2.2.0"
   }
 }

package/src/bridge/Bridge.sol

@@ -13,7 +13,8 @@ import {
     NotDelayedInbox,
     NotSequencerInbox,
     NotOutbox,
-    InvalidOutboxSet
+    InvalidOutboxSet,
+    BadSequencerMessageNumber
 } from "../libraries/Error.sol";
 import "./IBridge.sol";
 import "./Messages.sol";
@@ -42,18 +43,20 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
     address[] public allowedDelayedInboxList;
     address[] public allowedOutboxList;
 
-    address private _activeOutbox;
+    address internal _activeOutbox;
 
-    /// @dev Accumulator for delayed inbox messages; tail represents hash of the current state; each element represents the inclusion of a new message.
-    bytes32[] public override delayedInboxAccs;
+    /// @inheritdoc IBridge
+    bytes32[] public delayedInboxAccs;
 
-    /// @dev Accumulator for sequencer inbox messages; tail represents hash of the current state; each element represents the inclusion of a new message.
-    bytes32[] public override sequencerInboxAccs;
+    /// @inheritdoc IBridge
+    bytes32[] public sequencerInboxAccs;
 
-    IOwnable public override rollup;
+    IOwnable public rollup;
     address public sequencerInbox;
 
-    address private constant EMPTY_ACTIVEOUTBOX = address(type(uint160).max);
+    uint256 public override sequencerReportedSubMessageCount;
+
+    address internal constant EMPTY_ACTIVEOUTBOX = address(type(uint160).max);
 
     function initialize(IOwnable rollup_) external initializer onlyDelegated {
         _activeOutbox = EMPTY_ACTIVEOUTBOX;
@@ -81,11 +84,11 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
         return outbox;
     }
 
-    function allowedDelayedInboxes(address inbox) external view override returns (bool) {
+    function allowedDelayedInboxes(address inbox) external view returns (bool) {
         return allowedDelayedInboxesMap[inbox].allowed;
     }
 
-    function allowedOutboxes(address outbox) external view override returns (bool) {
+    function allowedOutboxes(address outbox) external view returns (bool) {
         return allowedOutboxesMap[outbox].allowed;
     }
 
@@ -94,9 +97,13 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
         _;
     }
 
-    function enqueueSequencerMessage(bytes32 dataHash, uint256 afterDelayedMessagesRead)
+    function enqueueSequencerMessage(
+        bytes32 dataHash,
+        uint256 afterDelayedMessagesRead,
+        uint256 prevMessageCount,
+        uint256 newMessageCount
+    )
         external
-        override
         onlySequencerInbox
         returns (
             uint256 seqMessageIndex,
@@ -105,6 +112,14 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
             bytes32 acc
         )
     {
+        if (
+            sequencerReportedSubMessageCount != prevMessageCount &&
+            prevMessageCount != 0 &&
+            sequencerReportedSubMessageCount != 0
+        ) {
+            revert BadSequencerMessageNumber(sequencerReportedSubMessageCount, prevMessageCount);
+        }
+        sequencerReportedSubMessageCount = newMessageCount;
         seqMessageIndex = sequencerInboxAccs.length;
         if (sequencerInboxAccs.length > 0) {
             beforeAcc = sequencerInboxAccs[sequencerInboxAccs.length - 1];
@@ -116,15 +131,9 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
         sequencerInboxAccs.push(acc);
     }
 
-    /**
-     * @dev allows the sequencer inbox to submit a delayed message of the batchPostingReport type
-     * This is done through a separate function entrypoint instead of allowing the sequencer inbox
-     * to call `enqueueDelayedMessage` to avoid the gas overhead of an extra SLOAD in either
-     * every delayed inbox or every sequencer inbox call.
-     */
+    /// @inheritdoc IBridge
     function submitBatchSpendingReport(address sender, bytes32 messageDataHash)
         external
-        override
         onlySequencerInbox
         returns (uint256)
     {
@@ -139,16 +148,12 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
             );
     }
 
-    /**
-     * @dev Enqueue a message in the delayed inbox accumulator.
-     * These messages are later sequenced in the SequencerInbox, either by the sequencer as
-     * part of a normal batch, or by force inclusion.
-     */
+    /// @inheritdoc IBridge
     function enqueueDelayedMessage(
         uint8 kind,
         address sender,
         bytes32 messageDataHash
-    ) external payable override returns (uint256) {
+    ) external payable returns (uint256) {
         if (!allowedDelayedInboxesMap[msg.sender].allowed) revert NotDelayedInbox(msg.sender);
         return
             addMessageToDelayedAccumulator(
@@ -201,7 +206,7 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
         address to,
         uint256 value,
         bytes calldata data
-    ) external override returns (bool success, bytes memory returnData) {
+    ) external returns (bool success, bytes memory returnData) {
         if (!allowedOutboxesMap[msg.sender].allowed) revert NotOutbox(msg.sender);
         if (data.length > 0 && !to.isContract()) revert NotContract(to);
         address prevOutbox = _activeOutbox;
@@ -216,12 +221,12 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
         emit BridgeCallTriggered(msg.sender, to, value, data);
     }
 
-    function setSequencerInbox(address _sequencerInbox) external override onlyRollupOrOwner {
+    function setSequencerInbox(address _sequencerInbox) external onlyRollupOrOwner {
         sequencerInbox = _sequencerInbox;
         emit SequencerInboxUpdated(_sequencerInbox);
     }
 
-    function setDelayedInbox(address inbox, bool enabled) external override onlyRollupOrOwner {
+    function setDelayedInbox(address inbox, bool enabled) external onlyRollupOrOwner {
         InOutInfo storage info = allowedDelayedInboxesMap[inbox];
         bool alreadyEnabled = info.allowed;
         emit InboxToggle(inbox, enabled);
@@ -241,7 +246,7 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
         }
     }
 
-    function setOutbox(address outbox, bool enabled) external override onlyRollupOrOwner {
+    function setOutbox(address outbox, bool enabled) external onlyRollupOrOwner {
         if (outbox == EMPTY_ACTIVEOUTBOX) revert InvalidOutboxSet(outbox);
 
         InOutInfo storage info = allowedOutboxesMap[outbox];
@@ -261,11 +266,15 @@ contract Bridge is Initializable, DelegateCallAware, IBridge {
         }
     }
 
+    function setSequencerReportedSubMessageCount(uint256 newMsgCount) external onlyRollupOrOwner {
+        sequencerReportedSubMessageCount = newMsgCount;
+    }
+
     function delayedMessageCount() external view override returns (uint256) {
         return delayedInboxAccs.length;
     }
 
-    function sequencerMessageCount() external view override returns (uint256) {
+    function sequencerMessageCount() external view returns (uint256) {
         return sequencerInboxAccs.length;
     }
 

package/src/bridge/IBridge.sol

@@ -32,13 +32,57 @@ interface IBridge {
 
     event SequencerInboxUpdated(address newSequencerInbox);
 
+    function allowedDelayedInboxList(uint256) external returns (address);
+
+    function allowedOutboxList(uint256) external returns (address);
+
+    /// @dev Accumulator for delayed inbox messages; tail represents hash of the current state; each element represents the inclusion of a new message.
+    function delayedInboxAccs(uint256) external view returns (bytes32);
+
+    /// @dev Accumulator for sequencer inbox messages; tail represents hash of the current state; each element represents the inclusion of a new message.
+    function sequencerInboxAccs(uint256) external view returns (bytes32);
+
+    function rollup() external view returns (IOwnable);
+
+    function sequencerInbox() external view returns (address);
+
+    function activeOutbox() external view returns (address);
+
+    function allowedDelayedInboxes(address inbox) external view returns (bool);
+
+    function allowedOutboxes(address outbox) external view returns (bool);
+
+    function sequencerReportedSubMessageCount() external view returns (uint256);
+
+    /**
+     * @dev Enqueue a message in the delayed inbox accumulator.
+     *      These messages are later sequenced in the SequencerInbox, either
+     *      by the sequencer as part of a normal batch, or by force inclusion.
+     */
     function enqueueDelayedMessage(
         uint8 kind,
         address sender,
         bytes32 messageDataHash
     ) external payable returns (uint256);
 
-    function enqueueSequencerMessage(bytes32 dataHash, uint256 afterDelayedMessagesRead)
+    function executeCall(
+        address to,
+        uint256 value,
+        bytes calldata data
+    ) external returns (bool success, bytes memory returnData);
+
+    function delayedMessageCount() external view returns (uint256);
+
+    function sequencerMessageCount() external view returns (uint256);
+
+    // ---------- onlySequencerInbox functions ----------
+
+    function enqueueSequencerMessage(
+        bytes32 dataHash,
+        uint256 afterDelayedMessagesRead,
+        uint256 prevMessageCount,
+        uint256 newMessageCount
+    )
         external
         returns (
             uint256 seqMessageIndex,
@@ -47,42 +91,25 @@ interface IBridge {
             bytes32 acc
         );
 
+    /**
+     * @dev Allows the sequencer inbox to submit a delayed message of the batchPostingReport type
+     *      This is done through a separate function entrypoint instead of allowing the sequencer inbox
+     *      to call `enqueueDelayedMessage` to avoid the gas overhead of an extra SLOAD in either
+     *      every delayed inbox or every sequencer inbox call.
+     */
     function submitBatchSpendingReport(address batchPoster, bytes32 dataHash)
         external
         returns (uint256 msgNum);
 
-    function executeCall(
-        address to,
-        uint256 value,
-        bytes calldata data
-    ) external returns (bool success, bytes memory returnData);
-
-    // These are only callable by the admin
-    function setDelayedInbox(address inbox, bool enabled) external;
-
-    function setOutbox(address inbox, bool enabled) external;
+    // ---------- onlyRollupOrOwner functions ----------
 
     function setSequencerInbox(address _sequencerInbox) external;
 
-    // View functions
-
-    function sequencerInbox() external view returns (address);
-
-    function activeOutbox() external view returns (address);
-
-    function allowedDelayedInboxes(address inbox) external view returns (bool);
-
-    function allowedOutboxes(address outbox) external view returns (bool);
-
-    function delayedInboxAccs(uint256 index) external view returns (bytes32);
-
-    function sequencerInboxAccs(uint256 index) external view returns (bytes32);
-
-    function delayedMessageCount() external view returns (uint256);
+    function setDelayedInbox(address inbox, bool enabled) external;
 
-    function sequencerMessageCount() external view returns (uint256);
+    function setOutbox(address inbox, bool enabled) external;
 
-    function rollup() external view returns (IOwnable);
+    // ---------- initializer ----------
 
-    function acceptFundsFromOldBridge() external payable;
+    function initialize(IOwnable rollup_) external;
 }

package/src/bridge/IInbox.sol

@@ -7,10 +7,44 @@ pragma solidity >=0.6.9 <0.9.0;
 
 import "./IBridge.sol";
 import "./IDelayedMessageProvider.sol";
+import "./ISequencerInbox.sol";
 
 interface IInbox is IDelayedMessageProvider {
+    function bridge() external view returns (IBridge);
+
+    function sequencerInbox() external view returns (ISequencerInbox);
+
+    /**
+     * @notice Send a generic L2 message to the chain
+     * @dev This method is an optimization to avoid having to emit the entirety of the messageData in a log. Instead validators are expected to be able to parse the data from the transaction's input
+     *      This method will be disabled upon L1 fork to prevent replay attacks on L2
+     * @param messageData Data of the message being sent
+     */
+    function sendL2MessageFromOrigin(bytes calldata messageData) external returns (uint256);
+
+    /**
+     * @notice Send a generic L2 message to the chain
+     * @dev This method can be used to send any type of message that doesn't require L1 validation
+     *      This method will be disabled upon L1 fork to prevent replay attacks on L2
+     * @param messageData Data of the message being sent
+     */
     function sendL2Message(bytes calldata messageData) external returns (uint256);
 
+    function sendL1FundedUnsignedTransaction(
+        uint256 gasLimit,
+        uint256 maxFeePerGas,
+        uint256 nonce,
+        address to,
+        bytes calldata data
+    ) external payable returns (uint256);
+
+    function sendL1FundedContractTransaction(
+        uint256 gasLimit,
+        uint256 maxFeePerGas,
+        address to,
+        bytes calldata data
+    ) external payable returns (uint256);
+
     function sendUnsignedTransaction(
         uint256 gasLimit,
         uint256 maxFeePerGas,
@@ -28,7 +62,11 @@ interface IInbox is IDelayedMessageProvider {
         bytes calldata data
     ) external returns (uint256);
 
-    function sendL1FundedUnsignedTransaction(
+    /**
+     * @dev This method can only be called upon L1 fork and will not alias the caller
+     *      This method will revert if not called from origin
+     */
+    function sendL1FundedUnsignedTransactionToFork(
         uint256 gasLimit,
         uint256 maxFeePerGas,
         uint256 nonce,
@@ -36,43 +74,120 @@ interface IInbox is IDelayedMessageProvider {
         bytes calldata data
     ) external payable returns (uint256);
 
-    function sendL1FundedContractTransaction(
+    /**
+     * @dev This method can only be called upon L1 fork and will not alias the caller
+     *      This method will revert if not called from origin
+     */
+    function sendUnsignedTransactionToFork(
         uint256 gasLimit,
         uint256 maxFeePerGas,
+        uint256 nonce,
         address to,
+        uint256 value,
         bytes calldata data
-    ) external payable returns (uint256);
+    ) external returns (uint256);
 
-    /// @dev Gas limit and maxFeePerGas should not be set to 1 as that is used to trigger the RetryableData error
+    /**
+     * @notice Send a message to initiate L2 withdrawal
+     * @dev This method can only be called upon L1 fork and will not alias the caller
+     *      This method will revert if not called from origin
+     */
+    function sendWithdrawEthToFork(
+        uint256 gasLimit,
+        uint256 maxFeePerGas,
+        uint256 nonce,
+        uint256 value,
+        address withdrawTo
+    ) external returns (uint256);
+
+    /**
+     * @notice Get the L1 fee for submitting a retryable
+     * @dev This fee can be paid by funds already in the L2 aliased address or by the current message value
+     * @dev This formula may change in the future, to future proof your code query this method instead of inlining!!
+     * @param dataLength The length of the retryable's calldata, in bytes
+     * @param baseFee The block basefee when the retryable is included in the chain, if 0 current block.basefee will be used
+     */
+    function calculateRetryableSubmissionFee(uint256 dataLength, uint256 baseFee)
+        external
+        view
+        returns (uint256);
+
+    /**
+     * @notice Deposit eth from L1 to L2 to address of the sender if sender is an EOA, and to its aliased address if the sender is a contract
+     * @dev This does not trigger the fallback function when receiving in the L2 side.
+     *      Look into retryable tickets if you are interested in this functionality.
+     * @dev This function should not be called inside contract constructors
+     */
+    function depositEth() external payable returns (uint256);
+
+    /**
+     * @notice Put a message in the L2 inbox that can be reexecuted for some fixed amount of time if it reverts
+     * @dev all msg.value will deposited to callValueRefundAddress on L2
+     * @dev Gas limit and maxFeePerGas should not be set to 1 as that is used to trigger the RetryableData error
+     * @param to destination L2 contract address
+     * @param l2CallValue call value for retryable L2 message
+     * @param maxSubmissionCost Max gas deducted from user's L2 balance to cover base submission fee
+     * @param excessFeeRefundAddress gasLimit x maxFeePerGas - execution cost gets credited here on L2 balance
+     * @param callValueRefundAddress l2Callvalue gets credited here on L2 if retryable txn times out or gets cancelled
+     * @param gasLimit Max gas deducted from user's L2 balance to cover L2 execution. Should not be set to 1 (magic value used to trigger the RetryableData error)
+     * @param maxFeePerGas price bid for L2 execution. Should not be set to 1 (magic value used to trigger the RetryableData error)
+     * @param data ABI encoded data of L2 message
+     * @return unique message number of the retryable transaction
+     */
     function createRetryableTicket(
         address to,
-        uint256 arbTxCallValue,
+        uint256 l2CallValue,
         uint256 maxSubmissionCost,
-        address submissionRefundAddress,
-        address valueRefundAddress,
+        address excessFeeRefundAddress,
+        address callValueRefundAddress,
         uint256 gasLimit,
         uint256 maxFeePerGas,
         bytes calldata data
     ) external payable returns (uint256);
 
-    /// @dev Gas limit and maxFeePerGas should not be set to 1 as that is used to trigger the RetryableData error
+    /**
+     * @notice Put a message in the L2 inbox that can be reexecuted for some fixed amount of time if it reverts
+     * @dev Same as createRetryableTicket, but does not guarantee that submission will succeed by requiring the needed funds
+     * come from the deposit alone, rather than falling back on the user's L2 balance
+     * @dev Advanced usage only (does not rewrite aliases for excessFeeRefundAddress and callValueRefundAddress).
+     * createRetryableTicket method is the recommended standard.
+     * @dev Gas limit and maxFeePerGas should not be set to 1 as that is used to trigger the RetryableData error
+     * @param to destination L2 contract address
+     * @param l2CallValue call value for retryable L2 message
+     * @param maxSubmissionCost Max gas deducted from user's L2 balance to cover base submission fee
+     * @param excessFeeRefundAddress gasLimit x maxFeePerGas - execution cost gets credited here on L2 balance
+     * @param callValueRefundAddress l2Callvalue gets credited here on L2 if retryable txn times out or gets cancelled
+     * @param gasLimit Max gas deducted from user's L2 balance to cover L2 execution. Should not be set to 1 (magic value used to trigger the RetryableData error)
+     * @param maxFeePerGas price bid for L2 execution. Should not be set to 1 (magic value used to trigger the RetryableData error)
+     * @param data ABI encoded data of L2 message
+     * @return unique message number of the retryable transaction
+     */
     function unsafeCreateRetryableTicket(
         address to,
-        uint256 arbTxCallValue,
+        uint256 l2CallValue,
         uint256 maxSubmissionCost,
-        address submissionRefundAddress,
-        address valueRefundAddress,
+        address excessFeeRefundAddress,
+        address callValueRefundAddress,
         uint256 gasLimit,
         uint256 maxFeePerGas,
         bytes calldata data
     ) external payable returns (uint256);
 
-    function depositEth() external payable returns (uint256);
+    // ---------- onlyRollupOrOwner functions ----------
 
-    /// @notice deprecated in favour of depositEth with no parameters
-    function depositEth(uint256 maxSubmissionCost) external payable returns (uint256);
+    /// @notice pauses all inbox functionality
+    function pause() external;
 
-    function bridge() external view returns (IBridge);
+    /// @notice unpauses all inbox functionality
+    function unpause() external;
 
+    // ---------- initializer ----------
+
+    /**
+     * @dev function to be called one time during the inbox upgrade process
+     *      this is used to fix the storage slots
+     */
     function postUpgradeInit(IBridge _bridge) external;
+
+    function initialize(IBridge _bridge, ISequencerInbox _sequencerInbox) external;
 }

package/src/bridge/IOutbox.sol

@@ -5,8 +5,10 @@
 // solhint-disable-next-line compiler-version
 pragma solidity >=0.6.9 <0.9.0;
 
+import "./IBridge.sol";
+
 interface IOutbox {
-    event SendRootUpdated(bytes32 indexed blockHash, bytes32 indexed outputRoot);
+    event SendRootUpdated(bytes32 indexed outputRoot, bytes32 indexed l2BlockHash);
     event OutBoxTransactionExecuted(
         address indexed to,
         address indexed l2Sender,
@@ -14,21 +16,52 @@ interface IOutbox {
         uint256 transactionIndex
     );
 
+    function rollup() external view returns (address); // the rollup contract
+
+    function bridge() external view returns (IBridge); // the bridge contract
+
+    function spent(uint256) external view returns (bytes32); // packed spent bitmap
+
+    function roots(bytes32) external view returns (bytes32); // maps root hashes => L2 block hash
+
+    // solhint-disable-next-line func-name-mixedcase
+    function OUTBOX_VERSION() external view returns (uint128); // the outbox version
+
+    function updateSendRoot(bytes32 sendRoot, bytes32 l2BlockHash) external;
+
+    /// @notice When l2ToL1Sender returns a nonzero address, the message was originated by an L2 account
+    ///         When the return value is zero, that means this is a system message
+    /// @dev the l2ToL1Sender behaves as the tx.origin, the msg.sender should be validated to protect against reentrancies
     function l2ToL1Sender() external view returns (address);
 
+    /// @return l2Block return L2 block when the L2 tx was initiated or 0 if no L2 to L1 transaction is active
     function l2ToL1Block() external view returns (uint256);
 
+    /// @return l1Block return L1 block when the L2 tx was initiated or 0 if no L2 to L1 transaction is active
     function l2ToL1EthBlock() external view returns (uint256);
 
+    /// @return timestamp return L2 timestamp when the L2 tx was initiated or 0 if no L2 to L1 transaction is active
     function l2ToL1Timestamp() external view returns (uint256);
 
-    // @deprecated batch number is now always 0
-    function l2ToL1BatchNum() external view returns (uint256);
-
+    /// @return outputId returns the unique output identifier of the L2 to L1 tx or 0 if no L2 to L1 transaction is active
     function l2ToL1OutputId() external view returns (bytes32);
 
-    function updateSendRoot(bytes32 sendRoot, bytes32 l2BlockHash) external;
-
+    /**
+     * @notice Executes a messages in an Outbox entry.
+     * @dev Reverts if dispute period hasn't expired, since the outbox entry
+     *      is only created once the rollup confirms the respective assertion.
+     * @dev it is not possible to execute any L2-to-L1 transaction which contains data
+     *      to a contract address without any code (as enforced by the Bridge contract).
+     * @param proof Merkle proof of message inclusion in send root
+     * @param index Merkle path to message
+     * @param l2Sender sender if original message (i.e., caller of ArbSys.sendTxToL1)
+     * @param to destination address for L1 contract call
+     * @param l2Block l2 block number at which sendTxToL1 call was made
+     * @param l1Block l1 block number at which sendTxToL1 call was made
+     * @param l2Timestamp l2 Timestamp at which sendTxToL1 call was made
+     * @param value wei in L1 message
+     * @param data abi-encoded L1 message data
+     */
     function executeTransaction(
         bytes32[] calldata proof,
         uint256 index,
@@ -41,6 +74,17 @@ interface IOutbox {
         bytes calldata data
     ) external;
 
+    /**
+     *  @dev function used to simulate the result of a particular function call from the outbox
+     *       it is useful for things such as gas estimates. This function includes all costs except for
+     *       proof validation (which can be considered offchain as a somewhat of a fixed cost - it's
+     *       not really a fixed cost, but can be treated as so with a fixed overhead for gas estimation).
+     *       We can't include the cost of proof validation since this is intended to be used to simulate txs
+     *       that are included in yet-to-be confirmed merkle roots. The simulation entrypoint could instead pretend
+     *       to confirm a pending merkle root, but that would be less practical for integrating with tooling.
+     *       It is only possible to trigger it when the msg sender is address zero, which should be impossible
+     *       unless under simulation in an eth_call or eth_estimateGas
+     */
     function executeTransactionSimulation(
         uint256 index,
         address l2Sender,
@@ -52,7 +96,11 @@ interface IOutbox {
         bytes calldata data
     ) external;
 
-    function isSpent(uint256) external view returns (bool);
+    /**
+     * @param index Merkle path to message
+     * @return true if the message has been spent
+     */
+    function isSpent(uint256 index) external view returns (bool);
 
     function calculateItemHash(
         address l2Sender,