evm: natspec changes and additions

Author: Rahul Maganti

evm/src/interfaces/INttManager.sol

@@ -7,16 +7,22 @@ import "../libraries/TransceiverStructs.sol";
 import "./INttManagerState.sol";
 
 interface INttManager is INttManagerState {
+    /// @notice The mode is either LOCKING or BURNING. In LOCKING mode, the NttManager locks the
+    ///         tokens of the sender and mints an equivalent amount on the target chain. In BURNING
+    ///         mode, the NttManager burns the tokens of the sender and mints an equivalent amount
+    ///         on the target chain.LOCKING mode preserves the total supply of the tokens.
     enum Mode {
         LOCKING,
         BURNING
     }
 
-    // @dev Information about attestations for a given message.
+    /// @notice Information about attestations for a given message.
+    /// @dev The fields are as follows:
+    ///      - executed: whether the message has been executed.
+    ///      - attested: bitmap of transceivers that have attested to this message.
+    ///                  (NOTE: might contain disabled transceivers)
     struct AttestationInfo {
-        // whether this message has been executed
         bool executed;
-        // bitmap of transceivers that have attested to this message (NOTE: might contain disabled transceivers)
         uint64 attestedTransceivers;
     }
 
@@ -43,12 +49,41 @@ interface INttManager is INttManagerState {
     /// @param mode The mode.
     error InvalidMode(uint8 mode);
 
+    /// @notice Error when the refund to the sender fails.
+    /// @dev Selector 0x2ca23714.
+    /// @param refundAmount The refund amount.
     error RefundFailed(uint256 refundAmount);
-    error TransceiverAlreadyAttestedToMessage(bytes32 nttManagerMessageHash);
+
+    /// @notice Error when the tranceiver already attested to the message.
+    ///         To ensure the client does not continue to initiate calls to the ateestationReceived function.
+    /// @dev Selector 0x2113894.
+    /// @param nttManagerMessageHash The hash of the message.
+    error TrasceiverAlreadyAttestedToMessage(bytes32 nttManagerMessageHash);
+
+    /// @notice Error when the message is not approved.
+    /// @dev Selector 0x451c4fb0.
+    /// @param msgHash The hash of the message.
     error MessageNotApproved(bytes32 msgHash);
+
+    /// @notice Error if the target chain is not supported or does not exist.
+    /// @dev Selector 0x3dcb204a.
+    /// @param targetChain The target chain.
+    /// @param thisChain The current chain.
     error InvalidTargetChain(uint16 targetChain, uint16 thisChain);
+
+    /// @notice Error when the transfer amount is zero.
+    /// @dev Selector 0x9993626a.
     error ZeroAmount();
+
+    /// @notice Error when the recipient is invalid.
+    /// @dev Selector 0x9c8d2cd2.
     error InvalidRecipient();
+
+    /// @@notice Error when the amount burned is different than the balance difference,
+    ///          since NTT does not support burn fees.
+    /// @dev Selector 0x02156a8f.
+    /// @param burnAmount The amount burned.
+    /// @param balanceDiff The balance after burning.
     error BurnAmountDifferentThanBalanceDiff(uint256 burnAmount, uint256 balanceDiff);
 
     /// @notice Transfer a given amount to a recipient on a given chain. This function is called

evm/src/interfaces/IWormholeTransceiver.sol

@@ -6,29 +6,65 @@ import "../libraries/TransceiverStructs.sol";
 import "./IWormholeTransceiverState.sol";
 
 interface IWormholeTransceiver is IWormholeTransceiverState {
+
+    /// @notice The instruction for the WormholeTransceiver contract
+    ///         to skip delivery via the relayer.
     struct WormholeTransceiverInstruction {
         bool shouldSkipRelayerSend;
     }
 
+    /// @notice Emitted when a relayed message is received.
+    /// @dev Topic0
+    ///      0xf557dbbb087662f52c815f6c7ee350628a37a51eae9608ff840d996b65f87475
+    /// @param digest The digest of the message.
+    /// @param emitterChainId The chain ID of the emitter.
+    /// @param emitterAddress The address of the emitter.
     event ReceivedRelayedMessage(bytes32 digest, uint16 emitterChainId, bytes32 emitterAddress);
+
+    /// @notice Emitted when a message is received.
+    /// @dev Topic0
+    ///     0xf6fc529540981400dc64edf649eb5e2e0eb5812a27f8c81bac2c1d317e71a5f0.
+    /// @param digest The digest of the message.
+    /// @param emitterChainId The chain ID of the emitter.
+    /// @param emitterAddress The address of the emitter.
+    /// @param sequence The sequence of the message.
     event ReceivedMessage(
         bytes32 digest, uint16 emitterChainId, bytes32 emitterAddress, uint64 sequence
     );
+
+    /// @notice Emitted when a message is sent from the transceiver.
+    /// @dev Topic0
+    ///      0x53b3e029c5ead7bffc739118953883859d30b1aaa086e0dca4d0a1c99cd9c3f5.
+    /// @param recipientChain The chain ID of the recipient.
+    /// @param message The message.
     event SendTransceiverMessage(
         uint16 recipientChain, TransceiverStructs.TransceiverMessage message
     );
 
+    /// @notice Error when the relaying configuration is invalid. (e.g. chainId is not registered)
+    /// @dev Selector: 0x9449a36c.
+    /// @param chainId The chain ID that is invalid.
     error InvalidRelayingConfig(uint16 chainId);
+
+    /// @notice Error when the peer transceiver is invalid.
+    /// @dev Selector: 0x79b1ce56.
+    /// @param chainId The chain ID of the peer.
+    /// @param peerAddress The address of the invalid peer.
     error InvalidWormholePeer(uint16 chainId, bytes32 peerAddress);
+
+    /// @notice Error when the VAA has already been consumed.
+    /// @dev Selector: 0x406e719e.
+    /// @param vaaHash The hash of the VAA.
     error TransferAlreadyCompleted(bytes32 vaaHash);
 
-    /// @notice Receive an attested message from the verification layer. This function should verify
-    /// the `encodedVm` and then deliver the attestation to the transceiver NttManager contract.
+    /// @notice Receive an attested message from the verification layer.
+    /// This function should verify the `encodedVm` and then deliver the attestation
+    /// to the transceiver NttManager contract.
     /// @param encodedMessage The attested message.
     function receiveMessage(bytes memory encodedMessage) external;
 
-    /// @notice Parses the encoded instruction and returns the instruction struct. This instruction
-    /// is specific to the WormholeTransceiver contract.
+    /// @notice Parses the encoded instruction and returns the instruction struct.
+    /// This instruction is specific to the WormholeTransceiver contract.
     /// @param encoded The encoded instruction.
     /// @return instruction The parsed `WormholeTransceiverInstruction`.
     function parseWormholeTransceiverInstruction(bytes memory encoded)

evm/src/libraries/RateLimiter.sol

@@ -9,10 +9,8 @@ import "../libraries/TrimmedAmount.sol";
 
 abstract contract RateLimiter is IRateLimiter, IRateLimiterEvents {
     using TrimmedAmountLib for TrimmedAmount;
-    /**
-     * @dev The duration it takes for the limits to fully replenish
-     */
 
+    /// @dev The duration it takes for the limits to fully replenish.
     uint64 public immutable rateLimitDuration;
 
     /// =============== STORAGE ===============================================