Merge pull request #73 from base-org/jack/clean-comments

clean comments

Author: jackchuma

README.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-RIP-7755 is a Rollup Improvement Proposal designed to establish a standardized, permissionless, and decentralized protocol for low-level cross-chain calls. By implementing immutable on-chain rules that incentivize off-chain participants, known as “fulfillers” in this context, to compete for transaction fees associated with cross-chain calls, we anticipate a significant enhancement in user experience without compromising on security or decentralization.
+RIP-7755 is a Rollup Improvement Proposal designed to establish a standardized, permissionless, and decentralized protocol for low-level cross-chain calls. By implementing immutable onchain rules that incentivize offchain participants, known as “fulfillers” in this context, to compete for transaction fees associated with cross-chain calls, we anticipate a significant enhancement in user experience without compromising on security or decentralization.
 
 When a user initiates a request for a cross-chain call, it is accompanied by a financial incentive for the first actor who can successfully execute the call. This reward is granted to the fulfiller only if they can provide cryptographic proof that the cross-chain call was executed successfully and correctly. One method to achieve this is through the use of storage proofs.
 

contracts/src/ERC7786Base.sol

@@ -55,6 +55,7 @@ contract ERC7786Base {
     bytes4 internal constant _USER_OP_ATTRIBUTE_SELECTOR = 0xd45448dd; // isUserOp(bool)
 
     /// @notice This error is thrown if an attribute is not found in the attributes array
+    ///
     /// @param selector The selector of the attribute that was not found
     error AttributeNotFound(bytes4 selector);
 
@@ -63,7 +64,7 @@ contract ERC7786Base {
     /// @custom:reverts If the attribute is not found
     ///
     /// @param attributes The attributes array to search
-    /// @param selector The selector of the attribute to find
+    /// @param selector   The selector of the attribute to find
     ///
     /// @return attribute The attribute found
     function _locateAttribute(bytes[] calldata attributes, bytes4 selector) internal pure returns (bytes calldata) {
@@ -79,9 +80,9 @@ contract ERC7786Base {
     /// @notice Locates an attribute in the attributes array without checking if the attribute is found
     ///
     /// @param attributes The attributes array to search
-    /// @param selector The selector of the attribute to find
+    /// @param selector   The selector of the attribute to find
     ///
-    /// @return found Whether the attribute was found
+    /// @return found     Whether the attribute was found
     /// @return attribute The attribute found
     function _locateAttributeUnchecked(bytes[] calldata attributes, bytes4 selector)
         internal
@@ -99,7 +100,7 @@ contract ERC7786Base {
     /// @notice Locates an attribute value in the attributes array
     ///
     /// @param attributes The attributes array to search
-    /// @param selector The selector of the attribute to find
+    /// @param selector   The selector of the attribute to find
     ///
     /// @return value The value of the attribute found
     function _locateAttributeValue(bytes[] calldata attributes, bytes4 selector) internal pure returns (uint256) {

contracts/src/RIP7755Inbox.sol

@@ -16,7 +16,7 @@ import {Paymaster} from "./Paymaster.sol";
 /// @author Coinbase (https://github.com/base-org/RIP-7755-poc)
 ///
 /// @notice An inbox contract within RIP-7755. This contract's sole purpose is to route requested transactions on
-/// destination chains and store record of their fulfillment.
+///         destination chains and store record of their fulfillment.
 contract RIP7755Inbox is ERC7786Base, Paymaster {
     using Address for address payable;
     using Strings for string;
@@ -45,12 +45,15 @@ contract RIP7755Inbox is ERC7786Base, Paymaster {
     /// @param fulfilledBy The account that fulfilled the cross chain call
     event CallFulfilled(bytes32 indexed requestHash, address indexed fulfilledBy);
 
-    /// @notice This error is thrown when an account attempts to submit a cross chain call that has already been fulfilled
+    /// @notice This error is thrown when an account attempts to submit a cross chain call that has already been
+    ///         fulfilled
     error CallAlreadyFulfilled();
 
-    /// @notice This error is thrown if a fulfiller submits a `msg.value` greater than the total value needed for all the calls
+    /// @notice This error is thrown if a fulfiller submits a `msg.value` greater than the total value needed for all
+    ///         the calls
+    ///
     /// @param expected The total value needed for all the calls
-    /// @param actual The received `msg.value`
+    /// @param actual   The received `msg.value`
     error InvalidValue(uint256 expected, uint256 actual);
 
     /// @notice This error is thrown when an invalid caller is detected
@@ -66,9 +69,9 @@ contract RIP7755Inbox is ERC7786Base, Paymaster {
 
     /// @notice Delivery of a message sent from another chain.
     ///
-    /// @param sourceChain The CAIP-2 source chain identifier
-    /// @param sender The CAIP-10 account address of the sender
-    /// @param messages The messages to be included in the request
+    /// @param sourceChain      The CAIP-2 source chain identifier
+    /// @param sender           The CAIP-10 account address of the sender
+    /// @param messages         The messages to be included in the request
     /// @param globalAttributes The attributes to be included in the message
     ///
     /// @return selector The selector of the function
@@ -111,9 +114,9 @@ contract RIP7755Inbox is ERC7786Base, Paymaster {
     /// @dev Filters out the fulfiller attribute from the attributes array
     ///
     /// @param sourceChain The CAIP-2 source chain identifier
-    /// @param sender The CAIP-10 account address of the sender
-    /// @param messages The messages to be included in the request
-    /// @param attributes The attributes to be included in the message
+    /// @param sender      The CAIP-10 account address of the sender
+    /// @param messages    The messages to be included in the request
+    /// @param attributes  The attributes to be included in the message
     ///
     /// @return _ The keccak256 hash of the message request
     function getRequestId(

contracts/src/RIP7755Outbox.sol

@@ -52,77 +52,87 @@ abstract contract RIP7755Outbox is ERC7786Base {
     uint256 private _nonce;
 
     /// @notice Event emitted when a user sends a message to the `RIP7755Inbox`
-    /// @param outboxId The keccak256 hash of the message request
+    ///
+    /// @param outboxId         The keccak256 hash of the message request
     /// @param destinationChain The CAIP-2 chain identifier of the destination chain
-    /// @param sender The CAIP-10 account address of the sender
-    /// @param messages The messages to be included in the request
+    /// @param sender           The CAIP-10 account address of the sender
+    /// @param messages         The messages to be included in the request
     /// @param globalAttributes The attributes to be included in the message
     event MessagesPosted(
         bytes32 indexed outboxId, string destinationChain, string sender, Message[] messages, bytes[] globalAttributes
     );
 
     /// @notice Event emitted when a cross chain call is successfully completed
+    ///
     /// @param requestHash The keccak256 hash of a `CrossChainRequest`
-    /// @param submitter The address of the fulfiller that successfully completed the cross chain call
+    /// @param submitter   The address of the fulfiller that successfully completed the cross chain call
     event CrossChainCallCompleted(bytes32 indexed requestHash, address submitter);
 
     /// @notice Event emitted when an expired cross chain call request is canceled
+    ///
     /// @param requestHash The keccak256 hash of a `CrossChainRequest`
     event CrossChainCallCanceled(bytes32 indexed requestHash);
 
     /// @notice This error is thrown when a cross chain request specifies the native currency as the reward type but
     ///         does not send the correct `msg.value`
+    ///
     /// @param expected The expected `msg.value` that should have been sent with the transaction
     /// @param received The actual `msg.value` that was sent with the transaction
     error InvalidValue(uint256 expected, uint256 received);
 
     /// @notice This error is thrown if a user attempts to cancel a request or a Filler attempts to claim a reward for
     ///         a request that is not in the `CrossChainCallStatus.Requested` state
+    ///
     /// @param expected The expected status during the transaction
-    /// @param actual The actual request status during the transaction
+    /// @param actual   The actual request status during the transaction
     error InvalidStatus(CrossChainCallStatus expected, CrossChainCallStatus actual);
 
     /// @notice This error is thrown if an attempt to cancel a request is made before the request's expiry timestamp
+    ///
     /// @param currentTimestamp The current block timestamp
-    /// @param expiry The timestamp at which the request expires
+    /// @param expiry           The timestamp at which the request expires
     error CannotCancelRequestBeforeExpiry(uint256 currentTimestamp, uint256 expiry);
 
     /// @notice This error is thrown if an account attempts to cancel a request that did not originate from that account
-    /// @param caller The account attempting the request cancellation
+    ///
+    /// @param caller         The account attempting the request cancellation
     /// @param expectedCaller The account that created the request
     error InvalidCaller(address caller, address expectedCaller);
 
     /// @notice This error is thrown if a request expiry does not give enough time for the delay attribute to pass
     error ExpiryTooSoon();
 
     /// @notice This error is thrown if an unsupported attribute is provided
+    ///
     /// @param selector The selector of the unsupported attribute
     error UnsupportedAttribute(bytes4 selector);
 
     /// @notice This error is thrown if the attribute length supplied to `sendMessage` is not equal to the expected
     ///         length
+    ///
     /// @param expected The expected length of the attributes
-    /// @param actual The actual length of the attributes
+    /// @param actual   The actual length of the attributes
     error InvalidAttributeLength(uint256 expected, uint256 actual);
 
     /// @notice This error is thrown if a required attribute is missing from the global attributes array for a 7755
     ///         request
+    ///
     /// @param selector The selector of the missing attribute
     error MissingRequiredAttribute(bytes4 selector);
 
     /// @notice Initiates the sending of a 7755 request containing a single message
     ///
     /// @custom:reverts If the attributes array length is less than 3
     /// @custom:reverts If a required attribute is missing from the global attributes array. Required attributes are:
-    ///                 - Reward attribute
-    ///                 - Delay attribute
-    ///                 - Inbox attribute
+    ///                   - Reward attribute
+    ///                   - Delay attribute
+    ///                   - Inbox attribute
     /// @custom:reverts If an unsupported attribute is provided
     ///
     /// @param destinationChain The CAIP-2 chain identifier of the destination chain
-    /// @param receiver The CAIP-10 account address of the receiver (not including the chain identifier)
-    /// @param payload The encoded calls array
-    /// @param attributes The attributes to be included in the message
+    /// @param receiver         The CAIP-10 account address of the receiver (not including the chain identifier)
+    /// @param payload          The encoded calls array
+    /// @param attributes       The attributes to be included in the message
     ///
     /// @return messageId The generated request id
     function sendMessage(
@@ -140,13 +150,13 @@ abstract contract RIP7755Outbox is ERC7786Base {
     ///
     /// @custom:reverts If the attributes array length is less than 3
     /// @custom:reverts If a required attribute is missing from the global attributes array. Required attributes are:
-    ///                 - Reward attribute
-    ///                 - Delay attribute
-    ///                 - Inbox attribute
+    ///                   - Reward attribute
+    ///                   - Delay attribute
+    ///                   - Inbox attribute
     /// @custom:reverts If an unsupported attribute is provided
     ///
     /// @param destinationChain The CAIP-2 chain identifier of the destination chain
-    /// @param messages The messages to be included in the request
+    /// @param messages         The messages to be included in the request
     /// @param globalAttributes The attributes to be included in the message
     ///
     /// @return messageId The generated request id
@@ -166,13 +176,13 @@ abstract contract RIP7755Outbox is ERC7786Base {
     /// @custom:reverts If finality delay seconds have not passed since the request was fulfilled on destination chain
     /// @custom:reverts If the reward attribute is not found in the attributes array
     ///
-    /// @param sender The CAIP-10 account address of the sender
-    /// @param destinationChain The CAIP-2 chain identifier of the destination chain
-    /// @param messages The messages to be included in the request
+    /// @param sender             The CAIP-10 account address of the sender
+    /// @param destinationChain   The CAIP-2 chain identifier of the destination chain
+    /// @param messages           The messages to be included in the request
     /// @param expandedAttributes The attributes to be included in the message
-    /// @param proof A proof that cryptographically verifies that `fulfillmentInfo` does, indeed, exist in storage on
-    ///              the destination chain
-    /// @param payTo The address the Filler wants to receive the reward
+    /// @param proof              A proof that cryptographically verifies that `fulfillmentInfo` does, indeed, exist in
+    ///                           storage on the destination chain
+    /// @param payTo              The address the Filler wants to receive the reward
     function claimReward(
         string calldata sender,
         string calldata destinationChain,
@@ -205,9 +215,9 @@ abstract contract RIP7755Outbox is ERC7786Base {
     /// @custom:reverts If the current block timestamp is less than the expiry timestamp plus the cancel delay seconds
     /// @custom:reverts If the reward attribute is not found in the attributes array
     ///
-    /// @param sender The CAIP-10 account address of the sender
-    /// @param destinationChain The CAIP-2 chain identifier of the destination chain
-    /// @param messages The messages to be included in the request
+    /// @param sender             The CAIP-10 account address of the sender
+    /// @param destinationChain   The CAIP-2 chain identifier of the destination chain
+    /// @param messages           The messages to be included in the request
     /// @param expandedAttributes The attributes to be included in the message
     function cancelMessage(
         string calldata sender,
@@ -262,10 +272,10 @@ abstract contract RIP7755Outbox is ERC7786Base {
 
     /// @notice Returns the keccak256 hash of a message request
     ///
-    /// @param sender The CAIP-10 account address of the sender
+    /// @param sender           The CAIP-10 account address of the sender
     /// @param destinationChain The CAIP-2 chain identifier of the destination chain
-    /// @param messages The messages to be included in the request
-    /// @param attributes The attributes to be included in the message
+    /// @param messages         The messages to be included in the request
+    /// @param attributes       The attributes to be included in the message
     ///
     /// @return _ The keccak256 hash of the message request
     function getRequestId(
@@ -279,10 +289,10 @@ abstract contract RIP7755Outbox is ERC7786Base {
 
     /// @notice Returns the keccak256 hash of a message request
     ///
-    /// @param sender The CAIP-10 account address of the sender
+    /// @param sender           The CAIP-10 account address of the sender
     /// @param destinationChain The CAIP-2 chain identifier of the destination chain
-    /// @param messages The messages to be included in the request
-    /// @param attributes The attributes to be included in the message
+    /// @param messages         The messages to be included in the request
+    /// @param attributes       The attributes to be included in the message
     ///
     /// @return _ The keccak256 hash of the message request
     function getRequestIdCalldata(
@@ -305,9 +315,9 @@ abstract contract RIP7755Outbox is ERC7786Base {
     ///
     /// @param inboxContractStorageKey The storage location of the data to verify on the destination chain
     ///                                `RIP7755Inbox` contract
-    /// @param inbox The address of the `RIP7755Inbox` contract
-    /// @param attributes The attributes to be included in the message
-    /// @param proofData The proof to validate
+    /// @param inbox                   The address of the `RIP7755Inbox` contract
+    /// @param attributes              The attributes to be included in the message
+    /// @param proofData               The proof to validate
     function _validateProof(
         bytes memory inboxContractStorageKey,
         address inbox,

contracts/src/interfaces/IPrecheckContract.sol

@@ -7,19 +7,19 @@ import {ERC7786Base} from "../ERC7786Base.sol";
 ///
 /// @author Coinbase (https://github.com/base-org/7755-poc)
 ///
-/// @notice A standardized interface for a valid Precheck Contract compatible with RIP-7755.
-///
-/// A cross-chain-call can optionally specify a Precheck Contract used to verify some arbitrary fulfillment condition during the `fulfill` transaction.
-/// To specify a Precheck contract, set its address in a global request attribute using the `_PRECHECK_ATTRIBUTE_SELECTOR` prefix.
-/// In order for the cross chain call to succeed with a precheck, the Precheck contract must inherit this interface and implement `precheckCall`.
+/// @notice A standardized interface for a valid Precheck Contract compatible with RIP-7755. A cross-chain-call can
+///         optionally specify a Precheck Contract used to verify some arbitrary fulfillment condition during the
+///         `fulfill` transaction. To specify a Precheck contract, set its address in a global request attribute using
+///         the `_PRECHECK_ATTRIBUTE_SELECTOR` prefix. In order for the cross chain call to succeed with a precheck,
+///         the Precheck contract must inherit this interface and implement `precheckCall`.
 interface IPrecheckContract {
     /// @notice A precheck function declaration.
     ///
-    /// @param sourceChain The CAIP-2 chain identifier of the source chain.
-    /// @param sender The CAIP-10 account address of the sender.
-    /// @param messages The messages to be included in the request.
+    /// @param sourceChain      The CAIP-2 chain identifier of the source chain.
+    /// @param sender           The CAIP-10 account address of the sender.
+    /// @param messages         The messages to be included in the request.
     /// @param globalAttributes The attributes array.
-    /// @param caller The address of the filler account that submitted the transaction to RIP7755Inbox.
+    /// @param caller           The address of the filler account that submitted the transaction to RIP7755Inbox.
     function precheckCall(
         string calldata sourceChain,
         string calldata sender,