add natspec for specifying no ordered channels, to use the polymerfee…

… estimation api,and clarifications in feeVault

contracts/core/Dispatcher.sol

@@ -48,7 +48,8 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
     string public portPrefix;
     uint32 public portPrefixLen;
 
-    mapping(address => mapping(bytes32 => Channel)) private _portChannelMap;
+    mapping(address => mapping(bytes32 => Channel)) private _portChannelMap; // Mapping used to check if a channel is
+        // owned by a port
     mapping(address => mapping(bytes32 => uint64)) private _nextSequenceSend;
     // keep track of received packets' sequences to ensure channel ordering is enforced for ordered channels
     mapping(address => mapping(bytes32 => uint64)) private _nextSequenceRecv;
@@ -158,9 +159,10 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
     /**
      * @notice Initializes the channel opening process with the specified parameters. This is the first step in the  channel
      * handshake, initiated directly by the dapp which wishes to establish a channel with the receiver.
-     * @param ordering The ordering of the channel (ORDERED or UNORDERED).
+     * @param ordering The ordering of the channel (ORDERED or UNORDERED). Note: ORDERED channels are not currently
+     * supported
      * @param feeEnabled A boolean indicating whether fees are enabled for the channel. Note: This value isn't currently
-     * used
+     * used, and is not being verified in light client proofs.
      * @param connectionHops The list of connection hops associated with the channel, with the first channel in this
      * array always starting from the chain this contract is deployed on
      * @param counterpartyPortId The port ID of the counterparty.
@@ -204,8 +206,10 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
      * succeeds, the dApp should return the selected version and the emitted even will be relayed to the  IBC/VIBC hub
      * chain.
      * @param local The counterparty information for the receiver.
-     * @param ordering The ordering of the channel (ORDERED or UNORDERED).
-     * @param feeEnabled Whether fees are enabled for the channel. Note: This value isn't currently used
+     * @param ordering The ordering of the channel (ORDERED or UNORDERED). Note: ORDERED channels are not currently
+     * supported
+     * @param feeEnabled Whether fees are enabled for the channel. Note: This value isn't currently used, and is not
+     * being verified in light client proofs
      * @param connectionHops The list of connection hops associated with the channel; with the first channel in this
      * array always starting from the chain this contract is deployed on
      * @param counterparty The counterparty information of the sender
@@ -278,9 +282,10 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
      * @param local The counterparty information for the local channel.
      * @param connectionHops The list of connection hops associated with the channel, with the first channel in this
      * array always starting from the chain this contract is deployed on.
-     * @param ordering The ordering of the channel (ORDERED or UNORDERED).
+     * @param ordering The ordering of the channel (ORDERED or UNORDERED). Note: ORDERED channels are not currently
+     * supported
      * @param feeEnabled A boolean indicating whether fees are enabled for the channel. Note: This value isn't currently
-     * used
+     * used and is not being verified in light client proofs.
      * @param counterparty The counterparty information for the channel.
      * @param proof The proof that the counterparty is in the ACK_PENDING state (i.e. that it responded with a
      * successful channelOpenTry )
@@ -338,9 +343,12 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
      * The receiver should implement the onChannelConnect method to handle the last channel handshake method:
      * ChannelOpenConfirm
      * @param local The counterparty information for the local channel.
-     * @param ordering The ordering of the channel (ORDERED or UNORDERED).
+     * @param ordering The ordering of the channel (ORDERED or UNORDERED). Note: ORDERED channels are not currently
+     * supported
      * @param connectionHops The list of connection hops associated with the channel, with the first channel in this
      * array always starting from the chain this contract is deployed on.
+     * @param feeEnabled A boolean indicating whether fees are enabled for the channel. Note: This value isn't currently
+     * used and is not being verified in light client proofs.
      * @param counterparty The counterparty information for the channel.
      * @param proof The proof of channel opening confirm.
      * @dev This function initiates the channel opening confirm process by calling the onChanOpenConfirm function of the
@@ -396,6 +404,7 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
     function channelCloseInit(bytes32 channelId) external nonReentrant {
         Channel memory channel = _portChannelMap[msg.sender][channelId];
         if (channel.counterpartyChannelId == bytes32(0)) {
+            // _portChannelMap is used to check ownership of a channel by a port
             revert IBCErrors.channelNotOwnedBySender();
         }
         (bool success, bytes memory data) = _callIfContract(
@@ -439,6 +448,7 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
         // ensure port owns channel
         Channel memory channel = _portChannelMap[portAddress][channelId];
         if (channel.counterpartyChannelId == bytes32(0)) {
+            // _portChannelMap is used to check ownership of a channel by a port
             revert IBCErrors.channelNotOwnedByPortAddress();
         }
 
@@ -494,6 +504,7 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
     {
         // ensure port owns channel
         if (_portChannelMap[msg.sender][channelId].counterpartyChannelId == bytes32(0)) {
+            // _portChannelMap is used to check ownership of a channel by a port
             revert IBCErrors.channelNotOwnedBySender();
         }
         if (timeoutTimestamp <= block.timestamp) {
@@ -684,6 +695,7 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
      * default values per EVM.
      */
     function getChannel(address portAddress, bytes32 channelId) external view returns (Channel memory channel) {
+        // _portChannelMap is used to check ownership of a channel by a port
         channel = _portChannelMap[portAddress][channelId];
     }
 
