PrizeDistributionHistory: general updates (#178)

contracts/PrizeDistributionHistory.sol

@@ -18,10 +18,16 @@ import "./interfaces/IPrizeDistributionHistory.sol";
 contract PrizeDistributionHistory is IPrizeDistributionHistory, Manageable {
     using DrawRingBufferLib for DrawRingBufferLib.Buffer;
 
+    /// @notice The maximum cardinality of the prize distribution ring buffer.
+    /// @dev even with daily draws, 256 will give us over 8 months of history.
     uint256 internal constant MAX_CARDINALITY = 256;
 
+    /// @notice The ceiling for prize distributions.  1e9 = 100%.
+    /// @dev It's fixed point 9 because 1e9 is the largest "1" that fits into 2**32
     uint256 internal constant DISTRIBUTION_CEILING = 1e9;
 
+    /// @notice Emitted when the contract is deployed.
+    /// @param cardinality The maximum number of records in the buffer before they begin to expire.
     event Deployed(uint8 cardinality);
 
     /// @notice PrizeDistribution ring buffer history.
@@ -149,7 +155,7 @@ contract PrizeDistributionHistory is IPrizeDistributionHistory, Manageable {
         uint32 index = buffer.getIndex(_drawId);
         _prizeDistributionsRingBuffer[index] = _prizeDistribution;
 
-        emit PrizeDistributionsSet(_drawId, _prizeDistribution);
+        emit PrizeDistributionSet(_drawId, _prizeDistribution);
 
         return _drawId;
     }
@@ -218,7 +224,7 @@ contract PrizeDistributionHistory is IPrizeDistributionHistory, Manageable {
         // update the ring buffer data
         _prizeDistributionsRingBufferData = buffer.push(_drawId);
 
-        emit PrizeDistributionsSet(_drawId, _prizeDistribution);
+        emit PrizeDistributionSet(_drawId, _prizeDistribution);
 
         return true;
     }

contracts/interfaces/IPrizeDistributionHistory.sol

@@ -16,11 +16,11 @@ interface IPrizeDistributionHistory {
     /**
      * @notice Emitted when the PrizeDistribution are set/updated
      * @param drawId       Draw id
-     * @param prizeDistributions DrawLib.PrizeDistribution
+     * @param prizeDistribution DrawLib.PrizeDistribution
      */
-    event PrizeDistributionsSet(
+    event PrizeDistributionSet(
         uint32 indexed drawId,
-        DrawLib.PrizeDistribution prizeDistributions
+        DrawLib.PrizeDistribution prizeDistribution
     );
 
     /**

contracts/libraries/DrawRingBufferLib.sol

@@ -45,7 +45,7 @@ library DrawRingBufferLib {
         uint32 indexOffset = _buffer.lastDrawId - _drawId;
         require(indexOffset < _buffer.cardinality, "DRB/expired-draw");
 
-        uint256 mostRecent = RingBufferLib.mostRecentIndex(_buffer.nextIndex, _buffer.cardinality);
+        uint256 mostRecent = RingBufferLib.newestIndex(_buffer.nextIndex, _buffer.cardinality);
 
         return uint32(RingBufferLib.offset(uint32(mostRecent), indexOffset, _buffer.cardinality));
     }

contracts/libraries/RingBufferLib.sol

@@ -17,11 +17,11 @@ library RingBufferLib {
     }
 
     /**
-    * @notice Returns the `_index` offsetted by `_amount`.
+    * @notice Computes the negative offset from the given index, wrapped by the cardinality.
     * @dev  We add `_cardinality` to `_index` to be able to offset event if `_amount` is superior to `_cardinality`.
-    * @param _index Index to offset.
-    * @param _amount Amount we want to offset the `_index` by.
-    * @param _cardinality TWAB buffer cardinality.
+    * @param _index The index from which to offset
+    * @param _amount The number of indices to offset.  This is subtracted from the given index.
+    * @param _cardinality The number of elements in the ring buffer
     * @return Offsetted index.
      */
     function offset(
@@ -32,13 +32,11 @@ library RingBufferLib {
         return wrap(_index + _cardinality - _amount, _cardinality);
     }
 
-    /**
-    * @notice Returns index of the last recorded TWAB.
-    * @param _nextAvailableIndex Next available twab index to which will be recorded the next TWAB.
-    * @param _cardinality TWAB buffer cardinality.
-    * @return Index of the last recorded TWAB.
-     */
-    function mostRecentIndex(uint256 _nextAvailableIndex, uint256 _cardinality)
+    /// @notice Returns the index of the last recorded TWAB
+    /// @param _nextIndex The next available twab index.  This will be recorded to next.
+    /// @param _cardinality The cardinality of the TWAB history.
+    /// @return The index of the last recorded TWAB
+    function newestIndex(uint256 _nextIndex, uint256 _cardinality)
         internal
         pure
         returns (uint256)
@@ -50,13 +48,11 @@ library RingBufferLib {
         return wrap(_nextAvailableIndex + _cardinality - 1, _cardinality);
     }
 
-    /**
-    * @notice Returns the next available TWAB index.
-    * @param _currentIndex Current TWAB buffer index.
-    * @param _cardinality TWAB buffer cardinality.
-    * @return Next available TWAB index.
-    */
-    function nextIndex(uint256 _currentIndex, uint256 _cardinality)
+    /// @notice Computes the ring buffer index that follows the given one, wrapped by cardinality
+    /// @param _index The index to increment
+    /// @param _cardinality The number of elements in the Ring Buffer
+    /// @return The next index relative to the given index.  Will wrap around to 0 if the next index == cardinality
+    function nextIndex(uint256 _index, uint256 _cardinality)
         internal
         pure
         returns (uint256)

contracts/libraries/TwabLib.sol

@@ -170,7 +170,7 @@ library TwabLib {
         AccountDetails memory _accountDetails
     ) internal view returns (uint24 index, ObservationLib.Observation memory twab) {
         index = uint24(
-            RingBufferLib.mostRecentIndex(_accountDetails.nextTwabIndex, MAX_CARDINALITY)
+            RingBufferLib.newestIndex(_accountDetails.nextTwabIndex, MAX_CARDINALITY)
         );
         twab = _twabs[index];
     }

test/PrizeDistributionHistory.test.ts

@@ -221,7 +221,7 @@ describe('PrizeDistributionHistory', () => {
         it('should create a new draw and emit DrawCreated', async () => {
             await expect(
                 await prizeDistributionHistory.pushPrizeDistribution(1, newPrizeDistribution()),
-            ).to.emit(prizeDistributionHistory, 'PrizeDistributionsSet');
+            ).to.emit(prizeDistributionHistory, 'PrizeDistributionSet');
         });
     });
 
@@ -318,7 +318,7 @@ describe('PrizeDistributionHistory', () => {
 
             await expect(
                 prizeDistributionHistory.setPrizeDistribution(1, newPrizeDistribution(6)),
-            ).to.emit(prizeDistributionHistory, 'PrizeDistributionsSet');
+            ).to.emit(prizeDistributionHistory, 'PrizeDistributionSet');
 
             expect(
                 (await prizeDistributionHistory.getPrizeDistribution(1)).matchCardinality,