PrizeDistributionHistory: general updates

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;
     }
@@ -217,7 +223,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

@@ -12,6 +12,11 @@ library RingBufferLib {
         return _index % _cardinality;
     }
 
+    /// @notice Computes the negative offset from the given index, wrapped by the 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 The offset index.
     function offset(
         uint256 _index,
         uint256 _amount,
@@ -21,10 +26,10 @@ library RingBufferLib {
     }
 
     /// @notice Returns the index of the last recorded TWAB
-    /// @param _nextAvailableIndex The next available twab index.  This will be recorded to next.
+    /// @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 mostRecentIndex(uint256 _nextAvailableIndex, uint256 _cardinality)
+    function newestIndex(uint256 _nextIndex, uint256 _cardinality)
         internal
         pure
         returns (uint256)
@@ -33,14 +38,18 @@ library RingBufferLib {
             return 0;
         }
 
-        return (_nextAvailableIndex + uint256(_cardinality) - 1) % _cardinality;
+        return (_nextIndex + uint256(_cardinality) - 1) % _cardinality;
     }
 
-    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)
     {
-        return (_currentIndex + 1) % _cardinality;
+        return (_index + 1) % _cardinality;
     }
 }

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

@@ -213,7 +213,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');
         });
     });
 
@@ -310,7 +310,7 @@ describe('PrizeDistributionHistory', () => {
 
             await expect(
                 prizeDistributionHistory.setPrizeDistribution(1, newPrizeDistribution(6)),
-            ).to.emit(prizeDistributionHistory, 'PrizeDistributionsSet');
+            ).to.emit(prizeDistributionHistory, 'PrizeDistributionSet');
 
             expect(
                 (await prizeDistributionHistory.getPrizeDistribution(1)).matchCardinality,