NAY4-S2 Documentation Improvement (#147)

* NAY4-S3-3 update docs * NAY4-S3-4 clarify usage of IERC1271 * NAY4-S3-5 _addUniqueValue follow standard internal functions naming convention * NAY4-S3-6 update natspec for _vTokenId * NAY4-S3-7 clarify logic in rewards_ * NAY4-S3-8 add comments about staking related mapping variables * NAY4-S3-9 fix natspec typo for _calculateStartTimeOfInterval * update staking related mappings descriptions
nayms · Oct 3, 2024 · fafdffe · fafdffe
1 parent 299ef59
commit fafdffe
Show file tree

Hide file tree

Showing 6 changed files with 20 additions and 38 deletions.
diff --git a/docs/src/src/libs/LibAdmin.sol/library.LibAdmin.md b/docs/src/src/libs/LibAdmin.sol/library.LibAdmin.md
@@ -10,13 +10,6 @@
 function _getSystemId() internal pure returns (bytes32);
 ```
 
-### _getEmptyId
-
-
-```solidity
-function _getEmptyId() internal pure returns (bytes32);
-```
-
 ### _updateMaxDividendDenominations
 
 

diff --git a/docs/src/src/libs/LibHelpers.sol/library.LibHelpers.md b/docs/src/src/libs/LibHelpers.sol/library.LibHelpers.md
@@ -5,13 +5,6 @@ Pure functions
 
 
 ## Functions
-### _getIdForObjectAtIndex
-
-
-```solidity
-function _getIdForObjectAtIndex(uint256 _index) internal pure returns (bytes32);
-```
-
 ### _getIdForAddress
 
 
@@ -33,13 +26,6 @@ function _getSenderId() internal view returns (bytes32);
 function _checkBottom12BytesAreEmpty(bytes32 value) internal pure returns (bool);
 ```
 
-### _checkUpper12BytesAreEmpty
-
-
-```solidity
-function _checkUpper12BytesAreEmpty(bytes32 value) internal pure returns (bool);
-```
-
 ### _getAddressFromId
 
 

diff --git a/docs/src/src/shared/FreeStructs.sol/struct.StakingCheckpoint.md b/docs/src/src/shared/FreeStructs.sol/struct.StakingCheckpoint.md
diff --git a/src/interfaces/IERC1271.sol b/src/interfaces/IERC1271.sol
@@ -6,6 +6,7 @@ pragma solidity ^0.8.20;
 /**
  * @dev Interface of the ERC1271 standard signature validation method for
  * contracts as defined in https://eips.ethereum.org/EIPS/eip-1271[ERC-1271].
+ * @dev We use this interface to generate java bindings for solidity contracts.
  */
 interface IERC1271 {
     /**

diff --git a/src/libs/LibTokenizedVaultStaking.sol b/src/libs/LibTokenizedVaultStaking.sol
@@ -19,6 +19,7 @@ library LibTokenizedVaultStaking {
 
     /**
      * @dev First 4 bytes: "VTOK", next 8 bytes: interval, next 20 bytes: right 20 bytes of tokenId
+     * @param _entityId The ID of the entity.
      * @param _tokenId The internal ID of the token.
      * @param _interval The interval of staking.
      */
@@ -270,7 +271,7 @@ library LibTokenizedVaultStaking {
             uint256 totalDistributionAmount = s.stakingDistributionAmount[_vTokenId(_entityId, tokenId, i)];
             if (totalDistributionAmount > 0) {
                 uint256 currencyIndex;
-                (rewards, currencyIndex) = addUniqueValue(rewards, s.stakingDistributionDenomination[_vTokenId(_entityId, tokenId, i)]);
+                (rewards, currencyIndex) = _addUniqueValue(rewards, s.stakingDistributionDenomination[_vTokenId(_entityId, tokenId, i)]);
 
                 // Use the same math as dividend distributions, assuming zero has already been collected
                 uint256 userDistributionAmount = LibTokenizedVault._getWithdrawableDividendAndDeductionMath(
@@ -362,7 +363,7 @@ library LibTokenizedVaultStaking {
         return s.stakingConfigs[_entityId].divider;
     }
 
-    function addUniqueValue(RewardsBalances memory rewards, bytes32 newValue) internal pure returns (RewardsBalances memory, uint256) {
+    function _addUniqueValue(RewardsBalances memory rewards, bytes32 newValue) internal pure returns (RewardsBalances memory, uint256) {
         require(rewards.currencies.length == rewards.amounts.length, "Different array lengths!");
 
         uint256 length = rewards.currencies.length;
@@ -375,7 +376,7 @@ library LibTokenizedVaultStaking {
         // prettier-ignore
         RewardsBalances memory rewards_ = RewardsBalances({
             currencies: new bytes32[](length + 1),
-            amounts: new uint256[](rewards.amounts.length + 1),
+            amounts: new uint256[](length + 1),
             lastPaidInterval: 0
         });
 
@@ -392,7 +393,7 @@ library LibTokenizedVaultStaking {
 
     /**
      * @dev Get the starting time of a given interval
-     * @param _entityId The internal ID of the token
+     * @param _entityId The internal ID of the entity
      * @param _interval The interval to get the time for
      */
     function _calculateStartTimeOfInterval(bytes32 _entityId, uint64 _interval) internal view returns (uint64 intervalTime_) {

diff --git a/src/shared/AppStorage.sol b/src/shared/AppStorage.sol
@@ -91,6 +91,20 @@ struct AppStorage {
     mapping(bytes32 entityId => mapping(bytes32 stakerId => uint64 interval)) stakingSynced; // last interval when data was synced into storage for staker
 }
 
+/// Staking-Related Mappings
+
+/// | Mapping Name                      | Key Structure                          | Value Type | Description                                                                                                 |
+/// |-----------------------------------|----------------------------------------|------------|-------------------------------------------------------------------------------------------------------------|
+/// | `stakeCollected`                  | `[Entity ID][Staker ID]`               | `uint64`   | Records the last timestamp a staker collected their stake.                                                  |
+/// | `stakeCollected`                  | `[Entity ID][Entity ID]`               | `uint64`   | Records the last timestamp an entity paid out rewards.                                                      |
+/// | `stakeBalance`                    | `[vTokenId][Account ID]`               | `uint256`  | Tracks staked balances for accounts across different intervals.                                             |
+/// | `stakeBoost`                      | `[vTokenId][Account ID]`               | `uint256`  | Tracks boosted staked balances for accounts.                                                                |
+/// | `stakeBalanceAdded`               | `[vTokenId][Staker ID]`                | `uint256`  | Raw balance staked at an interval without any boost, used for future interval calculations.                 |
+/// | `stakingDistributionAmount`       | `[vTokenId]`                           | `uint256`  | Stores the reward amount for each `vTokenId` at each interval.                                              |
+/// | `stakingDistributionDenomination` | `[vTokenId]`                           | `bytes32`  | Stores the reward currency (`denomination`) for each `vTokenId` at each interval.                           |
+/// | `stakingSynced`                   | `[Entity ID][Staker ID]`               | `uint64`   | Records the last interval when data was synced into storage for a staker.                                   |
+/// | `objectMinimumSell`               | `[Token ID][Entity ID]`                | `uint256`  | Sets minimum staking and reward amounts for tokens per entity.                                              |
+
 struct FunctionLockedStorage {
     mapping(bytes4 => bool) locked; // function selector => is locked?
 }