From fafdffed68e1e2fb050b2a650b6d302448d3f2b1 Mon Sep 17 00:00:00 2001 From: Kevin Park Date: Thu, 3 Oct 2024 18:56:11 +0700 Subject: [PATCH] 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 --- docs/src/src/libs/LibAdmin.sol/library.LibAdmin.md | 7 ------- .../src/libs/LibHelpers.sol/library.LibHelpers.md | 14 -------------- .../FreeStructs.sol/struct.StakingCheckpoint.md | 13 ------------- src/interfaces/IERC1271.sol | 1 + src/libs/LibTokenizedVaultStaking.sol | 9 +++++---- src/shared/AppStorage.sol | 14 ++++++++++++++ 6 files changed, 20 insertions(+), 38 deletions(-) delete mode 100644 docs/src/src/shared/FreeStructs.sol/struct.StakingCheckpoint.md diff --git a/docs/src/src/libs/LibAdmin.sol/library.LibAdmin.md b/docs/src/src/libs/LibAdmin.sol/library.LibAdmin.md index 116f54d0..67ec5ed0 100644 --- 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 index d1251d82..7f3770aa 100644 --- 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 deleted file mode 100644 index a4ff1b1a..00000000 --- a/docs/src/src/shared/FreeStructs.sol/struct.StakingCheckpoint.md +++ /dev/null @@ -1,13 +0,0 @@ -# StakingCheckpoint -[Git Source](https://github.com/nayms/contracts-v3/blob/0aa70a4d39a9875c02cd43cc38c09012f52d800e/src/shared/FreeStructs.sol) - - -```solidity -struct StakingCheckpoint { - int128 bias; - int128 slope; - uint256 ts; - uint256 blk; -} -``` - diff --git a/src/interfaces/IERC1271.sol b/src/interfaces/IERC1271.sol index a56057ba..42cef2b8 100644 --- 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 index 97b38bfc..581865b7 100644 --- 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 index 7b12846e..c98f9336 100644 --- 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? }