Submission Details
Impact:
Likelihood:
[I-2] Missing NatSpec Documentation Across Contract
[I-2] Missing NatSpec Documentation Across Contract
Description
The codebase lacks comprehensive NatSpec documentation. While some functions have `@notice` or `@dev` tags, most are missing complete documentation including `@param`, `@return`, and detailed explanations.
Examples
```solidity
// Incomplete documentation
/**
@dev allows users to join the event
*/
function joinEvent(uint256 countryId) public {
}
/**
@dev allows users to withdraw.
*/
function withdraw() external winnerSet {
}
// Minimal documentation
/**
@notice sets the winner at the end of the tournament
*/
function setWinner(uint256 countryIndex) public onlyOwner returns (string memory) {
// Missing @param, @return, detailed behavior description
}
```
Risk
Likelihood:
High — it’s a common and recurring issue since many developers omit NatSpec comments. It happens easily during development and affects overall code clarity and auditability rather than functionality.
Impact:
Reduced code maintainability
Difficult for auditors and developers to understand intended behavior
Poor developer experience for integrating protocols
[I-1] Missing NatSpec Documentation Across Contract Increased likelihood of integration errors
Proof of Concept
Recommended Mitigation
- remove this code
+ add this code
Add comprehensive NatSpec documentation to all public/external functions
```diff
+ /**
+ * @notice Allows users to join the prediction event by selecting a country
+ * @dev User must have deposited funds before joining. Can only join before event starts.
+ * @param countryId The index of the country in the teams array (0-47)
+ *
+ * Requirements:
+ * - User must have non-zero stakedAsset
+ * - countryId must be valid index in teams array
+ * - Current time must be before eventStartDate
+ * - User cannot join multiple times (currently not enforced - see H-4)
+ *
+ * Effects:
+ * - Sets userToCountry mapping
+ * - Sets userSharesToCountry mapping
+ * - Adds user to usersAddress array
+ * - Increments numberOfParticipants
+ * - Increases totalParticipantShares
+ *
+ * @custom:emits joinedEvent
+ */
+ function joinEvent(uint256 countryId) public {
// implementation
+ }
+ /**
+ * @notice Withdraws winnings for users who correctly predicted the winner
+ * @dev Can only be called after winner is set and event has ended
+ *
+ * Requirements:
+ * - Winner must be set (_setWinner == true)
+ * - Current time must be after eventEndDate
+ * - Caller must have predicted the winning country
+ * - Caller must have non-zero shares
+ *
+ * Effects:
+ * - Burns caller's vault shares
+ * - Transfers proportional amount of finalizedVaultAsset to caller
+ *
+ * Calculations:
+ * - Payout = (userShares * finalizedVaultAsset) / totalWinnerShares
+ *
+ * @custom:emits Withdraw
+ * @custom:security Check for division by zero when totalWinnerShares == 0 (see H-3)
+ */
+ function withdraw() external winnerSet {
// implementation
+ }
```
Follow NatSpec format: https://docs.soliditylang.org/en/latest/natspec-format.html
Include:
`@notice` - User-facing description
`@dev` - Developer notes
`@param` - Parameter descriptions
`@return` - Return value descriptions
`@custom`:security - Security considerations
`@custom`:emits - Events emitted
Rewards breakdown
nSLOC
193This contest has a flat reward structure with the following payouts:
100 EXP
20 EXP
2 EXP
Live
The contest is live. Earn rewards by submitting a finding.
Appeals
This is your time to appeal against judgements on your submissions.
Appeals Review
Appeals are being carefully reviewed by our judges.