fix[N06] Fix misleading comments (#104)

* fix[N04] Add additional documentation

Signed-off-by: chrismaree <christopher.maree@gmail.com>

* nit

Signed-off-by: chrismaree <christopher.maree@gmail.com>

* fix[N06] Fix missleading comments

Signed-off-by: chrismaree <christopher.maree@gmail.com>

* Apply suggestions from code review

Co-authored-by: nicholaspai <9457025+nicholaspai@users.noreply.github.com>

* nit

Signed-off-by: chrismaree <christopher.maree@gmail.com>

Co-authored-by: nicholaspai <9457025+nicholaspai@users.noreply.github.com>

Author: chrismaree

contracts/HubPool.sol

@@ -75,7 +75,9 @@ contract HubPool is HubPoolInterface, Testable, Lockable, MultiCaller, Ownable {
     bytes32 public identifier = "IS_ACROSS_V2_BUNDLE_VALID";
 
     // Interest rate payment that scales the amount of pending fees per second paid to LPs. 0.0000015e18 will pay out
-    // the full amount of fees entitled to LPs in ~ 7.72 days, just over the standard L2 7 day liveness.
+    // the full amount of fees entitled to LPs in ~ 7.72 days assuming no contract interactions. If someone interacts
+    // with the contract then the LP rewards are smeared sublinearly over the window (i.e spread over the remaining
+    // period for each interaction which approximates a decreasing exponential function).
     uint256 public lpFeeRatePerSecond = 1500000000000;
 
     // Mapping of l1TokenAddress to cumulative unclaimed protocol tokens that can be sent to the protocolFeeCaptureAddress
@@ -560,7 +562,7 @@ contract HubPool is HubPoolInterface, Testable, Lockable, MultiCaller, Ownable {
 
         uint32 requestExpirationTimestamp = uint32(getCurrentTime()) + liveness;
 
-        delete rootBundleProposal; // Only one bundle of roots can be executed at a time.
+        delete rootBundleProposal; // Only one bundle of roots can be executed at a time. Delete the previous bundle.
 
         rootBundleProposal.requestExpirationTimestamp = requestExpirationTimestamp;
         rootBundleProposal.unclaimedPoolRebalanceLeafCount = poolRebalanceLeafCount;
@@ -588,7 +590,6 @@ contract HubPool is HubPoolInterface, Testable, Lockable, MultiCaller, Ownable {
      * from this contract to the SpokePool designated in the leaf, and will also publish relayer refund and slow
      * relay roots to the SpokePool on the network specified in the leaf.
      * @dev In some cases, will instruct spokePool to send funds back to L1.
-     * @notice Deletes the published root bundle if this is the last leaf to be executed in the root bundle.
      * @param chainId ChainId number of the target spoke pool on which the bundle is executed.
      * @param groupIndex If set to 0, then relay roots to SpokePool via cross chain bridge. Used by off-chain validator
      * to organize leaves with the same chain ID and also set which leaves should result in relayed messages.
@@ -794,7 +795,7 @@ contract HubPool is HubPoolInterface, Testable, Lockable, MultiCaller, Ownable {
         emit ProtocolFeesCapturedClaimed(l1Token, _unclaimedAccumulatedProtocolFees);
     }
 
-    /**
+    /**master
      * @notice Conveniently queries which destination token is mapped to the hash of an l1 token + destination chain ID.
      * @param destinationChainId Where destination token is deployed.
      * @param l1Token Ethereum version token.

contracts/HubPoolInterface.sol

@@ -15,13 +15,12 @@ interface HubPoolInterface {
         uint256 chainId;
         // Total LP fee amount per token in this bundle, encompassing all associated bundled relays.
         uint256[] bundleLpFees;
-        // This array is grouped with the two above, and it represents the amount to send or request back from the
-        // SpokePool. If positive, the pool will pay the SpokePool. If negative the SpokePool will pay the HubPool.
-        // There can be arbitrarily complex rebalancing rules defined offchain. This number is only nonzero when the
-        // rules indicate that a rebalancing action should occur. When a rebalance does occur, runningBalances should be
-        // set to zero for this token and the netSendAmounts should be set to the previous runningBalances + relays -
-        // deposits in this bundle. If non-zero then it must be set on the SpokePool's RelayerRefundLeaf amountToReturn
-        // as -1 * this value to indicate if funds are being sent from or to the SpokePool.
+        // Represents the amount to push to or pull from the SpokePool. If +, the pool pays the SpokePool. If negative
+        // the SpokePool pays the HubPool. There can be arbitrarily complex rebalancing rules defined offchain. This
+        // number is only nonzero when the rules indicate that a rebalancing action should occur. When a rebalance does
+        // occur, runningBalances must be set to zero for this token and netSendAmounts should be set to the previous
+        // runningBalances + relays - deposits in this bundle. If non-zero then it must be set on the SpokePool's
+        // RelayerRefundLeaf amountToReturn as -1 * this value to show if funds are being sent from or to the SpokePool.
         int256[] netSendAmounts;
         // This is only here to be emitted in an event to track a running unpaid balance between the L2 pool and the L1
         // pool. A positive number indicates that the HubPool owes the SpokePool funds. A negative number indicates that
@@ -36,9 +35,9 @@ interface HubPoolInterface {
         uint256 groupIndex;
         // Used as the index in the bitmap to track whether this leaf has been executed or not.
         uint8 leafId;
-        // The following arrays are required to be the same length. They are parallel arrays for the given chainId and
-        // should be ordered by the l1Tokens field. All whitelisted tokens with nonzero relays on this chain in this
-        // bundle in the order of whitelisting.
+        // The bundleLpFees, netSendAmounts, and runningBalances are required to be the same length. They are parallel
+        // arrays for the given chainId and should be ordered by the l1Tokens field. All whitelisted tokens with nonzero
+        // relays on this chain in this bundle in the order of whitelisting.
         address[] l1Tokens;
     }