add documentation, natspec plus refactors (#186)

* IManagerEvents: add natpsec for manager events

* IRateLimiterEvents: add natspec for rate limiter events

* IRateLimiterEvents: add natspec for errors

* IRateLimiter: add natspec for rate limiter structs

* EndpointStructs: cleanup + add natspec

* forge fmt

---------

Co-authored-by: Rahul Maganti <rahulmaganti@Rahuls-MacBook-Pro.local>

Author: RahulMaganti47

evm/src/interfaces/IManagerEvents.sol

@@ -4,16 +4,69 @@ pragma solidity >=0.8.8 <0.9.0;
 import "../libraries/NormalizedAmount.sol";
 
 interface IManagerEvents {
+    /// @notice Emitted when a message is sent from the manager.
+    /// @dev Topic0
+    ///      0x71ec1d4b53baa86365b6523ea136c9fe0f72c36c721e7e28e9efac2c23b39d98.
+    /// @param recipient The recipient of the message.
+    /// @param amount The amount transferred.
+    /// @param recipientChain The chain ID of the recipient.
+    /// @param msgSequence The unique sequence ID of the message.
     event TransferSent(
         bytes32 recipient, uint256 amount, uint16 recipientChain, uint64 msgSequence
     );
+
+    /// @notice Emitted when the sibling contract is updated.
+    /// @dev Topic0
+    ///      0x51b8437a7e22240c473f4cbdb4ed3a4f4bf5a9e7b3c511d7cfe0197325735700.
+    /// @param chainId_ The chain ID of the sibling contract.
+    /// @param oldSiblingContract The old sibling contract address.
+    /// @param siblingContract The new sibling contract address.
     event SiblingUpdated(
         uint16 indexed chainId_, bytes32 oldSiblingContract, bytes32 siblingContract
     );
+
+    /// @notice Emitted when a message has been attested to.
+    /// @dev Topic0
+    ///      0x35a2101eaac94b493e0dfca061f9a7f087913fde8678e7cde0aca9897edba0e5.
+    /// @param digest The digest of the message.
+    /// @param endpoint The address of the endpoint.
+    /// @param index The index of the endpoint in the bitmap.
     event MessageAttestedTo(bytes32 digest, address endpoint, uint8 index);
+
+    /// @notice Emmitted when the threshold required endpoints is changed.
+    /// @dev Topic0
+    ///      0x2a855b929b9a53c6fb5b5ed248b27e502b709c088e036a5aa17620c8fc5085a9.
+    /// @param oldThreshold The old threshold.
+    /// @param threshold The new threshold.
     event ThresholdChanged(uint8 oldThreshold, uint8 threshold);
+
+    /// @notice Emitted when an endpoint is removed from the manager.
+    /// @dev Topic0
+    ///      0xc6289e62021fd0421276d06677862d6b328d9764cdd4490ca5ac78b173f25883.
+    /// @param endpoint The address of the endpoint.
+    /// @param endpointsNum The current number of endpoints.
+    /// @param threshold The current threshold of endpoints.
     event EndpointAdded(address endpoint, uint256 endpointsNum, uint8 threshold);
+
+    /// @notice Emitted when an endpoint is removed from the manager.
+    /// @dev Topic0
+    ///     0x638e631f34d9501a3ff0295873b29f50d0207b5400bf0e48b9b34719e6b1a39e.
+    /// @param endpoint The address of the endpoint.
+    /// @param threshold The current threshold of endpoints.
     event EndpointRemoved(address endpoint, uint8 threshold);
+
+    /// @notice Emitted when a message has already been executed to
+    ///         notify client of against retries.
+    /// @dev Topic0
+    ///      0x4069dff8c9df7e38d2867c0910bd96fd61787695e5380281148c04932d02bef2.
+    /// @param sourceManager The address of the source manager.
+    /// @param msgHash The keccak-256 hash of the message.
     event MessageAlreadyExecuted(bytes32 indexed sourceManager, bytes32 indexed msgHash);
+
+    /// @notice Emitted when a transfer has been redeemed
+    ///         (either minted or unlocked on the recipient chain).
+    /// @dev Topic0
+    ///      0x504e6efe18ab9eed10dc6501a417f5b12a2f7f2b1593aed9b89f9bce3cf29a91.
+    /// @param digest The digest of the message.
     event TransferRedeemed(bytes32 digest);
 }

evm/src/interfaces/IRateLimiter.sol

@@ -5,19 +5,60 @@ import "../libraries/NormalizedAmount.sol";
 import "../libraries/EndpointStructs.sol";
 
 interface IRateLimiter {
+    /// @notice Not enough capacity to send the transfer.
+    /// @dev Selector 0x26fb55dd.
+    /// @param currentCapacity The current capacity.
+    /// @param amount The amount of the transfer.
     error NotEnoughCapacity(uint256 currentCapacity, uint256 amount);
+
+    /// @notice Outbound transfer is not longer queued.
+    /// @dev Selector 0xbfd5f462.
+    /// @param queueSequence The sequence of the queue.
     error OutboundQueuedTransferNotFound(uint64 queueSequence);
+
+    /// @notice Cannot complete the outbound transfer, the transfer is still queued.
+    /// @dev Selector 0xc06cf05f.
+    /// @param queueSequence The sequence of the queue.
+    /// @param transferTimestamp The timestamp of when the transfer was queued.
     error OutboundQueuedTransferStillQueued(uint64 queueSequence, uint256 transferTimestamp);
+
+    /// @notice The inbound transfer is not longer queued.
+    /// @dev Selector 0xc06f2bc0.
+    /// @param digest The digest of the transfer.
     error InboundQueuedTransferNotFound(bytes32 digest);
+
+    /// @notice The transfer is still queued.
+    /// @dev Selector 0xe5b9ce80.
+    /// @param digest The digest of the transfer.
+    /// @param transferTimestamp The timestamp of the transfer.
     error InboundQueuedTransferStillQueued(bytes32 digest, uint256 transferTimestamp);
+
+    /// @notice The new capacity cannot exceed the limit.
+    /// @dev Selector 0x0f85ba52.
+    /// @param newCurrentCapacity The new current capacity.
+    /// @param newLimit The new limit.
     error CapacityCannotExceedLimit(NormalizedAmount newCurrentCapacity, NormalizedAmount newLimit);
 
+    /// @notice Parameters used in determining rate limits and queuing.
+    /// @dev
+    ///    - limit: current rate limit value.
+    ///    - currentCapacity: the current capacity left.
+    ///    - lastTxTimestamp: the timestamp of when the
+    ///                       capacity was previously consumption.
     struct RateLimitParams {
         NormalizedAmount limit;
         NormalizedAmount currentCapacity;
         uint64 lastTxTimestamp;
     }
 
+    /// @notice Parameters for an outbound queued transfer.
+    /// @dev
+    ///    - recipient: the recipient of the transfer.
+    ///    - amount: the amount of the transfer, normalized.
+    ///    - txTimestamp: the timestamp of the transfer.
+    ///    - recipientChain: the chain of the recipient.
+    ///    - sender: the sender of the transfer.
+    ///    - endpointInstructions: additional instructions to be forwarded to the recipient chain.
     struct OutboundQueuedTransfer {
         bytes32 recipient;
         NormalizedAmount amount;
@@ -27,6 +68,11 @@ interface IRateLimiter {
         bytes endpointInstructions;
     }
 
+    /// @notice Parameters for an inbound queued transfer.
+    /// @dev
+    ///   - amount: the amount of the transfer, normalized.
+    ///   - txTimestamp: the timestamp of the transfer.
+    ///   - recipient: the recipient of the transfer.
     struct InboundQueuedTransfer {
         NormalizedAmount amount;
         uint64 txTimestamp;

evm/src/interfaces/IRateLimiterEvents.sol

@@ -4,8 +4,24 @@ pragma solidity >=0.8.8 <0.9.0;
 import "../libraries/NormalizedAmount.sol";
 
 interface IRateLimiterEvents {
+    /// @notice Emitted when an inbound transfer is queued
+    /// @dev Topic0
+    ///      0x7f63c9251d82a933210c2b6d0b0f116252c3c116788120e64e8e8215df6f3162.
+    /// @param digest The digest of the message.
     event InboundTransferQueued(bytes32 digest);
+
+    /// @notice Emitted whenn an outbound transfer is queued.
+    /// @dev Topic0
+    ///      0x69add1952a6a6b9cb86f04d05f0cb605cbb469a50ae916139d34495a9991481f.
+    /// @param queueSequence The location of the transfer in the queue.
     event OutboundTransferQueued(uint64 queueSequence);
+
+    /// @notice Emitted when an outbound transfer is rate limited.
+    /// @dev Topic0
+    ///      0x754d657d1363ee47d967b415652b739bfe96d5729ccf2f26625dcdbc147db68b.
+    /// @param sender The initial sender of the transfer.
+    /// @param amount The amount to be transferred.
+    /// @param currentCapacity The capacity left for transfers within the 24-hour window.
     event OutboundTransferRateLimited(
         address indexed sender, uint64 sequence, uint256 amount, uint256 currentCapacity
     );

evm/src/libraries/EndpointStructs.sol

@@ -8,7 +8,15 @@ library EndpointStructs {
     using BytesParsing for bytes;
     using NormalizedAmountLib for NormalizedAmount;
 
+    /// @notice Error thrown when the payload length exceeds the allowed maximum.
+    /// @dev Selector 0xa3419691.
+    /// @param size The size of the payload.
     error PayloadTooLong(uint256 size);
+
+    /// @notice Error thrown when the prefix of an encoded message
+    ///         does not match the expected value.
+    /// @dev Selector 0x56d2569d.
+    /// @param prefix The prefix that was found in the encoded message.
     error IncorrectPrefix(bytes4 prefix);
     error UnorderedInstructions();
 
@@ -50,11 +58,9 @@ library EndpointStructs {
         return abi.encodePacked(m.sequence, m.sender, payloadLength, m.payload);
     }
 
-    /*
-     * @dev Parse a ManagerMessage.
-     *
-     * @params encoded The byte array corresponding to the encoded message
-     */
+    /// @notice Parse a ManagerMessage.
+    /// @param encoded The byte array corresponding to the encoded message
+    /// @return managerMessage The parsed ManagerMessage struct.
     function parseManagerMessage(bytes memory encoded)
         public
         pure
@@ -104,11 +110,9 @@ library EndpointStructs {
         );
     }
 
-    /*
-     * @dev Parse a NativeTokenTransfer.
-     *
-     * @params encoded The byte array corresponding to the encoded message
-     */
+    /// @dev Parse a NativeTokenTransfer.
+    /// @param encoded The byte array corresponding to the encoded message
+    /// @return nativeTokenTransfer The parsed NativeTokenTransfer struct.
     function parseNativeTokenTransfer(bytes memory encoded)
         public
         pure
@@ -154,13 +158,12 @@ library EndpointStructs {
         bytes endpointPayload;
     }
 
-    /*
-     * @dev Encodes an Endpoint message for communication between the Manager and the Endpoint.
-     *
-     * @param m The EndpointMessage struct containing the message details.
-     * @return encoded The byte array corresponding to the encoded message.
-     * @throws PayloadTooLong if the length of endpointId, managerPayload, or endpointPayload exceeds the allowed maximum.
-     */
+    // @notice Encodes an Endpoint message for communication between the
+    //         Manager and the Endpoint.
+    // @param m The EndpointMessage struct containing the message details.
+    // @return encoded The byte array corresponding to the encoded message.
+    // @custom:throw PayloadTooLong if the length of endpointId, managerPayload,
+    //         or endpointPayload exceeds the allowed maximum.
     function encodeEndpointMessage(
         bytes4 prefix,
         EndpointMessage memory m
@@ -203,13 +206,11 @@ library EndpointStructs {
         return (endpointMessage, encoded);
     }
 
-    /*
-    * @dev Parses an encoded message and extracts information into an EndpointMessage struct.
-    *
-    * @param encoded The encoded bytes containing information about the EndpointMessage.
-    * @return endpointMessage The parsed EndpointMessage struct.
-    * @throws IncorrectPrefix if the prefix of the encoded message does not match the expected prefix.
-    */
+    /// @dev Parses an encoded message and extracts information into an EndpointMessage struct.
+    /// @param encoded The encoded bytes containing information about the EndpointMessage.
+    /// @return endpointMessage The parsed EndpointMessage struct.
+    /// @custom:throw IncorrectPrefix if the prefix of the encoded message does not
+    ///         match the expected prefix.
     function parseEndpointMessage(
         bytes4 expectedPrefix,
         bytes memory encoded
@@ -238,7 +239,10 @@ library EndpointStructs {
         encoded.checkLength(offset);
     }
 
-    /// @dev Parses the payload of an Endpoint message and returns the parsed ManagerMessage struct.
+    /// @dev Parses the payload of an Endpoint message and returns
+    ///      the parsed ManagerMessage struct.
+    /// @param expectedPrefix The prefix that should be encoded in the manager message.
+    /// @param payload The payload sent across the wire.
     function parseEndpointAndManagerMessage(
         bytes4 expectedPrefix,
         bytes memory payload