@@ -720,9 +732,9 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
      * @param local The details of the local counterparty.
      * @param connectionHops The connection hops associated with the channel, with the first channel in this
      * array always starting from the chain this contract is deployed on.
-     * @param ordering The ordering of the channel.
+     * @param ordering The ordering of the channel. Note: ORDERED channels are not currently supported
      * @param feeEnabled A boolean indicating whether fees are enabled for the channel. Note: This value isn't currently
-     * used
+     * used and is not being verified in light client proofs.
      * @param counterparty The details of the counterparty.
      */
     function _connectChannel(
@@ -735,7 +747,7 @@ contract Dispatcher is OwnableUpgradeable, UUPSUpgradeable, ReentrancyGuard, IDi
     ) internal {
         // We don't need to check that a channel isn't already present between a portAddress and a chanenlId since
         // polymer chain verification should prevent double registration of the same channel (with the execption of the
-        // feeEnabled state, thoguh this isn't currently used anywhere so change a channel's feeEnabled state shouldn't
+        // feeEnabled state, though this isn't currently used anywhere so change a channel's feeEnabled state shouldn't
         // have any outcome)
         _portChannelMap[address(portAddress)][local.channelId] = Channel(
             local.version,

contracts/core/FeeVault.sol

@@ -26,6 +26,8 @@ contract FeeVault is Ownable, ReentrancyGuard, IFeeVault {
     /**
      * @notice Deposits the send packet fee for a given channel and sequence that is used for relaying recieve and
      * acknowledge steps of a packet handhsake after a dapp has called the sendPacket on dispatcher.
+     * @notice If you are relaying your own packets, you should not call this method.
+     * @notice Use the Polymer fee estimation api to get the required fees to ensure that enough fees are sent.
      * @dev This function calculates the required fee based on provided gas limits and gas prices,
      *      and reverts if the sent value does not match the calculated fee.
      *      The first entry in `gasLimits` and `gasPrices` arrays corresponds to `recvPacket` fees,
@@ -38,6 +40,8 @@ contract FeeVault is Ownable, ReentrancyGuard, IFeeVault {
      * @param gasPrices An array containing two gas price values:
      *                  - gasPrices[0] for `recvPacket` fees, for the dest chain
      *                  - gasPrices[1] for `ackPacket` fees, for the src chain
+     * @notice The total fees sent in the msg.value should be equal to the total gasLimits[0] * gasPrices[0] +
+     * gasLimits[1] * gasPrices[1]. The transaction will revert if a higher or lower value is sent
      */
     function depositSendPacketFee(
         bytes32 channelId,
@@ -55,6 +59,7 @@ contract FeeVault is Ownable, ReentrancyGuard, IFeeVault {
     /**
      * @notice Deposits the fee for a channel handshake, to pay a relayer for relaying the channelOpenTry,
      * channelOpenConfirm, and channelOpenAck steps after a dapp has called channelOpenInit
+     * @notice If you are relaying your own channelHandshake transactions, you should not call this method.
      * @dev The fee amount that needs to be sent for Polymer to relay the whole channel handshake can be queried on the
      * web2 layer.
      * @param src The address of the sender, should be the address in the localportId.

contracts/core/UniversalChannelHandler.sol

@@ -72,7 +72,7 @@ contract UniversalChannelHandler is IbcReceiverBaseUpgradeable, FeeSender, UUPSU
     }
 
     /**
-     * @notice Sends a universal packet over an IBC channel
+     * @notice Sends a universal packet over an IBC channel, without sending relaying fees to the FeeVault
      * @param channelId The channel ID through which the packet is sent on the dispatcher
      * @param destPortAddr The destination port address
      * @param appData The packet data to be sent
@@ -92,11 +92,23 @@ contract UniversalChannelHandler is IbcReceiverBaseUpgradeable, FeeSender, UUPSU
     }
 
     /**
-     * @notice Sends a universal packet over an IBC channel
+     * @notice Sends a universal packet over an IBC channel, and deposits relaying fees to a FeeVault within the same
+     * tx.
      * @param channelId The channel ID through which the packet is sent on the dispatcher
      * @param destPortAddr The destination port address
      * @param appData The packet data to be sent
      * @param timeoutTimestamp of when the packet can timeout
+     * @param gasLimits An array containing two gas limit values:
+     *                  - gasLimits[0] for `recvPacket` fees
+     *                  - gasLimits[1] for `ackPacket` fees.
+     * @param gasPrices An array containing two gas price values:
+     *                  - gasPrices[0] for `recvPacket` fees, for the dest chain
+     *                  - gasPrices[1] for `ackPacket` fees, for the src chain
+     * @notice The total fees sent in the msg.value should be equal to the total gasLimits[0] * gasPrices[0] +
+     * gasLimits[1] * gasPrices[1]. The transaction will revert if a higher or lower value is sent
+     * @notice if you are relaying your own transactions, you should not call this method, and instead call
+     * sendUniversalPacket
+     * @notice Use the Polymer fee estimation api to get the required fees to ensure that enough fees are sent.
      */
     function sendUniversalPacketWithFee(
         bytes32 channelId,

contracts/examples/Earth.sol

@@ -63,6 +63,26 @@ contract Earth is IbcUniversalPacketReceiverBase {
         );
     }
 
+    /**
+     * @notice Sends a universal packet with fee.
+     * @param destPortAddr The destination port address.
+     * @param channelId The channel ID.
+     * @param message The message to send.
+     * @param timeoutTimestamp The timeout timestamp.
+     * @param gasLimits The gas limits for the packet and the ack.
+     * @param gasPrices The gas prices for the packet and the ack.
+     * @return sequence The sequence number of the packet.
+     * @param gasLimits An array containing two gas limit values:
+     *                  - gasLimits[0] for `recvPacket` fees
+     *                  - gasLimits[1] for `ackPacket` fees.
+     * @param gasPrices An array containing two gas price values:
+     *                  - gasPrices[0] for `recvPacket` fees, for the dest chain
+     *                  - gasPrices[1] for `ackPacket` fees, for the src chain
+     * @notice If you are relaying your own packets, you should not call this method, and instead call greet.
+     * @notice The total fees sent in the msg.value should be equal to the total gasLimits[0] * gasPrices[0] +
+     * @notice Use the Polymer fee estimation api to get the required fees to ensure that enough fees are sent.
+     * gasLimits[1] * gasPrices[1]. The transaction will revert if a higher or lower value is sent
+     */
     function greetWithFee(
         address destPortAddr,
         bytes32 channelId,
@@ -76,6 +96,14 @@ contract Earth is IbcUniversalPacketReceiverBase {
         );
     }
 
+    /**
+     * @notice Handles the recv callback of a universal packet.
+     * @param channelId The channel ID.
+     * @param packet The universal packet.
+     * @return ackPacket The acknowledgement packet.
+     * @dev It's recommended to always validate the authorized channel of any packet or channel using the
+     * onlyAuthorizedChannel modifier.
+     */
     function onRecvUniversalPacket(bytes32 channelId, UniversalPacket calldata packet)
         external
         onlyUCH
@@ -86,6 +114,14 @@ contract Earth is IbcUniversalPacketReceiverBase {
         return this.generateAckPacket(channelId, IbcUtils.toAddress(packet.srcPortAddr), packet.appData);
     }
 
+    /**
+     * @notice Handles the acknowledgement of a universal packet.
+     * @param channelId The channel ID.
+     * @param packet The universal packet.
+     * @param ack The acknowledgement packet.
+     * @dev It's recommended to always validate the authorized channel of any packet or channel using the
+     * onlyAuthorizedChannel modifier.
+     */
     function onUniversalAcknowledgement(bytes32 channelId, UniversalPacket memory packet, AckPacket calldata ack)
         external
         onlyUCH
@@ -98,6 +134,14 @@ contract Earth is IbcUniversalPacketReceiverBase {
         ackPackets.push(UcAckWithChannel(channelId, packet, ack));
     }
 
+    /**
+     * @notice Handles the timeout of a universal packet. Timeouts are currently unimplemented, so this handler is
+     * unused.
+     * @param channelId The channel ID.
+     * @param packet The universal packet.
+     * @dev It's recommended to always validate the authorized channel of any packet or channel using the
+     * onlyAuthorizedChannel modifier.
+     */
     function onTimeoutUniversalPacket(bytes32 channelId, UniversalPacket calldata packet)
         external
         onlyUCH
@@ -107,7 +151,8 @@ contract Earth is IbcUniversalPacketReceiverBase {
     }
 
     /**
-     * @notice Authorize a channel that can receive/ack packets to this contract.
+     * @notice Authorize a channel that can receive/ack packets to this contract. If channels are not validated, this
+     * could allow any arbitrary dapps to trigger callbacks on this dapp.
      * @param channelId The channel id to authorize; should be packet.dest.channelId for recv packets &
      * packet.src.channelId for ack packets.
      */