evm: natspec changes and additions

Author: Rahul Maganti

evm/src/NttManager/NttManager.sol

@@ -17,6 +17,22 @@ import "../interfaces/ITransceiver.sol";
 
 import {NttManagerState} from "./NttManagerState.sol";
 
+/// @title NttManager
+/// @notice The NttManager contract is responsible for managing the token
+///         and associated transceivers.
+///
+/// @dev Each NttManager contract is associated with a single token but
+///      can be responsible for multiple transceivers.
+///
+/// @dev When transferring tokens, the NttManager contract will either
+///      lock the tokens or burn them, depending on the mode.
+///
+/// @dev To initiate a transfer, the user calls the transfer function with:
+///  - the amount
+///  - the recipient chain
+///  - the recipient address
+///  - (optional) a flag to indicate whether the transfer should be queued
+///    if the rate limit is exceeded
 contract NttManager is INttManager, NttManagerState {
     using BytesParsing for bytes;
     using SafeERC20 for IERC20;

evm/src/Transceiver/Transceiver.sol

@@ -11,6 +11,14 @@ import "../libraries/Implementation.sol";
 import "../interfaces/INttManager.sol";
 import "../interfaces/ITransceiver.sol";
 
+/// @title Transceiver
+/// @notice This contract is a base contract for Transceivers.
+/// @dev The Transceiver provides basic functionality for transmitting / receiving NTT messages.
+///      The contract supports pausing via an admin or owner and is upgradable.
+///
+/// @dev The interface for receiving messages is not enforced by this contract.
+///      Instead, inheriting contracts should implement their own receiving logic,
+///      based on the verification model and serde logic associated with message handling.
 abstract contract Transceiver is
     ITransceiver,
     PausableOwnable,

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 when trying to execute a message on an unintended target chain.
+    /// @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,64 @@ 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/interfaces/IWormholeTransceiverState.sol

@@ -4,17 +4,65 @@ pragma solidity >=0.8.8 <0.9.0;
 import "../libraries/TransceiverStructs.sol";
 
 interface IWormholeTransceiverState {
+    /// @notice Emitted when a message is sent from the transceiver.
+    /// @dev Topic0
+    ///      0x375a56c053c4d19a2e3445e97b7a28bf4e908617ce6d766e1e03a9d3f5276271.
+    /// @param relayingType The type of relaying.
+    /// @param deliveryPayment The amount of ether sent along with the tx to cover the delivery fee.
     event RelayingInfo(uint8 relayingType, uint256 deliveryPayment);
+
+    /// @notice Emitted when a peer transceiver is set.
+    /// @dev Topic0
+    ///      0xa559263ee060c7a2560843b3a064ff0376c9753ae3e2449b595a3b615d326466.
+    /// @param chainId The chain ID of the peer.
+    /// @param peerContract The address of the peer contract.
     event SetWormholePeer(uint16 chainId, bytes32 peerContract);
+
+    /// @notice Emitted when relaying is enabled for the given chain.
+    /// @dev Topic0
+    ///      0x528b18a533e892b5401d1fb63597275df9d2bb45b13e7695c3147cd07b9746c3.
+    /// @param chainId The chain ID to set.
+    /// @param isEvm A boolean indicating whether relaying is enabled.
     event SetIsWormholeRelayingEnabled(uint16 chainId, bool isRelayingEnabled);
+
+    /// @notice Emitted when special relaying is enabled for the given chain.
+    /// @dev Topic0
+    ///      0x0fe301480713b2c2072ee91b3bcfcbf2c0014f0447c89046f020f0f80727003c.
+    /// @param chainId The chain ID to set.
     event SetIsSpecialRelayingEnabled(uint16 chainId, bool isRelayingEnabled);
+
+    /// @notice Emitted when the chain is EVM compatible.
+    /// @dev Topic0
+    ///      0x50bbeb4e180e8f9e429f6ef6b53496616c747fe502441c4f423d5fc9ec958d9c.
+    /// @param chainId The chain ID to set.
     event SetIsWormholeEvmChain(uint16 chainId);
 
+    /// @notice Additonal messages are not allowed.
+    /// @dev Selector: 0xc504ea29.
     error UnexpectedAdditionalMessages();
+
+    /// @notice Error if the VAA is invalid.
+    /// @dev Selector: 0x8ee2e336.
+    /// @param reason The reason the VAA is invalid.
     error InvalidVaa(string reason);
+
+    /// @notice Error if the peer has already been set.
+    /// @dev Selector: 0xb55eeae9.
+    /// @param chainId The chain ID of the peer.
+    /// @param peerAddress The address of the peer.
     error PeerAlreadySet(uint16 chainId, bytes32 peerAddress);
+
+    /// @notice Error the peer contract cannot be the zero address.
+    /// @dev Selector: 0x26e0c7de.
     error InvalidWormholePeerZeroAddress();
+
+    /// @notice The chain ID cannot be zero.
+    /// @dev Selector: 0x3dd98b24.
     error InvalidWormholeChainIdZero();
+
+    /// @notice The caller is not the relayer.
+    /// @dev Selector: 0x1c269589.
+    /// @param caller The caller.
     error CallerNotRelayer(address caller);
 
     /// @notice Get the corresponding Transceiver contract on other chains that have been registered

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 (in seconds) it takes for the limits to fully replenish.
     uint64 public immutable rateLimitDuration;
 
     /// =============== STORAGE ===============================================