From f1ce53a12dfa0838e38e41243069645ec7a68b22 Mon Sep 17 00:00:00 2001 From: Dirk Brink Date: Thu, 1 Aug 2024 11:46:18 -0700 Subject: [PATCH] evm: More minor natspec improvements --- evm/src/interfaces/IManagerBase.sol | 11 ++++++++--- evm/src/interfaces/INttManager.sol | 27 ++++++++++++++++----------- evm/src/interfaces/IRateLimiter.sol | 9 +++++++++ evm/src/interfaces/ITransceiver.sol | 4 ++++ 4 files changed, 37 insertions(+), 14 deletions(-) diff --git a/evm/src/interfaces/IManagerBase.sol b/evm/src/interfaces/IManagerBase.sol index 6f4577818..98f6d144c 100644 --- a/evm/src/interfaces/IManagerBase.sol +++ b/evm/src/interfaces/IManagerBase.sol @@ -106,11 +106,11 @@ interface IManagerBase { /// @notice Error when the manager doesn't have a peer registered for the destination chain /// @dev Selector 0x3af256bc. - /// @param chainId The target chain id + /// @param chainId The target Wormhole chain id error PeerNotRegistered(uint16 chainId); /// @notice Fetch the delivery price for a given recipient chain transfer. - /// @param recipientChain The chain ID of the transfer destination. + /// @param recipientChain The Wormhole chain ID of the transfer destination. /// @param transceiverInstructions The transceiver specific instructions for quoting and sending /// @return - The delivery prices associated with each enabled endpoint and the total price. function quoteDeliveryPrice( @@ -120,7 +120,7 @@ interface IManagerBase { /// @notice Sets the threshold for the number of attestations required for a message /// to be considered valid. - /// @param threshold The new threshold. + /// @param threshold The new threshold (number of attestations). /// @dev This method can only be executed by the `owner`. function setThreshold(uint8 threshold) external; @@ -166,12 +166,17 @@ interface IManagerBase { function getThreshold() external view returns (uint8); /// @notice Returns a boolean indicating if the transceiver has attested to the message. + /// @param digest The digest of the message. + /// @param index The index of the transceiver + /// @return - Boolean indicating whether the transceiver at index `index` attested to a message digest function transceiverAttestedToMessage( bytes32 digest, uint8 index ) external view returns (bool); /// @notice Returns the number of attestations for a given message. + /// @param digest The digest of the message. + /// @return count The number of attestations received for the given message digest function messageAttestations(bytes32 digest) external view returns (uint8 count); /// @notice Returns of the address of the token managed by this contract. diff --git a/evm/src/interfaces/INttManager.sol b/evm/src/interfaces/INttManager.sol index 90b55b9cd..db83cdb85 100644 --- a/evm/src/interfaces/INttManager.sol +++ b/evm/src/interfaces/INttManager.sol @@ -140,8 +140,9 @@ interface INttManager is IManagerBase { /// sender's tokens. Finally, this function will call into registered `Endpoint` contracts /// to send a message with the incrementing sequence number and the token transfer payload. /// @param amount The amount to transfer. - /// @param recipientChain The chain ID for the destination. + /// @param recipientChain The Wormhole chain ID for the destination. /// @param recipient The recipient address. + /// @return msgId The resulting message ID of the transfer function transfer( uint256 amount, uint16 recipientChain, @@ -154,11 +155,12 @@ interface INttManager is IManagerBase { /// to send a message with the incrementing sequence number and the token transfer payload. /// @dev Transfers are queued if the outbound limit is hit and must be completed by the client. /// @param amount The amount to transfer. - /// @param recipientChain The chain ID for the destination. + /// @param recipientChain The Wormhole chain ID for the destination. /// @param recipient The recipient address. /// @param refundAddress The address to which a refund for unussed gas is issued on the recipient chain. /// @param shouldQueue Whether the transfer should be queued if the outbound limit is hit. /// @param encodedInstructions Additional instructions to be forwarded to the recipient chain. + /// @return msgId The resulting message ID of the transfer function transfer( uint256 amount, uint16 recipientChain, @@ -189,8 +191,8 @@ interface INttManager is IManagerBase { /// @dev This function enforces attestation threshold and replay logic for messages. Once all /// validations are complete, this function calls `executeMsg` to execute the command specified /// by the message. - /// @param sourceChainId The chain id of the sender. - /// @param sourceNttManagerAddress The address of the sender's nttManager contract. + /// @param sourceChainId The Wormhole chain id of the sender. + /// @param sourceNttManagerAddress The address of the sender's NTT Manager contract. /// @param payload The VAA payload. function attestationReceived( uint16 sourceChainId, @@ -203,7 +205,7 @@ interface INttManager is IManagerBase { /// as an NttManagerMessage to extract the sequence, msgType, and other parameters. /// @dev This function is exposed as a fallback for when an `Transceiver` is deregistered /// when a message is in flight. - /// @param sourceChainId The chain id of the sender. + /// @param sourceChainId The Wormhole chain id of the sender. /// @param sourceNttManagerAddress The address of the sender's nttManager contract. /// @param message The message to execute. function executeMsg( @@ -217,15 +219,16 @@ interface INttManager is IManagerBase { function tokenDecimals() external view returns (uint8); /// @notice Returns registered peer contract for a given chain. - /// @param chainId_ chain ID. + /// @param chainId_ Wormhole chain ID. function getPeer(uint16 chainId_) external view returns (NttManagerPeer memory); /// @notice Sets the corresponding peer. /// @dev The nttManager that executes the message sets the source nttManager as the peer. - /// @param peerChainId The chain ID of the peer. + /// @param peerChainId The Wormhole chain ID of the peer. /// @param peerContract The address of the peer nttManager contract. /// @param decimals The number of decimals of the token on the peer chain. - /// @param inboundLimit The inbound rate limit for the peer chain id + /// @param inboundLimit The inbound rate limit for the peer chain id. This is formatted in the normal + /// token representation. e.g. a limit of 100 for a token with 6 decimals = 100_000_000 function setPeer( uint16 peerChainId, bytes32 peerContract, @@ -235,12 +238,14 @@ interface INttManager is IManagerBase { /// @notice Sets the outbound transfer limit for a given chain. /// @dev This method can only be executed by the `owner`. - /// @param limit The new outbound limit. + /// @param limit The new outbound limit. This is formatted in the normal + /// token representation. e.g. a limit of 100 for a token with 6 decimals = 100_000_000 function setOutboundLimit(uint256 limit) external; /// @notice Sets the inbound transfer limit for a given chain. /// @dev This method can only be executed by the `owner`. - /// @param limit The new limit. - /// @param chainId The chain to set the limit for. + /// @param limit The new limit. This is formatted in the normal + /// token representation. e.g. a limit of 100 for a token with 6 decimals = 100_000_000 + /// @param chainId The Wormhole chain ID to set the limit for. function setInboundLimit(uint256 limit, uint16 chainId) external; } diff --git a/evm/src/interfaces/IRateLimiter.sol b/evm/src/interfaces/IRateLimiter.sol index 69b742b44..e85aa6602 100644 --- a/evm/src/interfaces/IRateLimiter.sol +++ b/evm/src/interfaces/IRateLimiter.sol @@ -84,14 +84,23 @@ interface IRateLimiter { address recipient; } + /// @notice Returns the currently remaining outbound capacity allowed + /// before transfers are queued (if desired) function getCurrentOutboundCapacity() external view returns (uint256); + /// @notice Returns the queued transfer details for a given sequence in the outbound queue + /// @param queueSequence The position of the transfer in the outbound queue function getOutboundQueuedTransfer( uint64 queueSequence ) external view returns (OutboundQueuedTransfer memory); + /// @notice Returns the currently remaining inbound capacity allowed from a given chain + /// before transfers are queued auutomatically + /// @param chainId The Wormhole chain ID of the peer function getCurrentInboundCapacity(uint16 chainId) external view returns (uint256); + /// @notice Returns the queued transfer details for a given message digest in the inbound queue + /// @param digest The digest of the transfer in the inbound queue function getInboundQueuedTransfer( bytes32 digest ) external view returns (InboundQueuedTransfer memory); diff --git a/evm/src/interfaces/ITransceiver.sol b/evm/src/interfaces/ITransceiver.sol index 9a4917749..4fc8bccea 100644 --- a/evm/src/interfaces/ITransceiver.sol +++ b/evm/src/interfaces/ITransceiver.sol @@ -62,6 +62,8 @@ interface ITransceiver { /// @param instruction An additional Instruction provided by the Transceiver to be /// executed on the recipient chain. /// @param nttManagerMessage A message to be sent to the nttManager on the recipient chain. + /// @param recipientNttManagerAddress The Wormhole formatted address of the peer NTT Manager on the recipient chain. + /// @param refundAddress The Wormhole formatted address of the refund recipient function sendMessage( uint16 recipientChain, TransceiverStructs.TransceiverInstruction memory instruction, @@ -71,8 +73,10 @@ interface ITransceiver { ) external payable; /// @notice Upgrades the transceiver to a new implementation. + /// @param newImplementation The address of the new implementation contract function upgrade(address newImplementation) external; /// @notice Transfers the ownership of the transceiver to a new address. + /// @param newOwner The address of the new owner function transferTransceiverOwnership(address newOwner) external; }